Jamie-BitFlight/claude_skills

agent-browser によるブラウザ自動化

コアワークフロー

すべてのブラウザ自動化は次のパターンに従います：

1. 移動: agent-browser open <url>
2. スナップショット: agent-browser snapshot -i (要素参照 @e1, @e2 などを取得)
3. 操作: 参照を使用してクリック、入力、選択
4. 再スナップショット: 移動またはDOM変更後、新しい参照を取得

agent-browser open https://example.com/form
agent-browser snapshot -i
# 出力: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # 結果を確認

コマンドチェーン

コマンドは && を使って1回のシェル呼び出しで連結できます。ブラウザはバックグラウンドデーモンで持続するため、チェーンは個別の呼び出しよりも安全で効率的です。

# 1回の呼び出しで open + wait + snapshot を連結
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# 複数の操作を連結
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3

# 移動とキャプチャ
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

チェーンを使用すべき場合: 中間コマンドの出力を読み取る必要がない場合（例: open + wait + screenshot）は && を使用します。出力を最初に解析する必要がある場合（例: snapshot で参照を発見し、それを使って操作する場合）は、コマンドを個別に実行します。

基本コマンド

# ナビゲーション
agent-browser open <url>              # 移動（エイリアス: goto, navigate）
agent-browser close                   # ブラウザを閉じる

# スナップショット
agent-browser snapshot -i             # 参照付きインタラクティブ要素（推奨）
agent-browser snapshot -i -C          # カーソルインタラクティブ要素を含む（div、onclick、cursor:pointer）
agent-browser snapshot -s "#selector" # CSSセレクタでスコープ

# 操作（snapshot の @ref を使用）
agent-browser click @e1               # 要素をクリック
agent-browser click @e1 --new-tab     # 新しいタブでクリックして開く
agent-browser fill @e2 "text"         # テキストをクリアして入力
agent-browser type @e2 "text"         # クリアせずに入力
agent-browser select @e1 "option"     # ドロップダウンオプションを選択
agent-browser check @e1               # チェックボックスをオンにする
agent-browser press Enter             # キーを押す
agent-browser scroll down 500         # ページをスクロール

# 情報取得
agent-browser get text @e1            # 要素のテキストを取得
agent-browser get url                 # 現在のURLを取得
agent-browser get title               # ページのタイトルを取得

# 待機
agent-browser wait @e1                # 要素を待機
agent-browser wait --load networkidle # ネットワークアイドルを待機
agent-browser wait --url "**/page"    # URLパターンを待機
agent-browser wait 2000               # ミリ秒待機

# キャプチャ
agent-browser screenshot              # スクリーンショットを一時ディレクトリに保存
agent-browser screenshot --full       # ページ全体のスクリーンショット
agent-browser screenshot --annotate   # 要素番号ラベル付き注釈スクリーンショット
agent-browser pdf output.pdf          # PDFとして保存

# 差分（ページ状態の比較）
agent-browser diff snapshot                          # 現在と最後のスナップショットを比較
agent-browser diff snapshot --baseline before.txt    # 現在と保存ファイルを比較
agent-browser diff screenshot --baseline before.png  # 視覚的なピクセル差分
agent-browser diff url <url1> <url2>                 # 2つのページを比較
agent-browser diff url <url1> <url2> --wait-until networkidle  # カスタム待機戦略
agent-browser diff url <url1> <url2> --selector "#main"  # 要素にスコープ

一般的なパターン

フォーム送信

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle

認証状態の永続化

# 一度ログインして状態を保存
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# 将来のセッションで再利用
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

セッション永続化

# ブラウザ再起動全体でCookieとlocalStorageを自動保存/復元
agent-browser --session-name myapp open https://app.example.com/login
# ... ログインフロー ...
agent-browser close  # 状態が ~/.agent-browser/sessions/ に自動保存

# 次回、状態が自動ロードされる
agent-browser --session-name myapp open https://app.example.com/dashboard

# 保存状態を暗号化
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com

# 保存状態の管理
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7

データ抽出

agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5           # 特定の要素テキストを取得
agent-browser get text body > page.txt  # 全ページテキストを取得

