文档提取

read_file 工具会自动把常见文档格式转换为可读文本，让 agent 能像阅读源代码一样查看 PDF 或电子表格。

支持的格式

* 可选转换器即 firecrawl-anydoc 包，在允许安装处惰性安装（config.yaml 中的 security.allow_lazy_installs）。没有它时，三种标准库格式仍可用；其他格式回退到二进制文件保护机制。

SQLite 文件以 schema 概览形式呈现，而非整库 dump：每张表的 CREATE 语句、行数和前五行，加上索引、视图和触发器列表。数据库以只读方式打开（mode=ro&immutable=1，因此即使另一进程正打开着一个活动数据库，也能不加锁地读取）；如需预览之外的操作，请从终端用 sqlite3 查询。一个并非 SQLite 的 .db（魔数不匹配）会被拒绝，并给出真实原因。Hermes 自身的读取黑名单在提取之前生效，因此 HERMES_HOME 下受保护的存储保持不可读。

read_file 还会标记未解决的 git 合并冲突：当返回区间内包含成对的 <<<<<<< / >>>>>>> 标记行时，结果会附带 conflict_blocks: N，并提示在围绕其编辑前先解决冲突。字符串或测试夹具中孤立的单个标记不计入。

转换输出为 Markdown，通过 read_file 常规的 offset/limit 窗口分页。东亚注音（XLSX rPh、DOCX 旁注文字）用于标注单元格或 run 文本，不属于提取值的一部分：一个含 東京 且注音为 トウキョウ 的单元格读取为 東京。超过 50 MB 的文档会被拒绝，以保证工具调用轮次有界。

笔记本单元格输出超过 20,000 字符会被截断；截断标记附带一条 jq 命令，给出笔记本完整且经 shell 转义的路径，从而可从原文件取回被省略的输出。

提取可与远程终端后端（Docker、Modal、SSH）协同工作：文件字节跨后端边界传输并在主机侧转换，因此沙箱内的文档与本地文档读取结果一致。

扫描版 PDF：覆盖范围警告

PDF 转换只读文本层。扫描图像页面——常见于法律文件、二手交易包、已签署合同、传真——不含文本层，会静默地转换为空。典型特征是小节标题下正文为空。

当有相当比例的页面无法产出文本（超过文档的 20%，或绝对页数 10 页以上），read_file 会在提取结果前附加一条警告。每个不可读缺口都会用其前最后提取到的文本标注——通常是一个小节分隔符——这样 agent 只需针对它真正需要的缺口，而不必对整份文档做 OCR：

[提取覆盖范围警告：本 PDF 共 311 页，其中 198 页未产出文本。……
不可读缺口，每个均以其前最后提取到的文本标注：
  第 42-77 页（36 页）——位于 "Antigua Maintenance Corp Bylaws" 之后（第 41 页）
  第 92-213 页（122 页）——位于 "... Covenants, Codes and Regulations" 之后（第 91 页）
  第 224 页（1 页）——位于 "... Insurance Declaration Pages" 之后（第 223 页）
请判断你实际需要哪些缺口——不要对全部内容做 OCR 或渲染。……]

警告列出确切的页码区间和恢复路径：

1. 少量页面——渲染 + 视觉。 将页面转为图像并用视觉工具读取：

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

   然后用 vision_analyze 检查每张图像。无需额外依赖（检测本身需要 poppler）。

2. 大量页面——OCR。 ocr-and-documents skill 涵盖基于 marker-pdf 的批量 OCR（90+ 种语言，可处理公式和表格；约 3-5 GB 安装）。

检测使用 poppler 的 pdftotext 统计每页文本量。若未安装 poppler，提取仍可进行——覆盖范围检查会被静默跳过。