Bug Report

Bug Report

Symptom: [用户看到的现象] Root Cause: [位于 file:line 的真实底层问题] Reproduction: [触发问题的最小步骤] Fix: [需要的最小代码改动] Verification: [如何证明问题已修复] Similar Issues: [代码库中其他可能存在该模式的位置]

References

• file.ts:42 - [Bug 表现的位置]
• file.ts:108 - [根因起源的位置]

### Build Error Resolution 模板

```markdown
## Build Error Resolution

**Initial Errors:** X
**Errors Fixed:** Y
**Build Status:** PASSING / FAILING

### Errors Fixed
1. `src/file.ts:45` - [错误消息] - Fix: [改动内容] - Lines changed: 1

### Verification
- Build command: [命令] -> exit code 0
- No new errors introduced: [confirmed]

Final Response Contract

<Final_Response_Contract> 是一条强约束：Debugger 的最后一条 assistant 消息必须是呈现给调用方的交付物，必须包含上述完整的 Bug Report（含 Symptom、Root Cause、Reproduction、Fix、Verification、References，以及适用时的 Build Error Resolution）。实质性诊断不得只藏在早期消息或工具评论里——如果之前已经起草过结论，必须在最后一条消息里重复最终判定结构。报告一律禁止以「done」「complete」「nothing further」「looks good」「no further comments」之类的空话收尾。

该契约并非仅靠提示词自律，而是被测试强制锁定：test/advisory-agent-final-output-contract.test.ts 将 debugger 列为 advisory agents 之一，断言其提示词必须包含 <Final_Response_Contract>、## Bug Report、## References、## Build Error Resolution 标记，必须声明「LAST assistant message is the deliverable」，必须禁止空泛签收词，并且要求最终消息重复结论结构。这意味着任何人编辑 agents/debugger.md 时若删掉这些结构，CI 会直接失败。

失败模式清单：Debugger 要主动规避的陷阱

<Failure_Modes_To_Avoid> 列举了 13 类典型失败，可作为人工审计 Debugger 输出时的对照表：

失败模式	错误做法 → 正确做法
症状修复	到处补 null 检查 → 追问「为什么是 null」，找到根因
跳过复现	未确认可触发就调查 → 先复现
堆栈只读首帧	只看栈顶 → 读完整堆栈
假设堆叠	一次试 3 个修复 → 一次只验证一个假设
死循环	同一失败方案反复变体重试 → 3 次后升级
无证据推测	「大概是竞态」→ 展示真实的并发访问模式
边修边重构	修类型错误时顺手改名/抽函数 → 只修类型错误
架构级改动	因导入错误重排模块结构 → 适配当前结构修 import
验证不完整	修了 5 个错误中的 3 个就宣称成功 → 修完所有错误并展示干净构建
过度修复	堆 null 检查/错误处理/类型守卫 → 单个类型注解即可的最小修复
语言工具错配	在 Go 项目上跑 tsc → 先识别语言再选工具

好/坏示例对照

文档以成对示例说明诊断质量差异：

• Good（运行时）：症状 user.ts:42 抛 TypeError: Cannot read property 'name' of undefined；根因是用户被删除后会话仍持有其 ID，db.ts:108 的 getUser() 返回 undefined，而 auth.ts:55 的会话清理有 5 分钟延迟，形成已删除用户仍持有活跃会话的时间窗；修复：在 getUser() 中检测已删除用户并立即失效会话。
• Bad（运行时）：「某处有空指针错误，试着给 user 对象加 null 检查」——无根因、无文件引用、无复现步骤。
• Good（编译期）：utils.ts:42 报 Parameter 'x' implicitly has an 'any' type；修复：加类型注解 x: string；改动 1 行；Build: PASSING。
• Bad（编译期）：同一错误却把整个 utils 模块重构成泛型、抽出类型辅助库、改名 5 个函数，改动 150 行。

Debugger 在团队流水线中的路由与别名

Debugger 并非只能被人工点选，它深度接入自动路由体系：

• 意图路由：src/team/role-router.ts 将 debug、troubleshoot、investigate、diagnos 等关键词映射到 debugger 角色；当任务文本命中 debug 意图时返回 { role: 'debugger', confidence: 'high' }。对应测试见 role-router.test.ts。
• 阶段路由：src/team/stage-router.ts 将 debugger 归入 MEDIUM 档模型层。
• 别名收敛：历史角色 build-fixer 已被合并进 debugger，delegation-routing/types.ts 维护 'build-fixer': 'debugger' 的映射，相关解析在 resolver.test.ts 与 consolidation-contracts.test.ts 中被断言。
• 工作流注册：workflow/registry.ts 中 debugger 被标记为 internalOnly: true、tier0Role: 'executor'，即它作为编排内部角色存在，Tier-0 直接对话场景由 executor 承接。
• HUD 展示：src/hud/elements/agents.ts 用快捷键 g 索引 debugger（sonnet 档），并在界面将名称显示为 debug。
• CLI 入口：npx oh-my-claudecode team 命令允许把任务显式委派给 debugger 角色，见 src/cli/commands/team.ts。

面向 Debugger 的评测基准

仓库为验证 Debugger 的诊断质量提供了可复现的基准：_benchmark 目录 的 runner 明确注明其目的——对比合并后的新 debugger（吸收 build-fixer）与旧 build-fixer 提示词的诊断质量。它通过统一的 shared runner 加载 fixtures 中的缺陷样本与 ground-truth 中的期望结论，将用户消息构造为 Diagnose the following bug and recommend fixes: ...，并对输出做结构化解析。

典型用法：

# 全量对比 debugger 与 build-fixer 两版提示词
npx tsx benchmarks/debugger/run-benchmark.ts

# 只跑单个 fixture / 只跑单版 agent / 本地校验管线
npx tsx benchmarks/debugger/run-benchmark.ts --fixture <id>
npx tsx benchmarks/debugger/run-benchmark.ts --agent debugger
npx tsx benchmarks/debugger/run-benchmark.ts --dry-run

收尾自检清单（Final Checklist）

agents/debugger.md 末尾给出 Debugger 结束工作前必须逐项自问的清单，也是一份现成的「Debugger 输出审计表」：

• [ ] 调查前是否已复现 Bug？
• [ ] 是否完整阅读了错误消息与堆栈？
• [ ] 根因是否已定位（而不只是症状）？
• [ ] 修复建议是否最小（单处改动）？
• [ ] 是否已检查代码库中其他位置的相同模式？
• [ ] 所有结论是否引用了 file:line？
• [ ] 构建命令是否以退出码 0 结束（针对构建错误）？
• [ ] 是否改动了最少行数？
• [ ] 是否避免了重构、改名或架构级改动？
• [ ] 是否修复了全部错误（而非部分）？

与「调试 OMC 自身」的区分：debug skill

需要注意的是，仓库中还存在一个面向会话/仓库状态诊断的 skills/debug/SKILL.md 技能（以及兼容旧命令 /oh-my-claudecode:debug 的 commands/debug.md）。它解决的是「当前 OMC 会话/工作流损坏、运行行为诡异」这类自诊断问题，方法上同样强调「真实证据优先于猜测」「区分症状与根因」「先窄幅复现」「推荐最小下一步」，但对象是 OMC 插件自身而非业务代码。二者哲学一致、应用层不同：Debugger Agent 修你的代码与构建，debug skill 修 OMC 的运行态。当问题属于编排、hooks 或代理流时，后者主张使用 trace/state 数据面定位信号；当问题属于应用代码缺陷时，才轮到前者登场。

快速上手指南

# 安装并激活 oh-my-claudecode 插件后，在 Claude Code 会话中直接委派
# 描述 Bug 现象与堆栈，Debugger 会按 Investigation Protocol 返回 Bug Report

# 显式指定 debugger 角色进行团队式编排
npx oh-my-claudecode team "定位并修复 utils 模块的空指针异常" --role debugger