修复 Bug：复现、定位、修复、回归

修 Bug 最忌讳"看到报错就试改"。稳定的修复流程是先复现、再定位根因、最小修复、回归验证、留下证据。本节把这套流程拆成可照做的步骤与检查点。

一、五阶段修复流程

阶段	目标	关键产出
1 稳定复现	用最小步骤稳定触发问题	复现条件、输入、预期与实际差异
2 定位根因	从现象追到代码层原因	报错栈、相关文件与调用链、根因假设
3 最小修复	只改必要部分解决根因	最小 diff，不夹带功能改动
4 回归验证	修复生效且不破坏既有行为	新增回归测试、全量测试结果
5 证据交付	说清根因、改动与验证方式	根因说明、改动清单、验证命令与结果

二、先复现，再动手

• 向代理提供：完整报错信息、复现步骤、相关环境（版本、配置、数据样例）、预期结果与实际结果。
• 让代理先运行现有测试或最小复现脚本确认问题存在；无法稳定复现的 Bug，应先补充复现手段，而不是直接修改代码。
• 复现条件要具体到"前置状态—操作输入—触发动作"，避免"偶尔出错"这类模糊描述进入修复任务。

三、定位根因而非压制症状

• 先用只读方式排查：可进入计划模式让代理只读分析报错栈、定位入口与调用链，确认根因假设后再退出计划模式修改。
• 区分"报错表象"与"根本原因"：例如空指针的根因可能是上游未做校验，而不是在出错处加一个空值兜底。
• 避免把错误静默吞掉、用特判掩盖边界输入、或绕过校验流程——这类"修复"会把问题推迟到更难排查的位置。

四、最小修复与回归测试

1. 先补一个能复现该缺陷的测试（先失败，即 red）。
2. 实施最小修复，使该测试通过（转绿，即 green）。
3. 运行相关测试与构建，确认既有用例不回归。
4. 通过只读的版本控制命令核对改动差异与文件清单，确认没有夹带无关重构。

让代理直接给出可运行的验证命令及其输出作为证据，而不是只口头声明"已修好"。

五、交付说明应包含什么

• 根因一句话结论 + 关键代码位置；改动文件清单与各自目的。
• 验证方式：执行了哪些测试/构建命令、结果如何。
• 影响范围与潜在副作用；是否需要数据迁移、配置调整或人工确认。
• 回退方式：若改动有问题，如何通过版本控制恢复到修复前状态。

常见误区	正确做法
未复现就修改	先建立稳定复现再改
只改报错处、不追上游	沿调用链定位根因
顺手重构无关代码	修复与重构分开提交
修复后不跑全量回归	补回归测试并跑相关测试集

六、小白照抄：从报错到修复的对话顺序

1. 先投喂完整现场：完整报错文本、复现步骤、环境与版本、输入数据样例、预期与实际差异；不要只贴一句"报错了"。
2. 要求先复现后诊断：让代理先运行现有测试或最小复现，确认问题可被稳定触发；无法复现时先补齐复现脚本或样例数据。
3. 只读定位根因：按 Shift+Tab 进入计划模式，请代理分析报错栈与调用链，给出根因假设与候选修复方案，先不改代码。
4. 最小修复：确认根因后退出只读分析，只改解决根因所必需的代码，不顺带重构与改风格。
5. 回归验证：先补复现失败的用例再使其转绿，运行相关测试集与构建；要求代理把执行命令和结果输出贴出来作为证据。
6. 人工复核后再收口：对运行中的应用可用 /verify 在代理自检之外做人工复核；确认无副作用、无密钥与调试残留后，再由人决定提交与回退预案。

七、"修好了"的证据清单

• 能稳定复现原问题的用例现已通过，且原失败现象不再出现。
• 相关测试集与构建/类型检查全部通过，输出结果可追溯。
• 根因、改动文件、改动目的、影响范围与回退方式均已写明。
• 没有把错误静默吞掉、没有用特判掩盖上游缺失的校验、没有新增绕过既有约束的分支。
• 同类输入的边界值（空值、超长、异常格式、缺失依赖）走查无新崩溃。

八、FAQ 与练习

问题	处理建议
时好时坏、无法稳定复现	先固定随机种子、排序顺序、并发时序与数据状态；记录触发频率与条件，优先写最小复现用例，不盲目改码。
多个报错互相纠缠	按依赖顺序先修阻断根因，验证通过后再处理次生现象；一次只聚焦一个根因，避免多改混杂。
代理反复改但测试仍红	要求它回到计划模式重新分析假设；每轮只改一处并说明验证方式，卡住时用检查点或 /rewind 回到最近可运行状态，不要在错误路径上连续叠加补丁。
修复引入了新的小问题	把新问题登记为独立缺陷，原修复先保证回归通过；修复与新问题分任务推进。

• 练习：找一个历史缺陷（或人为引入一个校验缺失），按六回合走完流程，交付"复现用例 + 根因说明 + 最小 diff + 验证输出 + 回退方式"五件套，并请一位只读审查者复核。