agenthub/deploy/cli-bridge/README.md

219 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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 —— 下发任务不需要,进会话需要,这个方向不对称是绕不开的。