gh-pr-review

/gh-pr-review — 代码审查

针对本地分支、PR、提交和文件的自动化代码审查。它会从参数中识别审查目标，然后根据 diff 大小和运行时能力选择审查引擎。较小的 diff 使用单 Agent 审查（references/local-review.md）。较大的 diff 仅在可用独立子 Agent 时使用多 Agent 的审查者—验证者流程（references/teams-review.md）；否则回退到单 Agent 审查，并披露该限制。PR 目标会在相同的引擎选择约定之外，增加工作树设置和 GitHub 提交（references/pr-review.md）。

Cherry Studio 专属审查规则位于 references/cherry-review-guidance.md。目标审查流程必须在代码、混合、架构文档和项目技能审查中加载该文件，以便审查者无需依赖记忆即可应用 DataApi、服务边界、渲染器 hook、React、UI 和类型契约检查。该参考还定义了每个变更领域应查阅哪些内部文档、内部技能、外部技能和官方网站；只加载相关子集。

所有面向用户的文本都匹配用户的语言。

交互与中断约定

除下文声明的类别外，正常审查无需提示：绝不询问模式选择、修复确认、发现项选择或提交预览。叶子流程只有在明确声明以下类别之一时，才可以请求输入：

• 产品决策 — 在交互式会话中，产品需求门禁可以向当前用户询问审查无法推导出的决策。在自动化会话中，记录影响和待定决策，而不替用户做决定。
• 安全或环境阻塞 — 继续执行将需要破坏性操作、新授权或缺失的外部配置。已声明的示例包括：脏的/不匹配的审查工作树、缺失的规范远程、清理无法解释的变更、移除失败的修复补丁，以及持有本次运行未确认评论的待处理审查草稿。在交互式会话中，保留状态，仅询问继续所需做出的决策。
• 显式维护模式 — diag 和单独请求的清单维护是正常审查之外的交互式选择流程。它们可以询问已声明的编辑选择或持久检出/分支目标。

自动化会话绝不等待用户输入。在产品决策处，它按下文规定继续仅做记录。在安全/环境阻塞处，它保留状态，安全地停止受影响的流程，并报告确切的阻塞和所需决策。在显式维护模式中，它报告候选项或缺失的目标信息，不应用任何依赖选择的编辑，并安全停止。任何叶子流程都不得引入其他提示类别。

评审阶段

每次评审都按顺序运行这些阶段。后续阶段只评审通过前面阶段的内容，因此某个阶段不会重新推翻之前的结论。

本表是阶段范围与引用的唯一事实来源；叶子流程不得扩大、缩小或重新引用某个阶段。

#	阶段	适用范围	引用
1	产品需求（门禁）	任何语义上影响产品的变更	见下文
2	消费者	任何新增或扩展共享表面的变更	references/consumer-review.md
3	架构优先	代码、混合、Cherry 架构文档、项目技能	references/cherry-review-guidance.md
4	实现	代码、混合	references/code-checklist.md（A/B）
4	实现	文档	references/doc-checklist.md（A/B）
5	风格 / 约定	代码、混合	references/code-checklist.md（C）
5	风格 / 约定	文档	references/doc-checklist.md（C）

阶段适用性取决于变更内容，而非提交标签：仅涉及文档的 diff 在修改 Cherry 架构文档或项目技能时仍会运行阶段 3–5，而同时编辑文档的代码 diff 会为阶段 4–5 运行两组引用。

阶段 1：产品需求门禁

先检查变更实际表达或约束的语义，再判断它是否影响产品语义、用户可见行为或产品方向。变更标签不足以作为证据：内部重构和非面向用户的修复通常没有产品影响，而面向用户的修复、文档、测试或工具链可能记录、锁定或改变产品行为。

当存在产品影响时，确定该方向是否已在当前评审上下文中确立。仅当当前用户明确决定该方向，或权威项目制品明确记录了被接受的行为及其由负责的项目权威批准时，才将其视为已确立，例如规范、ADR 或包含维护者决定并据此确定预期行为的 issue。不要从 issue 状态、标签、里程碑、指派或 PR 中的链接推断接受。变更标签、PR 正文、实现或测试能表明作者意图或当前行为，但其本身不能确立产品批准。

将门禁归类为恰好一种状态：

