Composer 与 Agent · Cursor 橙皮书

一、Ask / Manual / Agent —— 三种模式的本质区别

进入 Cursor 3 之后，原本独立的 Chat 和 Composer 在界面上合并成了"一个对话窗"，但是有三种不同的运行模式：

模式	它能做什么	它不做什么	适合
Ask	看你的项目 + 回答	不改文件 / 不跑命令	提问、讨论、debug 思路、读代码
Manual	看 + 改你"明确点选"的文件	不主动改 / 不跑命令	只想改一两个文件，不想 AI 自由发挥
Agent	看 + 改 + 跑命令 + 看浏览器 + 自己迭代	完全不限制	做一件完整的事

它们的"自由度"从左到右递增：

Ask           Manual         Agent
─────────────────────────────────────
最保守         中间           最自由
"你只能说"   "我指哪你打哪"  "你随便折腾，做完告诉我"

1.1 怎么切换

在 Composer / Chat 输入框上方，有一个下拉菜单，写着 Agent / Ask / Manual。点开切换。

默认应该是 Agent。它最强大，也最常用。下面我们整章默认在 Agent 模式下讲。

1.2 三种模式分别什么时候用

新手入门 / 第一次跑某个新项目 → 先 Ask 问问，再 Manual 小改，最后 Agent 大动。
重要项目（生产代码） → Manual 最稳，每一步都看着办。
个人项目 / 实验项目 → Agent 起飞，让它自己折腾，错了 Git 回滚就行。
本书后面所有的"实战" → 全部默认 Agent 模式。

二、Agent 模式的"超能力"

Agent 模式打开后，Cursor 多出了哪些"普通对话"做不到的能力？

2.1 跨文件改动

你说"把所有用到 userName 的地方改成 userId"，它会搜索整个项目，把每个文件里的相关代码统一改掉。

2.2 自己跑命令

你说"装一下 lodash"，它在 Cursor 内置终端里执行 npm install lodash，不用你打开终端敲。

2.3 自己装依赖

你说"用 react-query 重写这块的数据请求"，它会先确认你装没装 react-query，没装的话先装，再改代码。

2.4 自己看浏览器

你做了一个网页，让 Agent 跑一下试试，它会自己打开浏览器，截图，看截图，发现问题自己改。

2.5 自己写测试 + 自己跑测试

你说"加个测试覆盖这个函数"，它写完测试 → 跑测试 → 跑挂了 → 自己改函数 → 再跑 → 通过。

2.6 自己看错误日志

跑命令报错了，它直接读错误日志，分析原因，改代码，再跑。

2.7 自己用搜索引擎

遇到不知道的 API 用法，它自己调 @Web 去搜，再写。

2.8 自己规划任务

复杂任务它会自己拆成小步骤（"先做 1，再做 2，再做 3"），每完成一步勾选一下。

这 8 个超能力组合起来，就是真正的"AI 工程师同事"。

三、Agent 工作时你能看到什么

当 Agent 接到一个任务，它的工作过程是完全透明的。你能看到：

┌──────────────────────────────────────┐
│  [思考] 我需要先理解项目结构...        │
│  [工具] read_file: package.json        │
│  [思考] 这是一个 Vite + React 项目     │
│  [工具] list_dir: src/                 │
│  [思考] 我要在 src/components 里加...  │
│  [工具] write_file: PomodoroTimer.tsx  │
│         (正在写...)                    │
│  [工具] run_terminal: npm install      │
│  [输出] added 142 packages...          │
│  [工具] run_terminal: npm run dev      │
│  [输出] Local: http://localhost:5173   │
│  [工具] open_browser: localhost:5173   │
│  [思考] 看起来按钮位置不对，我修一下..│
│  [工具] edit_file: PomodoroTimer.tsx   │
│  [完成] 番茄钟已经能用了，请你打开预览│
└──────────────────────────────────────┘

每一步你都能：

暂停：点暂停按钮，让 Agent 先停下。
打断：点 Stop 按钮，立刻停止当前任务。
回到任意一步：每一步都是一个 Checkpoint，可以"回到这里"。
看 Diff：Agent 改的每一个文件都会显示 diff，你可以看清楚改了什么。
拒绝某个改动：单独 Reject 某个文件的修改。

这种"透明 + 可控"是 Agent 真正能让普通人放心用的原因。

四、让 AI 看到"整个项目"的两种方式

Agent 模式的 AI 不是"自动看到所有文件"——它会主动去搜它认为相关的文件。但是有两种方式能让它"看得更全面"：

4.1 索引（Indexing）

