基于 review-pr Skill 的 PR 分支审查方法论:从 git diff 到缺陷分级报告

原创2026-10-09 21:47:001,662 阅读
文章标签:网络安全应用安全AI 技能AI 插件代码评审静态分析SAST测试代码质量供应链安全漏洞扫描开发工具

基于 review-pr Skill 的 PR 分支审查方法论:从 git diff 到缺陷分级报告

导读

本文围绕 Trail of Bits skills 仓库中 code-improver 插件所依赖的 review-pr 技能(Skill)展开,完整拆解它如何以“只审查分支变更面、而非整个仓库”为原则完成一次 Pull Request 审查:从建立 base 分支与 HEAD 之间的 diff、逐 hunk 校验正确性、核对测试覆盖、检查文档是否过期,到按严重级别逐条报告缺陷。与此同时,本文结合该技能在 pr-improver 入口技能与 improve.js 动态工作流中的实际调用方式,说明这一审查方法如何被循环复用、如何被机器校验,帮助读者在 Claude Code 等 Agent 环境中亲手落地这套可重复、可验证的 PR 审查流程。

一、认识 review-pr Skill:它是谁,用在哪儿

review-pr 是 code-improver 插件 默认配置的 PR 审查技能,其定义位于 plugins/code-improver/tests/fixtures/pr-review-toolkit/skills/review-pr/SKILL.md。它的定位是:把当前分支相对 base 分支的改动当作一次 Pull Request 来审查——审查新增与修改代码的正确性、这些代码的测试覆盖情况,以及文档是否被改动改得失真。

它在仓库中的使用场景有两层:

  1. 独立一次性审查:用户要求“review this branch / this diff / this PR”时,直接调用该技能即可完成单次审查;
  2. 自动化“审查-修复”循环的评审者(reviewer):pr-improver 技能在启动 improve.js 动态工作流时,默认把 pr-review-toolkit:review-pr 作为 reviewer 注入循环,让它在每一轮迭代中对分支改动反复审查,直到零 critical/major 缺陷(见 pr-improver 技能 的调用参数示例)。

从 pr-mode 评估用例 可以看到该技能被验证的方式:一个带 main 与 feature 分支的仓库,feature 分支上预埋了一个带测试缺口的中位数 bug、一条被改动搞过期的 README 声明,以及一个分支从未触碰过的目录中的“诱饵”bug——最终判分要求循环收敛、bug 被修复且补上测试、README 恢复准确、未触碰的文件保持字节级一致。这正是 review-pr“只审查变更面、不越界报告”的方法论被机器验证的具体体现。

二、Skill 元信息:触发条件与工具边界

review-pr 的 YAML frontmatter 定义了该技能的元信息,直接决定了它何时被触发、可以使用哪些工具:

字段 值 含义
name review-pr 技能的唯一标识,被引用时使用命名空间形式 pr-review-toolkit:review-pr
description Reviews the current branch's changes against its base branch as a pull request: correctness of new and modified code, test coverage for it, and documentation accuracy. Use when asked to review a branch, a diff, or a pull request. 触发描述:当用户要求审查分支、diff 或 PR 时激活
allowed-tools Read Grep Glob Bash 审查者可用的工具集合:读取文件、正则搜索、glob 定位、执行 shell 命令

值得注意的是 allowed-tools 中没有 Write/Edit——审查者被设计为只读角色,这保证审查行为本身不会污染工作区。在 improve.js 的循环中,这一点被进一步强化:每一轮都明确要求 reviewer “perform no writes at all”,审查与修复严格分离,修复由独立的 fixer 完成。

三、核心方法论:只审查变更面

Skill 正文开宗明义一句话定下铁律:

Review the branch's change surface, not the whole repository.

这是整个方法论的总纲。分支审查的边界是 diff,不是整个代码库;缺陷是否值得报告,取决于该缺陷是否位于分支实际改动过的文件/代码块中。这条边界在自动化循环里被升级成了机器强制约束:pr-improver 从 git diff --name-only <base>...HEAD 提取变更文件,再映射为目录级 glob 作为 scope,improve.js 的 scope guard 在每一轮修复后都会用 git diff 校验是否存在越界修改,越界即 halted。

四、五步审查流程详解

步骤 1:建立 diff——确定“变更面”的精确边界

第一步是确定要审什么:

