118 lines
3.6 KiB
Markdown
Executable File
118 lines
3.6 KiB
Markdown
Executable File
# 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)** |
|