browserwing-executor

Name: browserwing-executor
Author: memtensor

github.com/memtensorエージェントワークフロー12.2k133 回インストール5 日前に更新

リポジトリ

browserwing-executor について

browserwing-executorは、BrowserWingのHTTP APIを使うエージェント向けブラウザー自動化スキルです。ページ操作、アクセシビリティスナップショット、データ抽出、連続処理に対応します。

主な機能

01ページの移動と制御
02アクセシビリティスナップショットの確認
03要素のクリック・入力・選択
04ページデータの抽出
05連続バッチ操作

活用シーン

01ウェブサイトでの検索自動化
02ウェブフォームの入力と送信
03構造化されたページ内容の収集

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/memtensor/memos --skill browserwing-executor

インストール後、Claude Code で/browserwing-executorを入力して読み込まれたか確認します。

詳細

BrowserWing Executor API

概要

BrowserWing Executor は、HTTP API を通じて包括的なブラウザー自動化機能を提供します。ブラウザーのナビゲーションを制御し、ページ要素を操作し、データを抽出し、ページ構造を分析できます。

API ベース URL： http://localhost:8080/api/v1/executor

認証： X-BrowserWing-Key: <api-key> ヘッダー、または Authorization: Bearer <token> を使用します。

主な機能

ページナビゲーション： URL への移動、戻る／進む、再読み込み
要素の操作： ページ要素のクリック、入力、選択、ホバー
データ抽出： 要素からテキスト、属性、値を抽出
アクセシビリティ分析： アクセシビリティスナップショットを取得してページ構造を把握
高度な操作： スクリーンショット、JavaScript の実行、キーボード入力
バッチ処理： 複数の操作を順番に実行

API エンドポイント

1. 利用可能なコマンドを確認する

重要： 利用可能なすべてのコマンドとそのパラメーターを確認するため、必ず最初にこのエンドポイントを呼び出してください。

curl -X GET 'http://localhost:8080/api/v1/executor/help'

レスポンス： パラメーター、例、使用ガイドラインを含むすべてのコマンドの完全な一覧を返します。

特定のコマンドを検索する：

curl -X GET 'http://localhost:8080/api/v1/executor/help?command=extract'

2. アクセシビリティスナップショットを取得する

必須： ページ構造を把握し、要素の RefID を取得するため、ナビゲーション後は必ずこのエンドポイントを呼び出してください。

curl -X GET 'http://localhost:8080/api/v1/executor/snapshot'

レスポンスの例：

{
  "success": true,
  "snapshot_text": "Clickable Elements:\n  @e1 Login (role: button)\n  @e2 Sign Up (role: link)\n\nInput Elements:\n  @e3 Email (role: textbox) [placeholder: [email protected]]\n  @e4 Password (role: textbox)"
}

使用例：

ページ上のインタラクティブ要素を把握する
要素を正確に特定するための RefID（@e1、@e2 など）を取得する
要素のラベル、ロール、属性を確認する
アクセシビリティツリーは生の DOM よりも整理されており、LLM に適しています
RefID は、ページの変更後も確実に使用できる安定した参照です

3. よく使う操作

URL に移動する

curl -X POST 'http://localhost:8080/api/v1/executor/navigate' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

要素をクリックする

curl -X POST 'http://localhost:8080/api/v1/executor/click' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e1"}'

識別子の形式：

RefID（推奨）： @e1、@e2（スナップショットから取得）
CSS セレクター： #button-id、.class-name
XPath： //button[@type='submit']
テキスト： Login（テキストコンテンツ）

テキストを入力する

curl -X POST 'http://localhost:8080/api/v1/executor/type' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "[email protected]"}'

データを抽出する

curl -X POST 'http://localhost:8080/api/v1/executor/extract' \
  -H 'Content-Type: application/json' \
  -d '{
    "selector": ".product-item",
    "fields": ["text", "href"],
    "multiple": true
  }'

要素を待機する

curl -X POST 'http://localhost:8080/api/v1/executor/wait' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": ".loading", "state": "hidden", "timeout": 10}'

バッチ操作

curl -X POST 'http://localhost:8080/api/v1/executor/batch' \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      {"type": "navigate", "params": {"url": "https://example.com"}, "stop_on_error": true},
      {"type": "click", "params": {"identifier": "@e1"}, "stop_on_error": true},
      {"type": "type", "params": {"identifier": "@e3", "text": "query"}, "stop_on_error": true}
    ]
  }'