打开任何一个文件夹，Cursor 会自动在后台对项目做"索引"——把所有文件的内容算成一个语义向量数据库（你可以理解为"语义级的目录"）。

之后 AI 问"项目里登录逻辑在哪"，它通过语义搜索能秒级定位。

怎么看索引状态：

左下角状态栏会显示 Indexing 87% 之类的进度。
100% 后，你的项目"全文+语义"都被 AI 知道了。

索引是私密的：

索引只存在你电脑上，不上传 Cursor 服务器。
你可以在「设置 → Features → Codebase Indexing」里关闭它。

4.2 主动 @ 投喂

即使有索引，Agent 不一定每次都去搜。你主动 @File / @Folder 仍然是最稳的方式。

@README.md @src/auth/ @src/api/login.ts

把 README + auth 文件夹 + 登录 API 全部明确投喂，Agent 会优先参考这些。

五、第一个项目：番茄钟（30 分钟）

下面我们用 Agent 模式从零做一个真东西——一个有声音、能记录、能统计、能上线的番茄钟。

5.1 番茄钟是什么

番茄工作法：25 分钟专注 + 5 分钟休息为一个"番茄"，4 个番茄后长休 15 分钟。我们要做的网页：

一个大圆盘，倒计时显示。
一键开始 / 暂停 / 重置。
计时结束响铃。
自动切换"工作 / 休息"模式。
记录今天完成了几个番茄。
历史记录可视化（按天柱状图）。
深色模式。
数据保存在浏览器本地（localStorage），关浏览器再开还在。

听起来不少功能。我们看 Cursor 多久能做完。

5.2 准备

步骤 1：在桌面新建文件夹 pomodoro-timer，命名为英文。

步骤 2：在 Cursor 里「文件 → 打开文件夹」选这个文件夹。

步骤 3：按 Cmd+I 打开 Composer，确认右上角是 Agent 模式，模型选 composer-2 或 claude-4.6-sonnet。

5.3 第一轮：让 AI 出方案（Plan）

不要直接说"做一个番茄钟"。先让它给方案。

把下面的提示词复制进去：

我要做一个番茄钟 web 应用。需求：

1. 一个大圆盘，倒计时显示当前剩余分钟和秒。
2. 一键开始 / 暂停 / 重置三个按钮。
3. 计时结束响铃（用 Web Audio API 合成提示音，不引入外部音频文件）。
4. 工作 25 分钟 / 短休 5 分钟 / 长休 15 分钟（4 个工作番茄后进入长休）。
5. 自动切换工作 / 休息阶段。
6. 记录今天完成的番茄数（顶部显示 "今日 X 个" 徽章）。
7. 历史 7 天柱状图（用 SVG 自己画，不引入图表库）。
8. 深色模式（点右上角图标切换，记忆设置）。
9. 所有数据用 localStorage 持久化。

技术约束：
- 一个 index.html + 一个 style.css + 一个 app.js，纯前端。
- 不引入任何外部库 / npm 依赖（不用 React / Vue）。
- 用语义化 HTML，无障碍属性齐全。
- 中文界面。

在动手写代码之前，请先列出：
A. 你打算把这些功能拆成哪些模块？
B. localStorage 的数据结构怎么设计？
C. 计时器的核心算法（避免 setInterval 漂移的方案）？

等我说"开始动手"再写代码。

按回车。

Agent 会只回答（因为你说了"等我说开始动手"），给你一份方案。看一眼，方案应该长这样：

A. 模块拆分
   - timer.js / timerLogic   计时核心
   - storage.js / pomodoroStore  数据持久化
   - audio.js / playBell  提示音
   - chart.js / renderHistoryChart  柱状图
   - ui.js / renderUI  视图

B. 数据结构
   - localStorage key: "pomodoro:v1"
   - 值: {
       phase: "work" | "shortBreak" | "longBreak",
       cycleCount: 当前番茄数（用于触发长休）,
       theme: "light" | "dark",
       history: [{ date: "2026-04-19", count: 7 }]
     }

C. 计时器算法
   - 使用 Date.now() 计算实际经过时间，避免 setInterval 漂移
   - 每 200ms 更新一次显示

如果方案合理，回复"开始动手"。如果某处不满意，先改方案再开始。

5.4 第二轮：开始动手（Act）

回复：

方案不错。一处微调：
- 短休改成 5 分钟，但是用户可以自定义（在右上角设置面板里）。
- 长休 15 分钟，也可以自定义。
- 工作 25 分钟，也可以自定义。
- 设置面板用一个齿轮图标打开。
- 把所有界面文字、提示音 README 等都中文化。

