第五章：终极武器 - Agent 模式、规则系统与高级定制 (深度解析与实战)

【本章教学目标】

• 深入剖析 Agent 模式的设计哲学、核心能力（上下文检索、命令执行、错误循环等）及其适用场景。

• 完全掌握 Cursor 规则系统 (Rules) 的原理、创建方式（.cursor/rules 目录、/Generate Cursor Rules 命令）、管理和应用机制。

• 精通 通过编写有效的规则来定制 AI 行为，使其符合项目规范和团队要求。

• 理解并应用 MCP (Multi-Context Prompting)、图像上下文、项目结构上下文等高级特性，为 AI 提供更丰富、更结构化的信息。

• 熟练配置 全局忽略文件、选择和评估不同的 AI 模型，最大限度地发挥 Cursor 的潜力。

引言： 如果说 Chat 和 Cmd+K 是 AI 提供的点状或线状支持，那么 Agent 模式则代表了 Cursor 尝试让 AI 提供面向任务、端到端解决方案的雄心。配合强大的规则系统 (Rules) 和高级上下文定制能力，你可以将 Cursor 的 AI 从一个通用的编程助手，"调教"成一个深度理解你项目、遵循你规范、能够自主完成复杂任务的“智能代理”。这一章，我们将深入探索这些代表 Cursor 最高阶能力的功能。

5.1 Agent 模式：从助手到自主行动的智能代理

Agent 模式旨在让 AI 不仅仅是被动地响应你的指令，而是能更主动地理解任务、规划步骤、调用工具、甚至与环境交互来达成目标。

• 5.1.1 设计哲学：面向任务，端到端解决

• 超越简单问答/编辑： Agent 的目标是处理那些需要多个步骤、涉及多种信息源或需要与外部环境（如终端、文件系统）交互的复杂编程任务。

• 模拟人类开发者工作流： 理想的 Agent 应该能够像一个初级开发者一样，接收一个高级别的任务描述（比如 "修复这个 Bug" 或 "实现这个新功能"），然后自主地：

1. 理解需求： 分析任务描述。

2. 收集信息： 检索代码库、查阅文档、甚至搜索网络。

3. 规划步骤： 制定解决问题的计划。

4. 执行操作： 编写/修改代码、运行命令、检查结果。

5. 验证与迭代： 检查是否达到目标，如果遇到问题则调整计划并重试。

• 用户掌控 (Keep the programmer in the loop)： 虽然追求自主性，但 Cursor 的 Agent 模式强调用户始终拥有控制权。关键步骤（如执行命令、应用重大修改）通常需要用户确认，确保 AI 的行为符合预期且安全。

• 5.1.2 核心能力详解 (Agent 的“超能力”)

• 自动上下文检索 (Automatic Context Retrieval):

• 机制： Agent 内置了专门的检索模型 (官方 Feature 页提到 Custom retrieval models)。当接收到任务时，它会主动分析任务需求，并在你的代码库（需要已索引）中智能地搜索最相关的代码片段、函数定义、类结构等信息，作为执行任务所需的上下文。

• 优势： 相比 Chat 模式需要你手动 @ 大量文件，Agent 能更自动化地获取背景信息，尤其是在处理涉及多个文件或模块的任务时，能显著减少你的手动操作。

• 示例： 你告诉 Agent：“重构用户认证流程，改用 JWT 替代 Session。” Agent 可能会自动去查找项目中与登录、会话管理、用户模型相关的代码文件作为上下文。

• 终端命令执行 (Command Execution):

• 机制： Agent 可以生成 Shell 命令，并请求在 Cursor 内置的终端中执行。这使得它可以完成编译、构建、运行测试、安装依赖、操作 Git 等需要与命令行交互的任务。

• 用户控制 (重要！)：

• 默认确认： 通常，Agent 生成命令后会展示给你，并等待你的确认 (Yes/No 或类似按钮) 才会执行。这是为了防止 AI 执行危险或错误的命令。

• Yolo Mode (0.44.x+)： 提供了一个“勇敢者模式”（可能需要在设置中开启），允许 Agent 自动运行它认为必要的终端命令，无需每次都确认。使用此模式务必谨慎！ 适用于你高度信任 Agent 判断且任务风险可控的场景。

