诊断调试流程

当用户说“诊断这个”/“调试这个”、报告一个错误、描述某处崩溃/失败/异常，或指出某个性能退化时，启动此诊断流程。

阶段一：构建反馈闭环（核心技能）

这是关键所在。其他都是机械操作。如果你有一个快速、确定、可由智能体运行并通过/失败的信号来检测该缺陷，你将能定位原因——二分查找、假设检验和插桩都依赖该信号。没有它，再盯着代码也没用。

在此阶段投入不成比例的努力。要激进，要富有创造力，绝不放弃。

构建方法（按推荐顺序尝试）：

1. 在能触达缺陷的最外层进行测试（单元测试、集成测试、端到端测试）
2. 对运行中的开发服务器发起 curl / HTTP 脚本请求
3. 通过 CLI 调用带有测试输入文件的操作，并与已知正确的快照进行 stdout 对比
4. 无头浏览器脚本（Playwright / Puppeteer）——驱动 UI，断言 DOM/控制台/网络状态
5. 回放已捕获的追踪数据——将真实网络请求/有效载荷/事件日志保存至磁盘，并在隔离环境下重新执行
6. 一次性测试框架——搭建系统的最小子集（一个服务，模拟依赖），通过单次函数调用触发缺陷路径
7. 属性测试/模糊测试循环——若缺陷表现为“偶尔输出错误”，则对 1000 个随机输入运行并寻找失败模式
8. 二分搜索框架——若缺陷出现在两个已知状态之间（提交记录、数据集、版本），自动化“从状态 X 启动，检查，重复”，以便执行 git bisect run
9. 差分循环——对同一输入分别在旧版本 vs 新版本（或两种配置）下运行，比较输出差异
10. 人机交互 bash 脚本——最后手段。如果必须由人点击，使用 scripts/hitl-loop.template.sh 引导他们，保持结构清晰。捕获的输出反馈给你

建立正确的反馈闭环，问题就解决了 90%。

迭代优化闭环本身

将此闭环视为产品。一旦有了 某个 闭环，请思考：

• 能否让它更快？（缓存设置，跳过无关初始化，缩小测试范围）
• 能否让信号更清晰？（针对具体症状断言，而非仅“未崩溃”）
• 能否让它更确定？（固定时间，设定随机数种子，隔离文件系统，冻结网络）

一个 30 秒且易出错的闭环几乎等同于没有闭环。一个 2 秒且确定的闭环就是调试神器。

非确定性缺陷

目标不是完美复现，而是 更高的复现率。循环触发 100 次，并行执行，增加压力，收窄时间窗口，注入休眠。50% 复现率的缺陷可调试；1% 则不可——持续提高直至可调试。

当你真的无法构建闭环时

停止并明确说明。列出你尝试过的所有方法。向用户请求：（a）能复现该缺陷的环境访问权限，（b）一个已捕获的工件（HAR 文件、日志转储、核心转储、带时间戳的屏幕录像），或（c）临时在生产环境中添加插桩的许可。没有闭环不得进入下一阶段。

在进入阶段二之前，你必须拥有一个值得信任的闭环。

阶段二：复现

运行闭环。观察缺陷显现。

确认：

• 闭环产生的故障模式与 用户 描述的一致——不是附近发生的另一种故障。错误的 bug = 错误的修复。
• 故障可在多次运行中复现（或非确定性 bug 能在足够高的频率下复现以支持调试）
• 你已经精确捕捉了症状（错误信息、错误输出、慢速时序），以便后续阶段验证修复确实解决了问题

在你复现 bug 前，请勿继续。

阶段三：提出假设

在测试任何假设前，生成 3–5 个排序后的假设。单一假设会让人陷入第一个看似合理的想法。

每个假设必须是 可被证伪的：陈述其预测结果。

格式：“如果 <X> 是根本原因，那么 <修改 Y> 将使缺陷消失 / <修改 Z> 将使情况恶化。”

若无法陈述预测，则该假设只是感觉——舍弃或精炼它。

将排序后的列表展示给用户后再进行测试。 他们通常拥有领域知识可立即重新排序（“我们刚部署了对 #3 的修改”），或知道哪些假设已被排除。这是低成本检查点，省时省力。若用户离线，可按自己的排序继续。

阶段四：插桩

每个探测必须对应阶段三中的一个具体预测。每次只改变一个变量。

工具偏好：

1. 调试器 / REPL 检查（如果环境支持）。一个断点胜过十个日志
2. 在区分假设的边界处进行精准日志记录
3. 永远不要“记录一切然后 grep”

为每个调试日志打上唯一前缀标签，例如 [DEBUG-a4f2]。结束后清理只需一次 grep。未打标签的日志会保留；打了标签的日志会被清除。

性能测试分支：对于性能回归，日志通常无效。应改为：建立基准测量（计时器、performance.now()、分析器、查询计划），然后进行二分搜索。先测量，后修复。

阶段五：修复 + 回归测试

在修复前编写回归测试——但仅当存在 正确切入点 时才这样做。

正确切入点是指能真实体现调用现场发生的确切缺陷模式的接口。如果唯一可用的切入点太浅显（单调用者测试，而缺陷需要多个调用者；单元测试无法还原触发缺陷的完整链条），则在此处的回归测试会产生虚假信心。

若不存在正确切入点，这本身就是发现。 记录下来。代码库架构阻止了缺陷被锁定。将此标记为下一阶段。

若存在正确切入点：

1. 将最小化的复现代码转为该切入点下的失败测试
2. 观察其失败
3. 应用修复
4. 观察其通过
5. 针对原始（未最小化）场景重新运行阶段一的反馈闭环

阶段六：清理 + 事后复盘

完成前必须满足以下条件：

• 原始复现已不再复现（重新运行阶段一闭环）
• 回归测试通过（或文档说明了无合适切入点）
• 所有 [DEBUG-...] 插桩代码已移除（用前缀 grep 检查）
• 一次性原型已删除（或移至明确标记的调试位置）
• 被证明正确的假设已在提交/PR 消息中说明——让下一个调试者受益

随后提问：什么本可以防止此缺陷？ 若答案涉及架构变更（无良好测试切入点、调用链纠缠、隐藏耦合），则将具体情况移交 /improve-codebase-architecture 技能。在修复上线后才给出建议——你现在掌握的信息比开始时更多。