用途:当存在需要理解或处理的 .pdf 文件时触发,例如用户附上 PDF 并提问、要求摘要、提取特定数据或表格,或批量处理文件夹内多个 PDF。PDF 是排版/打印格式,不能可靠地按纯文本读取,因此应先用本技能脚本转为 Markdown,而非直接打开或解析。
主要能力:脚本位于 scripts/convert_pdf_to_md.py,基于 MarkItDown 提取文本和表格,并用 PyMuPDF 单独提取真实嵌入图片,按文档生成自包含文件夹:<name>/img/ 与 <name>.md。由于 MarkItDown 的 PDF 文本不保留可靠的逐页标记,图片无法安全内联,脚本会在 Markdown 末尾追加“## Extracted Images”章节,按“### Page N”分页列出,需与该正文分开阅读;若无嵌入图片则不生成 img/ 与图片章节。
使用方式:单文件执行 python scripts/convert_pdf_to_md.py "C:\path\to\document.pdf",默认在源文件旁生成同名文件夹,含 document.md 及可能的 document\img\。可用 -o 指定输出目录。批量处理文件夹:python scripts/convert_pdf_to_md.py "C:\path\to\folder",加 --recursive 包含子文件夹;每个 .pdf 默认在旁生成同名输出文件夹,也可用 -o 汇总到指定父目录。首次使用前需按 references/setup.md 安装 Python、pip、markitdown 及 pymupdf。输出默认必须放在源文件旁,除非用户明确要求其他位置,否则不要传 -o。若源路径无法完整解析,应先用 ask_user 确认完整绝对路径,切勿猜测。混合类型文件夹中,本技能只处理 .pdf,须并行调用 convert-word-to-md 处理 .docx、convert-excel-to-md 处理 .xlsx,不得静默跳过受支持类型。
适用场景:单份或多份 PDF 的问答、摘要、数据与表格提取;与其他转换技能配合处理混合文档集。
限制:仅支持 .pdf。错误码方面,缺少模块返回 exit code 2,非 PDF 或不支持类型、路径不存在返回 exit code 3;批量中失败文件会单独报告,其余仍成功。扫描版或纯图片 PDF 无文本层时 Markdown 可能近乎为空,MarkItDown 不做 OCR,可告知用户不支持 OCR,但提取出的页面图片仍可查看。图片位于附录而非正文内联是已知设计限制。本技能只负责生成准确的 Markdown 与图片,不负责解释内容。