git-pr

PR 和 MR 工作流

GitHub 和 GitLab 拉取请求与合并请求工作流的主要技能。 涵盖完整生命周期：创建、查询评审、处理评论、添加特定行评论以及合并。所有操作示例都使用最少字段集，以提高令牌效率。

已针对 gh v2.102.0 进行验证（2026-09-30）：已根据对应的 --help 验证本文使用的每个 gh 子命令和标志。glab：未经验证——目前尚无固定版本；依赖某个 glab 标志前，请先查看 glab <cmd> --help。如果 gh --version 显示的版本比本文所述版本更新，请先阅读自 v2.102.0 以来的发布说明，再依赖相关标志的详细信息。CodeRabbit CLI 的固定版本位于 coderabbit 技能中。

上下文检查（先执行此步骤）

开始任何 PR 工作流之前，先检测当前状态。这将决定应采取的操作：

# Check if a PR exists for the current branch (allowlisted, zero approval)
gh pr view --json number,state,reviewDecision,reviewRequests,title 2>/dev/null

结果	后续操作
PR 已存在，状态为 CHANGES_REQUESTED	获取尚未解决的讨论串（参见“评审评论处理”）
PR 已存在，状态为 REVIEW_REQUIRED 或有待处理的 reviewRequests	检查评审状态或等待评审者
PR 已存在，机器人评审正在进行：REST 中的 requested_reviewers 仍有待处理请求（Copilot 显示为 Copilot），或 HEAD 的 CodeRabbit 状态显示 Review in progress	自动评审正在进行——按照托管平台允许的方式等待（关键规则 9）；不要重新请求
PR 已存在，仍有未解决的评审评论	先处理这些评论（参见“评审评论处理”）；有未解决评论时，绝不要请求新的评审
PR 已存在，状态为 APPROVED	检查 CI 状态或继续合并
PR 已存在，尚无评审决定	对于自动评审仓库，先查看机器人评审轮次的结果（bot_status，“机器人评审循环”）——如果该轮评审结果正常或遇到速率限制，此查询不会显示任何内容；然后检查 CI 状态、评审状态，或推送更多更改
当前分支没有 PR	创建 PR（参见“PR/MR 创建”）

这样可以避免在 PR 已存在时仍提议创建 PR，并立即发现待处理的评审工作。reviewDecision 字段可以可靠地指示评审者是否要求更改，无需获取各个讨论串。

自动评审是可选设置——绝不要假定它启用或未启用（GitHub）： 自动 Copilot 代码评审由仓库/组织的 ruleset 或作者的个人 Copilot 设置触发，因此不同账号、组织，甚至同一所有者的不同仓库，情况都可能不同。启用后，系统会在创建每个非草稿 PR 时请求 Copilot 评审（将草稿标记为准备好评审时也会请求），因此刚创建的 PR 可能已经有待处理的机器人请求，或几分钟后就出现机器人评论——而在其他仓库中则完全不会触发。ruleset 来源可通过只读方式检测（通过 gh api repos/{owner}/{repo}/rules/branches/{branch} 查询 copilot_code_review 规则；参见 references/copilot-review-config.md），但个人设置没有 API——因此，即使 ruleset 检查结果为空，也仍应检测而非假定：先检查是否有待处理的请求或现有机器人评审，只有两者都不存在时才请求评审；否则会产生重复评审轮次。**注意：**待处理的机器人请求只能通过 gh api repos/{owner}/{repo}/pulls/{n}/requested_reviewers 查看（登录名为 Copilot）——gh pr view --json reviewRequests 不会显示机器人评审者，结果始终为空。

机器人评审会产生费用（Copilot）或消耗配额（CodeRabbit）——请有计划地安排评审轮次。 每次 Copilot 评审（包括每次重新请求）都会全额计费：旧版年度方案每次评审消耗 13 个高级请求（Pro 每月最多约 23 次评审——所有高级功能共享该额度），当前方案则按令牌计量 AI 点数并消耗 Actions 分钟数。CodeRabbit PR 评审会消耗按方案划分的每小时额度，额度按开发者而非 PR 计算——开发者所有开放 PR 都会争用相同的评审时段。请求任何收费评审之前，请先查看项目的代码评审策略（见下文）；建议先使用本地 CodeRabbit CLI 评审（参见 coderabbit 技能），以较低成本迭代，然后再请求 PR 侧评审。

