Diagnosing Bugs Zh

---
name: diagnosing-bugs-zh
description: 疑难 Bug 诊断、性能回退排查、系统化调试方法。当用户说「帮我 debug」「诊断一下这个问题」「这个 bug 我查了三天」「偶现问题怎么复现」「接口突然变慢了」「报错但不知道哪里出的」「怎么定位性能退化」，或任何报错、失败、崩溃、变慢、结果不对的场景使用。六个阶段：先造一个"能变红"的反馈回路（失败测试 / curl 脚本 / 回放 / 二分），再复现并最小化，再列 3–5 个可证伪假设，按假设打探针，写回归测试后修，最后清理探针。没有反馈回路不许猜。也覆盖「偶现的空指针」「怎么定位」「数据不一致问题」这类说法。改编自 Matt Pocock 的 diagnosing-bugs（MIT），中文化并衔接线上排查简报。
author: Captain
version: 0.1.1
display_name: "Bug 诊断法"
display_name_en: "Diagnosing Bugs (zh)"
description_zh: "六阶段调试纪律：先造能变红的反馈回路，再复现最小化、列可证伪假设、定向探针、先写回归测试再修、最后清理；拒绝无回路的猜测。"
description_en: "A six-phase debugging discipline: build a red-capable feedback loop first, then reproduce and minimise, rank falsifiable hypotheses, probe, write the regression test before the fix, clean up; no guessing without a loop."
tags:
  - "Bug 诊断"
  - "调试"
  - "debugging"
  - "性能回退"
  - "反馈回路"
  - "根因分析"
examples_zh:
  - "这个偶现的空指针帮我系统地查一下"
  - "接口 P99 从 200ms 涨到 2s，怎么定位"
  - "用诊断法帮我复现并修这个数据不一致问题"
examples_en:
  - "Systematically diagnose this intermittent NPE"
  - "P99 went from 200ms to 2s, how do I locate it"
  - "Reproduce and fix this data inconsistency using the discipline"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "🔬" } }
---

# Bug 诊断法

## 何时用
报错、失败、崩溃、变慢、结果不对，且第一次看不出哪里错的时候用；简单明显的 bug（看一眼堆栈就知道哪一行错了）不需要走六个阶段，直接修。

## 边界
没有反馈回路（阶段 1）不许进入假设阶段——盯代码盯到天亮也没用。回归测试必须在 bug 真实发生的调用点重现，缝太浅就是假信心而不是验证。清理阶段不做完不算完成：所有 `[DEBUG-…]` 探针必须删除，一次性原型必须移到明确标记的目录或删除。

对付疑难 Bug 与性能回退的一套纪律。**只有明确说明理由才能跳过某个阶段。**
线上正在冒烟、需要先出简报稳住局面时，先用「线上排查简报」技能整理时间线，再回到这里找根因。

## 脱敏

本技能会让你展示命令、输出与抓取的产物。**先脱敏再展示**：凭证一律写成 `<REDACTED>`；构造回路时从环境变量读凭证，让密钥留在环境里而不是出现在你贴出来的内容里；抓包/日志只引用带信号的那几行。脱敏后信息不够就直说，问用户要。

## 阶段 1：造一个反馈回路（这就是本技能的全部）

其余阶段都是机械的。只要有一个**紧凑的、能对这个 bug 变红**的通过/失败信号，二分、假设检验、加探针都只是在消费它；没有信号，盯代码盯到天亮也没用。在这里投入不成比例的精力，**激进、有创造力、拒绝放弃**。

构造方式，大致按此顺序尝试：

1. **失败测试**：在能触达 bug 的最近一层（单元 / 集成 / e2e）。
2. **curl / HTTP 脚本**打本地服务。
3. **CLI + 固定输入**，把 stdout 与已知正确快照 diff。
4. **无头浏览器脚本**（Playwright）驱动 UI，断言 DOM / console / 网络。
5. **回放真实产物**：把线上请求 / 事件日志存盘，单独回放这条代码路径。
6. **一次性小环境**：只起一个服务、mock 依赖，一个函数调用打到 bug 路径。
7. **属性 / 模糊循环**："偶尔输出错"就跑 1000 个随机输入找失败模式。
8. **二分脚本**：bug 出现在两个已知状态之间（提交、数据集、版本）就自动化"切到 X → 检查 → 重复"，交给 `git bisect run`。
9. **差分回路**：同一输入过旧版 / 新版（或两套配置），diff 输出。
10. **人肉回路（最后手段）**：必须有人点的，用一个结构化脚本指挥人：打印步骤 → 等输入 → 记录结果，让输出仍能回流给你。

