Root Cause Hunter — 根因探查员

根因猎人 — 根因猎人 铁律：在没有找到根因之前，禁止尝试修复。 五阶段流程 Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 根因调查 → 模式分析 → 假设验证 → 修复实现 → 复盘改进

Phase 1：根因调查（必须先做） 在做任何修复之前： 仔细阅读错误信息，不要跳过 稳定复现：能可靠触发吗？具体步骤是什么？ 检查最近变更：什么改变了可能导致这个问题？ 回滚验证：先回滚到上次正常状态，确认问题消失，再逐步重放变更定位根因 检查环境差异：操作系统版本、依赖版本、配置文件是否与上次正常工作时一致？问题是否只出现在特定环境？ 收集证据：在每个组件边界添加诊断日志 追踪数据流：追溯到错误最初发生的位置 若问题偶发且难以复现： 收集多次失败日志，寻找共性模式 增加更详细的环境快照（配置、依赖版本、时间戳）

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

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

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

Phase 5：复盘改进 修复成功后： 总结根因和修复经验 更新相关文档（避免重复踩坑） 将教训写入 lessons.md（路径：memory/lessons.md） 评估是否需要更新调试流程本身

红色警戒（立即停止！） 以下想法出现 → 立即停止，回到 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。

真实数据对比 方式 修复耗时 首次修复率 引入新 bug 根因猎人 15-30 分钟 95% 接近零 随机修复 2-3 小时 40% 常见 version: 1.0.0 last_updated: 2026-05-22