• 无产品影响：在交互式和自动化运行中都完全跳过此阶段；对跳过的门禁不作任何说明。
• 方向已确立：将变更与记录的决定进行比较。如果一致，继续，无需再次请求产品决定。如果冲突，报告产品方向不匹配并立即停止整个评审——不运行消费者、架构、实现或风格阶段，也不报告代码发现。应用现有决定并非做出新决定。
• 待定产品决定：
  • 交互式会话（默认）：总结变更对产品功能和语义的影响，并就未解决的产品决定询问当前用户。不要从 PR 作者身份、评审归属或用户是否编写了该变更推断自动化。如果用户拒绝该方向，如上所述停止整个评审；如果用户批准，继续其余阶段。
  • 自动化会话（仅限显式）：仅当调用提示词或工作流上下文明确标识为无头、CI、批处理或其他自动化运行时，才使用此模式。不要代表用户做出任何产品决定。运行其余阶段，并在最终报告中总结产品影响、变更所采取的方向以及需要人工确认的要点。绝不要将此表述为已获得产品批准。

权限模型

审查请求仅授权进行分析与报告。审查目标、审查深度以及审查者–验证者的置信度从不授予执行权限；权限在调用时被显式授予，且只有在被授予后，执行才无需提示：

• 仅报告（默认）：任何审查、任何目标——报告发现的问题并附上修复指导。不编辑工作树，不写入 GitHub。
• 修复（显式）：仅由调用授予——$ARGUMENTS 中的 fix 或等效的显式用户措辞（“审查并修复……”）。仅限本地目标。每个风险等级随后允许什么，由 references/judgment-matrix.md § 按风险等级处理 拥有；本节授予权限，绝不重述该映射。 应用修复会使本次会话成为一项编码任务，因此必须以按下方 § 应用修复后的验证 所选的验证结束。
• 提交（显式）：仅由调用授予——$ARGUMENTS 中的 submit 或等效的显式用户措辞。PR 流程随后提交所有已确认的发现，无需逐条评论提示。批准或合并始终需要其自身的显式请求。

应用修复后的验证

在一次未编辑任何内容的审查期间，绝不运行本地 lint、测试或格式化。当已应用修复时，选择与被更改表面匹配的验证，遵循 AGENTS.md § 操作规则（“检查你所更改的内容，而非整个仓库”），并报告结果：

• 仅文档/markdown 的修复——包括本技能自身的文件——运行 pnpm docs:check。
• 代码修复运行 pnpm lint（其结尾已包含 pnpm format，因此绝不要再次调用 format）加上覆盖该更改的测试：各项目包装脚本，如 pnpm test:main <file> 或 pnpm exec vitest run <file>。绝不要用 pnpm test <path>——该脚本串联了多个 vitest 调用，而路径只会到达最后一个。
• 将完整的 pnpm test 保留给无法具名受影响测试的大范围更改，并在 CI 等效的 lint 门禁重要时使用 pnpm test:lint（pnpm lint 容忍 CI 拒绝的 oxlint 警告）。

路由

首先从 $ARGUMENTS 中剥离权限修饰符（对话中等效的显式用户措辞同样有效；二者均默认 false）。将其余部分称为 REVIEW_TARGET——下方每条规则以及每条叶子流程，读取的都是 REVIEW_TARGET，而绝非原始的 $ARGUMENTS：

• fix → AUTHORIZED_FIX = true（对本地目标有意义）
• submit → AUTHORIZED_SUBMIT = true（对 PR 目标有意义）

在选择审查引擎之前，检查运行时暴露的协调能力。仅当它能够启动一个独立审查者和一个全新的独立验证者时，才设置 HAS_SUBAGENTS = true。不要求并行执行；顺序子 Agent 仍满足隔离契约。

规则

按从上到下的顺序匹配第一条适用的规则：

1. REVIEW_TARGET 为 diag → references/diagnosis.md。
2. REVIEW_TARGET 为 checklist，或用户明确要求采用所提议的检查清单候选 → references/checklist-evolution.md，从其 Step 2 进入。维护仅在产生候选的会话中运行；它不审查任何内容。
3. REVIEW_TARGET 为 PR 编号或包含 /pull/ 的 URL → references/pr-review.md（传入 AUTHORIZED_SUBMIT 和 HAS_SUBAGENTS；包装器在选择引擎前收集确切的 PR 范围）。
4. 其他所有情况：按下方 § 范围推导推导出范围和 SMALL_SCOPE，然后选择引擎。
   • SMALL_SCOPE = true → references/local-review.md。
   • SMALL_SCOPE = false 且 HAS_SUBAGENTS = true → references/teams-review.md。
   • SMALL_SCOPE = false 且 HAS_SUBAGENTS = false → references/local-review.md；传入 LIMITED_SINGLE_AGENT = true，以便报告明确说明大型 diff 接受了单 Agent 审查，没有独立的对抗性验证。
   • 传入 AUTHORIZED_FIX（提交和范围目标是不可变历史——无论该标志如何，始终仅报告）。

