agy-bridge 是一个 MCP（模型上下文协议）桥接工具，用于让 Claude Code 把耗时或上下文密集的任务委派给 Antigravity CLI（命令行简称 agy）。其设计目标是节省 Claude 的上下文窗口和 token——Claude 只发送任务，桥接层通过 agy 路由到最佳可用模型，最终仅将答案返回给 Claude；大文件、深度 git 搜索和网页查询均不进入 Claude 的上下文。
主要能力
- 专用工具：提供针对性的任务工具集，覆盖文件分析（analyze_files）、仓库考古/深度搜索（deep_search）、网页查询（web_lookup）、对抗性代码评审（adversarial_review）、后续追问（follow_up）以及通用委派（delegate）等。
- 模型路由与回退：首次使用时桥接会运行 agy models（在进程生命周期内缓存），并按工具的偏好链选择第一个可用模型；若均不可用，则回退到 AGY_DEFAULT_MODEL，最后回退到 agy 自身默认模型。由于 agy 会静默忽略未知的 --model 值，桥接会预先校验模型名称，避免请求落到错误模型上。
- 配额感知故障转移：agy 在打印模式下不会暴露配额耗尽，而是静默重试 429 直到打印超时，随后以退出码 0 返回空输出。桥接通过 --log-file 监视每次运行的日志，遇到 RESOURCE_EXHAUSTED（429）时：立即终止 agy 进程组（不再等待超时）、从日志中解析重置时间（如 "Resets in 4h24m"）写入进程内冷却注册表、在工具链中的下一个模型上重试同一提示，并在后续调用中跳过处于冷却期的模型，直至其配额重置。故障转移会在响应页脚中标注（如 failover: <model>: quota exhausted (resets in 4h24m)）；仅当所有候选模型都耗尽时，调用才会在数秒内失败并列出重置时间，而不是挂起。
- 超时与取消：每个工具有独立默认超时——web_lookup 120 秒、deep_search 180 秒、analyze_files / adversarial_review / follow_up 300 秒、delegate 600 秒。设置 AGY_TIMEOUT 会一次性覆盖全部；如需单独调整某个工具，使用 AGY_TIMEOUT_<TOOL_NAME>（例如 AGY_TIMEOUT_DEEP_SEARCH=300），且单工具覆盖优先于全局 AGY_TIMEOUT 和工具默认值。可用的单工具变量包括 AGY_TIMEOUT_ANALYZE_FILES、AGY_TIMEOUT_DEEP_SEARCH、AGY_TIMEOUT_WEB_LOOKUP、AGY_TIMEOUT_ADVERSARIAL_REVIEW、AGY_TIMEOUT_FOLLOW_UP、AGY_TIMEOUT_DELEGATE。终止路径会从 SIGTERM 升级到 SIGKILL 覆盖整个进程组，即使 agy 的辅助进程仍持有输出管道，截止时间也会触发。从 MCP 客户端取消工具调用（例如在 Claude Code 中按 Esc）同样会终止 agy 运行，而非使其成为孤儿进程。
- 超时分层需对齐：上述超时是 agy 侧预算；MCP 客户端（Claude Code）有自己独立的工具调用超时。若客户端超时短于 agy 预算，客户端会先放弃并显示 Error: timed out waiting for response（注意：agy-bridge 自身的超时会显示 agy timed out after Ns）。工作不会丢失——agy 会话会持续存在，可用返回的 session_id 通过 follow_up 取回结果。推荐做法是让客户端等待时间至少与 agy 一致：安装命令已为 agy-bridge 条目设置 600000 毫秒（即 10 分钟）的每服务器超时；若注册时未包含，可重新执行安装命令或设置全局环境变量 MCP_TOOL_TIMEOUT=600000。经验法则：客户端超时 ≥ agy 预算。
- 预期延迟：多数“缓慢”感知来自冷启动——会话中第一次调用会启动 agy CLI 并预热模型。对 3 个文件的简单 analyze_files 冷启动约 40–50 秒（观测约 46 秒），同一会话后续调用会下降。首次调用若同时遇到配额 429，桥接故障转移期间耗时更长。因此低于约 60 秒的客户端超时可能间歇性触发冷启动超时，即使问题“简单”，也应设置得宽松些。
- 响应页脚：每次响应末尾带有页脚信息，用于标注故障转移等状态。
- 失败行为：桥接始终显式失败——agy 错误会以 MCP 工具错误形式暴露 agy 的实际 stderr，降级的模型路由会在响应页脚中标注。默认情况下，调用方代理（Claude）在失败后通常会自行完成工作——这在记录中可见，但在长会话中容易被忽略。设置 AGY_ON_FAILURE=strict 可在每个委派错误后附加明确指令：“不要自行执行此工作——向用户报告失败”，从而让你掌控 token 节省何时被悄然丢失的情况。
使用方式 前提是已安装并完成 Antigravity CLI（agy）的认证。工具均接受可选参数 cwd（项目根目录）和 model（agy models 中的 ID 或显示名称，会校验，名称不匹配时会列出可用模型）。安装配置需为 agy-bridge 条目设置 "timeout": 600000（10 分钟，毫秒）作为客户端工具调用截止时间；若客户端不支持每服务器超时，则设置全局环境变量 MCP_TOOL_TIMEOUT=600000。所有环境变量均为可选。
适用场景 适合需要将大文件分析、深度 git 搜索、网页查询以及第二意见式代码评审等重负载任务从 Claude 上下文卸载出去的场景，尤其适合关注上下文窗口与 token 消耗、且希望利用 agy 多模型回退与配额感知能力的开发者。
限制 需预先安装并认证 Antigravity CLI（agy）；agy 在打印模式下不暴露配额耗尽，需依赖日志监视；存在两层超时（客户端与 agy 侧），若不对齐会出现客户端先超时的情况；冷启动有数十秒延迟；模型名称由桥接预先校验，agy 本身会静默忽略未知 --model 值。贡献方面，仓库欢迎通过 issue 或 PR 参与。
