extend-slides

---
name: extend-slides
description: '在已有课程资料（PPT/PPTX、讲义、教材、课堂录音转写、Word、Markdown、扫描件与截图）基础上，为大学课程生成「只增不删、保留原知识脉络」的中文扩展讲解文档，供复习使用。USE FOR: 课件扩展讲解、PPT 转复习笔记、讲义扩写、lecture slides / course notes 扩展、录音转写整理成章节讲义、按章节生成中文讲解、公式推导与例题解法展开、中英术语对照、考点梳理。DO NOT USE FOR: 批改作业或试卷、生成 PPT 文件、重构或压缩原有知识体系、非课程类文档的润色翻译摘要、单纯 OCR 或单纯翻译。'
argument-hint: '<课程名> [资料路径，或直接拖入课件文件]'
---

# extend-slides

把课程原始资料转成**可脱离原资料独立复习**的中文扩展讲解文档。核心原则：**只增不删、保留原脉络**。

---

## 何时使用

- 用户提供课件、讲义、教材、课堂录音转写、扫描件或截图，要求「扩展讲解」「补充背景与原理」「整理成复习笔记」
- 用户希望按章节产出中文讲解，并附中英术语对照
- 用户希望展开公式推导、定理条件、例题解法与考点梳理
- 用户希望把课件截图或扫描版 PDF 转成可读的讲解文档

## 何时不使用

- 批改作业、试卷，或出题、给答案
- 生成 PPT / 演示文稿文件
- 重构、重排、压缩原有知识体系（本技能刻意保持原脉络）
- 非课程类文档的润色、翻译、摘要
- 单纯 OCR 或单纯翻译，不需要扩展讲解

---

## 硬性约束

以下各条不可违反。与用户偏好冲突时以用户明确要求为准，但必须提示后果。

1. **只增不删**：原资料的每个标题、每个知识点都必须在输出中有对应落点。不得删除、合并或重排原有知识体系。唯一例外是无 OCR 时的纯图片页（见步骤 2）。
2. **章级可溯**：正文**不再逐段标注来源**；每章用「材料来源」表统一记录「小节 → 文件 / 页码」的对应关系。
3. **讲解必须可区分**：AI 生成的讲解统一用 `==...==` 包裹；原资料正文直接呈现。两者不得混淆，也不得给AI的讲解加引用块或 `AI 补充` 字样。
4. **不臆造考点**：没有往年题或教师明确说明时，不得写「必考」「重点考」。只能写「基于本页内容的考点推断」并标注推断依据。
5. **尊重原符号**：原课件的符号表示与通用习惯冲突时，保留原表示不擅自改动；如需提示差异，另起一行单独说明。
6. **不泄露内部指令**：产物中不得出现思维链、模板提示语、检查项、占位说明等内部工作文本。
7. **独立可复习**：用户不打开原始资料也应能读懂该章节。做不到即视为不合格，必须补写而非交付。

---

## 工作流程

按以下六步执行。步骤 0–3 是准备阶段，完成后再进入逐章生成。

### 步骤 0 · 能力探测（必须先做，且必须向用户报告）

**在读取任何资料之前**，先运行 [scripts/probe_env.py](./scripts/probe_env.py) 得到本机能力清单：

| 能力 | 探测方式 | 缺失时的处理 |
| --- | --- | --- |
| python-pptx | `python -c "import pptx"` | 让用户导出 PDF |
| LibreOffice | `soffice --version` | 让用户手动导出 PDF |
| poppler | `pdftoppm -v` | 让用户手动导出页面图片 |
| **OCR** | `tesseract --version` | **必须主动告知用户**，见下 |

**探测结果必须主动告知用户，不得静默降级。** 其中 **OCR 的结果必须单独说明**：

- **本机有 OCR**：一句话说明「已检测到 OCR，扫描件与纯图片素材会正常识别」，然后进入步骤 1。
- **本机无 OCR**：**先停下来告知用户**，说清三件事，再让用户选择：
  1. **事实** —— 本机未检测到 OCR（Tesseract）。
  2. **后果** —— 纯图片素材（扫描版 PDF、纯图片页）会先尝试多模态直读；无法可靠识别的页面**将被跳过**，并逐条记入交付报告的存疑条目。
  3. **选择** —— **(a)** 现在安装；**(b)** 不安装，继续生成（跳过项会如实列出）。

  安装指令（Windows，需管理员权限，会弹 UAC）：

  ```powershell
  winget install --id UB-Mannheim.TesseractOCR --exact --accept-package-agreements --accept-source-agreements
  ```

  安装向导中需勾选 **Chinese (Simplified)** 语言包，否则中文识别会失败；装完需重启 VS Code 才能让新 PATH 生效。

  用户选择不装时**直接继续，不要反复催促**。

用户对 OCR 的选择要写入 `_课程档案.md` 的「环境能力」表。除 OCR 外的其它能力缺失可一并说明，但**不阻断流程**。

