# Codex ↔ Antigravity(agy) 桥 —— 施工报告

- 日期：2026-11-16
- 代码：`/vol1/ai/projects/agy-mcp-bridge/`
- 结论：**通了。** 六项验收全通过，Codex 自己能调 MCP 派单给 agy 并拿到结果。
- 没碰：`dsh-mcp-bridge/`、`codex-web`、`dsh`、`hermes-gateway`、agy 凭据（`.gemini/`）。

---

## 一、做了什么

照 `dsh-mcp-bridge` 的结构（stdio + 行分帧 JSON-RPC 2.0，只用标准库）重写了一版给 agy：

```
Codex ──MCP(stdio)──► agy_mcp_server.py ──spawn──► agy --print "任务" --output-format json
                            │                          │
                            └── /vol1/ai/agy-runs/<run_id>/  ◄── JSON 落盘
                                  prompt.txt / meta.json / stdout.log / stderr.log / done.json
```

| 文件 | 说明 |
|---|---|
| `agy_mcp_server.py`（29KB） | MCP 服务器，7 个工具，stdio 行分帧 |
| `agy_runner.py` | 子进程执行器：`stdin=DEVNULL`、stdout/stderr 落盘、双超时兜底、写 `done.json` |
| `test_channel.py` | 六项验收客户端（自带 MCP Client） |
| `test_extra.py` | 补测：effort 降级 / 坏会话 id / continue / cancel / runs |
| `codex-e2e.sh` | 真·端到端：让 codex 自己调 MCP 派单 |
| `README.md` | 结构、工具、坑、排障 |

注册（已写入并备份）：

```toml
# /vol1/ai/agents/codex/config.toml
[mcp_servers.agy]
command = "/usr/bin/python3"
args = ["/vol1/ai/projects/agy-mcp-bridge/agy_mcp_server.py"]
env = { HOME = "/vol1/ai/home" }
startup_timeout_sec = 30
tool_timeout_sec = 900
```

备份：`/vol1/ai/agents/codex/config.toml.bak-20261116-142946`（只追加，原有 MCP 段一行没动）
`codex mcp list` 已能看到 `agy  enabled`。

### 工具清单

| 工具 | 参数 | 说明 |
|---|---|---|
| `agy_dispatch` | `task`*, `cwd`, `model`, `effort`, `conversation_id`, `continue`, `add_dirs[]`, `mode`, `timeout_s`, `skip_permissions`, `files[]` | 后台开跑，立即返回 `run_id` |
| `agy_result` | `run_id`*, `wait_s`（≤600） | `state` / `answer` / `conversation_id` / `num_turns` / `usage` / `warnings` / `stderr` |
| `agy_runs` | `limit` | 最近派单（状态/任务前 60 字/会话 id） |
| `agy_cancel` | `run_id`* | SIGTERM 整个进程组 |
| `agy_models` | `refresh` | 模型清单 + 各自对 `--effort` 的支持情况（缓存 300s） |
| `agy_upload` | `paths[]`*, `cwd` | 复制进 `<cwd>/agy-inbox/`，返回绝对路径 |
| `agy_sessions` | `limit` | 读 `conversation_summaries.db`（只读），列最近会话 |

`state` 四种：`running` / `done` / `error` / `cancelled`。

### agy 这边摸出来、跟 dsh 不一样的地方（都已在代码里处理）

1. **失败时 exit code 可能是 0**：模型名写错 → `exit 0` + JSON `status=ERROR`。状态判定必须同时看两者。
2. **`--effort` 跟模型名打架**：`gemini-3.8-flash-high` 名字自带档位，再传 `--effort max` 直接 conflict；
   claude 系压根不支持。→ `resolve_model()` 自动换模型名或忽略并回 `warnings`。
3. **`--mode auto` 这个账号不支持**：stderr 一行 warning 后按默认模式跑（不报错），warning 会被带出来。
4. **请求不存在的 `conversation_id` 不报错**：只在 stderr 打 warning，然后默默新建会话 → 桥会比对返回 id 并明确点出来。
5. **`--continue` 接的是"全机最近一次会话"**，混跑时不可靠 → 优先 `conversation_id`，`continue` 只做退路。
6. **`--print-timeout` 必须带单位**（`5` 报错，`5s` 才对）。
7. 双超时：agy 侧 `--print-timeout=<timeout_s>s` 优雅收尾返回部分输出；runner 侧 `timeout_s+30s` 进程组 SIGTERM→SIGKILL。

---

## 二、六项验收——真实输出（`python3 test_channel.py`，2026-11-16 14:30）

