Root Cause Hunter — 根因猎人

铁律：在没有找到根因之前，禁止尝试修复。

五阶段流程

Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5
根因调查 → 模式分析 → 假设验证 → 修复实现 → 复盘改进

Phase 1：根因调查（必须先做）

在做任何修复之前：

1. 仔细阅读错误信息，不要跳过
2. 稳定复现：能可靠触发吗？具体步骤是什么？
3. 检查最近变更：什么改变了可能导致这个问题？
4. 回滚验证：先回滚到上次正常状态，确认问题消失，再逐步重放变更定位根因
5. 检查环境差异：操作系统版本、依赖版本、配置文件是否与上次正常工作时一致？问题是否只出现在特定环境？
6. 收集证据：在每个组件边界添加诊断日志
7. 追踪数据流：追溯到错误最初发生的位置

若问题偶发且难以复现：

• 收集多次失败日志，寻找共性模式
• 增加更详细的环境快照（配置、依赖版本、时间戳）

Phase 2：模式分析

修复之前找模式：

1. 找类似正常工作的代码/技能
2. 对比参考实现（完整阅读，不要略读）
3. 识别差异（列出每个不同点）
4. 理解依赖关系
5. 查阅官方文档/变更日志：部分问题源于依赖升级或配置变更
6. 搜索是否有已知的社区 issue 或讨论

Phase 3：假设与测试

科学方法：

1. 形成单一假设："我认为 X 是根因，因为 Y"
2. 最小化测试：一次只改一个变量
3. 验证后再继续
4. 记录：将假设、测试步骤、结果记录到 memory/debug_log.md，便于回溯
5. 不知道就说不知道，不要假装

Phase 4：实现

1. 创建失败测试用例 — 最简单的复现方式
2. 单一修复 — 只改根因，不要"顺便改进"
3. 验证修复 — 测试通过了吗？其他测试坏了吗？
4. 运行完整测试套件 — 包括 openclaw doctor 或相关健康检查，确保无新问题
5. 3+ 次修复失败 → 质疑架构 — 说明架构本身有问题

Phase 5：复盘改进

修复成功后：

1. 总结根因和修复经验
2. 更新相关文档（避免重复踩坑）
3. 将教训写入 lessons.md（路径：memory/lessons.md）
4. 评估是否需要更新调试流程本身

红色警戒（立即停止！）

以下想法出现 → 立即停止，回到 Phase 1：

• "先快速修复，回头再调查"
• "试试改 X，看看有没有用"
• "一次改多个，跑测试"
• "跳过测试，我手动验证"
• "大概是 X，我直接修"
• "再试一次修复"（已经试了 2+ 次）
• 每次修复都暴露新的不同位置的问题
• "我已经花了很多时间，必须修好它" → 情绪化修复，回到 Phase 1 重新评估问题边界
• 用户催促"别分析了直接修" → 坚持流程，记录用户豁免后继续

示例对话

用户：诊断
Agent：好的，我们走根因猎人五阶段。请问具体是什么问题？

用户：运行脚本时报错
Agent：了解。请提供完整的错误信息，以及复现步骤。

用户：[提供信息]
Agent：Phase 1 完成：已理解问题...
       回滚验证：问题是否与最近变更相关...
       现在进入 Phase 2：对比类似代码...

用户：[催促"别分析了直接修"]
Agent：（记录用户豁免）理解，但我们仍走流程，确保修复不引入新问题...
       形成假设：X 可能是根因...

用户：[确认]
Agent：Phase 3 执行最小化测试...
       测试结果：[结论]
       Phase 4 执行修复...

用户：[确认修复成功]
Agent：Phase 5 复盘完成。根因是...，已写入 lessons.md。

真实数据对比

version: 1.0.0 last_updated: 2026-05-22