ACP host 完整度:补全 fs/terminal 能力与 SessionUpdate 处理(当前为 V1 子集)

[harryfan1985]

背景

随着把外部 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 直接相关,可作为 feat(acp): add Oh My Pi (omp) as a built-in ACP agent #963 后续小 PR)。
2. 再评估 P0(完整宿主的实质门槛,成本最高;需先决定产品上是否要中介 agent 的所有工具 I/O —— 对远程是刚需,对本地是增强)。建议单独立项。
3. P2/P3 按实际需求排期。

备注

"完整标准 ACP" 的权威类型面来自依赖 agent-client-protocol = 0.11.1(schema 0.12.0)。本清单按其 SessionUpdate 变体与 client/agent 方法集对照得出。

[harryfan1985]

进展:P1 完成,P2 一项完成 —— 见 #979

#979 已实现并通过测试:

✅ P1 — 交互体验(完整三层)

• AvailableCommandsUpdate:host 机制(解析 + 按 session 存储 + get_acp_session_commands 查询 + agentic://acp-available-commands-updated 实时事件)+ 前端逻辑(useAcpSlashCommands / filterSlashCommands,已测)+ UI(接入 ChatInput 既有 slash picker,选中插入 /<name> )。
• Plan:解析 + agentic://acp-plan-updated 事件 + UI(useAcpPlan + AcpPlanPanel 实时清单)。

✅ P2 一项

• ConfigOptionUpdate:补上被忽略的通知,保持 session 存储的 config_options 不陈旧 + agentic://acp-session-options-changed 让前端 refetch。

⬜ 仍未做

• P2 CurrentModeUpdate(需配 available_modes + session/set_mode,model-selector 量级)
• P2 SessionInfoUpdate(标题,需与 BitFun 标题系统打通)
• P0 fs / terminal 宿主能力(高价值,但需先有产品决策:是否中介 agent 的所有工具 I/O;且需 app 内验证)

测试:cargo test -p bitfun-acp 48、vitest 151 passed。

注:slash 菜单与 plan 面板的最终视觉/交互建议在运行中的 app 内确认(实现严格照搬既有 slash picker 与事件订阅模式)。