MathBank - 本地化数学题库教研管理工作台

🏷️ 项目标签：数学题库 | 高中数学 | 备课教研 | LaTeX公式 | 公式识别 | OCR | DeepSeek AI | 教育技术 (EdTech)

🎉 MathBank 是一个为数学教师设计的、本地运行的轻量级半自动化数学题库管理系统。

本项目追求极简的配置与极致的本地体验，没有复杂的前端构建和繁重的第三方依赖，开箱即用，支持 LaTeX 公式秒级实时渲染，并深度集成了主流的大语言模型与 OCR 接口。

🎯 项目设计初衷与定位

本项目最初完全基于作者个人的实际高中数学教研与备课需求进行独立开发，因此在功能体系与数据内置上有着非常鲜明的个性化定位：

• 📚 教材目录内置：目前系统仅内置并适配了 「人教A版」 高中数学教材的章节目录与知识点级联结构。
• 🔍 题型与难度聚焦：本题库仅重点收录和整理「易错题」、「挑战题」及「强基题」。作者认为，网络上已存在海量的公开基础题、常规题，无须在本地题库中重复造轮子。本系统的核心价值在于对 高质量 的题目进行精细化收集与 AI 智能解析教研。
• 📋 关于组卷功能：由于本题库定位为“高价值特色题目的精细收集与整理”，而非大而全的通用考试卷库，因此系统 目前暂未开发 传统的“一键组卷”功能，未来将根据实际教研场景的演进再作规划。

🔧 二次开发：如何自定义教材或难度？

如果您有不同的教材版本（如人教B版、北师大版、苏教版）或希望自定义难度梯度（例如增加“基础题”或“压轴题”），可以直接按以下指引在本地进行极简改造：

1. 修改/增加教材目录结构：
   • 打开 main.py，找到其中的 RENJIAO_A_CURRICULUM 字典。您可以按相同的 Python 嵌套字典格式，自由修改学段、章节以及小节知识点名称，保存后大纲树级联将自动在前端生效。
   • 💡 提示：为避免修改代码中的多处引用，请直接在 RENJIAO_A_CURRICULUM 变量内部修改大纲内容，不要修改该变量名本身。
2. 自定义难度梯度：
   • 前端下拉菜单修改：打开 static/index.html，在 id="filterDifficulty"（左侧过滤选项）和 id="editDifficulty"（编辑表单选项）中，增加或修改您的新难度标签（例如 <option value="basic">基础题</option>）。
   • 前端样式与翻译：打开 static/js/api.js，在 getDifficultyBadge（小药丸徽章样式）与 getDifficultyText（翻译显示文本）这两个函数中，参照已有格式增加对您新难度 Key 的解析映射。
   • 后端大屏统计对接：打开 main.py，在 /api/stats 统计接口中，增加对您新加难度的 SQLAlchemy 查询计数，以确保项目首页的数据大屏能正常展示新增难度的题目数。

---

🌟 核心特性

• 🧪 极简技术栈：后端基于 Python + FastAPI + SQLAlchemy，数据库使用轻量级 SQLite；前端使用纯 HTML + JavaScript（无编译、无捆绑），通过 CDN 引入 Tailwind CSS 和 KaTeX。
• 📐 完美公式渲染：原生支持题干与解析框的 LaTeX 公式实时解析，秒级双向预览渲染。
• 🤖 三合一解答工作流：支持手动录入、AI 智能生成（如 DeepSeek 步骤推导）、OCR 图像识别（支持阿里百炼、硅基流动、SimpleTex 多通道公式识别）。
• 📂 存储自愈净化：编辑或删除题目时，系统会在后台物理删除不被任何题目引用的垃圾图片文件，并支持服务启动安全防误删扫描净化。
• 🔒 AI 专属只读题库备份：后台写入时自动生成 data_backup/questions_library.md（AI 专属题库），自动清洗 \item 等 Markdown 不兼容排版命令，且彻底过滤答案与解析，保障备课和 AI 命题时的隐私安全。
• 💻 CLI 极速模糊检索：内置终端检索工具 search_questions.py，支持在终端通过命令行快速查询知识点和题干。

