Fisherboyドキュメント

このページでは、Fisherboyの動作を端から端まで解説します：コアコンセプト、Web UI、ダウンロード機能、RESTおよびMCP API、そして高度な設定です。

コンセプト

ジョブとエンベロープ

Fisherboyが行うすべては ジョブ です。ジョブ（URLとオプション）を投入すると、Redis上にキューされ、ワーカーがパイプラインを実行し、結果が エンベロープ として保存されます — これは抽出されたコンテンツ（content_md）、構造化レコード、クロールツリー、発見されたリンク、メタデータを保持する単一のオブジェクトです。ステータスが ok になるまでジョブをポーリングします。

段階的フェッチ（ブロックされたときだけエスカレーション）

Fisherboyは必要になるまで重いブラウザに手を伸ばしません。最も安価な方法をまず試し、ゲート がブロックやCAPTCHAを検出したときだけ段階を上げます：

Tier 0 — httpx による静的HTTP。高速で安価。ほとんどの静的ページで機能します。
Tier 1 — curl_cffi によるTLSフィンガープリント。ネットワーク層で本物のブラウザのように見えます。
Tier 2 — JavaScript主体・アンチボットのページ向けのステルスブラウザ（Camoufox / Patchright）。このtierは 隠れたAPIの捕捉 も駆動します。
Tier 3 — 最後の手段としての本物のブラウザ（nodriver / Playwright）。

成功したtierは ドメインごとにキャッシュ され（TIER_CACHE_TTL_S）、同じサイトへの次のリクエストは前回成功した地点から始まります。高いtierは遅延インポートされ — ベースイメージは軽量に保たれ、各tierはそのライブラリがインストールされている場合のみ有効になります。エスカレーションの上限は MAX_FETCH_TIER で設定し、ジョブの tier_hint で開始地点を示唆できます。

隠れたAPIの捕捉

シングルページアプリや動的グリッドは、XHR/fetch で取得するJSONからレンダリングされます。レンダリングされたHTMLと戦う代わりに、Fisherboyは それらのネットワークレスポンスを監視し、ページがすでに消費しているJSONを保持 できます — 通常、データの最も確実で完全なソースです。ジョブごとに capture_api で有効化します。

プライバシーモード

プライバシーモードは ジョブごと に選択され、ロールによって制限 されます（privacy_matrix.yaml で定義され、ハードコードされることはありません）。パイプラインは フェイルクローズ です：匿名化が失敗した場合、生のデータは一切配信されません。

opaque（opaco）— 各エンティティは «PERSON_1» や «ID_2» のような安定した型付きマーカーになります。LLMはマーカー上で推論し、PIIを見ることはなく、元のデータは復元できません。
reversible — 同じマスキングですが、暗号化されたトークン対値のマップが保持されるため、後から POST /api/revert（単回使用、ロール制限）で再ハイドレートできます。マップはFernetキー（REVERSIBLE_KEY）で暗号化され、REVERSIBLE_TTL_S 後に失効します。
direct（directo）— 生の出力。機密でないデータ専用です。

決定論的な正規表現パスは、高リスクのPII（国民ID、メール、IP、Luhn有効なカード、電話番号）に対して常に実行されます。ANONIMAL_URL が Anonimal インスタンスを指している場合、その上で完全なNERが実行されます。スタンドアロンでは組み込みの正規表現パスのみにフォールバックします。

ロールが要求されたモードを許可しない場合、ゲートウェイは 403 を返します — 暗黙的にダウングレードすることはありません。

ロール

Fisherboyには3つのアクセスレベルがあり、それぞれ独自のパスワードと機能制限（どのtier、プロキシ、 APIキャプチャ、captchaソルバー、クロール、タランチュラが許可されるか）を持ちます。ロールは RESTとMCPの両方で適用されます。

ロール	opaque	reversible	direct
`humano`	あり	—	—
`angel`	あり	あり	—
`dios`	あり	あり	あり

大まかに言えば：humano は安価なtierを得て高価な「武器」は持ちません。angel はブラウザ、プロキシ、キャプチャを追加します（ただしcaptchaソルバーはなし）。dios はすべてを持ちます。タランチュラとブラウザクッキーの読み取りは sidekick モードでは拒否されます。

