copilot

copilot

驱动 GitHub Copilot CLI 和编码 Agent。提供三种模式：

模式	调用方式	用途
review	/copilot review <pr>	审查 PR，并通过行内评论将修复任务交给 Copilot。
delegate	/copilot delegate <task>	创建 gh agent-task，并持续监控，直到它生成 PR。
setup	/copilot setup	一次性初始化 .github/copilot-instructions.md 等文件。

日常工作使用 review 和 delegate。只有当用户明确说出“copilot setup”“generate copilot instructions”或“bootstrap copilot for this repo”时，才阅读 references/setup.md——日常的 review/delegate 工作切勿阅读该文件，因为它会加载约 12 KB 与这些模式无关的仓库初始化内容。

模式选择

将第一个位置参数解析为模式。如果未提供模式，则通过运行环境的交互式提示机制询问用户想要哪种模式；如果没有该机制，则用纯文本询问并等待回答。切勿静默地使用默认模式——每种模式的副作用都大不相同。

第一个参数	模式
review（后面可选 PR 编号 / URL）	review
delegate 后接任务描述	delegate
setup	setup（加载 references/setup.md）
裸 PR URL（https://github.com/...）	review
其他任何内容（裸整数、有歧义、缺失）	通过运行环境的提示机制询问

裸整数具有歧义——它可能是 PR 编号、gh agent-task ID，也可能只是无关内容。在假定为 review 模式前，务必先询问。

模式：review

审查 PR，并以可供 Copilot 执行的行内审查评论形式发布修复建议。

阶段 1：获取 PR 上下文

确定 PR 编号。如果参数是 PR URL，则提取编号。 如果传入的是裸整数，则向用户确认它是 PR 编号（它也可能是 gh agent-task ID）。如果未提供编号，则运行 gh pr list 并询问用户要审查哪个 PR。

PR=<number>
gh pr view "$PR" --json title,body,author,baseRefName,headRefName,url,number,additions,deletions,changedFiles
gh pr diff "$PR"
OWNER_REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
gh api "repos/${OWNER_REPO}/pulls/${PR}/files" \
  --jq '.[] | {filename, status, additions, deletions, patch}'

继续之前，先简要总结（标题、作者、base ← head、变更文件数、 新增 / 删除行数）。

阶段 2：执行审查

调用运行环境提供的任意代码审查技能（例如 age、 code-review 或类似技能）。审查必须给出带置信度评分的发现，以便 阶段 3 进行分类。如果没有可用的审查技能，请在继续之前让用户指定一个——不要自行猜测发现。

阶段 3：对发现进行分类，供 Copilot 处理

为每项发现指定处理方式：

• COPILOT_FIX — Copilot 可以处理的直接修复（添加验证、 修复逻辑、删除无用代码、将包装函数内联，或移除仅重复函数名的文档字符串）。
• FUTURE_TASK — 需要更广泛的上下文、架构决策或涉及多个文件的重构。

按文件展示表格：

### path/to/file.ts

| # | Score | Line | Category | Issue                       | Disposition |
|---|-------|------|----------|-----------------------------|-------------|
| 1 | 95    | 42   | BUG      | Null check missing          | COPILOT_FIX |
| 2 | 80    | 78   | COUPLING | Domain imports HTTP client  | FUTURE_TASK |

然后展示每项的完整评论正文。

COPILOT_FIX 正文：

**[CATEGORY]**: <issue description>

**Why this matters:** <teaching moment — the principle behind the fix>

@copilot fix this

FUTURE_TASK 正文：

**[CATEGORY]**: <issue description>

**Why this matters:** <teaching moment — the principle behind the suggestion>

_Noted for future work — not a Copilot fix._

询问用户要发布哪些、跳过哪些、编辑哪些，以及是否需要更改任何分类。未经明确批准，绝不发布。

阶段 4：发布审查

构建单个审查载荷并提交：

cat > /tmp/copilot-review-payload.json <<'JSON'
{
  "body": "Automated review — items marked for @copilot are actionable fixes.",
  "event": "COMMENT",
  "comments": [
    {
      "path": "path/to/file.ts",
      "line": 42,
      "side": "RIGHT",
      "body": "**BUG**: Null check missing...\n\n@copilot fix this"
    }
  ]
}
JSON
gh api --method POST \
  "repos/${OWNER_REPO}/pulls/${PR}/reviews" \
  --input /tmp/copilot-review-payload.json
rm -f /tmp/copilot-review-payload.json

