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

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

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

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

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

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

SQLite 数据库不会整库倒出来，而是先给你一份“结构速览”：每张表的建表语句、行数、前五行，外加索引、视图和触发器清单。它是只读打开的（mode=ro&immutable=1），所以别的进程正占着这个库也能读、不用加锁；想看更多细节，直接在终端用 sqlite3 查就行。要是 .db 文件其实不是 SQLite（magic bytes 对不上），Agent 会直接告诉你真实原因。另外，Hermes 自己的读取黑名单会在提取之前生效，HERMES_HOME 下受保护的存储照样读不到。

另外，read_file 还会顺手提醒你没解决的 git 合并冲突：如果读到的内容里有成对的 <<<<<<< / >>>>>>> 标记，结果里会带上 conflict_blocks: N，并建议你先解决冲突再改代码（字符串或测试样例里孤零零一个标记不算）。

转换结果会以 Markdown 格式输出，并且支持翻页阅读。超过 50 MB 的文件会被拒绝，这是为了防止一次处理太多内容导致卡顿。顺便说一句，东亚文字的注音（比如 XLSX 的 rPh、DOCX 的 ruby 文本）只是标注，不算正文内容——单元格里写着“東京”配注音“トウキョウ”，读出来就是“東京”。Jupyter 笔记本里超过 2 万字符的输出会被截断，截断提示里会附一条 jq 命令，命令里带着笔记本完整的、经过 shell 转义的路径，方便你回原文件把完整内容捞出来。

第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 $TMPDIR/page

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

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

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

小提示

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

---

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

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