autonomous-review

自主评审模式

发布评审结论前，使用辅助工具和包装器提供的标识符评估持久会话知识。检查早期的开发／评审候选内容，修正或丢弃过时事实，并在适用时记录明确的无更新原因。阅读 ../autonomous-common/references/session-knowledge.md。 Stop hook 检查的是这项评估，而非经验记录是否存在。确认合并后，包装器会提交有用且范围明确的文档更新，并另行创建一个 PR；本地环境／凭据引用会继续忽略。

提供方通道范围。 以下文字使用 GitHub 术语——gh pr review、gh pr merge、gh pr checks、gh pr view、gh issue view——因为这些是 GitHub 通道的具体形式。每条 INV-52 / INV-44 规则（Agent 发布评审结论评论；包装器负责批准／请求更改／合并；包装器执行可合并性硬性门槛）均与提供方无关，并原样适用于 GitLab 通道（CODE_HOST=gitlab）：包装器会通过 chp_approve / chp_merge / chp_mergeable 提供方接口，而不是使用 gh pr * 命令。当提示词在 CODE_HOST=gitlab 下运行时，请将每个 gh pr … / gh issue … 示例视为包装器提供的接口占位符——不要自行编写 glab 调用来替代它们。

彻底、客观地评审自主开发会话创建的 PR，然后发布评审结论评论（Review PASSED 或 Review findings:）。评审包装器负责 GitHub 原生操作：在 PASS 时提交 --approve 并合并（通过其可合并性和 no-auto-close 门槛后），在阻断性 FAIL 时提交 --request-changes。切勿自行运行 gh pr review 或 gh pr merge——参见谁提交 GitHub 原生 PR 操作（INV-52）。

适用场景

使用此技能	使用其他技能
对已完成的 PR 给出最终结论（发布评审结论评论；包装器负责批准并合并或请求更改）	实施期间开发流程中的自检 → 使用 autonomous-dev 第 8 步（pr-review）
调度器移交了标记为 pending-review 或 reviewing 的 PR	手动对草稿 PR 进行部分评审 → 直接使用 pr-review-toolkit Agent
运行 E2E 验证、检查验收标准并解决合并冲突	仅检查 CI 状态 → 直接使用 gh pr checks

跨平台说明

此技能适用于任何支持技能的 IDE／CLI。浏览器自动化步骤使用 Chrome DevTools MCP——请确保 IDE 已配置此 MCP 服务，以便进行 E2E 验证。

Hooks（可选）

如果 IDE 支持 hooks（Claude Code、Codex CLI、Kiro CLI），hooks/ 中的工作流强制执行 hooks 会提供自动门槛检查。若不支持 hooks，请手动遵循每个步骤。

评审清单

核验以下所有内容：

对于代码问题，使用项目配置或包装器提示中指定的 REVIEW_BLOCKING_SEVERITY：默认 P1 只会阻断首轮发现的 P0/P1。P2/P3 备注仍会显示，但不要求修复。P2/P3 会选择更严格的固定门槛；adaptive 会选择依赖轮次的旧版门槛。必要的验收标准、安全控制、测试、CI 和合并门槛仍具有阻断性。推迟处理未标记的正确性问题前，先对其分类。不要将风格偏好提升为 P1 来强制清理。记录在案的建议性处置视为已处理。

后续轮次中，核验现有阻断项、已更改代码及受影响的契约。只有出现新证据时，才重新打开已解决的问题；根据更改情况扩大评审范围。复用有效且对应同一 HEAD 的验证证据。如果包装器已运行 E2E，请阅读其结果和覆盖范围，不要再次运行。

1. 流程合规性

• 变更要求或仓库政策要求时，已创建设计画布
• 分支遵循命名约定（feat/、fix/、refactor/ 等）
• 必要时已记录测试用例；现有回归测试可用于说明小型修复
• PR 描述遵循模板（Summary、Design、Test Plan、Checklist 部分）
• PR 引用了相关问题（Closes #N 或 Fixes #N）

