quiz-drill：知识库 → 选择题 → 刷题 → 薄弱点报告

所有能力在 scripts/quiz_drill.py 里，刷题页是 scripts/page.html。本文件只讲什么时候用、参数怎么定、失败怎么报。

下文 quiz-drill 指 <本 skill 目录>/scripts/quiz_drill.py。脚本带 uv 内联依赖头，uv run 或直接执行都行； 没有 uv 时用 python3 运行，只有读 PDF 需要额外装 pypdf。

模型与密钥

出题和质检走任意 OpenAI 兼容的 chat/completions 接口，按下面的顺序读环境变量：

密钥放在 env 文件里时，设 QUIZ_DRILL_ENV_FILE=<文件路径>，脚本会读它（已有的环境变量优先）。 不要把密钥写进命令行参数、题库目录或任何会提交的文件。

出题模型如果是 reasoning 模型，脚本给了 16000 的 max_tokens，只取正文、丢掉思考过程。

一、出题

quiz-drill build <知识库路径...> --name <题库名> --out <题库目录> [--glob '**/*.md'] [--dry-run]

先 --dry-run：不调模型，只列出会划成哪些知识点、每个出几题。看一眼划分合不合理再出题。

参数怎么定：

• --out：放在知识库所属项目里、不进 Git 的位置（如 <项目>/_work/quiz-drill/；先确认 .gitignore）。题库里有原文摘句，别放进公开仓库。
• --glob：只挑正文文件。讲义仓库常是 '**/deck.html'，笔记库常是 '**/*.md'。不给时收目录下全部 .md/.txt/.html/.pdf，README、更新日志也会被当成材料。
• --split：知识点怎么划。报告按知识点统计，划得太粗就指不出具体哪块弱。
  • auto（默认）：短文件（≤ --max-chars，默认 9000 字符）整份一个知识点；长文件按二、三级标题（HTML 是 h1/h2）切，短于 --min-section（默认 600）的小节并进前一节。
  • always：总按标题切，适合一个文件里塞了很多主题的笔记。
  • never：一个文件一个知识点，适合一题一份的讲义。
  • PDF 没有标题结构，只按长度切块，知识点仍是整份 PDF。
• 模块 = 文件相对输入目录的第一级子目录；只给一个文件时模块就是它的标题。目录名不好读时用 --module-names names.json（{"01-llm-basics": "LLM 基础"}）。
• --title-sep：HTML 的 <title> 带前缀时（如「第 3 讲 · 注意力」），给分隔符取最后一段作知识点名。
• --lang：默认 auto，按原文是否以中文为主定中文或 English；也可以写死。
• --style：补一句出题风格，如「面试官口吻，偏原理、对比和后果」「考试复习，侧重定义和条件」。
• --multi：多选题占比上限，默认 0.2；0 = 只出单选。
• --per-topic：每个知识点出几题，默认按长度 2~10。
• --limit N：只处理前 N 块。首次跑先 --limit 3 试跑，抽两三道题给用户看质量，确认后再全量。

行为：

• 增量：已出过题的块（按文件路径 + 内容哈希）自动跳过；原文改了会当新块重出。本次选项写进 <题库目录>/bank_meta.json，more 会沿用。
• 长任务放后台跑，只看最后几行。每块：出题模型 14 次调用，每道候选题再加 24 次质检调用。

每道题过四关才入库：

1. 结构：4 个选项、题型和正确项数对得上、没有「以上都对」和否定题干、题干不引用「材料/上文」。
2. 长度：四个选项长度相差不超过 30%，正确项不能明显最长。不过关先让质检模型改写到长度接近、意思不变，再复检。
3. 作答：质检模型看完整题作答，必须答对且不认为有歧义。
4. 盲猜（只对单选）：遮住题干、打乱两次，质检模型两次都猜中 = 选项本身漏了答案。

不过关的题带着原因让出题模型重出，最多 4 轮（--rounds）。淘汰记录在 <题库目录>/gen/<块>.json 的 rejected，通过率低时去那里看原因。 常见情况：盲猜是主要淘汰原因，说明干扰项一眼就能排除，这一关该留，不要为了凑数关掉。

二、刷题

quiz-drill serve <题库名或目录> [--port 8765] [--round 20] [--no-open]

放后台运行，把打印出的本机 URL 给用户。端口被占用会自动 +1。

页面：

• 一次一题，选项每次随机打乱。A–D 或 1–4 选择，Enter 提交 / 下一题。
• 答完显示每个选项为什么对或错、考点、原文摘句和出处文件。
• 模式：「智能复习」（错题和到期复习题优先，新题优先挑还没碰过的知识点）、「错题本」、「只出新题」，可限定到某模块或某个知识点。
• 每轮默认 20 题，轮末列出这轮出错的知识点。
• 「这题有问题」会把题拉黑，以后不再出，也不计入统计。

作答记录追加写在 <题库目录>/log.jsonl，拉黑记录在 flags.jsonl，不要手改。

三、报告

quiz-drill report <题库名或目录>     # 写 <题库目录>/report.md，并打印一句话结论

页面「报告」页是同一份统计。给用户讲报告时先说大白话结论：「最该补的是 X、Y、Z」，再给数。两个口径：

• 首答正确率：第一次见到就答对的比例，反映原本会不会。
• 掌握度：最近一次答对的比例，反映复习后的状态。

薄弱知识点 = 至少做过 2 题且掌握度不满，按掌握度、首答正确率从低到高排，并列出还没掌握的考点。 报告还列出还没答对或反复答错的题（含常选的错项），以及还没碰过的知识点。

四、给薄弱点加题

quiz-drill more <题库名或目录> [--weak 5] [--n 4]
quiz-drill more <题库名或目录> --topics "知识点 A,知识点 B" --n 6

默认取报告里最弱的 5 个知识点，每个再出 4 道与已有题考点不重复的新题；也可以用 --topics 直接点名。 加完提醒用户刷新页面。原文文件被移动或改过时会提示先重新 build。

五、其他

• quiz-drill list：列出已登记的题库（登记表在 ~/.local/share/quiz-drill/banks.json）。题库名和目录都能当参数。
• 出题失败会记进 rejected，进度行显示「通过 0/n」；重跑同一条 build 命令只补没出成的块。
• 鉴权失败（401/403）和模型名错（404）不重试，直接报错；先检查上面的环境变量。
• 页面只监听 127.0.0.1，不上传任何内容。界面和报告是中文的。