用途
Systematic Debugging Protocol 是一套有纪律、以证据为基础的调试方法，旨在防止盲目猜测，确保找到问题的根本原因。它适用于调查复杂、间歇性或难以解释的问题，例如 bug、竞态条件或无法解释的失败。
主要能力
该协议将调试过程划分为四个阶段：
阶段一：REPRODUCE（建立基准事实）
目标是在任何调查之前，先创建可靠的复现步骤。具体动作包括：记录触发 bug 的精确步骤；记录环境细节（操作系统、版本、配置、内存、网络）；确定发生频率（总是、有时、特定条件）；捕获确切的错误信息、堆栈跟踪和截图；在不同环境中测试以隔离变量。关键问题包括：最后一次正常工作是什么时候？此后发生了什么变化（代码、依赖、配置、基础设施）？是否与特定环境、数据或时序相关？输出是能够可靠触发问题的清晰复现步骤。
阶段二：ISOLATE（缩小范围）
目标是将搜索空间从「整个代码库」缩小到「特定组件」。技术包括：
- 二分查找：确定正常状态和故障状态两个点，测试中点，递归进入故障的一半，直到定位变更。
- Git Bisect（用于回归问题）：通过 git bisect start、git bisect bad HEAD、git bisect good <已知良好提交> 等命令，让 Git 检出提交进行测试，逐步定位罪魁祸首。
- 代码消除：注释掉部分代码以隔离问题，创建最小复现案例，剥离所有非必要内容。
- 环境隔离：在隔离环境中执行失败路径（最小复现；仅在用户要求测试时才写单元测试），比较正常与故障环境，使用全新安装以消除污染。
输出是「bug 位于[特定组件/函数/行范围]」。
阶段三：DIAGNOSE（理解根本原因）
目标是确切知道 bug 为什么发生，而不仅仅是发生在哪里。采用科学方法：观察、假设、预测、用证据测试、迭代。日志策略建议在边界处添加战略性日志，例如函数入口、处理后和函数退出。常见根因对照表包括：本地正常但 CI 失败（环境差异、时序、资源）；间歇性失败（竞态条件、不稳定网络、资源争用）；先工作后停止（状态突变、内存泄漏、缓存污染）；数据错误（类型强制转换、编码、时区、精度）；静默失败（被吞掉的异常、异步错误、缺少 await）。输出是带有证据的根本原因清晰解释。
阶段四：FIX & VERIFY（解决与预防）
目标是修复问题并防止回归。修复流程：实施最小修复（尽可能少改动）；检查是否存在类似模式；审查修复的副作用（阅读其涉及的调用方、输入和错误路径）；记录修复（为什么发生、如何预防）。仅在用户要求测试时，编写捕获该 bug 的失败测试。验证清单包括：审查显示阶段三的根本原因已解决而非仅症状；修复已产生的输出（复现、完成工作的命令）确认了修复；修复在所有受影响环境中有效；未引入新的警告或错误。预防措施包括：在边界处添加守卫/验证；改进错误信息以便未来调试；为其他开发者记录陷阱；考虑架构变更是否能防止类似 bug。
使用方式
该技能以协议形式提供，包含快速参考和输出模板。快速参考为：1. REPRODUCE → 我能可靠触发它吗？2. ISOLATE → 它到底在哪里失败？3. DIAGNOSE → 它为什么失败？4. FIX → 我如何永久修复它？输出模板为 Markdown 格式，包含 Bug Investigation 标题，以及 Reproduction（复现步骤、环境细节、频率）、Isolation（使用的搜索方法、缩小到的范围）、Root Cause（实际错误、发生原因、证据）、Fix（代码变更、审查确认了什么、无法确认什么）、Prevention（如何防止类似 bug、文档更新）等部分。
适用场景
适用于调查 bug、竞态条件、回归问题、间歇性故障、无法解释的失败，以及本地正常但 CI 失败、先工作后停止、数据错误、静默失败等场景。
限制
该技能明确列出调试反模式：不要猜测并希望（随机更改）；不要在没有证据的情况下假设知道问题；不要信任注释/文档胜过实际代码行为；不要在生产环境用会忘记删除的打印语句调试；不要修复症状而非根本原因；不要一次做多个更改。应当：用证据验证假设；一次只改一件事；记录实际值而非期望值；信任代码胜过文档；卡住时休息（新鲜视角有帮助）。