convert-pdf-to-md

将 PDF 转换为 Markdown

何时使用此技能

只要存在需要理解或处理的 .pdf 文件，就触发此技能——例如，用户附上了一个 PDF 并询问相关问题、想要摘要、想要提取特定数据或表格，或者想要处理同一文件夹中的多个 PDF。PDF 是一种版式/打印格式，无法可靠地作为纯文本读取，因此务必先使用此技能中的脚本将其转换为 Markdown，而不是尝试直接打开或解析该文件。

此技能仅支持 .pdf——这是 MarkItDown 唯一支持的 PDF 系列格式，所以这里不必担心旧版格式（不像 Word 的 .doc 或 Excel 的 .xls）。

混合文件类型： 当用户引用包含多种受支持文件类型（.pdf、.docx、.xlsx）的文件夹或文档集合时，此技能只处理 .pdf 文件。Agent 必须同时并行调用同级技能：

• convert-word-to-md 用于任何 .docx 文件
• convert-excel-to-md 用于任何 .xlsx 文件

绝不要在处理文件夹时静默跳过受支持的文件类型。当存在混合类型时，必须同时调用这三个技能。

设置（每个环境一次）

在给定环境中进行首次转换之前，请逐步遵循 references/setup.md，确保 Python、 pip、markitdown 和 pymupdf（用于图像提取）已安装。请主动执行此操作，而不是猜测环境是否已就绪——如果某个依赖项确实缺失，脚本本身也会失败并给出明确指向该文件的提示，所以如果你有理由确信设置已完成，也可以直接先尝试转换。

用法

转换脚本位于 scripts/convert_pdf_to_md.py。

输出结构： MarkItDown 的 PDF 转换器仅提取文本和表格——它完全无法识别嵌入图像。此脚本通过 PyMuPDF 单独提取真正的嵌入图像，并为每个文档写入一个自包含文件夹：

<name>/
    img/
        page001_img001.<ext>
        page002_img001.<ext>
        ...
    <name>.md

由于 MarkItDown 的 PDF 文本无法保留可靠的逐页标记，因此无法安全地确定图像在行内应处的确切位置。与其冒将图像放错到错误段落旁边的风险，脚本会在 Markdown 末尾追加一个 ## Extracted Images 部分，并为每个包含图像的页面添加一个 ### Page N 子标题——请将此部分与正文文本分开阅读。如果文档没有嵌入图像，则不会创建 img/ 文件夹或 Extracted Images 部分。

单个文件：

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf"

这会在源文件旁边创建一个 document\ 文件夹（包含 document.md，以及如果存在的话，document\img\）。若要显式控制目标文件夹：

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf" -o "C:\path\to\output_folder"

一个 PDF 文件夹（批处理模式）：

python scripts\convert_pdf_to_md.py "C:\path\to\folder"

添加 --recursive 以同时包含子文件夹：

python scripts\convert_pdf_to_md.py "C:\path\to\folder" --recursive

默认情况下，找到的每个 .pdf 都会在其旁边获得自己的 <name>\ 输出文件夹。传入 -o "C:\path\to\output_parent" 可将所有生成的 <name>\ 文件夹收集到单独的父目录下（与 --recursive 结合使用时，会保留子文件夹结构）。

转换后，请阅读生成的 .md 文件，以执行用户所要求的实际分析——脚本的职责只是生成准确的 Markdown（和图像），而不是解释内容。

决定输出位置

默认 — 始终输出到源文件旁边。 <name>/ 文件夹会创建在源 .pdf 所在的同一目录中。这是所有情况下都必须遵循的默认行为。除非用户明确要求其他位置，否则不要覆盖此设置。

仅在用户明确提供输出路径时（例如“将输出保存到 C:\output”、“把结果放到 D:\work”）才使用 -o。不要基于 Agent 的当前工作目录、会话状态文件夹或任何隐含位置来传递 -o。

如果无法完全解析源文件路径 —— 例如，用户只提供了没有目录的文件名，或者路径有歧义 —— 请在运行转换前使用 ask_user 确认完整的绝对路径。切勿猜测或假设目录。

故障排除

症状	可能原因	修复方法
ModuleNotFoundError: No module named 'markitdown' 或 'fitz' / 退出码 2	未安装 MarkItDown 或 PyMuPDF	按照 references/setup.md 操作
ERROR: Unsupported file type '...' / 退出码 3	不是 .pdf 文件	向用户询问正确的文件，或者如果是 .doc/.docx/.xlsx，改用相匹配的同系列技能
ERROR: Input path not found / 退出码 3	路径错误，或文件已移动	与用户确认正确路径
批量输出中出现 FAILED <file> -> ...	该特定文件已损坏、受密码保护，或以其他方式无法读取	报告哪些文件失败；批次中的其他文件仍会成功
NOTE: skipped N non-.pdf file(s)	文件夹中包含非 PDF 文件	符合预期 —— 这些文件会被有意忽略
尽管已提取图像，Markdown 正文为空或接近为空	PDF 是扫描件/纯图像，没有嵌入文本层；MarkItDown 不执行 OCR	告知用户不支持 OCR —— 提取出的页面图像仍可供其查看
图像出现在附录中，而不是与正文内联	有意限制 —— MarkItDown 的 PDF 文本没有可靠的逐页标记来将图像内联放置	符合预期的行为；如有需要，将 ### Page N 标题与周围文本上下文进行交叉参照