219 lines
13 KiB
Markdown
219 lines
13 KiB
Markdown
# cli-bridge —— 把无头 CLI Agent 挂成 hub 的 connector
|
||
|
||
`codex` / `claude` 这类 CLI 只会"一问一答开一个进程",没有服务端、不会被 hub 拨号。
|
||
本目录提供一个几百行的桥接进程,把它翻译成 hub 眼里的一个 **connector Agent**:
|
||
|
||
```
|
||
hub ── ws ──> bridge 进程 ──spawn──> codex exec / claude -p / codebuddy -p(一次性子进程)
|
||
│ │
|
||
└── session_key ───────┘ 同一 key 的下发自动 --resume 续上同一段对话
|
||
```
|
||
|
||
思考、工具调用、沙箱都是 CLI 自己的事;bridge 只做三件事:**下发变子进程、JSONL 事件翻译成
|
||
hub 事件、session_key ↔ CLI 会话 id 的映射落盘**。所以新增一家 CLI = 写一个适配器文件,
|
||
hub 侧零改动。
|
||
|
||
## 能力矩阵(本机实测,2026-10-14)
|
||
|
||
| | codex | claude | workbuddy |
|
||
|---|---|---|---|
|
||
| `task`(下发一次对话) | ✅ | ✅ | ✅ |
|
||
| 事件流(正文/推理/工具/日志/usage) | ✅ | ✅ | ✅ 工具带成败 |
|
||
| 续话(同 `session_key` 自动接上) | ✅ `exec resume` | ✅ `--resume` | ✅ `--resume` |
|
||
| `agent.command`(会话内下达指令) | ✅ `codex queue` | ❌ 无原生注入 | ❌ 无原生注入 |
|
||
| `cancel`(hub 取消 → 杀子进程) | ✅ | ✅ | ✅ 无孤儿进程 |
|
||
| `describe`(版本/模型/会话数) | ✅ | ✅ | ✅ |
|
||
|
||
claude 和 workbuddy 没有 `command` 是 **CLI 的限制**,不是桥的缺陷:它们的 `deliver()` 明确回一句
|
||
"请用同一 `session_key` 再发一个 task"(`hub` 上表现为 `delivered: false` + 原因),而不是假装成功。
|
||
|
||
## 三步接入
|
||
|
||
### 1. hub 上注册身份(hub 机器上执行)
|
||
|
||
```bash
|
||
cd <repo>/backend && .venv/bin/python -m agenthub.cli \
|
||
agent add --name codex --display-name 'codex CLI' \
|
||
--connection connector --driver connector --show-token
|
||
```
|
||
|
||
印出来的 `agent_token`(`ag_…`)下一步要用,并且随时能从控制台「接入」页「查看凭证」或
|
||
`agenthub config` 查回来。控制台「接入」向导等价。
|
||
|
||
### 2. Agent 机器上启动桥接进程
|
||
|
||
```bash
|
||
python3 deploy/cli-bridge/bridge.py \
|
||
--hub http://<hub-host>:8100 --token ag_xxx \
|
||
--name codex --cli codex --workdir ~/code/my-project
|
||
```
|
||
|
||
`--workdir` 就是 CLI 干活的目录(子进程 cwd),一次进程只服务一个目录 —— 想让同一个 CLI
|
||
管多个仓库,就起多个桥接进程、注册成 `codex-api` / `codex-web` 这样的不同名字。
|
||
|
||
`--mode` 默认 `readonly`(codex `-s read-only`、claude `--permission-mode plan`),要允许改文件
|
||
才显式给 `--mode write`。默认保守是故意的:这台机器上的 Agent 能被 hub 远程下发,就不该默认有写权限。
|
||
|
||
### 3. 验证
|
||
|
||
```bash
|
||
curl -s -H "X-API-Key: $KEY" http://<hub>:8100/api/v1/agents | python3 -m json.tool
|
||
```
|
||
|
||
看到 `"status": "online"` 即通。刚连上的几秒里它可能还显示 offline,等心跳追上。下发:
|
||
|
||
```bash
|
||
curl -s -X POST -H "X-API-Key: $KEY" -H 'Content-Type: application/json' -d '{
|
||
"agent_id": "agt_xxx",
|
||
"prompt": "读一下 README 第一行,只回复那一行",
|
||
"session_key": "ops",
|
||
"wait": true
|
||
}' http://<hub>:8100/api/v1/tasks
|
||
```
|
||
|
||
第二个用同 `session_key: "ops"` 的 task 会自动续在上一段对话后面。中途下达指令(仅 codex):
|
||
|
||
```bash
|
||
curl -s -X POST -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
|
||
-d '{"command":"message","args":{"session_key":"ops","text":"改成只输出 JSON"}}' \
|
||
http://<hub>:8100/api/v1/agents/codex/command
|
||
```
|
||
|
||
实测语义:返回 `delivered: true` 只代表**排进了队列**,正在跑的那一轮看不到它,下一个 task
|
||
才开始消费。要立刻生效只能 `POST /api/v1/tasks/{id}/cancel` 再重发。
|
||
|
||
## 常驻(macOS LaunchAgent)
|
||
|
||
```bash
|
||
mkdir -p ~/Library/LaunchAgents && cat > ~/Library/LaunchAgents/com.agenthub.cli-bridge.codex.plist <<'PLIST'
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||
<plist version="1.0"><dict>
|
||
<key>Label</key><string>com.agenthub.cli-bridge.codex</string>
|
||
<key>ProgramArguments</key><array>
|
||
<string>/Users/me/nex_agenthub/backend/.venv/bin/python</string>
|
||
<string>/Users/me/nex_agenthub/deploy/cli-bridge/bridge.py</string>
|
||
<string>--token</string><string>ag_xxx</string>
|
||
<string>--name</string><string>codex</string>
|
||
<string>--cli</string><string>codex</string>
|
||
<string>--workdir</string><string>/Users/me/code/my-project</string>
|
||
</array>
|
||
<key>EnvironmentVariables</key><dict>
|
||
<key>PATH</key><string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
|
||
</dict>
|
||
<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
|
||
<key>StandardOutPath</key><string>/Users/me/Library/Logs/agenthub-cli-bridge-codex.log</string>
|
||
<key>StandardErrorPath</key><string>/Users/me/Library/Logs/agenthub-cli-bridge-codex.log</string>
|
||
</dict></plist>
|
||
PLIST
|
||
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.agenthub.cli-bridge.codex.plist
|
||
```
|
||
|
||
三个坑,都踩过:
|
||
|
||
- **`PATH` 必须显式给**。launchd 的默认 PATH 里没有 `/usr/local/bin`,`codex`/`claude` 会"找不到
|
||
可执行文件",而在你终端里手测是好的。
|
||
- **日志写 `~/Library/Logs/`**,别写 `/tmp`(重启即清,正好丢掉最需要的那段现场)。
|
||
- **卸载用 `launchctl bootout gui/$(id -u)/com.agenthub.cli-bridge.codex`**,不要 `kill -9`:
|
||
`KeepAlive` 会让它立刻复活,而且强杀会把正在跑的 CLI 子进程变成孤儿。
|
||
|
||
会话映射存在 `~/.agenthub/cli-bridge-<name>.json`(`--state` 可改)。桥接进程重启续话仍然接得上;
|
||
想开一段全新对话,删掉对应 key 或直接换 `session_key`。
|
||
|
||
## 运行环境
|
||
|
||
- **Python ≥ 3.10**(SDK 用了 `@dataclass(slots=True)`)。macOS 自带的 `/usr/bin/python3` 是 3.9,
|
||
会在 import 阶段直接 TypeError。Agent 机器上没有 venv 就用 nvm/brew 的 3.12,或者 WorkBuddy
|
||
自带的 `~/.workbuddy/binaries/python/versions/3.13.x/bin/python3.13`。除 SDK 那三个文件外只用标准库。
|
||
- CLI 路径自动探测(`which`),探不到用环境变量覆盖:`CODEX_BIN`、`CLAUDE_BIN`、`WORKBUDDY_BIN`。
|
||
WorkBuddy 的 `codebuddy` 不在 PATH 里,适配器已内置 .app 内的绝对路径,装了别的位置就给
|
||
`WORKBUDDY_BIN`。
|
||
- 桥接进程连不上 hub 时会自己指数退避重连,不需要外部守护;但正在跑的 task 会随连接断开而失败。
|
||
|
||
## 实测踩到的 CLI 坑(适配器里已处理,别改回去)
|
||
|
||
1. `codex exec resume` **不接受 `-C` 和 `-s`**(只有 `--json/--skip-git-repo-check/-c`),
|
||
照抄新会话那套参数 → 退出码 2。沙箱在 resume 时只能 `-c sandbox_mode="read-only"`。
|
||
2. claude 和 workbuddy 的 `--add-dir <directories...>` 都是**变长参数**,会把后面的位置参数
|
||
(也就是 prompt)一起吃掉,报 `Input must be provided either through stdin`。cwd 本来就是
|
||
workdir,不需要它;末尾用 `--` 分隔,防 prompt 以 `-` 开头。
|
||
3. claude 模型报错时 `result.subtype` 仍然是 `"success"`,**只有 `is_error` 是真的**。认错了就会
|
||
把 `API Error: 402` 当成正文结果上报给 hub。
|
||
4. resume 失败且这一轮没产出任何文本 → 桥会**丢弃这个 session_key 的映射**并在错误里说明,
|
||
否则一个坏掉的会话 id 会让这个 key 从此永久失败。
|
||
|
||
## WorkBuddy 接入要点
|
||
|
||
WorkBuddy 桌面装在 `/Applications/WorkBuddy.app`,自带 CLI `codebuddy`(**不在 PATH 里**)。它同时
|
||
提供 `--serve`(Web UI + REST + ACP)和无头 `-p --output-format stream-json` 两种被驱动方式:
|
||
|
||
- **本适配器走无头 CLI**(`--cli workbuddy`):和 codex/claude 完全一样的进程模型,hub 侧零改动。
|
||
`--serve` 是它的私有 ACP,**不提供** `/v1/chat/completions`,所以 hub 想 direct 直连必须新写一个
|
||
ACP driver —— 那是 hub 的活儿,不是这里的。
|
||
- 权限档:`readonly` → `--permission-mode plan`(实测仍允许 Glob/Read 这类只读工具);
|
||
`write` → `--permission-mode acceptEdits`(实测 Write 和 Bash 都真放行,`out.txt` 落盘)。
|
||
- 无头模式没人应答授权,**被拒的工具不会报错也不会重试**,只在 `result.permission_denials` 里留痕。
|
||
适配器把它折进 `log` 事件,所以任务"没干成但不报错"时先看那里。
|
||
- 它的 `codebuddy` 入口脚本会 exec 成 node(同一个 pid,不产生进程树),所以 hub cancel 之后
|
||
不会有孤儿进程 —— 实测确认。
|
||
- 注意 `acceptEdits` 下它会往 `~/.codebuddy/projects/<项目>/memory/` 写自己的记忆文件,
|
||
那是 workdir 之外的写入。想让桥接进程绝对干净,就用默认的 `readonly`。
|
||
|
||
### 为什么 WorkBuddy 桌面端里看不到 hub 下发的会话
|
||
|
||
不是配置错,是两套会话存储根本没打通(实测 5.5.6 / CLI 2.137.1):
|
||
|
||
- App 的会话列表读它自己的 sqlite 索引 `~/.workbuddy/workbuddy.db` 的 `sessions` 表,行由 **App 建会话时**写入
|
||
(title/cwd/permission_mode/use_sandbox_cli 这些都是 UI 要用的),之后 App 再通过 ACP 拉起或挂载一个
|
||
codebuddy sidecar —— 证据:会话的 `*.meta.json` 里有 `acpConnectionId`,`~/.workbuddy/sessions/*.json`
|
||
里是每个会话自带的 `http://127.0.0.1:<port>` endpoint。
|
||
- App 主进程 `configureElectronApp()` 给**它自己的**子进程设 `CODEBUDDY_CONFIG_DIR=~/.workbuddy`;我们起的
|
||
无头 CLI 没人设这个变量,默认落 `~/.codebuddy`,App 不读那棵树。反过来无头 CLI 也从不写 App 的 DB
|
||
(`codebuddy.js` 里搜不到 `workbuddy.db`)。
|
||
- deep link 只有 `workbuddy://chat/<sessionId>`(以及 `home`、`experts?expertId=`),只能**跳到已存在的会话**,
|
||
没有"带 prompt 新建会话"的入口。
|
||
|
||
所以:想让它出现在桌面端,只能由 App 自己发起会话,或者去伪造那行 sqlite 记录(不建议 —— App 一升级就碎,
|
||
而且它点开这条会话后会去 attach 一个并不存在的 sidecar)。无头会话的完整记录在
|
||
`~/.codebuddy/projects/<项目slug>/<session_id>.jsonl`,想在终端里看:同一 workdir 下 `codebuddy --resume <session_id>`。
|
||
|
||
### 在线状态跟着桌面端开关(`host()` 钩子)
|
||
|
||
适配器可以提供 `host() -> (可用?, 原因)`,桥就跟着它走:App 没起来时**先不接入**(每 10s 探一次),
|
||
App 退出时先发 `agent.deregister` 再掐掉 websocket —— hub 十几秒内从"已接入"变 offline,不会出现"桌面端都关了
|
||
hub 还亮着"。正在跑的 task 不打断(无头 CLI 不依赖 App,让它把这一轮跑完)。
|
||
|
||
桥进程本身不跟着桌面端退出,它下线后接着每 10s 探一次,WorkBuddy 一重新打开就自己接回去 —— 一次 `bridge.py`
|
||
管一整天的开关。要让开机/崩溃后也自动拉起,再配 LaunchAgent KeepAlive(见上面"常驻")。不想要这层耦合就把
|
||
`adapters/workbuddy.py` 里的 `host()` 删掉:codex/claude 没有这个钩子,行为不受影响。
|
||
|
||
### hub 和 agent 不在一台机器上
|
||
|
||
桥接进程对 hub 是**主动出站**连接,所以 hub 放哪都行,agent 机器不用开端口:
|
||
|
||
```bash
|
||
backend/.venv/bin/python deploy/cli-bridge/bridge.py \
|
||
--hub http://<HUB_IP>:8100 --token <agent_token> \
|
||
--cli workbuddy --name workbuddy --workdir ~/code/目标仓库
|
||
```
|
||
|
||
`describe()` 会带上 `host` / `user` / `workdir`,随心跳进 hub 的 `capabilities`(控制台 agent 详情页
|
||
的 capabilities 面板)—— 分开部署时这是唯一能回答"这个 agent 到底在哪台机器上"的地方。
|
||
|
||
**hub 上能看到的从来不是原生会话,是事件流**:hub 只存 TaskEvent(status/reasoning/delta/tool/…,
|
||
工具输出截到 600 字,没有权限弹窗、没有 file snapshot)。真正的会话记录在 **agent 那台机器**的
|
||
`~/.codebuddy|~/.claude/projects/<cwd-slug>/` 或 `~/.codex/sessions/` 里,所以要"进到那次会话"
|
||
必须回到 agent 机器、并 `cd` 到它当时的 workdir(会话按工作目录归档,站错目录 `-r` 会说找不到会话)。
|
||
|
||
这一步不用手算,交给脚本:
|
||
|
||
```bash
|
||
./scripts/attach.sh tsk_xxx # 本机直接进;agent 在别的机器就自动 ssh -t [user@]host
|
||
./scripts/attach.sh -n tsk_xxx # 只打印命令(远端路径不一样时先看清再改)
|
||
HUB_URL=http://10.0.0.5:8100 HUB_KEY=ah_xxx ./scripts/attach.sh tsk_xxx # 连远端 hub
|
||
```
|
||
|
||
它从 hub 拿 `session_id`(任务事件里最后一条非空的 `payload.session_id`)+ `capabilities` 里的
|
||
`cli/host/user/workdir`,再按各家语法拼命令:workbuddy 与 claude 是 `-r <id>`,codex 是 `resume <id>`。
|
||
进会话是**入站**动作,跨机器要求 agent 机器可 ssh —— 下发任务不需要,进会话需要,这个方向不对称是绕不开的。
|