Smart Wrong Notebook (智能错题本)

简体中文 | English

一个基于 AI 的智能错题管理系统：拍照或输入题目后，由 AI 识别、解答、打知识点标签并评定难度，支持错题本管理、举一反三练习、组卷打印和掌握程度跟踪。

⬇️ 下载安装包 · 🚀 在线演示（账号 demo@localhost，密码 demo123456） · 🌐 项目介绍页 · 📖 使用文档（Wiki）

演示站点为共享账号，数据对所有访客可见，请勿录入个人信息。介绍文章：别让错题本变成抄题本：我给孩子用的 AI 错题本开源了 · 不用先配 API Key：接上 MiniMax 免费账号

• 🤖 AI 识题与讲解：拍照、截图或输入文字，AI 识别题目、生成答案和解析，分析错因，打知识点标签并评定 1～5 星难度。

• 🔊 会说话的 SVG 动画讲解：AI 把解题思路做成分步骤动画并逐步语音讲解，画面等语音读完再进入下一步。语音有两种选择：

  语音	效果	费用
  浏览器本地语音（Web Speech）	由设备自带的语音朗读，听起来比较生硬，音色因设备而异	免费
  云端 TTS 语音（MiniMax、千问、智谱 GLM-TTS、阶跃星辰、火山引擎豆包语音、火山引擎 Agent Plan、OpenAI）	声音自然，与真人讲题无异，所有设备音色一致	需要付费，建议购买 Token Plan 等套餐，比按量付费划算；火山引擎有免费试用额度，可参考文档自行开通

• 🆓 免费账号就能用：选择「MiniMax Code OAuth」渠道，用 MiniMax Code 账号网页登录即可使用，不需要购买 API Key，应用每天自动签到领取积分（见 MiniMax Code OAuth）；火山引擎新用户也有免费推理额度。

• 📚 复习闭环：举一反三变式题自动判题、AI 评估掌握概率、艾宾浩斯间隔的今日复习、按错题组卷打印并回填结果。

• 📦 多平台安装：Docker 镜像（amd64 / arm64）、npm、Windows、macOS、Linux、飞牛OS、安卓手机与平板（单机版或客户端），也可添加到手机主屏幕（PWA）。

本仓库 fork 自 wttwins/wrong-notebook，在其基础上增加了上述及下文列出的大部分功能。

以下截图采集自实际运行的应用（2026-10-20），展示已有题目、讲解和试卷。用户名已遮挡，可点击图片查看大图。

错题管理：在同一页面查看题目摘要、难度星级和知识点，按年级、学期、掌握情况及 A/B 卷筛选，也可通过题目 ID 定位、比较相似度或批量打印。列表按需加载卡片数据，原图、答案和解析在详情或打印预览时读取，减少翻页时的数据传输。

