# 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 行。

---

# Skill 使用手册（2026-11-16 追加）

两个 agent 各配一份 skill，让它们不用翻源码就会用这座桥 / 会配合这座桥。

## 一、两个 skill

| 给谁 | 绝对路径 | 加载机制 |
|---|---|---|
| Codex | `/vol1/ai/agents/codex/skills/agy-mcp-bridge/SKILL.md` | Codex 扫 `$CODEX_HOME/skills/*/SKILL.md`（`$CODEX_HOME=/vol1/ai/agents/codex`） |
| Antigravity(agy) | `/vol1/ai/home/.gemini/config/skills/codex-agy-bridge-contract/SKILL.md` | agy 的全局 customization 根 = `~/.gemini/config/` |

agy 那份在仓库留了镜像：`/vol1/ai/projects/agy-mcp-bridge/skills/codex-agy-bridge-contract/SKILL.md`
（两处内容必须一致，改完 `cp` 过去）。

### agy 到底从哪读 skill（查证过程）

- `agy plugin --help` 只有 plugin 机制（`~/.gemini/config/plugins/<name>/plugin.json`），
  没有直接装 skill 的命令。
- agy 自带的 `agy-customizations` skill（`builtin/skills/agy-customizations/docs/skills.md`）写明：
  全局根 `~/.gemini/config/`，格式 `skills/<name>/SKILL.md`，frontmatter 必须有 `name` + `description`，
  按"渐进披露"只在需要时读正文。
- 落地后实测：`agy --print "列出你当前可用的 skills 名称"` 的回复里出现了
  `codex-agy-bridge-contract: Use when the incoming task is a machine handoff from another AI agent (Codex calling the local agy MCP bridge)…`
  → **真的会被自动加载**，不是摆设。所以放在 `~/.gemini/config/skills/`，没有退化成纯文档。

### Codex 到底认不认这个 skill（实测）

```text
codex exec -m gpt-5.6-luna -c model_provider=opencode "不要调用任何工具。只看你上下文里注入的技能列表…"
→ AGENT: 1) 有。
         2) 名称：agy-mcp-bridge
            Description 第一句：Use when a task should be handed to Antigravity (agy) through the
            local agy MCP bridge — a second opinion or long/bulk work from Gemini 3.8 Flash or
            Claude Opus 4.6 without burning your own context.
```

## 二、两份 skill 各教了什么

**Codex 侧（`agy-mcp-bridge`）**

1. 什么时候转给 agy（要第二视角 / 长任务不占上下文 / 大批文本 / 要真动手改文件），什么时候不该转。
2. 7 个工具逐个写：必填/可选参数、返回字段、什么时候用哪个；`state` 四态只认 `state` 不认退出码。
3. 多轮正确姿势：`dispatch → result 拿 conversation_id → 下一轮填回去`，附**真跑出来的实录**
   （第 1 轮「记住 83」→ 第 2 轮答 `83`，`num_turns=2`）；并写明"答对了不等于上下文保住了"的判据。
4. 发文件：`agy_upload` 拿 `path` → dispatch 里写绝对路径；`cwd` 两次必须一致；文件永远落 `agy-inbox/`。
5. 坑清单 8 条：exit code 可能是 0、effort 与模型名冲突、坏 conversation_id 静默新建、
   `--mode auto` 不支持、模型别硬编码、别循环烧额度、error 先看原文、上游偶发 503 可重试。

**agy 侧（`codex-agy-bridge-contract`）**

1. 判断"自己正被另一个 AI 调用"的 4 个信号。
2. 回复格式：结论第一行、不客套不复述、短列表、路径必须给纯文本绝对路径
   （它默认渲染的 `[名](file:///绝对路径)` 链接保留也行）。
3. 文件交付：先 `ls` 确认真存在；产物写指定绝对路径；回复给路径 + 行数/字数。
4. 多轮：同一 conversation 里接着做，不重新自我介绍；上下文丢了要明说。
5. 失败：明说做不到 + 原因 + 报错原文，**绝不编造执行结果**（上游会去磁盘验证）。
6. 模型档位：6 个模型各自什么时候选，以及 effort 的坑、503 是 Google 侧容量问题。