```
=== 测试 1 ===
   initialize → {"name": "agy-mcp-bridge", "version": "1.0.0"}
   tools/list → ['agy_dispatch', 'agy_result', 'agy_runs', 'agy_cancel', 'agy_models', 'agy_upload', 'agy_sessions']
[PASS] 1 握手 + 工具清单  server=agy-mcp-bridge 工具 7 个

=== 测试 2 ===
   派单 → {"ok": true, "run_id": "20261116-143020-f2f05c", "model": "gemini-3.8-flash-high", "cwd": "/tmp/agy-test"}
   结果 → state=done answer='桥通\n' conv=7043af5e-c20d-48d9-98e6-8db4262e81fb 3.5s
[PASS] 2 单轮问答  answer='桥通' exit=0

=== 测试 3 ===
   第1轮 → state=done answer='OK\n' conversation_id=76b2c9a3-7916-4fd7-9d09-ecb5b33e7a1e
   第2轮 → state=done answer='47' num_turns=2 conv=76b2c9a3-7916-4fd7-9d09-ecb5b33e7a1e
[PASS] 3 多轮对话（上下文保持）  第2轮答 '47'，会话沿用 True

=== 测试 4 ===
   上传 → [{"src": "/tmp/agy-test/agy-probe.txt", "dst": "/tmp/agy-test/agy-inbox/agy-probe.txt", "bytes": 92, "lines": 3}]
   回答 → '第二行：白桦 37 株，含水率 12.5%'
[PASS] 4 传文件 + 读取复述  第2行 一字不差

=== 测试 5 ===
   回答 → 'DONE'；磁盘校验 {'one.txt': 'FIRST', 'two.txt': 'SECOND', 'merged.txt': 'FIRSTSECOND'}
[PASS] 5 多步任务真动手  one/two/merged = ['FIRST', 'SECOND', 'FIRSTSECOND']

=== 测试 6 ===
   坏模型 → state=error exit=1 error='invalid model selection (--model "totally-bogus-model" --effort ""): model totally-bogus-model is not recognized as a known model or custom model in settings…'
   超时   → state=error exit=3 finished_reason=print_timeout warnings=['agy 自身 --print-timeout 到点，返回的是部分输出']
[PASS] 6 错误路径如实返回  坏模型：error；超时：print_timeout

=== 汇总 ===
6 项通过 / 0 项失败
```

第 5 项我自己去磁盘上查了（不靠 agy 自述）：

```
/tmp/agy-test/job-143045/  merged.txt=11B one.txt=5B two.txt=6B
one.txt=FIRST   two.txt=SECOND   merged.txt=FIRSTSECOND
```

## 三、Codex 真·端到端（`./codex-e2e.sh`）

`codex exec` 自己走完了 `agy_models → agy_dispatch → agy_result`，日志里的原始事件：

```
mcp_tool_call server=agy tool=agy_models   arguments={}
mcp_tool_call server=agy tool=agy_dispatch arguments={"task":"只回两个字：桥通","cwd":"/tmp/agy-test"}
  → {"ok":true,"run_id":"20261116-143228-b3d37d","model":"gemini-3.8-flash-high","run_dir":"/vol1/ai/agy-runs/20261116-143228-b3d37d"}
mcp_tool_call server=agy tool=agy_result   arguments={"run_id":"20261116-143228-b3d37d","wait_s":120}
  → {"state":"done","exit_code":0,"conversation_id":"bcb73f6a-a4bd-4c07-8302-2164a812242f","answer":"桥通\n"}
```

Codex 的最终结论原文：**「agy 桥验收结果 = 成功」**。

## 四、补测（`test_extra.py`）

```
effort=medium + gemini → model 自动换成 gemini-3.8-flash-medium（warnings 说明）→ done，答 OK
claude-sonnet-4-6 + effort=max → 忽略 effort（warnings 说明）→ done，答 OK
不存在的 conversation_id → 实际新建 c9bf1b36-…，warnings 明确报出
continue=true → 接上同一会话 num_turns=2，答 CT
agy_cancel → {'ok': True, 'killed': 2762510}，结果 state=cancelled，error='已被 agy_cancel 终止'
agy_runs → cancelled / done 状态、conv id、任务摘要都正确
```

## 五、怎么用（三条示例）

```text
1) 简单问一句
   用 agy_dispatch 派任务，task="用三句话解释什么叫 NDVI"，别的参数不传；
   拿到 run_id 后用 agy_result(run_id, wait_s=120) 取结果。

2) 多轮追问（同一个会话）
   第一轮 agy_dispatch(task="读取 /vol1/ai/agy-workspace/agy-inbox/报告.txt，总结成 5 条")
   → 从 agy_result 拿到 conversation_id；
   第二轮 agy_dispatch(task="把第 3 条展开讲讲", conversation_id="<那个 id>")。

3) 带文件派活 + 让它动手改
   先 agy_upload(paths=["/vol1/ai/projects/xxx/draft.md"], cwd="/tmp/work")
   → 返回 /tmp/work/agy-inbox/draft.md；
   再 agy_dispatch(task="把这个 md 改成 800 字以内的口语版，写回同目录 draft-short.md",
                  cwd="/tmp/work", mode="accept-edits")，用 agy_result 等 state=done。
```

## 六、还没做 / 注意

- **没做** `agy_set_default`（agy 没有"改全局默认模型"的口子，默认值在 `AGY_DEFAULT_MODEL` 环境变量里，
  改注册行的 env 即可）。同理 `agy_session_read`（会话内容是 protobuf blob，硬解不划算，
  `agy_sessions` 的预览 + `agy_result` 已经够排障）。
- **消费的是主人的 agy 订阅额度**（`wilczekfabian104@gmail.com`）。每次 dispatch 都会真花额度，
  一次短问答约 9.4k 输入 token；Codex 派单时注意不要循环重派。
- `--mode auto` 这个账号用不了，`accept-edits` 正常；默认不带 mode（走 agy 默认）。
- `/vol1/ai/agy-runs/` 会一直涨，定期清：`find /vol1/ai/agy-runs -maxdepth 1 -mtime +7 -type d -exec rm -rf {} +`
- Codex 配置只做了追加，回退方式：把 `config.toml.bak-20261116-142946` 拷回，或删掉 `[mcp_servers.agy]` 那 6 行。