• 📷 多种录入方式：上传图片、从剪贴板粘贴（Ctrl/⌘+V）、屏幕截图，或直接输入题目文字（支持 Markdown 和 LaTeX）；图片可裁剪（支持滚轮、双指捏合或按钮缩放图片，方便精确框选），也可在一张图上框选多道题批量导入。
• 🤖 AI 识别与解答：识别题目文字、答案、解析、学生的错误解答和错因，判断学科，并从知识点库中选择标签。可在「设置 → 通用」中开启「导入前人工确认」，先在校对页修改再保存。
• 📷 照片格式与压缩：按文件内容识别真实格式（扩展名写错也能识别），支持 JPG、PNG、WebP、HEIC/HEIF。浏览器能解码 HEIC 时直接使用（如 Safari），不能时自动加载解码组件，在裁剪前转换为 JPEG 并按照片的旋转信息摆正；无法解码时提示具体原因。裁剪预览使用缩略图，最终从原图裁剪，输出按最长边 4096、约 490 万像素、1.5MB 共同限制，JPEG 质量不低于 0.8，体积超出时缩小尺寸而不是继续降低质量，避免题目小字和公式模糊。读取、转换、裁剪压缩、上传、AI 识别和保存各阶段显示实际用时，百分比为阶段估算。
• 🧩 多题录入：「手动输入」中一次粘贴多道题时，按题号自动分题（本地规则，不调用 AI），选项、小问和阅读材料留在所属题内，标题、姓名/日期栏等不计入题目；编号像同一道题的小问时默认按一道题处理，没有题号的多题可选「用 AI 分题」。拍照时选择「自动分题」，由支持图片输入的模型识别照片中的每道题及其在原图上的位置。分题结果先在预览页确认：可选择/取消、编辑、在光标处拆分、合并、调整顺序、删除、撤销，照片题可在原图上调整区域；确认后才逐题解析（照片按区域裁剪后与单题拍照走同一识别流程），按「导入前人工确认」直接入库或逐题校对。整批在「识别任务」中显示为「一批 N 题」，刷新、锁屏或关闭页面后都能找回；失败的题可单独重试，已完成的不会重复调用 AI 或重复入库。
• 📮 识别任务：拍照或框选的题目上传后由服务器识别，任务和结果保存在数据库中，不依赖原页面连接。上传完成即可离开页面、锁屏或继续使用应用；页头「识别任务」入口显示识别中数量和未读结果，回到前台立即刷新，可继续校对、查看错题或重试失败任务。开启「导入前人工确认」时结果保存为待校对草稿，关闭时服务器识别后直接入库（判重、年级和卷别规则与手动保存一致），重复提交或重复确认不会重复入库。服务重启后已完成的结果仍可打开，处理中被中断的任务显示为失败并可重试；待校对和失败的任务会一直保留到处理，已保存的任务保留 7 天。
• 🎓 录入年级规则：在「设置 → 通用」按账户选择固定年级或 AI 识别。固定模式使用指定年级学期，未指定时沿用账户当前年级；AI 模式根据题目内容判断，无法确定时保持未设置。图片、文字、框选批量与 Openclaw 录入统一生效，手工选择优先。直接录入未填年级时会补充一次 AI 识别并计入每日用量，重复题不重复识别；已有题目和备份恢复的年级不受影响。
• 🔁 重复题判定：导入时比较题干相似度，超过阈值（默认 90%，可在设置中调整）的题目不会重复导入，而是在原题下记一次做错。
• 🆔 题目 ID：每道题有 6 位 ID，可复制，也可在错题本中输入 ID 直接打开该题；打印的错题和试卷都标有「来源 ID」，方便做完后定位原题录入结果。

• ∑ LaTeX 公式：题目、答案和解析中的公式用 KaTeX 显示，支持 $…$、$$…$$、\(…\)、\[…\]；编辑时可在「源代码 / 预览」之间切换。检测到公式语法错误时，详情页出现「修复 LaTeX」按钮，由 AI 只修复公式写法。
• 📝 重新生成解答：详情页「重新生成完整解答」由 AI 重新生成答案和解析（覆盖前二次确认），知识点和错因保持不变。
• 🖼️ 题目配图：识别时由 AI 用 SVG 重绘题目配图，详情页、打印和试卷都使用 SVG 配图；有配图的错题可在详情页设置「配图显示比例」（10%～200%，默认 100%）与「配图显示位置」（居左/居中/居右，默认居中），含配图的试卷也支持按题逐个调整或全卷统一调整配图比例与显示位置，保存后同步用于显示和打印，并随备份恢复。拍照原图可在「查看原题图片」中核对，也可替换或补充上传。
• ⭐ 难度星级：导入时由 AI 参考《高思学校竞赛数学导引》的星级标准评定 1~5 星（一二星为课本及校内拔高，三四星为常规奥数，五星为竞赛压轴），可手动修改；4 星及以上默认归入 B 卷。
• 🏷️ 知识点标签：错题本创建时选择学段（小学/初中/高中）和学科（创建后不可修改），小学支持数学、英语和语文；内置语文章节与知识点覆盖小学一年级至六年级及初高中。本错题本内的题目由 AI 从该学段、该学科的全部知识点中选择标签；支持自定义标签，单题或整本错题本可让 AI 重新识别知识点和难度。管理员可在「设置 → 用户管理 → 人教版课标知识点」上传 cn-math-taxonomy 的 topics.json，导入「人教版课标体系」（以数学为主，也包含语文、英语、物理、历史、地理、道德与法治，约 2800 个知识点）；导入后创建错题本时可选择标签体系，与内置体系并存，创建后不可更改。