手順

ステップごとのワークフロー：

コマンドを確認する： GET /help を呼び出し、利用可能なすべての操作とそのパラメーターを確認します（不明な場合は、最初に実行してください）。
移動する： POST /navigate を使用して、対象の Web ページを開きます。
ページを分析する： GET /snapshot を呼び出し、ページ構造を把握して要素の RefID を取得します。
操作する： 要素の RefID（@e1、@e2 など）または CSS セレクターを使用して、次の操作を行います。
- 要素をクリックする：POST /click
- テキストを入力する：POST /type
- オプションを選択する：POST /select
- 要素を待機する：POST /wait
データを抽出する： POST /extract を使用して、ページから情報を取得します。
結果を提示する： 抽出したデータを整形してユーザーに表示します。

完全な例

ユーザーのリクエスト： 「example.com で『laptop』を検索して、最初の 5 件の結果を取得してください」

実行する操作：

検索ページに移動します。

curl -X POST 'http://localhost:8080/api/v1/executor/navigate' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/search"}'

検索入力欄を見つけるためにページ構造を取得します。

curl -X GET 'http://localhost:8080/api/v1/executor/snapshot'

レスポンスには次のように表示されます：@e3 Search (role: textbox) [placeholder: Search...]

検索語を入力します。

curl -X POST 'http://localhost:8080/api/v1/executor/type' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": "@e3", "text": "laptop"}'

Enter キーを押して送信します。

curl -X POST 'http://localhost:8080/api/v1/executor/press-key' \
  -H 'Content-Type: application/json' \
  -d '{"key": "Enter"}'

結果の読み込みを待機します。

curl -X POST 'http://localhost:8080/api/v1/executor/wait' \
  -H 'Content-Type: application/json' \
  -d '{"identifier": ".search-results", "state": "visible", "timeout": 10}'

検索結果を抽出します。

curl -X POST 'http://localhost:8080/api/v1/executor/extract' \
  -H 'Content-Type: application/json' \
  -d '{
    "selector": ".result-item",
    "fields": ["text", "href"],
    "multiple": true
  }'

抽出したデータを提示します。

