jiuwenSwarm 多 Agent 协同经验分享 — 基于 AI 校园活动策划天团案例

一、背景与软件

1.1 为什么做 AI 校园活动策划

解决高校活动策划三大痛点：策划方案质量参差不齐、预算编制凭经验无标准、风险预案流于形式。AI策划实现知识库驱动标准化、多维度并行覆盖、量化预算+分级风险+合规文案一体化输出。

1.2 单 AI 做策划的困境

单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 第三步：配信号

结构化信号通信，不用自然语言：

• 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方案就绪

优点：精确解析、自动提取文件路径、可审计、prompt更简单。

三、具体怎么构建

3.1 Skill 设计要点

SKILL.md包含：Role、Persona、Core Responsibilities、Knowledge Base、Signal Protocol、Workflow、Performance Optimization Rules。建议控制在8-15KB。

关键设计：

• 知识库路径和输出路径通过 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预填充模板
• 整合任务只等待缺失的文件路径，不等待所有任务完成
• 实测效果：预算2min完成→立即发给文案师预填充，风险3.5min完成→继续填充，只需等文案数据

规则2：完成即待命，禁止跨域询问

• 成员完成任务后进入standby，不主动询问其他模块状态
• 所有跨模块协调由Leader发起
• 违反示例：预算会计完成后询问HTML整合进度→产生2条无效消息→禁止

规则3：瓶颈解耦，文案数据与PPTX渲染分离

• PPTX渲染是主要瓶颈（~10分钟），文案数据生成只需~3分钟
• Phase 1：快速生成文案JSON，立即返回供HTML整合
• Phase 2：异步执行PPTX渲染，完成后补入HTML下载链接
• 实测效果：总耗时从~14min降至~7min

四、架构模式总结

4.1 本案例模式

并行扇出 + 文件路径汇总 + 瓶颈解耦。特点：三模块同时执行、文件路径传递结果、先完成先整合、PPTX异步不阻塞HTML。

4.2 与面试天团模式对比

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（~3min）返回供HTML整合，Phase 2异步渲染PPTX。总耗时降至~7min。

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 文件，零代码改动。

六、一页纸清单

1. 拆角色（预算/风险/宣传/整合）
2. 定流程（画DAG：三并行→一整合）
3. 选模型（按任务特性分配）
4. 写Skill（5个SKILL.md+3个脚本+1个模板，含dashi-ppt依赖）
5. 配信号（ACTIVATE/TASK_COMPLETE/COPY_DATA_READY）
6. 备知识库（4个PDF，按Agent隔离）
7. 写config.json（知识库路径+输出路径，相对路径，全平台兼容）
8. 配团队（config.yaml：3成员+5agent模型）
9. 配渠道（飞书/Web，send_file_allowed:true）
10. 建输出目录（预算/风险预案/宣传物料，路径与config.json一致）
11. 验证（发送活动信息测试全流程）

七、为什么选择 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可灵活支持不同协同拓扑。