第五章:终极武器 - 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" 或 "实现这个新功能"),然后自主地:
-
理解需求: 分析任务描述。
-
收集信息: 检索代码库、查阅文档、甚至搜索网络。
-
规划步骤: 制定解决问题的计划。
-
执行操作: 编写/修改代码、运行命令、检查结果。
-
验证与迭代: 检查是否达到目标,如果遇到问题则调整计划并重试。
-
用户掌控 (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 目录
-
定位: 在你的项目根目录下。如果不存在 .cursor 文件夹,请手动创建它。然后在 .cursor 文件夹内创建 rules 文件夹。最终路径是 YourProjectRoot/.cursor/rules/。
-
创建规则文件: 在 rules 目录下创建文本文件,推荐使用 .md (Markdown) 或 .txt 扩展名。
-
命名规则文件: 文件名应该能清晰地反映规则的内容,方便管理。例如:coding_style.md, architecture.txt, security_checklist.md, api_conventions.txt。
-
编写规则内容: 使用清晰、明确的自然语言在文件中描述规则。
-
格式建议: 可以使用 Markdown 的列表、标题等来组织内容,使其更易读。
-
内容要点:
-
做什么 (Do's): “必须...”,“应该...”,“总是...”
-
不做什么 (Don'ts): “禁止...”,“避免...”,“绝不...”
-
原因 (Why - 可选但推荐): 简单解释规则背后的原因,有助于 AI 更好地理解和应用。
-
示例 (Examples - 强烈推荐): 提供符合规则和违反规则的代码示例,能极大地帮助 AI 理解。
-
引用项目其他部分 (可选): 可以引用项目中的特定文件、类或文档,例如:“错误码定义请参考 @docs/error_codes.md”。
- 组织规则 (0.47.x+): 如果规则很多,可以在 .cursor/rules/ 下创建子目录来分类管理,例如 .cursor/rules/backend/, .cursor/rules/frontend/, .cursor/rules/common/。Agent 也能识别嵌套目录中的规则。
- 快捷生成规则:/Generate Cursor Rules 命令 (0.49.x 新增 - 智能提取)
-
触发场景: 在 Chat 面板与 AI 对话时,你发现某段对话(可能是你对 AI 的要求,或者 AI 表现出的某种良好行为模式)非常有价值,希望将其固化为规则。
-
操作: 在聊天输入框中,输入 /Generate Cursor Rules 并按 Enter。
-
AI 动作: AI 会分析当前对话的上下文,尝试提取其中隐含的规则或指令,并将其格式化为一或多个规则文件的内容。
-
确认与保存: AI 会展示它生成的规则内容,并询问你是否要将其保存到你项目的 .cursor/rules 目录下(可能会建议文件名)。确认后,规则文件就会被创建或更新。
-
优势: 将临时的、对话中的“约定”快速转化为持久化的、可复用的项目级规则,非常高效。
-
规则的生效与应用 (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 的“引擎室”,探讨了其最高阶的能力:
-
Agent 模式: 从被动响应到主动执行任务,具备上下文检索、命令执行、错误修复等高级能力,是 AI 协作的未来方向。
-
规则系统 (Rules): 核心定制化机制,通过 .cursor/rules 目录或 /Generate 命令定义规则,让 AI 成为懂你项目、守你规矩的“圈内人”。
-
高级上下文与定制: MCP 图像支持、项目结构上下文、全局忽略文件等特性,为 AI 提供了更维度、更结构化的信息输入和行为约束。
-
模型选择: 紧跟前沿,按需选用最适合的 AI 大脑。
掌握这些高级功能,你才能真正将 Cursor 的潜力发挥到极致,实现与 AI 的深度融合,彻底革新你的编程工作流。