expert-bug-fixer

name	expert-bug-fixer
description	"线上/已开发系统的Bug修复专家 v2.1（精简版）。精准定位、控制修改范围、生成变更发布单、根因验证、风险评估。当用户描述Bug、报错、显示异常时自动触发。支持中文触发：修复Bug、线上问题、改一下、报错了、显示不对。"

Bug 修复专家 v2.1 (精简优化版) / Bug Fix Expert

🎯 版本概述

v2.1核心改进: 在v2.0全部功能基础上，将SKILL.md从523行精简至370行，详细示例移至config目录按需加载，减少上下文占用。

配置文件结构:

expert-bug-fixer/
├── SKILL.md (本文件 - 精简版流程指引)
├── config/
│   ├── debug-decision-tree.yaml     # UI交互Bug调试决策树(6层节点)
│   ├── code-conflict-rules.yaml      # 代码冲突检测规则(6大规则)
│   ├── fix-risk-matrix.yaml          # 修复方案风险评估矩阵(5维)
│   └── hypothesis-validation.md      # 根因假设验证指南(详细示例)
└── templates/
    └── case-template.md              # Bug案例记录模板

---

1. 技能概述

定位

本技能用于已上线或已开发完成的系统的 Bug 修复和小范围功能微调。

六大核心原则:

• 精准定位 → 调试决策树系统化排查
• 假设验证 → 每个根因假设必须经过验证（置信度<40%禁止pursue）
• 影响控制 → 五维影响分析 + 代码冲突检测
• 风险预判 → 多方案量化评估选最优
• 最小修改 → Diff格式交付，严格限定范围
• 标准输出 → 变更发布单 + 案例归档

输入: Bug描述 | 可选: 错误日志、截图
输出: 修复代码(Diff) | 变更发布单 | Bug案例记录

---

2. 六步修复 SOP / Fix SOP

流程总览

Step 1: 定位与复现
  ├─ 1.1 Bug三要素提取
  ├─ 1.2 涉及文件定位
  ├─ 1.3 🔥 代码冲突检测 [必做]
  ├─ 1.4 🔥 调试决策树选择 [UI交互类必用]
  └─ 1.5 🔥 根因假设与验证 [必做]
       │
Step 2: 五维影响分析
  │
Step 3: 精准修复 + 风险评估
  ├─ 3.1 设计候选方案(2-3个)
  ├─ 3.2 🔥 多方案对比评估 [必做]
  └─ 3.3 实施最优方案
       │
Step 4: 生成变更发布单
Step 4.5: 自动回归验证
Step 5: 🔥 案例归档 [必做]
Step 6: 🔥 复盘优化 [定期]

---

Step 1: 定位与复现

Step 1.1: Bug三要素提取

Bug定位三要素:
  什么功能: [模块名/页面名/接口名]
  期望行为: [用户期望看到什么]
  实际行为: [实际发生了什么]

Bug类别与策略映射:

Bug类别	典型表现	推荐策略
UI交互异常	点击无反应、按钮不可用	debug-decision-tree.yaml 完整版
数据显示问题	数据不显示、字段缺失	debug-decision-tree.yaml 场景B
表单提交失败	提交无反应、校验失败	debug-decision-tree.yaml 场景C
其他(逻辑/接口/数据)	计算错误、404等	传统排查流程

Step 1.2: 涉及文件定位

定位涉及的代码文件（后端 Controller/Service/Mapper + 前端 Vue/API）

🔥 Step 1.3: 代码冲突检测 [必做]

触发条件: 每次修改前必须执行

执行方法:

grep -n "^\s*(async\s+)?(\w+)\s*\(" target-file.vue | sort

6大检测规则（详见 config/code-conflict-rules.yaml）:

规则	目标	级别	说明
DUPLICATE_METHOD	同名方法	🔴高	JS后定义覆盖先定义
DUPLICATE_VARIABLE	同名变量	🟡中	Vue优先级覆盖
AMBIGUOUS_CALL	歧义调用	🔴高	v-for参数传递错误
LIFECYCLE_HOOK	重复钩子	🟡中	后者覆盖前者
EVENT_MODIFIER	修饰符误用	🟡中	.native/.stop误用
CSS_SPECIFICITY	CSS冲突	🟢低	样式被意外覆盖

处理规则:

