robin

Robin PR 完成协议

Robin 是一个以 GitHub Action 形式运行的 AI 审查工具。完成 PR 时，请将此技能作为所有者侧协议使用；不要盲目听从 Robin。Robin 可能只能看到差异，并且可能使用较弱的轮换模型，而负责工作的 Agent 拥有仓库和对话上下文。修复已核实的错误，并通过基于事实的回复驳回无关内容。

不可妥协的行为

• 普通 PR 工作时自动启用，无需用户提及“Robin”。
• 进入循环前，在 PR 的目标分支上检测 Robin。除非用户要求，否则不要安装它。
• 自主持续处理等待和审查轮次。正在运行的检查、已推送的修复或已请求重新审查，都不是终止状态。
• 统计已完成的 Robin 审查结果。初始预算为 5 次。超过 5 次后，每增加一次审查都需获得批准，除非用户明确预先授权持续审查。
• 分别回复 Robin 的每条行内评论，包括驳回的发现，并在回复后解决每个审查讨论串。
• 只修复已核实的缺陷。严重程度和置信度用于确定调查优先级，不能证明结论正确。
• 未经明确授权，绝不合并。“创建 PR”不代表授权合并。
• 保留无关的本地更改和分支。不得仅为完成此协议而暂存、丢弃、提交或删除它们。
• 绝不自动准备或发布版本。

终止状态

不要仅仅因为 Robin 或其他检查仍在运行就交还控制权。持续轮询、分流、修复、回复、解决讨论串并重新审查，直到恰好达到以下某一状态：

1. READY： 所有门槛均已通过，但尚未获得合并授权。
2. COMPLETE： 已确认合并获得授权，并已验证清理完成。
3. CAP： 当前获批的审查预算已用完，后续审查需要授权。
4. BLOCKED： 基础设施反复故障、清理存在不安全冲突、缺少访问权限，或存在其他无法在不询问用户的情况下解决的情况。

长时间等待时，请简要更新进度，但在达到终止状态前始终负责处理任务。

1. 确立策略并确保安全

计划创建 PR 时，创建之前记录两项独立策略。

合并策略：

• “检查通过后合并”或“创建、审查并合并”等明确指示，授权对此 PR 自动合并。
• 否则，询问一次用户是否希望检查通过后自动合并。在用户答复同意前，将策略记录为手动。
• 长期偏好仅在用户明确将其设为长期偏好时才适用。绝不要根据之前的一次合并推断长期偏好。

扩展审查策略：

• 默认采用逐次授权：预先批准第 1–5 次审查；第 5 次之后的每次审查都需要新的明确批准。
• One more Robin review 将预算恰好增加一次，不会授权所有后续审查。如果第 6 次审查后需要第 7 次审查，请再次询问。
• “全自动”“让 Robin 持续运行直到通过”“额外的 Robin 审查轮次之间无需询问”或含义相同的明确指示，表示授权对此 PR 持续进行额外审查。无需逐次询问即可继续，但若检查通过则应提前停止；若基础设施或安全问题导致 BLOCKED，也应停止。
• 单独的 Auto-merge 仅授权合并，不授权超过 5 次的审查。
• Full auto 或“通过 Robin 自动运行并合并”同时授权持续审查和对此 PR 合并。除非有明确说明，否则不要推断这是适用于其他 PR 的长期策略。

对于未记录授权的现有 PR，采用手动模式并继续审查循环；在 READY 状态停止。

记录初始仓库状态，以便保留并报告无关更改：

git status --short --branch
gh repo view --json nameWithOwner -q .nameWithOwner

PR 创建后，记录其标识和分支：

gh pr view --json number,url,baseRefName,headRefName,state,reviewDecision,mergeStateStatus,statusCheckRollup

仅暂存任务相关文件或已核实的审查修复文件。存在无关文件时，绝不要批量暂存。

2. 检测 Robin

对于已打开的 PR，Robin 必须存在于 PR 的目标分支上才能触发。获取目标分支并检查该分支的文件树，而不只是功能分支：

git fetch origin <base-branch>
git grep -n 'antongulin/robin' origin/<base-branch> -- .github/workflows

如果本地没有目标分支，也要通过 gh api 识别等效工作流。确认它会监听 pull_request，或通过 issue_comment 接受 /robin。

• 存在 Robin：自动运行完整协议。
• 不存在 Robin：继续用户的常规 PR 任务，不运行 Robin 审查循环，并说明其缺失。除非用户要求，否则不要添加 Robin。
• Robin 只添加在当前 PR 分支上：由于目标分支上缺少该工作流，它无法自动审查该 PR。请解释这一限制，不要假装会收到审查结果。

开始时允许尽力检查版本，但绝不能因此延误 PR 工作：

gh release view --repo antongulin/robin --json tagName -q .tagName 2>/dev/null

报告已安装的技能版本过时，但只有在事先获得授权后才能更新。

3. 等待已完成的审查

PR 打开时通常会自动触发审查。不要立即发布 /robin；先检查 PR 评论、审查、检查项和 Actions 运行。大约每 30 秒轮询一次。

