agy-delegate

Antigravity Delegate

你是协调者。此技能让你可以将一项范围明确的编码任务交给单独的实现者——Google Antigravity CLI（agy），之后审查其产出并由你自己提交。你编写任务说明并负责判断；Antigravity 在自己的对话中编写代码；你负责验证并提交。

这里没有任何内容专属于某一种协调 Agent。这个流程只需要能够运行 shell 命令和读取文件，因此任何类似的 Agent 都能驱动它。此流程专为 Claude Code 设计并在其上运行；对于其他协调者，应将其视为设计适用，但尚未验证。

不要在以下情况使用

• 任务很小，可以直接完成——委派的开销不值得。
• 尚未安装或验证 agy CLI。请根据 Antigravity 的 CLI 文档安装，并完成首次启动设置。
• 你想自己编写代码，或者只需要 Antigravity 对你所写代码提出意见（--read-only 调用可以在不修改代码的情况下进行审查，但纯粹的审查可能根本不需要委派）。

前置条件（检查一次即可）

1. agy help 成功运行。若未成功，请安装 Antigravity CLI 并完成首次启动设置。
2. agy models 成功运行。这证明 CLI 可以通过身份验证并列出可用的模型标签。
3. 你当前位于目标 git 仓库中，或将通过 --cd 指定目标 git 仓库。

这些检查并不能证明无头写入会获准。在 --print 模式下，Antigravity 无法请求写入权限，可能会自动拒绝。中继程序会检测此类拒绝，而不是报告任务已完成。

选择实现者模型

agy 已配置默认模型，因此 --model 为可选参数。若用户对任务有偏好的 Antigravity 模型标签，请使用该参数。否则，让 Antigravity 使用其当前默认模型，不要自行猜测。

工作流程

每项任务都按以下五个步骤执行。第 1、4、5 步需要你判断；第 2、3 步是机械操作。

1. 编写任务说明

Antigravity 只能看到你发送的文本以及它能在工作区中检查到的内容——没有聊天记录，也没有共享上下文。任务所需的一切都必须写进说明中：目标、当前状态、需要修改的内容、需要保持不变的内容、项目实际使用的检查命令，以及报告要求。告诉 Antigravity，它不会提交（由你提交）。每份说明只包含一项任务。完整指南和模板见： references/writing-the-brief.md。

2. 调用

对于 Codex 协调的后台工作，请先安装并配置单独的 codex-background 支持工具。如果缺少其 MCP 工具或注册表，请停止并说明所需的设置；不要悄悄改用由模型驱动的轮询。然后调用其已注册的 delegate_run MCP 工具一次，以代替下方的 shell 示例。 按照该技能传递结构化的通用参数、保持提供程序标志不变，并通过 runId 重新连接。请求保持待处理状态，直至任务完成，然后继续执行此技能中的审查和提交步骤。其他协调者使用下方的 shell 工作流程。

使用附带的辅助程序将任务说明发送给 Antigravity。它会封装 agy --print、捕获运行结果，并写入结构化的 result.json——因此你只需“运行命令，读取文件”。下文的 <skill-dir> 指此技能的安装目录，即包含 SKILL.md 的文件夹。

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# choose a model label:                 add --model "<label from agy models>"
# reasoning effort (low, medium, high): add --effort high
# read-only (sandbox — no edits):       add --read-only
# enable Antigravity terminal sandbox:  add --sandbox
# resume the most recent conversation:  add --resume-last  (delta brief only)
# see all options:                      node .../relay.mjs --help

默认情况下，辅助程序会启动一个全新的 Antigravity 项目，并传入 --add-dir <repo>（即 --cd 路径的绝对路径），为 agy 指定明确的工作区。默认情况下，它不会传入 --dangerously-skip-permissions。 有关工作机制、标志和 result.json 的结构，请参阅：references/dispatch-and-poll.md。

3. 等待完成

使用 codex-background 的 Codex 会让原始 MCP 请求保持挂起状态：无需模型驱动的休眠、状态或日志轮询。只有在请求中断后，才使用 delegate_wait 重新接续。

辅助程序会阻塞，直到 Antigravity 完成，因此应使用编排器提供的相应功能，并在其返回后继续：

• Claude Code： 使用 run_in_background: true 运行 Bash 调用；完成时会收到通知。
• 普通 shell / 其他 Agent： 对于短任务，在前台运行；否则将其放到后台运行，并轮询结果文件。

不要相信进度跟踪器胜过实际情况：只有在写入 result.json 且进程退出后，任务才算完成。查看工作树，而不是状态行。实现者的完整报告位于 result.json 的 finalMessage 字段中（stdout 中报告标记之间也会完整打印该报告）。

