Agent Client Protocol：编辑器与编码代理之间的中立协议层

编辑器与代理之间的巴别塔，谁来拆

编码代理正在成为开发工具链的常客，但每个编辑器与每个代理之间的通信方式各不相同。没有统一协议时，每对接一个组合就要写一套适配代码。Agent Client Protocol（ACP）想解决的就是这个问题：它定义了一组标准化的 JSON-RPC 消息，让编辑器与代理可以互相发现能力、发送请求、接收通知。这个仓库本身不是编辑器也不是代理，而是协议的定义与工具。它提供 Rust 数据模型、JSON Schema 文件，以及多语言 SDK 的入口。目标用户是编辑器插件作者、代理开发者，以及需要生成 SDK 的工具链维护者。

协议版本与制品版本，两套标尺不能混用

ACP 的版本管理很特别，容易踩坑。Rust crate 的版本号、JSON Schema 的 release 版本号，以及协议本身的 protocolVersion，是三套不同的东西。仓库明确指出，wire 兼容性由 initialize 阶段协商的 protocolVersion 决定，而不是由 crate 或 schema 的版本号决定。也就是说，schema-v1.21.0 和 schema-v2.0.0-alpha.3 可能描述的是同一个 wire 协议版本，只是结构组织不同。这种设计给 SDK 生成器留了自由度：可以调整 schema 的布局而不影响线上消息。但代价是下游必须理解这套双重版本逻辑，否则容易误判兼容性。

Rust 生态里的两层结构：schema crate 与 runtime crate

仓库根目录是 agent-client-protocol-schema crate，它只提供 ACP 消息的 Rust 类型，包括 request、response、notification、JSON-RPC envelope 和协议版本类型。官方建议：如果你要写代理或客户端，用更高层的 agent-client-protocol runtime crate，它封装了运行时 API。schema crate 适合需要直接操作协议类型、做 schema 工具或生成代码的场景。这种分层在 Rust 生态里常见，但要注意，schema crate 是底层接口，直接用它写应用会多出不少样板代码。仓库给出的示例位于 rust-sdk 仓库的 examples 目录，分别是 agent.rs 和 client.rs，可以作为起点。

JSON Schema 作为发布物，而不是 crate

生成的 JSON Schema 文件放在 schema/v1 和 schema/v2 目录，但发布方式不是 crates.io，而是附加到对应的 GitHub release 上。仓库明确说这是 SDK 生成器和发布自动化的推荐下载面。这意味着，如果你要写一个跨语言的 SDK，应该从 GitHub release 拉 schema 文件，而不是从 crate 里找。这个设计有实际好处：schema 文件不依赖 Rust 工具链，任何语言都能消费。但也要注意，release 附件的命名与版本号需要仔细核对，因为 schema 版本与协议版本并不一一对应。

官方 SDK 覆盖五种语言，社区库另算

仓库列出了官方维护的 SDK：Kotlin、Java、Python、Rust、TypeScript。每个 SDK 都有独立的 GitHub 仓库和示例代码。Kotlin SDK 目前只支持 JVM，其他目标平台还在开发中。Java SDK 有 examples 目录。Python SDK 也有 examples。Rust 的示例代码放在 rust-sdk 仓库的 src/agent-client-protocol/examples 下。TypeScript SDK 的示例在 src/examples 目录。社区库的列表在官网的 libraries/community 页面。如果你用的语言不在官方列表里，你需要自己基于 JSON Schema 生成类型，或者等待社区实现。

运行与集成，先看协议，再看 SDK

仓库没有提供一键运行的命令，因为它是协议定义而非应用程序。要实际跑起来，你需要选一个 SDK。以 Rust 为例，先添加 agent-client-protocol crate 到 Cargo.toml，然后参考 examples/agent.rs 或 examples/client.rs。TypeScript 用户用 npm 安装 @agentclientprotocol/sdk。Python 用户则从 python-sdk 仓库获取。无论哪种语言，第一步都是实现 initialize 握手，协商 protocolVersion。这个握手决定了后续所有消息的格式。官方文档的 overview/agents 和 overview/clients 页面分别说明了代理端和客户端的具体要求。

限制与失败模式：协议不是万能胶

ACP 的标准化是有代价的。它假设编辑器与代理之间是请求-响应加通知的模型，如果你的场景需要流式传输大量数据，或者需要自定义二进制消息，这个协议可能不合适。另一个限制是版本协商的复杂性：如果你只看了 crate 版本号就假设兼容，很可能出错。仓库明确警告，不要从制品版本推断 wire 兼容性。此外，协议版本 1 是当前稳定版，但 schema-v2.0.0-alpha.3 的存在表明 v2 正在开发中，这意味着未来可能有破坏性变更。采用前需要确认你的 SDK 是否支持目标协议版本，以及能否处理版本协商失败的情况。

替代方案与选择依据

与 ACP 类似的方案是 Language Server Protocol（LSP），但两者定位不同。LSP 标准化的是编辑器与语言服务器之间的通信，聚焦于代码分析、补全、诊断等编辑功能。ACP 则面向编码代理，强调自主修改代码的请求与通知。LSP 有更长的历史、更广的编辑器支持，但它的消息模型不完全适合代理场景，比如代理需要长时间运行的任务和进度通知。如果你的编辑器已经支持 LSP，你可以在 LSP 之上实现代理功能，但会受限于 LSP 的能力集。ACP 则从零设计，更贴合代理的工作流。选择时，关键看你的编辑器生态里是否已有 LSP 实现，以及代理是否需要 LSP 不具备的交互模式。

编辑结论

ACP 适合正在开发编辑器插件或代理适配层的团队，尤其是希望一次实现、多处复用的场景。不适合需要深度定制消息格式或追求最小依赖的项目，因为协议本身有明确的消息结构和协商机制。采用前应先确认目标编辑器或代理是否已有官方或社区 SDK，并核对 protocolVersion 的兼容性，不要仅凭 crate 版本判断。仓库当前稳定协议版本为 1，schema 版本与 wire 版本分离，实际兼容性以 initialize 阶段协商的 protocolVersion 为准。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes