claude-agy-mcp

User → Claude Code → claude-agy-mcp (MCP) → agy CLI → Gemini 3.8 Flash / Pro / Claude
                   ←                      ←         ← (Clean answers only)

为什么为 Claude Code 选择 Gemini Flash？

Gemini Flash 是 Google 最智能的编程和 Agent 执行主力模型。它具备深入的多步规划能力、严谨的终端推理能力，以及很高的首次代码准确率。

Gemini 3.8 Flash（High）是所有工具的默认模型。 每条调用链都优先使用 gemini-flash@latest-high，它会通过 agy models 解析为最新的 High effort Flash——截至 2026-09-11 为 3.8 Flash——只有在 Flash 不可用或处于冷却期时才会回退到 Pro 或 Claude。下方的基准测试表将 3.8 Flash 与 3.7 Flash 进行比较，数据来自Google 的发布表（2026-09-02）；该桥接不会固定到这一代模型。

基准测试亮点

基准测试 / 能力	Gemini 3.8 Flash（High）	上一代（3.7 Flash）	优势
DeepSWE v1.1	73.7%	65.3%	+8.4 pts 的长周期软件工程能力；与 Claude Opus 5 的差距仅为 0.3
Terminal-Bench 2.1	89.4%	85.8%	+3.6 pts 的 Agent 式 CLI 执行能力；领先 Opus 5（89.1%）和 GPT-5.6 Sol
OSWorld-2.0	59.0%	50.6%	+8.4 pts 的 Agent 式计算机使用能力
HLE-Verified	54.9%	53.6%	多步骤专家级推理能力，领先 Opus 5（54.4%）
Vals Finance Agent v2	61.4%	59.0%	在量化 Agent 工作方面领先 Opus 5（58.6%）和 GPT-5.6 Sol（53.8%）
Token 经济性	$0.75 / $3.75（1M）	$0.75 / $3.75	与 3.7 Flash 价格相同；比 Claude Opus/Sonnet 便宜多达 10x–20x

Token 与上下文倍增效应

当 Claude Code 直接分析包含 4,000 行内容的数据库转储文件，或在 git 历史记录中 grep 20 个文件时，这数千行内容会永久留在 Claude 的提示词上下文中，推高成本并促使你进行上下文压缩。

使用 claude-agy-mcp：

1. Claude 调用 analyze_files 或 deep_search。
2. Gemini 3.8 Flash 通过 agy 独立处理 100k+ 个 token。
3. 只有精确的代码级发现和行号引用会返回到 Claude 的提示词中。
4. 后续问题通过 follow_up 复用同一 agy 会话，无需重新发送任何文件。

---

终极 AI 工程 MCP 技术栈

claude-agy-mcp 旨在成为现代 AI 工程师 MCP 工具包的核心，并与互补的专用服务搭配使用：

┌─────────────────────────────────────────────────────────────────────────────┐
│                             Claude Code (Agent)                             │
└──────┬──────────────────────┬───────────────────────┬───────────────────────┘
       │                      │                       │                       │
       ▼                      ▼                       ▼                       ▼
┌──────────────┐      ┌──────────────┐        ┌──────────────┐        ┌──────────────┐
│claude-agy-mcp│      │   context7   │        │  firecrawl   │        │    tavily    │
│  (Gemini 3.8 │      │(Official Docs│        │(Web Scraping │        │(Live Search  │
│  Delegation) │      │  & API Specs)│        │  & Crawling) │        │ & Research)  │
└──────────────┘      └──────────────┘        └──────────────┘        └──────────────┘

MCP 服务	核心优势	Claude 的使用场景
claude-agy-mcp	重型计算与编码任务委派	分析超过 200 行的文件、挖掘代码仓库历史（git log/diff/blame）、对抗式代码审查，以及通过 Gemini 3.8 Flash 执行原始代码。
context7	最新官方文档	获取库（Next.js、React、Tailwind、Prisma、Vite 等）最新且版本准确的 API 签名和文档，以消除对 API 的幻觉。
firecrawl	整洁的网页抓取与爬取	将动态网页、文档网站和 GitHub 代码仓库转换为整洁、适合大模型处理的 Markdown 或结构化 JSON。
tavily	快速实时搜索与信息验证	低延迟网页搜索、最新新闻、错误消息查询和技术研究。

