acp

用途

Agent Client Protocol（ACP）是一套基于 JSON-RPC 2.0 的标准化协议，用于代码编辑器/IDE 与 AI 编程智能体之间的双向通信。它使智能体能够与任何兼容的编辑器协作，也使编辑器能够支持任何兼容 ACP 的智能体，其定位类似于 LSP 对语言服务器的标准化作用。

ACP 同时支持本地智能体（通过 stdio 以子进程方式运行）和远程智能体（通过 HTTP/WebSocket）。协议负责处理初始化、会话管理、提示轮次、工具执行、文件系统访问，并可通过自定义方法和元数据字段进行扩展。

主要文档地址：https://agentclientprotocol.com

主要能力

核心消息类型包括：

initialize：客户端 → 智能体，协商协议版本与能力
session/new：客户端 → 智能体，创建新会话
session/load：客户端 → 智能体，恢复已有会话（若支持）
session/prompt：客户端 → 智能体，发送带内容的用户消息
session/cancel：客户端 → 智能体，取消进行中的操作（通知）
session/update：智能体 → 客户端，流式输出、工具调用、计划（通知）
session/request_permission：智能体 → 客户端，请求用户批准工具执行
fs/read_text_file：智能体 → 客户端，读取客户端文件系统中的文件
fs/write_text_file：智能体 → 客户端，写入客户端文件系统中的文件
terminal/create：智能体 → 客户端，创建用于执行命令的终端

能力标志方面，客户端能力（在 initialize 中声明）包括 fs.readTextFile、fs.writeTextFile、terminal；智能体能力（在 initialize 中响应）包括 loadSession、promptCapabilities.image、promptCapabilities.audio、promptCapabilities.embeddedContext、mcpCapabilities.http、mcpCapabilities.sse（已废弃）。

内容类型包括 text（纯文本，无需能力）、image（base64 视觉上下文，需 promptCapabilities.image）、audio（base64 音频，需 promptCapabilities.audio）、resource（内嵌文件内容，需 promptCapabilities.embeddedContext）、resource_link（外部资源引用，无需能力）。

工具调用类型包括 read、edit、delete、move、search、execute、think、fetch、other；工具调用状态流转为 pending → in_progress → completed（或 failed）。

使用方式

智能体实现者

初始化连接：接收带客户端能力的 initialize 请求，响应协议版本、智能体能力与认证方式，校验版本兼容性，不支持则断开。
建立会话：接收带工作目录与 MCP 服务器的 session/new，连接指定的 MCP 服务器（stdio 必需，HTTP/SSE 可选），返回唯一会话 ID，可选返回配置项或模式。
处理提示轮次：接收带用户消息与内容的 session/prompt，通过 session/update 发送计划、智能体消息、工具调用通知；对每个工具调用报告状态；必要时通过 session/request_permission 请求权限；完成后返回带停止原因的响应。
管理文件访问：调用 fs/read_text_file 或 fs/write_text_file 前检查客户端能力，仅使用绝对路径，优雅处理错误。
支持取消：监听 session/cancel 通知，立即中止 LLM 请求与工具执行，并以 cancelled 停止原因响应原 session/prompt。

客户端实现者

初始化连接：发送带支持的协议版本与客户端能力的 initialize，接收智能体能力与协议版本，校验版本，不兼容则断开。
创建或加载会话：调用 session/new（带工作目录与 MCP 服务器配置），或在智能体支持 loadSession 时调用 session/load，接收会话 ID 及可选配置项/模式。
发送提示并处理更新：调用 session/prompt（遵守提示能力），监听 session/update 通知，实时展示工具调用进度与结果，通过 session/request_permission 处理权限请求。
提供文件系统访问：若声明了相应能力，则实现 fs/read_text_file 与 fs/write_text_file，使用绝对路径，文件不存在时创建。
管理终端（若支持）：实现 terminal/create、terminal/output、terminal/wait_for_exit、terminal/release、terminal/kill，实时流式输出，释放时清理。

决策指引

会话模式与配置项：简单开关、模型选择、推理级别优先使用配置项（更灵活）；会话模式已废弃，仅用于向后兼容。

权限请求与自动执行：破坏性操作（删除、修改）与执行代码应请求权限；读取文件与获取外部数据可自动执行。

传输选择：stdio 用于本地智能体、子进程模型，所有智能体必需；HTTP 用于远程智能体、云部署，可选，需检查 mcpCapabilities.http；SSE 用于旧版远程智能体，已被 MCP 规范废弃。

适用场景

构建 ACP 智能体：实现需要与编辑器（如 Claude Agent、Cline、Cursor 等）通信的编程智能体
构建 ACP 客户端：创建连接智能体的编辑器插件、IDE 集成或独立客户端
集成 MCP 服务器：为智能体配置 Model Context Protocol 服务器以访问工具与数据
实现工具调用：设计智能体如何报告文件修改、代码执行与工具结果
处理权限：为敏感操作构建权限请求流程
会话管理：实现会话持久化、加载与配置
扩展协议：添加自定义方法、通知或元数据以支持专有功能

限制与注意事项

能力不匹配：调用可选方法前必须检查能力，省略的能力应视为不支持。
绝对路径：协议中所有文件路径必须为绝对路径，相对路径会失败。
行号从 1 开始：文件操作中的行号使用 1 起始索引，而非 0。
换行分隔 JSON：stdio 传输中消息必须以换行分隔，且不得包含内嵌换行。
禁止污染 stdout：智能体只能向 stdout 写入合法 ACP 消息，其他输出会破坏协议。
取消错误处理：收到 session/cancel 时应捕获 API 调用异常并返回 cancelled 停止原因，而非错误。
会话 ID 作用域：会话 ID 在每个智能体实例内唯一，不应假设跨多个智能体进程全局唯一。
MCP 服务器连接：智能体必须连接客户端指定的所有 MCP 服务器，否则可用工具受限。
权限响应时机：客户端必须在智能体继续前响应 session/request_permission，不应让请求挂起。
废弃的会话模式：会话模式已废弃，推荐配置项，但为向后兼容可同时支持。
_meta 字段安全：实现不得对 _meta 字段的值做假设，应视为不透明扩展。
工具调用更新是增量的：发送 tool_call_update 时只包含发生变化的字段，省略字段保留先前值。

验证清单

提交智能体或客户端实现前应确认：协议版本协商正常；所有声明能力均已实现；所有必需基线方法已实现（initialize、session/new、session/prompt、session/cancel、session/update）；文件操作使用绝对路径；调用可选方法前检查能力；错误响应符合 JSON-RPC 2.0 格式；通知（无 id 字段）不期待响应；工具调用状态流转正确；权限请求处理得当且结果有效；取消能停止操作并返回 cancelled 停止原因；若指定则已连接 MCP 服务器；自定义方法/通知以下划线（_）开头；自定义能力在初始化时于 _meta 中声明；会话 ID 在智能体实例内唯一；文件写入在文件不存在时创建；stderr 仅用于日志，不用于协议消息。

资源

综合导航：https://agentclientprotocol.com/llms.txt

关键文档页面：协议概览（核心消息流与基线方法）、初始化（版本与能力协商）、提示轮次（含工具调用的完整会话生命周期）。