夜雨聆风
扫描PDF静默翻车？Hermes Agent覆盖率警告直接帮你标出198页盲区
🤖 AI Agent📖 工具拆解2026年8月11日
你有没有过这种经历：把一份PDF合同丢给AI，然后眼睁睁看着它"开始表演"——嘴上说在读，实际对着一堆二进制乱码现场编故事。我在这种坑里摔过不止一次，直到前两天翻 Hermes Agent 的官方文档，看到它的文档提取功能，差点拍大腿：这玩意儿读PDF、读Excel、读电子书，跟读源代码是一个姿势。
更绝的是，碰到扫描页这种"读不出字"的硬骨头，它不装、不编、不硬撑，而是直接甩给你一份覆盖率报告，把读不了的页码一段一段标得明明白白。有个例子里，一份311页的文档，它一口气标出了198页盲区。今天咱就把这个功能掰开了聊。
"The read_file tool automatically converts common document formats to readable text, so the agent can inspect a PDF or spreadsheet the same way it reads source code." —— read_file 工具会自动把常见文档格式转换成可读文本，agent 检查 PDF 和电子表格的方式，跟它读源代码一模一样。
─── ⋆⋅☆⋅⋆ ───
📱 格式清单：三个"原装"加四个"外挂"
整个功能的核心是 read_file 工具。它的格式支持清单，说白了就是"3+4"阵型：三个格式是出厂自带的，走纯标准库转换，任何时候都可用的那种——Jupyter 笔记本（.ipynb）、Word 文档（.docx）、Excel 工作簿（.xlsx）。
剩下四个属于"外挂扩展包"：PDF、老式 Office（.doc、.ppt、.xls、.pptx 及各种变体）、OpenDocument（.odt、.ods、.odp）、富文本和电子书（.rtf、.epub）。这些统一交给一个可选的 anydoc 转换器来干活，首次使用时自动安装。
📌 重点提示：这个"外挂"转换器是 firecrawl-anydoc 包，走的是"懒加载"路线——首次用到才自动安装，而且前提是 config.yaml 里的 security.allow_lazy_installs 允许安装。就算没装上也别慌：三个标准库格式照常工作，其他格式会回退到二进制文件防护，至少会明明白白告诉你"我读不了"，而不是假装读过。
─── ⋆⋅☆⋅⋆ ───
⚡ 两条硬规矩：输出Markdown，超50MB直接拒收
转换出来的东西统一是 Markdown，分页走 read_file 常规的 offset/limit 窗口——文档太长？那就跟翻书一样一页一页来，不会一次性把整本书糊你脸上。
还有一条红线：超过 50 MB 的文档直接拒收。官方给的理由特别实在：为了控制工具调用的回合数。毕竟谁也不想让 agent 啃一个附件啃一下午，token 烧得比外卖还快。
⚠️ 注意：50MB 以上的文档会被当场拒绝，没有商量余地。大文件请先拆分或瘦身再投喂，别让 agent 在门口就把你的附件退回来。
🌈 沙箱里也一样好使
这套提取在远程终端后端上同样成立：Docker、Modal、SSH 都支持。文件的字节会跨过后端边界传回来，在宿主机一侧完成转换。翻译成人话就是：扔在沙箱里的文档，读起来跟本地的一模一样，你完全不用换姿势。
─── ⋆⋅☆⋆ ───
🔥 扫描版PDF：最安静的坑
接下来是全篇最值钱的部分。PDF 转换只读文本层。而那些扫描成图片的页面——在法律文件、房产转售资料包、签过字的合同、传真件里简直不要太多——根本没有文本层，转换之后会静默地变成"无"。对，是静默，连个报错都不给你。
怎么识别？官方给了一个特征签名：章节标题下面空着正文。你看到一个小标题孤零零立在那儿、底下啥也没有，那多半不是内容缺失，而是整段被扫描了。
触发警告的阈值也写得很死：当超过 20% 的页面提取不出文本，或者绝对数量达到 10 页以上，read_file 就会在提取结果前面加一段覆盖率警告。更贴心的是，每个"读不了的缺口"都会贴上它前面最后一段提取到的文本——通常是某个章节分隔线——这样 agent 就能只盯着自己真正需要的缺口下手，而不是把整本书 OCR 一遍。
📊 官方实例：一份311页PDF的文本产出情况
常有文本页：113 页
看看官方文档里那段警告长什么样，你品品这个信息密度：
[EXTRACTION COVERAGE WARNING: 198 of 311 pages in this PDF yielded notext. ... Unreadable gaps, each labeled with the last text extractedbefore it:pages 42-77 (36 pages) — after "Antigua Maintenance Corp Bylaws" (p41)pages 92-213 (122 pages) — after "... Covenants, Codes and Regulations" (p91)page 224 (1 page) — after "... Insurance Declaration Pages" (p223)Decide which gaps you actually need — do NOT OCR or render everything. ...]
36页、122页、1页，每个缺口都挂着"前面最后读到的是什么"。这哪是报错，这简直是给你递了一张藏宝图，还是标好了"此处未探索"的那种。
─── ⋆⋅☆⋆ ───
🛡️ 补救指南：看菜吃饭，两条路线
警告里不光标了精确页码范围，还把恢复路径直接喂到嘴边。官方给了两条路线，按缺口大小对号入座：
🔷 几页的缺口：渲染加视觉，几分钟搞定
先把缺的那几页转成图片，官方给的命令长这样：
pdftoppm -jpeg -r 150 -f 92 -l 94 document.pdf /tmp/page然后拿 vision_analyze 一张一张看。这条路零额外依赖——poppler 是做检测本身就需要的东西，等于顺路就用上了，性价比拉满。
🔷 大片缺口：交给marker-pdf批量OCR
缺口上百页就别手动渲染了，直接上 ocr-and-documents 技能，底层是 marker-pdf：支持 90 多种语言，公式、表格都能处理。代价是安装体积约 3-5 GB——比不少游戏的资料片还大，装之前想清楚，别为了读一份传真把硬盘献祭了。
📌 重点提示：缺口检测靠的是 poppler 的 pdftotext 做逐页文本计数。如果没装 poppler，提取功能本身照样工作——但覆盖率检查会被静默跳过。也就是说：盲区还在，只是没人给你标出来了。
─── ⋆⋅☆⋆ ───
💡 结尾：AI敢说"我读不懂"，才是真的靠谱
原文里有个小 tip 我特别喜欢：agent 会自己处理这个警告——主动提出帮你渲染或 OCR 缺失的页面，全程不用你操心。如果你是自己人工阅读提取结果，请记住一句话：把"标题下面空着正文"当成扫描章节，而不是缺失章节。
💡 温馨提示：agent 看到覆盖率警告会自己接手，主动提议渲染或 OCR 缺失页。人工读提取结果时，看到"空正文标题"别急着骂内容残缺，那只是页面被扫描了而已。
聊到最后，我反而觉得这个功能最打动人的地方，不是它能读多少格式，而是它清楚地知道自己能力的边界在哪，还愿意把边界标给你看。读得了就读，读不了就精确告诉你哪几页读不了、该怎么补。这比那种"什么都懂"的AI，靠谱了一万个量级。
下次有合同、有报表、有扫描版老文件，尽管丢给 Hermes Agent 试试。记得先把 poppler 装上，让它把"体检设备"配齐再开工。😏