Cursor IDE多智能体协作系统实战：从旅行规划到AI自动化流程构建-编程阁

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

最近在探索AI编程助手的高级玩法，发现Cursor IDE内置的智能体（Agent）框架远不止是简单的代码补全。它允许我们像搭积木一样，创建多个具备特定技能的AI智能体，并让它们协同工作，完成复杂的、多步骤的任务。这个名为“yu-iskw/cursor-experiments”的项目，就是一个绝佳的实战案例，它清晰地展示了如何利用Cursor实现一个“旅行规划师”多智能体系统。

简单来说，这个项目模拟了一个旅行规划的场景：你告诉一个“总指挥”（Trip Planner Agent）你想从纽约去旧金山，它不会自己埋头苦干，而是会立刻召唤两个专家——一个“航班研究员”（Flight Researcher Agent）和一个“酒店研究员”（Hotel Researcher Agent）。这两个专家各自调用专门的“技能”（Agent Skills），比如执行脚本去“搜索”航班和酒店信息，最后将结果汇总给总指挥，生成一份完整的旅行报告和过程日志。整个过程透明、模块化，就像一支训练有素的AI小分队。

对于开发者、产品经理或者任何对AI自动化流程感兴趣的人来说，这个Demo的价值在于它提供了一个可复现的“蓝图”。它不仅仅展示了“能做什么”，更重要的是揭示了“怎么做”——如何定义智能体、如何设计技能、如何建立它们之间的协作关系。无论你是想构建一个自动化的代码审查流水线、一个智能的数据分析助手，还是一个复杂的客服工单处理系统，这个多智能体协作的模式都能给你带来直接的启发。接下来，我将带你深入这个项目的每一个细节，从设计思路到实操配置，并分享我在复现和扩展过程中踩过的坑和总结的经验。

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

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

在单智能体模型中，我们通常期望一个“全能”的AI助手处理所有事情。但现实是，面对“规划一次旅行”这种复合型任务，单个智能体很容易陷入细节混乱或产生“幻觉”，比如把航班时间和酒店政策搞混。多智能体架构的核心思想是“专业的人做专业的事”，通过职责分离和明确接口来提升整个系统的可靠性和输出质量。

在这个旅行规划项目中，架构师做了非常清晰的角色划分：

协调者（Trip Planner）：负责理解用户的高层意图、拆解任务、协调子任务执行顺序，并整合最终结果。它不关心航班具体怎么查，只关心“需要查航班”这个子任务及其结果。
执行者（Flight/Hotel Researcher）：它们是领域专家，只专注于自己的一亩三分地。航班研究员只懂如何搜索和比较航班，酒店研究员只懂如何筛选酒店。这种专注使得它们在自己的领域内能产生更精准、更可靠的输出。
工具层（Agent Skills）：这是智能体与外部世界（或模拟环境）交互的桥梁。智能体本身是“思考者”，它们通过调用预定义的“技能”来执行具体的操作，比如运行一个Shell脚本、调用一个API、或者查询一个数据库。

这种分层架构的优势非常明显：可维护性高（修改航班搜索逻辑只需动航班研究员的技能）、可扩展性强（想加个“景点研究员”直接新建一个即可）、容错性好（一个子任务失败不影响其他任务的执行）。它本质上是一种面向AI的“微服务”或“插件化”设计思想。

2.2 Cursor智能体框架的关键概念

要理解这个项目，必须先吃透Cursor中几个核心概念的定义和关系：

智能体（Agent）：在Cursor的语境下，一个智能体就是一个具有特定角色、目标和能力的AI实例。它通过一个Markdown文件（通常位于.cursor/agents/目录下）来定义，文件顶部用YAML格式的Frontmatter来描述其元数据（如名称、描述、协作的伙伴等），正文部分则详细说明其职责、工作流程和约束条件。智能体在聊天面板中被@提及或通过斜杠命令调用时激活。
技能（Skill）：技能是智能体可以执行的原子操作。它也被定义为一个Markdown文件（位于.cursor/skills/目录），其中包含了该技能的名称、描述以及最关键的部分——实际要执行的命令或脚本。例如，research-flight技能可能关联到一个执行bash research_flight.sh的指令。技能是智能体能力的具象化延伸。
计划（Plan）：当你在Cursor中向智能体提出一个复杂请求时，Cursor AI可能会先生成一个“计划”（Plan）。这是一个.plan.md文件，记录了AI打算如何一步步解决这个任务的思考过程，包括调用哪些智能体、使用哪些技能、预期的输出等。它相当于整个协作过程的“蓝图”或“执行预案”，对于调试和理解AI的决策逻辑至关重要。