• 编辑/跳过命令 (0.49.x+)： 最新的版本进一步增强了控制力。当 Agent 提出要运行一个命令时，你现在可以先编辑这个命令再让它运行，或者完全跳过这个命令让 Agent 尝试其他方法。

• 后台执行 (0.44.x+)： Agent 可以将某些耗时较长的命令放到后台运行，避免阻塞你的编辑器。0.49.x 将之前的 "Pop-out" 重命名为 "Move to background"，更准确地反映了这一行为。

• 读取退出码 (0.44.x+)： Agent 能获取它执行的命令的退出状态码，从而判断命令是否成功执行，并据此决定下一步行动。

• 错误自修复循环 (Error Loop):

• 机制： Agent 能够读取并理解 Linter (如 ESLint, Pylint) 在你的代码中报告的错误或警告信息 (0.44.x)。

• 自动修复尝试： 基于错误信息，Agent 会尝试自动生成修复代码，并可能直接应用（或通过 Diff 让你确认）。

• 循环迭代： 修复后，Agent 可能会重新触发 Linter 检查，看错误是否消失。如果还有其他错误，它会继续尝试修复，形成一个自动化的“发现错误 -> 修复 -> 验证”的过程。

• 价值： 对于那些常见的、模式化的 Linter 错误（比如格式问题、未使用的变量、简单的类型错误等），Agent 可以帮你快速清理，节省大量枯燥的手动修复时间。

• 文件系统操作 (读写文件):

• 能力： Agent 不仅能读取文件内容作为上下文，还能直接修改文件。

• 自动保存 (0.44.x+)： Agent 对文件所做的修改通常会自动保存到磁盘。

• 并行编辑 (0.44.x+)： 对于某些任务，Agent 可能判断出需要同时修改多个不同位置的代码，它可以并行地进行这些编辑操作。

• 智能应用编辑 (Smarter Apply Model - 0.44.x+)： Agent 在应用编辑时，可能使用了更智能的模型或逻辑，使其能更可靠地将修改合并到现有代码中，减少冲突或错误。

• 感知代码变更 (Sees recent changes - 0.45.x): Agent 能够知道在你上次与它交互后，你自己对代码做了哪些修改。这使得它的后续操作能基于最新的代码状态，避免操作过时的代码。

• 调用其他工具: Agent 模式下通常可以无缝调用 Chat 模式下的各种工具，如 @Web 搜索、@Docs 查询、@git 交互等 (0.44.x 明确提到这些在 Agent 中可用)。

• 5.1.3 如何有效使用 Agent 模式

• 选择入口： 通常在聊天面板的模式切换器中选择 "Agent" 模式。早期版本可能在 Composer 界面 (0.43.x)。

• 下达清晰的任务指令： 给 Agent 的指令应该更偏向于一个目标或任务，而不是一个简单的问句。

• 差指令： “代码有问题。”

• 好指令： “修复 calculate_discount 函数在处理负数价格时抛出异常的 Bug。”

• 好指令： “为 UserService 类添加一个 updatePassword 方法，需要验证旧密码，并对新密码进行哈希存储。请同时编写相应的单元测试。”

• 好指令： “将项目中的所有 axios 网络请求替换为使用 fetch API。”

• 监控与交互： Agent 执行任务时，留意聊天面板的输出。它可能会：

• 告诉你它的计划步骤。

• 展示它检索到的上下文代码。

• 请求你确认是否执行某个命令。

• 展示它生成的代码修改 Diff。

• 报告遇到的问题或请求你提供更多信息。

• 你需要及时响应它的请求，引导它完成任务。

• 耐心与迭代： 复杂的任务 Agent 可能无法一次性完美完成。如果结果不理想，分析它的执行过程，找出问题所在，然后给出更精确的后续指令，或者将任务拆解得更小。

• 局限性认知： Agent 虽然强大，但并非万能。对于需要深度领域知识、复杂架构决策或高度创造性的任务，它仍然是辅助角色。复杂的 Bug 调试仍需结合传统 Debugger。

