Quiz H5 Generator（题库 → 单文件刷题 H5）
这个技能做什么
输入一份题库（格式不限），输出一个 HTML 文件。双击就能用，手机浏览器/微信里打开就能刷题，断网也能用，不需要服务器、不需要装任何东西。
产物自带这些能力（无需再开发）：
| 能力 | 说明 |
|---|---|
| 5 种题型判分 | 单选、多选、判断点击即判；填空归一化匹配并支持等价表述；简答给参考答案自评 |
| 6 种练习模式 | 顺序 20 题、随机 20 题速测、按主题、错题本、收藏、60 秒快闪 |
| 专项训练 | 按题型集中刷：选择题（点选项即判）、填空题、简答题（看题 → 查看答案，不判分），三个专项各自记进度、互不覆盖，做完一轮自动打乱重开 |
| 语音听题 | 简答题连续朗读「题目 → 答案 → 要点」，自动播下一题，可暂停/切题/调速，用系统 TTS，不联网不花钱 |
| 术语注释 | 内置 150 条英文术语表（ComfyUI/SD/FLUX/AI 通用词），在答案解析区以标签列出「英文 + 中文」，题干保持原文干净 |
| 答对降权 | 选择题累计答对 3 次后出现权重降到 28%，把时间让给没掌握的题；设置里可一键重置 |
| 模拟考试 | 30 题随机卷（12 单选/5 多选/5 判断/5 填空/3 简答），交卷后统一判分、出题型明细 |
| 题卡速记 | 简答题卡片，左右滑动切换，收藏/已掌握影响出现权重 |
| 激励系统 | 段位、14 个非连续型成就、金色徽章、主题水位图、连击加倍 |
| 考前提醒 | 设置考试日期后，每次打开弹「剩几天 + 一句鼓励 + 一道简答题」 |
| 记忆技巧 | 题库里简答题可带一句 记忆技巧：…，会以金色提示块显示在答案下方，语音模式也会一起念 |
| 题库导入 | 页面内可再导入新题库，多题库切换 |
三条铁律
- 先问再动手（见「第 0 步」）。题库文件、应用标题、页脚署名、输出路径，四项都必须先问清楚，不要替用户决定。
- 不改模板结构。
assets/app-template.html是成品引擎，只通过build_quiz.py注入数据。要加功能就改模板并同步更新references/features.md，不要临时手改生成物。 - 必须自检。生成后一定跑
verify_quiz.py，把结论原样告诉用户；不通过就先修，不许直接交付。
工作流
第 0 步：收集信息（重要交互步骤，必须先问）
一次性把下面四问发出去，等用户回答后再继续：
| 要问的 | 为什么必须问 | 缺省建议（仅当用户说"你看着办"） |
|---|---|---|
| 题库文件在哪 | 没有题库就没有产物 | — 必须拿到 |
| 应用标题叫什么 | 显示在首页顶部，也是浏览器标签名 | 「我的刷题本」 |
| 页脚署名写谁 | 会印在页面底部版权行 | 沿用模板默认 |
| 存到哪个路径、叫什么文件名 | 用户要在自己电脑上找得到 | <桌面>/<标题>.html |
顺带确认（可选项，用户没提就用默认）：题库分组名（默认「我的题库」）。
如果用户只是把题库贴在对话里，先落盘成 .md 再走流程，不要凭记忆手写题库。
第 1 步：先解析预览，再生成
python3 scripts/build_quiz.py --input <题库> --out <输出.html> --title "<标题>" --dry-run
把打印出来的「题量 / 题型分布 / 分组 / 主题 / 警告」原样告诉用户，让用户确认没漏题。警告里的题是被跳过的，要问用户是不是格式问题。
第 2 步：生成
python3 scripts/build_quiz.py \
--input <题库> --out <输出.html> \
--title "<标题>" [--author "<署名>"] [--group "<分组>"]
存储键默认按标题自动生成（quiz_<hash>_v1），不同题库自动隔离进度；同一标题重新生成会沿用旧进度，这是有意设计（改题库不丢记录）。
第 3 步：自检
python3 scripts/verify_quiz.py <输出.html> [--expect <题数>]
必须把结论告诉用户：题量、题型分布、脚本语法、是否零外链、能不能直接发布。检查不通过就按提示修题库或重新生成。
第 4 步：交付 + 发布引导
先说明「文件在哪个路径、多少 KB、手机怎么打开」，再按用户情况给一条发布路线（细节见 references/publishing.md）：
| 场景 | 怎么做 |
|---|---|
| 只想自己用 | 微信发给自己 → 在浏览器打开；iPhone 用 Safari「添加到主屏幕」变成全屏 App |
| 想有在线链接、免运维 | 用 WorkBuddy 的「发布为应用」/ sites 技能托管，拿到 https 链接，可发人、可加桌面 |
| 有自己的服务器 | 把 html 传上去，Nginx 指过去即可（references/publishing.md 有完整配置片段） |
| 想长期维护题库 | 保留源 md 文件，改完重跑 build_quiz.py 覆盖输出 |
发布动作由用户决定，不要擅自上传或部署；只在用户明确说要发布时才执行。
命令速查
# 只看解析结果
python3 scripts/build_quiz.py --input bank.md --out out.html --dry-run
# 生成
python3 scripts/build_quiz.py --input bank.md --out ~/Desktop/刷题.html --title "医疗 AI 冲刺" --author "曹琦"
# 自检
python3 scripts/verify_quiz.py ~/Desktop/刷题.html --expect 100
# JSON 题库（已是标准结构）也能直接编
python3 scripts/build_quiz.py --input bank.json --out out.html --title "我的题库"
出问题时
| 现象 | 处理 |
|---|---|
| 一道题都没解析出来 | 打开 references/data-format.md 对照题号/答案写法；让用户把原文前 3 题贴出来看 |
| 题数比原文少 | 看 dry-run 的警告，通常是「答案认不出」「答案超出选项范围」，把那几题改好后重跑 |
| 题型判错（该多选变单选） | 答案写成 ABC 连写，或在题干后加 （多选） / 加一行 <sub>多选题</sub> |
| 简答题进了题卡但内容是空 | 简答题必须有 答案： 后的参考文本，否则会被跳过 |
| 打开是空白 | 跑 verify_quiz.py，多半是脚本语法被破坏；重新用模板生成一次 |
| 听题没声音 | 先确认手机装了中文 TTS（安卓）；iPhone 首次必须手动点播放键；微信内置浏览器支持不稳，改用 Safari |
| 术语块没出现 | 说明这题里没有命中术语表的英文，属正常；要补词就改模板里的 GLOSSARY |
| 专项训练点进去没题 | 题库里没有该题型（比如全是选择题时「填空题专项」会提示没有题目） |
版本记录
| 版本 | 变更 |
|---|---|
| 1.1.0 | 新增专项训练（选择题/填空题/简答题）、简答语音连播、英文术语中文对照（150 条，注释放解析区）、选择题答对 3 次降权 + 重置、专项底部大按钮（60px 圆形 + 胶囊）；题库支持 记忆技巧： 行；build_quiz.py 按题库内容生成 BANK_VER，换题库自动重置旧记录；云同步改为默认关闭（SYNC_ENABLED），单文件版不再依赖后端 |
| 1.0.0 | 首个版本：单文件刷题 H5，5 题型判分、6 种练习模式、模拟考试、题卡速记、徽章激励、考前提醒 |
资源索引
| 文件 | 什么时候读 |
|---|---|
assets/app-template.html |
需要看/改渲染引擎时；不要直接交付这个文件 |
references/data-format.md |
题库解析不对、或要向用户解释「题库该怎么写」 |
references/features.md |
用户问「还能加什么」、或要改交互逻辑 |
references/design-spec.md |
要调配色/字号/间距，保持与现有一致 |
references/publishing.md |
用户要发布，需要具体部署步骤 |
references/qa-checklist.md |
交付前自查，尤其是改过模板之后 |