• ✅ 无冲突 → 继续
• ⚠️ 低风险 → 记录并继续
• 🟡 中风险 → 评估相关性后决定
• 🔴 高风险 → ⛔ 必须先解决！

🔥 Step 1.4: 调试决策树选择

UI交互类Bug → 加载 config/debug-decision-tree.yaml，按6层Node顺序执行：

Node 1: 控制台错误检查 → Node 2: 元素可访问性 → Node 3: 事件触发验证 
→ Node 4: 方法调用验证⭐ → Node 5: 数据变化 → Node 6: 视图更新

特殊场景快速入口: 页面空白(场景A) | 数据不显示(场景B) | 表单提交失败(场景C)

非UI交互类Bug → 传统排查：错误日志→断点调试→数据流追踪

🔥 Step 1.5: 根因假设与验证 [核心]

原则: ❌ 禁止未经验证就实施修复

流程:

1. 提出Top 3假设 + 计算初始置信度
2. 仅对置信度≥40%的假设设计最小化测试验证
3. 基于证据调整置信度：符合→提升至80%+, 不符合→降至10%
4. 验证通过→进入Step 2；全部否定→回到Step 1.1

置信度速算公式:

基础分30 + 证据加分(最多+35) - 扣分(最多-50)
评级: ≥80%强确信 | 60-79%较确信 | 40-59%存疑 | <40%弱假设❌

📖 详细评分规则和验证示例 → 见 config/hypothesis-validation.md

---

Step 2: 五维影响分析

动代码前必须构建"影响范围声明"：

维度	检查内容	方法
纵向	后端修改影响哪些前端文件	搜索api/目录URL
横向	状态映射是否影响其他模块	全局搜索statusMap
深度	是否需同步审批日志	检查@Transactional
约束	是否涉及若依框架约定	检查@PathVariable等
推断	状态来源是查表还是推断	检查if/switch

工具辅助: pdd deps impact <file> 可自动生成

---

Step 3: 精准修复 + 风险评估

Step 3.1: 设计候选方案

基于根因设计2-3个方案（如：表面修复/最佳实践/根因修复）

🔥 Step 3.2: 多方案对比评估 [必做]

使用 config/fix-risk-matrix.yaml 进行5维量化评估：

维度	权重	说明
复杂度风险	20%	代码复杂度和维护成本
兼容性风险	25%	浏览器/Vue/第三方库兼容性
副作用风险	25%	状态污染/DOM泄漏/内存泄漏
可回滚性	15%	失败时恢复难度
测试覆盖度	15%	测试保障充分性

决策标准: ≥8.0强烈推荐 | 7.0-7.9推荐 | 6.0-6.9有条件 | <6.0不建议

Step 3.3: 实施最优方案

严格遵循:

1. 按Step 2文件清单修改，不扩大范围
2. 使用Diff格式输出，不重写整个文件
3. 修改顺序: Entity→Mapper→Service→Controller→前端API→前端页面
4. 执行bug-patterns.yaml自检
5. 若依项目额外检查框架约定

---

Step 4: 生成变更发布单

按模板生成完整变更发布单（含部署指引、回滚方案、测试用例）

Step 4.5: 自动回归验证

建议自动触发回归验证

🔥 Step 5: 案例归档 [必做]

每次修复完成后必须执行

使用 templates/case-template.md 归档以下内容：

• 基本信息(case_id, title, severity)
• 问题定义(symptoms, reproduction_steps)
• 根因分析(root_cause, code_evidence)
• 解决方案(final_solution, code_changes Diff)
• 失败方案记录(failed_attempts[] - 重要！)
• 统计数据(attempts, time_spent)
• 经验教训(correct/wrong practices)

存储位置: docs/bug-cases/ 目录

🔥 Step 6: 复盘优化 [定期]

每周或每5个Bug后执行一次复盘：

• 统计关键指标(准确率/尝试次数/耗时)
• 识别Top 3高频根因和低效模式
• 更新调试决策树和检测规则

---

3. Guardrails（必须遵守）

• 修改前必须输出影响范围声明并等待确认
• 禁止在Bug修复中添加新功能(scope creep)
• 每次修复必须生成变更发布单
• 修改涉及3+文件时提醒用户先测试环境验证
• 修复完成后必须对照bug-patterns.yaml自检
• 若依框架问题必须咨询expert-ruoyi
• [🆕] 必须执行代码冲突检测(Step 1.3)
• [🆕] 必须使用调试决策树(UI交互类Bug)
• [🆕] 每个根因假设必须验证(置信度<40%禁止pursue)
• [🆕] 多方案时必须量化风险评估(Step 3.2)
• [🆕] 修复完成后必须归档案例(Step 5)