2. 代码质量

• 不存在安全问题（无凭据、无注入漏洞）
• TypeScript 类型正确（未滥用 any）
• 错误处理恰当
• 代码遵循代码库中的现有模式
• 不存在明显的性能回退

3. 测试

• 新功能有单元测试
• 新代码的单元测试覆盖率合理
• UI 有变更时已更新 E2E 测试
• 所有 CI 检查均已通过

4. 基础设施（如适用）

• 基础设施即代码变更安全
• 未意外删除资源
• IAM 权限遵循最小权限原则

5. 可选：机器人审查验证

• 如果已配置的机器人审查员已发布审查意见，请确认其发现的问题均已处理
• 所有机器人审查讨论串均已解决
• 如果缺少机器人审查且已配置，请使用 scripts/gh-as-user.sh 触发（见下文“触发机器人审查员”）

触发机器人审查员

必需机器人的集合由项目 autonomous.conf 中的 REVIEW_BOTS 决定。REVIEW_BOTS 为空时，完全跳过本节；否则，触发每个已配置的机器人。

必须使用 scripts/gh-as-user.sh。 所有内置机器人（Amazon Q、Codex、Claude）都会拒绝由 GitHub App 机器人帐户发布的触发评论；该封装脚本会以真实用户身份发布评论。

内置机器人的触发方式：

# When q ∈ REVIEW_BOTS:
bash scripts/gh-as-user.sh pr comment {pr_number} --body "/q review"

# When codex ∈ REVIEW_BOTS:
bash scripts/gh-as-user.sh pr comment {pr_number} --body "/codex review"

# When claude ∈ REVIEW_BOTS (note: @claude, not /claude):
bash scripts/gh-as-user.sh pr comment {pr_number} --body "@claude review"

对于通过 REVIEW_BOTS_<NAME>_TRIGGER 声明的自定义机器人，请使用已配置的触发方式。

请勿使用默认的 gh pr comment 触发机器人审查——该命令会以机器人身份进行身份验证。如果项目中没有 scripts/gh-as-user.sh，则改用 gh pr comment，并接受某些机器人可能会忽略触发的情况。

6. E2E 验证

如果已配置 E2E 验证，本节为必填项。 封装脚本会根据 E2E_MODE 注入两种流程之一。如果提示词中没有出现任何一种流程，请跳过本节。

浏览器模式（E2E_MODE=browser，适用于 SaaS Web 应用）：

• 已从 PR 评论中提取预览 URL
• 已通过 Chrome DevTools MCP 成功访问预览 URL
• 已在预览环境中验证测试用户登录
• 已选择并执行正常流程测试用例（见下文）
• 已针对实时预览执行功能测试用例
• 已执行回归测试（身份验证、导航、控制台错误）
• 已截取并上传屏幕截图，并将其作为证据链接
• 已在 PR 评论中发布 E2E 验证报告，并附上屏幕截图链接

命令模式（E2E_MODE=command，适用于后端管道 / CLI / 库）：

• 已执行前置钩子（如已配置）——退出码为 0
• 已在超时时限内执行验证命令——退出码为 0（或发生可恢复的超时）
• 证据解析器生成了以 `` 结尾的 Markdown 块
• 已将证据块作为 PR 评论发布
• 问题正文中每项指定了可验证产物的验收标准，均已由证据块覆盖

合并冲突解决 — 强制预审步骤

开始评审前，检查 PR 分支是否与 main 存在合并冲突。如果存在，请变基该分支，确保 PR 可合并。完整的变基流程、冲突处理和失败协议，请参阅 references/merge-conflict-resolution.md。

快速检查：

MERGEABLE=$(gh pr view <PR_NUMBER> --repo <REPO> --json mergeable -q '.mergeable')