推荐的 MCP 配置（.agents/mcp_config.json 或 Claude Code）

{
  "mcpServers": {
    "claude-agy-mcp": {
      "command": "npx",
      "args": ["-y", "@pymodel/claude-agy-mcp"],
      "timeout": 3600000
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"]
    },
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"]
    }
  }
}

---

为什么选择它，而不是 claude-to-agy？

	claude-to-agy	claude-agy-mcp
工具范围	1 个通用的 delegate_to_agy	8 个专用工具 — Claude 可以可靠地自行选择工具
模型选择	无（仅使用 agy 默认模型）	按工具选择模型系列，随新一代模型更新，并支持配额故障转移
多轮对话	无状态	保持会话连续性 — follow_up 可继续 agy 对话，无需重新发送上下文
输出安全	无限制	可配置截断上限，保护 Claude 的上下文
沙盒	不支持	在 macOS 上，禁止只读工具写入工作区；也可选择启用 --sandbox
结果真实可靠	仅提供退出代码	根据 agy 的 JSON 信封作出判断 — 报告自动拒绝的工具操作，而不是将其隐藏
安装	uvx（Python）	npx（Node）— 无需安装

要求

• Node.js 18+
• 已安装并完成身份验证的 Antigravity CLI（agy）
• Claude Code

安装

# 1. Register the MCP server (user scope = all projects).
#    add-json bakes in a generous client-side timeout so long analyze_files /
#    delegate calls don't trip Claude Code's tool-call deadline (see Timeouts).
claude mcp add-json -s user claude-agy-mcp \
  '{"type":"stdio","command":"npx","args":["-y","@pymodel/claude-agy-mcp"],"timeout":3600000}'

# 2. Install the bundled skills into every agent found on this machine.
#    The server gives an agent the tools; the skills tell it when to use them.
npx --package @pymodel/claude-agy-mcp claude-agy-mcp-install-skills
#    --list to preview, --dir <path> to install somewhere explicit,
#    --force to replace a skill you have symlinked to your own checkout.

# 3. Optional: add delegation rules to your project (or ~/.claude/CLAUDE.md).
curl -o CLAUDE.md https://raw.githubusercontent.com/PyModel/claude-agy-mcp/main/CLAUDE.md

内置技能

安装此包时也会一并安装技能，因此无需单独复制或保持同步：

技能	功能
agy-delegation	路由规则：该使用哪个工具，以及何时委派比在当前上下文中自行完成工作更合适。
agy-delegate	完整的委派与审查工作流 — 编写 agy 无需额外说明即可执行的任务简报、分派任务、对照简报审查差异，并由你亲自提交结果。还包括 CLI 中继回退方案，供无法调用 MCP 工具的 Agent 使用。

"timeout": 3600000（60 分钟，单位为毫秒）是客户端的工具调用截止时间，与桥接服务的默认 AGY_MAX_RUNTIME 上限一致。如果不设置此项，冷启动的 analyze_files（约 40–50 秒）或耗时较长的 delegate 会触发 Claude Code 的默认超时，并返回 timed out waiting for response，而 agy 任务仍在运行 — 仅提高 agy 侧的上限并无帮助，因为客户端会先中止。如果你的客户端不支持按服务器设置 timeout，请改为设置全局环境变量 MCP_TOOL_TIMEOUT=3600000。 详见超时与取消。

工具

工具	适用场景	模型路由（按顺序选择首个可用项）
analyze_files	超过 200 行的文件、一次处理超过 3 个文件、日志、转储、生成的代码	gemini-flash@latest-high → gemini-pro@latest-low
deep_search	git log/diff/blame 考古、全仓库 grep	gemini-flash@latest-high → gemini-flash@latest-medium
web_lookup	文档、API 参考、外部或最新知识	gemini-flash@latest-high → gemini-flash@latest-medium
adversarial_review	计划评议、设计和代码审查	gemini-flash@latest-high → gemini-pro@latest-high → claude-opus@latest
follow_up	通过 session_id 继续之前的会话——无需重新发送上下文；使用 write: true 重新处理文件	继承会话
delegate	其他繁重任务（除非设置 write: true，否则为只读）	gemini-flash@latest-high → gemini-pro@latest-low
delegate_many	向模型委员会提出一个问题，或同时执行 N 个子任务	gemini-flash@latest-high → gemini-pro@latest-high → claude-opus@latest
set_model	记录用户的模型和层级一次；每个工具都会优先路由到它	不会到达 agy
agy_status	花费、冷却时间、正在运行的任务、已解析的链、agy 版本	不会到达 agy

