Composer 模型入门指南

Composer 是 Cursor 自研的前沿智能体编程模型，专门为了一件事而优化：快速完成真实的编程工作。它会制定计划、编辑多个文件、运行终端命令，并以极低的延迟循环调用工具，而成本只是大型前沿模型的一小部分。本指南将说明 Composer 是什么、如何选中它、它在哪些场景表现出色、在哪些场景你仍应选用 Claude 或 GPT 级别的模型，以及如何在日常工作中充分发挥它的价值。

什么是 Composer 模型？

Composer 是 Cursor 团队自建而非从第三方授权的一系列定制模型。它专门针对智能体编程进行训练：阅读你的代码库、制定计划、调用工具、跨文件应用修改并验证结果。与那些为编程而改造的通用聊天模型不同，Composer 从一开始就围绕智能体循环进行了优化。

这一模型系列背后的设计目标是：

• 低延迟：响应启动快，工具调用之间没有很长的停顿，因此「修改—测试」循环感觉是即时的。
• 智能体效率：模型经过调优，能够合理地串联工具调用，而不是要求你事无巨细地管理每一步。
• 价格效率：Composer 的每次请求成本显著低于顶级前沿模型，这对长时间的智能体会话至关重要。
• 实用的推理能力：它足以规划多步骤改动，同时比扩展思考型模型快得多。

在编辑器中它的行为和其他模型一样：你在模型选择器中选中它，它就能驱动 Chat、Agent 模式、行内编辑和后台代理。差异体现在吞吐量上。对于那些前沿模型需要思考一分钟的任务，用 Composer 往往几秒钟就能完成，而其质量对于大多数日常编程工作来说完全够用。

Composer 模型不是 2024 年的 Composer 功能

不要把 Composer 模型与 Cursor 在 2024 年推出的旧版「Composer」多文件编辑功能混为一谈。那个早期工具是一个用于跨多个文件应用改动的 UI 工作流，后来被并入如今的 Agent 模式。本指南讨论的 Composer 是模型本身，与 Claude 和 GPT 从同一个选择器中选中。如果你读到把 Composer 当作独立面板或键盘快捷键的旧教程，它们描述的是已退役的功能，而不是这个模型。

Composer 与第三方模型有何不同

Claude、GPT 和 Gemini 模型是通用的前沿模型，Cursor 通过网络将请求路由到它们。Composer 是另一种东西：由 Cursor 专门为智能体循环打造的模型。即使具体内部实现未公开，这种差异也会体现在行为上。

基础模型血统 vs 路由式前沿模型

当你在 Cursor 中选择第三方模型时，你调用的是一个大型通用模型，它在非常宽泛的数据分布上训练，然后被包在 Cursor 的智能体框架中。当你选择 Composer 时，你调用的是一个从设计目标上就围绕代码库导航、工具使用和快速迭代塑造出来的模型。在实践中这意味着：

• 第三方模型带来巨大的广度与深度推理能力，代价是延迟和每次请求的价格。
• Composer带来速度与低成本，针对编程任务的特定形态而非通用推理基准进行调优。
• 无论哪种，框架都很重要。 Cursor 的工具（文件读取、编辑、终端、搜索）都位于二者之前，因此真正的比较其实是模型在该框架内的行为。

速度与深度的权衡

把它想象成一个在深度与吞吐之间的旋钮，而不是「好」与「坏」的二元对立：

• 偏重深度的模型会在内部花更多时间规划和推理，这在模糊、庞杂的问题上能带来回报。
• 偏重吞吐的模型（如 Composer）会更快行动，做出猜测的频率比其速度所暗示的要低，并且在范围明确的任务上收敛很快。
• 大多数真实工作都是混合的。默认使用偏吞吐的那一端，当任务确实需要深度时再升级。

示例性延迟数据

为了让这种取舍更具体，以下是一些粗略的示例性数字。请把它们视为大概的估计，而不是实测基准，因为延迟在很大程度上取决于任务规模、上下文长度和负载。

场景	Composer（约）	前沿模型（约）
首个有意义的 token	远低于一秒	一秒或更久
一次简短的单文件编辑	几秒	十到三十秒
一个跨多文件、工具密集的任务	几十秒	一到几分钟

