Smart Wrong Notebook (智能错题本)

简体中文 | English

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

🌐 项目介绍页：https://blog.margrop.net/wrong-notebook-github-pages/

📝 介绍文章：别让错题本变成抄题本：我给孩子用的 AI 错题本开源了 · 不用先配 API Key：接上 MiniMax 免费账号

🚀 在线演示：https://wrong-notebook-demo.vercel.app（账号 demo@localhost，密码 demo123456）

演示站点为共享账号，数据对所有访客可见，请勿录入个人信息。

📦 多平台安装：Docker 镜像（amd64 / arm64）· npm（npm i -g wrong-notebook）· Windows · macOS · Linux · 飞牛OS · 安卓手机 / 平板（单机版内置服务端，或连接服务器的客户端），安装包见 Releases，安装方式见快速开始。

🆓 免费的 MiniMax 账号就能用：选择「MiniMax Code OAuth」渠道，用 MiniMax Code 账号网页登录即可调用 MiniMax-M3.1-Flash，不需要购买 API Key。应用每天自动签到领取积分，识题、讲解等 AI 功能消耗的是账号的免费积分额度，详见 MiniMax Code OAuth。

本仓库 fork 自 wttwins/wrong-notebook，在其基础上增加了较多功能（见下文）。

⭐ Star 增长趋势

🖼️ 功能预览

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

错题管理：在同一页面查看题目摘要、难度星级和知识点，按年级、学期、掌握情况及 A/B 卷筛选，也可通过题目 ID 定位、比较相似度或批量打印。

列表按需加载卡片数据，原图、答案和解析在详情或打印预览时读取，减少翻页时的数据传输。

✨ 主要功能

录入与识别

• 📷 多种录入方式：上传图片、从剪贴板粘贴（Ctrl/⌘+V）、屏幕截图，或直接输入题目文字（支持 Markdown 和 LaTeX）；图片可裁剪（支持滚轮、双指捏合或按钮缩放图片，方便精确框选），也可在一张图上框选多道题批量导入。
• 🤖 AI 识别与解答：识别题目文字、答案、解析、学生的错误解答和错因，判断学科，并从知识点库中选择标签。可在「设置 → 通用」中开启「导入前人工确认」，先在校对页修改再保存。
• 🔁 重复题判定：导入时比较题干相似度，超过阈值（默认 90%，可在设置中调整）的题目不会重复导入，而是在原题下记一次做错。
• 🆔 题目 ID：每道题有 6 位 ID，可复制，也可在错题本中输入 ID 直接打开该题；打印的错题和试卷都标有「来源 ID」，方便做完后定位原题录入结果。

题目内容

• ∑ LaTeX 公式：题目、答案和解析中的公式用 KaTeX 显示，支持 $…$、$$…$$、\(…\)、\[…\]；编辑时可在「源代码 / 预览」之间切换。检测到公式语法错误时，详情页出现「修复 LaTeX」按钮，由 AI 只修复公式写法。
• 📝 重新生成解答：详情页「重新生成完整解答」由 AI 重新生成答案和解析（覆盖前二次确认），知识点和错因保持不变。
• 🖼️ 题目配图：识别时由 AI 用 SVG 重绘题目配图，详情页、打印和试卷都使用 SVG 配图；拍照原图可在「查看原题图片」中核对，也可替换或补充上传。
• ⭐ 难度星级：导入时由 AI 参考《高思学校竞赛数学导引》的星级标准评定 1~5 星（一二星为课本及校内拔高，三四星为常规奥数，五星为竞赛压轴），可手动修改；4 星及以上默认归入 B 卷。
• 🏷️ 知识点标签：错题本创建时选择学段（小学/初中/高中）和学科（创建后不可修改），本错题本内的题目由 AI 从该学段、该学科的全部知识点中选择标签；支持自定义标签，单题或整本错题本可让 AI 重新识别知识点和难度。

讲解与演示

