缺陷诊断（Diagnosing Bugs）

一套处理棘手缺陷（hard bugs）的严谨方法。只有在理由明确时才能跳过阶段。

探索代码库时，读取 GLOSSARY.md（如果存在），建立对相关模块的清晰心智模型，并检查所涉及区域的 ADR。

脱敏（Redact）

本技能要求展示命令、输出及已捕获的制品。首先删去每一项敏感信息：用 <REDACTED> 代替。让反馈循环通过环境变量使用凭据，使凭据留在环境中，而不是出现在展示内容里。抓取的制品可能包含认证头，只引用能够体现诊断信号的行。

如果脱敏后的输出不足以诊断缺陷，明确说明并询问用户。

阶段 1：建立反馈循环（feedback loop）

**这就是本技能的核心。其他一切都只是机械操作。如果你为该缺陷建立了一个紧密（tight）**的通过/失败信号：一个会在_这个_缺陷上变红的信号：就一定能找到原因；二分查找（bisection）、假设检验（hypothesis-testing）和插桩（instrumentation）都只是在使用这个信号。没有这种信号，无论盯着代码看多久都无济于事。

在这里投入超出常规比例的精力。要积极。要有创造性。拒绝放弃。

构建反馈循环的方法：大致按此顺序尝试

1. 在任何能够触达缺陷的接缝处编写失败测试（failing test）：单元测试、集成测试或端到端测试。
2. 针对正在运行的开发服务器编写 Curl / HTTP 脚本。
3. 使用夹具输入进行 CLI 调用（CLI invocation），并将标准输出与已知正确的快照进行差异比较。
4. 编写无头浏览器脚本（headless browser script）（Playwright / Puppeteer）：驱动 UI，并对 DOM、控制台和网络作出断言。
5. **重放已捕获的跟踪（captured trace）。**将真实网络请求、载荷或事件日志保存到磁盘；再通过隔离的代码路径重放。
6. **一次性测试支架（throwaway harness）。**启动系统的最小子集（一个服务、模拟依赖），通过一次函数调用执行缺陷代码路径。
7. **属性测试或模糊测试循环（property/fuzz loop）。**如果缺陷是“有时输出错误”，就运行 1000 个随机输入并寻找失败模式。
8. **二分测试支架（bisection harness）。**如果缺陷出现在两个已知状态（提交、数据集、版本）之间，就自动执行“在状态 X 启动、检查、重复”，以便使用 git bisect run。
9. **差分循环（differential loop）。**让相同输入分别经过旧版本和新版本（或两种配置），然后比较输出差异。
10. **HITL bash 脚本。**这是最后手段。如果必须由人点击，就通过 scripts/hitl-loop.template.sh 引导_该用户_，使循环仍然保持结构化。捕获的输出会反馈给你。

建立正确的反馈循环，缺陷就已经解决了 90%。

收紧循环（Tighten the loop）

把循环当作产品。一旦有了_一个_循环，就要将其收紧：

• 能否让它更快？（缓存设置、跳过无关初始化、缩小测试范围。）
• 能否让信号更尖锐？（针对具体症状断言，而不是只断言“没有崩溃”。）
• 能否让它更具确定性？（固定时间、设置 RNG 种子、隔离文件系统、冻结网络。）

一个耗时 30 秒且不稳定的循环几乎不比没有循环好；一个耗时 2 秒且结果确定的循环才是紧密循环：这是调试超能力。

非确定性缺陷（Non-deterministic bugs）

目标不是获得干净复现，而是获得更高的复现率（reproduction rate）。让触发器循环 100 次、并行运行、增加压力、缩窄时序窗口、注入休眠。复现率为 50% 的不稳定缺陷可以调试；1% 的不行：持续提高复现率，直到可以调试。

确实无法建立循环时

停止并明确说明无法建立循环。列出已经尝试的事项。向用户请求：(a) 访问能够复现问题的环境；(b) 已脱敏的捕获制品（HAR 文件、日志转储、核心转储、带时间戳的屏幕录像）；或者 (c) 添加临时生产插桩（production instrumentation）的许可。没有循环时，不要继续提出假设。

完成标准：能够变红的紧密循环

当循环既紧密（tight）又具备变红能力（red-capable）时，阶段 1 才算完成：你能够给出一条命令（脚本路径、测试调用或 curl），并且已经至少运行过一次（展示脱敏后的调用及其输出），同时它满足：

