第33篇：文档提取——扫描件秒变文字

这篇讲的是：Hermes Agent 如何把 PDF、Word、Excel 等文档自动“读”成纯文本，以及遇到扫描件时怎么聪明地只补读缺失的那几页。

你有没有遇到过这种情况——收到一份合同扫描件，想复制里面的文字却只能得到一张张图片？Hermes Agent 的 read_file 工具就是为了解决这个问题而生的。它就像一位全能翻译官，能把各种格式的文档“翻译”成 Agent 能看懂的纯文本。

第1步：认识这位翻译官能处理哪些格式

格式	扩展名	说明
Jupyter 笔记本	`.ipynb`	内置支持，开箱即用
Word 文档	`.docx`	内置支持，开箱即用
Excel 表格	`.xlsx`	内置支持，开箱即用
PDF	`.pdf`	首次使用自动安装转换器
旧版 Office	`.doc`、`.ppt`、`.xls` 等	同上
OpenDocument	`.odt`、`.ods`、`.odp`	同上
富文本/电子书	`.rtf`、`.epub`	同上

内置支持意味着开箱即用；自动安装则是在第一次使用时，Agent 会悄悄装好一个叫 firecrawl-anydoc 的小工具（前提是你在 config.yaml 里允许了 security.allow_lazy_installs）。

转换结果会以 Markdown 格式输出，并且支持翻页阅读。超过 50 MB 的文件会被拒绝，这是为了防止一次处理太多内容导致卡顿。

第2步：扫描件的问题——只有图像，没有文字

PDF 转换时只读取文字层。扫描件本质上是一张张图片，里面根本没有文字层，所以转换出来是空的。怎么识别这种情况？看标题：如果章节标题下面空空如也，那这一节很可能就是扫描图片。

当超过 20% 的页面（或绝对超过 10 页）没有提取到文字时，Agent 会在结果前面加一段覆盖率警告，像这样：

[提取覆盖率警告：此 PDF 中 311 页里有 198 页没有提取到文字... 
  无法读取的空白段（每段标注了之前提取到的最后文字）：
    第 42-77 页（36 页）—— 在 "Antigua Maintenance Corp Bylaws" (第41页) 之后
    第 92-213 页（122 页）—— 在 "... Covenants, Codes and Regulations" (第91页) 之后
  请判断你真正需要的空白段——不要 OCR 或渲染全部内容...]

第3步：按需补读，而不是盲目全扫

情况A：只有几页缺失 → 渲染 + 视觉识别

用 poppler 工具把缺失的页码转成图片：

pdftoppm -jpeg -r 150 -f 92 -l 94 document.pdf /tmp/page

然后用 vision_analyze 工具逐张查看这些图片。这个方法不需要额外安装什么，poppler 本身也是检测功能需要的。

情况B：很多页缺失 → 批量 OCR

如果缺失页很多，就用 ocr-and-documents 技能做批量识别。它基于 marker-pdf，支持 90 多种语言，还能处理公式和表格，不过需要大约 3-5 GB 的安装空间。

小提示

如果没装 poppler，提取功能照样能用，只是覆盖率检查会被悄悄跳过。
Agent 会自己处理这个警告——它会主动提出渲染或 OCR 缺失的页面。如果你自己在读提取结果，看到“有标题但没内容”的段落，就当作扫描件处理，别以为是文档缺页。

总结一下：read_file 让 Agent 能像读代码一样读各种文档，遇到扫描件时会聪明地只补读缺失的部分，而不是盲目把整本 PDF 都 OCR 一遍。

下篇预告：文档读进来了，怎么让 Agent 在大量文本里快速找到关键信息？下一篇我们聊聊“智能搜索”功能。