Course Review Guide

课程复习文档生成器

核心目标

生成一份基础薄弱的学生仅靠本文档就能高效复习的HTML复习指南。关键不是"列出知识点"，而是讲明白、配好图、推导透、能自测。

🔴 API兼容性（最重要——任何内容读取前必读）

直接读取PDF/PPTX/DOCX原始文件会触发API错误（invalid value: document）。这些格式不是API支持的内容类型。

唯一正确流程：

1. 先运行 extract_course_materials.py 提取文本到 extracted_text/、图片到 extracted_images/
2. 只读取提取后的 .txt 文件和单个 .png/.jpg 图片文件
3. 永远不要直接读取原始课件文件

执行流程

7个Phase（Phase 0 + Phase 1-6），按顺序执行。每个Phase有进入下一Phase前的质量门。

---

Phase 0：上下文模式检测

0.1 询问用户模型信息

向用户提问： > "请告诉我你当前使用的模型名称和上下文窗口大小（例如：Claude Opus 4 — 200k、Gemini 2.5 Pro — 1M、GPT-4o — 128k）"

0.2 判定运行模式

根据用户回答的上下文窗口大小，确定运行模式：

| 上下文大小 | 模式标记 | 模式名称 | 说明 | |-----------|---------|---------|------| | > 200k tokens | [CTX_MODE: STANDARD] | 🟢 标准模式 | 完整流程，无优化限制 | | ≤ 200k tokens | [CTX_MODE: COMPACT] | 🟡 精简模式 | 启用三项优化策略 |

0.3 模式确认

向用户确认：

• 标准模式："🟢 标准模式已启用，将使用完整流程。"
• 精简模式："🟡 精简模式已启用，将启用分批读取、主动压缩和分阶段检查点策略。"

> 📦 精简模式（≤200k）核心原则： > 后续所有 Phase 中标注 📦 精简模式 的指令块为必须执行的操作。标准模式（>200k）跳过这些指令块。

✅ Phase 0 质量门

• [ ] 已确认用户使用的模型和上下文大小
• [ ] 已判定并确认运行模式（标准/精简）

---

Phase 1：信息收集与范围确认

1.1 判断运行模式

检查课件目录是否存在 exam-scope.json：

• 存在 → 自主模式：从配置文件读取所有参数，跳过用户询问
• 不存在 → 交互式模式：必须逐项询问用户

1.2 交互式模式：自动发现课程资料

1.2.1 扫描课程资料文件夹

首先，使用 Bash("ls 课程资料/") 或 Glob("课程资料/*/") 扫描 课程资料/ 目录：

• 有子文件夹 → 列出所有子文件夹，请用户选择要处理的课程：

> "检测到以下课程资料文件夹： > 1. 课程资料/数字信号处理/ > 2. 课程资料/线性代数/ > 3. 课程资料/电路分析/ > > 请选择要处理的课程（输入序号或课程名）"

• 目录为空或不存在 → 提示用户：

> "未检测到课程资料。请将课程课件文件夹放入 课程资料/ 目录中。例如： > `` > 课程资料/ > └── 你的课程名/ > ├── 第1章.pdf > ├── 第2章.pptx > └── ... > `` > 放置完成后请告诉我，我将继续。"

• 用户选定后：
• 课件目录 = 课程资料/
• 输出根目录 = 复习文档输出/
• 提取文本目录 = 复习文档输出//extracted_text/
• 提取图片目录 = 复习文档输出//extracted_images/

1.2.2 确认信息

逐项向用户确认（除非用户说"全部使用默认值"）：

1. 课件目录路径（已自动填充为 课程资料//）
2. 考试范围：哪些章节考、哪些不考
3. 课程全称（中/英文）和授课教师
4. 参考教材（书名、作者、版本）
5. 考试形式（闭卷/开卷/半开卷）
6. 授课语言（中文/英文/双语）
7. 输出文件名（默认：复习文档输出//_复习指南.html）
8. 是否需要押题文档：是/否，以及题型分布（选择/填空/简答/计算的比例）

1.3 自主模式：读取配置

从 exam-scope.json 读取所有参数。如文件不存在，按以下优先级推断：