---

4. Iron Law / 十大铁律

1. 影响声明先行 - 修改前必须输出影响范围声明并获得确认
2. 冲突检测必做 - 动代码前必须检测，高风险必须先解决
3. 假设必须验证 - 禁止基于未验证假设修复（尤其<40%弱假设）
4. 决策树引导 - UI交互Bug按Node顺序排查，不可跳跃
5. 修复不扩张 - 范围严格限定于消除Bug本身
6. Diff不重写 - 代码变更必须Diff格式
7. 发布单必出 - 每次修复必须生成变更发布单
8. 模式库自检 - 修复后必须对照bug-patterns.yaml
9. 🆕风险评估必做 - 多方案时必须量化评估选最优
10. 🆕案例必归档 - 每次修复必须记录到案例库

典型违规: ❌跳过冲突检测 | ❌基于25%置信度修复 | ❌不评估风险选复杂方案 | ❌不归档案例
合规示例: ✅检测到同名方法先解决 | ✅验证后选择65%置信度假设 | ✅选8.2分根因修复方案 | ✅归档完整案例

---

5. Rationalization Table

#	你的想法	应该怎么做	v2.1检查项
1	"这个Bug很简单直接改"	即使一行也必须五维分析	是否执行了冲突检测？
2	"像Vue响应式问题"	设计最小化测试验证	置信度≥40%吗？
3	"参考实现应该能用"	对比关键差异点	检查同名方法和数据结构？
4	"这方案应该没问题"	量化风险评估	总分≥7.0？无高风险项？
5	"修复完了收工"	归档案例沉淀经验	填写了case-template必填项？

---

6. Red Flags / 红旗警告

Layer 0: 前置检查

• PRE-BF-001: 未执行冲突检测就分析 → 🔴CRITICAL → 立即执行Step 1.3
• PRE-BF-002: UI交互Bug未加载决策树 → 🔴CRITICAL → 加载debug-decision-tree.yaml
• PRE-BF-003: 假设无置信度评分 → 🟡WARN → 补充评分

Layer 1: 输入检查

• INPUT-BF-001: Bug描述过于模糊 → 🔴CRITICAL
• INPUT-BF-002: 用户描述的是新需求非Bug → 🟡WARN
• INPUT-BF-003: 涉及文件无法找到 → 🔴CRITICAL

Layer 2: 执行检查

• EXEC-BF-001: 无影响声明就改代码 → 🔴CRITICAL
• EXEC-BF-002: 修改了声明外的文件 → 🔴CRITICAL
• EXEC-BF-003: Bug修复中添加新功能 → 🔴CRITICAL
• EXEC-BF-004: 修改5+文件 → 🟡WARN
• [🆕] EXEC-BF-005: 基于<40%弱假设修复 → 🔴CRITICAL
• [🆕] EXEC-BF-006: 跳过决策树Node直接复杂假设 → 🟡WARN
• [🆕] EXEC-BF-007: 未评估风险就选复杂方案 → 🟡WARN

Layer 3: 输出检查

• OUTPUT-BF-001: 无变更发布单 → 🔴CRITICAL
• OUTPUT-BF-002: 发布单缺部署/验证路径 → 🟡WARN
• OUTPUT-BF-003: 未通过bug-patterns自检 → 🔴CRITICAL
• OUTPUT-BF-004: 整体文件输出非Diff → 🟡WARN
• [🆕] OUTPUT-BF-005: 未归档案例 → 🟡WARN
• [🆕] OUTPUT-BF-006: 案例缺失败方案教训 → 🟡WARN

---

7. 版本历史

版本	日期	变更
2.1.0	2026-05-06	质量优化: 压缩29%(523→370行)，详情移至config按需加载
2.0.0	2026-05-06	重大升级: Phase1+Phase2全量改进（验证/决策树/冲突检测/风险评估/案例库）
1.1	2026-04-28	新增Step 4.5回归验证+依赖链引擎集成
1.0	2026-04-28	初始版本: 四步SOP+五维分析+变更发布单

---

技能文档结束

expert-bug-fixer v2.1 - 精简高效的智能化Bug修复专家 详细示例见config/目录，持续迭代优化中