spar-with-copilot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spar 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 not

Setup (once per repo)

设置(每个仓库一次)

Read
docs/agents/copilot-review.md
in the repo. It holds one line,
requested-by: agent
or
requested-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 (
docs: record who requests Copilot reviews
) before round 1, so no later session asks again.
读取仓库中的
docs/agents/copilot-review.md
。文件中包含一行
requested-by: agent
或
requested-by: github
:
  • agent — Copilot 从不自行发起审查。用户完成本地分流后运行此 skill;此后,每次 push 后都由你立即自行请求审查。
  • github — 每次审查都由 GitHub 发起:ruleset 会对每次 push 进行审查,或者由用户发起。你只需等待。
如果文件不存在,请询问用户:“我应在每次 push 后请求 Copilot 审查,还是由 GitHub(或你)发起审查?”将答案写入该文件,并在第 1 轮开始前单独提交(
docs: record who requests Copilot reviews
),这样后续 session 就不会再次询问。

0. Write the charter (once)

0. 编写章程(一次)

Read the linked issue (
Closes #…
), the PR body and
gh pr diff $N
. Write
$(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 —
    gh pr diff $N --name-only
    , as of now.
  • 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(
Closes #…
)、PR body 和
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:
🟢 Approval recommended
,
🟡 Changes recommended
,
🔵 Needs a closer look
. 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
<sha>
" and ask the user to check the PR on GitHub.
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}"
审查结论:
🟢 Approval recommended
(建议批准)、
🟡 Changes recommended
(建议修改)、
🔵 Needs a closer look
(需要进一步查看)。审查结果可能在 push 后 8 分钟至数小时中的任意时间出现。如果 15 分钟后仍没有审查结果,不要再次请求,也不要继续轮询:进入结束阶段,报告“没有
<sha>
对应的 Copilot 审查”,并请用户到 GitHub 上检查该 PR。

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
isOutdated
thread whose problem is gone from the current code is a fix with nothing to change.
Done 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。如果某个
isOutdated
讨论串中的问题已不再存在于当前代码中,则裁定为 fix,但无需做任何更改。
完成标准:每个未解决的 Copilot 讨论串都在台账中有一行记录。

3. Apply the round

3. 执行本轮更改

  1. 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.
  2. Run the repo's tests and linters for the touched code.
  3. One commit
    fix(<scope>): address Copilot review round <k>
    , push.
  4. 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}}}'
  1. 对每个 fix,以消除缺陷所需的最小改动进行修复。变更行对应的测试可以放在新文件中;任何其他新文件都会使该发现转为 escalate。
  2. 运行仓库中与改动代码对应的测试和 linter。
  3. 创建一个 commit:
    fix(<scope>): address Copilot review round <k>
    ,然后 push。
  4. 对每个 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。