spar-with-copilot
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSpar with Copilot
与 Copilot 过招
A round is: get Copilot's review of HEAD, judge each finding against the charter, push one commit. Copilot is a sparring partner, not the author: it finds something almost every round, and the charter is the fixed yardstick that keeps the PR the author's PR. The user steps in only at Finish.
bash
N=$(gh pr view --json number -q .number)
R=$(gh pr view --json url -q .url | cut -d/ -f4,5)
BOT=copilot-pull-request-reviewer # REST login has a "[bot]" suffix, GraphQL login does not一个 轮次 是:获取 Copilot 对 HEAD 的审查,根据 章程(charter) 逐项判断每条发现,然后推送一个 commit。Copilot 是陪练,而不是作者:它几乎每轮都会找出_一些值得讨论的内容_,而章程是固定的衡量标准,确保 PR 仍然是作者的 PR。用户只在结束阶段介入。
bash
N=$(gh pr view --json number -q .number)
R=$(gh pr view --json url -q .url | cut -d/ -f4,5)
BOT=copilot-pull-request-reviewer # REST login has a "[bot]" suffix, GraphQL login does notSetup (once per repo)
设置(每个仓库一次)
Read in the repo. It holds one line, or :
docs/agents/copilot-review.mdrequested-by: agentrequested-by: github- agent — Copilot never reviews on its own. The user runs this skill once they have triaged locally, and you request every review yourself, right after each push.
- github — GitHub starts each review: a ruleset reviews every push, or the user requests it. You only wait.
If the file is missing, ask the user: "Should I request Copilot reviews after each push, or does GitHub (or you) start them?" Write their answer to the file and commit it on its own () before round 1, so no later session asks again.
docs: record who requests Copilot reviews读取仓库中的 。文件中包含一行 或 :
docs/agents/copilot-review.mdrequested-by: agentrequested-by: github- agent — Copilot 从不自行发起审查。用户完成本地分流后运行此 skill;此后,每次 push 后都由你立即自行请求审查。
- github — 每次审查都由 GitHub 发起:ruleset 会对每次 push 进行审查,或者由用户发起。你只需等待。
如果文件不存在,请询问用户:“我应在每次 push 后请求 Copilot 审查,还是由 GitHub(或你)发起审查?”将答案写入该文件,并在第 1 轮开始前单独提交(),这样后续 session 就不会再次询问。
docs: record who requests Copilot reviews0. Write the charter (once)
0. 编写章程(一次)
Read the linked issue (), the PR body and . Write :
Closes #…gh pr diff $N$(git rev-parse --git-dir)/copilot-loop-$N.md- Goal — one sentence, taken from the issue or PR body.
- In scope — the behaviours or claims the PR introduces.
- Non-goals — what the issue/PR leaves out, and adjacent code it visibly chose not to touch.
- Files — , as of now.
gh pr diff $N --name-only - Ledger — one line per decided finding: .
<thread url> fix|decline|escalate <reason>
Show the charter in your reply and carry on. Goal, In scope and Non-goals change only on the user's word.
Done when: the file holds all five sections and Goal cites its source.
读取关联的 issue()、PR body 和 。将以下内容写入 :
Closes #…gh pr diff $N$(git rev-parse --git-dir)/copilot-loop-$N.md- Goal(目标) — 一句话,取自 issue 或 PR body。
- In scope(范围内) — PR 引入的行为或声明。
- Non-goals(非目标) — issue/PR 未涵盖的内容,以及它明显选择不去修改的相邻代码。
- Files(文件) — 的当前结果。
gh pr diff $N --name-only - Ledger(台账) — 每个已裁定发现一行:。
<thread url> fix|decline|escalate <reason>
在回复中展示章程,然后继续执行。Goal、In scope 和 Non-goals 只有在用户明确要求时才能更改。
完成标准:文件包含全部五个部分,且 Goal 引用了来源。
1. Get Copilot's review of HEAD
1. 获取 Copilot 对 HEAD 的审查
bash
SHA=$(gh pr view $N --json headRefOid -q .headRefOid)
REVIEWED=$(gh api repos/$R/pulls/$N/reviews --paginate --jq "[.[] | select(.user.login==\"$BOT[bot]\" and .commit_id==\"$SHA\")] | length")
[ "$REVIEWED" = 0 ] && grep -q "requested-by: agent" docs/agents/copilot-review.md && gh pr edit $N --add-reviewer @copilot
for i in $(seq 15); do
V=$(gh api repos/$R/pulls/$N/reviews --paginate --jq ".[] | select(.user.login==\"$BOT[bot]\" and .commit_id==\"$SHA\") | .body" | grep -m1 -oE '^### (🟢|🟡|🔵).*')
[ -n "$V" ] && break; sleep 60
done; echo "${V:-none}"Verdicts: , , . Reviews have landed anywhere from 8 minutes to hours after a push. If none after 15 minutes, do not request it again or keep polling: go to Finish reporting "no Copilot review for " and ask the user to check the PR on GitHub.
🟢 Approval recommended🟡 Changes recommended🔵 Needs a closer look<sha>bash
SHA=$(gh pr view $N --json headRefOid -q .headRefOid)
REVIEWED=$(gh api repos/$R/pulls/$N/reviews --paginate --jq "[.[] | select(.user.login==\\\"$BOT[bot]\\\" and .commit_id==\\\"$SHA\\\")] | length")
[ "$REVIEWED" = 0 ] && grep -q "requested-by: agent" docs/agents/copilot-review.md && gh pr edit $N --add-reviewer @copilot
for i in $(seq 15); do
V=$(gh api repos/$R/pulls/$N/reviews --paginate --jq ".[] | select(.user.login==\\\"$BOT[bot]\\\" and .commit_id==\\\"$SHA\\\") | .body" | grep -m1 -oE '^### (🟢|🟡|🔵).*')
[ -n "$V" ] && break; sleep 60
done; echo "${V:-none}"审查结论:(建议批准)、(建议修改)、(需要进一步查看)。审查结果可能在 push 后 8 分钟至数小时中的任意时间出现。如果 15 分钟后仍没有审查结果,不要再次请求,也不要继续轮询:进入结束阶段,报告“没有 对应的 Copilot 审查”,并请用户到 GitHub 上检查该 PR。
🟢 Approval recommended🟡 Changes recommended🔵 Needs a closer look<sha>2. Triage every unresolved Copilot thread
2. 分流每个未解决的 Copilot 讨论串
bash
gh api graphql -F owner=${R%/*} -F repo=${R#*/} -F n=$N -f query='query($owner:String!,$repo:String!,$n:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100){nodes{id isResolved isOutdated path line comments(first:1){nodes{databaseId url author{login} body}}}}}}}' \
--jq ".data.repository.pullRequest.reviewThreads.nodes[] | select((.isResolved|not) and .comments.nodes[0].author.login==\"$BOT\")"Each thread gets exactly one verdict:
- fix — a real defect in what this PR adds (a line of its diff, a claim in docs it writes), fixable with Goal and In scope unchanged.
- decline — anything outside the charter: pre-existing code, adjacent hardening, alternative designs, style preference, Non-goals, or Copilot being wrong (cite the code line, test output or source that shows it).
- escalate — real and in scope, but the fix changes behaviour the PR deliberately chose, rests on a fact you can't verify from the repo or a primary source, or would need a file outside Files.
A finding the ledger already decided keeps its verdict; reply with a link to the earlier thread. If Copilot brings new evidence against a ledger entry, escalate it. An thread whose problem is gone from the current code is a fix with nothing to change.
isOutdatedDone when: every unresolved Copilot thread has a ledger line.
bash
gh api graphql -F owner=${R%/*} -F repo=${R#*/} -F n=$N -f query='query($owner:String!,$repo:String!,$n:Int!){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100){nodes{id isResolved isOutdated path line comments(first:1){nodes{databaseId url author{login} body}}}}}}}' \
--jq ".data.repository.pullRequest.reviewThreads.nodes[] | select((.isResolved|not) and .comments.nodes[0].author.login==\\\"$BOT\\\")"每个讨论串恰好给出一个裁定:
- fix — 本 PR 新增内容中存在真实缺陷(其 diff 中的一行代码,或它写入文档的一项声明),且可以在不改变 Goal 和 In scope 的情况下修复。
- decline — 章程之外的任何事项:既有代码、相邻加固、替代设计、样式偏好、Non-goals,或者 Copilot 判断错误(需引用代码行、测试输出或来源作为依据)。
- escalate — 问题真实且在范围内,但修复会改变 PR 有意选择的行为、依赖仓库或一手来源无法核实的事实,或者需要修改 Files 之外的文件。
如果台账中已对某个发现作出裁定,就沿用该裁定;回复时附上先前讨论串的链接。如果 Copilot 针对台账中的某项裁定提出新证据,则将其升级为 escalate。如果某个 讨论串中的问题已不再存在于当前代码中,则裁定为 fix,但无需做任何更改。
isOutdated完成标准:每个未解决的 Copilot 讨论串都在台账中有一行记录。
3. Apply the round
3. 执行本轮更改
- Make each fix the smallest change that removes the defect. Tests for changed lines may land in new files; any other new file turns the finding into an escalate.
- Run the repo's tests and linters for the touched code.
- One commit , push.
fix(<scope>): address Copilot review round <k> - Reply to each fix and decline thread, then resolve it. Escalate threads stay open, without a reply.
bash
gh api repos/$R/pulls/$N/comments/<databaseId>/replies -f body="Fixed in <sha>: …" # or "Declined: <reason>"
gh api graphql -f query='mutation{resolveReviewThread(input:{threadId:"<id>"}){thread{isResolved}}}'- 对每个 fix,以消除缺陷所需的最小改动进行修复。变更行对应的测试可以放在新文件中;任何其他新文件都会使该发现转为 escalate。
- 运行仓库中与改动代码对应的测试和 linter。
- 创建一个 commit:,然后 push。
fix(<scope>): address Copilot review round <k> - 对每个 fix 和 decline 讨论串逐一回复,然后将其解决。escalate 讨论串保持打开,不回复。
bash
gh api repos/$R/pulls/$N/comments/<databaseId>/replies -f body=\"Fixed in <sha>: …\" # or \"Declined: <reason>\"
gh api graphql -f query='mutation{resolveReviewThread(input:{threadId:\"<id>\"}){thread{isResolved}}}'4. Loop or stop
4. 循环或停止
Go back to step 1 for the new HEAD, unless one of these holds — then Finish:
- converged — Copilot's review of HEAD is 🟢 and triage produced no fixes, or any round produced zero fixes (no push, so no new review).
- escalations pending — this round's fixes are pushed; the escalations go to the user. Resume at step 2 once they answer.
- round 5 done — Copilot is not converging; the user decides whether to continue.
针对新的 HEAD 返回步骤 1,除非出现以下情况——此时进入结束阶段:
- converged(已收敛) — Copilot 对 HEAD 的审查为 🟢 且分流未产生任何 fix,或者某一轮未产生任何 fix(没有 push,因此也不会有新的审查)。
- escalations pending(有待处理的升级项) — 本轮 fix 已推送;将 escalate 交给用户。用户答复后,从步骤 2 继续。
- round 5 done(第 5 轮完成) — Copilot 尚未收敛;由用户决定是否继续。
Finish
结束
Reply with:
- the PR URL, the last verdict and the number of rounds;
- each escalation: its thread URL and the question the user must answer;
- declined findings worth a follow-up: thread URL and one line each. Open issues only if the user asks.
回复中包含:
- PR URL、最近一次审查结论和轮次数;
- 每个 escalate:讨论串 URL,以及用户必须回答的问题;
- 值得后续跟进的 decline:讨论串 URL 和一行说明。只有在用户要求时才新建 issue。