From 951fada34bee3e081af0e008d6d5edceee3a19e6 Mon Sep 17 00:00:00 2001 From: OpenBot Date: Tue, 6 Oct 2026 09:59:08 +0800 Subject: [PATCH] init: project skeleton + design docs (ACP bridge) --- .gitignore | 6 + README.md | 47 ++++++++ config.example.yaml | 11 ++ docs/ACP_PRIMER.md | 39 ++++++ docs/DESIGN.md | 198 +++++++++++++++++++++++++++++++ pyproject.toml | 16 +++ src/acp_bridge/__init__.py | 1 + src/acp_bridge/__main__.py | 7 ++ src/acp_bridge/acp_client.py | 1 + src/acp_bridge/agent_registry.py | 1 + src/acp_bridge/config.py | 1 + src/acp_bridge/events.py | 1 + src/acp_bridge/nats_service.py | 1 + src/acp_bridge/session.py | 1 + tests/test_acp_frame.py | 1 + 15 files changed, 332 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 config.example.yaml create mode 100644 docs/ACP_PRIMER.md create mode 100644 docs/DESIGN.md create mode 100644 pyproject.toml create mode 100644 src/acp_bridge/__init__.py create mode 100644 src/acp_bridge/__main__.py create mode 100644 src/acp_bridge/acp_client.py create mode 100644 src/acp_bridge/agent_registry.py create mode 100644 src/acp_bridge/config.py create mode 100644 src/acp_bridge/events.py create mode 100644 src/acp_bridge/nats_service.py create mode 100644 src/acp_bridge/session.py create mode 100644 tests/test_acp_frame.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bd59653 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +__pycache__/ +*.pyc +.venv/ +dist/ +.pytest_cache/ +config.local.yaml diff --git a/README.md b/README.md new file mode 100644 index 0000000..26500b0 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# acp-bridge + +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 +``` + +## 定位 + +- **ACP agent 侧代理(client 角色)**:acp-bridge 作为 ACP client 拉起/管理 + 本地 agent 子进程,把 NATS 请求翻译成 ACP 会话。 +- **总线侧服务**:对外表现为 NATS 上的一个可发现服务(类似 A2A 的 + Agent Card 思路,但传输是 NATS)。 + +详细设计见 [docs/DESIGN.md](docs/DESIGN.md)。 + +## 仓库结构 + +``` +acp-bridge/ +├── docs/DESIGN.md # 设计方案(总) +├── docs/ACP_PRIMER.md # ACP 协议速查(方法/生命周期/坑) +├── src/acp_bridge/ +│ ├── __init__.py +│ ├── config.py # 配置加载 +│ ├── agent_registry.py # 本地 agent 进程池(拉起/复用/回收) +│ ├── acp_client.py # ACP JSON-RPC over stdio 客户端(frame 层) +│ ├── session.py # 会话状态机:nats 请求 <-> acp session 映射 +│ ├── events.py # ACP session/update -> NATS 事件主题 映射 +│ └── nats_service.py # NATS 订阅/发布、服务发现广播 +├── tests/ +└── pyproject.toml +``` + +## 快速开始(规划中) + +```bash +uv sync +uv run acp-bridge --config config.yaml +``` + +## 状态 + +设计阶段 → M0 骨架实现中。 diff --git a/config.example.yaml b/config.example.yaml new file mode 100644 index 0000000..ca15ac0 --- /dev/null +++ b/config.example.yaml @@ -0,0 +1,11 @@ +agents: + claude-code: + cmd: ["claude", "--acp"] + cwd_whitelist: ["~/projects/*"] +session: + idle_ttl_s: 1800 + max_sessions: 8 +nats: + url: "nats://127.0.0.1:4222" + inbox: "bots.acp-bridge.in" + events: "bots.acp-bridge.out" diff --git a/docs/ACP_PRIMER.md b/docs/ACP_PRIMER.md new file mode 100644 index 0000000..d8a2ac5 --- /dev/null +++ b/docs/ACP_PRIMER.md @@ -0,0 +1,39 @@ +# ACP 协议速查(Agent Client Protocol, Zed 系) + +> 供 acp-bridge 实现时对照。规范:agentclientprotocol.com +> (spec 源:zed-industries/zed repo docs/src/ai/external-agents.md) + +## 传输与分帧 + +- JSON-RPC 2.0 over stdio,LSP 风格 `Content-Length: N\r\n\r\n` 头分帧。 +- agent 子进程 = ACP **server**;桥 = ACP **client**。 + +## 生命周期(client → server) + +1. `initialize`:`{protocolVersion, clientCapabilities}` + → 返回 agent 能力(loadSession、promptCapabilities…) +2. `session/new`:`{cwd, mcpServers}` → `{sessionId}` +3. `session/load`(可选能力):恢复会话,agent 重放全部历史为 update 流 +4. `session/prompt`:`{sessionId, prompt: [content_block]}` → `{stopReason}` + - content block: text / image / audio / resource_link + - stopReason: end_turn | max_tokens | max_turn_requests | refused | cancelled +5. `session/cancel`:notification,随时打断 + +## server → client 通知与请求 + +- `session/update`(notification,核心事件流): + - sessionUpdate: agent_message_chunk | agent_thought_chunk | + tool_call | tool_call_update | plan | available_commands_update + - tool_call 字段:kind(read/edit/delete/move/search/execute/think/fetch)、 + status(pending/in_progress/completed/failed)、content、rawInput、locations +- `session/request_permission`(**request,需要回包**): + options 含 allow_once/allow_always/reject_once/reject_always → 回 optionId +- client 反向方法:`fs/read_text_file`、`fs/write_text_file`、 + `terminal/create`(output截断/exit)、`terminal/wait_for_exit`… + +## 实现提醒 + +- id 复用规则:同方向自增;notification 无 id。 +- stdout 只能走协议帧——任何 agent 混入的裸日志都会破坏分帧。 +- 权限请求必须回应,否则 agent turn 会挂死;桥侧超时默认拒绝。 +- 版本协商失败(protocolVersion 不兼容)→ 直接报错,不要猜。 diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..65364ad --- /dev/null +++ b/docs/DESIGN.md @@ -0,0 +1,198 @@ +# acp-bridge 设计方案 + +> 版本:draft v0.1(2026-10-05) +> 目标:IM/NATS 总线 ↔ 本地 ACP agent 的双向桥 + +## 0. 问题定义 + +现状两条链路各自独立: + +- Octop/botflow:**IM 用户 ↔ Agent**,传输 NATS(`bots.*` 主题) +- 编码 agent(Claude Code 等):**编辑器 ↔ Agent**,传输 ACP(stdio JSON-RPC) + +缺口:总线上没有"编码 agent"这个服务类别。写一个桥,把本地 ACP agent +注册成总线服务,编排方(Octop 机器人、其他 worker、未来 orchestrator) +就能像调普通服务一样派编码任务。 + +**为什么走 ACP 而不是直接 shell 调 CLI**: +- 统一权限审批(ACP 反转文件系统所有权,客户端可审计每次 read/edit) +- 统一事件流(session/update 分类事件,天然映射成总线消息) +- 一次接入,所有 ACP 兼容 agent 通用(40+,还在增长) + +## 1. 总体架构 + +``` + NATS bus + ┌──────────┐ ┌───────────────────────────┐ ┌──────────────┐ + │ Octop IM │──▶│ bots.acp-bridge.in (svc) │◀──│ 其他 worker │ + └──────────┘ └────────────┬──────────────┘ └──────────────┘ + │ + ┌──────────▼──────────┐ + │ acp-bridge │ + │ ┌───────────────┐ │ + │ │ nats_service │ │ 订阅 svc 主题、发现广播 + │ ├───────────────┤ │ + │ │ session mgr │ │ nats req <-> acp session + │ ├───────────────┤ │ + │ │ agent pool │ │ 子进程生命周期管理 + │ ├───────────────┤ │ + │ │ acp_client │ │ stdio JSON-RPC 分帧 + │ └───────────────┘ │ + └──────────┬──────────┘ + stdio/ACP │ + ┌──────────────┬───────┴─────┬──────────────┐ + ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌─────▼────┐ + │claude- │ │ codex │ │gemini │ │ opencode │ + │acp shim │ │ (native)│ │cli --acp│ │ (native) │ + └─────────┘ └─────────┘ └─────────┘ └──────────┘ +``` + +角色说明:acp-bridge 在 ACP 协议里是 **client**;agent 子进程是 server。 +NATS 侧 acp-bridge 是 **server**。桥是两种协议之间的翻译层。 + +## 2. 总线接口设计 + +### 2.1 主题约定(沿用 bots.* 体系) + +| 主题 | 方向 | 用途 | +|---|---|---| +| `bots.acp-bridge.in` | 入 | 服务请求(request/reply) | +| `bots.acp-bridge.out` | 出 | 事件流(会话进度,供订阅) | +| `bots.registry.upsert` / `.down` | 出 | 服务发现广播(见 §5) | + +### 2.2 请求协议(NATS request,JSON) + +```jsonc +// 派任务 +// PUB bots.acp-bridge.in +{ + "v": 1, + "op": "prompt", + "session_id": "s-abc123", // 可选;缺省=新建会话 + "agent": "claude-code", // agent 名(见 2.4 发现接口) + "cwd": "/path/to/workdir", // 必须在白名单内(§6) + "text": "把 config.py 里的超时改成 60s 并跑通测试", + "timeout_ms": 600000 +} +``` + +响应(reply inbox)分两类: + +- **终态响应**(request 的直接回包): + ```jsonc + { "v": 1, "op": "prompt", "ok": true, + "session_id": "s-abc123", "stop_reason": "end_turn", + "result_text": "已改完,测试 8/8 通过" } + ``` +- **过程事件**(PUB 到 `bots.acp-bridge.out`,不占 request): + ```jsonc + { "v": 1, "event": "agent_message_delta", "session_id": "s-abc123", + "seq": 42, "ts": 1728100000.123, "payload": { "text_chunk": "..." } } + ``` + +### 2.3 op 目录 + +| op | 语义 | 对应 ACP 方法 | +|---|---|---| +| `list_agents` | 列出可用 agent 及能力 | Agent Card 思路(自报家门) | +| `new_session` | 建会话(可带 cwd/mcp_servers/model) | `session/new` | +| `load_session` | 恢复历史会话 | `session/load` | +| `prompt` | 提交一轮任务 | `session/prompt` | +| `cancel` | 打断进行中的 turn | `session/cancel` | +| `permission_reply` | 回答权限请求 | (对应 `session/request_permission` 的应答) | + +### 2.4 事件类型(ACP session/update → NATS event 1:1 映射) + +| ACP update | NATS event | 说明 | +|---|---|---| +| agent_message_chunk | `agent_message_delta` | 流式文本增量 | +| agent_thought_chunk | `agent_thinking` | 思考流 | +| tool_call (start) | `tool_start` | 读/编辑/执行等,带 diff | +| tool_call_update | `tool_end` | 工具结果 | +| plan | `plan` | todo 列表变化 | +| request_permission | `permission_request` | **同时挂起 turn**,等 `permission_reply` | +| turn 结束 | `turn_end` | 终态,含 stop_reason | + +事件带单调 `seq`(每会话独立),消费者可检测丢失并触发全量补拉 +(`op: get_state`,M2 实现)。 + +## 3. ACP 客户端层(acp_client.py) + +- 传输:`subprocess.Popen(stdin/stdout)`,JSON-RPC 2.0 按 + `Content-Length` 头分帧(LSP 风格)。 +- 初始化握手:`initialize`(协议版本协商 + capabilities 交换)→ + 确认 `loadSession` 等能力。 +- 必须实现的 **client 侧方法**(agent 会反向调用): + - `fs/read_text_file` / `fs/write_text_file`:默认透传真实文件系统 + (本地桥是全权模式;未来需要审批时在这两个入口挂检查点) + - `terminal/create`:透传,但记录审计日志 + - `session/request_permission`:**不直接回答**,转成总线 + `permission_request` 事件挂起,等 `permission_reply` 到达后回包 + (超时按 `allow` 选项中保守项处理,默认 deny) +- 每个会话独立一个 agent 子进程(M0 简化;进程池复用见 §4)。 + +## 4. Agent 进程池(agent_registry.py) + +配置驱动: + +```yaml +agents: + claude-code: + cmd: ["claude", "--acp"] # 或 npx @anthropic-ai/claude-agent-acp + cwd_whitelist: ["~/projects/*"] + default_model: null + opencode: + cmd: ["opencode"] + cwd_whitelist: ["~/projects/*"] +session: + idle_ttl_s: 1800 # 空闲会话进程回收 + max_sessions: 8 +``` + +- 启动时**不**预拉进程;首个 new_session 拉起,idle_ttl 到期 kill。 +- 崩溃检测:进程退出 → 该会话所有挂起 request 返回错误事件 + `session_crashed`;支持配置自动重启 + `load_session` 恢复(M2)。 + +## 5. 服务发现 + +桥启动后向 `bots.registry.upsert` 广播自述(A2A Agent Card 的总线版): + +```jsonc +{ "service": "acp-bridge", "node": "", + "inbox": "bots.acp-bridge.in", + "agents": [ {"name": "claude-code", "modes": ["text"], + "capabilities": ["load_session"]} ], + "version": "0.1.0" } +``` + +心跳 20s 一次(TTL 60s)。M1 先做简单广播;M2 若引入 JetStream KV +注册中心(见总体规划),直接挂上去。 + +## 6. 安全边界 + +1. **cwd 白名单**:`new_session` 的 cwd 必须命中 `cwd_whitelist` glob。 +2. **权限守门**:`request_permission` 一律上抛到总线(人工/规则回答), + 桥自身绝不自动 allow 危险操作(delete/execute 类)。 +3. **输出限流**:事件流单会话限速(如 50 事件/s,超出合并 delta), + 防止 agent 疯狂输出打爆总线。 +4. **无鉴权假设**:内网 NATS 信任域内运行;如果暴露到公网必须先加 + NATS 账号体系 + 每会话 token。 + +## 7. 里程碑 + +| 阶段 | 内容 | 验收 | +|---|---|---| +| **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 端到端 | 企微里下指令看到流式进度 | + +## 8. 风险与已知坑 + +- ACP 官方 SDK 主要是 Rust/TS;Python 侧走 `acp` PyPI 包或直接手写 + 分帧(协议简单,M0 选择手写,减依赖)。 +- `claude --acp` shim 的认证:agent 自己管 API key,桥不碰凭据。 +- stdout 混入非协议输出(某些 agent 打日志到 stdout)会破坏分帧 → + 解析失败时整会话标记 crashed,日志落盘排查。 +- 事件回放:NATS core 不持久化,消费者掉线丢事件 → M2 用 + `get_state` 补拉兜底,或迁 JetStream。 diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..e6a6c1b --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,16 @@ +[project] +name = "acp-bridge" +version = "0.1.0" +description = "IM/NATS to local ACP (Agent Client Protocol) bridge" +requires-python = ">=3.11" +dependencies = [] # M0 零依赖:stdlib only(subprocess/json/asyncio 待定) + +[project.scripts] +acp-bridge = "acp_bridge.__main__:main" + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.pytest.ini_options] +testpaths = ["tests"] diff --git a/src/acp_bridge/__init__.py b/src/acp_bridge/__init__.py new file mode 100644 index 0000000..3dc1f76 --- /dev/null +++ b/src/acp_bridge/__init__.py @@ -0,0 +1 @@ +__version__ = "0.1.0" diff --git a/src/acp_bridge/__main__.py b/src/acp_bridge/__main__.py new file mode 100644 index 0000000..033c50b --- /dev/null +++ b/src/acp_bridge/__main__.py @@ -0,0 +1,7 @@ +"""CLI 入口(M0: 仅骨架)。""" + +def main() -> None: + raise SystemExit("acp-bridge: implementation pending (see docs/DESIGN.md milestones)") + +if __name__ == "__main__": + main() diff --git a/src/acp_bridge/acp_client.py b/src/acp_bridge/acp_client.py new file mode 100644 index 0000000..88692d6 --- /dev/null +++ b/src/acp_bridge/acp_client.py @@ -0,0 +1 @@ +"""ACP JSON-RPC over stdio 分帧与调用(M0 核心,见 docs/ACP_PRIMER.md)。""" diff --git a/src/acp_bridge/agent_registry.py b/src/acp_bridge/agent_registry.py new file mode 100644 index 0000000..4a53c52 --- /dev/null +++ b/src/acp_bridge/agent_registry.py @@ -0,0 +1 @@ +"""Agent 子进程生命周期管理(M2)。""" diff --git a/src/acp_bridge/config.py b/src/acp_bridge/config.py new file mode 100644 index 0000000..d3f08ac --- /dev/null +++ b/src/acp_bridge/config.py @@ -0,0 +1 @@ +"""配置加载(M1 实现,schema 见 docs/DESIGN.md §4)。""" diff --git a/src/acp_bridge/events.py b/src/acp_bridge/events.py new file mode 100644 index 0000000..f742bc5 --- /dev/null +++ b/src/acp_bridge/events.py @@ -0,0 +1 @@ +"""ACP session/update -> NATS 事件映射(M1,见 DESIGN §2.4)。""" diff --git a/src/acp_bridge/nats_service.py b/src/acp_bridge/nats_service.py new file mode 100644 index 0000000..88a9d7c --- /dev/null +++ b/src/acp_bridge/nats_service.py @@ -0,0 +1 @@ +"""NATS 订阅/发布/发现广播(M1,沿用 bots.* 主题约定)。""" diff --git a/src/acp_bridge/session.py b/src/acp_bridge/session.py new file mode 100644 index 0000000..fcc0813 --- /dev/null +++ b/src/acp_bridge/session.py @@ -0,0 +1 @@ +"""NATS 请求 <-> ACP 会话映射(M1)。""" diff --git a/tests/test_acp_frame.py b/tests/test_acp_frame.py new file mode 100644 index 0000000..bc0e192 --- /dev/null +++ b/tests/test_acp_frame.py @@ -0,0 +1 @@ +"""M0 首个测试:Content-Length 分帧编解码。"""