Web UIの使い方

standalone モードでは、FisherboyはサービスURL（例：http://localhost:8000）に独自のWeb UIをマウントします。ロールパスワードでログインした後の操作：

URLを貼り付け、出力（markdown、llms_txt、json）とロールが許可するプライバシーモードを選択します。
オプションで追加機能を有効化します — ページネーション、APIキャプチャ、クロール深度、タランチュラ、プロキシ、クッキー。
ジョブを実行します。結果はモーダルの エディター で開きます。

組み込みエディター

結果は3つのタブを持つモーダルエディターで開きます：

Markdown — ライブプレビュー付きのツールバー。
JSON — 検証機能付きエディター。
Table — 編集可能なテーブル。JSON ↔ テーブルはタブを切り替えるだけ です。

結果は .md、.json、.csv としてダウンロードできます。エンベロープ全体、データのみ（コンテンツ + レコード + ツリー + リンク）、またはフラットなレコード配列をダウンロードできます。ワンクリックで結果を Escriba に送り、さらなる変換、匿名化、チャンク化、エクスポートを行えます。

ダウンロード

ページのテキストにとどまらず、Fisherboyはメディアやプラットフォームデータを取得できます：

ファイル — 直接のファイルダウンロード。
動画 — yt-dlp 経由（YouTube、Vimeoなど多数）。イメージに同梱された ffmpeg が動画 + 音声を高品質なmp4に多重化します。それがない場合、ダウンロードは最良のプログレッシブ単一ファイルにフォールバックします。
ギャラリー／画像 — gallery-dl 経由（Instagram、X、Reddit、Pinterest、Tumblr、Flickr、DeviantArtなど）。
コメント／プラットフォームデータ — マルチプラットフォーム。Instagramの投稿コメントやフォロワー／フォロー中のデータは instaloader を使用し、セッションクッキー（IG_SESSIONID）を必要とし、dios ロールに制限されます。

REST API

POST /api/jobs            # スキーマ、ロール × プライバシーモード、コールバック・プロキシ（SSRF）を検証し、キューに入れる → 202
GET  /api/jobs/{job_id}   # ステータスと結果（「エンベロープ」）
POST /api/proxy/test      # プロキシ経由でリクエストをルーティングし、出口IP + 国 + レイテンシを返す
POST /api/revert          # 仮名化されたコンテンツを再ハイドレートする（reversibleモード）
POST /api/login           # ロールログイン（クッキーセッション）
GET  /healthz             # 生存確認
GET  /metrics             # Prometheusメトリクス

ジョブを投入してポーリングする：

curl -X POST http://localhost:8000/api/jobs \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/article","rol":"angel","privacy_mode":"opaco"}'
# → { "job_id": "…", "status": "pendiente" }

curl http://localhost:8000/api/jobs/<job_id>
# → status == "ok" になると匿名化された content_md を含むエンベロープ

ジョブのフィールド

フィールド	備考
`url`	フェッチするページ。
`rol`	`humano` / `angel` / `dios`。
`privacy_mode`	`opaco` / `reversible` / `directo`（ロールによって制限）。
`output_format`	`markdown` / `llms_txt` / `json`。
`tier_hint`	開始tierの示唆、`0`–`3`。
`crawl_depth`	スパイダークロールの深度。
`max_pages`	ページ予算（`CRAWL_MAX_PAGES` で上限）。
`paginate`	ページネーションを一掃する。
`capture_api`	隠れたXHR/fetchのJSONを捕捉する。
`tarantula`	各ノードのコンテンツ + APIをデータツリーに捕捉する。
`extract_schema`	構造化抽出用のJSON Schema（`output_format=json` 併用）。
`proxy`	ジョブごとのプロキシオーバーライド。
`cookies`	リクエスト用のセッションクッキー。
`callback_url`	完了時にエンベロープを受け取るWebhook。

MCP

同じパイプラインがMCPツール（submit_job、get_job、revert）として公開されているため、n8n、 Claude Code、EscribaはHTTPを手書きせずにジョブをキューに入れられます：

