v1.0.0 to v1.0.0

88 added, 171 removed. Audit A to A.

---

name: pdf2md

- description: "将任意 PDF 文件高质量转换为 Markdown 格式。支持复杂布局、表格、公式、图片提取，自动处理大文件分页，提供多种输出模式。基于 OpenDataLoader PDF - Benchmark #1 准确率。使用方法: /pdf2md <pdf路径> [--output=<输出目录>] [--mode=fast|hybrid] [--extract-images=true|false] [--ocr-lang=<语言>]"

- user_invocable: true

+ 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 铸造器

- 基于 [OpenDataLoader PDF](https://github.com/opendataloader-project/opendataloader-pdf) 的高精度 PDF 解析工具，将 PDF 完美转换为 Markdown 格式，特别适合 AI/RAG 工作流。

- ## 核心优势

- - **业界最高准确率**：Benchmark #1，综合 0.90，表格 0.93，阅读顺序 0.94

- - **双模式架构**：本地模式(0.05s/页) + 混合模式(AI增强，复杂PDF专用)

- - **完整内容还原**：表格、LaTeX公式、图片、多栏布局、标题层级

- - **大文件友好**：自动分页处理，支持批量文件夹处理

- - **边界框坐标**：每个元素都有坐标，支持溯源引用

- ## 使用方法

- ```

- /pdf2md <PDF路径> [--output=<目录>] [--mode=fast|hybrid] [--extract-images=true|false] [--ocr] [--ocr-lang=<语言>]

- ```

- ### 参数说明

- | 参数 | 说明 | 默认值 |

- |------|------|--------|

- | `PDF路径` | 单个PDF文件或包含PDF的文件夹 | 必填 |

- | `--output` | 输出目录 | `~/Downloads/pdf2md-output/` |

- | `--mode` | 处理模式: `fast`(本地) 或 `hybrid`(AI增强) | `fast` |

- | `--extract-images` | 是否提取图片 | `true` |

- | `--ocr` | 强制启用OCR(扫描版PDF) | `false` |

- | `--ocr-lang` | OCR语言: `en`, `ch_sim`, `ch_tra`, `ja`, `ko` 等 | `en` |

- | `--formula` | 提取数学公式为LaTeX(hybrid模式) | `false` |

- | `--charts` | 生成图表AI描述(hybrid模式) | `false` |

- ## 前置检查

- 在使用前，必须验证环境是否就绪：

- ```bash

- # 1. 检查 Java 版本 (需要 11+)

- java -version

- # 2. 检查 Python 版本 (需要 3.10+)

- python3 --version

- # 3. 检查 OpenDataLoader 是否安装

- pip show opendataloader-pdf

- # 4. 检查 hybrid 模式依赖 (如果使用)

- pip show opendataloader-pdf[hybrid]

- ```

- ### 使用 pdf2md CLI 工具

- ```bash

- # 基础转换

- python3 pdf2md/pdf2md.py document.pdf

- # Hybrid 模式（高质量，支持复杂表格/公式）

- python3 pdf2md/pdf2md.py document.pdf --mode=hybrid

- # 扫描版PDF（带OCR）

- python3 pdf2md/pdf2md.py scan.pdf --mode=hybrid --ocr --ocr-lang=ch_sim

- # 学术论文（含公式）

- python3 pdf2md/pdf2md.py paper.pdf --mode=hybrid --formula

+ ## Purpose

- # 批量处理文件夹

- python3 pdf2md/pdf2md.py ./pdfs/ --mode=hybrid --output=./output/

+ 把一个 PDF 文件或一整个 PDF 文件夹转成可直接用于 AI / RAG 工作流的 Markdown：正文、表格、

+ LaTeX 公式、图片与标题层级一站式还原，并额外产出带边界框坐标的结构化 JSON 与处理摘要。

+ 底层由 `scripts/pdf2md.py` 驱动 OpenDataLoader PDF。

- # 检查环境

- python3 pdf2md/pdf2md.py --check

+ ## When to Use

- # 安装依赖

- python3 pdf2md/pdf2md.py --install

- ```

+ - 用户要把 PDF 转成 Markdown / 纯文本 / 结构化 JSON。

+ - 用户要从 PDF 里提取表格、公式或图片，或需要溯源坐标。

+ - 用户要批量转换一个目录下的多个 PDF。

+ - 用户要处理扫描版 PDF（需要 OCR）。

+ - 触发词：PDF 转 Markdown、pdf 转 md、PDF 提取文字/表格/公式、扫描件 OCR、批量转换 PDF、

+ pdf2md、convert PDF to markdown、extract PDF tables/formulas。

- ### CLI 参数说明

+ ## When NOT to Use

- ```

- 参数:

- input PDF文件或文件夹路径

+ - 简单数字版 PDF、只需快速读一遍内容 -> 当前模型可直接读取该 PDF 并输出 Markdown，

+ 不必安装 OpenDataLoader 工具链（见 `references/upstream.md` 的「备选方案」）。

+ - 要处理的是 Word / PPT / HTML 等非 PDF 格式 -> 用各自的转换路径，不是本技能。

+ - 目标是把 PDF 内容纳入本地互链知识库 -> 优先用 `obsidian-kb-builder`。

+ - 用户只想看 PDF 的某几页摘要、不要结构化产物 -> 直接读取并回答。

- 可选参数:

- -o, --output 输出目录 (默认: ~/Downloads/pdf2md-output)

- -m, --mode 处理模式: fast 或 hybrid (默认: fast)

- --no-images 不提取图片

- --ocr 启用OCR (扫描版PDF)

- --ocr-lang OCR语言 (默认: en, 可选: ch_sim/ch_tra/ja/ko)

- --formula 提取数学公式为LaTeX (hybrid模式)

- --charts 生成图表AI描述 (hybrid模式)

- --port Hybrid后端端口 (默认: 5002)

- --check 仅检查环境依赖

- --install 安装/更新依赖

- ```

- ### 自动安装

+ ## 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

- # 基础安装

- pip install -U opendataloader-pdf

- # 混合模式安装(推荐，支持OCR/公式/图表)

- pip install -U "opendataloader-pdf[hybrid]"

- ```

- ## 实现说明

- 完整实现见 `pdf2md/pdf2md.py`，上文「使用 pdf2md CLI 工具」一节已覆盖全部能力：环境检查、单文件/批量转换、混合模式后端、OCR、公式、图片与表格后处理、失败重试。

- **本技能不要求手动复现下方历史步骤说明**——直接调用 CLI 即可。如确需了解内部逻辑，以 `pdf2md.py` 源码为准（该脚本本身已包含上述全部步骤的实现，文档与源码不再重复维护，避免漂移）。

- ## 输出结构

- 转换完成后，输出目录结构如下：

- ```

- output/

- ├── document.md # 主Markdown文件

- ├── document.json # 结构化JSON（含边界框坐标）

- ├── summary.json # 处理摘要

- └── images/ # 提取的图片

- ├── image_001.png

- ├── image_002.png

- └── ...

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

```

- ### Markdown 示例输出

- ```markdown

- # 文档标题

- ## 第一章介绍

- 这是一段正文内容。OpenDataLoader 会正确保留**粗体**和*斜体*。

- ### 表格示例

+ 4. **核对输出**：确认输出目录里有 `*.md`、`*.json`、`summary.json`、`images/`，

+ 且图片数量与 `summary.json` 一致。结构与样例见 `examples/sample-output.md`。

+ 5. **报告结果**：给出实际输出目录与文件清单（取自 CLI 打印与 `summary.json`，不要臆测路径）。

- | 列1 | 列2 | 列3 |

- |-----|-----|-----|

- | A1 | B1 | C1 |

- | A2 | B2 | C2 |

+ ## Decision Rules

- ### 图片示例

+ **模式选择**：

- ![image](images/image_001.png)

+ - 简单数字版 PDF、无复杂表格 -> `--mode=fast`（默认，约 0.05s/页，无额外依赖）。

+ - 复杂/无边框表格、多栏布局、公式、图表描述、扫描件 -> `--mode=hybrid`。

+ - 批量目录内 PDF 超过 10 个 -> `--mode=hybrid`；实测量级与准确率见 `references/performance.md`。

- ### 数学公式

+ **附加开关**：

- 行内公式: $E = mc^2$

+ - 扫描版 PDF -> `--ocr`（必须与 `hybrid` 同用）；中文用 `--ocr-lang=ch_sim`，

+ 另支持 `ch_tra` / `ja` / `ko`，默认 `en`。

+ - 需要 LaTeX 公式 -> `--formula`（hybrid 模式）。

+ - 需要图表 AI 描述 -> `--charts`（hybrid 模式）。

+ - 不需要图片 -> `--no-images`（默认提取图片）。

+ - hybrid 后端端口被占用 -> `--port`（默认 5002）。

- 块级公式:

- $$

- \frac{f(x+h) - f(x)}{h}

- $$

+ **失败分流**：

- ## 第二章方法

+ - 内存不足 -> 降级到 `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 后端实例抢同一端口。

- ### Q: 转换后表格格式错乱

- **A**: 使用 `mode=hybrid`，它会自动处理复杂/无边框表格

+ ## Verification

- ### Q: 扫描版PDF识别率低

- **A**: 添加 `--ocr` 参数，并确保使用 `--mode=hybrid`

+ 交付前逐项确认：

- ### Q: 大文件内存不足

- **A**: OpenDataLoader 会自动流式处理，如遇内存问题，改用 `mode=fast`

+ - [ ] `--check` 三项依赖（Java / Python / OpenDataLoader）全部通过。

+ - [ ] 输出目录包含 `*.md`、`*.json`、`summary.json`；需要图片时 `images/` 非空。

+ - [ ] 复杂表格 / 公式 / 扫描件场景使用了 `hybrid`（必要时叠加 `--ocr` / `--formula`）。

+ - [ ] 报告中给出的输出路径与文件名与实际磁盘一致。

+ - [ ] 若后端回退到 fast，已向用户说明。

- ### Q: 图片没有正确提取

- **A**: 确保使用 `--extract-images=true`（默认开启），并检查输出目录的 images 文件夹

+ ## Output

- ### Q: 数学公式显示不正确

- **A**: 使用 `--mode=hybrid --formula`，公式会以LaTeX格式输出

+ - **Outcome**：转换后的 Markdown 主文件 + 带边界框坐标的结构化 JSON + `summary.json` 处理摘要

+ + `images/` 图片目录，全部位于指定输出目录（默认 `~/Downloads/pdf2md-output/<文件名>/`）。

+ - **Done when**：`## Verification` 全部勾选，且输出目录结构符合 `examples/sample-output.md`。

+ - **Evidence**：CLI 成功退出（返回码 0）并打印 `✓ 转换完成!`；`summary.json` 与磁盘文件一致。

- ### Q: 中文PDF乱码

- **A**: 数字PDF应正常显示，扫描版PDF使用 `--ocr --ocr-lang=ch_sim`

+ ## References

- ## 性能参考

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

- | 文档类型 | 模式 | 速度 | 准确率 |

- |---------|------|------|--------|

- | 简单数字PDF | fast | 20页/秒 | 0.72 |

- | 复杂表格PDF | hybrid | 2页/秒 | 0.93 |

- | 扫描版PDF | hybrid+OCR | 1页/秒 | 0.90+ |

+ - `references/troubleshooting.md` — 转换报错或结果质量不达预期时读。

+ - `references/performance.md` — 选模式拿不准、或用户问速度/准确率时读。

+ - `references/upstream.md` — 安装依赖、核对上游出处与许可、或需要轻量替代方案时读。

- ## 依赖说明

+ ## Examples

- - **Java 11+**: 解析引擎基于Java

- - **Python 3.10+**: Python接口

- - **OpenDataLoader PDF**: `pip install opendataloader-pdf`

- - **Hybrid模式额外依赖**: `pip install "opendataloader-pdf[hybrid]"`

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

- ## 相关链接

+ ## Scripts

- - [OpenDataLoader GitHub](https://github.com/opendataloader-project/opendataloader-pdf)

- - [官方文档](https://opendataloader.org/docs)

- - [Benchmark结果](https://github.com/opendataloader-project/opendataloader-bench)

+ - `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

- - **原生 PDF 读取**：对于简单的数字PDF文档，当前模型可直接读取 PDF 内容并输出 Markdown，无需安装 OpenDataLoader 工具链。适合快速处理少量简单文档。复杂表格、公式、扫描件仍需使用本技能的 hybrid 模式。

+ - 表格格式错乱 -> `--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`。

- ## License

+ ## Related Skills

- Apache 2.0 - 与 OpenDataLoader PDF 保持一致

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