Cursor客户端解剖（七）一次请求怎么走完

发表于 2026-08-03 分类于 Cursor

系列：Cursor客户端解剖系列学习笔记
上一篇：（六）工具循环

一句话

模型在 Cursor 服务端（或 Private Inference）里“想”；文件 / 终端 / 检索 / MCP 在你这台机器（或 Cloud VM）上“做”。中间用双向流协议把 ToolCall 传来传去。

任务处理时序

端到端：你提交一个任务之后

用户输入（Chat / Agent / Composer）
        │
        ▼
① Workbench UI 收集：模式、模型、选中上下文、附件
        │
        ▼
② 本地组装上下文（不跑大模型）
   · Rules / AGENTS.md / Skills / MCP 清单 / 检索元数据
   · user_info、打开文件、选区、git 状态…
        │
        ▼
③ 发出 AgentRunRequest（流式）
        │
        ▼
④ 服务端 aiserver：拼最终 prompt + 调模型
   → 流式返回 thinking / text / ToolCall
        │
        ▼
⑤ 本地 Agent Exec 执行工具（可审批 / sandbox）
        │
        ▼
⑥ 工具结果回传 → 模型继续 → 循环直到结束
        │
        ▼
⑦ UI 展示：回复、diff、todo、提问、计划…

协议骨架（包内真实类型名）

方向	消息	含义
本地 → 服务	`AgentClientMessage.run_request`	开始/继续一轮 Agent
服务 → 本地	`AgentServerMessage.interaction_update`	文本/思考/工具调用增量
服务 ↔ 本地	`exec_server_message` / `exec_client_message`	工具执行通道
钩子	`PreToolUse` / `PostToolUse` / `BeforeSubmitPrompt`	拦截点

本地 vs 服务端

本地（Mac / SSH 机器 / Cloud Agent VM）

UI、会话展示
Rules / Skills 读取与热更新
cursor-retrieval 索引与搜索执行面
cursor-agent-exec：真正跑 Shell / 读写文件 / Diff…
MCP（含 browser automation）
权限确认、sandbox、shadow/worktree
Private Inference 时：cursor-local-agent-runtime

服务端（`aiserver.v1.*`）

最终 prompt 组装与模型推理（默认路径）
流式 assistant / thinking / tool_call
WebSearch 等联网能力编排
Background Composer / Cloud Agent 控制面
账号、模型目录、部分分析/埋点

后台/云端通道的特别之处

background-composer 不是 renderer 里随便开个 WebSocket，而是：

当作一种 Remote Window：权威解析 → 鉴权 → 传输 → 生命周期

参与者：cursor-resolver / cursor-resolver-helper / cursor-socket / cursor-always-local。
cursor-socket 注册 SocketConnectionProvider，走 TCP/TLS——和 Remote-SSH 同构的心智。

提示词拼装：客户端给积木

完整最终 prompt 主要在服务端；客户端提供：

角色/模式 system 片段（Ask / Agent / Debug / Cloud / Subagent…）
用户 Rules / Skills / custom_system_prompt
UserMessage（text、selected_context、mode…）
ExtraContextEntry（打开文件、路径、blob）
内置工具 schema + 当前 mcp_tools
环境提醒（worktree、本地 vs cloud、是否禁止乱 commit…）

这也解释了高质量任务写法为何有效：目标 + 约束 + 验收 + @文件，正好对齐 selected_context / Rules / 停机条件。

组件对照表

组件	在任务中的角色
Workbench / Glass	收任务、展示流式结果
agent-host	编排会话
agent-exec	执行 ToolCall
retrieval	索引/搜索上下文
mcp + mcpProcess	外部工具
aiserver	模型与多数 prompt 终态
resolver/socket	后台/云端远程管道

边界说明

最终发给模型的完整 prompt 文本大多在服务端，应用包看不到每一次全文
本篇依据：客户端协议字段 + 内置 prompt 模板 + 工具 protobuf —— 还原的是设计逻辑
Private Inference / 自带 Key 时，推理位置会变，但 Tool 执行面仍在 Agent Exec

小结

一次请求的本质不变：

检索缩小世界，规则约束世界，模型提出行动，Exec 执行行动，结果再改变世界。

下一篇收束：这些证据指向的护城河与可迁移原则。

一句话