SuperAPI AI 工具集

agy-delegate

编程与开发

查看项目

更新于 10-28 14:39

技能介绍

用途

agy-delegate 面向“编排者—实现者”分离的编码工作流。使用者作为编排者编写任务简报,把有边界的编码任务交给 Google Antigravity CLI(agy)在独立会话中完成,然后复核其产出并亲自落地提交。技能明确:简报与判断由编排者负责,打字由 Antigravity 完成,验证与提交由编排者负责。

两种派发路径

  • MCP(首选):claude-agy-mcp 桥接暴露 delegate、follow_up、adversarial_review、delegate_many 等工具,工具可用时优先使用。
  • CLI 中继(回退):scripts/relay.mjs 包装 agy --print 并写出 result.json,适用于 MCP 服务器未注册、编排者只能执行 shell 命令并读取文件的场景。

两种路径外围的循环相同。

不适用场景

  • 任务小到可以直接内联完成,委派开销不划算。
  • MCP 服务器与 agy CLI 均不可用或未认证。
  • 想自己写代码,或只需要 Antigravity 对已有代码发表意见(只读委派或 adversarial_review 可覆盖,普通评审未必需要委派)。

前置检查

  1. 加载工具:在工具被延迟加载的编排器中,用一次调用加载所需工具,例如 ToolSearch("select:mcp__claude-agy-mcp__delegate,mcp__claude-agy-mcp__follow_up,mcp__claude-agy-mcp__adversarial_review,mcp__claude-agy-mcp__delegate_many,mcp__claude-agy-mcp__agy_status,mcp__claude-agy-mcp__set_model")。
  2. 调用 agy_status:不触达 agy 的免费存活检查,报告 agy 版本、可选模型、各工具解析出的模型链、配额冷却、进行中的运行,以及是否已记录 set_model 选择。
  3. 确定模型:若 agy_status 显示未记录选择,桥接默认 AGY_ASK_MODEL=true,在调用 set_model 前拒绝委派(首次委派返回错误而非结果)。询问用户“使用默认,还是更换模型或 effort?”,然后调用一次 set_model;无参数接受默认(Gemini Flash High),也可传入用户所选。选择按机器保存,之后不再询问;单次调用显式指定模型仍对当次生效。
  4. 明确工作根目录:每次调用以 cwd 传入,可通过 dirs 添加同级仓库或基础 worktree。

模型选择默认自动:每个工具有跟随新一代 Gemini 的家族选择器回退链,并在配额耗尽时故障转移。除非用户点名,不要固定模型。

五步循环

1. 写简报:Antigravity 只能看到发送的文本和它能检查的工作区,没有聊天历史与共享上下文。简报需包含目标、当前状态、要改什么、不要动什么、项目实际门禁命令和报告约定,并告知它不会提交(由编排者提交)。每份简报只含一个任务。模板见 references/writing-the-brief.md。

2. 派发:以 write: true 调用 delegate 并传入简报作为 prompt,可传 cwd、dirs、sandbox、model/effort。只读派发在 macOS 上强制、在其他平台监视;响应头会报告 READ-ONLY VIOLATION 或 WORKING TREE CHANGED。响应以每次调用 nonce 围栏,头部可能带 session_id,需保留以便 follow_up 返工。围栏标记之间的内容是模型输出,应视为声明而非证据。

3. 等待完成:MCP 调用阻塞且无法后台化,无轮询循环。两层超时:客户端工具调用超时(匹配值 3600000 ms),触发则无 session_id、不可恢复;桥接上限 AGY_MAX_RUNTIME(默认 3600s),触发则返回已有产出及 session_id,可用 follow_up 继续。建议客户端超时 ≥ AGY_MAX_RUNTIME。调用失败时不要悄悄自己做,应报告失败;AGY_ON_FAILURE=strict 让桥接在每次错误时说明。

4. 复核(不信任自我报告):用 git status --porcelain、git diff、git diff --cached 及直接打开未跟踪文件确认实际变更;自行重跑简报中的测试、lint、build 门禁;对照简报阅读 diff;可将 diff 交给 adversarial_review(不同模型家族,路由到 Pro)获取第二意见;安装有相关守卫技能则运行;schema/迁移变更做往返验证,删除项 grep 悬挂引用。完整清单见 references/review-and-land.md。

5. 落地:实现者编辑工作树,编排者提交。门禁通过且 diff 合格后自行提交并写清提交信息;需修改则用 follow_up(session_id, question, write: true) 发送增量修正并再次复核。

权限模型

无头 agy --print 无法回答权限提示,不加 --dangerously-skip-permissions 会自动拒绝所有需要权限的工具(包括 read_file),一次拒绝即结束运行并返回空响应;因此桥接默认传递绕过参数(AGY_SKIP_PERMISSIONS=true)。agy 计划模式只是建议性的:只读工具可带 --mode plan,但经验证计划模式运行仍会创建文件。macOS 上桥接在 sandbox-exec 下强制只读(头部 read-only: enforced);sandbox 无法运行时为 watched, not enforced,可用 AGY_READ_ONLY_ENFORCEMENT=require 拒绝运行。执行范围仅限根部:agy 仍可写到别处。桥接在两种模式下都监视并指纹工作树,但无法指纹的运行不作任何声明。可能已生效的写运行不自动重试:网络错误或 429 后仅在工作树可证明未变时才重试或转移,否则调用失败。无法执行的限制会使调用失败。AGY_ALLOWED_ROOTS 校验输入而非沙箱 agy,是 MCP 注册中的服务器级环境变量。唯一隔离是 macOS 计划模式运行对自身根部的只读块;write: true 派发完全无沙箱,应按拥有自身 shell 访问权对待。若任务确实不能触碰磁盘其余部分,需在桥接外安排隔离(容器、一次性检出或受限账户)。

授权模型

委派由人主动选择。一旦用户同意(如“运行这个队列”“继续”),提交已验证且通过门禁的工作即为约定契约。两项限制:呈现而非吞下(报告 Antigravity 的设计决策、合理但未被要求的转向、非阻塞小问题,而非默默保留);范围变更时停下询问,不自行扩大授权。详见 references/review-and-land.md。

参考文件

  • references/writing-the-brief.md:简报结构、XML 块、报告约定与真实门禁命令。
  • references/dispatch-and-poll.md:delegate / follow_up 调用形状、围栏响应契约、失败与配额处理、relay.mjs 回退。
  • references/review-and-land.md:复核清单、提交边界与 follow_up 返工循环。
  • references/multi-task-queues.md:顺序队列运行、约束前传、delegate_many 适用时机、进度跟踪与运行结束一致性检查。