ECC 中的 /review-pr：借助专项 Agent 协作实现多视角、高信心的 PR 审查

导读

/review-pr 是 ECC（The agent harness performance optimization system）提供的一键式命令，用于对拉取请求（Pull Request）执行全面、多视角的代码审查。它的核心思想不是让单个 Agent 通读一遍 diff，而是把不同关注点（测试覆盖、静默失败、类型设计、注释质量、代码简化、通用质量与安全）拆分给各自的专项审查 Agent 并行处理，再汇总去重、按严重程度输出报告。读完本文，你将掌握 /review-pr 的命令语法、六种 --focus 定向模式的取舍、五步执行流程背后的工作原理，以及“置信度 >= 80 才报告”的防噪音过滤体系是如何落在具体 Agent 定义上的。

一、命令速览：一条命令拉起整套审查栈

/review-pr 的完整语法由 commands/review-pr.md 定义：

/review-pr [PR-number-or-URL] [--focus=comments|tests|errors|types|code|simplify]

两条默认规则值得先记住：

• 不指定 PR：审查当前分支对应的 PR；
• 不指定 focus：运行完整的审查堆栈（full review stack），即默认同时启用全部六个专项审查 Agent。

若只想快速核查某一个方面，可以通过 --focus 缩小审查范围，六个取值分别对应六个专项 Agent：

focus 取值	目标关注点	对应的专项审查 Agent
comments	注释与文档的准确性、腐烂风险	comment-analyzer
tests	测试是否真正覆盖变更行为	pr-test-analyzer
errors	静默失败、被吞掉的错误、缺失的错误传播	silent-failure-hunter
types	类型设计的封装性、不变量表达与约束力	type-design-analyzer
code	通用代码质量、安全性与可维护性	code-reviewer
simplify	在保持行为不变的前提下精简代码	code-simplifier

该命令在仓库中的定位可以通过 COMMANDS-QUICK-REF.md（第 16 行以 “Comprehensive PR review using specialized agents” 收录）与 COMMAND-REGISTRY.json（注册类型为 testing，指向 commands/review-pr.md）确认——它是 ECC 命令体系里归类于“测试与审查”侧的标准命令。

二、五步执行流程：从拿到 PR 到输出分组报告

原文档 commands/review-pr.md 给出了清晰的五步流水线，下面结合 Agent 定义逐一展开。

第 1 步：识别 PR

使用 GitHub CLI 获取 PR 详情、变更文件与差异：

gh pr view

这一步确定审查对象：要审哪些文件、diff 有多大、涉及什么 feature 或修复。若传入 PR-number-or-URL，则对该具体 PR 执行；否则面向当前分支的 PR。

第 2 步：查找项目指南

在审查前先定位仓库内的约定性文件，包括：

• CLAUDE.md（项目级规范入口，本仓库根目录即有 CLAUDE.md）；
• lint 配置（例如本仓库的 eslint.config.js、commitlint.config.js）；
• TypeScript 配置；
• 其它仓库约定（如文件长度上限、emoji 策略、不可变性要求、数据库策略、错误处理模式等）。

这一步的意义在于让后续审查“入乡随俗”：code-reviewer 的定义明确要求审查要匹配项目既有模式，而不是机械套用外部最佳实践——项目自己的 CLAUDE.md、规则文件与编码规范优先于泛化标准，具体依据见 code-reviewer.md 中 “Project-Specific Guidelines” 一节。

第 3 步：运行六个专项审查 Agent

ECC 将一次 PR 审查拆成六个正交的视角，每个视角由独立 Agent 承担，避免单一 Agent 因视野过宽而顾此失彼：

Agent	默认模型	关注焦点
code-reviewer	sonnet	代码质量、安全、可维护性全量清单，覆盖 CRITICAL（安全）到 LOW（最佳实践）
comment-analyzer	haiku	注释是否准确、完整、有长期价值、有无误导或腐烂风险
pr-test-analyzer	sonnet	测试是否真正覆盖 PR 变更的行为，而非“只测了不抛异常”
silent-failure-hunter	—	静默失败、被吞掉的错误、糟糕的 fallback、缺失的错误传播
type-design-analyzer	—	类型设计：封装性、不变量表达、有用性与约束执行力
code-simplifier	—	保持行为一致地精简代码，聚焦最近修改的部分

以 comment-analyzer（comment-analyzer.md）为例，它的分析框架分四个维度：事实准确性（对照代码验证注释声明、核对参数与返回值描述、标记过期引用）、完整性（复杂逻辑是否解释到位、副作用与边界情况是否被记录）、长期价值（标记只复述代码的注释与易腐烂的脆弱注释、暴露 TODO/FIXME/HACK 债务）、误导元素（与代码矛盾的注释、对已删除行为的过期引用、夸大或描述不足的行为）。输出按 Inaccurate / Stale / Incomplete / Low-value 分组，全部以“建议级”提交，不参与合并拦截。

