pdf-to-markdown

PDF 转 Markdown 转换器

使用 IBM Docling AI 将 PDF 的完整内容提取为结构化 Markdown，并保留：

• 标题（根据字体大小检测，并转换为 # 标签）
• 粗体、斜体、等宽字体格式
• 表格（使用 TableFormer AI 模型进行高精度提取）
• 列表（有序和无序）
• 多栏布局（保持正确的阅读顺序）
• 代码块
• 图像（提取后复制到输出文件旁，并使用相对路径）

何时使用此技能

在以下情况使用此技能：

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

环境设置

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

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

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

验证安装

~/.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 docling docling-core)

第 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 会被积极缓存，以避免重复处理。首次提取速度较慢（每页约 1 秒），此后每次请求都会即时完成。

工作原理

• 缓存位置：~/.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

图像处理

始终会提取图像。图像会：

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

图像的自动查看行为

**重要：**当提取的 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:
  --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

性能

• 首次提取：每页约 1 秒（Docling AI 处理）
• 首次运行：下载 AI 模型（一次性约 500MB）
• 缓存提取：即时完成
• 高分辨率图像：默认分辨率的 4 倍，确保输出清晰

故障排除

“No module named docling”或 venv 不存在

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

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

提取质量不佳

对于扫描版 PDF，请确保已安装 Tesseract OCR：brew install tesseract

表格格式不正确

此技能使用 IBM 的 TableFormer AI 模型，该模型对复杂表格的准确率约为 93.6%。如果表格仍然杂乱，PDF 可能采用了特殊格式。