核心用法
Extract PDF Text 技能围绕 PyMuPDF（fitz）构建，提供从基础到高级的 PDF 文本提取工作流。核心操作遵循「打开文档 → 遍历页面 → 提取文本 → 关闭文档」四步模式，支持纯文本、结构化字典、JSON 三种输出格式。对于扫描件或图文混排文档，技能提供 OCR 检测逻辑：通过 page.get_text() 获取文本量，若少于 50 字符则判定为需 OCR 处理，避免在原生文本 PDF 上误用 OCR 导致效率损失。
代码示例覆盖完整生命周期管理，强调使用 doc.close() 或上下文管理器防止内存泄漏，并通过 sort=True 参数修正阅读顺序错误。安全层面明确约束：所有处理本地完成，禁止主动访问文件、外发数据或修改原始 PDF。
显著优点
1. 纯本地化执行：PyMuPDF 作为 C 扩展库无需网络依赖，满足敏感文档处理的合规要求
2. 多格式输出能力：原生支持 text/dict/json/raw/html 等提取模式，便于对接下游 NLP 或数据分析流程
3. 性能优异：C 语言底层实现，大文档处理速度显著优于纯 Python 方案
4. 版式感知：dict 模式保留字体、坐标、块级结构，适合表格与复杂布局的精细解析
潜在缺点与局限性
- OCR 能力间接依赖：核心库本身不含 OCR，需额外集成 pytesseract 等工具，增加部署复杂度
- 扫描件处理门槛：自动检测阈值（50 字符）为经验值，特殊场景需人工调参
- 密码保护处理：仅支持基础密码解密，高强度加密或证书加密需预处理
- 跨平台依赖：Windows 环境需处理 Tesseract 二进制分发，Linux 需管理系统级依赖
适合人群
| 用户类型 | 适用场景 |
|---------|---------|
| 开发者/数据工程师 | 构建文档解析流水线、批量提取财报/论文/合同文本 |
| 隐私敏感型企业 | 本地化替代云端 OCR 服务，满足数据不出境要求 |
| 学术研究人员 | 提取结构化元数据（字体、坐标）进行版式分析 |
| 自动化运维 | 日志报表 PDF 的文本化与全文检索构建 |
常规风险
| 风险类别 | 具体表现 | 缓释建议 |
|---------|---------|---------|
| 资源耗尽 | 超大 PDF（>10k 页）未分页处理导致内存溢出 | 采用生成器模式逐页 yield |
| OCR 误触发 | 图文混排页文字量少触发冗余 OCR | 结合图像特征（如 `get_images()`）二次判断 |
| 编码异常 | 非 UTF-8 嵌入式字体导致乱码 | 利用 PyMuPDF 的 `get_textbox()` 指定区域重试 |
| 依赖冲突 | 与系统 MuPDF 版本不兼容 | 隔离虚拟环境，锁定 PyMuPDF==1.23.x 系列 |
版本与维护
当前版本 1.0.2（2024），更新聚焦构建产物清理。技能由 Clawic 维护，通过 clawhub 生态分发，建议关注 ocr.md 与 troubleshooting.md 获取 OCR 配置与异常处理指南。