Agent 模式：自主完成复杂任务

什么是 Agent 模式

在 AI 领域，Agent（智能体）指能够感知环境、制定计划、采取行动并根据反馈调整策略的 AI 系统，区别于只能"问答"的普通语言模型。

Cursor Agent 模式将 LLM 的推理能力与一系列 工具（Tools）结合：AI 不只是给你看代码建议，而是直接调用工具去做事——读取文件、写入代码、运行测试、搜索代码库，直到任务完成。

Agent vs Ask 模式的本质区别

一个类比

Ask 模式就像请一位专家 出谋划策：他告诉你应该怎么做，但动手的是你自己。 Agent 模式就像雇用一位 全职工程师：你描述需求，他自己找代码、写代码、运行测试，完成后给你看结果。

Agent 的工具箱

Cursor Agent 内置了以下核心工具：

• read_file 读取指定文件的完整内容或部分行范围。Agent 会在需要了解代码时主动调用，比手动 @ 引用更智能（知道需要读什么）。
• edit_file（write_file） 创建新文件或修改现有文件。所有文件修改都以 diff 形式展示，用户可以接受或拒绝，除非开启 Yolo 模式。
• search_codebase 在代码库中进行语义搜索或正则搜索，找到相关代码片段。这是 Agent 自主获取上下文的核心能力。
• run_terminal_command 在集成终端中执行 shell 命令，如运行测试、安装依赖、构建项目、格式化代码。结果反馈给 AI 继续推理。
• list_directory 列出目录结构，帮助 Agent 了解项目组织方式，决定在哪里创建新文件。
• mcp_tool_call 调用 MCP（Model Context Protocol）服务器提供的外部工具，如查询数据库、操作浏览器、调用 API。详见第6章。

工具调用的可见性

在 Agent 执行过程中，Chat 面板会实时展示 AI 的每个工具调用（工具名称 + 参数 + 返回值），你可以全程监控 Agent 在做什么。 展开工具调用条目可以看到完整的输入输出，便于理解 AI 的推理过程。

Yolo 模式：全自动执行

默认情况下，Agent 每次修改文件或执行终端命令都会先展示预览，等待用户确认。 Yolo 模式（Yes to All）打开后，Agent 可以不等待确认直接执行所有操作，实现真正的全自动运行。

开启方式：Chat 设置 → Enable Yolo Mode，或在 Agent 运行时点击"允许所有操作"。

Yolo 模式配置

// Cursor Settings → Features → Agent → Yolo Mode
// 可以限制允许的命令类型：

{
  "cursor.agent.yolo.allowedCommands": [
    "npm test",
    "npm run build",
    "npm run lint",
    "npx prettier",
    "git status",
    "git diff"
  ],
  "cursor.agent.yolo.blockedCommands": [
    "rm -rf",
    "sudo",
    "git push",
    "git reset --hard"
  ]
}

Agent 循环与任务分解

Agent 的工作方式是一个 推理-行动循环（ReAct Loop）：

1. 思考（Reason）：分析当前情况，规划下一步行动
2. 行动（Act）：调用工具执行操作（读文件、写代码、运行命令）
3. 观察（Observe）：获取工具调用的结果
4. 循环：基于观察结果更新理解，继续推理…
5. 完成：任务达成后输出最终结果

任务分解的最佳实践

Agent 对 具体、可验证的任务效果最好。过于模糊的任务会导致 Agent 方向偏移或反复确认。

// ❌ 太模糊，Agent 不知道"优化"的标准是什么
"帮我优化这个项目"

// ✅ 具体、有明确的成功标准
"帮我完成以下任务：
1. 在 src/hooks/ 下创建 useDebounce.ts hook，支持泛型和自定义延迟
2. 在 src/components/SearchBar.tsx 中使用这个 hook 替换现有的 setTimeout 逻辑
3. 运行 npm test 确认所有测试通过
4. 如果有测试失败，修复后再次运行"

任务规模建议

Checkpoint 与回滚

Checkpoint（检查点）是 Cursor Agent 的安全网机制。在 Agent 开始执行任务时，Cursor 自动保存当前所有文件的快照。 如果 Agent 的修改不符合预期，可以一键回滚到 Checkpoint 状态。

操作方式：在 Agent 对话的顶部工具栏，点击"Checkpoint"图标，选择"Restore to this checkpoint"。

实战案例

案例一：实现新功能（含测试）

// 向 Agent 发送：
"在 src/services/ 下创建 EmailService.ts，需要：
1. 使用 nodemailer 发送邮件，从 process.env.SMTP_* 读取配置
2. 实现 sendWelcomeEmail(user: User) 和 sendPasswordReset(email: string, token: string) 方法
3. 所有方法返回 Promise，失败时抛出自定义 EmailError
4. 在 src/services/__tests__/EmailService.test.ts 编写单元测试，mock nodemailer
5. 运行 npm test src/services 确认通过"

// Agent 的执行步骤（可在 Chat 中看到）：
// 1. list_directory: 查看 src/services/ 的结构
// 2. read_file: 读取现有 Service 文件了解项目规范
// 3. read_file: 读取 User 类型定义
// 4. edit_file: 创建 EmailService.ts
// 5. edit_file: 创建测试文件
// 6. run_terminal_command: npm test src/services
// 7. (如果测试失败) edit_file: 修复错误
// 8. run_terminal_command: npm test src/services （再次验证）

案例二：代码库分析与重构

// 向 Agent 发送：
"分析项目中所有的 API 调用，找出没有错误处理（没有 try/catch 或 .catch()）的地方，
列出文件名和行号，然后逐一修复，添加统一的错误处理逻辑"

// Agent 会：
// 1. search_codebase: 搜索 "fetch(" 和 "axios." 等 API 调用模式
// 2. 分析每个文件中的错误处理情况
// 3. 列出问题清单并展示给你确认
// 4. 逐文件修复（你可以逐个接受）

案例三：调试运行时错误

// 向 Agent 发送，并粘贴错误堆栈：
"运行 npm start 后出现以下错误，帮我定位并修复：

Error: Cannot find module '@/components/Layout'
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1083:15)
    at ...

当前的 tsconfig.json 路径别名配置和 next.config.js 请一并检查"

// Agent 会：
// 1. read_file: 读取 tsconfig.json
// 2. read_file: 读取 next.config.js
// 3. search_codebase: 搜索 Layout 组件的实际位置
// 4. 发现是路径别名配置不一致，修复后运行 npm build 验证

Agent 的局限与注意事项

• 上下文窗口限制 Agent 的每个推理步骤都消耗 token。超大型项目（数十万行代码）中，Agent 可能无法一次看到所有相关代码，需要分阶段执行。
• 幻觉风险 当 Agent 无法找到足够上下文时，可能会"编造"不存在的 API 或错误的逻辑。始终检查关键的生成代码。
• 不可逆操作需谨慎 确保 Agent 不能执行 git push、数据库清空等不可逆操作。通过 Yolo 模式的命令黑名单进行限制。
• 循环与卡死 Agent 有时会陷入重复修复同一个错误的循环。若发现 Agent 在兜圈子，及时手动中断并重新描述任务。
• API 额度消耗 Agent 模式比普通 Chat 消耗更多请求额度（每个工具调用都是一次 API 请求）。复杂任务可能消耗 10-50 次请求。