pdf-to-markdown

PDF 转 Markdown 转换器

将 PDF 的完整内容提取为结构化 Markdown，并保留：

• 标题（根据字体大小检测，并转换为 # 标签）
• 粗体、斜体、等宽字体格式
• 表格（转换为 Markdown 表格）
• 列表（有序和无序）
• 多栏布局（按正确顺序阅读）
• 代码块
• 图片（提取后复制到输出文件旁，并使用相对路径）

何时使用此技能

在以下情况使用此技能：

• 用户希望在上下文中包含“整个 PDF”或“完整文档”
• 分析、总结或讨论 PDF 内容
• 用户说“加载”“阅读”“导入”或“提取”PDF
• 使用 grep 或搜索会遗漏上下文或结构
• PDF 包含需要保留的表格、格式或结构

环境设置

此技能使用专用虚拟环境 ~/.claude/skills/pdf-to-markdown/.venv/，以避免污染用户的工作目录。

首次设置（如果 .venv 不存在）

# For fast mode only (PyMuPDF):
cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm

# For --docling mode (high-accuracy tables):
cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf docling docling-core

# Or install everything:
cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm docling docling-core

验证安装

# Verify fast mode:
~/.claude/skills/pdf-to-markdown/.venv/bin/python -c "import pymupdf; import pymupdf4llm; print('OK')"

# Verify docling mode:
~/.claude/skills/pdf-to-markdown/.venv/bin/python -c "import pymupdf; import docling; import docling_core; print('OK')"

快速入门

# Convert PDF to markdown (always extracts images)
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py document.pdf

# Output: document.md + images/ folder (next to the .md file)

标准工作流

用户提供 PDF 并希望在上下文中包含完整内容时：

步骤 1：确保技能的 venv 存在

test -d ~/.claude/skills/pdf-to-markdown/.venv || (cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm)

步骤 2：将 PDF 转换为 Markdown

~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py "/path/to/document.pdf"

步骤 3：读取输出

# Output is written to document.md in the same directory as the PDF
cat /path/to/document.md

缓存

PDF 会被积极缓存，以避免重复处理。首次提取较慢，此后的每次请求都能即时完成。

工作原理

• 缓存位置：~/.cache/pdf-to-markdown/<cache_key>/
• 缓存键：根据文件内容哈希值和提取模式生成
• 失效条件：以下情况会使缓存失效：
  • 源 PDF 已修改（大小或 mtime 发生变化）
  • 提取器版本发生变化（自动重新提取）
  • 使用 --clear-cache 或 --clear-all-cache 显式清除

缓存命令

# Clear cache for a specific PDF
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py document.pdf --clear-cache

# Clear entire cache
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py --clear-all-cache

# Show cache statistics
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py --cache-stats

缓存内容

~/.cache/pdf-to-markdown/<cache_key>/
├── metadata.json    # source path, mtime, size, total_pages
├── full_output.md   # cached full markdown
└── images/          # extracted images

图片处理

始终提取图片。图片会：

1. 缓存到 ~/.cache/pdf-to-markdown/<cache_key>/images/
2. 复制到输出 .md 文件旁的 images/ 文件夹
3. 在 Markdown 中通过相对路径（images/filename.png）引用
4. 在文档末尾的表格中汇总

图片的自动查看行为

**重要：**当提取出的 Markdown 包含如下图片引用时：

**[Image: figure_1.png (1200x800, 125.3KB)]**

如果用户询问的内容可能涉及视觉元素（图表、图形、示意图、插图、截图、布局、设计、绘图），请自动使用 Read 工具查看相关图片文件后再回答。不要询问用户，直接查看。

自动查看图片的示例：

• 用户：“第 3 页的图表展示了什么？”→ 读取图片文件
• 用户：“总结这篇论文中的图表。”→ 读取所有图片文件
• 用户：“示意图里有什么？”→ 读取图片文件
• 用户：“描述图中所示的架构。”→ 读取图片文件
• 用户：“结果是什么？”（且文中有结果图）→ 读取该图片

输出格式

Markdown 输出包括：

页眉（元数据）

---
source: document.pdf
total_pages: 42
extracted_at: 2025-01-15T10:30:00
from_cache: true
images_dir: images
---

带图片引用的内容

# Main Title

## Section Header

Regular paragraph text with **bold**, *italic*, and `code` formatting.

![Figure 1](images/figure_1.png)

**[Image: figure_1.png (800x600, 45.2KB)]**

| Column A | Column B |
|----------|----------|
| Data 1   | Data 2   |

图片汇总表（末尾）

---

## Extracted Images

| # | File | Dimensions | Size |
|---|------|------------|------|
| 1 | figure_1.png | 800x600 | 45.2KB |
| 2 | chart_2.png | 1200x800 | 89.1KB |

脚本参考

位置：~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py

Usage: pdf_to_md.py <input.pdf> [output.md] [options]

Options:
  --docling         Use Docling AI for high-accuracy tables (~1 sec/page)
  --no-progress     Disable progress indicator

Cache Options:
  --clear-cache        Clear cache for this PDF and re-extract
  --clear-all-cache    Clear entire cache directory and exit
  --cache-stats        Show cache statistics and exit

高精度模式（Docling）

对于包含复杂表格且需要高精度处理的 PDF，请使用 --docling 标志：

~/.claude/skills/pdf-to-markdown/.venv/bin/python \
    ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py \
    document.pdf --docling

适用 --docling 的情况：

• PDF 包含复杂表格（无边框、合并单元格、多栏）
• 表格准确性至关重要（医疗数据、财务报告）
• 默认模式下的表格输出出现乱码

权衡：

• 每页约需 1 秒（快速模式下则即时完成）
• 首次运行会下载 AI 模型（一次性约 500MB）
• 图片分辨率更高（默认值的 4 倍）

注意：--accurate 是 --docling 的别名。

故障排除

“No module named pymupdf4llm”或 venv 不存在

重新创建此技能的虚拟环境：

# For fast mode:
cd ~/.claude/skills/pdf-to-markdown && rm -rf .venv && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm

# For docling mode:
cd ~/.claude/skills/pdf-to-markdown && rm -rf .venv && uv venv .venv && uv pip install --python .venv/bin/python pymupdf docling docling-core

提取质量较差

• 对复杂表格尝试使用 --docling
• 对于扫描版 PDF，请确保已安装 Tesseract OCR：brew install tesseract

表格格式不正确

对于复杂表格，请使用 --docling 模式，该模式使用 IBM 的 TableFormer AI 模型。

与其他方法的比较

方法	适用场景	局限性
此技能（pymupdf4llm）	包含图像的完整文档上下文	大型 PDF 可能超出上下文限制
--docling 模式	复杂表格、医疗/金融 PDF	速度较慢（约 1 秒/页），模型较大
Grepping PDF	查找特定文本	会丢失结构，不包含图像
逐页提取	指定页面	需要手动操作，会丢失跨页上下文
使用 Read 工具读取 PDF	快速预览	格式保留有限