# JSON出力（解析用）
agent-browser snapshot -i --json
agent-browser get text @e1 --json

並列セッション

agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com

agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i

agent-browser session list

既存Chromeへの接続

# リモートデバッグが有効なChromeを自動検出
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot

# 明示的なCDPポート指定
agent-browser --cdp 9222 snapshot

ビジュアルブラウザ（デバッグ）

agent-browser --headed open https://example.com
agent-browser highlight @e1          # 要素をハイライト
agent-browser record start demo.webm # セッションを録画
agent-browser profiler start         # Chrome DevToolsプロファイリング開始
agent-browser profiler stop trace.json # 停止してプロファイルを保存（パスは任意）

ローカルファイル（PDF、HTML）

# ローカルファイルを file:// URL で開く
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png

iOSシミュレータ（Mobile Safari）

# 利用可能なiOSシミュレータを一覧表示
agent-browser device list

# 特定のデバイスでSafariを起動
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# デスクトップと同じワークフロー - snapshot、操作、再snapshot
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1          # タップ（clickのエイリアス）
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up         # モバイル固有のジェスチャー

# スクリーンショット撮影
agent-browser -p ios screenshot mobile.png

# セッションを閉じる（シミュレータをシャットダウン）
agent-browser -p ios close

要件: macOS（Xcode付き）、Appium（npm install -g appium && appium driver install xcuitest）

実機: 事前設定されていれば物理iOSデバイスでも動作します。UDIDは xcrun xctrace list devices で確認し、--device "<UDID>" で指定します。

差分（変更の検証）

アクション実行後、diff snapshot を使用して意図した効果があったかを確認します。現在のアクセシビリティツリーとセッション内で最後に撮影したスナップショットを比較します。

# 一般的なワークフロー: snapshot -> アクション -> diff
agent-browser snapshot -i          # ベースラインスナップショットを撮影
agent-browser click @e2            # アクションを実行
agent-browser diff snapshot        # 変更を確認（自動的に最後のスナップショットと比較）

ビジュアル回帰テストやモニタリングの場合：

# ベースラインスクリーンショットを保存し、後で比較
agent-browser screenshot baseline.png
# ... 時間経過または変更 ...
agent-browser diff screenshot --baseline baseline.png

# ステージングと本番を比較
agent-browser diff url https://staging.example.com https://prod.example.com --screenshot

diff snapshot の出力は、git diff と同様に追加は +、削除は - で表示されます。diff screenshot は、変更されたピクセルを赤色でハイライトした差分画像と不一致率を生成します。

タイムアウトと低速ページ

デフォルトのPlaywrightタイムアウトはローカルブラウザで60秒です。低速なWebサイトや大きなページの場合は、デフォルトのタイムアウトに頼るのではなく、明示的な待機を使用します。

# ネットワークアクティビティが落ち着くのを待機（低速ページに最適）
agent-browser wait --load networkidle

# 特定の要素が出現するのを待機
agent-browser wait "#content"
agent-browser wait @e1

# 特定のURLパターンを待機（リダイレクト後に便利）
agent-browser wait --url "**/dashboard"

# JavaScript条件を待機
agent-browser wait --fn "document.readyState === 'complete'"

# 最後の手段として固定時間（ミリ秒）待機
agent-browser wait 5000

一貫して低速なWebサイトを扱う場合は、open の後に wait --load networkidle を使用して、スナップショットを撮る前にページが完全にロードされていることを確認します。特定の要素のレンダリングが遅い場合は、wait <selector> または wait @ref で直接待機します。

セッション管理とクリーンアップ

複数のエージェントや自動化を同時に実行する場合は、競合を避けるために常に名前付きセッションを使用します。

# 各エージェントは独自の分離セッションを持つ
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# アクティブなセッションを確認
agent-browser session list

終了時は常にブラウザセッションを閉じて、プロセスがリークしないようにします。

agent-browser close                    # デフォルトセッションを閉じる
agent-browser --session agent1 close   # 特定のセッションを閉じる