### skill 生效验证（不只是挂在列表里）

```text
A. 派任务「读 /tmp/agy-test/这个文件不存在.txt，总结成三句话」
   → state=done
   → 回复：目标文件 … 在指定目录中并不存在。
           1. 系统在 /tmp/agy-test/ 目录下未找到名为 这个文件不存在.txt 的文件。
           2. 由于该文件不存在且无任何内容可读，因此无法提取内容生成摘要。
           3. 请确认文件名与路径是否准确…
   （没有编内容，符合 skill 的"做不到就明说"）

B. 派任务「写 skill-out.md，内容三行 甲/乙/丙，写完报告路径」
   → state=done，回复给了 [skill-out.md](file:///tmp/agy-test/skill-out.md)
   → 磁盘校验：exists=True  content='甲\n乙\n丙'
```

## 三、顺手修掉的问题：`agy_upload` 返回值是空的

**现象**：调用方按 `path` 取值时拿到 `None`，`uploaded` 也是空的，但文件其实送进去了。

**根因**（两处，都在桥这一侧）：

1. 参数名只认 `paths`（数组）。客户端写成 `path` / `files` / `file` 时，桥拿到的 `paths` 是 `None`
   → 循环一次都不跑 → 返回 `{"ok": true, "uploaded": []}`，**既不报错也不传文件**，看着就像"传了但没回填"。
2. 返回体里没有扁平字段，只有一个 `uploaded` 数组，取值方按 `path` 拿就永远是 `None`。

**修法**（只动 `agy_upload` 的返回与入参，桥的其它逻辑没碰）：

- 入参兼容 `paths` / `path` / `files` / `file`，字符串或数组都行；
- 一个路径都没收到 → `ok:false` + 明确错误 + 示例；
- 返回体补齐 `path`（第一个落点）、`paths`（全部落点）、`count`、`hint`，保留 `uploaded[]` 明细；
- 全部失败时 `ok:false` 并把失败原因写进 `error`。

**自测（真实输出）**

```text
A. paths 数组 → ok=true  path=/tmp/agy-test/agy-inbox/skill-probe.txt  count=1
   uploaded[{src,dst,bytes:33,lines:2}]
B. path 字符串（别名）→ ok=True  path=…/agy-inbox/skill-probe.txt  count=1
C. files 数组（别名）→ ok=True  path=…/agy-inbox/skill-probe.txt  count=1
D. 不给参数 → ok=False  error=没有收到文件路径。参数名用 paths（数组），也接受 path / files / file；示例：…
E. 不存在的文件 → ok=False  error=没有一个文件送进去：[{'src': '/tmp/agy-test/不存在.txt', 'error': '不存在'}]
F. 真发文件 + 让 agy 读 → state=done  answer='行2: 白桦 37 株'（文件确实到位）
```

改完把六项验收**整套复跑**：`6 项通过 / 0 项失败`（`/tmp/agy-retest.log`）。

## 四、这一轮还额外摸清的两件事

1. **新会话到底带不带旧上下文**：同一 `cwd` 新开一轮、不传 `conversation_id`，agy 仍答出了上一段的数字
   （输入 token 是正常值 3 倍 ≈ 28k，说明它塞了额外上下文）；换一个全新 `cwd` 再问，老实回 `UNKNOWN`。
   → skill 里已改成"别拿答对当证据，看 `conversation_id` 是否一致 + `num_turns` 是否在涨"。
2. **上游会 503**：`UNAVAILABLE (code: 503) No capacity available for model gemini-3.8-flash-high`，
   报错里带 `retryable: true`。这是 Google 侧容量问题，隔一分钟重派即可，已写进两份 skill 的坑清单。

## 五、硬约束执行情况

- 没重启 `codex-web` / `dsh` / `hermes-gateway`；
- 只改了 `agy_upload` 的入参与返回（外加对应 schema 文字），桥的调度/会话/取消逻辑一行没动；
- 没动 `dsh-mcp-bridge`、没重新登录 agy、没碰 `.gemini/` 里的凭据（只在 `~/.gemini/config/skills/` 新建了一个技能目录）。