• 🎬 SVG 动画讲解：AI 按解题思路生成分步骤的 SVG 动画，打开页面或切换动画时停在首帧，点击播放后才开始；支持播放/暂停、拖动进度、重播和全屏；动画文字与界面语言一致，中英文版本分别保存，切换语言时自动显示对应版本。默认开启，可在「设置 → 通用」中关闭。
• 🔊 语音讲解：点击播放器上的喇叭开启，画面等语音读完再进入下一步，语速可调。语音可选浏览器本地语音或云端 TTS（见云端语音讲解）；旧动画没有讲解稿时朗读画面字幕，也可点击「补充讲解稿」由 AI 只补写讲解稿，画面保持不变。
• 📐 GeoGebra 动态演示：数学、物理题可由 AI 生成交互式 GeoGebra 图形。默认关闭，可在「设置 → 通用」中开启。
• 已生成的动画讲解和 GeoGebra 演示都可删除（需二次确认）。

• 🔄 举一反三：基于错题生成同知识点的变式题（填空或解答题），可选难度；提交答案后自动判题（不要求过程且结论一致时本地判对，证明或说明理由题交给 AI 核验论证，其余情况由 AI 对照标准答案判定并给出依据），保存前可修改结果；每道错题暂存最近一次生成的变式题与解答，再次进入时直接显示，需要新题再点「重新生成」。
• 📈 掌握概率：根据举一反三和试卷的作答历史，由 AI 评估每道题的已掌握概率。错题分为三种状态：没有举一反三记录的为「待复习」，有记录且掌握概率低于已掌握阈值的为「复习中」，达到阈值的为「已掌握」。阈值默认 50%，每个用户可在设置中单独调整。
• 📅 今日复习：按 1、2、4、7、15、30 天的艾宾浩斯间隔安排每道错题的复习，做对进入下一轮间隔，做错从头开始。导航栏的「复习」页列出今天到期的错题（最早到期的在前），首页显示今日���复习数量。
• 🧾 错题试卷：按错题本、知识点和掌握情况随机抽题，用举一反三生成一套可打印的试卷；做完后可按题录入结果，结果计入原题的作答历史。
• 🖨️ 错题打印：筛选后打印错题，可选打印题目文字或原图、答案、解析、知识点，调节图片比例以及全局/单题留白高度（单题留白自动保存），可直接打印或保存为 PDF。

• 🔍 多维度筛选：按掌握状态、时间范围、知识点、年级学期、试卷等级等条件筛选，支持批量操作和两题相似度比较。
• 📊 数据统计：错题与练习的掌握率、月度趋势和学科分布。
• ⏳ 后台任务：页面右下角的按钮可查看识别、AI 生成、动画语音生成、批量标注、组卷等耗时事务的进度；离开页面后事务仍在服务器上继续。拍照识别的结果另在「识别任务」中持久保存。
• 💾 数据导入导出：在「设置」中导出或导入数据备份，包含错题本、错题、系统及自定义标签、练习与作答记录、试卷、个人偏好和已合成的云端语音；标签按体系和父子路径还原，不同年级下的同名章节与知识点分别保留，题目恢复到具体标签节点。账户凭据和 AI 配置不在备份中。
• 🌗 深色模式：顶部导航栏的主题按钮可在「自动（跟随系统）」「浅色」「深色」之间切换，默认自动。偏好按用户保存在账号中，换设备登录也保持一致。
• 🕒 应用时区：默认北京时间，管理员可修改，日期显示与统计都按应用时区计算，详见 时区说明。
• 🔑 一次性初始化链接：全新安装不再预置固定密码的管理员。服务首次启动时生成只能使用一次的初始化链接，打开后自行设置管理员邮箱和密码：桌面版、安卓单机版自动打开；飞牛OS 直接在安装向导中填写管理员邮箱和密码；Docker、npm、源码运行打印在启动日志中（也可在数据目录的 config/setup-token 中找到令牌）。从旧版本升级的实例保留原有账号。
• 🧭 安装向导：管理员首次登录时进入向导：修改默认密码（仅旧版本的默认管理员需要）→ 配置 AI 渠道（推荐免费的 MiniMax Code）→ 创建第一个错题本，后两步可跳过；可在「设置 → 用户管理」中重新运行。已在使用的实例升级后不会自动弹出。
• 🔐 多用户与管理后台：支持注册、登录，数据按用户隔离；新用户注册默认关闭（关闭时登录页不显示注册入口，改为提示联系管理员），管理员可在「设置 → 用户管理」中开启，并可限制每人每天的 AI 使用次数、查看今日用量；管理员可在「设置 → 用户管理」进入管理后台，查看使用统计，启用/禁用或删除用户。登录和注册带失败次数限制，防止暴力破解密码。
• 🐞 调试日志：遇到问题时，管理员在「设置 → 用户管理」中打开调试模式，复现问题后导出调试日志（JSON）发给作者。调试模式下记录包括 debug 级别在内的全部服务端日志和前端错误，导出时自动去除 API Key、密码和令牌；日志只保存在内存中，24 小时后自动关闭，服务重启后清空。
• 🔌 Openclaw 集成：外部 Openclaw agent 可通过 POST /api/openclaw/batch-upload 批量上传题目图片，配置见环境变量。

