ACP

概述

Cursor 命令行界面支持用于高级集成的 ACP (智能体客户端协议) 。您可以运行 agent acp，并通过 JSON-RPC 在 stdio 上连接自定义客户端。

更多信息请参阅官方 智能体客户端协议文档。

启动 ACP 服务器

以 ACP 模式启动 Cursor 命令行界面：

agent acp

传输与消息格式

• 传输方式：stdio
• 协议封装：JSON-RPC 2.0
• 分帧：以换行符分隔的 JSON (每行一条消息)
• 方向：
  • 客户端将请求/通知写入 stdin
  • Cursor 命令行界面将响应/通知写入 stdout
  • 日志可能会写入 stderr

请求流程

典型的 ACP 会话流程：

1. initialize
2. 使用 methodId: "cursor_login" 执行 authenticate
3. session/new (或 session/load)
4. session/prompt
5. 在模型流式输出期间处理 session/update 通知
6. 通过返回决策处理 session/request_permission
7. 可选：发送 session/cancel

认证

Cursor 命令行界面将 cursor_login 作为 ACP 认证方法提供。实际上，你可以在启动前通过现有的 CLI 认证方式预先完成认证：

• agent login
• --api-key (或 CURSOR_API_KEY)
• --auth-token (或 CURSOR_AUTH_TOKEN)

你还可以通过根 CLI 命令传入端点和 TLS 选项：

agent --api-key "$CURSOR_API_KEY" acpagent -e https://api2.cursor.sh acpagent -k acp

会话、模式与权限

会话

• 使用 session/new 创建会话
• 使用 session/load 恢复现有会话

模式

ACP 会话支持与命令行界面 (CLI) 相同的核心模式：

• agent (完整工具访问权限)
• plan (规划模式，仅可读取)
• ask (问答模式，仅可读取)

权限

当工具需要获得批准时，Cursor 会发送 session/request_permission。客户端应返回以下选项之一：

• allow-once
• allow-always
• reject-once

如果客户端未响应权限请求，工具执行可能会被阻塞。

MCP 服务器

ACP 支持使用项目级或用户级 .cursor/mcp.json 中定义的 MCP 服务器。在项目目录中启动 agent，然后批准要使用的服务器。

Cursor 扩展方法

Cursor 会发送 ACP 扩展方法，以提供更丰富的客户端体验。分为两类：

• 阻塞方法 (cursor/ask_question、cursor/create_plan)：智能体会等待响应后再继续。客户端必须返回 JSON-RPC 响应。
• 通知方法 (cursor/update_todos、cursor/task、cursor/generate_image)：智能体会以即发即弃的方式发送这些通知。客户端可以显示这些通知，但无需响应。

cursor/ask_question

向用户展示多项选择题。智能体会一直阻塞，直到客户端作出响应。

请求：

interface CursorAskQuestionRequest {  toolCallId: string;  title?: string;  questions: Array<{    id: string;    prompt: string;    options: Array<{ id: string; label: string }>;    allowMultiple?: boolean;  }>;}

响应：

interface CursorAskQuestionResponse {  outcome:    | {        outcome: "answered";        answers: Array<{          questionId: string;          selectedOptionIds: string[];        }>;      }    | { outcome: "skipped"; reason?: string }    | { outcome: "cancelled" };}

请求示例：

{  "toolCallId": "call_123",  "title": "Need input",  "questions": [    {      "id": "q1",      "prompt": "Which mode should I use?",      "options": [        { "id": "agent", "label": "Agent" },        { "id": "plan", "label": "Plan" }      ],      "allowMultiple": false    }  ]}

cursor/create_plan

请求用户批准方案。智能体会阻塞，直到客户端接受或拒绝该方案。

请求：