mcpField
P
pdf-to-markdown

pdf-to-markdown

github.com/pspdfkit-labs文档处理18833 次安装1 周前更新
代码仓库

关于 pdf-to-markdown

面向 Agent 和文档工作流的 PDF 转 Markdown 技能，支持批量转换、可选图像导出，并可用 Vision 处理扫描件和纯图像 PDF。

主要功能

  1. 01将 PDF 转为结构化 Markdown
  2. 02并行处理输入目录中的文件
  3. 03将图像导出到 Markdown 旁
  4. 04用 Vision 处理扫描件和复杂版式
  5. 05搜索已保存的结果，避免重复转换

适用场景

  1. 01转换报告并保留标题和表格
  2. 02批量转换文件夹中的 PDF
  3. 03用 Vision 提取扫描文档内容
  4. 04搜索大型转换文档

安装

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

$npx skills add https://github.com/pspdfkit-labs/nutrient-skills --skill pdf-to-markdown

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

附带文件bin/nutrientbin/pdf-to-markdown

详细介绍

Agent 规则

  • 每个 PDF 只转换一次，并保存结果。搜索已保存的文件，而不是再次转换。
  • 对于已知术语，先使用限定范围的搜索，例如 grep -n -i -C2 "term" file | head。
  • 如果不知道准确措辞，或普通搜索返回太多结果，请使用 query 技能。
  • 当空白和列对齐比 Markdown 结构更重要时，请使用 pdf-to-text。
  • 不要将 PDF 页面渲染为图像来提取可选择的文本。对于扫描件和仅含图像的 PDF，请使用 Vision。

PDF 转 Markdown

将 PDF 转换为 Markdown，同时保留标题、表格、列表和阅读顺序。

相关技能

  • pdf-to-text — 在纯文本中保留空白和列对齐。
  • query — 搜索大型转换文件，并仅返回最相关的段落。

用法

将 SKILL_DIR 设置为包含此文件的目录的绝对路径。在以下命令中使用 $SKILL_DIR/bin/pdf-to-markdown。

此封装脚本首次运行时会从 Nutrient 的 CDN 下载 CLI，并将其存储在 ~/.local/share/nutrient/cli/。它每六小时检查一次更新。

转换一个 PDF
$SKILL_DIR/bin/pdf-to-markdown INPUT.pdf OUTPUT.md

省略 OUTPUT.md 可将 Markdown 写入标准输出。

转换多个 PDF

对于两个或更多 PDF，请传入一个输入目录和一个输出目录。CLI 会并行转换这些文件。

$SKILL_DIR/bin/pdf-to-markdown INPUT_DIR/ OUTPUT_DIR/
导出图像

添加 --enable-image-export，即可将图像保存到 Markdown 输出文件旁边，并在文件中添加指向这些图像的链接。

$SKILL_DIR/bin/pdf-to-markdown --enable-image-export INPUT.pdf OUTPUT.md

图像存储在 {output}_resources/ 中。默认关闭图像导出，因为处理图像较多的 PDF 时会增加工作量。

使用 Vision

Vision 可处理扫描件、照片、手写内容、公式和复杂布局。

$SKILL_DIR/bin/pdf-to-markdown --vision INPUT.pdf OUTPUT.md

标准转换免费且无需账户。Vision 需要 Nutrient 账户、API 密钥或 Nutrient CLI 许可证密钥。使用账户或 API 密钥时，每个输入页面会占用账户月度额度中的一个 Vision 页面。Nutrient CLI 许可证密钥沿用现有条款。转换失败不会消耗 Vision 页面。

如果 Vision 要求使用账户，请向用户显示该消息，并让他们运行：

$SKILL_DIR/bin/nutrient auth login

不要自动开始登录。未经身份验证，不要重试 Vision。

如需无人值守使用，用户可以设置 NUTRIENT_API_KEY。绝不要要求用户在聊天中粘贴密钥，也不要让他们将密钥直接写入命令。

账户命令
$SKILL_DIR/bin/nutrient auth login
$SKILL_DIR/bin/nutrient auth status
$SKILL_DIR/bin/nutrient auth logout

status 会显示当前套餐、Vision 访问权限以及等待上报的用量。除非用户提出要求，否则绝不要退出登录或切换账户。

工作流

  1. 选择 Standard 或 Vision。除非 PDF 是扫描件或仅含图像，否则从 Standard 开始。
  2. 转换 PDF 一次，并检查退出代码。退出代码为 0 表示成功。
  3. 检查输出文件是否存在且非空。
  4. 告知用户输出文件的保存位置。
  5. 除非用户希望分析大型输出文件，否则不要将其读回上下文。请使用限定范围的 grep 或 query 技能搜索。

离线行为

Nutrient 不可用时，Standard 仍可继续工作。Vision 连接后，可离线工作一小时，并处理最多 100 页，之后必须重新连接。超过 100 页阈值的文档仍可完成处理。

故障排查

  • 输出为空或内容很少： PDF 可能是扫描件或纯图片文件。请提供 Vision。
  • Vision 要求登录： 显示 CLI 消息，并让用户运行 $SKILL_DIR/bin/nutrient auth login。不要先重试。
  • Vision 页面额度已用完： 显示 CLI 消息和定价页面。不要重试或更改账户状态。
  • Standard 转换期间出现凭据错误： 显式配置的密钥或已保存的登录信息无效。显示错误。除非用户要求，否则不要移除或替换凭据。
  • 首次运行较慢： 包装程序会下载一次平台二进制文件。之后的运行会使用缓存副本。
  • 其他非零退出： 阅读标准错误并报告具体错误。常见原因包括 PDF 已损坏、加密方式不受支持或首次运行下载失败。

方案与许可

Standard 转换免费。使用账户或 API 密钥时，Vision 会使用账户的每月额度。Nutrient CLI 许可证密钥沿用现有条款。请参阅当前方案。

使用须遵守 Nutrient PDF to Markdown 许可证和 Nutrient 的隐私政策。再分发、OEM、嵌入式和白标用途需要与 Nutrient 另行签订协议。

评论

支持 Markdown