obscura-browser

Obscura Browser

概要

このスキルを使って、ユーザーによる obscura CLI の操作や、クライアントライブラリとその CDP サーバーとの接続を支援します。まず短く実行可能なコマンドを提示し、ユーザーのシナリオに役立つ場合にのみ、オプションのフラグやサンプルコードを追加してください。ローカル開発では、localhost へのアクセスを提案するのではなく、Vite + hostc + Obscura を標準の方法とします。

ワークフロー

1. 実行コマンドを提示する前に、obscura がローカルで利用可能かどうかを確認します。
2. 見つからない場合は、現在の OS で最短のインストール方法を説明します。
3. 対象がローカル開発の場合、Obscura のパッチ適用や localhost の直接利用を提案しないでください。以下を標準の方法とします。
   • Vite または別の開発サーバー上のローカルアプリ
   • hostc でローカルポートを公開 https:// URL として公開
   • Obscura から公開 URL にアクセス
4. リクエストに合った、最小限の Obscura の利用方法を選びます。
   • 1 ページまたは 1 回の抽出には fetch
   • 複数 URL の並列処理には scrape
   • Playwright または Puppeteer の CDP 接続には serve
5. まず、最小限のコマンドを 1 つ、または最小限のコードサンプルを 1 つ提示します。
6. ユーザーの目的に関係するフラグ（--stealth、--timeout、--wait-until、--output、--concurrency、--quiet など）のみを追加します。

クイックスタート

最初に scripts/detect_obscura.py を実行します。次の項目を確認します。

• obscura が PATH にあるかどうか
• 同じディレクトリに obscura-worker があるかどうか
• Windows、macOS、Linux における、ローカルバイナリの候補となる場所

バイナリが見つからない場合：

• ユーザーのプラットフォーム向けの GitHub Releases アーカイブを推奨します。
• Windows では、並列 scrape を実行するため、obscura.exe と obscura-worker.exe を同じフォルダーに置くよう伝えます。
• ソースからビルドする場合は、cargo build --release と cargo build --release --features stealth を案内します。

タスク別のパターン

Vite を使ったローカル開発

ユーザーが Obscura から http://localhost:5173 または別のローカル Vite ポートにアクセスしたい場合は、これを標準の回答とします。

推奨手順：

1. Vite をローカルで起動したままにします。
2. hostc で Vite のポートを公開します。
3. hostc が生成した公開 https:// URL を Obscura に指定します。

最短で動作するコマンド一式を生成するには、scripts/command_templates.py vite-hostc を使います。 ユーザーが hostc を使う方法と、すぐに実行できる Playwright または Puppeteer のスニペットを求めている場合は、scripts/command_templates.py vite-hostc-cdp を使います。

最小構成の手順：

pnpm dev
npx hostc 5173
obscura fetch https://your-hostc-url --dump html

単一ページの取得ではなく、ブラウザー自動化が必要な場合：

obscura serve --port 9222

次に、hostc の URL に移動する Playwright または Puppeteer のスニペットを提示します。

例：

python scripts/command_templates.py vite-hostc-cdp playwright --public-url https://your-hostc-url

listhen を使ったローカル開発

ユーザーが明示的に listhen を希望している場合、またはすでに利用している場合に限り、代替手段として使います。重要なのはローカルのリスナーではなく、公開トンネル URL です。

以下は推奨しないでください。

• localhost
• 127.0.0.1
• 192.168.x.x などの LAN IP
• ユーザーがコード変更を明示的に求めている場合を除き、SSRF 保護を無効にするソースのパッチ

単一ページの抽出

最初のコマンドを作成するには scripts/command_templates.py fetch を使い、その後、必要に応じて調整します。

よくある例：

obscura fetch https://example.com --eval "document.title"
obscura fetch https://example.com --dump links
obscura fetch https://news.ycombinator.com --dump html --wait-until networkidle0

以下を優先します。

• DOM の式または計算値を 1 つ取得するには --eval
• 組み込みの出力形式を使うには --dump html|text|links
• ファイルへの出力が必要な場合は --output

並列スクレイピング

ユーザーが複数の URL を提示した場合、または並列処理を求めている場合は、scripts/command_templates.py scrape を使います。

よくある例：

obscura scrape https://example.com https://example.org --concurrency 10 --eval "document.querySelector('h1')?.textContent" --format json

出力をスクリプトやパイプで使う場合は、--quiet を優先します。

Playwright または Puppeteer 用の CDP サーバー

起動コマンドの作成には scripts/command_templates.py serve を、クライアントコードのサンプルには scripts/command_templates.py cdp を使います。

一般的な serve コマンド：

obscura serve --port 9222

以下を追加します。

• 検出回避が重要な場合は --stealth
• プロキシが必要な場合は --proxy <url>
• CDP ワーカープロセスの並列実行が役立つ場合は --workers <n>

次に、対応するクライアントのスニペットを提示します。

• Playwright では chromium.connectOverCDP({ endpointURL: 'ws://127.0.0.1:9222' }) を使います。
• Puppeteer では puppeteer.connect({ browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser' }) を使います。

回答のスタイル

実用性を重視して回答してください。

• 環境の状態が不明な場合は、最初に環境の状態を示してください。
• 次に実行する正確なコマンドを提示してください。
• コードが必要な場合は、最小限の動作するスニペットを1つ提示してください。
• フラグを選択する際は、前提条件を説明してください。

参考資料

必要な場合にのみ、以下を参照してください。

• references/cli-cheatsheet.md：コマンドのパターンとフラグの選択
• references/cdp-integration.md：Playwright と Puppeteer の接続方法
• references/local-dev-tunnels.md：Vite + hostc + Obscura と listhen のフォールバックに関するガイダンス

スクリプト

• scripts/detect_obscura.py インストール済みバイナリの検出と、ワーカーの同居状態の検証に使用します。
• scripts/command_templates.py fetch、scrape、serve、CDP クライアント、およびデフォルトの Vite + hostc + Obscura フロー向けのコマンドとコードスニペットのひな形を生成するために使用します。