Cursor IDE多智能体协作系统：构建AI团队自动化复杂任务

1. 项目概述：在Cursor IDE中构建一个多智能体协作系统

如果你和我一样，是个喜欢折腾开发工具、探索效率边界的程序员，那你肯定对AI辅助编码不陌生。但大多数时候，我们用的都是“单打独斗”的AI助手，问一个问题，得到一个回答。最近我在Cursor IDE里尝试了一个更有意思的玩法：让多个AI智能体（Agent）像一支训练有素的团队一样协作，共同完成一个复杂的多步骤任务。这个项目yu-iskw/cursor-experiments就是一个绝佳的演示，它展示了一个“旅行规划师”智能体如何指挥“航班研究员”和“酒店研究员”两个子智能体，最终生成一份完整的旅行报告。

简单来说，这就像是你作为项目经理（主智能体），手下有两个专家下属（子智能体）。你只需要下达一个高层指令：“帮我规划从纽约到旧金山的旅行”，项目经理就会自动把任务拆解，分别派给懂航班的专家和懂酒店的专家去调研，最后把两份报告汇总，交给你一份完整的方案。整个过程在Cursor的聊天面板里自动完成，你只需要看着它“干活”就行。这不仅仅是自动化，更是一种智能的任务编排与协作范式，对于处理代码审查、文档生成、多模块系统设计等需要多领域知识的开发任务，潜力巨大。

2. 核心架构与设计思路拆解

2.1 为什么选择多智能体架构？

传统的AI编码助手，无论是Copilot还是Cursor的默认模式，本质上是“一问一答”的增强型自动完成。当面对“规划一次旅行”这种复合型任务时，它可能会生成一段笼统的文字，但缺乏深度、结构化和可验证的细节。多智能体架构的核心优势在于分工与专业化。

• 解耦复杂性：将一个大问题（旅行规划）分解为多个正交的子问题（航班搜索、酒店搜索）。每个子智能体只需专注于自己的领域，其指令（Prompt）和工具（Skills）可以设计得极其精准和高效。
• 提升可靠性与可控性：航班搜索的逻辑和酒店搜索的逻辑完全不同。如果混在一个智能体里，指令很容易变得冗长且容易混淆。分开后，我们可以为@flight-researcher专门定制如何解析城市代码、查询日期、比较价格的逻辑；为@hotel-researcher定制如何筛选区域、房型和预算。这样每个环节的产出质量更高，也更容易单独调试和优化。
• 模拟真实工作流：这非常贴近人类团队协作的模式。架构师（主智能体）负责拆解需求和整合成果，开发工程师（子智能体）负责实现具体模块。这种模式使得整个系统更容易理解和维护，也便于未来引入新的“专家”（例如@restaurant-researcher或@attraction-planner）。

2.2 Cursor智能体框架的运作机制

Cursor的智能体框架是其区别于其他IDE的核心特性之一。它允许开发者通过定义Agent和Skill来扩展AI的能力边界。

• 智能体（Agent）：你可以把它理解为一个拥有特定角色、知识和能力范围的“虚拟员工”。每个智能体都是一个Markdown文件（通常位于.cursor/agents/目录下），文件顶部用YAML格式的Frontmatter来定义它的元数据，比如名称、描述、它可以调用的其他智能体（collaborates_with）以及它可以使用的技能（uses_skills）。文件正文则是给这个智能体的详细“岗位说明书”（System Prompt），告诉它该如何思考、如何行动、输出的格式是什么。
• 技能（Skill）：这是智能体可以执行的“动作”或“工具”。一个技能通常关联一个具体的可执行脚本（如Shell、Python脚本），智能体可以通过调用技能来与外部系统交互、执行计算或获取数据。技能也定义在.cursor/skills/目录下的Markdown文件中，其中会描述技能的作用、输入参数和输出格式。

在这个旅行规划项目中，三者之间的关系构成了一个清晰的层级：