5.2 规则系统 (Rules)：驯服 AI 的缰绳 (核心定制化能力)

规则系统是 Cursor 提供给用户塑造 AI 行为的最重要机制。通过定义规则，你可以让 AI 的回答和代码生成更符合你的特定需求和项目规范。

• 5.2.1 规则的核心价值与应用场景

• 代码风格与规范统一：

• 场景：团队有严格的编码规范（如 Google Style Guide, Airbnb Style Guide），或者使用特定的 Linter/Formatter 配置。

• 规则示例：所有 Python 代码必须遵循 PEP 8。使用 Black 进行格式化。函数参数和返回值必须添加类型提示。 JavaScript 代码使用 Prettier 格式化，遵循 Airbnb 风格指南。禁止使用 var，优先使用 const。

• 项目特定知识注入：

• 场景：项目使用了自研框架、内部库，或者有独特的架构模式、业务术语。

• 规则示例：本项目基于自研的 'Phoenix' MVC 框架。Controller 负责接收请求和参数校验，Service 负责业务逻辑，Repository 负责数据库交互。 与 'Orion' 支付网关交互时，必须使用 PaymentGatewayClient类，并处理其可能抛出的TimeoutException和InsufficientFundsException。

• 强制性要求：

• 场景：规定必须执行的操作，如日志记录、错误处理、安全检查。

• 规则示例：所有捕获到的异常，在处理后必须调用 Logger.error() 记录详细错误信息和堆栈。 所有处理用户输入的函数，必须先进行输入清理 (Sanitization) 和验证，防止 XSS 和注入攻击。

• AI 角色与行为设定：

• 场景：希望 AI 在回答问题或生成代码时扮演特定角色或遵循特定风格。

• 规则示例：你是一位资深的安全专家。在评审代码或提供建议时，请优先关注潜在的安全风险。 请以简洁、直接的方式回答问题，避免冗长的解释，优先提供可执行的代码示例。 请总是使用简体中文进行交流。

• 5.2.2 创建与管理规则的权威指南 (基于 0.45.x 及以后版本)

• 核心机制：.cursor/rules 目录

1. 定位： 在你的项目根目录下。如果不存在 .cursor 文件夹，请手动创建它。然后在 .cursor 文件夹内创建 rules 文件夹。最终路径是 YourProjectRoot/.cursor/rules/。

2. 创建规则文件： 在 rules 目录下创建文本文件，推荐使用 .md (Markdown) 或 .txt 扩展名。

3. 命名规则文件： 文件名应该能清晰地反映规则的内容，方便管理。例如：coding_style.md, architecture.txt, security_checklist.md, api_conventions.txt。

4. 编写规则内容： 使用清晰、明确的自然语言在文件中描述规则。

• 格式建议： 可以使用 Markdown 的列表、标题等来组织内容，使其更易读。

• 内容要点：

