试卷转互动讲题课件（paper-to-lecture-html）

把一份试卷变成一个单文件互动讲题课件 HTML：双开即用、可离线、适合教室一体机。v1.2 起自带试卷解析能力（MinerU）；v1.3 起支持题目可视化：老师确认勾选后，按题型路由到 edu-* 可视化技能族生成交互面板，折叠挂载进课件（协议见 references/visual-embed-protocol.md）。装有 exam-to-courseware 可额外产出 PPTX 讲评版（互补，非必需）。

使用前置（分享/部署本技能前必读）

• 本技能自带 PDF/docx→Markdown 解析（v1.2 起，v1.3.1 起 docx 亦统一走 MinerU），两条路径任选：
• 路径 A · MinerU 云端 API 自动解析：需要 API Token（见 Stage 0），一条命令跑完解析；
• 路径 B · MinerU App 手动解析：老师用 MinerU 桌面版/网页版导出产物（full.md + images/），直接交给本技能后续处理。
  两条路径的产物形态相同，进入 Stage 2 后完全一致。不再需要安装 exam-to-courseware 才能解析 PDF。
• 可视化能力（v1.3 引入，v1.4 起按需增强，可选）：由随包附带的 6 个 edu- 子技能提供（本技能目录下的 edu-solid-geometry/、edu-analytic-geometry/、edu-function-plot/、edu-chem-reaction/、edu-physics-mechanics/、edu-geo-earth/，各自 SKILL.md 为自包含工作流）。执行 Stage 3.5 时按路径读取对应子目录的 SKILL.md 并照其工作流执行（读文件即可驱动，无需按名安装）；若运行环境中恰好也安装了同名独立技能，以独立安装版优先。子目录缺失时本技能全部主流程照常工作——Stage 3 照常先交付基线版课件，只是可视化建议清单会提示"未检测到对应子技能"。edu- 的 kernel 依赖 sympy（python -c "import sympy" 检查，缺失先征得老师同意再安装）；路径 A 的解析脚本依赖 httpx（python -c "import httpx" 检查）。
• 材料质量决定成品上限：有「解析版」试卷（每题带【答案】【分析】【详解】）时质量最高、AI 推断几乎为零；只有「试卷+答案速查」时，AI 需自行推断解析，对应题自动打"AI生成·待核对"徽章，老师人工核对量会明显增加。生成前应向老师说明这一预期，别让成品质量落差来得突然。

产出形态（学生/老师看到什么）

• 每个语篇/题组一个标签页；左栏材料精读（段落、配图、术语气泡、可选音频/译文），右栏试题演练（点击选项即时判分 + 正确率进度条 + 逐题精讲四件套：答案→材料定位→解题思路→干扰项排雷→考点）。
• "定位材料"按钮：右栏点击 → 左栏对应句黄色高亮闪烁 + 滚动居中（锚点预埋在材料 HTML 里）。
• 完形/语法填空/方程式配平：材料中渲染为带题号挖空，讲题时答案"填入"闪烁。
• 解答题：分步解析按钮逐步揭示解题步骤；主观题：踩分点对照逐条点亮模拟评分。
• 顶栏：字号缩放（存 localStorage）、答案速查、对照译文、素材积累、方法点拨、导出 JSON；数学公式走 KaTeX（CDN，离线降级显示原文）。

工作流

Stage 0：MinerU Token 配置（仅"路径 A · API 解析"需要）

1. 检查 Token 是否已有（按优先级）：环境变量 MINERU_API_TOKEN → 本技能 scripts/mineru_token.txt → 当前工作目录 mineru_token.txt。
2. 若都没有，用这段话引导老师（不索要明文写进任何共享文档）：
   > "打开 mineru.net 并登录 → 右上角头像进入「API 管理页」→ 创建 API Token → 复制发给我。我只写入你本地的配置文件，不写进任何脚本或交付物；用完后你可以随时在官网重置。"