使用场景

• 创建 PR 或 MR —— 工作流草案、填写模式、标题格式
• 处理 PR/MR 审查反馈 ——“修复 PR 评论”“处理审查意见”“处理反馈”“解决审查讨论串”
• 回应代码审查 —— 评估审查者的评论、回复、解决讨论串
• 检查审查状态 —— 批准情况、待处理的审查者、审查决定
• 查询 PR/MR 数据 —— 变更的文件、提交、标签、关联的问题
• 在 PR/MR 上发表评论 —— 针对特定行的评论、讨论串回复
• 循环进行机器人审查轮次（仅限 GitHub；Copilot、CodeRabbit）——重新请求机器人审查，等待异步审查，处理评论，重复以上步骤，直到没有有效评论为止（“循环进行 Copilot 审查”“循环 3 轮”）
• 配置 Copilot 代码审查 ——自动审查规则集、审查力度、自定义指令、计费/额度检查
• 配置工具允许列表 ——只读命令的自动批准模式

关键规则

1. 优先使用 CLI 子命令，而不是直接调用 API。 子命令会处理分页、错误格式化和仓库检测。只有子命令不支持的操作（行内评论、解决讨论串、GraphQL）才使用 gh api / glab api。
2. 使用 gh 时，通过 --json field1,field2 筛选输出。 这就是提高效率的机制——基本查询不需要 --jq。只请求实际需要的字段。
3. glab 没有与 --json field1,field2 等效的选项。 使用 -F json | jq '{fields}' 筛选输出，以节省令牌。
4. 严格按照本技能中展示的命令使用。 以下命令经过设计，可匹配自动批准的允许列表模式。自行调整标志顺序或添加意料之外的标志，可能会触发权限提示。
5. 只推送已完成的工作——每轮推送一次。 自动审查和 auto_incremental_review 开启时（默认均开启），git push 就是审查请求，审查会针对分支在当时的内容进行。先完成本轮的所有任务——完成所有修复、测试、文档和本地检查（coderabbit review --committed）并提交所有内容，然后再推送一次。推送进度会把稀缺的每位开发者审查时段耗费在你本来就打算修改的代码上。更改仍在进行时，让 PR 保持为草稿（草稿不会自动审查，因此推送不会消耗审查时段）；将其标记为就绪才会发起审查。完整流程见：references/bot-review-loop.md（每轮推送一次）。
6. 只有处理完仅存在于审查正文中的问题，审查才算完成。 从未形成讨论串的机器人问题（CodeRabbit 的 nitpick、差异范围外问题、重复问题和发布失败问题）会留在审查正文中，讨论串查询无法看到它们——也要对这些问题进行分类处理，并核对声称的评论数，之后才能宣布本轮完成。
7. 机器人检查通过不代表审查已完成。 CodeRabbit 会将每轮结果记录为提交状态，无论审查结果如何，该状态都会是 success——结果只显示在 description 中（Review completed 与 Review rate limited）。遇到速率限制时，通常不会发布任何其他内容：没有审查、没有讨论串，也没有评论。报告 PR 已审查之前，请使用 gh pr checks --json name,state,bucket,description 读取该状态（默认不会返回此字段，而且 gh pr view --json statusCheckRollup 会完全丢弃该字段）。
8. 本地 CodeRabbit 命令必须严格使用 coderabbit review --committed --base {base}，需要输出 JSON 行时再加上 --agent。 默认输出纯文本——绝不要传入 --plain：CLI v0.7 到 v0.9.0 会拒绝该参数（error: unknown option），v0.9.1 则再次接受它，但它只是隐藏的无操作参数。--type <scope> 并未移除，只是隐藏：它仍会启动审查，但与 --committed 一起使用会失败。不要凭记忆臆造输出或范围标志：coderabbit 技能定义了 CLI 的可用选项。v0.7 中，错误标志会打印用法文本并以退出码 0 结束，因此读取输出末尾内容的包装程序会将其误判为审查通过（v0.8 的退出码为 1）。
9. 轮到你操作结束时，绝不能让机器人审查仍在进行，却没有后续处理方式。 自动审查仓库中的非草稿 PR 创建时就会启动一轮审查；请根据托管环境支持的方式等待审查结果。如果允许轮询，请运行 bot_tick 循环。如果托管环境禁止自行轮询，但提供 PR 监视器（Claude Code 桌面应用：Auto-fix），请让用户启用它，并说明它可能遗漏的情况：CodeRabbit 审查通过时不会发布审查评论；遇到速率限制时，只会将 CodeRabbit 状态描述更改为 Review rate limited，因此监视器可能永远不会唤醒会话——之后用户需要重新调用 /git-pr，由它读取本轮结果。如果两者都不具备，请明确说明本轮仍在等待处理，并告知用户结果出来后重新调用 /git-pr 即可处理。详情见：references/bot-review-loop.md（等待正在进行的审查轮次）。