1. 扫描课程资料：扫描 课程资料/ 目录，选择第一个包含课件文件（PDF/PPTX/DOCX）的子文件夹
2. 从课件文件名推断：提取章节编号和主题
3. 所有推断值标注 [自动推断]

自动推断的输出路径：复习文档输出//。

✅ Phase 1 质量门

• [ ] 考试范围明确（哪些章节考、哪些不考）
• [ ] 课程基本信息齐全
• [ ] 押题需求已确认（如适用）

---

Phase 2：课件内容提取与深度理解

2.1 运行提取脚本

# 推荐（多模态模型）——含整页渲染，理解版式最佳
python extract_course_materials.py --course-dir "课程资料/" --output-dir "复习文档输出/" --render-pages

# 轻量版——仅文本+图片
python extract_course_materials.py --course-dir "课程资料/" --output-dir "复习文档输出/"

提取结果将输出到 复习文档输出//extracted_text/ 和 复习文档输出//extracted_images/。

2.2 智能图片-章节匹配

运行 match_images.py 对提取的图片进行智能分类和章节归属推断：

# 基础分析：基于文本上下文自动分类图片
python match_images.py --text-dir "复习文档输出//extracted_text" --image-dir "复习文档输出//extracted_images"

# 交互式确认模式（推荐）：逐张确认图片的章节归属
python match_images.py --text-dir "复习文档输出//extracted_text" --image-dir "复习文档输出//extracted_images" --interactive

# 指定输出文件供后续HTML生成使用
python match_images.py --text-dir "复习文档输出//extracted_text" --image-dir "复习文档输出//extracted_images" -o image_mapping.json

该脚本自动完成：

• 解析所有 [图片: xxx.png] 标记，提取上下文
• 将图片分为6类（示意图、数据图表、公式推导、例题配图、对比分析、物理/结构模型）
• 推断每张图片所属章节，生成 image_mapping.json
• --interactive 模式允许逐张确认和手动修正

在生成HTML时，参考 image_mapping.json 按章节嵌入图片，优先使用高置信度匹配的图片。

2.3 读取并理解全部内容

逐一读取 extracted_text/ 下所有 .txt 文件。对于长课件（>2000行），分段读取。

> 📦 精简模式（≤200k）— 分批读取策略： > 不要一次性读取所有提取文本。改为： > 1. 先 ls extracted_text/ 获取文件列表，建立"文件名→章节"映射 > 2. 按章节顺序，每次只读取 1-2 个文件 > 3. 读完每个文件后，立即提取核心知识点并记录精简摘要（每章≤200字），包含：章节标题、核心公式列表、关键概念列表、图片标记位置 > 4. 后续章节处理时，仅参考摘要而非原文 > 5. 每读完 3 个章节文件后，执行一次上下文压缩（见下方压缩检查点）

2.4 处理纯图片课件（如扫描版PDF）

如提取脚本报告某文件为纯图片型，逐张读取 extracted_images/ 中的图片进行视觉识别——每次只传一张图片。

🔴 2.5 图片内容视觉识别与交叉验证（强制执行，不可跳过）

> ⚠️ 这是整个生成流程中最容易被跳过、但后果最严重的步骤。 跳过此步骤导致的问题：课件中的渐变装饰条、幻灯片分隔符被当作"原理图"嵌入HTML，标题与实际图片内容完全不符（如将抽象原理示意图标注为"实物外观照片"、将章节标题页当作"完整流程图"），学生无法通过图片理解概念。

在将任何图片写入HTML之前，必须完成以下三项操作：

第一步：批量尺寸筛查（程序化，约30秒）

提取所有待嵌入图片，用Python/PIL批量检查每张图的尺寸和宽高比：

from PIL import Image
img = Image.open('图片路径')
w, h = img.size
# 装饰性元素特征：宽高比>4、高度 4) or (h ` 文本框替代 |
| 图片内容与页面文字主题不一致 | ❌ 错配 | 删除或寻找该课件同页面的其他图片替代 |
| 图片内容正确但标题描述不准确 | ⚠️ 标题不准 | 修改 figcaption 以准确描述实际图片内容 |

**判例参考**（常见错误模式，必须警惕——以下用泛化术语描述，适用于任何学科）：

