wrong-notebook README

项目的 README,来自 github.com/margrop/wrong-notebook。合并为一个 markdown 文件:README.md。

智能错题本应用图标

Smart Wrong Notebook (智能错题本)

简体中文 | English

GitHub downloads npm downloads GitHub stars GitHub forks

桌面版 Android Docker npm 飞牛OS 群晖 威联通 Web

License: MIT Release CI CodeQL npm

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

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

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

🌟 亮点

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

⭐ Star 增长趋势

margrop/wrong-notebook 的 GitHub Star 增长趋势图

🖼️ 功能预览

以下截图采集自实际运行的应用(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卷/其他)可在设置中自定义名称、新增分组(如单元测试、期中、期末)、停用或删除自定义分组。

通用设置中的导入确认、动画讲解、GeoGebra 和判重阈值

题目详情:公式排版、难度星级、知识点和试题信息

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

真实错题详情中的公式、难度星级、知识点和年级学期信息

SVG 动画讲解:把解题思路变成分步骤的动态演示,并配语音讲解

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

六边形染色题的 SVG 动画讲解、递推计数表与播放控制

复习反馈:回看变式题、作答历史和 AI 掌握概率

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

已有试卷变式题、先错后对的作答历史与 AI 掌握概率评估

组卷与打印:针对错题生成试卷,做完后按题回填结果

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

已生成的真实错题试卷、来源 ID 和多次作答结果

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

真实试卷的打印预览、来源 ID、答案页开关和导出入口

知识点库:按学科、年级、章节逐级浏览

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

数学知识点按四年级、几何图形、角和四边形逐级展开

学习统计:查看错题分布、掌握率、练习正确率和趋势

错题统计展示累计错题、待复习、复习中、已掌握数量及掌握率,附三段式复习状态进度条、科目分布和趋势图;支持按时间范围(近 7 天 / 近 30 天 / 近 6 个月 / 全部)和学科筛选。筛选某个学科后,点击待复习 / 复习中 / 已掌握卡片可直接跳转到该错题本中对应状态的错题列表(地址栏带 ?mastery= 参数,错题列表按此参数预设筛选)。趋势图按粒度显示每日或月度,包含「新增」与「新掌握」两个系列:新增是每桶内创建的错题数,新掌握是最近一次掌握评估时间落在该桶内的已掌握错题数(近似口径,以最近一次评估时间作为掌握时间;这类错题可能创建于范围之前,因此不受创建时间范围限制)。对比两个系列可以直观看出错题本是在变少还是越积越多。没有数据时显示引导去录入错题,加载失败时可重试。

错题统计页签在科目分布与趋势图下方还有「错因分布」卡片:上半部分按作答状态(不会做 / 做错了 / 未判断)展示环形图与占比,下半部分按错误类型展示横向条形列表(名称 + 数量 + 进度条),错误类型为自由文本,仅显示数量前 7 个,其余合并为「其他」;尚未填写错误类型时显示提示文案。统计同样受当前时间范围与学科筛选约束。

错题统计页签在错因分布右侧还有「难度分布」卡片:按难度星级(1~5 星)展示每个难度的总错题数与已掌握数,已掌握部分以不同颜色叠加显示;未评定的错题也会单独列出。没有任何已评星错题时该卡片不显示。

错题统计页签在概览与进度条下方还有「薄弱知识点」排行:按未掌握错题数、近期练习错误率排序,列出最需要巩固的知识点 Top 10。每行展示排名、知识点名称、所属学科、未掌握/总数、近期正确率(无记录时显示「近期未练习」)和未掌握占比进度条;点击一行可跳转到对应错题本并按该知识点筛选的错题列表(地址栏带 ?tag= 参数)。排行只统计当前时间范围内、当前学科筛选下的错题,近期正确率口径与练习统计一致(近 30 天 result 为 correct/wrong 的记录,排除重复导入产生的记录)。

真实错题数量、掌握率、科目分布和月度趋势图表

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

真实练习次数、正确率、活跃月份与练习趋势图表

✨ 主要功能

录入与识别

题目内容

讲解与演示

复习与练习

管理与统计

🚀 快速开始

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

方式一:安装包(Windows / macOS / Linux / 飞牛OS / 群晖 / 威联通 / 安卓 / npm)

从下载页(自动识别系统与架构)或 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。

方式二:Docker 镜像部署(推荐用于服务器 / NAS)

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