---

提供方检测

git remote get-url origin

远程 URL 包含	提供方	CLI	PR 术语
github.com	GitHub	gh	PR
gitlab.com 或自托管 GitLab	GitLab	glab	MR

如果存在歧义或两者都出现，请询问用户。

glab 操作指南遵循 GitLab 文档，未在实际实例上进行测试——GitHub 的操作指南则经过测试。GitLab 侧的标志和 JSON 结构请视为有文档记载但未经验证：在无人值守的工作流中依赖它们之前，请先检查 glab <command> --help，并优先使用 -F json | jq，不要假设某个字段一定存在。

---

只读与写入分类

• 只读（可安全地自动批准）：view、list、status、diff、checks、search
• 写入（需要用户批准）：create、edit、merge、close、reopen、comment、review、approve

参考：分层自动批准模式请参阅 references/allowlist.md。

---

PR/MR 摘要（当前分支）

GitHub：

gh pr view --json number,title,state,isDraft,reviewDecision,mergeable,baseRefName,headRefName

GitLab：

glab mr view -F json | jq '{iid:.iid,title:.title,state:.state,draft:.draft,merge_status:.merge_status,target:.target_branch,source:.source_branch}'

PR/MR 摘要（按编号）

GitHub：

gh pr view {number} --json number,title,state,isDraft,reviewDecision,mergeable,baseRefName,headRefName

GitLab：

glab mr view {iid} -F json | jq '{iid:.iid,title:.title,state:.state,draft:.draft,merge_status:.merge_status,target:.target_branch,source:.source_branch}'

审查状态

参考：高级审查查询（按审查者查看状态、批准检查、待审查者）请参阅 references/review-queries.md。

GitHub：

gh pr view --json reviews,reviewRequests,latestReviews

GitLab：

glab mr view -F json | jq '{upvotes:.upvotes,reviewers:[.reviewers[]?.username]}'

详细的批准信息（GitLab）：

glab api projects/{project_id}/merge_requests/{iid}/approvals | jq '{approved:.approved,approvers:[.approved_by[]?.user.username]}'

更改的文件

GitHub：

gh pr diff --name-only

GitLab：

glab mr diff

文件统计

GitHub：

gh pr view --json files

GitLab：

glab api projects/{project_id}/merge_requests/{iid}/changes | jq '[.changes[] | {path:.new_path,added:.diff | split("\n") | map(select(startswith("+"))) | length,removed:.diff | split("\n") | map(select(startswith("-"))) | length}]'

列出未关闭的 PR/MR

GitHub：

gh pr list --json number,title,author,reviewDecision,updatedAt

GitLab：

glab mr list -F json | jq '[.[] | {iid:.iid,title:.title,author:.author.username,updated:.updated_at}]'

PR/MR 提交

GitHub：

gh pr view --json commits

GitLab：

glab api projects/{project_id}/merge_requests/{iid}/commits | jq '[.[] | {sha:.short_id,title:.title}]'

搜索 PR/MR

GitHub：

gh pr list --search "review-requested:@me" --json number,title,url

GitLab：

glab mr list --reviewer=@me -F json | jq '[.[] | {iid:.iid,title:.title,url:.web_url}]'

---

