Yoda
参考Agent 设计指南标准与协议

ACP 协议

Agent Client Protocol——编辑器↔agent 的"LSP 时刻"；CC/Codex 均无原生实现，靠 Zed 维护的适配器入网

ACP 协议

结论

ACP（Agent Client Protocol，agentclientprotocol.com）是 Zed 于 2025-08 发起、与 Google Gemini CLI 团队合作首发的编辑器↔agent 标准，定位是 agent 时代的 LSP：JSON-RPC 2.0 over stdio（远程 HTTP/WebSocket 在路上），三阶段消息流（initialize → session/new|load → prompt turn），权限、文件系统、终端全部以"client 方法"反向委托给编辑器 [一手文档]。生态已成型：30+ agent、Zed/JetBrains 原生支持、Neovim/Emacs/VS Code/Obsidian/Jupyter 等数十个 client。关键事实是：CC 与 Codex 都没有原生 ACP 实现——CC 经 zed-industries/claude-code-acp（包装 Claude Agent SDK），Codex 经 zed-industries/codex-acp（codex-rs 全仓 grep 无 acp 依赖，其第一方 IDE 协议是私有的 app-server）[一手源码]。对 Yoda 这类 workspace 产品，ACP 是"实现一个 client、接入整个 agent 生态"的最高杠杆标准。

研究问题

  • 协议的消息模型：方法、通知、会话生命周期、权限与终端委托如何设计？
  • 谁原生实现、谁靠适配器？适配器由谁维护、可靠性如何？
  • codex-rs 里到底有没有 acp？它的 app-server 与 ACP 是什么关系？
  • Yoda 做 ACP client 的成本与收益？

协议结构（agentclientprotocol.com，2026-06-11 访问）

[一手文档]

  • 传输与编码：JSON-RPC 2.0；本地 agent 走 stdio，"Full support for remote agents is a work in progress"（HTTP/WebSocket）。内容表示"re-uses the JSON representations used in MCP where possible"——content block 与 MCP 对齐，降低双栈成本。
  • 三阶段流程：
    1. 初始化：initialize（版本与能力协商）→ 可选 authenticate；
    2. 会话建立：session/new 新建，或 session/load（可选能力）恢复；
    3. Prompt turn：client 发 session/prompt，agent 以 session/update 通知流式回传（消息块、tool call、mode 变化），以 stop reason 结束；session/cancel 通知可中断。
  • Agent 侧方法：基线 initialize / authenticate / session/new / session/prompt；可选 session/load、session/set_mode、logout。
  • Client 侧方法（编辑器要实现的）：基线 session/request_permission（工具执行授权，UI 决策点）；可选文件系统 fs/read_text_file、fs/write_text_file（让 agent 看到编辑器中未保存的 buffer）；终端族 terminal/create|output|wait_for_exit|kill|release（终端归编辑器所有，agent 借用）。
  • 硬性约定：所有路径必须绝对路径；行号 1-based；属性 camelCase（判别字段 snake_case）；错误遵循 JSON-RPC 标准 code/message。

设计上的两个聪明点：权限是 client 方法而非 agent 配置——授权 UI 与策略完全归编辑器，agent 只管发起请求；fs/terminal 反向委托——agent 不直接碰磁盘和 PTY，workspace 产品因此天然获得审计点和"脏 buffer 一致性"。

生态现状（2026-06-11）

  • Agent 端（30+）：Gemini CLI（首发原生）、Claude Agent（适配器）、Codex（适配器）、Goose、Cline、GitHub Copilot（public preview）、Cursor、OpenCode、OpenHands、Qwen Code、Kimi CLI、JetBrains Junie、Mistral Vibe、Factory Droid 等 [一手文档：agentclientprotocol.com/get-started/agents]。Zed 内部统计最常用三个：Zed Agent、Claude Agent、Codex [一手文档：zed.dev/acp]。
  • Client 端：Zed（原生）、JetBrains（2025-10 宣布原生 AI Assistant 支持）、Neovim（CodeCompanion/avante 等多插件）、Emacs（agent-shell.el）、VS Code（扩展）、Obsidian、Unity、Jupyter/marimo、以及 Slack/Telegram/微信/飞书等消息桥 [一手文档：agentclientprotocol.com/get-started/clients]。
  • 许可：Apache License，治理在 Zed（未进任何基金会——与 MCP/AGENTS.md 不同）。

各 Agent 设计与实现

Claude Code

CC 本体（CLI/扩展）不暴露 ACP。接入路径是 zed-industries/claude-code-acp（npm @zed-industries/claude-code-acp，GitHub 现更名方向为 claude-agent-acp）：它包装 Claude Agent SDK，把 SDK 的会话/工具/权限事件翻译为 ACP JSON-RPC [一手文档：zed.dev/blog/claude-code-via-acp]。要点：

  • 适配器由 Zed 维护、Apache 开源，"freely available for any editor that's adopted ACP"；Anthropic 未接手 [推断：仓库归属 zed-industries]。
  • 因为走 Agent SDK 而非爬 CLI 输出，hooks/MCP/权限模式等 CC 能力大体可透传；但 CC 的 TUI 专属功能（如 / 命令面板交互）不在协议面内。
  • 社区另有独立实现 Xuanwo/acp-claude-code，佐证适配层需求真实存在。
  • CC 官方文档（本地镜像全文 grep）无任何 ACP 字样 [一手源码：claude-code-docs/docs/ 检索零命中]——Anthropic 官方对 ACP 的态度是沉默。

