企业官网建设流程全解析

• AI 应用
• CLI
• 开发工具

导读

在 ccusage 仓库的create-pr技能（skill）所定义的完整 PR 生命周期中，请求 AI 评审、回复评审线程、轮询 CI 是三个密不可分的环节。本文聚焦.agents/skills/create-pr/references/gh-review.md这份参考文档，讲解ghCLI 原生命令（porcelain）覆盖不到的两个关键操作：通过 GitHub REST API 在行内（inline）评审线程中回复，以及通过 GraphQL API 读取线程的解析状态（isResolved），并结合仓库中的create-pr、ai-review、fix-ci技能与 CI 校验脚本，给出可直接复制运行的完整命令与工作流。

一、背景：这份参考文档在 PR 工作流中的位置

ccusage 仓库在.agents/skills/create-pr/SKILL.md中定义了完整的 PR 生命周期技能：开分支、提交、推送、开 PR、请求 AI 评审、回复评审线程、驱动 CI 到全绿并最终合并。其中第 3 步明确写道：

Request and handle AI review —references/ai-review.md, with theghreply and thread-state calls inreferences/gh-review.md.

也就是说，gh-review.md专门提供ai-review.md需要、但gh没有内置命令（no porcelain）的底层 API 调用：

文档原文即声明："gh pr comment,gh pr view --json comments,reviews,statusCheckRollup, andgh pr checkscover requesting review and polling. The calls below are the onesghhas no porcelain for."——这正是这份参考文档的存在理由：补齐 gh 命令行无法直接表达的两个 API 能力。

二、在行内评审线程中回复（REST API）

2.1 为什么需要 REST replies 端点

gh pr comment只能发布顶层评论，无法把回复挂到某条具体的行内评审线程（inline thread，即 diff 上某一行旁边的评论）下面。而当 CodeRabbit（@coderabbitai）或 Cubic（@cubic-dev-ai）在 PR 上留下行内反馈后，按ai-review.md的约定，处理完每条 actionable 反馈需要在原线程内回复，并且回复要以 bot 的 mention 开头，说明改了什么、跑了哪些验证。

2.2 完整调用链

第一步，拿到目标行内评论的 id。gh pr comment只发顶层评论，所以要查询该 PR 的所有行内评论，找到 bot 打开的那条线程对应的 comment id：

gh api repos/:owner/:repo/pulls/<pr-number>/comments

第二步，用 REST replies 端点把回复挂进这条线程：

gh api -X POST repos/:owner/:repo/pulls/<pr-number>/comments/<comment-id>/replies \ -f body='@coderabbitai Fixed in <commit-sha>. Validation: just typecheck, just test.'

这是gh-review.md原文给出的命令。几个要点：

• :owner与:repo由gh自动替换为当前仓库；<pr-number>与<comment-id>需要替换为实际值。
• -f body=...以表单字段方式提交正文，gh api会负责正确的编码；正文中的@coderabbitaimention 是让 bot 重新行动的触发条件。
• 文档特别说明："Reviewer handles are examples; use the ones current on the PR."——即示例中的 handle 是占位符，应以该 PR 上实际出现的评审者为准（例如 Cubic 在不同仓库可能使用不同的 handle）。

2.3 在仓库工作流中的语义

结合.agents/skills/create-pr/references/ai-review.md，回复线程的完整流程是：

1. 开 PR 后发一条顶层评论 mention bot 请求评审；
2. 每次有意义的新推送后再次 mention 相关 bot；
3. 若 bot 没有自动重新运行，则重复请求；
4. 轮询评论、评审与行内线程（gh pr view --json comments,reviews,statusCheckRollup+gh pr checks），把每条反馈分类为 actionable / question / false positive / informational；
5. 对每条 actionable 反馈做最小修复、跑相关检查、通过commit技能提交推送，然后在对应线程内回复——开头 mention bot，说明变更内容与通过的验证。

gh-review.md中的这条 REST 命令正是第 5 步的执行载体。

三、读取线程解析状态（GraphQL）

3.1 为什么只能走 GraphQL

行内线程的"已解析/未解析"状态（isResolved）是 GitHub 的GraphQL-only字段，REST API 与 gh 内置命令都无法直接读取。gh-review.md因此提供了reviewThreads查询。在判断 PR 是否真正"ready"时，这个状态至关重要：create-pr技能的 "Ready means" 一节要求"no unresolved actionable feedback"，而线程是否被解析正是判断依据之一。

3.2 查询命令

