refactor(acp): reduce bridge to automation protocol

2026-07-24 01:40:25 +08:00
parent b06bcfd21c
commit e819a586b0
406 changed files with 3880 additions and 21325 deletions
@@ -0,0 +1,51 @@
+# Agent Note：ACP 作为仅面向自动化的协议
+
+Status: implemented
+
+[English](2026-07-23-acp-automation-only-protocol.md) | 中文
+
+## 问题
+
+ACP（Agent Client Protocol）桥接层已经变成第二套交互式产品 UI。它将持久事件转换为编辑器卡片、终端元数据、diff、计划、标题、推理、命令、模式、模型和权限选择器、会话导航以及面向人类的询问。这些职责与 TUI 和 Web 客户端重复，同时将自动化传输层与 UI 服务、持久化查询、展示策略和编辑器特定约定耦合在一起。
+
+ACP 仍有一个有用的职责：另一个 agent（智能体）或自动化控制器可以启动 harness 进程、创建隔离会话、发送文本、接收已提交的回答、取消工作并回答权限请求。跨进程 ACP subagent 后端依赖这个标准协议边界。
+
+快照套件使移除工作更复杂。大多数 ACP 场景测试的是组装后的 agent 后端，而不是 ACP 展示层；如果随编辑器桥接层一起删除整个套件，就会丢失大量无密钥行为覆盖。
+
+## 决策
+
+`@deepseek-ai/dsh-acp` 是位于 [`packages/acp/acp`](../../../../packages/acp/acp/README.md) 下、独立于 `ui` 包组的自动化传输层。其公开协议特意保持精简：版本协商、全新文本会话（每个会话最多允许一个进行中的提示词）、已提交的助手文本更新、按会话取消、并发会话，以及由连接负责的资源清理。桥接层会拒绝附加目录、MCP 服务器、非文本提示词、空提示词、未知会话和重叠提示词。
+
+桥接层只发出已提交的 `assistant/message` 文本。推理、原始分片、工具活动、待办事项、计划、标题、重试标记、终端元数据、diff、位置和资源链接仍保留在持久会话日志或 UI 专用传输层中。它不提供会话加载、列出与删除、命令、模式、配置选择器、模型切换、plan 评审或面向人类的询问。
+
+保留一次性 `session/request_permission`。它是为桥接层拥有的 agent 提供的机器策略通道，而不是面向人类的审批 UI：客户端可选择允许一次、拒绝一次或取消，桥接层绝不会将该响应转换为持久授权。[`dsh-subagent-acp`](../../../../packages/subagent/subagent-acp/README.md) 会以程序化方式使用该通道。
+
+应用组装包含 agent 主干、持久化、检查点策略和 ACP 传输层。它不会为 ACP 挂载命令、会话查询、会话引用、plan mode、权限选择器或用户交互服务。SDK 脚手架同样将 `ask_user_question` 视为 TUI 专属功能。
+
+断开连接与插件 dispose（资源释放）共享同一个经记忆化处理的静止边界。传输关闭无论成功还是失败，都会将待处理提示词以已取消状态结算，dispose 每个由桥接层拥有的 agent，并等待循环和会话清理完成。创建流程如果在与关闭的竞态中落败，就会 dispose 其尚未发布的 handle。
+
+## 快照边界
+
+ACP 快照套件保留面向后端的场景，并继续启动组装后的 ACP 示例。该重构保留 53 个场景，覆盖循环、工具、钩子、压缩（compaction）、subagent、文件系统、PTY、Code Mode、权限提升与持久化行为。原本描述已删除展示层的名称改为面向后端的名称（`bash-tool-turn` 和 `todo-write`）。
+
+删除七个场景，因为其脚本覆盖的是已删除的 ACP UI 控件：配置通告、模式通告、模型选择、权限预设选择、命令状态，以及通过选择器与询问流程实现的 plan mode 评审。它们所属的包仍保留专门的无密钥覆盖。语义检查点场景改用 headless `stream-json` 示例，不再使用 ACP。
+
+[`examples/acp-agent/tests/acp.snapshot.ts`](../../../../examples/acp-agent/tests/acp.snapshot.ts) 中的 FIXME 记录了明确的后续工作：将余下的后端测试集转移到 headless `stream-json` 套件，使 ACP 快照只负责自动化协议。该迁移独立实施，因为在本次变更中重写共享快照 harness 与每个 fixture（测试前置数据），会模糊本次协议精简的主线。
+
+## 考虑过的替代方案
+
+**在 Web 达到同等能力前，继续将 ACP 作为编辑器 UI。** 不予采用，因为这会留下两套需要演进的交互契约，并使编辑器约定继续存在于自动化边界中。
+
+**用私有 subagent RPC 替换 ACP。** 不予采用，因为 ACP 已经提供类型化、可互操作的进程协议，并由跨进程 subagent 后端使用。
+
+**随其他交互功能一起移除机器权限请求。** 不予采用，因为自动化父 agent 必须回答子 agent 的一次性策略决策；这是 agent 之间的控制流，而不是展示层。
+
+**删除 ACP 快照套件，或在本次变更中迁移每个场景。** 不予采用，因为大多数场景测试后端且仍有价值，而完整的 harness 迁移是一项独立的测试变更。只有驱动脚本依赖已删除 UI 方法的场景才离开该套件。
+
+## 结果
+
+ACP 具有适合 agent 与自动化的精简契约，而 TUI 和 Web 拥有面向人类的交互与展示。该包注入的服务、依赖、协议分支和生命周期状态更少，也不再将自身定位为通用编辑器入口。
+
+自动化客户端收到完整的已提交文本，而不是 token 增量或结构化工具 UI。当它们需要推理、工具跟踪信息、标题或更丰富的状态时，需要查看持久日志或其他 API。只支持全新会话也意味着，需要浏览持久会话或恢复会话的调用方必须使用 host API，而不是 ACP。
+
+过渡期间仍可使用后端快照覆盖，但其传输方式暂时只是附带选择。FIXME 明确记录了这项技术债，又不会将本 PR（Pull Request）扩展为全仓库快照迁移。