feat: initial public release (MAESTRO)

2026-06-03 05:08:00 +00:00
commit f5c7666f6b
823 changed files with 184150 additions and 0 deletions
@@ -0,0 +1,69 @@
+# WebFetch
+
+URL を HTTP GET してレスポンス本文を取得するツール。静的ページ向け。
+
+## 基本
+
+```js
+WebFetch({ url: "https://example.com/article", timeout: 30 })
+```
+
+- HTML はテキスト化されて返る（タグ等は除去）
+- JSON / XML / プレーンテキストもそのまま取得可能
+- リダイレクトは自動で追従
+
+## いつ使うか
+
+| 状況 | 使うツール |
+|------|-----------|
+| 静的 HTML ページ | **WebFetch** |
+| JS で動的レンダリングされる SPA | BrowseWeb |
+| ボタン・フォーム操作が必要 | BrowseWeb |
+| ファイルダウンロード | DownloadFile |
+| 検索結果を一覧で取得 | WebSearch |
+
+WebFetch は軽量で速い。BrowseWeb はブラウザ起動コストがかかるので、できる限り WebFetch を優先する。
+
+## レスポンス履歴
+
+各 WebFetch 呼び出しは `logs/webfetch-history.jsonl` に記録される。後から「どの URL を取得したか」を振り返れる。
+
+## スクリーンショット添付（vlmEnabled 時のみ）
+
+ワーカーが `vlm=true`（主 LLM が画像入力対応）の場合、WebFetch は成功時に Playwright でファーストビュー（1280×1600 viewport）のスクショを撮り、LLM の文脈に `image_url` として自動添付する。天気・ダッシュボード・地図など、HTML テキスト抽出では情報が欠落しやすいサイトの理解を補う目的。
+
+- 保存先: `logs/webfetch-screenshots/{timestamp}-{url-hash}.png`
+- `logs/webfetch-history.jsonl` の各レコードに `screenshotPath` が記録される
+- Playwright 未インストール・CAPTCHA・タイムアウト等で失敗しても WebFetch 本体は成功扱い（テキストだけ返る）
+- 無効化: `config.yaml` の `tools.webfetch_screenshot: false`
+- タイムアウト: `tools.webfetch_screenshot_timeout_ms`（デフォルト 15,000）
+
+## SSRF 保護
+
+ローカル/プライベート IP（127.x.x.x, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, ::1, fc00::/7 等）はデフォルトでブロックされる。社内ホストへアクセスする必要がある場合は Settings UI の「SSRF Allowed Hosts」に追加する。
+
+## トラブルシューティング
+
+- **本文がほぼ空**: SPA で JS レンダリングが必要 → BrowseWeb に切り替え
+- **タイムアウト**: `timeout` パラメータを増やす（デフォルト 30 秒）
+- **403/404**: User-Agent 制限・bot 検出の可能性 → BrowseWeb なら回避できる場合あり
+- **SSRF blocked**: ローカル/プライベート IP に向いている → 設定追加またはターゲット見直し
+
+## エラー時のフォールバック方針
+
+WebFetch がエラーを返した場合、以下の原則で `BrowseWeb` にリトライする:
+
+| エラー | BrowseWeb で再試行すべきか |
+|---|---|
+| HTTP 403 / 429 | **する** — bot 検出・レート制限。ブラウザ User-Agent で回避できる可能性 |
+| HTTP 502 / 503 / 504 | **する** — CDN/upstream の一時的エラー。別の HTTP スタックで成功することがある |
+| ネットワークエラー / タイムアウト | **する** — 動的ページが静的 fetch に応答しないケースが多い |
+| HTTP 404 / 401 / 410 | しない — 永続的なエラー。URL を見直すべき |
+| `invalid_url` | しない — URL の記述ミス |
+| `ssrf_blocked` | しない — セキュリティ設定。Settings で allowed hosts を追加 |
+| `pdf_blocked` | しない — `DownloadFile` + `ReadPdf` の組み合わせを使う |
+| `binary_blocked` | しない — `DownloadFile` でバイナリ保存する |
+| 本文が極端に短い（< 200 chars） | **する** — SPA の空シェルを取得した可能性が高い |
+| `Just a moment...` 等 Cloudflare challenge | **する** — ブラウザで JS challenge を通過できる |
+
+リトライ時は同じ URL を `BrowseWeb({ url: "..." })` に渡すだけでよい。`BrowseWeb` はジョブ内で Cookie・セッションを保持するので、複数回呼んでもログイン状態は引き継がれる。