pdf-lecture-notes-zhlisted
Install: claude install-skill wonder37-debug/agent-skill-pdf-lecture-notes
# 中文 PDF 课件 → Markdown 学习笔记
把课程 PDF 课件转化为结构化、可直接复习的中文 Markdown 笔记;图例(流程图、结构图、示意图等)裁剪为完整图片,嵌入对应知识点下方。
## 适用条件
| 条件 | 说明 |
| --- | --- |
| PDF 有文本层 | 文本提取依赖 `pdfplumber`;纯扫描件需先 OCR,不适用本流程 |
| 图例由图形对象构成 | 位图(images)或矢量(curves/lines/rects)均可,两者裁剪路径不同,见第 3 步 |
| 页面尺寸动态读取 | 常见 960×540、720×405、1280×720,用 `page.width/height` 读取,不要硬编码 |
## 环境准备
```bash
python3 -m venv .venv
# Linux / macOS
.venv/bin/pip install -r requirements.txt
# Windows (PowerShell)
# .venv\Scripts\pip install -r requirements.txt
```
依赖共三个:`pdfplumber`(文本与图形对象坐标)、`pypdfium2`(整页渲染)、`Pillow`(裁剪与像素统计)。不需要 numpy,逐行/逐列像素统计用 PIL 的 `histogram()` 即可。
## 工作流
```
- [ ] 1. 提取文本 + 渲染页面 + 诊断固定角标
- [ ] 2. 挑选图例页
- [ ] 3. 裁剪图例(figures.json 驱动)
- [ ] 4. 目视复核裁剪结果
- [ ] 5. 撰写 Markdown 笔记
- [ ] 6. 校验图片引用
- [ ] 7. 清理中间文件
```
### 第 1 步:提取文本 + 渲染页面
```bash
python scripts/extract_and_render.py 课件.pdf -o _tmp --scale 3 --diagnose-deco
```
产出:
- `_tmp/text_raw.txt`:每页文本 + `images/curves/rects/lines` 计数,计数高的页大概率含图例;
- `_tmp/pages/pNN.png`:整页渲染图(scale=3,保证裁剪后仍清晰);
- `--diagnose-deco`:找出"在多数页面相同坐标重复出现"的图形对象(页眉校名、页脚校徽这类固定角标),直接输出可粘进 `figures.json` 各项 `deco` 字段的 bbox 列表。
PPT 型课件通常有两个固定角标(页眉 + 页脚),诊断结果要全部填入 `deco`;漏填会使 auto 模式的裁剪边界一路扩到页边。
PPT 类课件的文本抽取顺序常常错乱(标题与正文穿插),需结合渲染图判断真实版面。
### 第 2 步:挑选图例页
只截真图。以下情况不截:
- 纯文字页(包括带项目符号的要点罗列);
- 与正文文字完全重复的内容;
- 目录页、章节分隔页、参考文献页(除非含图)。
值得截的:流程图、结构图、语法树、状态机��时序图、架构图、示意图、带标注的代码对比图、表格化的映射关系图。
同一张图在多页重复出现时只截一次;同一页有多个独立图例时分开裁剪保存,不要合并成一张。
### 第 3 步:裁剪图例
核心原则:**宁可截大,不可截破**。裁剪过紧导致标题、箭头、边框、图注被切掉,是最