- 幻灯片背景渐变条（宽高比极大、高度仅1px）≠ 学科内容原理图
- 抽象的工作原理/机制示意图 ≠ "实物外观照片"（前者是线条/框图，后者是摄影图像）
- 原理步骤序列图 ≠ "设备实物"（序列图展示的是逻辑过程，不是物理外观）
- 实际设备/场景的实物照片 ≠ "过程流程图"（实物照片展示的是最终成品，不是设计步骤）
- 只写了章节标题文字的标题页/分隔页 ≠ "完整的流程图"（标题页仅用于分隔幻灯片章节）

**每完成一批图片验证后，输出验证报告**（写在上下文中即可，不需要文件）：

图片验证报告 (X/Y 通过) ✅ 匹配: 图1.2([学科概念A示意图]), 图2.3([学科概念B结构图])... ❌ 装饰: [文件名](渐变条), [文件名](分隔符)... ⚠️ 标题修正: 图X.X 原标题"[不准确的描述]"→修正为"[准确描述]"

### 🔴 2.6 深度理解（生成前必须完成）

读完所有内容后，回答以下问题（不需要输出给用户，但必须在上下文中形成清晰答案）：

1. 这门课的**核心主线**是什么？（一句话概括从第一章到最后一章的逻辑链）
2. 哪些概念是**基石**？（后续章节依赖的基础概念）
3. 每章**必考的核心公式/定理**是哪些？
4. 学生在哪些地方**最容易混淆**？（至少列出3对易混淆概念）
5. 课件中哪些**推导步骤被省略**了？（列出需要补全的推导）
6. 课件中有哪些**关键图片**？（浏览 `extracted_images/`，标记每张重要图片属于哪个概念）

### 2.7 图表格式选择指南

在进入 Phase 4 生成 HTML 之前，根据课程内容类型规划图表格式。根据不同内容选择合适的表达方式：

| 内容类型 | 首选格式 | 示例场景 |
|---------|---------|---------|
| 概念层级/分类体系 | `mermaid graph TD` | 学科知识分类树、定理体系层级、物质分类、协议栈分层 |
| 算法/处理流程 | `mermaid flowchart TD` | 计算方法步骤、实验操作流程、推导证明路径、信号处理流水线 |
| 系统架构/组件关系 | `mermaid graph LR` 或 `TD` | 模块依赖关系、设备结构框图、反应路径、控制系统方框图 |
| 状态转换/判断分支 | `mermaid graph TD` + 菱形节点 `{}` | 收敛判据、相变条件、判断逻辑、状态机 |
| 时间线/发展历程 | `mermaid timeline` 或编号列表 | 学科发展史、技术演进脉络 |
| 并列对比 | HTML 表格 | 方法对比、参数对比、优缺点分析、概念辨析 |
| 数学坐标系/函数曲线 | SVG `` | 函数图像、相图、几何证明图示、分布曲线 |
| 实物/场景照片 | 课件截图 `` | 实验装置、设备外观、晶体结构照片、地质构造图 |
| 公式推导流程 | LaTeX + `` | 数学/物理/化学推导步骤（不需要额外图表） |

**选择原则**：
1. 能用 Mermaid 描述的流程/结构 → **优先 Mermaid**（纯文本生成、渲染一致性高、跨平台无依赖、易于修改）
2. 需要精确坐标/曲线的数学图 → 用 **SVG**（坐标系、函数图像、几何关系）
3. 课件中有不可替代的实物图/照片 → 用**课件截图**

> ⚠️ Mermaid 安全语法规则（详见 [html-template.md](references/html-template.md) 末尾）：节点标签含特殊字符必须用双引号包裹，否则图表渲染失败。

### ✅ Phase 2 质量门

- [ ] `match_images.py` 已运行，`image_mapping.json` 已生成
- [ ] 全部课件文本已读取，无遗漏
- [ ] 纯图片课件已通过视觉识别处理
- [ ] 每张待嵌入图片已通过视觉识别交叉验证（图片内容与文字上下文一致）
- [ ] 已完成深度理解6问
- [ ] 已规划每章需要引用的图片清单（含"图片→概念"映射）
- [ ] 已根据图表格式选择指南（2.7节）规划每章的图表方案

