CursorCursor

模型与开放条件Model & openness

可选模型、额度和刷新周期随档位变化；核验时的具体限制见下文。

官方首页列出的可选范围：

• OpenAI / Anthropic / Gemini / SpaceXAI / Cursor 自研

供应方已明确不止一家：导航含 Grok / Grok Bot，各档另列「Grok 使用额度」。

Auto 模式的候选（2026-10-01 官网示例）：

• Grok 4.7
• GPT-5.6 Sol
• Fable 5.1
• Max Opus 5.5
• Gemini 3.1 Pro
• Composer 2.5

额度机制（2026-10-23 滚动核验：已换轨）：

旧口径是按月额度倍数（Pro=extended、Pro+=3x、Ultra=20x）； 官方定价页现改为每档一个跨 Cursor 与 Grok 共享的用量池、按周刷新 （官方原文 "allowance refreshes weekly"）。

⚠ 换轨后模型可得性成了档位差异：Plus 仅含 Grok 模型 （"Plus includes Grok models only"），Premium 及以上给 Grok 宽裕用量 但仍不含第三方模型额度（"do not include an allowance for third-party models"）。 这与旧版「差别只在额度倍数、不在模型可得性」的结论相反。

Cursor Router 按 cost / balance / intelligence 三档在多模型间路由。 官方说明按被路由到的模型标价计费。 Router 先在 Teams / Enterprise 推出，个人档「数月后」跟进。

Available models, allowances and refresh periods vary by tier; the checked restrictions are described below.

The selectable range listed on the official homepage:

• OpenAI / Anthropic / Gemini / SpaceXAI / Cursor in-house

The supply side is explicitly more than one vendor: the navigation includes Grok / Grok Bot, and each tier lists a separate "Grok usage allowance".

Auto-mode candidates (official-site example, 2026-10-01):

• Grok 4.7
• GPT-5.6 Sol
• Fable 5.1
• Max Opus 5.5
• Gemini 3.1 Pro
• Composer 2.5

Allowance mechanism (rolling re-check 2026-10-23: the scheme has switched):

The old scheme was monthly allowance multiples (Pro=extended, Pro+=3x, Ultra=20x); the official pricing page now uses one usage pool per tier, shared across Cursor and Grok, refreshed weekly (official wording: "allowance refreshes weekly").

⚠ After the switch, model availability became a tier difference: Plus includes Grok models only ("Plus includes Grok models only"); Premium and above give generous Grok usage but still do not include an allowance for third-party models ("do not include an allowance for third-party models"). This is the opposite of the old conclusion that "the difference is only in allowance multiples, not model availability".

Cursor Router routes across models in three modes: cost / balance / intelligence. The official docs say billing follows the list price of whichever model gets routed to. The Router launched first on Teams / Enterprise; personal tiers follow "in a few months".

运行位置Where it runs

两种运行形态：云端，或自托管在你自己的机器上。

这是本分区最独特的架构。

2026-09-02 官方推出自托管支持：

• 代码库、构建产物与密钥都留在你自有基础设施内运行的机器上
• 由智能体在本地处理工具调用

另有 My Machines 形态： 把单台笔记本或 VM 连到账户，用于个人工作流。

Cursor Router 的可用面更宽。 官方文档说明它可以在编辑器 / CLI / Cursor SDK / iOS 应用中使用。

Two run modes: cloud, or self-hosted on your own machines.

This is the most distinctive architecture in this section.

Official self-hosting support launched 2026-09-02:

• Codebases, build artifacts and secrets stay on machines running inside your own infrastructure
• Agents handle tool calls locally

There is also the My Machines mode: connect a single laptop or VM to your account, for personal workflows.

Cursor Router has a wider surface. Official docs say it works in the editor / CLI / Cursor SDK / iOS app.

本地文件Local files

编辑器形态读工作区文件；自托管形态下代码与产物不离开你的基础设施。

它由 VS Code 衍生而来，所以文件访问方式与编辑器一致。

索引策略官方写了（2026-10-03 补，取自官方 Search 文档页）。

检索用自研的 Instant Grep。 官方称它在大型代码库上优于 ripgrep，无需配置。

官方原文："runs automatically; no configuration needed"。

一条值得单独记的数据边界：

官方原文："Instant Grep builds and queries its index on your machine. Cursor does not upload file paths or code to build a search index, and it does not store embeddings of your codebase for search"。

也就是说：检索索引完全在本机，官方明说不为检索存 embedding。

⚠ 但同一页紧接着补了一句：

官方原文："When Agent opens a match, that file content can still be included in the model request"。

所以「建索引不出本机」≠「文件内容不出本机」。 命中之后，内容照样进模型请求。

Explore 子智能体是官方给的上下文控制手段：

• 跑在独立上下文窗口
• 用更快的模型
• 执行并行搜索后只回传相关发现

