nstbrowser-ai-agent

nstbrowser-ai-agent

このスキルは、Nstbrowser のワークフロー向けです。

デフォルトの操作モード

動作確認済みの Nstbrowser プロファイルを使用し、すべてのブラウザーコマンドで同じ --profile <name-or-id> を指定してください。

• AI エージェントにとって、これが最も安全なデフォルト設定です。
• タスクで分離された複数ステップのワークフローが本当に必要な場合に限り、--session を導入してください。
• 1 つのデーモンセッション内で --profile twitter1 を指定した場合は、twitter1 に切り替わります。以前のプロファイルが引き続きアクティブだと思い込まないでください。
• @e1 などの ref が、ページ遷移後や別のセッションでも引き続き使えると思い込まないでください。

前提条件

• Nstbrowser デスクトップクライアントがインストールされ、実行中であること
• nstbrowser-ai-agent config set key YOUR_API_KEY または NST_API_KEY で API キーが設定されていること
• ユーザーが別のホスト／ポートを設定していない限り、NST サービスに http://127.0.0.1:8848 で接続できること

最初の確認

環境が未設定の可能性がある場合は、最初に以下を実行してください。

nstbrowser-ai-agent nst status
nstbrowser-ai-agent profile list
nstbrowser-ai-agent --version

すぐに始める

ユーザーがより専門的な方法を明示的に求めていない限り、この方法を使用してください。

nstbrowser-ai-agent nst status
nstbrowser-ai-agent profile list
nstbrowser-ai-agent verify --profile YOUR_PROFILE
nstbrowser-ai-agent --profile YOUR_PROFILE open https://example.com
nstbrowser-ai-agent --profile YOUR_PROFILE snapshot -i
nstbrowser-ai-agent --profile YOUR_PROFILE click @e1
nstbrowser-ai-agent --profile YOUR_PROFILE get url
nstbrowser-ai-agent --profile YOUR_PROFILE screenshot --annotate /tmp/page.png

YOUR_PROFILE を profile list に表示されるプロファイルに置き換えてください。

まだクリーンなプロファイルがない場合：

nstbrowser-ai-agent profile create task-profile
nstbrowser-ai-agent --profile task-profile open https://example.com

NST の基本コマンド

設定

nstbrowser-ai-agent config set key YOUR_API_KEY
nstbrowser-ai-agent config show
nstbrowser-ai-agent config get key

診断

以下の形式のみを使用してください。

nstbrowser-ai-agent nst status
nstbrowser-ai-agent profile list
nstbrowser-ai-agent verify YOUR_PROFILE
nstbrowser-ai-agent verify --profile YOUR_PROFILE
nstbrowser-ai-agent repair

プロファイル管理

• profile list 候補となるプロファイルの一覧を人が読みやすい形式で素早く確認する場合に使用します。 重要なパラメーター：--verbose を指定すると、短い概要ではなく、NST プロファイルオブジェクト全体が返されます。

• profile list-cursor --page-size <size> [--cursor <token>] [--direction next|prev] プロファイルが多数あり、確実にページを切り替えて表示したい場合に使用します。 --page-size は 1 ページあたりの件数を制限します。 --cursor は、以前に返されたカーソルから続けて表示します。 --direction は、そのカーソルが次のページ用か前のページ用かを NST に指定します。

• profile show <name-or-id> 1 つのプロファイルのグループ、プロキシ、タグ、プラットフォーム、または最終起動情報を正確に確認する場合に使用します。

• profile create <name> [--platform <Windows|macOS|Linux>] [--kernel <version>] [--group-id <id>] 新しいタスク用のクリーンなプロファイルが必要な場合に使用します。 --kernel は優先するカーネルのマイルストーンを指定します。NST は、現在サポートされているバージョンに調整する場合があります。 任意のプロキシパラメーター： --proxy-host <host>、--proxy-port <port>、--proxy-type <http|https|socks5>、--proxy-username <user>、--proxy-password <pass>。

