技能介绍

这个技能解决什么问题

复习资料通常以 docx 大纲、md 笔记或 pdf 试卷的形式散落在各处，题目、选项、解析混在正文里，没有现成的刷题入口。html-flashcard-builder 把资料转换成一个自包含的 HTML 文件：题目存进 CARDS 数组，解析写在 EXPLANATIONS 查找表里，浏览器打开即可做题，进度通过 localStorage 落盘，不依赖任何后端。

核心能力与工作流

多格式输入：docx 用 python-docx 提取文本，md/txt 直接读取，也可以从对话文本中抽取知识点；多个文件会分别处理再合并
四种题型：选择题、判断题、填空题、简答题，统一用对象结构描述，简答题背面直接放参考答案
键盘优先的交互：空格 翻转或进入下一题，j/k 或方向键翻页，选择题按 A–D、判断题按 1/2 在正面直接作答；鼠标点击只是可选项
筛选与模拟测试：按章节过滤、标记「已掌握/待巩固」、汇总错题；若资料包含完整试卷，可构建 EXAM_A/EXAM_B 进入模拟测试模式

生成流程分六步：提取内容 → 按题型和章节结构化 → 为选择/判断/填空题写解析 → 按 reference.md 模板生成单文件 HTML（深色主题、3D 翻转动画、渲染引擎）→ 可选模拟测试 → 验证输出。验证阶段会用 node -e "new Function(scriptContent)" 检查 JS 语法、核对题目计数、扫描引号冲突。

实现时的注意点

引号冲突是最高频错误：JS 字符串用双引号定界时，题干里的中文引号（""）会导致语法错误，生成后必须用正则扫描并替换
answeredCards 状态机：flipCard() 翻转到背面时要把当前索引加入集合，这是填空题、简答题这类无键盘作答机制的题型也能纯键盘操作的关键；切换模式或章节时要重置集合
realIdx 计算方式不同：常规模式用 CARDS.indexOf(card)，考试模式题目不在 CARDS 中，需改用 currentIndex
持久化时机：saveProgress() 要在翻页、切模式、切章节时调用；恢复位置后 filterCards(true) 需要传 keepIndex，否则题号会被重置