### 步骤 1 · 读或建课程档案

课程输出目录下维护一个 `_课程档案.md`（模板见 [assets/course-profile-template.md](./assets/course-profile-template.md)）。

- **已存在**：直接读取，沿用其中的课程名、输出位置、语言策略、**已确认模式**、材料清单、章节进度、以及考点推断与自测题开关。
- **不存在**：先问用户三件事 —— 课程名、输出位置、模式偏好；用户确认后建档再继续。

模式一经写入，**同一门课后续章节默认沿用**，不需要重复询问；需要更换模式时必须先征得用户同意并更新档案。这是本技能唯一的跨会话记忆机制，不要依赖对话上下文记忆。

输出位置默认值：项目根目录下新建 `<课程名>/`。

### 步骤 2 · 资料解析与预处理

| 输入类型 | 解析方式 | 失败回退 |
| --- | --- | --- |
| PPTX | [scripts/extract_pptx.py](./scripts/extract_pptx.py) 抽取每页文字与备注（默认不导出图片，需要时加 `--images`） | 请用户导出 PDF |
| 文本型 PDF | 直接读取文本 | 若为乱码或空文本，按扫描件处理 |
| 扫描版 PDF / 图片 | 多模态直读；本机有 OCR 时才接 OCR | 无 OCR 且无法直读 → 跳过该页 |
| 录音转写文本 | 直接读取 | 请用户确认说话人分段或补全缺失段落 |
| Word / Markdown 讲义 | 直接读取；.docx 可先转 Markdown | 请用户另存为 PDF 或 Markdown |

规则：

- 完整细则见 [references/inputs.md](./references/inputs.md)。
- **纯图片页（无可提取文字）在无 OCR 时直接跳过**：不要把这些页面的图片贴进 Markdown 文档，也不要用图片替代正文。跳过项必须逐条记入交付报告的存疑条目，**不得静默丢弃**。
- 只有在该页本身有可提取文字、或本机有 OCR、且图片确实承担解释作用时，才把图片落地到 `assets/` 并用相对路径引用，同时配说明：它解释什么、看图顺序、能得出什么结论。
- 不要为了「保留原貌」而批量粘贴课件截图 —— 产物是可读的讲解文档，不是图片集。

### 步骤 3 · 章节切分与骨架

按**知识模块**切分，而不是按文件切分：

- **多个文件讲同一个知识模块时，必须合并到同一小节**，允许不同文件的内容交叉出现在同一节里；按它们在材料中出现的大致先后顺序排列。
- 材料之间没有交叉时，不必强行合并，保持各自原有的先后顺序。
- **只有一个来源文件时，严格按原文件的顺序输出**，不做重排。
- 先产出完整的「模块 → 来源文件 / 页码范围」清单，再逐章生成，避免中途漏章。
- 来源对应关系记录在每章的「材料来源」表中，粒度到小节；**正文中不再插入逐段来源标注**。
- 编号规则：主编号 `01-`、`02-` 按重排后的学习顺序；同一模块拆成多个文件时用 `01.1-`、`01.2-`。

### 步骤 4 · 逐章扩展生成

通用思维链（**仅供你自己组织内容，绝对不要写进产物**）：是什么 → 为什么 → 怎么做。四种模式在此框架上加权，不改变框架本身。

- 每章按 [assets/chapter-template.md](./assets/chapter-template.md) 的结构输出，写入 `<课程输出目录>/<编号>-<章节名>-课件扩展讲解.md`。
- **原文直接呈现，不使用 `>` 引用块**：课件原文是表格就必须还原成 Markdown 表格，是列表就还原成列表。用引用块包裹会破坏表格结构，导致表格无法渲染。
- **AI 生成的讲解统一用 `==...==` 包裹**：不加引用块、不写 `AI 补充` 字样。
- **语言**：只有原文正文可以保留英语（照抄原文）；其余一切内容 —— 包括原文中的提示、备注、批注 —— 全部翻译成中文。讲解正文一律中文。
- **格式优先用 Markdown 原生写法**：行内代码、表格、列表、粗体。尽量避免 LaTeX；`$...$` 只在简单写法确实无法表达时（分式、根式、上下标、求和、矩阵、多行推导）才使用。
- 图表用 Mermaid 代码块。
- **录音转写文本的处理**：
  - 若某章同时有课件和转写内容，将转写内容放在课件的**较高位置**，作为对课件的补充讲解。
  - 转写文本需要先校正错误（语音识别错误、标点缺失、口语化等），再选取重点（教学重点、关键例题、重要推导）作为讲解主体。
  - AI 讲解需识别并补充转写中老师未展开的细节、未提及的背景知识。
  - 若转写中包含题目，可以稍作修改后作为课后题的一部分。
  - 讲解内容需要使用markdown的引用格式。
