agenthub/deploy/cli-bridge/README.md

13 KiB
Raw Permalink Blame History

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 机器上执行)

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 机器上启动桥接进程

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. 验证

curl -s -H "X-API-Key: $KEY" http://<hub>:8100/api/v1/agents | python3 -m json.tool

看到 "status": "online" 即通。刚连上的几秒里它可能还显示 offline,等心跳追上。下发:

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):

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)

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 机器不用开端口:

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 会说找不到会话)。

这一步不用手算,交给脚本:

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