08 · Composer / Agent 模式

Cmd+I 打开的不是一个编辑器窗口——它是 Cursor 的”自主执行层”，也是整个 Cursor 中最接近”让 AI 独立开发”的形态。理解 Agent 模式，才算真正开始使用 AI 编程助手。

01 什么是 Composer / Agent 模式

当你按下 Cmd+I（Windows: Ctrl+I），Cursor 会在编辑器中打开一个内嵌的对话面板——这就是 Composer。而 Composer 中的Agent 模式（在输入框上方选择 “Agent”），则是 Cursor 最强大、最完整的 AI 能力形态。

先做一个最直白的对比：

简而言之：Agent 模式是 Cursor 的”全栈程序员”。 你给它一个任务描述，它会自己读代码、自己设计方案、自己改文件、自己跑命令验证、自己修 BUG——直到任务完成。

这不是夸大。我们来看一个真实场景：

你说：“帮我给登录页面加一个”忘记密码”功能，发重置邮件到用户邮箱。”

Agent 做了：

1. 读了你项目的认证代码，找到现有登录逻辑
2. 分析了你的数据库 schema，确认用户表有 email 字段
3. 创建了 forgot-password.ts 服务层文件
4. 创建了 reset-password.ts 服务层文件
5. 创建了前端 ForgotPasswordForm.tsx 组件
6. 创建了前端 ResetPasswordForm.tsx 组件
7. 在路由配置中加了两个新页面
8. 在 package.json 里加了 nodemailer（或者你的邮件 SDK）
9. 运行 npm install 安装依赖
10. 创建了一个邮件模板文件

整个过程中，你只需要在最后审查一遍 diff，确认没问题，点一下”接受 All”。十几分钟完成一个以前至少半天才能做完的功能。

这就是 Composer / Agent 模式的威力——它不是帮你写代码，而是替你完成一个完整的开发任务。

02 Agent 模式的「大脑」：它是怎么工作的

要善用 Agent 模式，你需要理解它内部的”工作循环”。Cursor 的 Agent 不是一个”问一句答一句”的简单对话——它有一套完整的自主决策循环。

Agent 工作循环（Agent Loop）

┌─ 用户给出任务描述 ──────────────────────┐
│                                          │
│  Step 1: 理解任务 & 定计划                │
│    ↓                                     │
│  Step 2: 搜索/读取项目代码               │
│    ↓                                     │
│  Step 3: 决定下一步操作（改文件/跑命令）   │
│    ↓                                     │
│  Step 4: 执行操作（写入文件/执行终端命令）  │
│    ↓                                     │
│  Step 5: 检查结果（跑测试/验证）          │
│    ↓                                     │
│  Step 6: 如果出错了 → 分析错误 → 回到 3   │
│    ↓                                     │
│  任务完成 → 输出改动的文件列表和 diff       │
└──────────────────────────────────────────┘

注意 Step 6——Agent 会自动修复自己犯的错误。 这是 Agent 模式区别于 Chat 模式的关键特征。Chat 的 Agent 子模式也有工具调用能力，但 Composer 中的 Agent 模式会持续执行直到任务完成，并且在每一步都给你看到进展和改动。

心智模型：「你把需求说清楚，它自己跑完开发流程」

把 Agent 模式想象成一个新入职、聪明但需要你带的项目成员：

• 你给它讲清楚需求（你的 prompt）
• 它自己去看项目代码熟悉上下文（读文件）
• 它在动手前会先想清楚怎么做（定计划）
• 它一步步改代码、跑命令（执行）
• 它跑完会自己检查有没有编译错误（验证）
• 它出错了会自己看报错信息、自己修（自愈）
• 最后你把改动的 diff 过一遍，确认没问题（review）

最关键的一点：你不是在”指挥一个工具”，而是在”和一个开发搭档合作”。 你的角色从”写代码的人”变成了”审代码的人”。

03 Agent 模式的七种工具

Agent 模式能完成上述工作循环，是因为它背后有七种工具。理解这些工具，你就理解了 Agent 的能力边界：

这七种工具的组合，构成了 Agent 模式的完整能力边界。

背后的模型

Cursor 在 Agent 模式下使用的是经过深度定制的模型。当你选择不同的模型时，Agent 的行为和效率有显著差异：

关键建议：复杂的跨文件功能开发，建议用 claude-sonnet-4-20250514 或 claude-3.7-sonnet-thinking。简单的单文件修改，用 gpt-4o 或 deepseek-v4 会更省 token。

04 用 Checkpoints 和 Agent Review Tab 做安全网