镜像标签 说明
2026.10.20 等精确版本 推荐,升级时可控
2026.10 当月最新版本
latest 最新正式版本
  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。

    未设置 NEXTAUTH_SECRET 时,容器首次启动会生成密钥并保存到数据目录的 .nextauth_secret,之后保持不变。

  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。

Unraid(Docker 界面,不使用 docker-compose.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(Container Manager)

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 进入应用,首次启动按页面提示设置管理员。升级套件会按新镜像重建容器并保留数据,卸载套件保留数据目录。

手动容器方式:

  1. 拉取映像:Container Manager → 映像 → 新增,从注册表搜索 margrop/wrong-notebook,或从 URL 添加 ghcr.io/margrop/wrong-notebook:<精确版本>。
  2. 新建容器:容器 → 新增 → 从映像创建。容器名 wrong-notebook;端口本地 3000 → 容器 3000;卷映射 /volume1/docker/wrong-notebook/data → /app/data、.../config → /app/config(读写);环境变量 NEXTAUTH_SECRET、NEXTAUTH_URL、PRESERVE_EXISTING_DATA=true;开启自动重启。
  3. 初始化:启动后在容器详情日志中查找 initialize 链接(令牌也在 /volume1/docker/wrong-notebook/config/setup-token),设置管理员邮箱和密码。
  4. 升级:先按数据备份与恢复停止容器并归档整个目录,或在 Hyper Backup 中把该目录加入备份。然后在映像页拉取新版本标签,停止旧容器,用新映像和相同的卷、端口、环境变量重建;启动时自动迁移数据库,数据保留。使用 latest 时拉取最新映像后重建即可。
  5. 回退:数据库迁移后不一定兼容旧镜像。停止容器,恢复升级前的 data/、config/,再按旧版本映像重建。

威联通 QTS(Container Station)

使用 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 的打开链接进入应用,首次启动按页面提示设置管理员。升级套件会按新镜像重建容器并保留数据,卸载套件保留数据目录。

手动容器方式:

  1. 拉取映像:在映像页拉取 ghcr.io/margrop/wrong-notebook:<精确版本>;也可通过 SSH 执行 docker pull,或使用 应用程序(Compose)方式。
  2. 新建容器:容器 → 创建,选择已拉取的映像。容器名 wrong-notebook;端口主机 3000 → 容器 3000;卷映射 /share/Container/wrong-notebook/data → /app/data、.../config → /app/config;环境变量 NEXTAUTH_SECRET、NEXTAUTH_URL、PRESERVE_EXISTING_DATA=true;重启策略 unless-stopped。
  3. 初始化:启动后在容器日志中查找 initialize 链接(令牌在 /share/Container/wrong-notebook/config/setup-token)。
  4. 升级:先停止容器并归档数据目录,或在 Hybrid Backup Sync 中把该目录加入备份。拉取新版本映像后,用相同卷、端口和环境变量重建容器;使用 应用程序 时,修改 YAML 中的映像标签后重新应用。启动时自动迁移数据库。
  5. 回退:数据库迁移后不一定兼容旧镜像。停止容器,恢复升级前的 data/、config/,再按旧版本映像重建。

上游项目的镜像 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 与语音配置

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

  1. 管理员点击首页右上角的设置图标,打开「AI 设置」。
  2. 选择提供商,填写 API Key、Base URL(或 Endpoint)、模型(或部署名称)。提供商下方附有官方接入文档,「API Key」「模型名称」旁附有获取说明和模型列表链接。
  3. 点击「测试连接」检查文本与图片识别能力,失败时会显示服务商的原始报错;保存后配置写入 config/app-config.json,优先于 .env。
  4. 同一页下方的「语音讲解」切换浏览器语音或云端语音;「提示词」页可自定义识别、解题和举一反三的提示词模板。
  5. 「渠道分工」可让图片识别与文本分析分别使用不同渠道,并指定一个备用渠道:主渠道额度用完或登录失效时自动改用备用渠道,无需再到设置里换渠道。

提示词值得定制。 默认提示词面向通用场景;家长按孩子的年级、薄弱点和学习习惯改写角色、语气和分析步骤,效果通常明显更好。在「提示词」页点「复制」取走默认模板,改好后点「用剪贴板替换」覆盖并保存;「恢复默认」可随时退回。请保留模板中的 {{变量}},它们会被替换为每道题的数据,页面会提示遗漏的变量。应用仍会补充输出协议、语言、年级、知识点和生成题型规则,旧模板遗漏变量时也不例外。

渠道分工能省钱。 拍照识别需要能看图的模型,解题、判分、举一反三等纯文字任务用便宜的文字模型即可。在「渠道分工」中分别选择「图片识别渠道」和「文本分析渠道」,两者可各自填自己的 API Key;再选一个「备用渠道」,例如让付费渠道给免费 MiniMax Code 积分兜底——积分用完后自动接手,不用手动切换。用量按实际使用的渠道分别记录。

提示词、渠道分工都属于实例级设置。 AI 设置、提示词、连接测试和模型列表只对管理员开放;普通用户在「设置 → 通用」中只能修改自己的偏好。

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

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

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

支持的 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 Code OAuth

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

使用方法:在“设置 → 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。

📚 更多

PWA(添加到主屏幕)

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

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

屏幕截图(需要 HTTPS)

屏幕截图依赖浏览器的安全上下文(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/ 目录下提供维护和调试脚本,例如:

文档

使用、部署和常见问题见 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,方便跟踪处理;在群里发截图前请隐去孩子姓名、学校、账号和访问地址。

智能错题本用户交流 QQ 群二维码,群号 964325781

也可以在 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 扩展,原项目代码版权归原作者所有。

wrong-notebook (margrop/wrong-notebook)

正在搜索数据库…

这是什么?Wrong Notebook(智能错题本)是一个由 AI 驱动的错题管理系统:你可以拍照或手动输入题目,AI 会识别题目、给出解答、标注知识点、评定难度,并长期跟踪你的掌握情况。
这是需要自己部署的服务,还是只是一个手机应用?这是一个可自托管的 Next.js 网页应用,需要你自己运行(可以用 Docker、npm 或二进制文件)。另外还提供可选的桌面端(Windows/macOS/Linux)和 Android 应用,其中包括内置服务器的独立版 Android 应用。
我该怎么把它跑起来?推荐使用 Docker:下载仓库中的 docker-compose.yml,设置 NEXTAUTH_SECRET,然后运行 docker compose up。你也可以使用 Node.js 22+ 和 npm 从源码本地构建,或者使用 npm、Windows、macOS、Linux、Android 的预构建安装包。首次登录的账号是 admin@localhost,密码是 123456,之后设置向导会强制你修改密码。
使用它是否需要付费购买 AI API 密钥?不需要。你可以使用免费的“MiniMax Code OAuth”渠道,在浏览器中登录 MiniMax Code 账号即可,它会使用每日免费额度调用 MiniMax-M3.1-Flash,无需付费的 API 密钥。如果你愿意,也可以使用付费服务商,包括 GLM、DeepSeek、Kimi、Qwen、Anthropic、Azure OpenAI、OpenAI 和 Gemini。
任何 AI 模型都能用吗?不是。所选模型必须支持图片输入(多模态),才能进行拍照识题,否则你只能手动输入题目。另外,模型还需要能输出较长且格式规范的内容,SVG 动画讲解才能有良好的效果。
我可以在哪些平台上运行或安装它?它可以通过 Docker/npm 在 Linux(amd64/arm64)上以自托管网页应用的形式运行,并提供 Windows、macOS、Linux、飞牛OS 和 Android(独立版或客户端版)的原生安装包。它还支持 PWA,可以添加到 iPhone/iPad 或 Android 的主屏幕。
什么是 SVG 动画讲解功能?AI 会生成分步骤的解题 SVG 动画,带有播放/暂停、拖动进度和重播控制。你还可以选择使用浏览器语音合成,或云端语音合成(MiniMax/Qwen),为每一步配上语音讲解。
间隔复习是怎么运作的?错题会按照艾宾浩斯式的间隔安排复习,间隔为 1、2、4、7、15 和 30 天。做对变体题会进入下一个间隔,做错则会重置复习计划。“今日复习”列表会显示当天需要复习的题目。
外部智能体能自动把题目送进来吗?可以。Openclaw 智能体可以通过 POST /api/openclaw/batch-upload 接口批量上传题目照片,相关设置通过环境变量完成。
为什么不直接用上游项目的 Docker 镜像?这个仓库是 wttwins/wrong-notebook 的分支,并增加了许多功能,因此上游镜像(ghcr.io/wttwins/wrong-notebook)不包含这些功能。请改用 ghcr.io/margrop/wrong-notebook。
作者
margrop
大小
79.9 MB
星标
651
时长
1个月
提交 · 90 天