1. 主智能体（@trip-planner）：接收用户原始需求，理解“规划旅行”这个高层目标。
2. 子智能体（@flight-researcher, @hotel-researcher）：被主智能体调用，分别接收“查纽约到旧金山的航班”和“查旧金山的酒店”这样的具体指令。
3. 技能（@research-flight, @research-hotel）：被子智能体调用，实际执行背后的搜索脚本（在这个Demo里是模拟脚本），并返回结构化的数据。

注意：这种“智能体 -> 子智能体 -> 技能”的调用链是Cursor智能体协作的一种典型模式，但不是唯一模式。智能体也可以直接调用多个技能，或者一个技能被多个智能体共享。设计的关键在于找到职责的平衡点。

3. 项目文件结构与核心配置详解

要复现或理解这个项目，必须吃透它的目录结构，每一个文件都有其明确的使命。下面我结合自己的实践，带你深入每个核心文件。

3.1 智能体定义文件剖析

智能体定义是项目的“大脑”，位于.cursor/agents/目录下。我们以trip-planner.md为例：

--- name: trip-planner description: An agent that orchestrates trip planning by collaborating with flight and hotel researcher agents. collaborates_with: - flight-researcher - hotel-researcher uses_skills: [] --- # Trip Planner Agent You are a senior travel coordinator. Your job is to take a user's high-level trip request and break it down into actionable sub-tasks for specialist agents. ## Core Workflow 1. **Parse Request**: Extract key details: origin, destination, dates (if provided), budget hints, traveler count. 2. **Delegate**: * Task the `@flight-researcher` with finding optimal flight options. * Task the `@hotel-researcher` with finding suitable hotel accommodations. 3. **Synthesize**: Collect findings from both sub-agents. Integrate them into a cohesive, reader-friendly trip plan. 4. **Document**: Generate two final outputs: * A clean trip report (`trip_plan.md`). * A detailed execution log (`task_logs.md`) including a Mermaid diagram of the agent interaction. ## Output Format Instructions - The trip report must be in Markdown, with clear sections for Flights, Hotels, and a Summary. - The task log must chronologically record every step, decision, and agent interaction. The Mermaid diagram is mandatory and should visualize the delegation flow.

关键点解析：

• YAML Frontmatter：collaborates_with字段是灵魂，它声明了这个智能体可以“召唤”哪些伙伴。这相当于在团队通讯录里加了好友。
• System Prompt：正文部分就是智能体的“人格”和“工作手册”。这里写得越清晰、越结构化，智能体执行就越稳定。我特别欣赏它明确规定了工作流和输出格式。这避免了AI自由发挥导致输出不一致的问题。
• 强制图表生成：要求生成Mermaid图表是一个神来之笔。这不仅让日志可视化，更重要的是，它强制主智能体在思考时必须显式地构建任务流模型，从而提高了整个过程的逻辑性和可解释性。

flight-researcher.md和hotel-researcher.md的结构类似，但它们的uses_skills字段会指向具体的技能，并且其System Prompt会专注于如何解析航班/酒店查询、如何调用技能、如何处理返回的数据。

3.2 技能定义与脚本实现

技能是“手”，位于.cursor/skills/目录。以research-flight/SKILL.md为例：

--- skill: research-flight description: Researches flight options between two cities. arguments: - name: origin description: IATA city code for the origin (e.g., NYC) required: true - name: destination description: IATA city code for the destination (e.g., SFO) required: true script: .cursor/skills/research-flight/research_flight.sh --- This skill executes a flight search. It expects origin and destination city codes and returns a structured list of flight options with details like airline, price, and times.

关键点解析：

• 参数定义：arguments部分定义了技能所需的输入，包括参数名、描述和是否必填。这为智能体调用技能提供了清晰的“接口文档”。
• 脚本关联：script字段指向实际执行的Shell脚本。这是技能落地的地方。

我们看看配套的Shell脚本research_flight.sh（简化版）：