以前のセッションが適切に閉じられなかった場合、デーモンがまだ実行されている可能性があります。新しい作業を開始する前に agent-browser close でクリーンアップします。

参照ライフサイクル（重要）

参照（@e1, @e2 など）はページが変更されると無効になります。以下の操作後は必ず再スナップショットを実行します。

• ナビゲートするリンクやボタンのクリック
• フォーム送信
• 動的コンテンツのロード（ドロップダウン、モーダル）

agent-browser click @e5              # 新しいページに移動
agent-browser snapshot -i            # 必ず再スナップショット
agent-browser click @e1              # 新しい参照を使用

注釈付きスクリーンショット（ビジョンモード）

--annotate を使用すると、インタラクティブ要素に番号ラベルを重ねたスクリーンショットが撮影されます。各ラベル [N] は参照 @eN に対応します。これにより参照がキャッシュされるため、個別のスナップショットなしで要素と即座に操作できます。

agent-browser screenshot --annotate
# 出力には画像パスと凡例が含まれる:
#   [1] @e1 button "Submit"
#   [2] @e2 link "Home"
#   [3] @e3 textbox "Email"
agent-browser click @e2              # 注釈スクリーンショットから参照を使用してクリック

注釈付きスクリーンショットは次の場合に使用します:

• ページにラベルのないアイコンボタンやビジュアルのみの要素がある場合
• 視覚的なレイアウトやスタイルを確認する必要がある場合
• キャンバスやチャート要素が存在する場合（テキストスナップショットでは見えない）
• 要素の位置に関する空間推論が必要な場合

セマンティックロケータ（参照の代替）

参照が利用できないか信頼できない場合は、セマンティックロケータを使用します。

agent-browser find text "Sign In" click
agent-browser find label "Email" fill "[email protected]"
agent-browser find role button click --name "Submit"
agent-browser find placeholder "Search" type "query"
agent-browser find testid "submit-btn" click

JavaScript評価（eval）

eval を使用してブラウザコンテキストでJavaScriptを実行します。シェルの引用符は複雑な式を破損させる可能性があります -- 問題を回避するには --stdin または -b を使用します。

# 単純な式は通常の引用符で動作
agent-browser eval 'document.title'
agent-browser eval 'document.querySelectorAll("img").length'

# 複雑なJS: heredocで --stdin を使用（推奨）
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
  Array.from(document.querySelectorAll("img"))
    .filter(i => !i.alt)
    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF

# 代替: base64エンコード（すべてのシェルエスケープ問題を回避）
agent-browser eval -b "$(echo -n 'Array.from(document.querySelectorAll("a")).map(a => a.href)' | base64)"

これが重要な理由: シェルがコマンドを処理するときに、内部の二重引用符、! 文字（履歴展開）、バッククォート、$() はすべて、agent-browser に到達する前にJavaScriptを破損させる可能性があります。--stdin と -b フラグはシェル解釈を完全にバイパスします。

経験則:

• 1行で入れ子引用符なし -> 通常のシングルクォート eval 'expression' で問題なし
• 入れ子引用符、アロー関数、テンプレートリテラル、複数行 -> eval --stdin <<'EVALEOF' を使用
• プログラム/生成スクリプト -> base64 で eval -b を使用

設定ファイル

プロジェクトルートに agent-browser.json を作成して永続的な設定を行います。

{
  "headed": true,
  "proxy": "http://localhost:8080",
  "profile": "./browser-data"
}

優先順位（低いものから高いものへ）: ~/.agent-browser/config.json < ./agent-browser.json < 環境変数 < CLIフラグ。カスタム設定ファイルには --config <path> または AGENT_BROWSER_CONFIG 環境変数を使用します（存在しない場合や無効な場合はエラーで終了）。すべてのCLIオプションはキャメルケースキーにマップされます（例: --executable-path -> "executablePath"）。ブールフラグは true/false 値を受け入れます（例: --headed false で設定を上書き）。ユーザーとプロジェクト設定の拡張はマージされ、置き換えられません。

詳細ドキュメント

リファレンス	使用すべき場合
references/commands.md	全オプションを含む完全なコマンドリファレンス
[references/...