SmartClass Agent 是一个专为教师设计的智能教学助手，通过对话式交互帮助教师完成从教学设计到课件生成的全流程工作。系统基于 LangGraph 编排动作式对话入口、教学需求收集、RAG 检索、教学设计与产物生成，并提供长期记忆、版本管理、差量修改等高级特性。
- 💬 对话式交互：自然语言描述教学需求，Agent 自动理解并生成内容
- 🎨 多模态输入：支持文本、图片、语音、视频等多种输入方式
- 📚 知识库增强：RAG 检索个人教学资料，生成个性化教学内容
- 🔄 版本管理：产物支持多次迭代修改，保留完整版本链
- 🧠 长期记忆：记住教师偏好和教学经验，持续优化生成效果
graph LR
A[教师输入需求] --> B[对话入口 Agent]
B -->|普通对话| C[直接回答]
B -->|教学设计动作| D[对话式收集教学需求]
B -->|产物修改动作| E[识别修改目标]
D --> R[教学要素确认]
R --> F[RAG 与教学经验并行准备]
F --> G[生成教学设计]
G --> H[并行生成产物]
H --> I[PPT 课件]
H --> J[DOCX 教案]
H --> K[HTML 互动内容]
E --> L[加载当前版本]
L --> M[差量修改]
M --> N[生成新版本]
- 教学设计：根据学科、年级、主题自动生成教学目标、重难点、教学方法
- 课件生成：自动生成 PowerPoint 课件（.pptx），支持标题页、目录页、内容页、总结页
- 教案生成：自动生成 Word 教案（.docx），包含完整的教学流程和活动设计
- 互动内容：生成 HTML 互动小游戏、演示页面，提升课堂参与度
- RAG 向量检索：基于 PGVector 的知识库检索，支持 PDF、DOCX、TXT 等格式
- 附件分析：自动分析图片、文档内容，提取关键信息融入教学设计
- 视频转写：抽取视频音频、转写文本、提取关键帧、生成画面描述
- 用户画像：记忆教师背景、教学风格、学生特点
- 经验积累：记录成功的教学案例、学生反馈、效果评价
- 语义检索：根据当前话题智能召回相关经验，辅助决策
- 差量修改：基于当前版本进行局部调整，保留原有内容
- 版本链追溯：完整记录修改历史，支持版本回退
- 多产物并行：同时生成 PPT、DOCX、HTML，独立修改互不干扰
- Workspace 隔离：每次执行独立工作区，防止路径遍历和数据泄露
- 代码执行限制：超时、输出截断、依赖拦截，确保安全
- 资源归属校验：所有资源按用户隔离，严格权限控制
- 结构化日志：关联
run_id、thread_id、user_id，支持全链路追踪 - JSONL Trace：每日归档，便于离线分析
- Prometheus 指标：请求量、错误率、响应时间、Token 消耗
- OpenTelemetry：分布式追踪，集成 Jaeger、Zipkin、Honeycomb
后端
- 框架：FastAPI + Uvicorn
- Agent：LangChain + LangGraph
- 数据库：PostgreSQL + PGVector
- 运行事件：Redis Streams（断线重连、游标回放、实时输出快照）
- 存储：Local / MinIO 对象存储
- 认证：JWT Bearer
- 可观测：OpenTelemetry + Prometheus
前端
- 框架：Vue 3 + Vite
- UI 组件：Element Plus
- 状态管理：Pinia
- 文件预览：OnlyOffice Document Editor
- 实时通信：SSE (Server-Sent Events)
┌─────────────────────────────────────────────────────────┐
│ Frontend │
│ Vue 3 + Element Plus + Pinia + OnlyOffice │
└────────────────┬────────────────────────────────────────┘
│ SSE Events (metadata, token, progress, artifact)
│ REST API (auth, file, memory, session)
┌────────────────┴────────────────────────────────────────┐
│ FastAPI Backend │
│ ┌──────────────────────────────────────────────────┐ │
│ │ LangGraph Agent Workflow │ │
│ │ ┌─────────┐ ┌─────────┐ ┌──────────────┐ │ │
│ │ │ Entry │→ │ Intake │→ │ RAG + Memory │ │ │
│ │ │ Agent │ │ Agent │ │ Context │ │ │
│ │ └─────────┘ └─────────┘ └──────────────┘ │ │
│ │ ↓ ↓ ↓ │ │
│ │ ┌─────────────────────────────────────────┐ │ │
│ │ │ Teaching Design Planner │ │ │
│ │ └─────────────────────────────────────────┘ │ │
│ │ ↓ ↓ ↓ │ │
│ │ ┌──────┐ ┌──────┐ ┌──────────┐ │ │
│ │ │ PPT │ │ DOCX │ │ HTML │ │ │
│ │ │ Gen │ │ Gen │ │ Game │ │ │
│ │ └──────┘ └──────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Redis Streams│ │ LangGraph │ │
│ │(生命周期快照)│ │ (运行事件) │ │ Store │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MinIO / │ │ Workspace │ │ Observability│ │
│ │ Local FS │ │ (隔离执行) │ │ (日志/指标) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
| 模块 | 文件 | 职责 |
|---|---|---|
| 认证权限 | app/core/auth.py |
JWT 认证、密码哈希、用户归属校验 |
| 存储服务 | app/core/storage.py |
统一存储抽象，支持 Local/MinIO |
| 对话流程 | app/core/graph.py |
LangGraph 主流程，60+ KB |
| 运行事件 | app/core/chat_run_events.py |
Redis Streams 发布、回放、快照与保留策略 |
| Agent Runtime | app/core/agent.py |
Agent 执行、工具集成，91 KB |
| 长期记忆 | app/core/memory.py |
Profile/Experience 记忆管理 |
| RAG 检索 | app/core/rag.py |
向量检索、文档分块 |
| Workspace | app/core/workspace.py |
隔离工作区、代码执行，43 KB |
| 可观测性 | app/core/observability.py |
日志、指标、Trace，40 KB |
主图节点、interrupt、SSE、记忆边界和回滚开关详见 主 LangGraph 对话编排。
- Python 3.11+
- Node.js 20.19+ 或 22.12+
- PostgreSQL 14+（已安装 PGVector 扩展）
- Redis 7.4+（必须启用 AOF，并使用
noeviction） - 可选：MinIO（对象存储）、Prometheus（指标监控）
git clone --recurse-submodules https://github.com/cyone123/SmartClass-Agent.git
cd SmartClass-Agent如果已经克隆过主仓库：
git submodule update --init --recursivecd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt复制 .env.local.example 到 .env 并修改：
cp .env.local.example .env核心配置：
# 数据库
DATABASE_URL=postgresql://user:password@localhost:5432/smartclass
# 持久对话 Run 的实时事件存储（必需）
REDIS_URL=redis://localhost:6379/0
# LLM API (OpenAI 兼容)
MODEL=your-model-name
API_KEY=your-api-key
BASE_URL=your-base-url
# JWT 密钥（生产环境必须修改）
JWT_SECRET_KEY=your-secret-key-change-in-production
# 存储后端（local 或 minio）
STORAGE_BACKEND=local
FILE_STORAGE_ROOT=../storage
# 可选：MinIO 对象存储
# STORAGE_BACKEND=minio
# MINIO_ENDPOINT=localhost:9000
# MINIO_ACCESS_KEY=minioadmin
# MINIO_SECRET_KEY=minioadmin
# MINIO_BUCKET=smartclass
# 可选：可观测性
OBSERVABILITY_ENABLED=true
OBSERVABILITY_TRACE_JSONL_ENABLED=true
PROMETHEUS_ENABLED=false
OTEL_ENABLED=false# 创建数据库和扩展
psql -U postgres -c "CREATE DATABASE smartclass;"
psql -U postgres -d smartclass -c "CREATE EXTENSION IF NOT EXISTS vector;"python run_server.py后端将运行在 http://localhost:8000
cd frontend
npm installnpm run dev前端将运行在 http://localhost:5173
打开浏览器访问 http://localhost:5173
默认账号（首次启动自动创建）：
- 用户名：
admin - 密码：
admin12345
- 登录后进入"知识库管理"
- 上传教学资料（PDF、DOCX、TXT）
- 等待索引完成（状态变为"已就绪"）
- 在对话中 Agent 将自动检索相关内容
# 准备环境文件：
cp .env.docker.example .env.docker
# 构建并启动所有服务
docker compose --env-file .env.docker up -d --build
# 停止服务
docker compose --env-file .env.docker down服务访问：
- 前端：
http://localhost:8080 - 后端：
http://localhost:8000 - Prometheus：
http://localhost:9090 - MinIO：
http://localhost:9000
smartclass-agent/
├── backend/ # 后端服务
│ ├── app/
│ │ ├── api/ # API 路由
│ │ ├── core/ # 核心模块（graph, agent, memory...）
│ │ ├── models/ # SQLAlchemy 模型
│ │ ├── services/ # 业务逻辑层
│ │ └── schemas/ # Pydantic 模型
│ ├── skills/ # Skill 定义
│ ├── storage/ # 文件存储（本地模式）
│ ├── tests/ # 单元测试
│ └── run_server.py # 启动脚本
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── api/ # API 调用
│ │ ├── components/ # Vue 组件
│ │ ├── store/ # Pinia 状态
│ │ └── views/ # 页面
│ └── vite.config.js
├── docs/ # 模块文档
├── docker-compose.yml # Docker Compose 配置
├── CLAUDE.md # AI 开发规范
└── README.md
- 定义数据模型：
backend/app/models/ - 实现业务逻辑：
backend/app/services/ - 添加 API 路由：
backend/app/api/ - 集成 LangGraph 节点：
backend/app/core/graph.py - 前端界面开发：
frontend/src/views/
cd backend
pytest tests/Python：
- 使用
black格式化 - 遵循 PEP 8 规范
- 类型注解（Type Hints）
Vue：
- 使用
<script setup>语法 - Composition API
- 遵循 Vue 3 风格指南
我们欢迎所有形式的贡献！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
- 🐛 Bug 修复：提交 Issue 并附上复现步骤
- ✨ 新功能：先在 Issue 讨论设计方案
- 📝 文档改进：修正错误、补充示例
- 🎨 UI/UX 优化：改进用户体验
- 🧪 测试覆盖：增加单元测试、集成测试
- 提交信息：遵循 Conventional Commits
feat:新功能fix:Bug 修复docs:文档更新refactor:代码重构test:测试相关
- 代码审查：所有 PR 需至少一人审查
- 测试要求：核心功能需有测试覆盖
- 基础对话流程
- 教学设计生成
- PPT/DOCX/HTML 产物生成
- 知识库 RAG 检索
- 长期记忆系统
- 产物版本管理
- 评估数据集构建
- Grafana 仪表盘模板
- 多语言支持（英文）
- 多模型支持（Claude、Gemini、Qwen）
- 协作编辑（多教师共享知识库）
- 移动端适配
- 插件系统
- SaaS 部署方案
SmartClass Agent 基于以下优秀的开源项目构建：
- LangChain - LLM 应用框架
- LangGraph - Agent 状态图编排
- FastAPI - 现代 Python Web 框架
- Vue.js - 渐进式前端框架
- PostgreSQL - 开源关系型数据库
- PGVector - PostgreSQL 向量扩展
特别感谢所有贡献者的付出！
本项目采用 MIT License 开源协议。
- Issue Tracker：GitHub Issues
- 讨论区：GitHub Discussions
- 邮件：zsh.xyz@foxmail.com
⭐ 如果这个项目对你有帮助，请给我们一个 Star！
Made with ❤️ by SmartClass Team