3. 拿到 Token 后写入 mineru_token.txt（纯文本首行；该文件不得提交 git、不得进入任何交付物）。
4. 验证：直接跑 Stage 1 路径 A 即可；若报 A0202/A0211 说明 Token 无效或过期，请老师重新创建。
5. 依赖：pip install httpx pypdf（一次性）。

Stage 1：获取试卷文本（两条路径，产物形态相同）

路径 A · MinerU 云端 API 自动解析（试卷为 PDF/docx 时首选）

1. 多段 PDF 先合并：pypdf.PdfWriter 顺序 append；docx 直接交给 mineru_parse.py，不要在本地拆读（docx 由服务端自动转 PDF 解析，2026-09 实测直传成功，产物形态与 PDF 一致）。
2. 运行：python <本技能>/scripts/mineru_parse.py <试卷.pdf> <输出目录>。
3. 产物：<输出目录>/output/result/full.md（LaTeX 公式）+ images/（图形资产）。整理为后续输入目录：<工程目录>/<试卷名>/full.md + images/。
4. API 契约要点（2026-09 实测，勿用旧文档）：POST /api/v4/file-urls/batch（Authorization: Bearer、model_version:"vlm"、enable_formula:true）→ PUT 预签名地址直传 PDF（绝不能带 Content-Type 或任何额外 header，签名不含它，加了必 403；直连 OSS 不走代理） → 上传后系统自动触发解析，无需再调 /extract/task/batch（传 batch_id 报 -10002）→ 轮询 GET /api/v4/extract-results/batch/{batch_id}（不是 /extract/task/batch/{id}），extract_result 是数组，done 后取 full_zip_url 下载解压。状态机：waiting-file → pending → running → converting → done / failed。失败不重试不静默，直接报错。 每账号每日 1000 页高优先级额度；29 页卷约 2~10 分钟。

路径 B · MinerU App/网页手动解析（老师已有产物时直接用）

1. 老师用 MinerU 桌面版/网页版上传试卷 PDF（开启公式/表格识别），解析完成后导出 Markdown 结果。
2. 把产物整理为：<工程目录>/<试卷名>/full.md + images/<图>（App 导出的 zip 解压通常即此形态；若 md 与图片平铺，自建 images/ 把图归入并把 md 里的引用改为 images/xxx）。
3. AI 收下后先自查产物结构（缺图/引用错位在此步补齐），再进 Stage 2。
4. 路径 B 不需要 Token、不需要联网（产物已在老师手里），与路径 A 的后续完全一致。

路径 C · 纯文字稿/已有结构化材料：仅限纯文字稿（txt、直接粘贴）或老师已有的结构化材料（答案册、解析文档）直接读取作为第一来源。docx 不走本路径——docx 统一交路径 A（MinerU）解析，保证公式与图片走同一条 OCR 管线；docx 中 MathType/OLE 公式对象可能被 vlm 漏读，解析后按下方质检红线核对，缺损处回 docx 原文核对补齐。

质检红线（A/B 共用）：解析完成后抽 2~3 题核对公式是否完整（如"中位数为（）"必须有数据、选项必须是 LaTeX 而非空白）。若大面积丢公式，停止并报告，不带病进入 Stage 2。生成 HTML 后追加一道终检：全片扫描正文，出现 \frac/\triangle/\left 等裸 LaTeX 命令（未渲染成公式）即为公式退化，必须清零后才能交付。

Stage 2：结构化生成 data.json（核心工作量）

