agentclientprotocol/agent-client-protocol

Agent Client Protocol (ACP)

是什么 – ACP 是一种 标准化、语言无关的协议，允许 代码编辑器 与 代码代理（使用生成式 AI 自动读取、编写和重构源代码的程序）进行通信。该协议定义了双方之间流动的 JSON-RPC 风格消息（请求、响应、通知），并包含版本协商机制，使编辑器和代理能够独立演进而不会相互破坏。

为何重要 – 随着 AI 驱动的“结对编程”工具（如 GitHub Copilot、Cursor、基于 Code Llama 的助手）日益普及，各厂商历史上都自行设计了临时的 API。ACP 提供了一个 通用契约，使得：

• 编辑器可通过单一集成层支持多个代理。
• 代理只需编写一次，即可在任何实现 ACP 的编辑器中运行。
• 多种语言的 SDK 可以从同一 JSON-Schema 定义生成类型安全的客户端/代理代码。

核心资产

• Rust crate agent-client-protocol-schema – 与网络格式（消息、封装、版本信息）对应的低级 Rust 类型。当你需要直接访问模式或希望为其他语言生成代码时使用。
• Rust crate agent-client-protocol – 高级运行时，实现客户端和代理端，处理连接设置、消息路由和能力协商。
• JSON-Schema 文件 – 版本化的模式文件位于 schema/v1/ 和 schema/v2/。每次发布都会将 .json 文件作为 GitHub 资产打包，供 SDK 生成器（Kotlin、Java、Python、TypeScript 等）消费，生成特定语言的库。

版本控制模型

• 协议版本（当前为 1）通过 initialize 请求的 protocolVersion 字段在运行时协商。这决定了可交换消息的结构。
• crate 和 schema 的发布号与网络兼容性 独立；它们仅反映 Rust API 或 JSON-Schema 文件布局的更改。兼容性由协商的协议版本和双方声明的能力决定。

官方 SDK

语言	仓库	亮点
Kotlin	acp-kotlin	JVM 支持，示例客户端/代理项目
Java	java-sdk	Maven/Gradle 资产，示例
Python	python-sdk	pip 包，快速入门脚本
Rust	agent-client-protocol	Crates.io 包，示例 agent.rs / client.rs
TypeScript	@agentclientprotocol/sdk	npm 包，浏览器与 Node 示例

典型工作流

1. 选择与你的编辑器或代理实现相匹配的语言 SDK。
2. 生成或导入 SDK（大多数已发布在 crates.io、Maven Central、PyPI、npm 等平台）。
3. 在编辑器中实现客户端：注册通知（如 codeChange、applyEdits）并发送 generateCode 或 refactor 等请求。
4. 实现代理端：接收请求，调用生成式 AI 模型，并回复编辑或诊断结果。
5. 在 initialize 交换期间协商能力，使双方知道哪些可选消息被支持。

快速入门

• Rust: cargo add agent-client-protocol → 运行 rust-sdk/examples/ 中的示例，查看通过 stdin/stdout 通信的最小客户端与代理。
• Python: pip install agentclientprotocol → 按照 Python SDK 仓库中的 examples/ 文件夹操作。
• Java/Kotlin/TypeScript: 克隆对应 SDK 仓库，使用标准工具链构建，并运行提供的示例项目。

社区与贡献

• 协议是故意 开放 的；任何人都可通过 GitHub 问题追踪器和 CONTRIBUTING.md 中描述的正式贡献流程提出扩展。
• 无需 CLA；贡献采用 Apache 2.0 许可证。
• 社区维护的库列表可在官方网站获取。

谁应该关注？

• 希望以即插即用方式添加 AI 代码助手的 编辑器开发者（VS Code、JetBrains、Neovim 等）。
• 希望其服务能在多个开发环境中使用而无需编写自定义编辑器集成的 AI 代理构建者。
• 创建由 AI 代理驱动的代码分析、linting 或重构工具的 工具作者。

---

TL;DR – ACP 是一种跨语言协议，标准化了代码编辑器与生成式 AI 代码代理之间交换 JSON-RPC 消息的方式。该仓库托管权威的 Rust 模式 crate、版本化的 JSON-Schema 文件，并提供 Kotlin、Java、Python、Rust 和 TypeScript 的官方 SDK 链接，推动 AI 辅助编程的统一生态系统。