# SmartKBS 智慧学平台
**Repository Path**: youufis/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**: 18
- **Forks**: 9
- **Created**: 2026-09-25
- **Last Updated**: 2026-10-06
## Categories & Tags
**Categories**: instructional
**Tags**: 智慧教学, AI教育, 在线考试, 智能组卷, 题库
## README
# 智慧教学平台 (SmartKBS)
> **🌐 [English](README.en.md) | [中文](README.md)**
> 全学段全学科通用 AI 智慧教学管理平台 — **任何学科、任何学段均可使用**
>
> 集成 AI 流式对话、学伴/助手、试题库、在线考试、智能组卷与 Word 导出、
> 课程大纲、课堂互动（随堂测验/投票/提问）、分组讨论（AI 助教）、
> 知识抢答活动、知识闯关挑战、代码练习、编程自动批改、
> 积分奖励体系（12 级称号 + 成就徽章）、课堂积分、智能点名、考勤统计、
> 错题巩固、同步练习、课程练习、每日精选、热点新闻、AI 资源推荐、学情分析、成长档案、
> AI 自我画像、协作白板、课堂总结、活动监控、资源浏览统计、
> 对话作业与 AI 智能批改、用户管理、系统公告、通知中心、
> 在线增量升级、多主题外观系统、全学段年级班级体系等 **50+ 功能模块**。
>
> 基于 **FastAPI + React** 构建，深度集成阿里云 DashScope 与 DeepSeek AI 能力。
---
---
> 📌 **V8.6.0 更新亮点**：
> 🔊 **语音合成落地**：系统配置新增语音合成小节（开关 / 模型 / 音色 / 语速 / 音量），音色只列实测出声成功的 23 条，关闭即零计费调用，不新增任何依赖
> 🗣 **智能点名会念名字**：点到谁就念出谁的姓名，音频藏在揭示动画里、教师无感；同名缓存，多音姓氏自动校正，界面仍显示原姓名
> 🧭 **模型可选 + 配置自检**：对话 / 长文本 / 视觉 / 生图模型改为下拉选择（清单外仍可直接填写），生图与语音合成各加一个自检按钮，配置填完当场就知道对不对
> 📊 **登录页访问统计**：在线人数之外，新增今日访问（人数/人次）与累计次数；正文只留数字并按量级缩写，手机端也只占一行
> 🖼 **生图两代通道自动分派**：按模型自动路由到对应调用通道，尺寸默认「自动」、可选档位按各模型实测边界过滤，配错保存时即拦下；入口页不再被浏览器缓存，发版后无需强刷
> 🧮 **考试卷面分值做成硬不变量**：卷面合计必须等于目标总分，加题删题自动配平；新增「卷面体检」，默认只试算、确认才修复
> 🎯 **选题三套并成一套**：自动选题 / AI 生成 / 智能组卷共用一份引擎，配置阶段就显示题库供给量、超配标红
> 🔢 **导出显示修复**：配图中文不再变豆腐块、解析公式正常渲染、填空位不再消失，并修掉导出永久卡死
> 🔀 **题目拖拽排序** + 🔒 **有人在作答就锁卷** + 🎲 **题目乱序真正生效** + ⏱ **AI 生成与配图改后台任务**（带进度、连点不重复计费）
> 📱 **手机适配落地**：手机浏览器打开即用，底部标签栏 + 按角色白名单，桌面端与桌面版版式零变化
> 🖼 **试题配图链路治理**：题库 / 闯关 / 白板配图分目录隔离，矢量图统一安全清洗，配图管理重新可用
> 🏆 **积分防刷与学生荣誉收口**：对话、抢答、总分每日封顶可调，教师与管理员退出积分与榜单，学生端新增「本周之星」
> 🛡 **运维与配置体验**：暂停学生 / 教师 / 外网登录三开关、升级历史批量删除、在线升级多镜像兜底、登录历史统一管理、技能按场景精准注入；每日请求限额并入「AI 对话权限」小节
---
## 📋 项目简介
**SmartKBS** 是一款功能完备的全学段全学科通用 AI 智慧教学管理平台，专为中小学及高中教育场景设计。系统不限定任何特定学科，通过灵活的配置即可适配数学、语文、英语、物理、化学、生物、历史、地理、信息科技、通用技术、人工智能等任意学科的教学需求。
系统基于 **FastAPI + React** 构建，采用现代化前后端分离架构，深度整合阿里云
DashScope（通义千问/通义万相）与 DeepSeek 等大语言模型能力，通过灵活的 AI 调用服务
（支持知识库+大模型、百炼智能体应用、直接调用大模型三种模式，按「知识库 > 智能体 > 大模型」优先级自动接管），为师生提供一站式的智能化教学与学习体验。
**📦 三种部署方式**：Windows 桌面版一键安装（零环境，不需要 Python / Node.js）· 源码包部署 · Git 克隆部署（支持在线增量升级）。详见 [部署安装指引](#-部署安装指引)。
> 💡 **核心设计理念**
>
> - **🧠 AI Native 全场景注入**
> AI 不是外挂工具，而是贯穿教、学、练、评、管的原生能力。
> 每一次对话、每一道试题、每一份报告都有 AI 深度参与，
> 却又让师生"感受不到 AI 的存在"，自然融入教学流程。
>
> - **🎯 因材施教 · 千人千面**
> 学生端 AI 学伴根据年级、知识薄弱点、学习习惯
> 动态调整对话风格与推荐内容；教师端 AI 助手
> 按任教班级、学科、时段提供精准的备课辅助与学情洞察。
>
> - **🔄 教学闭环 · 数据飞轮**
> 从学习行为采集 → AI 分析 → 个性化反馈 → 行为改善，
> 形成完整数据飞轮。每一次考试、练习、对话都在丰富
> 学生画像，反哺后续 AI 决策。
>
> - **⚡ 反浪费架构 · 零闲置 AI**
> 所有 AI 调用按需触发，无人访问不消耗任何资源。
> 每日精选池、热点新闻缓存、AI 摘要懒加载，
> 确保每一分算力都花在刀刃上。
>
> - **👥 角色感知 · 双轮驱动**
> 学生 → AI 学伴（陪伴式学习），教师 → AI 助手
> （减负增效），管理员 → 全局智控。
> 三者各司其职，互不干扰。
>
> - **🏆 游戏化激励 · 内生驱动**
> 12 级称号系统 + 成就徽章 + 积分奖励引擎，
> 将学习过程转化为有成就感的成长旅程。
> 不靠外部压力，而靠持续的正反馈激发学习动力。
>
> - **🌐 学科无关 · 灵活适配**
> 任何学科、任意学段均可通过配置快速适配。
> AI 提示词动态构建，无需修改代码即可切换课程体系。
---
## 🎮 演示环境
> **🌐 演示地址：**
>
> **开发环境：** [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 |
---
## ✨ 完整功能总览
### 📱 手机访问
平台可直接用手机浏览器访问，**无需安装 App**。手机端定位是「学生练与查、教师看与批」，管理型重页面保持电脑端专属。
#### 手机已开放的页面
| 角色 | 数量 | 页面 |
| --- | --- | --- |
| 学生 | 27 | 首页、AI 学伴、错题巩固、每日精选、热点新闻、通知中心、系统公告、课堂提问、知识抢答、待办清单、对话作业、积分称号、考试与成绩、AI 周画像、学伴设置、知识闯关、同步练习、课堂互动、课堂投票、分组讨论与讨论室、文件中心、成长档案、风采展示、我的资源、资源中心、关于系统 |
| 教师 / 管理员 | 22 | 首页、AI 助手、通知中心、系统公告、提问管理、AI 课堂总结、学情分析、对话作业批改确认、课堂积分、AI 周画像、分组讨论与讨论监控、闯关记录查看、汇总统计导出、文件中心、成长档案、风采展示、我的资源、资源中心、资源管理、关于系统 |
#### 手机端怎么用
- 底部标签栏固定 5 格：首页 / 学伴（教师为助手）/ 错题（教师为提问）/ 通知 / **菜单**，「菜单」打开当前角色全部可用功能
- 未适配的功能在手机端不显示入口；直接输入地址会看到「此功能请在电脑端使用」，可一键返回上一页
- 考试作答、抢答答题、闯关战斗是独立全屏页，选项按钮按触屏放大，倒计时与进度常驻顶部
- 列表类数据（通知、公告、考试、抢答记录、作业、资源）在窄屏自动改为卡片或可横向滚动，标题不会被压成竖排
#### 保持电脑端专属
试题管理与智能组卷、题库维护、用户管理、系统配置、点名管理、活动监控、汇总导出、课程大纲维护、知识闯关管理、代码练习、协作白板、管理控制台
#### 🏠 首页概览
### 📊 系统首页（仪表盘）
登录后默认进入智能首页仪表盘，按角色聚合展示关键数据：
**学生端：**
- 📋 待完成考试数、已完成考试数
- 🏆 累计课堂积分与班级排名
- ✅ 活跃任务数与本周对话次数
- 📝 待答随堂测验数、已参与投票数
- 📅 待参加的考试列表（一键开始）
- 📈 近期考试成绩（得分/是否通过）
- 📢 系统公告滚动展示
- ⏱️ 最近活动动态时间线
- 🚀 快速入口（知识问答/考试中心/积分/互动）
**教师/管理员端：**
- 📊 考试概览（总数/草稿/已发布/已结束）
- 📋 任务提交总数与活跃任务数
- 👥 学生总数、教师总数、任教学科
- 🎯 本周点名次数
- 📝 随堂测验总数与进行中数量
- 📊 活跃投票数与回应人数
- 💬 今日对话数
- 🚀 快速入口（AI 对话/考试发布/点名/用户管理/互动）
> **所有登录用户可用**
---
### 📋 待办事项（学生任务聚合）
学生端专属任务聚合看板：
- 📊 按分类聚合待办事项（考核测评、课程学习、互动课堂、共享资源、系统服务）
- 🔴 即将截止高亮提醒
- 🚀 一键跳转到对应功能页面
- 📈 完成进度统计
> **学生可用**
---
#### 📚 教学管理
### 📖 课程大纲（课程导学）
课程 → 章 → 节 → 知识点四级树形结构：
- **🤖 AI 智能生成**：粘贴文本或上传文件（txt/md/pdf/docx），AI 自动提取课程结构
- **✏️ 手动管理**：添加、编辑、删除课程/章节/知识点
- **🔀 拖拽排序**：同级和跨层级拖拽排序，灵活组织
- **🔗 资源绑定**：为知识点绑定 7 类资源（HTML 课件、下载文件、试题、考试、讨论、随堂测验、任务）
- **✅ 学习进度追踪**：学生逐知识点学习，标记完成状态，实时进度条
- **📊 课程进度总览（教师）**：全班学生知识点完成进度矩阵，按年级/班级筛选
- **🏋️ 课程练习**：教师一键为知识点生成 10 道单选题，学生在线作答
> **管理员/教师可管理；学生可查看并标记进度**
---
### 📚 课程练习（知识点练习）
基于课程大纲知识点的 AI 练习系统：
- **🤖 AI 自动出题**：教师为知识点一键生成 10 道单选题
- AI 从题库智能搜索合并匹配题目
- 差额由 AI 补全新题
- 新题自动入库
- **✍️ 学生在线作答**：在课程学习页面点击知识点直接练习
- **🏆 自动积分奖励**：
- 参与基础分：2 分
- 优秀（≥90%）：+15 分
- 良好（≥75%）：+10 分
- 及格（≥60%）：+5 分
- **📊 数据展示**：首页看板展示完成数与平均正确率
- **📋 成长档案集成**：个人档案页集成练习明细
> **管理员/教师可出题；学生可参与练习**
---
### 💬 AI 对话（知识问答）
核心智能问答界面，基于 SSE 流式传输，提供流畅的 AI 对话体验：
- **⚡ 流式对话**：AI 实时逐字输出回复，即时反馈
- **📎 文件上传**：支持图片（JPG/PNG/GIF）和文档（PDF/Word/Excel/PPT/TXT/MD 等）
- **👁️ 图像理解**：上传图片调用视觉模型识别分析
- **🖼️ 多模态对话**：启用多模态后支持图片+文本同时输入，由多模态模型直接理解，无需文件摘要
- **📄 文件摘要增强**：自动对上传文档进行摘要，增强 AI 对话上下文
- **🔍 RAG 知识增强**：从试题库和课程大纲中检索相关知识，提升回答准确性
- **📜 历史记录**：自动保存并按会话标题显示，今天/昨天/按月分组，支持标题与正文搜索、悬浮预览、重命名与下载
- **👁️ HTML 预览**：对话中 HTML 代码块可一键预览
- **📋 示例提示词**：内置多个教学场景示例，一键填充
- **🎭 三种模式**：智答模式 / 学伴模式（学生）/ 助手模式（教师/管理员）
- **🎤 语音输入**：支持麦克风语音转文字输入
- **📷 拍照上传**：支持摄像头拍照直接上传
> **所有登录用户可用**
---
### 🧠 AI 学伴（学生专属）
AI 对话的智能升级模式，为学生提供个性化的学习陪伴体验：
- **👤 专属学习伙伴**：AI 学伴知道学生的姓名、年级、学习进度和薄弱知识点
- **🔄 三种人格切换**：
- 🌟 **鼓励型**：温暖热情，充满正能量，多用鼓励用语
- 📐 **严谨型**：严谨细致，注重分析"为什么错""怎么改"，举一反三
- 😄 **幽默型**：风趣幽默，适度用梗和调侃让学习不枯燥
- **📊 学习画像侧栏**：实时显示称号、积分、薄弱知识点、考试趋势、连续学习天数
- **🔔 主动推送**：早安问候、考试结果分析、称号升级祝贺、学习提醒
- **💾 对话历史统一管理**：与智答模式共用聊天历史系统
- **⚙️ 自定义设置**：可自定义学伴名称、人格、开关学伴、每日唤醒时间
- **🎨 视觉差异化**：紫色学伴风格气泡与头像
> **学生可用（智答页面顶部切换）**
---
### 🎓 教学助手（教师/管理员专属）
为教师和管理员提供的 AI 教学工具型助手：
- **📝 智能备课**：根据课题自动生成完整教案（教学目标、教学过程、课堂活动、作业设计）
- **📄 自动出卷**：按知识点/题型/难度生成试卷和随堂测验
- **📊 学情分析**：分析班级或学生个人成绩数据，指出薄弱点和进步空间
- **🎯 活动策划**：设计课堂互动方案（小组讨论、抢答、随堂测验等）
- **📋 教学数据侧栏**：实时显示学生人数、考试统计、提交任务、课堂互动等教学概览
- **🎨 视觉差异化**：青绿助手风格气泡与头像
> **教师/管理员可用（智答页面顶部切换）**
---
### 📝 同步练习（AI 定向出题）
教师从错题本或知识点生成针对性练习题，推送至班级或指定学生：
- **🤖 AI 出题**：从错题本或知识点自动生成针对性练习题
- **📤 定向推送**：推送至班级或指定学生
- **✍️ 学生作答**：在线答题，支持选择题和简答题
- **🤖 AI 自动批改**：简答题自动批阅
- **⚡ 异步出题**：不阻塞界面，支持后台生成
- **📊 练习记录**：历史练习查看与成绩统计
> **管理员/教师可出题；学生可参与**
---
### 📝 试题管理（智能题库）
AI 智能试题管理系统，支持多种题型和多媒体：
- **🤖 AI 一键生成**：按科目、题型、知识点、难度和数量自动生成试题
- **📤 智能提取**：支持粘贴文本或上传 .docx/JSON 文件，自动识别题型、选项和答案
- **📋 题型支持**：单选题、多选题、判断题、简答题、填空题、作文、主观题
- **📐 公式支持**：全面支持 LaTeX 公式（$...$）渲染显示
- **🖼️ 配图系统**：
- SVG 绘制技术图示
- 通义万相生成实物图片
- 支持图片生成、预览、删除，并发生成优化
- 图片占位符管理
- **📂 题库管理**：分类筛选、搜索、编辑、删除
- **🔄 AI 生图**：自动为主观题 SVG/图片占位符生成配图
> **管理员和教师可用**
---
### 📝 考试发布（在线考试系统）
完整的在线考试管理系统：
- **⚙️ 创建配置**：标题、科目、时长、总分、及格分、题目/选项乱序、答题次数、时间范围
- **📋 组卷方式**：
- **智能选题**：按题型/难度/知识点等条件组合筛选，AI 辅助
- **手动选题**：从题库逐题挑选
- **📋 考试流程**：发布 → 学生在线答题（实时倒计时） → 客观题自动批改 → 成绩查看
- **📊 成绩统计**：得分/总分/百分比/是否通过/排名
- **📤 数据导出**：成绩导出为 Excel
- **🔔 消息通知**：发布/取消/修改/提前结束时自动通知
> **管理员/教师可创建管理；学生可参加已发布的考试**
---
### 📄 智能组卷 & Word 导出
分步引导式组卷向导，支持智能选题与专业文档导出：
- **📋 配置向导**：题型题量配置、难度分布、知识点范围筛选
- **🤖 AI 智能选题**：按知识点智能匹配
- **📊 规则选题**：按难度比例随机抽取
- **📊 组卷统计面板**：实时题型/难度分布、总分，支持手动移除题目
- **📄 Word 导出**（三份文档）：
- **试卷**：学生用，含答题线
- **答案卷**：红色标注答案 + 蓝色解析
- **答题卡**：标准答题卡格式
- **📐 LaTeX 公式渲染**：matplotlib 渲染为图片嵌入
- **🖼️ SVG 自动转 PNG**：确保 Word 兼容性
- **📦 题型排序**：单选题 → 多选题 → 判断题 → 填空题 → 简答题 → 作文 → 主观题
> **管理员和教师可用**
---
### 📕 错题巩固
自动归集学生错题，AI 辅助复习：
- **📋 错题归集**：按考试归类展示错题
- **✅ 自主标记已掌握**：每道题可标为「已掌握」也随时取消，配合待掌握/已掌握/全部三档筛选，学生自己决定还要不要继续练
- **📐 多媒体展示**：支持 LaTeX 公式和配图显示
- **🤖 AI 复习计划**：一键生成个性化复习报告（错题分析、知识点复习建议、针对性练习题）
- **👁️ 三级联动查看（教师）**：按年级 → 班级 → 学生逐级筛选
- **📊 错题统计**：各科错题数和正确率
> **学生查看自己；教师/管理员可查看全班学生**
---
### 📁 资源中心（共享中心）
以卡片网格展示 HTML 教学资源文件：
- **👁️ 卡片浏览**：缩略图 + 文件名称
- **🔗 共享操作**：
- **管理员共享**：可选择「所有人」「指定教师」「指定年级/班级」
- **教师共享**：选择「管理员和教师」+「自己的班级」
- **🔍 搜索筛选**：按文件名搜索
- **🗂️ 统一浏览器**：学生端「共享资源」、教师端「共享给我的」与学生端「共享文件」共用同一套浏览界面（未看·时间·类型·课程·共享者·范围六维分类 + 网格/列表双视图 + 偏好记忆）
- **🔗 直达定位**：任务清单与共享通知点进去直接落到对应标签页，不会先跳回默认页再让人自己找
- **🤖 AI 生成**：5 种资源类型（动画讲解、互动答题、章节练习、实验互动、自定义 HTML）
- **👁️ 资源浏览统计**：自动记录学生查看行为
> **所有登录用户可用；学生仅查看共享资源**
---
### 📁 资源管理
上传/删除/重命名教学资源文件：
- 📤 上传文件、目录（HTML/CSS/JS/图片/文档等）
- 🗑️ 删除与重命名
- 📁 每位教师拥有独立资源目录
- 🔗 文件共享操作（同资源中心共享）
- 📊 配额管理
> **管理员和教师可用**
---
### 🤖 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 教育示意图 + 通义万相实景配图
> **管理员和教师可用**
---
### 📥 文件中心
下载目录文件管理：
- 📤 上传 / 📥 下载 / 🗑️ 删除
- 📊 配额管理（按教师独立配额）
- 📁 子目录支持
- 🔗 目录共享（整个目录自动继承权限；接收方显示为「文件夹」条目，内含文件数与总大小一目了然）
- 🗂️ 统一资源浏览器：与「共享资源」共用分类侧栏 / 统计条 / 网格·列表双视图 / 搜索排序分页与偏好记忆
- 👁️ 学生可查看共享文件，并记录未看·已看与浏览量（首次浏览奖励 1 分）
> **管理员和教师可用；学生可查看共享文件**
---
#### 🌐 知识拓展
### ⭐ 每日精选 & 📰 热点新闻
知识拓展双模块，让学生在学习之余轻松拓宽视野：
- **📖 每日精选**：AI 趣味知识卡片池，每人随机抽取 6 张，
7 天去重窗口，支持收藏与手动刷新。智能知识池按需补充，
无人用时不消耗 AI，浏览可获积分与徽章。
- **📰 热点新闻**：RSS 聚合多个主流新闻源（中新网、IT之家等），
AI 按需摘要 + 学科关联，支持今日简报、收藏与分页浏览（不再只能看到前 20 条）。
2h 缓存懒加载，72h 滚动清理，无人访问零抓取；源清单可在系统配置中修改，单源失效自动熔断并切备用源。
> **所有用户可用**
---
#### 💻 编程实践
### 💻 编程实践（代码练习）
在线编程练习与自动评分系统：
- **教师端**：
- 创建编程题目（题目描述、测试用例、示例代码）
- AI 代码审查
- 查看提交统计和学生代码
- **学生端**：
- 在线编码（语法高亮，支持 Python）
- 运行调试（自定义输入）
- 提交评分
- **🤖 自动评分引擎**：
- AST 静态分析 + 沙箱执行
- 逐用例比较输出
- 支持 Python
- 超时控制（10秒）
- **🔒 安全沙箱**：
- 危险模块黑名单
- 危险函数拦截
- 临时目录隔离
> **所有登录用户可用**
---
#### 🎪 课堂活动
### 🎯 课堂互动工具
#### 📋 随堂测验
课堂即时测验系统：
- ✏️ 可视化编辑器创建（单选/多选/判断）
- 🤖 AI 一键生成（指定主题/题型/数量）
- 📊 自动评分与结果统计
- 📐 支持 LaTeX 公式和配图
- 📤 数据导出
#### 📊 课堂投票
课堂即时投票系统：
- 📋 单选/多选模式
- 🤖 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 学习报告导出**
- **👁️ 权限控制**：学生查看自己，教师/管理员可查看任何学生
- **📊 课程练习集成**：练习统计与明细
> **所有登录用户可用**
---
#### ⚙️ 系统管理
### 👥 用户管理
完整的账号管理体系：
- **📝 注册用户**：支持管理员/教师/学生三种角色
- **✏️ 信息更新**：修改用户名、班级、年级、姓名、性别、角色、任教学科
- **🔑 修改密码**：所有用户可修改自己的密码；管理员可重置他人密码
- **🗑️ 删除用户**：逐条或批量删除
- **📤 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 小时的临时上传文件 |
## 📦 更新日志
### v8.6.0 (2026-10-05 ~ 10-06)
- 🔊 **语音合成落地**：系统配置新增「语音合成」小节（总开关、模型、音色、语速、音量），默认权威播报男声；音色清单只收实测出声成功的 23 条（精选 15 + 替补 8），总开关关闭时全线不产生计费调用，且不新增任何依赖
- 🗣 **智能点名接上语音播报**：点到的学生姓名会被念出来，音频在滚动揭示动画期间并行取好，教师无感；同名落盘缓存、第二次零延迟；等不到音频就放弃这一次播报，点名绝不被音频问题挡住；连按打断上一段、一轮只提示一次、离开页面自动收声
- 🔤 **多音姓氏自动校正**：内置约 40 条多音与易误读姓氏，按同音常用字替换、复姓优先匹配；只影响播报文本，界面、点名历史与积分记录仍是原姓名
- 🛡 **播报接口带权限与次数护栏**：只接受该班名册里真实存在的姓名，沿用点名的任教班级权限，另加每分钟次数限制；失败返回可读中文原因而非报错
- 🔧 **每日请求限额归位**：从「账号与安全」并入「AI 对话权限与每日限额」小节，谁能用与能用多少次放在一起；配置项与计数表全部不变，存量部署无需迁移
- 🧭 **模型候选集中一处、配置页改下拉**：对话 / 长文本 / 视觉 / 生图的可选模型统一到一份目录，配置页从手打文本框改成带说明的下拉（按推荐程度分组，清单外的模型名仍可直接填写）。此前模型名散在 18 个调用点，换一次默认值容易漏改，填了下线的模型也要等运行时才报错
- 🔎 **配置自检补齐**：生图与语音合成各加一个自检按钮，与既有的对话模型 / 智能体 / 知识库自检同口径。生图自检会回报实际走的通道与真正发出的尺寸，语音自检直接给一段可播放音频；两者限管理员并限次数，按钮旁注明会产生一次真实调用与少量费用
- 🖼 **生图两代通道自动分派**：新旧两代生图模型的调用通道、参数结构与尺寸规则都不同，旧代码只支持旧通道，而配置说明推荐的恰是新通道模型 —— 照说明改就全线生不出图。现在按模型自动路由，降级链也按各自通道重新装配参数；尺寸默认「自动」（不指定、由模型定），可选档位按每个模型的实测边界过滤，配错在保存时就拦下并写明规则
- 📊 **登录页访问统计**：原来只显示在线人数，现在补上今日访问（人数/人次）与累计次数。累计走一张**只增不减**的独立计数器 —— 管理员批量删除登录历史不会让这个数往回退（建档基线取当前留存条数，启用前已被删掉的历史追不回来，只偏低一次）。接口免登录、与登录页共用同一个 15 秒轮询并同频缓存，不给登录增加开销；统计写库失败只记日志，绝不拖垮登录
- 🗣 **语音合成加入第二代模型**：音色清单按模型分组（第二代自带方言与外语、英文音色更多），换模型时音色列表与默认音色自动跟着切。音色与模型不配对在保存时即拒绝（清单外手填的仍放行），运行时会回落本模型默认音色并留日志 —— 点名现场不会静默失声
- ⚡ **入口页不再被缓存**：入口 HTML 此前没有任何缓存指令，浏览器会沿用旧页面壳、一直跑旧的前端包，表现为"服务器已更新、管理员却看不到新功能"；现改为每次回源校验，发版后直接刷新即生效
- 🧪 **回归测试**：新增 102 条（模型目录一致性、尺寸实测边界、手填端点路由、音色配对、自检接口权限与节流），全量 542 通过
- ⚠️ **破坏性变更**：无（新增配置项都有默认值，计数表与存量配置不动，老部署升级后语音合成仍是关闭状态）
### v8.5.0 (2026-10-03 ~ 10-04)
- 🧮 **考试卷面分值做成硬不变量**：卷面合计必须等于目标总分；选题不再改写目标分，加题删题后按原有比例自动配平，判分满分按卷面实算，发布前强制体检并拦下失效题目、无法判分题型、零分值、及格分高于总分
- 🩺 **卷面体检与修复**：扫描历史上被改坏的卷子，默认只报告不改数据，逐题列出改分方案、确认后才执行；重复入卷自动删除，有人在作答的考试跳过，目标总分与及格分永不被动
- 🔒 **有人在作答就锁卷**：题目增删、改分、配平、排序检测到在途答卷即拒绝并说明是谁还在答；重复入卷被唯一约束挡住，批量写库收进单个事务，不再出现「半套卷子」
- 🎯 **选题三套并成一套**：自动选题 / AI 生成 / 智能组卷共用一份引擎（题型配额 + 难度配比 + 学科同族召回 + AI 结果不原样入库），题型分布不再靠运气；组卷阶段即显示每个题型可选数量、超配标红
- 🔢 **导出显示修复**：配图中文不再变豆腐块、解析里的公式正常渲染、填空位不再被吞成空白，并修掉一个会让导出请求永久卡死的缺陷
- 🔀 **题目拖拽排序与管理补齐**：决定排版顺序的字段第一次有了界面入口，整行可拖；题目可就地预览、批量移除与清空全卷、显示题型与难度分布
- 📄 **抬头随考试落库**：学校名与学期不再每次重填，三份文档共用一份页眉取数
- ⏱ **AI 生成与配图改后台任务**：不再同步挂长连接干等，带进度回传、连点去重不重复计费、超时提示「仍在后台进行」而非误报失败
- 🎲 **题目乱序真正生效**：此前只被读写、从未应用，全班题序其实完全一样；现按学生确定性打乱，刷新换设备不变、成绩零影响
- 📱 **手机适配落地**：断点体系与移动端外壳，按角色开放白名单（学生 27 页 / 教师 22 页），六批增量全部上手机，桌面端与桌面版版式零变化；窄屏表格自动横滑、弹窗宽度钳制、文案语言包收口
- 🖼 **试题配图链路治理**：题库 / 闯关 / 白板配图分目录隔离，自动生图的占位状态与图片一起落库，配图管理面板重新可用，矢量图统一安全清洗
- 🏆 **积分防刷与学生荣誉收口**：对话、抢答、总分每日封顶（可调，0 = 不限），点名改每日计分，幂等由唯一约束保证；教师与管理员不再进入积分、称号、徽章与一周之星，学生端新增「本周之星」
- 🔐 **登录历史与运维增强**：考勤统计新增管理员专用登录历史子页（筛选 / 分页 / 三表导出 / 批量删除），在线判定改按服务端活跃会话；新增暂停学生 / 教师 / 外网登录三开关、升级历史批量删除、在线升级多镜像与仓库真值兜底
- 🧠 **技能系统加固**：出题与判分等结构化输出摘除技能注入，新增场景映射与注入白名单，内容安全清单真正生效
- 🧪 **回归测试**：考试与组卷新增 130+ 条，覆盖分值、配平、在途守卫、排序、体检、导出与三个选题入口的一致性
- ⚠️ **破坏性变更**：无（历史卷子里若已有重复题目，唯一约束会降级为普通索引并记日志，不删任何数据）
### v8.0 – v8.4 (2026-09-05 ~ 2026-09-29)
- 🔒 **鉴权与越权收口**：逐功能体检 16 轮，收紧匿名读取与跨教师越权写入；点名与课堂互动归属以登录身份为准，活动与资源发布限本人任教班级，配置接口密钥掩码回显
- ⏱️ **AI 调用全面异步化**：批改移出请求线程、交卷加幂等回执、长任务端点各自配超时；SSE 流式修复并加启动自检
- 🎯 **课堂活动稳定性**：抢答全员答完自动推进、重置后可安全重开；闯关开局即返回、余题后台补货；编程题归口「代码练习」
- 🧮 **积分与数据口径**：9 类活动支持「清参与数据、留活动内容」的重置（干跑预览 + 名称二次确认 + 可回滚 + 全程审计）；删除或重置活动后立即重算受影响学生总分，不再留孤儿成绩；清理主库 7 张同名空壳表，荣耀殿堂与统计改读实时积分
- 📝 **教学主流程体验**：「任务管理」升级为「对话作业」，按教师要求逐条找证据批改；公式渲染统一 23 处；历史记录按会话标题分组、可搜索与重命名并自动与磁盘对账；跨活动成绩一键导出四表 Excel / CSV
- 📚 **知识库接管 AI 链路**：出题 / 教案 / 批改 / 学情 / 白板统一「先检索再生成」，检索失败自动降级并在聊天页展示引用来源；生成与判分加固（限制生成长度并记录截断、JSON 容错、答案归一化判分与入库查重）
- 📰 **资讯与看板重构**：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/
```
---
## 🚀 快速开始
### 环境要求
- Python 3.9+
### 1️⃣ 启动后端服务
```bash
# 方式一：直接启动
cd D:\SmartKBS
python backend/main.py
# 方式二：使用 Uvicorn 启动
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8086 --reload
```
后端服务默认运行在 `http://localhost:8086`，自动提供前端静态文件服务。
### 2️⃣ 启动前端开发服务器（仅开发前端时需要）
```bash
cd frontend
npm install
npm run dev
```
前端开发模式默认运行在 `http://localhost:5173`
### 3️⃣ 默认管理员登录
| 用户名 | 密码 |
| --- | --- |
| root | root |
### 4️⃣ 配置 AI 服务
在「系统配置」页面设置 DashScope API Key。
---
## 📁 项目结构
```text
SmartKBS/
├── backend/ # FastAPI 后端
│ ├── main.py # 入口文件（路由挂载、静态文件服务）
│ ├── config.py # 全局配置常量
│ ├── database.py # 数据库连接管理（smartkb.db）
│ ├── question_db.py # 试题库数据库（questions.db）
│ ├── auth.py # JWT 认证 + bcrypt 密码哈希 + SSO
│ ├── middleware.py # 认证中间件
│ ├── logger.py # 统一日志配置
│ ├── rag.py # RAG 检索增强生成
│ ├── paper_generator.py # Word 试卷生成引擎（python-docx）
│ ├── reward_engine.py # 积分奖励引擎
│ ├── ai_task_manager.py # AI 异步任务管理器
│ ├── permission_service.py # 统一年级班级权限服务
│ ├── companion_memory.py # AI 学伴记忆引擎
│ ├── companion_profile.py # AI 学伴配置管理
│ ├── companion_push.py # AI 学伴主动推送引擎
│ ├── title_system.py # 12 级称号 + 成就徽章系统
│ ├── score_utils.py # 积分工具函数
│ ├── subject_config.py # 学科配置
│ ├── code_grader.py # 代码自动评分引擎
│ ├── code_runner.py # 代码沙箱执行引擎
│ ├── whiteboard_ws.py # 协作白板 WebSocket 管理器
│ ├── ws_manager.py # WebSocket 连接管理器（讨论）
│ ├── downloads_api.py # 文件下载 API
│ ├── system_config.json # 运行时配置
│ ├── api/ # API 路由模块
│ │ ├── ai_service.py # AI 统一调用服务（三模式自动接管）
│ │ ├── image_gen_service.py# 通义万相图片生成
│ │ └── ... (路由文件)
│ ├── prompts/ # AI Prompt 模板
│ │ ├── chat.py, exam.py, paper.py, quiz.py
│ │ ├── companion.py, portrait.py, quest.py
│ │ ├── practice.py, recommend.py, report.py
│ │ ├── whiteboard_ai.py, html_generator.py
│ │ └── ...
│ └── migrations/ # 数据库迁移脚本
├── frontend/ # React + Vite + TypeScript 前端
│ ├── src/
│ │ ├── api/ # API 接口封装
│ │ ├── components/ # 公共组件
│ │ ├── pages/ # 页面组件
│ │ ├── stores/ # Zustand 状态管理
│ │ ├── types/ # TypeScript 类型定义
│ │ ├── hooks/ # 自定义 Hooks
│ │ └── styles/ # 主题样式
│ └── dist/ # 预编译构建产物
├── root/ # 管理员数据目录
│ ├── html/ # 教学资源
│ └── ChatHistory/ # 对话历史
├── stu/ # 学生数据目录
├── question_media/ # 试题配图文件
├── temp_uploads/ # 临时上传文件（自动清理）
├── LogFiles/ # 日志文件
├── package.json # 项目配置
├── requirements.txt # Python 依赖
└── README.md
```
---
## 💾 数据存储
| 数据类型 | 存储位置 |
| --- | --- |
| 用户/积分/点名/任务/通知等核心业务数据 | `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` 表 |
---
## 👥 权限总览
| 页面/功能 | 学生 | 教师 | 管理员 |
| --- | :---: | :---: | :---: |
| 系统首页仪表盘 | ✅ | ✅ | ✅ |
| AI 对话（智答模式） | ✅ | ✅ | ✅ |
| AI 学伴模式 | ✅ | ❌ | ❌ |
| AI 教学助手模式 | ❌ | ✅ | ✅ |
| 课程大纲（学习） | ✅ 查看/练习 | ✅ 管理 | ✅ 管理 |
| 课程进度追踪 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 试题管理 | ❌ | ✅ | ✅ |
| 考试中心（参加） | ✅ | ✅ 管理 | ✅ 管理 |
| 智能组卷 & Word 导出 | ❌ | ✅ | ✅ |
| 同步练习 | ✅ 参与 | ✅ 出题 | ✅ 出题 |
| 课程练习 | ✅ 练习 | ✅ 出题 | ✅ 出题 |
| 每日精选 | ✅ | ✅ | ✅ |
| 热点新闻 | ✅ | ✅ | ✅ |
| 对话作业 | ✅ 提交 | ✅ 管理 | ✅ 管理 |
| 待办事项 | ✅ | ❌ | ❌ |
| 资源中心（浏览共享） | ✅ | ✅ | ✅ |
| 资源管理 | ❌ | ✅ | ✅ |
| 资源分类导航 | ✅ | ✅ | ✅ |
| 文件中心 | ✅ 共享文件 | ✅ | ✅ |
| 课堂积分 | ✅ 查看 | ✅ 自己班级 | ✅ 全部 |
| 积分奖励体系 | ✅ 查看 | ✅ 自己班级 | ✅ 全部 |
| 点名管理 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 考勤统计 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 随堂测验 | ✅ 答题 | ✅ 创建 | ✅ 创建 |
| 课堂投票 | ✅ 投票 | ✅ 创建 | ✅ 创建 |
| 提问管理 | ✅ 提问 | ✅ 审批 | ✅ 管理 |
| 分组讨论 | ✅ 参与 | ✅ 管理 | ✅ 管理 |
| 知识抢答 | ✅ 参与 | ✅ 管理 | ✅ 管理 |
| 知识闯关 | ✅ 闯关 | ✅ 管理 | ✅ 管理 |
| 代码练习 | ✅ | ✅ | ✅ |
| 错题巩固 | ✅ 自己 | ✅ 全班 | ✅ 全班 |
| 学情分析 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 进度详情 | ❌ | ✅ 自己班级 | ✅ 全部 |
| 成长档案 | ✅ 自己 | ✅ 全班 | ✅ 全班 |
| AI 课堂总结 | ❌ | ✅ | ✅ |
| AI 自我画像 | ✅ | ✅ | ✅ |
| 协作白板 | ✅ 参与 | ✅ 创建 | ✅ 创建 |
| 活动监控 | ❌ | ✅ | ✅ |
| 活动数据重置 | ❌ | ✅（仅本人活动） | ✅（全部活动） |
| 资源浏览统计 | ❌ | ✅ | ✅ |
| AI 资源推荐 | ❌ | ✅ | ✅ |
| AI 生成 HTML 资源 | ❌ | ✅ | ✅ |
| 数据导出 | ❌ | ✅ | ✅ |
| 用户管理 | 仅改密 | ✅ 部分 | ✅ 全部 |
| 系统公告 | ✅ 查看 | ✅ 发布 | ✅ 发布 |
| 通知中心 | ✅ | ✅ | ✅ |
| 系统配置 | ❌ | ❌ | ✅ |
| 在线升级（版本管理） | ❌ | ❌ | ✅ |
| 多主题系统 | ✅ | ✅ | ✅ |
| 关于系统 | ✅ | ✅ | ✅ |
---
## 🔧 技术栈
| 层级 | 技术 |
| --- | --- |
| **后端框架** | Python 3.11+, FastAPI, Uvicorn |
| **前端框架** | React 19, TypeScript, Vite 6 |
| **UI 组件库** | Ant Design 6, Ant Design Charts |
| **状态管理** | Zustand |
| **路由** | React Router 7 |
| **数据库** | SQLite（双数据库架构） |
| **认证** | JWT（bcrypt + PyJWT），Token 版本 SSO |
| **AI 模型** | 通义千问 DashScope (Qwen), DeepSeek |
| **AI 调用模式** | 知识库+大模型 / 百炼智能体应用 / 直接调用大模型（三模式，按优先级自动接管；知识库链路不可用时自动降级） |
| **图片生成** | 通义万相 (wanx2.1/wan2.2) |
| **流式传输** | Server-Sent Events (SSE) |
| **实时通信** | WebSocket（白板 / 讨论 / 抢答） |
| **文档导出** | python-docx (Word), openpyxl (Excel) |
| **公式渲染** | matplotlib (LaTeX → 图片) |
| **白板引擎** | TLDraw |
| **安全沙箱** | AST 静态分析 + subprocess 隔离 |
---
## 📄 许可证
本项目基于 **GNU Affero General Public License v3.0 (AGPL-3.0)** 开源。
Copyright © 2026 youufis
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see .
---
## ❓ 常见问题
**Q: 忘记密码怎么办？**
A: 如果设置了密保问题，可在登录页点击「忘记密码」自助找回。否则请联系管理员在「用户管理」中重置密码。
**Q: AI 对话没有回复？**
A: 检查「系统配置」中是否已填写有效的 DashScope API Key。如已填写，检查 API Key 余额是否充足。
**Q: 文件上传失败？**
A: 文档最大 10MB，图片最大 5MB。请检查文件格式是否在白名单中。
**Q: 无法使用 AI 学伴/助手？**
A: 学伴模式仅学生可用，助手模式仅教师/管理员可用。请确认登录角色是否正确。
**Q: 考试无法提交？**
A: 检查是否在考试有效时间范围内，以及答题次数是否已用完。
**Q: 课堂积分未增加？**
A: 确认参与了支持积分的活动类型。积分在活动完成后自动发放，等级奖励需达到相应成绩百分比。
**Q: 如何升级系统？**
A: 1、管理员登录后，进入「系统配置 → 版本管理」，点击「检测更新」后按提示操作（仅 Git 部署支持）。
2、下载最新源码 ZIP 包，解压覆盖原目录（保留 `backend/system_config.json` 和数据库文件），重启服务。
---
## 📬 关于
**SmartKBS** — 全学段全学科通用 AI 智慧教学平台
- 👨💻 **作者：** UNET
- 📧 **联系：** [youufis@sina.com](mailto:youufis@sina.com)
- 💬 **微信：** UNET-WX