> 📦 **精简模式（≤200k）— 压缩检查点 ①（Phase 2 完成后）：**
> 在进入 Phase 3 之前，主动压缩当前会话上下文：
> 1. 将所有已读课程材料总结为一张"章节要点摘要表"（每章≤200字）
> 2. 摘要表保留：章节标题、核心公式列表（LaTeX）、关键概念列表（中英双语）、图片文件名→概念映射
> 3. 丢弃已读取的原始文本细节（原文占上下文最多）
> 4. 目标：将上下文占用降至当前的 30-40%
> 5. 向用户报告："已完成上下文压缩，已保留 N 章摘要。"

---

## Phase 3：补充调研（可选）

搜索GitHub/Wikipedia补充对核心概念的理解。**课件内容始终是主，外部资料仅作辅助**。所有外部来源标注出处。

> 📦 **精简模式（≤200k）— 压缩检查点 ②（Phase 3 完成后）：**
> 1. 将补充调研内容压缩为"补充要点列表"（≤100字），仅保留核心补充概念和来源链接
> 2. 如果 Phase 3 未执行，跳过此检查点
> 3. 向用户报告："补充调研压缩完成。"

---

## Phase 4：生成HTML复习文档

### 4.0 生成方法——Python串行追加（唯一可靠方式）

HTML文档规模巨大（2000+行），**禁止使用Agent/子Agent生成章节内容**——会因超长输出而卡死。

**正确流程**：

1. **Write工具** → 创建HTML文件头部（`` 到 ``，含完整CSS + Hero + 侧边栏目录 + 搜索栏 + 阅读指南 + 内联目录）
2. **Python脚本1** → 追加 Ch0 + Ch1 + Ch2（约250行）
3. **Python脚本2** → 追加 Ch3 + Ch4 + Ch5（约250行）
4. **Python脚本3** → 追加 Ch6 + Ch7 + Ch8（约300行）
5. **Python脚本4** → 追加 Ch9 + Ch10（约200行）
6. **Python脚本5** → 追加 Ch11 + Ch12 + 附录A/B/C + 页脚 + JavaScript + ``（约500行）

> 📦 **精简模式（≤200k）— 更细粒度的分批策略：**
> 上述分批方案针对标准模式。精简模式下采用更小的批次：
> - 每个 Python 脚本仅生成 **1 个章节**（约 100-150 行 HTML），而非 2-3 个章节
> - 即：脚本1→Ch0，脚本2→Ch1，脚本3→Ch2，...，以此类推
> - 每完成一章的脚本执行后，**立即输出进度检查点**（格式见下方）
> - 如果感到上下文紧张（如工具调用开始变慢），**先执行压缩**再继续下一章

> 📦 **精简模式（≤200k）— 进度检查点格式（每完成一章后输出）：**
> ```
> ✅ 第 N 章生成完毕。已写入文件。进度：N/M
> 剩余章节：[章节列表]
> 下一章需要的关键信息：[从摘要中提取的提示]
> ```

每个Python脚本模式——**必须使用三双引号 `"""..."""`，禁止使用 `r'''...'''`**：

