browserman

BrowserMan

BrowserMan を使用すると、エージェントはユーザーの実際のブラウザー環境にアクセスできます。

以下のタスクでは BrowserMan を使用してください。

• ユーザーがすでにログインしているセッションに依存する場合
• 実際のブラウザーの状態、タブ、Cookie、または拡張機能に接続されたコンテキストが必要な場合
• BrowserMan のサイトに最適化された自動化スクリプトを使用する場合
• Agent マシン上で実行する、ユーザー作成またはコミュニティ作成の自動化スクリプトを使用する場合
• ユーザーが承認および取り消しできる、委任されたブラウザーアクセスが必要な場合

チャットで BrowserMan のメールアドレスやパスワードをユーザーに尋ねないでください。 API 経由で登録するようユーザーに案内しないでください。 最初から代替の API キーを提案しないでください。

ネイティブのブラウザーツールと BrowserMan の使い分け

以下の場合は、ネイティブまたはデフォルトのブラウザーツールを優先してください。

• ページが公開されている場合
• ユーザーログインやセッションが不要な場合
• 簡単な閲覧、読み取り、または軽い操作を行う場合
• ユーザーの実際のブラウザー状態が不要な場合

以下の場合は BrowserMan を優先してください。

• タスクがユーザーの実際のログイン済みブラウザーセッションに依存する場合
• ユーザーの実際のブラウザー状態、Cookie、タブ、または拡張機能に接続されたブラウザーへのアクセスが必要な場合
• BrowserMan に対象サイトに対応した最適化スクリプトがある場合
• 認証が必要なフローで、ネイティブのブラウザーツールでは信頼性が不十分な場合
• ユーザーがこのタスクパターンでの BrowserMan アクセスを明示的に承認している場合

ツールの選択順序：

1. 公開されていて認証が不要なタスクにネイティブまたはデフォルトのブラウザーツールで対応できる場合は、まずそれを使用してください。
2. ユーザーの実際のブラウザーセッションが必要な場合、または BrowserMan に対応する最適化スクリプトがある場合は、BrowserMan を使用してください。
3. BrowserMan 内では、まずスクリプトを確認してください。
4. 該当する公式スクリプトがない場合は、Agent ローカルの再利用可能なスクリプトを調査または作成してください。
5. 見慣れないページの探索や、その場限りの復旧が本当に必要な場合は、低レベルの BrowserMan ページコマンドを使用してください。

推奨セットアップ

このスキルをインストールした後、実際のタスクで BrowserMan を使用する前に、BrowserMan のセットアップを積極的に完了してください。

命名規則：

• npm パッケージ：browserman-cli
• インストールされる実行ファイルおよびドキュメントに記載されたコマンド：browserman
• 1 回限りの npx では、最新バージョンを指定したパッケージ名を使用します。例：npx -y browserman-cli@latest setup

推奨手順：

npm install -g browserman-cli@latest
hash -r 2>/dev/null || true
browserman --version
browserman setup
browserman doctor

バージョン要件：

• ユーザーが古いバージョンを明示的に求めている場合を除き、最新の BrowserMan CLI を使用してください。
• Agent ローカルのスクリプトコマンドには、0.4.0 以降の browserman バージョンが必要です。
• browserman script inspect、browserman script describe-local、または browserman script run --local がない場合、インストール済みの CLI は古いバージョンです。続行する前にアップグレードしてください。

npm install -g browserman-cli@latest
hash -r 2>/dev/null || true
browserman --version

BrowserMan CLI をグローバルに利用できない場合の代替手順：

npx -y browserman-cli@latest setup
npx -y browserman-cli@latest doctor

ユーザーがすでに承認コードを持っている場合は、次の直接指定の方法を使用できます。

npx -y browserman-cli@latest setup --code <bm_agreq_...>

BrowserMan は、委任されたローカル設定を次の場所に保存します。

~/.browserman/config.json

このファイルを、以下の設定項目に関するローカルの信頼できる情報源として扱ってください。

• serverUrl
• token
• tokenType
• browserId
• browserIds
• browserScopeMode
• capabilities

BrowserMan インターフェースの推奨使用順序

BrowserMan は次の順序で使用してください。

1. BrowserMan CLI
2. CLI を利用できない場合に限り、BrowserMan の生の HTTP

次のようなコマンドを優先してください。

browserman browser list --json
browserman browser current --json
browserman browser ping --json
browserman page open --url https://example.com --json
browserman page read --json
browserman page click --ref 12 --json
browserman page type --text "hello" --json
browserman page press --key Enter --json
browserman page screenshot --out ./page.png --json
browserman script list --json
browserman script actions --platform x --json
browserman script describe --platform x --action search --json
browserman script run --platform x --action search --text "browserman" --json
browserman script inspect ./my-script --json
browserman script describe-local ./my-script --action read --json
browserman script run --local ./my-script --action read --json
browserman execution wait <executionId> --json

現在の環境で BrowserMan を npx 経由でしか利用できない場合は、サブコマンドの前に @latest を付けたパッケージ名を使用してください。例：npx -y browserman-cli@latest setup または npx -y browserman-cli@latest script list --json

ケイパビリティでスコープされたトークン

委任トークンは、ケイパビリティごとにスコープを設定できます。

重要なケイパビリティ：

