chrome-bridge-automation

Chrome ブリッジ自動化

重要なルール — 違反するとワークフローが破綻します：

1. midscene コマンドをバックグラウンドで実行しないでください。 各コマンドは同期的に実行し、次のアクションを決める前に出力（特にスクリーンショット）を確認してください。バックグラウンド実行では、スクリーンショットを確認して分析し、操作するループが機能しなくなります。
2. midscene コマンドは一度に1つだけ実行してください。 前のコマンドが完了するまで待ち、スクリーンショットを確認してから、次のアクションを決めてください。複数のコマンドを連結して実行しないでください。
3. 各コマンドが完了するまで十分な時間を確保してください。 Midscene のコマンドでは AI 推論と画面操作が行われるため、一般的なシェルコマンドより時間がかかることがあります。通常、コマンドの実行には約1分かかり、複雑な act コマンドではさらに時間がかかる場合があります。
4. 終了する前に、必ずタスクの結果を報告してください。 自動化タスクを完了したら、見つかった重要なデータ、完了した操作、撮影したスクリーンショット、関連する調査結果を含め、必ずユーザーに結果を積極的に要約してください。最後の自動化手順のあと、何も報告せずに終了しないでください。ユーザーは1回のやり取りで完結した回答を期待しています。

Midscene Chrome 拡張機能（ブリッジモード）を介して、ユーザーの実際の Chrome ブラウザーを自動操作します。Cookie、セッション、ログイン状態はそのまま保持されます。AI エージェントであるあなたは、スクリーンショットに基づいてどの操作を行うかを判断します。

act でできること

Chrome ブリッジモードの単一の act 呼び出しでは、現在表示されている内容に基づき、ユーザーの実際の Chrome セッション内でクリック、右クリック、ダブルクリック、ホバー、テキストの入力やクリア、キーの押下、スクロール、ドラッグ、長押し、複数ステップにわたるページ操作を実行できます。タッチ入力が有効な場合、タッチ操作に対応したページでスワイプやピンチのような操作も実行できます。

コマンド形式

重要 — すべてのコマンドは、必ず以下の正確な形式にしてください。コマンドのプレフィックスは変更しないでください。

npx @midscene/web@1 --bridge <subcommand> [args]

• --bridge フラグはここでは必須です。ユーザーのデスクトップ上の Chrome ブラウザーに接続するブリッジモードを有効にします。

前提条件

ユーザーはすでに Chrome と Midscene 拡張機能の準備を済ませています。接続前にブラウザーや拡張機能の状態を確認しないでください。直接接続してください。

Midscene には、視覚的なグラウンディング能力に優れたモデルが必要です。次の環境変数を、システム環境変数または現在の作業ディレクトリにある .env ファイルで設定してください（Midscene は .env を自動的に読み込みます）。

MIDSCENE_MODEL_API_KEY="your-api-key"
MIDSCENE_MODEL_NAME="model-name"
MIDSCENE_MODEL_BASE_URL="https://..."
MIDSCENE_MODEL_FAMILY="family-identifier"

例：Gemini（Gemini-3-Flash）

MIDSCENE_MODEL_API_KEY="your-google-api-key"
MIDSCENE_MODEL_NAME="gemini-3-flash"
MIDSCENE_MODEL_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
MIDSCENE_MODEL_FAMILY="gemini"

例：Qwen 3.5

MIDSCENE_MODEL_API_KEY="your-aliyun-api-key"
MIDSCENE_MODEL_NAME="qwen3.5-plus"
MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
MIDSCENE_MODEL_FAMILY="qwen3.5"
MIDSCENE_MODEL_REASONING_ENABLED="false"
# If using OpenRouter, set:
# MIDSCENE_MODEL_API_KEY="your-openrouter-api-key"
# MIDSCENE_MODEL_NAME="qwen/qwen3.5-plus"
# MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"

例：Doubao Seed 2.0 Lite

MIDSCENE_MODEL_API_KEY="your-doubao-api-key"
MIDSCENE_MODEL_NAME="doubao-seed-2-0-lite"
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_FAMILY="doubao-seed"

よく使用されるモデル：Doubao Seed 2.0 Lite、Qwen 3.5、Zhipu GLM-4.6V、Gemini-3-Pro、Gemini-3-Flash。

モデルが設定されていない場合は、ユーザーに設定を依頼してください。対応プロバイダーについては、モデルの設定を参照してください。

コマンド

Web ページに接続

npx @midscene/web@1 --bridge connect --url https://example.com

スクリーンショットを撮影

npx @midscene/web@1 --bridge take_screenshot

スクリーンショットを撮影したら、次の操作を決める前に保存された画像ファイルを読み込み、現在のページの状態を確認してください。

操作を実行

act を使ってページを操作し、結果を取得します。クリック、入力、スクロール、ホバー、待機、ページ移動など、すべての UI 操作を内部で自律的に処理します。そのため、小さな手順に分けるのではなく、複雑で大まかなタスクを全体として指示してください。自然言語で何をしたいか、どのような結果を望むかを説明します。

