bug-fix

name	bug-fix
description	【强制调用】用户说"fix/修改bug/修复/修一下/解决报错/不工作/报错/异常/debug/not working/error"等任何表达修复意图时必须调用。先诊断根因，评估难度，简单Bug直接修复，复杂Bug出多方案供选择。全程分支隔离，自测验证，最小化对其他模块影响。不适用于PPT、文档等非代码任务。

Bug 修复流程

核心原则

1. 先诊断，再开药 — 使用 systematic-debugging 完成根因分析，根因未确认前禁止动手
2. 最小影响 — 修改前评估对其他模块的影响；若引入新 bug，一并修复
3. 分支隔离 — 使用 using-git-worktrees 创建 fix/issue-<编号>-<描述> 分支，禁止在主分支直接改
4. 自测通过再交付 — 先模拟验证，再浏览器实测，全部通过才算完成
5. 失败不钻死角 — 方案级失败换方案，代码级失败就地修，连续 3 次失败暂停并告知用户
6. 全程记录 — 修复前读取项目 BUGFIX_LOG.md，完成后更新；同步写 memory 日志
7. 中文交互

---

流程

一、收集信息

每次最多问 3 个问题：具体表现？预期行为？复现步骤？错误日志？必现还是偶发？安全类 Bug 追加追问数据泄露风险和外部触发可能。

二、根因分析

使用 systematic-debugging：读错误 → 定位代码 → 追踪数据流 → 检查近期变更 → 确认根因。

三、难度评估

🟢 简单 —— 跳过方案设计，直接修复： 拼写错误、字段未对齐、缺空值判断、逻辑符号反了、缺 await、配置遗漏、类型不匹配等，≤5 行、单文件改动。

🔴 复杂 —— 必须走方案设计： 其余所有情况。

四、方案设计（仅复杂 Bug）

产出 ≥2 个方案，每个方案评估对其他模块的影响：

方案 N：[名称]
- 思路：[一句话]  |  修改范围：[文件清单]
- 优点：[2-3个]   |  缺点/风险：[1-2个]
- 破坏性变更：[是/否]  |  对其他模块的影响：[说明]

选最优并说明理由，难分优劣则交给用户选择。

五、修复计划 + 用户确认

## Bug 修复计划
Bug：[一句话]  |  根因：[一句话]  |  难度：[简单/复杂]
[复杂] 选定方案：[方案N] — 理由：[...]
修改文件：path/file — [改什么]
验证：1.模拟[...] 2.浏览器[...]
影响范围：[说明]  |  预计行数：[...]

六、安全漏洞

涉及 XSS、SQL 注入、权限绕过、敏感数据泄露等：不公开讨论细节、优先评估影响面、commit 用 fix(security): <描述>、修复方案本身不能降低安全标准。

七、实施修复

1. 按计划修改，不顺手重构无关代码
2. 遵循项目编码规范，高内聚低耦合
3. 修改时检查对其他模块的影响，发现会引入新 bug 则调整方案一并处理
4. 需大面积架构调整 → 立即停止，向用户说明，由用户决策

八、验证测试

1. 模拟验证（先做）： 构造输入 → 跟踪执行路径 → 验证输出 → 确认异常路径也处理
2. 浏览器实测： 按复现步骤操作，确认 Bug 不复现，同时检查相关功能无回归
3. 自动化测试（如有）： 运行测试套件

九、迭代修复

🟡 代码细节 → 直接修，重新验证，最多 3 轮
🔴 方案根本错误 → 优先调整方向；实在不行 git reset --hard（仅兜底），换备选方案
⛔ 所有方案失败 → 回到根因分析；连续 3 次失败暂停，告知用户

---

修复日志（双写）

项目日志：<项目根目录>/BUGFIX_LOG.md

修复前读取，完成后更新。格式：

## Bug 修复日志

### 2026-05-05：登录按钮点击无响应
- **根因：** 前端 onClick 绑定的事件名与后端接口路径不一致
- **难度：** 简单
- **方案：** 统一字段名为 `userLogin`
- **分支：** `fix/issue-1024-login-btn`
- **修改文件：** `src/api/auth.js`、`src/components/Login.vue`

Memory 日志

同步记录到 memory（project 类型），用于跨会话追踪迭代过程：

轮次	方案	结果	失败原因/新bug
1	A	❌	影响模块X，导致新bug
2	B	✅	-

---

红牌

⛔ 禁止	✅ 正确
没找到根因就改代码	回到根因分析
在主分支直接改	必须建分支
改完不验证	先模拟再浏览器
凑合能用的方案	选最优，选不出交给用户
顺手重构无关代码	只修 Bug
大改不告知用户	第一时间说明
不检查对其他模块的影响	修改前评估，引入新bug一并修