Agent 总览
基于 Cursor 官方 Agent 文档解释 instructions、tools、model、checkpoints、queue 和模式选择。
Cursor Agent 是能独立完成复杂编码任务的助手。官方文档说明，它可以编辑代码、运行 terminal commands、搜索代码库和 web，并围绕不同 frontier models 调整 instructions 和 tools。
学习 Agent 的关键不是“它能不能改代码”，而是理解三件事：它由 instructions、tools、model 组成；它会在任务中调用很多工具；它会用 checkpoints 和 queued messages 支撑更长的迭代。
阅读目标：读完本章，你应该能判断什么时候用 Agent、Ask、Plan、Debug，并知道 Agent 做任务时哪些证据必须审查。
1. Agent 的三个组成部分
官方 Agent 文档把 agent 拆成三部分。
| 组件 | 官方含义 | 你要控制什么 |
|---|---|---|
| Instructions | system prompt（系统提示词，模型每次推理前看到的隐性指令）和 rules，指导 agent 行为 | 项目 rules、团队约束、任务边界 |
| Tools | 文件编辑、代码库搜索、terminal、browser 等 | 哪些工具可用，哪些要人工确认 |
| Model | 你为任务选择的 agent model | 复杂度、成本、上下文和速度 |
Cursor 会为不同模型调整 instructions 和 tools。用户不需要手工适配每个模型，但仍要定义任务边界和验收方式。
flowchart TD
Goal["用户任务"] --> Agent["Cursor Agent"]
Agent --> Instructions["Instructions / Rules"]
Agent --> Tools["Tools"]
Agent --> Model["Model"]
Tools --> Search["Codebase / Web search"]
Tools --> Edit["Read / Edit files"]
Tools --> Terminal["Run shell commands"]
Tools --> Browser["Browser screenshots / tests"]
Edit --> Diff["Diff view"]
Terminal --> Output["Command output"]
Browser --> Evidence["Visual evidence"]2. Tools 是 Agent 的工作手
官方列出的 tools 包括：
| Tool | 用途 |
|---|---|
| Semantic search | 在 indexed codebase 中按含义搜索 |
| Search files and folders | 找文件名、目录结构、关键词和 pattern |
| Web | 生成搜索查询并执行 web searches |
| Fetch Rules | 根据 type 和 description 获取相关 rules |
| Read files | 读取文本和图片文件，并把图片加入视觉模型上下文 |
| Edit files | 建议并应用文件编辑 |
| Run shell commands | 执行 terminal 命令并监控输出 |
| Browser | 控制浏览器截图、测试应用、验证视觉变化 |
| Image generation | 生成 UI mockup、产品素材或架构图 |
| Ask questions | 任务中提出澄清问题 |
官方还说明 Agent 一次任务中的 tool calls 没有数量上限。对真实项目来说，这意味着你不能只看最终回复，要看它到底读了什么、改了什么、跑了什么命令。
3. Checkpoints 是本地回退，不是 Git 替代
官方文档说明，Agent 会在重要改动前自动创建 checkpoints，保存 modified files 的状态。如果 Agent 走错，可以在 chat timeline 中点击 checkpoint 预览并 restore。
关键边界：
- Checkpoints 存在本地。
- 它们和 Git 分开。
- 只适合撤销 Agent changes。
- 永久版本管理仍然用 Git。
Checkpoint 能帮你撤回 Agent 的一次错误方向，但不能代替 commit、branch、PR 和 code review。
4. Queued messages 和立即消息
官方文档说明，Agent 工作时可以排队后续指令：
| 操作 | 行为 |
|---|---|
| 输入下一条并按 Enter | 加入 queue，等当前任务完成后顺序执行 |
| 拖动 queued messages | 调整执行顺序 |
Cmd+Enter | 立即发送，绕过 queue，追加到最近 user message |
实操上，排队适合“等当前小步骤结束后继续”。如果 Agent 已经走偏，用 Stop 或立即消息重定向，不要连续塞多个互相冲突的 queued messages。
深读：为什么 Agent 工具越多，任务边界越重要
Cursor Agent 可以搜索、读文件、改文件、跑命令、控浏览器、生成图片和提问。工具越多，它越容易把一个模糊目标扩展成一串副作用动作。
所以商业级 prompt 必须写目标、范围、允许工具、禁止动作和验收证据。比如“只读解释当前目录，不要修改文件”与“修复并运行测试”是完全不同的授权级别。
5. 模式选择
官方 Help Center 给出四种模式判断。
| Mode | Best for | Can edit files |
|---|---|---|
| Agent | 构建功能、重构、修 bug | Yes |
| Ask | 理解代码、探索架构 | No |
| Plan | 复杂功能，先审方案 | Yes，审批后 |
| Debug | 需要运行时证据的疑难 bug | Yes |
切换方式：
Shift + Tab循环模式。- Agent panel 的 mode picker dropdown。
官方提醒：每个 mode 使用自己的 context，切换模式会开启新的 context window；换任务最好开新 chat。
本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
- Cursor Agent 的 instructions、tools、model 各自负责什么？
- Checkpoints 和 Git 的边界是什么？
- Ask、Agent、Plan、Debug 分别适合什么任务？
通过标准：你能给一个真实任务选择模式，并写清楚允许工具、回退方式和验收证据。
官方来源
- Cursor Agent Overview —— 官方说明 Agent 三组件、tools、checkpoints 和 queued messages。
- Cursor Agent Help —— Help Center 说明 Agent mode、Ask / Plan / Debug、Restore Checkpoint 和模式切换。