mantle-ai-trader/skills/quiz-html/README.md

quiz-html · 网页题库生成器

把题目数组 → 一个可独立打开的 HTML 练习网页。

✨ 功能一览

• 📂 双重筛选：分类（学科/子模块） + 学习状态（已掌握/未做/错题）
• 🎯 4 种题型：选择 / 判断 / 填空 / 简答
• 🤖 智能答题：选 ≠ 提交，可反复改；答错给一次重试机会
• ⌨️ 键盘快捷键：A/B/C/D · Enter · ← → · Space
• 📝 模拟考模式：选题量 + 限时 + 一次性提交 + 成绩页
• 🧠 记忆口诀：题目带 memory_tip 字段会高亮显示
• 🌓 主题切换：明 / 暗双主题，localStorage 记忆
• 💾 进度持久化：浏览器记住每题状态，关掉再开还在
• 📱 移动端适配：手机也能用

🚀 快速上手

# 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)