# SmartKBS 智慧教学平台
**Repository Path**: shinebug/smartkbs
## Basic Information
- **Project Name**: SmartKBS 智慧教学平台
- **Description**: 全学段全学科通用 AI 智慧教学平台。AI 对话与智能学伴、智能题库与组卷导出 Word、在线考试自动批改、课堂互动抢答闯关、分组讨论 AI 助教、学情分析与成长档案、积分称号激励，50+ 功能模块。FastAPI + React 构建，深度集成通义千问与 DeepSeek，支持私有化部署。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: http://youufis.oicp.net:8086
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 39
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# SmartKBS — 智慧教学平台
> **🌐 [中文](README.md) | [English](README.en.md)**
>
> **面向小学、初中、高中三个学段的 AI 智慧教学平台** — 学科、年级、班级均由配置驱动，**不限定任何一门学科**。
>
> 覆盖 **教 · 学 · 练 · 评 · 管** 五条主线，46 个功能分区按主线归为六章，共 50+ 功能点：
>
> - 🏠 **入口 · 首页与待办** — 智能仪表盘、学生待办清单
> - 🧑🏫 **教 · 教学与资源** — 课程大纲、AI 教学助手、智能题库、在线考试、智能组卷与 Word 导出、AI 资源推荐、AI 生成 HTML 资源、资源中心与管理、文件中心
> - 🎓 **学 · 学习与练习** — AI 对话（知识问答）、AI 学伴、课程练习、同步练习、错题巩固、每日精选与热点新闻、代码练习
> - 🎪 **练 · 课堂活动** — 随堂测验、课堂投票、提问管理、知识抢答、分组讨论、协作白板、智能点名与考勤、知识闯关、对话作业
> - 📊 **评 · 学情分析与激励** — AI 学情分析、AI 课堂总结、进度与活动监控、数据导出、成长档案、12 级称号与成就徽章、自动积分奖励
> - ⚙️ **管 · 系统管理** — 用户与权限、系统公告、通知中心、技能管理、系统配置、AI 自我画像、在线增量升级、多主题外观
>
> 基于 **FastAPI + React** 构建，接入阿里云 DashScope（通义千问 / 通义万相）与 DeepSeek；SSE 流式输出与 WebSocket 实时链路支撑课堂并发，数据全部落在本地 SQLite 与本地目录，可完全离线部署。
---
## 目录
- 📋 [项目简介](#intro) · 💡 [核心设计理念](#philosophy) · 🎮 [演示环境](#demo) · ✨ [功能总览](#overview)
- 📦 [更新日志](#changelog) · 🚢 [部署安装指引](#deployment) · 🚀 [快速开始](#quickstart) · 📁 [项目结构](#structure)
- 💾 [数据存储](#storage) · 👥 [权限总览](#permissions) · 🔧 [技术栈](#tech-stack) · 📄 [许可证](#license) · ❓ [常见问题](#faq) · 📬 [关于](#about)
**功能分章**：[首页与待办](#ch-home) · [教学与资源](#ch-teach) · [学习与练习](#ch-learn) · [课堂活动](#ch-practice) · [学情分析与激励](#ch-assess) · [系统管理](#ch-manage)
---
> 📌 **V8.6.0 更新亮点**（2026-10-05 ~ 10-09）
>
> - 🔊 **语音合成与点名播报落地**：音色清单只保留实测可发声的项，多音姓氏自动校正，关闭即零计费、不新增依赖
> - 🧭 **配置不再靠猜**：模型候选集中维护、配置页改下拉，生图与语音各加自检按钮，尺寸按实测边界过滤，配错在保存时即拦下
> - 🧱 **题目入库只留一道关口**：原先 9 处各写各的落库路径合并成一个出口（体检 → 查重 → 单事务 → 连知识点边），不合格题与重复题不再进库
> - 🔁 **凑题只留一份策略**：题库优先 → 缺口交 AI → AI 题必须入库才返回；抢答不再凑重复题，组卷可勾选「缺口补差」（默认关）
> - 📏 **题量说话算数**：随堂测验与页面出题的题量都成为真实入参，越界报错而不是偷偷改数
> - 🎨 **协作白板可用性与实时链路重做**：连不上会说清原因、结束可重开、慢学生不再拖住全班、断线自动重连
> - ⏱ **AI 出题不再一口气赌满超时**：输出上限按题量给，超时预算按接入地址分段重试，超时报错会说清等了多久、试过哪个域名
> - 📊 **看板观感与统计口径** + 📱 **手机适配落地** + 🖼 **配图链路治理** + 🏆 **积分防刷** + 🛡 **运维与配置体验**
---
## 项目简介
**SmartKBS** 把备课出题、课堂互动、练习考试、学情分析、荣誉激励和系统运维收敛在同一套账号体系与数据链路里，供一所学校、一个教研组或一位任课老师直接使用，无需拼装多个工具。
系统**不限定学科**。学科清单、年级、班级、题型、称号、AI 模型与提示词模板全部来自配置（`backend/system_config.json` 与数据库主数据表），切换课程体系只改配置、不改代码。平台自身就是从「人工智能」一门课起步、再泛化为多学科通用版式，因此「零学科硬编码」是落地结论而非宣传语。
系统内置**小学、初中、高中**三个学段的年级与班级主数据（一年级 ~ 高三，共 12 个预置年级），教师可持有「高一|高二」这样的多年级任教范围，所有数据读写按任教范围收口。幼儿与高校场景没有内置学段规则，需自行扩展年级主数据。
AI 能力经统一调用服务接入，支持三种模式，并按优先级自动接管、逐级降级：
1. **知识库检索增强（RAG）** — 知识库就绪时接管整条 AI 链路：先检索（百炼知识库，或本地题库与课程大纲），再基于命中文本生成，界面标注引用来源；检索失败自动降级到下一级
2. **百炼智能体应用** — 直接调用配置好的智能体应用
3. **直接调用大模型** — 兜底路径，兼容 DashScope 与 DeepSeek
> 📦 **三种部署方式**：Windows 桌面版一键安装（零环境，不需要 Python / Node.js）· 源码包部署 · Git 克隆部署（支持在线增量升级）。详见[部署安装指引](#deployment)。
## 核心设计理念
- **🧠 AI 原生，但题库优先**
AI 嵌在出题、批改、答疑、分析、板书的具体环节里，而不是外挂一个聊天框；同时能靠已有数据解决的绝不重复调用模型——出题与组卷一律「题库优先 → 缺口交 AI → AI 生成的题必须入库留用」，让每一次算力消耗都沉淀成可复用的资产。
- **🎯 因材施教 · 千人千面**
学生端 AI 学伴按自选人格（鼓励型 / 严谨型 / 幽默型）、连续出错的薄弱知识点与学习画像调整回答风格和推荐内容；教师端 AI 助手按任教范围与学科给出备课辅助与学情洞察。
- **🔄 教学闭环 · 数据飞轮**
学习行为采集 → AI 分析 → 个性化反馈 → 行为改善构成闭环：考试、练习、对话、点名的数据回流成学生画像，画像再反哺下一轮的 AI 决策与推荐。
- **⚡ 按需调用，无人使用零消耗**
所有 AI 调用按需触发：精选池用完才补、热点新闻缓存懒加载、AI 摘要不访问不生成、语音合成关闭即零计费。不为闲置算力付费。
**产品特性**
| 特性 | 落地方式 |
| --- | --- |
| 👥 三层角色，各配其 AI | 学生用 AI 学伴陪伴式学习，教师用 AI 助手减负增效，管理员掌握配置与督导，互不干扰 |
| 🏆 游戏化激励 | 12 级称号 + 成就徽章 + 自动积分奖励引擎，把外部压力换成持续正反馈 |
| 🌐 配置驱动 · 学科无关 | 换学科只改配置与提示词模板，无需修改代码 |
| 🔒 本地化优先 | 双 SQLite 库 + 本地目录存数据，可完全离线部署；AI 走国内可达通道，pip 有镜像方案，学生数据不出校 |
| 📱 零安装多端 | 手机浏览器直接访问，无需 App、无需额外部署 |
| 🖥️ 桌面版一键装 | Electron 壳 + 内置后端与前端产物，目标机器不需要 Python / Node.js |
| ⬆️ 在线增量升级 | Git 部署可站内完成拉取、迁移、依赖安装、重启，失败自动回滚 |
## 演示环境
| 用途 | 地址 |
| --- | --- |
| 开发环境 | [http://youufis.oicp.net:8086](http://youufis.oicp.net:8086) · [https://youufis.oicp.net:8085](https://youufis.oicp.net:8085) |
| 部署环境 | [http://183.239.51.37:8086](http://183.239.51.37:8086) · [https://183.239.51.37:8085](https://183.239.51.37:8085) |
**测试账号**
| 角色 | 用户名 | 密码 |
| --- | --- | --- |
| 教师 | `youufis` | `ultraultra` |
| 学生 | `s11001` ~ `s11009` | `123456` |
| 学生 | `s18001` ~ `s19009` | `123456` |
> ⚠️ **共享演示环境**：所有访客共用同一个数据库，里面是测试数据，且他人可见你的操作痕迹。请勿填入真实学生姓名、真实成绩或学校涉密资料。
## 功能总览
六章各对应一条主线，前言里的六行与本表逐条对应（🏠 入口是跨主线的聚合层）：
| 主线 | 章 | 覆盖的分区 | 数量 |
| --- | --- | --- | :---: |
| 🏠 入口 | [首页与待办](#ch-home) | 智能仪表盘、学生待办清单 | 2 |
| 🧑🏫 教 | [教学与资源](#ch-teach) | 课程大纲、AI 教学助手、试题管理、考试发布、智能组卷与 Word 导出、AI 教学资源推荐、AI 生成 HTML 资源、资源中心、资源管理、文件中心 | 10 |
| 🎓 学 | [学习与练习](#ch-learn) | AI 对话、AI 学伴、课程练习、同步练习、错题巩固、每日精选与热点新闻、编程实践 | 7 |
| 🎪 练 | [课堂活动](#ch-practice) | 课堂互动工具（随堂测验、投票、提问）、知识抢答、分组讨论、协作白板、考勤与点名、对话作业、知识闯关 | 7 |
| 📊 评 | [学情分析与激励](#ch-assess) | AI 学情分析、AI 课堂总结、进度详情、活动监控、资源浏览统计、数据导出、积分奖励、课堂积分、荣耀殿堂、成长档案 | 10 |
| ⚙️ 管 | [系统管理](#ch-manage) | 用户管理、系统公告、系统配置、技能管理、通知中心、AI 自我画像、在线升级、关于系统、其他系统服务 | 9 |
> 各节末尾的 **权限提示**（如「所有用户可用」）标出该功能的可访问角色；完整的角色矩阵见[权限总览](#permissions)。
### 手机访问
平台可直接用手机浏览器访问，**无需安装 App**。手机端定位是「学生练与查、教师看与批」，管理型重页面保持电脑端专属。
#### 手机已开放的页面
| 角色 | 数量 | 页面 |
| --- | --- | --- |
| 学生 | 27 | 首页、AI 学伴、错题巩固、每日精选、热点新闻、通知中心、系统公告、课堂提问、知识抢答、待办清单、对话作业、积分称号、考试与成绩、AI 周画像、学伴设置、知识闯关、同步练习、课堂互动、课堂投票、分组讨论与讨论室、文件中心、成长档案、风采展示、我的资源、资源中心、关于系统 |
| 教师 / 管理员 | 22 | 首页、AI 助手、通知中心、系统公告、提问管理、AI 课堂总结、学情分析、对话作业批改确认、课堂积分、AI 周画像、分组讨论与讨论监控、闯关记录查看、汇总统计导出、文件中心、成长档案、风采展示、我的资源、资源中心、资源管理、关于系统 |
#### 手机端怎么用
- 底部标签栏固定 5 格：首页 / 学伴（教师为助手）/ 错题（教师为提问）/ 通知 / **菜单**，「菜单」打开当前角色全部可用功能
- 未适配的功能在手机端不显示入口；直接输入地址会看到「此功能请在电脑端使用」，可一键返回上一页
- 考试作答、抢答答题、闯关战斗是独立全屏页，选项按钮按触屏放大，倒计时与进度常驻顶部
- 列表类数据（通知、公告、考试、抢答记录、作业、资源）在窄屏自动改为卡片或可横向滚动，标题不会被压成竖排
#### 保持电脑端专属
试题管理与智能组卷、题库维护、用户管理、系统配置、点名管理、活动监控、汇总导出、课程大纲维护、知识闯关管理、代码练习、协作白板、管理控制台
## 首页与待办
登录后的第一眼：按角色聚合的智能仪表盘与学生待办，是五条主线的统一入口。
### 系统首页（仪表盘）
登录后默认进入智能首页仪表盘，按角色聚合展示关键数据：
**学生端：**
- 📋 待完成考试数、已完成考试数
- 🏆 累计课堂积分与班级排名
- ✅ 活跃任务数与本周对话次数
- 📝 待答随堂测验数、已参与投票数
- 📅 待参加的考试列表（一键开始）
- 📈 近期考试成绩（得分/是否通过）
- 📢 系统公告滚动展示
- ⏱️ 最近活动动态时间线
- 🚀 快速入口（知识问答/考试中心/积分/互动）
**教师/管理员端：**
- 📊 考试概览（总数/草稿/已发布/已结束）
- 📋 任务提交总数与活跃任务数
- 👥 学生总数、教师总数、任教学科
- 🎯 本周点名次数
- 📝 随堂测验总数与进行中数量
- 📊 活跃投票数与回应人数
- 💬 今日对话数
- 🚀 快速入口（AI 对话/考试发布/点名/用户管理/互动）
> **所有登录用户可用**
---
### 待办事项（学生任务聚合）
学生端专属任务聚合看板：
- 📊 按分类聚合待办事项（考核测评、课程学习、互动课堂、共享资源、系统服务）
- 🔴 即将截止高亮提醒
- 🚀 一键跳转到对应功能页面
- 📈 完成进度统计
> **学生可用**
---
## 教学与资源
教师侧从备课到资源沉淀的完整链路：课程大纲、出题组卷、考试发布、AI 生成与共享资源。
### 课程大纲（课程导学）
课程 → 章 → 节 → 知识点四级树形结构：
- **🤖 AI 智能生成**：粘贴文本或上传文件（txt/md/pdf/docx），AI 自动提取课程结构
- **✏️ 手动管理**：添加、编辑、删除课程/章节/知识点
- **🔀 拖拽排序**：同级和跨层级拖拽排序，灵活组织
- **🔗 资源绑定**：为知识点绑定 7 类资源（HTML 课件、下载文件、试题、考试、讨论、随堂测验、任务）
- **✅ 学习进度追踪**：学生逐知识点学习，标记完成状态，实时进度条
- **📊 课程进度总览（教师）**：全班学生知识点完成进度矩阵，按年级/班级筛选
- **🏋️ 课程练习**：教师一键为知识点生成 10 道单选题，学生在线作答
> **管理员/教师可管理；学生可查看并标记进度**
---
### 教学助手（教师/管理员专属）
为教师和管理员提供的 AI 教学工具型助手：
- **📝 智能备课**：根据课题自动生成完整教案（教学目标、教学过程、课堂活动、作业设计）
- **📄 自动出卷**：按知识点/题型/难度生成试卷和随堂测验
- **📊 学情分析**：分析班级或学生个人成绩数据，指出薄弱点和进步空间
- **🎯 活动策划**：设计课堂互动方案（小组讨论、抢答、随堂测验等）
- **📋 教学数据侧栏**：实时显示学生人数、考试统计、提交任务、课堂互动等教学概览
- **🎨 视觉差异化**：青绿助手风格气泡与头像
> **教师/管理员可用（智答页面顶部切换）**
---
### 试题管理（智能题库）
AI 智能试题管理系统，支持多种题型和多媒体：
- **🤖 AI 一键生成**：按科目、题型、知识点、难度和数量自动生成试题
- **📤 智能提取**：支持粘贴文本或上传 .docx/JSON 文件，自动识别题型、选项和答案
- **🧱 入库统一出口**：AI 出题、智能提取与各练习 / 测验补题都走同一道关口（体检 → 查重 → 事务 → 连知识点边），不合格与重复的题不再进库。同一道题只有一条写入路径，判分、查重、选题口径从源头对齐
- **📋 题型支持**：单选题、多选题、判断题、简答题、填空题、作文、主观题
- **📐 公式支持**：全面支持 LaTeX 公式（$...$）渲染显示
- **🖼️ 配图系统**：
- SVG 绘制技术图示
- 通义万相生成实物图片
- 支持图片生成、预览、删除，并发生成优化
- 图片占位符管理
- **📂 题库管理**：分类筛选、搜索、编辑、删除
- **🔄 AI 生图**：自动为主观题 SVG/图片占位符生成配图
> **管理员和教师可用**
---
### 考试发布（在线考试系统）
完整的在线考试管理系统：
- **⚙️ 创建配置**：标题、科目、时长、总分、及格分、题目/选项乱序、答题次数、时间范围
- **📋 组卷方式**：
- **智能选题**：按题型/难度/知识点等条件组合筛选，AI 辅助
- **手动选题**：从题库逐题挑选
- **📋 考试流程**：发布 → 学生在线答题（实时倒计时） → 客观题自动批改 → 成绩查看
- **📊 成绩统计**：得分/总分/百分比/是否通过/排名
- **📤 数据导出**：成绩导出为 Excel
- **🔔 消息通知**：发布/取消/修改/提前结束时自动通知
> **管理员/教师可创建管理；学生可参加已发布的考试**
---
### 智能组卷 & Word 导出
分步引导式组卷向导，支持智能选题与专业文档导出：
- **📋 配置向导**：题型题量配置、难度分布、知识点范围筛选
- **🤖 AI 智能选题**：按知识点智能匹配
- **🔌 缺口补差**：默认只报缺口；勾选后题库不足的部分由 AI 出题补齐并入库
- **📊 规则选题**：按难度比例随机抽取
- **📊 组卷统计面板**：实时题型/难度分布、总分，支持手动移除题目
- **📄 Word 导出**（三份文档）：
- **试卷**：学生用，含答题线
- **答案卷**：红色标注答案 + 蓝色解析
- **答题卡**：标准答题卡格式
- **📐 LaTeX 公式渲染**：matplotlib 渲染为图片嵌入
- **🖼️ SVG 自动转 PNG**：确保 Word 兼容性
- **📦 题型排序**：单选题 → 多选题 → 判断题 → 填空题 → 简答题 → 作文 → 主观题
> **管理员和教师可用**
---
### AI 教学资源推荐
根据知识点内容智能推荐教学资源：
- **🔍 智能分析**：AI 分析知识点内容自动推荐关联资源
- **📋 推荐类型**：HTML 课件、考试试卷、课堂讨论、随堂测验、任务
- **🔗 一键绑定**：推荐资源可直接绑定到知识点
- **📄 AI 生成课件**：AI 可根据知识点自动生成完整 HTML 课件
> **管理员和教师可用**
---
### AI 生成 HTML 资源
在资源中心直接使用 AI 生成 HTML 教学资源：
- **📄 5 种资源类型**：
- 🎬 **动画讲解**：3D 视差、粒子动画等技术生动讲解知识
- ✍️ **互动答题**：卡片式交互答题，含选择题和即时反馈
- 📝 **章节练习**：结构化习题，含题号导航和提交按钮
- 🧪 **实验交互**：算法可视化、数理化实验、AI 交互仿真
- 🎨 **自定义 HTML**：自由输入主题，按需生成任意 HTML
- **🎭 主题选择**：每种类型提供多套预设主题
- 动画 17 种、答题 20 种、练习 10 种、实验 12 种
- **📚 题库 + AI 混合出题**：自动匹配题库题目，不足由 AI 补充；题目数量可在生成前指定
- **💾 AI 新题自动入库**：AI 生成的题目自动保存到题库
- **🔗 学科/年级智能关联**：根据学科和年级获取对应题库
#### 实验交互资源详情
覆盖 **9 大学科分类**：
- 🔬 **算法与编程**：排序/搜索可视化、数据结构、编译原理
- 📐 **数学**：函数曲线调参、几何证明、概率统计、微积分
- ⚡ **物理**：力学仿真、电路模拟、光学实验、热力学循环
- 🧪 **化学**：分子结构、化学反应、元素周期表、滴定实验
- 🧬 **生物**：细胞结构、DNA 复制、生态系统、遗传杂交
- 🌍 **地理与天文**：地图投影、气候模拟、太阳系模型、板块运动
- 🏛️ **人文与社会**：历史年表、经济模型、语法分析、配色实验
- 🤖 **人工智能**：CNN 可视化、图像分类、Transformer 注意力机制
- 🎯 **通用交互**：拖拽点击、图表联动、自定义仿真
**多文件子目录结构**（复杂资源）
**配图增强**：AI 自动规划并生成 SVG 教育示意图 + 通义万相实景配图
> **管理员和教师可用**
---
### 资源中心（共享中心）
以卡片网格展示 HTML 教学资源文件：
- **👁️ 卡片浏览**：缩略图 + 文件名称
- **🔗 共享操作**：
- **管理员共享**：可选择「所有人」「指定教师」「指定年级/班级」
- **教师共享**：选择「管理员和教师」+「自己的班级」
- **🔍 搜索筛选**：按文件名搜索
- **🗂️ 统一浏览器**：学生端「共享资源」、教师端「共享给我的」与学生端「共享文件」共用同一套浏览界面（未看·时间·类型·课程·共享者·范围六维分类 + 网格/列表双视图 + 偏好记忆）
- **🔗 直达定位**：任务清单与共享通知点进去直接落到对应标签页，不会先跳回默认页再让人自己找
- **🤖 AI 生成**：5 种资源类型（动画讲解、互动答题、章节练习、实验互动、自定义 HTML）
- **👁️ 资源浏览统计**：自动记录学生查看行为
> **所有登录用户可用；学生仅查看共享资源**
---
### 资源管理
上传/删除/重命名教学资源文件：
- 📤 上传文件、目录（HTML/CSS/JS/图片/文档等）
- 🗑️ 删除与重命名
- 📁 每位教师拥有独立资源目录
- 🔗 文件共享操作（同资源中心共享）
- 📊 配额管理
> **管理员和教师可用**
---
### 文件中心
下载目录文件管理：
- 📤 上传 / 📥 下载 / 🗑️ 删除
- 📊 配额管理（按教师独立配额）
- 📁 子目录支持
- 🔗 目录共享（整个目录自动继承权限；接收方显示为「文件夹」条目，内含文件数与总大小一目了然）
- 🗂️ 统一资源浏览器：与「共享资源」共用分类侧栏 / 统计条 / 网格·列表双视图 / 搜索排序分页与偏好记忆
- 👁️ 学生可查看共享文件，并记录未看·已看与浏览量（首次浏览奖励 1 分）
> **管理员和教师可用；学生可查看共享文件**
---
## 学习与练习
学生侧的答疑与练笔：知识问答、AI 学伴、知识点练习与定向练习、错题巩固、视野拓展与编程实践。
### AI 对话（知识问答）
核心智能问答界面，基于 SSE 流式传输，提供流畅的 AI 对话体验：
- **⚡ 流式对话**：AI 实时逐字输出回复，即时反馈
- **📎 文件上传**：支持图片（JPG/PNG/GIF）和文档（PDF/Word/Excel/PPT/TXT/MD 等）
- **👁️ 图像理解**：上传图片调用视觉模型识别分析
- **🖼️ 多模态对话**：启用多模态后支持图片+文本同时输入，由多模态模型直接理解，无需文件摘要
- **📄 文件摘要增强**：自动对上传文档进行摘要，增强 AI 对话上下文
- **🔍 RAG 知识增强**：从试题库和课程大纲中检索相关知识，提升回答准确性
- **📜 历史记录**：自动保存并按会话标题显示，今天/昨天/按月分组，支持标题与正文搜索、悬浮预览、重命名与下载
- **👁️ HTML 预览**：对话中 HTML 代码块可一键预览
- **📋 示例提示词**：内置多个教学场景示例，一键填充
- **🎭 三种模式**：智答模式 / 学伴模式（学生）/ 助手模式（教师/管理员）
- **🎤 语音输入**：支持麦克风语音转文字输入
- **📷 拍照上传**：支持摄像头拍照直接上传
> **所有登录用户可用**
---
### AI 学伴（学生专属）
AI 对话的智能升级模式，为学生提供个性化的学习陪伴体验：
- **👤 专属学习伙伴**：AI 学伴知道学生的姓名、年级、学习进度和薄弱知识点
- **🔄 三种人格切换**：
- 🌟 **鼓励型**：温暖热情，充满正能量，多用鼓励用语
- 📐 **严谨型**：严谨细致，注重分析「为什么错」「怎么改」，举一反三
- 😄 **幽默型**：风趣幽默，适度用梗和调侃让学习不枯燥
- **📊 学习画像侧栏**：实时显示称号、积分、薄弱知识点、考试趋势、连续学习天数
- **🔔 主动推送**：早安问候、考试结果分析、称号升级祝贺、学习提醒
- **💾 对话历史统一管理**：与智答模式共用聊天历史系统
- **⚙️ 自定义设置**：可自定义学伴名称、人格、开关学伴、每日唤醒时间
- **🎨 视觉差异化**：紫色学伴风格气泡与头像
> **学生可用（智答页面顶部切换）**
---
### 课程练习（知识点练习）
基于课程大纲知识点的 AI 练习系统：
- **🤖 AI 自动出题**：教师为知识点一键生成 10 道单选题
- AI 从题库智能搜索合并匹配题目
- 差额由 AI 补全新题
- 新题自动入库
- **✍️ 学生在线作答**：在课程学习页面点击知识点直接练习
- **🏆 自动积分奖励**：
- 参与基础分：2 分
- 优秀（≥90%）：+15 分
- 良好（≥75%）：+10 分
- 及格（≥60%）：+5 分
- **📊 数据展示**：首页看板展示完成数与平均正确率
- **📋 成长档案集成**：个人档案页集成练习明细
> **管理员/教师可出题；学生可参与练习**
---
### 同步练习（AI 定向出题）
教师从错题本或知识点生成针对性练习题，推送至班级或指定学生：
- **🤖 AI 出题**：从错题本或知识点自动生成针对性练习题
- **📤 定向推送**：推送至班级或指定学生
- **✍️ 学生作答**：在线答题，支持选择题和简答题
- **🤖 AI 自动批改**：简答题自动批阅
- **⚡ 异步出题**：不阻塞界面，支持后台生成
- **📊 练习记录**：历史练习查看与成绩统计
> **管理员/教师可出题；学生可参与**
---
### 错题巩固
自动归集学生错题，AI 辅助复习：
- **📋 错题归集**：按考试归类展示错题
- **✅ 自主标记已掌握**：每道题可标为「已掌握」也随时取消，配合待掌握/已掌握/全部三档筛选，学生自己决定还要不要继续练
- **📐 多媒体展示**：支持 LaTeX 公式和配图显示
- **🤖 AI 复习计划**：一键生成个性化复习报告（错题分析、知识点复习建议、针对性练习题）
- **👁️ 三级联动查看（教师）**：按年级 → 班级 → 学生逐级筛选
- **📊 错题统计**：各科错题数和正确率
> **学生查看自己；教师/管理员可查看全班学生**
---
### 每日精选 & 热点新闻
知识拓展双模块，让学生在学习之余轻松拓宽视野：
- **📖 每日精选**：AI 趣味知识卡片池，每人随机抽取 6 张，
7 天去重窗口，支持收藏与手动刷新。智能知识池按需补充，
无人用时不消耗 AI，浏览可获积分与徽章。
- **📰 热点新闻**：RSS 聚合多个主流新闻源（中新网、IT之家等），
AI 按需摘要 + 学科关联，支持今日简报、收藏与分页浏览（不再只能看到前 20 条）。
2h 缓存懒加载，72h 滚动清理，无人访问零抓取；源清单可在系统配置中修改，单源失效自动熔断并切备用源。
> **所有用户可用**
---
### 编程实践（代码练习）
在线编程练习与自动评分系统：
- **教师端**：
- 创建编程题目（题目描述、测试用例、示例代码）
- AI 代码审查
- 查看提交统计和学生代码
- **学生端**：
- 在线编码（语法高亮，支持 Python）
- 运行调试（自定义输入）
- 提交评分
- **🤖 自动评分引擎**：
- AST 静态分析 + 沙箱执行
- 逐用例比较输出
- 支持 Python
- 超时控制（10秒）
- **🔒 安全沙箱**：
- 危险模块黑名单
- 危险函数拦截
- 临时目录隔离
> **所有登录用户可用**
---
## 课堂活动
一节 40 分钟课里的实时互动与组织工具：测验、投票、提问、抢答、讨论、白板、点名、闯关与对话作业。
### 课堂互动工具
#### 随堂测验
课堂即时测验系统：
- ✏️ 可视化编辑器创建（单选/多选/判断）
- 🤖 AI 一键生成（指定主题/题型/数量）：题库优先，缺口由 AI 补题并入库复用
- 📊 自动评分与结果统计
- 📐 支持 LaTeX 公式和配图
- 📤 数据导出
#### 课堂投票
课堂即时投票系统：
- 📋 单选/多选模式
- 🤖 AI 自动生成投票主题
- 📊 实时柱状图统计结果
- 👥 参与人数实时显示
#### 提问管理
学生提问与教师审批一体化管理：
- 🙋 **学生提问**：学生发起提问（支持匿名）
- 🤖 **AI 辅助回答**：AI 自动生成建议回答，教师可修改后发布
- 👨🏫 **教师回答**：教师直接回答或审批通过学生的回答
- ✅ **审批机制**：教师可标记学生回答为「已通过」或「未通过」
- 🔒 **权限控制**：仅本班学生和教师可见
> **学生可提问；教师可管理回答与审批**
---
### 知识抢答活动
实时多人在线抢答竞赛系统：
- **教师端**：
- 创建抢答房间（设置限时、题目数量、科目）
- 题目来源：题库优先，缺口由 AI 补题并入库；AI 也拿不到题时才用内置题，且不重复凑数
- 控制抢答进程（开始/下一题/结束）
- 查看实时排行榜
- **学生端**：
- 输入 6 位房间码加入
- 限时作答（速度递减计分）
- 连击加分（连对 5 题 2 倍得分）
- 实时排名
- **计分规则**：
- 速度计分：0-3 秒 100 分，3-7 秒 70 分，7-11 秒 40 分，11+ 秒 20 分
- 连击倍率：连对 2 题 1.2x，3 题 1.5x，4 题 1.8x，5+ 题 2.0x
- 连续答错 3 题扣 10 分
- 全对额外 1.2x 奖励
- 📊 **活动回顾**：排行榜、每题正确率统计
> **管理员/教师可创建管理；学生可参与抢答**
---
### 分组讨论（AI 助教）
AI 助教辅助的课堂分组讨论系统：
- **创建讨论**：
- 分组模式：不分组（自由讨论区）/ 自动分组 / 随机分组
- AI 助教角色：旁观者 / 引导者 / 主动参与 / 辩论裁判 / **综合角色（智能切换）**
- AI 智能生成讨论方案（支持 Markdown 格式标题与说明）
- **参与讨论**：
- 学生进入讨论室实时聊天，可展开查看讨论主题说明
- AI 助教根据角色自动参与
- 实时消息推送（WebSocket）
- **讨论管理**：
- 👁️ **监控面板**：教师实时查看所有分组动态
- 🛡️ **内容审核**：自动检测不当发言，违规扣分
- ⏹️ **结束讨论**：AI 自动生成结构化总结报告
- 📄 **Word 导出**：AI 总结可导出为 Word 文档
- 📊 **总结报告**：关键观点、AI 评价、小组评分
> **管理员/教师可创建管理；学生可参与本班讨论**
---
### 协作白板（AI 白板助手）
基于 TLDraw 的实时协作白板系统，内置 AI 白板助手侧栏：
- **三种教学模式**：
- 📺 **演示模式**：教师展示，学生仅观看
- 🤝 **互动模式**：教师授权后学生可操作
- 📝 **自习模式**：学生独立操作
- **🔗 房间系统**：教师创建房间（支持班级/课程/临时类型），学生输入 6 位房间码加入
- **👥 实时成员管理**：在线成员列表，显示当前在线的学生
- **🎨 白板工具**：画笔、形状（矩形/椭圆/菱形/箭头）、文本、便签、图片、激光笔
- **📄 多页面支持**：支持多页白板，缩略图导航
- **🤖 AI 白板助手**（教师专属）：
- 💬 **流式对话**：AI 结合白板当前内容进行上下文问答，支持视觉增强理解
- 🖼️ **生成图示**：根据描述自动生成教学图示（SVG 优先）
- 📝 **一键板书**：根据知识点自动生成结构化板书内容
- ✨ **美化排版**：对白板上杂乱内容重新排版为清晰美观的板书
- 🏷️ **智能批注**：对选中内容自动分析并给出标注建议
- 🌳 **思维导图**：根据板书内容自动生成结构化思维导图
- 🌐 **中英双语**：将板书内容一键转换为中英对照双语版
- 💡 **教学建议**：根据当前白板内容推荐下一步教学思路
- ❓ **随堂提问**：根据板书自动生成课堂练习题
- 🔍 **解答题目**：识别白板中图片上的题目并进行解析
- 👁️ **视觉理解**：切换视觉模式，通过多模态模型看懂白板图片内容
- 📄 **导出总结**：AI 生成结构化课堂总结并导出为 Word 文档
> **管理员/教师可创建管理；学生可参与**
---
### 考勤与点名管理
智能点名 + 考勤统计一体化管理：
- **🎲 权重随机点名**：每个学生具有动态权重，被点到后权重衰减，
覆盖超过 60% 学生后自动重置权重，保证公平
- **🗣 点名语音播报**：点到谁就念出谁的姓名（多音姓氏自动校正读法），由管理员在系统配置中启用
- **✅ 点名记录**：标记正确/错误，查看历史记录与统计
- **📊 点名统计**：按人统计被点次数与正确率
- **📝 考勤记录**：自动记录每次登录的时间、IP、浏览器信息
- **📅 历史追踪**：完整的历史登录记录
- **👁️ 权限控制**：教师仅查看本班，管理员可查看全部
> **管理员/教师可用**
---
### 对话作业
教师布置一个主题，学生与 AI 对话完成学习后把对话记录提交上来，教师逐个批改：
- **教师端**：
- 创建作业（名称/要求/面向范围），或点「AI 创建作业」把一句话想法变成可编辑草稿
- 作业要求即批改依据：AI 先拆成 3-5 条要求点，再逐条对照对话找证据评分
- AI 智能批改（三维度：完成度、理解深度、表达质量）：可一次批完全班（含全班总结与各要求点达成情况），也可在学生行上只批某一个人
- 每个作业标出待批改份数，可一键「只看待批改」（首页待办徽标直达此筛选）
- 查看详情逐个阅读学生提交的对话与要求原文，撤销提交、结束作业
- **学生端**：
- 查看进行中的作业与完整作业要求
- 在「知识问答」里聊完后一键提交当前对话
- 查看 AI 评分、要求点达成情况与评语建议
- **📖 使用说明**：标题旁「使用说明」按钮，学生端与教师端各一套分步指引
- **🧮 公式渲染**：对话内容与作业要求中的公式都能正常显示，写在文字同一行的也可以
> **所有用户可用，按角色功能区分**
---
### 知识闯关
AI 即时出题的百科答题挑战：
- **🎯 闯关规则**：限时答题（每题 30 秒），答错即终止，最多 15 题
- **🤖 AI 出题**：由 AI 即时生成百科题目（支持题库模式）
- **💡 三种锦囊**（每局限用一次）：
- 🎯 去伪存真：排除一个错误选项
- 📞 远程连线：AI 给出提示
- 👥 群策群力：AI 模拟投票结果
- **📊 计分规则**：阶梯计分（第 1 题 10 分 → 第 15 题 50 分），锦囊折减
- **🏆 成就徽章**：初出茅庐 / 闯关新秀 / 闯关达人 / 闯关大师 / 闯关传奇 / 一站到底 / 十连斩
- **📊 教师管理**：查看学生闯关记录、闯关题库管理、AI 批量生题
- **📋 闯关历史**：统计总次数、最高正确数、总分
> **学生可参与；教师/管理员可管理题库和查看记录**
---
## 学情分析与激励
行为数据回流成画像，画像反哺教学，再以积分、称号与荣誉形成持续正反馈。
### AI 智能学情分析
利用 AI 对教学数据进行深度分析：
- **📊 班级学情报告**：
- 整体评价
- 学习亮点
- 薄弱环节分析
- 教学改进建议
- 支持 Word 导出
- **📋 考试分析报告**：
- 分数分布统计
- 逐题正确率分析
- 班级对比
- 教学改进建议
- **📤 数据导出**：支持导出为 Word
> **教师和管理员可用**
---
### AI 课堂总结
AI 对课堂互动数据进行综合分析：
- **🤖 智能分析**：AI 分析随堂测验、投票、提问等互动数据
- **📋 总结报告**：总体情况、参与度分析、知识点掌握度、教学建议
- **📄 Word 导出**：支持导出为 Word 文档
- **📊 班级筛选**：按年级/班级选择分析范围
> **教师和管理员可用**
---
### 进度详情
课程进度与学习进度综合分析：
- **📖 课程进度**：按课程查看全班学生的章节/知识点完成情况，展开可看明细
- **📊 学习进度**：按班级查看学生综合统计（课程进度/完成率/正确率/连续学习天数），支持筛选单个学生
- **🔍 权限控制**：教师仅见自己班级，管理员可见全部
> **教师和管理员可用****
---
### 活动监控（教学督导）
教师查看各类教学活动的完成情况：
- **📋 活动类型**：考试、智能练习、知识抢答、任务、随堂测验、代码练习、分组讨论、投票、课程练习
- **👥 完成状态**：已完成 / 未完成学生列表
- **📊 成绩概览**：简要成绩和统计数据
- **🔍 多维筛选**：按活动名称、年级、班级筛选
- **📥 数据导出**
#### 活动数据重置（清参与数据、留活动内容）
9 类活动（考试 / 智能练习 / 知识抢答 / 在线任务 / 随堂测验 / 代码练习 / 分组讨论 / 快速投票 / 课程练习）均提供「重置」入口：
- **🧹 清什么**：学生参与产生的数据（答卷、提交、投票、发言、组员与小组报告、AI 批改结果、资源浏览与学习进度），以及派生数据（积分流水、活动关联通知、错题本条目）
- **📦 留什么**：活动内容本身全部保留 —— 题目与选项、试卷结构与分值、代码题面与测试用例、讨论配置、房间码、任务 ID 等；被删除的参与记录不可恢复
- **🔎 先看后删**：弹窗内先做干跑预览，逐条列出将清理的数据项与条数；调整勾选项即时重算，看到的数字就是会删除的数字（预览与执行同一份口径）
- **🔁 状态回滚**：可选把活动状态退回「可重新参与」（如考试 已结束 → 已发布、知识抢答 进行中 → 等待中），不清内容
- **⌨️ 二次确认**：须原样输入活动名称；口令由服务端校验，直接调用接口也无法绕过
- **📩 学生告知**：可向受影响学生推送回执，回执按界面语言渲染（英文界面不残留中文）
- **🧮 积分口径**：回收该活动积分流水后立即重算受影响学生总分，与每日对账同口径，不做升级判定
- **🛡️ 权限**：管理员可重置全部（重置他人活动会在审计中标记为代操作）；教师仅能重置本人创建的活动，课程练习按「资源共享人 + 本人任教年级」双重判定；学生界面无入口且接口一律拒绝
- **📝 审计留痕**：每次重置都留下完整审计记录：操作者与角色、活动标识与名称、勾选项、删除明细与行数、回收积分、影响人数、通知人数、时间
> 所有活动类型共用同一套重置流程（选范围 → 预览 → 确认 → 审计留痕），新增活动类型自动获得同样的能力。
---
### 资源浏览统计
追踪学生查看 HTML 和下载资源的行为：
- **📊 统计概览**：活跃学生数、总浏览数、已浏览资源数
- **📋 资源明细**：每份资源的浏览人数、浏览时间
- **👤 学生明细**：每位学生的资源浏览详情
- **📚 知识点绑定**：按课程知识点查看资源查看情况
- **🏆 积分奖励**：首次浏览共享资源自动奖励 1 分
> **教师和管理员可用**
---
### 数据导出
支持将各类数据导出为 Excel/CSV：
- 📊 考试成绩导出
- 📊 跨活动成绩汇总导出：各类活动得分与完成情况按年级/班级/学生/活动类型/时间筛选，导出多表 Excel 或 CSV
- 📊 点名记录导出
- 📊 课堂互动数据导出
- 📊 活动监控数据导出
- 📊 资源浏览统计导出
> **教师和管理员可用**
---
### 积分奖励体系（自动奖励引擎）
全自动积分激励机制，覆盖所有课堂活动：
- **参与活动自动获分**：
| 活动类型 | 基础分 | 等级奖励 |
| --- | :---: | :---: |
| 随堂测验 | 2 | ✅ |
| 快速投票 | 2 | ❌ |
| 课堂提问 | 2 | ✅ |
| 考试 | 2 | ✅ |
| 同步练习 | 2 | ✅ |
| 分组讨论 | 2 | ✅ |
| 点名签到 | 2 | ❌ |
| AI 对话 | 2 | ❌ |
| 任务 | 2 | ✅ |
| 学习进度 | 2 | ❌ |
| 每日登录 | 1 | ❌ |
| 代码练习 | 2 | ✅ |
| 知识闯关 | 1 | ✅ |
| 知识抢答 | 2 | ✅ |
| 课程练习 | 2 | ✅ |
| 资源浏览 | 1 | ❌ |
| 每日精选 | 1 | ❌ |
| 热点新闻 | 1 | ❌ |
- **等级奖励**：优秀（≥90%）+15 / 良好（≥75%）+10 / 及格（≥60%）+5
- **🏅 12 级称号系统**：初窥门径 → 筑基学徒 → 勤学新人 → 知识猎人 → 解题能手
→ 逻辑新星 → 学业先锋 → 班级学霸 → 创新领袖 → 全能学神 → 传奇大师 → 至高贤者
- **🎖️ 成就徽章**：崭露头角、满分达人、学习之星、刷题达人、全能选手、AI 探索者、讨论之星、准时达人、点名达人、全勤标兵、闯关系列徽章等
- **🏫 班级排名**：总积分排名
- **📊 积分规则页**：展示所有积分来源和规则
> **管理员/教师可用；学生可查看**
---
### 课堂积分（班级管理）
课堂积分激励系统：
- ⭐ 每位教师独立管理积分
- 📊 积分排行榜（班级内排名）
- 👥 学生管理（加减分操作）
- 💾 数据持久化至数据库
- 📤 支持导入/导出
> **管理员/教师可用；学生可查看**
---
### 荣耀殿堂（学生荣誉展示墙）
学生成就集成展示页，汇聚积分、称号、徽章等荣誉于一墙：
- **🎴 卡片展示**：每位学生一张荣誉卡片，展示称号横幅、积分星级、徽章墙、学科称号
- **🎨 10 套渐变主题皮肤**：金色荣耀、深海探秘、森林物语、落樱缤纷、极光幻境、日落余晖、星际漫游、玉瓷雅韵、烈焰斗志、极简素白
- **🔄 主题自适应**：12 级称号自动映射主题，支持手动切换（🎨 调色板按钮）
- **❤️ 点赞互动**：卡片点赞 + 粒子动画效果，浏览记录统计
- **🔍 多维筛选**：按年级/班级/姓名搜索，支持多维度排序（积分/称号等级/点赞数/浏览数）
- **👨🏫 教师管理**：按任教年级/班级控制权限，支持批量生成/刷新/删除
- **🔄 自动同步**：每次生成自动拉取最新积分、称号、徽章数据
> **所有用户可查看；教师/管理员可管理**
---
### 学生成长档案
全维度学习数据聚合画像：
- **📋 综合摘要**：AI 生成的个性化学习评价
- **📊 五维统计**：考试、积分、点名、任务、对话
- **📈 成绩走势图**：各次考试成绩变化趋势
- **🏆 积分趋势图**：积分累积变化曲线
- **⏱️ 成长时间轴**：所有学习活动按时间线展示
- **📄 Word 学习报告导出**
- **👁️ 权限控制**：学生查看自己，教师/管理员可查看任何学生
- **📊 课程练习集成**：练习统计与明细
> **所有登录用户可用**
---
## 系统管理
账号、配置、AI 技能、通知、升级与运维。
### 用户管理
完整的账号管理体系：
- **📝 注册用户**：支持管理员/教师/学生三种角色
- **✏️ 信息更新**：修改用户名、班级、年级、姓名、性别、角色、任教学科
- **🔑 修改密码**：所有用户可修改自己的密码；管理员可重置他人密码
- **🗑️ 删除用户**：逐条或批量删除
- **📤 CSV 导入**：批量导入用户
- **🔍 筛选搜索**：按角色/年级/班级筛选，按用户名/姓名搜索
- **🏫 教师任教管理**：设置教师任教年级班级学科
- **🧩 班级维护**：查看各班在读人数与任教安排，可清理无人的空壳班级（仅管理员）
- **📊 批量升/降年级**：一键预览并执行，智能同步积分和点名数据
- **🔒 安全设置**：密保问题（忘记密码自助找回）
- **🔐 单点登录**：Token 版本控制，异地登录踢出
> **管理员和教师可用；学生仅改密**
---
### 系统公告
发布和管理系统公告：
- **📝 发布公告**：标题、内容、优先级（普通/重要/紧急）
- **📌 置顶功能**：重要公告置顶显示
- **👥 可见范围**：按角色（学生/教师/管理员）、年级、班级限定
- **📋 公告列表**：分页展示，按优先级排序
- **✏️ 编辑/删除**：管理已发布的公告
> **所有用户可查看；管理员和教师可发布**
---
### 系统配置
集中管理系统所有配置参数：
- **🏷️ 品牌信息**：平台版本名称、单位名称
- **🔑 API 密钥**：DashScope API Key
- **🤖 模型配置**：APPID、API 地址、默认对话模型、长文本模型、视觉模型、多模态开关（模型均为下拉可选）
- **💬 AI 对话设置**：对话权限角色、每日请求限额（启用开关 + 上限次数）
- **⚙️ 系统限制**：文件大小限制、Token 有效期、在线超时、IP 防护与登录闸门
- **🔊 语音合成**：启用开关、合成模型（两代可选）、音色（按模型分组的实测音色下拉，换模型自动跟随）、语速、音量、合成自检
- **📚 课程设置**：课程名称列表、试题题型
- **🔔 消息通知**：启用的通知类型
- **📁 文件类型白名单**：图片/文档扩展名
- **🎨 图片生成**：生图开关、模型（下拉，两代通道自动分派）、尺寸（默认自动，档位随模型）、单题自动配图上限、生图自检
- **⚡ 闯关挑战**：出题模式（题库/AI）
> **仅管理员可用**
---
### 技能管理
模块化 AI 技能文档系统，通过 YAML + Markdown 定义每个技能的行为，按场景自动注入到 AI 调用：
- **🧩 20 个预置技能**：8 个通用核心 + 12 个领域专精
- **🎯 按场景注入**：控制技能只注入匹配的场景
- **⚡ 质量三阶增强**：深度分析 → 结构化输出 → 自我审查
- **📋 可视化管理**：列表搜索、类型筛选、分页、全部开启/关闭
- **🔍 详情预览**：查看技能文档原始内容、版本、标签、优先级
- **🛡️ 安全降级**：技能出错时自动跳过，不影响原有功能
> **仅管理员可用**
---
### 通知中心
实时消息通知系统：
- 🔔 顶栏铃铛实时显示未读通知数量
- 📋 通知列表（全部/未读筛选）
- ✅ 标记已读 / 全部已读
- 🗑️ 删除通知
- 🔄 自动触发场景：
- 考试发布/变更/结束
- 资源共享
- 版本更新通知
- 提交批改完成
- ⚙️ 通知类型可在系统配置中启用/关闭
> **所有登录用户可用**
---
### AI 自我画像
基于通义万相模型生成的个性化 AI 画像：
- **🤖 AI 生图**：根据用户平台数据（积分、称号、学习/教学数据）生成专属画像
- **🎭 15 种创意风格**：
🔮 魔法学院 | 💻 赛博学霸 | 🖌️ 国风墨韵 | 🚀 星际探险 | 💥 热血漫画
🧚 童话精灵 | ⚙️ 蒸汽朋克 | 🎮 像素世界 | 🎭 敦煌飞天 | 🌌 极光幻境
🦸 超级英雄 | ⚔️ 圣殿骑士 | 🦋 赛博精灵 | 🐚 海洋探险 | ⏳ 时光旅者
- **📝 创意寄语**：大模型根据用户数据自动生成风格各异的寄语（武侠、星际、古风等体裁）
- **👤 角色感知**：根据学生/教师/管理员自动调整画像身份和寄语语气
- **♀️♂️ 性别精准**：读取用户性别信息，确保画像性别正确
- **🖼️ 个人画展**：历史画像按时间线展示
- **🌐 分享画廊**：
- 全校画廊 / 本班画廊 / 热门推荐
- 点赞互动
- 三种隐私范围：公开 / 本班可见 / 私密
- **⏰ 生成限制**：每周一次
> **所有登录用户可用**
---
### 在线升级系统（版本管理）
基于 Git 的在线增量升级系统：
- **🔍 检测更新**：自动对比 GitHub 最新版本
- **📥 增量升级**：自动执行 git fetch → git reset → 数据库迁移 → pip 安装 → 重启
- **📊 进度可视化**：实时进度条和日志输出
- **⏪ 一键回滚**：升级失败自动回滚，也可手动回滚
- **📋 升级历史**：完整记录每次升级详情（时间、版本、变更文件列表）
- **🔧 环境诊断**：自动检测 Git 安装、.git 目录、远程配置、网络连通性
- **🤖 后台自动检测**：每 6 小时自动轮询，发现新版本通知管理员
- **🔒 文件锁**：防止多 IIS Worker 并发升级
> **仅管理员可用**
---
### 关于系统
| 功能 | 说明 |
| --- | --- |
| ❓ **关于系统** | 查看说明文档 |
---
### 其他系统服务
| 功能 | 说明 |
| --- | --- |
| 🔑 **修改密码** | 所有用户可修改自己的密码 |
| 🔐 **忘记密码** | 通过密保问题自助找回密码 |
| 🗑️ **临时文件清理** | 自动清理超过 24 小时的临时上传文件 |
## 更新日志
当前版本 **8.6.0**（2026-10-05 ~ 10-09）。按版本列出读者可感知的变化，逐条实现细节见提交记录。
### v8.6.0（2026-10-05 ~ 10-09）
- 🔊 语音合成与智能点名播报落地，多音姓氏自动校正，关闭即零计费
- 🧭 模型候选集中维护、配置页改下拉、生图与语音加自检，配置错误在保存时拦下；入口页不再被缓存；新增登录页访问统计
- 🧱 题目入库合并成一个出口：不合格题拒收、重复题判重回填、AI 题当天进选题引擎、配图统一清洗
- 🔁 凑题策略统一到「题库优先 → 缺口交 AI → AI 题入库才返回」；抢答不再凑重复题；组卷可选「缺口补差」（默认关）
- 📏 随堂测验与页面出题的题量成为真实入参，越界直接报错；异步生成路径与同步路径行为一致
- 🧮 卷面分值口径、选题引擎、导出显示、拖拽排序与按学生乱序一批收口；AI 生成改后台任务
- 🎨 协作白板可用性与实时链路重做（连不上有原因、结束可重开、慢学生不拖全班、断线自动重连）
- ⏱ AI 出题按题量给输出上限，超时预算按接入地址分段重试，超时报错说清等待时长与试过的域名
- 📊 看板观感与图表重做、最近动态降噪，并尊重系统「减弱动态效果」
- 🧪 回归测试新增 134 条，全量 802 通过 1 跳过
- ⚠️ **破坏性变更**：无。题量越界由静默改数变为报错；白板与出题这两批改动需重启后端才生效；换接入地址重试时同一条提示词可能被计费两次
### v8.5.0（2026-10-03 ~ 10-04）
- 🧮 卷面分值成为硬不变量，配平与卷面体检默认只试算、确认才执行
- 🔒 在途答卷锁卷：有人作答时拒绝改题并说明是谁还在答
- 🎯 选题三套引擎并成一套；题目拖拽排序与按学生确定性乱序真正生效
- 🔢 导出显示修复（中文配图、公式、填空位）；抬头随考试落库
- 📱 手机适配落地；🖼 配图链路治理；🏆 积分防刷与荣誉收口
- 🔐 管理员登录历史与三个登录开关；🧠 技能注入按场景白名单收口；🧪 新增 130+ 条回归测试
- ⚠️ **破坏性变更**：无（历史卷子已有重复题时，唯一约束降级为普通索引并记日志，不删数据）
### v8.0 – v8.4 (2026-09-05 ~ 2026-09-29)
- 🔒 **鉴权与越权收口**：逐功能体检 16 轮，收紧匿名读取与跨教师写入；活动与资源限本人任教班级，密钥掩码回显
- ⏱️ **AI 调用全面异步化**：批改移出请求线程、交卷加幂等回执、长任务各自配超时，流式输出修复并加启动自检
- 🎯 **课堂活动稳定性**：抢答全员答完自动推进、重置后可安全重开；闯关开局即返回、余题后台补货；编程题归口「代码练习」
- 🧮 **积分与数据口径**：9 类活动支持「清参与数据、留活动内容」的重置（干跑预览 + 二次确认 + 可回滚 + 全程审计），删改后立即重算总分
- 📝 **教学主流程**：「任务管理」升级为「对话作业」按教师要求逐条找证据；公式渲染统一 23 处；历史记录按会话分组可搜可改名；四表成绩一键导出
- 📚 **知识库接管 AI 链路**：出题 / 教案 / 批改 / 学情 / 白板统一「先检索再生成」，失败自动降级并展示引用来源
- 📰 **资讯与看板重构**：RSS 换源校验 + 熔断 + 备用源池，今日简报冷启动 57.2s → 6.6s；教师端改为待办驱动
- ⚠️ **破坏性变更**：点名写接口需登录且限任教范围；测验 / 投票仅面向本人任教班级；「任务管理」更名「对话作业」
### v7.x 及更早（2026 上半年）
- 🎯 **AI 技能体系与国际化**：20 个技能按场景自动注入 40+ 路由，全站中英一键切换
- 🏆 **荣耀殿堂与全站 UI**：荣誉展示墙、10 套主题、70+ 页面容器规范统一
- 📰 **知识拓展与教学互动**：每日精选卡片池 + RSS 热点与今日简报、AI 学伴三种人格、智能备课出卷、协作白板、练习自动批改
- 🧱 **平台化重构**：去掉学科硬编码做到全学段全学科通用，批量导入与升年级、学情分析与成长档案、智能组卷与 Word 导出、全面安全审计
---
## 部署安装指引
### 方式一：一键部署 · SmartKBS 桌面版（零环境，最省事）
不想装 Python 和 Node.js，就用桌面版安装包 —— 双击装完就能用。
1. 下载最新安装包：[SmartKBS 最新版下载](https://github.com/youufis/SmartKBS/releases/latest)（自动跳最新 Release）
（安装包命名形如 `SmartKBS-Setup-版本号.exe`，约 120 MB，**仅 Windows x64**）
2. 双击安装：简体中文向导，可自选安装目录，自动创建桌面与开始菜单快捷方式
3. 启动 SmartKBS：桌面版自动拉起内置后端，等 `8086` 就绪后自动打开应用窗口
4. 本机访问 `http://127.0.0.1:8086`；同一局域网内的学生访问 `http://本机局域网IP:8086`（如 `http://192.168.1.100:8086`）
（首次启动请在 Windows 防火墙弹窗中选「允许访问」，否则其他设备连不上）
| 项目 | 说明 |
| --- | --- |
| 运行依赖 | 无。目标机器不需要 Python / Node.js（Electron 壳 + PyInstaller 后端 + Vite 前端） |
| 数据存放 | `%APPDATA%\SmartKBS\`（数据库、上传文件、日志都在此），**卸载重装不丢数据** |
| 升级方式 | 下载新版安装包直接覆盖安装；桌面版不走「在线增量升级」（那是 Git 部署专属） |
| 端口 | 固定 `8086`。若这台机器已用 IIS 跑着 Web 版，先停掉，否则桌面版起不来 |
| 支持平台 | 目前只发布 Windows x64 安装包；macOS / Linux 的打包配置已就绪但暂未出包 |
### 方式二：下载源码包部署（需 Python 环境）
1. 从 GitHub 下载最新源码 ZIP：[youufis/SmartKBS](https://github.com/youufis/SmartKBS)
2. 解压到服务器目录（如 `D:\SmartKBS`）
3. 安装 Python 依赖：
```bash
pip install -r requirements.txt
```
4. 启动服务：
```bash
python backend/main.py
```
### 方式三：Git 克隆部署（推荐学校机房，支持在线升级）
```bash
git clone https://github.com/youufis/SmartKBS.git
cd SmartKBS
pip install -r requirements.txt
python backend/main.py
```
### 在线升级系统（Git 部署专属）
如果通过 `git clone` 部署，系统升级全自动完成：
1. 管理员登录 → 系统配置 → **版本管理**
2. 点击「检测更新」，系统自动对比 GitHub 最新版本
3. 点击「增量升级」，自动执行：
```text
git fetch（增量拉取差异代码）→ git reset（同步文件）
→ 数据库迁移 → pip 增量安装 → 重启服务
```
4. 升级失败自动回滚，进度实时显示
> **💡** 首次点击「增量升级」时，系统会自动执行 `git init` + `git remote add` 初始化本地仓库，无需手动配置即可享受在线升级。
### PIP 国内镜像加速
```bash
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```
**可选增强依赖**
| 依赖 | 作用 | 缺少时 |
| --- | --- | --- |
| `matplotlib` | 试卷与讲义中的 LaTeX 公式渲染为图片 | 公式降级为 Unicode 文本，不影响其他功能 |
| `cairosvg` | SVG 配图栅格化 | 自动降级到 svglib，中文标注与渐变还原度下降 |
两者都按需用 `pip install matplotlib` 单独安装即可，未列入 `requirements.txt` 以免拖慢基础安装。
---
[object Object]
---
## 快速开始
**环境要求**
- Python **3.11+**（开发与打包实测版本 3.11.9）
- Node.js 仅在需要开发前端时安装；桌面版已内置全部运行时
### 步骤 1：启动后端服务
```bash
# 方式一：直接启动
python backend/main.py
# 方式二：使用 Uvicorn 启动（开发模式，热重载）
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8086 --reload
```
后端默认运行在 `http://localhost:8086`，并自动托管 `frontend/dist` 的前端产物，无需额外配置。
### 步骤 2：启动前端开发服务器（仅开发前端时需要）
```bash
cd frontend
npm install
npm run dev
```
前端开发模式默认运行在 `http://localhost:5173`，接口请求代理到后端。
### 步骤 3：以默认管理员登录
| 用户名 | 密码 |
| --- | --- |
| `root` | `root` |
> 🔑 首次登录后请立即修改密码并设置密保问题，避免默认凭据留在生产环境。
### 步骤 4：配置 AI 服务
进入「系统配置」填写 DashScope API Key（及可选的百炼知识库 / 智能体应用配置、DeepSeek Key）。配置页内置模型清单与连通性自检按钮，填完当场知道对不对。
未配置 AI 服务时，题库、考试、点名、资源、积分等主流程功能仍可使用，仅 AI 相关入口会给出明确提示。
---
## 项目结构
**随源码分发（入库内容）**
```text
SmartKBS/
├── backend/ # FastAPI 后端
│ ├── main.py # 入口：路由挂载、静态文件托管
│ ├── config.py # 全局配置常量
│ ├── database.py # 业务库 smartkb.db + 年级/班级主数据
│ ├── question_db.py # 试题库 questions.db
│ ├── auth.py # JWT 认证 · bcrypt · Token 版本 SSO
│ ├── middleware.py # 认证中间件与角色校正
│ ├── permission_service.py # 统一年级班级权限服务
│ ├── rag.py # 检索增强（题库 + 课程大纲）
│ ├── bailian_kb.py # 百炼知识库检索
│ ├── ai_task_manager.py # AI 异步任务管理
│ ├── question_fill.py # 凑题策略（题库优先 → AI 补差）
│ ├── question_select.py # 选题引擎
│ ├── paper_compose.py # 组卷与卷面分值配平
│ ├── paper_generator.py # Word 试卷生成（python-docx）
│ ├── reward_engine.py # 积分奖励引擎
│ ├── title_system.py # 12 级称号 + 成就徽章
│ ├── companion_*.py # AI 学伴：记忆 / 配置 / 主动推送
│ ├── code_grader.py # 代码自动评分
│ ├── code_runner.py # 代码沙箱执行
│ ├── whiteboard_ws.py # 白板 WebSocket 管理
│ ├── ws_manager.py # 讨论 WebSocket 管理
│ ├── tts_service.py # 语音合成（点名播报）
│ ├── model_catalog.py # 模型候选清单与能力边界
│ ├── skill_engine.py # AI 技能注入引擎
│ ├── api/ # 48 个模块：各业务路由 + AI 调用与生图服务
│ │ ├── ai_service.py # AI 统一调用（三模式自动接管）
│ │ ├── image_gen_service.py # 通义万相图片生成
│ │ └── *_router.py # 考试 / 题库 / 互动 / 学情 / 白板 …
│ ├── prompts/ # AI 提示词模板（按场景分组）
│ ├── skills/ # 20 个技能：core 8 + domain 12（*.skill.md）
│ ├── locales/ # 后端文案 zh-CN / en
│ └── migrations/ # 数据库迁移脚本
├── frontend/ # React + Vite + TypeScript 前端
│ ├── src/
│ │ ├── api/ # 接口封装
│ │ ├── components/ # 公共组件
│ │ ├── pages/ # 页面
│ │ ├── stores/ # Zustand 状态
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── types/ # 类型定义
│ │ ├── i18n.ts # 中英切换入口
│ │ └── styles/ # 主题与外观
│ └── dist/ # 预编译产物（后端直接托管）
├── requirements.txt # Python 依赖
├── version.json # 当前版本与更新日志（在线升级读取）
├── LICENSE # AGPL-3.0
├── README.md · README.en.md # 中英文文档
└── .markdownlint.json # 文档规则
```
**运行时生成，不随源码分发**（首次启动自动创建，也是备份时应保留的内容）
| 目录 / 文件 | 内容 |
| --- | --- |
| `backend/smartkb.db` | 用户、积分、点名、任务、通知等业务数据 |
| `backend/questions.db` | 试题库与考试数据 |
| `backend/system_config.json` | 运行时配置（学科、模型、API Key 等），含密钥故不入版本库 |
| `root/`、`stu/` | 管理员与各学生的数据目录（对话历史、教学资源 HTML、画像等） |
| `question_media/` | 试题配图，按题目 ID 分目录 |
| `temp_uploads/` | 临时上传文件，超 24 小时自动清理 |
| `LogFiles/`、`backend/logs/` | 运行日志 |
| `db_backups/`、`.upgrade_backups/` | 数据库备份与升级回滚快照 |
> 🖥️ 桌面版（Electron + PyInstaller）为本地构建产物，工程目录未随源码分发；发行安装包通过 GitHub Releases 提供，数据存放于 `%APPDATA%\SmartKBS\`。
---
## 数据存储
| 数据类型 | 存储位置 |
| --- | --- |
| 用户/积分/点名/任务/通知等核心业务数据 | `backend/smartkb.db`（SQLite） |
| 试题库与考试数据 | `backend/questions.db`（SQLite） |
| 对话历史 | `<用户目录>/ChatHistory/` 按日期分目录 |
| 教学资源 | `<用户目录>/html/` 各账号独立 |
| 系统配置 | `backend/system_config.json` |
| 用户 API Key | 环境变量 `DASHSCOPE_API_KEY` / 系统配置 |
| 试题配图 | `question_media/` 按题目 ID 分目录 |
| 临时上传文件 | `temp_uploads/`（自动清理超 24 小时） |
| 自我画像 | `<用户目录>/portraits/` |
| 白板快照 | 数据库 `whiteboard_pages` 表 |
---
> 💾 **备份清单**：迁移或升级前，保留 `backend/smartkb.db`、`backend/questions.db`、`backend/system_config.json` 与 `root/`、`stu/`、`question_media/` 三个内容目录即可完整还原；桌面版对应 `%APPDATA%\SmartKBS\` 整个目录。
---
## 权限总览
| 页面/功能 | 学生 | 教师 | 管理员 |
| --- | :---: | :---: | :---: |
| 系统首页仪表盘 | ✅ | ✅ | ✅ |
| AI 对话（智答模式） | ✅ | ✅ | ✅ |
| AI 学伴模式 | ✅ | ❌ | ❌ |
| AI 教学助手模式 | ❌ | ✅ | ✅ |
| 课程大纲（学习） | ✅ 查看/练习 | ✅ 管理 | ✅ 管理 |
| 课程进度追踪 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 试题管理 | ❌ | ✅ | ✅ |
| 考试中心（参加） | ✅ | ✅ 管理 | ✅ 管理 |
| 智能组卷 & Word 导出 | ❌ | ✅ | ✅ |
| 同步练习 | ✅ 参与 | ✅ 出题 | ✅ 出题 |
| 课程练习 | ✅ 练习 | ✅ 出题 | ✅ 出题 |
| 每日精选 | ✅ | ✅ | ✅ |
| 热点新闻 | ✅ | ✅ | ✅ |
| 对话作业 | ✅ 提交 | ✅ 管理 | ✅ 管理 |
| 待办事项 | ✅ | ❌ | ❌ |
| 资源中心（浏览共享） | ✅ | ✅ | ✅ |
| 资源管理 | ❌ | ✅ | ✅ |
| 资源分类导航 | ✅ | ✅ | ✅ |
| 文件中心 | ✅ 共享文件 | ✅ | ✅ |
| 课堂积分 | ✅ 查看 | ✅ 自己班级 | ✅ 全部 |
| 积分奖励体系 | ✅ 查看 | ✅ 自己班级 | ✅ 全部 |
| 点名管理 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 考勤统计 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 随堂测验 | ✅ 答题 | ✅ 创建 | ✅ 创建 |
| 课堂投票 | ✅ 投票 | ✅ 创建 | ✅ 创建 |
| 提问管理 | ✅ 提问 | ✅ 审批 | ✅ 管理 |
| 分组讨论 | ✅ 参与 | ✅ 管理 | ✅ 管理 |
| 知识抢答 | ✅ 参与 | ✅ 管理 | ✅ 管理 |
| 知识闯关 | ✅ 闯关 | ✅ 管理 | ✅ 管理 |
| 代码练习 | ✅ | ✅ | ✅ |
| 错题巩固 | ✅ 自己 | ✅ 全班 | ✅ 全班 |
| 学情分析 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 进度详情 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 成长档案 | ✅ 自己 | ✅ 全班 | ✅ 全班 |
| AI 课堂总结 | ❌ | ✅ | ✅ |
| AI 自我画像 | ✅ | ✅ | ✅ |
| 协作白板 | ✅ 参与 | ✅ 创建 | ✅ 创建 |
| 活动监控 | ❌ | ✅ | ✅ |
| 活动数据重置 | ❌ | ✅（仅本人活动） | ✅（全部活动） |
| 资源浏览统计 | ❌ | ✅ | ✅ |
| AI 资源推荐 | ❌ | ✅ | ✅ |
| AI 生成 HTML 资源 | ❌ | ✅ | ✅ |
| 数据导出 | ❌ | ✅ | ✅ |
| 用户管理 | 仅改密 | ✅ 部分 | ✅ 全部 |
| 系统公告 | ✅ 查看 | ✅ 发布 | ✅ 发布 |
| 通知中心 | ✅ | ✅ | ✅ |
| 系统配置 | ❌ | ❌ | ✅ |
| 在线升级（版本管理） | ❌ | ❌ | ✅ |
| 多主题系统 | ✅ | ✅ | ✅ |
| 关于系统 | ✅ | ✅ | ✅ |
---
## 技术栈
| 层级 | 技术 |
| --- | --- |
| 后端框架 | Python 3.11+ · FastAPI · Uvicorn |
| 前端框架 | React 19 · TypeScript · Vite 8 |
| UI 组件库 | Ant Design 6 |
| 图表 | Recharts |
| Markdown 与公式 | react-markdown · KaTeX |
| 代码编辑器 | Monaco Editor（代码练习页） |
| 白板引擎 | tldraw 5 |
| 状态管理 · 路由 | Zustand · React Router 7 |
| 国际化 | i18next（全站中英切换，前后端各有文案包） |
| 数据库 | SQLite 双库（业务库 + 试题库），无外部数据库依赖 |
| 认证 | JWT（bcrypt 哈希 + PyJWT），Token 版本实现单点登录 |
| AI 模型 | 通义千问 DashScope（Qwen）· DeepSeek |
| AI 调用模式 | 知识库检索增强 / 百炼智能体应用 / 直接调用大模型，按优先级自动接管并逐级降级 |
| 图片生成 | 通义万相（wanx2.1 / wanx2.2） |
| 语音合成 | DashScope TTS（点名播报，可选） |
| 流式与实时 | Server-Sent Events（AI 流式）· WebSocket（白板 / 分组讨论 / 抢答） |
| 文档导出 | python-docx（Word）· openpyxl（Excel） |
| 公式出图 | matplotlib（可选增强，缺失时降级为 Unicode 文本） |
| 代码沙箱 | AST 静态分析 + subprocess 隔离 |
| 桌面版 | Electron + PyInstaller + Vite 产物（仅发布 Windows x64 安装包） |
---
## 许可证
本项目以 **AGPL-3.0** 开源，完整条款见 [LICENSE](LICENSE)。
- ✅ 可自由使用、修改、分发，校内直接部署不受限制；
- ⚠️ 若修改本系统后**通过网络对外提供服务**，须以相同许可证公开你的修改源码；
- ℹ️ 独立于本项目、仅通过接口通信的自有系统不受此约束。
Copyright © 2026 youufis (UNET)
---
## 常见问题
- **忘记密码怎么办？**
设置了密保问题的账号，可在登录页点「忘记密码」自助找回；否则联系管理员在「用户管理」中重置。
- **AI 对话没有回复？**
先在「系统配置」确认 API Key 已填写且余额充足，再用配置页的连通性自检按钮验证；自检报错会指明是模型、知识库还是智能体应用的问题。
- **文件上传失败？**
文档上限 10 MB、图片上限 5 MB（图片上限可在系统配置中调整），并需符合扩展名与内容白名单。
- **AI 学伴 / 教学助手打不开？**
学伴仅学生可用，助手仅教师与管理员可用，先确认登录角色；教师还需在「用户管理」里配置任教年级与班级，否则AI 助手取不到教学范围。
- **考试无法提交？**
检查当前时间是否在考试有效期内、答题次数是否已用完；卷面处于「有人在作答」状态时教师改题会被拒绝，这是锁卷保护。
- **课堂积分没增加？**
只有支持积分的活动类型会在完成后自动发放，且设有每日封顶（可在系统配置调整）；教师与管理员不参与积分与榜单。等级奖励需要达到相应成绩百分比。
- **改了代码或升级后界面没变化？**
先硬刷新（Ctrl+F5）；涉及 WebSocket、语音合成、AI 超时策略的改动需要**重启后端**才生效。
- **如何升级系统？**
1. Git 部署：管理员登录后进入「系统配置 → 版本管理」，点「检测更新」再「增量升级」，失败会自动回滚；
2. 源码包部署：下载最新 ZIP 覆盖原目录，保留 `backend/system_config.json` 与两个 `.db` 文件后重启；
3. 桌面版：下载新版安装包直接覆盖安装，数据在 `%APPDATA%\SmartKBS\` 不会丢。
- **新机器装完起不来？**
先确认 Python 为 3.11+，再核对依赖是否装全（`pip install -r requirements.txt`）；报错提示缺少模块时，优先检查该模块是否已在 requirements.txt 中。
---
## 关于
**SmartKBS** — 面向小学、初中、高中学段的 AI 智慧教学平台，学科与年级班级配置驱动。
- 👨💻 **作者：** youufis (UNET)
- 📧 **联系：** [youufis@sina.com](mailto:youufis@sina.com)
- 💬 **微信：** UNET-WX
- 📄 **许可证：** [AGPL-3.0](LICENSE)
项目由个人独立开发维护，迭代以真实课堂反馈为驱动 —— 版本节奏、功能取舍、乃至「按需调用不烧钱」这类设计，都来自一线使用中的问题。遇到 bug 或有想加的功能，欢迎开 Issue 或邮件联系。