rename acp-bridge -> agenthub; design v0.2: front-end agnostic entry + supervisor orchestration + depth guard

This commit is contained in:
openbot committed 2026-10-06 10:16:15 +08:00
1 parent 951fada34b
commit de4a3337ec
11 files changed
+138 -78

No files matched your search

+5 -5
View File
@@ -1,16 +1,16 @@
# acp-bridge # agenthub
IM/NATS ↔ 本地 ACP 桥:让总线上的编排方(Octop / botflow / 任意 worker) IM/NATS ↔ 本地 ACP 桥:让总线上的编排方(Octop / botflow / 任意 worker)
能够**发现并驱动**运行在本地机器上的 ACP 编码 agent 能够**发现并驱动**运行在本地机器上的 ACP 编码 agent
(Claude Code、Codex、Gemini CLI、OpenCode …),并收回结构化事件流。 (Claude Code、Codex、Gemini CLI、OpenCode …),并收回结构化事件流。
``` ```
IM 用户 ── Octop ── NATS bus ── acp-bridge ── stdio JSON-RPC (ACP) ── coding agent IM 用户 ── Octop ── NATS bus ── agenthub ── stdio JSON-RPC (ACP) ── coding agent
``` ```
## 定位 ## 定位
- **ACP agent 侧代理(client 角色)**:acp-bridge 作为 ACP client 拉起/管理 - **ACP agent 侧代理(client 角色)**:agenthub 作为 ACP client 拉起/管理
本地 agent 子进程,把 NATS 请求翻译成 ACP 会话。 本地 agent 子进程,把 NATS 请求翻译成 ACP 会话。
- **总线侧服务**:对外表现为 NATS 上的一个可发现服务(类似 A2A 的 - **总线侧服务**:对外表现为 NATS 上的一个可发现服务(类似 A2A 的
Agent Card 思路,但传输是 NATS)。 Agent Card 思路,但传输是 NATS)。
@@ -20,7 +20,7 @@ IM 用户 ── Octop ── NATS bus ── acp-bridge ── stdio JSON-RPC (
## 仓库结构 ## 仓库结构
``` ```
acp-bridge/ agenthub/
├── docs/DESIGN.md # 设计方案(总) ├── docs/DESIGN.md # 设计方案(总)
├── docs/ACP_PRIMER.md # ACP 协议速查(方法/生命周期/坑) ├── docs/ACP_PRIMER.md # ACP 协议速查(方法/生命周期/坑)
├── src/acp_bridge/ ├── src/acp_bridge/
@@ -39,7 +39,7 @@ acp-bridge/
```bash ```bash
uv sync uv sync
uv run acp-bridge --config config.yaml uv run agenthub --config config.yaml
``` ```
## 状态 ## 状态
+132 -72
View File
@@ -1,36 +1,77 @@
# acp-bridge 设计方案 # agenthub 设计方案
> 版本:draft v0.1(2026-10-05) > 版本:v0.2(2026-10-05)
> 目标:IM/NATS 总线 ↔ 本地 ACP agent 的双向桥 > 目标:把本地 ACP 编码 agent 桥接到 NATS 消息总线上,形成可发现、可派活、
> 可编排的 agent 服务网格。IM(Octop)只是前端的一种。
## 0. 问题定义 ## 0. 问题定义与形态演进
现状两条链路各自独立: 现状两条链路各自独立:
- Octop/botflow:**IM 用户 ↔ Agent**,传输 NATS(`bots.*` 主题) - Octop/botflow:**IM 用户 ↔ Agent**,传输 NATS(`bots.*` 主题)
- 编码 agent(Claude Code 等):**编辑器 ↔ Agent**,传输 ACP(stdio JSON-RPC) - 编码 agent(Claude Code / Codex / Gemini CLI / OpenCode …):**编辑器 ↔ Agent**,传输 ACP(stdio JSON-RPC)
缺口:总线上没有"编码 agent"这个服务类别。写一个桥,把本地 ACP agent ### 形态定位(v0.2 关键修正)
注册成总线服务,编排方(Octop 机器人、其他 worker、未来 orchestrator)
就能像调普通服务一样派编码任务。 agenthub **不绑定任何前端**。它的入口就是消息总线:
```
形态 B(本设计):
IM(Octop) ──┐
总管 agent ──┼──▶ NATS ──▶ agenthub ──▶ codex / opencode / pi / gemini...
cron/CI ───┘ (stdin/ACP 子进程) (可再派生子任务,最终汇总回入口)
```
- 对前:暴露统一的 op 接口(prompt/new_session/...),调用方是 IM 网关、
supervisor agent、cron,**一视同仁**
- 对后:把 ACP agent 变成总线上的可发现服务
**为什么走 ACP 而不是直接 shell 调 CLI**: **为什么走 ACP 而不是直接 shell 调 CLI**:
- 统一权限审批(ACP 反转文件系统所有权,客户端可审计每次 read/edit) - 统一权限审批(ACP 反转文件系统所有权,客户端可审计每次 read/edit/execute)
- 统一事件流(session/update 分类事件,天然映射成总线消息) - 统一事件流(session/update 分类事件,天然映射成总线消息)
- 一次接入,所有 ACP 兼容 agent 通用(40+,还在增长) - 一次接入,所有 ACP 兼容 agent 通用(40+,还在增长)
## 1. 总体架构 ## 1. 角色模型:三责分离(编排怎么长出来)
```
┌────────────────────────────────────────────┐
│ supervisor agent(总管,如 codex) │ ← 决定"派什么活"(LLM)
│ 它自己也是 ACP agent,也跑在 agenthub 上 │
└──────────────┬─────────────────────────────┘
│ 派子任务:prompt op(带 session_id + depth)
┌──────────────▼─────────────────────────────┐
│ agenthub(= gateway + registry + 护栏) │
│ ① gateway:op 路由到正确的 agent │
│ ② registry:哪些 agent 在线、能力是什么 │
│ ③ 护栏:预算/超时/深度上限(代码管,非 LLM 管)│
└──────────────┬─────────────────────────────┘
┌──────────────▼─────────────────────────────┐
│ worker agents:opencode / pi / gemini ... │ ← 干活
└────────────────────────────────────────────┘
```
原则:
- **supervisor 是 agent,agenthub 是普通服务**。分拆/汇总的"智能"在
supervisor 的 LLM 里;agenthub 只提供机制
- **汇总不需要专门机制**:supervisor 用 session_id 收各子任务 turn 终态,
把结果拼进自己的上下文,最后一轮输出回调用方——ACP 会话语义天然支持
- **递归防护**:`new_session` 请求带 `depth`(默认 0),worker 会话派生
子会话时 agenthub 强制 depth+1,超过 `max_depth`(默认 3)直接拒绝。
没有这个,supervisor 套 supervisor 会无限递归烧穿
## 2. 总体架构
``` ```
NATS bus NATS bus
┌──────────┐ ┌───────────────────────────┐ ┌──────────────┐ ┌──────────┐ ┌───────────────────────────┐ ┌──────────────┐
│ Octop IM │──▶│ bots.acp-bridge.in (svc) │◀──│ 其他 worker │ │ Octop IM │──▶│ bots.agenthub.in (svc) │◀──│ supervisor │
└──────────┘ └────────────┬──────────────┘ └──────────────┘ └──────────┘ └────────────┬──────────────┘ │ agent/cron等 │
│ │ └──────────────┘
┌──────────▼──────────┐ ┌──────────▼──────────┐
│ acp-bridge │ │ agenthub │
│ ┌───────────────┐ │ │ ┌───────────────┐ │
│ │ nats_service │ │ 订阅 svc 主题、发现广播 │ │ nats_service │ │ 订阅/发布/发现广播
│ ├───────────────┤ │ │ ├───────────────┤ │
│ │ session mgr │ │ nats req <-> acp session │ │ session mgr │ │ nats req <-> acp session
│ ├───────────────┤ │ │ ├───────────────┤ │
@@ -47,30 +88,31 @@
└─────────┘ └─────────┘ └─────────┘ └──────────┘ └─────────┘ └─────────┘ └─────────┘ └──────────┘
``` ```
角色说明:acp-bridge 在 ACP 协议里是 **client**;agent 子进程是 server。 角色说明:agenthub 在 ACP 协议里是 **client**;agent 子进程是 server。
NATS 侧 acp-bridge 是 **server**。桥是两种协议之间的翻译层。 NATS 侧 agenthub 是 **server**。hub 是两种协议之间的翻译层。
## 2. 总线接口设计 ## 3. 总线接口设计
### 2.1 主题约定(沿用 bots.* 体系) ### 3.1 主题约定(沿用 bots.* 体系)
| 主题 | 方向 | 用途 | | 主题 | 方向 | 用途 |
|---|---|---| |---|---|---|
| `bots.acp-bridge.in` | 入 | 服务请求(request/reply) | | `bots.agenthub.in` | 入 | 服务请求(request/reply) |
| `bots.acp-bridge.out` | 出 | 事件流(会话进度,供订阅) | | `bots.agenthub.out` | 出 | 事件流(会话进度,供订阅) |
| `bots.registry.upsert` / `.down` | 出 | 服务发现广播(见 §5) | | `bots.registry.upsert` / `.down` | 出 | 服务发现广播(见 §6) |
### 2.2 请求协议(NATS request,JSON) ### 3.2 请求协议(NATS request,JSON)
```jsonc ```jsonc
// 派任务 // 派任务
// PUB bots.acp-bridge.in <reply inbox> // PUB bots.agenthub.in <reply inbox>
{ {
"v": 1, "v": 1,
"op": "prompt", "op": "prompt",
"session_id": "s-abc123", // 可选;缺省=新建会话 "session_id": "s-abc123", // 可选;缺省=新建会话
"agent": "claude-code", // agent 名(见 2.4 发现接口) "agent": "claude-code", // agent 名(见 list_agents)
"cwd": "/path/to/workdir", // 必须在白名单内(§6) "cwd": "/path/to/workdir", // 必须在白名单内(§7)
"depth": 0, // 编排深度,默认 0
"text": "把 config.py 里的超时改成 60s 并跑通测试", "text": "把 config.py 里的超时改成 60s 并跑通测试",
"timeout_ms": 600000 "timeout_ms": 600000
} }
@@ -81,27 +123,29 @@ NATS 侧 acp-bridge 是 **server**。桥是两种协议之间的翻译层。
- **终态响应**(request 的直接回包): - **终态响应**(request 的直接回包):
```jsonc ```jsonc
{ "v": 1, "op": "prompt", "ok": true, { "v": 1, "op": "prompt", "ok": true,
"session_id": "s-abc123", "stop_reason": "end_turn", "session_id": "s-abc123", "depth": 0,
"stop_reason": "end_turn",
"result_text": "已改完,测试 8/8 通过" } "result_text": "已改完,测试 8/8 通过" }
``` ```
- **过程事件**(PUB 到 `bots.acp-bridge.out`,不占 request): - **过程事件**(PUB 到 `bots.agenthub.out`,不占 request):
```jsonc ```jsonc
{ "v": 1, "event": "agent_message_delta", "session_id": "s-abc123", { "v": 1, "event": "agent_message_delta", "session_id": "s-abc123",
"seq": 42, "ts": 1728100000.123, "payload": { "text_chunk": "..." } } "seq": 42, "ts": 1728100000.123, "payload": { "text_chunk": "..." } }
``` ```
### 2.3 op 目录 ### 3.3 op 目录
| op | 语义 | 对应 ACP 方法 | | op | 语义 | 对应 ACP 方法 |
|---|---|---| |---|---|---|
| `list_agents` | 列出可用 agent 及能力 | Agent Card 思路(自报家门) | | `list_agents` | 列出可用 agent 及能力 | Agent Card 思路(自报家门) |
| `new_session` | 建会话(可带 cwd/mcp_servers/model) | `session/new` | | `new_session` | 建会话(cwd/mcp_servers/model/depth) | `session/new` |
| `load_session` | 恢复历史会话 | `session/load` | | `load_session` | 恢复历史会话 | `session/load` |
| `prompt` | 提交一轮任务 | `session/prompt` | | `prompt` | 提交一轮任务 | `session/prompt` |
| `cancel` | 打断进行中的 turn | `session/cancel` | | `cancel` | 打断进行中的 turn | `session/cancel` |
| `permission_reply` | 回答权限请求 | (对应 `session/request_permission` 的应答) | | `permission_reply` | 回答权限请求 | (对应 `session/request_permission` 的应答) |
| `get_state` | 补拉会话当前状态(丢事件兜底,M2) | — |
### 2.4 事件类型(ACP session/update → NATS event 1:1 映射) ### 3.4 事件类型(ACP session/update → NATS event 1:1 映射)
| ACP update | NATS event | 说明 | | ACP update | NATS event | 说明 |
|---|---|---| |---|---|---|
@@ -113,27 +157,27 @@ NATS 侧 acp-bridge 是 **server**。桥是两种协议之间的翻译层。
| request_permission | `permission_request` | **同时挂起 turn**,等 `permission_reply` | | request_permission | `permission_request` | **同时挂起 turn**,等 `permission_reply` |
| turn 结束 | `turn_end` | 终态,含 stop_reason | | turn 结束 | `turn_end` | 终态,含 stop_reason |
事件带单调 `seq`(每会话独立),消费者可检测丢失并触发全量补拉 事件带单调 `seq`(每会话独立),消费者可检测丢失并触发 `get_state` 补拉。
(`op: get_state`,M2 实现)。
## 3. ACP 客户端层(acp_client.py) ## 4. ACP 客户端层(acp_client.py)
- 传输:`subprocess.Popen(stdin/stdout)`,JSON-RPC 2.0 按 - 传输:`subprocess.Popen(stdin/stdout)`,JSON-RPC 2.0 按
`Content-Length` 头分帧(LSP 风格)。 `Content-Length` 头分帧(LSP 风格)。M0 手写分帧,零依赖
(协议只有一层帧格式,不值得引 SDK)。
- 初始化握手:`initialize`(协议版本协商 + capabilities 交换)→ - 初始化握手:`initialize`(协议版本协商 + capabilities 交换)→
确认 `loadSession` 等能力。 确认 loadSession 等能力。
- 必须实现的 **client 侧方法**(agent 会反向调用): - 必须实现的 **client 侧方法**(agent 会反向调用):
- `fs/read_text_file` / `fs/write_text_file`:默认透传真实文件系统 - `fs/read_text_file` / `fs/write_text_file`:默认透传真实文件系统
(本地桥是全权模式;未来需要审批时在这两个入口挂检查点) (本地全权模式;未来需要审批时在这两个入口挂检查点)
- `terminal/create`:透传,但记录审计日志 - `terminal/create`:透传,记录审计日志
- `session/request_permission`:**不直接回答**,转成总线 - `session/request_permission`:**不直接回答**,转成总线
`permission_request` 事件挂起,等 `permission_reply` 到达后回包 `permission_request` 事件挂起,等 `permission_reply` 到达后回包
(超时按 `allow` 选项中保守项处理,默认 deny) (超时按保守项处理,默认 deny)
- 每个会话独立一个 agent 子进程(M0 简化;进程池复用见 §4)。 - 每个会话独立一个 agent 子进程(M0;进程池复用 M2)。
## 4. Agent 进程池(agent_registry.py) ## 5. Agent 进程池(agent_registry.py)
配置驱动: 配置驱动(config.example.yaml):
```yaml ```yaml
agents: agents:
@@ -147,52 +191,68 @@ agents:
session: session:
idle_ttl_s: 1800 # 空闲会话进程回收 idle_ttl_s: 1800 # 空闲会话进程回收
max_sessions: 8 max_sessions: 8
orchestration:
max_depth: 3 # supervisor 递归上限
nats:
url: "nats://127.0.0.1:4222"
inbox: "bots.agenthub.in"
events: "bots.agenthub.out"
``` ```
- 启动时**不**预拉进程;首个 new_session 拉起,idle_ttl 到期 kill。 - 启动时不预拉进程;首个 new_session 拉起,idle_ttl 到期 kill。
- 崩溃检测:进程退出 → 该会话所有挂起 request 返回错误事件 - 崩溃检测:进程退出 → 该会话所有挂起 request 返回 `session_crashed`
`session_crashed`;支持配置自动重启 + `load_session` 恢复(M2)。 错误事件;M2 支持自动重启 + `load_session` 恢复。
## 5. 服务发现 ## 6. 服务发现
桥启动后向 `bots.registry.upsert` 广播自述(A2A Agent Card 的总线版): agenthub 启动后向 `bots.registry.upsert` 广播自述(A2A Agent Card 的总线版):
```jsonc ```jsonc
{ "service": "acp-bridge", "node": "<hostname>", { "service": "agenthub", "node": "<hostname>",
"inbox": "bots.acp-bridge.in", "inbox": "bots.agenthub.in",
"agents": [ {"name": "claude-code", "modes": ["text"], "agents": [ {"name": "claude-code", "modes": ["text"],
"capabilities": ["load_session"]} ], "capabilities": ["load_session"]} ],
"version": "0.1.0" } "version": "0.2.0" }
``` ```
心跳 20s 一次(TTL 60s)。M1 先做简单广播;M2 若引入 JetStream KV 心跳 20s(TTL 60s)。M1 简单广播;M2 若引入 JetStream KV 注册中心
注册中心(见总体规划),直接挂上去。 (nats-sync 加 KV 子集后),直接挂接,支持客户端冷启动全量拉取与
崩溃自动下线。
## 6. 安全边界 ## 7. 安全边界
1. **cwd 白名单**:`new_session` 的 cwd 必须命中 `cwd_whitelist` glob。 1. **cwd 白名单**:new_session 的 cwd 必须命中 `cwd_whitelist` glob
2. **权限守门**:`request_permission` 一律上抛到总线(人工/规则回答), 2. **权限守门**:request_permission 一律上抛总线(人工/规则回答),
桥自身绝不自动 allow 危险操作(delete/execute 类)。 agenthub 绝不自动 allow 危险操作(delete/execute 类)
3. **输出限流**:事件流单会话限速(如 50 事件/s,超出合并 delta), 3. **输出限流**:事件流单会话限速(50 事件/s,超出合并 delta),
防止 agent 疯狂输出打爆总线。 防止 agent 疯狂输出打爆总线
4. **无鉴权假设**:内网 NATS 信任域内运行;如果暴露到公网必须先加 4. **深度护栏**:max_depth 递归上限(§1)
NATS 账号体系 + 每会话 token。 5. **无鉴权假设**:内网 NATS 信任域内运行;暴露公网前必须加
NATS 账号体系 + 每会话 token
## 7. 里程碑 ## 8. 里程碑
| 阶段 | 内容 | 验收 | | 阶段 | 内容 | 验收 |
|---|---|---| |---|---|---|
| **M0** | acp_client 分帧层 + initialize/session/new/prompt 通路;接通 claude-code 跑通一次真实会话(stdio 直连测试,不进总线) | 单测 + 手工脚本输出完整 update 流 | | **M0** | acp_client 分帧层 + initialize/session/new/prompt 通路;接通 claude-code 跑通一次真实会话(stdio 直连测试,不进总线) | 单测 + 手工脚本输出完整 update 流 |
| **M1** | nats_service + 事件映射 + permission 挂起/恢复;e2e:NATS 客户端发 prompt → 收全事件流 → 终态回包 | pytest e2e 全绿(含 cancel、crash) | | **M1** | nats_service + 事件映射 + permission 挂起/恢复 + 发现广播;e2e:NATS 客户端发 prompt → 收全事件流 → 终态回包 | pytest e2e 全绿(含 cancel、crash) |
| **M2** | 会话恢复(session/load)、进程池、注册中心接入、get_state 补拉 | 杀进程重启恢复会话 | | **M2** | 会话恢复(session/load)、进程池、get_state 补拉、JetStream KV 注册中心接入、depth 护栏 | 杀进程重启恢复会话;递归派生被拒绝 |
| **M3** | Octop 侧接一个 `/code` 命令走通 IM 端到端 | 企微里下指令看到流式进度 | | **M3** | supervisor 形态验证:codex 作为 supervisor 派子任务给 opencode 并汇总 | 一次 IM 指令 → 多 agent 协作 → 汇总回包 |
| **M4** | Octop 侧接 `/code` 命令走通 IM 端到端 | 企微里下指令看到流式进度 |
## 8. 风险与已知坑 ## 9. 风险与已知坑
- ACP 官方 SDK 主要是 Rust/TS;Python 侧走 `acp` PyPI 包或直接手写 - ACP 官方 SDK 主要是 Rust/TS;Python 侧手写分帧(M0 决策,减依赖)
分帧(协议简单,M0 选择手写,减依赖)。 - `claude --acp` shim 的认证:agent 自己管 API key,agenthub 不碰凭据
- `claude --acp` shim 的认证:agent 自己管 API key,桥不碰凭据。 - stdout 混入非协议输出会破坏分帧 → 解析失败整会话标记 crashed,日志落盘
- stdout 混入非协议输出(某些 agent 打日志到 stdout)会破坏分帧 → - 事件回放:NATS core 不持久化,消费者掉线丢事件 → `get_state` 补拉
解析失败时整会话标记 crashed,日志落盘排查。 兜底(M2),或迁 JetStream
- 事件回放:NATS core 不持久化,消费者掉线丢事件 → M2 用 - supervisor 自我递归:同 agent 既当 supervisor 又当 worker 时 depth
`get_state` 补拉兜底,或迁 JetStream。 护栏是唯一防线,max_depth 不可配置过大
## 10. 命名与发布
- 仓库:`vxquant/agenthub`(Gitea 主仓;按发布流程,稳定后镜像 GitHub)
- import/包名:`agenthub`(PyPI 的 `agenthub` 当前空闲,可用;
`bothub`/`agent-hub` 均已被占,弃用)
- 未来若发布 PyPI:直接用 `agenthub` 名
+1 -1
View File
@@ -6,7 +6,7 @@ requires-python = ">=3.11"
dependencies = [] # M0 零依赖:stdlib only(subprocess/json/asyncio 待定) dependencies = [] # M0 零依赖:stdlib only(subprocess/json/asyncio 待定)
[project.scripts] [project.scripts]
acp-bridge = "acp_bridge.__main__:main" agenthub = "agenthub.__main__:main"
[build-system] [build-system]
requires = ["hatchling"] requires = ["hatchling"]
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.