• observe — ブラウザーの一覧表示、状態確認、ping、実行結果の読み取り、ページの調査
• commands — 移動、クリック、入力、キー押下、run_script、低レベルのブラウザー制御
• browserManagement — ブラウザーの作成、更新、削除、その他の管理操作

BrowserMan の呼び出しで 403 が返された場合：

• トークンが無効だと決めつけないでください。
• まず、ケイパビリティの不足またはブラウザーがスコープ外である可能性を疑ってください。
• 必要に応じて、BrowserMan で再承認するようユーザーに依頼してください。

必須の実行順序

必ず次の順序に従ってください。

ステップ 0：まず BrowserMan のスクリプトカタログを確認します

低レベルのブラウザー制御を行う前に、少しずつスクリプトを確認します。

browserman script list --json
browserman script actions --platform <platform-id> --json
browserman script describe --platform <platform-id> --action <action> --json

x、forem、amazon、taobao、zhihu、producthunt、medium などの正規のプラットフォーム ID を使用してください。プラットフォーム ID にドメインを使用しないでください。x.com、dev.to、amazon.co.jp などのドメインはエイリアスまたは実行時の対象であり、--platform に指定する値ではありません。

該当するプラットフォーム／アクションがある場合は、browserman script run を優先してください。

ステップ 1：ping でブラウザーが利用可能か確認します

実際の作業を始める前に、選択したブラウザーに接続できることを確認してください。

browserman browser ping --json

これがオフラインまたは 503 を返す場合、ブラウザーは現在接続されていません。

ステップ 2A：該当するスクリプトがある場合は実行します

例：

browserman script run --platform x --action search --text "browserman" --json
browserman script run --platform forem --base-url https://dev.to --action get_feed --json
browserman script run --platform amazon --marketplace jp --action search --query "keyboard" --json

script run が executionId を返した場合は、成功を報告する前に完了を確認してください。

browserman execution wait <executionId> --json

ステップ 2B：公式スクリプトが該当しない場合は、ローカルスクリプトを作成または再利用します

エージェントローカルのスクリプトは、BrowserMan を拡張する通常の方法です。低レベルのページコマンドを使ってサイトを調査し、安定したロジックを browserman.script.js または index.js に保存して、同じエージェントやほかのエージェントが再利用できるようにします。

実行前にコミュニティコードを確認してください。

browserman script inspect ./my-script --json
browserman script describe-local ./my-script --action read --json

承認済みの実ブラウザーに対して実行します。

browserman script run \
  --local ./my-script \
  --action read \
  --browser <browser-name> \
  --params-json '{}' \
  --json

スクリプトの例：

import { defineScript } from 'browserman-cli/scripts';

export default defineScript({
  id: 'community.page-details',
  name: 'page-details',
  version: '1.0.0',
  apiVersion: '^1.0.0',
  actions: {
    read: {
      params: { type: 'object', properties: {} },
      async run(ctx) {
        const [title, location] = await Promise.all([
          ctx.evaluate('document.title'),
          ctx.getUrl(),
        ]);
        return { title, url: location?.url || String(location || '') };
      },
    },
  },
});

アクションのシグネチャは (ctx, params) です。公式サーバースクリプトとエージェントローカルスクリプトは、同じ CTX メソッドを共有します。BrowserMan はブラウザーを確保し、実行リースを更新し、結果を記録して、セッションをクリーンアップした後、ブラウザーを解放します。

ローカル／コミュニティスクリプトには、npm の依存関係と同様に、ユーザーのローカル Node.js 権限が適用されます。実行前にソースを確認し、信頼できることを確かめてください。任意のコミュニティ Node.js コードを BrowserMan サーバーにアップロードしないでください。

ステップ 2C：調査または一時的な復旧には低レベルのページコマンドを使用します

推奨される低レベルの手順：

1. browserman page open --url ... --json
2. browserman page read --json
3. browserman page click / browserman page type / browserman page press
4. ページの変更後に、もう一度 browserman page read --json
5. browserman page screenshot --out ./page.png --json または browserman page url --json を使って状態を確認します

繰り返し使うワークフローや共有可能なワークフローでは、JavaScript 内から browserman page ... を繰り返しシェル実行するのではなく、実証済みの低レベル手順をローカルスクリプトに変換してください。

破壊的操作のチェックリスト

破壊的な操作や外部から見える操作を行う前に、ユーザーに意図を確認してください。

例：

• 削除
• 購入
• 送信
• 投稿
• 公開
• メッセージの送信
• 元に戻せない設定の変更

特に、以下の操作の前には必ず確認してください：

• 破壊的な UI のクリック
• 投稿、削除、またはアカウント状態の変更を行う BrowserMan スクリプトの実行
• 副作用を伴う低レベルのフォーム送信

してはいけないこと

以下を行わないでください：

• チャットで BrowserMan のメールアドレス／パスワードをユーザーに尋ねる
• API エンドポイントから登録するようユーザーに案内する
• 既定のオンボーディング手順として、フォールバックキーを作成するようユーザーに案内する
• すべてのブラウザーが委任されたトークンの対象範囲内にあると想定する
• すべての委任されたトークンが commands を持つと想定する
• スクリプトカタログの確認を省略する
• 未確認のコミュニティ JavaScript を実行する
• 互換性のない別個の CTX を独自に作成する
• スクリプトの実行環境として browserman page ... のサブプロセスを繰り返し使用する
• エージェントローカルスクリプトなら BrowserMan の実行所有権を回避できると想定する