coderabbit-resolver

Codex 兼容性

在 Codex 中运行此技能时，操作前先将 Claude Code 专用原语转换为对应项：AskUserQuestion -> chat/request_user_input，TodoWrite -> update_plan，Task/TaskCreate/TeamCreate/SendMessage -> 在可用且允许时使用 spawn_agent/send_input/wait_agent，EnterPlanMode/ExitPlanMode -> 简洁的聊天计划并明确征求批准。 将 Read/Write/Edit/Bash/WebSearch/WebFetch 映射到 Codex 文件/命令行/网页工具；除非任务明确针对 Claude Code，否则将 ~/.claude/... 路径映射到 ~/.agents/... 或 ~/.codex/...。

Cursor 兼容性

在 Cursor Agent 中运行此技能时，操作前先将 Claude Code 专用原语转换为对应项：AskUserQuestion -> AskQuestion；TodoWrite -> Cursor TodoWrite 或等效清单；Task/TaskCreate/TeamCreate/SendMessage/多 Agent 流程 -> 在允许时使用 Cursor Task（子 Agent）、并行 Tasks 或 run_in_background（TeamCreate/SendMessage 可能没有完全对应项）；EnterPlanMode/ExitPlanMode -> Plan mode（SwitchMode / CreatePlan）并明确征求用户批准。 通过 Cursor Composer 或 Agent 的对应功能解析 Read/Write/Edit/StrReplace/Bash/网页/搜索/MCP。写作 mcp__server__tool 的 MCP 名称通常映射到使用已配置服务标识符的 call_mcp_tool。除非任务明确针对 Claude Code，否则将 ~/.claude/... 映射到 ~/.cursor/skills/、.cursor/skills/ 和 .cursor/rules/。

<essential_principles>

此技能的工作方式

自动执行 GitHub PR 上的 CodeRabbit 迭代审查循环，直到解决所有审查评论且 CI 通过，然后合并并清理。

原则 1：仅通过 GraphQL 解决线程

GitHub 没有用于解决审查线程的 REST API。必须使用 GraphQL resolveReviewThread mutation 和带 PRRT_ 前缀的线程 ID。该 mutation 具有幂等性——对已解决的线程调用也安全。

Diff 范围外的发现项位于审查正文中，没有可解决的线程 ID。在审计表中记录其处理结论和证据；未解决的行内线程为零，并不能证明这些发现项已处理。

原则 2：迭代循环直到干净

工作流按循环执行：

1. 提取未解决的 CodeRabbit 行内线程以及所有 CodeRabbit 审查正文，包括较早的 Diff 范围外发现项
2. 根据当前代码核实每项发现；修复问题，或记录其已修复/跳过的原因，并解决适用的行内线程
3. 提交 → 推送 → 等待 CI + CodeRabbit 重新审查（或在 cli 模式下，等待 CI + CodeRabbit CLI 重新审查）
4. 每次重新审查后、合并前，重新获取这两个来源。重复此过程，直到：未解决线程为零，未审计/未处理的 Diff 范围外发现项为零，所有 CI 检查均通过，并且（CodeRabbit 已审查当前 HEAD，或 CLI 审查已通过 CR_CLI_LOG 门槛）

原则 3：每次推送前验证

每次提交前运行 pnpm validate（或项目专用的验证命令）。绝不推送有问题的代码。

原则 4：安全合并与清理

仅当满足所有条件时才合并：CI 通过（没有待处理、失败或已取消的检查），没有未解决的线程，每项 Diff 范围外发现都有基于当前代码的处理结论和证据，并且 CodeRabbit 已审查当前 HEAD 提交（其检查已通过，且该提交上存在 CodeRabbit 审查）。若 PR 侧没有审查涵盖 HEAD，则通过 CR_CLI_LOG 门槛（原则 5）的 CodeRabbit CLI 审查可满足最后一项条件。check-ci-status.sh 是 CI 和审查的门槛，因为仓库可能不要求任何检查，此时 GitHub 仍会允许合并红色 PR。它不会审计 Diff 范围外的发现项；其退出码为 0 不能替代该审计。仅合并已验证的 head（--match-head-commit）。合并后，重新指定叠加在该分支上的 PR 的目标分支，然后删除远程分支并清理本地分支（review-loop.md 第 9 步）。绝不使用 gh pr merge --delete-branch：GitHub 会关闭叠加的 PR，而不是重新指定其目标分支。

原则 5：HEAD 未通过审查，不得合并——包括速率限制在内

CodeRabbit 可能会触发 API 速率限制，并发布速率限制警告评论，而不是执行实际审查。关键是，在这种情况下，GitHub Checks API 仍会报告 completed/success——无法仅通过 API 信号区分实际审查和速率限制响应。仅信任 Checks API 会导致合并未经审查的 PR。

