PyMuPDF PDF Parser Clawdbot Skill

核心用法

PyMuPDF PDF 技能基于 PyMuPDF（fitz）库，提供轻量级的本地 PDF 解析能力。主要功能包括：

• 快速文本提取：将 PDF 内容转换为 Markdown（默认）或 JSON 格式
• 多媒体支持：可选提取图片到独立子目录，提取表格为简化 JSON
• 结构化输出：按文档创建独立输出文件夹，保持内容组织清晰

基础调用方式：

./scripts/pymupdf_parse.py /path/to/file.pdf --format md --outroot ./pymupdf-output

支持 --format md|json|both、--images、--tables 等选项，JSON 输出可包含语言元数据（--lang）。

显著优点

1. 速度优先：PyMuPDF 以高性能著称，解析速度快于多数重型 OCR 方案
2. 零外部依赖：纯本地处理，无需调用云端 API，保护数据隐私
3. 资源轻量：内存占用低，适合批量处理或资源受限环境
4. 输出灵活：同时支持人类可读的 Markdown 和机器友好的 JSON
5. 模块化设计：可作为重型解析器（如 MinerU）不可用时的可靠 fallback

潜在局限

1. 鲁棒性不足：在复杂排版、扫描版 PDF、特殊字体场景下表现弱于专业 OCR 工具
2. 表格识别粗糙：--tables 仅提供基于行的简单提取，非结构化表格可能失真
3. 格式保真度：复杂版式（多栏、图文混排）可能丢失原始布局信息
4. 依赖管理：需处理 PyMuPDF 安装及可能的 Nix 环境 libstdc++ 兼容问题

适合人群

• 需要快速原型验证或大批量预处理的开发者
• 处理标准文本型 PDF、对格式还原要求不高的场景
• 隐私敏感环境（本地离线处理为刚需）
• 已有重型解析器但需要轻量备用方案的团队

常规风险

| 风险类型 | 说明 |

|---------|------|

| 解析失败 | 加密/损坏 PDF 可能导致异常，需提前校验文件完整性 |

| 内容遗漏 | 复杂文档可能出现文本顺序错乱或内容丢失 |

| 环境冲突 | Nix 用户需参考 `pymupdf-notes.md` 解决库依赖问题 |

| 输出偏差 | 表格/图片提取结果需人工复核，不宜直接用于生产 |

建议在关键业务场景中，将本工具作为初筛或辅助手段，配合人工校验或重型解析器使用。

核心用法

pymupdf-pdf 是一款轻量级本地 PDF 解析技能，基于 PyMuPDF（fitz）库实现。核心操作通过单一命令完成：

./scripts/pymupdf_parse.py /path/to/file.pdf --format md --outroot ./pymupdf-output

支持三种输出格式（md/json/both），可选提取图片（--images）和简单表格（--tables）。输出遵循严格的目录约定：为每个 PDF 创建独立子目录，包含 output.md、output.json、images/ 和 tables.json。

显著优点

1. 极速本地处理：纯本地运行，无网络依赖，12.5 秒完成完整扫描验证，适合批量文档快速预处理
2. 零外部攻击面：安全报告六维全绿，无 API 调用、无 Telemetry、无敏感信息泄露
3. 灵活输出：Markdown 便于人工阅读，JSON 便于下游自动化，图片和表格按需提取
4. Apache 2.0 开源：协议友好，可审计性强，依赖 PyMuPDF 为 Artifex 维护的成熟库

潜在缺点与局限

1. 鲁棒性边界明确：官方文档坦承 "PyMuPDF is fast but less robust on complex PDFs"，复杂排版、扫描件、嵌套表格可能解析失败
2. 表格提取简易：--tables 基于行线检测，非结构化表格、跨页表格、合并单元格处理能力有限
3. T3 来源风险：维护者 kesslerio 为个人开发者，GitHub 仓库创建仅 4 个月，社区活跃度低，长期维护存疑
4. PDF 漏洞暴露面：虽然代码本身安全，但 PyMuPDF 作为 C 扩展库，理论上存在解析恶意 PDF 的内存漏洞风险（CVE 未检出但需警惕）

适合人群

• 开发者/自动化脚本编写者：需要快速、可编程的 PDF 文本提取流水线
• 本地隐私敏感用户：拒绝云端 OCR、要求数据不出本地环境
• 预处理和筛选场景：作为首道过滤器快速提取可解析文档，复杂文档再转交 MinerU 等重型工具

常规风险

• 处理来源不明 PDF 时建议容器/沙箱隔离
• 关注 PyMuPDF 上游安全公告，及时 pip upgrade
• 避免 --outroot 指向系统关键目录，防止路径遍历或文件覆盖
• 定期监控 GitHub 仓库更新动态，评估维护者响应能力