---
title: "Cursor Agent 如何工作"
description: "理解 instructions、tools、model、checkpoints、queued messages 和模式选择。"
verifiedAt: "2026-05-09"
---

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

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

## 1. Agent 的三件套

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

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

```mermaid
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 互相冲突，都会让同一个任务出现完全不同的结果。

## 2. Tools 是能力，也是副作用入口

官方 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 示例：

```text
目标：修复用户列表分页按钮在空数据时仍可点击的问题。
范围：只允许修改 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。

实操建议：

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

> [!IMPORTANT]
> 不要因为有 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 指令模板

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

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

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

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

等我确认计划后再执行。
```

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

## 官方来源

- [Cursor Agent Overview](https://cursor.com/docs/agent/overview.md)：官方说明 Agent 的 instructions、tools、model、checkpoints 和 queued messages。
- [Cursor Agent Help](https://cursor.com/help/ai-features/agent.md)：Help Center 对 Agent、Ask、Plan、Debug、Restore Checkpoint 和模式切换的说明。
- [Cursor Documentation Index](https://cursor.com/llms.txt)：官方 Agent、tools、Help Center 和 CLI 索引。

## 接下来去哪

<Cards>
  <Card title="上一篇" description="先完成安装、迁移和第一个低风险项目闭环。" href="/docs/cursor/understanding/02-install-migrate-first-project" />
  <Card title="下一篇" description="理解 Agent、Plan、Ask、Debug 和 Tab 的分工。" href="/docs/cursor/understanding/04-agent-plan-ask-debug-tab" />
  <Card title="官方 Agent 总览" description="回到官方重组页查看 Agent 组件、tools 和 checkpoints。" href="/docs/cursor/official/01-agent-workflow/10-agent-overview" />
</Cards>