按上手难度从易到难排列。全新安装没有默认账号：首次启动时会生成一次性初始化链接，打开后设置管理员邮箱和密码，再进入安装向导配置 AI 渠道、创建第一个错题本。桌面版、安卓单机版会自动打开该链接；Docker 用 docker logs wrong-notebook 2>&1 | grep initialize 查看；npm、源码运行打印在终端里。链接中的主机为 localhost 时，从其他设备访问需换成服务器地址（或设置 NEXTAUTH_URL）。尚未创建管理员时，登录页也会显示这些说明。

从下载页（自动识别系统与架构）或 Releases 下载对应安装包，安装后直接打开：

Windows 的 Code signing policy（代码签名政策）与隐私说明已公开。项目正在申请 SignPath Foundation；当前发布的 Windows 安装包仍未签名。维护者获批后的接入步骤见 Windows 签名配置。

macOS 提示「已损坏」或无法打开：安装包未经 Apple 签名。把应用拖入「应用程序」后，在终端执行以下命令移除隔离属性并在本机重新自签名，再打开即可：

xattr -cr /Applications/WrongNotebook.app
codesign --force --deep --sign - /Applications/WrongNotebook.app

也可以通过 npm 安装（Node.js 22 及以上）：

npm install -g wrong-notebook
wrong-notebook --port 3000

安卓单机版内置服务端，安装后直接使用，数据保存在本机（卸载 App 会删除数据；数据含 API Key，不参与系统备份，卸载或换机前请在设置中导出备份）；需要 Android 8.0 及以上的 64 位 ARM 设备。客户端版不内置服务端，首次打开时填写已部署的服务器地址（如 http://192.168.1.10:3000），可在「设置 → 关于」中更换服务器，需要 Android 7.0 及以上。两种 App 都支持拍照上传、导出文件和系统打印，可以同时安装。数据目录、默认账号、本地构建方法见 INSTALL_PACKAGES.md。

每次发版都会把镜像发布到 GitHub Container Registry：ghcr.io/margrop/wrong-notebook，支持 linux/amd64 和 linux/arm64，可直接拉取，不需要源码。

1. 准备目录和密钥：

   mkdir -p wrong-notebook/data wrong-notebook/config
   cd wrong-notebook
   openssl rand -base64 32   # 生成的字符串用作 NEXTAUTH_SECRET

2. 启动容器（任选一种）：

   docker run -d --name wrong-notebook \
     --restart always \
     -e NEXTAUTH_SECRET="上一步生成的密钥" \
     -e NEXTAUTH_URL="http://你的IP或域名:3000" \
     -p 3000:3000 \
     -v "$(pwd)/data:/app/data" \
     -v "$(pwd)/config:/app/config" \
     ghcr.io/margrop/wrong-notebook:latest

   或下载仓库中的 docker-compose.yml 放到当前目录，修改 NEXTAUTH_SECRET（及 NEXTAUTH_URL）后执行 docker compose up -d。

