Cursor Agent 架构全景讲解

以 Agent 的生命脉络 为主线，讲清楚 Cursor 这款 AI-first IDE 里"agent"到底是怎么被定义、被唤起、怎么思考、怎么记忆、怎么开口的。Cursor 是 Anysphere 公司基于 VSCode fork 出的闭源产品，没有源码可读，本文以官方文档 + 团队博客 + 社区可观测行为为基础，凡推断与未确认处都会显式标记。

适合：第一次接触 Cursor 想建立心智模型 / 老用户查具体机制 / 拿来对比其他 IDE-agent 产品。

2026-06-08 官方复核补丁：Cursor changelog 已到 3.7；2.4 官方加入 Subagents、 Agent Skills（SKILL.md）、图片生成与 hooks 扩展。当前 modes 文档按 Agent / Ask / Custom 描述，Plan / Debug 更应理解为 Custom mode 示例或产品化模式来源，而不是旧文里的固定四模式口径。

资料层级与置信度约定（全文遵循）：

官方确认：来自 cursor.com/docs、cursor.com/blog、cursor.com/changelog 的事实，引用即可。

公开可观测：来自 .cursor/rules/、.cursor/mcp.json、Pro 计费仪表盘、Forum 的多人复现描述，标 (可观测)。

第三方推断：第三方逆向 / 博客猜测，标 (推断)。

未公开 / 低置信度：资料不足或互相矛盾的地方明确标注置信度，不编造。

#目录

零、写在前面：项目身份与核心矛盾
零·五、一张图看懂：Cursor = Model + Harness
一、Agent 是什么 —— 模式 + Rules + Memory + 模型选择
二、Agent 怎么活起来 —— 从一次 Cmd+L 到 Composer 跑起来
三、Agent 怎么思考 —— Agent / Ask / Custom + Composer 主循环 + Cloud Agent
四、Agent 怎么行动 —— Edit / Shell / Search / @ 引用 / MCP
五、Agent 怎么记忆 —— Rules / Memories / 索引 / AGENTS.md
六、Agent 怎么开口 —— 内联 diff / Chat panel / Agents Window
七、Agent 的外脑 —— Auto 路由 / Composer / Frontier 模型池
八、关键设计权衡（架构师视角）
九、附录：组件地图、关键概念、文档索引

#零、写在前面：项目身份与核心矛盾

"The harness is the product." —— 第三方对 Cursor Cloud Agents 的总结

#0.1 项目身份消歧

易混点	真相
Cursor 是一个模型？	不是。Cursor 是 IDE / harness / 工具体系，模型是它的"外脑"（自家 Composer + 外采 Claude/GPT/Gemini）
公司叫 Cursor？	公司是 Anysphere，产品名才是 Cursor
Composer 和 Agent 是两个东西？	Composer 是早期 multi-file edit 的 UI 名称，2.0 起合并/重命名进 Agent 模式；与此同时 Composer 也成了一个自家训练的 MoE 模型名称（同名不同物，下文严格区分 Composer-UI vs Composer-Model）
`.cursorrules` 和 `.cursor/rules/` 是同一个？	前者是早期单文件版本，后者是当前的多文件 + MDC frontmatter 版本，两者并存但 `.cursor/rules/` 是当前推荐
Background Agent 和 Cloud Agent 是不是一回事？	是。早期叫 Background Agents，后期博客统一为 Cloud Agents，本文混用
听过 Cursor 的 "Ask / Edit / Composer / Manual / Agent" 五种模式？	这是 1.x 时代的早期叫法。当前官方 modes 文档按 Agent / Ask / Custom 三类组织（见 cursor.com/docs/agent/modes）；Plan / Debug 可以由 Custom mode 承载或以产品化模式出现，不再把它们和 Agent 并列成固定四模式。"Manual" 现在指 rules 的触发档（§1.2），不是 chat mode；"Composer" 在 2.0 起合并进 Agent UI，单独的 Composer mode 已下线

#0.2 三个核心矛盾

矛盾	Cursor 的回答
闭源 IDE 想读懂用户全部代码，但又不想触法律红线	本地 chunk + remote embedding（Turbopuffer），plaintext 不入库，Privacy Mode 下连 embedding 都不留
想让 LLM 又快又强，但 frontier 模型贵且慢	Auto 路由 + 自家 Composer-Model（MoE，4× 同档位推理速度），routine 分流给 Composer，硬骨头送 Claude/GPT
既要"贴身助理"（Tab/Cmd+K）又要"自主员工"（Background Agent）	同一套 harness 上叠不同模式：Tab → 内联 → Agent → Plan/Debug → Cloud Agent，颗粒度从"行级"到"PR 级"递增

每章会反复回到这三个矛盾。

#零·五、一张图看懂：Cursor = Model + Harness

业界视角：Anthropic / Cursor / Codex / Aider / Cline 用的是同一批底层模型，实际表现差距却很大。差的不是模型，是"模型之上的外壳（Harness）"——指令、工具、基础设施、可观测性这四层共同决定了 agent 的真实能力上限。

Cursor 团队自己也用"harness"这个词，第三方更直接喊出 "The harness is the product." 模型可换（Auto 池里 Sonnet/GPT-5/Composer 任意切），harness 不可换——IDE、Tab/Cmd+K/ Cmd+L 入口、Cloud VM、PR 出口、git worktree 隔离、Turbopuffer 索引这一坨才是产品本体。下文按"4 层 + 8 支柱"反向索引本文档每个章节。

#0.5.1 四层 Harness 结构