Agent 模式能力再强，也是 AI——会犯错。Cursor 为 Agent 设计了两层安全机制。

第一层：Checkpoints（自动快照）

每次你按下 Cmd+I 启动一个 Composer 会话时，Cursor 会自动给当前工作目录拍一张快照——这就是 Checkpoint。

它的工作原理是：

1. 触发时机：每次你运行一个 Agent 任务时，Cursor 在 Agent 动手改代码之前拍快照
2. 存储位置：本地磁盘，存放在项目目录外的独立位置
3. 持久性：跨会话保留，不会因为你关掉 Cursor 就消失
4. 恢复方式：在任何时候，Open Composer History → 找到对应的 Composer 会话 → 点击 “Restore Checkpoint”

心智模型：Checkpoint 像是一个”DVR 录像机”——它录下了 Agent 动手之前的代码状态。Agent 改坏了？一键倒带，就像什么都没发生过。

第二层：Agent Review Tab（改动审查面板）

当 Agent 完成了所有改动后，Composer 面板会变成一个 Review 界面——这是 Agent 模式独有的：

┌─────────────────────────────────────┐
│  Composer Review                    │
│                                     │
│  ✅ 新建: src/services/email.ts     │
│  ✅ 新建: components/forgot-form.tsx│
│  ✅ 修改: src/routes/auth.ts       │
│  ✅ 修改: package.json             │
│  ✅ 运行: npm install (成功)        │
│                                     │
│  ┌─ diff of src/routes/auth.ts ────┐│
│  │ - import { login } from './auth'││
│  │ + import { login, forgotPass }  ││
│  │ + import { resetPass } from '..'││
│  └─────────────────────────────────┘│
│                                     │
│  [Accept All]  [Accept Selected]  [Reject]│
└─────────────────────────────────────┘

Review 面板的核心价值：

• 能看的：每个文件的改动 diff。
• 能选的：可以逐个文件接受，也可以全量接受/拒绝。一个 Agent 改了 5 个文件，你觉得其中 3 个写得好、2 个有问题——只接受那 3 个的改动，剩下的手动改。
• 能聊的：Review 面板可以继续和 Agent 对话。如果某段改动不满意，直接说”这段改得不对，帮我重写”，Agent 会补充改动。

两层安全网的使用策略

Checkpoint：粗粒度的"大不了重来"
  └── 用在对 Agent 完全没有把握的场景
      └── 不用删代码，随时回去

Review Panel：细粒度的"改动级别控制"
  └── 用在日常 Agent 开发流程中
      └── 用逐文件审查代替全盘接受

05 Agent vs Chat：决策树

在 07 · Chat 模式深度用法 中我已经详细对比了 Chat 和 Composer 的定位。这里用一个更直接的方法来解决”什么时候按哪个”的问题。

核心原则：先判断你现在的状态。

决策树

你现在的大脑状态是什么？
│
├─ 模糊状态："我想加个什么东西，但不确定具体怎么做"
│  └─→ Cmd+L（Chat 模式）：先聊清楚
│       ├─ 聊清楚了 → Cmd+I 去执行
│       └─ 还没聊清楚 → 继续聊
│
├─ 清楚状态："我要做这个功能，方案都想好了"
│  └─→ Cmd+I（Composer Agent）：直接动手
│
├─ 学习状态："我在学这段代码，想知道它怎么工作的"
│  └─→ Cmd+L → Ask 模式：只读问答
│
├─ 修 BUG 状态："这里报错了，帮我查一下"
│  └─→ Cmd+L → Debug 模式：系统诊断
│       └─ 定位到原因了 → Cmd+I 去修复
│
└─ 评估状态："我想改这个，但不知道影响面多大"
   └─→ Cmd+L → Plan 模式：先调研方案
        └─ 方案确认了 → Cmd+I 去执行

对比速查表

记住这篇文章的核心：Cmd+I Agent 模式最适合”任务明确、需要跨多个文件、是一整套功能”的场景。 它不是用来聊天的，是用来干活的。

06 实战演练：完整开发一个功能

纸上谈兵够了，我们来走一个真实的实战。假设你在一个 Next.js 电商项目里，要实现”商品收藏夹（Wishlist）“功能。

Step 0：确认任务

先自我评估：任务明确了吗？确定了——就是加一个”收藏夹”功能。好，直接按 Cmd+I。

Step 1：写 Agent Prompt

在 Composer 输入框中，选择 Agent 模式，然后写：

在现有项目中实现商品收藏夹（Wishlist）功能。

功能要求：
1. 用户可以对商品点"收藏/取消收藏"按钮
2. 有一个 /wishlist 页面展示所有收藏的商品
3. 收藏状态需要持久化到数据库

