SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pdf-to-markdown

pdf-to-markdown

办公与效率

查看项目

更新于 10-16 02:04

技能介绍

用途

pdf-to-markdown 用于把 PDF 转换为经过校验的整篇 Markdown 文档，同时保留原 PDF 作为视觉权威。默认输出与源文件同名的 Markdown（例如 report.pdf 对应 report.md）。除非用户明确指定了消费方，否则不保留解析器 JSON、坐标、提取资源或分块。

主要能力

  • 使用 Xberg 解析器生成整篇文档 Markdown。
  • 支持韩文扫描页 OCR（通过 --korean-ocr，使用 PaddleOCR 并显式选择韩文，仅对分类为扫描件的页面做 OCR，其余保留原生文本）。
  • 支持版面恢复（通过 --layout，附加 --layout-strategy auto --use-layout-for-markdown）。
  • 原子写入输出文件，保留源 PDF，拒绝空或结构不一致的输出，且不调用 shell。
  • 校验 Xberg 的页面记录是否构成连续的从 1 开始的序列，并与其声明的页数一致。
  • 当 Xberg 对分类为空白页的页面省略标记时，从页面元数据恢复这些标记，同时保持 Xberg 的 Markdown 正文不变。
  • 页面标记启用时，通过 --config-json 提供随机化的私有标记，之后仅将这些私有标记转换为 <!-- PAGE n -->。

使用方式

  1. 解析每个源 PDF 和预期输出路径。多个 PDF 逐个处理，以便独立校验每个结果。
  2. 如果预期输出已存在，仅在用户明确授权替换该确切文件时使用 --overwrite；缺少授权则在转换前停止。不要自行发明替代目标路径。
  3. 检查 xberg 可执行文件是否存在。若缺失，识别当前主机平台的官方安装方法，并在需要时请求用户批准。不要在该批准之外运行安装脚本、包管理器或模型下载预热。
  4. 相对于本 SKILL.md 解析 scripts/convert_pdf.py 并运行：
python3 scripts/convert_pdf.py /absolute/path/report.pdf

韩文扫描页：

python3 scripts/convert_pdf.py /absolute/path/report.pdf --korean-ocr

版面恢复对比（输出到临时文件）：

python3 scripts/convert_pdf.py /absolute/path/report.pdf \
  --output /absolute/path/report.layout.md \
  --layout
  1. 每次转换后校验：检查 Markdown 的开头、中间和结尾，核对标题、段落顺序、表格、列表、代码、韩文（如预期）、数字、日期、缺失页、可疑重复、乱码和密度突变。阅读包装器的校验摘要，报告物理页、非空白页和空白页计数，以及恢复的空白页标记数量。
  2. 如果普通提取丢失阅读顺序、标题、表格、列表或图形位置，用 --layout 重跑到临时对比文件，比较内容保真度后，仅在用户有覆盖授权时替换预期输出。不要假设更大的输出更好。
  3. 如果韩文 OCR 仍遗漏或损坏内容，仅当原生文本层是原因时才用 --force-ocr 重试。对于仍不可靠的复杂视觉页面，报告失败页面并提供 Docling 或 document-VLM 对比，而不是静默切换工具或安装另一个解析器。

适用场景

  • 为智能体生成可读的文本产物。
  • 需要将 PDF 转换为整篇 Markdown 并保留 PDF 作为视觉参照。
  • 处理含韩文扫描页的 PDF。
  • 需要版面恢复以保留阅读顺序、标题、表格、列表和图形位置。

限制

  • 不要通过拼接逐页 Markdown 来重建文档，因为这会重置列表并破坏跨页结构。
  • 不要用直接 shell 重定向替代包装器来创建最终产物。
  • 不要仅因为 PDF 语言是韩文就对其做 OCR；仅当整个文档是纯图像或其文本层明显损坏时才使用 --force-ocr。
  • 首次使用 PaddleOCR 可能作为所请求转换的一部分下载模型；当网络使用或模型存储在当前环境中很重要时，应在开始前告知用户。
  • 如果 Python 不可用但 Xberg 存在，可检查 scripts/convert_pdf.py 并用可用运行器复现其命令构造和校验，保持相同的非覆盖、临时输出、非空结果和原子最终化保证；若无法保持这些保证，应停止并报告缺失的能力。
  • 如果版面提取报告 ONNX Runtime API 不匹配，应将其视为原因，即使后续 worker 消息说 Mutex poisoned。在 Windows 上，检查是否加载了较旧的 C:\Windows\System32\onnxruntime.dll。仅在用户授权下将 ORT_DYLIB_PATH 指向兼容运行时；不要静默安装或替换系统库。此失败后包装器不发布部分版面输出。
  • 重复的 pdf_oxide dictionary-as-stream 警告会被汇总而非转储；它们意味着畸形或不寻常的 PDF 对象被当作空流处理，因此当保真度不确定时应检查附近的视觉内容。包装器还会以有界输出报告 Xberg 的结构化处理警告，应将其视为页面或管道特定的保真度风险进行检查。

完成条件

仅当 Markdown 存在、非空、通过代表性源检查且源 PDF 保持不变时才完成。报告 PDF 和 Markdown 路径、Xberg 版本、使用的 OCR 或版面选项、物理/非空白/空白页计数、恢复的标记数量、汇总的解析器警告、任何经用户明确授权覆盖的文件，以及任何仍不确定的页面或结构。