Cursor Agent 如何工作

Cursor Agent 的稳定性来自结构，不是来自"模型更聪明"这一句话。官方 Agent 文档把它拆成三部分：instructions、tools、model。你写的任务、项目 rules、可用工具、模型选择和验证方式，会共同决定 Agent 的行为边界。

本章目标：你会知道 Agent 为什么能跨文件完成任务，也会知道它什么时候容易失控，以及如何用 Ask、Agent、Plan、Debug、checkpoints 和 diff review 把风险压住。

1. Agent 的三件套

Agent 每次工作都在组合三类输入：

Instructions：system prompt（系统提示词，模型每次推理前看到的隐性指令）、rules、用户 prompt 和当前任务边界。
Tools：读文件、改文件、搜索代码库、运行 terminal、使用 browser、web search、MCP 等能力。
Model：承担推理和生成的模型，不同任务适合不同复杂度和成本。

flowchart TD
  Task["User Task"] --> Agent["Cursor Agent"]
  Agent --> Instructions["Instructions / Rules"]
  Agent --> Tools["Tools"]
  Agent --> Model["Model"]
  Tools --> Read["Read Files"]
  Tools --> Edit["Edit Files"]
  Tools --> Terminal["Run Shell Commands"]
  Tools --> Browser["Browser"]
  Tools --> MCP["MCP Servers"]
  Edit --> Diff["Diff"]
  Terminal --> Logs["Command Output"]
  Browser --> Evidence["Visual Evidence"]

只要其中一项不清楚，Agent 就会不稳定。例如 prompt 没有范围，tools 权限太宽，model 选得过轻，或者项目 rules 互相冲突，都会让同一个任务出现完全不同的结果。

官方 Agent 文档列出多类 tools，包括 semantic search（语义搜索，按含义而不是关键字找代码）、file search（按文件名 / 目录结构搜索）、web（生成搜索查询并搜网）、fetch rules（按需调取项目 rule）、read files（读文件，含图片）、edit files（改文件）、run shell commands（跑命令）、browser（控制浏览器截图 / 点击 / 读 console + network）、image generation（图像生成）和 ask questions（澄清问题）——单次任务里工具调用次数不设上限。

这些 tools 让 Agent 能完成真实开发任务，但也带来副作用：

Read files 会把本地代码、图片和配置送进上下文。
Edit files 会改变 working tree（工作树，git 里你当前看到的文件状态，未提交的改动也算）。
Run shell commands 可能启动服务、安装依赖、删除文件或触发脚本。
Browser 可以访问本地页面和外部页面。
MCP 可以连接数据库、GitHub、文档、任务系统或内部工具。

所以商业级用法不是“默认全开”，而是按任务授权。

安全 prompt 示例：

目标：修复用户列表分页按钮在空数据时仍可点击的问题。
范围：只允许修改 src/components/UserTable.tsx 和相关测试。
工具：可以读取文件，可以运行 pnpm test -- UserTable；不要安装依赖，不要改配置。
流程：先给计划，等我确认后再修改。
验收：输出 diff 摘要、测试结果、未覆盖风险。

这类 prompt 不会让 Agent 更慢，反而会减少误操作和返工。

3. Checkpoints 是撤销机制，不是版本管理

Cursor 会在重要改动前创建 checkpoints，保存 modified files 的状态。Agent 走错时，你可以在 chat timeline 里预览并 restore。

但要记住边界：

Checkpoints 是本地回退点。
它们主要针对 Agent changes。
它们和 Git 分开。
它们不能替代 branch、commit、PR 和 code review。

实操建议：

任务开始前看 Git status。
小任务直接依赖 diff review。
Agent 改偏时先看 checkpoint preview。
重要工作仍然用 Git branch 和 commit 固化。

不要因为有 checkpoint 就批准大范围修改。checkpoint 适合撤错方向，不适合管理长期版本历史。

4. Queued messages 适合串行，不适合混乱指挥

官方文档说明，Agent 工作时可以把后续 messages 加入 queue；也可以用 Cmd+Enter 立即发送，追加到最近 user message。

推荐用法：

Enter 排队：当前任务还在跑、下一步很明确、不需要打断当前工作时用。
Cmd / Ctrl + Enter 立即发送：Agent 已经偏离方向、需要立即重定向时用——消息会附在最近一条 user message 后立即进入推理。
不要连续 queue 多条互相矛盾的要求。
不要在 Agent 正改文件时不断追加"顺便再改"。

队列让长任务更顺，但它不是项目管理系统。范围变大时，应停下来重新定义任务。

5. 四种模式怎么选

Cursor Help Center 把常见 AI modes 分成 Agent、Ask、Plan、Debug。理解模式比记住快捷键更重要。

Ask：只读理解代码、解释架构、找入口、评估风险。默认不改文件。
Agent：执行小到中等任务，适合有明确目标和验证方式的改动。
Plan：复杂任务先给方案，适合跨模块功能、重构、迁移。
Debug：需要运行时证据的 bug，适合日志、复现、断点、浏览器和终端配合。

切换模式可以用 mode picker，也可以用 Shift + Tab。官方提醒不同 mode 有自己的 context，换任务时最好开新 chat。

6. 判断 Agent 是否健康

健康的 Agent 通常有这些迹象：

先读相关文件，而不是立刻改。
能说明为什么这些文件是入口。
计划里写清楚改动范围和验证方式。
每次修改范围可审查。
会运行目标检查，并报告失败原因。
总结和真实 diff 一致。

不健康的迹象：

没看代码就给大方案。
自动扩大范围，修改无关文件。
遇到测试失败就跳过或改测试迎合实现。
用“应该没问题”替代验证。
总结说修好了，但 diff 和命令输出对不上。

7. 推荐第一条 Agent 指令模板

可以把这个模板作为起点：

你在一个已有 Git 项目里工作。先只读分析，不要修改文件。

任务：
[写清楚要解决的问题]

请先输出：
1. 你需要读取哪些文件
2. 初步根因或实现路径
3. 最小修改范围
4. 需要运行的验证命令
5. 风险和停止条件

等我确认计划后再执行。

这条模板的重点不是格式，而是权限分离：先理解，再计划，再批准，再写入，再验证。

官方来源

Cursor Agent Overview：官方说明 Agent 的 instructions、tools、model、checkpoints 和 queued messages。
Cursor Agent Help：Help Center 对 Agent、Ask、Plan、Debug、Restore Checkpoint 和模式切换的说明。
Cursor Documentation Index：官方 Agent、tools、Help Center 和 CLI 索引。

接下来去哪

先完成安装、迁移和第一个低风险项目闭环。

理解 Agent、Plan、Ask、Debug 和 Tab 的分工。

官方 Agent 总览

回到官方重组页查看 Agent 组件、tools 和 checkpoints。