bridgic-browser

依存関係

bridgic-browser プロジェクトには、次のパッケージが必要です。

パッケージ	説明
bridgic-browser	ブラウザー自動化 CLI ＋ Python SDK（どちらかをインストールすると両方がインストールされます）

さらに、ブラウザーのバイナリを一度インストールする必要があります：uv run playwright install chromium。

インストール：インストールスクリプトを実行して、すべての依存関係をセットアップします。

bash "skills/bridgic-browser/scripts/install-deps.sh" "$PWD"

スクリプトは uv が利用可能か確認し、必要に応じて uv プロジェクトを初期化し、不足しているパッケージをインストールして、Playwright chromium が利用可能であることを確認します。

戦略とガイドライン（重要!!）

注意：

• bridgic-browser CLI を呼び出すときは、必ず uv run を使用してください。
• ユーザーが従うべき手順を明確に指定している場合は、その手順に従って調査を行ってください。調査中にループや分岐が発生した場合は、最適な調査経路を自律的に判断してください。
• 新しいページに移動した後、元のページに戻る必要があると思われる場合は、「クリックしてから戻る」方法ではなく、新しいページを新しいブラウザータブで開いてください。元のページに入力済みのフォームや適用済みのフィルターなどの操作状態がある場合は特に重要です。そうしないと、戻った際にその状態が失われる可能性があります。関連する操作が完了したら、新しいタブを速やかに閉じてください。
• リスト内の項目を繰り返しクリックして調査する場合、すべての項目を確認する必要はありません（特にリストが大きい場合）。
• 調査中にログイン、検証、または認証が必要になった場合は、タスク内でユーザーが明示的に指示していない限り、作業を一時停止し、手動で完了するようユーザーに依頼してください。
• ウェブサイトへのアクセス頻度が高くなりすぎないよう、調査中とコーディング中の両方で、人間らしいアクセス間隔を保ってください。ブロックされるリスクを減らすため、ランダムな待ち時間を設けてもかまいません。注意：bridgic-browser wait コマンドのパラメーターはミリ秒ではなく秒です。例：bridgic-browser wait 2 または bridgic-browser wait 3.2。
• 調査とコードの作成が完了したら、自動的にテスト／検証を実行してください。
• CDP モードでのタブの表示範囲：ユーザーが起動している Chrome に --cdp で接続した場合、tabs ／ switch-tab ／ close-tab で表示されるのは bridgic 自身が開いたページ（最初の空白タブと、そこから new-tab または target="_blank" リンクのクリックで開いたページ）のみです。ユーザーの他のタブは意図的に bridgic から見えないようになっています。そこに切り替えられるとは決して考えないでください。そのようなタブを操作するには、bridgic 経由でそのページに移動するようユーザーに依頼するか、new-tab <url> を使用してください。

リファレンスファイル

リファレンスファイルには、すべてのユースケースが記載されています。タスクに関連するファイルのみを読み込んでください。

シナリオ	インターフェース	読み込むファイル
ターミナルからブラウザーを直接操作する	CLI	cli-guide.md
ブラウザー自動化に関する Python コードを作成する	Python	sdk-guide.md
ブラウザー自動化に関するシェルスクリプトを作成する	CLI	cli-guide.md
CLI で調査してから Python コードを生成する	CLI → Python	cli-sdk-api-mapping.md + sdk-guide.md
CLI ↔ SDK の移行／比較／説明	両方	cli-sdk-api-mapping.md
環境変数またはログイン状態の永続化を設定する	いずれか	env-vars.md
既存の Chrome に接続する（chrome://inspect、--remote-debugging-port、クラウドブラウザー、Electron）	CLI ／ SDK	cdp-mode.md

インターフェースの選択ルール

1. シェルコマンドまたはスクリプトの出力が求められている場合 → まず CLI ガイドを参照します（references/cli-guide.md）。
2. 実行可能な Python コード（async、Browser、ツールビルダー）の出力が求められている場合 → まず SDK ガイドを参照します（references/sdk-guide.md）。
3. 入力が CLI の出力または操作で、出力に Python コードが必要な場合 → まずマッピングガイドを参照し（references/cli-sdk-api-mapping.md）、次に最終コードの生成に向けて SDK ガイドを参照します（references/sdk-guide.md）。
4. 意図が曖昧な場合は、求められている成果物（.sh／ターミナルセッションと .py スクリプト）から判断します。

共通の使い方（CLI + SDK）

• Ref を使った操作は、最新のスナップショットに依存します。
• ページ遷移や DOM の大きな更新後は Ref が古くなることがあります。Ref を使った操作の前にスナップショットを更新してください。
• CLI は呼び出し間でデーモンセッションの状態を保持します。複数の独立したデーモンインスタンス（それぞれ独自のソケット、ログ、ユーザーデータを持ちます）を実行するには、BRIDGIC_HOME 環境変数を設定してください。
• SDK は Python プロセス／コンテキスト内で状態を保持します。デフォルトでは、ブラウザープロファイル（Cookie、セッション）が $BRIDGIC_HOME/bridgic-browser/user_data/（デフォルトは ~/.bridgic/...）に保持されます。一時的なセッションにするには、Browser() に clear_user_data=True を渡してください。
• リファレンスに記載されている正確なコマンド名／メソッド名を使用してください。別名を作らないでください。

ブリッジワークフロー：CLI 操作から Python コードへ

1. CLI の手順を順番に解析します。
2. references/cli-sdk-api-mapping.md を使って各手順を対応付けます。
3. Ref、オプション、引数、設定などの動作の詳細を維持します。
4. ブラウザーのライフサイクルを明示した、実行可能な非同期 Python コードを出力します（async with Browser(...) を推奨）。
5. 1 対 1 で表現できない動作の違いがあれば、明記します。

最低限の品質チェックリスト

• CLI のリクエスト：有効な CLI コマンド／オプションのみを返します。
• SDK のリクエスト：正しいインポートを含む、実行可能な非同期 Python コードを返します。
• ブリッジのリクエスト：対応付けの根拠と、最終的な SDK コードを含めます。