1. 读 references/data-schema.md（字段定义）与 references/per-subject-guides.md（目标学科细则）；先浏览 references/golden-sample/README.md 及对应学科完整样例（english 覆盖语篇阅读/七选五/完形与语法填空挖空/两篇作文/段落译文；math 覆盖解答题一题一节、steps 分步、题干图/解析图分离），按样例的结构与解析密度生成 lecture_data.json。
2. 逐题生成精讲四件套：answer / point / loc（埋锚点）/ thought / distractors；解答题写 steps（每步标注用了哪个条件）；主观题写 score_points（教材规范表述）。
3. 同时执行 references/accuracy-guard.md 的第一~三道关（原文优先 → 版本锚定 → 术语红线）；第四关（对抗找茬）在 Stage 2.5 由独立审查代理执行，生成方不自审。其中第二关（教材版本）需先问老师一次：教材版本 + 新/旧课标；未答则按统编/人教新课标处理并声明假设。
4. 疑难处理：
   - 原卷无解析的题：AI 生成并强制 review: true；
   - 图片：MinerU 的 images/ 相对路径直接引用，最后 --embed-images 内嵌；
   - 英语听力音频：整卷一段 audio（base64 内嵌），每题 segStart/segEnd 秒区间裁剪；无音频时留空。
5. 生成 lecture_preview.md（题号、答案、考点、思路一句话、踩分点、全部"AI 推断"标记）。

Stage 2.5：独立对抗审查（他检，必做，禁止自我审查）

1. 另起一个子代理当「找茬方」：生成方不得自审。审查代理先读 references/accuracy-guard.md 第四关清单与 references/per-subject-guides.md，再运行：
   bash python <本技能>/scripts/check_data.py <数据包>.json --dump-answers [--source full.md]
--dump-answers 出全卷答案清单逐题回比 full.md【答案】；脚本报 [ERROR] 必须清零，[WARN] 逐条裁决。
2. 审查重点（脚本查不了的部分靠人眼）：解析完整度是否还原推导链/踩分点、图归属是否对得上 full.md 上下文、score_points 教材表述是否逐字、vocab.term 是否真在材料里。
3. 发现问题由审查代理直接修复（python 脚本改 JSON，保护转义），修完重跑 check_data 到 ERROR=0。
4. 未通过 Stage 2.5 不得进入 Stage 3。

Stage 3：基线组装 + 人工核对清单（v1.4 起：先出课件，再确认）

1. 先组装「无可视化基线版」课件（Stage 2.5 通过后立即执行，不让老师干等）：

python <本技能>/scripts/assemble.py <输出目录>/lecture_data.json <输出目录>/讲题课件-<卷名>.html --embed-images

> assemble 自带 schema 校验（缺 title/sections/题干会报错退出）；图片转 base64 单文件交付；q.visual.src 指向的 embed 面板自动 base64 内嵌（全卷无 visual 时行为与 v1.2 一致）。

2. 同时生成并呈现 lecture_preview.md，两部分内容缺一不可：
   - 老师重点核对项：题目切分完整性、答案正误、AI 推断修订处、原卷疑似错误（review 标记）、OCR 恢复处——逐条列出让老师逐项裁决；
   - 《可视化建议清单》：按 visual-embed-protocol.md §4 格式列出可视化候选题，每条含：题号、题型识别、建议 skill 与交互形态、价值判断（原卷图为何讲不清）、两段耗时（按协议 §4 校准公式估算：批次固定开销 5~8 分钟计入首题 + 每题边际按"内置拓扑 3~5 分钟 / 自定义拓扑 6~10 分钟"区分；核对耗时按风险 低3/中5/高8-10 分钟）、准确风险（高/中/低 + 核对要点）、默认建议（推荐生成/可选/不建议）。路由对照表见协议 §5：立体几何→edu-solid-geometry、圆锥曲线→edu-analytic-geometry、函数与导数→edu-function-plot、反应微观→edu-chem-reaction、受力分析→edu-physics-mechanics、地球运动→edu-geo-earth；三视图/统计图表/实验装置图不路由（原卷图已够用）。
3. 老师核对修正后回写 data.json 并重新组装基线版。勾选可视化 → 进 Stage 3.5；不勾选则基线版即最终版（五道关的第五关仍以老师"确认/修正"为准）。

Stage 3.5：可视化生成（v1.3 引入；v1.4 起为「按需增强 → 重组装新版」）

仅处理老师勾选的题。子技能调用方式（随包版）：读取 <本技能>/edu-<学科>/SKILL.md（自包含工作流），其 kernel/模板均以相对本子目录的路径引用，按其指引执行即可；若运行环境装有同名独立技能则优先用独立版。