现在开始动手。完成后告诉我怎么打开预览。

回车。Agent 开始写代码：

创建 index.html，写入页面骨架。
创建 style.css，写入样式。
创建 app.js，写入逻辑。
跑 python3 -m http.server 8000 起一个本地服务器（或 Cursor 的内置预览）。
在内置浏览器打开 http://localhost:8000，看效果。
截图自己看，发现问题自己修。

整个过程你只需要看着。大约 3-8 分钟。

5.5 第三轮：验收 + 微调

打开你电脑上的 pomodoro-timer/index.html，双击它（或者 localhost:8000）。试一试每个按钮。

99% 概率会有 1-3 个小问题，比如：

字体太小。
圆盘进度环走得不对（顺时针 vs 逆时针）。
深色模式切换后柱状图颜色看不见。

把每个问题列出来回到 Composer 一并讲：

我打开预览了，有几个问题：

1. 圆盘进度环现在是逆时针的，请改成顺时针，从 12 点位置开始。
2. 深色模式下柱状图柱子完全看不见，请用浅色填充。
3. 设置面板打开后没有"保存"按钮，请加一个，点击后立即生效。
4. 按钮文字"start / pause / reset"请改成中文"开始 / 暂停 / 重置"。
5. 番茄完成后的响铃声音太刺耳，请改成柔和的两声"叮"。

请直接修改对应文件。

Agent 会一一修复。再刷新预览，应该就完美了。

5.6 第四轮：加点高级感

做一个 MVP 是不够的。我们再加点惊喜：

请再加几个升级：

1. 圆盘外面加一个进度环，根据剩余时间填充。
2. 工作模式 / 休息模式各一种主色（工作=番茄红 #e74c3c，休息=薄荷绿 #2ecc71）。
3. 浏览器标签页 title 实时显示剩余时间，比如"⏱ 12:34 - 工作中"。
4. 桌面通知（用 Notification API），番茄结束时弹出系统通知。
5. PWA 支持（让用户能"添加到主屏"，离线也能用）。
6. 键盘快捷键：空格=开始/暂停，R=重置，D=切换深色。

回车。

10 分钟后，你的番茄钟变成了一个真正能用的小产品。

5.7 第五轮：上线（提前预告）

如果你想立刻把这东西发出去给朋友看，跳到第十一章，跟着做"Vercel 一键部署"。10 分钟后你能拿到一个 pomodoro-xxx.vercel.app 链接发朋友圈。

或者等下面的章节我们再系统讲。

5.8 整个过程你做了什么

让我们回看一下。整个番茄钟项目你做了：

不到 30 分钟时间。
4-5 段中文提示词。
0 行代码。

但它包含的"技术含量"是：

一个完整的前端项目（HTML + CSS + JS 三个文件，约 800 行）。
用 Web Audio API 合成提示音。
用 SVG 手画柱状图。
localStorage 持久化。
主题切换 + 持久化偏好。
进度环 SVG 动画。
桌面通知 API。
PWA 离线支持。
浏览器标签页动态 title。
键盘快捷键。

如果你雇一个外包做这个项目，市场价大约 1500-3000 元、3-5 天工期。

六、Agent 工作中的 6 个常见操作

6.1 看 Diff 选择性接受

Agent 改完文件，会在 Composer 历史里展开 diff 视图。你可以：

点 ✓「Accept all」全部接受。
点 ✗「Reject all」全部拒绝。
在 diff 里逐行点接受 / 拒绝。

6.2 让 Agent 暂停

Agent 跑长任务时（比如装很多依赖），你可以：

点输入框右侧"暂停"图标，让它在当前步骤完成后停下。
点"Stop"按钮，立刻硬停。

6.3 让 Agent 重新跑某一步

如果 Agent 跑完后某一步效果不满意，你不必"全部回滚"。可以：

在历史里找到那一条消息。
点"Restore Checkpoint"，回到那一刻的代码状态。
修改你的指令，让它"重做这一段"。

6.4 让 Agent 跑测试

你可以专门让 Agent 写测试 + 跑测试：

@File src/timer.js
为这个文件写一个 vitest 测试，覆盖率达到 80%。
然后跑测试，确保全部通过。

它会自己 npm install vitest → 写测试 → 跑 → 改 → 跑通过。

6.5 让 Agent 看浏览器

请你打开浏览器看一下 http://localhost:5173 的登录页面，
告诉我视觉上有什么问题，并直接修复。

它会调用内置浏览器工具，截图，分析，修复。

6.6 让 Agent 用 @Web 查最新文档