┌──────────────────────────────────────────────────────────────────────┐
│         Agent  =  Model  (LLM)  +  Harness  (本平台四层外壳)            │
└──────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────┐
│ ① 指令层  │ .cursor/rules/*.mdc 四档触发                  → §1.2     │
│           │   (Always / Auto-Attached / Agent-Requested / Manual)    │
│           │ User Rules（账号级，跨项目）+ Team Rules（企业） → §1.2   │
│           │ AGENTS.md（行业通用，子目录与父目录组合）       → §1.2    │
│           │ Memories（模型自动萃取，项目级，存后端）        → §1.3    │
│           │ Mode：Agent / Ask / Custom 切换 prompt 与工具面 → §1.4    │
├──────────────────────────────────────────────────────────────────────┤
│ ② 能力层  │ 内置工具：read/edit/grep/run_terminal/browser  → §4.1    │
│           │ @ 引用语法糖（@File/@Code/@Web/@Docs/@Codebase）→ §4.2    │
│           │ MCP（stdio / HTTP-SSE / OAuth Remote）         → §4.3    │
│           │ ⚠ 40 工具软上限 / ~80 硬上限                   → §4.3.1  │
├──────────────────────────────────────────────────────────────────────┤
│ ③ 基础设施│ Codebase Index：Merkle + chunk + Turbopuffer    → §5.2   │
│           │ 路径分段加密 + Privacy Mode 零持久化            → §5.2   │
│           │ 本地 git worktree（多 agent 并行物理隔离）      → §3.3   │
│           │ Cloud Agents：isolated Linux VM + computer use  → §3.4   │
│           │ .cursor/hooks.json（2025 起，主要给 Cloud Agent）→ §4.4  │
│           │ 多入口共享配置：IDE / CLI / Cloud Agent 同一份  → §8.5   │
├──────────────────────────────────────────────────────────────────────┤
│ ④ 可观测  │ Chat panel "Used tool" 折叠块（工具名+参数截断）→ §2.3   │
│           │ Settings → Indexing（已索引文件数 / 上次同步）  → §2.3   │
│           │ Dashboard → Usage（按模型 credit 消耗）         → §2.3   │
│           │ Cloud Agent 视频回放 + PR artifact bundle       → §6.3   │
│           │ ⚠ Auto 路由实际选了谁不显示（长期 Forum 痛点）    → §7.2 │
└──────────────────────────────────────────────────────────────────────┘

#0.5.2 八支柱对照表

#	Harness 支柱	一句话定义	Cursor 的实现	对应章节
01	FS + Git	state 必须活在 context 之外	`.cursor/` 目录承载 rules / mcp.json / hooks.json；Codebase Index 把代码切 chunk 灌进 Turbopuffer；git worktree 给本地多 agent 做物理隔离；Cloud Agent 用 isolated Linux VM 完全外置 state	§3.3 / §5.2
02	Bash 通用工具	"随用随装"，避免 token 爆炸	内置 `run_terminal_cmd` / `run_in_background`；MCP `stdio/HTTP-SSE/OAuth Remote` 三 transport 接外部进程；但工具 schema 不能 lazy load，40 个软上限就是这条短板	§4.1 / §4.3
03	沙箱 + 子工具	行动可隔离 + 可自检	git worktree 本地隔离 + Cloud VM 远端隔离；shell 默认 ask before run；Debug Mode 注入临时 log 做"自我验证"；MCP 工具默认弹审批气泡	§3.3 / §3.4
04	记忆 + 搜索	跨 turn / 跨 project 拿历史	四层记忆：User Rules / .cursor/rules / Memories / Codebase Index；codebase_search（语义，走 Turbopuffer）+ grep（精确）双轨；同 org 内 simhash 跨用户复用索引	§5.1 / §5.2
05	对抗 Context Rot	长对话也别糊	Composer 自家 MoE 长上下文 → 压缩压力小一些；rules 四档触发让"硬盘 N 条规则 ≠ 进 prompt N 条"；但长会话压缩机制官方未公开	§1.2 / §5.4
06	长程执行	多 phase 任务不跑偏	Custom/Plan 类模式可强制先研究 + 出方案 + 用户 confirm；Cloud Agent 在 VM 里跑数十分钟到小时级；race pattern 同任务多模型并发挑最优	§1.4 / §3.4
07	Hooks 强制层	失败转成永久规则	`.cursor/hooks.json` 2025 才上，目前只有 Cloud Agent 在用，schema 文档化都不全；IDE 端没有 pre/post tool hook 体系	§4.4
08	规划 + 工具选择	别什么都试，先想再调	Mode 切换 = system prompt 模板 + 工具白名单 + 终止条件；Auto 路由把"选哪个模型"也从用户决策升格为产品决策；@ 引用做冷热分流（已决定的注入 prompt，待定的留工具调用）	§1.4 / §4.2 / §7.2

#0.5.3 当前架构的短板（按 Harness 视角看出来的）

Cursor 是 "harness as product" 的代表，但闭源 + IDE-first 的基因让它在 4 层里几条线非常薄：

可观测层几乎为零——这是最大的短板。Auto 实际选了哪个模型不显示（§7.2 提到这是 Forum 长期痛点），Cloud Agent 决策路径全是第三方推断（§3.4），apply / Tab 小模型工程细节不可见（§9.5 自己列为最不确定点）。整个 harness 跑了什么用户基本只能"行为反推"，这跟 Claude Code 的 OTel hook 体系差了好几个量级。
Hooks 强制层（07）发育不全：.cursor/hooks.json 2025 才上、文档披露很少（见 §4.4），且只覆盖 Cloud Agent。IDE 端的内联 edit / Cmd+K / Chat 都没有 pre/post tool hook 给团队做 lint 强校验 / 审计落盘 —— 这块在 Claude Code 是核心扩展点。
指令层 Rules vs Memories 概念重叠：四档 rules + User Rules + Team Rules + AGENTS.md + Memories 五种来源（§1.2 / §1.3），写者、触发方式、存储位置、跨设备语义全不一样，社区分两派讨论"该用 rules 还是 memories"（§5.3）。harness 自己没给出明确边界文档，靠用户自悟。
能力层的 40 工具软上限是工程"硬伤"：MCP schema 不能 deferred（对比 Claude Code 的 ToolSearch），导致工具数一上来就被静默禁用 + 模型选错率上升（§4.3.1）。这是一个 harness 层本可以解决但目前选择"让用户手动开关"的偷懒方案。
闭源 = 调试与定制都到天花板：harness 出问题（路由错误、索引漂移、Plan Mode 卡住）你只能等官方修，没法 fork、没法插自己的中间件。这跟"模型可换、harness 不可换"是一体两面——把 harness 做成护城河的代价就是用户没法把它拆开。
指令层在多入口下的"一致性疲劳"：IDE / CLI / Cloud Agent 共享 .cursor/ 是亮点（§8.5），但 Memories 走后端、rules 走 git、hooks 只在 Cloud 端生效，同一份"指令"在不同入口的有效集不同，调试时心智负担不低。

如果给 Cursor 排短板优先级：可观测层 > Hooks 体系 > 指令层去重。可观测做不好，连"它今天为啥变笨了"都答不上来，Auto 这种产品级路由的口碑就持续被磨损（参见 2025-06 pricing 改革后那波退款风波，本质就是计费 + 路由不透明叠加爆雷）。

#一、Agent 是什么 —— 模式 + Rules + Memory + 模型选择

"Cursor 的'一个 Agent'不是一段代码，而是当前会话的'模式 × 规则 × 记忆 × 模型'四元组。"

#1.1 反直觉的起点：Cursor 没有"Agent 实体"

对象**。当你按 Cmd+L（Mac）打开 Chat / Composer 面板时，每次会话都是临时拼出来的：

本次会话的 Agent 行为
  = 选中的 Mode（Agent / Ask / Custom；Plan / Debug 可视为 Custom 化形态）
  + 命中的 Rules（项目级 .cursor/rules/ + 用户级 + AGENTS.md）
  + 可用 Agent Skills（2.4 起，`SKILL.md`）
  + 自动召回的 Memories（项目级长期记忆，2025 年新增）
  + Codebase 索引（按需召回的代码片段）
  + 当前选中的 Model（Auto / Composer / Sonnet / GPT-5 / ...）
  + @ 引用注入的临时上下文（@File / @Web / @Docs / @Code）

这五个维度的笛卡尔积才是"我现在在用的 agent"。这种"无实体"设计有一个直接后果： 你不能像调用 API 那样把 Cursor agent 复用到 CI——这正是 Cursor CLI / Cloud Agents 要补的洞。

#1.2 用 .cursor/rules/ 给 Agent 装"职业卡"

.cursor/
  rules/
    always-typescript.mdc          # alwaysApply: true
    when-touching-react.mdc        # globs: src/**/*.tsx
    db-migration-guidelines.mdc    # description: 触发器，agent 自己决定要不要读
    project-conventions.mdc        # 空 frontmatter，靠 @-mention 手动调

