feat: initial public release (MAESTRO v0.1.0)
Open-source release of MAESTRO, an agent orchestration platform that runs LLM-driven tasks through sandboxed tools, with a web UI. Apache-2.0. See README.md and docs/ (getting-started, configuration, architecture).
This commit is contained in:
clade
@@ -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・セッションを保持するので、複数回呼んでもログイン状態は引き継がれる。
|
||||
Reference in New Issue
Block a user