offline-quiz-builder

离线智能题库生成器

把用户的学习资料变成一个可离线运行的复习题库网站，并配好每日提醒。

产物是纯静态网页（无框架、无后端、无网络请求），双击 index.html 即可使用， 学习数据存在浏览器 localStorage 中。

核心特性（向用户介绍时的要点）

• 自适应遗忘曲线：每道题都有专属的记忆强度 ease，答得越轻松间隔拉得越长， 答错或卡壳自动缩回来。同一天开始学的两道题，几轮之后复习节奏会完全分开。 这是与「固定 1/3/7/14/30 天」式题库的本质区别。
• 完全离线：无任何网络请求，断网可用，数据不外传。
• 五种题型：单选、多选、判断、填空、简答。
• 配套功能：错题本、收藏夹、打卡日历、学习统计（含趋势图）、深浅双主题、复习节奏可调。

执行流程

步骤 1：确定输入通道

读取用户提供的资料，判断走哪条通道。判断规则与各文件类型的读取方式见 references/material-ingestion.md。

判断为 A 或 A′ 时绝不重新出题——用户已有的题目往往来自真题或老师划的重点， 价值高于 AI 现编的内容。

步骤 2（仅 B 通道）：估算规模并告知

出题前先估算题量和耗时，向用户播报后再开工。超过 150 道题时必须先征询用户意见。 估算方法与播报格式见 references/material-ingestion.md。

步骤 3（仅 B 通道）：生成题目

严格按 references/question-schema.md 生成。该文档定义了：

• 顶层结构、meta / subjects 字段含义
• 五种题型各自的必填字段与取值约束
• 20 个可选科目图标及其适用学科
• 出题质量准则（一题一考点、干扰项要合理、解析讲原因、难度与题型配比等）

题量超过 40 道时分片生成，每片单独落盘再合并，避免单次输出过长导致 JSON 截断。

关于出处：.docx / .md / .txt 没有可靠分页信息，source.page 必须为 null， 章节信息放进 locator。绝不编造页码。

步骤 4：预检

 /scripts/build_bank.py   --check-only

脚本会逐条校验并打印题目总数、题型/科目/难度分布。有错先修再继续， 常见报错与修法见 references/material-ingestion.md。

步骤 5：向用户预览确认

建站前必须展示并等待用户确认：

1. 上一步输出的四项分布统计
2. 随机抽 3 道题的完整内容（题干、选项、答案、解析），题型尽量不同
3. 提示用户可以现在提出调整

抽样展示是最有效的质量闸门，不要跳过。

步骤 6：建站

把应用模板拷到目标目录，再写入题库数据：

# 1. 拷贝应用壳（不含题库数据）
cp -r /assets/app-template/. /

# 2. 写入题库（同时生成 questions.json 与内嵌的 assets/js/data.js）
 /scripts/build_bank.py  

`` 默认放在用户工作目录下的 题库/ 或 quiz-site/，路径里尽量不要有空格。

应用壳不要改写。 网页的品牌名、标题、科目图标全部由题库 JSON 的 meta.brandName / meta.title / meta.brandIcon / subjects[].icon 驱动， 改这些字段即可，无需碰 HTML/CSS/JS。这样才能保证每次生成的成品完全一致。

步骤 7：验收

用浏览器打开确认无误：

 /scripts/open_quiz.py 

检查首页科目卡片数量与题量是否正确、进入科目能弹出今日复习、能正常作答。

步骤 8：创建每日提醒

先问用户希望几点被提醒，然后用 automation_update 创建定时任务。 完整的参数模板、rrule 写法、prompt 模板见 references/automation-reminder.md。

这一步有一个必须遵守的硬约束：提醒任务只能通过 scripts/open_quiz.py 以 file:// 打开题库，绝不能用 present_files 或任何本地 HTTP 预览。 原因是 localStorage 按来源隔离，用预览面板打开会让用户看到一个进度全空的题库， 且数据永久分裂。详见该参考文档。

用户明确表示不需要提醒时跳过本步，不要反复劝说。

步骤 9：收尾说明

告知用户：

• 站点位置，以及双击 index.html 即可使用
• 学习数据只存在这台电脑的这个浏览器里，清缓存、换浏览器、无痕模式都会丢失
• 不要移动站点目录——路径变了 file:// 的 URL 就变了，可能读不到原数据
• 想改题目可直接编辑站点根目录的 questions.json，改完重新运行 build_bank.py 同步
• 提醒任务可在「设置 → 数据管理」中管理

资源索引

常见偏差

以下是容易做错的地方，逐条规避：

• 拿到成品题库还重新出题 —— A/A′ 通道只做转换，不要用 AI 重写用户的题目。
• 编造页码 —— docx/md/txt 一律 source.page: null。
• 跳过预览确认 —— 用户看不到样题就无法发现 AI 理解偏差，错题会被反复复习，危害成倍放大。
• 改写应用壳 —— 品牌与图标走数据驱动，改模板会破坏成品一致性。
• 提醒任务用预览面板打开 —— 会导致学习数据分裂，这是最严重的错误。
• 在提醒里编造进度数字 —— Agent 读不到 localStorage，说「你今天有 N 道题」必然是假的。
• 一次性输出上百道题 —— 容易中途截断，务必分片。