gh pr view <number> --json comments,reviews,statusCheckRollup
gh run list --limit 20 --json databaseId,event,status,conclusion,workflowName,createdAt,url,displayTitle,headBranch

• 如果 Robin 运行正在进行，持续观察并轮询。
• 如果运行失败，将其归类为基础设施故障，检查故障，并在考虑使用斜杠命令之前重试一次失败的运行。
• 如果约 3 分钟后仍未出现 Robin 信号，确认工作流触发条件。只有此时才发布 /robin。
• 单次等待最长约 8–10 分钟。如果提供商或 Actions 持续故障，将其报告为 BLOCKED，并附上运行 URL；绝不要将无响应或空结果视为审查通过。

只有收到已完成且可用的 Robin 结果时，才递增审查计数。对于已有 PR，当前 head 上最新的可用结果在本次完成流程中计为审查 1；不要计算已过时的历史结果。每次完成的重新审查只递增一次计数。同时跟踪 reviews_used 和 reviews_approved；将后者初始化为 5。

4. 获取并分类每条发现

获取顶层审查数据、REST 行内评论以及 GraphQL 审查线程状态。请阅读 references/github-pr-api-reference.md，了解确切的查询、回复端点和解决问题的 mutation。

根据实际代码库对每条发现进行分类：

• FIX：确认存在正确性、安全性、可靠性、数据丢失、测试方面的问题，或会造成实质误导的文档缺陷。无论 Robin 声明的严重程度如何，都要修复。
• REJECT：误报、重复、已处理、主观性改动、与代码库约定冲突，或被更广泛的上下文证伪的说法。不要更改代码。
• INFRA：审查超时、工作流失败、响应为空，或运行已被取代/取消。处理运行问题；不要更改代码。

默认不采纳建议。只有在建议能避免具体问题，或对所请求的更改显然不可或缺时才采纳。绝不要为了满足审查者而凭空编造改动。

5. 开始下一轮审查前，先结束当前审查

对于每个已完成的 Robin 结果，按以下顺序执行：

1. 仅按照仓库现有风格处理 FIX 项。
2. 进行适度的本地验证，并运行 git diff --check。
3. 只暂存预期文件；如果代码有变更，则创建本地提交。
4. 逐条回复本轮审查中 Robin 的每条行内评论：
   • FIX：说明修正内容和本地提交。
   • REJECT：说明不作更改的具体仓库证据。
5. 对仅出现在审查正文中的发现，发布一条逐项列出处理结果的评论， 因为 GitHub 没有可供行内回复的目标。
6. 解决所有已处理的审查讨论串，包括过时的讨论串。
7. 重新查询 GraphQL，确认已处理的讨论串中未解决的数量为零，且 Robin 尚未收到回复的行内评论数量为零。
8. 只有现在才能决定是否推送，并按照第 6 步重新审查。

回复示例：

• 已在 abc123 修复：中止和超时失败现在会返回不同的错误。
• 不作更改：该值在 db.ts:84 作为绑定查询参数传入，因此不存在所报告的插值路径。

不要用一条顶层总结代替行内回复。当前审查的回复或讨论串仍未处理完毕时，不要开始下一轮审查。

6. 决定是否重新审查

• 如果所有发现均为 REJECT，且没有代码变更：不要再花费一轮 Robin 审查。 继续执行放行检查。
• 如果代码有变更且 reviews_used < reviews_approved：推送代码并获取另一轮 Robin 结果。
• 如果已用完批准的审查额度，且再获取一个结果能显著提高信心：按照下方的额度扩展规则执行。

Robin 的默认工作流会在 PR 创建时和收到 /robin 时进行审查，不会在每次推送时审查（synchronize 需显式启用）；不过，某些安装和自定义工作流会在 synchronize 时触发。推送修复后：

1. 检查工作流触发条件和 Actions 运行记录，确认 synchronize 是否会触发审查。
2. 如果推送启动了 Robin，等待该运行完成，不要重复发送命令。
3. 否则，使用 /robin 请求常规的手动重新审查，并附上修复提交和验证摘要。

gh pr comment <number> --body '/robin

Fixed in <commit>:
- <verified issue>

Verification:
- <command and result>'

然后返回第 3 步，不要要求用户提示下一轮。

批准的审查额度用完时，照常修复已验证的缺陷、回复并解决讨论串。然后判断是否确实需要再审查一次：

• 如果 PR 已通过，或只剩下已驳回的噪声，则停止，不要再审查。
• 如果仍有已验证的问题、代码有变更且需要验证，或仍存在重大不确定性，则再审查一次是有价值的。
• 在连续模式下，将 reviews_approved 增加一，然后自动继续。
• 在逐次批准模式下，进入 CAP 并询问：已使用 <N> 次获批的 Robin 审查。您要我运行第 <N+1> 次审查吗？ 同意后，预算恰好增加一。完成该次审查后，重复此判断；如果再进行一轮审查仍有价值，则再次询问。

在预算临界点推送前，检查 synchronize 的触发行为。如果推送本身会启动未经批准的下一轮审查，则先请求批准。否则，推送已验证的修复，不要发送 /robin，然后进入 CAP。在逐次批准模式下，绝不能以不确定性为由自动增加审查次数。