技术细节：
- 数据库用 Prisma（schema 在 prisma/schema.prisma）
- 前端用 React Server Components
- API 路由在 src/app/api/ 下
- 用户认证用 next-auth

约束：
- 不要改动现有的数据库 migration
- 收藏按钮需要等登录态加载完再显示（不要闪烁）
- 页面要有 loading 态和空状态

写 prompt 的关键原则：

1. 告诉它项目结构 —— Agent 是第一次接触你的项目，告诉它关键文件在哪
2. 明确约束条件 —— 不想让它碰的东西说出来
3. 边界情况要提 —— 你不会希望收藏按钮在用户未登录时显示出错

Step 2：Agent 执行

Agent 收到 prompt 后会：

1. 读 prisma/schema.prisma —— 了解现有数据模型
2. 读 src/app/api/ 下的路由结构 —— 了解 API 风格
3. 读现有的组件 —— 了解 UI 模式
4. 新建/修改文件：
   • prisma/schema.prisma → 加 Wishlist 模型
   • prisma/seed.ts → 也许不动
   • src/app/api/wishlist/route.ts → 新建收藏 API
   • src/components/WishlistButton.tsx → 新建收藏按钮组件
   • src/app/wishlist/page.tsx → 新建收藏夹页面
5. 运行 npx prisma generate → 更新 Prisma Client
6. 运行 npm run build → 检查是否编译通过

整个过程你会看到 Composer 面板里不断滚动输出：

[Read] prisma/schema.prisma
[Read] src/app/api/auth/[...nextauth]/route.ts
[Read] src/components/ProductCard.tsx
[Write] prisma/migrations/wishlist (schema update)
[Write] src/app/api/wishlist/route.ts
[Write] src/components/WishlistButton.tsx
[Write] src/app/wishlist/page.tsx
[Terminal] npx prisma generate
[Terminal] npm run build

最后一个 [Terminal] npm run build 如果输出了 success，Agent 会自信地说”功能已经实现，编译通过”。

Step 3：Review 改动

Agent 停下来后，Composer 面板变成 Review 视图。你会看到每个文件的 diff：

prisma/schema.prisma         [+12 -0]
src/app/api/wishlist/route.ts  [+58 -0]
src/components/WishlistButton.tsx [+89 -0]
src/app/wishlist/page.tsx    [+72 -0]
src/app/layout.tsx           [+1 -0]   (加了 WishlistButton 的导入)

不要直接点 Accept All——逐文件看一遍：

• ✅ schema.prisma：Wishlist 模型加得合理，字段正确 → 接受
• ✅ wishlist/route.ts：API 实现正确，有错误处理 → 接受
• ✅ WishlistButton.tsx：交互方式合理，有 loading 状态 → 接受
• ✅ wishlist/page.tsx：有空状态展示，有 loading 态 → 接受
• ⚠️ layout.tsx：它把 WishlistButton 加在了全局 layout 里——这可能导致收藏按钮出现在所有页面，包括首页。这里需要改：

在 review 面板中直接说：

WishlistButton 不应该在全局 layout 里，它应该只在商品详情页和商品卡片上显示。把 layout.tsx 的改动撤销

Agent 会立刻撤销 layout.tsx 的改动，然后补充说”建议在 ProductCard 组件中手动引入 WishlistButton”。

Step 4：最终确认

改完后，重新编译检查：

[Terminal] npm run build → success

确认没问题 → 点击 Accept All。改动正式写入项目文件。

整个过程回顾

写 prompt（1 分钟）
  → Agent 执行（2-3 分钟）
    → Review（3-5 分钟）
      → 和 Agent 讨论修正（1-2 分钟）
        → Accept（10 秒）

总共：不到 10 分钟，完成一个完整功能。
如果没有 Agent：设计 + 编码 + 测试 = 至少 1-2 小时。

07 Review 工作流：用好 Agent 输出的四种检查方式

Agent 输出的改动，你通过什么方式确认质量？这里总结了四种检查方式，从轻到重：

方式一：肉眼 Review Diff（最常用）

Composer 自带的 Review 面板提供了每个文件的 diff。一个合格的 diff 检查清单：

✅ 代码风格符合项目规范
✅ 没有遗留的 console.log / debug 代码
✅ 变量命名一致
✅ 没有引入不必要的依赖
✅ 新增的 API 接口有错误处理
✅ 前端组件有 loading 和 error 状态
✅ 类型定义正确（TypeScript）

方式二：终端验证

Agent 执行完改动后，让它在终端跑验证：

