explorbot-setup

Explorbot のセットアップ

Explorbot をユーザーのプロジェクトにインストールし、プロバイダーを接続して、アプリへのアクセス方法を設定し、1 回のナビゲーションで動作を確認します。

設定ファイル、ナレッジファイル、生成されたテストはすべてリポジトリに保存されるため、ほかのコードと同様にレビューおよびバージョン管理されます。ローカルにインストールする目的はそこにあります。

プロジェクトにインストールせずに Explorbot を実行する場合、このスキルは適していません — [[explorbot-fundamentals]] で説明しています。npx とプロバイダーを使い、プロジェクトファイルは作成しません。

npx explorbot navigate <path> が終了コード 0 で終了した時点で、この作業の範囲は終了です — 探索とテストについては [[explorbot-fundamentals]] を参照してください。

1. 要件

• Node ≥ 24 または Bun が必要です。どちらも存在しない場合は、ここで中止してください。ランタイムをインストールしてはいけません。
• 生成される設定では import を使うため、package.json は ESM である必要があります。npm init -y は CommonJS を生成します。既存のファイルで "type" がない場合、または "commonjs" になっている場合は、変更する前に確認してください。ユーザーが変更を希望しない場合は、explorbot.config.mjs（--config で指定）を作成してください。
• Explorbot は CRUD の多いアプリ向けです。対象がランディングページ、ブログ、CMS、または静的サイトの場合は、インストール前に警告してください。

2. インストール

npm pkg set type=module
npm i explorbot --save
npx playwright install chromium     # ~/.cache/ms-playwright, once per machine
npx explorbot init                  # writes explorbot.config.js, .env, output/

3. プロバイダー

プロバイダー、モデル ID、キーの環境変数名は、このスキルではなく Explorbot で管理されています。 生成される設定には 1 つのプロバイダーが含まれています。ほかのプロバイダーのパッケージ名とモデル ID はドキュメントの basics/providers.md に、最新の推奨事項は models.json に記載されています。

• ユーザーがアカウントを持っているプロバイダーを尋ね、テンプレートと異なる場合は、インポートとモデルの 3 行を置き換えてください。
• 対応するプロバイダーパッケージを npm i でインストールしてください。

キーを設定するには、ユーザーにエディターで .env に貼り付けて「続ける」と入力するよう伝え、その後 grep -q "^<KEY>=." .env で確認します。.env が Git の対象外であることを確認してください。キーを復唱してはいけません。

~/.explorbot/.env も毎回の実行時に読み込まれ、プロジェクトの .env に設定されていない変数が補完されます。

4. アプリの URL

ユーザーに URL を尋ね、設定ファイルの web.url に記述してください。ホストのみを指定し、パスは含めません。Explorbot は自動でクリック、入力、送信を行うため、本番環境よりステージング環境が適しています。

推測してはいけません。プロジェクト内で根拠を探してください。たとえば、package.json のスクリプト、.env ファイル、フレームワークのポートを確認し、見つかった情報とその出典を提示します。それ以外の場合は、通常のテキストでユーザーに尋ねてください。このスキルや記憶をもとに URL を提案してはいけません。

5. 確認

順番に手順を進めます。最初に失敗した箇所で止め、問題を修正してから再開してください。

1. curl -sS -o /dev/null -w "%{http_code}\n" <url> — 000 は DNS、VPN、またはホストの誤り、5xx はアプリ自体の問題です。200 の場合は手順 3 に進みます。

2. 3xx／401／403 の場合は、curl -sIL -o /dev/null -w "%{url_effective}\n" <url> を実行します。最終 URL がログイン画面のような場合は認証情報が必要です。先に手順 4 を行ってください。

3. npx explorbot navigate <path> --session — 終了コード 0 でセットアップは完了です。--session は Cookie を output/session.json に保存します。終了コード 1 の場合は、output/explorbot.log を確認してください。認証画面で止まった場合は手順 4 に進み、それ以外の場合はパスが誤っているか、ページが壊れています。

4. 認証を設定します。まずナレッジ、次に値の順で設定してください。

   npx explorbot knows /login      # reuse existing variable names if auth knowledge exists
   npx explorbot learn "/login" 'Sign in with ${env.APP_USER} / ${env.APP_PASSWORD}'
   

   認証情報の名前だけを指定してください。セレクターや DOM のヒントは不要です。フィールドは Navigator が特定します。次に、ユーザーに 2 つの変数を .env に追加してもらい、grep で確認してから、手順 3 を再実行してください。本番環境以外のテストアカウントを依頼してください。

   認証でまだ失敗する場合は、learn を使ってナレッジに実際のフォーム URL、SSO、二要素認証についての文を 1 つ追加してください。書き換えは行わないでください。

npx explorbot context <path> は AI 呼び出しを行わずに見出し、一致したナレッジ、操作可能な要素を出力します。手順のデバッグを無料で行う際に使用してください。

6. 引き継ぎ

プロジェクトに追加されたものを報告してください。explorbot.config.js、.env（Git の対象外）、knowledge/、セッションが保存された output/ です。その後、最初のコマンドとともに [[explorbot-fundamentals]] に引き継いでください。

npx explorbot explore /<crud-page> --max-tests 10

アンチパターン

• ユーザーが Explorbot を試したいだけなのに、プロジェクトにインストールすること。これは [[explorbot-fundamentals]] を参照してください。
• ドキュメントや生成された設定を確認せずに、プロバイダー、モデル ID、キー変数の名前を挙げること。
• ナレッジファイルや設定にシークレットを記載すること。必ず ${env.NAME} を使用し、値は .env に記載してください。
• explorbot start を実行させること。これは対話型 TUI なので、ユーザーに実行してもらってください。
• 対象ページ、機能、テスト件数を最初に尋ねること。