# Changelog

OpenMentor 的所有用户面变更都记录在此文件。

格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)：
**主版本号** 不兼容（数据库 schema 不向下兼容）·
**次版本号** 加功能（向下兼容）·
**修订号** 仅修 bug。

> 升级：UI-only / 不动 DB 的小改动，覆盖增量包即可；动 DB 或装新依赖的，整包重装并按 README 迁移数据。

---

## [Unreleased]

（暂无）

---

## [2.2.0] - 2026-07-07

> 本版新增「AI 生成图片 / 视频提示词语音输入」与「在线自动更新」。
> 仅新增功能、不改数据库 schema，向下兼容，故为次版本号 2.2.0。

### Added
- **生成弹窗语音输入**：在 AI 导师聊天里的「AI 生成图片」「AI 生成视频」提示词弹窗内新增麦克风，学生可直接说出想生成的画面，自动转成文字填进提示词框（可再编辑后生成）。复用现有硅基流动 SenseVoice 转写，需老师在「个人设置」配置硅基流动 API Key；仅在该 AI 导师开启「允许学生语音输入」时出现。
- **在线自动更新**：管理员可在「设置 → 检查更新」一键检查、下载并应用新版本。更新只替换程序代码，绝不改动本地数据库、AI 配置、学生上传的附件与 AI 生成图、语音缓存；被替换的旧版会自动备份到 `backups/` 可回滚。下载带 sha256 校验，应用后由启动器自动重启完成升级。

### Upgrade Notes
- 无新增数据库字段、无新增依赖。
- 在线更新仅在通过启动器运行的免安装包中生效；源码 / 开发模式下「应用更新」仅演练不落地。

---

## [2.1.0] - 2026-06-18

> 本版扩展 AI 模型来源（自定义 OpenAI 兼容）并新增校园版「全校统一 API」供给能力。
> 仅新增数据库字段、自动迁移、向下兼容，故为次版本号 2.1.0。

### Added
- **自定义 API（OpenAI 兼容）模型来源**：在「AI 配置」新增一类自定义来源，可接入任何 OpenAI 兼容服务（OpenAI、Kimi、各类中转 / 聚合 API、本地 vLLM 等）。可分别配置对话模型与图片生成模型（图片走标准 `/v1/images/generations` 接口）。
- **校园版「全校统一 API」共享**：管理员可在「AI 配置」勾选要分享的厂商并打开总开关，全校老师即可在「选择 AI 模型」及每个 AI 导师的模型选择里使用「学校统一 · 厂商」，直接用管理员配置的 API（含 Key），老师自己的配置不受影响。覆盖文本对话与图片生成。学校统一采购 API 后，管理员配一次，全校老师即可免费使用。

### Fixed
- AI 配置页切换到「自定义 API / 学校统一 API」时，会残留上一个厂商的「申请 Key / 下载」跳转按钮的问题（现对无申请链接的来源整行隐藏）。

### Upgrade Notes
- 新增数据库字段 `ai_config.share_to_campus`、`ai_config.shared_providers`；升级会自动迁移并自动备份，不覆盖现有数据，向下兼容。
- 无新增依赖。

---

## [2.0.0] - 2026-06-14

> 本版引入「OpenMentor 掌上讲台」教师手机 App 配套服务，并大幅扩展 AI 导师的多模态能力。
> 因数据库结构升级（新增数据表与字段，不向下兼容），按语义化版本规范定为**主版本 2.0.0**。

### Added
- **掌上讲台 App 配套（iOS）**：教师手机 App 全套服务端接口（扫码配对、长效令牌鉴权、独立设备表）。配套能力包括——
  - **锁屏推送**：学生举手、敏感词命中、额度预警、导师熔断、服务器下线，均可推送到教师手机锁屏。
  - **通知即操作**：推送点开直接弹处理面板，远程封禁/解禁学生、熔断/恢复导师、一键回复「收到」。
  - **移动控制台**：手机上调该导师的全部课堂开关（语音/朗读/图片/文件/生图/生视频/找老师）与黑名单，开关即时生效；右上角可调出学生扫码二维码。
  - **漫游备课**：手机改提示词、试聊、拍照入知识库。
  - **审对话**：查看某学生完整对话（含图片/视频/语音/文件）。
  - **下课一键总结**：本节课人数/提问/违禁/热词/风险生成图片卡片，转发教研群。
  - **数据任务**：手机查看提交列表、在线看附件、打开挂载 HTML 页。