每个 .mdc 文件长这样：

---
description: "When the user asks about database migrations, load this."
alwaysApply: false
globs: ["db/migrations/**"]
---

# DB Migration Conventions

- 所有迁移脚本必须可逆
- 命名格式：YYYYMMDDHHMMSS_short_name.sql
- ...

四种触发模式（官方文档 cursor.com/docs/context/rules 明确列出，原文用语 "Always Apply / Apply Intelligently / Apply to Specific Files / Apply Manually"，社区通常简写如下）：

模式	官方原文	frontmatter 关键字段	何时塞进 system prompt
Always	Always Apply	`alwaysApply: true`	每次 agent 调用都注入
Auto Attached	Apply to Specific Files	非空 `globs`	当对话里出现匹配该 glob 的文件时自动注入
Agent Requested	Apply Intelligently	非空 `description`，`alwaysApply: false`	把 description 给 agent，由 agent 自己决定要不要拉这条 rule
Manual	Apply Manually	空 frontmatter	只在用户写 `@rule-name` 时才加载

并存的还有：

User Rules：在 Cursor Settings 里全局配置，跟着账号走（不进 git）。
Team Rules：Team / Enterprise 计划，从后台仪表盘下发，可强制启用。
AGENTS.md：2025 年起 Cursor 兼容了行业里的 AGENTS.md 通用约定，可放项目根或子目录，子目录的 AGENTS.md 与父目录组合，更具体的规则优先。

#1.3 Agent Skills：Rules 之外的 procedural context（2026-06 复核）

