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文件中其中会描述技能的作用、输入参数和输出格式。在这个旅行规划项目中三者之间的关系构成了一个清晰的层级主智能体trip-planner接收用户原始需求理解“规划旅行”这个高层目标。子智能体flight-researcher, hotel-researcher被主智能体调用分别接收“查纽约到旧金山的航班”和“查旧金山的酒店”这样的具体指令。技能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 users 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 Frontmattercollaborates_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:451 | \$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的高级特性之一。克隆仓库在终端中将示例项目克隆到本地。git clone https://github.com/yu-iskw/cursor-experiments.git cd cursor-experiments用Cursor打开项目这很重要必须用Cursor IDE打开这个目录因为它需要读取项目根目录下的.cursor文件夹来识别智能体和技能的定义。检查智能体面板打开Cursor后在侧边栏或Chat面板中你应该能看到可用的智能体列表。如果配置正确trip-planner、flight-researcher等应该会出现。实操心得有时Cursor不会立即加载所有自定义智能体。如果没看到尝试完全关闭Cursor再重新打开项目或者检查.cursor/agents/目录下的文件格式是否正确YAML frontmatter不能有语法错误。4.2 发起一次多智能体协作请求这是最激动人心的部分。我们按照项目说明在Cursor的Chat面板中快捷键CmdL或CtrlL输入/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界面会变成一场“交响乐指挥现场”主智能体响应trip-planner首先会确认任务并开始它的“思考”。你会在聊天记录里看到它说“我将把这个任务分解并协调flight-researcher和hotel-researcher...”。自动子智能体紧接着你会发现聊天记录里自动出现了对flight-researcher的召唤和具体指令例如“flight-researcher请搜索从纽约NYC到旧金山SFO的航班选项。”子智能体调用技能flight-researcher被唤醒后它会分析指令然后调用其技能“我将使用research-flight技能参数为 originNYC, destinationSFO。”技能执行此时Cursor会在后台执行关联的Shell脚本research_flight.sh。你可能会在终端或日志中看到脚本运行如果脚本有输出。脚本的返回结果那个Markdown表格会作为消息反馈给flight-researcher。结果汇总与传递flight-researcher收到技能返回的数据后可能会进行一些格式化或总结然后将“找到3个航班选项详情如下...”的结果回复给trip-planner。并行与串行通常trip-planner会同时或近乎同时召唤hotel-researcher开启另一条并行任务线。你会在聊天记录中看到交错的对话非常像两个专家在同时向项目经理汇报。最终合成当两个子任务都完成后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代码的安全性。创建智能体文件在.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.创建配套技能在.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]} |\) 集成到工作流你可以修改trip-planner或新建一个project-manager让它collaborates_with: [code-reviewer]。然后就可以在Chat里说“project-manager请审查src/utils.py文件的安全性并生成报告。”5.2 连接真实数据源Demo中的技能脚本返回的是模拟数据。要让它实用化必须连接真实API。以酒店搜索为例连接一个模拟API如MockAPI或真实API需处理密钥修改技能脚本将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) |\安全处理密钥绝对不要将API密钥写在脚本里应该通过Cursor的环境变量或系统环境变量传入。在Cursor的设置中可以配置项目级环境变量然后在脚本中通过$ENV_VAR_NAME读取。错误处理真实脚本必须包含完善的错误处理网络超时、API限流、返回数据异常等并给智能体返回清晰的错误信息以便它能决定重试还是上报失败。5.3 设计更复杂的协作流程当前的流程是简单的“主-从”式。你可以设计更复杂的模式条件性协作让主智能体根据子任务的结果决定下一步。例如如果flight-researcher返回“机票太贵”则主智能体可以召唤一个budget-advisor来提供替代方案。迭代式优化主智能体生成初版计划后召唤一个plan-critic进行挑刺然后根据反馈进行修改形成多轮迭代。竞争与择优同时召唤两个不同的flight-researcher一个用Expedia逻辑一个用Kayak逻辑让它们分别搜索然后主智能体对比结果选择最优方案整合。实现这些的关键在于设计智能体的System Prompt让它具备评估、决策和发起新协作的能力。这需要更精细的Prompt工程。6. 常见问题、排查技巧与避坑实录在实际搭建和运行这类多智能体系统时我踩过不少坑。这里把最常见的问题和解决方案整理出来希望能帮你节省大量时间。6.1 智能体或技能未加载/不可见问题在Cursor的Chat中输入没有出现我定义的智能体名字。排查步骤检查文件位置和命名确保智能体文件在.cursor/agents/目录下且文件名与name字段一致例如trip-planner.md对应name: trip-planner。技能同理。检查YAML语法Frontmatter的---必须准确缩进使用空格而非Tab冒号后要有空格。一个微小的语法错误会导致整个文件不被识别。可以使用在线YAML校验器检查。重启Cursor这是最常用也最有效的办法。Cursor有时不会热加载.cursor目录的变更。检查项目根目录确保你是用Cursor打开的包含.cursor文件夹的那个项目根目录而不是子目录。6.2 技能脚本执行失败或无输出问题智能体调用了技能但聊天记录里没有技能的返回结果或者报错。排查步骤脚本权限在Unix-like系统上确保技能脚本如.sh文件有可执行权限chmod x .cursor/skills/research-flight/research_flight.sh。脚本路径在SKILL.md中定义的script路径是相对于项目根目录的。确保路径正确。脚本输出技能脚本的所有标准输出stdout会被作为结果返回给智能体。确保你的脚本是通过echo或print将结果输出到stdout而不是仅写入文件。调试时可以在脚本开头加set -x或在关键步骤加echo \Debug: ...\ 2输出到标准错误不影响返回结果。环境依赖如果脚本调用jq,curl或python确保这些命令在Cursor的运行环境中可用。有时IDE的环境和系统终端环境不同。6.3 智能体不按预期协作或“胡言乱语”问题主智能体没有召唤子智能体或者召唤了但指令不清导致子智能体执行错误。排查步骤精炼System Prompt智能体的行为90%由它的System Prompt决定。检查主智能体的Prompt是否清晰说明了在什么条件下、以什么格式、召唤哪个子智能体。指令要具体避免歧义。例如“Delegate the flight search to flight-researcher” 比 “Work with the flight agent” 要好得多。检查collaborates_with和uses_skills确保这些字段里的名字拼写完全正确且对应的智能体/技能确实存在。提供上下文当主智能体召唤子智能体时它传递给子智能体的消息就是“上下文”。确保这个消息包含了子智能体完成任务所需的全部信息。例如主智能体应该传递“Search for flights from NYC to SFO for next weekend”而不是简单的“Find flights”。迭代调试不要指望一次写好。采用“小步快跑”的方式先让主智能体完成一个最简单的任务如“召唤A并说你好”测试通过后再增加复杂性。6.4 处理真实API时的安全与稳定性问题问题技能连接真实API时遇到认证失败、速率限制、网络超时。解决方案表问题可能原因解决方案认证失败API密钥错误、过期或未正确传递。1. 使用Cursor环境变量存储密钥。2. 在技能脚本中通过$VAR读取。3. 在脚本中加入认证失败的判断逻辑并返回明确错误信息。速率限制短时间内调用API太多次。1. 在技能脚本中实现简单的延时sleep。2. 如果可能让智能体“思考”慢一点减少不必要的调用。3. 考虑缓存机制对相同参数的查询缓存结果。网络超时API服务不稳定或网络连接问题。1. 在curl命令中设置超时参数-m 30。2. 实现重试逻辑最多2-3次。3. 返回友好的错误信息如“酒店服务暂时不可用请稍后再试或手动查询”。返回数据格式异常API返回了非预期的JSON或HTML错误页面。1. 使用jq或python的try-catch解析前先检查HTTP状态码。2. 对解析失败的情况提供降级处理如返回“数据获取成功但解析失败原始响应...”。6.5 生成的Mermaid图表格式错误问题任务日志中的Mermaid代码无法渲染出图表或渲染出错。排查步骤检查语法Mermaid有严格的语法。确保生成的代码是有效的。常见的错误是节点标识符包含空格或特殊字符未用引号包裹。智能体生成的代码有时会缺少闭合的graph TD或使用不支持的图表类型。引导智能体在主智能体的System Prompt中提供一个非常具体的Mermaid图表示例。例如“你必须生成一个Mermaid流程图。使用以下格式作为参考mermaid graph TD A[用户请求] -- B[Trip Planner]; B -- C[Flight Researcher]; ... ”。这能极大提高生成代码的规范性。后处理如果图表只是轻微格式问题可以考虑在技能中增加一个“图表格式化”步骤用简单的文本处理工具如sed或Python脚本对智能体生成的Mermaid代码进行清洗和标准化。这个多智能体协作的Demo打开了一扇新的大门。它不仅仅是Cursor IDE的一个炫酷功能更代表了一种构建AI应用的新范式将复杂任务分解由多个专业化、可编排的AI模块协同完成。从我自己的体验来看一旦你熟悉了定义智能体和技能的套路就能迅速将这种模式应用到代码生成、系统设计、文档撰写、数据分析等无数场景中。最大的挑战和乐趣从“如何让AI理解我的一句话”变成了“如何设计一支高效的AI团队并给它们写好分工明确的岗位说明书”。这其中的设计思维和工程实践才是更有价值的部分。