mcpField
P
pdf-to-markdown

pdf-to-markdown

github.com/sjunepark文档处理150 次安装3 周前更新
代码仓库

关于 pdf-to-markdown

pdf-to-markdown 是将 PDF 转为经过验证的 Markdown 文件的技能，同时保留源 PDF 作为视觉依据。它通过转换封装脚本检查页结构和输出，并提供版面提取及韩语 OCR 选项。

主要功能

  1. 01为每个 PDF 创建对应 Markdown
  2. 02验证页序与转换结果
  3. 03支持复杂结构的版面提取
  4. 04识别扫描版韩语页面
  5. 05保留源 PDF 并防止未授权覆盖

适用场景

  1. 01将 PDF 转成 Markdown 以便后续编辑
  2. 02提取含扫描韩语页面的 PDF 文本
  3. 03阅读顺序不清时比较版面提取结果

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sjunepark/agent-scripts --skill pdf-to-markdown

安装后在 Claude Code 中输入/pdf-to-markdown确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
evals/
evals.json
test_convert_pdf.py
scripts/
convert_pdf.py

详细介绍

PDF 转 Markdown

生成经过验证的 Markdown 同级文件，同时以 PDF 作为视觉权威。默认使用 report.pdf 和 report.md；除非用户指定了使用方，否则不要保留解析器 JSON、坐标、提取的资源或分块。

安全转换

  1. 确认每个源 PDF 和预期输出路径。一次处理一个 PDF，以便分别验证每个结果。

  2. 如果预期输出已存在，只有在用户明确授权替换该特定文件时才使用 --overwrite。如果缺少此授权，请在转换前停止。不要擅自另选目标路径；只有用户选择或批准其他路径时才可使用。

  3. 检查是否存在 xberg 可执行文件。如果不存在，查找适用于当前主机平台的官方安装方法，并遵循适用的用户审批流程；仅在尚未获得审批时请求审批。未经审批，不要运行安装脚本、包管理器或模型下载预热操作。

  4. 根据此 SKILL.md 的位置解析 scripts/convert_pdf.py，然后运行：

    python3 scripts/convert_pdf.py /absolute/path/report.pdf

    此封装脚本会以原子方式写入 report.md，保留 PDF，拒绝空输出或结构不一致的输出，并且绝不调用 shell。它会请求 Xberg 返回 JSON，以便验证每个物理页面，但只发布 Xberg 的整篇文档 Markdown，且不保留解析器 JSON。

    启用页面标记时，封装脚本还会通过 --config-json 传入随机生成的私有标记；之后只会将这些私有标记转换为 ``。直接回退方案必须使用具有同等抗冲突能力的私有标记，而不是在验证期间使用公开的页面注释。

    封装脚本会验证 Xberg 的页面记录是否构成连续的 1 起始序列，并与其声明的页数一致。如果 Xberg 未为其判定为空白的页面输出标记，封装脚本会从页面元数据中恢复这些标记，同时保持 Xberg 的 Markdown 正文不变。如果标记与页面元数据无法对应，封装脚本会拒绝发布。不要通过拼接逐页 Markdown 来重建文档，因为这可能导致列表重置，并破坏跨页结构。创建最终产物时，不要用直接的 shell 重定向替代封装脚本。

  5. 对于包含扫描版韩文页面的 PDF，添加 --korean-ocr。此选项会明确选择韩文并使用 PaddleOCR，仅对判定为扫描版的页面执行 OCR，同时保留其他页面中的原生文本：

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

    首次使用 PaddleOCR 时，可能会在所请求的转换过程中下载模型。如果网络使用或模型存储会对当前环境造成重大影响，请在开始前告知用户。

不要仅因为 PDF 的语言是韩文，就对原生数字版 PDF 执行 OCR。只有在整份文档都是图像，或其文本层明显损坏时，才使用 --force-ocr；处理韩文文档时，还要同时使用 --korean-ocr。

如果无法使用 Python，但存在 Xberg，请检查 scripts/convert_pdf.py，并使用可用的运行器复现其命令构造和验证流程，同时保留相同的防覆盖、临时输出、非空结果和原子化最终处理保障。如果无法保留这些保障，请停止并报告缺少的能力。

验证并升级处理

每次转换后：

  1. 检查 Markdown 的开头、中间和结尾。检查标题、段落顺序、表格、列表、代码、预期出现的 Hangul、数字、日期、缺失页面、可疑的重复内容、乱码，以及内容密度的突变。

  2. 阅读包装器的验证摘要。其中会报告物理页数、非空页数和空白页数；如果数量非零，还会报告恢复了多少个空白页标记。若具备 PDF 检查能力，请将此总数与独立统计的 PDF 页数进行比较。空白页可以确实不含文本，但除非请求了 --no-page-markers，否则最终 Markdown 中仍必须有对应标记。 重复出现的 pdf_oxide 字典流警告会汇总显示，而不是全部列出；这表示格式错误或特殊的 PDF 对象被视为空流，因此在保真度无法确定时，请检查附近的视觉内容。包装器还会以有限的输出报告 Xberg 的结构化处理警告；请将其视为特定页面或处理流程的保真度风险，并进行检查。

  3. 如果常规提取丢失了阅读顺序、标题、表格、列表或图表位置，请使用 --layout 重新运行，并输出到临时对比文件：

    python3 scripts/convert_pdf.py /absolute/path/report.pdf \
  --output /absolute/path/report.layout.md \
  --layout

    这会在常规 Xberg 命令中添加 --layout --layout-strategy auto --use-layout-for-markdown。

    比较内容保真度；只有获得用户授权覆盖时，才替换指定输出文件。不要假设输出越大越好。如果布局提取报告 ONNX Runtime API 不匹配，即使后续工作线程消息提示 Mutex poisoned，也应将其视为根本原因。在 Windows 上，检查是否加载了较旧的 C:\Windows\System32\onnxruntime.dll。只有获得用户授权后，才可将 ORT_DYLIB_PATH 指向兼容的运行时；不得擅自安装或替换系统库。发生此故障后，包装器不会发布部分布局输出。

  4. 如果韩语 OCR 仍遗漏或损坏内容，仅当原因是原生文本层时，才使用 --force-ocr 重试。对于仍无法可靠处理的复杂视觉页面，请报告出错页面，并提出使用 Docling 或文档 VLM 进行对比；不要擅自切换工具或安装其他解析器。

完成

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

评论

支持 Markdown