创建 PR/MR（写入——手动批准）

操作	GitHub	GitLab
创建草稿	gh pr create --draft --fill	glab mr create --draft --fill
创建并指定标题	gh pr create --title "feat: ..." --body "..."	glab mr create --title "feat: ..." --description "..."
创建并请求 Copilot 审查	gh pr create --title "..." --body "..." --reviewer @copilot (gh >= 2.88)	n/a

**正文应简洁。**标题遵循 Conventional Commits（git-commit skill）；正文用几句话或简练的要点说明更改内容和原因——不要重述差异，也不要添加仓库 PR 模板要求之外的套话章节。

创建非草稿 GitHub PR 后，在请求任何机器人审查之前，先检查 gh api repos/{owner}/{repo}/pulls/{n}/requested_reviewers——已启用自动 Copilot 审查的仓库已经有一个审查正在进行（且不会显示在 gh pr view --json reviewRequests 中）。如果你确定仓库没有自动审查，请跳过创建后再编辑的往返操作，在创建时使用 --reviewer @copilot 请求 Copilot 审查；不确定时，正常创建，并由检测结果决定。

**创建后已有审查正在进行时，下一步应是等待审查，而不是结束本轮。**CodeRabbit 会在 HEAD 的 CodeRabbit 状态中显示 Review in progress（bot_requested 会检查这两个位置）。按照托管平台允许的方式等待（关键规则 9）——使用 PR 监控器，且不要自行轮询；报告新 PR 的消息应提示用户启用监控器。

合并（写入 -- 手动审批）

操作	GitHub	GitLab
Squash 合并	gh pr merge --squash --delete-branch	glab mr merge --squash --remove-source-branch
Rebase 合并	gh pr merge --rebase --delete-branch	glab mr merge --rebase --remove-source-branch

---

处理审查评论

参考：完整且带有明确主张的工作流（含所有命令模式和示例），请参阅 references/pr-comment-workflow.md。

此工作流分为两个不同阶段——切勿混为一谈：

阶段 1：分析并修复（本地工作，不写入 GitHub API）——获取操作无需审批；git commit/git push 属于写入操作，仍需由人工把关

1. 使用内联 --jq 过滤器，通过单个 GraphQL 查询获取所有未解决的审查线程，然后获取机器人的审查正文——线程并不涵盖完整审查（见下文）
2. 对每个线程：读取引用路径和行号处的文件，通过研究代码库（模式、惯例、CLAUDE.md、git log）来检查评论是否有效
3. 保持审慎——接受评论前，先依据实际代码验证每条评论。审查者也可能出错。
4. 完成所有必要的代码修复——不要添加叙述修复过程或复述代码现有内容的代码注释
5. 提交修复（根据变更需要提交任意数量的提交），并为整轮变更推送一次——提交消息描述变更本身，绝不描述审查流程（不要写“处理审查反馈”、机器人名称或轮次编号；请参阅 git-commit 技能）

并非每条发现都会成为线程（CodeRabbit）。 小问题（profile: chill 下）、差异范围外的发现、重复项和发布失败的评论只存在于审查正文中；reviewThreads 不会返回这些内容，这通常是审查看起来已处理、实际却没有处理的原因。获取机器人的审查正文，也对其中的项目进行分类处理，并将机器人顶层线程与审查中声称的 Actionable comments posted: N 对照核实——命令见 references/bot-review-loop.md。

阶段 2：回复并解决（一个批处理命令，一次审批） 6. 将所有回复和所有解决操作合并为一条由 && 连接的命令 7. 先发送 REST 回复，然后使用单个带别名的 GraphQL mutation 批量解决所有已处理的线程 8. 将“需要讨论”的线程保持未解决——你回复过的每个 CodeRabbit 线程也要保持未解决，包括被驳回的线程：它会重新检查 HEAD 上的修复或评估你的理由，然后自行解决线程，作为复审的确认替代方式（references/bot-review-loop.md 中的 Fixes Confirmed in the Thread）。只有在 10 分钟内没有收到回复时，才自行解决，并且不要将其计为已确认

此顺序很重要：先推送修复，确保审查者阅读回复时能看到变更。在修复实际推送之前，绝不要回复声称“已修复”的评论。

