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