• MERGEABLE — 继续评审流程
• CONFLICTING — 按 references 中的流程进行变基；这是一个阻塞性问题（FAIL）
• UNKNOWN — 等待并重试（最多 3 次）；如果仍为 UNKNOWN，切勿将其视为 MERGEABLE — 暂不完成评审，留待下一次检查

此步骤是尽力而为的提示指导；评审包装器会在汇总各项判定后以机械方式执行同一规则（合并性硬性门槛，INV-44）。即使跳过此步骤，CONFLICTING 的 PR 也绝不会获批；持续处于 UNKNOWN 的 PR 会重新排队，而不会自动获批。

评审流程

1. 阅读问题，了解需求
2. 阅读问题的所有评论，检查需求是否有变化（参见下文“需求变更检测”）
3. 彻底阅读 PR 差异（gh pr diff <number>）
4. 检查 CI 状态（gh pr checks <number>）
5. 阅读设计文档、测试用例等文件，确认这些文件确实存在
6. 根据上方的检查清单评估代码质量
7. 核实机器人评审者的发现（如果已配置 — 参见检查清单第 5 节）
8. 根据 PR 差异分析选择顺畅路径测试用例（参见下文）
9. 执行端到端验证（如果已配置 — 参见下文流程）
10. 标记验收标准 — 对每项已验证的标准，在问题正文中勾选其复选框（参见“标记验收标准”）
11. 强制自检门槛 — 提交任何评审判定之前，先执行“发现项→判定”门槛（参见下文）

需求变更检测 — 强制要求

此步骤必须在阅读 PR 差异之前完成。 实现完成后，仓库所有者或维护者可能会通过问题评论修改需求。

阅读问题的所有评论（不只是正文），并查找以下内容：

• 范围变更（“移除”“不再”“放弃”“不支持”“改为”等）
• 原始问题创建后新增的要求
• 仓库所有者提供的更正或说明
• 给开发 Agent 的明确指示，这些指示可能尚未反映在 PR 代码中

# Read all issue comments to check for requirement changes
gh issue view <ISSUE_NUMBER> --repo <REPO> --json comments \
  -q '.comments[] | "\(.author.login) [\(.createdAt)]: \(.body[0:500])"'

如果发现 PR 代码未体现任何需求变更：

• 这是一个 [BLOCKING] 需求变更问题
• 必须将 PR 退回给开发者，并明确说明具体变更
• 引用导致需求变更的评论
• 列出需要更新的具体代码或文件

顺畅路径测试用例

顺畅路径测试用例因项目而异。评审 Agent 根据以下内容选择用例：

1. 查看 docs/test-cases/ 目录，了解有哪些测试用例文档
2. 分析 PR 差异，确定哪些区域发生了变更
3. 选择与变更功能最相关的测试用例
4. 每次评审至少执行一个顺畅路径测试用例

如果不存在测试用例文档，则执行基本的冒烟测试：

• 导航至应用根 URL
• 确认页面加载且没有错误
• 检查浏览器控制台是否有 JavaScript 错误

端到端验证流程

本节仅适用于已配置端到端验证的情况。 评审包装脚本（autonomous-review.sh）会根据项目在 autonomous.conf 中设置的 E2E_MODE，向提示词注入以下两种端到端流程之一：

• E2E_MODE=browser — 使用 Chrome DevTools MCP 进行 UI 冒烟测试（登录、导航、截图）。适用于每个 PR 都有预览 URL 的 SaaS Web 应用。
• E2E_MODE=command — 调用项目提供的验证命令，并验证其证据输出。适用于后端流水线、CLI 工具、库、基础设施即代码或 ML 流水线。

如果提示词中没有出现任何一个代码块，则表示项目未启用端到端验证（E2E_MODE=none 或未设置）。跳过本节。

浏览器模式

完整的浏览器模式分步流程（浏览器自动化、截图上传、测试执行、报告格式），请参阅 references/e2e-verification.md。

关键步骤：

