试卷转 HTML + PPTX 讲评课件技能（paper-to-html-and-pptx）
概述
将用户提供的试卷材料（Word / PDF / 图片 / 文本）转换为英语试卷讲评交付物，支持三种形态：
- 讲评版交互 HTML：左侧章节导航 + 右侧五视图面板（解析/翻译/考点/短语/长难句）+ 完形/阅读双栏原文翻译 + 整卷点评/班级分析 + 知识卡片
- 教室演示版 PPTX：封面 → 整卷命题点评 → 班级答题分析 → 每篇时文分析 → 每题讲评页（大字、单列、视觉层次清晰）
- 交互式讲评版 HTML（参考 lingxi 专项练习形式）：左文章右详情面板 + 段落中文翻译 + 考点分布分析 + 变式训练 + 板块语篇分析 + 整卷系统性报告
本技能自带 references/review_template.md 讲评模板与全部生成脚本，完全自包含，不依赖其他 skill。
何时使用
- 用户发来一份试卷文件（docx/pdf/图片），要求转成 HTML 网页、PPTX 课件或两者
- 用户说"把这份试卷做成讲评课件""试卷转网页和PPT""做一份可交互的试卷"
- 用户说"参考专项练习交互版形式 / 点击空白格查看详解 / 段落中文意思 / 考点分布分析 / 变式训练 / 语篇分析"
工作流程
第一步：读取试卷内容
| 输入类型 | 方式 |
|---|---|
| Word（.docx） | python-docx 提取段落与表格；参考 scripts/docx_extract_example.py |
| pdfplumber / PyMuPDF 提取文本 | |
| 图片 | 多模态 OCR 识别 |
| 现成文本 | 直接用 |
第二步：识别题型 + 提取题目
- 题型分类：
choice（选择）/cloze（完形）/reading（阅读）/writing（问答/写作）/ 七选五（choice + passage） - 提取要素：题干、选项（A/B/C/D 或 A-E）、篇章（完形/阅读/七选五的短文）、小题题号
- ⚠️ 提取坑位（已实战踩坑，必守）：
1. 选项跨段：docx 排版常把选项拆成多段（A/B 一段、C/D 一段），提取时遇[A-E].开头的段落并入上一题，而非跳过
2. 题号前缀：选项段形如16. A. celebration B. training，切选项前先去掉行首题号^\d+\.\s*
3. 段落范围限定：提取必须限定题区段落索引范围（如while i < end_idx），否则后续大题的选项段会误追加到上一题，导致单页溢出
4. 答案需补齐：试卷 docx 通常无答案/解析，由 AI 在构造 examData 时补全（答案 + 方法 + 考点 + 命题意图 + 知识卡）
第三步：构造 examData（含 AI 生成内容）
核心字段：
- examMeta：整卷讲评元数据（testAnalysis 命题点评 + classAnalysis 班级分析）
- section：{id, title, type, passage?, passageAnalysis?, questions[]}
- question：{q, a, type, options[{letter,en,zh,isCorrect?}], analysis{answer,method,keyPoint,strategy,structure,keySentence,distractors}, points[], propositionIntent, knowledgeCard[], itemAnalysis?}
AI 生成要求（对标新课标）：
1. 选项补中文释义（options[].zh），正确项标 isCorrect:true
2. analysis：答案 + 解题方法 + 关键考点（新课标表述，如"主谓一致·语法知识运用"）
3. propositionIntent：命题专家意图（考点设计意图，要点式 2 行内）
4. knowledgeCard：考点速查卡（术语 + 释义，2 条）
5. 完形/阅读补 passageAnalysis：theme / passageStructure / phrases（重点短语）/ longSentences（长难句解析）
第四步：生成讲评版 HTML
python scripts/gen_html.py <exam_data.json> [output.html]
第五步：生成教室演示版 PPTX
python scripts/gen_pptx.py <exam_data.json> [output.pptx]
第六步：生成交互式讲评版 HTML（可选）
用户要求"参考 lingxi 交互版形式"时使用：
python scripts/build_interactive_example.py <试卷docx路径> [输出html路径]
生成前需准备三个数据模块（脚本同目录）：
- translations_example.py：P_ZH 各篇章逐段中文翻译
- variants_example.py：POINTS 考点聚类 + VARIANTS 每考点 3 道变式题
- discourse_analysis_example.py：SEC_ANALYSIS 板块语篇分析 + PAPER_REPORT 整卷报告
第七步：校验并交付
- HTML：抽内联 JS 跑
node --check（防空白页） - PPTX：python-pptx 逐页检查元素边界 ≤ 页面高度（7.5"），防溢出
present_files交付 HTML + PPTX
交互式讲评版要点（参考 lingxi 专项练习形式）
- 形式：绿色主题（#1B5E20/#E8F5E9）；左"文章区"（分段英文 + 每段下方紧接原文另起一行灰色中文翻译 + 绿色空白格可点）+ 右"就近详情面板"（题干/选项含中文/答案/解析/干扰项/命题意图/知识卡片/同考点变式 3 道）；顶部考点分布分析区 + 板块导航条；选项点击自测（对绿错红），变式题点击核对答案
- 考点分析：选择题按 keyPoint 聚类（词汇辨析/短语搭配/时态/语法功能词/情景交际/细节定位/主旨标题/推断评价/词义猜测指代/写作手法出处/句意理解/七选五衔接），统计题数 + 题号 + 条形图
- 变式训练：每考点生成 3 道同类变式题，难度分难/中/易（数据在
variants_example.py） - 板块分析卡：每个题型板块顶部附数据分析卡——选择题逐题标考点（标注到具体题号），阅读/完形等篇章板块附语篇分析
- 语篇分析：参考语篇分析理论（Halliday 衔接理论 + 语篇模式理论），六维呈现：语篇体裁 / 语篇模式 / 衔接手段（人称照应/时间链/词汇复现/连接词）/ 语篇结构 / 阅读策略 / 主题意义
- 整卷系统性报告：顶部报告卡含 7 板块概况表（题数/题型/核心考点）+ 难度结构 + 主题与目标覆盖（人与自我/社会/自然）+ 整体结论与讲评建议
- 段落翻译：每段英文下方紧接原文另起一行显示中文（虚线分隔），禁止同段混排
输入输出
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 试卷文件 | docx/pdf/图片/文本 | 是 | 原始试卷 |
| 班级答题数据 | JSON/文本 | 否 | 不提供则 AI 按典型学情生成（标注"可替换"） |
| 输出格式 | string | 否 | html/pptx/both（默认 both） |
| 输出 | 类型 | 说明 |
|---|---|---|
| 讲评版 html | .html | 单文件零依赖交互网页 |
| 交互版 html | .html | 参考 lingxi 形式的单文件交互网页 |
| pptx | .pptx | 教室演示版课件，按题分页 |
资源索引
references/review_template.md：讲评版 HTML 完整模板（含扩展 examData 数据结构说明），gen_html.py读取其中html代码块scripts/gen_html.py：examData JSON → 讲评版 HTMLscripts/gen_pptx.py：examData JSON → 教室演示版 PPTX（python-pptx，教室大字版式）scripts/docx_extract_example.py：docx 试卷提取示例（含选项跨段/题号前缀/题区限定等坑位处理代码）scripts/build_interactive_example.py：交互式讲评 HTML 生成器（v2.1，含模板与渲染逻辑）scripts/translations_example.py：各篇章段落中文翻译数据（P_ZH）scripts/variants_example.py：考点聚类（POINTS）+ 每考点 3 道变式题（VARIANTS）scripts/discourse_analysis_example.py：板块语篇分析（SEC_ANALYSIS）+ 整卷系统性报告（PAPER_REPORT）samples/sample_exam.json：精简样例（选择3 + 完形2 + 阅读2，字段齐全）
环境依赖
- Python 3.13：
python-docx、python-pptx、pdfplumber/PyMuPDF - Node.js：
node --check（校验内联 JS） - 无其他外部服务依赖
已验证范围
- 测试材料：《2025—2026学年（下）八年级适应性练习》英语试题（docx），7 板块 50 题
- 验证结果：选择填空 15 / 完形 10 / 阅读 A·B·C 各 5 / 七选五 5 / 问答 5 全部提取正确；HTML 内联 JS 校验通过；PPTX 57 页无溢出
- 交互版：35 道选择题聚类 12 大考点，每考点 3 道变式共 36 道；6 篇篇章 31 段中文翻译；7 板块分析卡 + 整卷报告就位
- 选项解析：docx 排版（A/B 一段、C/D 一段）跨段选项已实战修复，正确率 100%
