mc-skills/catalog

Fork 0

mc-skills 52efc07510 catalog: 更新 2026-04-07 11:44

2026-04-07 11:44:56 +08:00

9.3 KiB

Raw Permalink Blame History

GitHub PR 代码审查工具

GitHub CLI 代码审查 GraphQL Pull Request

gh-pr-review

gh-pr-review 是一个预编译的 GitHub CLI 扩展，专为高效的 Pull Request 审查而设计。它管理待处理的 GraphQL 审查、展示线程元数据，并可在不克隆仓库的情况下解决讨论。

快速入门
审查视图
后端策略
其他文档
1.6.0 版本发布

快速入门

从打开待处理审查到解决线程的最快路径：

安装或升级扩展。

gh extension install Agyn-sandbox/gh-pr-review
# 更新已有安装
gh extension upgrade Agyn-sandbox/gh-pr-review

创建待处理审查（GraphQL）。 记录返回的 id（GraphQL 节点）。
```
gh pr-review review --start -R owner/repo 42

{
  "id": "PRR_kwDOAAABbcdEFG12",
  "state": "PENDING"
}
```
待处理审查不包含 submitted_at 字段；该字段在提交后才会出现。

使用待处理审查 ID 添加内联评论（GraphQL）。 如果提供的是数字 ID 而非所需的 PRR_… GraphQL 标识符，review --add-comment 命令会快速失败。

gh pr-review review --add-comment \
  --review-id PRR_kwDOAAABbcdEFG12 \
  --path internal/service.go \
  --line 42 \
  --body "nit: 使用辅助函数" \
  -R owner/repo 42

{
  "id": "PRRT_kwDOAAABbcdEFG12",
  "path": "internal/service.go",
  "is_outdated": false,
  "line": 42
}

查看审查线程（GraphQL）。 review view 显示待处理审查摘要、线程状态和内联评论元数据。始终包含线程 ID；当需要单独的评论节点标识符时，启用 --include-comment-node-id。

gh pr-review review view --reviewer octocat -R owner/repo 42

{
  "reviews": [
    {
      "id": "PRR_kwDOAAABbcdEFG12",
      "state": "COMMENTED",
      "comments": [
        {
          "thread_id": "PRRT_kwDOAAABbcdEFG12",
          "path": "internal/service.go",
          "body": "nit: 建议使用辅助函数",
          "is_resolved": false,
          "is_outdated": false,
          "thread": []
        }
      ]
    }
  ]
}

使用 thread_id 值配合 comments reply 继续讨论。如果在自己的待处理审查中回复，请通过 --review-id 传入关联的 PRR_… 标识符。

gh pr-review comments reply \
  --thread-id PRRT_kwDOAAABbcdEFG12 \
  --body "已在提交 abc123 中处理后续问题" \
  -R owner/repo 42

提交审查（GraphQL）。 最终确认时复用待处理审查的 PRR_… 标识符。成功提交后返回仅含状态的响应。GraphQL 级别的错误以结构化 JSON 形式返回，便于排查。

gh pr-review review --submit \
  --review-id PRR_kwDOAAABbcdEFG12 \
  --event REQUEST_CHANGES \
  --body "请添加测试" \
  -R owner/repo 42

{
  "status": "Review submitted successfully"
}

GraphQL 错误时，命令输出以下内容后以非零状态退出：

{
  "status": "Review submission failed",
  "errors": [
    { "message": "mutation failed", "path": ["mutation", "submitPullRequestReview"] }
  ]
}

查看并解决线程（GraphQL）。 当没有匹配线程时，数组响应始终为 []。

gh pr-review threads list --unresolved --mine -R owner/repo 42

[
  {
    "threadId": "R_ywDoABC123",
    "isResolved": false,
    "path": "internal/service.go",
    "line": 42,
    "isOutdated": false
  }
]

gh pr-review threads resolve --thread-id R_ywDoABC123 -R owner/repo 42

{
  "thread_node_id": "R_ywDoABC123",
  "is_resolved": true
}

审查视图

gh pr-review review view 输出 Pull Request 讨论的 GraphQL 快照。响应按"审查 → 父内联评论 → 线程回复"分组，省略可选字段而非返回 null。

使用组合选择器或显式标志运行：

gh pr-review review view -R owner/repo --pr 3

安装或升级至 v1.6.0 或更新版本（仅 GraphQL 线程解析和最简评论回复）：

gh extension install Agyn-sandbox/gh-pr-review
# 更新已有安装
gh extension upgrade Agyn-sandbox/gh-pr-review

命令行为

每次调用仅执行单个 GraphQL 操作（不混用 REST）。
默认包含所有审查者、审查状态和线程。
回复按 created_at 升序排列。
输出仅暴露 author_login，不含用户对象或 html_url 字段。
可选字段（body、submitted_at、line、thread）为空时省略；空回复列表渲染为 "thread": []。