这些数字只表示方向，并非承诺

上表中的数字只是为了传达差异的形态：Composer 始终更快，而且在工具密集的循环中差距会拉大。不要把它们的当作精确数值引用；如果精度很重要，请在你自己的工作负载上进行测量。

在模型选择器中选中 Composer

凡是能选择模型的地方都可以使用 Composer：Chat、Agent 模式，以及 Agent 内部 Composer 风格的行内工作流。切换方法：

1. 用常用的面板快捷键打开 Chat 或 Agent 模式。
2. 点击输入框旁边的模型选择器。
3. 在模型列表中找到 Composer。Cursor 的自研模型与第三方模型分组显示。
4. 选中 Composer 这一项，然后像平常一样发送你的提示词。

你还可以在 Settings > Models 中把 Composer 设为默认模型，这样每个新对话都会以它开始。许多开发者把 Composer 作为默认，只在任务确实需要更深推理时手动切换到更重的模型。

Composer 也会出现在后台代理的模型列表中，这使它成为远程任务的天然选择——在这些任务中你无法直接观察延迟，但很关心成本和总耗时。

Composer 可用于哪些场景

场景	如何使用 Composer	典型计费方式
Chat	在模型选择器中选中它	按请求计费，计入你的套餐
Agent 模式	同一个选择器，用于多步骤任务	按请求
Cmd-K / 行内编辑	可用于快速的单点编辑	按请求
后台代理	启动任务时选择 Composer	按请求，会话越长成本越高
Tab 补全	不是选择器选项；Tab 使用自己的模型	计量方式与模型请求不同

按请求计费 vs 按 Token 计费

Cursor 的套餐用量通常按请求计量，而不是纯粹按 token 计量，这就是为什么像 Composer 这种每次请求更便宜的模型，能比其原始 token 价格所暗示的更能拉长套餐的使用寿命。两个实际影响：

• 那些串联大量工具调用的长会话，正是 Composer 优势最大的地方，因为每个额外步骤都相对便宜。
• 如果你习惯用原始 API 的方式思考 token 成本，请记住 Cursor 会把你的用量呈现为套餐消耗量，因此你要关注的数字是套餐计量，而不是金额。

优势与取舍

没有哪个模型能样样第一。以下展示 Composer 与你通常会交替使用的前沿模型相比如何。

能力	Composer	Claude 级别模型	GPT 级别模型
响应延迟	非常快	中等偏慢	中等
每次请求成本	低	高	高到中等
多文件编辑	强，专为此打造	极佳	很好
终端命令熟练度	强	极佳	很好
深度架构推理	良好	极佳	极佳
长时间、模糊的重构	在指令清晰时良好	最佳	很好
快速迭代循环	最佳	中等	中等

规律很清楚：Composer 用一点峰值推理深度换取速度与成本上的大幅提升。对于相当大一部分日常工作——例如实现一个规格明确的组件、修复失败的测试、编写迁移脚本，或用清晰接口重构一个模块——Composer 会在前沿模型刚完成规划之前就把活干完了。

在 Composer 与更大的模型之间做选择

一条实用的经验法则是：默认使用 Composer，当任务显示出需要更深推理的迹象时再升级。以下情况选择 Composer：

• 任务规格明确：你知道涉及哪些文件、要遵循什么模式，以及完成的定义。
• 你正在快速迭代，预期会有几轮小的修改。
• 你在做例行维护：依赖升级、重命名、格式化驱动的重构。
• 你在批量处理许多互不相关的小任务，此时成本会迅速累积。

以下情况选用 Claude 或 GPT 级别的模型：

• 问题模糊，模型必须从庞杂的代码库中推断意图。
• 你需要跨许多相互依赖的模块进行持续推理，例如一项触及客户端、服务端和 schema 层的协议变更。
• 你在调试微妙的并发、内存或正确性问题，猜错代价高昂。
• 你在做架构级设计，此时第一个方案的质量比第一个响应的速度更重要。

在任务中途升级模型，而不是重新开始