```python
# -*- coding: utf-8 -*-
content = """
[HTML内容——JS中的单引号 ' 在Python三双引号中无需转义，直接写即可]
"""
with open('目标文件.html', 'a', encoding='utf-8') as f:
    f.write(content)
print('ChX-Y appended')

🔴 为什么禁止 r'''...'''（raw triple single quotes）：JavaScript 中大量使用单引号 ' 作为字符串分隔符（如 addEventListener('click', ...)）。在 Python 的 r'''...''' raw string 中，连续单引号 '' 会被原样写入文件，导致 JS 语法错误（''click'' 而非 'click'）。使用 """...""" 三双引号完全避免此问题——JS 单引号在 Python 三双引号字符串中不产生任何冲突。

执行：python _append_ch0_2.py → 每批执行完成后立即清理临时 .py 文件。

🔴 4.1 生成前思考清单（每批执行前必做）

在写每一批Python脚本之前，先确认你要写的这几章：

1. 每章的核心概念是哪些？（列出清单）
2. 每个概念对应的课件图片是哪张？（确认文件名）
3. 🔴 每张图片是否已通过 Phase 2.5 视觉交叉验证？（逐张确认验证状态：✅匹配 / ❌装饰已排除 / ⚠️标题已修正。未完成验证的图片不得写入HTML。）
4. 哪些推导需要补全？（列出推导链的起点→终点）
5. 每章的综合性大题是什么？（至少想好1道）
6. 每章的易混淆点是什么？（至少2个）

4.2 文档结构（8部分）

1. Hero封面（考试范围、形式、教师、教材、日期）
2. 📖 阅读指南（给不同基础学生的路径建议）
3. 📑 目录（侧边栏 + 内联，含进度checkbox）
4. 第〇章：课程核心思维（主线流程图、核心关系、学习动机）
5. 第1章～第N章：每章精讲
6. 附录A：公式速查卡（按主题分类）
7. 附录B：解题模板（标准化步骤）
8. 附录C：常见错误与陷阱（对照表）

🔴 4.3 每章内容规范（质量核心）

每章一个 .chapter-card，包含两个选项卡：

⚡ 快速复习面板：

• 2-3句话章节概要
• 3-5张术语闪卡（.flashcard-grid，禁止内联onclick，翻转由JS事件委托处理）
• 关键公式表格

📖 详细讲解面板——每个核心概念必须做到5层结构：

📌 1. 定义：精确的数学定义 + 通俗语言复述
🖼️ 2. 配图：课件原图 + 上下文结合的图说（见4.4）
💡 3. 物理意义：生活中的类比、直观解释
🔢 4. 数学拆解：每个符号的含义、单位、取值
⚠️ 5. 适用条件：什么时候能用、什么时候不能用、常见误用

对每个核心概念还要补充：

• 📐 完整推导（可折叠，每步有"为什么这一步？"解释）
• ✏️ 例题（至少1道综合性计算大题，含考点分析→解题策略→分步详解→验证→易错点）
• 🔗 概念关联（前置知识链接 + 后续延伸链接 + 易混淆对比）

每章交互组件要求： | 组件 | 数量要求 | |------|---------| | 术语闪卡 | 3-5张 | | 可折叠推导 | 每个核心定理1个 | | 练习测验 | 2-4道题 | | 综合性大题 | 至少1道 | | 高频考点汇总表 | 每章1张（见下方规范） |

🔴 跨章节引用规范

当概念之间存在跨章节依赖或容易混淆时，使用标准格式标注，帮助学生建立知识网络：

• 前置依赖：📖 前置：见 [第X章 X节](#chX-Y) — [概念名]
• 后续延伸：🔗 延伸：见 [第Z章 Z节](#chZ-W) — [概念名]
• 易混淆对比：⚠️ 区分：与 [第X章的XX](#chX-Y) 不同，本概念...

这些引用标注在5层结构中的「5. 与其他概念的关联」部分自然融入。

🔴 每章高频考点汇总表

在每章 .chapter-card 内部、.tab-container 和练习测验之后，使用 .exam-points-summary 区块添加高频考点汇总表：

| 考点 | 重要度 | 考查形式 | |------|--------|----------| | [考点名称] | ★★★ | [考查形式] |

重要度标准（与学科无关，根据考点在课程中的客观重要性评定）：

• ★★★（核心）：多章节依赖的基石概念，考试核心，几乎必考
• ★★（重要）：本章重点内容，常见题型，需要熟练掌握
• ★（了解）：辅助理解的概念，知道即可，出题概率较低

考查形式分类（覆盖理工科常见题型，根据考点特征从以下选取 1-2 项标注）：

| 标注 | 适用场景 | |------|---------| | 选择题 | 概念辨析、定义判断、参数选择 | | 填空题 | 关键公式、核心参数、定理条件 | | 计算题 | 公式应用、数值求解、工程计算 | | 简答题/论述题 | 原理阐释、方法比较、概念解释 | | 证明题 | 定理推导、公式证明、逻辑推理 | | 分析题/综合题 | 跨章节综合应用、实际场景分析 | | 设计题 | 方案设计、参数选取、系统构建 |

> 标注时从上述分类中选取适用的 1-2 项，不预设仅适用于特定学科的题型。

🔴 4.4 图文策略——图表与图片的协同

图表和图片不是装饰——是核心教学内容的一部分。本章节定义了三种视觉元素的选用规范和分工边界。

A. 图表格式决策

在选择图表格式前，对照 Phase 2.7 的决策表确定每种内容类型的最佳视觉格式：

• 流程/层级/架构/判断关系 → 优先 Mermaid（纯文本生成、渲染一致、易于修改）
• 坐标系/函数曲线/精确几何关系 → 使用 SVG（需要精确坐标控制）
• 实物照片/实验装置/不可替代的课件原图 → 使用课件截图

B. Mermaid 图表规范（流程图/架构图/层级图/决策树——首选方案）

当概念之间涉及流程、层级、架构或判断关系时，使用 Mermaid 生成图表：

语法安全（最高优先级）：含特殊字符（| _ = { } ( ) ` # ^ : , *`）的节点标签必须用双引号包裹，否则图表渲染失败。详见 [html-template.md](references/html-template.md) 末尾的「Mermaid 安全语法规则」完整版。

