pdf2md

---
name: pdf2md
description: "将任意 PDF 高质量转换为 Markdown（保留表格、LaTeX 公式、图片、多栏布局与标题层级），基于 OpenDataLoader PDF（Benchmark #1 准确率）；支持单文件与批量文件夹、fast/hybrid 双模式、扫描件 OCR，自动处理大文件分页。触发场景：PDF 转 Markdown、PDF 转 md、提取 PDF 正文/表格/公式/图片、扫描版 PDF 识别 OCR、批量转换 PDF、为 RAG / AI 工作流解析 PDF；convert PDF to markdown, extract PDF tables or formulas, OCR a scanned PDF。用法：/pdf2md <pdf路径> [--output=<输出目录>] [--mode=fast|hybrid] [--ocr] [--ocr-lang=<语言>] [--formula] [--charts] [--no-images]"
user-invocable: true
version: "1.0.0"
---

# pdf2md: PDF 转 Markdown 铸造器

## Purpose

把一个 PDF 文件或一整个 PDF 文件夹转成可直接用于 AI / RAG 工作流的 Markdown：正文、表格、
LaTeX 公式、图片与标题层级一站式还原，并额外产出带边界框坐标的结构化 JSON 与处理摘要。
底层由 `scripts/pdf2md.py` 驱动 OpenDataLoader PDF。

## When to Use

- 用户要把 PDF 转成 Markdown / 纯文本 / 结构化 JSON。
- 用户要从 PDF 里提取表格、公式或图片，或需要溯源坐标。
- 用户要批量转换一个目录下的多个 PDF。
- 用户要处理扫描版 PDF（需要 OCR）。
- 触发词：PDF 转 Markdown、pdf 转 md、PDF 提取文字/表格/公式、扫描件 OCR、批量转换 PDF、
  pdf2md、convert PDF to markdown、extract PDF tables/formulas。

## When NOT to Use

- 简单数字版 PDF、只需快速读一遍内容 -> 当前模型可直接读取该 PDF 并输出 Markdown，
  不必安装 OpenDataLoader 工具链（见 `references/upstream.md` 的「备选方案」）。
- 要处理的是 Word / PPT / HTML 等非 PDF 格式 -> 用各自的转换路径，不是本技能。
- 目标是把 PDF 内容纳入本地互链知识库 -> 优先用 `obsidian-kb-builder`。
- 用户只想看 PDF 的某几页摘要、不要结构化产物 -> 直接读取并回答。

## Workflow

1. **前置检查**：`java -version`（需 11+）、`python3 --version`（需 3.10+）、
   `pip show opendataloader-pdf`。也可直接跑 `python3 <skill>/scripts/pdf2md.py --check`。
   缺依赖时脚本会自动安装；也可显式 `--install`。
2. **选模式**：按 `## Decision Rules` 决定 `fast` 还是 `hybrid`，以及是否需要
   `--ocr` / `--formula` / `--charts`。
3. **执行转换**：

```bash
python3 <skill>/scripts/pdf2md.py <PDF路径|文件夹> [--output=<目录>] [-m fast|hybrid] [--ocr --ocr-lang=ch_sim] [--formula] [--charts] [--no-images]
```

4. **核对输出**：确认输出目录里有 `*.md`、`*.json`、`summary.json`、`images/`，
   且图片数量与 `summary.json` 一致。结构与样例见 `examples/sample-output.md`。
5. **报告结果**：给出实际输出目录与文件清单（取自 CLI 打印与 `summary.json`，不要臆测路径）。

## Decision Rules

**模式选择**：

- 简单数字版 PDF、无复杂表格 -> `--mode=fast`（默认，约 0.05s/页，无额外依赖）。
- 复杂/无边框表格、多栏布局、公式、图表描述、扫描件 -> `--mode=hybrid`。
- 批量目录内 PDF 超过 10 个 -> `--mode=hybrid`；实测量级与准确率见 `references/performance.md`。

**附加开关**：

- 扫描版 PDF -> `--ocr`（必须与 `hybrid` 同用）；中文用 `--ocr-lang=ch_sim`，
  另支持 `ch_tra` / `ja` / `ko`，默认 `en`。