如果你用 Composer 开始了一个任务，却发现它原地打转、迟迟不收敛，那么请为下一轮切换模型，而不是新开一个对话。已有的上下文、打开的文件以及目前的计划都会保留，更强的模型可以接着快速模型卡住的地方继续。

面向小型快速模型的提示词技巧

快速模型奖励精确。当你的提示词消除猜测空间时，Composer 的表现会明显更好，因为它不必做的每一次猜测都等于节省了延迟和 token。

遵循以下习惯：

• 一开始就点明文件和目录。 快速模型的规划范围较小，因此立刻把它们指向正确的范围能让它们保持正轨。
• 说明完成的定义。 说明哪些测试应通过、应运行哪条命令，或哪种行为应发生变化。
• 一个提示词只放一个目标。 把多目标请求拆成按顺序的提示词；智能体循环处理一串小目标的能力远好于处理一个庞杂的大目标。
• 锚定到已有的模式。 引用一个已经实现了你想要模式的文件，并要求模型照着它做。
• 限定影响面。 明确指出不要碰什么，例如「不要修改 UserService 的公开 API」。

一个为 Composer 塑造良好的提示词长这样：

In src/services/, add retry logic to the StripeClient class.
Follow the existing retry pattern in src/services/GithubClient.ts
(exponential backoff, max 3 attempts, logs via the shared logger).

Requirements:
- Only src/services/StripeClient.ts and its test file may change.
- Add unit tests mirroring GithubClient.test.ts.
- `npm test -- stripe` must pass when you are done.

Do not modify the public constructor signature.

把它与一个含糊的提示词如「给 Stripe 客户端加上重试」相比。两者最终都能工作，但第一个版本通常一次就能到位，这正是一个为速度优化的模型的用途所在。

为快速模型优化提示词

上面的习惯涵盖了基础；本节更深入地探讨如何塑造快速模型的工作，使它在第一次尝试时就成功。

该做与不该做

该做	不该做
点明确切的文件和目录	让模型在整个仓库里「找到 X 在哪里」
说明完成的定义	让成功标准处于隐含状态
每个提示词只给一个目标	把几个不相关的目标塞进一个提示词
指向一个已有的模式去照搬	只用文字描述一个全新的模式
列出哪些内容不能改变	指望模型自行推断影响面
要求一个验证步骤	跳过测试，凭肉眼信任 diff

好的提示词 vs 差的提示词

含糊的提示词往往产生含糊的修改：

Clean up the auth code and make it better.

范围明确的提示词能给快速模型一次性到位所需的一切：

In src/auth/session.ts, extract the token-refresh logic into a
private method refreshToken() and call it from getSession().

Constraints:
- Only src/auth/session.ts and src/auth/session.test.ts may change.
- Keep the public exports of the module identical.
- Mirror the structure of src/auth/oauth.ts, which already does this.
- `npm test -- auth` must pass.

Report the test output when done.

差异不在于礼貌或长度，而在于模型必须自行做出的决策数量。更少的决策意味着更少的错误转向，而对于一个为速度优化的模型来说，意味着更少的浪费的秒数。

把任务拆解成小步骤

把较大的目标拆成一小段序列，让智能体循环承载每一步：

1. 规划：先要求一份书面计划，在动手修改之前确认它。
2. 实现：每个提示词只处理一个文件或一个模块。
3. 验证：每一步之后运行相关测试或命令。
4. 继续：只有上一步通过后才进入下一步。

给出明确的文件引用

优先使用路径和符号而不是描述。「更新 src/billing/Invoice.ts」胜过「更新发票代码」。当你能做到时，粘贴确切的函数名或一小段可供参照的代码片段，因为这样模型用于搜索的时间会更少，用于编辑的时间会更多。

要求验证

当你把验证变得明确时，快速模型获益最大。在提示词结尾加上一行，例如「运行 npm test -- <scope> 并粘贴输出」，或「报告你运行的确切命令」。这会把智能体的速度转化为可信的进展，而不是未经证实的动作。

用规则固化团队约定

由于 Composer 为速度而优化，它比那些把一切都推理清楚的慢速模型更依赖护栏。把你们的约定放进 .cursor/rules，对快速模型的回报尤其显著。一份简洁的规则文件：

