copilot-pr-autopilot

Copilot PR Autopilot

驱动任意 GitHub 拉取请求经历多轮 Copilot 代码审查，直到 Agent 完成其工作 — 每条 Copilot 发现都得到 Agent 的回复（修复确认、附理由拒绝，或明确升级移交用户）。剩余的未关闭讨论串（如果有）是刻意移交给人肉合并负责人的 — 它们不是循环失败。与仓库无关 — 可在任何启用了 Copilot Code Review 的仓库上运行，从安装了 gh CLI 并已通过身份验证的机器上执行（参见先决条件）。

何时使用此技能

• 用户要求在 PR 上“请求 Copilot 审查”或“运行 Copilot 审查循环”。
• PR 在功能上已完成，用户希望通过重复的自动审查轮次做一次最终正确性检查。
• 该 PR 上先前的 Copilot 审查留下了需要分诊、修复、回复和解决的未关闭讨论串。

何时不要使用此技能

• PR 仍处于活跃设计阶段 — 等到结构稳定；否则发现会一轮又一轮地反复变动。
• 用户想要的是人类审查者的反馈，而不是 Copilot 的。

先决条件

• 已安装 gh CLI，并已针对目标仓库完成身份验证。
• PATH 中有 PowerShell — Windows PowerShell 5.1+（powershell.exe）或 PowerShell 7+（pwsh）。两者均已测试。
• Copilot Code Review 是主要用例（01-request-review.ps1 使用 GraphQL requestReviewsByLogin 来触发 Copilot）。这不是硬性要求 — 如果 01-request-review.ps1 因仓库 / 账户未启用 Copilot 而失败，Agent 仍可通过将步骤 3–8 作为单次迭代运行一次，将现有审查讨论串（人类、advanced-security 等）推进到完成；只需跳过触发 + 等待。没有针对“Copilot 不可用”的自动检测 — Agent 在触发失败后自行做出该判断（仅凭 API 状态，脚本无法可靠地区分“Copilot 已禁用”和“Copilot 已启用但尚未触发”）。

权限：谁可以运行完整循环

完整的多轮 autopilot（步骤 1 → 9 → 1）需要对目标仓库具有 Triage 或 Write 权限，因为 GitHub 唯一用于将 Copilot 机器人添加为审查者的公开 API（requestReviewsByLogin）受该权限限制。已针对本 PR 提交历史中的公开 REST + GraphQL 接口进行验证 — 没有写权限时，不存在添加机器人审查者的公开 API 途径。

你是……	什么可行
具有 Triage / Write 的仓库协作者	完整循环：01 触发 Copilot，02 等待，04–08 分诊 / 修复 / 回复，循环回到 01。无需人工干预。
外部 PR 作者（无写权限）	01 会抛出清晰且可操作的错误。使用 -SingleIteration 模式：一次性处理所有当前发现，然后要么点击 Copilot 旁的 UI 🔄，要么推送一个实质性提交（在大多数仓库上，synchronize 事件会自动触发 Copilot）。然后重新运行 02 进行验证。

在单次迭代模式下，当且仅当 OpenThreadsAwaitingReply == 0（Agent 一侧已完成）时，循环的收敛布尔值为 Converged: true。随后维护者一侧的重新触发会驱动任何额外的轮次。

每个脚本都会点源引入 scripts/_lib.ps1，它在加载时运行 Assert-GhReady：如果 gh 缺失，或者 gh auth status 失败，脚本会在任何工作开始之前停止，并给出单条可操作的错误消息，指明安装命令和 gh auth login。Agent 应将该消息原样呈现给用户并停止循环 — 不要重试或绕过它。

分步工作流

循环： 步骤 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9，然后如果 Converged: false 则回到步骤 1。重复 1→9 这一轮，直到步骤 9 返回 Converged: true；只有此时才运行一次步骤 10 并调用 task_complete。每第 10 轮时，父级在回环之前运行轮次上限回顾门禁——回顾所有之前的轮次，如果循环已偏离 PR 的原始范围就停止。

每一轮运行步骤 1–9；步骤 10 是收敛后的一次性清理。父 Agent 负责协调；每个子 Agent 步骤都在全新上下文中以有界预算运行。横切协议（时间盒、延期、单次迭代回退）：见 orchestration.md。

1. 请求审查 （父级） — 见 01-request-review.md
2. 等待审查 （子 Agent，上限 20 分钟） — 见 02-wait.md
3. 列出 + 分类未解决的讨论串 （子 Agent，5 分钟） — 见 03-list-threads.md
4. 分诊 （子 Agent，每 ≤5 个讨论串 5 分钟） — 见 04-triage.md
5. 修复 （子 Agent，并行最多 5 个，每个 5 分钟） — 见 05-fix.md
6. 按仓库约定构建 + 测试 （子 Agent，10 分钟） — 见 06-build-test.md
7. 提交 + 推送 （父级） — 见 07-commit-push.md
8. 回复（始终）+ 解决（视情况） （子 Agent 起草，父级发布） — 见 08-reply-resolve.md
9. 收敛验证 （子 Agent，3 分钟） — 见 09-convergence.md
   • Converged: false → 回到步骤 1 进行另一轮（重新触发、等待、列出、分诊、修复、推送、回复、重新检查）。每一轮都针对上一轮 HEAD 上 Copilot 的发现进行处理；一旦 Copilot 没有新的意见并且每个未解决的讨论串都有 Agent 的回复，循环即终止。
   • Converged: true → 退出循环，运行一次步骤 10，携带证据调用 task_complete。
   • 每第 10 轮（10、20、30……）→ 在回环之前运行轮次上限回顾门禁。 对照 PR 的原始范围回顾所有之前的轮次，并选择一个结论：CONTINUE、REVERT-AND-SHIP（丢弃已漂移的提交，交付在范围内的提交）或 HAND-OFF（升级给用户）。这是阻止失控机器人审查循环的断路器。