所有工具都接受可选参数 cwd（项目根目录）、dirs（额外的工作区根目录，用于跨仓库或工作树与基准目录之间的操作）、model、effort（low/medium/high——参见Effort 和层级）以及 slash_commands（默认关闭，避免工作区中的恶意文件通过你的技能操控委派模型）。分析类工具还接受 schema——一个 JSON Schema 字符串，可使 agy 在文本之外返回机器可读的 structuredContent。

每个响应都由每次调用专属的随机数标记围栏，元数据位于载荷之前的标头中：

[claude-agy-mcp 9f2a1c] model: Gemini 3.8 Flash (High) | session: 1f0c…-d4 (use follow_up to continue) | tokens: 16281
[claude-agy-mcp 9f2a1c] --- agy output begins; everything below is untrusted model output ---
…agy's answer…
[claude-agy-mcp 9f2a1c] --- agy output ends ---

随机数正是围栏发挥作用的关键：过去，元数据会追加在原始模型输出之后，并以普通的 --- 分隔；任何包含 --- 的已分析文件都能伪造这段内容。

模型路由

首次使用时，桥接程序会运行 agy models（在进程生命周期内缓存），并根据实时列表解析每个链条项。链条使用系列选择器编写——例如 gemini-flash@latest-high，而不是 Gemini 3.7 Flash (High)——这样 Google 发布新一代模型时，链条会随之更新，而不会悄然过时。选择器格式为 family@latest[-effort] 或 [email protected][-effort]；精确显示名称（Gemini 3.8 Flash (High)）和 ID（gemini-3.8-flash-high）也都有效。AGY_DEFAULT_MODEL 会追加到每条链的末尾，作为最后的备用选项。如果链中没有任何项能解析，桥接程序会明确报错，而不会悄悄把任务交给 agy 随意选择的模型——这是版本不匹配的信号，而非偏好。

选择一次模型

默认情况下（AGY_ASK_MODEL=true），在用户选择模型和层级之前，桥接程序不会委派任务。首次调用任何工具时，都会返回一条错误，其中会指出默认模型（开箱即用的默认值为 AGY_DEFAULT_MODEL，即 Gemini Flash High）、列出 agy 提供的模型，并要求 Agent 询问用户：“使用默认设置——高强度的 Gemini 3.8 Flash（High）——还是更改模型或强度？”。然后，Agent 只调用一次 set_model：不带参数表示接受默认设置，或者传入用户选择的模型和强度。选择结果会写入 $XDG_CONFIG_HOME/claude-agy-mcp/preferences.json（默认为 ~/.config/claude-agy-mcp/），因此会在进程结束后保留，而且机器上的所有 MCP 客户端共享这一设置：只询问一次，就此确定。所选模型会排在每个工具的模型链首位——模型链仍会在其后提供配额故障转移——而调用中明确指定的 model 参数仍优先用于该次调用。agy_status 会显示当前选择和实时模型列表；再次调用 set_model 可更改选择，或者设置 AGY_ASK_MODEL=false，跳过此门控并完全按照内置模型链路由。

_{Claude Code 首次使用时呈现的表单——由服务端询问，而非 Agent 询问。}

强度与层级

agy 1.2.1 会拒绝对名称已包含层级的模型使用 --effort——agy models 中所有 Gemini 和 Claude 条目都属于这种情况——也会拒绝层级与标志不一致的 ID。因此，桥接程序将名称中的层级视为强度：不同于该层级的 effort 会选择该层级的同系列模型（Gemini 3.8 Flash (High) + effort: medium → Gemini 3.8 Flash (Medium)）；没有列出同系列模型的强度会保持模型不变；而 agy 自身的 --effort 标志只会与不带层级的模型一起传递。内置模型链会在选择器中编码层级（gemini-flash@latest-high），因此工具不会单独设置自己的强度。强度只作用于主模型——即 model 参数指定的模型，否则为 set_model 选择的模型，再否则为模型链首位的模型。后备模型的名称中保留了层级，因此配额故障转移从 Flash (High) 实际会切换到 Flash (Medium)，而不会重新分配为刚刚耗尽配额的模型层级。