• 🎬 SVG 动画讲解：AI 按解题思路生成分步骤的 SVG 动画，支持播放/暂停、拖动进度、重播和全屏。动画文字与界面语言一致：中文界面生成中文版、英文界面生成英文版，两种版本分别保存，切换语言时自动显示对应版本。默认开启，可在「设置 → 通用」中关闭。
• 📐 GeoGebra 动态演示：数学、物理题可由 AI 生成交互式 GeoGebra 图形。默认关闭，可在「设置 → 通用」中开启。
• 已生成的动画讲解和 GeoGebra 演示都可删除（需二次确认）。

复习与练习

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

管理与统计

• 🔍 多维度筛选：按掌握状态、时间范围、知识点、年级学期、试卷等级等条件筛选，支持批量操作和两题相似度比较。
• 📊 数据统计：错题与练习的掌握率、月度趋势和学科分布。
• ⏳ 后台任务：页面右下角的按钮可查看识别、AI 生成、批量标注、组卷等耗时事务的进度；离开页面后事务仍在服务器上继续。
• 💾 数据导入导出：在「设置」中导出或导入数据备份，包含错题本、错题、练习与作答记录、试卷和个人偏好；账户凭据和 AI 配置不在备份中。
• 🕒 应用时区：默认北京时间，管理员可修改，日期显示与统计都按应用时区计算，详见 时区说明。
• 🧭 安装向导：管理员首次登录时进入向导：修改默认密码（必须）→ 配置 AI 渠道（推荐免费的 MiniMax Code）→ 创建第一个错题本，后两步可跳过；可在「设置 → 用户管理」中重新运行。已在使用的实例升级后不会自动弹出。
• 🔐 多用户与管理后台：支持注册、登录，数据按用户隔离；新用户注册默认关闭，管理员可在「设置 → 用户管理」中开启，并可限制每人每天的 AI 使用次数、查看今日用量；管理员可在「设置 → 用户管理」进入管理后台，查看使用统计，启用/禁用或删除用户。
• 🔌 Openclaw 集成：外部 Openclaw agent 可通过 POST /api/openclaw/batch-upload 批量上传题目图片，配置见下文环境变量。

📸 屏幕截图功能 (HTTPS 设置)

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

📱 PWA 支持 (添加到主屏幕)

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

• iPhone / iPad (Safari): 点击底部 分享 按钮 -> 选择 "添加到主屏幕"。
• Android (Chrome): 点击右上角 菜单 -> 选择 "添加到主屏幕" 或 "安装应用"。也可以安装 Releases 中的安卓 App（见下文安装包）。

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

🛠️ 技术栈

• 框架: 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 / Anthropic（及兼容接口）/ Azure OpenAI / OpenAI（及兼容接口）/ Google Gemini
• 认证: NextAuth.js v4
• 测试: Vitest（单元、集成）、Playwright（E2E）

🚀 快速开始

方式一：本地源码运行

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

2. 克隆并安装依赖：

   git clone https://github.com/margrop/wrong-notebook.git
   cd wrong-notebook
   npm ci

3. 配置环境变量：复制 .env.example 为 .env，按下文「环境变量」一节填写。

   cp .env.example .env

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

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

5. 启动开发服务器：

   npm run dev

   访问 http://localhost:3000，使用默认管理员账户登录：邮箱 admin@localhost，密码 123456。首次登录会进入安装向导：先修改默认密码（必须），再配置 AI 渠道、创建第一个错题本。

AI 的 API Key 等也可以在登录后通过网页设置填写，见下文「AI 模型配置」一节。

方式二：Docker 镜像部署（推荐）

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

可用版本见 Releases。

1. 准备目录和密钥：

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

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

   使用 docker run：

   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：下载仓库中的 docker-compose.yml 放到当前目录，修改 NEXTAUTH_SECRET（及 NEXTAUTH_URL）后执行：

   docker compose up -d

3. 登录：访问 http://你的IP或域名:3000，使用默认管理员账户登录：邮箱 admin@localhost，密码 123456。首次登录会进入安装向导：先修改默认密码（必须），再配置 AI 渠道、创建第一个错题本。

4. 升级：拉取新镜像并重建容器，数据保留在挂载目录中，启动时只执行数据库迁移。

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

   升级前建议先备份 data/ 目录。

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

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

