review-prs

审查 PR

审查拉取请求，并将发现作为行内评论留在每个 PR 上；只要修复方案明确，就附上建议的修改，让作者可以一键应用。每个拉取请求都要经过两轮检查：它是否实现了关联 issue 的意图，以及代码是否正确。

建议的修改是 GitHub 的一项功能，因此此技能需要 GitHub 仓库和 gh。issue 跟踪工具可以是任何形式——GitHub、Jira 或本地 Markdown 文件。

此技能描述的是操作——“分派审查者”——而不是工具。请使用你所在平台上的等效方式。

第 1 阶段——选择拉取请求

1. 确认已安装 gh，且 gh auth status 检查通过；否则说明原因并停止。
2. 仓库：用户指定的仓库；若未指定，则使用当前检出的 GitHub 仓库（gh repo view --json nameWithOwner）。说明你使用的是哪个仓库。
3. 拉取请求：用户指定的请求；如果用户说“全部”或“开放的请求”，则运行 gh pr list --repo <owner/repo> --state open --limit 1000 --json number,title,url,isDraft。除非用户指定草稿，否则排除草稿。
4. 列出这些请求，并说明将对每个拉取请求发表评论。用户确认列表后即可发布；但如果你收到分派时已获准发布（例如 implement-issues 对其创建的草稿就是如此），则列出请求后继续。

第 2 阶段——收集每个拉取请求的上下文

1. gh pr view <number> --json title,body,baseRefName,headRefOid 会提供描述和头部提交。获取提交以便在本地审查——运行 git fetch origin pull/<number>/head <base>，然后将 HEAD_SHA 设为头部提交，并将 BASE_SHA 设为 git merge-base origin/<base> <HEAD_SHA>。
2. 找出它关联的意图 issue：根据 docs/agents/issue-tracker.md 的 Linking 部分，在标题和正文中查找引用——在 GitHub 上查找 Closes #<number> 或 Relates to #<number>——并使用 Reading method 阅读该 issue。如果没有关联 issue 或没有跟踪器配置，则跳过该拉取请求的意图检查，并在审查中说明。
3. 阅读已有评论——运行 gh api --paginate repos/<owner>/<repo>/pulls/<number>/comments——避免重复发布已提出的发现。

第 3 阶段——审查

意图检查（你）。 将差异与 issue 的 Proposed outcome 和 Constraints 进行比较。报告 issue 要求但拉取请求未实现的内容、拉取请求实现但 issue 未要求的内容，以及差异违反的每一项 Constraint。

代码检查（审查者）。 使用 Superpowers 的 requesting-code-review：将拉取请求的标题和描述作为描述，将意图 issue（若没有，则使用拉取请求正文）作为需求，并提供 BASE_SHA 和 HEAD_SHA，然后分派其代码审查者。使用你所在平台提供的能力最强的模型；但如果 docs/agents/delivery.md 存在，且其中的 pr-code-reviewer 席位解析为你所在平台分派功能接受的模型（该平台 Tiers 表中列出的层级，或精确名称），则改用该模型。若该席位不存在或无法解析，则使用能力最强的模型，并在报告中说明；不要因此停止。审查不会修改任何内容，因此可以同时分派多个拉取请求的审查者。如果不支持子 Agent，则自行审查每个差异。

仅检查意图。 如果分派给你的任务关闭了代码检查——implement-issues 在工作量较小时会这样做，因为构建流程已在整个分支上完成代码审查——则跳过代码检查。在审查正文中说明跳过的原因。

发布前检查每一项发现。 打开每项发现所指向的代码，并确认问题确实存在。审查者可能会出错，而在他人的拉取请求上留下错误评论，造成的影响大于漏掉一项发现。删除无法确认的问题，并在报告中说明原因。

第 4 阶段 — 评论并提出修改建议

每个拉取请求发布一条评审，设置 event: "COMMENT"。

• 将每条问题定位到相关的已更改行：path、line 和 side: "RIGHT"；如果涉及多行，还要设置 start_line 和 start_side。GitHub 只接受出现在拉取请求差异中的行。

• 每条评论以严重程度开头 — Critical、Important 或 Minor — 并用一句话说明后果。

• 如果修复方案明确，在评论末尾添加建议代码块，其中包含所定位行的完整新文本，缩进与文件保持一致：

  **Important** — an invalid address reaches the queue and fails later in
  the worker, where the user never sees the error.
  
  ```suggestion
  if (!isValidEmail(email)) throw new ValidationError("email");
  await queue.add("confirm", { email });
  ```
  

• 如果修复需要讨论设计，或涉及差异之外的行，请不添加建议代码块，直接说明，或将其写入评审正文。

gh api --method POST repos/<owner>/<repo>/pulls/<number>/reviews --input review.json

{
  "commit_id": "<HEAD_SHA>",
  "event": "COMMENT",
  "body": "<counts by severity, and the intent pass's result>",
  "comments": [
    {
      "path": "src/signup.ts",
      "start_line": 41,
      "start_side": "RIGHT",
      "line": 42,
      "side": "RIGHT",
      "body": "<severity and consequence, then the suggestion block>"
    }
  ]
}

如果没有发现问题，发布一条评审，在正文中说明这一点，不添加行内评论。

第 5 阶段 — 报告

制作一张表格，列出拉取请求、关联议题、按严重程度发布的问题，以及评审的 URL。然后列出在检查步骤中舍弃的问题，并说明原因。

注意事项

• 不要批准或请求更改 — 只发布 COMMENT 评审；是否批准由用户决定。
• 不要向拉取请求的分支推送提交；是否应用建议由作者决定。
• 不要发布未经代码检查的问题。
• 不要提交替换行数多于或少于评论所定位行数的建议，也不要提交并非这些行完整新文本的建议。
• 不要将评论定位到拉取请求差异之外的行。
• 不要发布拉取请求中已有的问题。
• 除非派发任务时要求跳过代码检查，否则不要跳过代码检查；如果任务要求跳过，请在评审正文中说明。
• 不要悄悄跳过意图检查 — 如果没有关联议题，请在评审正文中说明。