python -m app.mcp_server      # fastmcp が必要

MCPサーバーのロール上限は MCP_ROLE で設定されます（呼び出し元が主張するロールを信頼しません）。

高度な設定

プロキシ

プロキシを 任意の形式 で貼り付けます — host:port、host:port:user:pass、 user:pass@host:port、または完全なURL — Fisherboyがそれを正規化します（socks5対応）。 Test ボタン（または POST /api/proxy/test）はそれ経由でリクエストをルーティングし、出口の IP + 国 + レイテンシ を返します。接続できない場合は実行可能なヒントを示します。PROXIES でプールを設定し、PROXY_ROTATION（round_robin / random / sticky）でローテーションを選び、 PROXY_COOLDOWN_S と PROXY_ATTEMPTS を調整します。ジョブは独自の proxy でプールをオーバーライドできます。

クッキー

ブラウザ拡張なしで、ログインの背後や特定リージョンのページを使えます。クッキーをNetscape cookies.txt、JSON、name=value ペアとして貼り付けるか、ローカルブラウザ（Chrome / Firefox / Edge / Brave）から直接読み取ります。ブラウザクッキーの読み取りは standalone専用 で、 sidekick モードでは拒否されます。

CAPTCHA

既定のアンチCAPTCHA戦略は、エスカレーションによる予防です（CAPTCHA_SOLVER=none）：フェッチゲートがCAPTCHAを検出し、tierを1段上げます。オプションで、外部APIソルバーを CAPTCHA_SOLVER=external、 CAPTCHA_SOLVER_URL、CAPTCHA_SOLVER_KEY で設定できます（ロールにより制限）。

ページネーション

ジョブに paginate を設定して複数ページのリストを一掃します。Fisherboyは一般的な方式を処理します — ASP.NETのポストバック、「次へ」リンク、?page= クエリパターン。総数は max_pages とハードな CRAWL_MAX_PAGES キャップによって制限されます。

ブラウザtier

tier 2および3では、ヘッドレスブラウザを BROWSER_HEADLESS、BROWSER_SETTLE_S （読み込み後の待機）、BROWSER_SCROLL（遅延読み込みのトリガー）、BROWSER_LOCALE、 BROWSER_USER_AGENT で調整します。

スパイダー＆タランチュラ（深掘りクロール）

スパイダー — 内部リンクをツリー状にたどり（セクションスコープ付き）、crawl_depth まで、オプションでページネーションと組み合わせます。
タランチュラ — 深掘りモード：各ノードを歩き、そのコンテンツと隠れたAPIの両方を単一のデータツリーに捕捉します。タランチュラは高ロールに制限され、sidekick モードでは拒否されます。

複数ページのクロールは RESPECT_ROBOTS=1 のとき robots.txt を尊重します。

セキュリティと制限

Fisherboyはフェイルクローズで堅牢化されています：アンチSSRF（DNS解決済み。プライベート/ループバック/ リンクローカル/クラウドメタデータの範囲をブロックし、すべてのリダイレクトホップ とすべてのブラウザリクエスト（プロキシオーバーライドを含む）で再検証）、ジョブごとのシークレット除去（プロキシ認証情報、captchaキー、クッキーはエンベロープやWebhookに一切現れません）、RESTとMCPでのロールゲーティング、レート制限（MAX_JOBS_PER_MIN）、ハードなページおよびバイトキャップ（CRAWL_MAX_PAGES、JOB_MAX_TOTAL_BYTES）、そして非rootコンテナ。公開する前に本番チェックリストを確認してください — 本番では ALLOW_PRIVATE_TARGETS=1 や FISHERBOY_OPEN_GOD=1 を絶対に設定しないでください。

オプションの永続化と可観測性

Postgres + pgvectorの永続化はオプションです（DATABASE_URL、加えてベクトルストア用の EMBEDDINGS_ENABLED）。それがなくてもシステムはRedisだけで動作し、緩やかに機能を縮退させます。 Prometheus + Loki + Grafanaスタックは docker-compose.observability.yml 経由で利用できます。