init: project skeleton + design docs (ACP bridge)
This commit is contained in:
commit
951fada34b
15 files changed
+332
No files matched your search
@@ -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 不兼容)→ 直接报错,不要猜。
|
||||
+198
@@ -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 <reply inbox>
|
||||
{
|
||||
"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": "<hostname>",
|
||||
"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。
|
||||
Reference in new issue
Block a user