Codex CLI

  • codex-rs 无 ACP：对 acp / agentclientprotocol 全仓检索（*.rs / *.toml / *.md）零命中 [一手源码]。
  • 第一方 IDE 面是 app-server：codex-rs/app-server、app-server-protocol（含 jsonrpc_lite.rs、experimental_api.rs、schema 导出）构成 Codex 自己的 JSON-RPC 协议，供 VS Code 扩展等官方前端使用 [一手源码]。功能上与 ACP 同构（会话、审批、流式事件），但消息面私有。
  • ACP 接入靠 zed-industries/codex-acp（Rust，按架构/OS 发布二进制）；Zed 社区还出现过"围绕 codex app-server 构建的实验性适配器"（Codex ACP CAS，zed discussion #52749）——说明桥接点既可以在 SDK 层也可以在 app-server 层 [一手文档]。

两家的共同模式：头部 agent 厂商不主动实现 ACP，由最大受益方（编辑器厂商 Zed）出钱出人维护适配器。这决定了适配器的能力上限永远滞后于 agent 本体的新特性。

差异矩阵

维度Claude CodeCodex CLI
原生 ACP server无无（全仓无 acp 依赖）
官方机器可读接口Claude Agent SDK（TS/Python）app-server（私有 JSON-RPC）
ACP 适配器zed-industries/claude-code-acp（npm，包 SDK）zed-industries/codex-acp（Rust 二进制）
适配器维护方Zed（Apache）Zed（Apache）
适配层桥接点Agent SDK 事件流codex 核心/app-server
厂商对 ACP 公开表态文档零提及文档零提及
在 Zed 中的地位最常用外部 agent 之一最常用外部 agent 之一

最小复现

# 1. codex-rs 无 ACP（源码级）
grep -ril "agentclientprotocol" codex/codex-rs/ --include="*.rs" --include="*.toml"
# →（空）
ls codex/codex-rs/app-server-protocol/src/
# → experimental_api.rs export.rs jsonrpc_lite.rs lib.rs protocol ...

# 2. CC 文档无 ACP
grep -rli "agent client protocol" claude-code-docs/docs/ ; echo "exit=$?"
# → exit=1（零命中）

# 3. 行为级：手撕 ACP 握手（需 npm 网络）
npx @zed-industries/claude-code-acp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true}}}}
EOF
# 预期：返回 agentCapabilities（含 promptCapabilities）的 initialize 响应

（第 3 步在本机未实际执行，标 [推断]，方法名与握手字段以官方 schema 为准。）

Harness 接入建议（Yoda 实践）

  1. Yoda 应实现 ACP client，而非 N 个私有集成。一次投入换来 Gemini CLI（原生）、CC、Codex、Goose、Copilot 等全生态；JetBrains 原生跟进证明协议成熟度足以支撑商业产品。
  2. 实现优先级：基线（initialize / session/new / session/prompt / session/update 渲染 / session/request_permission）→ fs 委托（脏 buffer 一致性是 workspace 产品的差异化卖点）→ terminal 委托（把 agent 命令执行收进 Yoda 的终端面板，获得审计与回放）→ session/load 与 set_mode。
  3. 权限即产品：session/request_permission 是 Yoda 策略引擎的天然挂载点——allowlist、一次性放行、会话级模式都在 client 侧实现，对所有 agent 统一生效。
  4. 对冲适配器滞后风险：CC/Codex 的新能力先出现在 SDK/app-server，后到适配器。Yoda 架构上应保留"原生通道"逃生门：runtime 抽象层之下，CC 可直连 Agent SDK、Codex 可直连 app-server，UI 事件模型统一对齐 ACP 的 session/update 语义，保证两条通道可互换。
  5. 迁移路径：现有私有 spawn 集成 → 先把内部事件总线改成 ACP update/permission 语义（纯重构，不换传输）→ 切换传输为 ACP stdio 子进程 → 删私有解析代码。远程 agent 场景等 ACP remote 转正再上。

失效条件

  • Anthropic 或 OpenAI 官方接管/内置 ACP（CC changelog 或 codex-rs 出现 acp crate）——"适配器模式"结论失效，Yoda 逃生门设计可简化
  • ACP remote（HTTP/WebSocket）正式发布——本章"stdio 为主"的传输描述与 Yoda 远程架构建议需更新
  • zed-industries 适配器仓库停止维护或更名完成（claude-code-acp → claude-agent-acp）——引用与依赖坐标需更新
  • ACP 捐入基金会（AAIF 或 LF）——治理风险评估（单一厂商主导）需重写
  • Codex app-server 协议公开标准化并提供稳定承诺——"私有协议"定性失效

参考资料

（访问日期均为 2026-06-11）

高质量 Agent 设计指南

基于主流 Agent 源码分析与最佳实践——成稿章节

AGENTS.md 规范

项目级 agent 指令的事实标准——60k+ 项目采用；Codex 原生实现最完整，CC 仅经 import 桥接

On this page

ACP 协议结论研究问题协议结构（agentclientprotocol.com，2026-06-11 访问）生态现状（2026-06-11）各 Agent 设计与实现Claude CodeCodex CLI差异矩阵最小复现Harness 接入建议（Yoda 实践）失效条件参考资料