Logger 日志库

type LogLevel =
  | 'error'    // 优先级: 2 — 错误
  | 'warn'     // 优先级: 3 — 警告
  | 'info'     // 优先级: 4 — 信息（默认级别）
  | 'debug'    // 优先级: 5 — 调试
  | 'trace'    // 优先级: 6 — 追踪
  | 'fatal'    // 优先级: 1 — 致命错误
  | 'silent'   // 优先级: 0 — 静默（不输出但缓冲诊断）

Silent(0) < Fatal(1) < Error(2) < Warn(3) < Info(4) < Debug(5) < Trace(6)

interface LoggerDiagnosticInput {
  readonly code: string                       // 错误代码标识
  readonly title: string                      // 显示标题（用于 ### 渲染）
  readonly rootCause: DiagnosticLines         // 必填，问题描述（至少一行）
  readonly exactFix?: DiagnosticLines         // 可选，精确修复步骤
  readonly possibleFixes?: readonly DiagnosticLines[]  // 可选，备选修复方案列表
  readonly details?: Record<string, unknown>  // 可选，附加上下文数据
}
 
type DiagnosticLines = readonly [string, ...string[]]  // 至少包含一个元素的只读元组

interface LoggerDiagnosticRecord extends LoggerDiagnosticInput {
  readonly level: LoggerDiagnosticLevel     // 实际日志级别 ('error' | 'warn' | 'fatal')
  readonly namespace: string                // 来源命名空间
  readonly copyText: DiagnosticLines        // 可复制文本版本（纯 Markdown 行数组）
}

显式参数 > 全局级别 > LOG_LEVEL 环境变量 > Info(默认)

### 你的消息标题
 
- key: value          # meta 数据以列表形式展示

### 第一行标题
 
第二行内容
第三行内容

### 诊断标题
 
**What happened**
  - 这里描述发生了什么问题
 
**Do this**
  - 这是精确的修复步骤
 
**Try this if needed**
  1. 备选方案一的第一步
     备选方案一的延续
 
**Context**
  - path: /some/file.json
  - phase: cleanup

enum OutputCommand {
  Write { use_stderr: bool, output: String },  // 写入命令
  Flush { ack: Sender<()> },                     // 刷新同步命令
}

import { createLogger } from '@truenine/memory-sync-sdk'
 
const logger = createLogger('example-app')
 
// info — 默认可见
logger.info('应用启动成功')
// 输出: ### 应用启动成功
 
// info — 带 meta 对象
logger.info('处理请求', { method: 'GET', path: '/api/users', duration: 42 })
// 输出:
// ### 处理请求
//
//   - method: GET
//   - path: /api/users
//   - duration: 42
 
// debug — 需要日志级别 >= debug 才可见
logger.debug('查询数据库', { table: 'users', query: 'SELECT * FROM users' })
 
// trace — 最详细级别
logger.trace('进入函数', { fn: 'processRequest', args: ['req', 'res'] })

import { createLogger } from '@truenine/memory-sync-sdk'
 
const logger = createLogger('config-loader')
 
// error — 完整诊断（含所有字段）
logger.error({
  code: 'CONFIG_FILE_NOT_FOUND',
  title: '配置文件不存在',
  rootCause: [
    '指定的配置文件路径下没有找到有效的配置文件',
    '程序需要 config.json 来初始化运行时环境'
  ],
  exactFix: [
    '在项目根目录创建 config.json 文件',
    '或使用 --config-path 指定正确的配置文件位置'
  ],
  possibleFixes: [
    ['从版本控制恢复已删除的 config.json'],
    ['运行 init 命令重新生成默认配置']
  ],
  details: {
    searchedPaths: ['./config.json', '/etc/app/config.json'],
    expectedFormat: 'JSON'
  }
})
// 输出:
// ### 配置文件不存在
//
// **What happened**
//   - 指定的配置文件路径下没有找到有效的配置文件
//   - 程序需要 config.json 来初始化运行时环境
//
// **Do this**
//   - 在项目根目录创建 config.json 文件
//   - 或使用 --config-path 指定正确的配置文件位置
//
// **Try this if needed**
//   1. 从版本控制恢复已删除的 config.json
//      运行 init 命令重新生成默认配置
//
// **Context**
//   - searchedPaths:
//     - ./config.json
//     - /etc/app/config.json
//   - expectedFormat: JSON
 
// warn — 简洁警告
logger.warn({
  code: 'DEPRECATED_OPTION',
  title: '使用了已弃用的选项',
  rootCause: ['--legacy-flag 将在下个主版本中被移除'],
  exactFix: ['改用 --new-flag 替代']
})
 
// fatal — 致命错误
logger.fatal({
  code: 'RUNTIME_PANIC',
  title: '运行时发生不可恢复错误',
  rootCause: ['内存分配失败，无法继续执行'],
  exactFix: ['检查系统可用内存并重启应用'],
  details: { allocatedMB: 2048, limitMB: 2048 }
})

import {
  createLogger,
  setGlobalLogLevel,
  getGlobalLogLevel,
  clearBufferedDiagnostics,
  drainBufferedDiagnostics,
  flushOutput
} from '@truenine/memory-sync-sdk'
 
// 1. 设置全局级别为 warn — 只显示 error/warn/fatal
setGlobalLogLevel('warn')
console.log(getGlobalLogLevel())  // 'warn'
 
const logger = createLogger('batch-processor')
 
// 这些不会输出到终端（级别低于 warn）
logger.info('开始批处理')        // 被过滤
logger.debug('读取第 1 条记录')   // 被过滤
logger.trace('解析 JSON payload') // 被过滤
 
// 但诊断会被缓冲！
logger.error({
  code: 'PARSE_ERROR',
  title: 'JSON 解析失败',
  rootCause: ['第 42 行存在语法错误'],
  exactFix: ['修正 JSON 格式后重试']
})
 
logger.warn({
  code: 'SLOW_QUERY',
  title: '查询耗时过长',
  rootCause: ['查询执行时间超过 5000ms'],
  possibleFixes: [['添加索引优化查询性能']]
})
 
// 2. 提取所有缓冲的诊断记录（包括 silent 模式下的）
const diagnostics = drainBufferedDiagnostics()
console.log(`捕获了 ${diagnostics.length} 条诊断记录`)
// 输出: 捕获了 2 条诊断记录
 
diagnostics.forEach(d => {
  console.log(`[${d.level}] ${d.code}: ${d.title}`)
  console.log(`  命名空间: ${d.namespace}`)
  console.log(`  可复制文本:\n${d.copyText.join('\n')}`)
})
 
// 3. 刷新确保所有输出已写入
flushOutput()
 
// 4. 清空缓冲区
clearBufferedDiagnostics()
console.log(drainBufferedDiagnostics().length)  // 0

# bash / zsh
export LOG_LEVEL=debug
LOG_LEVEL=trace tnmsc run
 
# Windows PowerShell
$env:LOG_LEVEL = "warn"

// 推荐：按功能模块划分命名空间
const dbLogger = createLogger('database')
const httpLogger = createLogger('http-server')
const pluginLogger = createLogger('plugin-system')