# 调试系统

## 概述

Codev 提供两层调试能力：

1. **会话级调试日志** — 基于 `logForDebugging()` 的持久化日志系统，用于内部诊断
2. **`/debug` 交互式调试** — 基于 DEBUG PROBE 的主动式调试工作流（v2.0）

---

## 1. 会话调试日志

### 基础用法

通过 CLI 标志启用：

```bash
claude --debug              # 启用调试日志
claude --debug=api,hooks    # 按分类过滤
claude -d                   # 简写
claude --debug-file=/tmp/debug.log  # 自定义日志路径
claude --debug-to-stderr    # 输出到 stderr
```

环境变量：

| 变量 | 说明 |
|------|------|
| `DEBUG` / `DEBUG_SDK` | 启用调试模式 |
| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 最低级别：`verbose`, `debug`, `info`, `warn`, `error` |
| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 自定义日志目录 |

### 日志位置

默认路径：`~/.claude/debug/<sessionId>.txt`

`latest` 符号链接总是指向最新会话的日志文件。

### 核心文件

| 文件 | 职责 |
|------|------|
| `src/utils/debug.ts` | `logForDebugging()`, `isDebugMode()`, `enableDebugLogging()`, `getDebugLogPath()` |
| `src/utils/debugFilter.ts` | 分类过滤：`parseDebugFilter()`, `shouldShowDebugMessage()` |
| `src/utils/bufferedWriter.ts` | 缓冲写入器，批量写入日志 |

`logForDebugging()` 在代码库中 250+ 个文件中使用。

---

## 2. `/debug` 交互式调试（v2.0）

### 架构

```
用户输入 /debug <bug描述>
        │
        ▼
debug.ts (bundled skill)
        │
        ▼
8 步 CHECKPOINT 工作流注入模型上下文
        │
        ▼
模型自动执行：分析 → 插探针 → 复现 → 分析日志 → 修复 → 验证 → 清理
        │
        ▼
DebugSessionTool — 管理 .codev-debug/ 目录
```

### 与 v1 的区别

| 方面 | v1（旧） | v2.0（当前） |
|------|---------|-------------|
| 方式 | 被动读取调试日志 | 主动插入探针 |
| 数据源 | `~/.claude/debug/*.txt` | `.codev-debug/debug.log` |
| 模型角色 | 分析已有日志 | 插桩 → 复现 → 分析 → 修复 |
| 工作流 | 无结构化步骤 | 8 步 CHECKPOINT |

### 8 步 CHECKPOINT 工作流

| 步骤 | 操作 |
|------|------|
| **Step 0: Triage** | 确认 bug 报告完整（预期/实际/复现步骤/一致性/错误） |
| **Step 1: Plan Probes** | 阅读代码，形成 2-3 个假设，输出探针插入计划表 |
| **Step 2: Init Session** | 调用 `DebugSession({ action: "init" })` 创建 `.codev-debug/` |
| **Step 3: Insert Probes** | 用 Edit 插入 `DEBUG PROBE [N]` / `DEBUG PROBE END [N]` 代码块 |
| **Step 4: Reproduce & Log** | 调用 `DebugSession begin_run`，运行复现命令，通过 `read_log` 收集 |
| **Step 5: Analyze** | 引用日志行，定位根因 |
| **Step 6: Fix & Verify** | 修复后调用 `begin_verify`，重跑，对比日志 |
| **Step 7: Cleanup** | 删除所有探针，Grep 确认清理，调用 `DebugSession cleanup` |
| **Final** | 总结根因、证据、修复、验证、清理 |

### DEBUG PROBE 格式

```typescript
// DEBUG PROBE [1] <label>
try {
  require('fs').appendFileSync('.codev-debug/debug.log',
    `[${new Date().toISOString()}] [js] file.ts:42 | label | value=${JSON.stringify(value)}\n`)
} catch {}
// DEBUG PROBE END [1]
```

规则：
- 探针必须是**只观察不修改**的
- 每个探针有唯一编号 `[N]` 和匹配的 START/END 标记
- 每种语言的探针模板不同（JS/TS、Python、Go、Rust）
- 最多 3 轮探针迭代
- 必须在最终回复前完全清理

### DebugSession 工具

工具名：`DebugSession`

可用动作：

| 动作 | 说明 |
|------|------|
| `init` | 创建 `.codev-debug/` 目录、`debug.log`、`state` 文件 |
| `begin_run` | 追加 `RUN #N` 分隔符，递增运行计数器 |
| `begin_verify` | 追加 `VERIFY` 分隔符 |
| `read_log` | 读取 `debug.log` 尾部内容 |
| `cleanup` | 删除 `.codev-debug/` 目录 |

### 目录结构

```
.codev-debug/
  debug.log       -- 探针写入 + RUN/VERIFY 分隔符
  state           -- JSON: { "runCount": 3 }
```

### 核心文件

| 文件 | 职责 |
|------|------|
| `src/skills/bundled/debug.ts` | `/debug` skill 定义，8 步工作流提示词，探针模板 |
| `src/tools/DebugSessionTool.ts` | DebugSession 工具实现 |
| `src/utils/debug.ts` | 通用调试日志基础设施 |
| `src/commands/debug-tool-call/index.js` | 遗留桩命令（`isEnabled: false`） |