Extract PDF Text

核心用法

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 配置与异常处理指南。

核心用法

Extract PDF Text 是一款面向Agent的PDF文本提取技能，采用PyMuPDF（fitz）作为核心引擎，提供完全本地化的文档处理能力。用户可通过简单的Python代码实现PDF文本提取，支持三种输出格式：纯文本（get_text()）、结构化字典（get_text("dict")）和JSON格式（get_text("json")）。对于扫描版PDF，技能提供OCR集成指导，通过pytesseract实现图像文字识别。使用时需先安装PyMuPDF库，导入为fitz后即可操作文档对象，遍历页面提取内容。技能特别强调内存管理，要求显式调用doc.close()或使用with语句避免内存泄漏。

显著优点

该技能的最大优势在于纯本地处理架构：所有计算均在用户机器完成，无外部API调用，从根本上杜绝数据泄露风险。PyMuPDF作为成熟开源库，具备出色的解析速度和准确性，尤其擅长处理复杂版式文档和表格结构。技能文档详尽实用，涵盖从基础提取到OCR集成、密码保护PDF处理等完整场景，并贴心标注常见陷阱（如误对文本PDF执行OCR导致性能下降）。代码示例经过精心设计，包含智能检测机制（通过文本长度判断是否需要OCR），帮助用户自动选择最优处理策略。

潜在缺点与局限性

作为纯Markdown文档型Skill，其本质是使用指南而非封装工具——用户需自行编写和调试Python代码，对编程能力有一定要求。OCR功能依赖外部系统组件（tesseract-ocr），跨平台配置可能复杂，且扫描文档处理速度显著慢于文本PDF。此外，技能未提供批量文件处理、异步操作或内存优化的高级抽象，大规模文档处理时需用户自行实现分页加载等机制。来源可信度为T3级（个人开发者），虽经ClawHub平台发布，但缺乏企业级维护背书。

适合的目标群体

本技能最适合具备Python基础的技术型用户，包括数据分析师、研究人员、开发者以及需要自动化文档处理的办公人员。特别适合处理敏感PDF文档的场景（如法律合同、财务报表、医疗记录），因其本地化特性可满足严格的数据合规要求。对于仅需偶尔提取PDF内容的非技术用户，可能需要更简单的图形化工具；而对于需要企业级PDF处理方案的大规模生产环境，建议评估商业OCR服务或专用文档处理平台。

使用风险

常规风险主要包括依赖管理和性能考量：PyMuPDF版本兼容性、系统OCR引擎的安装配置可能带来环境配置负担；处理大型PDF或批量文件时需注意内存占用，建议实现分页处理逻辑。密码保护PDF需提供正确密钥，否则触发异常。尽管技能本身安全，但用户在实际应用中需确保运行环境可信，避免在公共机器处理敏感文档。总体而言，该技能风险可控，是安全优先场景下的可靠选择。