10. 清理过时内容 （父级，收敛后，一次） — 见 10-cleanup.md

收敛由 scripts/02-check-review-status.ps1 计算，为单个 Converged: true 布尔值。在它返回 true 之前不要调用 task_complete；在完成消息中打印证据（HeadOid、LatestCopilotReview.commitOid、submittedAt）。

注意事项

随附的脚本强制执行严格的正确性不变量（通过 copilot_work_started 事件 id 触发落地、Converged 要求 HEAD 匹配 + 零待处理 + HEAD 处的审查、单次迭代回退语义、PR 状态守卫）。信任它们——不要重新推导。以下说明涵盖了脚本无法替你做出的决策：

• 回复每个未关闭的线程；仅当循环拥有处置权时才解决。 对于 fix 和 decline 线程，回复 + 解决。对于 escalate-to-user 线程，回复分析内容但保持线程为 OPEN 状态（08-reply-and-resolve.ps1 -NoResolve），以便人工合并负责人可以对其采取行动。参见 08-reply-resolve.md。
• Copilot 线程由循环拥有；人工 / 高级安全 / 其他机器人线程默认为 escalate-to-user。 自动解决人工审查线程可能会隐藏未处理的问题。评判标准参见 04-triage.md。
• 每轮一个聚焦的提交，而不是每个 PR 一个。 捆绑多轮提交会破坏哪个发现驱动了哪些变更的审计追踪，并破坏 git bisect。参见 07-commit-push.md。
• 使用仓库自身的命令进行构建/测试/lint（依据其 CONTRIBUTING / AGENTS / README / package.json / Makefile），然后再推送修复。发现流程：06-build-test.md。
• 当 Copilot 的发现会为假设的边缘情况而过度设计时，以书面理由进行反驳。 自动接受每一条建议会侵蚀设计——参见 04-triage.md 中的 decline 路径。
• 脚本陷阱（gh api graphql -F 类型强制转换、git stash push -m 位置参数解析、reviewer mutation 的三个 GraphQL 陷阱）记录在 references/api-quirks.md 中。在修改任何脚本之前请先阅读。

故障排查

问题	解决方案
脚本抛出 prerequisite missing — gh CLI is not on PATH	安装 gh（Windows 上 winget install GitHub.cli；macOS 上 brew install gh；Linux 上使用包管理器；或从 https://cli.github.com 下载）。然后执行 gh auth login。将消息呈现给用户并停止循环——不要重试。
脚本抛出 prerequisite missing — gh CLI is not authenticated	运行 gh auth login。停止循环，直到用户完成认证。
触发失败或没有 copilot_work_started 事件落地	推送一个实质性（非空白）提交——synchronize 上的自动分配是最可靠的触发器。持续失败表明 Copilot Code Review 可能未在仓库 / 账户上启用（检查仓库 Settings → Code & automation → Copilot，或账户级别的 Copilot Pro/Pro+）。
等待约 10 分钟后没有新审查	最近驳回后的静默期或琐碎差异抑制。推送一个实质性提交并重试。不要盲目重新运行 01-request-review.ps1——当 Copilot 仍是被请求的审查者时它会报告 InFlight。
打开列表中已过时但未解决的线程	预期行为：未解决状态是事实来源。像处理任何其他打开的线程一样回复 + 解决它们。10-cleanup-outdated.ps1 只是最终的安全网。
不确定是修复还是拒绝某个发现	参见 references/04-triage.md。
需要为"已修复"、"已拒绝"或"漂移"提供回复措辞	参见 templates/ 下的模板——reply-fix.md、reply-decline.md、reply-drift.md、reply-partial.md。

参考

• references/orchestration.md — 横切循环控制：时间盒与延长协议、 子 Agent 委派映射、单次迭代回退，以及循环范围内的 说明。
• 各步骤契约（每个步骤一个 NN-*.md）： references/01-request-review.md （父级）、 references/02-wait.md、 references/03-list-threads.md、 references/04-triage.md（包含 修复与拒绝的评判标准）、 references/05-fix.md、 references/06-build-test.md、 references/07-commit-push.md （父级）、 references/08-reply-resolve.md、 references/09-convergence.md（包含 轮次上限回顾门控）、 references/10-cleanup.md （父级）。
• references/api-quirks.md — 经验证的 GitHub API 行为、死胡同，以及 reviewer mutation 的 GraphQL 陷阱。
• 模板（每种回复类型一个）： templates/reply-fix.md — 接受修复 模式；templates/reply-decline.md — 附理由拒绝模式； templates/reply-drift.md — PR 描述 / 评论 / 测试计划漂移确认； templates/reply-partial.md — 部分修复并延后跟进。横切回复指引 与反模式位于 references/08-reply-resolve.md。
• scripts/_lib.ps1 — 共享辅助函数（Invoke-Gh、 Invoke-GhGraphQL、Resolve-RepoCoords）；由每个 脚本通过 dot-source 引入。
• scripts/01-request-review.ps1 — 触发 Copilot review 并通过 copilot_work_started 事件验证接管。
• scripts/02-check-review-status.ps1 — PR 的 Copilot review 状态的单次快照；仅当三个条件 全部满足时才输出 Converged: true。
• scripts/03-list-open-threads.ps1 — 来自所有 reviewer（Copilot、 人工、github-advanced-security 等）的每个未解决 PR review 线程。
• scripts/08-reply-and-resolve.ps1 — 一次调用即可发布回复并解决。
• scripts/10-cleanup-outdated.ps1 — 针对过时 Copilot 线程的安全网。