感知配额的故障转移

agy 在打印模式下不会显示配额耗尽信息——它会静默重试 429，直到达到打印超时，然后以代码 0 退出并返回空输出，这之前看起来就像无限期挂起。现在，桥接程序会监视每次运行的日志文件（通过 --log-file），并在遇到 RESOURCE_EXHAUSTED (code 429) 时：

1. 立即终止 agy 进程组（不等待超时结束），
2. 将重置时间（“Resets in 4h24m”）解析到进程内冷却注册表中，
3. 使用该工具模型链中的下一个模型重试相同的提示词，
4. 在后续调用中跳过处于冷却状态的模型，直到其配额重置（即使是“Resets in 0s”，也至少冷却一分钟）。

通过 model 固定的模型即使处于冷却状态也会尝试。允许写入的运行（write: true）只有在能确证工作树未发生变化时才会故障转移；如果工作树发生变化或无法生成指纹，调用会改为以 Not failed over 失败，因为配额耗尽的运行可能已经做出了修改，换用下一个模型会重复修改。网络错误后的单次重试，以及已接收轮次后返回空答案或退出的常驻会话，也遵循相同规则。

故障转移信息会附注在响应页脚中（failover: <model>: quota exhausted (resets in 4h24m)）。只有所有候选模型的配额都已耗尽时，调用才会失败——几秒内即可返回，并列出重置时间——而不会一直挂起。

超时与取消

桥接程序不会因为运行缓慢而终止任务。 已用时间无法区分正常的长时间模型调用与卡住的进程，而误判为“卡住”会在 Agent 编辑过程中将其打断，留下只写入一半的文件。因此，只有在有权威信号表明应终止时，才会终止任务：

1. 调用方取消（例如在 Claude Code 中按 Esc）、客户端断开连接或桥接程序停止——它启动的每个 agy 运行都会随之终止，而不会成为孤立进程，
2. 确认配额已耗尽（运行日志中出现 429），从而触发故障转移，或
3. 资源上限到期——AGY_MAX_RUNTIME，默认为 3600s。

此上限是资源限制，并非诊断结果。达到上限时，运行仍会返回 agy 目前为止生成的所有内容以及 session_id，并明确说明：agy 已做出的任何文件更改都已写入磁盘，follow_up 会从停止处继续。AGY_TIMEOUT 会为所有工具覆盖此上限；AGY_TIMEOUT_<TOOL_NAME> 会为单个工具覆盖此上限（例如 AGY_TIMEOUT_DEEP_SEARCH=900），且优先级高于全局设置。完整列表为 AGY_TIMEOUT_ANALYZE_FILES、AGY_TIMEOUT_DEEP_SEARCH、AGY_TIMEOUT_WEB_LOOKUP、AGY_TIMEOUT_ADVERSARIAL_REVIEW、AGY_TIMEOUT_FOLLOW_UP、AGY_TIMEOUT_DELEGATE 和 AGY_TIMEOUT_DELEGATE_MANY；任何其他 AGY_TIMEOUT_<NAME> 都会导致启动错误，因此拼错的限制值不会悄无声息地失效。所有超时时间最长为 604800s（7 天），因为超过此时长的计时器会被 Node 立即触发。终止流程会向整个进程组逐步发送 SIGTERM → SIGKILL；即使 agy 的辅助进程仍持有输出管道，也会执行终止。

两层超时——而通常先触发的是客户端超时。 上述上限是 _agy 端_的运行时预算。你的 MCP 客户端（Claude Code）有独立的_工具调用_超时；如果该超时更短，客户端会先放弃——你会看到 Error: timed out waiting for response，而桥接程序自身的上限则会显示 MAXIMUM RUNTIME EXCEEDED。因此，仅提高 AGY_MAX_RUNTIME 并无作用：客户端仍会按自己的时限中止调用。无论哪种情况，工作都不会丢失——agy 会保留会话，因此可以使用返回的 session_id 调用 follow_up 来取回结果；但真正的解决方法是让客户端至少等待与上限相同的时长。安装 命令会为单个服务设置 timeout 为 3600000ms（仅适用于此服务）。如果注册服务时未设置此项，请重新运行安装说明中的 add-json 命令，或设置全局环境变量 MCP_TOOL_TIMEOUT=3600000。经验法则：客户端 timeout ≥ AGY_MAX_RUNTIME。

