# BrowseWeb 詳細ガイド ヘッドレスブラウザで Web ページを操作するツール。同一ジョブ内ではブラウザコンテキスト（Cookie・ログイン状態）が永続化される。 ログインが必要なサイト（X / 管理画面など）を継続的にスクレイピングするなら、保存済みログインセッションを使うとよい。詳細は `ReadToolDoc({ name: "BrowserSessions" })`（または [browse-sessions.md](./browse-sessions.md)）を参照。 ## 2 つのモード ### 1. 基本モード — URL を開いてテキスト取得 ```js BrowseWeb({ url: "https://example.com" }) ``` ローカルで生成した HTML をブラウザで確認したい場合は、workspace ルートからの **相対パス** をそのまま渡す（推奨）。 ```js BrowseWeb({ url: "output/viewer.html" }) ``` 例: - `output/viewer.html` を開く → `BrowseWeb({ url: "output/viewer.html" })` - `input/sample.html` を開く → `BrowseWeb({ url: "input/sample.html" })` 内部的には実行中ジョブの workspace 絶対パスと結合され `file://` URL に変換される。`../` で workspace 外に出るパスは拒否される。`file:///` で始まる絶対 URL を直接渡すことも可能だが、workspace 外を指すものは拒否される。 オプション: - `waitFor`: 待機する CSS セレクタ（省略時は load イベント完了まで待機） - `extractSelector`: 特定要素のテキストだけ抽出する CSS セレクタ - `screenshot`: スクリーンショットを保存するファイル名（例: `"page.png"` → `output/page.png`）。縦長ページは既定で分割保存（下記） - `screenshotSegments`: `false` で分割せずフルページ 1 枚（既定: 分割あり） - `screenshotMaxSegments`: 分割の最大枚数（既定 10） - `timeout`: タイムアウト（ms、デフォルト 60000） ### 2. アクションモード — 連続操作 ```js BrowseWeb({ actions: [ { type: "goto", url: "https://example.com/login" }, { type: "fill", ref: "e3", value: "user@example.com" }, { type: "click", ref: "e5" }, { type: "getText" } ] }) ``` 利用可能な `type`: - `goto` — `url` で指定したページに遷移 - `click` — `selector` または `ref` で要素をクリック - `fill` — `selector` または `ref` の input/textarea に `value` を入力 - `screenshot` — `value` で指定したファイル名で保存（省略時 `screenshot.png`）。縦長ページは既定で分割保存（下記）。`segments: false` でフルページ 1 枚、`maxSegments` で枚数上限を調整 - `getText` — 全ページのスナップショット（ref 注釈付き）または `selector` 内のテキストを取得 - `wait` — `ms` ミリ秒待機（最大 30000） - `dumpHtml` — `ref` または `selector`（省略時 body）の outerHTML を取得（脱出口、後述） ### スクリーンショットの分割保存 縦長ページを 1 枚で撮ると画像が極端に縦長になり、細部が潰れて読み取りづらくなる。BrowseWeb は既定で、ページを **1 画面ぶん（ビューポート高さ）ごとに区切って複数枚**に分割保存する。 - 1 画面に収まるページはそのまま `output/page.png` の 1 枚（連番なし） - 2 画面ぶん以上あるページは `output/page-001.png`, `output/page-002.png` … と連番で保存し、戻り値に全ファイルを列挙する - 無限スクロールなどの暴走を防ぐため、既定で最大 10 枚まで（`screenshotMaxSegments` / アクションの `maxSegments` で変更）。上限で打ち切った場合は戻り値にその旨を表示する - 分割せずフルページ 1 枚が欲しいときは `screenshotSegments: false`（基本モード）またはアクションの `segments: false` ```js // 縦長レポートを 1 画面ぶんずつ分割して撮る（既定） BrowseWeb({ url: "output/report.html", screenshot: "report.png" }) // → output/report-001.png, output/report-002.png, ... // フルページ 1 枚で撮りたいとき BrowseWeb({ url: "output/report.html", screenshot: "report.png", screenshotSegments: false }) ``` ## 長文ページの取得（preview + ファイル保存） `getText` (selector 有無問わず) およびスナップショットの戻り値が **5000 文字を超える** 場合、フルテキストはワークスペースの `logs/browse/{ISO-timestamp}-{hash}.txt` に保存され、戻り値は **先頭 5000 文字 + 続きの取得方法案内** になる: ``` （先頭 5000 文字） ... (truncated; full 38214 chars saved to logs/browse/2026-05-07T09-30-12-a1b2c3d4.txt — Read({file_path:"logs/browse/2026-05-07T09-30-12-a1b2c3d4.txt", offset, limit}) で続きを取得可能) ``` 続きを読みたい場合は `Read` ツールで `offset` / `limit` を指定: ```js Read({ file_path: "logs/browse/2026-05-07T09-30-12-a1b2c3d4.txt", offset: 200, limit: 200 }) ``` 5000 文字以下のページなら従来通り全文が直接返り、ファイルは作成されない。 ## ref 注釈の仕組み（重要） `BrowseWeb({ url })` や `getText` の出力には、操作可能な要素が以下のような注釈付きで埋め込まれる: ``` ようこそ {e1 link "ホーム" href="/"} {e2 link "製品" href="/products"} ログインしてください {e3 textbox name="email" placeholder="メールアドレス"} {e4 textbox name="password"} {e5 button "ログイン"} ``` - `e1`, `e2`, ... の ID（ref）は出現順に自動採番される - 各 ref は内部的に Playwright で解釈可能なセレクタ（`data-testid` / `id` / `[name]` / `aria-label` / nth-of-type CSS chain の優先順）にマッピングされている - click/fill アクションで `ref: "e5"` のように指定するだけで操作できる - **CSS セレクタを自分で組み立てる必要がない** ### 検出される要素の範囲 ref が振られるのは以下の要素: - 標準 HTML タグ: `` / `