# 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）。**テキスト読みのみ有効**（PDF/Office では無視される） |
| `limit` | 読む最大行数。**テキスト読みのみ有効**（PDF/Office では無視される） |
| `byte_offset` | 読み始めるバイト位置。改行の無い巨大ファイル向け。`offset` / `limit` と排他。テキスト読みのみ有効 |
| `byte_length` | 読むバイト数。`byte_offset` と併用。テキスト読みのみ有効 |
| `page_range` | **PDF のページ範囲**（例 `5-10` / `3`）。PDF を途中から / 一部だけ読むときは `offset` ではなくこれを使う |

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

> **PDF/Office をずらして読むとき**: `offset` / `limit` / `byte_*` は**テキスト専用**で、
> PDF・Excel・Word・PowerPoint では黙って無視される（＝常に先頭から返る）。PDF は
> `page_range`、Excel は `sheet` / `range` を使うこと。これらのフォーマットに
> `offset` / `limit` を渡すと、出力の先頭に正しいパラメータへの誘導注記が付く。

## フォーマット固有の詳細オプション（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） |

### 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）
| オプション | 説明 |
|-----------|------|
| `slideRange` | スライド範囲（例 `1-5` / `3`、省略時は全スライド） |

### Outlook メール（.msg）
- 件名・送信者・宛先・本文を抽出する。
- 添付ファイルは `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", slideRange: "2-4" })
Read({ file_path: "input/mail.msg" })                         // 添付は input/ へ
Read({ file_path: "logs/huge.log", byte_offset: 0, byte_length: 4096 })
```

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