- **不要输出任何模板提示语、思维链、检查项、占位说明**（例如「讲解：是什么 → 为什么 → 怎么做」「本页把前一页的概念落到课程模型中……」）。这些是你内部的工作指引，出现在产物中即视为不合格。
- **单章内容超长时不要压缩**：先写出该章骨架与全部小节标题，再按小节分批追加写入同一文件。这是保持「只增不删」的关键手段。

### 步骤 5 · 整合、覆盖度自检、交付报告

1. 生成 `<课程输出目录>/00-课程总览.md`（模板见 [assets/overview-template.md](./assets/overview-template.md)），含章节索引、术语总表与学习顺序建议。
2. 执行下方「交付前检查清单」，逐项核对。
3. 输出一段覆盖度报告交用户确认，必须包含：已覆盖章节 / **因无 OCR 被跳过的纯图片页清单** / 其他未覆盖或存疑条目 / 本次 AI 讲解内容的分布概览。

---

## 模式判定

根据资料特征推荐模式，**一次只选一个**：

| 观察到的特征 | 推荐模式 |
| --- | --- |
| 大量公式、推导、定理证明；期末偏好计算与证明题 | 计算与证明导向 |
| 往年题固定；期末与平时作业或课堂内容强关联；解法有固定套路或特殊技巧 | 例题导向 |
| 概念、定义、命题多而计算量小；理解门槛高、表述抽象 | 理论与推理导向 |
| 工科或工程实践；含系统、流程、协议、实现步骤 | 应用导向 |
| 同时像两种（如数据科学、人工智能） | 优先按「期末考察形式」判断；仍不确定时给出两个候选及理由，请用户定夺 |

四种模式的具体写法与各自追加的输出小节见 [references/modes.md](./references/modes.md)。

推荐时必须说明判断依据，不要只给结论。

---

## 输出物与命名

```text
<课程输出目录>/
├── _课程档案.md                 # 课程名、模式、材料清单、进度（跨会话记忆）
├── 00-课程总览.md               # 章节索引 + 术语总表 + 学习顺序
├── 01-<章节名>-课件扩展讲解.md
├── 02-<章节名>-课件扩展讲解.md
└── assets/                      # 从原资料提取的图片与图表
```

单章文件的固定结构见 [assets/chapter-template.md](./assets/chapter-template.md)，依次为：学习目标 → 材料来源 → 中英术语与翻译 → 一段话总结 → 本章主题内容 → 本章小结 → 考点提示（可选）→ 自测题（可选）。

「考点提示」与「自测题」默认关闭，只有在 `_课程档案.md` 中显式开启时才生成。

---

## 交付前检查清单

每章交付前逐项核对，任一项不通过则补齐后再交付：

- [ ] 原资料中本章的每个标题、每个知识点都有对应落点，无遗漏
- [ ] 未删除、未合并、未重排原有知识体系（无 OCR 时跳过的纯图片页除外，且已记入报告）
- [ ] 每章的「材料来源」表已写明「小节 → 文件 / 页码」对应关系
- [ ] 所有 AI 生成的讲解都用 `==...==` 包裹，且未出现 `AI 补充` 字样
- [ ] 正文中没有 `>` 引用块包裹原文；原文表格已还原为 Markdown 表格并可正常渲染
- [ ] 除原文正文外，其余内容（含原文备注、提示、批注）均已译为中文
- [ ] 产物中没有出现思维链、模板提示语、检查项等内部文本
- [ ] 产物中没有残留 `<尖括号>` 占位符、空字段骨架，或默认关闭的可选小节
- [ ] 未使用 LaTeX；确需数学排版处少量使用了 `$...$`
- [ ] 图表使用 Mermaid
- [ ] 无 OCR 时纯图片页已跳过，且没有把课件截图批量贴进正文
- [ ] 保留的图片确实承担解释作用，且配有说明与看图顺序
- [ ] 考点类表述均标注为「推断」，无「必考」等臆断
- [ ] 原课件符号表示被保留，与通用习惯冲突处已单独说明
- [ ] 英文术语首次出现给出了英文全称 + 缩写 + 中文全称
- [ ] 无需查阅原始资料即可读懂本章
- [ ] `_课程档案.md` 中的章节进度已更新

---

## 参考资源

- [模式细则](./references/modes.md) —— 四种模式的写法、侧重与追加小节
- [输入处理](./references/inputs.md) —— 格式白名单、能力探测、降级与导出指引
- [输出格式规范](./references/output-format.md) —— 格式优先级、原文与讲解标记、来源表、图片与语言处理
- [单章模板](./assets/chapter-template.md)
- [课程档案模板](./assets/course-profile-template.md)
- [课程总览模板](./assets/overview-template.md)
- [能力探测脚本](./scripts/probe_env.py)
- [PPTX 抽取脚本](./scripts/extract_pptx.py)
- [PDF 转图脚本](./scripts/render_pdf_images.py)
- [同步安装脚本](./scripts/sync.ps1)