Initial commit

skills/quiz-html/README.md

@@ -0,0 +1,117 @@
+# quiz-html · 网页题库生成器
+
+把题目数组 → 一个可独立打开的 HTML 练习网页。
+
+## ✨ 功能一览
+
+- 📂 **双重筛选**：分类（学科/子模块） + 学习状态（已掌握/未做/错题）
+- 🎯 **4 种题型**：选择 / 判断 / 填空 / 简答
+- 🤖 **智能答题**：选 ≠ 提交，可反复改；答错给一次重试机会
+- ⌨️ **键盘快捷键**：A/B/C/D · Enter · ← → · Space
+- 📝 **模拟考模式**：选题量 + 限时 + 一次性提交 + 成绩页
+- 🧠 **记忆口诀**：题目带 `memory_tip` 字段会高亮显示
+- 🌓 **主题切换**：明 / 暗双主题，localStorage 记忆
+- 💾 **进度持久化**：浏览器记住每题状态，关掉再开还在
+- 📱 **移动端适配**：手机也能用
+
+## 🚀 快速上手
+
+```bash
+# 1. 准备题目 JSON 文件（数组）
+cat > /tmp/q.json << 'EOF'
+[
+  {"type":"single_choice","prompt":"1+1=?","options":["A. 1","B. 2","C. 3"],"answer":"B",
+   "explanation":"基础运算","category":"数学 / 加减法","level":1}
+]
+EOF
+
+# 2. 生成 HTML
+python3 scripts/build_quiz_html.py /tmp/q.json --title "数学练习" --open
+```
+
+## 📁 目录结构
+
+```
+quiz-html/
+├── SKILL.md                  # skill 描述（给 agent 用）
+├── README.md                 # 本文件（给人看）
+├── skill.yaml                # skill 元数据
+├── scripts/
+│   └── build_quiz_html.py    # 注入脚本
+├── templates/
+│   └── quiz_template.html    # HTML 模板（含 {{占位符}}）
+└── examples/
+    └── demo.html             # 示例：已注入的可直接打开的 demo
+```
+
+## 🔗 与 quiz-mastery 联动
+
+本 skill 不直接出题，专门负责"题目 → 网页"这一步。
+出题/导入请用 `quiz-mastery`。完整链路：
+
+```
+quiz-mastery 出题
+       ↓
+   题目 JSON
+       ↓
+  询问用户："要做成网页吗？"
+       ↓ 用户说要
+   quiz-html  ← 你在这里
+       ↓
+  生成 .html
+       ↓
+ 浏览器打开 → 用户开始练
+```
+
+## 📝 题目字段
+
+| 字段 | 必填 | 类型 | 说明 |
+|---|---|---|---|
+| `type` | ✅ | string | `single_choice` / `true_false` / `fill_blank` / `short_answer` |
+| `prompt` | ✅ | string | 题干 |
+| `options` | 选择题 | array | `["A. xxx", "B. yyy", ...]` |
+| `answer` | ✅ | string | 标准答案 |
+| `explanation` | 推荐 | string | 解析（支持 `**粗体**` `*斜体*` `\` 代码 \``） |
+| `knowledge_point` | 推荐 | string | 知识点名（侧边栏分组用） |
+| `category` | 推荐 | string | 分类路径，建议格式 `"学科 / 子模块"` |
+| `level` | 可选 | int | 难度 1-3 |
+| `memory_tip` | 可选 | string | 记忆口诀，会用橙色卡片高亮 |
+
+## ⌨️ 用户使用快捷键
+
+| 按键 | 作用 |
+|---|---|
+| `A` `B` `C` `D` | 选选项 |
+| `T` `F` | 判断题 |
+| `Enter` | 提交 |
+| `←` `→` | 上一题 / 下一题 |
+| `Space` | 查看答案 |
+| `Ctrl/⌘+Enter` | 模拟考一键交卷 |
+
+## 🛠️ 命令行参数
+
+```
+python3 build_quiz_html.py <questions.json> [options]
+
+  --output, -o    输出 HTML 路径（默认：题目同目录）
+  --title         页面标题
+  --subtitle      副标题（默认自动生成）
+  --id            题库 ID（用于 localStorage 隔离）
+  --open          生成后用浏览器打开
+```
+
+## 🔍 退出码
+
+| 码 | 含义 |
+|---|---|
+| 0 | 成功 |
+| 1 | 参数错误 / 文件不存在 / 模板缺失 |
+| 2 | JSON 解析失败 / 数据格式不合法 |
+
+## 📌 边界
+
+| 任务 | 用谁 |
+|---|---|
+| 出题 / 评分 / 掌握度追踪 | `quiz-mastery` |
+| 长期学习计划 | `study-buddy` |
+| **把题目做成网页让用户在浏览器练** | **`quiz-html` (本 skill)** |