#!/bin/bash # 模拟航班搜索脚本 ORIGIN=$1 DEST=$2 # 模拟一些逻辑和延迟，使其更真实 sleep 1 # 生成模拟数据 echo "Flight search results for $ORIGIN to $DEST:" echo "" echo "| Airline | Flight No. | Departure | Arrival | Price | Notes |" echo "|---------|------------|-----------|---------|-------|-------|" echo "| Delta | DL 789 | JFK 08:00 | SFO 11:20 | \$420 | Non-stop, Economy |" echo "| United | UA 456 | EWR 14:30 | SFO 17:55 | \$385 | 1 stop (ORD), Basic Economy |" echo "| JetBlue | B6 123 | JFK 21:15 | SFO 00:45+1 | \$350 | Non-stop, Mint upgrade available |"

这个脚本非常简单，就是返回一个固定的Markdown表格。但在真实场景中，这里可以替换为调用真实的航班API（如Skyscanner、Google Flights的API），进行复杂的查询和数据处理后，返回结构化的结果。技能脚本的威力在于，它可以将任何命令行工具、API或本地程序封装成AI智能体可以调用的能力。

3.3 输出报告的结构

项目运行后，结果会输出到reports/目录下。trip_plan.md是最终用户看到的旅行计划，而task_logs.md则是开发者查看的“后台日志”，其中包含了智能体间的对话记录和最重要的Mermaid流程图。这个流程图是动态生成的，直观展示了本次任务中智能体是如何被调用的，对于调试和理解系统行为至关重要。

4. 完整实操流程与核心环节实现

现在，让我们从头到尾跑一遍这个Demo，看看魔法是如何发生的。我会穿插很多实际操作中的细节和心得。

4.1 环境准备与项目初始化

首先，你需要有一个安装了Cursor IDE并拥有高级功能（通常需要订阅）的环境。因为智能体（Agent）功能是Cursor的高级特性之一。

1. 克隆仓库：在终端中，将示例项目克隆到本地。

   git clone https://github.com/yu-iskw/cursor-experiments.git cd cursor-experiments

2. 用Cursor打开项目：这很重要，必须用Cursor IDE打开这个目录，因为它需要读取项目根目录下的.cursor文件夹来识别智能体和技能的定义。
3. 检查智能体面板：打开Cursor后，在侧边栏或Chat面板中，你应该能看到可用的智能体列表。如果配置正确，@trip-planner、@flight-researcher等应该会出现。

实操心得：有时Cursor不会立即加载所有自定义智能体。如果没看到，尝试完全关闭Cursor再重新打开项目，或者检查.cursor/agents/目录下的文件格式是否正确（YAML frontmatter不能有语法错误）。

4.2 发起一次多智能体协作请求

这是最激动人心的部分。我们按照项目说明，在Cursor的Chat面板中（快捷键Cmd+L或Ctrl+L）输入：

/trip-planner I want to go to San Francisco from NYC. Please write a trip report in @reports/plan_to_san_francisco/trip_plan.md . You have to comprehensively and precisely leave logs what and how you address the tasks with a diagram in Mermaid in @reports/plan_to_san_francisco/task_logs.md . You have to show a diagram of what you address the task in the plan.

输入解析：

• /trip-planner：这是一个“斜杠命令”，直接唤醒了我们定义的主智能体。你也可以直接输入@trip-planner。
• 第一行是自然语言需求。
• 后面两行是非常关键的指令，明确指定了输出文件路径和日志格式要求。这遵循了“清晰指令出优质结果”的原则。

4.3 观察智能体协作的“现场直播”

发送指令后，不要眨眼。Cursor的Chat界面会变成一场“交响乐指挥现场”：