预期延迟。 感知到的“缓慢”大多来自冷启动：每次调用都会启动 agy CLI 并预热模型。在 agy 1.2.0 上测得，一个简单提示词需要 2–6s，工具操作被拒绝的运行约需 16s，受 --json-schema 约束的运行则最长可达 56s（该 schema 会使思考令牌数量大约增加三倍）。对多个大型文件执行实际的 analyze_files 工作会慢得多，而触发配额 429 的调用还会额外叠加故障转移耗时。follow_up 是个例外：它会复用一个常驻 agy 进程（参见 AGY_WARM_SESSIONS），完全跳过冷启动；但如果调用固定指定了 model 或 effort，或要求 write，常驻会话就无法满足这些要求，因此会以冷启动方式运行。常驻会话中的每轮运行同样受运行时上限和取消机制约束。设置客户端超时时，应以较慢的情况为准，而不是较快的情况。

配置

所有配置均为可选，通过环境变量设置：

变量	默认值	描述
AGY_PATH	agy	agy 二进制文件的路径
AGY_MAX_RUNTIME	3600	秒；绝对运行时间上限。桥接程序不会因不活动而终止进程——只有取消、配额耗尽或达到此上限时才会终止
AGY_TIMEOUT	AGY_MAX_RUNTIME	秒；为每个工具覆盖运行时间上限，作为 --print-timeout 传入，并在 15s 的强制终止宽限期后执行
AGY_TIMEOUT_<TOOL>	AGY_MAX_RUNTIME	秒；为单个工具覆盖运行时间上限，例如 AGY_TIMEOUT_DEEP_SEARCH=900。优先级高于 AGY_TIMEOUT
AGY_MAX_OUTPUT_CHARS	50000	工具输出的截断上限
AGY_DEFAULT_MODEL	gemini-flash@latest-high	作为最后手段追加到每条模型链中
AGY_ASK_MODEL	true	在用户通过 set_model 选择模型之前，拒绝委派（只询问一次，并按机器保存）
AGY_EFFORT	agy 自身的默认值	low | medium | high 回退层级；选择该层级的同系列模型（参见 Effort 和层级）
AGY_SKIP_PERMISSIONS	true	将 --dangerously-skip-permissions 传给 agy
(所有布尔变量)	—	接受 true/false、1/0、yes/no、on/off，不区分大小写。无法识别的值会导致启动错误，不会静默采用默认值
(所有数值变量)	—	仅接受普通十进制数字（1e3、0x10 和带填充的值会导致启动错误）。枚举变量（AGY_EFFORT、AGY_ON_FAILURE）不区分大小写
AGY_SANDBOX	false	使用 --sandbox 运行 agy
AGY_ON_FAILURE	fallback	strict 会在工具失败错误中追加一条指示，告知调用 Agent 不要自行承担这项工作
AGY_MAX_CONCURRENCY	2	同时运行的 agy 进程数上限。超出上限的调用会排队，而不是同时冲击共享配额
AGY_BUDGET_TOKENS	未设置	自启动以来消耗的令牌数达到此值时立即停止。使用 agy_status 检查消耗量
AGY_ALLOWED_ROOTS	未设置（不受限制）	cwd、dirs、files 和派生的工作区根目录不得越出的根目录；会跟随符号链接；用 : 分隔（Windows 上用 ;），也可用逗号分隔。这是输入验证，而非沙箱
AGY_REDACT	true	在返回文本到达调用方上下文之前，清除其中看起来像凭据的字符串
AGY_MAX_DELEGATION_DEPTH	1	达到此委派深度后拒绝继续委派，以防 Claude → agy → 此服务 → agy 形成循环
AGY_WARM_SESSIONS	true	每个对话保留一个常驻 agy 进程，让 follow_up 跳过冷启动
AGY_WARM_MAX	2	保留的常驻会话数上限；最近最少使用的会话会被逐出
AGY_WARM_IDLE_SEC	300	常驻会话空闲达到此时长后将其终止
AGY_READ_ONLY_ENFORCEMENT	auto	auto 会在平台支持时（macOS）阻止只读运行向其根目录写入，并在其他平台进行监视；require 会拒绝无法阻止写入的只读运行；off 仅进行监视