Found 15 results for 'laptop':
1. Gaming Laptop - $1299 (https://...)
2. Business Laptop - $899 (https://...)
...

主要コマンド一覧

要素の操作

POST /click - 要素をクリック（RefID @e1、CSS セレクター、XPath、テキストコンテンツに対応）
POST /type - 入力欄にテキストを入力（RefID @e3、CSS セレクター、XPath に対応）
POST /select - ドロップダウンのオプションを選択
POST /hover - 要素にホバー
POST /wait - 要素の状態（表示、非表示、有効）を待機
POST /press-key - キーボードキーを押す（Enter、Tab、Ctrl+S など）

データ抽出

POST /extract - 要素からデータを抽出します（複数要素、カスタムフィールドに対応）
POST /get-text - 要素のテキストコンテンツを取得します
POST /get-value - 入力要素の値を取得します
GET /page-info - ページの URL とタイトルを取得します
GET /page-text - ページ内のすべてのテキストを取得します
GET /page-content - HTML 全体を取得します

ページ分析

GET /snapshot - アクセシビリティスナップショットを取得します（⭐ ナビゲーション後は常に呼び出してください）
GET /clickable-elements - すべてのクリック可能な要素を取得します
GET /input-elements - すべての入力要素を取得します

高度な操作

POST /screenshot - ページのスクリーンショットを撮影します（base64 エンコード）
POST /evaluate - JavaScript コードを実行します
POST /batch - 複数の操作を連続して実行します
POST /scroll-to-bottom - ページの最下部までスクロールします
POST /resize - ブラウザウィンドウのサイズを変更します
POST /tabs - ブラウザのタブを管理します（一覧、新規作成、切り替え、閉じる）
POST /fill-form - 複数のフォームフィールドを一度にインテリジェントに埋めます

デバッグと監視

GET /console-messages - ブラウザのコンソールメッセージを取得します（ログ、警告、エラー）
GET /network-requests - ページが行ったネットワークリクエストを取得します
POST /handle-dialog - JavaScript ダイアログ（alert、confirm、prompt）の処理を設定します
POST /file-upload - 入力要素にファイルをアップロードします
POST /drag - 要素をドラッグアンドドロップします
POST /close-page - 現在のページ/タブを閉じます

要素の識別

要素は次の方法で識別できます。

RefID（推奨）: @e1、@e2、@e3
- 最も信頼性の高い方法 - ページの変更に対して安定しています
- /snapshot エンドポイントから RefID を取得します
- スナップショット取得後 5 分間有効です
- 例: "identifier": "@e1"
- 堅牢性のためにマルチストラテジーフォールバックに対応しています
CSS セレクター: #id、.class、button[type="submit"]
- 標準の CSS セレクター
- 例: "identifier": "#login-button"
XPath: //button[@id='login']、//a[contains(text(), 'Submit')]
- 複雑なクエリ向けの XPath 式
- 例: "identifier": "//button[@id='login']"
テキストコンテンツ: Login、Sign Up、Submit
- 一致するテキストを持つボタンやリンクを検索します
- 例: "identifier": "Login"
ARIA ラベル: aria-label 属性を持つ要素
- 自動的に検索されます

ガイドライン

開始する前に:

利用可能なコマンドやそのパラメータが不明な場合は GET /help を呼び出してください
ブラウザが起動していることを確認してください（起動していない場合は、最初の操作時に自動起動します）

自動化の実行中:

ナビゲーション後は常に /snapshot を呼び出して、ページ構造と RefID を取得してください
信頼性と安定性のために、CSS セレクターよりも RefID（@e1 など）を優先してください
ページの変更後は再度スナップショットを取得して、更新された RefID を取得してください
非同期で読み込まれる動的コンテンツには /wait を使用してください
操作の前に要素の状態（表示されているか、有効か）を確認してください
複数の連続した操作には /batch を使用して効率を向上させてください

エラー処理:

操作が失敗した場合は、要素の識別子を確認し、別の形式を試してください
タイムアウトエラーの場合は、タイムアウト値を増やしてください
要素が見つからない場合は、/snapshot を再度呼び出してページ構造を更新してください
エラーは解決策を提案しながらユーザーに明確に説明してください

データ抽出:

fields パラメータを使用して抽出する内容を指定します: ["text", "href", "src"]
複数の要素から抽出するには multiple: true を設定します
抽出したデータはユーザーにとって読みやすい形式に整形してください

完全なワークフロー例

シナリオ: ユーザーがウェブサイトにログインしたい

User: "Please log in to example.com with username 'john' and password 'secret123'"

あなたの操作:

ステップ 1: ログインページに移動する

POST http://localhost:8080/api/v1/executor/navigate
{"url": "https://example.com/login"}

ステップ 2: ページ構造を取得する

GET http://localhost:8080/api/v1/executor/snapshot

レスポンス:

Clickable Elements:
  @e1 Login (role: button)

Input Elements:
  @e2 Username (role: textbox)
  @e3 Password (role: textbox)

ステップ 3: ユーザー名を入力する

POST http://localhost:8080/api/v1/executor/type
{"identifier": "@e2", "text": "john"}

ステップ 4: パスワードを入力する

POST http://localhost:8080/api/v1/executor/type
{"identifier": "@e3", "text": "secret123"}

ステップ 5: ログインボタンをクリックする

POST http://localhost:8080/api/v1/executor/click
{"identifier": "@e1"}

ステップ 6: ログイン成功を待つ（任意）

POST http://localhost:8080/api/v1/executor/wait
{"identifier": ".welcome-message", "state": "visible", "timeout": 10}

ステップ 7: ユーザーに通知する

"Successfully logged in to example.com!"

バッチ操作の例

シナリオ: 複数のフィールドを持つフォームを入力する

5 回の個別の API 呼び出しを行う代わりに、1 回のバッチ操作を使用します:

curl -X POST 'http://localhost:8080/api/v1/executor/batch' \
  -H 'Content-Type: application/json' \
  -d '{
    "operations": [
      {
        "type": "navigate",
        "params": {"url": "https://example.com/form"},
        "stop_on_error": true
      },
      {
        "type": "type",
        "params": {"identifier": "#name", "text": "John Doe"},
        "stop_on_error": true
      },
      {
        "type": "type",
        "params": {"identifier": "#email", "text": "[email protected]"},
        "stop_on_error": true
      },
      {
        "type": "select",
        "params": {"identifier": "#country", "value": "United States"},
        "stop_on_error": true
      },
      {
        "type": "click",
        "params": {"identifier": "#submit"},
        "stop_on_error": true
      }
    ]
  }'

ベストプラクティス

まず情報を確認する： 不明な場合は、/help または /help?command=<name> を呼び出してコマンドを確認してください
まず構造を確認する： ページを移動した後は、必ず /snapshot を呼び出してページを把握してください
アクセシビリティインデックスを使用する： CSS セレクターよりも信頼性が高いです（要素のクラスは動的に変わる場合があります）
動的コンテンツの読み込みを待つ： 非同期で読み込まれる要素を操作する前に /wait を使用してください
可能な場合はまとめて実行する： 複数の操作を順番に行う場合は /batch を使用してください
エラーに適切に対処する： 操作が失敗した場合は、明確な説明と解決策を提示してください
結果を確認する： 操作後、目的の結果が得られたか確認してください

よくあるシナリオ

フォームへの入力

フォームページに移動します
アクセシビリティスナップショットを取得して、入力要素とその RefID を確認します
各フィールドで /type を使用します：@e1、@e2 など
ドロップダウンには /select を使用します
RefID を使用して送信ボタンをクリックします

データのスクレイピング

対象のページに移動します
/wait を使用してコンテンツの読み込みを待ちます
CSS セレクターと multiple: true を指定して /extract を使用します
抽出するフィールドを指定します：["text", "href", "src"]

検索操作

検索ページに移動します
アクセシビリティスナップショットを取得して、検索入力欄を確認します
入力欄に検索クエリを入力します
Enter キーを押すか、検索ボタンをクリックします
結果が表示されるまで待ちます
結果データを抽出します

ログインの自動化

ログインページに移動します
アクセシビリティスナップショットを取得して RefID を確認します
ユーザー名を入力します：@e2
パスワードを入力します：@e3
ログインボタンをクリックします：@e1
成功を示す表示が出るまで待ちます

重要な注意事項

ブラウザーが起動している必要があります（必要に応じて、最初の操作時に自動で起動します）
操作は現在アクティブなブラウザータブで実行されます
アクセシビリティスナップショットは、ページの移動とクリック操作の後に更新されます
すべてのタイムアウト値の単位は秒です
信頼性の高い要素操作には wait_visible: true（デフォルト）を使用してください
localhost:8080 を実際の API ホストアドレスに置き換えてください
認証が必要です：X-BrowserWing-Key ヘッダーまたは JWT トークンを使用してください

トラブルシューティング

要素が見つからない場合：

/snapshot を呼び出して利用可能な要素を確認します
別の識別子形式（アクセシビリティインデックス、CSS セレクター、テキスト）を試します
ページの読み込みが完了しているか確認します

タイムアウトエラー：

リクエストのタイムアウト値を大きくします
要素が実際にページに表示されているか確認します
操作前に適切な状態を指定して /wait を使用します

抽出結果が空の場合：

CSS セレクターが対象の要素に一致しているか確認します
コンテンツが読み込まれているか確認します（先に /wait を使用します）
別の抽出フィールドまたはタイプを試します

クイックリファレンス

# Discover commands
GET localhost:8080/api/v1/executor/help

# Navigate
POST localhost:8080/api/v1/executor/navigate {"url": "..."}

# Get page structure
GET localhost:8080/api/v1/executor/snapshot

# Click element
POST localhost:8080/api/v1/executor/click {"identifier": "@e1"}

# Type text
POST localhost:8080/api/v1/executor/type {"identifier": "@e3", "text": "..."}

# Extract data
POST localhost:8080/api/v1/executor/extract {"selector": "...", "fields": [...], "multiple": true}

レスポンス形式

すべての操作は次を返します：

{
  "success": true,
  "message": "Operation description",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    // Operation-specific data
  }
}

エラーレスポンス：

{
  "error": "error.operationFailed",
  "detail": "Detailed error message"
}

Markdown 対応

ログインしてコメント

基本情報

作者: memtensor
リポジトリ: memtensor/memos
カテゴリ: エージェントワークフロー
インストール数: 133
GitHub スター: 12,157

問題を報告