---
description: Service layer conventions for fast model edits
globs:
  - "src/services/**/*.ts"
alwaysApply: false
---

- Follow the client class pattern in src/services/GithubClient.ts.
- All network calls use the shared http client; never import axios directly.
- Every public method needs a unit test in the matching .test.ts file.
- Prefer early returns; keep methods under 40 lines.
- After edits, run `npm test -- <affected-scope>` and report results.

有了这样的规则，你就可以向 Composer 抛出简短的提示词，并相信那些重复性的标准会被强制执行，无需每次都重新声明。

在后台代理中使用 Composer

后台代理会在你处理其他事情时，以远程方式针对你的仓库运行 Cursor 的智能体，并通过 diff 或拉取请求回报。Composer 通常是这方面最好的默认选择，原因有两点：

1. 成本效率。 后台任务往往更长、更具探索性，token 成本会在整个会话中累积。每次请求更便宜的模型能让一队后台代理保持成本可负担。
2. 吞吐量。 当你并行铺开多个后台代理时，每个都提前几分钟完成，会叠加成整体明显更快的工作流。

适合 Composer 的后台任务包括为一个模块补写缺失的测试、在一个包内应用机械式重构、生成文档占位内容，以及修复从问题跟踪器里拉出来的简单问题。对于需要在整个系统范围内做判断的任务，请改用 Claude 或 GPT 级别的模型启动后台代理，或者先在你的前台编辑器里进行规划阶段，再把一份精确的计划交给 Composer。

像写工单一样编写后台提示词

后台代理无法像交互式会话那样在运行中途向你提出澄清性问题。请给它目标、约束、涉及的文件，以及如何验证成功。把这个提示词当作一份小而自包含的工单，Composer 就能很好地运用它的自主性。

Composer 在后台代理中的表现

后台代理正是 Composer 的成本与速度优势叠加的地方，因为你不会坐在那里盯着每一步。要委派得好，需要一点纪律。

委派长时间运行的任务

一个好的委派提示词是自包含且工单式的：

Goal: add unit tests for every public method in src/services/Billing.ts.

Context: follow the testing style in src/services/Billing.test.ts if it
exists; otherwise mirror src/services/GithubClient.test.ts.

Scope: only create or edit test files under src/services/. Do not change
production code. If a method looks untestable as written, note it in the
final summary instead of refactoring.

Verify: `npm test -- services/Billing` must pass. Report the output.

选择范围

• 让一个后台任务只覆盖一个包、一个模块或一个关注点。过宽的任务会跑偏。
• 后台运行优先选择机械式改动：重命名、测试覆盖、文档占位、迁移脚本。
• 避免依赖品味或架构判断的任务；这类任务应在前台会话中开始，以便你随时掌舵。

审查 diff

后台代理会返回一个 diff 或拉取请求，因此要像审查队友的工作那样审查它：

1. 对照你设定的范围检查被触及的文件。任何落在范围之外的内容都是需要更仔细查看的信号。
2. 阅读智能体对其所做工作的总结，然后在代码中至少核实其中一项声明。
3. 在合并之前，在本地运行测试或确认报告的输出。
4. 如果 diff 大体正确但有少量粗糙之处，请在编辑器中修复，而不是重新运行整个代理；重跑可能会改动无关的行。

未经审查的后台 diff 是隐患

由于 Composer 行动很快，它可能迅速产出一个庞大的 diff。产出的速度不等于正确的速度。在你验证测试和范围之前，把每个后台结果都当作提案，并且要为审查安排时间，而不仅仅是运行时间。

成本与用量特征

Composer 是消耗 Cursor 套餐最经济的方式之一。实际影响：

• 与所有事情都用前沿模型相比，你的套餐用量额度能容纳显著更多的智能体请求。
• 长时间的智能体会话会串联大量工具调用，由于每一步成本更低，因此仍然负担得起。
• 快速响应意味着每个会话的总耗时更短，当你进行交互式迭代时，这会间接省钱。

如果你在仪表盘中监控用量，在以 Composer 为默认一周之后你就会清楚地看到差异：相同数量的已完成任务，只占用明显更小的额度比例。一种常见策略是只把前沿模型的额度花在真正能买到推理质量的地方，让 Composer 承担日常的量。