1. 对每个勾选题：抽取题目要素为该 skill 的 spec → 调用其 kernel 精确计算（禁止心算）→ render_html(data, out, embed=True) 产出 embed 面板，写入 <输出目录>/visuals/q<题号>.html。
2. 三方一致断言：kernel 答案 == 课件题面/解析答案 == embed 页展示值；不一致时以原卷解析为准回改 spec 重算，仍不一致则该题降级为不生成并告知老师。
3. 在 data.json 对应题写入 q.visual（type/skill/src/label/caption，见 data-schema.md）；同时执行 accuracy-guard.md 的「可视化核对关」。
4. 运行 check_data.py：visual 字段非法或 embed 文件缺失为 [ERROR]，必须清零。
5. 重新组装产出新版课件（文件名加版本后缀，如 讲题课件-<卷名>-v2.html；不覆盖基线版，老师可对比取舍）。

Stage 4：交付简报

• 交付 讲题课件.html（基线版，勾选了可视化则另有 -v2 新版）+ lecture_data.json。
• 简报五道关执行结果（检查 N 题、修复 X 处、review 标记 Y 题）与可视化结果（建议 M 题、勾选 K 题、生成 K' 题、降级 D 题）。

学科适配速查

> 逐科完整细则（页面组织/各题型要点/内容红线/实测踩坑）见 references/per-subject-guides.md，下表只作快速定位。

> 生物等"填空大题"学科：每道非选择题小问按题型策略表决策——答案开放/需完整解析 → 用 score_points（踩分点对照，不机判）；答案封闭可机判 → 用 answers+thought（输入判分）。见 data-schema.md「判分与完整解析二选一的决策」。别给所有填空无差别加 score_points（会全部失去输入判分）。

课堂规律硬性规则（生成与审查时逐条核对）

1. 一题一讲：解答题/实验/计算/流程/材料分析题每道大题独立一个 section（标签页），老师按题推进课堂；禁止多道大题合并一个 section。
2. 图随其文：题干图挂 q.images，原卷【详解】/【分析】内的解析图挂 q.solution_images（渲染在精讲展开区），逐图对照 full.md 判断归属，禁止解析图混入题干。题干图数量 = 选项数量且选项为纯文字时，引擎自动渲染成带 A/B/C/D 标签的选项图卡片。
3. 解析完整：steps / thought / score_points 必须完整还原原卷【详解】/【解析】的推导链与踩分点（steps 可拆 4~10 步），禁止一两句话带过；原卷多解法取主解法分步、其余并入 thought。
4. 界面结构：标签为左侧竖向目录（不遮内容）；无有效材料的题组自动单栏满宽；短"题头"段落自动并入右栏说明条；配图统一缩略图条 + 灯箱（地理 240px、历史/政治/生物 220px、化学 200px、数学/物理 190px、语文/英语 170px）。
5. 可视化非侵入（v1.3）：可视化面板只挂 q.visual 字段，默认折叠一行；未勾选不生成、不写字段；embed 面板经 iframe 隔离，出错只影响本面板；全卷零 visual 时课件与 v1.2 行为一致。可视化是讲题的辅助，禁止让它替代 steps/解析文本。

学科话语体系（引擎已内置，由 subject 字段驱动）：界面文案随学科切换——英语/语文"定位原文·定位句"，数学/理综"定位条件·关键条件"，政治"定位材料"，历史"定位史料"，地理"定位图示"；左栏标题、素材按钮同步切换（数学"公式·结论"、英语"词汇积累"等），可用 data.labels 覆盖。定位按钮只在预埋锚点/挖空时渲染：数学选择/填空题干在右栏、无锚点即无定位按钮，不出现学科错位的话术。

实战高频返工点（v1.0 沉淀，生成与找茬时优先自查）