HTML 嵌入格式：

graph TD
    A["节点标签含特殊|字符时引号包裹"] --> B["普通文本可省略引号"]
    C{"判断条件?"} -->|"是"| D["结果A"]
    C -->|"否"| E["结果B"]

使用时机：

• ✅ 概念分类树、算法流程图、系统架构框图、状态/判断分支图
• ✅ 层级关系、依赖关系、处理流水线
• ❌ 单一公式、纯文本关系、无需"图"来表达的内容

配色：Mermaid 通过 %%{init}%% 配置已预设为与文档蓝色主题一致（参见 html-template.md 中初始化配置），无需逐图指定颜色。

排版要求：

• 每个 Mermaid 图表放在独立的 `` 中
• 图表下方必须有一句解释文字（如"如上图所示，[对图表内容的说明]"）
• 节点数量控制在 5-15 个，层级不超过 4 层，保持可读性

C. SVG 示意图规范（坐标系/曲线图场景）

适用范围：数学坐标系图、函数曲线图、几何证明图示、分布曲线——这些需要精确坐标控制，Mermaid 无法表达。

保留现有 SVG 生成指南不变：

• 流程图/框图（如非 Mermaid 可表达）：使用 `, , ` 等基本元素
• 坐标系/曲线图：使用 `` 绘制函数曲线
• 颜色使用 currentColor 或 CSS 变量以支持暗色模式
• SVG必须设置 viewBox 以确保缩放不变形
• 所有文本使用 ` 元素并指定 font-family="system-ui, sans-serif"`

🔴 禁止使用ASCII字符画：ASCII art（用 ┌─┐│└┘ 等字符画的框图）渲染效果不一致（依赖字体和等宽设置），在移动端和打印时严重错位。需要示意图时一律使用 SVG 或 Mermaid。

D. 课件截图规范

保留现有课件截图逻辑不变：

每章至少引用8-10张课件原图（实物照片、实验装置、不可替代的课件插图）。

图片规划（在写每章内容前完成）：

1. 查看 extracted_images/ 目录，找到该章节对应的所有图片
2. 将每张图片分配到具体概念位置
3. 为每张图片写一句上下文相关的图说（不只是"如图所示"）

图片引用格式：

  
  图N.M：[结合上下文的说明]（来源：[课件文件名]）

如上图所示，[对图片内容的具体解释，与当前讲解的概念建立关联]。

图片选择优先级：核心概念示意图 > 公式推导图 > 对比图 > 解题流程图 > 例题配图 > 实验数据图

🔴 写入前置条件：每张图片在写入HTML前，必须已通过 Phase 2.5 的视觉交叉验证（尺寸筛查 + 视觉识别 + 内容比对三步全部完成）。未验证的图片一律不得写入。验证报告必须在上下文中可追溯。

🔴 不引用：纯装饰图、Logo、与文字完全重复的简单公式截图、分辨率过低（/_复习指南.html" --in-place

### 🔴 4.5 公式与推导规范

**公式完整性**：逐一检查每个提取的公式，修复断裂、丢失符号、错位上下标。