因此：每个「CodeRabbit 成功」都必须与最新的 CodeRabbit 问题评论交叉验证。如果最新评论符合速率限制模式（例如「Rate limit exceeded」「wait X minutes before requesting another review」），无论 API 状态如何，该次运行都属于速率受限。一次「成功」也可能对应 CodeRabbit 从未读取过的推送：某次运行没有留下审查结果，但该 SHA 的状态可能显示「Review completed」，也可能显示「Reviews paused」或「Review skipped」；后续运行还可能覆盖该状态。只有 commit_id 为 HEAD 的 CodeRabbit 审查才能证明 HEAD 已通过审查。

check-ci-status.sh 会在内部执行这些检查：该 SHA 的状态文本、最新评论，以及针对 HEAD 的审查。如果这些检查表明没有审查覆盖 HEAD，它会返回 退出码 3。工作流的步骤 6a 会将退出码 3 视为「转到步骤 6b」，步骤 8（最终验证）则会将退出码 3 视为「不得合并」。这样就无法绕过审查门禁。

如果没有审查覆盖 HEAD，不要等待速率限制窗口结束。使用 CodeRabbit CLI 在本地审查 PR（scripts/cli-review.sh，review-loop.md 步骤 6b），像审查评论一样审核其发现，然后通过设置 CR_CLI_LOG（以及对人工处理的发现设置 CR_CLI_ACCEPT）重新运行 check-ci-status.sh，通过合并门禁。该脚本只接受已完成的 CLI 运行日志，且日志中的发现数量必须完全一致；审查必须针对 HEAD（如果发现已被接受，则必须针对 HEAD 的祖先提交，且之后的提交已修复这些问题）。

CLI 也有自身的限制。每次运行都会计入账户的 CLI 审查次数（coderabbit usage），并且套餐会限制每小时的 CLI 审查次数。因此，每个 HEAD 只运行一次，每个 PR 最多进行 3 次 CLI 审查，因为多轮审查不会逐步减少发现数量。除非所有者提出要求，否则绝不要添加 --use-credits（按用量计费）。

只有在 CLI 无法运行时才退而等待：例如未安装、未登录，或同样受到速率限制（cli-review.sh 退出码为 5 或 6）。此时，wait-for-ratelimit.sh 会等待限制窗口结束（再加 30 秒缓冲），然后发布 @coderabbitai full review。每个 PR 最多重试 3 次，以防止无限循环。

当 CLI 受到速率限制（退出码 6）时，新建 PR 时应在描述中添加 @coderabbitai ignore，避免机器人也在这些 PR 上触发限制。CLI 恢复审查能力后，移除这一行，并使用 CLI 审查这些 PR（review-loop.md 步骤 6b 第 6 项）。这种临时忽略不属于 cli 模式。

原则 6：长时间等待使用 ScheduleWakeup，而不是 sleep