每个 → 意味着：Read 目标文件，并将其作为关于如何获取 diff、应用修复和提交结果的唯一剩余指令加以遵循。不要凭记忆或习惯进行审查。技能级章节——§ 审查阶段、§ 权限模型、§ 应用修复后的验证，以及 § 范围推导——仍然具有约束力；叶子流程按名称引用它们。

绝不要为了路由而向用户询问任何事情。将 REVIEW_TARGET、解析后的范围、SMALL_SCOPE 和权限标志传入目标文件。

范围推导

只能从上面的规则 4 到达此处；diag 和 checklist 目标从不进入本小节。它是审查范围及其大小如何推导的唯一负责人——叶子流程引用它，绝不重述它。

将 REVIEW_TARGET 解析为审查范围：

REVIEW_TARGET	范围
为空，存在未提交的更改	仅未提交的更改——git diff HEAD（已暂存 + 未暂存的已跟踪文件），加上来自 git status --porcelain 的未跟踪（??）文件，作为新代码进行审查
为空，工作区干净	与基线进行分支 diff：git merge-base origin/{main|master} HEAD，然后 git diff <merge-base-sha>，再加上未跟踪文件
提交哈希	用 git rev-parse --verify 验证，然后 git show
提交范围（A..B / A...B）	验证两个端点，然后 git diff A~1..B
文件/目录路径	验证每个路径存在，然后解析出的文件的完整内容
PR 编号或 /pull/ URL	该 PR 的 merge-base diff，由 references/pr-review.md 收集

决定是否有工作可做的是解析出的审查范围，而不是 diff：对于路径目标，它是由给定路径解析出的文件集合；对于其他所有目标，它是 diff。干净的工作区不会使路径目标为空。如果解析出的范围为空，显示下面的用法示例并退出。

然后测量叶子流程实际会读取的内容——对于 diff 形态的目标是 diff，对于路径目标是完整文件文本：

• diff 形态的目标（未提交的更改、分支/merge-base diff、单个提交、提交范围、PR）：CHANGED_LINES 是完整审查范围内来自 git diff --numstat 的数字形式的添加和删除行数之和，CHANGED_FILES 是其中唯一更改路径的数量。
• 文件/目录路径目标：叶子流程审查完整内容，因此测量完整内容——CHANGED_FILES 是由给定路径解析出的文件数量（目录递归展开，排除被忽略的路径），CHANGED_LINES 是这些文件的总行数。干净的工作区绝不会默认使路径目标变小。
• 未跟踪的文本文件在 diff 形态的范围中每个算作一个文件，其完整行数计为添加。
• 生成的文件在两个总计中都正常计数；不要因为它们是生成的而排除它们。
• 任何二进制文件——二进制 diff（--numstat 中的 -/-）、未跟踪的二进制文件，或从路径目标解析出的二进制文件——都算作一个文件，并使范围变为非小范围，因为其行数大小未知。

仅当 CHANGED_LINES <= 1000、CHANGED_FILES <= 20 且范围中不包含二进制文件时，才设置 SMALL_SCOPE = true。两个数字条件都必须成立。SMALL_SCOPE 是每个流程用于此结果的名称。

用法示例

当解析出的范围为空时打印此列表：

/gh-pr-review                      review uncommitted changes, else the branch diff
/gh-pr-review a1b2c3d              review a commit
/gh-pr-review a1b2c3d..e4f5g6h     review a commit range
/gh-pr-review src/foo.ts           review files or directories
/gh-pr-review 123                  review a PR (also accepts a /pull/ URL)
/gh-pr-review <target> fix         also apply low-risk fixes (local targets)
/gh-pr-review <pr> submit          also publish the review to GitHub
/gh-pr-review checklist            adopt this session's proposed checklist items
/gh-pr-review diag                 diagnose gaps in this skill