| 问题 | 修复 |
|------|------|
| 公式断裂（多行被拆碎） | 根据数学常识还原为完整LaTeX |
| 符号丢失（希腊字母变乱码） | 根据上下文推断正确符号 |
| `a/b` 应为分数 | 改写为 `\frac{a}{b}` |
| `x2` 应为上下标 | 判断为 `x^2` 或 `x_2` |
| `sin` 应为函数名 | 统一 `\sin`, `\cos`, `\lim`, `\exp` |

**推导补全标准**：课件中被跳过的推导必须补全。每个推导步骤包含3要素：
1. **做了什么**操作
2. **为什么这一步**（基于什么原理/定理）
3. **完整中间表达式**（不跳步）

课件写法 → 必须展开 "易证得..." → 完整证明（至少3-5步） "显然..." → 写出"显然"背后的逻辑 "由此可得..." → 写出具体代数操作 只有结果无过程 → 从定义出发补全推导链

**独立公式格式**：`$$` 必须单独成行，行内公式用 `$...$`，重要结果用 `\boxed{}`。

### 4.6 HTML模板与交互系统

完整CSS样式和HTML骨架见 [references/html-template.md](references/html-template.md)。**MathJax必须使用CDN在线渲染**：``。禁止使用本地 `./mathjax/` 或 `../mathjax/` 路径。关键交互组件：

| 组件 | HTML模式 | 要点 |
|------|----------|------|
| 可折叠推导 | `` | 默认折叠，每步含"为什么" |
| 选项卡 | `` | ⚡快速复习 / 📖详细讲解 |
| 术语闪卡 | `` | **禁止内联onclick**，JS事件委托 |
| 练习测验 | `` | 答案默认折叠 |
| 进度追踪 | `.section-checkbox` | localStorage持久化 |
| 搜索过滤 | `.search-input` | 实时过滤所有内容块 |

**图标约定**：📌定义 `.callout-def` | 🔑关键 `.callout-key` | 📐推导 `details.derive-steps` | ✏️例题 `.callout-example` | 💡直观 `blockquote` | ⚠️注意 `.callout-warn` | 📝测验 `.quiz-section`

### 4.7 作者信息禁令

HTML文档中**禁止出现**项目作者姓名（Li Jiawei, Peng Chen, Cai Haoxuan）。页脚只标注生成工具和日期。

### ✅ Phase 4 质量门（每章生成后自检）

- [ ] 本章8-10张课件原图已嵌入，图说与上下文结合
- [ ] 每个📌概念有完整的5层结构（定义→配图→物理意义→数学拆解→适用条件）
- [ ] 每个核心推导有完整步骤 + 每步"为什么"
- [ ] 至少1道综合性计算大题（含考点分析→策略→详步→验证→易错点）
- [ ] 3-5张闪卡 + 2-4道练习题 + 可折叠推导 + 选项卡
- [ ] 所有公式用LaTeX，重要结果 `\boxed{}`
- [ ] 关键术语中英双语
- [ ] 闪卡HTML中无内联onclick
- [ ] 数学符号首次出现时说明了含义和单位

> 📦 **精简模式（≤200k）— 压缩检查点 ③（Phase 4 每生成 3 章后）：**
> 每完成 3 个章节的 HTML 生成后，执行上下文压缩：
> 1. 回顾已生成章节的结构完整性（仅检查标题层级和组件数量，不重新读取文件）
> 2. 将已生成章节信息压缩为"已生成章节清单"：仅保留章节标题 + 状态（完成/待检查）+ 图片数量
> 3. 丢弃已写入 HTML 的内容原文（文件已保存，无需在上下文中保留）
> 4. 向用户报告："已完成 N 章生成和压缩，上下文已释放。继续生成剩余章节。"

---

## Phase 5：全局质量检查

HTML生成完成后，按以下顺序执行后处理和质量检查：

> 📦 **精简模式（≤200k）— 压缩检查点 ④（Phase 5 开始前）：**
> 在进入质量检查前，执行最终上下文压缩：
> 1. 将全部已生成章节信息压缩为"完整章节清单"（仅标题 + 状态 + 图片数 + 公式数）
> 2. 丢弃所有中间过程信息（原文摘要、调研内容、生成过程记录）
> 3. 仅保留：章节清单 + HTML文件路径 + 质量检查清单引用
> 4. 目标：为 Phase 5 的质量检查释放最大上下文空间
> 5. 向用户报告："全部章节生成完毕，上下文已压缩。开始质量检查。"