哪些操作会占用你的额度

Chat 和 Agent 请求、Cmd-K 编辑以及后台代理运行都会计入你的套餐，按请求计量。Tab 补全通常单独处理，读取文件或运行命令本身不单独计费；成本由调用它们的模型轮次驱动。

相对成本、速度与质量

下表是一个粗略的近似对比，用于帮你做选择，而不是基准测试。排名可能随模型版本和你的任务组合而变化。

模型	相对速度（约）	相对成本（约）	相对推理深度（约）
Composer	最快	最低	良好
Claude Sonnet	中等	较高	强
Claude Opus	最慢	最高	最强
GPT-family models	中等	高到中等	强
Gemini models	中等偏快	中等	强

请这样理解这张表：「Composer 在速度与成本上胜出；前沿模型在峰值推理上胜出」。大多数团队最终会形成默认使用 Composer、并有意地升级的节奏，而不是反过来。

将 Composer 与其他模型组合使用

最强的工作流不是「永远只选一个模型」，而是把任务的每个阶段路由到适合它的模型。

1. 用推理模型做规划。 先用 Claude 或 GPT 级别的模型，只要求一份计划：要改动哪些文件、按什么顺序、如何验证。此时还不要编辑。
2. 用 Composer 执行。 计划写出来并且你认可之后，把模型切换到 Composer 进行实际修改。一个拥有清晰计划的快速模型，胜过边做边摸索计划的快速模型。
3. 用第二个模型做审查。 修改落地后，切换到另一个模型，让它审查 diff 的正确性、边界情况以及遗漏的需求。一个全新的模型阅读结果时，能发现执行模型自我合理化掉的问题。

Phase 1 (Claude/GPT, plan only):
"Read src/payments/ and propose a step-by-step plan to add idempotency
keys to the charge endpoint. List files, order, and verification. Do not edit."

Phase 2 (Composer, execute):
"Implement step 1 from the plan. Only src/payments/charge.ts may change.
Run `npm test -- payments` and report output."

Phase 3 (second model, review):
"Review this diff for correctness and edge cases. Flag anything that
breaks idempotency under retries."

这个「规划—执行—审查」循环让昂贵的深度推理调用保持少量且集中，同时由 Composer 承担实际编辑的量。

相同的上下文，不同的模型

在任务中途切换模型会保留对话、打开的文件和计划不变，因此阶段之间的交接不需要任何成本。你无需重新解释任务；只要更改选择器然后继续即可。

未来展望：Composer 3

Composer 系列正在积极开发中，社区的路线图讨论里已经充满了对下一代迭代（常被称为 Composer 3）的诉求。这些讨论中反复出现的主题包括更强的长程规划能力、在超大仓库上更好的表现，以及在模糊的多步骤任务上更高的可靠性，同时保持标志性的低延迟和低成本。

你不需要等待这些就能在今天受益。当前的 Composer 模型是生产级的日常主力，而且由于模型选择只是一个下拉选项而非承诺，你现在就可以采用它们，并在新一代模型出现在选择器中时立即切换。

常见问题与局限

Composer 很快，而速度也有其自身的故障模式，你应该尽早识别它们。

进行大范围改动

Composer 可能会尝试一次性完成整个仓库的改动，留下一个庞大且难以审查的 diff。

• 原因：范围不明确的提示词，例如「把各处的日志重构一下」。
• 修复：把改动限制在一个包或模块内，或者把任务拆成一串简短且范围明确的提示词。如果改动确实很宽，先要求一份计划。

在长任务中丢失指令

在长会话中，随着上下文增长，早期的约束可能被稀释。

• 原因：在一个对话里进行许多轮且目标不断变化。
• 修复：当你改变方向时重申关键约束，或者用一个目标与规则的简洁摘要重开一个新对话。.cursor/rules 中的规则文件也有助于在整个会话中钉住约定。

幻觉出的 API

快速模型偶尔会引用不存在的方法或包。

