速记卡 Study Flashcards

本地可运行的题库练习系统：多题库 · 错题本 · SQL 在线判题 · C++ 编译判题 · AI 学习助手

---

纯 HTML/CSS/JS 前端 + Python 标准库后端（零第三方依赖），打开浏览器就能刷题：选择题即时判定并给出逐选项解析，简答题展示答案后自评对错；内置 MySQL 练习（SQL 在线运行 + 自动判题）与 C++ 算法练习（在线编译运行 + 用例比对）；还集成了聊天学习助手（后端代理调用大模型，API Key 不出本机，会话本地落盘）。

A local-first quiz & flashcards web app with an online SQL judge, a C++ compile-and-run grader, and a BYO-key AI study assistant — zero third-party dependencies, your data never leaves the machine.

🖼️ 界面预览

主界面：题目卡片、选项判定与逐选项解析

✨ 功能亮点

📚 多题库合并加载 基础题库 + 7 个可选题库包自动合并，缺失某个包不影响整体运行；题库下拉分组、目录概览、搜索跳转一应俱全。	✅ 即时判定与逐选项解析 选择题提交后高亮对错，每个选项都有独立解析；简答题展示答案后自评，支持公式推导、变量说明、例题等结构化区块。
🗄️ SQL 在线判题 MySQL 语法练习题，后端在只读 SQLite 判题库上执行并比对结果集；仅放行 SELECT，内置 shop / hr / school 三套数据集。	⚙️ C++ 在线编译判题 算法题调用本机 g++/clang++ 在临时目录编译运行，按测试用例比对标准输出，编译错误与超时都有反馈。
🤖 AI 学习助手 后端代理调用 MiniMax API，Key 只存本机环境变量；支持「带入当前题目」提问，回答里的 LaTeX 公式直接渲染，会话落盘可回溯。	📖 小白模式 + 公式渲染 内置术语词典自动扫描题干/解析生成「名词解释」；MathJax 渲染 LaTeX 公式与推导，多 CDN 兜底、失败可降级。
🎯 错题本与进度统计 localStorage 持久化做题进度、错题列表、每题尝试/错误统计；「只看错题」模式 + 顺序/随机两种出题策略。	🏠 纯本地、零依赖部署 后端只用 Python 标准库 http.server，无需 pip install；同一 Wi-Fi 下平板也能访问，断网可刷题（聊天除外）。

🏗️ 架构与数据流

flowchart TD
    A["浏览器前端 site/<br>纯 HTML + CSS + JS"] -->|"GET 题库 *.json"| B["server.py<br>Python 标准库 http.server"]
    A -->|"POST /api/sql/run"| B
    A -->|"POST /api/cpp/run"| B
    A -->|"POST /api/minimax/chat"| B
    B -->|"只读执行 + 结果比对"| C["SQLite 判题库（只读）<br>shop / hr / school 数据集"]
    B -->|"临时目录编译运行"| D["g++ / clang++<br>用例输出比对"]
    B -->|"代理转发（Key 不出本机）"| E["MiniMax API<br>聊天学习助手"]
    B -->|"会话落盘"| F[("data/chat_sessions/<br>+ chat_logs.jsonl")]

Loading

🚀 快速上手

只需要 Python 3，无需安装任何依赖：

git clone https://github.com/JingHao-Leon/study-flashcards.git
cd study-flashcards
python server.py

• 电脑浏览器：http://127.0.0.1:5173/
• 平板（同一 Wi-Fi）：http://<你的电脑局域网IP>:5173/（需以 HOST=0.0.0.0 python server.py 启动）
• 端口/监听地址可用环境变量覆盖：PORT、HOST

⚠️ 不要双击 site/index.html 用 file:// 打开——题库 fetch 与 API 都需要经由本地 server 访问。 C++ 判题需要本机已安装 g++ 或 clang++（Windows 推荐 MinGW-w64）并加入 PATH；未安装时其余功能不受影响。

基础题库说明

site/questions.json（基础题库）未随仓库发布（见 .gitignore）。缺失时 7 个可选题库包仍可正常加载练习；如需从 PDF 抽题生成自己的基础题库：

python tools/extract_mcq.py \
  --pdf "你的题库1.pdf" \
  --pdf "你的题库2.pdf" \
  --out "site/questions.json"

📦 内置题库一览

题库文件	题数	内容
fintech_beginner_questions.json	150	金融科技入门
fintech_questions.json	120	金融科技进阶
deep_learning_questions.json	80	深度学习
xigua_ml_questions.json	52	西瓜书风格机器学习
fintech_math_formulas.json	25	金融数学公式推导卡（LaTeX）
mysql_practice_questions.json	24	MySQL 练习（在线运行判题）
cpp_algo_questions.json	16	C++ 算法题（在线编译判题）