- **学生语音输入**：学生可语音提问，支持「转写成文字」与「原声直达」（多模态模型直接听音频）两种方式。
- **AI 回复朗读（TTS）**：学生可朗读 AI 回复（免费在线音色，默认关闭，仅学生端）。
- **AI 导师知识库（RAG）**：老师可为导师上传/拍照录入资料，AI 优先依据资料作答。
- **AI 图片生成 / 视频生成**：导师可生成图片（多模型）与视频（豆包 Seedance，文生/图生）。
- **Cherry Studio 企业版**：新增第 7 类模型来源接入。
- **小组共享会话模式**：同组学生共享一个会话，@AI 召唤才回复，实时同步、按人配色。
- **老师试聊**：以教师预览身份进入对话自测，不计入统计与审计。
- **课堂投屏模式**：全屏展示学生访问二维码 + 实时进入/提问统计。
- **简体 / 繁体切换**：界面一键切换。
- **内置模板任务「作品采集与展览」**：随安装/升级自动下发，每位老师自动拥有专属一份（学生上传 → 数据大屏统计 → 作品展览画廊），三个页面自适应手机/平板，接口自动匹配本机地址，开箱即用。
- **数据任务置顶**：数据任务可置顶（最多 3 个），置顶项排在列表最前。
- **视频演示浮窗**：导航栏一键调出教学演示视频列表（B 站在线播放）。

### Changed
- **生产级服务器**：默认改用 waitress 多线程服务器，长时间挂机更稳定（未安装自动回退，无痛升级）。
- **打卡统计提速**：首页打卡地图改用聚合数据源，加载更快。
- **手机端聊天输入优化**：学生在手机访问导师对话时，多个动作按钮收纳进「+」菜单，不再挤占输入框（平板/桌面仍平铺）。

### Fixed
- 黑名单触发次数被统计成 2 次的问题（系统提示不再计入，并已修正历史数据）。
- 图片生成会重复显示、生成图在手机上超出气泡范围的问题。
- 换账号配对后手机收不到推送的问题。

### Upgrade Notes
- **本版升级数据库结构**：新增 `app_device`、知识库相关表，以及任务/消息/导师的多个新字段。升级会**自动迁移并自动备份**，不覆盖 `openmentor.db`、`.env`、`static/uploads/`、`static/reports/`、`backups/`。因 schema 不向下兼容，故为主版本号 2.0.0。
- **新增依赖**：opencc-python-reimplemented、edge-tts、waitress、httpx[http2]、PyJWT、cryptography、jieba（安装器已同步；缺失时对应功能自动关闭，不影响启动）。
- **锁屏推送**为可选能力：需自备 Apple 推送密钥（APNs）；多机构部署可通过中继地址下发。未配置时推送静默关闭，其余功能照常。
- 整包重装请按 README 迁移本地数据。

---

## [1.4.0] - 2026-05-25

### Added
- **数据使用矩阵支持远程维护**：数据任务详情页的数据使用矩阵现在支持从统一数据源读取，新增或调整场景卡片、提示词与演示视频时，不再需要修改项目代码。
- **数据使用矩阵手动同步**：页面提供同步入口，老师可以在更新内容后立即刷新矩阵；系统也会保留本地默认内容作为兜底，避免网络异常时页面空白。
- **公共广场同步刷新**：导师广场新增公共广场同步能力，支持手动刷新与定时刷新，方便老师更快看到最新共享的 AI 导师模板。
- **HTML 文件在线编辑**：数据任务中上传的 HTML 文件支持在线打开编辑，老师可以直接在后台修改采集页面或数据大屏页面。
- **HTML 链接一键修复**：在线编辑器可识别并替换旧的数据接口链接；带 AI 导师悬浮球的页面也可以选择目标导师后一键修复学生访问链接。
- **HTML 文件下载**：任务详情页为上传的 HTML 文件新增「下载」按钮，在线编辑后的文件也能重新下载到本地保存。
- **单学生 AI 学情报告**：对话审计页新增单个学生「报告」按钮，老师可以针对某个学生单独生成 AI 学情报告。