在这个项目中，三者构成了清晰的调用链：用户触发 Trip Planner -> Trip Planner 根据计划调用 Flight/Hotel Researcher -> Researcher 调用对应的 Research Skill -> Skill 执行底层脚本。整个数据流和控制流都在Cursor IDE的环境内闭环完成。

3. 项目结构与关键文件详解

让我们打开项目仓库，像解刨麻雀一样看看每个部分是如何工作的。清晰的文件结构是理解任何代码项目的起点。

3.1 目录树与核心文件功能

.cursor/ ├── agents/ # 智能体定义目录 │ ├── trip-planner.md # 总指挥智能体 │ ├── flight-researcher.md # 航班专家智能体 │ └── hotel-researcher.md # 酒店专家智能体 ├── skills/ # 技能定义目录 │ ├── research-flight/ │ │ ├── SKILL.md # “研究航班”技能定义 │ │ └── research_flight.sh # 技能实际执行的脚本 │ └── research-hotel/ │ ├── SKILL.md # “研究酒店”技能定义 │ └── research_hotel.sh # 技能实际执行的脚本 ├── plans/ # 自动生成的计划文件（运行时产生） └── rules/ # （可能存在的）项目级规则文件 reports/ # 输出目录 ├── plan_to_san_francisco/ │ ├── trip_plan.md # 最终生成的旅行计划报告 │ └── task_logs.md # 详细的任务执行日志（含Mermaid图） docs/ # 项目文档和截图

关键文件解析：

智能体定义文件（如.cursor/agents/trip-planner.md）：这类文件通常以YAML Frontmatter开头，用于配置智能体的基础属性。虽然项目README中提及的是Markdown，但在实际最新的Cursor实践中，更推荐使用.agent.yaml或.agent.yml格式，因为YAML的结构化程度更高，Cursor解析起来更准确。一个典型的智能体YAML定义可能包含：

name: trip-planner description: An agent that orchestrates trip planning by delegating to flight and hotel researchers. collaborators: - flight-researcher - hotel-researcher instructions: | You are a trip planning coordinator. When given a trip request, you MUST: 1. Parse the origin and destination. 2. Delegate flight research to @flight-researcher. 3. Delegate hotel research to @hotel-researcher. 4. Compile their findings into a comprehensive trip report. Always generate a Mermaid diagram in the logs to show your workflow.

instructions部分是灵魂，它用自然语言详细规定了该智能体的行为准则、协作方式和输出要求。

技能定义文件（如.cursor/skills/research-flight/SKILL.md）：技能文件定义了“做什么”。它的核心是一个action字段，指定了要运行的具体命令。
```
name: research-flight description: Searches for flight options between two cities. action: bash .cursor/skills/research-flight/research_flight.sh
```
这里的action指向了一个Shell脚本research_flight.sh。这个脚本就是模拟或真实执行搜索逻辑的地方。
技能执行脚本（如research_flight.sh）：这是真正“干活”的地方。在这个Demo中，脚本内容通常是模拟的，例如：
```
#!/bin/bash # 模拟航班搜索，输出结构化结果 echo “## Flight Search Results for NYC -> SFO” echo “- **Airline**: Demo Airways” echo “- **Flight Number**: DA123” echo “- **Departure**: JFK, 2023-10-27 08:00” echo “- **Arrival**: SFO, 2023-10-27 11:00” echo “- **Price**: $350”
```
在真实场景中，你可以把这里的echo命令替换成调用真实的航班搜索API（如Skyscanner、Google Flights的API），并解析返回的JSON数据。

