# 出题专家 · 使用手册

> 面向使用者的一步步操作指南。装好插件后，从"想出一张卷子"到"拿到可打印的 Word"只需要四步。
> 安装与配置请看 [README](../README.md)；本手册只讲怎么用。

---

## 全流程一览

```
点「📝 出题」→ 选角色 + 选目录 → 确定通读 → 面板弹勾选表单 → 填参数、确认出卷
     ↓                                                              ↓
  AI 通读你的资料（自动）                              六分身流水线自动跑（值守中）
                                                                    ↓
                                              参照目录收货：看板×2 + 学生版/教师版 MD + Word
```

## 第 0 步 · 准备资料

把本次出题要参考的**教师版 MD 文件**放进一个目录（就是"参照目录"）。

- **只需要教师版**：文件名带「教师版」的才会被读；带「学生版」的直接跳过。
- 文件叫「全解版」「解析版」「原题版」也没关系——AI 打开看一眼，每道题都带解析的就会认定为教师版。
- 每道选用/改编的题都必须能在教师版里找到答案出处，这是压低题目出错率的第一道保险。

## 第 1 步 · 点火：选角色、选目录

打开任意会话，点顶栏的「**📝 出题**」标签：

![顶栏标签](screenshots/tabs.png)

面板打开后：

![启动面板](screenshots/panel-setup.png)

1. **出题专家角色**：下拉选择（高考数学 / 中考数学 / 竞赛……清单可在 设置 → 出题专家 里增删）；
2. **参照目录**：点「**📂 浏览…**」弹出系统目录选择框，选中你的资料目录；也可以手动粘贴路径；
3. **特殊要求**（可不填）：任何额外交代，比如"以 2024 年新课标卷为难度参照"。

点「**确定 · 开始通读**」。

## 第 2 步 · 等 AI 通读（不用盯着）

面板进入等待状态，下方**执行实况**每 3 秒刷新，AI 的每个动作都看得见：

- `🔧 调用工具 exam_start` —— 绑定角色与目录
- `🤖 …` —— AI 汇报读取了哪些文件
- `⛔` —— 如果出错，真实原因直接显示在这里

通读完成后面板**自动弹出勾选表单**，不需要你做任何操作。

## 第 3 步 · 填表单：勾题型、定参数

![勾选表单](screenshots/panel-form.png)

1. **勾选题型**：AI 从你的资料里归纳出的题型全部列成勾选框——勾哪个出哪个，支持「全选 / 清空」；
2. **试卷名称**：必填，会原样成为卷头标题；
3. **难度系数范围**：默认 0.3~0.7，每道题的难度系数必须落在区间内；
4. **试题来源**（必填，三项合计须为 100%）：
   - **网上**：填具体来源（如"网上历年高考真题集"）；
   - **样板试卷**：选「原封不动」或「做了修改」，并补充说明；
   - **原创卷**：选基础（高考真题 / 网上试卷 / 参照卷），并写一段说明；
   - 灰色提示语跟随你改的百分比动态变化；说明没填齐、「确认出卷」按钮不可点；
5. **题型数量与分值结构**：如"选择8×3 + 填空6×3 + 解答4×10"。

一切就绪，点「**✅ 确认出卷**」。

## 第 4 步 · 流水线自动跑，你只管看

确认后面板切换为**流水线实况**，六道工序依次推进：

```
出题员 → 评题员 → 答案员 ‖ 排版员 → 转换员 → 校验员
```

- 每个分身的动作都显示在实况里；评题不通过会**自动打回**，只返工被点名的题；
- **转换员**开跑前会问你有无 Word 样式样本：有就给路径（严格照做），没有就用内置默认版式；
- 全部完成后，到**参照目录**里收货：

| 文件 | 说明 |
|---|---|
| 看板-流程.md / 看板-验收.md | 六分身状态 + 整卷验收结论 |
| （卷名）（学生版）.md / .docx | 无答案，直接可打印 |
| （卷名）（教师版）.md / .docx | 题下全解：每题七个字段（答案/考点/难度系数/易错点/解析/教师注意/来源），各自独立成段 |
| images/ | 试卷插图 |

## 智能减负机制（你不用记，系统自动执行）

- **教师版甄别**：只读带解析的教师版文件，学生版跳过——答案一律有出处；
- **来源弹性止损**：网上搜不到题不死磕——精确检索 → 目录改编 → 原创兜底，逐级降级；实际比例与设定有小幅出入时，AI 会发一条简报说明并继续，验收看板里注明实际构成；
- **成本守护**：配合纪律卫士，无缓存路由跑长流水线时自动拦停，防止 token 失控。

## 常见问题

**Q：面板里出现 ⛔ 怎么办？**
⛔ 后面是真实错误原因。如果是会话历史里有旧错误（比如换过模型、中断过），**新开一个会话**重新点火即可——被污染的旧会话不要再用。

**Q：表单没有弹出来，一直停在"等待"？**
确认你开的是正确的会话（对照实况里的内容），并且参照目录里确实有教师版 MD。超过两分钟无动静，切回「对话」标签看 AI 卡在哪一步。

**Q：想再出一卷？**
面板底部点「再出一卷」，回到第 1 步。建议每张卷子用一个新的会话，互不干扰。

**Q：Word 排版想微调？**
生成物是规整的（字段独立成段、样式统一），直接在 Word 里快速手调即可——每次打印需求不同，系统只负责"规整"，不替代你的最终把关。