gh api graphql \ -F owner='OWNER' \ -F repo='REPO' \ -F number=<pr-number> \ -f query=' query($owner: String!, $repo: String!, $number: Int!) { repository(owner: $owner, name: $repo) { pullRequest(number: $number) { reviewThreads(first: 100) { nodes { id isResolved comments(first: 20) { nodes { id databaseId author { login } path body } } } } } } }'

要点说明：

• -F owner='OWNER' -F repo='REPO'用变量形式传入 GraphQL 变量；-F number=<pr-number>中number会被gh api graphql按 GraphQL 的Int!类型自动序列化。
• reviewThreads(first: 100)只返回前 100 条线程；文档明确指出："addpageInfoandafterpagination for large PRs"——大型 PR 需要自行追加pageInfo（hasNextPage/endCursor）并在下一次查询中传入after游标完成分页。
• comments(first: 20)限制每条线程最多取 20 条评论，返回databaseId（REST 体系中的数字 ID）便于与 REST 的 replies 端点衔接——即先查 GraphQL 拿线程与评论结构，再用 REST 的 comment id 去回复。

3.3 与 REST 查询的配合

实际轮询时可以先用 REST 接口获取行内评论列表（含每条评论的id），再用 GraphQL 查询拿到线程级isResolved状态与评论归属（author.login、path、body）。两者组合即可回答ai-review.md要求的"poll comments, reviews, and inline threads before calling the PR ready"。

四、围绕评审循环的完整命令集

把gh-review.md放入create-pr技能的完整上下文后，一次典型 PR 评审循环涉及以下命令（路径见 create-pr 技能 与 fix-ci 技能）：

五、为什么 PR 标题与正文同样受校验约束

gh-review.md讲的是"评审后处理"，而评审的对象——PR 本身——在本仓库有严格的形状约束，理解这一点有助于把回复内容写得更贴合仓库约定。依据 open-pr.md：

• 本仓库采用squash merge，PR 标题会直接成为main分支上的提交 subject，因此标题必须按 Conventional Commit 书写；
• check-pr-title.yaml 校验标题的 Conventional Commit 形状，并针对 PR diff 重新运行 scripts/validate-commit-scope.nu（该脚本同时被 commit-msg hook 用于本地提交，两者保持同步）；
• 从 scripts/validate-commit-scope.nu 源码可见，scope 命名的是"发生变更的 agent"而非目录（如feat(codex)、fix(kimi)），跨切面 scope 为deps、release、pricing、revert，跨多 agent 的工作区 scope 为adapter、all、rust。

因此评审回复中若提到"Validation: just typecheck, just test"，对应的是仓库 justfile 中的校验配方（如just check、just rust::test、just test-node，映射关系见 fix-ci 技能 中的表格）。

六、实操注意事项

1. handle 以 PR 实况为准：gh-review.md与ai-review.md都强调评审者 handle 只是示例（Cubic 的 GitHub 用户是cubic.dev，但也可能使用 PR 中出现的其他 handle），复制命令时必须替换为当前 PR 上的真实值。
2. 分页勿遗漏：reviewThreads(first: 100)在大型 PR 上会截断，务必补充pageInfo/after游标分页，否则可能漏掉未解析线程，误判 PR ready。
3. bot 只在被 mention 时行动：create-pr技能的 Context 一节明确——bot 只有在 handle 被提及时才会响应，初次请求和每次要求其做事的回复都要 mention。
4. 沉默不等于完成：当 bot 或 CI 在合理轮询窗口内保持沉默，要如实说明 pending 状态，而不是声称完成。
5. 谨慎 force-push：评审者已阅读 PR 后，amend 或 force-push 需要用户明确要求。
6. 合并前确认条件：分支已推送、PR 存在、CodeRabbit（以及可用时的 Cubic）已评审最新提交且无未解决 actionable 反馈、所有必需检查通过，且用户明确要求合并——缺一不可。

结语

gh-review.md虽短，却是 ccusage 仓库 AI 评审闭环中不可替代的一环：它补上了ghCLI 的两个能力缺口——REST 层级的行内线程回复与 GraphQL 层级的线程解析状态查询。配合 ai-review.md 的分类与回复策略、open-pr.md 的标题与正文规范、fix-ci 的 CI 修复流程，即可在任意 PR 上完整复现本仓库的评审循环。上述命令全部基于官方gh api/gh api graphql，在任何使用 GitHub 的项目中均可直接迁移使用。

• AI 应用
• CLI
• 开发工具