Cursor 2.4 changelog 已把 Agent Skills 做进编辑器和 CLI，文件形态是 SKILL.md。因此旧文把 Cursor 的 skill 形态完全等同于 .cursor/rules/*.mdc 已不准确。

边界可以这样记：

机制	主要作用	典型内容
Rules	declarative context，告诉 agent 项目规范、约束、何时附加规则	代码风格、目录约定、架构边界
Agent Skills	procedural/on-demand context，告诉 agent 按步骤完成一类任务	发布流程、迁移步骤、排查 playbook

Skills 与 Rules 都是 markdown 生态的一部分，但 Rules 更像"上下文规则"，Skills 更像 "可复用操作手册"。跨家对比时，Cursor 不应再放在"没有原生 skill，只有 rules"这一档。

#1.4 Memories：第一个真正"记忆"的产品形态

直到 2025 年，Cursor 才上了 Memories：

来源：从 Chat 对话中自动萃取（"用户偏好用 pnpm 不用 npm" 这种）
范围：项目级（不跨项目，不跨账号）
存储：Cursor 后端（不是本地文件，不进 git）
与 Rules 的差别：
- Rules 是用户写的、确定性触发的
- Memories 是模型生成的、agent 自己决定何时召回的

这是 Cursor 第一次承认"长期记忆 != Rules 文件"。(官方文档已确认)

#1.5 模式（Mode）：身份的最后一片拼图

Cmd+L 打开 Chat 后右下角能切（Shift+Tab 快速切换）：

模式	能改文件？	能跑 shell？	主要用途
Agent	是	是	完整 ReAct，看到任务就干
Ask	否	否	只读问答、解释代码
Custom	由配置决定	由配置决定	保存一套 prompt + tool selection；Plan / Debug 可由这里派生

2026-06-08 复核：官方 modes 文档当前列的是 Agent / Ask / Custom。本文其它章节提到 Plan / Debug 时，按"Custom mode 示例或产品化模式来源"理解。早期的 "Composer mode"（1.x）已合入 Agent；"Edit mode"（1.x 行内编辑）现在通过 Cmd+K 触发，不再作为 Chat 模式存在。

模式 = system prompt 模板 + 工具白名单 + 终止条件。同一个 model 在 Ask 模式下完全不会调 edit 工具；Custom/Debug 类模式可以主动加临时打印或限制工具集。

(推断) 模式切换大概率体现在 system prompt 和 tool schema 注入上，而非模型本身不同——Forum 上有人观察到同一个 Auto 在不同 mode 下行为差异极大，但底层模型选择没变。

#二、Agent 怎么活起来 —— 从一次 Cmd+L 到 Composer 跑起来

"Cursor 的请求链路藏在二进制里，但出口和入口是公开的。"

#2.1 五个入口，一条 harness

┌──────────────────────────────────────────────────────────┐
│                    用户触发入口                            │
├──────────────────────────────────────────────────────────┤
│  ① Tab（按 Tab 键）        → Cursor Tab 模型 → 内联 ghost text │
│  ② Cmd+K（行内 edit）       → 短链路 edit 模型 → 局部 diff      │
│  ③ Cmd+L（Chat / Composer）→ Agent harness → 多文件 edit       │
│  ④ Cursor CLI（终端 cursor agent）→ 同一 harness 的 CLI 形态     │
│  ⑤ Cloud Agents（cursor.com/agents / Slack / Linear / GitHub）│
│       → 远端 VM 里的 harness                                  │
└──────────────────────────────────────────────────────────┘

①② 走"轻量补全/编辑"通道，③④⑤ 共享同一套 agent harness（这是 Cursor 团队自己用的术语，对应"模型外面那一圈让模型变得有用的工程层"）。

#2.2 一次 Cmd+L 触发的链路（以 Agent 模式为例）

[ 用户在 IDE 输入 prompt + Cmd+Enter ]
            │
            ▼
[ Client：本地装配 context ]
   ├─ 拉当前 active editor 文件 + 选中文本
   ├─ 命中 Always rules + 命中 globs 的 Auto-Attached rules
   ├─ 把 Agent-Requested rules 的 description 塞进 system prompt 候选区
   ├─ 加载 Memories（项目级）
   ├─ 解析 prompt 中的 @File / @Code / @Docs / @Web / @Codebase
   ├─ 如带 @Codebase：本地把 query 加密 → 服务端检索 → 返回 obfuscated
   │   path + 行号 → 客户端按 hash 验证后**本地读原文**塞进 ctx
   └─ 列出当前可用 tools：内置 edit/shell/search + MCP servers + ...
            │
            ▼
[ 发到 Cursor 后端（HTTPS） ]
   - request 体：messages + tools + model selector
   - Privacy Mode 下走专门的"零持久化"实例
            │
            ▼
[ Auto 路由（如果选了 Auto） ]
   - 根据 prompt 复杂度 + 当前余额池 + 模型可用性
     选择 Composer / Sonnet / GPT-5 / Gemini
            │
            ▼
[ 模型 ReAct 循环 ]
   ├─ thought + tool_call → 后端代理执行
   ├─ tool_result → 流式回 client
   └─ 直到 final answer 或用户中断
            │
            ▼
[ Client：渲染 ]
   ├─ 文本 → Chat panel
   ├─ edit → 内联 diff（绿/红高亮，按 Accept/Reject）
   ├─ shell → 终端 panel（默认 ask before run，可配 auto-run）
   └─ MCP tool 调用 → 弹审批气泡（默认）

#2.3 entry point 的"可观测出口"

虽然 Cursor 不开源，但下面这些是用户侧能直接看到的：

出口	在哪能看到	可观测内容
网络流量	浏览器 DevTools / mitmproxy（自费试）	请求会到 `*.cursor.com` 域名
工具调用	Chat panel 里的 "Used tool" 折叠块	工具名 + 参数（部分截断）
索引状态	Settings → Indexing	已索引文件数 / 上次同步时间
Model 决策	Settings → Models（不显示 Auto 实际选了谁，这是个长期 Forum 痛点）	启用列表
计费	cursor.com/dashboard → Usage	各模型消耗 credits

官方未披露：Auto 路由的具体策略未公开。Forum 里反复有人投诉 "Auto 太慢" "Auto 不告诉我用了什么"，2026 年仍未给出可见性。

#三、Agent 怎么思考 —— Agent / Ask / Custom + Composer 主循环 + Cloud Agent

"Composer 不是一个模型在思考，是 harness 借模型来思考。"

#3.1 主循环就是工具增强 ReAct

不管选哪个模式（Plan / Agent / Debug），主循环都是经典的 ReAct：

loop:
  model.invoke(messages, tools=[edit, shell, grep, read, search, mcp_*, ...])
    ├─ if response.tool_calls:
    │     for call in tool_calls:
    │         result = execute(call)             # 客户端或服务端执行
    │         messages.append(tool_result)
    │     continue
    └─ else:
          stream final text → UI
          break

不同模式的差异主要是工具白名单 + 终止条件 + 系统提示：

模式	tools 白名单（可观测）	终止条件
Ask	read, grep, codebase_search, web	给出文字答案即停
Plan	上述 + 探查类 shell（如 `ls`/`git log`）	输出结构化 plan，等用户 confirm 后再进 Agent
Agent	全部（edit / shell / mcp / browser / ...）	任务完成或用户中断
Debug	Agent 全集 + 临时 log 注入	拿到运行时证据后给结论

#3.2 Composer-Model：自家训的"快但够用"

2025 年 10 月 29 日发布的 Composer 模型（注意：和 UI 名同名，见 cursor.com/blog/composer）有几个明牌：

架构：Mixture-of-Experts (MoE)，支持长上下文 generation 与 understanding。
训练方式：RL 在"真实大型代码库的软件工程任务"中训练，挂载真实工具（代码编辑、 semantic search、terminal）让模型 learns useful behaviors on its own——做复杂搜索、修 lint、写 + 跑单测。
训练时挂的工具：codebase 语义搜索、grep、终端、文件读写。注意：模型在训练时就"知道"这些工具的存在，所以推理时调用得格外熟练。
速度目标：官方原话 "generation speed four times faster than similar models"，把"交互式开发的低延迟"作为一等公民优化。
能力定位：宣称"frontier-level coding performance"，但第三方实测整体仍弱于 GPT-5 / Sonnet 4.5 / Opus 这一档（待核实，无统一基准）；主要用来截"日常 routine" 的 token 量。

这个定位很关键：Composer 不是想干掉 Anthropic / OpenAI，是想截走"日常 routine" 那一档的 token 量——既省成本又能更紧地耦合自家 harness 的工具调用约定。

#3.3 多 Agent 并行 = git worktree + 远端 VM

Cursor 2.0 引入"多 agent 同时跑同一任务"。两种隔离方式：

本地多 agent（git worktree）：
  repo/.git 共用
  agent A → worktree-a/  改 src/foo.ts
  agent B → worktree-b/  改 src/foo.ts （不冲突）
  最后用户挑一个合并

云端多 agent（Cloud Agents）：
  agent A → VM A：clone repo, 跑测试, 出 PR
  agent B → VM B：clone repo, 跑测试, 出 PR

并配套了一个"race pattern"：对同一任务派发多个不同模型，挑输出最好的。这是 Cursor 在 "模型路由不可知，那就让它们一起跑、再选" 这条思路上的实践。

#3.4 Background / Cloud Agents：harness 的远端复制

完整链路 (基于官方文档 + 第三方逆向)：

用户在以下任一处发起（官方文档列举的 6 种入口）：
  - cursor.com/agents 页面（Cursor Web）
  - IDE 的 Cloud 下拉（Cursor Desktop）
  - Slack 里 @cursor 加任务描述
  - Linear ticket 评论里 @cursor
  - GitHub PR/Issue 评论里 @cursor
  - REST API（Cursor 官方对外提供）

         │
         ▼
[ Cursor 后端：分配一个 isolated VM ]
  ├─ git clone 仓库到 VM（需要 read-write 权限，GitHub/GitLab）
  ├─ 按 `.cursor/environment.json` 装环境（可指定 Dockerfile / snapshot / agent-led setup）
  ├─ 检 hooks + 企业 hooks
  ├─ 注入 workspace secrets
  ├─ 启动 harness 主循环（同 IDE 内 Agent）
  └─ 给 VM 配齐：terminal / browser / 桌面（computer use）
         │
         ▼
[ Agent 在 VM 内自主跑：可以用 Computer Use ]
  ├─ 跑 dev server 看效果
  ├─ 浏览器操作 UI 验证
  ├─ 录视频 + 截图
  └─ commit + push 到新分支
         │
         ▼
[ 出口 ]
  ├─ GitHub PR
  ├─ 通知回 Slack / Linear
  └─ Cursor Web 仪表盘可看视频回放

第三方观察的关键洞察：harness 才是产品——同一个模型（GPT-5 / Claude）你自己用 API 也能跑，但 Cursor 把"VM、git worktree、video recording、PR 组装、conflict 解决、重试策略"打包成产品，这是定价依据。

(推断) Cloud Agents 的模型选择发生在 harness 层，由 Cursor 决定，不暴露给开发者。例如 "GPT-5 用于长 horizon 编码，Claude 用于推理重的子任务，Gemini 用于大上下文，Composer 用于 routine"——这是第三方观察，官方未列硬规则。

#3.5 Cursor CLI vs Claude Code

行业里最近这两个会被反复对比，关键差别：

维度	Cursor CLI	Claude Code
起家	IDE 起家，CLI 是补丁	CLI 起家
sub-agent 能力	单层	可嵌套多层 + hook
与 IDE 协同	与 Cursor IDE 共享配置（.cursor/rules、mcp.json）	IDE 协同靠扩展
默认模型	Auto 路由（含 Composer）	Sonnet/Opus
适合场景	"在终端里复用我已经配好的 IDE 工程上下文"	"在终端里把 agent 当无人值守的 worker"

Cursor CLI 的存在主要是为了让 .cursor/rules + mcp.json 这套工程配置在 CI / SSH 远端机器上也能跑，不是要跟 Claude Code 在 CLI 哲学上对线。

#四、Agent 怎么行动 —— Edit / Shell / Search / @ 引用 / MCP

"Cursor 的工具系统分两层：内置工具（焊死的）+ MCP 工具（你接的）。"

#4.1 内置工具清单（可观测 + 部分官方）

文件类：
  read(path, lines?)        # 读文件（agent 高频调用）
  edit(path, diff)          # 应用 diff
  apply_patch(...)          # 大块改写
  create_file(path, body)
  delete_file(path)

搜索类：
  codebase_search(query)    # 语义搜索（走 Turbopuffer 索引）
  grep(pattern, path?)      # 精确搜索
  list_dir(path)

执行类：
  run_terminal_cmd(cmd)     # 终端命令，默认 ask before run
  run_in_background(cmd)    # 后台 dev server 等

Web / Docs：
  fetch_url(url)            # @Web 背后
  search_docs(library)      # @Docs 背后

UI / Browser（2.0 起）：
  browser_navigate / click / screenshot   # 测试自家产物

(可观测) 这些都能在 Chat panel 的 "Used tool" 折叠块里看到调用名。

#4.2 @ 引用 = "把上下文塞 prompt 的语法糖"

@-symbol 是 Cursor 的核心交互发明之一：

符号	作用	是工具调用还是 prompt 注入？
`@File` / `@Folder`	把整个文件/目录贴进 ctx	prompt 注入，进 ctx 就走了
`@Code`	选定行号范围贴进 ctx	prompt 注入
`@Codebase`	让 agent 用语义搜索召回	触发 codebase_search 工具
`@Web`	实时联网搜索	触发 web 工具
`@Docs`	第三方库官方文档（可自己加 URL crawl）	触发 docs 工具
`@Git`	把 commit / diff / branch 信息贴进 ctx	prompt 注入
`@<rule-name>`	手动激活 Manual rule	rules 注入

设计巧思：@Codebase / @Web 这种"成本高"的留在工具调用里（agent 决定是否要用）， @File / @Code 这种"用户已经决定要的"直接注入 prompt。一冷一热分开处理。

#4.3 MCP：把外部世界接到 Composer

Cursor 是较早把 MCP（Model Context Protocol，Anthropic 提的标准）做成一等公民的 IDE。配置文件：

// .cursor/mcp.json (项目级) 或 ~/.cursor/mcp.json (全局)
{
  "mcpServers": {
    // stdio：本地起进程
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${env:GH_TOKEN}" }
    },
    // HTTP / SSE：远端 server
    "my-sse-server": {
      "url": "https://example.com/sse",
      "headers": { "Authorization": "Bearer ${env:MY_TOKEN}" }
    },
    // OAuth Remote：远端 + OAuth flow（用户首次连接时弹浏览器授权）
    "linear": {
      "url": "https://mcp.linear.app/sse"
      // OAuth 由 Cursor IDE 接管，回调 URI 由 Cursor 内置注册，
      // 用户无需在 mcp.json 里填 client_id / client_secret
    }
  }
}

支持三种连接方式：

stdio：本地起进程，pipe 通信
HTTP/SSE：远端 server，URL + headers
OAuth Remote：远端 + OAuth 流，回调 URI 是 Cursor 内置注册的 cursor://anysphere.cursor-mcp/oauth/callback（待核实最新版本是否变更）

变量插值支持：${env:NAME} / ${userHome} / ${workspaceFolder}。

#4.3.1 著名的"40 工具天花板"

社区实战痛点：所有启用的 MCP 工具加起来超过 ~40 个会触发警告，部分工具会被静默禁用。官方解释为"模型在过多工具中选错的概率显著上升 + 每个工具的 schema 都吃 context tokens"。(Forum 可观测) 实际硬上限大约在 80 左右，超过会直接拒绝注册。

应对：用户得在 Settings → Tools & MCP 里手动开关具体工具，避免一个 MCP server 注册 20 个 tool 把池子吃掉。Cursor 没有像 Claude Code 那样的 ToolSearch 延迟加载机制，schema 全部前置注入。

#4.4 Hooks / 环境配置（2025 起）

Cloud Agent 的环境装配通过两个文件描述（待核实是否合并/拆分）：

.cursor/environment.json：官方确认的 Cloud Agent 环境定义文件，可指定 Dockerfile / 保存的 snapshot / agent-led setup 三选一，让 VM 启动时装好依赖、注入 secrets、跑预热脚本。
.cursor/hooks.json：用于在工具调用前后插入脚本，做 audit log / 强制 lint 等。官方对 hooks 的完整 schema 文档化不全（截至 2026-04），社区也主要在 Cloud Agent 上见到生效；IDE 端没有等价的 pre/post tool hook。

这是 Cursor 第一次承认 "agent 行为需要确定性 hook"，但整体生态远不如 Claude Code 的 hook 体系成熟（Claude Code 有 OTel + 5 类 hook + 进程级 sandbox）。

官方未披露：hooks.json 完整 schema 没找到详细文档；environment.json 的字段表官方也只在 background-agent 文档里以例子形式给出，完整 reference 缺失。

#五、Agent 怎么记忆 —— Rules / Memories / 索引 / AGENTS.md

"Cursor 的记忆是分四层堆出来的，每层独立失效。"

#5.1 四层记忆架构

┌─────────────────────────────────────────────────────┐
│  Layer 4: 用户长期偏好                                │
│  - User Rules（账号级，跨项目）                       │
│  - 不进 git、不跨电脑（除非登录）                     │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│  Layer 3: 项目工程约定                                │
│  - .cursor/rules/*.mdc（进 git，团队共享）            │
│  - AGENTS.md（进 git，行业通用）                      │
│  - Team Rules（企业管理后台下发）                      │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│  Layer 2: 自动萃取的会话记忆                           │
│  - Memories（项目级，模型从对话学，存 Cursor 后端）    │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│  Layer 1: 代码实体记忆                                │
│  - Codebase Index（Merkle tree + chunk + embedding）  │
│  - 存 Turbopuffer + AWS cache，按 hash 索引           │
└─────────────────────────────────────────────────────┘

#5.2 Codebase Indexing 的工作原理（最有料的一层）

官方博客 "Securely indexing large codebases" 给了较多细节。简化流程：

[ 客户端 ]
  1. 扫描工作区（尊重 .gitignore + .cursorignore）
  2. 给所有文件构建 Merkle tree（每个节点是子内容的 cryptographic hash）
  3. 把文件按句法切成 chunks
  4. 把 Merkle 根 hash 上传给服务器，比对差异
       ↓
[ 服务端 ]
  5. 找出哪些 chunk 是新的 / 改过的
  6. 对新 chunk 调 embedding API（OpenAI 或自家模型）
  7. 把 embedding 写进 Turbopuffer（向量库，GCP US 区）
  8. 把 embedding **缓存到 AWS**，按 chunk hash 索引（同样代码二次索引秒级完成）
  9. 文件路径以"按 / 和 . 切段后逐段加密"的形式存（key 在 client）
       ↓
[ 查询时 ]
 10. 客户端把 query embed 送服务端
 11. Turbopuffer 返回 top-K chunk hash + obfuscated path + 行号
 12. 客户端用本地 Merkle 验证 "我确实有这个文件 + 这一段"
 13. 客户端**本地读原文** 拼进 LLM context

几个反直觉的设计细节：

plaintext 永不上服务端：服务端只知道 hash + embedding。这点对企业 sell 至关重要。
Privacy Mode：连 embedding 都不留，跑完即焚；走专门的 "no logging" 实例。
simhash 跨用户复用：同一组织内不同用户索引同一个 repo，Cursor 会识别"你们其实索引的是同一份代码"，新用户不用从头跑 embedding。
每 ~10 分钟增量同步：靠 Merkle tree diff，只传变动节点。

#5.3 Memories 与 Rules 的边界

维度	Rules	Memories
谁写的	用户	模型
触发	确定性（always / glob / @-mention / agent decides）	agent 自动召回
存哪	文件（进 git） / Settings	Cursor 后端
跨设备	rules 进 git 跟着代码	跟着账号走
可审	直接读文件	UI 列表里看
失效粒度	删文件	单条删除

(Forum 共识) Memories 上线之后社区分两派：一派觉得"终于有真记忆了"，另一派担心"模型瞎记"，最佳实践是 关键约定写 rules，琐碎偏好留 memories。

#5.4 上下文压缩 / 长会话

官方未披露：Cursor 没公开他们对长会话怎么做 summarization / pruning。社区可观测的现象是"对话拉长后老 ctx 会被有损压缩"，但具体机制（窗口、阈值、压缩 prompt）未公开。Cursor 2.0 起 Composer 是长上下文 MoE，理论上压缩压力小一些。

#六、Agent 怎么开口 —— 内联 diff / Chat panel / Agents Window

"输出形态是 Cursor 的强项——它把 LLM 文本回流变成了可审、可撤、可继续的 UI 组件。"

#6.1 三种输出 UI

UI	触发	形态	可交互
Inline diff（行内绿/红）	edit 工具	在编辑器原位	Accept / Reject / Accept all / Modify
Chat panel	普通文本回复	右侧/底部面板	复制、引用上一条、继续追问
Agents Window（2.0 / 3.0 引入）	Cloud Agents / 多 agent 并行	替代 chat 的"任务编排"视图	看每个 agent 状态：Planning / Executing / Reviewing / Done

#6.2 流式 + 增量 diff 的关键工程

Cursor 的"边写边显示 diff"是核心体验，背后涉及：

流式 token 回压：Cursor 后端做了一层 buffer，用稳定速率 push 给 client，避免抖动。(推断)
diff 的 morphing：模型不是一次生成完整 diff，而是 token 流入时增量重建 diff 视图， Forum 上提到过这是 Cursor 对自家 "morph apply" 模型的优化。 (推断)
可中断：用户按 ESC 任何时候都能掐流，已经写到 buffer 的 diff 不会落盘。

官方未披露：Cursor 的内部 apply model（专门把 LLM 输出的 patch 套到代码上的小模型）工作机制只在零散博客里提到，没有完整 spec。

#6.3 Background Agent 的"开口"特别在哪

Cloud Agents 不通过流式 chat 开口，而是通过：

GitHub PR：commit message + PR description 由 agent 写
30 秒 demo 视频：computer-use 录的实操回放
Slack/Linear 评论：进度更新 + 完成提醒
artifact bundle：截图 / 日志 / 视频打包附 PR

端长任务的 output"做成了 PR + 视频，而不是 chat 流**——这背后是对"agent 长任务等不来用户盯着"的工程认知。

#七、Agent 的外脑 —— Auto 路由 / Composer / Frontier 模型池

"Cursor 卖的是 harness，不是模型 API；模型只是路由器后面的池子。"

#7.1 模型池构成

类别	例子	在 harness 里的角色
自家专长	Cursor Tab 模型	Tab 自动补全（不暴露选择）
自家专长	Apply 模型（morph）	把 LLM 输出的 patch 真正落到文件
自家通用	Composer / Composer-2	Auto 模式下的 routine 选择，4× 同档位速度
外采 frontier	Sonnet 4.5 / 5、Opus、GPT-5、Gemini 2.5	Auto 模式遇到硬任务时升级；用户也可手选
外采 fast	Haiku、Gemini Flash	早期 Auto 选项，现被 Composer 部分取代

#7.2 Auto 模式做了什么（已知 + 推断）

官方说法：基于任务类型 + 复杂度选最合适的模型。 Forum 可观测：

不显示具体选了谁（这是用户最大的抱怨）
简单任务被路由到便宜模型，效果时好时坏
高峰期会进"slow pool"——同一任务排队更久

(推断) Auto 大概率综合了：prompt 长度 + 工具调用预测 + 当前余额 + 各模型当前容量。用户偶尔抱怨"Auto 比手选还慢"，根因是它进了 slow pool 但 UI 没说。

#7.3 Fast vs Slow Pool（计费分层的旧模型）

2025 年 6 月之前是这样的：

Pro $20/月：
  - 500 fast requests（专属配额，秒级响应）
  - unlimited slow requests（共享池，可能排队 30s-数分钟）

2025 年 6 月起改成 credit-based：

Pro $20/月：
  - 折成 $20 API credits 池
  - 所有模型按真实成本扣费
  - 没有 fast/slow 之分了（理论上）

切换过程社区炸锅过一轮（"我之前花的 fast 要怎么算？"），Anysphere 7 月 4 日发了公开道歉 + 退款。这件事是 Cursor 商业模式与产品复杂度冲突的典型案例。 (已确认)

#7.4 Cloud Agents 的模型选择

由 harness 决定，不暴露：

(第三方推断) GPT-5 用于长 horizon 任务、Claude 用于推理重子任务、Gemini 用于大上下文场景、Composer 用于 routine。Cursor 团队也用 race pattern：同任务并发派给多个模型，挑最好的输出。

这种"模型路由从用户决策升格为产品决策"是 Cursor 与 Claude Code 哲学最大的分歧之一。Claude Code 让你用啥就是啥，Cursor 把模型当成了可替换的零件。

#八、关键设计权衡（架构师视角）

每条按"问题 → 回答 → 启发"三段式。

#8.1 闭源 IDE 怎么"读懂大型代码库"又不变成法律风险？

问题：要给 LLM 喂全部代码片段才好用，但客户最怕"我代码被你存了"。

回答：

客户端 chunk + 上传 hash 与 embedding，不传 plaintext
文件路径分段加密（key 在客户端）
Privacy Mode 下连 embedding 都不持久化
Turbopuffer 选 GCP US 区，合规边界清晰
用 Merkle tree 做增量 + simhash 做跨用户复用，少传就是少风险

启发：当你既想"看到所有代码"又"不能存代码"时，索引层和明文层必须分开—— 让服务端只持有"指针 + 摘要"，明文永远在客户端。这思路对任何"私有数据 + 公有 LLM"产品都通用。

#8.2 自家模型 vs 外采 frontier，怎么不打自己脸？

问题：Anthropic / OpenAI 模型那么强，自家小模型存在的意义是什么？

回答：

场景错位：自家 Tab 模型干"行级补全"，frontier 模型干"多文件 edit"，不抢生意。
训练耦合：Composer 训练时把 Cursor 自家工具（codebase 语义搜索、apply diff）当成一等公民学，调用熟练度比通用模型高。
成本路由：routine 走 Composer，4× 速度 + 自有定价，省下来的钱补 frontier 的开销。
harness 锁定：模型可以换，harness 不能换；自家模型让 harness 更容易优化 end-to-end。

启发：当你做 LLM 应用时，不一定要训自己的 frontier，但训一个"懂自家工具" 的中端模型很有杠杆——它解锁的是 "我能控制的延迟 + 我能控制的 routine 路径"。

#8.3 Rules 越来越多，怎么不让 system prompt 爆炸？

问题：项目大了 .cursor/rules/ 能塞 50+ 文件，全 inject 会把 ctx 吃光。

回答：四种触发模式分层

Always：核心强约束（编码风格、安全），少而精
Auto-Attached：靠 globs 文件相关性触发，按需加载
Agent-Requested：把 description 给 agent，agent 自己决定要不要看全文
Manual：需要时 @-mention 调

四种方式叠加，实际进 prompt 的 rules 远少于硬盘上的 rules。

启发：规则系统的关键不是"能写多少"，是"何时不进 prompt"。任何"长期规则 + LLM"的系统都需要一套召回机制（无论是 glob、embedding 还是 LLM 自决策）。

#8.4 多 Agent 并行，怎么不互相打架？

问题：用户想让 5 个 agent 同时跑 5 个候选实现，但它们改的是同一份代码。

回答：

本地：git worktree 给每个 agent 一个独立工作树，公用 .git
云端：isolated Linux VM 每个 agent 一台机
出口：race pattern——结果在 review 阶段由用户挑，或自动选 test 全过的

启发：并行 agent 的真正瓶颈不是模型，是文件系统隔离 + 结果合并。Cursor 用 "文件系统 == 物理隔离"取代了软件级 lock，解法又笨又有效。

#8.5 IDE-only → IDE + CLI + Cloud，怎么不让用户精分？

问题：用户在 IDE 配了一堆 rules + MCP，跑去 CLI 或 Cloud Agent 时不想再配一遍。

回答：统一配置层

.cursor/rules/ → IDE / CLI / Cloud Agent 都读
.cursor/mcp.json → 三处共享
.cursor/hooks.json → Cloud Agent 也认
账号级 Memories → 跟着账号走

启发：当一个产品从单形态扩展到多形态（IDE + CLI + Cloud），配置标准化早做比晚做便宜十倍。Cursor 抓住了 .cursor/ 这个目录约定，把它做成事实标准（甚至其他 agent 工具开始兼容）。

#8.6 闭源能走多远？开放标准能不能反吃自己？

问题：Cursor 拥抱了 MCP（Anthropic 标准）和 AGENTS.md（行业约定），同时坚持 harness 闭源。这两件事矛盾吗？

回答：

拥抱开放是为了减小客户接入摩擦——你已经有 MCP server，不用为我重写
闭源 harness 是因为harness 才是产品——VM 编排、PR 组装、视频录制、模型路由这些细节构成护城河
模型是商品，规范是地基，harness 是产品。

启发：现代 AI 产品的护城河越来越"在工程编排层"而非"模型/协议层"。借开放标准把上下游打通，把价值留在中间的 harness。

#九、附录：组件地图、关键概念、文档索引

#9.1 组件地图（一张图看懂 Cursor agent 生态）

┌────────────────────────────────────────────────────────────────────┐
│                          用户表面                                    │
├────────────────────────────────────────────────────────────────────┤
│  IDE                  CLI            Web Dashboard    Slack/Linear/GH│
│  - Tab                cursor agent   cursor.com/agents @cursor       │
│  - Cmd+K              cursor mcp     PR/Issue 评论     mention       │
│  - Cmd+L (Chat)                                                      │
│  - Agents Window                                                     │
└────────────────────────────────────────────────────────────────────┘
              │              │                │              │
              └──────┬───────┴────────────────┴──────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│                      Cursor Harness (闭源核心)                       │
├────────────────────────────────────────────────────────────────────┤
│  ┌── 配置层 ──┐  ┌── 编排层 ──┐  ┌── 执行层 ──┐  ┌── 验证层 ──┐    │
│  │ rules/    │  │ Mode 路由  │  │ Local IDE  │  │ Browser    │    │
│  │ mcp.json  │  │ Auto 模型  │  │ git worktree│  │ Computer use│   │
│  │ hooks.json│  │ Race pattern│  │ Cloud VM   │  │ 视频/截图   │   │
│  │ Memories  │  │ Plan/Debug │  │ Sandbox    │  │ 测试        │    │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘     │
└────────────────────────────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│                       工具与索引                                     │
├────────────────────────────────────────────────────────────────────┤
│  内置 Tools          MCP Servers           Codebase Index            │
│  - read/edit/grep    - stdio/http/oauth    - Merkle tree             │
│  - run_terminal      - 40 个软上限         - chunks → embeddings     │
│  - browser           - 个体审批            - Turbopuffer (GCP)       │
│  - codebase_search                         - AWS hash cache          │
│  - fetch_url / docs                        - 路径分段加密            │
└────────────────────────────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────────┐
│                          模型池（外脑）                              │
├────────────────────────────────────────────────────────────────────┤
│  自家：Tab / Apply / Composer (MoE, RL-trained)                     │
│  外采：Claude Sonnet/Opus/Haiku · GPT-5/Codex · Gemini 2.5 Pro/Flash │
│  路由：Auto = 自家路由器；Cloud Agent = harness 决定               │
└────────────────────────────────────────────────────────────────────┘

#9.2 关键概念速查

概念	一句话	与谁易混
Cursor	Anysphere 出品的 AI-first IDE	不是模型；不是公司名
Anysphere	Cursor 的母公司
Composer (UI)	multi-file edit 面板，2.0 起合入 Agent 模式
Composer (Model)	自家训的 MoE 模型，主打 routine 编码 + 速度	同名不同物，与 UI 无直接关系
Agent Mode	主推模式：可读写文件、跑 shell、迭代	Ask/Plan/Debug 是它的兄弟模式
Cloud Agents / Background Agents	远端 VM 里跑的 agent，靠 PR 出活	"Background" 是早期名
Cursor Tab	行级/多行 ghost-text 补全（自家小模型）	不是 LLM，专用
Cmd+K	行内编辑（局部 edit），轻量	比 Chat 简单，比 Tab 重
`.cursor/rules/`	项目级规则目录，多 mdc 文件	旧 `.cursorrules` 单文件已被替代但仍兼容
MDC frontmatter	rules 文件头部的 yaml 元数据
Always / Auto Attached / Agent Requested / Manual	四种 rule 触发模式
AGENTS.md	行业通用约定，Cursor 兼容	与 rules 同效但更通用
Memories	模型从对话萃取的项目级长期记忆	与 rules 互补
`.cursor/mcp.json`	MCP server 配置文件
40-tool limit	启用 MCP 工具数量软上限	实际硬上限 ~80
Auto Mode	自家模型路由器	不显示选了谁
Fast / Slow pool	旧计费模型，已 2025-06 改 credit-based	老文章里仍常见
Bugbot	自动 PR review：默认每次 PR 更新触发，可手动评论 `cursor review` / `bugbot run`；Bugbot Autofix 会拉起 Cloud Agent 在新分支或同分支修（3 次重试上限）
`.cursor/environment.json`	Cloud Agent 的环境装配文件，Dockerfile / snapshot / agent-led setup 三选一	与 `hooks.json` 不同
Cursor CLI	`cursor agent` / `cursor mcp` 命令行入口	与 Claude Code 不同哲学
harness	"模型外的所有工程层"——Cursor 自己的术语
race pattern	同任务多模型并发，挑最优
git worktree	本地多 agent 并行的物理隔离基础
Turbopuffer	Cursor 用的向量数据库（GCP US）
Privacy Mode	关闭一切持久化 + 模型 provider 不训

#9.3 一句话总结

Cursor 不卖模型，卖的是"模型外面那一圈让模型变得有用的工程"——把 IDE、Tab、 Cmd+K、Chat、Plan、Debug、Cloud VM、PR、Slack 通知、git worktree、MCP、视频回放、模型路由、credit 计费打包成一个产品。模型可以换，harness 不能换。

#9.4 文档与资料索引

官方文档（已确认事实来源）：

Cursor Docs: https://cursor.com/docs
Rules: https://cursor.com/docs/context/rules
Modes (Agent / Ask / Custom): https://cursor.com/docs/agent/modes
Cursor changelog: https://cursor.com/changelog
Cursor 2.4 changelog（Subagents / Agent Skills / hooks）：https://cursor.com/changelog/2-4
MCP: https://cursor.com/docs/mcp / https://cursor.com/docs/cli/mcp
Cloud Agents: https://cursor.com/docs/cloud-agents
Bugbot: https://cursor.com/docs/bugbot
Tab: https://cursor.com/docs/tab（旧 URL docs.cursor.com/tab/overview 现已重定向）
Security & Privacy: https://cursor.com/security / https://cursor.com/data-use

官方博客（设计意图来源）：

Cursor 2.0: https://cursor.com/blog/2-0
Composer Model（2025-10-29 发布）: https://cursor.com/blog/composer
Cloud Agents: https://cursor.com/blog/cloud-agents
Self-hosted Cloud Agents: https://cursor.com/blog/self-hosted-cloud-agents
Securely indexing large codebases: https://cursor.com/blog/secure-codebase-indexing
Pricing 改革: https://cursor.com/blog/june-2025-pricing
Bugbot: https://cursor.com/blog/bugbot-autofix
Debug Mode: https://cursor.com/blog/debug-mode
Best practices: https://cursor.com/blog/agent-best-practices

社区可观测来源：

Forum: https://forum.cursor.com/（特别是 Auto / Slow pool / 40-tool limit / Memories 讨论帖）
Changelog 2.2 (Debug Mode / Plan Mode): https://cursor.com/changelog/2-2

第三方深度分析（部分推断的源头）：

"The Harness Is the Product": https://cozypet.github.io/cursor-cloud-harness/
Engineer's Codex 索引解析: https://read.engineerscodex.com/p/how-cursor-indexes-codebases-fast
Towards Data Science 索引解析: https://towardsdatascience.com/how-cursor-actually-indexes-your-codebase/

#9.5 本文最不确定的两点

文末按交付要求，明确标记调研中最弱的两个环节：

Auto 路由的具体策略不公开。包括"复杂度判定"、"任务类型分类"、与 fast/slow pool 的关系，全部是 forum 推断 + 行为观察，无 cursor.com 官方 spec。
Cursor 内部 apply model / Tab model 的工程细节几乎不可见。我们知道存在这两个小模型、大概干什么，但训练数据、规模、和 Composer 的 RL pipeline 是不是同一套基础设施，都是空白。

凡正文中标 (推断) / (可观测) / 官方未披露 的段落，请读者带着这层置信度去读。

总结（≤200 字）

消歧：Cursor 是 Anysphere 的 AI-first IDE，不是模型；其"agent"无持久化实体，由 Mode + Rules + Memories + Codebase Index + Model 五维拼出。核心产品是 harness 而非模型——Composer-Model 自家训只为 routine 路径，frontier 模型外采后被 Auto 路由调度。Cloud Agents 用 isolated Linux VM 把 harness 复制到云端，出口是 PR + 视频。

文档路径：agents/docs/cursor-agent-architecture.md

最不确定 2 点：(1) Auto 路由的具体策略全部为推断，没有官方 spec；(2) Cursor 内部 apply / Tab 小模型的工程细节几乎不可见。