3. 登录：访问 http://你的IP或域名:3000。

4. 升级：拉取新镜像并重建容器，数据保留在挂载目录中，启动时执行数据库迁移并增量补齐内置语文标签，保留已有标签 ID 和题目关联。升级前建议先备份 data/ 目录。

   docker compose pull && docker compose up -d
   # 使用 docker run 时：docker pull 新镜像后 docker rm -f wrong-notebook，再执行上面的 docker run

数据保存在挂载的 data/（SQLite 数据库）和 config/（网页中保存的 AI 配置、云端语音缓存等）目录。设置页「关于」和 /api/health 显示当前运行的版本。HTTPS 部署见 HTTPS 配置指南 和 docker-compose.https.yml。

上游项目的镜像 ghcr.io/wttwins/wrong-notebook 不包含本仓库新增的功能，请使用 ghcr.io/margrop/wrong-notebook。

1. 环境准备：Node.js 22 及以上（推荐 24）和 npm。

2. 克隆并安装依赖：

   git clone https://github.com/margrop/wrong-notebook.git
   cd wrong-notebook
   npm ci
   cp .env.example .env   # 按「环境变量」一节填写

3. 初始化数据库：创建表结构和管理员账户，再导入系统知识点（与 Docker 构建时相同）：

   npx prisma migrate dev
   npx prisma db seed
   npx ts-node --compiler-options '{"module":"CommonJS"}' scripts/rebuild-system-tags.ts

4. 启动开发服务器：npm run dev，访问 http://localhost:3000。

需要修改代码或使用未发布的改动时，可以自行构建。构建过程中会在镜像内运行全部测试，并完成生产构建：

docker build -t wrong-notebook:local .

docker run -d --name wrong-notebook \
  -e NEXTAUTH_SECRET="your_secret_key" \
  -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  -v "$(pwd)/config:/app/config" \
  wrong-notebook:local

使用 docker-compose.yml 时，把其中的 image 改为 wrong-notebook:local 即可。

AI 配置在网页中修改，保存后立即生效，无需重启：

1. 管理员点击首页右上角的设置图标，打开「AI 设置」。
2. 选择提供商，填写 API Key、Base URL（或 Endpoint）、模型（或部署名称）。提供商下方附有官方接入文档，「API Key」「模型名称」旁附有获取说明和模型列表链接。
3. 点击「测试连接」检查文本与图片识别能力，失败时会显示服务商的原始报错；保存后配置写入 config/app-config.json，优先于 .env。
4. 同一页下方的「语音讲解」切换浏览器语音或云端语音；「提示词」页可自定义识别和举一反三的提示词模板。

AI 设置、提示词、连接测试和模型列表只对管理员开放；普通用户在「设置 → 通用」中只能修改自己的偏好。

计算题核对等价答案，证明和说明理由题检查必要论证；不要求过程且结论能直接比对时才本地判对，其他情况交给 AI 判定。

GeoGebra 的文字、不等式和标签参数按共用命令清单校验，重新生成时附带实际执行错误反馈。

应用统一保留输出协议、字段语言、年级范围及候选知识点约束，旧自定义模板遗漏变量时也会补齐。识别保留原题和学生作答原文，解析与错因分析跟随界面语言，学科、年级和知识点存储值不翻译；AI 返回的知识点会按候选清单过滤并去重，手工添加的标签不受影响。掌握度评估携带本次评估时间和练习间隔。

国产大模型官方渠道通过各家的 OpenAI 兼容接口调用，只需填写 API Key，Base URL 和模型留空时使用下表默认值；使用国际站时改填国际站地址。

兼容接口：OpenAI 提供商可接入任何 OpenAI API 格式的第三方服务（如硅基流动），Anthropic 提供商可接入兼容 Messages API 的服务；把 Base URL 改为服务商地址，模型填写对应平台的完整模型 ID。推理模型返回的思考内容会被自动忽略。

支持免费版 MiniMax 账号：用 MiniMax Code 账号网页登录，不需要 API Key，也不需要开通付费套餐。

