review-pr

PR 审查技能

审查当前拉取请求，并将输出写入 review.json。

上下文

• 工作目录是 PR 分支的检出目录。
• 工作流通常会在 pr_diff.txt 中提供带注释的差异。
• 工作流通常会在 pr_description.txt 中提供 PR 描述。
• 如果存在 spec_context.md，其中包含用于验证实现是否符合规范的上下文。
• 当提示词引用 .agents/skills/review-pr/scripts/resolve_spec_context.py 时，请使用该脚本按需生成 spec_context.md，而不是期待提示词中已嵌入规范内容。
• 重点关注此 PR 更改的文件和行。
• 不要直接向 GitHub 发布评论或审查意见。

审查范围

• 优先关注正确性、安全性、错误处理和有实际意义的性能问题。
• 与这些问题同等优先地审查注释质量和测试质量；它们并非只有时间充裕时才需要提及的可选小问题。定稿前，请根据仓库自身的惯例检查这两项。
• 如果使用仓库提供了本地的 security-review-pr 配套技能，或提示词要求进行安全审查，请将其作为代码 PR 的补充指南，并将所有安全问题纳入同一份 review.json，不要单独输出。
• 如果存在 spec_context.md，且仓库提供本地的 check-impl-against-spec 技能，请使用该技能，并将实质性偏离规范的问题视为审查关注点。
• 只有在能提供具体建议代码块时，才评论风格或细节问题。
• 如果问题涉及未修改的代码，请在顶层 body 中提及，而不要添加行内评论。
• 如果现有测试已覆盖有意义的行为，不要建议添加仅变更构造函数输入或结构体字段的测试。只有新测试能覆盖不同的代码路径或边界情况时，才建议添加。
• 如果 PR 明显属于 V0 或初始实现，除非超时、重试、生命周期管理方面的问题会影响正确性、安全性或导致数据丢失，否则应将这些健壮性建议作为可选的后续工作，而非阻塞性问题。

仓库特定指南

开始审查前，请主动检查使用此技能的仓库是否提供了专门针对其惯例的配套 review-pr-local 技能：如果提示词指明了技能位置，请到该位置阅读；否则请在仓库中查找（例如 .agents/skills/review-pr-local/SKILL.md，但仓库可能使用不同的路径或名称）。如果存在配套技能，请阅读并在审查中遵循其指南。如果无论如何都没有找到，则仅依据核心约定进行审查。

配套技能应根据仓库自身的惯例，细化此技能的评论和测试指南。但它绝不能更改其他部分中规定的输出 JSON 架构、严重性标签、安全规则、证据规则、建议代码块约束或差异行注释约定。

差异行注释

差异文件使用以下前缀：

• [OLD:n] 表示旧版本中删除的行。使用 "LEFT"。
• [NEW:n] 表示新版本中新增的行。使用 "RIGHT"。
• [OLD:n,NEW:m] 表示未更改的上下文行。使用 "RIGHT"，行号为 m。

将这些注释视为行内评论位置的唯一依据。每条行内评论发出前，先在 pr_diff.txt（或内嵌的 PR 差异）中找到确切的带注释行，并将其路径、侧别和行号复制到 review.json。不要根据文字说明、GitHub 渲染视图、文件长度、周边规范文本或未标注的代码片段推断行号。如果无法指向具体的 [NEW:n]、[OLD:n] 或 [OLD:n,NEW:m] 行，请将反馈写入顶层 body，而不要添加行内评论。

评论要求

每条评论正文都必须以以下标签之一开头：

• 🚨 [CRITICAL] 用于错误、安全问题、崩溃或数据丢失。
• ⚠️ [IMPORTANT] 用于逻辑问题、边缘情况或缺少错误处理。
• 💡 [SUGGESTION] 用于值得采纳的改进或更好的模式。
• 🧹 [NIT] 仅当评论包含建议块时用于清理类问题。

确认违反仓库评论或测试指南的情况，可以单独使用 ⚠️ [IMPORTANT]——无论 PR 的其他部分多么完善。不要仅仅因为周边代码看起来不错，就默认将这类问题标为 🧹 [NIT]/💡 [SUGGESTION]。

撰写评论时请遵守以下要求：

• 简洁、直接且可执行。
• 不要添加赞美或模棱两可的措辞。
• 尽量使用单行评论。
• 评论范围最多为 10 行。
• 行内评论仅限于注释所针对的 PR 差异中明确出现的行。
• 仅对存在于此 PR 差异中的文件创建文件级或行内评论。
• 如果相关文件或行不属于差异，请将反馈写入顶层 body，而不是 comments。
• 添加每个评论对象前，请确认其 path、side、line 以及可选的 start_line/start_side 对应于同一文件差异部分中的实际注释位置。