过滤器

标志	用途
`--reviewer <login>`	仅包含由 `<login>` 撰写的审查（大小写不敏感）。
`--states <list>`	逗号分隔的审查状态（`APPROVED`、`CHANGES_REQUESTED`、`COMMENTED`、`DISMISSED`）。
`--unresolved`	仅保留未解决的线程。
`--not_outdated`	排除标记为过期的线程。
`--tail <n>`	每个线程仅保留最后 `n` 条回复（0 = 全部）。父内联评论始终保留，仅裁剪回复。
`--include-comment-node-id`	为父评论和回复添加 GraphQL 评论节点标识符。

示例

# 默认：返回所有审查、状态、线程
gh pr-review review view -R owner/repo --pr 3

# 仅显示未解决的线程
gh pr-review review view -R owner/repo --pr 3 --unresolved

# 聚焦单个审查者的变更请求；每个线程仅保留最新回复
gh pr-review review view -R owner/repo --pr 3 --reviewer alice --states CHANGES_REQUESTED --tail 1

# 排除过期线程并包含评论节点 ID
gh pr-review review view -R owner/repo --pr 3 --not_outdated --include-comment-node-id

输出结构

{
  "reviews": [
    {
      "id": "PRR_…",
      "state": "APPROVED|CHANGES_REQUESTED|COMMENTED|DISMISSED",
      "author_login": "…",
      "body": "…",          // 为空时省略
      "submitted_at": "…",   // 不存在时省略
      "comments": [           // 无评论时省略
        {
          "thread_id": "PRRT_…",
          "comment_node_id": "PRRC_…",  // 未请求时省略
          "path": "…",
          "line": 21,         // 为 null 时省略
          "author_login": "…",
          "body": "…",
          "created_at": "…",
          "is_resolved": true,
          "is_outdated": false,
          "thread": [         // 仅回复；升序排列；tail 生效
            {
              "comment_node_id": "PRRC_…",  // 未请求时省略
              "author_login": "…",
              "body": "…",
              "created_at": "…"
            }
          ]
        }
      ]
    }
  ]
}

回复线程

在回复时使用报告中显示的 thread_id 值。在继续自己拥有的待处理审查时，同时提供 --review-id 和 --thread-id。

gh pr-review comments reply -R owner/repo --pr 3 \
  --thread-id PRRT_kwDOAAABbcdEFG12 \
  --body "已在提交 abc123 中处理后续问题"

gh pr-review comments reply -R owner/repo --pr 3 \
  --thread-id PRRT_kwDOAAABbcdEFG12 \
  --review-id PRR_kwDOAAABbcdEFG12 \
  --body "来自待处理审查的回复"

后端策略

每个命令绑定到单一的 GitHub 后端，没有运行时回退。

命令	后端	说明
`review --start`	GraphQL	通过 `addPullRequestReview` 开启待处理审查。
`review --add-comment`	GraphQL	需要 `PRR_…` 审查节点 ID。
`review view`	GraphQL	聚合审查、内联评论和回复（用于获取线程 ID）。
`review --submit`	GraphQL	通过 `submitPullRequestReview` 使用 `PRR_…` 审查节点 ID 完成待处理审查（通过内部 `gh api graphql` 包装器执行）。
`comments reply`	GraphQL	通过 `addPullRequestReviewThreadReply` 回复；在待处理审查中回复时提供 `--review-id`。
`threads list`	GraphQL	枚举 Pull Request 的审查线程。
`threads resolve` / `unresolve`	GraphQL	通过 `resolveReviewThread` / `unresolveReviewThread` 变更线程解析状态；提供 GraphQL 线程节点 ID（`PRRT_…`）。

其他文档

docs/USAGE.md — v1.6.0 各命令的输入、输出和示例。
docs/SCHEMAS.md — 每种结构化响应的 JSON 结构（可选字段省略而非设为 null）。
docs/AGENTS.md — 面向 Agent 的工作流、提示词和最佳实践。

设计说明

每个命令绑定到恰好一个 GitHub 后端：审查视图仅使用 GraphQL，评论列表/回复同样仅使用 GraphQL。可选的 REST 查询仅在转换旧版 ID 时出现。
可选字段完全省略，从不用空字符串或 null 占位填充。
输出针对无头环境和 LLM 工作流优化（稳定排序、最少修饰、机器友好的 JSON）。

开发

在本地运行测试套件和代码检查工具，禁用 cgo（与发布构建保持一致）：

CGO_ENABLED=0 go test ./...
CGO_ENABLED=0 golangci-lint run

发布版本使用 cli/gh-extension-precompile 工作流构建，为 macOS、Linux 和 Windows 发布二进制文件。

9.3 KiB Raw Permalink Blame History Unescape Escape