File size: 4,446 Bytes
762b1c8 96f34e3 762b1c8 96f34e3 762b1c8 96f34e3 762b1c8 96f34e3 762b1c8 96f34e3 762b1c8 96f34e3 762b1c8 96f34e3 762b1c8 96f34e3 762b1c8 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 | # 调试系统
## 概述
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`） |
|