警告

AGY_SKIP_PERMISSIONS 是一项真正的授权，而 agy 不会在此基础上强制执行只读限制。 它 默认设为 true，因为无头模式下的 agy 会自动拒绝所有需要权限的工具——包括 read_file——而一次拒绝就会让运行以空响应结束，因此没有这项授权的桥接程序 无法读取、搜索或获取任何内容。只读工具会传入 --mode plan，但我们已针对 agy 1.2.1 验证过，并再次针对 1.2.2 验证：无论是否启用权限绕过，计划模式都只是建议。 agy 无论如何都会在 --mode plan 运行中创建文件。

因此，在 macOS 上由桥接程序强制执行只读限制。 每次计划模式运行，无论是冷启动还是常驻运行，agy 都会在 内核沙盒（sandbox-exec）中运行，禁止 agy 及其启动的所有进程在 cwd 和每个 dirs 根目录下 写入。我们已针对 agy 1.2.2 验证：它的文件写入工具和 shell 都会因“Operation not permitted”而失败，而读取、git 检查以及 agy 在主目录下的自身状态仍可正常使用。响应标头会显示 read-only: enforced。启动时会探测沙盒； 如果无法运行——例如在 Linux 上，或桥接程序本身处于沙盒中——则会改为监视只读运行，标头会显示 read-only: watched, not enforced 并附上原因，而 AGY_READ_ONLY_ENFORCEMENT=require 会直接拒绝此类运行。agy_status 会报告实际采用的方式。

边界严格限定在工作区根目录。agy 仍可在用户有权限的其他任何位置写入，而通过 open、应用或 launchd 作业启动的、位于其自身进程树之外的进程不会受到沙盒限制。因此，两种模式下都会保持监视：桥接程序会在每次计划模式运行前后对工作树进行指纹比对。即使启用了强制限制，工作树仍发生变化时，会报告为 WORKING TREE CHANGED（可能是其他写入者，也可能是通过此类进程逃逸）；未启用强制限制时发生变化，则会报告为 READ-ONLY VIOLATION。没有警告表示检查后未发现变化；无法生成指纹的工作树不会给出任何结论。指纹涵盖 cwd 以及调用传给 agy 的每个目录。在 git 仓库中，指纹涵盖 HEAD、每项已跟踪变更的内容和模式、每个未跟踪文件的内容，以及每个被忽略条目的模式、大小和修改时间；被忽略的目录也会以相同方式遍历。位于仓库顶层的依赖项或构建目录（node_modules、.venv、 venv、__pycache__、.next、dist）各自视为一个条目——因此，计划模式下写入的 .env 或 build/out.js 会被发现，而在 node_modules 深处的重写则不会。非 git 仓库则会比较路径、类型、大小、模式和修改时间。两种方式都将上限设为 20,000 个条目和 10 秒。在 Apple M5 Max 上测得：对一个包含 3,500 个文件且没有未提交变更的仓库，每次快照约需 150 毫秒；对一个包含 300 个已修改文件和 3,000 个未跟踪文件的仓库，约需 1.1 秒；每次运行前后各生成一个快照。 运行期间，任何其他写入工作树的操作（编辑器、监视程序或并行写入委派）也会造成变化：警告表示运行期间工作树发生了变化，并不能证明是谁造成的。工作树发生变化后运行失败的计划模式调用，会在错误中附带警告。应以标头作为可信信号，而非工具名称，也非没有 denied-actions 提示；只有关闭授权时才会填充被拒绝的操作。

无法强制执行的限制会导致调用失败：如果安装的 agy 不支持 --mode 或 --sandbox，需要其中任一参数的运行都会被拒绝，而不会以超出请求范围的权限运行。无论如何，--sandbox 限制的是终端，而非权限边界。 [!IMPORTANT] AGY_ALLOWED_ROOTS 用于验证输入，并非沙箱。 它会在 agy 启动前检查每次调用的 cwd、dirs 和 files，包括桥接程序根据它们推导出的工作区根目录，因此调用方无法将委派指向你指定根目录之外的位置。它不会限制运行范围：在获得的权限范围内，agy 拥有 shell，可访问运行桥接程序的用户能够访问的任何内容。 上述只读沙箱仅会阻止向只读运行自己的根目录写入，而允许写入的运行则完全不受沙箱限制。若要实现真正的隔离，请在受限环境中运行桥接程序。