### Changed
- **公共广场数据存储与读取方式优化**：公共广场的共享模板改为更易维护的统一数据结构，并支持通过状态字段控制模板是否展示；旧公开接口仍作为兼容兜底。
- **首页打卡数据存储与读取方式优化**：打卡提交与地图统计统一由后端接口处理，减少前端页面对外部接口地址的直接依赖，同时保留旧数据读取兼容。
- **数据使用矩阵展示更易维护**：矩阵卡片按分类和序号稳定排序，后续添加新场景时能自动进入对应分类，不影响老师原有复制、查看和演示操作。
- **对话审计报告生成更灵活**：批量生成 AI 学情报告前可以勾选学生，并在浮窗中确认或修改报告提示词，避免学生过多导致上下文被截断，也方便按课堂需求调整报告重点。
- **对话审计按钮更紧凑**：学生列表中的「查看 / 报告 / 封禁」按钮统一为更短文案和更紧凑尺寸，尽量保持在同一行显示。

### Upgrade Notes
- 本次更新不改变老师本地数据库结构，不会覆盖 `openmentor.db`、`.env`、`static/uploads/`、`static/reports/` 和 `backups/`。
- 如果使用免安装包或无损升级包，仍按原方式运行启动器即可。外部数据源配置不随开源个人版发布包附带，缺少配置时会自动走兼容兜底逻辑。

---

## [1.3.0] - 2026-05-23

### Added
- **移动控制台**：AI 导师列表新增「移动控制台」入口和二维码，老师可以用手机或平板打开轻量控制台，在课堂中快速查看并管理自己的全部 AI 导师。
- **AI 导师课堂应急控制**：移动端支持切换图片输入、文件上传、图片生成等常用开关；支持维护黑名单分类与关键词、查看黑名单命中记录、禁用 / 解禁学生身份，以及一键熔断或重新启用某个 AI 导师。
- **学生链接移动端管理**：移动控制台中可查看学生访问链接和二维码，支持复制、投屏或转发；学生链接过期后，也可以在移动端直接重置有效时长。
- **数据使用矩阵**：数据任务详情页将原「数据提交说明」升级为卡片式「数据使用矩阵」，按「数据采集」和「数据分析」组织常用场景，页面不再直接铺开大段提示词。
- **5 个数据任务使用场景**：矩阵内置「基础提交页面」「附件采集功能」「AI 导师悬浮球功能」「基础数据大屏」「本地附件查看功能」5 张场景卡片，每张卡片都提供「查看 / 复制 / 演示」按钮。
- **数据大屏提示词模板**：新增「基础数据大屏」提示词，引导老师先提交 1-2 条测试数据，再复制数据接口返回的完整 JSON 样例，让 AI 更容易按真实字段制作实时数据大屏。
- **AI 导师悬浮球提示词**：新增可复制提示词，用于让 AI 在生成 HTML 数据采集页面时，把某个 AI 导师做成页面右下角悬浮球，学生填表时可以在小窗中同步向导师提问。
- **提示词视频演示**：数据使用矩阵的 5 个场景均已接入 B 站浮窗播放器，老师可以先看演示视频，再一键复制提示词照做。
- **模型配置视频演示**：设置页为 DeepSeek、豆包、阿里云百炼、智谱清言、硅基流动增加 API 申请 / 模型 ID 获取视频演示，帮助老师按当前官方页面找到正确配置项。
- **推荐他人使用入口**：顶部导航新增推荐按钮，点击后打开 `https://openmentor.top`，并自动复制网址到剪贴板，方便老师直接分享给同事。
- **OpenMentor Skill 入口**：页脚新增 OpenMentor Skill 链接，方便需要 AI Agent 辅助部署、配置和使用的老师查看配套 Skill。

