README проекта с github.com/margrop/wrong-notebook. Одним файлом markdown: README.md.
简体中文 | 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 评估掌握概率、艾宾浩斯间隔的今日复习、按错题组卷打印并回填结果。
🗂️ 共享真题库:新增「真题库」页,可从 margrop/wrong-notebook-question-bank 下载小学、初中、高中多学科题库包;导入默认只进入真题库、不产生错题,也可勾选同时写入错题本。举一反三可按知识点从真题库选题(不消耗 AI 额度),也可选「真题库变式」:先选出题库题目,再由 AI 以该题为原题生成变式题。
📦 多平台安装:Docker 镜像(amd64 / arm64)、npm、Windows、macOS、Linux、飞牛OS、群晖/威联通套件、安卓手机与平板(单机版或客户端),也可添加到手机主屏幕(PWA)。
本仓库 fork 自 wttwins/wrong-notebook,在其基础上增加了上述及下文列出的大部分功能。
以下截图采集自实际运行的应用(2026-10-20),展示已有题目、讲解和试卷。用户名已遮挡,可点击图片查看大图。
错题管理:在同一页面查看题目摘要、难度星级和知识点,按年级、学期、掌握情况及 A/B 卷筛选,也可通过题目 ID 定位、比较相似度或批量打印。列表按需加载卡片数据,原图、答案和解析在详情或打印预览时读取,减少翻页时的数据传输。错题列表支持用地址参数预设掌握状态(?mastery=new|reviewing|mastered)和知识点标签(?tag=标签名)筛选。

首页提供拍照上传、手动输入、导入题库文件和直接录入入口,支持拖拽图片与剪贴板粘贴。手机上有「拍照」「相册」「从文件选择」三个独立入口:拍照直接打开相机,相册中找不到的照片可从文件选择。
「导入题库文件」支持 JSON(题目交换格式 v1)、Word(.docx)、Excel(.xlsx)、CSV 与 PDF 题库文件,解析后展示摘要(题数、错误原因、警告、暂未导入字段),选择目标错题本后按批次进入导入中心,可「按原样入库」不调用 AI;一次最多导入 2000 题。导入页可下载 Excel / CSV 模板。TXT / Markdown 文件仍在「手动输入」中经「从文件导入」填入文字框。PDF 必须带文字层;扫描版 PDF 可选择页码范围(单次最多 20 页)转为图片,页面按输出上限放大(A4 约 225 DPI)后由 AI 识别分题导入,每页消耗一次 AI 分题额度;分不出题目的页面(如答案页、空白页)会自动跳过,不留下失败批次。带文字层的 PDF 默认给每道题按版面区域截图作为题目原图(可改为只截有图形的题或不保存),公式与图形不会因文字层乱码而丢失。
直接录入和人工校对保存失败时,页面会保留具体原因及处理建议,区分 AI 年级识别、字段长度或卷别校验、登录状态、数据库迁移与写入权限、网络或代理等问题。AI 年级识别失败时,可手动填写年级或改用固定年级后再保存;超时或断网后先确认错题本中是否已保存,避免重复提交。

通用设置可调整导入前人工确认(默认开启,先核对再保存)、录入题目的年级识别规则(固定年级或 AI 识别)、SVG 动画讲解、GeoGebra 动态演示、题目判重相似度阈值和已掌握阈值。卷别分组(A卷/B卷/其他)可在设置中自定义名称、新增分组(如单元测试、期中、期末)、停用或删除自定义分组。

一道错题集中展示题干、知识点、年级学期与试卷等级;点击「编辑年级/学期」可调整归属,校对页也可手工选择,可核对原题图片,并从详情页进入举一反三。

下图为已有六边形染色题的动画讲解,展示区域关系与递推计数过程;播放器支持暂停、拖动进度、重播和全屏。点击喇叭开启语音讲解:浏览器本地语音免费但较生硬,云端 TTS 语音自然、与真人无异(需付费,建议购买 Token Plan 等套餐)。

原题下汇总举一反三和试卷作答结果,展开记录可回看变式题与答案。AI 根据实际作答历史评估掌握概率,辅助安排后续复习。

生成的试卷保留来源题目 ID,并展示各次作答结果,方便回到原题跟踪复习效果。

打印预览可选择包含答案页,并设置每题下方的留白:按题型自动(填空、选择、判断题少留,解答题按小问数多留),或固定为不留白、小、中、大,也可在单题下方手动调节留白高度(调整后自动保存,下次打印直接沿用);逐行排列的选择题选项按长度自动横排为 4 列、2 列或 1 列,单独成行的作答横线上方留出书写空间;支持下载 HTML、打印或通过浏览器保存为 PDF。

标准标签库按教学层级组织知识点。知识点已并入「统计」栏目:「知识点」页签顶部可切换标签体系(导入其他标签体系后显示切换器),中部展示使用频率 Top 20(按标签体系和学科分别计数,不同体系或学科的同名知识点不合并),下方可浏览标准标签库、增删自定义标签(均按所选体系显示和添加)。

