| 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: 根因假设与验证 [核心]
原则: ❌ 禁止未经验证就实施修复
流程:
- 提出Top 3假设 + 计算初始置信度
- 仅对置信度≥40%的假设设计最小化测试验证
- 基于证据调整置信度：符合→提升至80%+, 不符合→降至10%
- 验证通过→进入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: 实施最优方案
严格遵循:
- 按Step 2文件清单修改，不扩大范围
- 使用Diff格式输出，不重写整个文件
- 修改顺序: Entity→Mapper→Service→Controller→前端API→前端页面
- 执行bug-patterns.yaml自检
- 若依项目额外检查框架约定
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（必须遵守）
4. Iron Law / 十大铁律
- 影响声明先行 - 修改前必须输出影响范围声明并获得确认
- 冲突检测必做 - 动代码前必须检测，高风险必须先解决
- 假设必须验证 - 禁止基于未验证假设修复（尤其<40%弱假设）
- 决策树引导 - UI交互Bug按Node顺序排查，不可跳跃
- 修复不扩张 - 范围严格限定于消除Bug本身
- Diff不重写 - 代码变更必须Diff格式
- 发布单必出 - 每次修复必须生成变更发布单
- 模式库自检 - 修复后必须对照bug-patterns.yaml
- 🆕风险评估必做 - 多方案时必须量化评估选最优
- 🆕案例必归档 - 每次修复必须记录到案例库
典型违规: ❌跳过冲突检测 | ❌基于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/目录，持续迭代优化中