# specific instructions
npx @midscene/web@1 --bridge act --prompt "click the Login button and fill in the email field with '[email protected]'"
npx @midscene/web@1 --bridge act --prompt "scroll down and click the Submit button"

# or target-driven instructions
npx @midscene/web@1 --bridge act --prompt "click the country dropdown and select Japan"

切断

npx @midscene/web@1 --bridge disconnect

ワークフローパターン

ブリッジモードでは、ユーザーが実際に使っている Chrome ブラウザーに接続します。CLI コマンドごとに一時的な接続が確立されますが、接続を切断してもブラウザー、タブ、およびすべての状態（Cookie、ログインセッション）は常に保持されます。そのため、再接続は簡単で、状態が失われることもありません。

次のパターンに従ってください。

1. 接続：URL に接続してセッションを確立します
2. スクリーンショットを撮影：現在の状態を確認し、ページが読み込まれていることを確認します。
3. アクションを実行：act を使って、目的のアクションまたは対象を指定した指示を実行します。
4. 結果を報告：完了した作業を要約し、重要な結果とタスク中に抽出したデータを提示して、生成されたファイル（スクリーンショット、ログなど）とそのパスを列挙します
5. 切断：ユーザーのタスク全体が完了した場合にのみ切断します。ユーザーが追加の操作を行う可能性がある場合は切断せず、以降の会話でも引き続き操作できるようセッションを維持してください。

ベストプラクティス

1. 必ず最初に接続する：操作を始める前に、connect --url で対象の URL に移動します。
2. UI 要素を具体的に指定する：「ボタン」ではなく、「お問い合わせフォームにある青い送信ボタン」のように指定します。
3. 自然な言葉を使う：CSS セレクターではなく、ページ上で見えるものを説明します。「#buy-btn」ではなく、「赤い購入ボタン」と伝えます。
4. 読み込み中の状態に対応する：ページの読み込みが発生するナビゲーションや操作の後は、スクリーンショットを撮影してページが読み込まれたことを確認します。
5. 作業が完全に終わった場合にのみ切断する：ユーザーのタスク全体が完了し、追加の操作が想定されない場合にのみ切断します。複数ターンにわたる会話では、その後もブラウザーを操作できるよう、切断をスキップしてください。切断しても問題はありません。閉じるのは CLI 側のブリッジ接続のみで、ブラウザーやタブは閉じません。ただし、ユーザーが操作を続けたい場合、再接続すると不要な手間がかかります。
6. バックグラウンドで実行しない：すべての midscene コマンドは同期的に実行する必要があります。バックグラウンド実行は、スクリーンショットの撮影、分析、操作を繰り返す流れを妨げます。
7. 関連する操作を 1 つの act コマンドにまとめる：同じページで連続して操作する場合は、別々のコマンドに分けず、1 つの act プロンプトにまとめます。たとえば、「メールアドレスとパスワードの欄に入力してから、ログインボタンをクリックする」は、3 回ではなく 1 回の act 呼び出しで実行します。これにより、往復の回数と不要なスクリーンショット撮影・分析のサイクルが減り、大幅に時間を短縮できます。
8. 完了後は必ず結果を報告する：自動化タスクを終えたら、ユーザーに尋ねられるのを待たずに、必ず結果を提示してください。これには、（1）ユーザーの元の質問への回答、または依頼されたタスクの結果、（2）実行中に抽出または確認した重要なデータ、（3）スクリーンショットやその他の生成ファイルとそのパス、（4）実施した手順の簡潔な要約が含まれます。最後の自動化コマンドを実行した後、結果を報告せずに終えてはいけません。ユーザーは、1 回のやり取りですべての結果が提示されることを期待しています。

例 — ドロップダウンの選択：

npx @midscene/web@1 --bridge act --prompt "click the country dropdown and select Japan"
npx @midscene/web@1 --bridge take_screenshot

例 — フォームの操作：

npx @midscene/web@1 --bridge act --prompt "fill in the email field with '[email protected]' and the password field with 'pass123', then click the Log In button"
npx @midscene/web@1 --bridge take_screenshot

トラブルシューティング

ブリッジモードの接続エラー

• Chrome が開いていて、Midscene Extension がインストールされ、有効になっているかユーザーに確認してもらいます。
• Midscene Extension は Chrome ウェブストアからインストールできます：https://chromewebstore.google.com/detail/midscenejs/gbldofcpkknbggpkmbdaefngejllnief
• 拡張機能の「ブリッジモード」インジケーターに「Listening」と表示されていることを確認します。
• ブリッジモードのドキュメントを参照してください。

タイムアウト

• Web ページの読み込みには時間がかかる場合があります。接続後、操作する前にスクリーンショットを撮影し、準備ができていることを確認してください。
• 読み込みの遅いページでは、手順の間に少し待機してください。

スクリーンショットが表示されない場合

• スクリーンショットのパスは、ローカルファイルの絶対パスです。Read ツールを使って表示してください。