错题统计展示累计错题、待复习、复习中、已掌握数量及掌握率,附三段式复习状态进度条、科目分布和趋势图;支持按时间范围(近 7 天 / 近 30 天 / 近 6 个月 / 全部)和学科筛选。筛选某个学科后,点击待复习 / 复习中 / 已掌握卡片可直接跳转到该错题本中对应状态的错题列表(地址栏带 ?mastery= 参数,错题列表按此参数预设筛选)。趋势图按粒度显示每日或月度,包含「新增」与「新掌握」两个系列:新增是每桶内创建的错题数,新掌握是最近一次掌握评估时间落在该桶内的已掌握错题数(近似口径,以最近一次评估时间作为掌握时间;这类错题可能创建于范围之前,因此不受创建时间范围限制)。对比两个系列可以直观看出错题本是在变少还是越积越多。没有数据时显示引导去录入错题,加载失败时可重试。
错题统计页签在科目分布与趋势图下方还有「错因分布」卡片:上半部分按作答状态(不会做 / 做错了 / 未判断)展示环形图与占比,下半部分按错误类型展示横向条形列表(名称 + 数量 + 进度条),错误类型为自由文本,仅显示数量前 7 个,其余合并为「其他」;尚未填写错误类型时显示提示文案。统计同样受当前时间范围与学科筛选约束。
错题统计页签在错因分布右侧还有「难度分布」卡片:按难度星级(1~5 星)展示每个难度的总错题数与已掌握数,已掌握部分以不同颜色叠加显示;未评定的错题也会单独列出。没有任何已评星错题时该卡片不显示。
错题统计页签在概览与进度条下方还有「薄弱知识点」排行:按未掌握错题数、近期练习错误率排序,列出最需要巩固的知识点 Top 10。每行展示排名、知识点名称、所属学科、未掌握/总数、近期正确率(无记录时显示「近期未练习」)和未掌握占比进度条;点击一行可跳转到对应错题本并按该知识点筛选的错题列表(地址栏带 ?tag= 参数)。排行只统计当前时间范围内、当前学科筛选下的错题,近期正确率口径与练习统计一致(近 30 天 result 为 correct/wrong 的记录,排除重复导入产生的记录)。

练习统计单独展示累计练习、正确率(答对数 / 已作答数)和活跃天数,并按学科、难度观察练习分布与趋势;同样支持时间范围和学科筛选;没有数据时显示引导去复习,加载失败时可重试。练习统计页签顶部还有「学习日历」热力图,以 GitHub 风格方格展示最近 26 周每天的学习活动(录入错题 + 练习次数),顶部和左侧分别标注月份与星期,并显示当前连续天数、最长连续天数和累计活跃天数;录入错题也算活动,所以没有练习记录时热力图也能显示。练习统计页签最下方还有「反复错题目」榜:列出所选范围内做错 2 次以上的题目 Top 10(含举一反三、试卷、手动录入与重复导入的做错记录),每行显示题干预览、学科、出错次数、最近出错日期和复习状态,点击可跳到对应错题详情,提示重点复习;没有数据时显示一句简短提示。