建议块

提出代码更改时，请使用：

<replacement code here>

规则：

• 与原文件的缩进完全一致。
• 仅包含替换代码。
• 块内容将精确替换第 start_line–line 行（含首尾）。块中的每一行都会成为该范围内的新文件内容，GitHub 会保留其他所有行。
• 不要包含该范围之外的行。start_line 上方和 line 下方的行会保留在文件中；如果在建议块中重复这些行，提交建议后它们会出现两次。
• 不要以紧邻 start_line 上方已有的行作为块的开头，也不要以紧邻 line 下方已有的行作为块的结尾。如果需要将这些行用作锚点，请扩大 start_line 或 line，将它们纳入实际替换范围。
• 计算原始替换行与替换内容中的花括号、方括号、圆括号和块分隔符（{、[、(、end 等）的深度，并确保替换内容结束时深度一致。不要输出多余的闭合符号，也不要遗漏必需的符号。
• 不确定周边上下文时，请扩大 start_line/line，纳入足够多的差异中实际存在的行，而不要猜测周边符号。
• 对于多行建议，请将 start_line 和 start_side 设为首行，将 line 和 side 设为末行。

输出格式

创建 review.json，格式如下：

{
  "verdict": "REJECT",
  "body": "## Overview\n...\n\n## Concerns\n- ...\n\n## Verdict\nFound: 1 critical, 2 important, 3 suggestions\n\n**Request changes**",
  "comments": [
    {
      "path": "path/to/file",
      "line": 42,
      "side": "RIGHT",
      "start_line": 40,
      "start_side": "RIGHT",
      "body": "⚠️ [IMPORTANT] Short explanation\n\n```suggestion\nreplacement\n```"
    }
  ]
}

字段规则：

• verdict 为必填项，且必须是字符串 "APPROVE" 或 "REJECT"（大写）。请按以下规则映射最终建议：Approve 或 Approve with nits → "APPROVE"；Request changes → "REJECT"。verdict 必须与顶层 body 中面向读者的建议一致。
• 顶层 body 是必填项，内容为 GitHub 审查正文。请使用 body，而不是 summary，来撰写审查概述和最终建议。
• comments 为必填项，且必须是数组。没有行内评论时，请使用空数组。
• path 必须是相对于仓库根目录的路径。
• line 为必填项，且必须指向正确的一侧。
• start_line 为可选项，仅用于多行范围。存在 start_line 时，必须提供 start_side，且其值必须为 "LEFT" 或 "RIGHT"。
• side 必须为 "LEFT" 或 "RIGHT"。

正文要求

顶层 body 必须包含：

• 对 PR 的高层概述。
• 重要问题，以及无法在行内评论的未触及代码问题。
• 按 Found: X critical, Y important, Z suggestions 格式列出问题数量。
• 最终建议：Approve、Approve with nits 或 Request changes。该建议必须与顶层 verdict 字段一致（Approve / Approve with nits → "APPROVE"；Request changes → "REJECT"）。

裁决前审查

在起草顶层 body 或选择 verdict 之前，先完成这项审查——仅通读整个 diff 并不足够。

• 注释：逐条列出 diff 新增或修改的所有注释（文档注释或行内注释），并注明文件和行号。针对每条注释，分别依据仓库自身的注释规范（无论其形式如何）进行检查；如果仓库没有相关规范，则根据项目现有代码中注释的分布情况（密度、语气，以及现有注释解释和未解释的内容）进行判断。评估是否符合规范时，不考虑注释的写作质量、技术准确性，也不考虑其描述的问题有多微妙或重要：这些因素都不能成为违反适用规范或明显偏离代码库自身惯例的理由。
• 测试：依据仓库自身的测试规范，检查 diff 新增或修改的每项测试。

最终检查

返回或上传 review.json 之前：

• 如果 JSON 验证失败，请修复无效内容。
• 确认行号与已标注的 diff 相符。
• 针对你审查的确切标注版 diff 运行随附的验证器：

  python3 .agents/skills/review-pr/scripts/validate_review_json.py --review-json review.json --diff pr_diff.txt
  

  如果脚本报告任何无效评论，请修复 review.json 并重新运行。验证器通过之前，不要返回或上传 review.json。如果该脚本路径不存在，请在已加载的 review-pr 技能目录下找到 validate_review_json.py，并使用相同参数运行该副本。
• 不要运行 gh pr review、gh pr comment、gh api 或任何其他会向 GitHub 发帖的命令。

你的唯一输出是最终的 review.json。