1. 确认预览 URL 可用
2. 打开浏览器，并通过 Chrome DevTools MCP 导航
3. 使用测试用户凭据登录
4. 执行正常流程和功能测试用例
5. 运行回归检查（身份验证、导航、控制台错误）
6. 在 PR 上发布结构化的 E2E 报告并附上截图证据

命令模式

完整的契约（项目端脚本要求、证据块格式、退出码语义、接入示例），请参阅 references/e2e-command-mode.md。

关键步骤：

1. 如果配置了前置钩子，则运行这些钩子（例如，将测试数据植入对应 PR 的阶段环境）
2. 运行验证命令并设置超时
3. 检查退出码（0 = 通过；124 = 超时；其他 = 失败）
4. 运行证据解析器以提取结构化 Markdown 块
5. 验证该块以 SHA 绑定标记 `` 结尾（必须包含 SHA，以防先前提交的过期证据被重复用于评论）
6. 将证据块作为 PR 评论发布
7. 根据退出码和证据对验收标准的覆盖情况判定通过/失败

标记验收标准

在 E2E 验证期间，验证每项验收标准后，都要勾选 issue 正文中的对应复选框。

流程

1. 阅读 issue 正文并找到 ## Acceptance Criteria 部分
2. 对于每项标准： a. 通过 Chrome DevTools MCP、代码检查或 CI 检查结果进行验证 b. 如果通过，勾选复选框：

   bash scripts/mark-issue-checkbox.sh <ISSUE_NUMBER> "<criterion text>"
   

   c. 如果失败，停止勾选——记录失败并继续执行“Review findings”
3. 该脚本使用 gh（它会通过 GH_TOKEN_FILE 获取当前生效的 App 令牌），因此所做的修改会显示为由已配置的审核机器人完成

重要规则

• 仅在验证通过后勾选标准——不要提前勾选
• 如果任意一项标准失败，不要勾选它——改为发布“Review findings:”
• 不要勾选 Requirements 复选框——这些由开发 Agent 负责
• 批准 PR 前，所有验收标准都必须已勾选（- [x]）

Findings -> 决策门——强制要求

此门槛不可妥协。在提交任何 PR 审查（APPROVE 或 REQUEST_CHANGES）以及在 issue 上发布裁定评论之前，必须先执行此自检。

完整的门槛流程（发现分类、阻塞与非阻塞规则、自检问题、决策标准和输出格式）请参阅 references/decision-gate.md。

硬性规则摘要：

• 任何阻塞性发现 -> 裁定必须为 FAIL——发布 Review findings:（随后由包装器提交 --request-changes）。
• 没有阻塞性发现 -> 裁定为 PASS——发布 Review PASSED（随后由包装器提交 --approve，并在通过其门槛后合并）。
• 没有中间状态——包含阻塞项的 Review findings: 评论与 Review PASSED 评论互斥。

将审查结果作为评论发布在 issue 上（而非 PR），且只能通过确定性辅助脚本 bash scripts/post-verdict.sh <issue> <pass|fail> <body-file> <agent-name> <session-id> [<model>] 发布——不得直接使用 gh issue comment 发布裁定（INV-56）。该辅助脚本会确保首行为包装器轮询的 "Review PASSED" / "Review findings:"，并自行附加 Review Session: \`+Review Agent: 尾注，因此你无需手动编写。提供可选的第 6 个参数时，辅助脚本会将其合并到 Agent 行，格式为Review Agent: (model: )，以便裁定评论记录生成结果的模型（[INV-60](../../docs/pipeline/invariants.md)）。传入正文**文件**（而非 argv 字符串），以避免多行发现内容中的反引号或引号遭到破坏；包装器会在提示词中提供 、和`——请原样传入。你唯一的输出是裁定评论——GitHub 原生 PR 操作由包装器执行（见下文）。

对于 Claude 审查成员，包装器还会在启动时检查是否至少配置了一种无人值守的裁定报告途径。有关 #524 故障特征、修复方法和抑制约定，请参阅 Claude 无人值守裁定途径启动警告。