跑一下测试：npm test -- --testPathPattern=wishlist

或者直接让它在改动后自动跑测试——在 prompt 末尾加一句：

所有改动完成后，跑一次 npm run build 和 npm test，如果有失败就修复。

方式三：本地运行验证

有些改动只有肉眼看到 UI 才能确认：

改成后，帮我启动 dev server，我确认一下 UI

然后在浏览器中实际操作一下收藏功能。发现问题后切回 Composer 输入问题，Agent 会继续修复。

方式四：让 Agent 自检

如果改动比较复杂，可以要求 Agent 在交付前做一次自我检查：

改动完成后，请你逐条检查：
1. 是否有未处理的错误情况
2. 是否所有新增功能都覆盖了边界条件
3. 有没有安全漏洞（SQL 注入、XSS、认证绕过等）
4. 有没有引入了不必要的代码改动

Agent 会认真 review 自己刚写的内容，有时能发现遗漏的问题。

什么时候选 “Accept All”

原则上永远不要全盘接受不经过审查的改动。但对于以下情况，可以快速审查：

• 改动量小（1-2 个文件，几行代码）
• 改动模式很明确（加一个字段、改一段逻辑）
• 你已经很熟悉这个代码区域

如果你的改动涉及 5 个以上文件，或者改到了核心逻辑层——逐文件 review，不要偷懒。

08 好 Agent Prompt 的心法

Agent 模式的效果，有一半取决于你的 prompt 质量。这里总结几条经过大量实战验证的经验：

心法一：给背景，不要只给指令

❌ "给用户表加一个 avatar 字段"

✅ "给用户表（prisma/schema.prisma 中的 User model）加一个 avatar 字段，
    类型为 String，可选，用于存储用户头像 URL。然后在用户注册 API 中
    支持上传头像的逻辑（头像存到 S3，URL 存数据库）。"

Agent 不知道你的项目背景。你认为是”显而易见”的信息，对 AI 来说并不显而易见。

心法二：说清楚”不要做什么”

AI 在不知道边界的情况下会自由发挥。提前说清楚约束：

约束条件：
- 不要修改现有的 migration 文件
- 不要引入新的 npm 包（已有的够用）
- 不要改动核心的认证逻辑
- 不要修改已有的 API 接口签名

心法三：复杂任务拆步骤

如果任务很大，不要让 AI 一次性完成所有事——上下文窗口有限，到后面它会”失忆”。

❌ "实现一个完整的 CMS 系统"（一次说完，Agent 上半段还行，下半段开始胡来）

✅ 分三步：
   Step 1 prompt: "创建 CMS 的数据库模型：文章表、分类表、标签表"
   Step 2 prompt: "基于刚才建好的模型，实现文章 CRUD API"
   Step 3 prompt: "基于 API，实现前端的文章管理页面"

一个实用的基准：如果一个功能需要 8 个以上的文件改动，分两次或三次交给 Agent。

心法四：用自然语言，不要用代码术语硬聊

很多人面对 AI 编程工具时会不自觉地”编程化”——只给代码层面的指令。但 Agent 模式的优势恰恰是你能用自然语言描述意图而不是实现。

❌ "在 ProductCard 组件中加一个 useEffect 调用 GET /api/wishlist/check，参数是 productId"

✅ "商品卡片上要显示"是否已收藏"——收藏过的显示实心爱心，没收藏的显示空心。
    加载状态显示灰色占位。用户点击时切换状态。"

自然语言描述意图，Agent 会自己决定最优的实现方式——它可能用 Server Component 直接查数据库，而不是加一个额外的 API 请求。你给的实现细节越少，Agent 能做出的优化决策就越多。

心法五：给定稿标准

在 prompt 末尾设定”完成标准”：

验收标准：
1. npm run build 编译通过
2. 新增功能不影响已有功能
3. 所有新增的 API 都有错误处理
4. 前端组件在 loading / error / empty 三种状态下都有对应 UI

这样 Agent 会在送审前自动检查这些条件。

09 Agent 模式的边界与局限

再怎么赞美 Agent 模式，它的局限也必须清楚：

10 心智模型总结

整篇文章，可以用几个心智模型来概括：

11 小结

总结成一句话：

Cmd+I Agent 模式是 Cursor 的「终极形态」——它不是帮你写代码的补全工具，而是一个能独立完成完整开发任务的 AI 程序员。你的角色从「写代码的人」变成了「提出需求、审查交付的产品经理」。

下一篇：09 Plan 模式 —— 先想清楚再动手，Plan 模式是 Cursor 给你的”设计阶段”，让你在写代码之前先确认方案。