debug-mantra

调试准则

适用于任何调试会话的四步纪律。先逐字复述，然后按顺序执行。

首次回复时，首先逐字复述以下内容

准则：

1. 首先要确保可复现。 能否可靠地复现问题？
2. 弄清失败路径。 先用调试器；然后追踪源码并枚举可调参数；最后在代码中添加插桩。
3. 质疑你的假设。 什么情况能证明它不成立？
4. 每次运行都是一条线索。 交叉核对所有运行结果。

然后开始处理。

---

1. 可靠地复现

先构建可运行的复现用例，再做其他事。

• 可靠复现 → 将确切的步骤、输入和环境记录为可运行的产物：失败测试、curl 脚本、CLI 调用或回放工具。
• 不稳定复现 → 目前还无法调试这个 Bug。先提高触发率：循环触发、并行执行、增加压力、缩小时间窗口、注入休眠。50% 的偶发率可以调试；1% 则不行。
• 完全无法复现 → 停下。明确说明这一点。向用户请求环境访问权限、已捕获的产物（HAR、日志转储、核心转储），或添加插桩的许可。不要继续推测。

目标：获得快速（1–5 s）、确定性的通过／失败信号。固定时间、设定随机数生成器的种子、冻结网络、隔离文件系统。

2. 弄清失败路径

确认可以复现后，找出代码在哪里出错，以及是什么阻止了错误发生。差异有助于缩小搜索范围。按以下顺序尝试；只有前一种方法失败时才升级到下一种。

1. 附加调试器。 如果环境支持，附加调试器并单步执行到故障位置。一个断点胜过十条日志。在调整任何可调参数之前先这样做。
2. 追踪源码并枚举可调参数。 如果没有调试器（或调试器无法触及 Bug），就端到端追踪代码路径，并列出所有可能影响结果的可调参数：
   • 配置标志、环境变量、功能开关
   • 分支条件、输入形态
   • 时序、并发、构建选项 每个参数都是差异分析中可尝试改变的维度。每次只改变一个。
3. 在代码中添加插桩。 如果调整外部参数无法改变失败情况，就深入代码内部：在疑似故障位置添加 printf／日志语句，转储相关内部状态。为每个探针添加唯一前缀（例如 [DBG-a4f2]），这样只需一次 grep 即可清理。让追踪结果显示实际情况从何处偏离了你的模型。

3. 证伪假设

当出现一个可能的根本原因时，先仔细审视它，再进行测试。

• 它真的能从头到尾解释症状吗？逐步验证。
• 最简单的证明是什么？最清晰的证伪方法是什么？
• 先运行证伪测试。如果假设经受住了检验，它就有可能成立；如果不成立，你就避免了追查一个幻象。
• 提出 3–5 个按可能性排序的假设，而不是只提一个。只考虑单一假设会让你锚定在第一个看似合理的想法上。

4. 每次运行都是一条线索

在本次会话中持续记录每项实验，维护一份记录表。每条记录都应说明：改了什么、发生了什么、排除了什么或支持了什么。

• 出现新假设时，逐条检查记录表。它是否适用于每一条先前观察，而不只是最新的一条？
• 如果任何过去的运行结果与假设矛盾，那么这个假设就是错误的或不完整的——应加以完善或舍弃。
• 如果拿不准，就设计出结果足以确定结论的单个实验。接下来运行这个实验，而不是不断尝试相近的实验。
• 每次运行后更新记录表。它是你在整个会话中的记忆。

---

操作规则

• 每次调试会话只在首次回复时背诵一次口号段落。会话中途不要再次背诵。
• 逐字背诵。绝不改写、缩短或跳过任何一行。
• 如果用户说“跳过口号” → 跳过背诵，但仍要默默执行这四个步骤。
• 按顺序执行这四个步骤：
  • 在满足 #1（存在可靠的复现方法）之前，不要提出修复方案。
  • 在 #2 缩小故障路径范围之前，不要开始测试假设。
  • 在 #3 尝试证伪假设之前，不要认定某个假设成立。
  • 在 #4 对照所有先前线索进行确认之前，不要断定某个假设正确。
• 如果你发现自己在没有可靠复现方法的情况下提出了修复方案，请停下来，返回步骤 1。
• 口号是你在整个会话中必须遵守的约束——不是要传达给用户的建议。