Agent Client Protocol

ACP 是给高级集成和自定义客户端用的协议入口。普通终端工作流继续用 agent；只有你要把 Cursor Agent 接进自己的 editor、IDE、TUI（Terminal User Interface，终端图形化界面，如 Neovim / lazygit 风格）或自动化客户端时，才需要 agent acp。

阅读目标：读完本章，你应该能解释 ACP 的 transport、消息格式、session 生命周期、权限回调，以及为什么它不是普通用户的第一入口。

1. ACP 适合谁

需求	是否适合 ACP	理由
在终端里和 Agent 对话	不适合	直接用 `agent` 更简单
给自研 IDE 插件接 Cursor Agent	适合	需要稳定协议和 UI 事件
给 Neovim / Zed 这类编辑器接入 Agent	适合	由插件作为 ACP client
在 CI 里跑一次审查	通常不需要	`agent -p` 更直接
做多用户 SaaS 后台代理	高风险	需要认证、权限、租户隔离和审计设计

一句话：ACP 是集成界面（integration surface，给第三方编辑器 / IDE / TUI 接入 Cursor Agent 的协议入口），不是日常命令别名。

2. 启动方式和协议形态

启动 ACP server：

agent acp

官方定义的通信形态：

项目	行为
Transport	`stdio`
Envelope	JSON-RPC 2.0
Framing	newline-delimited JSON
Client input	client 写入 Cursor CLI 的 `stdin`
Agent output	Cursor CLI 向 `stdout` 写 responses / notifications
Logs	可能写入 `stderr`

这意味着你的客户端必须正确处理 stdout 的逐行 JSON，不能把日志、普通文本和协议消息混在一起解析。

3. 标准 session 流程

官方给出的典型 ACP 流程可以理解为：

sequenceDiagram
  participant Client
  participant Agent as agent acp
  Client->>Agent: initialize
  Client->>Agent: authenticate cursor_login
  Client->>Agent: session/new or session/load
  Client->>Agent: session/prompt
  Agent-->>Client: session/update notifications
  Agent-->>Client: session/request_permission
  Client-->>Agent: permission decision
  Client->>Agent: session/cancel optional

如果客户端不处理 session/request_permission，工具执行可能卡住。商业级客户端必须把权限请求做成明确 UI，而不是后台默认允许。

4. 认证方式

ACP 会使用 cursor_login 认证方法。你也可以在启动前通过 CLI 认证路径准备好身份：

agent login
agent --api-key "$CURSOR_API_KEY" acp
agent --auth-token "$CURSOR_AUTH_TOKEN" acp

还可以传 endpoint 和 TLS 相关选项：

agent -e https://api2.cursor.sh acp
agent -k acp

上线集成时不要把 CURSOR_API_KEY 或 CURSOR_AUTH_TOKEN 打进日志。ACP 客户端通常会处理更长的 stdout/stderr 流，更容易意外泄露环境变量和错误上下文。

5. Sessions、modes 和 permissions

ACP 支持创建或恢复 session：

能力	方法
新会话	`session/new`
恢复会话	`session/load`
发 prompt	`session/prompt`
取消	`session/cancel`

核心 modes 与 CLI 一致：

Mode	含义
`agent`	完整工具访问
`plan`	计划模式，偏只读和方案确认
`ask`	问答/只读理解

权限请求会通过 session/request_permission 回到 client。官方列出的决策包括：

allow-once
allow-always
reject-once

商业级客户端要默认 allow-once 起步，只有稳定低风险命令才允许用户显式选择长期允许。

6. MCP 支持和限制

ACP 可以使用项目级或用户级 .cursor/mcp.json 里的 MCP servers。启动 agent 时应从项目目录启动，并审批需要的 servers。

当前官方文档明确限制：Cursor dashboard 配置的 team-level MCP servers 不支持 ACP mode。

这对企业集成很重要。不要假设编辑器里可用的 team MCP，在 ACP 自定义客户端里也能用。

7. Cursor extension methods

Cursor 会发送一组扩展方法，让自定义客户端呈现更完整的 UI。

Method	Type	用途
`cursor/ask_question`	Blocking	多选问题，需要用户回答
`cursor/create_plan`	Blocking	请求用户批准计划
`cursor/update_todos`	Notification	更新 todo 状态
`cursor/task`	Notification	通知 subagent task 完成
`cursor/generate_image`	Notification	通知生成图片输出

Blocking method 必须响应，否则 Agent 会等待。Notification 可以展示，但不需要回复。

一个最小权限响应的思路：

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}

不要在客户端里把 permission request 静默变成 allow-always。这会绕过用户审查，也会让企业权限策略失去意义。

8. IDE 和自定义客户端

官方文档列出的典型集成方向包括：

JetBrains IDE：通过 JetBrains integration guide 接入。
Neovim：例如 avante.nvim 通过 ACP provider 连接 agent acp。
Zed：由 Zed extension spawn agent acp 并处理 stdio。
Custom editors：自己实现 ACP client。

实现一个客户端至少要覆盖：

spawn agent acp。
按行读写 JSON-RPC。
处理 streaming session/update。
处理 session/request_permission。
根据需要实现 Cursor extension methods。
安全处理认证、日志和退出。

深读：ACP 客户端最容易漏掉什么

最容易漏的是“等待用户决定”的阻塞方法。比如计划审批、问题回答、权限请求，如果客户端只展示文本流，不处理这些事件，Agent 看起来就像卡住。

第二个常见问题是把 stdout 当普通文本流。ACP 的 stdout 是协议流，必须逐行解析 JSON-RPC；日志和调试输出应该走 stderr 或单独面板。

本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

为什么普通终端用户不应该优先使用 ACP？
session/request_permission 如果不响应会发生什么？
team-level MCP servers 为什么不能直接假设在 ACP mode 可用？

通过标准：你能画出一个最小 ACP client 的数据流，并说明认证、session、permission、streaming update 和日志隔离怎么处理。

官方来源

Cursor ACP —— 官方 ACP overview、启动方式、transport、request flow、authentication、sessions、permissions、MCP、extension methods 和 IDE integrations。
Agent Client Protocol —— ACP 官方协议说明。
Cursor MCP —— Cursor MCP 配置和使用背景。