• 具备变红能力（Red-capable）：它驱动真实缺陷代码路径，并断言用户描述的确切症状，因此会在该缺陷上变红，并在修复后变绿。不是“运行时不报错”：它必须能够_捕获这个具体缺陷_。
• 结果确定（Deterministic）：每次运行都得出相同结论（对于不稳定缺陷，按上文固定一个较高复现率）。
• 快速（Fast）：以秒而不是分钟计。
• 智能体可运行（Agent-runnable）：你可以无人值守地运行；只有通过 scripts/hitl-loop.template.sh 才允许人在循环中参与。

如果发现自己在这条命令出现前就开始阅读代码并构建理论，**立即停止：直接跳到假设正是本技能要防止的失败。**没有具备变红能力的命令，就不能进入阶段 2。

阶段 2：复现并最小化（Reproduce + minimise）

运行循环。观察它变红：缺陷出现。

确认：

• 循环产生的是用户描述的失败模式：而不是恰好发生在附近的另一个失败。缺陷找错 = 修复错误。
• 失败可以在多次运行中复现（对于非确定性缺陷，则达到足以开展调试的高复现率）。
• 已经捕获确切症状（错误消息、错误输出、缓慢耗时），使后续阶段可以验证修复确实解决了它。

最小化（Minimise）

循环变红后，将复现场景缩减到仍会变红的最小场景。每次只删减输入、调用方、配置、数据或步骤中的一项，每次删减后重新运行循环：只保留对失败起承重作用（load-bearing）的内容。

这样做的原因：最小复现（minimal repro）会缩小阶段 3 的假设空间（留下更少的可疑活动部件），并成为阶段 5 中干净的回归测试。

只有当每个剩余元素都在承重时才算完成：删除其中任何一个都会让循环变绿。

完成复现并且完成最小化之前，不要继续。

阶段 3：提出假设（Hypothesise）

在测试任何假设之前，生成 3–5 个排序后的假设（ranked hypotheses）。只生成一个假设会锚定在第一个看似合理的想法上。

每个假设都必须可证伪（falsifiable）：明确写出它所作的预测。

格式：“如果 <X> 是原因，那么 <changing Y> 会使缺陷消失，或 <changing Z> 会使缺陷恶化。”

如果无法写出预测，这个假设就只是一种感觉：丢弃它或继续磨砺。

**测试之前向用户展示排序后的列表。**用户往往掌握能够立即改变排序的领域知识（“我们刚部署了与第 3 项有关的变更”），或者知道哪些假设已经被排除。这是成本低廉却能节省大量时间的检查点。不要在这里阻塞：如果用户暂时离开（AFK），就按照你的排序继续。

阶段 4：插桩（Instrument）

每个探针（probe）都必须对应阶段 3 中的一项具体预测。每次只改变一个变量。

工具优先顺序：

1. 如果环境支持，优先使用调试器或 REPL 检查（Debugger / REPL inspection）。一个断点胜过十条日志。
2. 在能够区分不同假设的边界处添加定向日志（targeted logs）。
3. 绝不要“记录一切再 grep”。

用唯一前缀标记每条调试日志，例如 [DEBUG-a4f2]。这样最后只需一次 grep 即可完成清理。未标记的日志保留，已标记的日志删除。

**性能分支（Perf branch）。**对于性能回退，日志通常不是正确工具。应当先建立基线测量（计时支架、performance.now()、性能分析器、查询计划），再进行二分查找。先测量，后修复。

阶段 5：修复并添加回归测试（Fix + regression test）

在修复之前编写回归测试：但前提是存在一个正确接缝（correct seam）。

正确接缝能让测试按调用点实际发生的方式执行真实缺陷模式（real bug pattern）。如果唯一可用的接缝过浅（缺陷需要多个调用方，却只能进行单调用方测试；单元测试无法复制触发缺陷的调用链），在该处编写回归测试只会带来虚假信心。

**如果不存在正确接缝，这本身就是一项发现。**将其记录下来。代码库架构正在阻止你锁定该缺陷。把它标记给下一阶段。

如果存在正确接缝：

1. 在该接缝处把最小复现转换为失败测试。
2. 观察测试失败。如果通过修改代码或夹具（fixture）强制制造红灯，先与干净副本进行 diff，证明修改确实生效，再信任该结果。
3. 应用修复。
4. 观察测试通过。
5. 针对原始（未最小化）场景重新运行阶段 1 的反馈循环。

阶段 6：清理（Cleanup）

宣布完成之前必须满足：

• 原始复现不再出现（重新运行阶段 1 循环）
• 回归测试通过（或者已记录缺少接缝）
• 删除所有 [DEBUG-...] 插桩（对前缀执行 grep）
• 删除一次性原型（或者移动到明确标记的调试位置）
• 在提交或 PR 消息中说明最终证实正确的假设：让下一位调试者能够从中学习