Claude Code 的 Bash 策略会阻止顶层的 sleep，并耗尽 5 分钟的提示词缓存。在 scripts/*.sh 内部使用 sleep 没问题——Claude 会将脚本视为单条命令。但如果你（Agent）需要在没有脚本封装的情况下等待步骤之间的间隔（例如检查完成后等待 CodeRabbit 发布评论），请使用 ScheduleWakeup，并提供一个会重新进入工作流的续接提示词。绝不要将 sleep 180; gh api ... 写成顶层 Bash 命令。

原则 7：cli 模式会停用 GitHub Bot

当调用中包含 cli 或 --cli 时，GitHub Bot 不得审查此 PR。请在PR 描述中单独一行写上 @coderabbitai ignore（scripts/ensure-cli-ignore.sh），并保留这行内容——注释中写入相同文本不会生效。使用 cli-review.sh 审查每个 HEAD，并通过设置 CR_CLI_MODE=1 和 CR_CLI_LOG 来通过检查。不要发布 @coderabbitai review / full review / resume，也不要运行 wait-for-ratelimit.sh（它会发布 full review）。如果无法运行 CLI，请停止并询问用户。 </essential_principles>

此技能接受 PR 编号、`--bulk` 和可选的 `cli` 标志。`cli` 和 `--cli` 是同一标志。用法：

/coderabbit-resolver <PR_NUMBER>       # Process single PR (GitHub bot)
/coderabbit-resolver 17                # Process PR #17
/coderabbit-resolver 17 cli            # PR #17 via CodeRabbit CLI; bot ignored
/coderabbit-resolver cli               # Current-branch PR via CodeRabbit CLI
/coderabbit-resolver --bulk            # Process ALL open PRs (oldest first)
/coderabbit-resolver --bulk cli        # All open PRs via CodeRabbit CLI

解析每个参数：cli / --cli 表示启用 CLI 模式；--bulk 选择批量工作流；第一个全数字令牌是 PR 编号。如果没有 PR 编号（且没有 --bulk），则从当前分支检测：

gh pr view --json number -q .number

获取 PR 编号后，阅读并遵循 workflows/review-loop.md。 如果指定了 --bulk，阅读并遵循 workflows/bulk-loop.md。 如果设置了 cli，请遵循相应工作流的 CLI 模式规则（原则 7）。

| 输入 | 操作 | |-------|--------| | 提供了 PR 编号 | 阅读 `workflows/review-loop.md` 并针对该 PR 执行 | | 没有 PR 编号 | 从当前分支自动检测，然后阅读 `workflows/review-loop.md` | | `--bulk` 标志 | 阅读 `workflows/bulk-loop.md` 并处理所有未关闭的 PR | | `cli` / `--cli`（与上述任意选项一起使用） | 使用相同工作流的 CLI 模式：`@coderabbitai ignore` + CodeRabbit CLI |

阅读工作流后，请严格遵循。

<reference_index>

参考资料

文件均位于 references/：

文件	内容
github-graphql-api.md	用于解决讨论线程和检查 CI 状态的 GraphQL 查询/变更
coderabbit-commands.md	CodeRabbit Bot 命令和行为参考
</reference_index>

<workflows_index>

工作流

文件均位于 workflows/：

工作流	用途
review-loop.md	主要的迭代审查、修复、解决和合并流程（单个 PR）
bulk-loop.md	按顺序处理所有未关闭的 PR（从最早的开始），并逐个合并
</workflows_index>

<scripts_index>

脚本

脚本	用途
resolve-threads.sh	解决 PR 中所有未解决的 CodeRabbit 讨论串
check-ci-status.sh	合并门槛：等待 PR 头提交上的 CI 和 CodeRabbit 检查。任何失败、已取消或待处理的检查都会阻止合并（依据 gh pr checks 分类）；如果 PR 除 CodeRabbit 外没有 CI，或头提交没有 CodeRabbit 审查，也会阻止合并。当 PR 侧没有覆盖 HEAD 的审查时，可通过 CR_CLI_LOG 接受 CLI 审查。CR_CLI_MODE=1 会跳过 GitHub 机器人检查，并要求提供该日志
cli-review.sh	当 PR 侧没有覆盖 HEAD 的审查时（速率受限、审查暂停或处于 cli 模式），使用 CodeRabbit CLI 在本地审查 PR；--verify 会检查已保存的运行记录是否满足合并门槛
ensure-cli-ignore.sh	在 PR 描述中加入 @coderabbitai ignore，以防 GitHub 机器人自动审查（cli 模式）。可重复运行而不产生重复内容
wait-for-ratelimit.sh	CLI 无法运行时的备用方案：检测速率限制，等待限制过期并触发完整审查。不要在 cli 模式下使用此脚本

tests/run_tests.py 使用伪造的 gh 和伪造的 CLI 测试 cli-review.sh、check-ci-status.sh（CR_CLI_LOG / CR_CLI_MODE 分支、审查层级和 CI 判定）以及 ensure-cli-ignore.sh（运行 python3 tests/run_tests.py；不会消耗审查次数）。修改这些脚本后请运行该测试。 </scripts_index>

<success_criteria> 成功调用 coderabbit-resolver（单个 PR）：

• 所有 CodeRabbit 审查讨论串均已解决（未解决数量为零）
• 已根据当前 HEAD 审核所有差异范围之外的审查正文问题：有证据表明已修复，或说明原因并标记为已跳过；不得有未经审核或未修复的问题
• 所有 CI 检查均已通过（绿色，且没有待处理、失败或已取消的检查），包括修复与本次变更无关的 CI 故障
• CodeRabbit 已审查 HEAD（对该提交进行了审查）；或者，当 PR 侧没有覆盖 HEAD 的审查时，HEAD 的 CLI 审查已通过 CR_CLI_LOG 门槛
• PR 已成功合并
• 已将基于该分支堆叠的 PR 重新指定目标分支，随后删除远程分支
• 已清理本地分支（切换到 main 并清理已删除的远程分支引用）

成功调用 --bulk：

• 已处理所有开放的 PR（从最早的开始）
• 每个 PR 均已合并或跳过（并说明原因）
• 已生成包含结果表格的汇总报告

成功调用 cli（单个 PR 或 --bulk cli）还需满足：

• 整个运行期间，PR 描述中都包含 @coderabbitai ignore
• 审查证据是已通过 CR_CLI_MODE=1 + CR_CLI_LOG 门槛的 CodeRabbit CLI 日志
• 未发布 @coderabbitai review / full review / resume 评论 </success_criteria>