3.2 智能体与技能的协作关系图（非Mermaid文本描述）

理解它们如何联动至关重要。我们可以用文字描述这个调用关系图：用户发起请求 ->@trip-planner被激活 -> 它分析任务，生成一个内部计划 -> 根据计划，它通过@提及或指令调用@flight-researcher和@hotel-researcher-> 每个研究员智能体接收到子任务（如“查找NYC到SFO的航班”）-> 研究员智能体在自身指令驱动下，决定调用其可用的技能，于是执行@research-flight->@research-flight技能被触发，执行其action中定义的bash research_flight.sh命令 -> 脚本运行，输出结果 -> 结果沿调用链反向返回：技能输出给研究员，研究员整理后给总规划师，总规划师汇总所有结果，生成最终报告和日志。

这个链条体现了清晰的“决策-执行”分离。智能体负责“想”（理解和规划），技能负责“做”（执行具体命令）。

4. 实操：从零复现与运行Demo

看懂了结构，手痒想自己跑一遍？没问题，我们一步步来。这里我会补充原项目可能未提及的细节和避坑点。

4.1 环境准备与项目初始化

首先，你需要一个安装了Cursor IDE的环境。确保你的Cursor版本是比较新的（建议使用官方最新稳定版），因为Agent功能在持续迭代。

获取项目代码：
```
git clone https://github.com/yu-iskw/cursor-experiments.git cd cursor-experiments
```
或者，你也可以直接在Cursor IDE中使用“Clone Git Repository”功能。
检查关键目录：进入项目后，确认.cursor/agents/和.cursor/skills/目录存在，并且里面的文件内容完整。这是项目运行的基石。
权限设置（重要！）：由于技能要执行Shell脚本，在Unix-like系统（MacOS, Linux）或Windows的Git Bash/WSL下，需要确保脚本有可执行权限。
```
chmod +x .cursor/skills/research-flight/research_flight.sh chmod +x .cursor/skills/research-hotel/research_hotel.sh
```
踩坑提示：如果忘记这一步，在运行时会遇到Permission denied错误，智能体调用技能会失败，日志中可能只显示一个空响应或错误信息，排查起来会有点绕。

4.2 运行完整的旅行规划流程

一切就绪后，我们按照项目说明来触发整个多智能体协作流程。

打开Cursor IDE并加载项目：确保你的工作区（Workspace）是当前项目根目录。
唤出聊天面板：使用快捷键Cmd+L(Mac) 或Ctrl+L(Windows/Linux)。这是与智能体交互的主界面。
调用总规划师智能体：在聊天输入框中，你有两种方式：
- 方式一（直接@提及）：输入@trip-planner，然后空格，接着输入你的请求。
- 方式二（使用斜杠命令，如果已配置）：输入/，如果列表中出现/trip-planner，则选择它。原项目提到“if configured”，这意味着你需要在Cursor的设置中，或者通过项目的.cursor/rules文件来定义这个自定义命令。对于初次复现，直接使用@提及是最可靠的方式。
输入完整提示词：这是成功的关键。你不能只说“我想去旧金山”。必须给出清晰、结构化的指令，告诉智能体输出的具体位置和格式要求。按照示例，输入：
```
@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 and logs in @reports/plan_to_san_francisco/task_logs.md.
```
注意要点：
- @reports/...的用法：这是在提示词中直接指定输出文件的路径。Cursor智能体理解这种上下文引用，并会尝试在该路径创建或写入文件。
- 明确要求日志和图表：原提示词中要求“comprehensively and precisely leave logs”和“show a diagram of what you address the task”，这引导trip-planner在日志中生成详细的Mermaid流程图，这是观察协作过程的最佳窗口。
观察执行过程：按下回车后，静静观察。你会看到Cursor开始“思考”，聊天记录里会逐步出现各个智能体的“发言”和动作。它可能会先生成一个.plan.md文件（在.cursor/plans/目录下），然后依次调用子智能体和技能。
查看结果：
- 最终报告：打开reports/plan_to_san_francisco/trip_plan.md，你会看到一份整合了模拟航班和酒店信息的旅行计划。
- 执行日志：打开reports/plan_to_san_francisco/task_logs.md，这里记录了每一步发生了什么，以及最关键的——那个展示TripPlanner -> FlightResearcher -> ResearchFlight Skill调用关系的Mermaid图表。这张图是理解多智能体工作流的可视化总结。

