第 38 章：调试的艺术

// 文件：src/utils/debug.ts
export function logForDebugging(
  message: string,
  { level }: { level: DebugLogLevel } = { level: 'debug' },
): void {
  // 检查日志级别
  if (LEVEL_ORDER[level] < LEVEL_ORDER[getMinDebugLogLevel()]) {
    return
  }
  // 检查是否应该记录这条消息
  if (!shouldLogDebugMessage(message)) {
    return
  }
  // 格式化并写入
  const timestamp = new Date().toISOString()
  const output = `${timestamp} [${level.toUpperCase()}] ${message.trim()}\n`
  if (isDebugToStderr()) {
    writeToStderr(output)
    return
  }
  getDebugWriter().write(output)
}

// 文件：src/utils/debugFilter.ts
export function extractDebugCategories(message: string): string[] {
  const categories: string[] = []
  // "category: message" → 提取 category
  const prefixMatch = message.match(/^([^:[]+):/)
  if (prefixMatch) categories.push(prefixMatch[1].trim().toLowerCase())
  // "[CATEGORY] message" → 提取 CATEGORY
  const bracketMatch = message.match(/^\[([^\]]+)]/)
  if (bracketMatch) categories.push(bracketMatch[1].trim().toLowerCase())
  // "MCP server \"name\"" → 提取 mcp 和 name
  const mcpMatch = message.match(/^MCP server ["']([^"']+)["']/)
  if (mcpMatch) { categories.push('mcp'); categories.push(mcpMatch[1].toLowerCase()) }
  return Array.from(new Set(categories))
}

import { logForDebugging } from '../utils/debug.js'

// 在你的工具逻辑中
async call(input) {
  logForDebugging(`MyTool called with input: ${JSON.stringify(input)}`)

  // ... 核心逻辑 ...

  logForDebugging(`MyTool result: ${result}`, { level: 'info' })

  // 出错时
  logForDebugging(`MyTool error: ${error.message}`, { level: 'error' })

  return { data: result }
}

// 文件：src/skills/bundled/debug.ts
export function registerDebugSkill(): void {
  registerBundledSkill({
    name: 'debug',
    description: 'Enable debug logging for this session and help diagnose issues',
    allowedTools: ['Read', 'Grep', 'Glob'],
    async getPromptForCommand(args) {
      const wasAlreadyLogging = enableDebugLogging()
      const debugLogPath = getDebugLogPath()

      // 读取日志文件的最后 64KB
      const stats = await stat(debugLogPath)
      const readSize = Math.min(stats.size, TAIL_READ_BYTES)
      // ... 读取并格式化最后 20 行 ...

      return [{
        type: 'text',
        text: `# Debug Skill\n\n日志路径: ${debugLogPath}\n\n${logInfo}\n\n## 问题\n${args || '请描述你遇到的问题'}`
      }]
    },
  })
}

// 文件：src/utils/startupProfiler.ts
const PHASE_DEFINITIONS = {
  import_time: ['cli_entry', 'main_tsx_imports_loaded'],
  init_time: ['init_function_start', 'init_function_end'],
  settings_time: ['eagerLoadSettings_start', 'eagerLoadSettings_end'],
  total_time: ['cli_entry', 'main_after_run'],
}

// 文件：src/utils/slowOperations.ts
export function jsonStringify(value, replacer?, space?) {
  using _ = slowLogging`JSON.stringify(${value})`
  return JSON.stringify(value, replacer, space)
}

class AntSlowLogger {
  constructor(args) {
    this.startTime = performance.now()
    this.err = new Error()  // 捕获调用栈
  }
  [Symbol.dispose]() {
    const duration = performance.now() - this.startTime
    if (duration > SLOW_OPERATION_THRESHOLD_MS) {
      logForDebugging(
        `[SLOW OPERATION DETECTED] ${description} (${duration.toFixed(1)}ms)`
      )
    }
  }
}

async call(input) {
  logForDebugging(`[MyTool] enter call, input=${JSON.stringify(input)}`)
  // ... 核心逻辑 ...
  logForDebugging(`[MyTool] exit call, result=${JSON.stringify(result)}`)
  return result
}

// → 在 queryLoop 中添加
const toolCallHistory = new Map<string, number>()
// 每轮记录
for (const block of response.content) {
  if (block.type === "tool_use") {
    const key = `${block.name}:${JSON.stringify(block.input)}`
    const count = (toolCallHistory.get(key) ?? 0) + 1
    toolCallHistory.set(key, count)
    logForDebugging(`[Loop] tool_call #${turnCount}: ${key} (第${count}次)`)
  }
}

// → 结构化 Logger（最小实现 ~25 行）
type LogLevel = "debug" | "info" | "warn" | "error"

interface LogEntry {
  timestamp: string
  level: LogLevel
  sessionId: string
  message: string
  context?: Record<string, unknown>
}

