---

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. 执行转换：

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，与本技能互补）。