### 5.1 图片内嵌

```bash
python embed_images.py "复习文档输出//_复习指南.html" --in-place -v

5.2 质量检查

对照 [references/quality-checklist.md](references/quality-checklist.md) 逐项自检。

必须修复的问题（再检查一遍）：

• [ ] embed_images.py 已运行，所有图片已base64内嵌
• [ ] MathJax 使用 CDN 在线加载（https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js），无任何本地 ./mathjax/ 或 ../mathjax/ 路径引用
• [ ] 搜索全文档确认无 onclick= (闪卡bug)
• [ ] 搜索全文档确认无作者姓名
• [ ] $$ 数量为偶数
• [ ] 所有锚点链接可点击跳转
• [ ] 所有 Mermaid 代码块闭合完整，节点标签特殊字符已引号包裹（详见 quality-checklist.md Mermaid 检查项）
• [ ] 每章末尾有「高频考点汇总」表（.exam-points-summary），重要度星级标注正确
• [ ] 跨章节依赖概念使用标准引用格式（📖前置 / 🔗延伸 / ⚠️区分）

---

Phase 6：考试押题文档（独立HTML）

6.1 输出方式

押题文档必须生成为独立HTML文件——不追加到复习文档。原因：(1) 复习文档已2000+行；(2) 押题需要独立的试卷风格（衬线字体、隐藏解答的打印模式）；(3) 便于单独打印分发。

使用 Write 工具直接生成（押题文档约400-600行，单次Write即可，无需分片）。

6.2 押题分析（生成前完成）

分析信号优先级：

1. 高频概念：多章节反复出现
2. 重点推导：课件中有完整推导的公式
3. 课件标注："重点""掌握""必考"
4. 例题分布：课件中例题对应的知识点
5. 跨章节主题：连接多章的综合概念 → 综合题
6. 套公式题型：流程化计算 → 大题
7. 概念对比：易混淆概念对 → 辨析题

6.3 押题文档结构

1. 押题概述：题型分布预测、各章节出题概率表、难度预估
2. 分章节押题（每章）：
   - 🔴 高频考点 + 预测理由 + 可能出题形式
   - 📐 重点推导题 2-4道 + 详细解答
   - ✏️ 概念应用题 2-3道 + 解答
3. 模拟试卷（完整一套）：
   - 按用户指定题型比例编排
   - 题量：选择题15-20道 + 填空题10-15道 + 计算题5-8道
4. 押题依据表：每道题 → 对应课件来源

6.4 押题质量标准

每题必须包含：

• 题干：清晰、准确、与课件内容对应
• 详细解答（默认折叠）：完整推导过程 + \boxed{} 最终结果
• 考点来源：对应课件文件+页码
• 评分要点（计算题）：各步骤分值
• 常见错误预判：学生可能犯的2-3个错误

详细模板见 [references/prediction-guide.md](references/prediction-guide.md)。

✅ Phase 6 质量门

• [ ] 押题为独立HTML文件，未追加到复习文档
• [ ] 题量充足：选择15-20道 + 填空10-15道 + 计算5-8道
• [ ] 每题有详细解答 + 考点来源 + 常见错误预判
• [ ] 计算题有评分要点
• [ ] 押题依据表完整（每道题→课件来源）
• [ ] MathJax引用正确，$$ 成对
• [ ] 打印时解答可隐藏

---

输出

生成完成后报告统计：章节数、例题数、图片数（课件原图+SVG）、补全推导数、公式数（近似）、闪卡数、练习题数、附录条目数、押题数（如有）。

参考资源

• [references/html-template.md](references/html-template.md) — 完整HTML/CSS/JS模板
• [references/quality-checklist.md](references/quality-checklist.md) — 36项质量检查清单
• [references/prediction-guide.md](references/prediction-guide.md) — 押题文档模板与标准

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lijiawei255
• Source: lijiawei255/agent-edu-reviewkit
• License: MIT

Install and usage instructions live in the source repository linked above.