从零跑通「AI 校园活动策划天团」:用 WorkSwarm 多智能体把活动策划做成流水线
从零跑通「AI 校园活动策划天团」:用 WorkSwarm 多智能体把活动策划做成流水线
项目地址:https://gitcode.com/agent-best-practices/ai-campus-event-planner 本文是一篇上手教程:从装 WorkSwarm 到跑出一份完整策划案(4 份交付物),全程可复制。 一句话理解这个项目:给一句活动信息,4 个 AI 角色并行开工,7 分钟交出一套可交付的活动策划包。
读完这篇你能做到什么
装 WorkSwarm → 克隆仓库 → 部署知识库与 Skills → 配团队 → 启动
→ 发一句"校园歌手大赛,校级,500人,11月15日,体育馆" → 拿到 4 份交付物
产出的是四件真实文件:预算明细 Excel、风险预案 Excel、宣传 PPTX、整合 HTML 方案。不是聊天记录,是能直接交给老师/赞助商的东西。
前置条件清单
| 依赖 | 版本 | 用途 |
|---|---|---|
| WorkSwarm | 最新版 | 多智能体框架 |
| Python | 3.8+ | Excel 生成脚本 |
| openpyxl | 最新版(pip install openpyxl) |
预算/风险 Excel |
| Node.js | 20+ | dashi-ppt 渲染 PPTX |
| npm | 随 Node.js | dashi-ppt 依赖 |
| OpenAI 兼容 API | 任意(GLM/DeepSeek/Qwen…) | LLM 推理 |
只有 WorkSwarm + 1 个模型 API + Python + openpyxl 也能跑(少一份 PPTX),见第 11 步的降级方案。
第 1 步:认识 WorkSwarm 与它的配置目录
WorkSwarm 是什么(由 openJiuwen 团队维护的开源多智能体协作框架):
- 多 Agent 团队:定义 Leader + 多个专业 Agent,按任务 DAG 协作
- Skill 机制:每个 Agent 绑定一个
SKILL.md定义行为规则 - 多渠道接入:Web、飞书、钉钉、Telegram、Discord、企业微信
- 多模型支持:OpenAI 兼容 API,不绑定特定模型
- 团队持久化:团队可长期保活、跨会话复用
安装后,配置目录因平台而异,下文统一用 <JWS_HOME> 代指:
| 平台 | 路径 |
|---|---|
| Windows | C:\Users\<用户名>\.workswarm\ |
| macOS | /Users/<用户名>/.workswarm/ |
| Linux | $HOME/.workswarm/ |
目录结构(记住两个关键位置,第 4、5 步要用):
<JWS_HOME>/
├── config/config.yaml # 全局配置(模型/团队/渠道/权限)
├── agent/workspace/skills/ # 全局技能目录(5 个 SKILL.md 放这里)
├── agent/workspace/ # 工作区(知识库和 config.json 放这里)
└── .agent_teams/ # 团队运行时数据(自动生成)
官方仓库:https://gitcode.com/openJiuwen/jiuwenswarm
第 2 步:克隆仓库,看清谁干什么
git clone https://gitcode.com/agent-best-practices/ai-campus-event-planner.git
cd ai-campus-event-planner
下文用 <PROJECT_ROOT> 代指这个目录。仓库里有五类东西:
| 目录 | 内容 | 作用 |
|---|---|---|
zhishiku/ |
4 个 PDF 知识库 | 各 Agent 的"标准手册"(预算标准/风险标准/文案标准/统筹流程) |
skills/ |
5 个 Skill | 4 个 Agent + 1 个 PPT 引擎 |
config.json |
路径配置 | 知识库与输出目录的统一入口 |
scripts/ |
install_nodejs.sh |
Node.js 一键安装(含兜底) |
output/ |
输出目录 | 运行时生成:预算/、风险预案/、宣传物料/ |
知识库是按 Agent 隔离的——每个角色只读自己那本 PDF。这是设计上的刻意选择:避免所有 Agent 都去检索全部知识库,既慢又互相干扰。
第 3 步:搞懂架构(这一步决定你后面会不会用错)
活动统筹总指挥 (Leader) — Skill: event-orchestrator
├─ 1. 预算会计 — Skill: budget-accountant → 预算明细 Excel(2 个 Sheet)
├─ 2. 风险顾问 — Skill: risk-advisor → 风险预案 Excel(8 个 Sheet)
└─ 3. 宣传文案师 — Skill: promotion-copywriter → 宣传 PPTX + 最终 HTML 方案
执行模式:三模块并行 → 文件路径传递 → HTML 整合
PPT 风格:A 声波霓虹风 | B 黑金实验风 | C 玻璃糖风 | D 轻拟态风
任务依赖是一个并行扇出 + 单点汇总的 DAG:
budget (并行) ─┐
risk (并行) ─┼─→ final_html (整合)
promotion (并行) ─┘
三个模块互不依赖(预算只需类型+级别+人数,风险多需场地+日期,宣传只需名称+类型+级别),所以能真正并行;final_html 会被自动阻塞到三者完成。
三个关键设计决策,理解它们才能理解这个项目为什么快:
- Leader 不干具体活:只做解析、建 DAG、收集产出、委派。因为 Leader 的 SKILL.md 已经要塞下"信息提取 + 信号协议 + 性能优化三规则",再塞预算计算就会 Prompt 超长、质量下降。
- 宣传文案师兼任 HTML 整合:文案数据最先就绪,HTML 模板和
gen_html.py也在它自己的resources/里——谁有数据谁执行。 - 人设(persona)全员可见,prompt_hint 仅自己可见:前者用于团队协作时的角色认知,后者(含 config.json 读取规则、信号格式)只注入该成员的 system prompt。
第 4 步:部署知识库与 config.json
为什么必须单独拷一次:Skills 运行时是从 workspace 目录读 zhishiku/ 和 config.json 的,不是从仓库根目录。漏了这步,知识库读取必然失败——这是最常见的部署失败原因。
# Linux / macOS
WS="$HOME/.workswarm/agent/workspace"
cp -r "<PROJECT_ROOT>/zhishiku" "$WS/zhishiku"
cp "<PROJECT_ROOT>/config.json" "$WS/config.json"
# Windows PowerShell
$ws = "$env:USERPROFILE\.workswarm\agent\workspace"
Copy-Item -Path "<PROJECT_ROOT>\zhishiku" -Destination "$ws\zhishiku" -Recurse -Force
Copy-Item -Path "<PROJECT_ROOT>\config.json" -Destination "$ws\config.json" -Force
config.json 长这样,确认路径与实际文件一致即可:
{
"knowledge_base": {
"base_dir": "zhishiku/",
"leader": "zhishiku/南华理工大学活动统筹全流程知识库(Leader总指挥Agent专属).pdf",
"budget": "zhishiku/南华理工大学 校园活动预算标准知识库(预算会计Agent专属).pdf",
"risk": "zhishiku/南华理工大学 校园活动风险与应急预案知识库(风险顾问Agent专属).pdf",
"promotion": "zhishiku/南华理工大学 校园活动宣传文案标准知识库(文案师Agent专属).pdf"
},
"output": {
"base_dir": "output/",
"budget": "output/预算/",
"risk": "output/风险预案/",
"promotion": "output/宣传物料/",
"html": "output/"
}
}
路径三条规则(这是这个项目跨平台能力的核心):
- 所有路径都写在
config.json里,SKILL.md 里不写死路径,只写"读取config.json中knowledge_base.budget获取知识库路径" - 路径全部用正斜杠
/,Windows/macOS/Linux 通吃 - 路径相对于项目根目录(即
config.json所在目录)
换环境只要换这一个文件:
| 场景 | 操作 |
|---|---|
| 本地开发 | 用默认 zhishiku/、output/ |
| Linux 生产 | 改成 /data/event-planner/zhishiku/ 等 |
| Docker 容器 | 挂载 config.json,改成 /app/zhishiku/ 等 |
第 5 步:部署 5 个 Skills
拷到 WorkSwarm 全局技能目录(<JWS_HOME>/agent/workspace/skills/):
# Linux / macOS
SRC="<PROJECT_ROOT>/skills"
DST="$HOME/.workswarm/agent/workspace/skills"
for s in event-orchestrator budget-accountant risk-advisor promotion-copywriter dashi-ppt; do
cp -r "$SRC/$s" "$DST/$s"
done
五个 Skill 的分工:
| Skill | 核心职责 | 知识库/资源 |
|---|---|---|
event-orchestrator |
总调度:解析输入、并行激活三模块、收集产出、委派 HTML 整合 | 统筹流程知识库 |
budget-accountant |
检索预算标准 → 匹配级别算费用 → 生成预算 Excel(2 Sheet) | 预算知识库 + gen_budget_excel.py |
risk-advisor |
检索风险标准 → 识别四类风险 → 生成风险预案 Excel(8 Sheet) | 风险知识库 + gen_risk_excel.py |
promotion-copywriter |
检索宣传标准 → 生成文案 + 委派时生成 PPTX 与最终 HTML | 宣传知识库 + gen_html.py + HTML 模板 |
dashi-ppt |
PPTX 渲染引擎(promotion-copywriter 依赖它) | npm 项目 |
第 6 步:装 Node.js 20+ 与 dashi-ppt 依赖
dashi-ppt 需要 Node.js 20+。仓库自带一键安装脚本(三重兜底:包管理器 → 下载二进制 → 只读文件系统兜底):
bash <PROJECT_ROOT>/scripts/install_nodejs.sh
node --version # 应 >= v20
然后装 dashi-ppt 的 npm 依赖(只需一次):
cd <SKILLS_DIR>/dashi-ppt/project
npm install
cd <PROJECT_ROOT>
网络慢就用国内镜像:
npm install --registry=https://registry.npmmirror.com
装不上时的排查顺序:① node --version 确认 ≥20 → ② curl -I https://registry.npmjs.org/ 确认网络 → ③ 换国内镜像 → ④ 仍失败就走第 11 步降级,跳过 PPTX。
第 7 步:配置团队(config.yaml)
在 <JWS_HOME>/config/config.yaml 里配三样东西:模型、团队、渠道。
模型走 .env 注入环境变量(这样模型名不硬编码在配置里,换模型只改环境变量):
# .env
BUDGET_MODEL=deepseek-chat
RISK_MODEL=deepseek-chat
COPY_MODEL=deepseek-chat
LEADER_MODEL=deepseek-chat
模型分配策略:按任务特性分配,不必都上最强的。预算/风险是"检索+计算",用稳定的即可;文案/PPT 更需要表达力;Leader 需要强指令遵循。多模型不可用时,全部填同一个也行。
渠道方面:不配飞书就用 Web 界面(功能一致);配了飞书记得在渠道配置里开 send_file_allowed: true,否则 Agent 无法把生成的 4 个文件发给你。
第 8 步:启动并发出第一个需求
启动后在对话里直接给活动信息,例如:
校园歌手大赛,校级,500人,11月15日,体育馆
Leader 的交互逻辑值得单独看——它的目标是"最大限度减少交互轮次":
活动菜单引导:如果你输入得很模糊(比如"搞个活动"),Leader 会先展示类别菜单(歌唱/体育/文艺/学术/文化)和输入示例,而不是让你面对空白框发呆。菜单数据在 resources/activity_menu.json,运行时读取,不硬编码。
信息提取三步法(核心交互逻辑):
| 步骤 | 动作 | 示例(输入"校园歌手大赛,800人") |
|---|---|---|
| Step 1 扫描 | 提取已有字段 | 名称=校园歌手大赛,人数=800 |
| Step 2 推断 | 推断缺失字段 | 800>200 → 级别=校级;含"歌手" → 类型=歌手大赛 |
| Step 3 仅问缺失 | 只问仍缺的 | "请问举办日期和场地是?" |
原则一句话:能提取的不推断,能推断的不询问,绝不重复提问。
PPT 四风格(不选则按活动类型自动匹配):
| 选项 | themePack | 风格 | 适用 |
|---|---|---|---|
| A | theme12 | 声波霓虹风 | 音乐/文艺/歌唱 |
| B | theme08 | 黑金实验风 | 正式大型活动/体育 |
| C | theme04 | 玻璃糖风 | 创意/院系活动 |
| D | theme01 | 轻拟态风 | 通知/简报/班级 |
第 9 步:验收(4 份交付物 + 预期耗时)
跑完后应该在 output/ 下拿到:
| 交付物 | 目录 | 内容 |
|---|---|---|
| 预算明细 Excel | output/预算/ |
2 个 Sheet(9 列明细 + 分类小计 + 合计、汇总 + 占比) |
| 风险预案 Excel | output/风险预案/ |
8 个 Sheet(风险识别/分级研判/排查清单/处置预案/组织架构/物资清单/变更规范/复盘方案) |
| 宣传 PPTX | output/宣传物料/ |
按选定风格渲染 |
| 整合 HTML 方案 | output/ |
单文件,含各模块摘要与下载链接 |
各模块预期耗时(心里有数就不会误判卡死):
| 模块 | 耗时 |
|---|---|
| 预算 | ~2 min |
| 风险 | ~3.5 min |
| 宣传文案数据(Phase 1) | ~3 min |
| PPTX 渲染(Phase 2) | ~7–10 min |
第 10 步:性能优化的三条规则(本项目的核心创新)
这三条写在 event-orchestrator 的 SKILL.md 里,标注为 MANDATORY。它们把总耗时从 ~14 分钟压到 ~7 分钟:
规则 1:路径传递,非内容传递。 子任务只报告输出文件路径 + 摘要(如"总预算:7960元"),不传输文件内容。早期尝试直接传 Excel 二进制或完整 HTML 源码,直接撞上 API 参数超限(400 Bad Request)。而且——先完成的子任务会立即把路径发给整合 Agent 预填充模板,不必等所有任务都完成。
规则 2:完成即待命,禁止跨域询问。 成员完成自己的任务后进入 standby,不主动问别人的进度。所有跨模块协调都由 Leader 发起。实测:预算会计在 final_html 已指派给文案师后还发了一条"协调询问",白白增加 2 次通信。多 Agent 系统里,"好心办坏事"比"各扫门前雪"更浪费资源。
规则 3:瓶颈解耦——文案数据与 PPTX 渲染分离。 PPTX 渲染是瓶颈(~7–10 min),文案数据只要 ~3 min,而 HTML 整合只需要文案数据、不需要 PPTX 文件本身。于是拆成两阶段:
- Phase 1:快速生成文案 JSON(~3min),立即返回
COPY_DATA_READY,供 HTML 整合 - Phase 2:异步渲染 PPTX,完成后返回
TASK_COMPLETE,把下载链接补进 HTML
效果对比:
| 阶段 | 优化前(串行等待) | 优化后(并行 + 解耦) |
|---|---|---|
| 预算 | 2 min | 2 min(并行) |
| 风险 | 3.5 min | 3.5 min(并行) |
| 文案数据 Phase 1 | — | 3 min(并行,立返 JSON) |
| PPTX 渲染 Phase 2 | 10 min(阻塞后续) | 7 min(异步,不阻塞 HTML) |
| HTML 整合 | 1 min(等 PPTX 完成) | 1 min(等文案 JSON 即可) |
| 总计 | ~14 min | ~7 min(降 50%) |
第 11 步:降级方案(别让缺一个依赖毁掉整条流程)
系统依赖分三层:核心层(WorkSwarm + LLM + Python)、增强层(openpyxl → Excel)、可选层(Node.js → PPTX、飞书 → IM)。缺哪层降哪层,而不是直接报错退出:
| 缺失依赖 | 影响 | 降级方案 | 输出文件数 |
|---|---|---|---|
| Node.js 20+ / npm | PPTX 无法生成 | 仍输出预算 Excel + 风险 Excel + HTML;HTML 里 PPTX 链接置灰标注 | 3 份 |
| openpyxl | Excel 无法生成 | 改用 CSV 输出(需改脚本),PPTX + HTML 正常 | 3 份 |
| 飞书应用 | 飞书渠道不可用 | 用 Web 界面,功能一致 | 4 份 |
| 只有 1 个模型 | 多模型不可用 | 所有角色用同一模型 | 4 份 |
| 无外网 | npm install 失败 | 用离线 npm 包或跳过 PPTX | 3 份 |
最小可用配置:WorkSwarm + 1 个 LLM API + Python 3.8+ + openpyxl,即可产出 3 份文件,不需要 Node.js。
附录 A:11 个实测坑(挑最有价值的)
| # | 坑 | 根因与解法 |
|---|---|---|
| 1 | DAG 创建顺序 | 同时创建带依赖的任务会因"依赖目标不存在"失败。必须按拓扑序分两步:先建三个并行任务,成功后再建 final_html |
| 2 | 成员 idle ≠ 卡死 | 成员在读 SKILL.md、解析 PDF、算账,期间状态就是 idle。不要催促、不要重发启动消息(会导致重复执行) |
| 3 | 跨域询问 | 成员"帮忙"问别的模块进度 → 无效通信。在成员 SKILL.md 里写 Communication Behavior Constraints,列明 PROHIBITED / REQUIRED |
| 4 | 传内容 vs 传路径 | 传文件内容会 400。只传路径 + 摘要 |
| 5 | PPTX 渲染瓶颈 | 两阶段返回(Phase 1 文案 JSON,Phase 2 异步 PPTX),总耗时 14→7 min |
| 6 | 脚本不要内联写 | 用 write_file 写 200+ 行 Python 会参数超限。规则是"脚本预置 + 小幅修改 + 直接执行",改动每次 <2000 字符 |
| 7 | 路径硬编码 | 硬编码 Windows 绝对路径导致 Linux 全失效。统一进 config.json |
| 8 | HTML 模板必须只读 | 模板与产物同目录时,Agent 可能"自作聪明"改坏模板,导致之后每次都基于坏模板生成。SKILL.md 里用 🚨 CRITICAL 标注 READ-ONLY |
| 9 | 禁用 ask_user 卡片 | 结构化卡片打断多 Agent 对话节奏,且选项可能漏掉用户真实意图。改用普通文字列出缺失字段 |
| 10 | HTML 模板归属 | 模板放 Leader 下会导致 Leader 既当项目经理又当前端,SKILL.md 膨胀。迁到 promotion-copywriter,Leader 只委派 |
| 11 | 演进机制 | 每个 Skill 配 evolutions.json + evolution/*.md,执行前先看 Experience Index,命中匹配经验就先读详情——让 Skill"越用越聪明" |
附录 B:一页纸构建清单
- 拆角色(Leader / 预算 / 风险 / 宣传)
- 定流程(DAG:三并行 → 一整合)
- 设计交互(活动菜单 + 信息提取三步法 + PPT 四风格 + 禁用 ask_user)
- 选模型(按任务特性分配,环境变量管理,不绑定特定模型)
- 写 Skill(5 个 SKILL.md + 3 个脚本 + 1 个 HTML 模板 + dashi-ppt 依赖)
- 配信号(ACTIVATE / TASK_COMPLETE / COPY_DATA_READY / HTML_PLAN)
- 备知识库(4 个 PDF,按 Agent 隔离)
- 写 config.json(知识库 + 输出路径,相对路径,全平台兼容)
- 配演进(evolutions.json + evolution/*.md)
- 配团队(config.yaml:成员 + 模型 + 渠道
send_file_allowed: true) - 建输出目录(预算 / 风险预案 / 宣传物料)
- 规划降级(缺 Node.js / openpyxl / 飞书时怎么办)
- 验证(发一条活动信息,确认 4 份文件都出来了)
常见问题(FAQ)
Q:为什么注册/部署不用敲一堆命令? 因为部署指南本身就是写给 WorkSwarm 读的——你可以把仓库地址丢给 WorkSwarm 的对话框,让它照着指南自动配置。
Q:一定要用飞书吗? 不。不配飞书就用 Web 界面,功能完全一致。但无论哪个渠道,要记得允许发送文件,否则拿不到那 4 份产物。
Q:知识库能换成我们学校的吗? 可以,这正是 zhishiku/ + config.json 设计的用途。你只要准备 4 本对应标准的 PDF(统筹流程 / 预算标准 / 风险标准 / 文案标准,都要含校级/院级/班级三档),然后改 config.json 的路径即可,不用改任何 SKILL.md。
Q:为什么我的 Excel/PPTX 没生成? 按第 11 步的降级表对号入座——最可能是缺 openpyxl(Excel)或 Node.js <20(PPTX)。
Q:能扩展到别的场景吗(比如公司团建、婚礼策划)? 可以。角色拆分(统筹/预算/风险/文案)是通用的,改的是知识库内容和活动菜单。作者也提出过与"面试天团"模式的对比,这套 DAG 是"并行扇出+单点汇总",不是所有场景都适用。
结语
「AI 校园活动策划天团」真正值得学的,不是"AI 能写策划案",而是它把多 Agent 协作的工程细节都解决了:
- 职责边界:Leader 不干活,谁有数据谁执行
- 通信协议:结构化信号而非自然语言,传路径而非传内容
- 性能设计:并行扇出 + 瓶颈解耦(14min → 7min)
- 跨环境能力:一个 config.json 切换本地/生产/Docker
- 容错:分层降级,缺依赖不阻塞主流程
这些经验写在两份文档里(部署指南 1000+ 行、经验分享 450+ 行),含 11 个真实踩坑记录——比代码本身更有复用价值。如果你要做任何多 Agent 流程编排,建议先读那份"经验分享"。
参考资料:项目 README.md、AI校园活动策划天团 — 快速部署指南.md、多Agent协同AI校园活动策划天团 — 经验分享.md、config.json;文中耗时与踩坑结论均为项目内记录的真实执行数据。
- 点赞
- 收藏
- 关注作者
评论(0)