第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 在大量文字裡快速找到關鍵資訊？下一篇我們聊聊「智慧搜尋」功能。