Appearance
Cursor Agent 是 Cursor 的 AI 自主编程核心，通过 Cmd+I 打开，能独立完成复杂编码任务：搜索整个代码库、编辑多个文件、执行终端命令、控制浏览器。本文是官方 Agent Overview 的中文改写，介绍 Agent 工作原理（指令 + 工具 + 模型三层架构）、全部可用工具、Checkpoints 快照功能和消息队列机制，帮助你充分利用 Cursor Agent。
Cursor Agent：AI 自主编程助手完整指南
Cursor Agent 是 Cursor 的 AI 编程核心——不是简单的代码补全，而是能完整理解你的项目、多文件协同编辑、执行终端命令，自主完成复杂编程任务。通过 Cmd+I（macOS）或 Ctrl+I（Windows）打开。
Agent 的工作原理
每个 Agent 任务由三个组件驱动：
- 指令（Instructions）：系统提示和
.cursorrules文件中定义的行为规则 - 工具（Tools）：文件编辑、代码库搜索、终端执行、网页搜索等
- 模型（Model）：你选择的 AI 模型
Cursor 会针对每个支持的模型优化工具的组合方式，你只需关注代码任务本身，不用手动调模型参数。
可用工具
Agent 可以使用以下工具，且没有调用次数上限：
| 工具 | 功能 |
|---|---|
| 语义搜索 | 在已索引代码库里按语义（不是精确关键词）搜索代码 |
| 文件/目录搜索 | 按文件名查找、读取目录结构、精确字符串搜索 |
| Web 搜索 | 生成搜索词并执行网络搜索 |
| 读文件 | 读取文件内容，支持图片（png/jpg/gif/webp/svg）和视觉分析 |
| 编辑文件 | 建议并自动应用文件改动 |
| 运行终端命令 | 执行 shell 命令并监控输出 |
| 浏览器 | 截图、测试应用、验证 UI 效果（详见浏览器文档） |
| 生成图片 | 根据文字描述生成图片，自动保存到 assets/ |
| 提问 | 任务中途向你询问，等你回答的同时继续执行其他操作 |
与 Claude Code 的对比：Claude Code 的工具机制类似，但 Cursor Agent 在 IDE 内深度集成，能直接看到 diff 并通过 Checkpoints 安全回滚。
Checkpoints：任意回滚
Agent 在执行大改动前会自动创建 Checkpoints（快照），记录所有被修改文件的当前状态。
使用方式：
- 在聊天记录时间线上点击任意 Checkpoint，预览该时刻的文件状态
- 点击"Restore Checkpoint"恢复到该版本，撤销之后所有改动
- 也可以在悬停消息时点击
+按钮手动创建
注意事项：
- Checkpoints 存在本地，与 Git 独立，不影响 Git 历史
- 只用来撤销 Agent 操作，长期版本管理还是用 Git
- 对于探索性工作、复杂重构特别有用
消息队列：一边等 Agent 一边排队
Agent 工作时不用等它完成才输入下一条指令——可以提前排队：
- Agent 执行中，直接在输入框输入下一条指令
- 按
Enter加入队列（不会立刻发送） - 队列里的消息按顺序显示，可拖拽调整顺序
- Agent 完成当前任务后自动处理队列
键盘快捷键：
Enter：加入队列（等 Agent 完成后执行）Cmd+Enter：立即发送（插入当前工具结果后，不等队列）
快速开始
- 打开 Cursor，
Cmd+I打开 Agent - 输入你的任务（用中文或英文都行）
- Agent 会搜索代码库、读取相关文件，开始执行
- 执行中可以继续排队下一条指令
常见问题
Q: Cursor Agent 和 GitHub Copilot 有什么区别？
Copilot 主要做光标处的代码补全，只看当前文件。Cursor Agent 能理解整个项目，跨文件读写、执行终端命令，完成端到端的多步骤任务。
Q: Agent 执行后我发现方向错了，怎么快速撤销？
直接在聊天记录里点击 Checkpoint 回滚到改动前的状态。比手动 git revert 快很多，适合探索性的 AI 编程工作流。
Q: 终端命令执行需要我每次确认吗？
默认每次都需要手动批准。可以在设置里配置 allow list 预先批准特定命令，但不建议开启"全部自动执行"——存在安全风险。