Quiz Builder — 学习材料 → 单文件 HTML 互动习题库

把任意学习材料变成一个 自包含、可离线打开、可反复刷 的 HTML 习题库。最终产物 是 一个 .html 文件：双击即用、零依赖、进度存在浏览器本地、可发给同学或丢进 网盘。适用于备考、刷题、记忆类自学。

• 模板：${CLAUDE_SKILL_DIR}/templates/quiz_template.html（完整引擎，5 个占位符）
• 可运行示例：${CLAUDE_SKILL_DIR}/examples/demo.html（5 种题型 + 中英双语，先打开它看成品）
• 辅助脚本：${CLAUDE_SKILL_DIR}/scripts/（仅在处理 PPT 导出 PDF 时才需要，见 Phase 2）
• 姊妹 skill：cheatsheet-generator（同样"材料 → 复习产物"，但产出 LaTeX 速查表）

技能目录是 ${CLAUDE_SKILL_DIR}。工作目录默认当前目录，除非 $ARGUMENTS 指定路径。 按顺序执行下面四个阶段。

---

Phase 1 — 收集材料 & 确认配置

1. 扫描材料：用 Glob 找 **/*.{pdf,pptx,md,txt,docx,ipynb,html} 和图片 **/*.{png,jpg,jpeg}。也接受用户直接粘贴的文本 / 一个网址。
2. 用 AskUserQuestion 一次问清（给出默认值，能推断的就别问）：
   • 题库标题（+ 是否要中英双语标题）。
   • 怎么分组（groups）：按章节 / 周 / 主题，默认一章一组。
   • 题量与配比：每组多少题；"官方/原文题"（type:"official"，来自材料原文） vs "自拟练习题"（type:"practice"）的比例。默认：原文里的例题全收 + 每组补 4-6 道练习题。
   • 题型（kind，可混用）：单选 single / 多选 multi / 判断 tf / 填空 fill / 闪卡 flash。默认以单选为主，按材料性质点缀其它题型 （概念记忆→闪卡，定义→填空，"对错辨析"→判断，多个正确项→多选）。
   • 语言：UI 与解析默认语言（zh/en）。模板本身支持运行时一键切换，且题目 文本字段可写成 {zh, en} 双语；先问清是否要双语出题（双语出题工作量更大）。

---

Phase 2 — 把材料读成"带出处的干净文本"（按类型分支，不要一刀切）

目标：拿到可靠的文本，并尽量保留出处（页码/章节）以便每题标 source。按材料 类型选路径，绝大多数材料用不到去动画那一步：

• Markdown / txt / 网页 / 用户粘贴文本 → 直接 Read，无需任何依赖。
• DOCX / ipynb → 直接 Read。
• 普通 PDF（教材、讲义、试卷） → 优先用 Read 工具直接读 PDF；需要更精确的 逐页文本时再用 pdftotext -layout file.pdf out.txt（macOS 自带 / poppler）。
• 图片笔记 / 拍照讲义 → 用 Read 直接视觉读取。
• ⚠️ 仅当材料是 PPT 导出的 PDF 且带逐条飞入动画（同一页文字重复 4-5 次、 页码对不上）→ 才用下面两个脚本先去重，否则同一张 slide 会被反复出题：

  python "${CLAUDE_SKILL_DIR}/scripts/dedup_pdf.py" --glob "week*/module*.pdf"      # 去动画 build，保留最后一帧
  python "${CLAUDE_SKILL_DIR}/scripts/extract_text.py" --glob "week*/*_dedup.pdf" --out _module_text  # 逐页抽文本，带 PAGE N 标记
  

  这两个脚本依赖 pymupdf（pip install pymupdf）。装不上不要卡住：退回到 pdftotext 或直接 Read PDF 即可，只是页码引用会粗一些。

读完所有要用到的内容再出题——出题只能基于真正读到的文本，source 的页码/章节 必须来自材料本身，绝不臆造。

---

Phase 3 — 出题（写 QUESTIONS 数组）

题目 schema 见模板顶部注释。所有题型共有：id / group / source / type / kind / question / explanation；各题型附加字段：

kind	附加字段	判分
single	options[], correct(索引)	选项 == correct
tf	correct(0/1)；options 可省→默认 正确/False	同单选
multi	options[], correct([索引…])	选中集合 == correct 集合（提交制）
fill	answer(字符串 或 可接受变体数组)	忽略大小写/空格匹配任一变体
flash	back(答案面)	自评：会/不会（不会→进错题本）