官方原文："returning only the relevant findings"。 官方明说这是为了避免把原始文件内容整段倒进主对话。

⚠ 大仓库的索引性能与规模上限，官方文档未给数字。

The editor mode reads workspace files; in the self-hosted mode code and artifacts never leave your infrastructure.

It derives from VS Code, so file access works the way an editor's does.

The indexing strategy is documented officially (added 2026-10-03, from the official Search docs page).

Retrieval uses the in-house Instant Grep. The official page claims it beats ripgrep on large codebases, with no configuration.

Official wording: "runs automatically; no configuration needed".

One data-boundary point worth recording separately:

Official wording: "Instant Grep builds and queries its index on your machine. Cursor does not upload file paths or code to build a search index, and it does not store embeddings of your codebase for search".

In other words: the search index stays entirely on your machine, and the official page explicitly says it stores no embeddings of your codebase for search.

⚠ But the same page adds right after:

Official wording: "When Agent opens a match, that file content can still be included in the model request".

So "indexing stays local" ≠ "file content stays local". Once a match is opened, the content still goes into the model request.

The Explore subagent is the official context-control mechanism:

• Runs in a separate context window
• Uses a faster model
• After parallel searches it returns only the relevant findings

Official wording: "returning only the relevant findings". The official page says this is to avoid dumping raw file contents into the main conversation.

⚠ Indexing performance and scale limits on large repos: the official docs give no numbers.

关机后的任务Tasks after shutdown

云端 Agent 可以脱离你的电脑继续跑，而且官方有明确表述。

「项目」跑在云端的独立计算机上，合上笔记本电脑也不会中断。

需要本机测试时，协调智能体会启动本地智能体。

官方另称协调智能体还能主动行动：

• 监听 Slack 频道
• 按计划运行
• 跟踪所有 PR

也就是无需等待提示就会动手。

Cloud agents keep running without your computer, and the official wording is explicit.

"Projects" run on dedicated cloud machines — closing the laptop does not interrupt them.

When local testing is needed, the orchestrator agent spins up local agents.

The official page also says the orchestrator can act proactively:

• Listen to Slack channels
• Run on schedules
• Track all PRs

That is, it acts without waiting for a prompt.

工具与扩展Tools & extensions

MCP、技能（Skills）与钩子（Hooks）三项官方成页。

⚠ 旧版档案写「从 Pro+ 起可用」——那是旧定价页能力清单的表述； 2026-10-23 滚动核验时档位已换轨（见「档位结构」一节）， 新定价页与 MCP 文档页均未再标注这三项的档位门槛， 本站未核验到新档位下这三项的可用范围。 Bugbot 是智能体驱动的代码审查。

Teams 档另有团队应用市场，面向内部规则、技能与插件。

MCP 接入细节（2026-10-03 补，取自官方 MCP 文档页）。

三种传输方式：

• stdio：本地，由 Cursor 启动；可用 shell 命令启动；手动认证
• SSE：可本地或远程部署为服务器；多用户；OAuth 认证
• Streamable HTTP：与 SSE 相同，可本地或远程部署为服务器；多用户；OAuth 认证

协议能力六项全支持：

• Tools / Prompts / Resources / Roots / Elicitation / Apps

配置分两层：

• 项目级 .cursor/mcp.json，可用 ${workspaceFolder}
• 全局 ~/.cursor/mjsson，可用 ${userHome}

变量插值支持四种：

• ${env:NAME}
• ${userHome}
• ${workspaceFolder}
• ${pathSeparator}

还支持 envFile 从 .env 读密钥（仅 stdio）。

⚠ 注意 ~ 是 home 目录缩写，与任何档位无关。

工具审批默认开启。

官方原文："Cursor asks for approval before using MCP tools by default"。

工具级 allowlist 可以限制某个服务器上哪些工具能自动运行。

每个 MCP 服务器有独立网络模式：

• Allow all / Allowlist / Deny all / No sandbox

Hooks 事件清单（2026-10-03 补，取自官方 Hooks 与插件参考页）。

agent 钩子 18 个：

• sessionStart sessionEnd preToolUse postToolUse
• postToolUseFailure subagentStart subagentStop
• beforeShellExecution afterShellExecution
• beforeMCPExecution afterMCPExecution
• beforeReadFile afterFileEdit
• beforeSubmitPrompt preCompact stop
• afterAgentResponse afterAgentThought

另有 Tab 钩子：

• beforeTabFileRead
• afterTabFileEdit

应用生命周期钩子：

• workspaceOpen

钩子是命令型，可带 matcher 过滤。

官方原文：{"command": "./hooks/audit.sh"}

官方还给了 TypeScript 变体（由 Bun 驱动），可做结构化 I/O 与 HTTP。

MCP, Skills and Hooks each have an official page.