• profile proxy show <name-or-id> プロキシの動作が不審で、保存済みのプロキシ設定と最後のプロキシチェック結果を確認したい場合に使用します。

• profile proxy update <name-or-id> --host <host> --port <port> [--type <type>] [--username <user>] [--password <pass>] プロファイルの Cookie や履歴は保持したまま、別のプロキシに変更する場合に使用します。

• profile proxy reset <name-or-id> [name-or-id...] プロファイルをローカル／デフォルトのルーティングに戻す場合に使用します。

• profile tags list、profile tags create、profile tags update、profile tags clear エージェントのワークフローを繰り返す際に、プロファイルを整理したい場合に使用します。 profile tags create で必要なのはタグ名のみです。CLI がデフォルトのタグ色を設定します。

• profile groups list、profile groups change <group-id> <name-or-id> [name-or-id...] 有効な NST グループ ID を確認したり、プロファイルを特定のグループに移動したりする場合に使用します。

ブラウザー管理

• browser list 実行中のプロファイルブラウザーや一時ブラウザーを確認する必要がある場合に使用します。

• browser start <name-or-id> [--headless] [--auto-close] 最初の open より前にブラウザーを起動しておきたい場合に使用します。 --headless はヘッドレスでの起動を要求します。 --auto-close は、所有者が終了したときに NST がそのブラウザーを閉じるよう要求します。

• browser pages <name-or-id> 実行中のブラウザーで、現在デバッグ可能なページを確認する必要がある場合に使用します。

• browser debugger <name-or-id> デバッガーポートとブラウザーレベルの WebSocket エンドポイントを確認する必要がある場合に使用します。

• browser cdp-url <name-or-id> ブラウザーレベルの CDP WebSocket URL だけが必要な場合に使用します。

• browser connect <name-or-id> 必要に応じて NST にブラウザーを起動させ、接続情報をすぐに返してほしい場合に使用します。

• browser start-once [--platform <platform>] [--kernel <kernel>] [--headless] [--auto-close] 保存済みのプロファイルに残す必要のない、一時的な作業に限って使用します。

• browser cdp-url-once 一時ブラウザーで十分で、CDP URL だけが必要な場合に使用します。

• browser connect-once [--platform <platform>] [--kernel <kernel>] 1 つのコマンドで一時ブラウザーを作成し、CDP 接続情報も返す場合に使用します。

• browser stop <name-or-id> and browser stop-all タスクの後にクリーンアップするときや、古いブラウザーを終了するときに使用します。

NST コマンドの使い分け

• 環境自体に問題がある可能性がある場合は、まず nst status を使用します。
• 作業をすぐに始めるためにプロファイル名だけが必要な場合は、profile list を使用します。
• ワークスペースにプロファイルが多すぎて 1 つのリストに収まらない場合は、profile list-cursor を使用します。
• 特定のプロファイルの設定について確認する場合は、profile show を使用します。
• プロファイルが古い、または信頼できない可能性がある場合は、実際の作業の前に verify を使用します。
• verify でブラウザーの状態が古いと報告された場合や、アタッチの失敗が繰り返される場合は、repair を使用します。
• ブラウザーの起動を明示的に制御したい場合は、browser start を使用します。
• 管理ではなくタスクの実行が目的の場合は、ブラウザー操作に --profile <name-or-id> を直接指定します。

ブラウザー操作

すべてのブラウザー操作で --profile <name-or-id> を使用できます。値にはプロファイル名または UUID を指定できます。

推奨ワークフロー

一時ブラウザーよりも、このワークフローを優先してください。

nstbrowser-ai-agent --profile YOUR_PROFILE open https://example.com
nstbrowser-ai-agent --profile YOUR_PROFILE snapshot -i
nstbrowser-ai-agent --profile YOUR_PROFILE click @e1
nstbrowser-ai-agent --profile YOUR_PROFILE get url
nstbrowser-ai-agent --profile YOUR_PROFILE screenshot --annotate /tmp/page.png
nstbrowser-ai-agent browser stop YOUR_PROFILE