方式三：从源码构建镜像

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

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 即可。

方式四：安装包（npm / Windows / macOS / Linux / 飞牛OS / 安卓）

不想使用 Docker 时，可以从 Releases 下载桌面版或飞牛OS 安装包，也可以通过 npm 安装：

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

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

数据目录、默认账号、本地构建方法见 INSTALL_PACKAGES.md。

🔧 环境变量

基础配置

AI 配置（网页中保存的配置优先于环境变量）

Openclaw 集成（可选）

新增环境变量时需同步更新 .env.example。

⚙️ AI 模型配置

AI 配置可在网页中动态修改，无需重启服务器。

1. 进入设置：管理员点击首页右上角的设置图标，打开「AI 设置」。
2. 选择提供商：默认使用 MiniMax；可选 MiniMax、用 MiniMax Code 账号网页登录的 MiniMax Code OAuth、智谱 GLM、DeepSeek、Kimi，以及 Anthropic、Azure OpenAI、OpenAI（含兼容接口）、Google Gemini，OpenAI 可添加多个配置并切换。
3. 填写参数：API Key、Base URL（或 Endpoint）、模型（或部署名称）；可测试连接并从接口获取模型列表。
4. 保存生效：配置保存到 config/app-config.json，优先级高于 .env。

「提示词」页可自定义识别和举一反三的提示词模板。

模型要求

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

推荐使用各提供商当前的多模态旗舰或快速模型，例如 MiniMax-M3.1-Flash、glm-5.3-flash、deepseek-flash、kimi-k3、claude-sonnet-5-5、gpt-6.1-sol、gemini-3.8-flash。使用兼容接口的第三方模型时，请先确认它支持图片输入。

配置样例

国产大模型官方渠道

以下渠道通过各家官方的 OpenAI 兼容接口调用，只需填写 API Key；Base URL 和模型留空时使用下表默认值（中国大陆官方地址和当前最新的多模态模型）。使用国际站时把 Base URL 改为国际站地址即可。

MiniMax Code OAuth

支持免费版 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 的服务条款。

Anthropic

兼容模式：Anthropic 提供商同样可以接入兼容 Anthropic Messages API 的第三方服务。Base URL 填写服务商提供的地址（不含 /v1，程序会自动拼接 /v1/messages），模型名称填写对应平台的模型 ID。推理模型返回的思考内容会被自动忽略。

Azure OpenAI

OpenAI

兼容模式：OpenAI 提供商兼容所有支持 OpenAI API 格式的第三方服务。将 Base URL 改为对应服务地址，即可使用硅基流动、通义千问 DashScope 等平台的模型，模型名称填写对应平台的完整模型 ID。

Google Gemini

权限：AI 设置、提示词、连接测试和模型列表只对管理员开放；普通用户在「设置 → 通用」中只能修改自己的偏好（导入前人工确认、SVG 动画讲解、GeoGebra 动态演示、判重阈值）。应用时区由管理员设置。

🧪 开发与测试

npm run lint                # ESLint（出现警告即失败）
npm run test:unit           # 单元测试
npm run test:integration    # 集成测试
npm test                    # 全部 Vitest 测试
npm run test:coverage       # 测试覆盖率（低于最低要求时失败）
npm run test:e2e            # Playwright E2E（先运行 node scripts/prepare-e2e.js 准备测试账号）
bash scripts/ci.sh          # 完整 CI（Node.js 22+、Python 3，含生产构建）

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

📚 文档

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

🛠️ 实用脚本

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

• 重置密码：node scripts/reset-password.js <邮箱> <新密码>
• 重建管理员：node scripts/seed-admin.js（默认 admin@localhost / 123456）
• 重建系统知识点：npx ts-node --compiler-options '{"module":"CommonJS"}' scripts/rebuild-system-tags.ts（保留自定义标签和题目关联；生产环境操作前请先备份）
• 检查数据库：node scripts/check-db-users.js、node scripts/check-db-data.js

🤝 参与贡献

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

📄 许可证

MIT License

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