打印摘要：发布总数、COPILOT_FIX 数量、FUTURE_TASK 数量、 PR 链接。

Review 模式规则

• 未经用户批准，绝不发布。
• 用业务角度描述问题——切勿说“此函数处理数据”。
• 每个问题只写一条评论——重复问题请注明“相同模式也出现在第 X、Y、Z 行”。
• 遵循代码库的现有做法——不要指出与已有一致的模式。
• 所有审查判断均来自审查子技能；此模式只负责获取 PR 并按 Copilot 格式整理评论。

模式：delegate

创建 gh agent-task，轮询检查，直到 Copilot 编码 Agent 创建 PR，然后可选择交接给 review 模式。

Copilot 模型约束

编码 Agent 使用 Auto 模型选择。CLI 没有 --model 标志。请优化任务描述：

• 明确具体地说明预期行为。
• 严格限定范围。每次委派只处理一项聚焦的任务。
• 指明文件和符号。“在 src/auth/login.ts 中，validateToken 应该……”
• 列出验收标准。“邮箱为空时返回 400，格式错误时返回 422。”
• 说明约束。参考现有模式（例如 AppError）。
• 省略原因。编码 Agent 需要知道做什么、在哪里做，而不是为什么做。

与用户确认任务时（阶段 1 步骤 3），根据这些标准检查描述。若描述含糊或不够具体，请提出明确的改进建议。

阶段 1：创建 Agent 任务

1. 如果用户未提供任务描述，请询问要委派什么任务。
2. 获取仓库上下文：gh repo view --json nameWithOwner --jq '.nameWithOwner'。
3. 创建任务前与用户确认：显示任务描述和目标仓库，并询问是否需要使用非默认基础分支。
4. 创建任务：gh agent-task create "<task description>"。
5. 使用 gh agent-task list --limit 1 获取任务引用。解析制表符分隔的行（description \t #PR \t repo \t status \t timestamp），并提取 PR 编号和状态。
6. 向用户确认：任务描述、PR 编号、状态和链接（https://github.com/<repo>/pull/<number>）。

阶段 2：监控任务完成情况

每 90 秒轮询一次，最长等待 15 分钟。

sleep 90
gh agent-task list --limit 5

找到与已获取的 PR 编号匹配的行。根据状态执行相应操作：

• In progress / Working — 打印一行状态更新，并注明已用时间。继续轮询。
• Ready for review / Completed — 结束轮询并进入阶段 3。
• Failed / Error — 使用 gh agent-task view <PR#> 显示详情，然后停止。

若达到 15 分钟超时，请告知用户任务仍在运行，提供 PR 链接，并询问是再等待 10 分钟，还是停止并稍后查看。

阶段 3：审查 PR

打印完成摘要（PR 编号、链接、最终状态、已用时间），并询问“对 PR #N 运行 /copilot review 吗？”。如果用户同意，使用 PR 编号以审查模式调用此技能。如果用户不同意，打印链接并退出。

委派模式规则

• 创建前务必确认。用户必须批准任务和仓库。
• 轮询状态更新保持精简——每次检查只输出一行。
• 遇到错误立即停止。如果 gh agent-task create 失败，请显示错误并停止。
• 切勿猜测 PR 编号——务必解析 gh agent-task list 的输出。

模式：setup

setup 是一次性引导流程，会创建 .github/copilot-instructions.md 和 .github/instructions/ 下按语言和角色划分的文件。

对于仅编写或审查指令文件的工作——添加或完善 .github/copilot-instructions.md 和 .github/instructions/*.instructions.md，且不执行审查或委派——请改用 /github-copilot-repo-instructions；此处的 setup 模式用于从头开始引导。

请参阅 references/setup.md——仅在用户明确说“copilot setup”“generate copilot instructions”或“bootstrap copilot for this repo”时阅读。该文档包含完整的操作指南：项目类型检测、工具检测、覆盖门控、全局指令模板、代码审查指令模板、特定语言的存根以及编码 Agent 指令。加载该文档会占用约 12 KB 的上下文，与常规 review / delegate 工作无关。

此技能绝不会执行的操作

• 提交代码、运行 git push 或创建 PR——这些由 /plate 负责。
• 合并 PR——这由 /gh 负责。
• 自行生成代码审查——review 模式会委派给环境提供的审查技能（例如 age、code-review）。
• 在 setup 期间修改 .github/ 之外的任何文件。
• 未经用户明确批准便发布审查评论。