4.3 实操心得与注意事项

网络与模型依赖：整个过程需要Cursor的后端AI模型（通常是GPT-4系列）参与规划和执行。确保你的Cursor账号有可用的AI额度，并且网络连接通畅。如果中途卡住或报错，可能是网络波动或模型服务暂时不稳定，重试一次即可。
文件路径的准确性：在提示词中指定输出路径时，确保路径是存在的，或者智能体有权限创建。例如，reports/plan_to_san_francisco/目录可能需要智能体自行创建，通常这没问题。但如果你指定了一个不存在的父目录，可能会失败。
理解“模拟”的本质：这个Demo中的“搜索”是通过脚本返回静态或随机文本模拟的。不要期望它真的连接到互联网去抓取实时航班信息。它的价值在于演示协作框架，而非提供真实的旅行规划服务。
智能体的“人格”稳定性：AI模型有一定随机性。不同时间运行，生成的报告详略程度、日志格式可能略有差异，但整体的协作逻辑和输出结构应该是稳定的。如果结果与预期偏差很大，检查一下智能体定义文件中的instructions是否写得足够清晰和具有约束力。

5. 深度定制：打造你自己的多智能体应用

复现Demo只是第一步。真正的乐趣在于用它作为模板，构建解决你自己问题的智能体系统。下面我们探讨几个关键的定制方向。

5.1 创建新的专属智能体

假设你想增加一个“景点推荐研究员”（attraction-researcher）。

创建智能体定义文件：在.cursor/agents/目录下新建attraction-researcher.md(或.agent.yaml)。

# .cursor/agents/attraction-researcher.agent.yaml name: attraction-researcher description: An expert in finding and recommending tourist attractions and activities in a given city. collaborators: [] # 它可以独立工作，或未来与其他智能体协作 instructions: | You are an expert travel activity researcher. When given a city name and optionally trip dates or interests, your task is to: 1. Identify popular and highly-rated tourist attractions, landmarks, and activities in that city. 2. Consider categories like museums, parks, historical sites, tours, and unique local experiences. 3. For each recommendation, provide the name, a brief description, estimated visit duration, and any useful tips (like best time to visit or booking needs). 4. Format your findings in clear markdown with sections. You do NOT book anything. You only research and provide information.

创建对应的技能：在.cursor/skills/下新建目录research-attraction，里面创建SKILL.md和一个模拟脚本。

# .cursor/skills/research-attraction/SKILL.md name: research-attraction description: Researches tourist attractions in a specified city. action: bash .cursor/skills/research-attraction/research_attraction.sh

#!/bin/bash # .cursor/skills/research-attraction/research_attraction.sh # 模拟景点搜索 CITY=$(echo $1 | tr -d '\n') # 简单获取参数，实际可能更复杂 echo “## Attraction Recommendations for $CITY” echo “- **Golden Gate Bridge**: Iconic suspension bridge, great for photos and walks. Allow 1-2 hours.” echo “- **Alcatraz Island**: Historic prison island. Requires ferry booking in advance. Allow half a day.” echo “- **Fisherman‘s Wharf**: Bustling area with seafood, shops, and sea lions. Allow 2-3 hours.”

修改总规划师：更新trip-planner的定义，在collaborators中添加attraction-researcher，并在instructions中增加关于协调景点研究的逻辑，例如：“... 3. Delegate attraction research to @attraction-researcher. 4. Compile findings from all researchers...”。

5.2 连接真实数据源（替换模拟脚本）

这是让项目从Demo变成实用工具的关键一步。以航班搜索为例，你需要将research_flight.sh脚本从“模拟”改为“真实调用”。

核心思路：在Shell脚本中，使用curl命令调用第三方API，并用jq等工具解析返回的JSON数据。

示例步骤（假设使用一个模拟的免费旅行API）：