获取未解决的讨论串（零批准）

GitHub —— 使用 $(...) 替换的一条命令。生成单行命令，不要在前面添加变量赋值（OWNER=...、REPO=...）——两者都会导致允许列表匹配失败：

gh api graphql -f query="{ repository(owner: \"$(gh repo view --json owner --jq '.owner.login')\", name: \"$(gh repo view --json name --jq '.name')\") { pullRequest(number: $(gh pr view --json number --jq '.number')) { reviewThreads(first: 100) { totalCount pageInfo { hasNextPage endCursor } nodes { id isResolved isOutdated path line startLine comments(first: 20) { nodes { id fullDatabaseId body author { login } } } } } } } }" --jq '.data.repository.pullRequest.reviewThreads | {total: .totalCount, nextCursor: (if .pageInfo.hasNextPage then .pageInfo.endCursor else null end), unresolved: [.nodes[] | select(.isResolved==false)]}'

返回未解决的讨论串，以及用于证明获取完整的两个数字。reviewThreads 不会自行分页——非空的 nextCursor 表示存在第 101 条及之后的讨论串，其中可能包含未解决的评论；在判定已处理任何内容之前，使用 reviewThreads(first: 100, after: \"{nextCursor}\") 重新获取并合并结果。

响应字段映射（至关重要——使用错误的 ID 会导致静默失败）：

字段	格式	用途
讨论串 .id	PRRT_...（节点 ID）	resolveReviewThread mutation
评论 .fullDatabaseId	"2949637341"（字符串）	REST 回复端点
评论 .id	PRRC_...（节点 ID）	通常无需使用

GitLab（REST）：

glab api projects/{project_id}/merge_requests/{iid}/discussions --paginate | jq '[.[] | select(.notes[0].resolvable==true and .notes[0].resolved==false) | {id:.id,path:.notes[0].position.new_path,line:.notes[0].position.new_line,body:.notes[0].body,author:.notes[0].author.username}]'

回复并解决（单条批处理命令）

GitHub —— 将所有 REST 回复与批量 GraphQL resolve mutation 合并为一条由 && 串联的命令。回复使用 fullDatabaseId（字符串；databaseId 已弃用），解决操作使用讨论串的 id（PRRT_ 节点 ID）。此示例适用于人工和 Copilot 讨论串：对于 CodeRabbit 讨论串，保留所有回复，但不要将其任何讨论串纳入 mutation，即使是被拒绝的也不例外，因为 CodeRabbit 会回复每条评论并自行解决讨论串（步骤 8）：

gh api repos/{owner}/{repo}/pulls/{pr}/comments/{fullDatabaseId_1}/replies -f body="Fixed in {sha} -- {explanation}" && \
gh api repos/{owner}/{repo}/pulls/{pr}/comments/{fullDatabaseId_2}/replies -f body="Addressed in {sha}" && \
gh api graphql -f query="
mutation {
  t1: resolveReviewThread(input: {threadId: \"PRRT_thread1\"}) { thread { isResolved } }
  t2: resolveReviewThread(input: {threadId: \"PRRT_thread2\"}) { thread { isResolved } }
}"

如果一轮中只有 CodeRabbit 讨论串，则只需发送回复——不执行 mutation。

GitLab：

glab api projects/{id}/merge_requests/{iid}/discussions/{disc_1}/notes --method POST --field "body=Fixed in {sha}" && \
glab api projects/{id}/merge_requests/{iid}/discussions/{disc_1} --method PUT --field "resolved=true" && \
glab api projects/{id}/merge_requests/{iid}/discussions/{disc_2}/notes --method POST --field "body=Addressed" && \
glab api projects/{id}/merge_requests/{iid}/discussions/{disc_2} --method PUT --field "resolved=true"

---

代码审查策略（约定）

审查偏好应在 Agent 指令文件的 Code Review Policy 部分中声明——请求审查前先检查是否存在此部分。策略有两个适用范围，以最具体的为准：

1. 仓库策略——项目的 AGENTS.md 或 CLAUDE.md。AGENTS.md 是首选位置：Copilot 代码审查本身会读取根目录下的 AGENTS.md，因此一个文件即可同时指导 Agent 和审查者。
2. 用户全局策略——用户的全局 Agent 指令（Claude Code：~/.claude/CLAUDE.md），作为跨仓库的默认流程。

**两种审查者都是可选的。**检查实际可用的审查者（是否安装 CodeRabbit 应用／已通过 CLI 身份验证、是否存在 Copilot 规则集或已观察到自动审查），绝不要假设某个审查者存在、已付费，或应该添加。Reviewer: none 是有效策略——仅进行人工审查。示例：

## Code Review Policy
- Reviewer: coderabbit            # coderabbit | copilot | both | none
- CodeRabbit plan: team until 2026-10-20, then essentials   # free | essentials | team | advanced | enterprise
- Copilot billing: legacy         # legacy (premium requests) | credits
- Local review: coderabbit review --committed --base main   # run before every push; --agent for JSON lines, no --plain
- PR review rounds: ask           # ask | loop <= N

声明 CodeRabbit 套餐——没有 API 会报告此信息。coderabbit usage 会显示仓库包含的额度和计费周期，但不会显示套餐等级；PR API 也从不提及套餐，因此未获告知的 Agent 要么会过度安排 PR，使其超出套餐可处理的范围，要么会闲置本可使用的额度。套餐决定每小时额度的上限（Free 为每位开发者 1 次／Essentials 为 5 次／Team 为 8 次／Advanced 为 10 次 PR 审查；Essentials 和 Team 在 2026 年 9 月前分别名为 Pro 和 Pro+，而保留旧套餐的 Pro+ 用户仍有 10 次额度——详见 coderabbit 技能中的表格），但公平使用限流会将实际速率限制在低于此上限的水平，依据是开发者在滚动的 24 小时或 7 天窗口内的审查次数——审查繁忙的一周会使 Essentials 开发者降至每小时 1–2 次。两个位置会报告实时额度：每次已发布审查中的运行配置块（其中也会注明套餐），以及 @coderabbitai rate limit 评论；后者会返回剩余额度和下次可用时间，且不会消耗一次审查——这是开启循环前成本最低的检查。额度也决定了可以同时保持多少个 PR 处于非草稿状态，以及本地 CLI 流程中适合进行多少轮迭代。试用期也要同样记录结束日期：能在 Advanced 上正常运行的队列，可能会在试用期结束、转为 Essentials 的当天早晨停滞。未声明时，应推断最低值，而非猜测——bot_bucket（references/bot-review-loop.md）会列出所有打开的 PR 中最近的审查轮次，而过去一小时内完成的审查次数是实际额度的下限。

**不存在策略时（任一范围均无），默认采取保守做法：**如果触发了自动审查，就处理该轮审查——按照宿主平台允许的方式等待（关键规则 9）；之后在再次请求任何计费审查前先询问，并根据该轮发现的质量给出建议（大多是有效且实质性的问题 -> 再审一轮可能值得；大多是噪声 -> 停止）。对于没有自动审查的仓库，绝不要在未获提示时主动发起计费审查；仅在明确要求时才进行循环。

Bot 审查循环（GitHub）

参考：完整循环请参阅 references/bot-review-loop.md：各 Bot 的配置块（Copilot、CodeRabbit）、bot_status/bot_tick 驱动程序、轮询和适配宿主平台的等待方式，以及终止逻辑。 参考：Copilot 审查配置请参阅 references/copilot-review-config.md：计费模式和配额检查、自动审查规则集的检测／管理、自定义指令，以及 Copilot CLI 本地审查选项。 GitHub 审查机器人（Copilot、CodeRabbit）仅适用于 GitHub，以异步方式运行（每次审查约需数分钟），且不会阻塞：其审查 state 始终为 COMMENTED。每个机器人的循环完全相同；只有身份（要筛选的登录名）、重新请求触发条件以及可检测到的失败／速率限制／审查无问题通知不同——这些由每个机器人的配置块设置。启用状态检测并不完整（可以读取 Copilot 自动审查的 ruleset，但无法读取个人设置中的自动审查状态和机器人的整体可用性——见上文 Context Check），因此，当远程服务不是 GitHub 或重新请求出错时，bot_tick 会以状态码 5 退出；请求已接受但未收到回复时则以状态码 3 退出（可能是响应慢，也可能是服务未通知地不可用）。

持续迭代，直到没有剩余的有效评论。加载某个机器人的配置和 bot_status／bot_tick 驱动程序——一轮操作如下：

1. 仅在需要时重新请求 + 等待——bot_tick {N} 首先检查未解决的机器人讨论串（处理这些讨论串，绝不在它们尚未解决时重新请求），然后检查 HEAD 上的评审（干净的 CodeRabbit 评审不会发布评审对象——其“没有可操作评论”的说明文本或“Review finished.”确认消息才是评审干净的信号，绝不代表失败或触及速率限制），接着检查 HEAD 的 CodeRabbit 提交状态；即使该轮请求被拒绝，它也会显示为 success（Review rate limited 表示 HEAD 从未被评审），然后检查 REST requested_reviewers 中是否有待处理的请求（非草稿 PR 创建时通常会自动评审，因此第 1 轮通常完全不需要重新请求）。只有以上情况都不适用时，才重新请求（Copilot：gh pr edit {N} --add-reviewer "@copilot"，gh >= 2.88，推送后不会自动重新评审；CodeRabbit：发表评论 @coderabbitai review），随后轮询异步评审结果——仅限托管平台允许轮询的情况；否则等待交由 PR 监控器或用户处理（关键规则 9）。返回值：0 干净 / 2 不干净 / 3 重试 / 4 失败（已冷却约 5 分钟并重新请求——重新运行以轮询）/ 5 不适用 / 6 触及速率限制 / 7 线程中的修复已确认（CodeRabbit 在 HEAD 上逐一复查了每项修复，或在聊天中接受了每项理由，并解决了对应讨论串；不重新请求——使用本地 CLI 流程检查修复新增的额外代码；对于大型 PR，可向用户建议发送一次 @coderabbitai full review，而不是直接发布该请求）。
2. 验证，而非盲目修复——评估每条未解决的评论，以及评审中仅出现在正文里的每个类别（吹毛求疵、位于差异范围之外、重复、发布失败；参见 Research Checklist）；机器人可能缺少上下文或使用了过时信息。修复有效意见（每项分别提交，然后每轮只推送一次；提交消息应说明更改内容，绝不提及机器人或轮次）；对无效意见回复理由并解决对应讨论串——但 CodeRabbit 的评论除外：回复它每个线程中的评论，并保持线程未解决，以便它自行解决（Phase 2，第 8 步）。要清除所有评审者的评论，每个活跃机器人各运行一次循环，并按照上述评论工作流处理人工评审者的讨论串。
3. 终止——当机器人没有评论时停止；当有效评论为零时停止（重新请求只会让这些评论再次出现）；连续约 3 次评审失败后停止（exit 4 是暂时性错误——例如“Copilot encountered an error”——bot_tick 会在冷却约 5 分钟并重新请求后重试；只有反复失败才属于结构性问题：PR 过大、包含二进制文件、配额不足；请上报）；触及速率限制时停止（exit 6：CodeRabbit——根据 tick 导出的 BOT_WAIT_UNTIL 安排后续操作，因为相关通知可能会被编辑掉；如果当时能读取通知，这就是打印出的时间窗口，否则从请求被拒绝时起约 10 分钟，仅当重试后再次被拒绝时才加倍。先检查 bot_bucket——你被拒后，若有同一配额桶中的其他 PR 完成评审，说明共享配额桶现在已开放——然后发布一个新的触发请求，因为请求不会排队；并使用 @coderabbitai full review：被拒的那一轮仍将这些提交标记为已评审，因此普通的 review 不会执行任何操作。被拒不会消耗评审次数或改变截止时间，但请求也绝不会排队，因此应使用 @coderabbitai rate limit 探测（不会消耗评审次数，会报告下次可用时间——但它是 PR 评论，因此与其他评论一样需要写入批准），而不是重复触发；如果 Copilot 也覆盖该仓库，则可跳过该机器人；Copilot——若评审运行的 CI 日志中显示通用“encountered an error”评论实际由每周硬性上限导致，则在日志所列重置日期之前绝不重新请求，并向用户说明原因和日期）；不可用时（exit 5）停止；达到轮次上限后停止（默认为 5，或“loop 3”）；或者自上一轮以来 HEAD 未发生变化时停止。 轮次会产生费用，在自动审查仓库中，推送就是一个轮次 —— Copilot 的每个轮次都会收取一次完整审查的费用；CodeRabbit 的每个轮次都会消耗按小时计算的配额，而该配额是按开发者计算，不按 PR 计算：你所有未关闭的 PR 都会争用相同的审查时段，因此有多个 PR 正在进行时，请将等待中的 PR 保持为草稿（草稿不会触发自动审查；标记为就绪才会发起请求），并一次只将一个 PR 标记为就绪 —— 请参阅参考文档中的 Scheduling Several PRs Through One Bucket 和 One Push Per Round。如果没有明确要求循环处理，也没有宽松的 Code Review Policy：如果触发了自动审查轮次，就处理该轮，然后再次请求前先询问（根据发现问题的质量给出建议）。只有用户提出要求时才自主循环处理。

CodeRabbit：首次完整审查后，讨论串就是循环处理流程。 一次性推送该轮修复，逐条回复所有讨论串 —— 可以回复“已在 {sha} 中修复”、部分采纳，或说明未修改的原因 —— 并让 CodeRabbit 的回复将问题关闭：这些是聊天，不是审查，因此不会占用 PR 审查配额（references/bot-review-loop.md、Fixes Confirmed in the Thread）。默认不再请求审查：修复额外引入的代码通过本地 CLI 流程检查。只有在大型 PR 中，才向用户提出一次 @coderabbitai full review —— 对新提交进行完整审查有时能发现讨论串无法发现的问题 —— 仅在用户同意后才发起。

身份标识注意事项： REST 中每个机器人的登录名都带有 [bot] 后缀，而 GraphQL 讨论串中的登录名没有该后缀（Copilot：copilot-pull-request-reviewer[bot] / copilot-pull-request-reviewer，REST 行内评论中还有 Copilot；CodeRabbit：coderabbitai[bot] / coderabbitai）。请根据接口筛选正确的标识。

---

行级评论（编写）

参考：完整模式请参阅 references/line-comments.md：单行、多行范围、回复、编辑/删除、批量审查。

GitHub：

gh api repos/{owner}/{repo}/pulls/{pr}/comments \
  -f body="{comment}" -f path="{file}" -F line={line} -f side=RIGHT \
  -f commit_id="$(gh pr view {pr} --json headRefOid --jq .headRefOid)"

GitLab：

glab api projects/{project_id}/merge_requests/{iid}/discussions --method POST \
  --field "body={comment}" \
  --field "position[base_sha]={base_sha}" \
  --field "position[head_sha]={head_sha}" \
  --field "position[start_sha]={base_sha}" \
  --field "position[position_type]=text" \
  --field "position[new_path]={file}" \
  --field "position[new_line]={line}"

---

只读 API 端点

参考：两种提供方的只读 REST 和 GraphQL 端点完整列表（PR 数据、议题时间线、审查讨论串），请参阅 references/api-readonly.md。

---

glab 与 gh 的主要区别

方面	gh	glab
MR 描述标志	--body	--description
删除源分支	--delete-branch	--remove-source-branch
JSON 输出	--json field1,field2（经过筛选）	-F json（完整资源）
jq 筛选	--jq '.expr'（原生支持）	管道传给 | jq '.expr'
创建时压缩合并	--squash	--squash-before-merge
GraphQL	gh api graphql -f query='...'	不支持（仅 REST）
解决讨论串	GraphQL mutation	使用 resolved=true 执行 PUT /discussions/:id
审批模式	审查状态（APPROVED、CHANGES_REQUESTED）	审批规则 + 批准/撤销
分页	--paginate（子命令 + api）	--paginate（仅 api），-P（子命令）

---

允许列表

参考：涵盖所有只读操作的分级 Bash(command:*) 模式请参阅 references/allowlist.md —— 可在 Claude Code settings.json 或 OpenCode 配置中安全地自动批准。