谁负责提交 GitHub 原生 PR 操作（INV-52）

GitHub 原生 PR 审查/合并操作由审查包装器负责，而非你。 你发布裁定评论（通过 post-verdict.sh）；包装器读取评论并执行操作。

• 对于 PASS，包装器会在通过机械式可合并硬性门槛（INV-44）以及 no-auto-close 跳过合并检查后，提交 gh pr review --approve，并且（除非 issue 带有 no-auto-close）提交 gh pr merge。
• 对于存在阻塞性问题的 FAIL，包装器会提交 gh pr review --request-changes，使 PR 的 reviewDecision 变为 CHANGES_REQUESTED——这是对人类、分支保护和 dev-resume Agent 具有权威性的状态（INV-52）。
• 你绝不能自行运行 gh pr review --approve、gh pr review --request-changes、gh pr merge 或 MCP 合并工具。 这样做会与包装器的门槛检查发生竞态：自行批准并合并，可能会合并可合并性仍为 UNKNOWN 的 PR（INV-44），或合并关联 no-auto-close issue 的 PR——这正是促使制定 INV-52 的 PR #191 事件。Agent 执行任何 GitHub PR 审查或合并操作都属于缺陷，而非捷径。

多 Agent 审查（配置后）

当项目将 AGENT_REVIEW_AGENTS 设置为多个 CLI 时，多个审查 Agent 会针对同一个 PR 并行运行，每个 Agent 都是完全独立的审查者。如果你是其中之一：

• 独立运行“发现项 → 决策关卡”——根据自己的发现得出 PASS/FAIL。不要尝试与其他 Agent 协调或听从它们的判断；你看不到它们的结论。
• 使用 bash scripts/post-verdict.sh 提交自己的结论，并附上分配给你的 Agent 名称和会话 ID（两者都在你的提示词中）——绝不要直接使用 gh issue comment（INV-56）。此辅助脚本会根据你传入的参数写入 Review Agent: <name> 标识行，因此始终准确；封装程序会根据该行区分并行审查者的结论（INV-40）。
• 封装程序依据全员通过规则汇总所有 Agent 的结论：只有所有可用 Agent 都通过时，封装程序才会批准并合并；任何一个 FAIL 都会使封装程序提交 --request-changes，并将 PR 退回给开发人员。这与关卡自身“任何阻断性发现项 → FAIL”的原则一致，只是应用于多个 Agent。如上所述，没有任何 Agent 会提交 GitHub 原生操作——汇总完成后，由封装程序统一提交一次。

内部审查子 Agent 仅提供建议

Claude 或 Codex 的内部子 Agent 可以并行检查安全性、测试、可维护性或其他审查维度。它们会向父级返回证据和发现项，仅提供建议，不属于 AGENT_REVIEW_AGENTS。

在封装程序分配的每个结论会话中，只有父级审查会话会执行“发现项 → 决策关卡”，并使用封装程序提供的 Agent 名称和会话 ID 调用 post-verdict.sh。不要将 post-verdict.sh 委托给内部子 Agent。每个父级都必须将建议性发现整合到自己的单一 PASS/FAIL 决策中。

请区分以下三种机制：REVIEW_BOTS 是外部代码托管平台审查者，AGENT_REVIEW_AGENTS 是由封装程序管理、独立形成结论的会话，内部子 Agent 则是此类会话中的建议性工作者。

---

参考资料

详细流程请参阅：

• references/merge-conflict-resolution.md -- 完整的变基流程、冲突处理和故障处理协议
• references/e2e-verification.md -- 浏览器自动化步骤、截图上传、测试执行、E2E 报告格式（E2E_MODE=browser）
• references/e2e-command-mode.md -- 项目提供的验证命令约定、证据块格式、入门示例（E2E_MODE=command）
• references/decision-gate.md -- 发现项分类、阻断规则、决策标准和输出格式