### Changed
- **模型配置说明更稳妥**：不再依赖容易过时的推荐模型文案，改为提示老师以官方平台当前模型 ID 为准，并通过视频演示学习查找方式。
- **数据任务提示词区域更清爽**：提示词默认收纳到场景卡片和查看弹窗中，常用操作变成「复制」和「演示」，降低页面阅读负担。
- **导师广场操作文案优化**：克隆按钮文案简化为「克隆」，减少按钮文字过长导致的换行和视觉干扰。
- **页面入口轻量优化**：顶部工具区、页脚链接、版本形态标识等细节做了统一，导航栏更清爽，也更容易确认当前运行形态。

### Fixed
- **提示词复制更稳定**：复制逻辑增加浏览器剪贴板 API 与传统复制兜底，降低浏览器权限或环境差异导致复制失败的概率。
- **模型配置保存更稳**：保存某个模型配置时，尽量保留其他模型已有配置，避免部分表单提交误清空已经填写过的 API Key 或模型参数。
- **数据安全保护**：启动时增加运行数据保护检查；如果 `openmentor.db` 缺失但 `static/uploads/` 或 `static/reports/` 中已有数据，会停止启动并提示检查数据库，避免静默创建空库造成“数据像被清空”的错觉。

### Upgrade Notes
- 本次版本包含数据库结构的非破坏性迁移。首次启动会自动检查并补齐所需字段 / 表结构，真正迁移前会把 SQLite 数据库备份到 `backups/`。
- 覆盖更新时不要覆盖老师原有的 `openmentor.db`、`.env`、`static/uploads/`、`static/reports/` 和 `backups/`。这些目录和文件都属于本地运行数据。

---

## [1.2.2] - 2026-05-15

### Fixed
- 修复 v1.2.1「页脚版本号自动跟随 CHANGELOG」实际不生效的问题：版本号原本是模块加载时一次性算好缓存的常量，Flask debug 只监听 `.py` 变化，改 `.md` 后服务不会自动重载，footer 一直挂着旧版本号。改成**按 mtime 缓存的动态读取**——CHANGELOG 一改下次请求即生效，没改时零 IO 开销。

---

## [1.2.1] - 2026-05-15

### Added
- 数据任务详情页加 2 行新「参考提示词」复制按钮：
  - **带附件提交版** —— 老师做带附件上传的 HTML 表单时，AI 容易踩坑（漏 enctype、手动设 Content-Type 等），这条提示词把关键点都给 AI
  - **打开服务器本地文件夹版** —— 自部署场景下让大屏 / 数据看板加「📁 打开服务器文件夹」按钮，调 `POST /attachment/reveal` 在服务器机器上弹 Finder / 资源管理器

### Changed
- 页脚版本号现在**自动跟随 `CHANGELOG.md` 最新版本**走，每次发版只需在 CHANGELOG 顶部加一段 `## [X.Y.Z]` 条目，不用扫所有页面改硬编码版本

---

## [1.2.0] - 2026-05-14

### Added
- **AI 导师广场**：浏览全国老师分享的 AI 导师，按学科 / 学段 / 关键词筛选，一键克隆到自己的库直接使用
- **分享自己的导师到广场**：导师详情页一键发布；明确「公开 + 不可撤回」二次确认；填学科 / 学段 / 用途 + 选填昵称 / 学校
- **AI 优化已有提示词**：编辑导师时新增「AI 优化这段」按钮，老师说明优化方向（更适合小学生 / 增加互动性 / 缩短篇幅 等），AI 在保留原意基础上精准优化
- **更新日志页**：右上角用户菜单加「更新日志」入口，让老师知道每版改了啥

