# agy-bridge

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

## 它有什么作用

调用链如下：

```text
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 可执行文件位于：

```text
%LOCALAPPDATA%\agy\bin\agy.exe
```

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

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

## 安装

克隆仓库并安装依赖：

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

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

```powershell
npm ci
```

## 配置 Codex

打开 Codex 配置文件：

```text
%USERPROFILE%\.codex\config.toml
```

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

```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 中运行：

```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` |

示例调用参数：

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

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

```markdown
对于需要实现、修改或修复代码的任务，使用 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 工具会返回错误，包括进程退出异常、超时、取消、权限拒绝、配额耗尽或未得到有效最终结果。

## 停用或移除

临时停用：

```toml
[mcp_servers.agy-bridge]
enabled = false
```

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

## 安全提示

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

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

## 许可证

[MIT](LICENSE)