---
name: quiz-mastery
description: 出题、测验、复习、掌握度追踪工具。**用户说"复习"、"巩固"、"回顾"任一关键词时优先触发本 skill**。当用户的请求与"题目/复习"相关时触发：把学习资料/PDF/材料转成题目练习（"给这个 PDF 出几道题"）、导入题目文件做练习（"我有一份题目文件，帮我做"）、复习已学内容（"复习一下昨天的"、"巩固一下"、"回顾下昨天"、"用艾宾浩斯帮我安排"）、遗忘曲线追踪、掌握度评分。**🔴 强制规则**：每次出题/导入题目成功后，**首轮展示题目前必须问一句**"要不要生成网页练习页？"，用户说要 → 调用 quiz-html skill。**不处理**：长期学习项目的进度管理、计划制定（→ study-buddy）。
---

# 测验大师 (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 | 识记 | 基础记忆和理解，考察概念辨认和基本事实 |
| L2 | 理解 | 深层理解，考察概念区分、原理解释和简单应用 |
| L3 | 应用 | 综合运用，考察实际场景应用、分析和问题解决 |

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

## 题型分配规则

| 级别 | 选择题 | 判断题 | 填空题 | 简答题 |
|------|--------|--------|--------|--------|
| L1 | 70% | 30% | - | - |
| L2 | 50% | 20% | 30% | - |
| L3 | 40% | 20% | 20% | 20% |

## 出题数量

- **默认每次出 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. 从学习资料提取知识点

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

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

### 2. 从题目文件导入题目

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

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

### 3. 生成测验

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

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

### 4. 提交答案

```bash
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` |
| "不用 / 不要 / 算了 / 直接做 / 这里做" | ❌ 不要 | 走原对话流程 |
| 没回应 / 不明确 | 默认 ❌ 不要 | 直接走原流程，不强推 |

### 调用 quiz-html 的具体步骤

```python
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 学生很需要）

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

### 边界

| 任务 | 用谁 |
|---|---|
| 出题、提取题目 | 本 skill (quiz-mastery) |
| 评分、掌握度追踪 | 本 skill (quiz-mastery) |
| **题目 → 网页练习页** | **quiz-html** |

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