• 每天自动签到：登录后应用每天自动签到，领取 MiniMax Code 的签到积分（连续签到奖励更多），不用手动打开客户端。
• ��耗免费积分：识题、解析、举一反三、判题等 AI 调用消耗的是账号的免费积分额度；剩余积分随时可在设置页查看。
• 默认模型 MiniMax-M3.1-Flash：已实测可用，支持图片识别；也可选 MiniMax-M3、MiniMax-M2.7 等。

使用方法：在“设置 → AI 设置”中选择 MiniMax Code OAuth，点击“网页登录”，在打开的 MiniMax 页面完成授权即可；设置页会显示登录状态、剩余积分和今天是否已自动签到。

登录凭据保存在服务端配置目录的 minimax-code.json（与 app-config.json 同目录，不随数据备份导出），Access Token 到期前自动续期。登录后服务每小时检查一次，当天（北京时间）还没签到时自动领取 MiniMax Code 的签到积分，也可以在设置页关闭自动签到或手动立即签到。该渠道使用 MiniMax Code 桌面客户端的登录方式（OAuth 设备码授权），不是官方开放接口，MiniMax 可能随时调整或限制；请遵守 MiniMax 的服务条款。

注册火山引擎即可获得每个模型的免费推理额度（官方文档为每个模型 50 万 tokens）。在火山方舟控制台的「开通管理」中开启「安心体验模式」后，调用只消耗免费额度，额度接近用完时自动暂停，不会产生费用。选择「火山引擎（免费试用）」渠道并填写方舟的 API Key 即可；额度用完后如需继续使用，完成实名认证并改用「火山引擎 豆包」或对应的套餐渠道。

动画的语音讲解默认使用浏览器本地语音（免费，但较生硬）。管理员可在「设置 → AI 设置 → 语音讲解」改用云端 TTS 语音（声音自然，与真人无异）：

• 默认音色为年轻男声，自然、清晰、略带科技感，不用播音腔；模型、音色和接口地址都可修改，各字段旁附有说明文档或音色列表链接，「保存并试听」会先保存再朗读一段示例。
• 服务端把合成结果统一到约 -15 LUFS 的响度，编码为 MP3 缓存，同一段讲解只合成一次；开启语音时一次合成整个动画的讲解并登记为后台任务，已生成语音的动画打开时默认开启语音讲解，已有动画可「重新生成语音」。
• 合成的语音随数据导出、导入备份；云端语音失败时自动改用浏览器语音。合成消耗语音服务商额度，不计入每人每日的 AI 次数。

各服务商的接口说明见 Wiki 的 AI 配置 · 云端语音讲解。

所选模型需要满足以下条件，否则部分功能无法使用或效果较差：

常用环境变量如下，完整列表见下方折叠表格和 .env.example。AI 相关配置也可以登录后在网页中填写，网页中保存的配置优先。

可将应用添加到手机或平板主屏幕，全屏运行、点击图标直接打开，平板可横屏使用。

• iPhone / iPad (Safari)：点击底部 分享 按钮 → 选择 "添加到主屏幕"。
• Android (Chrome)：点击右上角 菜单 → 选择 "添加到主屏幕" 或 "安装应用"；也可以安装安卓 App。

通过 HTTPS（或 localhost）访问时会启用 Service Worker：缓存页面脚本、样式和图标以加快打开速度，断网时显示离线提示页。题目、统计等数据始终从服务器读取，不做离线缓存。

屏幕截图依赖浏览器的安全上下文（HTTPS）。在 Docker 或局域网环境中使用时，请参考 HTTPS 配置指南 启用内置 HTTPS 支持。

• 框架：Next.js 16（App Router）+ React 19 + TypeScript
• 数据库：SQLite（via Prisma 5）
• 样式：Tailwind CSS v4 + Radix UI（shadcn/ui 风格组件）
• 公式：KaTeX（react-markdown + remark-math）
• AI：MiniMax / MiniMax Code（网页登录）/ 智谱 GLM / DeepSeek / Kimi / 千问 Qwen / 阶跃星辰 StepFun / 火山引擎豆包（含 Agent Plan、Coding Plan、免费试用）/ Anthropic（及兼容接口）/ Azure OpenAI / OpenAI（及兼容接口）/ Google Gemini
• 认证：NextAuth.js v4
• 测试：Vitest（单元、集成）、Playwright（E2E）

