# BrowseWeb 詳細ガイド ヘッドレスブラウザで Web ページを操作するツール。同一ジョブ内ではブラウザコンテキスト（Cookie・ログイン状態）が永続化される。 ## 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`） - `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`） - `getText` — 全ページのスナップショット（ref 注釈付き）または `selector` 内のテキストを取得 - `wait` — `ms` ミリ秒待機（最大 30000） - `dumpHtml` — `ref` または `selector`（省略時 body）の outerHTML を取得（脱出口、後述） ## 長文ページの取得（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 タグ: `` / `