# Read

テキストでもドキュメントでも、あらゆるファイルを 1 つの `Read` で読む。拡張子から
フォーマットを自動判定し、Office / PDF / メールは内部の抽出ハンドラへ委譲する。

以前は `ReadExcel` / `ReadDocx` / `ReadPdf` / `ReadPPTX` / `ReadMsg` が独立ツールとして
存在したが、「どのリーダーを選ぶか」で誤りが起きやすかったため `Read` に統合した。
今はどのファイルでも `Read({ file_path })` を呼べばよい。

> 画像ファイル（.png / .jpg / .gif / .webp / .bmp / .tif 等）は **Read では開けない**。
> VLM で内容を見る `ReadImage` を使う（意味的に別物のため統合していない）。

## フォーマット自動判定

| 拡張子 | 委譲先の抽出 | 返るもの |
|--------|--------------|----------|
| `.txt` / `.md` / `.csv` / コード等のテキスト | Read 本体（行 / バイト読み） | 生テキスト |
| `.xlsx` / `.xlsm` | Excel 抽出 | シートのセル値（＋任意で装飾） |
| `.docx` | Word 抽出 | 本文＋表 |
| `.pdf` | PDF 抽出 | ページ単位テキスト（＋任意で検索） |
| `.pptx` | PowerPoint 抽出 | スライドのテキスト・表・ノート |
| `.msg` | Outlook メール抽出 | 件名 / 送受信者 / 本文、添付は `input/` に保存 |

> 旧バイナリ Office（`.xls` / `.doc` / `.ppt` の CFB 形式）は**直接抽出できない**。
> Read すると「`.xlsx` / `.docx` / `.pptx` として保存し直してください」と案内されるので、
> 変換してから読む（`.xlsm` / `.docm` / `.pptm` のマクロ有効形式は読める）。

不透明なバイナリ（.zip / .exe / .db / 音声 / 動画 等）や、先頭バイトがバイナリと判定
されたファイルは拒否する（LLM コンテキスト破壊を防ぐため）。

## 共通パラメータ（inline schema）

| パラメータ | 説明 |
|-----------|------|
| `file_path` | workspace 内の相対 / 絶対パス（必須） |
| `offset` | 読み始める行番号（0-indexed）。**行数以上を指定するとエラー**。**テキストと `.msg` 本文のみ有効**（PDF/Office に渡すと**エラーになり本文は返らない**） |
| `limit` | 読む最大行数。**テキストと `.msg` 本文のみ有効**（PDF/Office に渡すと**エラーになり本文は返らない**） |
| `byte_offset` | 読み始めるバイト位置。改行の無い巨大ファイル向け。**ファイルサイズ以上を指定するとエラー**。`offset` / `limit` と排他。テキスト読みのみ有効（PDF/Office/`.msg` に渡すとエラー） |
| `byte_length` | 読むバイト数。`byte_offset` と併用。テキスト読みのみ有効（PDF/Office/`.msg` に渡すとエラー） |
| `page_range` | **PDF のページ範囲 / PowerPoint のスライド範囲**（例 `5-10` / `3`）。途中から / 一部だけ読むときは `offset` ではなくこれを使う。**実在しないページ・スライドを指すとエラー**。PDF と PowerPoint 専用（テキストファイルに渡すとエラー） |

大きすぎる出力は残コンテキスト予算に収まるよう自動で切り詰められ、続きの読み方が
注記される。

> **範囲指定は形式ごとに専用**。合わない組み合わせは **エラーになり、本文は一切返らない**。
>
> | 読むもの | 使うパラメータ |
> |---|---|
> | テキスト | `offset` / `limit`（行）、`byte_offset` / `byte_length`（バイト） |
> | PDF | `page_range` / `query` |
> | Excel | `sheet` / `range` |
> | Word | `max_paragraphs` |
> | PowerPoint | `page_range`（PDF と同じ名前） |
> | `.msg` | `offset` / `limit`（**抽出した本文の行**） |
>
> 以前は合わない指定でも注記を添えて本文を返していたが、注記が読み飛ばされて
> 先頭部分だけを「全部」と扱う事故が起きていたため、拒否に変えた（#1009）。
> テキストにドキュメント用の指定を渡す逆向きは注記すら出なかった（#1041）。
> どちらもエラー本文に、その形式で使うべきパラメータが書いてある。