注册并获取一个API提供商（如Amadeus、Skyscanner的开发者API，或一个模拟API服务）的密钥。

修改research_flight.sh：

#!/bin/bash ORIGIN=“NYC” DESTINATION=“SFO” API_KEY=“YOUR_API_KEY_HERE” # 重要：切勿将真实密钥提交到Git！应使用环境变量。 # 使用curl调用API RESPONSE=$(curl -s -X GET \ “https://api.example.com/flights?origin=${ORIGIN}&destination=${DESTINATION}” \ -H “Authorization: Bearer ${API_KEY}”) # 使用jq解析JSON，并格式化为Markdown echo “## Real Flight Search Results for ${ORIGIN} -> ${DESTINATION}” echo $RESPONSE | jq -r ‘.flights[] | “- **\(.airline) \(.flightNumber)**: Departs \(.departureTime) from \(.originAirport), arrives \(.arrivalTime) at \(.destinationAirport). Price: \(.price)“’

安全警告：绝对不要将API密钥等敏感信息硬编码在脚本中！应该使用环境变量。在运行Cursor前，在终端中设置export API_KEY=your_key，然后在脚本中通过$API_KEY引用。或者使用Cursor可能支持的环境变量管理方式。

5.3 设计更复杂的协作逻辑

当前的协作是简单的线性委托。你可以设计更复杂的模式：

条件分支：让trip-planner根据用户预算（“我要经济型旅行” vs “我要豪华游”）决定调用不同的酒店研究员（budget-hotel-researchervsluxury-hotel-researcher）。这需要在智能体的instructions中描述清晰的判断逻辑。
迭代循环：航班研究员第一次搜索的结果不符合时间要求，它可以被设计成自动调整参数（如日期偏移）重新搜索。这需要技能脚本支持参数化输入，并且智能体具备基于输出进行判断和循环的能力。
竞争与汇总：同时启动两个不同的航班搜索技能（比如一个查直飞，一个查中转），然后由航班研究员智能体对比结果，选出最优推荐。这展示了智能体作为“决策者”而不仅仅是“传递者”的能力。

这些高级模式对智能体instructions的编写提出了更高要求，需要你用非常精确和逻辑严密的自然语言来“编程”AI的行为。这本身就是一门值得深入研究的提示工程（Prompt Engineering）学问。

6. 常见问题排查与调试技巧

在实际操作中，你可能会遇到一些波折。这里记录了我遇到的一些典型问题及解决方法。

6.1 智能体未被识别或调用失败

症状：在聊天框输入@trip-planner没有自动补全，或者发送后AI回复说“我不知道这个智能体”。
排查步骤：
1. 检查文件位置和格式：确认智能体定义文件是否放在.cursor/agents/目录下，并且文件名正确。尝试使用.agent.yaml格式，因为Cursor对它的支持可能更稳定。
2. 重启Cursor或重载项目：有时Cursor的索引可能没有及时更新。尝试完全关闭Cursor IDE再重新打开，或者使用“File” -> “Open Folder”重新打开项目根目录。
3. 检查项目根目录：确保你的当前工作区确实是这个项目的根目录，而不是某个子目录。智能体的识别是基于当前打开的工作区。

6.2 技能执行报错（如Permission denied或命令未找到）

症状：任务日志显示技能被调用，但输出是空的或包含错误信息。
排查步骤：
1. 检查脚本权限：如前所述，在终端运行chmod +x /path/to/your_script.sh。
2. 检查脚本路径：在技能定义文件SKILL.md的action中，路径是相对于项目根目录的吗？确保路径正确。使用绝对路径或相对于项目根目录的路径更保险。
3. 手动测试脚本：在终端中，切换到项目根目录，手动执行技能定义中的完整命令（如bash .cursor/skills/research-flight/research_flight.sh）。看是否能正常运行并输出预期内容。这是隔离问题的最有效方法。
4. 检查环境差异：Cursor运行时环境可能与你的终端环境略有不同。确保脚本中使用的命令（如curl,jq,python3）在系统PATH中可用。

6.3 AI不按预期协作或遗漏步骤