失败行为

桥接程序始终会明确报告失败，并根据 agy 的 JSON 封套，而非退出代码，判断何为“失败”。这一点很重要，因为 agy 可能以 status: SUCCESS 和看似合理的答案、退出代码为 0，但其工具操作实际上已被静默自动拒绝——桥接程序会将这些情况显示为操作被拒绝的警告，而不是把只完成一半的答案当作正常结果返回。失败会分类处理：只有配额 429 错误会切换到下一个模型；网络错误会重试一次；无效模型或登录过期则会立即停止，不会耗尽整个模型链。只有状态码旁边带有状态词时，该状态码才会被视为有效，因此日志中的 read 429 bytes 不属于配额错误，foo.ts:401 也不属于身份验证失败。失败尝试消耗的令牌仍会计入 AGY_BUDGET_TOKENS。响应头中会标注降级的模型路由。默认情况下，调用方 Agent（Claude）通常会在失败后自行完成任务——这会显示在对话记录中，但在较长的会话中很容易被忽视。设置 AGY_ON_FAILURE=strict，即可在每个委派错误中附加明确指令：“不要自行执行此工作——请向用户报告失败”，从而让你掌控何时会悄然失去令牌节省效果。在尚未进行任何委派前就被拒绝的调用——例如路径位于根目录之外、缺少 cwd，或 agy 无法接收提示词——应由调用方修复，且不会附带此类指令。

已知限制

这些问题是有意保留的，避免被误认为疏忽：

• 委派深度计数器由协作机制保障。 AGY_MAX_DELEGATION_DEPTH 通过环境变量传递给子进程，因此会清理环境变量的嵌套启动器会将其重置为 0。失败时造成的后果是通过委派循环浪费配额，而非权限逃逸。
• 运行日志不会进行脱敏。 AGY_REDACT 会清理返回给调用方的内容；agy 为配额轮询器写入的临时日志可能会以明文形式保存机密，直到运行结束。该日志位于仅当前用户可读的进程专属目录中，并会在关闭时删除；如果因崩溃而遗留，下次启动桥接程序时也会删除。
• 输入大小有限制。 提示词作为单个命令行参数传给 agy，因此构建后的提示词超过 128 KiB（Linux 的单参数限制）或包含 NUL 字节时，会在运行任何内容之前被拒绝；对于较大的内容，请传递文件路径，而不要直接内嵌。delegate_many 最多接受 8 个任务或 8 个不同的模型，且 tasks 不能与 models 一起使用。
• --disable-slash-commands 尽力而为。 与 --mode plan 和 --sandbox 不同，如果已安装的 agy 未声明支持该选项，就会直接省略而非拒绝；这是因为没有此标志的构建很可能没有需要禁用的命令扩展。
• 只读模式仅在 macOS 上强制执行。 Linux 没有桥接程序可以在无需额外软件的情况下使用的等效机制，因此只会监视只读运行，而不会阻止。设置 AGY_READ_ONLY_ENFORCEMENT=require 可改为拒绝此类运行。
• macOS 上的拦截基于路径。 如果某个根目录中的文件已在所有根目录之外存在硬链接，就可以通过该外部链接重写文件。运行期间会阻止创建此类链接，也会阻止重命名根目录上方的任何目录，以免将目录树移出规则的管辖范围。工作树指纹仍会报告通过旧链接所做的更改。
• 包含 agy 状态的根目录仍有部分可写区域。 如果根目录包含 ~/.gemini，该目录会被豁免，以便 agy 继续运行；其中的写入不会被阻止，指纹也会跳过该目录。位于 ~/.gemini 或其内部的根目录只会受到监视，不会被强制执行只读限制。
• 共享同一个 session_id 的扇出任务会按顺序运行。 agy 会持有每个对话的锁，因此针对同一对话并发执行会导致内容损坏。若要并行运行，请扇出到多个对话。

开发

npm install
npm test           # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build      # esbuild → dist/index.js

贡献

请阅读 CONTRIBUTING.md — 使用 Conventional Commits、prettier，并为每项行为变更添加一个测试。漏洞请通过 SECURITY.md 报告，切勿发布为公开问题。

贡献者

许可证

MIT