7. 绿灯门槛

在宣布 READY 或合并之前，请确认以下所有事项：

• 已通过与变更相适应的本地验证。
• 必需的 GitHub 检查均已成功，或有意标记为中立／跳过。
• Robin 或相关必需检查均未处于运行状态。
• 每条审核意见都有记录在案的处理结果。
• 每条行内审核评论之后都有负责人回复。
• 每个审核讨论串（包括过时的讨论串）均已解决。
• PR 可以合并，且没有未解决的冲突。
• 已知已使用和已获批准的审核次数，且没有发生未经批准的审核。

以 GraphQL 讨论串状态为准。较晚的检查结果已通过后，reviewDecision: CHANGES_REQUESTED 可能仍是过时状态；仅当最新的审核意见均已处理、所有讨论串均已解决且所有检查均已通过时，才将其视为过时状态。

在手动模式下，报告门槛检查摘要并进入 READY。如果尚未请求合并许可，请提出请求。在自动模式下，直接继续合并。

8. 获准后合并与清理

只有在通过门槛检查且已获得授权后，才能合并。选择 squash、merge 或 rebase 之前，请检查仓库设置和惯例。优先遵循明确指定的合并方式或项目指示。如果只允许一种方式，则使用该方式。在通过 conventional commits 生成发布版本的仓库中，优先使用 squash，使一个 PR 生成一条发布记录。否则遵循仓库近期的历史；如果合并方式仍存在实质性歧义，请在合并前询问。不要更改仓库设置。

gh repo view --json mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed
gh pr merge <number> --squash --delete-branch # use the selected allowed method
gh pr view <number> --json state,mergedAt,mergedBy,mergeCommit,url

不要假设 --delete-branch 已完成所有本地操作。确认 PR 已合并后：

1. 明确切换到已记录的 PR 基础分支。
2. 从其上游快进更新该分支。
3. 获取更新并清理过时的远程跟踪引用。
4. 确认远程已不存在任务分支；如果合并命令未能删除该分支，则删除该确切的远程分支。
5. 如果本地任务分支仍存在，则将其删除。只有在确认 squash、rebase 或 merge 已完成后，才可强制删除。
6. 检查当前分支、与上游的同步状态、剩余分支和工作树。

git switch <base-branch>
git pull --ff-only origin <base-branch>
git fetch --prune origin
git status --short --branch
git branch --list <task-branch>
git ls-remote --heads origin refs/heads/<task-branch> # no output means deleted
task_branch="<task-branch>"
if git ls-remote --exit-code --heads origin "refs/heads/$task_branch" >/dev/null; then
  git push origin --delete "$task_branch"
fi
if git show-ref --verify --quiet "refs/heads/$task_branch"; then
  git branch -D "$task_branch" # only after confirmed merge and base-branch switch
fi

只删除为此任务创建的分支。绝不要删除无关的本地或远程分支。保留预先存在的未提交文件；如果这些文件妨碍安全切换或拉取，请进入 BLOCKED，并准确报告哪些清理后置条件仍未完成。

9. 最终报告与可选的发布提议

报告：

• PR 编号、URL 和最终状态。
• 使用的 Robin 审核次数，包括默认 5 次以内的次数以及额外获批的次数。
• FIX 和 REJECT 的数量及简要说明。
• 已回复的评论数和已解决的讨论串数，并注明核实后的总数。
• 本地和 GitHub 检查结果。
• 合并授权和合并结果。
• 当前基础分支及其与上游的同步状态。
• 本地／远程任务分支的删除状态。
• 已保留的无关未提交文件，或 none。

获准合并并达到 COMPLETE 后，检查仓库是否已有既定的发布机制。如果有，并且合并的变更看起来适合发布，请以一个可选问题结束：Do you want me to prepare and publish a release? 将此视为需要新的明确许可的独立任务。不要在此 PR 流程中编辑变更日志、标签、版本或已发布的发布说明。

常见失败模式

• 只等待一次就返回，而不是负责跟进整个循环，直到达到终止状态。
• 明明可以检测到已安装的工作流，却仍要求用户提及 Robin。
• 把严重程度当作证据，或修复风格方面的噪声。
• 尚未回复并解决当前审查就推送。
• 自动运行已在进行时仍发布 /robin。
• 未检查工作流触发条件就假设每次推送都会自动运行 Robin；默认安装不包含 synchronize，并使用 /robin 进行重新审查。
• 统计修复轮次，而不是已完成的审查结果。
• 把对“再进行一次”审查的许可视为对之后所有审查的许可。
• 把自动合并许可视为持续审查许可。
• 把空白或失败的审查运行结果当作无问题。
• 依赖 REST 数据或 reviewDecision，而不是 GraphQL 线程状态。
• 未经明确授权就合并。
• 未检查基分支和任务分支就假设合并清理已成功。
• 触碰无关的脏文件、分支、发布或发布说明。

参考资料

• references/github-pr-api-reference.md — GitHub API 查询和变更的具体内容。
• references/lessons-learned.md — 协议安全措施背后的事件。