**把回路当产品打磨**：更快（缓存初始化、缩小范围）、信号更尖（断言具体症状而不是"没崩"）、更确定（固定时间、随机种子、隔离文件系统与网络）。30 秒的抖动回路比没有好不了多少；2 秒的确定回路是超能力。

**非确定性 bug**：目标不是干净复现，是**提高复现率**。循环 100 次、并行、加压、缩小时间窗、插 sleep。50% 复现率能查，1% 不能——把它抬到能查为止。

**真的造不出回路**：明确停下来说，列出试过什么，向用户要：(a) 能复现的环境；(b) 脱敏后的抓取产物（HAR、日志、core dump、带时间戳的录屏）；(c) 允许加临时线上探针。**没有回路不进入假设阶段。**

**完成标准**：你能说出**一条命令**（脚本 / 测试 / curl），并且**已经至少跑过一次**（贴出命令与脱敏输出），它满足：
- [ ] 能变红：驱动真实 bug 路径并断言**用户描述的那个症状**；修好后会变绿。
- [ ] 确定：每次跑结论一致（偶现 bug 则复现率已固定在可查水平）。
- [ ] 快：秒级。
- [ ] 无人值守可跑。

发现自己在没有这条命令前就读代码建理论——**停**，这正是本技能要防的失败。

## 阶段 2：复现 + 最小化

跑回路，看它变红。确认：是**用户描述的那个**失败而不是旁边另一个；多次可复现；已记录精确症状（报错文本、错误输出、耗时）。
然后**最小化**：逐一删输入、调用方、配置、数据、步骤，每删一项重跑，只保留"删了就变绿"的部分。最小复现缩小假设空间，也是阶段 5 的回归测试。

## 阶段 3：假设

先列 **3–5 个按可能性排序的假设**再验证任何一个——只想一个会锚定在第一个"像"的念头上。每个假设必须**可证伪**：

> "如果原因是 X，那么改 Y 会让 bug 消失 / 改 Z 会让它更严重。"

说不出预测的假设是感觉，丢掉或磨尖。**验证前把排序给用户看**：他们常有领域知识能瞬间重排（"我们刚发了 #3 相关的改动"）。用户不在也不阻塞，按你的排序继续。

## 阶段 4：探针

每个探针对应阶段 3 的一个具体预测，**一次只改一个变量**。优先级：调试器 / REPL 断点 > 边界处的定向日志 > 绝不"全打日志再 grep"。
所有调试日志加唯一前缀如 `[DEBUG-a4f2]`，清理时一条 grep 搞定。
**性能回退分支**：日志通常是错的工具。先建基线测量（计时脚本、profiler、执行计划），再二分。先测量后修。

## 阶段 5：修复 + 回归测试

**先写回归测试再修**，前提是存在**正确的缝**：测试要在 bug 真实发生的调用点重现它。缝太浅（需要多个调用方而单元测试只有一个）就会给假信心。
**没有正确的缝本身就是发现**：记下来，架构在阻止 bug 被锁定。
有缝就：最小复现改成失败测试 → 看它失败 → 修 → 看它通过 → 用阶段 1 的回路跑原始（未最小化）场景。

## 阶段 6：清理

```
- [ ] 原始复现不再复现（重跑阶段 1 回路）
- [ ] 回归测试通过（或已记录"无缝"）
- [ ] 所有 `[DEBUG-…]` 探针已删（grep 前缀）
- [ ] 一次性原型已删或移到明确标记的 debug 目录
- [ ] 提交信息里写明最终成立的假设，让下一个人少走弯路
```

---
改编自 [mattpocock/skills](https://github.com/mattpocock/skills) 的 `diagnosing-bugs`（MIT）。改动见 ATTRIBUTION.md。