セッションワークフロー

ユーザーが分離環境や、デーモンを利用した長時間の実行を明示的に必要としている場合に限り、これを使用します。関連するすべてのコマンドで、同じ --session と --profile を指定してください。

同じ --session 内で、タスクの対象を意図的に別の Nstbrowser プロファイルに切り替える場合は、切り替えコマンドで新しい --profile を明示的に指定し直してください。

nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE open https://example.com
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE snapshot -i
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE click @e1
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE tab new https://iana.org
nstbrowser-ai-agent --session task-run --profile YOUR_PROFILE get url

一時ブラウザーのワークフロー

ユーザーが使い捨てのブラウザーを求めており、プロファイルを保持する必要がない場合に限り、browser start-once を使用します。

nstbrowser-ai-agent browser start-once
nstbrowser-ai-agent open https://example.com
nstbrowser-ai-agent snapshot -i

close は既存のブラウザーを停止するだけで、新たに起動したり作成したりすることはありません。Agent API 経由で特定の NST プロファイルブラウザーを停止するには、close --profile <name-or-id> を使用します。 セッションのコンテキストを利用できない場合、単独の close は実行中の Agent ブラウザーが 1 つだけならそれを停止し、複数のブラウザーが実行中の場合は --profile の指定が必要です。

便利なグローバルオプション

--profile <name-or-id>   Use a specific Nstbrowser profile
--session <name>         Use an isolated daemon session
--session-name <name>    Auto-save and restore browser state
--json                   Machine-readable output
--headers <json>         Scoped HTTP headers for the opened origin
--proxy <server>         Override proxy for the launched browser session
--proxy-bypass <hosts>   Bypass proxy for specific hosts
--annotate               Add numbered labels to screenshot output
--full                   Full-page screenshot

推奨パターン

1. 環境について不明な点がある場合は、nst status と profile list から始めます。
2. click または fill の前に snapshot -i を使用し、参照が最新であることを確認します。
3. 専用の --session を意図的に使用している場合を除き、すべてのブラウザーコマンドで同じ --profile を指定します。
4. 分離されたワークフローが必要な場合に限り --session を使用し、その場合は実行全体を通じて --session と --profile の両方を一貫して指定します。
5. NST からブラウザーの状態が古い、または複数のインスタンスが停止していると報告された場合は、再試行の前に repair を使用します。
6. 既存のプロファイルでプロキシまたはネットワーク設定に問題がある場合は、問題のないプロファイル、または新しく作成したプロファイルを優先します。

よくあるエラーからの復旧

• Profile not found：profile list を実行し、正確なプロファイル名または UUID を使用してください。
• @e1 not working：ナビゲーション後は参照が変わるため、snapshot -i をもう一度実行してください。
• 参照は順序に依存します。先に生成し、同じセッション内で後から使用してください。
• @e1 が CSS として扱われる場合、プロファイルまたはセッションのコンテキストを変更したか、同じ --profile を再度渡し忘れている可能性があります。
• Browser not running：browser start <name-or-id> を実行するか、open を再実行してください。
• NST agent not responding：Nstbrowser デスクトップクライアントを起動してから、nst status を実行してください。
• Command appears stale：新しい --session 名を使用するか、browser stop <name-or-id> ／ browser stop-all を実行してください。
• open https://example.com で Chrome のエラーページが表示される場合：現在のプロファイルのプロキシに問題がある可能性があるため、クリーンなプロファイルに切り替えるか、新しいプロファイルを作成してください。

注意事項

• browser start-once は、Nstbrowser が管理する一時的なブラウザーを作成します。
• プロファイルに紐づくセッションでは、Cookie とサイトストレージが Nstbrowser プロファイル自体に保持されます。
• --profile は Nstbrowser のプロファイル選択にのみ使用します。