git diff <base>...HEAD
  • <base> 是调用方指定的基准分支名,未指定时回退到 main;
  • 使用三点语法 ... 比较的是 base 与 HEAD 之间的共同祖先到 HEAD 的差异,即“分支真正带来的改动”,而非 base 当前状态与 HEAD 的差异;
  • 当工作区还带有属于该分支的未提交改动时,需要补充执行 git diff <base>(两点语法),把暂存区/工作区的未提交变更也纳入审查范围。

对应到 pr-improver 技能 中的落地实现:先 git rev-parse --show-toplevel 确认仓库根,再取参数或默认分支(git symbolic-ref refs/remotes/origin/HEAD 的短名,兜底 main),随后用 git diff --name-only <base>...HEAD 列出变更文件,并做一条防御性检查——当前分支就是 base 时拒绝运行(没有可审的 diff)。

从源码结构看,improve.js 的基线阶段 进一步把“diff 边界”固化为可审计的基线:记录 HEAD sha、用 git ls-files --others --exclude-standard 枚举未跟踪文件并逐个 hash-object 计算内容哈希——因为 git diff 永远看不见未跟踪文件的变化,内容哈希成为这些文件被越界改写时的唯一证据。

步骤 2:逐个 hunk 检查正确性

对每个被改动的代码块(hunk),从三个角度审查正确性:

  1. 边界输入上的错误结果(wrong results on edge inputs):空集合、长度奇偶、溢出、空指针、索引越界等边界情形是否处理正确;
  2. 未处理的错误路径(unhandled error paths):文件不存在、网络失败、解析失败、权限不足等错误分支是否有对应处理;
  3. 与函数名或调用方语义相矛盾的行为(behavior that contradicts the function's name or callers):实现是否辜负了函数名承诺的语义,或是否破坏了某个既有调用方对它的假设。

这三个角度共同构成“正确性审查”的完整检查面。在 pr-mode 评估用例 中,预埋的“偶数长度中位数”bug 正是“边界输入上结果错误”的典型:奇数长度返回中间元素、偶数长度应返回中间两元素的平均值,而预埋实现漏掉了后者。

步骤 3:核对变更行为的测试覆盖

审查者必须检查被改动的行为是否有测试覆盖:

New logic without a test exercising its edge cases is a finding.

即:新增逻辑若没有针对其边界情况的测试,本身就是一个 finding(缺陷项),而不是“建议”。这一条在循环机制里被强化为硬性要求——improve.js 的 FIX_SCHEMA 要求每个修复(verdict 为 fixed)都附带 pin:一个针对修复前代码必然失败、修复后通过的测试或断言(纯文档改动可标注 none: prose-only change)。也就是说,行为变更必须有“钉住”它的测试,修复是否成立由下一轮审查用读代码的方式验证(verified_fixed),而非由修复者自证。

步骤 4:检查 diff 是否让文档失真

Check documentation the diff made stale: statements in README or docs that were true on the base branch and are false after the change.

文档准确性与代码正确性同等重要:审查 README 或 docs 中那些在 base 分支上为真、改动后为假的陈述。典型场景是接口签名变了但文档还写着旧签名、默认值变了但文档还写着旧默认值、行为语义变了但文档仍描述旧行为。这类“文档过期”同样构成 finding。pr-mode 用例中预埋的“README 声称 mean 是唯一统计量”就是一条典型的被改动搞过期的文档陈述。

步骤 5:分级报告所有缺陷,且只报告分支触碰过的文件

最后一条是报告契约:

  • 报告发现的每一个缺陷,并为每个缺陷标注严重级别(severity);
  • 包括 minor 和 informational 级别的低危发现——不允许审查者自行预筛或扣留低危项;
  • 不报告分支未触碰的文件中的缺陷——它们不在本次 Pull Request 范围内。

这条“低危也要报、越界不能报”的双向约束,恰好对应 improve.js 的 SEVERITIES 与 BLOCKING 定义:严重级别被归一化为 critical | major | minor | info 四级,其中 critical 和 major 构成阻塞级(blocking);报告阶段要求“不预筛”,而是否阻塞由循环在账本(ledger)层面统一裁决一次,而不是在每个 reviewer 那里各裁一次。

五、从单次审查到循环审查:review-pr 在自动化循环中的角色

review-pr 的单次方法论是闭环的(建立 diff → 审 hunk → 核测试 → 核文档 → 分级报告),但当它被嵌入 pr-improver 驱动的“审查-修复”循环时,还需要遵守额外的契约才能与账本、scope guard、振荡检测协同工作。这些契约定义在 improve.js 的 REVIEW_SCHEMA 中:

  • 每条 finding 必须携带 id(file:line:class)、file、line、class、severity、title、evidence 七个字段,其中 class 是短横线连接的缺陷类别(如 dangling-reference);
  • 已知 finding 再次出现时必须复用账本中的精确 id,即使行号已发生偏移——这是账本能跨轮匹配、避免重复派发的关键;
  • 被 rejected 的 finding 除非带来 new_evidence: true 且确实提供拒绝理由未覆盖的新证据,否则不得重新上报——一轮裁决不被反复翻案;
  • 修复必须通过读代码验证:verified_fixed 列出确认成立的修复 id,没成立的修复按原 id 重新上报(等价于“修复未生效,重新开启”);
  • 如果该技能内部编排了专家子代理(SKILL_REVIEW_SCHEMA 的 dispatch 模式),由于工作流子代理无法再派生子代理,它不能直接启动专家,而应把派发请求交回循环,由循环代为执行(最多 3 波、每波 8 个专家)后再继续审查。

六、一次真实运行的完整观感:pr-improver 如何驱动 review-pr

把上文串起来,一次典型的 PR 分支审查-修复运行如下:

  1. 用户发出类似“review this branch”或“clean up this branch until review passes”的指令;
  2. pr-improver 解析 base 分支与变更文件,推导出目录级 scope(<变更目录>/**),定位 improve.js 工作流脚本,以 reviewer: {"kind": "skill", "name": "pr-review-toolkit:review-pr"} 启动;
  3. 工作流逐轮执行:审查(调用 review-pr)→ 账本裁决 → 修复(fixer 只处理阻塞级 finding,附测试 pin)→ scope 检查 → 再审查;
  4. 循环只有在“最后一次动作是零阻塞级 finding 的审查”时才以 converged: true 结束;修复预算耗尽则显式输出 capped, NOT converged 并列出剩余阻塞项;连续三轮计数不降、同一 finding 连续三轮出现、或同一 finding 被“修复”两次,则触发振荡升级(escalation),要求设计决策而非继续烧轮次(见 README 的 Guarantees 一节);
  5. 所有产物落在 .code-improver/<目标名>/ 目录:ledger.json(跨轮记忆)、fixes-round-N.diff(每轮累计 diff)、status.md、metrics.json 等(README 的 Artifacts 表),且循环从不 commit,所有改动停留在工作区等待人工复核。

七、适用前提与边界

把 review-pr 投入实战前,需要明确它的适用前提:

  • 必须位于 git 仓库内:diff 建立与 scope 校验都依赖可 diff 的基线;improve.js 在目标不在仓库时会以显式身份(code-improver-baseline)执行 git init 并提交基线快照,且会大声告知用户“创建了一个 git 仓库”;
  • 运行环境为支持动态工作流的 Claude Code:循环本身是工作流脚本,其他客户端(如 Codex)只能加载技能、无法运行循环(README 的 Requirements);
  • 审查者必须已安装:review-pr 技能由 pr-review-toolkit 插件提供;若该插件缺失,循环以 halted: "reviewer-unavailable" 大声退出并给出安装指引,绝不以内联模仿的审查顶替——因为那样会失去账本、scope guard 与升级保障的全部保证。

对于“仅需一次性审查”的场景,正确的做法是直接调用 review-pr 技能本身,而非启动循环——循环的价值在于迭代收敛,单次审查用不到它的全部机制。

总结

review-pr 用短短五步定义了一套可执行、可机器校验、可跨轮复用的 PR 分支审查方法论:以 diff 为唯一边界,逐 hunk 查正确性,用测试覆盖卡住新逻辑,用文档失真检查守住一致性,最终按 critical/major/minor/info 全量分级上报、严格限定在分支触碰过的文件内。它在 code-improver 插件中既可作为独立审查技能直接调用,也可作为 pr-improver 循环的默认 reviewer 反复执行,配合跨轮 findings 账本、机械 scope guard 与振荡升级机制,构成了一个“审查-修复直到干净为止”的自动化闭环。理解这份 Skill,等于同时掌握了单次 PR 审查的全部检查维度与自动化循环对审查者的全部接口契约。

登录后查看全文
skills