---

🛠️ 快速开始

Tip

📦 便携包推荐（非技术/懒人用户首选） 如果您不熟悉 Git、Python 或命令行操作，可以直接前往 Releases 页面 下载我们打包好的双平台便携包，解压即用：

• 💻 Windows 用户：下载 MathBank-Windows-x64.zip，解压后双击 启动题库系统.bat 即可运行（包内已完整内置便携式 Python 运行环境）。
• 🍏 macOS 用户：下载 MathBank-macOS.zip，解压后双击 启动题库系统.command 即可运行（首次启动时会自动在本地创建虚拟环境并初始化依赖）。

⚠️ 关于 API 密钥的获取与配置： 无论是使用源码还是便携包，AI 智能解析与 OCR 公式识别均依赖外部 API。请先前往以下平台注册并申请相应的 API 密钥，在启动项目后，点击网页右上角的 设置（齿轮）按钮 即可一键填入并保存：

• 🤖 AI 推理大模型：请注册并获取密钥于 DeepSeek 开放平台
• 📷 OCR 公式识别（首选通道）：请通过专属 硅基流动 (SiliconFlow) 邀请链接 注册并获取密钥 (模型推荐使用 Qwen/Qwen3-VL-8B-Instruct，正常够用了；也可以选择 Qwen/Qwen3-VL-32B-Instruct，双倍价格但效果更好)
• 📷 OCR 公式识别（备选通道）：请注册并获取 Token 于 SimpleTex 开放平台 (专注复杂数学公式识别)

如果您需要进行二次开发或习惯使用终端，请参照以下常规步骤运行源码：

1. 克隆/下载项目到本地

git clone https://github.com/JudgePeach/math-question-bank.git
cd math-question-bank

2. 安装 Python 依赖

推荐在 Python 3.8+ 环境下运行以下命令：

pip install -r requirements.txt

3. 配置 API 密钥（二选一）

• 方式 A（网页配置，推荐）：直接启动项目，进入网页后点击右上角的设置（齿轮）按钮，直接在面板中填写您的 API 密钥保存，后端会自动生成 .env 配置文件。
• 方式 B（手动配置）：复制 .env.example 为 .env，并在文件中填入您的密钥：

  cp .env.example .env

4. 启动项目

🍏 Mac 用户（一键启动）

双击项目根目录下的 启动题库系统.command 脚本，系统将自动检查并释放端口、在后台拉起服务，并自动为您在默认浏览器中打开：

http://127.0.0.1:8000

💻 Windows 用户（一键启动）

双击项目根目录下的 启动题库系统.bat 批处理文件，系统将自动检测 Python 环境、清理端口冲突，并在后台（最小化窗口）拉起服务，且自动为您在默认浏览器中打开：

http://127.0.0.1:8000

⌨️ 命令行启动（通用）

在终端/命令提示符中运行：

python -m uvicorn main:app --reload

打开浏览器访问 http://127.0.0.1:8000。

---

🔍 本地终端命令行检索

为了方便在编写教案、备课时快速访问本地题库，本项目在根目录下提供了一个高效的模糊检索命令行工具 search_questions.py。

在终端中运行（例如搜索包含“导数”的题目）：

python3 search_questions.py -q "导数"

参数说明：

• -q : 检索的模糊关键词（匹配学段、章节、知识点、题干）
• -n : 限制返回数量，默认最多 50 条（使用 -1 为无上限）
• -a : 携带答案和解析（默认只拉取题干，安全防泄露）
• -t : 题型过滤（如 single_choice, fill_in_blank）
• -d : 难度过滤（easy, medium, hard）

---

🧪 运行单元测试

项目配备了高隔离度的 Pytest 单元测试（使用内存 SQLite 数据库，不污染本地数据）。如需测试，请运行：

PYTHONPATH=. pytest tests/

---

📄 开源协议

本项目采用 MIT 协议开源。