症状：trip-planner没有调用子智能体，或者子智能体没有调用技能，而是尝试自己生成答案。
排查步骤：
1. 审查智能体指令（Instructions）：这是最常见的原因。指令必须极其明确和无歧义。使用“MUST”、“ALWAYS”、“DO NOT”等强约束性词语。明确写出“Delegate flight research to @flight-researcher”和“Use the @research-flight skill to perform the search”。
2. 查看生成的计划（.plan.md）：在.cursor/plans/目录下找到最新生成的计划文件。仔细阅读AI最初是如何规划这个任务的。如果计划里就没有包含调用子智能体的步骤，那说明你的提示词或智能体指令在规划阶段就没能引导正确。
3. 简化与迭代：如果协作复杂，先从最简单的场景测试。例如，先测试@flight-researcher能否独立调用@research-flight技能。成功后再让@trip-planner去调用@flight-researcher。分层调试，定位问题环节。

6.4 输出文件未生成或内容不全

症状：reports/目录下没有文件，或者文件内容只有一部分。
排查步骤：
1. 检查路径权限：确保Cursor有在项目目录下创建和写入文件的权限。
2. 检查提示词指令：在给智能体的提示词中，是否明确指定了输出文件的完整路径（如@reports/my_trip/trip_plan.md）？路径中的目录可能需要智能体创建，通常这没问题，但也可以尝试先在文件系统中创建好目录。
3. 查看完整聊天历史：在Cursor的聊天面板中，查看整个对话历史。有时AI可能会在回复中直接输出报告内容，而不是写入文件。这可能是因为文件写入指令不够明确，或者AI“认为”直接输出更合适。在指令中强调“Write to the file… Do not output the plan in the chat.”。

6.5 调试心得：像对待分布式系统一样对待多智能体

调试多智能体系统有点像调试微服务。你需要关注“服务”（智能体）间的“API调用”（@提及和指令传递）和“数据流”（输入输出）。日志（task_logs.md）是你的最佳朋友，尤其是其中由智能体生成的Mermaid图，它能直观地展示调用链路是否如你所愿。养成在关键步骤要求智能体输出状态或中间结果的习惯，这能极大提升系统的可观测性和可调试性。

7. 扩展思考与应用场景展望

通过这个旅行规划Demo，我们看到了Cursor多智能体框架的潜力。它的模式具有很强的通用性，绝不仅限于旅行规划。以下是一些可以探索的方向：

软件开发流水线：
- 代码审查助手：一个主智能体接收PR描述，调用“代码风格检查智能体”、“安全漏洞扫描智能体”、“性能分析智能体”，汇总生成综合审查报告。
- Bug诊断助手：主智能体接收错误日志，调用“日志分析智能体”、“相关代码检索智能体”、“相似案例匹配智能体”，提出可能的根本原因和修复建议。
内容创作与运营：
- 多平台内容分发：一个“内容创作核心智能体”生成一篇博客草稿，然后分别调用“SEO优化智能体”、“社交媒体摘要生成智能体”、“邮件订阅文案智能体”，一键适配不同平台。
- 竞品分析报告：主智能体协调“市场信息抓取智能体”、“产品功能对比智能体”、“用户评论情感分析智能体”，自动生成周期性竞品报告。
个人效率工具：
- 智能邮件处理：一个“收件箱管家”智能体识别邮件类型，将会议邀请转发给“日历管理智能体”，将账单转发给“财务记录智能体”，将待办任务转发给“任务列表管理智能体”。
- 学习研究助手：给定一个主题，主智能体协调“学术论文搜索智能体”、“关键概念解释智能体”、“知识图谱构建智能体”，帮你快速入门一个新领域。

这个项目的精髓在于它提供了一种范式：如何将复杂问题分解，如何为每个子问题定义专家角色，如何通过清晰的指令和技能接口将它们粘合起来。随着AI模型能力的持续进化，以及像Cursor这样的工具将智能体协作变得日益简单和可视化，构建属于你自己的、能够自动处理复杂工作的“AI团队”正在从一个科幻概念迅速变为触手可及的开发实践。