pdf-to-markdown

用途

pdf-to-markdown 用于把 PDF 内容转换为结构化 Markdown，保留标题、表格、列表和阅读顺序，适合后续分析或接入 AI 工作流。当用户需要从 PDF 中获取文本或 Markdown 时，可以使用该技能。

主要能力

将 PDF 转换为 Markdown，保留标题、表格、列表和阅读顺序。
支持单个 PDF 转换，也支持传入输入目录与输出目录，由 CLI 并行转换多个 PDF。
可通过 --enable-image-export 导出图片，图片保存在 {output}_resources/ 目录，并在 Markdown 中链接；该选项默认关闭，因为对图片较多的 PDF 会增加工作量。
提供 Vision 模式，处理扫描件、照片、手写、公式和复杂版式。
相关技能：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/

导出图片：

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

使用 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 访问权限和待上报的使用量。除非用户要求，不要退出登录或切换账户。

适用场景与限制

适用于需要从 PDF 提取结构化 Markdown 的通用场景，包括批量转换。
对于已知术语，可先用有界搜索，例如 grep -n -i -C2 "term" file | head。
当不确定确切措辞或普通搜索返回过多匹配时，使用 query 技能。
当空白和列对齐比 Markdown 结构更重要时，使用 pdf-to-text。
不要将 PDF 页面渲染为图片来提取可选中文本。对扫描件和纯图片 PDF 使用 Vision。

离线行为

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

故障排除

输出为空或极少：PDF 可能是扫描件或纯图片。建议使用 Vision。
Vision 要求登录：展示 CLI 消息并请用户运行 $SKILL_DIR/bin/nutrient auth login。不要先重试。
没有剩余 Vision 页数：展示 CLI 消息和定价页面。不要重试或更改账户状态。
Standard 转换期间凭据错误：显式配置的密钥或已保存登录无效。展示错误。除非用户要求，不要移除或替换凭据。
首次运行较慢：包装脚本会下载平台二进制文件一次，之后使用缓存副本。
其他非零退出：读取 stderr 并报告具体错误。常见原因包括 PDF 损坏、不支持的加密或首次运行下载失败。

计划与许可

Standard 转换免费。使用账户或 API 密钥时，Vision 使用账户的每月配额。Nutrient CLI 许可证密钥沿用原有条款。请查看当前计划。使用受 Nutrient PDF to Markdown License 和 Nutrient 隐私政策约束。再分发、OEM、嵌入和白标使用需要与 Nutrient 另行签订协议。

技能介绍

用途