1. 主智能体响应：@trip-planner首先会确认任务，并开始它的“思考”。你会在聊天记录里看到它说：“我将把这个任务分解，并协调@flight-researcher和@hotel-researcher...”。
2. 自动@子智能体：紧接着，你会发现聊天记录里自动出现了对@flight-researcher的召唤和具体指令，例如：“@flight-researcher，请搜索从纽约（NYC）到旧金山（SFO）的航班选项。”
3. 子智能体调用技能：@flight-researcher被唤醒后，它会分析指令，然后调用其技能：“我将使用@research-flight技能，参数为 origin=NYC, destination=SFO。”
4. 技能执行：此时，Cursor会在后台执行关联的Shell脚本research_flight.sh。你可能会在终端或日志中看到脚本运行（如果脚本有输出）。脚本的返回结果（那个Markdown表格）会作为消息反馈给@flight-researcher。
5. 结果汇总与传递：@flight-researcher收到技能返回的数据后，可能会进行一些格式化或总结，然后将“找到3个航班选项，详情如下...”的结果回复给@trip-planner。
6. 并行与串行：通常，@trip-planner会同时（或近乎同时）召唤@hotel-researcher，开启另一条并行任务线。你会在聊天记录中看到交错的对话，非常像两个专家在同时向项目经理汇报。
7. 最终合成：当两个子任务都完成后，@trip-planner会收集所有信息，开始撰写最终的旅行报告和任务日志。它会严格按照其System Prompt的要求，生成包含航班、酒店等章节的Markdown报告，并在日志中插入一个描述本次协作流程的Mermaid图表。

整个过程中，你作为用户，完全是一个“旁观者”和“结果验收者”。所有的任务分解、调度、执行和汇总都是自动完成的。

4.4 结果验收与文件生成

过程结束后，你可以去项目目录下的reports/plan_to_san_francisco/文件夹查看成果：

• trip_plan.md：一份格式工整的旅行计划，包含了模拟的航班和酒店信息。

• task_logs.md：这是精华所在。打开它，你会看到：

  • 完整的时间线日志，记录了每个智能体说了什么、做了什么。
  • 一个由AI自动生成的Mermaid图表代码块。将其复制到任何支持Mermaid的Markdown渲染器中（如GitHub、Obsidian、某些IDE插件），就能看到一幅类似下文的可视化流程图：

  graph TD A[用户: /trip-planner 请求] --> B[Trip Planner Agent]; B --> C[Flight Researcher Agent]; B --> D[Hotel Researcher Agent]; C --> E[Research Flight Skill]; D --> F[Research Hotel Skill]; E --> C; F --> D; C --> B; D --> B; B --> G[生成 Trip Plan]; B --> H[生成 Task Logs with Diagram];

  这个图表不是项目文档里预设的静态图，而是本次任务执行过程的真实记录。它证明了主智能体确实理解并执行了编排逻辑。

5. 深度定制与扩展实践指南

这个Demo提供了一个完美的起点，但它的真正价值在于你可以基于此进行无限扩展，将其应用到真实的开发场景中。下面分享几个我的扩展思路和实操细节。

5.1 创建你自己的专属智能体

假设你想创建一个@code-reviewer智能体，专门负责审查Python代码的安全性。

1. 创建智能体文件：在.cursor/agents/下新建code-reviewer.md。

   --- name: code-reviewer description: A specialized agent for conducting security-focused code reviews on Python modules. collaborates_with: [] uses_skills: - static-analysis --- # Code Reviewer Agent You are a senior security engineer. Review the provided Python code for: 1. Common vulnerabilities (SQL injection, XSS, command injection). 2. Hard-coded secrets (API keys, passwords). 3. Insecure deserialization. 4. Misconfigured dependencies. Format your findings as a Markdown table with: Severity (High/Medium/Low), Location, Vulnerability, Recommendation.

