Quiz Mastery

测验大师 (Quiz Mastery)

两大核心能力

能力一：从学习资料出题

1. 用户提供学习资料（.md / .txt / .docx / .pdf / .ppt / .pptx）
2. 调用 generate_from_material.py 获取知识点提取 prompt
3. 将 prompt 发给 LLM，得到知识点 JSON
4. 调用 service.save_knowledge_points() 保存知识点
5. 调用 run_quiz.py 生成出题 prompt
6. 将 prompt 发给 LLM，得到题目 JSON
7. ⭐ 询问用户是否生成网页练习页（见下方"网页练习联动"章节）
   • 用户说要 → 调用 quiz-html skill 生成 HTML 并打开
   • 用户说不用 → 走原流程
8. 逐题展示给用户，收集答案
9. 调用 submit_answers.py 提交评分

能力二：从题目文件练习

1. 用户提供题目文件（.md / .txt / .docx / .pdf / .ppt / .pptx）
2. 调用 import_quiz.py 获取题目解析 prompt
3. 将 prompt 发给 LLM，得到标准化题目 JSON
4. 调用 service.import_questions() 导入题目并创建 session
5. ⭐ 询问用户是否生成网页练习页（见下方"网页练习联动"章节）
   • 用户说要 → 调用 quiz-html skill 生成 HTML 并打开
   • 用户说不用 → 走原流程
6. 逐题展示给用户，收集答案
7. 调用 submit_answers.py 提交评分

何时使用（触发条件）

1. 用户主动要求："出几道题"、"测试一下"、"来个小测"、"练习题"、"考考我"
2. 用户说"复习"、"巩固"、"回顾"：直接触发
3. 基于已有题目文件练习：用户上传题目文件后触发

⚠️ 不处理 study-buddy 的"即时练习"——那条链路由 study-buddy 走外部 exam_take，不调本 skill。

没历史数据时的兜底

当用户说"复习"但 data/user_progress/ 是空的（新用户/没答过题）：

• 不要硬启动复习流程——没数据可复习
• 主动告诉用户："还没有可复习的历史数据，要不要先用一份学习资料出题练一下？"
• 引导用户走"能力一：从学习资料出题"

难度系统

• 首次出题：强制从 L1 开始
• 答对当前难度：升一级（最高 L3）
• 答错当前难度：降一级（最低 L1）

题型分配规则

出题数量

• 默认每次出 3 道题（一次对话展示 3 题，用户一次性回答后统一评分）
• 每轮最多 15 题（用户可要求调整数量）
• 简答题尽量少出，不自动评分（标记为 needs_review，由外部 LLM/人工评判）

薄弱知识点追踪

• 标记为薄弱：累计错误次数 ≥ 3
• 不解除：薄弱知识点只增不减，作为历史档案保留
• 内部数据保存在 data/user_progress/（错误次数、艾宾浩斯阶段等）
• 同步到 USER.md 第 3 节"薄弱知识点"（由本 skill 直接写入，来源=quiz-mastery）： | 知识点 | 错误次数 | 来源 | 备注 |
  • 已有该知识点 → 更新错误次数
  • 未在表中 → 新增一行

遗忘曲线复习机制

基于艾宾浩斯遗忘曲线，按 1天 → 2天 → 4天 → 7天 → 15天 间隔安排复习：

• 答对：review_stage +1（推进到下一个间隔）
• 答错：review_stage 重置为 0（从头开始）
• 复习推荐包含：即将遗忘的知识点 + 最近 3 天薄弱知识点

脚本调用方式

1. 从学习资料提取知识点

python3 scripts/generate_from_material.py <file_path> <document_id>

输出知识点提取 prompt（JSON），将 prompts.system_prompt 和 prompts.user_prompt 发给 LLM。

2. 从题目文件导入题目

python3 scripts/import_quiz.py <file_path> <document_id> <user_id>

输出题目解析 prompt（JSON），将 prompts.system_prompt 和 prompts.user_prompt 发给 LLM。

