ACP host 完整度:补全 fs/terminal 能力与 SessionUpdate 处理(当前为 V1 子集)
- Ngôn ngữ chính
- Rust
- Star
- 2.3k
- Fork
- 231
- Merge trung bình
- 2 giờ 49 phút
- Pull request đã merge (30 ngày)
- 589
Mô tả
## 背景
随着把外部 agent 通过 ACP 接入(opencode / claude-code / codex,以及 #963 新增的 omp),BitFun 已经是一个 ACP **host/client**。但目前实现的是 ACP V1 的一个**可用子集**,并非完整标准协议。本 issue 跟踪"补全到完整 ACP host"的差距与优先级。
相关:#963(omp via ACP)、#931(自定义多运行时方案,建议关闭、改走 ACP)。
## 现状基线(client 侧,`ProtocolVersion::V1`)
已实现:
- `initialize` + client_info
- `session/new` `load` `resume` `prompt` `cancel` `close`
- `session/set_model`
- agent→client 回调:`session/request_permission`(唯一实现的回调)
- 流式 `session/update`:`AgentMessageChunk` / `AgentThoughtChunk` / `ToolCall` / `ToolCallUpdate` / `UsageUpdate`
关键限制:`InitializeRequest` 传的是 `ClientCapabilities::new()` —— **fs、terminal 能力均未声明**(默认 false)。因此外部 agent **不会**把文件读写 / shell 回调给 BitFun,而是在自己进程里直接执行(BitFun 仅把 cwd 设为 workspace)。`stream.rs` 也只处理上述 5 种 SessionUpdate,其余变体收到即丢弃。
## 差距清单(按优先级)
### P0 — 宿主能力核心:fs + terminal(价值最高,远程场景刚需)
声明并实现后,agent 的文件/shell 才会经 BitFun 中介(沙箱 / 审批 / 远程 SSH workspace),而非自管黑盒。
- [ ] 声明 `ClientCapabilities.fs`(readTextFile / writeTextFile)+ 实现 `fs/read_text_file`、`fs/write_text_file` 回调,路由到 BitFun workspace fs(含远程 SSH)
- [ ] 声明 `ClientCapabilities.terminal` + 实现 `terminal/create·output·wait_for_exit·kill·release`,接 BitFun 终端/进程基础设施
- 位置:`src/crates/acp/src/client/manager.rs`(initialize)+ 新增回调 handler
- 说明:`request_permission` 已实现,P0 完成后形成"agent 动手前问 BitFun + 动手经 BitFun"闭环。远程 workspace 必须靠 fs 回调才能让 agent 读写远端文件。
### P1 — 交互体验(低成本,体感明显)
- [ ] `AvailableCommandsUpdate`:`stream.rs` 加分支,把 agent 广播的命令列表喂前端 → `/` slash 补全菜单
- [ ] `Plan`(SessionUpdate):渲染 agent 的执行计划(ACP agent-plan)
- 位置:`src/crates/acp/src/client/stream.rs` + 前端
### P2 — 会话控制面(按需)
- [ ] `session/set_mode` + `CurrentModeUpdate`(模式切换)
- [ ] `session/set_config_option` + `ConfigOptionUpdate`(会话级配置)
- [ ] `SessionInfoUpdate`(agent 回写标题/元数据)
### P3 — 边缘/条件性
- [ ] `authenticate` + auth capabilities(仅当某 agent 在 initialize 要求鉴权时)
- [ ] `session/list` `session/fork`(使用 agent 端会话管理/分叉时)
- [ ] `UserMessageChunk`(宿主一般不需要)
## 建议路线
1. 先做 P1 的 `AvailableCommandsUpdate` + `/` 命令菜单(成本最低,和刚接入的 omp 直接相关,可作为 #963 后续小 PR)。
2. 再评估 P0(完整宿主的实质门槛,成本最高;需先决定产品上是否要中介 agent 的所有工具 I/O —— 对远程是刚需,对本地是增强)。建议单独立项。
3. P2/P3 按实际需求排期。
## 备注
"完整标准 ACP" 的权威类型面来自依赖 `agent-client-protocol = 0.11.1`(schema 0.12.0)。本清单按其 `SessionUpdate` 变体与 client/agent 方法集对照得出。
Hướng dẫn đóng góp
Hướng nghiên cứu
Start in src/crates/acp/src/client/manager.rs to inspect initialization and client capabilities, then read src/crates/acp/src/client/stream.rs for handled SessionUpdate variants. Compare the implementation with agent-client-protocol 0.11.1 and scope a priority item such as AvailableCommandsUpdate or filesystem callbacks. Done should include the selected capability, its routing, and the corresponding frontend or host integration where required.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- rust
- Lĩnh vực
- backend-api-design
- Loại issue
- Tính năng
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Ít trao đổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 35/100