Cursor Agent 协议逆向工程文档

最后更新：2026-04-25

分析目标

• 安装路径：~/.local/share/cursor-agent/versions/2026.04.17-787b533/
• 运行时入口：index.js（7.5 MB，高度压缩混淆）
• 包名：@anysphere/agent-cli-runtime
• 框架：@connectrpc/connect@1.6.1 / @bufbuild/protobuf@1.10.0
• 603 个 agent.v1 消息 + 28 个枚举，2357 个 aiserver.v1 消息 + 129 个枚举

文档索引

文件	内容
00-overview.md	架构概览——协议栈、消息流、核心发现，引导到各详细文档
01-transport.md	端点、HTTP 传输层、Connect RPC 线格式、SSE/Poll 降级机制
02-stream-messages.md	AgentClientMessage、AgentServerMessage、InteractionUpdate、InteractionQuery 消息定义
03-tool-protocol.md	ToolCall oneof 定义、ExecServer/ClientMessage、KV 协议、控制消息
04-conversation-state.md	AgentRunRequest、ConversationAction、ConversationStateStructure、PrewarmRequest 定义
05-authentication.md	凭据存储（Keychain/文件）、JWT 结构、API 密钥交换
06-request-headers.md	全部 HTTP 头——静态与动态、各值来源
07-session-concurrency.md	会话模型、流生命周期、子代理并发、Best-of-N
08-models.md	模型发现 API、上下文窗口、Max Mode、Effort Level
09-context-summarization.md	上下文压缩：自动/手动触发、协议消息、状态变更
10-turn-lifecycle.md	TurnEnded 触发条件、流保活策略、阻塞读取
11-subagent-billing.md	子代理（Task 工具）协议、计费分析、服务端执行模型
12-proxy-design.md	Cursor Agent API 代理设计
proto/agent_v1.proto	全部 603 个 agent.v1 消息 + 28 个枚举定义（自动提取）
proto/aiserver_v1.proto	全部 2357 个 aiserver.v1 消息 + 129 个枚举定义（自动提取）

脚本

工具脚本

脚本	用途
extract_proto.py	从 CLI bundle 中提取 protobuf 定义
parse_proto.py	将提取的 protobuf 解析为 .proto 格式
get_models.py	从 Cursor Agent API 获取模型列表

实验脚本

脚本	用途	关联文档
concurrent_sessions.py	单 H2 连接上的并发隔离会话	07
concurrent_subagent_test.py	父代理活跃时的子代理计费	11
resume_billing_test.py	Resume 操作计费测试	10
repeated_summarize_test.py	重复中途摘要压缩	09
summarize_midstream_test.py	中途摘要操作	09
subagent_intercept_test.py	模型发起的子代理拦截（最小上下文）	11
task_tool_rich_context_test.py	通过丰富 RequestContext 启用 Task 工具	11
tool_loop_exploit.py	多工具类型的扩展工具循环	07, 10
nodejs-agent-test/	Node.js 阶段 1（http2）+ 阶段 2（ConnectRPC）客户端	11

架构概览

┌─────────────────────────────────────────────────────────────┐
│  cursor-agent CLI                                           │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │CredentialMgr│  │ ConfigProvider│  │ ExtensibilityService│ │
│  └──────┬──────┘  └──────┬───────┘  └────────────────────┘  │
│         │                │                                   │
│  ┌──────▼────────────────▼───────────────────────────────┐  │
│  │          Connect RPC Transport                         │  │
│  │  HTTP/2 BiDi (default) │ HTTP/1.1 SSE+BidiAppend      │  │
│  └──────────────────────┬────────────────────────────────┘  │
└─────────────────────────┼───────────────────────────────────┘
                          │
            ┌─────────────▼─────────────┐
            │  https://api2.cursor.sh    │
            │                            │
            │  agent.v1.AgentService     │
            │    ├─ Run (BiDi)           │
            │    ├─ RunSSE (Server)      │
            │    ├─ RunPoll (Server)     │
            │    ├─ NameAgent            │
            │    ├─ GetUsableModels      │
            │    └─ ...                  │
            └────────────────────────────┘