### Changed
- 多处 UI 一致性修复：AI 导师 / 数据任务 / 导师广场页标题字体统一成跟班级花名册 / 学情大屏一致的 serif 样式
- 导航栏「广场」入口去掉 emoji 改为「导师广场」

### Note
- 跳过 v1.1.5 直接发 v1.2.0，因 v1.1.4 发布后短期内累积了大量新能力，按 SemVer 升 minor 更合适
- 数据库 schema 不变，纯增量 UI 升级，可直接覆盖更新

---

## [1.1.4] - 2026-05-14

### Added
- **数学 / 化学公式渲染**：所有渲染 markdown 的页面（学生对话 / 老师审计 / AI 学情报告 / 智能分析）自动识别 LaTeX 数学公式（`$...$` / `$$...$$` / `\(...\)` / `\[...\]`）并用 KaTeX 排版；`\ce{...}` 化学公式由 mhchem 扩展支持。AI 导师讲二次函数、化学反应方程式时不再是裸文本。
  - 不污染代码块（`<pre>` / `<code>` 内不解析）
  - KaTeX 资源全部本地化（`static/vendor/katex/` 约 596KB），不依赖 CDN

### Changed
- 首页 hero 区按钮改为单行布局（`col-md-6 + col-md-6`），避免「📍 打卡与意见」按钮被挤到第二行
- `.gitignore` 把 `openmentor.db` / `.cert/` 从 git 追踪里摘出，老师本地测试不再污染仓库

---

## [1.1.3] - 2026-05-08

### Added
- **附件 docx / xlsx 在线预览**：浏览器端懒加载渲染（docx-preview + SheetJS），免下载查看 Word 文档与 Excel 工作簿
- **AI 学情报告 SSE 流式生成**：单学生 / 全班级一键生成结构化 Markdown 报告，AI 边写边显示，自动持久化到「报告历史」可回看 / 下载 / 删除
- **提示词草稿历史**：localStorage 自动保存最近 10 条 AI 生成的 system prompt，支持随时恢复 / 删除 / 清空
- **API Key 申请直达**：设置页选模型后下方自动出现「申请 API Key」按钮，链接到对应官网

### Patch · 2026-05-14
- 首页加 **「📍 打卡与意见」** 按钮 + 浮窗
  - 浮窗内 ECharts 中国地图实时打卡热力图（数据从 QuickForm 公开任务拉取）
  - 8 大行政区分组的省份选择，提交后自动刷新热力图
  - 「💬 提意见」外链跳飞书反馈表单
  - 增量更新包：`OpenMentor_热力图增量更新.zip`（templates/home.html + static/vendor/echarts/china.json）

---

## [1.1.2] - 2026-05-07

### Added
- **AI 学情报告**：基于学生对话历史和黑名单命中记录，AI 生成结构化分析报告
- **QuickForm 任务支持多模态附件上传**：原本仅采集 JSON 文本，现在 multipart 表单可附图片 / 文档 / 音视频；老师后台「查看附件」模态框预览
- **附件按日期分桶存储**：所有附件按 `<日期>/<会话>/` 二级目录组织，长期使用不会单层目录爆掉
- **服务器本机打开附件文件夹**：审计页一键 reveal in Finder / Explorer，自部署场景免下载

---

## [1.1.1] - 2026-05-07

### Added
- 首个公开发布版本，由 **厦门市演武小学 信息中心** 基于 [QuickForm 2.0](https://github.com/wstlab/quickform) 二次开发并开源
- 完整的 OpenMentor 核心能力：AI 导师创建 / 学生扫码即用 / AI 帮你写提示词 / 多模态对话 / 审计大屏 / 学情大屏 / 安全防护 / 6 大国产 LLM
- 严格遵循 QuickForm「加法不减法」原则，原有任务管理 / HTML 表单 / 数据采集 / AI 报告等功能 100% 保留

### Note
此前的 V1.0 / V1.1 为内部迭代版本，未公开发布。