@Web Stripe Checkout 最新版本怎么用？
按照最新文档帮我加一个支付按钮。

它会上网搜，确认 API，再写代码。

七、Composer 的 5 个隐藏快捷键

快捷键	功能
`Cmd+I`	打开 Composer / Agents Window
`Cmd+Enter`	提交当前提示词
`Cmd+Shift+Enter`	提交并打开新对话
`Cmd+/`	把当前选中代码"快速发到 Composer"
`Cmd+\`	在 Composer 历史里前后切换会话

记住前两个就够了。

八、Plan 模式 vs Act 模式（Cursor 3 的新玩法）

Cursor 3 之后，Composer 顶部多了一个开关：Plan / Act。

Plan 模式：AI 只规划，不动手。它会给你一份 todo 列表，你确认后再切到 Act 执行。
Act 模式：AI 直接动手，边规划边做。

什么时候用 Plan？

任务复杂、不确定 AI 思路对不对。
改的是生产代码，不能错。
你想让 AI 教你"它打算怎么做"，作为学习。

什么时候用 Act？

小任务，浪费时间在 plan 上不值。
个人项目，错了 Git 回退就行。
你已经很清楚自己要什么。

我们后面的第五章会更深入讲 Plan→Act 心法。

九、Agent 容易翻车的 5 个场景

Agent 不是万能的。它在这些场景容易翻车，需要你额外小心：

翻车 1：动你不希望它动的东西

比如它"自作主张"装了一个新依赖、删了一个旧文件。对策：

用 .gitignore 之外，再加 .cursorignore（参考第六章）。
在提示词里明确"只改 X 文件，不要动其他文件"。

翻车 2：在错误的方向上越走越远

你看 Agent 跑了 5 分钟，发现它根本理解错了你的意图。对策：

不要等它跑完才看，前 30 秒就介入。
复杂任务先 Plan，确认方向再 Act。

翻车 3：跑出来的代码"能跑但不对"

比如它把 >= 写成 >，结果业务逻辑错了。对策：

让 Agent 写测试覆盖。
自己花 5 分钟看 diff（看不懂代码也要看大致改了什么）。

翻车 4：依赖装错了 / 装老了

Agent 有时会装一个老版本的库，导致和你项目冲突。对策：

在 package.json 里固定版本（用 ^ 谨慎）。
出错了让 Agent "卸载，再装最新"。

翻车 5：耗费大量 Token / 钱

Agent 一次任务可能耗 50 万 token，钱就没了。对策：

关注左下角"用量"图标。
不要在大项目里跑"重写整个 X 模块"这种任务。
第十二章会教成本控制。

十、Agent 模式的 7 条心法

写在最后，是真的过来人的总结：

先 Plan 后 Act：复杂任务不要一上来 Act。
先小后大：每次只让它改一两个文件，看效果，再放手。
先 Git 后改：所有大改之前，先 git commit -m "before AI"。
看 Diff 不是浪费时间：你看不懂代码没关系，看"它改了几个文件、改了哪些区域"也是有用的。
打断比让它跑完更有价值：第一句不对就停，比让它跑完再回滚成本低 10 倍。
复杂任务给好上下文：相关文件、相关文档、约束条件、示例输出，越多越好。
让 Agent 自己测试：写代码 + 写测试 + 跑测试 + 自己改，是 Agent 模式最值得养成的习惯。

本章一图回顾

Composer 三种模式
═══════════════════════════════════════════════
  Ask              Manual           Agent
  ─────            ──────           ─────
  只问不改         指哪打哪         自由发挥
  最保守           中间             最自由

Agent 8 大超能力
─────────────
  跨文件改 / 跑命令 / 装依赖 / 看浏览器
  写测试 / 看错误 / 用搜索 / 自己规划

让 AI 看到项目
─────────────
  ① 自动索引（左下角看进度）
  ② 主动 @ 投喂

第一个项目：番茄钟
─────────────
  Plan  →  Act  →  验收  →  微调  →  升级
   ↑                                    ↓
  方案                                30 分钟做好

7 条 Agent 心法
─────────────
  1. 先 Plan 后 Act
  2. 先小后大
  3. 先 Git 后改
  4. 看 Diff 不浪费
  5. 打断 > 跑完
  6. 给好上下文
  7. 让 Agent 自己测

下章预告

接下来第五章学会和 AI 对话，我们专门讲"提示词功夫"——为什么有些人写一句话 AI 就懂，有些人写一段话 AI 还跑偏？提示词五要素、Plan→Act 心法、模型选型矩阵，这章帮你把"和 AI 沟通"变成一种系统能力。