• 做什么 (Do's): “必须...”，“应该...”，“总是...”

• 不做什么 (Don'ts): “禁止...”，“避免...”，“绝不...”

• 原因 (Why - 可选但推荐): 简单解释规则背后的原因，有助于 AI 更好地理解和应用。

• 示例 (Examples - 强烈推荐): 提供符合规则和违反规则的代码示例，能极大地帮助 AI 理解。

• 引用项目其他部分 (可选): 可以引用项目中的特定文件、类或文档，例如：“错误码定义请参考 @docs/error_codes.md”。

1. 组织规则 (0.47.x+)： 如果规则很多，可以在 .cursor/rules/ 下创建子目录来分类管理，例如 .cursor/rules/backend/, .cursor/rules/frontend/, .cursor/rules/common/。Agent 也能识别嵌套目录中的规则。

• 快捷生成规则：/Generate Cursor Rules 命令 (0.49.x 新增 - 智能提取)

1. 触发场景： 在 Chat 面板与 AI 对话时，你发现某段对话（可能是你对 AI 的要求，或者 AI 表现出的某种良好行为模式）非常有价值，希望将其固化为规则。

2. 操作： 在聊天输入框中，输入 /Generate Cursor Rules 并按 Enter。

3. AI 动作： AI 会分析当前对话的上下文，尝试提取其中隐含的规则或指令，并将其格式化为一或多个规则文件的内容。

4. 确认与保存： AI 会展示它生成的规则内容，并询问你是否要将其保存到你项目的 .cursor/rules 目录下（可能会建议文件名）。确认后，规则文件就会被创建或更新。

5. 优势： 将临时的、对话中的“约定”快速转化为持久化的、可复用的项目级规则，非常高效。

• 规则的生效与应用 (Agent 如何使用)：

• 自动发现： Cursor Agent 会自动扫描项目根目录下的 .cursor/rules/ 目录（包括子目录）。

• 上下文关联应用 (0.49.x 重点)： 当 Agent 需要读取或写入某个文件时，它会检查是否有规则与该文件的路径相关联（可能是通过规则文件内的元数据、特定的命名约定，或者更智能的路径模式匹配）。如果找到匹配的规则，Agent 在处理该文件时会优先遵循这些规则。

• 全局应用 (Always attached rules - 0.49.x 修复)： 可能存在某些规则被标记为“总是附加”，无论处理哪个文件都应该生效（比如通用的代码风格规则、安全要求）。0.49.x 修复了这类规则在长对话中会丢失的问题。

• 视觉指示器 (0.46.x)： Cursor 界面上可能会有视觉提示，告诉你当前操作将应用哪些规则，让你更清楚 AI 的行为依据。

• 编辑现有规则 (0.49.x)： 你不仅可以手动编辑 .cursor/rules/ 目录下的文件，还可以通过聊天指令让 Agent 帮你修改已存在的规则。例如：“请更新 python_style_guide.md 规则，补充关于异步代码的规范。”

• 5.2.3 编写有效规则的最佳实践

• 清晰具体，避免模糊： 不要说“写好代码”，要说“函数长度不应超过 50 行，嵌套层级不应超过 3 层”。

• 使用祈使句： “必须...”、“应该...”、“禁止...”。

• 提供正反示例： “好代码示例：... 坏代码示例：...”。

• 保持简洁： 规则太多太复杂，AI 可能难以完全理解和遵循。抓住核心要点。

• 模块化组织： 将不同类型的规则放到不同的文件中，使用清晰的文件名和目录结构。

• 与团队同步： 如果是团队项目，规则应该是团队共识的体现，并保持更新。

• 逐步完善： 不需要一次性写出完美的规则。先写核心的，然后在实际使用中观察 AI 的表现，逐步补充和调整规则。

5.3 高级上下文与定制：突破 AI 交互的边界

除了代码和规则，还有一些高级方式可以为 AI 提供更丰富、更结构化的信息。

• 5.3.1 MCP (Multi-Context Prompting) 与图像支持

• 概念深化： MCP 不仅仅是组合 @ 引用。它更倾向于一种结构化提供多种不同类型上下文给 AI 的机制。对于高级用户或企业，这可能涉及到配置专门的 MCP 服务器。这个服务器可以根据请求动态地准备和组合上下文信息（比如，从代码库、数据库、内部文档系统、API 等多处获取信息），然后传递给 Cursor 的 AI 模型。

• 图像作为 MCP 上下文 (0.49.x 关键更新)： 这是多模态能力的重要进展。如果你的工作流涉及到需要 AI 理解视觉信息的复杂任务（例如，根据 UI Mock 自动生成前端代码、分析包含图表的测试报告、基于流程图理解业务逻辑），并且你使用了 MCP 服务器，那么现在可以通过 MCP 服务将这些图像数据（截图、设计稿、图表等）作为上下文的一部分，直接传递给 AI 模型。这极大地扩展了 AI 能处理的任务范围。

• 普通用户的体现： 虽然普通用户不直接配置 MCP 服务器，但 Cursor 内部可能利用类似 MCP 的技术来整合你通过 @、选中代码、聊天历史等方式提供的多种上下文。聊天中直接支持图像输入也是这种多模态能力的体现。

• 5.3.2 项目结构上下文 (Project structure in context - 0.49.x Beta)

• 解决的问题： AI 理解单个文件的代码通常没问题，但对于一个大型项目，理解文件之间的组织关系、模块划分、目录结构也很重要。只看代码片段可能会“只见树木，不见森林”。

• 功能： 启用这个 Beta 功能后，当你与 AI 交互时（特别是 Agent 模式或代码库问答），Cursor 会将你项目的主要文件目录结构树信息，作为附加上下文一同发送给 AI。

• 带来的好处：

• 更好的导航建议： 当你问“实现 XX 功能需要修改哪些文件？”时，AI 能基于目录结构给出更靠谱的建议。

• 改进对大型仓库/Monorepo 的理解： AI 能更好地把握不同子项目或模块之间的关系。

• 更准确的代码生成/重构： AI 生成的代码能更好地放到项目结构中合适的位置，或者在重构时更好地考虑模块边界。

• 如何开启： 在 Cursor 设置 (Settings) 中查找 "Beta" 或 "Features" 相关选项，找到 "Project structure in context" 并启用。

• 5.3.3 全局忽略文件 (Global Ignore Files - 0.49.x)：全局视角下的配置优化

• 回顾与深化： 如第一章所述，这是在用户级别（而非项目级别）配置的忽略规则。

• 配置方法： 通常是编辑你的**用户 **settings.json 文件 (可以通过命令面板 Preferences: Open User Settings (JSON) 打开)，添加或修改 cursor.globalIgnorePatterns (或类似名称) 的数组，写入符合 .gitignore 语法的模式。

• 核心价值：

• 避免重复配置： 对于所有项目都通用的忽略规则（如编译产物、系统文件、版本控制目录），只需配置一次。

• 强制性忽略： 即使项目忘记配置 .cursorignore，全局规则也能生效，提供一层基础保障。

• 保护通用敏感模式： 如果你有常用的本地配置文件或临时文件模式不希望被 AI 接触，可以在全局配置。

• 与项目级忽略的关系： 通常项目级的 .cursorignore 会优先于全局忽略规则，并且可以覆盖全局规则（例如，全局忽略了 *.log，但某个项目需要在 .cursorignore 里用 !important.log 来强制包含某个日志文件）。需要根据实际行为确认优先级。

• 5.3.4 最新 AI 模型选择与评估

• 保持关注： AI 模型领域发展极快。Cursor 通常会很快集成业界最新的、表现优异的模型。留意 Settings > Models 列表的变化，以及官方的 Changelog 和博客。

• 0.49.x 提到的新模型： GPT-4.1, Gemini 2.5 Pro, Gemini 2.5 Flash, Grok 3, Grok 3 Mini, o3, o4-mini。这些都代表了当前（发布时）的先进水平。

• 如何选择？（再强调）

• 质量优先？ GPT-4 系列、最强的 Claude/Gemini/Grok。

• 速度优先？ Gemini Flash, o4-mini, Cursor-Fast, GPT-3.5 Turbo。

• 长上下文？ Claude 系列, Gemini Pro, GPT-4 Turbo。

• 成本敏感？ 优先用免费额度涵盖的模型，或者选择 Token 成本较低的模型。

• 实验与评估： 对于重要或常用的任务，可以尝试用不同的模型执行相同的指令，比较它们的输出质量、速度和成本，找到最适合你需求和预算的模型组合。

【本章深度总结】

这一章我们深入了 Cursor 的“引擎室”，探讨了其最高阶的能力：

1. Agent 模式： 从被动响应到主动执行任务，具备上下文检索、命令执行、错误修复等高级能力，是 AI 协作的未来方向。

2. 规则系统 (Rules)： 核心定制化机制，通过 .cursor/rules 目录或 /Generate 命令定义规则，让 AI 成为懂你项目、守你规矩的“圈内人”。

3. 高级上下文与定制： MCP 图像支持、项目结构上下文、全局忽略文件等特性，为 AI 提供了更维度、更结构化的信息输入和行为约束。

4. 模型选择： 紧跟前沿，按需选用最适合的 AI 大脑。

掌握这些高级功能，你才能真正将 Cursor 的潜力发挥到极致，实现与 AI 的深度融合，彻底革新你的编程工作流。