2. 创建配套技能：在.cursor/skills/下创建static-analysis/目录，里面放SKILL.md和一个执行脚本（例如调用bandit或semgrep的Python脚本）。

   # SKILL.md 定义 --- skill: static-analysis description: Runs static analysis on a given Python file. arguments: - name: filepath description: Path to the Python file to analyze required: true script: .cursor/skills/static-analysis/run_analysis.sh ---

   # run_analysis.sh #!/bin/bash FILEPATH=$1 # 使用 bandit 进行安全扫描 bandit -f json -o /tmp/bandit_result.json $FILEPATH 2>/dev/null # 将JSON结果转换为可读的Markdown摘要 python3 -c " import json with open('/tmp/bandit_result.json') as f: data = json.load(f) print('## Static Analysis Results') for issue in data['results']: print(f\"| **{issue['issue_severity']}** | {issue['issue_text']} | {issue['filename']}:{issue['line_number']} |\") "

3. 集成到工作流：你可以修改@trip-planner（或新建一个@project-manager），让它collaborates_with: [code-reviewer]。然后就可以在Chat里说：“@project-manager，请审查src/utils.py文件的安全性并生成报告。”

5.2 连接真实数据源

Demo中的技能脚本返回的是模拟数据。要让它实用化，必须连接真实API。

以酒店搜索为例，连接一个模拟API（如MockAPI）或真实API（需处理密钥）：

1. 修改技能脚本：将research_hotel.sh从返回静态文本，改为调用curl命令查询API。

   #!/bin/bash DEST_CITY=$1 # 假设有一个返回JSON的酒店查询端点 API_URL=\"https://api.example.com/hotels?city=${DEST_CITY}\" # 注意：真实场景中，API密钥应通过环境变量管理，切勿硬编码！ API_KEY=${HOTEL_API_KEY} response=$(curl -s -H \"Authorization: Bearer $API_KEY\" \"$API_URL\") # 使用jq解析JSON，并格式化为Markdown表格 echo \"## Hotel Options in $DEST_CITY\" echo \"\" echo \"| Name | Area | Price/Night | Rating |\" echo \"|------|------|-------------|--------|\" echo $response | jq -r '.hotels[] | \"| \(.name) | \(.district) | $\(.price) | \(.rating) |\"'

2. 安全处理密钥：绝对不要将API密钥写在脚本里！应该通过Cursor的环境变量或系统环境变量传入。在Cursor的设置中，可以配置项目级环境变量，然后在脚本中通过$ENV_VAR_NAME读取。
3. 错误处理：真实脚本必须包含完善的错误处理（网络超时、API限流、返回数据异常等），并给智能体返回清晰的错误信息，以便它能决定重试还是上报失败。

5.3 设计更复杂的协作流程

当前的流程是简单的“主-从”式。你可以设计更复杂的模式：

• 条件性协作：让主智能体根据子任务的结果决定下一步。例如，如果@flight-researcher返回“机票太贵”，则主智能体可以召唤一个@budget-advisor来提供替代方案。
• 迭代式优化：主智能体生成初版计划后，召唤一个@plan-critic进行挑刺，然后根据反馈进行修改，形成多轮迭代。
• 竞争与择优：同时召唤两个不同的@flight-researcher（一个用Expedia逻辑，一个用Kayak逻辑），让它们分别搜索，然后主智能体对比结果，选择最优方案整合。

实现这些的关键在于设计智能体的System Prompt，让它具备评估、决策和发起新协作的能力。这需要更精细的Prompt工程。

6. 常见问题、排查技巧与避坑实录

在实际搭建和运行这类多智能体系统时，我踩过不少坑。这里把最常见的问题和解决方案整理出来，希望能帮你节省大量时间。

6.1 智能体或技能未加载/不可见

问题：在Cursor的Chat中输入@，没有出现我定义的智能体名字。排查步骤：

1. 检查文件位置和命名：确保智能体文件在.cursor/agents/目录下，且文件名与name字段一致（例如trip-planner.md对应name: trip-planner）。技能同理。
2. 检查YAML语法：Frontmatter的---必须准确，缩进使用空格而非Tab，冒号后要有空格。一个微小的语法错误会导致整个文件不被识别。可以使用在线YAML校验器检查。
3. 重启Cursor：这是最常用也最有效的办法。Cursor有时不会热加载.cursor目录的变更。
4. 检查项目根目录：确保你是用Cursor打开的包含.cursor文件夹的那个项目根目录，而不是子目录。

