课堂AI模拟系统

一个基于大语言模型的多Agent高中信息技术课堂模拟系统。

快速开始

# 1. 配置 API Key
cp .env.example .env
# 编辑 .env，填入你的 API Key

# 2. 安装依赖
pip install -e ".[dev]"

# 3. 启动 WebUI
python run_webui.py

# 或运行命令行备课
python -m classroom_simulation.main --mode prep --topic "数据采集与编码"

项目结构

classroom-sim/
├── src/classroom_simulation/
│   ├── auto_sim/          # 核心：手动编排课堂模拟
│   ├── crews/             # CrewAI 备课流程
│   ├── web/               # Streamlit WebUI
│   ├── tools/             # 工具函数
│   ├── utils/             # 工具类
│   ├── knowledge/         # 知识库
│   └── main.py            # CLI 入口
├── knowledge/             # 知识库文件
├── scripts/               # 辅助脚本
├── tests/                 # 测试
├── Dockerfile             # Docker 构建
├── docker-compose.yml     # 多服务编排
├── run_webui.py           # WebUI 启动
└── .env.example           # 环境变量模板

架构说明

备课流程（CrewAI）

使用 CrewAI Sequential Pipeline 生成教案、PPT脚本、说课稿、课堂时间线。

课堂模拟（自定义编排）

手动编排的多Agent对话循环，替代CrewAI的GroupChat：

1. 骨架生成 — 单次LLM调用生成6环节课堂骨架（5-8分钟/环节）
2. 模拟循环 — 教师和学生轮流发言，每次调用1个LLM
3. 状态管理 — 固定大小context（~1100字/轮），含时间预算、学生状态、知识覆盖
4. 时间系统 — 教师声明 [用时] + 讨论批量计时 + 环节90%阈值自动推进

关键设计

特性	实现
活动类型	讲解型(安静)/提问型(对话)/活动型(讨论)/安静型(阅读)/管理型
小组讨论	6-9轮互动 → 批量计时(总时间-2分钟汇报) → 教师指定汇报
PPT翻页	教师 [PPT页] 引用 → get_page_by_ref() 自动切换
学生模型	纯Python规则追踪理解度/注意力/挫败感（无需LLM）
问答限次	同一问题最多2人回答 → 回教师

课堂活动类型

活动	学生回应	耗时
概念讲解/PPT展示	❌ 安静	60-180秒
启发提问/互动问答	✅ 对话（最多2人）	30-90秒
分组讨论/案例分析	✅ 讨论（6-9轮）	180-600秒
阅读教材/随堂练习	❌ 安静	60-600秒
课堂小结/收尾	❌ 安静	30-180秒

修改指南

调整课堂行为

• 修改 teacher_system（main.py）中的规则编号 #1-#10
• 修改 QUIET_ACTIVITIES / NEEDS_DIALOGUE / DISCUSSION_STAGES（team.py）

调整时间系统

• 修改 _check_stage_transition 的 0.9 阈值（team.py）
• 修改 _estimate_time 的语速常数（team.py）
• 修改 max_rounds（team.py run() 方法）

调整学生模型

• 修改 StudentTracker 中的 understanding_delta 等参数（state_tracker.py）
• 修改 to_student_context() 学生看到的上下文内容

🐳 Docker 部署（推荐）

一键启动完整环境（应用 + ChromaDB 向量库）：

# 1. 准备环境变量
cp .env.example .env
# 编辑 .env，填入你的 API Key

# 2. 启动所有服务
docker compose up -d

# 3. 打开浏览器访问
open http://localhost:8501

# 4. 查看运行日志
docker compose logs -f

# 5. 停止服务
docker compose down

服务架构

┌─────────────────┐     ┌──────────────────┐
│  classsim-web   │     │  classsim-chroma │
│  :8501          │◄───►│  :8000           │
│  Streamlit UI   │     │  向量知识库       │
│  CrewAI/AutoGen │     └──────────────────┘
└────────┬────────┘
         │ (可选)
         ▼
┌─────────────────┐
│  classsim-ollama│
│  :11434         │
│  本地 Embedding │
└─────────────────┘

数据持久化

数据	存储位置	说明
备课输出	classsim_output volume	所有备课包和模拟结果
向量库	chroma_data volume	ChromaDB 持久化数据
知识库	./knowledge/ 映射	教材原文等知识文件

独立构建

# 仅构建 Web 镜像
docker build -t classsim:latest .

# 单独运行（需自备 ChromaDB）
docker run -p 8501:8501 --env-file .env classsim:latest

本地开发

# 方式一：Makefile
make dev

# 方式二：手动
uv sync
uv run streamlit run src/classroom_simulation/web/app.py --server.port 8501

# 或直接
python run_webui.py

环境要求

• Python 3.10 – 3.13
• DeepSeek / OpenAI 兼容 API Key
• Docker & Docker Compose（可选，用于容器化部署）
• Ollama（可选，用于本地 Embedding）

License

MIT License