新增题库很简单：放一个 site/<your_pack>.json（JSON 数组，每题至少含 id/source/seq/type/question），再到 site/app.js 的 extraPaths 里登记路径即可。

⚙️ 配置（聊天助手可选）

聊天功能需要配置环境变量，或复制 .env.example 为 .env.local 填写（不要提交到 Git）：

变量	必填	说明
MINIMAX_API_KEY	✅	MiniMax API Key
MINIMAX_MODEL	⬜	模型名，默认 MiniMax-M2.7-highspeed
MINIMAX_GROUP_ID	⬜	MiniMax Group ID
MINIMAX_BASE_URL	⬜	API 地址，默认 https://api.minimax.chat/v1
MINIMAX_SOUL_FILE	⬜	助手人格/输出规范文件，默认读根目录 soul.md

📁 目录结构

├── server.py                      # 后端：静态服务 + SQL/C++/聊天 API（纯标准库）
├── soul.md                        # 聊天助手人格与输出规范（系统提示词）
├── requirements.txt               # 空文件——零第三方依赖
├── .env.example                   # 聊天配置模板
├── site/
│   ├── index.html                 # 页面骨架（MathJax 多 CDN 兜底）
│   ├── app.js                     # 前端全部逻辑：题库加载/判定/目录/聊天 UI
│   ├── style.css                  # 样式
│   ├── sql_datasets.json          # SQL 判题数据源：shop / hr / school
│   ├── sql_datasets.sqlite        # 判题库（由 tools/rebuild_sql_db.py 生成，判题期只读）
│   └── *_questions.json           # 7 个内置题库包（见上表）
├── tools/
│   └── extract_mcq.py             # 从 PDF 抽题生成 questions.json
├── assets/
│   └── preview.png                # 界面预览（本 README 引用）
└── TECHNICAL_OVERVIEW.md          # 技术原理拆解（架构/状态机/扩展指南）

想深入了解实现机制（选择题状态机、术语扫描、MathJax 策略、会话落盘格式、如何扩题库），请读 TECHNICAL_OVERVIEW.md。

❓ FAQ

Q：需要 pip install 吗？

不需要。后端只用 Python 标准库 http.server，python server.py 即可启动；SQL 判题用标准库 sqlite3（只读打开随仓库分发的判题库），C++ 判题调用本机编译器。唯一的外部依赖是聊天助手（可选）需要配置 MiniMax API Key。

Q：能部署到 GitHub Pages 或公网服务器吗？

前端可以静态托管，但 SQL 判题、C++ 编译和聊天代理这三个接口由 server.py 提供，纯静态托管时不可用。本项目按本地学习工具设计：无账号体系、无鉴权，不建议暴露到公网。

Q：我的做题进度和聊天记录存在哪里？

进度与错题存在浏览器 localStorage（不换浏览器就不丢）；聊天会话落盘在本机 data/chat_sessions/ 与 chat_logs.jsonl。数据不出本机，不同设备之间也不同步。

Q：SQL 判题是真 MySQL 吗？

题目按 MySQL 语法设计，实际在只读 SQLite 判题库上执行并比对结果集，仅放行 SELECT。判题库由 tools/rebuild_sql_db.py 从 site/sql_datasets.json 生成，新增数据集时改 JSON 后重新生成即可。个别 MySQL 专有函数行为可能有差异，以 server.py 实现为准。

Q：怎么添加自己的题库？

放一个 site/<your_pack>.json（JSON 数组，每题至少含 id/source/seq/type/question），再到 site/app.js 的 extraPaths 里登记路径；也可以用 tools/extract_mcq.py 从 PDF 抽题生成。

⚠️ 说明与局限

• 本地学习工具：进度与错题存在浏览器 localStorage，无账号体系、不同设备间不同步。
• GitHub Pages 无法完整运行：纯静态托管可以用，但 SQL/C++ 判题与聊天必须运行 server.py。
• SQL 判题方言：题目按 MySQL 语法设计，实际由只读 SQLite 判题库执行，个别 MySQL 专有函数行为可能有差异；仅放行 SELECT 查询。
• C++ 判题依赖本机编译器，运行超时与输出比对的规则以 server.py 实现为准。
• 基础题库 site/questions.json 未入库，需自行生成或从空数组起步。

---

_{本地运行 · 零依赖 · 数据不出本机 ｜ License: MIT
Made with ☕ by JingHao-Leon}