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 配置和使用背景。