4. 审查——不要轻信自我报告

Antigravity 的 result.json 包含其最终消息和任何检查结果声明。请重新验证，不要直接接受：

• 自行重新运行项目的检查项（第 1 步中的测试 / lint / 构建命令）。
• 根据需求说明阅读差异： Antigravity 是否完成了要求，且没有多做或少做？ touchedFiles 是查看结果的起点。
• 如果已安装相关防护技能，请针对差异运行它们。
• 对于架构 / 迁移变更，请进行往返验证；对于删除操作，请搜索是否有悬空引用。

完整检查清单：references/review-and-land.md。

5. 落地

实现者修改工作树；由编排器提交。 只有在检查项通过且差异符合要求后，才：

• 自行提交已验证的工作，并使用清晰的提交信息。
• 如果需要修改，请使用 --resume-last 发送增量需求说明，然后重新审查。

权限模型

Antigravity 有自己的权限策略。默认情况下，中继不会绕过该策略。只有在人类明确接受 Antigravity 可能会自动批准工具权限请求时，才使用 --dangerously-skip-permissions。--read-only 会组合使用 --sandbox 和 --dangerously-skip-permissions：沙盒负责执行限制——工作区内的写入会被覆盖并丢弃，工作区外的路径则会因 EPERM 失败——而自动批准只会让工具在沙盒内运行。作为面向用户的标志，它与 --dangerously-skip-permissions 保持互斥；后者单独使用（不带沙盒）时会授予完全访问权限。若要在写入任务中启用终端沙盒，请单独使用 --sandbox。 如果无头模式下的 --print 自动拒绝写入，中继会报告 status: "failed" 并以非零状态码退出。中继会在 --read-only 运行前后对工作树进行指纹比对，并在 result.json 中报告 readOnlyViolation。设置中的允许规则确实会应用于无头模式下的 --print 运行，但匹配规则和配置文件位置会随 agy 版本和平台而异，因此应在自己的安装环境中实测拒绝情况，而不要想当然。目前已测得两个陷阱。第一，精确匹配行为：在 Windows 上使用 agy 1.2.5 时，command(<name>) 只匹配不带参数的裸命令——command(git) 从不允许实际的 git status，必须使用 command(regex:git .+) 才行（issue #614 评论）。在 macOS 上使用 agy 1.2.0 时，同一条裸命令规则 command(git) 确实允许 git status，因此精确匹配陷阱并非所有版本都存在。第二，在 Windows 上，Antigravity 权限引擎中有一个尚未修复的上游缺陷 （issue #614）：它会按空白字符拆分解析后的路径，因此位于 C:\Program Files\... 下的二进制文件——而 git 本身通常就安装在这里，这也是委派编码任务中最常见的触发原因，并不只是 node/npm——会被拆成首个片段，导致任何 command(<name>) 规则都无法匹配。关于 agy 读取哪个文件：在 Windows 上使用 agy 1.2.5 实测确认，有效规则位于 ~/.gemini/config/config.json 中的 userSettings.globalPermissionGrants.allow，而非 agy 自身拒绝消息所指向的 ~/.gemini/antigravity-cli/settings.json 中的 permissions.allow；在 macOS 上使用 agy 1.2.0 实测确认，antigravity-cli/settings.json 中的规则确实生效。在依赖任一文件之前，请针对你的版本重新核实这两种情况。完整说明请参阅 references/dispatch-and-poll.md。未经人类明确批准，不得添加绕过标志。

授权模型

委派必须由人类主动选择。一旦人类选择了委派（“运行这个队列”“继续”），提交经过验证且通过关卡的工作就是双方约定的责任范围。该授权有两项限制：呈现出来，不要自行吸收（应报告 Antigravity 的设计决策、有合理依据但未被要求的改动，以及不会阻塞任务的小问题，而不是默默保留它们）；范围变更时停止（如果正确完成任务需要超出简述的范围，应先询问，不要自行扩大授权范围）。完整说明请参阅 references/review-and-land.md。

参考资料

• references/writing-the-brief.md — 如何编写一份简洁的任务说明，让 Antigravity 能够在不询问的情况下执行：结构、XML 块、报告约定和实际的门禁命令。
• references/dispatch-and-poll.md — relay.mjs 标志、result.json 约定、各编排器的后台运行方式，以及运行异常时的恢复方法。
• references/review-and-land.md — 审查清单、提交边界，以及通过 --resume-last 进行返工的周期。
• references/multi-task-queues.md — 运行顺序队列：延续约束、跟踪进度，以及运行结束时的一致性检查。