class StructuredLogger {
  constructor(private sessionId: string) {}

  log(level: LogLevel, message: string, context?: Record<string, unknown>) {
    const entry: LogEntry = {
      timestamp: new Date().toISOString(),
      level,
      sessionId: this.sessionId,
      message,
      context,
    }
    // 输出为 JSON Lines（每行一个 JSON，方便 grep + jq 处理）
    process.stderr.write(JSON.stringify(entry) + "\n")
  }

  debug(msg: string, ctx?: Record<string, unknown>) { this.log("debug", msg, ctx) }
  info(msg: string, ctx?: Record<string, unknown>)  { this.log("info", msg, ctx) }
  warn(msg: string, ctx?: Record<string, unknown>)  { this.log("warn", msg, ctx) }
  error(msg: string, ctx?: Record<string, unknown>) { this.log("error", msg, ctx) }
}

// → 在 AgentLoop 中埋点
class AgentLoop {
  private logger: StructuredLogger

  async *run(input: string): AsyncGenerator<AgentEvent> {
    this.logger.info("agent.start", { input: input.substring(0, 100) })

    for (let turn = 1; turn <= this.config.maxTurns; turn++) {
      const turnStart = Date.now()
      this.logger.debug("turn.start", { turn })

      const response = await this.client.createMessage({ /*...*/ })
      this.logger.debug("turn.api_response", {
        turn,
        stopReason: response.stop_reason,
        tokens: response.usage,
        durationMs: Date.now() - turnStart,
      })

      if (response.stop_reason === "tool_use") {
        for (const block of response.content) {
          if (block.type === "tool_use") {
            const toolStart = Date.now()
            try {
              const result = await this.toolExecutor.execute(block)
              this.logger.debug("turn.tool_success", {
                turn,
                tool: block.name,
                durationMs: Date.now() - toolStart,
              })
              yield { type: "tool_result", data: result }
            } catch (err) {
              this.logger.error("turn.tool_error", {
                turn,
                tool: block.name,
                error: err.message,
              })
            }
          }
        }
        continue
      }

      this.logger.info("agent.complete", {
        turns: turn,
        totalTokens: this.totalTokens,
        totalDurationMs: Date.now() - this.sessionStart,
      })
      yield { type: "response", data: response }
      return
    }

    this.logger.warn("agent.max_turns", { maxTurns: this.config.maxTurns })
  }
}

// → 最简 OTel 集成（控制台输出）
import { trace, SpanStatusCode } from "@opentelemetry/api"
import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"
import { ConsoleSpanExporter } from "@opentelemetry/sdk-trace-node"

// 初始化
const provider = new BasicTracerProvider()
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()))
provider.register()

const tracer = trace.getTracer("my-agent")

// 使用：包裹 Agent run
async function* runWithTrace(agent: AgentLoop, input: string) {
  return tracer.startActiveSpan("agent.run", async (span) => {
    span.setAttribute("agent.model", agent.model)
    span.setAttribute("agent.input", input.substring(0, 200))

    try {
      for await (const event of agent.run(input)) {
        if (event.type === "response") {
          span.setAttribute("agent.turns", agent.turnCount)
          span.setAttribute("agent.tokens", agent.totalTokens)
          span.setStatus({ code: SpanStatusCode.OK })
        }
        yield event
      }
    } catch (err) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })
      throw err
    } finally {
      span.end()
    }
  })
}

// → 最简指标收集器（Counter + Histogram，~30 行）
class MetricsCollector {
  private counters = new Map<string, number>()
  private histograms = new Map<string, number[]>()

  counter(name: string, value = 1): void {
    this.counters.set(name, (this.counters.get(name) ?? 0) + value)
  }

  histogram(name: string, value: number): void {
    if (!this.histograms.has(name)) this.histograms.set(name, [])
    this.histograms.get(name)!.push(value)
  }

  report(): string {
    const lines: string[] = []
    for (const [name, count] of this.counters) {
      lines.push(`COUNT ${name}: ${count}`)
    }
    for (const [name, values] of this.histograms) {
      values.sort((a, b) => a - b)
      const p50 = values[Math.floor(values.length * 0.5)]
      const p95 = values[Math.floor(values.length * 0.95)]
      const avg = values.reduce((a, b) => a + b, 0) / values.length
      lines.push(`HIST ${name}: avg=${avg.toFixed(1)} p50=${p50} p95=${p95} n=${values.length}`)
    }
    return lines.join("\n")
  }
}

// 使用
const metrics = new MetricsCollector()
metrics.histogram("turn.count", agent.turnCount)
metrics.histogram("token.per_turn", usage.output_tokens)
metrics.histogram("tool.latency_ms", Date.now() - toolStart)
console.log(metrics.report())