### 範囲外の位置を指したとき（#1170）

`offset` がファイルの行数以上、または `byte_offset` がファイルサイズ以上のとき、
`Read` は **エラーを返す**。以前は行指定なら空文字列を、バイト指定なら「範囲外」という
文を、どちらも成功として返していたため、「読めたが中身が空だった＝まだ続きがある」と
誤解する事故が起きていた。

エラー本文には **指定した位置** と **そのファイルの実際の行数 / バイト数** が入る。
続きが要る場合の手順はこの通り。

| 何が起きたか | 次にやること |
|---|---|
| `offset` が行数以上 | エラー本文の行数を上限として、`0` 以上その値未満で指定し直す |
| `byte_offset` がサイズ以上 | エラー本文のバイト数未満で指定し直す |
| そもそも全体を読みたい | `offset` / `byte_offset` を外して呼び直す（自動切り詰めが効く） |

境界の扱いも書いておく。

| 場合 | 結果 |
|---|---|
| `offset` = 行数（末尾ちょうど。読める行が 1 行も無い） | エラー |
| 空ファイル（0 行）に `offset: 0` | エラー（`0 行` と返る） |
| 空ファイルを `offset` 無しで読む | 成功（空文字列） |
| `offset` は範囲内で `limit` が余る | 成功（読めた分だけ返る） |
| 末尾が改行のファイル（`a\nb\n` は **2 行**）に `offset: 2` | エラー |

## フォーマット固有の詳細オプション（inline schema には無いが実行時に受理される）

`Read` はこれらを **raw のまま抽出ハンドラへ素通し**する。inline schema を軽く保つため
一覧には出していないので、必要なときはここを見て指定する。

### Excel（.xlsx / .xlsm）
| オプション | 説明 |
|-----------|------|
| `sheet` | シート名（省略時は全シート） |
| `range` | セル範囲（例 `A1:D10`、省略時はシート全体） |
| `max_cells` | 最大セル数（デフォルト 1000）。**ブック全体の合計**で数える |
| `include_styles` | `true` で背景色 / フォント / 罫線 / 書式 / 結合を `### Styles` として追記（デフォルト false） |
| `max_style_ranges` | `include_styles` 時の style range 上限（デフォルト 250） |

出力の先頭には、ブックにあるシートの一覧（名前・行数・列数・読めたかどうか）が
`## Sheets` として必ず載る。`max_cells` はブック全体の合計なので、1 枚目で使い切ると
2 枚目以降は 1 セルも読まれない。その場合、一覧のそのシートは `NOT READ` になり、
途中で切れたシートには最後に読めたセルの番地が付く（#1165）。

> 一覧を先頭に置くのは、末尾が出力の文字数上限とトークン持ち分の両方で
> 切られるため。以前は落ちたシートが出力に一切現れず、受け取った側からは
> 1 枚しか無いブックに見えていた。

### Word（.docx）
| オプション | 説明 |
|-----------|------|
| `mode` | `text` / `text+tables`（デフォルト `text+tables`） |
| `max_paragraphs` | 最大段落数（デフォルト 200） |

### PDF（.pdf）
| オプション | 説明 |
|-----------|------|
| `page_range`（別名 `pageRange`） | ページ範囲（例 `1-5` / `3`、省略時は全ページ）。inline schema にも公開済み |
| `max_pages` | 抽出する最大ページ数 |
| `max_chars` | 返却する最大文字数（デフォルト 8000） |
| `query` | 指定するとマッチしたページのみを `grep -n` 風（周辺行付き）で返す |
| `query_mode` | `substring`（既定・大小無視の部分一致）/ `regex`（大小区別）/ `iregex`（大小無視の正規表現） |
| `context_lines` | `query` マッチ時の前後コンテキスト行数（デフォルト 2、最大 20） |