npm run lint                # ESLint（出现警告即失败）
npm run test:unit           # 单元测试
npm run test:integration    # 集成测试
npm test                    # 全部 Vitest 测试
npm run test:coverage       # 测试覆盖率（低于最低要求时失败）
npm run test:e2e            # 隔离应用、正式迁移测试库与本地模型服务，无需真实 API Key
bash scripts/ci.sh          # 完整 CI（Node.js 22+、Python 3，含生产构建）

GitHub 的 main 与 PR CI 还会使用正式 Dockerfile，在原生 amd64、arm64 环境中验证镜像内的测试和生产构建，检查通过后不推送镜像。.dockerignore 保留单元测试复用的 e2e/support 模块；浏览器用例和测试产物仍排除在构建上下文外。

E2E 启动器会在系统临时目录复制应用和依赖、执行正式迁移、生成测试账号并完成生产构建，随后使用本地固定模型响应运行浏览器用例。不会读取现有应用配置、复用开发服务器或访问外部模型。报告路径在命令结束时输出；可用 npm run test:e2e -- --grep E2E-M01 筛选用例。用例与运行边界见 E2E 设计与验收。

修改 prisma/schema.prisma 后使用 npx prisma migrate dev --name <名称> 生成正式迁移并提交；迁移须兼容已有数据。更多开发约定见 AGENTS.md。

scripts/ 目录下提供维护和调试脚本，例如：

• 重置密码：node scripts/reset-password.js <邮箱> <新密码>
• 恢复默认管理员角色：node scripts/seed-admin.js（只为已有的 admin@localhost 恢复管理员角色并启用；没有任何管理员时，重启服务会在日志中打印新的初始化链接）
• 重建系统知识点：npx ts-node --compiler-options '{"module":"CommonJS"}' scripts/rebuild-system-tags.ts（保留自定义标签和题目关联；生产环境操作前请先备份）
• 补齐语文知识点：npx ts-node --compiler-options '{"module":"CommonJS"}' scripts/seed-chinese-primary.ts（与主课程数据共用来源，只增量补齐内置语文体系及更新课程排序，保留标签 ID、题目关联、自定义标签和其他体系；可重复执行）。Docker 和安装包启动时自动执行编译后的 dist-scripts/scripts/seed-chinese-primary.js，旧安装无需重建全部标签。
• 导入人教版课标知识点：与「设置 → 用户管理 → 人教版课标知识点」相同的命令行方式。先下载 topics.json 到 scripts/data/cn-math-taxonomy-topics.json，再执行 npx tsx scripts/seed-cnm-tags.ts（也可把文件路径作为参数传入；作为独立的 cnm 标签体系增量导入，不影响内置体系和已有题目，可重复执行）。
• 检查数据库：node scripts/check-db-users.js、node scripts/check-db-data.js

使用、部署和常见问题见 Wiki（另有 English 版）。专项文档：

使用中遇到问题、想分享用法或提建议，欢迎加入 QQ 群 964325781，或用 QQ 扫描下方二维码。Bug 和功能需求仍建议提交到 Issues，方便跟踪处理；在群里发截图前请隐去孩子姓名、学校、账号和访问地址。

也可以在 X 上关注作者 @MargropMe，获取更新动态或私信交流。

欢迎提交 Issue 和 Pull Request，请先阅读贡献指南和行为准则。提问和反��方式见获取帮助，安全漏洞请按安全策略私下报告。各正式版的改动见更新日志。

MIT License

浏览器无法直接解码 HEIC/HEIF 照片时按需加载的转换组件 heic-to 1.6.6 及其包含的 libheif、libde265 采用 LGPL-3.0，Emscripten 运行时代码采用 MIT/NCSA 双许可。第三方说明、完整许可证文本与对应源码和构建说明链接见 public/third-party-licenses/heic-to/，该目录随 Docker 镜像和各安装包一起分发，登录后也可在应用中访问 /third-party-licenses/heic-to/NOTICE.txt。

© 2026 margrop。本项目基于 wttwins/wrong-notebook 扩展，原项目代码版权归原作者所有。