$…$、$$…$$、\(…\)、\[…\];编辑时可在「源代码 / 预览」之间切换。检测到公式语法错误时,详情页出现「修复 LaTeX」按钮,由 AI 只修复公式写法。?mastery=new|reviewing|mastered)和知识点标签(?tag=标签名)筛选。.json),导入自动解压并兼容旧版纯 JSON;单个备份解压后最大 256MB(常见几十 MB)。config/setup-token 中找到令牌)。从旧版本升级的实例保留原有账号。TELEMETRY_DISABLED=true 强制全部关闭。协议升级后管理员需重新同意,期间暂停外发,普通用户不受影响。详见隐私说明与设计。POST /api/openclaw/batch-upload 批量上传题目图片,配置见环境变量。POST /api/mcp 读写错题本、错题、知识点与复习数据;配置 MCP_API_KEY 与 MCP_USER_EMAIL 后启用,工具与接入方式见 MCP 服务。按上手难度从易到难排列。全新安装没有默认账号:首次启动时会生成一次性初始化链接,打开后设置管理员邮箱和密码,再进入安装向导配置 AI 渠道、创建第一个错题本。桌面版、安卓单机版会自动打开该链接;Docker 用 docker logs wrong-notebook 2>&1 | grep initialize 查看;npm、源码运行打印在终端里。链接中的主机为 localhost 时,从其他设备访问需换成服务器地址(或设置 NEXTAUTH_URL)。尚未创建管理员时,登录页也会显示这些说明。
从下载页(自动识别系统与架构)或 Releases 下载对应安装包,安装后直接打开:
| 平台 | 安装包 |
|---|---|
| Windows | WrongNotebook-Win-Setup-<版本>-x64.exe(安装版)、WrongNotebook-Win-Portable-<版本>-x64.exe(免安装) |
| macOS | WrongNotebook-Mac-<版本>-arm64.dmg(Apple 芯片)、WrongNotebook-Mac-<版本>-x64.dmg(Intel) |
| Linux | WrongNotebook-Linux-<版本>-<架构>.AppImage、.deb |
| 飞牛OS | WrongNotebook-FnOS-<版本>-x86.fpk、WrongNotebook-FnOS-<版本>-arm.fpk |
| 群晖 DSM | WrongNotebook-Synology-<版本>-x86_64.spk / -arm64.spk(套件中心手动安装,内置镜像的 Docker 套件,需 Container Manager) |
| 威联通 QTS | WrongNotebook-QNAP-<版本>-x86_64.qpkg / -arm64.qpkg(App Center 手动安装,内置镜像的 Docker 套件,需 Container Station) |
| 安卓手机 / 平板(单机版) | WrongNotebook-Android-Phone-<版本>.apk(竖屏)、WrongNotebook-Android-Tablet-<版本>.apk(横竖屏自动旋转) |
| 安卓手机 / 平板(客户端) | WrongNotebook-Android-Client-Phone-<版本>.apk、WrongNotebook-Android-Client-Tablet-<版本>.apk |
Windows 的 Code signing policy(代码签名政策)与隐私说明已公开。项目已通过 SignPath Foundation 审核,正在用测试证书接入,取得生产证书前发布的 Windows 安装包仍未签名。维护者接入步骤见 Windows 签名配置。
macOS 首次打开被拦截:安装包只有本地自签名(ad-hoc),未经 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 设备。两个版本都由系统的 Android System WebView 显示界面,需要 WebView 111 及以上,版本过旧时页面顶部会提示升级(没有 Google Play 的手机可在手机自带的应用商店升级)。客户端版不内置服务端,首次打开时填写已部署的服务器地址(如 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,可直接拉取,不需要源码。
| 镜像标签 | 说明 |
|---|---|
2026.10.20 等精确版本 |
推荐,升级时可控 |
2026.10 |
当月最新版本 |
latest |
最新正式版本 |
准备目录和密钥:
mkdir -p wrong-notebook/data wrong-notebook/config
cd wrong-notebook
openssl rand -base64 32 # 生成的字符串用作 NEXTAUTH_SECRET
启动容器(任选一种):
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。
未设置 NEXTAUTH_SECRET 时,容器首次启动会生成密钥并保存到数据目录的 .nextauth_secret,之后保持不变。
登录:访问 http://你的IP或域名:3000。
升级:拉取新镜像并重建容器,数据保留在挂载目录中,启动时执行数据库迁移并增量补齐内置语文标签,保留已有标签 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。
在 Unraid 的 Docker 页新建容器即可,不需要 Compose 文件:
| 字段 | 值 |
|---|---|
| Repository | ghcr.io/margrop/wrong-notebook:<精确版本>(如 2026.11.6,也可用 latest) |
| Network / Port | bridge;容器端口 3000,主机端口自定(如 3000) |
| Path 1 (host → container) | /mnt/user/appdata/wrong-notebook/data → /app/data(数据库) |
| Path 2 (host → container) | /mnt/user/appdata/wrong-notebook/config → /app/config(AI 配置、提示词等) |
| Variable 1 | NEXTAUTH_SECRET:openssl rand -base64 32 的输出 |
| Variable 2 | NEXTAUTH_URL=http://你的IP或域名:3000 |
| Variable 3 | PRESERVE_EXISTING_DATA=true |
| Restart policy | unless-stopped |
主机目录不存在时 Unraid 会自动创建。首次启动后,在容器日志中查找 initialize 链接(也可读取 /mnt/user/appdata/wrong-notebook/config/setup-token),打开设置管理员邮箱和密码。
升级:Docker 页 → 点击容器 → Force update,会按当前 Repository 标签重新拉取并重建容器。使用精确版本时,先把 Repository 标签改成新版本再 Force update;latest 直接 Force update 即可。启动时会自动执行数据库迁移,data、config 目录中的数据保留。升级前先按 数据备份与恢复 停止容器并归档整个 appdata 目录,或使用 Unraid 的 Appdata Backup 插件。
回退:数据库迁移后不一定兼容旧镜像。回退时先停止容器,恢复升级前的 data/、config/,再把 Repository 标签改回旧版本并启动。
DSM 7.2 及以上使用 Container Manager(旧版为 Docker 套件)。建议数据目录为 /volume1/docker/wrong-notebook/{data,config};先在 File Station 或 SSH 中创建,其他存储卷路径相应替换。
套件安装(推荐):先安装 Container Manager,然后在套件中心 →「手动安装」选择 WrongNotebook-Synology-<版本>-x86_64.spk(Intel / AMD 机型)或 -arm64.spk(64 位 ARM 机型)。需要 DSM 7.2.1 及以上。套件在 Container Manager 中创建项目 wrong-notebook,加载套件内置的同版本镜像(安装时无需联网拉取),把主机端口 39300 映射到容器 3000,数据放在套件数据目录 /volumeN/@appdata/wrongnotebook;从 DSM 主菜单的「错题本」图标或 http://NAS地址:39300 进入应用,首次启动按页面提示设置管理员。升级套件会按新镜像重建容器并保留数据,卸载套件保留数据目录。
手动容器方式:
margrop/wrong-notebook,或从 URL 添加 ghcr.io/margrop/wrong-notebook:<精确版本>。wrong-notebook;端口本地 3000 → 容器 3000;卷映射 /volume1/docker/wrong-notebook/data → /app/data、.../config → /app/config(读写);环境变量 NEXTAUTH_SECRET、NEXTAUTH_URL、PRESERVE_EXISTING_DATA=true;开启自动重启。initialize 链接(令牌也在 /volume1/docker/wrong-notebook/config/setup-token),设置管理员邮箱和密码。latest 时拉取最新映像后重建即可。data/、config/,再按旧版本映像重建。使用 Container Station。建议数据目录为 /share/Container/wrong-notebook/{data,config};Container Station 的默认共享文件夹是 Container,自定义存储位置时相应替换。
套件安装(推荐):先安装 Container Station,然后在 App Center →「手动安装」选择 WrongNotebook-QNAP-<版本>-x86_64.qpkg(Intel / AMD 机型)或 -arm64.qpkg(64 位 ARM 机型)。套件加载内置的同版本镜像(无需联网拉取)、生成 NEXTAUTH_SECRET、把主机端口 39300 映射到容器 3000,数据放在 /share/Container/wrong-notebook/{data,config};App Center 的打开链接进入应用,首次启动按页面提示设置管理员。升级套件会按新镜像重建容器并保留数据,卸载套件保留数据目录。
手动容器方式:
ghcr.io/margrop/wrong-notebook:<精确版本>;也可通过 SSH 执行 docker pull,或使用 应用程序(Compose)方式。wrong-notebook;端口主机 3000 → 容器 3000;卷映射 /share/Container/wrong-notebook/data → /app/data、.../config → /app/config;环境变量 NEXTAUTH_SECRET、NEXTAUTH_URL、PRESERVE_EXISTING_DATA=true;重启策略 unless-stopped。initialize 链接(令牌在 /share/Container/wrong-notebook/config/setup-token)。data/、config/,再按旧版本映像重建。上游项目的镜像
ghcr.io/wttwins/wrong-notebook不包含本仓库新增的功能,请使用ghcr.io/margrop/wrong-notebook。
环境准备:Node.js 22 及以上(推荐 24)和 npm。
克隆并安装依赖:
git clone https://github.com/margrop/wrong-notebook.git
cd wrong-notebook
npm ci
cp .env.example .env # 按「环境变量」一节填写
初始化数据库:创建表结构和管理员账户,再导入系统知识点(与 Docker 构建时相同):
npx prisma migrate dev
npx prisma db seed
npx ts-node --compiler-options '{"module":"CommonJS"}' scripts/rebuild-system-tags.ts
启动开发服务器: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 配置在网页中修改,保存后立即生效,无需重启:
config/app-config.json,优先于 .env。提示词值得定制。 默认提示词面向通用场景;家长按孩子的年级、薄弱点和学习习惯改写角色、语气和分析步骤,效果通常明显更好。在「提示词」页点「复制」取走默认模板,改好后点「用剪贴板替换」覆盖并保存;「恢复默认」可随时退回。请保留模板中的 {{变量}},它们会被替换为每道题的数据,页面会提示遗漏的变量。应用仍会补充输出协议、语言、年级、知识点和生成题型规则,旧模板遗漏变量时也不例外。
渠道分工能省钱。 拍照识别需要能看图的模型,解题、判分、举一反三等纯文字任务用便宜的文字模型即可。在「渠道分工」中分别选择「图片识别渠道」和「文本分析渠道」,两者可各自填自己的 API Key;再选一个「备用渠道」,例如让付费渠道给免费 MiniMax Code 积分兜底——积分用完后自动接手,不用手动切换。用量按实际使用的渠道分别记录。
提示词、渠道分工都属于实例级设置。 AI 设置、提示词、连接测试和模型列表只对管理员开放;普通用户在「设置 → 通用」中只能修改自己的偏好。
计算题核对等价答案,证明和说明理由题检查必要论证;不要求过程且结论能直接比对时才本地判对,其他情况交给 AI 判定。
GeoGebra 的文字、不等式和标签参数按共用命令清单校验,重新生成时附带实际执行错误反馈。
应用统一保留输出协议、字段语言、年级范围及候选知识点约束,旧自定义模板遗漏变量时也会补齐。识别保留原题和学生作答原文,解析与错因分析跟随界面语言,学科、年级和知识点存储值不翻译;AI 返回的知识点会按候选清单过滤并去重,手工添加的标签不受影响。掌握度评估携带本次评估时间和练习间隔。
国产大模型官方渠道通过各家的 OpenAI 兼容接口调用,只需填写 API Key,Base URL 和模型留空时使用下表默认值;使用国际站时改填国际站地址。
| 提供商 | 推荐方式 | 默认 Base URL | 默认模型 |
|---|---|---|---|
| MiniMax | MiniMax 开放平台 | https://api.minimax.cn/v1(国际站 https://api.minimax.io/v1) |
MiniMax-M3.1-Flash |
| MiniMax Code OAuth | 免费账号,网页登录,见下文 | 固定接口 | MiniMax-M3.1-Flash |
| 智谱 GLM | 智谱开放平台 | https://open.bigmodel.cn/api/paas/v4(国际站 https://api.z.ai/api/paas/v4) |
glm-5.3-flash |
| DeepSeek | DeepSeek 开放平台 | https://api.deepseek.com |
deepseek-v4-flash |
| Kimi | Kimi 开放平台 | https://api.moonshot.cn/v1(国际站 https://api.moonshot.ai/v1) |
kimi-k3.1-pro |
| 千问 Qwen | 阿里云百炼,推荐 Token Plan | https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1(按量付费 https://dashscope.aliyuncs.com/compatible-mode/v1) |
qwen3.8-max |
| 阶跃星辰 StepFun | 阶跃星辰开放平台,推荐 Step Plan | https://api.stepfun.com/step_plan/v1(按量付费 https://api.stepfun.com/v1,国际站 https://api.stepfun.ai/v1) |
step-5-preview |
| 火山引擎 豆包 | 火山方舟,按量付费 | https://ark.cn-beijing.volces.com/api/v3(国际站 https://ark.ap-southeast.bytepluses.com/api/v3) |
doubao-seed-evolving |
| 火山引擎 Agent Plan | Agent Plan 专属 Key,套餐含豆包语音合成 | https://ark.cn-beijing.volces.com/api/plan/v3 |
doubao-seed-evolving |
| 火山引擎 Coding Plan | Coding Plan,方舟 API Key | https://ark.cn-beijing.volces.com/api/coding/v3(不要改成 /api/v3,否则不计入套餐) |
doubao-seed-evolving |
| 火山引擎(免费试用) | 新用户免费推理额度,见下文 | https://ark.cn-beijing.volces.com/api/v3 |
doubao-seed-evolving |
| Anthropic 及兼容接口 | Claude Console | https://api.anthropic.com(不含 /v1) |
claude-sonnet-5-5 |
| Azure OpenAI | Azure 门户 → OpenAI 资源 → 密钥和终结点 | 填写资源 Endpoint 和部署名称 | 部署名称 |
| OpenAI 及兼容接口 | OpenAI Platform,可添加多个配置并切换 | https://api.openai.com/v1 |
gpt-6.1-sol |
| Google Gemini | Google AI Studio | 官方地址 | gemini-2.5-flash(推荐 gemini-3.8-flash) |
兼容接口:OpenAI 提供商可接入任何 OpenAI API 格式的第三方服务(如硅基流动),Anthropic 提供商可接入兼容 Messages API 的服务;把 Base URL 改为服务商地址,模型填写对应平台的完整模型 ID。推理模型返回的思考内容会被自动忽略。
支持免费版 MiniMax 账号:用 MiniMax Code 账号网页登录,不需要 API Key,也不需要开通付费套餐。
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 语音(声音自然,与真人无异):
| 云端语音 | API Key | 默认模型 / 音色 |
|---|---|---|
| MiniMax(建议 M Plan) | 与 MiniMax 渠道共用 | speech-2.8-hd / male-qn-jingying |
| 千问(建议 Token Plan) | 与千问渠道共用 | qwen-audio-3.0-tts-plus / longanlufeng |
| 智谱 GLM-TTS(建议 GLM Coding Plan) | 与智谱 GLM 渠道共用 | glm-tts / xiaochen |
| 阶跃星辰(建议 Step Plan) | 与阶跃星辰渠道共用 | stepaudio-2.5-tts / qingniandaxuesheng |
| 火山引擎豆包语音(可免费试用,建议资源包) | 单独的豆包语音 API Key | seed-tts-2.0 / zh_male_yangguangqingnian_uranus_bigtts |
| 火山引擎 Agent Plan(计入套餐额度) | 与 Agent Plan 渠道共用 | seed-tts-2.0 / zh_male_yangguangqingnian_uranus_bigtts |
| OpenAI | 可单独填写,留空时用当前 OpenAI 配置 | gpt-4o-mini-tts / cedar |
各服务商的接口说明见 Wiki 的 AI 配置 · 云端语音讲解。
所选模型需要满足以下条件,否则部分功能无法使用或效果较差:
| 要求 | 用到的功能 | 说明 |
|---|---|---|
| 支持图片输入(多模态) | 拍照/截图识别题目、照片自动分题、AI 重新生成配图、有原图时的重新生成解答 | 纯文本模型只能使用文字录入,识别图片会失败 |
| 能写准确的 SVG 代码 | 题目配图、举一反三和试卷新题的配图、SVG 动画讲解 | 这些「图片」都由模型输出 SVG 代码生成,不调用图片生成模型;模型的几何作图和 SVG 动画(SMIL)能力决定配图与动画的质量 |
| 较长的单次输出 | SVG 动画讲解、识别题目(含配图)、多题分题等 | 每次调用都直接按模型允许的最大输出请求(已知模型用官方上限,未知模型用 262144(256K),接口报超限时自动读出模型上限再试并记住),推理模型的思考过程也计入输出;模型的最大输出不足 16K 时,动画讲解容易生成失败。按 max_tokens 预扣额度的中转网关(如 NewAPI)需要账户余额足以覆盖预扣 |
| 严格遵循输出格式 | 所有 AI 功能 | 结果按 <answer_text>、<svg_animation> 等标签或 JSON 解析,格式不符会提示「AI 返回格式异常,可能模型不兼容」 |
| 规范的 LaTeX | 题目、答案、解析 | 公式须能被 KaTeX 显示;出现语法错误时可用详情页的「修复 LaTeX」修正 |
| 较强的数学推理 | 解答、错因分析、难度星级、掌握概率评估 | 推理(思考)模型可以使用,思考内容会被自动忽略;思考耗时较长时,管理员可在「设置 → 通用」中调大「AI 分析超时时间」 |
常用环境变量如下,完整列表见下方折叠表格和 .env.example。AI 相关配置也可以登录后在网页中填写,网页中保存的配置优先。
| 环境变量 | 说明 |
|---|---|
NEXTAUTH_SECRET |
Session 加密密钥,生产环境必须设置,可用 openssl rand -base64 32 生成 |
NEXTAUTH_URL |
部署后的访问地址,如 http://your-domain:3000 |
DATABASE_URL |
SQLite 数据库路径;源码默认 file:./dev.db,Docker 默认 file:/app/data/dev.db |
AI_PROVIDER |
AI 提供商,默认 minimax,取值见完整列表 |
<提供商>_API_KEY |
对应提供商的 API Key,如 MINIMAX_API_KEY、QWEN_API_KEY、OPENAI_API_KEY |
TTS_MODE |
动画语音讲解的朗读方式,默认 browser(浏览器本地语音) |
ALLOW_REGISTRATION |
是否开放注册,默认 false |
AI_DAILY_LIMIT |
普通用户每天的 AI 次数,默认 0(不限制) |
AI_CONCURRENCY_LIMIT |
同一模型同时进行的 AI 调用上限,默认 5,超出的排队 |
FIGURE_REVIEW |
AI 配图比对校正开关,默认 false;重绘后多一次 AI 调用 |
基础配置
| 环境变量 | 描述 | 默认值 | 说明 |
|---|---|---|---|
DATABASE_URL |
数据库连接地址 | 源码 file:./dev.db;Docker file:/app/data/dev.db |
SQLite 数据库路径 |
NEXTAUTH_SECRET |
Auth 密钥 | 无 | 用于加密 Session,生产环境必须设置,可用 openssl rand -base64 32 生成 |
NEXTAUTH_URL |
访问地址 | 无 | 部署后的访问地址,如 http://your-domain:3000 |
AUTH_TRUST_HOST |
信任主机头 | Docker 镜像中为 true |
为 true 时根据请求自动推断访问地址,适合 Docker/反向代理 |
LOG_LEVEL |
日志级别 | 开发 debug / 生产 info |
可选 trace、debug、info、warn、error、fatal,详见 日志指南 |
DEBUG_DB |
SQL 日志 | false |
为 true 时输出数据库查询日志 |
HTTP_PROXY / HTTPS_PROXY |
代理 | 无 | 访问 AI 服务时使用的代理 |
TELEMETRY_DISABLED |
关闭匿名遥测 | false |
为 true 时强制关闭本地记录、错误回报与外发,设置界面只读,适合演示站和内网合规场景 |
ALLOW_REGISTRATION |
允许注册 | false |
为 true 时默认开放注册;管理员在「设置 → 用户管理」中保存的开关优先 |
AI_DAILY_LIMIT |
每人每日 AI 次数 | 0(不限制) |
普通用户每天可发起的 AI 操作次数,管理员不受限制;「设置 → 用户管理」中保存的值优先 |
AI_CONCURRENCY_LIMIT |
同一模型 AI 并发上限 | 5 |
同一渠道、地址和模型同时进行的 AI 调用数量(1~100),超出的调用排队等待,避免服务商返回 429;「设置 → 用户管理」中保存的值优先 |
FIGURE_REVIEW |
AI 配图比对校正 | false |
为 true 时重绘配图后把原图与结果并排交给 AI 比对并修正差异;每张配图多一次带图片的 AI 调用,耗时更长。管理员在「设置 → 通用」中保存的开关优先 |
TTS_MODE |
动画语音讲解的朗读方式 | browser |
browser 为浏览器本地语音;minimax、qwen、glm、stepfun、volcengine、volcengine-agent、openai 为云端语音,复用对应渠道的 API Key(豆包语音使用 VOLCENGINE_TTS_API_KEY,OpenAI 使用当前激活的 OpenAI 配置)。「设置 → AI 设置 → 语音讲解」中保存的值优先 |
AI 配置(网页中保存的配置优先于环境变量)
| 环境变量 | 描述 | 默认值 | 说明 |
|---|---|---|---|
AI_PROVIDER |
AI 提供商 | minimax |
可选 minimax、minimax-code、glm、deepseek、kimi、qwen、stepfun、volcengine、volcengine-agent、volcengine-coding、volcengine-free、anthropic、azure、openai、gemini |
MINIMAX_API_KEY / MINIMAX_BASE_URL / MINIMAX_MODEL |
MiniMax | 地址 https://api.minimax.cn/v1,模型 MiniMax-M3.1-Flash |
地址和模型可留空 |
MINIMAX_CODE_MODEL |
MiniMax Code 模型 | MiniMax-M3.1-Flash |
账号在网页设置中登录,无需 API Key |
MINIMAX_CODE_AUTO_CHECKIN |
MiniMax Code 每日自动签到 | true |
设为 false 关闭 |
GLM_API_KEY / GLM_BASE_URL / GLM_MODEL |
智谱 GLM | 地址 https://open.bigmodel.cn/api/paas/v4,模型 glm-5.3-flash |
地址和模型可留空 |
DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL / DEEPSEEK_MODEL |
DeepSeek | 地址 https://api.deepseek.com,模型 deepseek-v4-flash |
地址和模型可留空 |
KIMI_API_KEY / KIMI_BASE_URL / KIMI_MODEL |
Kimi | 地址 https://api.moonshot.cn/v1,模型 kimi-k3.1-pro |
地址和模型可留空 |
QWEN_API_KEY / QWEN_BASE_URL / QWEN_MODEL |
千问 Qwen | 地址 https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1(百炼 Token Plan),模型 qwen3.8-max |
按量付费的 Key 改填 https://dashscope.aliyuncs.com/compatible-mode/v1 |
STEPFUN_API_KEY / STEPFUN_BASE_URL / STEPFUN_MODEL |
阶跃星辰 StepFun | 地址 https://api.stepfun.com/step_plan/v1(Step Plan 套餐),模型 step-5-preview |
按量付费改填 https://api.stepfun.com/v1,国际站 https://api.stepfun.ai/v1 |
VOLCENGINE_API_KEY / VOLCENGINE_BASE_URL / VOLCENGINE_MODEL |
火山引擎 豆包 | 地址 https://ark.cn-beijing.volces.com/api/v3,模型 doubao-seed-evolving |
按量付费;订阅 Agent Plan 等套餐时选择对应的套餐渠道;国际站 https://ark.ap-southeast.bytepluses.com/api/v3 |
VOLCENGINE_AGENT_API_KEY / VOLCENGINE_AGENT_BASE_URL / VOLCENGINE_AGENT_MODEL |
火山引擎 Agent Plan | 地址 https://ark.cn-beijing.volces.com/api/plan/v3,模型 doubao-seed-evolving |
Agent Plan 管理页的专属 API Key;套餐含豆包语音合成 |
VOLCENGINE_CODING_API_KEY / VOLCENGINE_CODING_BASE_URL / VOLCENGINE_CODING_MODEL |
火山引擎 Coding Plan | 地址 https://ark.cn-beijing.volces.com/api/coding/v3,模型 doubao-seed-evolving |
方舟 API Key;不要改成 /api/v3(不计入套餐);套餐不含语音合成 |
VOLCENGINE_FREE_API_KEY / VOLCENGINE_FREE_BASE_URL / VOLCENGINE_FREE_MODEL |
火山引擎(免费试用) | 地址 https://ark.cn-beijing.volces.com/api/v3,模型 doubao-seed-evolving |
新用户免费推理额度,开启「安心体验模式」后用完自动暂停 |
VOLCENGINE_TTS_API_KEY |
豆包语音 API Key | 无 | 云端语音选择火山引擎豆包语音时使用,与火山方舟的 Key 不同 |
ANTHROPIC_API_KEY |
Anthropic API Key | 无 | 从 Claude Console 获取 |
ANTHROPIC_BASE_URL |
API 地址 | https://api.anthropic.com |
兼容服务填写不含 /v1 的地址 |
ANTHROPIC_MODEL |
模型 | claude-sonnet-5-5 |
如 claude-opus-5-5、claude-haiku-5-5 |
AZURE_OPENAI_API_KEY |
Azure API Key | 无 | 从 Azure 门户获取 |
AZURE_OPENAI_ENDPOINT |
Azure Endpoint | 无 | 如 https://xxx.openai.azure.com |
AZURE_OPENAI_DEPLOYMENT |
部署名称 | 无 | Azure 中配置的部署名称 |
AZURE_OPENAI_API_VERSION |
API 版本 | 2024-02-15-preview |
|
AZURE_OPENAI_MODEL |
模型名称 | gpt-4o |
仅用于显示 |
OPENAI_API_KEY |
OpenAI API Key | 无 | 从 OpenAI Platform 获取 |
OPENAI_BASE_URL |
OpenAI API 地址 | https://api.openai.com/v1 |
使用兼容服务时填写其地址 |
OPENAI_MODEL |
OpenAI 模型 | gpt-6.1-sol |
兼容服务填写对应平台的模型 ID |
GOOGLE_API_KEY |
Gemini API Key | 无 | 从 Google AI Studio 获取 |
GEMINI_BASE_URL |
Gemini API 地址 | 官方地址 | 通常无需修改 |
GEMINI_MODEL |
Gemini 模型 | gemini-2.5-flash |
推荐 gemini-3.8-flash |
Openclaw 集成(可选)
| 环境变量 | 描述 | 默认值 | 说明 |
|---|---|---|---|
OPENCLAW_API_URL |
Openclaw agent 地址 | 无 | 本地部署的 Openclaw agent 服务地址 |
OPENCLAW_API_KEY |
Openclaw API 密钥 | 无 | 调用 Openclaw agent 时使用 |
OPENCLAW_TIMEOUT |
超时(毫秒) | 30000 |
|
OPENCLAW_AUTH_MODE |
认证方式 | credentials |
credentials(用户名密码)或 apikey |
OPENCLAW_INTEGRATION_API_KEY |
本系统 API 密钥 | 无 | 仅 apikey 模式需要,供 Openclaw 调用本系统,可用 openssl rand -hex 32 生成 |
MCP 服务(可选)
| 环境变量 | 描述 | 默认值 | 说明 |
|---|---|---|---|
MCP_API_KEY |
MCP 集成密钥 | 无 | 外部 agent 通过 Authorization: Bearer 或 x-api-key 提交;可用 openssl rand -hex 32 生成 |
MCP_USER_EMAIL |
MCP 目标账号 | 无 | 固定该账号的错题数据;填邮箱(也可填用户名),账号须启用 |
新增环境变量时需同步更新 .env.example。
可将应用添加到手机或平板主屏幕,全屏运行、点击图标直接打开,平板可横屏使用。
通过 HTTPS(或 localhost)访问时会启用 Service Worker:缓存页面脚本、样式和图标以加快打开速度,断网时显示离线提示页。题目、统计等数据始终从服务器读取,不做离线缓存。
屏幕截图依赖浏览器的安全上下文(HTTPS)。在 Docker 或局域网环境中使用时,请参考 HTTPS 配置指南 启用内置 HTTPS 支持。
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(保留自定义标签和题目关联;生产环境操作前请先备份)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 版)。专项文档:
| 文档 | 内容 |
|---|---|
| INSTALL_PACKAGES.md | npm、桌面版、飞牛OS、群晖/威联通套件、安卓安装包与构建 |
| HTTPS_SETUP.md | HTTPS 配置(屏幕截图需要) |
| TIME_ZONE.md | 应用时区 |
| LOGGING_GUIDE.md | 日志 |
| MARKDOWN_GUIDE.md | Markdown 与公式 |
| TABLE_RECOGNITION.md | 表格识别 |
| PROJECT_OVERVIEW.md、operational_flow.md | 项目结构与操作流程(部分内容早于本仓库新增功能) |
| release-guide.md | 版本发布 |
| BRANCH_WORKFLOW.md | 公开主线与上传前检查 |
| setup-wsl-network.md | WSL 网络配置 |
使用中遇到问题、想分享用法或提建议,欢迎加入 QQ 群 964325781,或用 QQ 扫描下方二维码。Bug 和功能需求仍建议提交到 Issues,方便跟踪处理;在群里发截图前请隐去孩子姓名、学校、账号和访问地址。
也可以在 X 上关注作者 @MargropMe,获取更新动态或私信交流。
欢迎提交 Issue 和 Pull Request,请先阅读贡献指南和行为准则。提问和反馈方式见获取帮助,安全漏洞请按安全策略私下报告。各正式版的改动见更新日志。
浏览器无法直接解码 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 扩展,原项目代码版权归原作者所有。