6.2 技能脚本执行失败或无输出

问题：智能体调用了技能，但聊天记录里没有技能的返回结果，或者报错。排查步骤：

1. 脚本权限：在Unix-like系统上，确保技能脚本（如.sh文件）有可执行权限：chmod +x .cursor/skills/research-flight/research_flight.sh。
2. 脚本路径：在SKILL.md中定义的script路径是相对于项目根目录的。确保路径正确。
3. 脚本输出：技能脚本的所有标准输出（stdout）会被作为结果返回给智能体。确保你的脚本是通过echo或print将结果输出到stdout，而不是仅写入文件。调试时可以在脚本开头加set -x或在关键步骤加echo \"Debug: ...\" >&2（输出到标准错误，不影响返回结果）。
4. 环境依赖：如果脚本调用jq,curl或python，确保这些命令在Cursor的运行环境中可用。有时IDE的环境和系统终端环境不同。

6.3 智能体不按预期协作或“胡言乱语”

问题：主智能体没有召唤子智能体，或者召唤了但指令不清，导致子智能体执行错误。排查步骤：

1. 精炼System Prompt：智能体的行为90%由它的System Prompt决定。检查主智能体的Prompt是否清晰说明了在什么条件下、以什么格式、召唤哪个子智能体。指令要具体，避免歧义。例如，“Delegate the flight search to @flight-researcher” 比 “Work with the flight agent” 要好得多。
2. 检查collaborates_with和uses_skills：确保这些字段里的名字拼写完全正确，且对应的智能体/技能确实存在。
3. 提供上下文：当主智能体召唤子智能体时，它传递给子智能体的消息就是“上下文”。确保这个消息包含了子智能体完成任务所需的全部信息。例如，主智能体应该传递“Search for flights from NYC to SFO for next weekend”，而不是简单的“Find flights”。
4. 迭代调试：不要指望一次写好。采用“小步快跑”的方式：先让主智能体完成一个最简单的任务（如“召唤A并说你好”），测试通过后再增加复杂性。

6.4 处理真实API时的安全与稳定性问题

问题：技能连接真实API时，遇到认证失败、速率限制、网络超时。解决方案表：

6.5 生成的Mermaid图表格式错误

问题：任务日志中的Mermaid代码无法渲染出图表，或渲染出错。排查步骤：

1. 检查语法：Mermaid有严格的语法。确保生成的代码是有效的。常见的错误是节点标识符包含空格或特殊字符未用引号包裹。智能体生成的代码有时会缺少闭合的graph TD或使用不支持的图表类型。
2. 引导智能体：在主智能体的System Prompt中，提供一个非常具体的Mermaid图表示例。例如：“你必须生成一个Mermaid流程图。使用以下格式作为参考：```mermaid graph TD A[用户请求] --> B[Trip Planner]; B --> C[Flight Researcher]; ... ```”。这能极大提高生成代码的规范性。
3. 后处理：如果图表只是轻微格式问题，可以考虑在技能中增加一个“图表格式化”步骤，用简单的文本处理工具（如sed或Python脚本）对智能体生成的Mermaid代码进行清洗和标准化。

这个多智能体协作的Demo打开了一扇新的大门。它不仅仅是Cursor IDE的一个炫酷功能，更代表了一种构建AI应用的新范式：将复杂任务分解，由多个专业化、可编排的AI模块协同完成。从我自己的体验来看，一旦你熟悉了定义智能体和技能的套路，就能迅速将这种模式应用到代码生成、系统设计、文档撰写、数据分析等无数场景中。最大的挑战和乐趣，从“如何让AI理解我的一句话”变成了“如何设计一支高效的AI团队，并给它们写好分工明确的岗位说明书”。这其中的设计思维和工程实践，才是更有价值的部分。