agy-bridge

agy-bridge 是一个面向 Codex 的本地 MCP（Model Context Protocol）桥接服务。它把本机的 Antigravity CLI 包装成 antigravity_execute 工具，使 Codex 可以把仓库探索、代码修改、构建、测试和修复任务委派给 Antigravity。

它有什么作用

调用链如下：

Codex
  -> MCP: antigravity_execute
  -> agy-bridge
  -> Antigravity CLI (agy.exe)
  -> Gemini 3.6 Flash High
  -> 在指定项目目录中检查、修改并验证代码

主要能力：

• 检查传入的项目路径是否为有效的绝对目录。
• 为 Antigravity 注入统一的执行约束和验收要求。
• 使用 accept-edits 模式运行 Antigravity，允许其修改指定项目。
• 以流式 JSON 接收执行事件，并向 MCP 客户端回传进度。
• 支持超时和取消。
• 识别配额不足、权限拒绝、无输出等语义失败。
• 要求 Antigravity 保留用户已有改动，不提交、不推送、不操作生产环境。
• 当任务可以安全拆分时，允许 Antigravity 使用原生子代理并行执行。

环境要求

• Windows。
• Node.js 18 或更高版本。
• 已安装并可用的 Antigravity CLI。
• Antigravity 可执行文件位于：

%LOCALAPPDATA%\agy\bin\agy.exe

• 支持 MCP stdio 服务的 Codex 版本。

当前实现固定使用 gemini-3.6-flash-high，并按 Windows 的默认 Antigravity 安装路径寻找 agy.exe。

安装

克隆仓库并安装依赖：

git clone <你的仓库地址>
cd agy-bridge
npm install

也可以使用锁文件进行可重复安装：

npm ci

配置 Codex

打开 Codex 配置文件：

%USERPROFILE%\.codex\config.toml

加入以下配置，并把路径替换为本仓库的实际绝对路径：

[mcp_servers.agy-bridge]
command = "C:\\Program Files\\nodejs\\node.exe"
args = ["C:\\path\\to\\agy-bridge\\server.mjs"]
enabled = true

如果不知道 Node.js 的路径，可以在 PowerShell 中运行：

(Get-Command node).Source

修改配置后，重新启动 Codex 或新建任务，使 MCP 配置重新加载。

使用方法

配置成功后，Codex 会获得一个名为 antigravity_execute 的 MCP 工具。工具参数如下：

参数	必填	默认值	说明
project_path	是	无	需要处理的项目绝对路径
task	是	无	完整任务、限制条件、验收标准和测试要求
effort	否	high	当前只能传入 high
timeout_seconds	否	1800	超时时间，范围为 30–3600 秒
detail_level	否	detailed	进度详情，可选 summary 或 detailed

示例调用参数：

{
  "project_path": "C:\\projects\\example-app",
  "task": "修复登录页面提交后重复请求的问题。保留现有 UI，补充回归测试，并运行相关测试。",
  "effort": "high",
  "timeout_seconds": 1800,
  "detail_level": "detailed"
}

在日常对话中，也可以让 Codex 根据项目规则自动调用。例如在项目或全局 AGENTS.md 中写入：

对于需要实现、修改或修复代码的任务，使用 agy-bridge 的
antigravity_execute 工具执行实现和测试；返回后由 Codex 检查
git diff，并独立验证关键测试。

不建议把这条规则设置成无条件的全局强制规则。更稳妥的方式是在确实需要该工作流的项目内放置 AGENTS.md，避免所有项目都自动委派。

执行行为

桥接器向 Antigravity 传递的核心约束包括：

• 只在指定项目目录内工作，除非任务明确允许其他目录。
• 保留无关文件和用户已有修改。
• 修改前先检查仓库。
• 实际实现任务，而不只是解释方案。
• 运行相关构建、检查和测试。
• 不执行 Git 提交、推送或历史重写。
• 不操作生产系统。
• 并行写入时必须分配互不重叠的目录，并使用隔离工作区。
• API 契约、数据库迁移、根依赖文件、锁文件和最终集成测试保持串行。

返回结果

成功时，工具返回的 JSON 包含：

• stdout：Antigravity 的最终回复。
• exit_code：进程退出码。
• model：实际使用的模型。
• conversation_id：Antigravity 会话 ID。
• status：执行状态。
• duration_seconds：执行耗时。
• num_turns：执行轮数。
• usage：使用量信息。
• progress：最近的执行时间线。

失败时，MCP 工具会返回错误，包括进程退出异常、超时、取消、权限拒绝、配额耗尽或未得到有效最终结果。

停用或移除

临时停用：

[mcp_servers.agy-bridge]
enabled = false

完全移除时，删除 config.toml 中的 [mcp_servers.agy-bridge] 配置，并删除相关 AGENTS.md 自动调用规则。仓库目录可以按需保留或删除。

安全提示

antigravity_execute 允许外部执行代理在 project_path 内修改文件并运行命令。使用时应注意：

• 只传入你明确允许修改的目录。
• 在重要仓库中先保存或提交现有改动。
• 不要在任务文本中放入密码、令牌或其他敏感信息。
• Codex 应在委派完成后检查 git status、git diff 和测试结果。
• 对生产部署、推送、发布及数据库操作保留人工确认。

许可证

MIT