pr-test-analyzer（pr-test-analyzer.md）则关心行为覆盖率：先映射变更涉及的函数/类/模块并定位对应测试，再核查每个 feature 是否都有测试、边界与错误路径是否被覆盖、集成点是否到位；在测试质量上偏好“有意义的断言”而非“不抛异常即通过”，并标记 flaky 模式；最终把覆盖率缺口按 critical / important / nice-to-have 分级输出。

code-reviewer（code-reviewer.md）承担最重的全量清单职责，从安全（CRITICAL）到最佳实践（LOW）共六级；它还额外包含 v1.8 AI 生成代码审查增补条款：优先检查行为回归与边界处理、安全假设与信任边界、隐藏耦合与架构漂移，以及不必要的、推高模型成本的复杂度——成本意识贯穿其中，例如推荐对确定性重构使用更低成本档位，并标记“没有明确推理需求就升级到高成本模型”的工作流。该仓库对这类“成本感知审查”的偏好也体现在其它命令中（如 commands/cost-report.md 的存在侧面印证了这一点，具体以各命令文档为准）。

第 4 步：汇总结果

六个 Agent 的结果汇合后做两件事：

1. 去重（dedupe）：不同 Agent 可能命中同一个问题（例如某个静默失败同时被 code-reviewer 与 silent-failure-hunter 发现），只保留一条；code-reviewer 本身也要求在内部合并同类项——“5 个函数缺失错误处理”应作为一条发现而不是五条。
2. 按严重程度排序（rank by severity）：CRITICAL > HIGH > IMPORTANT > ADVISORY，保证最危险的问题最先可见。

第 5 步：按严重程度分组报告

最终报告以严重程度为纲组织发现项，每条建议遵循结构化输出。code-reviewer 定义的输出模板可以作为统一的参照（code-reviewer.md）：

[CRITICAL] Hardcoded API key in source
File: src/api/client.ts:42
Issue: API key "sk-abc..." exposed in source code. This will be committed to git history.
Fix: Move to environment variable and add to .gitignore/.env.example

  const apiKey = "sk-abc123";           // BAD
  const apiKey = process.env.API_KEY;   // GOOD

审查结束还会附带一个汇总表与结论（verdict）：

## Review Summary

| Severity | Count | Status |
|----------|-------|--------|
| CRITICAL | 0     | pass   |
| HIGH     | 2     | warn   |
| MEDIUM   | 3     | info   |
| LOW      | 1     | note   |

Verdict: WARNING — 2 HIGH issues should be resolved before merge.

三、置信度规则：>= 80 才报告，宁缺毋滥

/review-pr 最关键的工程约束写在 commands/review-pr.md 的 “Confidence Rule” 一节：只报告置信度 >= 80 的问题。与之配套，严重程度划分为三档，且严格限定各自的内容域：

级别	报告范围	说明
Critical（严重）	错误、安全、数据丢失	会导致真实损害的问题
Important（重要）	缺少测试、质量问题、风格违规	不影响正确性但影响长期健康
Advisory（建议）	仅在明确要求时才提供	不主动输出“仅供参考”式噪音

这条规则在 code-reviewer 的 Agent 定义里被展开成一套可操作的过滤机制（code-reviewer.md）：

• Reporting Gate：>80% 确信是真实问题才报告；跳过纯风格偏好（除非违反项目约定）；跳过未变更代码中的问题（除非是 CRITICAL 安全项）；合并相似问题；优先暴露会引发 bug、安全漏洞或数据丢失的项。
• Pre-Report Gate（写发现前的四问）：能否指出精确行号？能否描述具体失败模式（输入、状态、坏结果）？是否已阅读周边上下文（调用方、导入、测试）？严重程度是否站得住脚？任何一问答不上来，就降级或丢弃。
• HIGH / CRITICAL 需要证据：必须给出精确代码片段与行号、具体失败场景（输入/状态/输出）、以及为何现有防线（类型、校验、框架默认行为）拦不住；三条缺一就降为 MEDIUM 或删除。

文档还明确写了一条容易被人忽略的准则：“零发现是有效的审查结果”（It Is Acceptable And Expected To Return Zero Findings）。diff 小而清晰、类型良好、有测试且遵循项目模式时，正确的输出就是零行发现的总结 + APPROVE 结论；制造假发现、填充挑剔性意见、无触发场景的臆测边界情况，是 LLM 审查者最主要且最损害可信度的失败模式。

