jiuwenSwarm 多智能体协同实战经验分享 — 基于 AI 校园活动策划天团案例
一、项目背景与工具选型
1.1 为何选择 AI 赋能校园活动策划
高校活动策划长期面临三大痛点：策划方案质量参差不齐、预算编制缺乏科学标准、风险预案往往流于形式。引入 AI 技术进行策划，核心思路是通过知识库驱动实现流程标准化，借助多维度并行覆盖，最终将量化预算、分级风险管控和合规文案整合为一体输出。
1.2 单 Agent 执行策划的局限性
试想让一个 Agent 同时承担预算计算、风险识别、文案创作、PPT 生成乃至 HTML 整合任务——结果必然是 Prompt 臃肿不堪，注意力分散，每个模块都无法深入，更谈不上并行处理。根本原因在于，真实的活动策划本质上是多专业协作：财务、安全、宣传各司其职，单一 AI 包揽全部工作，天然违背了这一协作本质。
1.3 多智能体协同的必要性
解决思路其实很清晰：让多个专业 AI 各司其职，协同完成复杂策划任务。具体映射关系为——项目总指挥对应活动统筹 Leader Agent，财务专家对应预算会计 Agent，安全专家对应风险顾问 Agent，宣传专家对应宣传文案师 Agent。与面试天团的串行流水线不同，活动策划天然适合并行模式：预算、风险、宣传三个模块互不依赖，完全可以同时启动。
1.4 jiuwenSwarm 框架简介
这是一个开源的多智能体协同框架，核心功能涵盖：多 Agent 团队管理、Skill 约束机制（SKILL.md）、任务 DAG 编排、多模型分配、多渠道接入（飞书/Web/钉钉），以及团队持久化能力。
1.5 本文分享要点
本文将重点探讨：设计思路（角色拆解、流程设计、信号通信）、实现方法（Skill 编写、模型配置、知识库搭建）、踩坑经验、选择 jiuwenSwarm 的原因，以及与串行模式的对比分析。
二、构建思路详解
2.1 核心设计原则
先拆解角色，再确定流程，最后配置信号。这一设计起点与面试天团一致，但流程拓扑完全不同。
2.2 第一步：角色拆解
- 活动统筹总指挥（Leader）：负责统筹协调，解析用户输入，创建任务 DAG，收集产出。关键约束：不执行具体模块。
- 预算会计：从知识库检索预算标准，计算全部费用，生成 Excel。不负责风险或文案。
- 风险顾问：从知识库检索风险标准，识别四类风险，生成应急预案 Excel。不负责预算或文案。
- 宣传文案师：从知识库检索宣传标准，生成全套文案 + PPTX + 最终 HTML 整合方案。不负责预算或风险。
几个关键决策点：
- Leader 不执行具体模块——避免注意力分散，专注协调
- 三个模块并行执行——预算/风险/宣传互不依赖，天然并行
- 宣传文案师兼任 HTML 整合——因为 HTML 模板在其 resources 目录下，且文案数据最先就绪
2.3 第二步：流程定义
通过任务 DAG 声明依赖关系：
budget (并行) ─┐
risk (并行) ─┼─→ final_html (整合)
promotion (并行) ─┘与面试天团的串行 DAG（破冰→技术→HR→报告）相比，本案例采用典型的并行扇出 + 单点汇总模式。框架自动管理状态流转：三个任务同时处于 pending 状态，被各自成员认领后并行执行，final_html 被自动阻塞直至三者全部完成。
2.4 第三步：信号配置
采用结构化信号通信替代自然语言，优势在于精确解析、自动提取文件路径、可审计，且 prompt 更简洁：
ACTIVATE|BUDGET_ACCOUNTANT|{类型}|{级别}|{人数}— Leader 激活预算模块ACTIVATE|RISK_ADVISOR|{类型}|{级别}|{人数}|{场地}|{日期}— Leader 激活风险模块ACTIVATE|PROMOTION_COPYWRITER|{名称}|{类型}|{级别}— Leader 激活宣传模块TASK_COMPLETE|BUDGET_ACCOUNTANT|{名称}|{级别}|{总预算}|{Excel路径}— 预算完成TASK_COMPLETE|RISK_ADVISOR|{名称}|{级别}|{风险摘要}|{Excel路径}— 风险完成TASK_COMPLETE|PROMOTION_COPYWRITER|COPY_DATA_READY|{名称}|{JSON路径}|{摘要}— 文案数据就绪TASK_COMPLETE|PROMOTION_COPYWRITER|HTML_PLAN|{HTML路径}— HTML 方案就绪
三、具体构建实操
3.1 Skill 设计要点
SKILL.md 包含以下内容：Role、Persona、Core Responsibilities、Knowledge Base、Signal Protocol、Workflow、Performance Optimization Rules。建议控制在 8-15 KB。
关键设计细节：
- 知识库路径和输出路径通过 config.json 统一管理，SKILL.md 运行时读取配置，不硬编码任何路径
- Excel 生成脚本预置在 scripts/ 目录，Agent 直接执行而非内联写代码
- HTML 模板预置在 resources/ 目录，只读不修改
- 每个 Skill 定义"完成后进入待命"的通信约束
3.2 模型分配策略
根据任务特性选择模型，而非一刀切：
- Leader（event-orchestrator）：强推理 + 长上下文，协调并行流程 → glm-5.2
- 预算会计：精确计算 + Excel 生成，无需强创意 → deepseek-v3.2
- 风险顾问：全面分析 + 多 Sheet 生成，需要逻辑严密 → glm-5
- 宣传文案师：创意文案 + PPTX + HTML 整合，需要强语言能力 → glm-5.1
3.3 知识库设计
每个 Agent 仅访问自身所需的知识库，互不交叉：
- Leader → 统筹流程知识库（活动分级、时间线模板）
- 预算会计 → 预算标准知识库（场地/设备/奖品/人力价格表）
- 风险顾问 → 风险标准知识库（风险分级、四类风险、应急预案模板）
- 宣传文案师 → 宣传标准知识库（文案规范、核心六要素、分阶段模板）
知识库隔离的优势显而易见：prompt 更精简、内容不串味、可独立更新、并行检索无竞争。
路径管理方面：所有知识库路径和输出路径写入 config.json，SKILL.md 运行时读取配置字段（如 knowledge_base.budget、output.budget），不硬编码任何路径。换环境只需替换 config.json，无需修改 SKILL.md。
3.4 人设与提示词的区分
- persona（全员可见）：角色身份描述，1-2 句，例如"严谨的财务专家，精打细算、分毫不差"
- prompt_hint（仅自己可见）：详细行为规则，包含从 config.json 读取路径的规则、信号格式、脚本使用方式
3.5 异常处理设计
SKILL.md 必须明确边界处理逻辑：
- 知识库检索失败：输出 ERROR|KNOWLEDGE_BASE_NOT_FOUND，通知 Leader
- Excel 脚本执行失败：读取错误信息，通过 edit_file 小幅修复后重试，不重写整个脚本
- PPTX 渲染失败：确认 Node.js 已安装、dashi-ppt 依赖完整、npm 命令正确
- 模块间数据传递：只传文件路径不传内容，避免 API 参数超限
3.6 性能优化三规则（核心创新）
这部分是本次案例最重要的架构创新，源自实际执行中的经验积累：
规则1：路径传递，而非内容传递
- 子任务仅报告输出文件路径 + 摘要，不传输文件内容
- 先完成的子任务立即发给整合 Agent 预填充模板
- 整合任务只等待缺失的文件路径，不等待所有任务完成
- 实测效果：预算 2 分钟完成→立即发给文案师预填充，风险 3.5 分钟完成→继续填充，只需等待文案数据
规则2：完成后即待命，禁止跨域询问
- 成员完成任务后进入 standby，不主动询问其他模块状态
- 所有跨模块协调由 Leader 发起
- 违规示例：预算会计完成后询问 HTML 整合进度→产生 2 条无效消息→禁止
规则3：瓶颈解耦，文案数据与 PPTX 渲染分离
- PPTX 渲染是主要瓶颈（约 10 分钟），文案数据生成仅需约 3 分钟
- Phase 1：快速生成文案 JSON，立即返回供 HTML 整合
- Phase 2：异步执行 PPTX 渲染，完成后补入 HTML 下载链接
- 实测效果：总耗时从约 14 分钟降至约 7 分钟
四、架构模式总结
4.1 本案例模式
并行扇出 + 文件路径汇总 + 瓶颈解耦。核心特点：三个模块同时执行、文件路径传递结果、先完成先整合、PPTX 异步不阻塞 HTML。
4.2 与面试天团模式对比
| 维度 | 面试天团 | 活动策划天团 |
|---|---|---|
| 执行模式 | 串行流水线 | 并行扇出 |
| 通信控制 | 单发话人（一次一个 Agent） | 多 Agent 同时执行 |
| 数据传递 | 信号传递评分数据 | 文件路径传递产出 |
| 整合方式 | 逐级汇总（技术→HR→综合） | 单点汇总（三模块→HTML） |
| 瓶颈处理 | 无（各环节耗时相近） | 瓶颈解耦（PPTX 异步） |
| 总耗时 | 各环节时间之和 | max(预算,风险,宣传)+整合 |
4.3 其他支持模式
- 串行流水线：严格顺序，单点通信
- 对抗校验：两 Agent 互查结果
- 动态增减：按需 spawn 新成员
- HITT：真人作为团队成员参与
4.4 选择建议
- 模块间无依赖 → 并行扇出（本案例）
- 模块间有严格顺序 → 串行流水线
- 能用 DAG 就不用硬编码 if-else
- 能用结构化信号就不用自然语言
- 能 Skill 隔离就不要塞进一个 prompt
- 有明显瓶颈环节 → 解耦为快慢两阶段
五、踩坑经验与避坑指南
5.1 任务 DAG 创建顺序
第一个坑就出在这里。创建有依赖关系的任务时，必须先创建无依赖的并行任务，再创建依赖任务。如果同时创建带 depended_by 的任务，会因"依赖目标不存在"而失败。解法很简单：分两步创建——先创建三个并行任务（无依赖），再创建 final_html（depends_on 三者）。
5.2 成员 idle 是正常状态
成员启动后不会立即回复，需要时间查看任务、检索知识库、执行工作。idle ≠ 卡死。经验就是：不要催促 idle 成员，不要重发启动消息。只有长时间无进展且未汇报阻塞时才介入。
5.3 跨域询问的通信浪费
成员完成自身任务后，主动询问其他模块的任务状态（比如预算会计问 HTML 整合进度），产生无效通信轮次。解法是在 SKILL.md 中明确写入"完成后进入待命，不主动询问非自身专业领域的任务状态"。
5.4 文件路径 vs 文件内容
早期尝试在消息中传递完整文件内容，结果 API 参数超限（400 Bad Request）。解法是只传文件路径 + 摘要。整合 Agent 直接读取本地文件，不在消息中传输内容。
5.5 PPTX 渲染瓶颈
PPTX 生成（npm render + export）约需 7-10 分钟，是系统主要瓶颈。如果等 PPTX 完成再开始 HTML 整合，总耗时约 14 分钟。解法是两阶段返回——Phase 1 快速生成文案 JSON（约 3 分钟）返回供 HTML 整合，Phase 2 异步渲染 PPTX。总耗时降至约 7 分钟。
5.6 Excel 脚本安全规则
用 write_file 写大段 Python 代码会导致工具参数超限（400 Bad Request）。解法是脚本预置在 scripts/ 目录，直接执行 python scripts/gen_xxx.py。需要自定义时用 edit_file 小幅修改变量后重新执行。
5.7 知识库路径管理
早期将知识库路径硬编码在 SKILL.md 中（比如 D:zhishikuxxx.pdf），存在两个问题：① Windows 绝对路径在 Linux/macOS 下不可用；② 更换环境需修改每个 SKILL.md 代码。解法是创建 config.json 统一管理所有路径（知识库 + 输出目录），SKILL.md 运行时读取配置。更换环境只需替换 config.json，无需修改任何 SKILL.md。路径用正斜杠 / 兼容全平台。
5.8 HTML 模板只读
整合 Agent 可能误修改模板文件，导致后续生成全部异常。解法是在 SKILL.md 中明确标注"模板文件 READ-ONLY，NEVER 修改"，脚本只读取模板生成新文件。
5.9 绝对路径硬编码（跨环境失效）
初版 SKILL.md 中硬编码了 Windows 绝对路径（比如 D:zhishikuxxx.pdf、D:活动策划方案预算），导致：① Linux/macOS 下路径不存在，知识库检索失败；② 更换部署环境需逐个修改 4 个 SKILL.md 中的数十处路径，极易遗漏。解法是引入 config.json 统一管理所有路径，SKILL.md 改为运行时读取配置字段（如 config.json knowledge_base.budget）。路径统一用正斜杠 / 相对路径，全平台兼容。换环境只需替换一个 config.json 文件，零代码改动。
六、一页纸清单
- 拆角色（预算/风险/宣传/整合）
- 定流程（画 DAG：三并行→一整合）
- 选模型（按任务特性分配）
- 写 Skill（5 个 SKILL.md + 3 个脚本 + 1 个模板，含 dashi-ppt 依赖）
- 配信号（ACTIVATE/TASK_COMPLETE/COPY_DATA_READY）
- 备知识库（4 个 PDF，按 Agent 隔离）
- 写 config.json（知识库路径 + 输出路径，相对路径，全平台兼容）
- 配团队（config.yaml：3 成员 + 5 agent 模型）
- 配渠道（飞书/Web，send_file_allowed:true）
- 建输出目录（预算/风险预案/宣传物料，路径与 config.json 一致）
- 验证（发送活动信息测试全流程）
七、为什么选择 jiuwenSwarm
7.1 我们要解决的问题
多专业角色并行、任务 DAG 依赖管理、文件路径协调、知识库隔离、瓶颈解耦、多格式输出（Excel + PPTX + HTML）。这些问题单 Agent 完全无法满足。
7.2 核心助攻
- 多 Agent 团队：3 个专业 Agent 并行执行
- Skill 约束：每个 Agent 行为由 SKILL.md 严格定义
- 任务 DAG：自动管理并行 + 依赖 + 阻塞 + 解锁
- 多模型分配：不同 Agent 用不同模型优化性价比
- 多渠道接入：飞书/Web/钉钉，支持文件发送
- 团队持久化：跨会话复用，长期保活
- 信号协议：结构化通信，精确解析
- 配置文件管理：config.json 统一管理路径，跨环境切换零代码改动
7.3 对比其他方案
- 单 Agent：角色混乱，无法并行，Prompt 爆炸
- 手写编排：无 DAG 管理，无模型分配，无 Skill 约束
- LangChain：缺 Skill 约束/持久化/团队模式
- jiuwenSwarm：声明式配置 + Skill 约束 + 多模型 + 多渠道 + 持久化 + 任务 DAG，开箱即用
7.4 与面试天团的互补价值
面试天团验证了串行流水线 + 单发话人控制模式；活动策划天团验证了并行扇出 + 文件路径协调 + 瓶颈解耦模式。两者共同证明 jiuwenSwarm 可以灵活支持不同协同拓扑。