スキャン PDF（テキスト無し）は `PdfToImages` で PNG 化してから `ReadImage` で読む。

### PowerPoint（.pptx）
| オプション | 説明 |
|-----------|------|
| `page_range` | スライド範囲（例 `2-4` / `3`、省略時は全スライド）。inline schema にも公開済み |

スライドの範囲は PDF のページ範囲と**同じ `page_range`** で指定する。形式ごとに別の
名前を覚えなくてよい。

`page_range` を外せば全スライドが返る。外した場合を除いて**黙って全体を返すことはない**。

| 渡したもの | 結果 |
|---|---|
| 実在するスライドを含む範囲（`2-3`、`4`） | その範囲だけ返す |
| 実在しないスライドだけを指す範囲（5 枚のファイルに `9-10`） | **エラー**。本文に実際の枚数（`presentation has 5 slide(s)`）が入る |
| 書式が読めない範囲（`abc` / `2-` / 空文字列 / 数値） | **エラー**（`Invalid page_range: ...`）。以前は黙って**全スライド**が返っていた |
| `offset` / `limit` / `byte_offset` / `byte_length` | **エラー**。`page_range` を使う |

範囲外・書式不正のときは本文を一切返さない。先頭だけ返して成功にすると、受け取った
側が「これで全部」と扱う（#1009 と同じ壊れ方）。

### Outlook メール（.msg）
| オプション | 説明 |
|-----------|------|
| `offset` | **抽出した本文**の読み始め行（0-indexed）。本文の行数以上を指定するとエラー |
| `limit` | 本文から読む最大行数 |

絞る単位を本文の行にしたのは、件名・送信者・宛先・添付の一覧が出力の骨格で、量を
食っているのが本文だけだからである（自動切り詰めも本文にしか掛かっていない）。
行なのでテキスト読みと同じ `offset` / `limit` をそのまま使う。

| 渡したもの | 結果 |
|---|---|
| `offset` / `limit`（本文の行数の内側） | ヘッダーと添付一覧は全件、本文はその範囲だけ返す |
| 本文の行数以上の `offset` | **エラー**。本文に実際の行数が入る。**添付も保存しない** |
| `byte_offset` / `byte_length` | **エラー**。`.msg` は OLE2 の複合ファイルで、ファイル上のバイト位置は抽出した本文と対応しない |

- 件名・送信者・宛先・本文を抽出する。
- 添付ファイルは `input/` に保存し、保存先パスを出力に列挙する。**範囲を絞っても
  添付の一覧は全件残す**（保存先パスは呼び出し側が必要とするため）。
- 読み取り専用フェーズ（verify 等、edit 不可）では添付を保存せず、その旨を注記する。
- ファイル名衝突時は `name-1.ext` のように連番で退避し、既存ファイルは上書きしない。

## 使用例

```
Read({ file_path: "input/report.md" })                       // テキスト
Read({ file_path: "input/sales.xlsx", sheet: "Q1", range: "A1:D20" })
Read({ file_path: "input/spec.docx", mode: "text" })
Read({ file_path: "input/manual.pdf", page_range: "5-10" })   // PDF の 5-10 ページ目
Read({ file_path: "input/manual.pdf", query: "認証", context_lines: 3 })
Read({ file_path: "input/deck.pptx", page_range: "2-4" })      // 2-4 枚目のスライド
Read({ file_path: "input/mail.msg" })                         // 添付は input/ へ
Read({ file_path: "input/mail.msg", offset: 100, limit: 50 })  // 本文の 100 行目から 50 行
Read({ file_path: "logs/huge.log", byte_offset: 0, byte_length: 4096 })
```

## 関連ツール
- `ReadImage` — 画像を VLM で読む（Read とは別ツール）
- `PdfToImages` — PDF の各ページを PNG 化（スキャン PDF の前処理）
- `SplitExcelSheets` / `SplitDocxSections` — 巨大な表計算 / 文書をシート / 章単位に分割