eduSwarm 是一个基于多智能体框架构建的智能化教学辅助平台。它将AI技术应用于课件准备、作业建议、学情分析等环节，旨在辅助教师更高效地完成教学工作，帮助教师从重复性事务中解放出来，将更多精力专注于教学创新和学生个性化指导。教师始终是教学的主导者，平台仅为教学提供技术支撑。学生可通过课堂码加入，平台严格遵守相关数据安全法规，保障师生信息安全。
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 14 天前 | ||
| 15 天前 | ||
| 1 天前 | ||
| 4 天前 | ||
| 15 天前 | ||
| 13 天前 | ||
| 4 天前 | ||
| 15 天前 | ||
| 4 天前 | ||
| 4 天前 | ||
| 1 天前 | ||
| 12 天前 | ||
| 1 天前 | ||
| 14 天前 | ||
| 15 天前 | ||
| 15 天前 | ||
| 15 天前 | ||
| 1 天前 | ||
| 1 天前 | ||
| 5 天前 | ||
| 14 天前 | ||
| 13 天前 | ||
| 14 天前 | ||
| 15 天前 | ||
| 13 天前 | ||
| 13 天前 | ||
| 15 天前 | ||
| 13 天前 | ||
| 14 天前 | ||
| 15 天前 | ||
| 5 天前 | ||
| 5 天前 | ||
| 5 天前 | ||
| 5 天前 |
EduSwarm · AI智慧课堂工作台
AI 教师团队协作平台 · 备课 / 上课 / 作业 / 批改 / 学情 全流程 AI 辅助
中文 · English · 全景流程图 · 快速部署指南 · 经验分享
简介
EduSwarm 是一个基于多智能体框架构建的 AI 教师团队协作平台：把备课、上课、作业、批改、学情等教学环节，交给多位专职 AI Agent（课件师、出题官、批改师、学情分析师等）协作完成。教师从「亲力亲为」变成「做决策」，学生只需凭课堂码加入即可实时跟课。
与「单 Agent 大而全」的思路不同，EduSwarm 遵循 「先拆角色 → 再定流程 → 最后配信号」 的多智能体设计原则：每个 Agent 只做自己最擅长的一件事，由 LEADER 教研组长统一调度，知识库按 Agent 隔离、互不越界。
⚡ 极速部署体验（推荐）
不想在本机装任何环境？打开华为云 AI 办公实践中心，进入「EduSwarm · AI 智慧课堂工作台」实践，把下面这段话发给它的 AI 助手，自动完成云主机创建 + EduSwarm 容器部署，全程自动执行、无需逐步确认：
- 打开 华为云 AI 办公实践中心
- 点击 EduSwarm · AI 智慧课堂工作台 → 前往 AI DevSpace 实践
- 将下方提示词整段复制发给 AI 助手
- 部署完成后，浏览器打开
http://<云主机IP>:5173进入教师端工作台（学生同地址输课堂码加入）
提示词：
帮我创建 ECS 并部署容器，全程自动执行（plan 通过后直接 apply，无需我确认），
最后汇总各阶段耗时。
区域：cn-north-4
可用区：自动选择
计费模式：按需
ECS：s6.large.2（2vCPU/4GB），Ubuntu 22.04 server 64bit，40GB SAS 系统盘，5Mbit/s EIP
新建 VPC（192.168.0.0/16）和子网（192.168.0.0/24）
SSH 用户：root
SSH 密码：纯大小写字母+数字（不要特殊字符，避免 cloud-init 注入失败），至少 16 位
Docker：apt-get install -y docker.io docker-compose（用 Ubuntu 自带源，不要用 Docker 官方源，
GPG 密钥在华为云 ECS 内可能无法验证）
镜像：swr.cn-north-4.myhuaweicloud.com/wsm/eduswarm:latest
容器启动：
docker run -d --name eduswarm --restart=always \
-p 5173:5173 -p 18092:18092 -p 19000:19000 -p 19001:19001 -p 19200:19200 \
swr.cn-north-4.myhuaweicloud.com/wsm/eduswarm:latest
安全组放行端口（TCP）：
22 SSH
5173 Web 前端（HTTP）
18092 AgentServer（WebSocket）
19000 WebChannel（WebSocket）
19001 Gateway（WebSocket）
19200 edu REST 网关
验证：curl http://<EIP>:5173 返回 HTTP 200
耗时统计：Terraform apply、Docker 安装、镜像拉取、容器启动、总耗时
平台架构
教学 Agent 团队
| Agent | 职责 | 挂载 Skill |
|---|---|---|
| LEADER 教研组长 | 总控调度：任务分解、团队协调、质量把控与交付节奏 | lesson-planner / class-scheduler / courseware-maker |
| 课件制作师 | 教案 / 上传材料 → 8–15 页精美课件（教案 + 幻灯片 + 随堂练习 + 答案），支持 AI 优化与发布 | courseware-maker |
| 出题教师 | 按「知识点 + 题型 + 难度」命制高质量习题与作业 | quiz-generator |
| 批改教师 | 客观题自动判分，主观题 AI 批注与改进建议，生成整份课堂批改报告（HTML） | grading-assistant |
| 学情分析师 | 成绩分布统计、薄弱知识点诊断、补救路径建议，数据回流指导下一轮备课 | analyst-diagnosis |
| 主讲教师 | 教学过程实施：把自然语言描述转化为有趣的小题目与生动的课堂活动，随堂测 / 投票 / 点名 | ppt-craft-edu |
| 讨论引导员 | 抛出有分歧的讨论话题、设计引导话术、异质分组与角色轮换、同伴互评量规 | peer-discussion |
| 答疑教师 | 教师端答疑辅导：针对学生薄弱知识点提供个性化讲解与一对一辅导建议 | homework-assigner / grading-assistant |
| 答疑辅导员 | 学生端 AI 辅导员：耐心、鼓励、分层教学，一对一讲解、分层练习与即时反馈，错因回溯前置缺口并生成补差路径 | tutor-agent / learning-path / exercise-recommend |
知识图谱师（Agent）为待开发状态：暂不加入教学团队、不在团队面板出现；知识图谱相关能力（kg_build 等）在此阶段不被教研组长调度。待功能完善后开放，届时自动进入团队协作。
全部教学 Agent 自动使用工作台配置的主模型，可在 Agent 配置中心 单独覆盖模型 / 人设 / 知识库 / 挂载 Skill。
教学闭环流程
配置模型 → 创建班级 → AI 备课/生成课件 → 创建课堂（学生扫码加入）
↑ ↓
学情迭代 ← 学情诊断报告 ← 自动批改报告 ← 在线作答 ← 随堂互动授课
备课产出的知识点 / 习题数据自动沉淀到班级与学情数据中，下一轮备课直接复用 —— 形成「备课 → 上课 → 作业 → 批改 → 学情 → 备课」的教学数据闭环。
📚 个人知识库（内置 workvault）
内置了一个第三方个人知识库技能：直接对 AI 说 「把某班成绩录入知识库 / 查知识库」，它就会自动拉取班级与学生成绩，整理成 Markdown 知识库；之后可在页面或飞书群随时查询（例如 「计算机科学 大一(3)班 谁的学习情况最差？」）。
- 它是什么：结构化的 Markdown 知识库（笔记、双链、记忆）——不是 RAG 上传检索库
- 能力：run（数据转笔记）· compile（资料转 wiki）· query（带来源问答）· memory（跨会话记忆）· lint（健康检查）
- 上游仓库：https://gitcode.com/agent-best-practices/workvault
🚀 快速启动（两种方式，任选其一）
🖥️ Web 版（浏览器使用，跨平台）—— 最推荐
# Windows：双击 start-backend.bat（项目根目录）
# Linux / macOS / WSL：首次执行前 chmod +x start.sh，然后 ./start.sh
脚本自动完成：装依赖（国内镜像）→ 构建前端 → 启动服务 → 自动打开浏览器 http://localhost:5173
📦 客户端版（桌面应用，仅 Windows）—— 喜欢桌面窗口
install-desktop.bat # 一键打包安装到桌面
uninstall-desktop.bat # 想卸载时一键移除
装好后桌面出现 EduSwarm 图标，双击即用（中文界面 · 品牌启动页 · 无黑窗 · 下载自动保存）
🐳 Docker 版（Linux 服务器，用户零环境依赖）—— 目标机器无 Python/Node 时
# 用户侧（部署机）：装 Docker → 拉镜像 → 一行启动 → 浏览器访问
docker pull swr.cn-north-4.myhuaweicloud.com/wsm/eduswarm:latest # 或离线: docker load < eduswarm.tar
docker run -d --name eduswarm --restart unless-stopped \
-p 5173:5173 -p 18092:18092 -p 19000:19000 -p 19001:19001 -p 19200:19200 \
-v eduswarm-data:/data eduswarm:latest
镜像内含 Python 运行时 + 全部依赖 + 前端产物，用户无需装 Python / Node / 依赖，数据自动持久化。详细步骤见 EduSwarm快速部署指南。
脚本已内置：依赖自检自动安装（国内镜像）、Python ≥ 3.11 校验、前端自动构建、无模型也能启动（自动注入占位模型，配好真实模型即用）。全部 Python 依赖自动装入项目内
.venv虚拟环境（与系统 Python 完全隔离，删除.venv即重置）。详细步骤见 EduSwarm快速部署指南。
🏫 教室局域网：让学生端能访问（单教室同网段）
教师机跑起 EduSwarm 后，学生用浏览器访问教师机 IP 即可（无需安装、无需账号）：
| 步骤 | 操作（Windows 教师机） |
|---|---|
| 1. 固定 IP | 网络设置改为静态 IP（如 192.168.1.50，按教室网段），或路由器 DHCP 绑定教师机 MAC，避免换 IP |
| 2. 防火墙放行 | 管理员 PowerShell：New-NetFirewallRule -DisplayName "EduSwarm" -Direction Inbound -Protocol TCP -LocalPort 5173,18092,19000,19001,19200 -Action Allow |
| 3. 配局域网地址 | config.yaml 的 edu_gateway：frontend_url: http://192.168.1.50:5173、backend_url: http://192.168.1.50:19200 |
| 4. 重启生效 | start-backend.bat --stop → start-backend.bat |
| 5. 学生访问 | 浏览器打开 http://192.168.1.50:5173 → 输入课堂码 + 学号 + 姓名加入课堂 |
排障：页面打不开 →
ping 教师机IP不通是网络隔离（找 IT 或换同网段），通则检查防火墙（步骤 2）；页面能开但互动不实时 → WS 端口 19000/19001 未放行（有 1 秒轮询兜底，功能仍可用）；学生看到的链接是 localhost →frontend_url未配或改后未重启；今天能用明天断 → 教师机 IP 变了，务必固定 IP（步骤 1）。跨网段/全校部署再额外联系 IT 做网络放行。
核心能力
| 能力 | 说明 |
|---|---|
| AI 备课与课件生成 | 描述需求或上传教材（PDF/Word/PPT），AI 自动生成课件（教案 + 幻灯片 + 随堂练习 + 参考答案），支持 AI 优化与发布 |
| 实时课堂指挥中心 | 学生扫码加入，随堂测 / 投票 / 点名 / 滚动补签 / 课堂消息实时双向互动，自动统计出勤与理解度，下课自动生成课堂总结 |
| 课堂协作白板 | 教师端无限画布书写，学生端只读实时跟随，板书与课件、习题同屏呈现，随堂板书实时同步到全班 |
| 作业自动批改 | AI 按知识点 / 题型 / 难度自动出题 → 分发到课堂 → 学生在线作答 → 客观题秒判、主观题 AI 批注 → 生成课堂整份批改报告（HTML） |
| 学情分析与诊断 | 班级成绩分布、薄弱知识点诊断、补救路径建议，生成可下载的学情诊断报告，数据回流指导下一轮备课 |
| Agent 配置中心 | 管理各教学 Agent 的人设、挂载的 SKILL、模型与知识库，可创建自定义 Agent，查看调用统计 |
| Edu Skill Hub | 平台内置 17 个教学 Skill + 教育市场（Hermes 中文教育库 170+ SKILL），按需安装、挂载、删除 |
| 多 Agent 协同 | LEADER 教研组长总控调度，备课 / 出题 / 批改 / 学情等专职 Agent 并行协同，知识库按 Agent 隔离 |
| 自然语言驱动 | 对话中可直接用自然语言调起任意教学能力（备课 / 出题 / 课件 / 作业 / 批改 / 学情 / 课堂等 186+ 方法），无需记忆接口 |
| 外部 REST 接入 | 教学 Studio 提供完整 API 文档与 curl/Python 示例，外部系统（教务 / 小程序 / 脚本）带鉴权 Key 调用 Agent 能力 |
| 一键部署与桌面版 | 双击脚本自动装好 Python/Node/依赖（国内镜像）并启动；install-desktop.bat 打包桌面版（中文界面 + 品牌启动页 + 真实加载进度 + 无黑窗，仅 Windows），uninstall-desktop.bat 一键卸载 |
快速启动
一键部署（推荐）
start-backend.bat（Windows）/ start.sh（Linux / macOS / WSL）内置依赖自检：自动检测并安装 Python 包与前端依赖（国内镜像加速）、设置数据目录、校验 Python ≥ 3.11、前端构建产物缺失自动构建、未配模型自动注入占位保证页面可开，随后一键启动全部服务并自动打开浏览器。
# Windows：双击 start-backend.bat（项目根目录）
# Linux / macOS / WSL：首次执行前 chmod +x start.sh，然后 ./start.sh
常用参数：--install 强制补装依赖 / --dev 前端热更新 / --foreground 前台调试 / --stop 停止服务 / --background 后台（完整说明见 EduSwarm快速部署指南）。
虚拟环境隔离（自动）
start-backend.bat / start.sh 会把全部 Python 依赖自动安装到项目内的 .venv 虚拟环境，与系统 Python 完全隔离：不污染全局环境、版本跟随本仓库锁定、与其他项目互不干扰；想重置环境，删除 .venv 后重新启动脚本即可自动重建。
-
首次启动：自动创建
.venv并安装依赖（联网走国内镜像，约 2-5 分钟），之后每次启动均为秒开 -
离线快速安装（可选）：在有网机器上提前把全部依赖下载到本地：
python -m pip freeze > requirements-offline.txt python -m pip download -r requirements-offline.txt -d offline_wheels把
offline_wheels/放到项目根目录后，脚本检测到会自动改为本地安装（--no-index --find-links），全程不联网——适合教室 / 内网等无外网环境分发（offline_wheels为 Windows + Python 3.12 专用，其他平台需各自生成一份）。
启动完成后浏览器打开 http://localhost:5173 即可进入教师端工作台。
1. 安装依赖（Python ≥ 3.11）
# 推荐使用 uv（与框架一致）；pip 亦可
uv pip install -e ./openjiuwen_src
uv pip install -e .
# 或 pip：
pip install -e ./openjiuwen_src
pip install -e .
前端依赖（首次启动前端前）：
cd jiuwenswarm/channels/web/frontend
npm install
2. 配置数据目录（重要）
数据目录决定技能 / 配置 / 数据读写位置，必须指向仓库内资源，否则会落到默认目录 ~/.jiuwenswarm：
# Windows（cmd）:
set JIUWENSWARM_DATA_DIR=D:\EduSwarm\jiuwenswarm\resources
# Windows（PowerShell）:
$env:JIUWENSWARM_DATA_DIR = "D:\EduSwarm\jiuwenswarm\resources"
# Linux / macOS:
export JIUWENSWARM_DATA_DIR=/path/to/eduswarm/jiuwenswarm/resources
start-backend.bat/start.sh会自动设置数据目录，手动启动时才需要上面的环境变量。
3. 生成配置文件
cp jiuwenswarm/resources/config/config.example.yaml jiuwenswarm/resources/config/config.yaml
# 可选：若需 REST 网关鉴权，把 config.yaml 中 edu_gateway.api_key 的
# ${EDU_GATEWAY_API_KEY} 替换为真实 Key，或设置环境变量：
export EDU_GATEWAY_API_KEY=你的网关Key
模型 Key 不需要在这里配：首次启动后按界面引导「配置模型」添加主模型即可（见下），配置会自动写入 config.yaml 并同步到所有教学 Agent。
4. 手动启动
python -m jiuwenswarm.start_services
前端开发模式（可选，热更新）：
start-dev.bat
# 等价命令
cd jiuwenswarm/channels/web/frontend && npx vite --host
服务端口一览
| 端口 | 服务 | 说明 |
|---|---|---|
| 5173 | Web 前端 | 教师端 / 学生端页面（学生链接自动跟随本项目端口） |
| 18092 | AgentServer WS | Agent 实时通道 |
| 19000 / 19001 | Gateway WS | 消息网关 |
| 19200 | edu REST 网关 | 外部应用调用 Agent（可选 Key 鉴权） |
学生端 / 飞书推送中的链接、前端 REST 请求都会自动跟随本项目实际端口，多实例部署互不串台；手机等局域网设备访问时，在 config.yaml 的
edu_gateway段配置frontend_url/backend_url（如http://192.168.x.x:5173/...:19200）即可。
快速上手
- 配置模型：首次打开工作台 → 按引导第一步「配置模型」→ 添加主模型（模型名称 / API 地址 / API Key / 提供商）。所有教学 Agent 自动选择该主模型，之后可在 Agent 配置中心单独覆盖
- 创建班级：班级管理 → 创建班级 → 添加学员（学号 + 姓名名册）
- 生成课件：课件中心 → 新建课件 → 自由描述或上传教材，AI 自动生成
- 创建课堂：课堂管理 → 创建课堂 → 选择班级与知识点，学生凭课堂码加入
- 上课：授课指挥中心 → 开始上课 → 随堂测 / 投票 / 点名 / 白板板书（学生端实时只读跟随），下课自动总结
- 作业闭环：作业中心 → AI 出题 → 分发 → 学生在线作答 → 自动批改 → 批改报告
- 学情迭代：学情看板 → 生成诊断报告 → 据此调整下一轮备课
- 扩充技能：Edu Skill Hub → 教育市场 → 从 Hermes 中文教育库按需安装（首次打开自动克隆仓库到本地缓存，之后自动增量更新）
目录结构
eduswarm/
├── openjiuwen_src/ # openjiuwen 框架源码（多智能体运行时 / SDK）
├── jiuwenswarm/ # EduSwarm / 工作台主体
│ ├── channels/web/frontend/ # 教师端 / 学生端 Web 前端（React + Vite）
│ ├── extensions/edu_platform/ # EduSwarm 教学扩展（edu_backend + REST 网关 + Agent 工具）
│ ├── agents/ # 多智能体运行时（教师团队协作 / Harness）
│ ├── server/ # AgentServer / 网关服务端
│ ├── gateway/ # Web / 飞书 / 钉钉等渠道网关
│ ├── resources/config/ # 配置（config.yaml 不入库，config.example.yaml 模板入库）
│ ├── resources/agent/ # Agent 配置 / 教学 SKILL（运行时数据不入库）
│ └── resources/config.yaml # 全新克隆时的默认模板（占位符走环境变量）
├── docs/ # 框架文档（zh/en，jiuwenswarm/openjiuwen 使用文档与配图）
├── scripts/ # 构建 / 启动辅助脚本
├── packages/ # 打包相关（TUI 等）
├── jiuwenbox/ # 沙箱 / 执行环境（可选组件）
├── desktop_app.py # 桌面端入口（可选）
├── desktop_splash.html # 桌面版启动页（品牌 splash + 加载进度）
├── start-backend.bat # Windows 一键启动
├── start-dev.bat # Windows 前端开发模式
├── install-desktop.bat # 桌面版打包安装（Windows）
├── uninstall-desktop.bat # 桌面版一键卸载（Windows）
├── start.sh # Linux / macOS 一键启动
├── requirements-offline.txt # 离线依赖清单（用 pip download 重新生成 offline_wheels）
├── offline_wheels/ # 可选：预下载的依赖（脚本自动检测，免联网安装）
├── EduSwarm全景流程图.html # 完整流程 · 多 Agent 架构 · 三方调用 · 一节课的旅程
├── EduSwarm架构图.svg # 平台架构图（五层：教师端 → LEADER → 教学 Agent → 学生/接入 → 支撑）
├── EduSwarm快速部署指南.md # 快速部署文档（照着做就能跑）
├── EduSwarm经验分享.md # 多智能体设计思路与踩坑经验
├── 教案_C语言顺序结构程序设计.md # ┐
├── 教案_Python程序设计.md # ├ 内置教案示例——可直接作为课件生成的输入
├── 教案_大学计算机基础.md # │ （在「任务」对话里说"根据《教案_Python程序设计》生成课件"）
├── 教案_数据结构.md # ┘
└── README.md / README_CN.md # 项目首页（本文件）
文档导览
| 文档 | 说明 |
|---|---|
| EduSwarm 快速部署指南 | 从零开始的完整部署步骤，照着做就能跑 |
| EduSwarm 经验分享 | 多智能体设计思路、关键决策与踩坑经验，适合想了解"为什么这么做"的读者 |
| EduSwarm 全景流程图 | 完整流程 · 多 Agent 架构 · 三方调用 · 一节课的旅程（浏览器打开，可交互） |
| docs/zh | 框架中文文档（安装 / 配置 / 频道 / 技能 / Agent 团队 / Harness 等） |
| docs/en | Framework English docs |
| 教学操作指引 | 教师端左下角「操作提示」按钮（分步引导） |
贡献
欢迎开发者参与 EduSwarm 的建设：提交 Bug / 功能建议 / 代码 / 文档。
License
本项目基于 Apache License 2.0 开源。
EduSwarm 作为教学辅助工具，不替代教师的专业判断；接入 AI 模型用于教学场景时，请遵守相关法律法规与数据合规要求。