3. 生成测验

python3 scripts/run_quiz.py <user_id> <document_id>

根据已保存的知识点和用户当前掌握度自动决定难度，输出出题 prompt（JSON）。

4. 提交答案

python3 scripts/submit_answers.py <user_id> <document_id> <session_id> '<answers_json>'

参数说明：

• answers_json：JSON 格式的答案字典，如 {"q_001": "A", "q_002": "True"}

返回评分结果：score、total、accuracy、逐题 results。

出题流程（面向 study-buddy 的调用说明）

1. 确定知识点来源（学习资料 or 已有题目文件）
2. 执行对应的提取/导入流程
3. 调用 run_quiz.py 生成出题 prompt
4. 每次展示 3 道题给用户（一次性展示，编号清晰，不要逐题出），用户一次性回答后再统一评分
5. 收集用户回答（用户可以一次性回复 3 道题的答案）
6. 调用 submit_answers.py 提交评分
7. 将评分结果返回给 study-buddy，由其写入 memory 文件

⚠️ 本 skill 仅写入 USER.md 第 3 节"薄弱知识点"（来源=quiz-mastery）；不写其他分区，也不写 memory/。其他持久化由 study-buddy 统一负责。

数据目录结构

skills/quiz-mastery/data/
├── knowledge_points/     ← 知识点定义（按 document_id）
├── sessions/             ← 测验会话记录
└── user_progress/        ← 用户掌握度数据（含薄弱标记、遗忘曲线）

⭐ 网页练习联动（与 quiz-html 协作）

每次拿到题目 JSON 之后（"能力一"步骤 7、"能力二"步骤 5），都要主动问用户一句：

"题目准备好啦～ 要不要我把它们生成一个网页练习页？你可以在浏览器里慢慢做，错题会自动记下来，还能切换主题、模拟考试 🎯"

用户回应判定

调用 quiz-html 的具体步骤

import json, subprocess, tempfile
from pathlib import Path

# 1. 把已经拿到的题目 JSON 写到临时文件
tmp_dir = Path(tempfile.mkdtemp(prefix="quiz_"))
qjson = tmp_dir / "questions.json"
qjson.write_text(json.dumps(questions, ensure_ascii=False), encoding="utf-8")

# 2. 决定输出路径（推荐放 ~/Desktop）
output = Path.home() / "Desktop" / f"quiz_{title_slug}.html"

# 3. 调脚本
result = subprocess.run([
    "python3",
    str(Path.home() / "Desktop/studybuddy_4.0/skills/quiz-html/scripts/build_quiz_html.py"),
    str(qjson),
    "--title", page_title,        # 如 "📚 物理 · 电学练习"
    "--output", str(output),
    "--open",                     # 生成后自动用浏览器打开
], capture_output=True, text=True)

info = json.loads(result.stdout)  # {"success": true, "output_path": "...", ...}

题目字段补全建议

调用前，最好给每道题补上以下字段（如果出题时没生成）：

• category：一级分类，短词（建议 2-6 字），用于网页顶部分类筛选 chip。
  • ✅ 推荐：物理 / 数学 / 法律 / 历史 / 编程 / 通用
  • ❌ 避免：通用类 / 1.中华人民共和国证券法（1998年12月29日…） 这种长串、含日期/编号/斜杠的写法
  • 如果非要分两级，用 / 分隔且二级也要短：物理 / 电学
• knowledge_point：知识点名（侧边栏分组用，可与 quiz-mastery 的 KP title 一致，不要带层级前缀）
• memory_tip：记忆口诀（可选，K12 学生很需要）

这样网页的分类筛选、侧栏分组、记忆卡片才能发挥作用。

边界

调完 quiz-html 之后，仍然要走 quiz-mastery 的评分流程——网页里的答题状态是给用户自查用的，正式的 mastery 数据要靠 submit_answers.py 写入。两者并行不冲突。