- 需要 LaTeX 公式 -> `--formula`（hybrid 模式）。
- 需要图表 AI 描述 -> `--charts`（hybrid 模式）。
- 不需要图片 -> `--no-images`（默认提取图片）。
- hybrid 后端端口被占用 -> `--port`（默认 5002）。

**失败分流**：

- 内存不足 -> 降级到 `fast`（CLI 会自动做，并在日志中提示）。
- 加密 PDF -> 停止，要求用户先解密；不要尝试绕过。
- 表格错乱 / 公式异常 / 扫描件识别差 / 图片缺失 -> 读 `references/troubleshooting.md`。
- 需要装依赖或核对上游出处 -> 读 `references/upstream.md`。

## Constraints

- **环境硬要求**：Java 11+ 与 Python 3.10+。缺任一者无法转换，先修环境再说。
- **hybrid 是独立进程**：它要求额外的 `opendataloader-pdf[hybrid]` 依赖，并占用一个本地端口；
  后端 30 秒内探活失败时 CLI 会自动回退到 fast，此时必须在报告里说明"实际用的是 fast"。
- **不编造结果**：所有产出路径、页数、图片数量都必须来自 CLI 输出或 `summary.json`。
- **不绕过加密**：加密 PDF 直接返回失败并要求用户解密。
- 批量转换时不要并发跑多个 hybrid 后端实例抢同一端口。

## Verification

交付前逐项确认：

- [ ] `--check` 三项依赖（Java / Python / OpenDataLoader）全部通过。
- [ ] 输出目录包含 `*.md`、`*.json`、`summary.json`；需要图片时 `images/` 非空。
- [ ] 复杂表格 / 公式 / 扫描件场景使用了 `hybrid`（必要时叠加 `--ocr` / `--formula`）。
- [ ] 报告中给出的输出路径与文件名与实际磁盘一致。
- [ ] 若后端回退到 fast，已向用户说明。

## Output

- **Outcome**：转换后的 Markdown 主文件 + 带边界框坐标的结构化 JSON + `summary.json` 处理摘要
  + `images/` 图片目录，全部位于指定输出目录（默认 `~/Downloads/pdf2md-output/<文件名>/`）。
- **Done when**：`## Verification` 全部勾选，且输出目录结构符合 `examples/sample-output.md`。
- **Evidence**：CLI 成功退出（返回码 0）并打印 `✓ 转换完成!`；`summary.json` 与磁盘文件一致。

## References

按需加载，不要预先全读：

- `references/troubleshooting.md` — 转换报错或结果质量不达预期时读。
- `references/performance.md` — 选模式拿不准、或用户问速度/准确率时读。
- `references/upstream.md` — 安装依赖、核对上游出处与许可、或需要轻量替代方案时读。

## Examples

- `examples/sample-output.md` — 需要向用户展示输出长什么样，或核对输出结构时读。

## Scripts

- `scripts/pdf2md.py` — 唯一实现，覆盖环境检查、单文件/批量转换、hybrid 后端、OCR、公式、
  图片与表格后处理、失败重试。参数见 `--help`：位置参数 `input`（必填，PDF 或文件夹），
  `-o/--output`、`-m/--mode`、`--no-images`、`--ocr`、`--ocr-lang`、`--formula`、`--charts`、
  `--port`、`--check`、`--install`。成功返回码 0，失败 1，用户中断 130。

## Troubleshooting

- 表格格式错乱 -> `--mode=hybrid`。
- 扫描件识别率低 -> `--mode=hybrid --ocr --ocr-lang=ch_sim`。
- 内存不足 -> `--mode=fast`（CLI 亦会自动降级）。
- 图片未提取 -> 检查是否误加 `--no-images`，并确认 `images/` 目录存在。
- 公式不对 -> `--mode=hybrid --formula`。
- 中文乱码 -> 数字版应正常；扫描版加 `--ocr --ocr-lang=ch_sim`。
- 更多细节见 `references/troubleshooting.md`。

## Related Skills

- `obsidian-kb-builder` — 把 PDF 等素材摄入本地互链知识库（走 pandoc，与本技能互补）。