bug-review

Bug Review v2

多轮 PR 审查 Agent，包含 5 轮并行审查、多数投票、独立 Opus 验证和解决率学习。在 PR 中发布行内评论，并可选择生成自动修复提交。跟踪问题在合并时是否得到解决，并利用这一信号改进后续审查。

适用场景

• 用户要求审查拉取请求中的 Bug 或正确性问题
• 用户运行 /bug-review <PR-number-or-URL>
• 用户在合并后运行 /bug-review:resolve <PR>，对解决情况进行分类
• 用户运行 /bug-review:report，查看解决率统计
• 用户要求进行侧重逻辑错误、边缘情况或安全性的代码审查
• 用户想要在差异或一组更改中查找 Bug

设置

首次运行时，验证以下事项：

• 已安装并完成身份验证的 gh CLI（gh auth status）
• 当前目录是带有 GitHub 远程地址的 git 仓库
• 已安装 jq（用于处理 JSON）
• 已安装 bc（用于计算解决率；大多数系统已预装）

读取 config.json 获取配置（审查轮数、投票阈值、模型、类别权重）。

工作流概览

/bug-review <PR>
  |
  v
Fetch PR context + gather-context.sh
  |
  v
5 parallel passes (shuffled diffs, Sonnet) --> Aggregate & vote (3/5 majority)
  |
  v
Independent Opus validator --> Dedup --> Present findings --> Post + store
  |
  (later, after merge)
  v
/bug-review:resolve <PR> --> Classify resolutions --> Update category weights

命令：/bug-review

步骤 1：解析输入并获取上下文

1. 解析 PR 标识符（编号、URL 或分支名）
2. 检查缓存：查找 ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/ — 如果存在对应相同 head commit 的缓存，则询问是否从上一个检查点继续
3. 运行 scripts/fetch-pr.sh <pr-identifier>，以 JSON 格式获取 PR 差异和元数据
4. 将差异保存到临时文件，以便打乱顺序
5. 运行 scripts/gather-context.sh <changed-files-json>，获取优先级上下文（调用方、类型、测试、仓库规则）
6. 如果仓库根目录下存在 .bug-review.md，则读取该文件
7. 保存检查点：将上下文写入 ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/context.json

步骤 2：运行 5 轮并行审查

为每轮审查（1-5）准备一份打乱顺序的差异：

scripts/shuffle-diff.sh <pass-number> < pr.diff > pass-<N>.diff

并行启动 5 个 Agent 子进程。各轮的确切提示词请参阅 review-passes.md。

• 第 1 轮：逻辑与边缘情况（种子 1）
• 第 2 轮：安全与数据完整性（种子 2）
• 第 3 轮：错误处理与 API 契约（种子 3）
• 第 4 轮：并发与状态（种子 4）
• 第 5 轮：数据流与契约（种子 5）

使用 config.json 中的 agent_model 作为 model（默认值："sonnet"）。

每个 Agent 返回一个 JSON 数组，其中包含发现的问题。

保存检查点：将所有轮次的结果写入 ${CLAUDE_PLUGIN_DATA}/bug-review/cache/pr-{N}/pass-results.json

步骤 3：汇总并投票

1. 收集全部 5 轮审查的发现
2. 按相似度对发现进行分组：同一文件 + 行号相差不超过 5 行 + 类别相同或相关
3. 统计每组的票数
4. 仅保留获得 3 票或以上的发现（5 轮中的多数票；可通过 vote_threshold 配置）
5. 应用 config.json 中的类别权重：final_score = votes × severity_weight × category_weight
6. 权重小于 0.1 的类别将被完全抑制
7. 按 final_score 降序排序

如果只有 1-2 轮发现了 Bug，而其他轮次均未发现，则仍展示这些发现，但注明它们未达成共识。

保存检查点：将投票后的发现写入缓存。

步骤 4：独立验证（Opus）

使用 config.json 中的 validator_model（默认值："opus"）启动一个独立的 Agent。

该 Agent 尚未查看过审查轮次的结果。它只会收到投票后的发现和原始代码。提示词请参阅 review-passes.md 中的 Validator 部分。

对于每项发现，验证器会输出：{id, verdict: "KEEP"|"DISCARD", confidence, reasoning}

