| name | bug-organize |
| description | 当需要整理错题集时触发。触发条件:用户要求整理错题集、清理失效条目、归类重复问题、按重要性重排、用户要求查看整理建议、**代码重构完成后自动执行路径迁移**。 |
Bug Organize Skill
整理 bug-book 数据库中的错题记录,保持错题集的健康度和可用性。
Python 脚本执行规则
【强制要求】禁止 cd 到插件目录!必须在当前项目目录执行 Python 代码。
- ✅ 正确:保持在项目目录(如
/home/user/my-project)执行
- ❌ 错误:cd 到插件目录(如
~/.claude/plugins/bug-book/scripts)
如果需要使用插件脚本,使用绝对路径导入:
import sys
sys.path.insert(0, "{CLAUDE_PLUGIN_DIR}/bug-book")
from scripts.bug_ops import list_bugs, get_bug_detail, mark_invalid, delete_bug, list_unverified_old, analyze_impact_patterns
常量定义
以下是 bug-book 中使用的关键阈值常量:
THRESHOLD_HIGH_SCORE = 30
THRESHOLD_AUTO_VERIFY = 30
THRESHOLD_OLD_BUGS_DAYS = 30
何时需要整理
- 用户明确要求整理错题集
- 手动整理周期到了(建议每周一次)
- 用户要求"清理失效条目"
- 用户要求"归类相似问题"
- 代码重构完成后(文件重命名、目录移动后必须立即执行路径迁移)
整理流程
1. 加载数据
使用 scripts/bug_ops.py 加载所有记录:
from scripts.bug_ops import list_bugs, get_bug_detail, mark_invalid, delete_bug, list_unverified_old
bugs = list_bugs(status="active", order_by="score", limit=100)
unverified_old = list_unverified_old(days=30)
2. 检查长期未验证记录
对超过 30 天(THRESHOLD_OLD_BUGS_DAYS)未验证的活跃记录,提示用户:
## 未验证记录提醒
Bug #N 已记录 45 天仍未验证:
- 标题:session 存储未设置持久化
- 创建时间:YYYY-MM-DD
建议:确认是否已修复?如已修复请验证,如功能已废弃请标记失效。
3. 检查路径有效性
对每条活跃 bug,检查 recalls 中的路径是否仍然存在于代码库中:
from scripts.bug_ops import check_path_valid
def check_bug_paths(bug_id):
"""检查 bug 的所有路径是否有效"""
from scripts.bug_ops import get_conn_ctx, get_bug_detail
with get_conn_ctx() as conn:
detail = get_bug_detail(bug_id)
if not detail:
return []
invalid_paths = []
for path in detail.get("paths", []) + detail.get("recalls", []):
if not check_path_valid(path):
invalid_paths.append(path)
for impact in detail.get("impacts", []):
impacted_path = impact.get("impacted_path")
if impacted_path and not check_path_valid(impacted_path):
invalid_paths.append(impacted_path)
return invalid_paths
路径失效的处理:
- 标记该 bug 为"待确认失效"
- 向用户展示:
Bug #N 的相关路径 [path] 已不存在,是否标记为失效?
4. 归类相似问题
检查是否存在根因相同或现象相似的 bug:
from scripts.bug_ops import list_bugs, get_bug_detail
bugs = list_bugs(status="active", order_by="score", limit=100)
bugs_by_tag = {}
for bug in bugs:
detail = get_bug_detail(bug["id"])
if detail and "tags" in detail:
for tag in detail["tags"]:
bugs_by_tag.setdefault(tag, []).append(bug)
合并建议格式:
## 相似问题归类建议
Bug #3 和 Bug #7 可能相关:
- #3: "登录页样式错位"
- #7: "样式问题导致布局崩溃"
根因相似度:高(都涉及 CSS 样式覆盖)
建议:合并为一条记录,保留更高分的作为主记录
5. 按重要性排序
分数计算公式(参考 bug_ops.py 中的 DEFAULT_WEIGHTS):
DEFAULT_WEIGHTS = {
"importance": 2.0,
"complexity": 1.5,
"scope": 1.0,
"difficulty": 1.0,
"occurrences": 1.0,
"emotion": 1.5,
"prevention": 2.0,
}
总分 = importance×2.0 + complexity×1.5 + scope×1.0 + difficulty×1.0
+ occurrences×1.0 + emotion×1.5 + prevention×2.0
展示排序结果,标记分数异常高/低的条目供用户参考。
6. 分析影响模式(新功能)
调用 analyze_impact_patterns() 分析高频回归模块:
from scripts.bug_ops import analyze_impact_patterns
patterns = analyze_impact_patterns(limit=10)
返回示例:
[
{
"path": "src/cart/",
"impact_count": 5,
"avg_severity": 7.2,
"max_severity": 9,
},
{
"path": "src/auth/",
"impact_count": 3,
"avg_severity": 8.0,
"max_severity": 9,
}
]
在整理报告中添加影响分析章节:
### 📊 影响分析报告
#### 高风险模块 Top 5
1. **src/cart/** - 被影响 5 次,平均严重度 7.2
- Bug #42 → cart/add_to_cart.ts (回归,严重度 8)
- Bug #38 → cart/checkout.ts (副作用,严重度 7)
- ...
2. **src/auth/** - 被影响 3 次,平均严重度 8.0
- Bug #45 → auth/middleware.ts (回归,严重度 9)
- ...
#### 💡 洞察与建议
- **auth 和 cart 模块耦合度高**,修改其中一个容易影响另一个
- 建议在 auth/cart 之间增加接口层,降低直接依赖
- 可以考虑为这两个模块编写集成测试
7. 执行清理操作
根据整理结果,执行以下操作(需用户确认):
- 标记失效:
mark_invalid(bug_id, reason) — 功能/代码已移除
- 合并重复:
delete_bug(id) — 删除冗余记录
- 更新分数:
increment_score(bug_id, dimension, delta) — 累加出现次数等维度
- 验证 bug:
update_bug(bug_id, verified=True, verified_at="CURRENT_TIMESTAMP", verified_by="User")
重要:整理完成后,必须记录整理时间!
from scripts.bug_ops import set_last_organize_time
set_last_organize_time()
print("✅ 整理完成!已更新最后整理时间。")
用户确认后的执行示例:
from scripts.bug_ops import mark_invalid, delete_bug, update_bug, increment_score
mark_invalid(5, reason="路径 src/old/auth.ts 已不存在")
delete_bug(7)
update_bug(8, verified=True, verified_at="CURRENT_TIMESTAMP", verified_by="User")
increment_score(3, "occurrences", 1.0)
print("✅ 整理完成!共执行 4 项操作")
执行后提示:
## 整理完成
已执行以下操作:
- ✅ 标记 Bug #5 为失效
- ✅ 删除 Bug #7(与 #3 合并)
- ✅ 验证 Bug #8
- ✅ 累加 Bug #3 出现次数
- ✅ **记录最后整理时间**
当前状态:
- 总记录数:14(减少 1 条)
- 活跃记录:11
- 已失效:4(增加 1 条)
- 已验证:8(增加 1 条)
8. 生成整理报告
## 错题集整理报告
### 统计
- 总记录数:15
- 活跃记录:12
- 已失效:3
### 未验证记录(超过 30 天)
1. Bug #5 - session 存储未设置持久化 - 创建于 2024-01-15(45 天前)
2. Bug #8 - 按钮点击无响应 - 创建于 2024-01-20(40 天前)
### 路径检查结果
**失效路径:**
- Bug #3: `src/old/auth.ts` 已不存在
- Bug #7: `components/LegacyButton.vue` 已不存在
**有效记录:** 10 条
### 相似问题归类
**可能重复的 bugs:**
- Bug #3 和 Bug #7:都涉及 CSS 样式问题,标签重叠(auth, session)
- #3: "登录页样式错位" - 分数 42.5
- #7: "样式问题导致布局崩溃" - 分数 18.0
- 建议:保留 #3,删除 #7
### 排序 TOP 10
1. #3 - session 存储未设置持久化 - 分数 42.5 ⏳未验证
2. #12 - 数据库连接池泄漏 - 分数 35.0 ✅已验证
3. #1 - 用户权限校验失败 - 分数 28.5 ✅已验证
4. #7 - 按钮样式错位 - 分数 18.0 ✅已验证
5. #8 - 按钮点击无响应 - 分数 15.0 ⏳未验证
...
### 待确认操作
请确认是否执行以下操作:
- [ ] **标记失效**:Bug #3(路径 src/old/auth.ts 已不存在)
- [ ] **标记失效**:Bug #7(路径 components/LegacyButton.vue 已不存在)
- [ ] **合并重复**:Bug #3 和 #7 → 保留 #3,删除 #7
- [ ] **验证**:Bug #5(已 45 天未验证,确认是否已修复?)
- [ ] **验证**:Bug #8(已 40 天未验证,确认是否已修复?)
**回复示例:**
- “全部执行” → 执行所有操作
- “只执行第 1 和第 4 项” → 选择性执行
- “我看一下 #3 和 #7 的详情” → 展开详细信息
- “#5 其实已经修复了” → 只验证 #5,跳过其他
如果用户需要更多信息才能决定:
当用户对某项操作有疑问时,AI 应该主动提供详细信息:
# 用户问:“#3 和 #7 为什么可以合并?”
from scripts.bug_ops import get_bug_detail
detail_3 = get_bug_detail(3)
detail_7 = get_bug_detail(7)
print(f"""
## Bug #3 详情
- 标题:{detail_3['title']}
- 现象:{detail_3['phenomenon']}
- 根因:{detail_3.get('root_cause', 'N/A')}
- 解决方案:{detail_3.get('solution', 'N/A')}
- 标签:{', '.join(detail_3.get('tags', []))}
- 分数:{detail_3['score']}
## Bug #7 详情
- 标题:{detail_7['title']}
- 现象:{detail_7['phenomenon']}
- 根因:{detail_7.get('root_cause', 'N/A')}
- 解决方案:{detail_7.get('solution', 'N/A')}
- 标签:{', '.join(detail_7.get('tags', []))}
- 分数:{detail_7['score']}
## 相似性分析
- 共同标签:auth, session
- 根因相似度:高(都涉及 CSS 样式覆盖)
- 建议:保留分数更高的 #3,删除 #7
""")
用户可能的反馈及处理:
- “我看一下 #3 的详情” → 调用
get_bug_detail(3) 展示完整信息
- “#5 其实已经修复了” → 执行
update_bug(5, verified=True, ...)
- “#3 和 #7 不能合并,它们不一样” → 跳过该项操作
- “全部执行” → 执行所有待确认操作
- “只执行第 1 和第 3 项” → 选择性执行
重构后自动路径迁移(独立触发流程)
触发条件:当 AI 完成代码重构(文件重命名、目录移动)后,必须立即执行此流程。
执行原则:静默执行,无需用户确认
使用示例:
from scripts.bug_ops import migrate_bug_paths_after_refactor
migrated_bugs, impacted_count = migrate_bug_paths_after_refactor(
old_path="src/auth/session.ts",
new_path="src/modules/auth/session.ts"
)
print(f"✅ 已自动更新 {len(migrated_bugs)} 个 Bug:{', '.join([f'#{bid}' for bid in migrated_bugs])}")
if impacted_count > 0:
print(f"✅ 已自动更新 {impacted_count} 条影响关系")
API 说明:
migrate_bug_paths_after_refactor(old_path, new_path) 会自动:
- 查找所有受影响的 Bug(通过 paths 和 recalls 双向匹配)
- 更新 paths(精确匹配替换)
- 更新 recalls(保持通配符结构,如
auth/* → modules/auth/*)
- 更新影响关系中的 impacted_path
- 返回
(更新的 bug_id 列表, 更新的影响关系数量)
注意事项:
- ⚠️ 此流程仅在重构完成后自动执行,不需要用户确认
- ⚠️ AI 需要自己识别本次重构涉及的路径变更
- ⚠️ 如果重构涉及多个文件,对每个文件分别调用此 API
注意事项
- 每次整理最多处理 50 条记录,避免单次操作过多
- 标记失效前必须向用户确认
- 合并记录前必须向用户确认
- 整理后提示用户关键变更