• 原因：模型是从训练数据而非你的代码库做模式匹配。
• 修复：给出明确的文件引用，并要求它对照实际源码进行验证。如果它虚构了一个 API，请指出真实的那一个，并要求它只用仓库中实际存在的符号重做这次编辑。

需要对整个代码库进行重构

有些重构确实横跨整个系统，超出了一个快速模型一次性能处理好的范围。

• 原因：改动具有横切依赖和模糊的边界。
• 修复：先用推理模型做规划，然后以一系列范围明确的 Composer 步骤来执行，并在每一步之后验证。考虑每个包用一个后台代理，而不是一次巨大的运行。

超时或卡住

偶尔一次智能体运行会卡住或超时，尤其是在非常大的任务上。

• 原因：目标过于宽泛、上下文巨大，或某个步骤始终无法完成。
• 修复：缩小任务范围并重试；如果问题反复出现，就把工作拆成更小的步骤，并考虑对那个总是卡住的步骤使用前沿模型。为长时间的后台运行设定范围，让一次卡住只让你损失几分钟而不是一小时。

症状 → 原因 → 修复

症状	可能原因	修复
巨大且无法审查的 diff	范围不明确的提示词	限定范围；要求一份计划并拆成步骤
模型忽略早期约束	长对话中的上下文稀释	重申约束，或重开一个带摘要的新对话
模型调用不存在的方法	基于训练数据的模式匹配	给出文件引用；要求它对照真实符号验证
整个代码库的重构感觉不安全	横切性改动	用推理模型规划，然后以范围明确的步骤执行
运行卡住或超时	任务过宽或上下文过大	缩小并重试；拆成更小的步骤

常见问题解答

Composer 与 2024 年的 Composer 功能是同一个东西吗？

不是。2024 年的「Composer」是 Cursor UI 中的一个多文件编辑工作流，后来被并入 Agent 模式。本指南中的 Composer 是一个模型，与 Claude 和 GPT 从同一个选择器中选中。

Composer 运行在什么模型之上？

Composer 是 Cursor 自研的模型系列，由 Cursor 团队训练，而不是路由到第三方。它的速度与成本特征来自这种专注，而不是来自通用基础模型。

什么时候应该选择 Composer 而不是 Claude 或 GPT？

对于规格明确、快速、迭代式的工作，默认使用 Composer。当任务模糊、跨越许多相互依赖的模块，或需要深度的架构级推理时，再升级。

它对真实的生产工作够好吗？

是的，对于绝大多数日常工作而言：实现规格明确的组件、修复测试、机械式重构以及例行维护。对于高风险的推理，请使用「规划—执行—审查」工作流把它与前沿模型配对使用。

它会额外收费吗？

它是消耗你套餐最便宜的方式之一。由于套餐主要按请求计量，一个每次请求成本低的模型能让更多工作装进你的额度里。

我可以在任务中途切换模型吗？

可以，而且你应该这么做。对话、打开的文件和计划都会保留，因此你可以用推理模型做规划，然后切换到 Composer 执行，而不会丢失上下文。

为什么我的修改会卡住或原地打转？

通常是因为任务对单次执行来说太宽了。缩小范围、给出明确的文件，并在每一步之后验证，而不是指望一个提示词搞定一切。

会有 Composer 3 吗？

社区讨论指向下一代将具备更强的长程规划能力和大仓库表现。你不需要等待；模型选择只是一个下拉选项，因此新版本一出现你就可以采用。

快速参考

问题	答案
什么是 Composer？	Cursor 自研、为速度优化的智能体编程模型
我在哪里选中它？	Chat 和 Agent 模式中的模型选择器，或 Settings > Models
什么时候不该用它？	深度、模糊、架构密集的推理任务
它是旧的 Composer 功能吗？	不是，2024 年的多文件工具已并入 Agent 模式
它在后台代理中能用吗？	能，而且是那里成本效益很高的默认选择
下一步是什么？	社区正在讨论 Composer 3 这一代

Composer 奖励一种简单的工作流：默认用它、写精确的提示词、把你的约定固化到规则里，只在任务确实需要更深推理时才升级到前沿模型。这个习惯能让你获得 Cursor 自研模型系列的速度与成本优势，同时在关键之处不牺牲质量。