gh-pr-review

gh-pr-review

一个 GitHub CLI 扩展，可在终端中完整访问 PR 内联审查评论，并输出适合大模型处理的 JSON。

适用场景

在以下情况下使用此工具：

• 查看拉取请求中的内联审查评论和讨论串
• 以编程方式回复审查评论
• 解决或取消解决审查讨论串
• 创建并提交带有内联评论的 PR 审查
• 获取自动化工作流所需的 PR 审查上下文
• 按状态、审查者或解决状态筛选审查

此工具尤其适用于：

• 自动化 PR 审查工作流
• 基于大模型的代码审查 Agent
• 基于终端的 PR 审查流程
• 无需多次 API 调用即可获取结构化审查数据

安装

首先，确保已安装此扩展：

gh extension install agynio/gh-pr-review

核心命令

1. 查看所有审查和讨论串

获取包含内联评论和讨论串回复的完整审查上下文：

gh pr-review review view -R owner/repo --pr <number>

实用筛选项：

• --unresolved - 仅显示未解决的讨论串
• --reviewer <login> - 按指定审查者筛选
• --states <APPROVED|CHANGES_REQUESTED|COMMENTED|DISMISSED> - 按审查状态筛选
• --tail <n> - 每个讨论串仅保留最后 n 条回复
• --not_outdated - 排除已过时的讨论串

**输出：**包含审查、评论、thread_ids 和解决状态的结构化 JSON。

2. 回复审查讨论串

回复现有的内联评论讨论串：

gh pr-review comments reply <pr-number> -R owner/repo \
  --thread-id <PRRT_...> \
  --body "Your reply message"

3. 列出审查讨论串

获取筛选后的审查讨论串列表：

gh pr-review threads list -R owner/repo <pr-number> --unresolved --mine

4. 解决/取消解决讨论串

将讨论串标记为已解决：

gh pr-review threads resolve -R owner/repo <pr-number> --thread-id <PRRT_...>

5. 创建并提交审查

开始一项待处理的审查：

gh pr-review review --start -R owner/repo <pr-number>

向待处理的审查添加内联评论：

gh pr-review review --add-comment \
  --review-id <PRR_...> \
  --path <file-path> \
  --line <line-number> \
  --body "Your comment" \
  -R owner/repo <pr-number>

提交审查：

gh pr-review review --submit \
  --review-id <PRR_...> \
  --event <APPROVE|REQUEST_CHANGES|COMMENT> \
  --body "Overall review summary" \
  -R owner/repo <pr-number>

输出格式

所有命令都会返回针对编程使用优化的结构化 JSON：

• 字段名称一致
• 顺序稳定
• 省略字段，而不是使用 null 值
• 仅包含必要数据（不含 URL 或冗余元数据）
• 预先合并的讨论串回复

输出结构示例：

{
  "reviews": [
    {
      "id": "PRR_...",
      "state": "CHANGES_REQUESTED",
      "author_login": "reviewer",
      "comments": [
        {
          "thread_id": "PRRT_...",
          "path": "src/file.go",
          "author_login": "reviewer",
          "body": "Consider refactoring this",
          "created_at": "2024-01-15T10:30:00Z",
          "is_resolved": false,
          "is_outdated": false,
          "thread_comments": [
            {
              "author_login": "author",
              "body": "Good point, will fix",
              "created_at": "2024-01-15T11:00:00Z"
            }
          ]
        }
      ]
    }
  ]
}

最佳实践

1. 始终使用 -R owner/repo 明确指定仓库
2. 使用 --unresolved 和 --not_outdated 聚焦于可采取行动的评论
3. 保存 review view 输出中的 thread_id 值，以便回复
4. 在处理特定审查反馈时按审查者筛选
5. 使用 --tail 1 仅保留最新回复，以减少输出大小
6. 解析 JSON 输出，不要尝试从文本中抓取信息

常见工作流

获取当前 PR 的未解决评论

gh pr-review review view --unresolved --not_outdated -R owner/repo --pr $(gh pr view --json number -q .number)

回复所有未解决的评论

1. 获取未解决的讨论串：gh pr-review threads list --unresolved -R owner/repo <pr>
2. 对每个 thread_id 进行回复：gh pr-review comments reply <pr> -R owner/repo --thread-id <id> --body "..."
3. 可选：解决讨论串：gh pr-review threads resolve <pr> -R owner/repo --thread-id <id>

创建带有内联评论的审查

1. 开始：gh pr-review review --start -R owner/repo <pr>
2. 添加评论：gh pr-review review --add-comment -R owner/repo <pr> --review-id <PRR_...> --path <file> --line <num> --body "..."
3. 提交：gh pr-review review --submit -R owner/repo <pr> --review-id <PRR_...> --event REQUEST_CHANGES --body "Summary"

重要说明

• 所有 ID 均使用 GraphQL 格式（审查使用 PRR_...，讨论串使用 PRRT_...）
• 命令仅使用 GraphQL（不回退到 REST API）
• 如果没有数据符合筛选条件，则返回空数组 []
• 需要时，--include-comment-node-id 标志会添加 PRRC_... ID
• 讨论串回复按 created_at 升序排列

文档链接

• 使用指南：docs/USAGE.md
• JSON 架构：docs/SCHEMAS.md
• Agent 工作流：docs/AGENTS.md
• 博客文章：https://agyn.io/blog/gh-pr-review-cli-agent-workflows