文本字段（question/explanation/options/back/label/title）都支持 纯字符串（中英共用）或 {zh, en} 双语对象。题干可含内联 HTML （<code>/<pre>/<strong>），计算题可在解析里用 <pre> 写分步推导。

出题准则：

• 原文题（official）逐字照搬 材料里的例题/习题，source 写明出处页码或章节 （如 "Ch.3 p.42" / "M2 课件 P13"）——这是题库可信度的锚。
• 练习题（practice）同风格自拟，覆盖该单元核心概念，source 写 "练习题"。
• 干扰项要"像真的"：用常见混淆点；并在 explanation 里逐项点破每个错误选项 错在哪，而不只是说正确答案。
• id 以组前缀编号（u1-1、u1-2…），group 必须能在 CONFIG.groups 找到。

✅ 准确性自检（公开给别人用，这一步是信任的命门，必须做）

出完题后，逐题回到原文核对，再交付：

1. 每道 official 题的答案/选项确实出自所标 source；标不出处的题改成 practice 或删掉，绝不挂"官方"标签。
2. 每道题的 correct / answer / back 与材料一致，解析里没有与原文矛盾的断言。
3. 拿不准的题宁可不出。可以把"低置信度"的题单独放一个 group 让用户复核。 对题量较大的课，分单元批次出题 + 批次自检，避免一次性糊弄出几道就收尾。

---

Phase 4 — 填模板，产出单文件 HTML，并实测

1. 复制 ${CLAUDE_SKILL_DIR}/templates/quiz_template.html，替换 5 个占位符：
   • {{TITLE}} — <title> 用的纯文本标题。
   • {{STORAGE_KEY}} — 唯一 localStorage key，建议 "<课程代号>-quiz-v1"； 以后想强制清空所有人进度就把 -vN 递增。
   • {{DEFAULT_LANG}} — "zh" 或 "en"。
   • {{TITLE_JSON}} / {{SUBTITLE_JSON}} — 标题/副标题，写成 "..." 或 {zh:"...", en:"..."}（注意这里是 JS 字面量，不是字符串占位）。
   • {{GROUPS}} — CONFIG.groups 数组项，按顺序： {key:"u1", label:{zh:"第1章",en:"Unit 1"}}, …。
   • {{QUESTIONS}} — Phase 3 的全部题目对象，逗号分隔。
   • 参考 examples/demo.html 的填法（它就是模板填好的成品）。
2. 填完做静态自检（任选其一，别跳过）：
   • 抽出 <script> 用 node --check 验语法（占位符没转义/引号没闭合会在这里暴雷）；
   • 校验：每个 question.group 都能在 CONFIG.groups 找到 key；每个 correct 是合法索引；id 全局唯一。
3. 输出文件放材料同目录，命名 Quiz.html。
4. 用浏览器打开实测（见 [[feedback_verify_visual_output]]：UI 产物先 render-and-read 再说"完成"）。可用 chrome-devtools：覆盖每种用到的题型——答题→判分变色→出解析、 筛选计数、错题本筛选、保存快照→重做、语言切换、导出、刷新后进度仍在。控制台 不能有报错。确认无误再交付。

---

给大众的：怎么用 & 怎么分享

• 用：双击 Quiz.html 用任意浏览器打开即可，纯前端、不联网、不收集数据， 答题进度只存在你自己浏览器的 localStorage。
• 分享：直接把这个 .html 文件发给别人 / 丢网盘；或推到 GitHub Pages / 任意静态托管，发链接即可。每个人的进度互相独立。
• 重置：页面里"重置主进度"按钮，或换浏览器/清缓存即清空。

成品自带功能（模板已实现，无需重写）

单文件零依赖离线、移动端自适应；中英一键切换（记住选择）；5 种题型即时判分 + 解析； 按单元/题型/错题本筛选并显示题数；统计条（已答/正确/错误/正确率）；进度 localStorage 自动保存；错题本快照（把当前错题存成命名集合，单独刷、重做、删除， 与主进度互不干扰）；导出错题为纯文本；键盘快捷键（1-5 选项、Enter 提交/翻面、 ←/→ 翻题）。

适用 / 不适用

• ✅ 选择/多选/判断/填空/记忆卡 自学题库。
• ⚠️ 需要打分计时的"正式考试模式"、随机组卷、服务端记录成绩 → 本模板是纯自学 工具，需另行扩展。
• ❌ 只想要一张压缩复习表 → 用 cheatsheet-generator。