文書からの本文抽出

read_file ツールは、よく使われる文書の形式を自動で読める文字に変換します。おかげでエージェントは、ソースコードを読むのと同じ感覚で PDF や表計算の中身を確かめられます。

対応している形式

\* 追加の変換器は firecrawl-anydoc パッケージで、導入が許可されている場合にだけその場で入ります（config.yaml の security.allow_lazy_installs）。入っていなくても標準ライブラリで扱う3形式は動きますが、それ以外の形式はバイナリとして読み込みを断られます。

SQLite のファイルは中身をそのまま吐き出すのではなく、構造の見取り図として表示されます。テーブルごとの CREATE 文、行数、先頭5行に加えて、索引・ビュー・トリガーの一覧が並びます。データベースは読み取り専用で開かれるので（mode=ro&immutable=1。ほかのプロセスが開いたままの稼働中のデータベースでも、ロックをかけずに読めます）、この下見より先を知りたいときはターミナルから sqlite3 で問い合わせてください。中身が SQLite ではない .db（先頭の識別バイトが合わないもの）は、その理由をそのまま添えて断られます。抽出の前に Hermes 自身の読み取り禁止一覧が効くので、HERMES_HOME の下にある保護された保管場所は読めないままです。

read_file は、未解決のまま残った git の衝突箇所も教えてくれます。読み出した範囲に <<<<<<< と >>>>>>> の目印の行が対になって含まれていると、結果に conflict_blocks: N と、その周辺を編集する前に衝突を解消するようにという助言が付きます。文字列の中やテストの用例に目印が単独で現れているだけのものは数えません。

変換後の出力は Markdown で、read_file が普段使う offset／limit の窓で区切って読み出せます。東アジア圏のふりがな（XLSX の rPh、DOCX のルビ）はセルや文字列に付いた注記であって、取り出す値そのものではありません。トウキョウ というふりがなの付いた 東京 というセルは 東京 として読み出されます。50 MB を超える文書は、ツールの1回のやり取りが膨らみすぎないよう受け付けません。

ノートブックのセル出力は 20,000 文字を超えると途中で切られます。切った印には jq のコマンドが添えられ、そこにノートブックの絶対パスがシェル用に引用された形で入っているので、省かれた出力は元のファイルから取り出せます。

抽出は離れた場所のターミナル（Docker、Modal、SSH）でも働きます。ファイルの中身が実行先の境界をまたいで運ばれ、手元の側で変換されるので、サンドボックスの中にある文書も手元のものと同じように読めます。

画像として取り込まれた PDF：読み取り率の警告

PDF の変換が読むのは文字の層だけです。紙を取り込んだ画像のページ（法律文書、不動産の売買資料、署名済みの契約書、FAX でよくあります）には文字の層がなく、何も出てこないまま静かに変換が終わります。見分けどころは、見出しはあるのに中身が空になっていることです。

読み取れないページが無視できない割合になったとき（文書全体の20%超、または実数で10ページ以上）、read_file は抽出結果の先頭に警告を付けます。読み取れなかった空白のかたまりには、その直前に取り出せた文字（多くは節の区切り）が目印として添えられるので、エージェントは文書全体を OCR にかけず、本当に必要な箇所だけを狙えます。

[EXTRACTION COVERAGE WARNING: 198 of 311 pages in this PDF yielded no
text. ... Unreadable gaps, each labeled with the last text extracted
before 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. ...]

警告には、正確なページの範囲と、そこから中身を取り戻す方法が並びます。

1. 数ページなら、画像にして目で読む。 ページを画像に変換し、画像を扱うツールで読ませます。

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

そのうえで各画像を vision_analyze で確かめます。追加で入れるものはありません（そもそも検出のために poppler が必要です）。

1. 多くのページなら、OCR。 ocr-and-documents スキルが marker-pdf を使った一括 OCR を扱います（90 以上の言語に対応し、数式や表も処理できます。導入には 3〜5 GB ほど必要です）。

検出にはページごとの文字数を数えるため poppler の pdftotext を使います。poppler が入っていない場合も抽出そのものは動き、読み取り率の確認だけが静かに省かれます。