1. 公式乱码：答案类字段的裸 LaTeX 不带 $ 定界符 → answer 可裸写（引擎 texify 自动包裹），但 thought/steps/explanation/loc 等正文字段必须自带 $...$；JSON 内反斜杠要 \\ 转义，$ 个数必须成对。
2. 解析图错挂题干：full.md 里【详解】之后的图一律进 q.solution_images，不是 q.images。--embed-images 已覆盖 solution_images（v1.0 修复，历史上曾漏内嵌导致单文件解析图死链）；引用文件必须真实存在、相对 JSON 所在目录可解析。
3. 多道大题挤一节：解答/实验/计算/流程/材料题按「一题一节」拆 section（见上），这是课堂节奏硬需求。
4. 解析简略：steps 必须完整还原推导链（4~10 步），不是结论摘要；原卷【解析】里的推理过程、数值代入、踩分表述都要进 steps/thought/score_points。
5. 填空 vs 踩分点二选一：加 score_points 就失去输入判分（见学科表下注释）。
6. 选项图顺序：q.images 数=选项数且选项纯文字时自动配对 A/B/C/D；顺序不同必须给 imageLabels，否则图文错位。
7. 无锚点不出定位按钮：选择/填空题组（题干即题面）别在材料里画蛇添足埋锚点；锚点文字必须逐字取自材料。
8. JSON 双引号：正文引语用中文引号「」“”或转义，未转义 ASCII 双引号会断 JSON。

深度交互（受力动画、图上热点标注、音频进度滑条）为 v2 规划；v1.0 已覆盖：选项图卡片、解析图/题干图分离、左侧目录、单栏自适应、学科差异化图片高度、逐段译文折叠。

交付规范

• 提醒老师：带"AI生成·待核对"徽章的题上课前务必人工核对；解析质量以原卷解析为最高优先。
• 不修改/不删除老师的原始试卷文件；所有产物写入独立输出目录。
• Token 安全（Stage 0 路径 A）：只写本地配置文件 mineru_token.txt，不入脚本、不入文档、不入任何交付物；不提交 git。

版本

当前 v1.4.1（完整变更见 CHANGELOG.md）。v1.2 起自带 MinerU 解析管线；v1.3 起支持题目可视化；v1.4 起流程改为「基线先行」：Stage 3 先组装无可视化基线版课件并随附 lecture_preview.md（老师重点核对项 + 可视化建议清单），Stage 3.5 按老师勾选生成 embed 面板后重组装出新版课件（-v2），不覆盖基线版。同版修复：edu-solid-geometry / edu-physics-mechanics embed 模板全屏后控制条消失（全屏对象由 #canvas-container 改为根元素）。v1.4.1 新增可视化耗时估算校准公式（协议 §4：批次固定开销 5~8 分钟计入首题 + 每题边际，据实测 16 分钟/2 题校准）。引擎/脚本/文档同步演进，升级任一文件后须更新 CHANGELOG 与版本号：SKILL.md frontmatter、data-schema.md 标题、assemble.py 与 check_data.py 头部注释。

已知边界

• 路径 A（API 解析）依赖网络与 MinerU 账号额度，离线环境用路径 B（App 手动解析产物）。
• model_version:"vlm" 对扫描件/手写体效果更好；纯电子版 PDF 可去掉该字段用默认 pipeline。
• 可视化面板内的 3D/公式库（three.js/KaTeX/MathJax）依赖 CDN，首开需联网一次让浏览器缓存；纯离线打开时可视化面板可能空白（主课件其余功能不受影响）。未安装对应 edu-* 技能或其 kernel 依赖 sympy 未装时，对应题的可视化自动降级为不生成。
• 图上热点标注（地理等值线、化学装置图、生物图解的点击放大）、受力动画、音频进度滑条尚未实现，v2 规划；受力分析已有静态矢量重绘（edu-physics-mechanics），动画形态仍属 v2。
• KaTeX 依赖 CDN；纯离线环境公式显示为 $...$ 原文（不影响其余功能）。离线一体化交付时，可提示老师首次联网打开一次让浏览器缓存。