移除 verdict 为 DISCARD 的发现。每项发现的分数乘以验证器给出的置信度。

计算每项发现的最终 confidence 字段：

confidence = (votes / total_passes) × validator_confidence

置信度低于 0.5 的发现会显示“低置信度”警告。

保存检查点：将验证后的发现写入缓存。

步骤 5：与之前的评审去重

运行 scripts/dedup.sh <pr-number>，获取现有的 [bug-review] 评论。 按位置接近程度（文件 + 行号在 +/-10 范围内）和类别匹配，而非文本相似度。

步骤 6：向用户展示发现

显示一张表格：

#	严重性	置信度	文件	行号	标题	票数

对每项发现，显示完整描述、触发场景、建议修复方案和验证器的判断理由。

使用 AskUserQuestion（并启用 multiSelect）询问用户：

• 选择哪些发现作为 PR 评论发布（默认：全部）
• 选择哪些发现自动修复（默认：无）

如果投票和验证后没有任何发现："经过 5 轮评审，未发现 Bug。代码改动看起来没有问题。"

步骤 7a：发布 PR 评审

将获准发布的发现写入临时 JSON 文件，然后运行：

scripts/post-review.sh <pr-number> <findings-json-file>

然后保存发现，以便跟踪其解决状态：

scripts/store-findings.sh <pr-number> <findings-json-file> <head-commit-sha>

步骤 7b：自动修复（用户选定的发现）

对每项选定自动修复的发现：

1. 读取文件并理解周边上下文
2. 生成最小修复（尽可能小的改动）
3. 使用 Edit 工具应用修复
4. 范围检查：运行 git diff --stat，确认只有发现所在的文件被修改，且差异少于 20 行。如果超出，撤销改动并发出警告。
5. 如果有现成的测试，则运行测试（如 npm test、go test ./...、pytest 等）
6. 如果测试通过：使用 fix: {title} [bug-review] 提交
7. 如果测试失败：撤销修复（git checkout -- <file>），并向用户报告
8. 所有修复完成后：推送到 PR 分支

安全要求：每项修复单独提交，修复之间运行测试，绝不强制推送，并对每项修复进行范围验证。

命令：/bug-review:resolve

PR 合并后运行，以判断发现的问题是否已解决。

1. 运行 scripts/classify-resolutions.sh <pr-number>
   • 从 ${CLAUDE_PLUGIN_DATA}/bug-review/findings/pr-{N}.json 加载已存储的发现
   • 检查 PR 是否已合并
   • 对每项发现：比较评审提交与合并提交之间的代码差异
   • 将每项发现归类为 RESOLVED、UNRESOLVED 或 INCONCLUSIVE
   • 使用解决状态数据更新已存储的发现文件
2. 向用户显示解决状态摘要
3. 如果积累的数据足够（10 项或以上发现、3 个或以上 PR）：运行 scripts/update-weights.sh，以调整类别权重

命令：/bug-review:report

显示所有受跟踪 PR 的解决率统计信息。

运行 scripts/resolution-report.sh，该脚本会输出：

• 总体解决率
• 按严重性划分的解决率
• 按类别划分的解决率（按最差到最好排序，以突出噪声较大的类别）
• 已抑制的类别（权重 < 0.1）

仓库专属规则（.bug-review.md）

团队可以在仓库根目录创建 .bug-review.md：

## Focus Areas
- Pay special attention to authentication flows
- Check all database queries for SQL injection

## Ignore
- Don't flag issues in generated files (*.generated.ts)
- Ignore style-only concerns

## Invariants
- All API endpoints must check req.user before accessing user data
- Database migrations must be reversible

## Severity Overrides
- Treat any auth bypass as CRITICAL regardless of category default

使用方法

阅读 workflow.md，了解包含错误处理的详细分步说明。 阅读 review-passes.md，了解全部 5 轮评审提示词和验证器。 阅读 categories.md，了解 Bug 类别和学习到的权重。

相关技能

• 可考虑创建一个用于调查本次评审发现的 Bug 的 Runbook 技能
• 可考虑创建一个在 PR 开启时自动运行本次评审的 CI/CD 技能