PDF 课件 → Obsidian 笔记知识库

一个 Claude Code Skill：把一整个目录的 PDF / PPT 课件，全自动整理成图文并茂、专为 Obsidian 优化的中文复习笔记知识库（Vault）。

你只需提供「课件目录」和一个 MinerU Token，Claude 会自动完成 解析 → 选图 → 重构润色 → 落盘 → 质检 的整条流水线，产出结构化的 .md 笔记、配套 assets/ 配图，以及一张课程总览 MOC。

不是一个普通的「PDF 转 Markdown」工具。它会去粗取精地重写讲义内容、甄别并嵌入有信息量的示意图（数据通路图、流水线时空图、状态机、搜索树等）、对原图缺失的难点主动用表格/代码块自绘图解，并按 Obsidian 的 Callout、双链、LaTeX 规范排版。

它能做什么

📥 批量解析：基于 MinerU 云端 VLM 模型，把 PPT 原生矢量图（流水线图、电路图等）直接渲染成清晰位图，表格还原为 HTML、公式还原为 LaTeX、版面与标题层级一并还原。
🖼️ 智能选图：用「图片索引 → 接触表 → 放大核验」三级漏斗筛图，自动排除装饰碎片、二维码/签到码、logo 模板，只嵌入真正有信息量的图。
✍️ 重构而非搬运：按学习者视角重写内容，重难点处主动自绘代码图/表格（如流水线时空图、Cache 命中对比、补码算例、内存布局）。
🗂️ Obsidian 原生：YAML Frontmatter、Callout、[[双链]]、LaTeX 公式、00_课程总览_MOC.md 学习路线图一应俱全。
🔁 可靠落盘：超长课件分块追加防溢出，落盘后自动做零图自检、死链检查、Callout 表格渲染修复。

工作原理

源课件目录/*.pdf
      │
      ▼  scripts/mineru.py parse   （MinerU 云端：提交→轮询→下载→解压）
  _mineru/<课件名>/                 full.md · images/ · content_list.json
      │                            + 选图三件套（图片索引 / 接触表 / 核验拼图）
      ▼  Claude 读正文 + 三级漏斗选图 + 重构润色
  <课件名>_笔记.md  +  assets/<配图>
      │
      ▼  收尾质检（零图自检 / 死链 / Callout 修复 / MOC 索引）
  <源目录名>_Obsidian笔记/   ← 可直接用 Obsidian 打开的 Vault

核心脚本 scripts/mineru.py 只负责解析与选图辅助（确定性、可复现）；内容理解、选图决策、重写、排版由 Claude 在 Skill 指引下完成。

环境要求

依赖	说明
Claude Code	本项目是它的一个 Skill
Python ≥ 3.13	运行脚本
uv	依赖与运行环境管理
MinerU Token	云端解析必需，mineru.net 控制台「API 管理」页免费创建

Python 依赖仅两个：requests（调 API）、PyMuPDF（拼接触表/读图尺寸），由 uv 自动安装。

Windows 用户可用 scoop install python + uv 一键搞定；macOS / Linux 用系统 Python + uv 即可，脚本本身跨平台。

安装

把整个目录拷到 Claude Code 的 skills 目录即可（self-contained，零额外配置）：

# 项目级（仅当前项目可用）
git clone https://github.com/PhSeCl/pdf-courseware-to-obsidian \
    .claude/skills/pdf-courseware-to-obsidian

# 或 用户级（全局可用）
git clone https://github.com/PhSeCl/pdf-courseware-to-obsidian \
    ~/.claude/skills/pdf-courseware-to-obsidian

然后准备 Token（切勿写进任何文件或提交到 git）：

export MINERU_TOKEN="你的_token"      # bash / zsh
$env:MINERU_TOKEN = "你的_token"      # PowerShell

使用

在 Claude Code 里直接用自然语言触发即可，例如：

帮我把 D:\课程\人工智能原理 这个目录的课件整理成 Obsidian 复习笔记

Claude 会识别到本 Skill（触发词：整理课件、课件转笔记、PDF转笔记、Obsidian笔记、复习笔记、讲义整理），向你确认源目录、输出目录与 Token，然后静默跑完整条流水线，最后汇报总结。输出默认落在 <源目录名>_Obsidian笔记/。

手动调用脚本（可选）

脚本也能脱离 Claude 单独跑：

# 列出目录下所有可解析课件
uv run python scripts/mineru.py --list "源课件目录"

# 解析（云端较慢，建议后台运行）
uv run python scripts/mineru.py parse "课件.pdf" --out "Vault目录" --token "$MINERU_TOKEN"

# 放大核验候选图
uv run python scripts/mineru.py inspect "p8_1,p33_1" --doc "Vault目录/_mineru/课件名"

# 把选中的图拷入 assets 并重命名
uv run python scripts/mineru.py collect --doc "Vault目录/_mineru/课件名" \
    --pick "p5_1,p9_1" --assets "Vault目录/assets"

命令	作用
`--list DIR`	列出目录下所有可解析课件
`parse FILES... --out DIR --token T`	提交→轮询→下载→解压→生成选图三件套
`fetch BATCH_ID --out DIR --token T`	凭 batch_id 断点续取（parse 超时后用）
`imgmap --doc DOC`	重新生成图片索引
`contact --doc DOC`	重新生成接触表
`inspect "p8_1,p33_1" --doc DOC`	放大核验若干候选图
`collect --doc DOC --pick "..." --assets DIR`	拷选中图入 assets 并重命名

常用参数：--model vlm|pipeline（默认 vlm）、--language ch、--page-ranges "1-200"（>200 页时必填，分段解析）、--timeout 1800。

限制与注意事项

隐私：课件会上传到 MinerU 云端解析。涉密 / 敏感资料请谨慎使用。
MinerU 配额：单文件 ≤ 200MB、≤ 200 页；单次批量 ≤ 50 个；每账号每天 1000 页最高优先级额度，超出降速。超 200 页课件需 --page-ranges 分段。
离线兜底：scripts/extract.py（PyMuPDF 本地提取）仅作无网络 / API 失败时的降级方案，质量低于 MinerU，正常流程不用。
不嵌入 mermaid：MinerU 会用 VLM 把图转 mermaid，但复杂图幻觉严重，本流程默认一律使用渲染位图。

完整的设计理念、图片甄别准则与流水线细节见 SKILL.md。

协议

MIT

PDF Courseware To Obsidian

README