code-reviewer 甚至列出了 LLM 常误报的“假阳性清单”，要求除非有本代码库特有证据否则跳过：例如上层已由 Express 错误中间件/React Error Boundary/顶层 try-catch 兜住的错误路径不该再报“建议加错误处理”；内部函数且调用方已校验过的不该报“缺少输入校验”；200/404/超时毫秒数/HTTP 状态码等熟知的常量不该报“魔法数字”；测试夹具里的硬编码值本就是期望值，也不该报。判断的最终标准被提炼为一句问话：“团队里的资深工程师真的会在审查中改这个吗？如果不会，跳过。”

四、--focus 定向模式：什么时候只跑单一 Agent

--focus 的设计目的是在以下场景下跳过完整堆栈、节约成本并减少噪音：

• 一次纯重构提交，行为未变 → --focus=code 或 --focus=simplify；
• 一个小型 bugfix，主要风险在回归与错误处理 → --focus=errors；
• 只动了类型声明与接口 → --focus=types；
• 提交主体是测试补全 → --focus=tests；
• 注释与文档同步修改 → --focus=comments。

从源码结构看，--focus 的取值与六个 Agent 一一对应（见本文第一节的映射表），这意味着定向模式实际是只调度与该关注点对应的专项 Agent，从而把审查资源集中在真正的风险区。而“不指定 focus 即全栈”的默认行为，则把六个视角全部纳入——适合合并大 PR、涉及多层改动、或首次接手他人大型改动时的全面体检。

五、命令的底层注册与周边联动

/review-pr 并非孤立命令，它在 ECC 命令体系中的位置可以从三个层面确认：

1. 命令注册表：docs/COMMAND-REGISTRY.json 中将 review-pr 登记为 type: "testing"，指向 commands/review-pr.md，即它属于 ECC 的测试/质量门禁侧工具，与代码审查、测试覆盖类命令并列。
2. 快速参考：COMMANDS-QUICK-REF.md 收录该命令，便于 Agent 在检索命令清单时发现它。
3. 兼容别名与 Epic 联动：commands/epic-review.md 声明 /review-pr 与 /code-review 是协调 Epic issue 审查状态的兼容别名——例如通过 node scripts/github-coordination.js review <issue-number> --repo <owner/repo> --review approved 把审查结论写回 GitHub。这意味着 /review-pr 这类命令既可独立触发即席审查，也能被纳入 Epic 级审查状态机，把结论同步为 issue 上的标签与审计评论。

此外本仓库对命令文档实行多语言维护，commands/review-pr.md 已有对应的中文镜像 docs/zh-CN/commands/review-pr.md 与日文镜像 docs/ja-JP/commands/review-pr.md，内容保持一致，说明这是一条被持续维护、面向多语言用户的正式命令，而非一次性脚本。

六、把 /review-pr 接入日常开发流

综合原文档与 Agent 定义，推荐的使用姿势如下：

• 每次 PR 合并前跑一次全栈 /review-pr，把结果当作合并前的质量门禁；code-reviewer 的审批标准（code-reviewer.md）定义了清晰的三态结论：Approve（无 CRITICAL/HIGH，包括零发现）、Warning（仅有 HIGH，可谨慎合并）、Block（存在 CRITICAL，必须修复后再合）。
• 不要让审查 Agent “为了显得严谨而不放行”：clean diff 就批准，这是定义中明确鼓励的合法结果。
• 为 PR 附上项目级 CLAUDE.md 与 lint/TS 配置约定，让第 2 步的项目指南查找有据可依，审查才能贴合本仓库而非泛泛而谈。
• 对大 PR 善用定向模式分批审查，先 --focus=errors 与 --focus=code 抓高危，再按需补 --focus=tests 验证测试质量。

小结

/review-pr 提供了一条可复现的 PR 审查流水线：gh pr view 识别对象 → 项目指南对齐约定 → 六个专项 Agent（code-reviewer、comment-analyzer、pr-test-analyzer、silent-failure-hunter、type-design-analyzer、code-simplifier）分视角深挖 → 去重并按严重程度排序 → 输出分组报告。真正让它区别于“让 LLM 随便看看”的，是贯穿其中的反噪音纪律：置信度 >= 80 才报告、HIGH/CRITICAL 必须附带可复现证据、假阳性清单前置拦截、零发现是被认可的合法结果。这套机制连同按级别定义的 Approve/Warning/Block 结论，使多 Agent 协作的审查既能覆盖更广的视角，又不至于淹没在臆测与挑剔之中。