⚠ The old entry said "available from Pro+" — that phrasing came from the old pricing page's feature list; at the 2026-10-23 rolling re-check the tiers had already switched (see the "Tier structure" section), and neither the new pricing page nor the MCP docs page marks a tier gate for these three features. This site has not verified the availability of these three features under the new tiers. Bugbot is agent-driven code review.

Teams also has a team marketplace for internal rules, skills and plugins.

MCP integration details (added 2026-10-03, from the official MCP docs page).

Three transports:

• stdio: local, launched by Cursor; can start via a shell command; manual auth
• SSE: local, or deployed remotely as a server; multi-user; OAuth
• Streamable HTTP: same as SSE, local or deployed remotely as a server; multi-user; OAuth

All six protocol capabilities are supported:

• Tools / Prompts / Resources / Roots / Elicitation / Apps

Configuration lives in two layers:

• Project-level .cursor/mcp.json, supports ${workspaceFolder}
• Global ~/.cursor/mjsson, supports ${userHome}

Four variable interpolations are supported:

• ${env:NAME}
• ${userHome}
• ${workspaceFolder}
• ${pathSeparator}

envFile is also supported, to read secrets from .env (stdio only).

⚠ Note: ~ is the home-directory shorthand, unrelated to any tier.

Tool approval is on by default.

Official wording: "Cursor asks for approval before using MCP tools by default".

A tool-level allowlist can restrict which tools on a given server may run automatically.

Each MCP server has its own network mode:

• Allow all / Allowlist / Deny all / No sandbox

Hooks event list (added 2026-10-03, from the official Hooks and plugin reference pages).

18 agent hooks:

• sessionStart sessionEnd preToolUse postToolUse
• postToolUseFailure subagentStart subagentStop
• beforeShellExecution afterShellExecution
• beforeMCPExecution afterMCPExecution
• beforeReadFile afterFileEdit
• beforeSubmitPrompt preCompact stop
• afterAgentResponse afterAgentThought

There are also Tab hooks:

• beforeTabFileRead
• afterTabFileEdit

App lifecycle hooks:

• workspaceOpen

Hooks are command-type and can carry a matcher filter.

Official wording: {"command": "./hooks/audit.sh"}

The official page also offers a TypeScript variant (Bun-powered), for structured I/O and HTTP.

上下文与记忆Context & memory

「项目」的核心设计是长期上下文维持。

官方原文说它能做三件事：

• 在长达数月的工作中持续保持上下文
• 把任务委派给成千上万个子智能体
• 无需提示就自动执行周期性工作

共享上下文会在多个云端与本地机器间同步。 一个智能体摸清某服务怎么测之后，后续智能体可以直接复用。

The core design of "Projects" is long-lived context maintenance.

The official wording says it does three things:

• Keeps context across work lasting months
• Delegates tasks to thousands of subagents
• Runs periodic work automatically, without prompts

Shared context syncs across multiple cloud and local machines. Once one agent figures out how to test a service, later agents can reuse it directly.

权限与限制Permissions & limits

安全审查是一个 bot，而且分成两个职责。

Security Review 管可利用的缺陷：

• 结合全库上下文读每个 PR
• 报告可被利用的缺陷
• 每项标明严重级别、攻击路径与修复建议

检查项包括注入、认证绕过、密钥提交、SSRF、不安全反序列化， 以及引入已知漏洞的依赖变更。

代码风格与质量问题仍由 Bugbot 负责。

还可以为仓库添加规则，Security Review 会在每个 PR 强制执行。 例如外部调用必须走哪个客户端、哪些表不能在请求处理程序里查。

草稿 PR 会被跳过。

The security review is a bot, split into two responsibilities.

Security Review covers exploitable flaws:

• Reads each PR with whole-repo context
• Reports exploitable flaws
• Each finding carries a severity, an attack path and a fix suggestion

Checks include injection, auth bypass, secret commits, SSRF, unsafe deserialization, and dependency changes that introduce known vulnerabilities.

Code style and quality issues remain Bugbot's job.

You can also add per-repo rules that Security Review enforces on every PR. For example, which client external calls must go through, or which tables may not be queried in request handlers.

Draft PRs are skipped.

适合什么任务Best for

适合三类人：

• 需要云端 Agent、希望合上笔记本任务继续跑的人
• 需要长周期（数月级）上下文维持与大规模子智能体编排的人
• 代码不能离开自有基础设施的企业（自托管形态）

Free 档适合想低成本试智能体的人：有限额度 + Composer 访问。

Good fit for three kinds of people:

• People who need cloud agents and want tasks to keep running with the laptop closed
• People who need long-horizon (months-scale) context maintenance and large-scale subagent orchestration
• Enterprises whose code cannot leave their own infrastructure (the self-hosted mode)

The Free tier suits people who want to try agents at low cost: limited allowance + Composer access.

项目规则：只改 src/ 下文件；不改 CI 配置；新增依赖前先问我。
任务：【bug 描述】。先给计划，再改代码。

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.