prima

Prima

Prima は playwright-cli の上に構築された AI レイヤーです。playwright-cli がすでに開いているブラウザーを操作し、ロケーターではなく言葉で記述された動作を受け取り、プレーンテキストのエンベロープを返します。Prima は npx 経由で呼び出します（npx prima-cli ...）。playwright-cli はインストール方法に応じて呼び出します。グローバルにインストールされている場合は playwright-cli ... を、そうでない場合は npx -y @playwright/cli ... を使います。npx playwright-cli@latest は絶対に使わないでください。その名前のパッケージは存在せず、「could not determine executable to run」というエラーが発生します。

ウェブページ上の操作では、playwright-cli よりも Prima を優先してください。 スナップショットは Prima 内にとどまり、コンテキストに取り込まれません。また、そのページについてすでに持っている調査マップや記録済みの経験を再利用するため、同じシナリオを手動で操作する場合に比べて、トークンの使用量を大幅に抑えられます。Prima に該当するコマンドがない場合、または AI モデルが設定されていない場合（その場合も pw は動作します）は、playwright-cli を直接使ってください。

モデルとプロバイダー

Prima は環境から取得した AI モデルを必要とします。初期化の手順はありません。複数の AI プロバイダー（OpenRouter、OpenAI、Anthropic、Groq、Mistral、Google、Poolside）に対応しています。

対応するプロバイダー、各役割に推奨されるモデル、環境ですでに設定されている API キーを確認するには、次を実行します。

npx prima-cli recommended-models

キーやプロバイダーの選択をユーザーが設定できるよう、必ず npx prima-cli recommended-models を使ってください。

1. プロバイダー別（推奨）

API キーをエクスポートして、プロバイダー変数を設定します。Prima はそのプロバイダーで推奨されるモデルを、3 つすべての役割（高速実行用の model、スクリーンショット用の visionModel、スマートな計画用の agenticModel）に自動で選択します。

# OpenRouter
export OPENROUTER_API_KEY="sk-or-..."
export PRIMA_CLI_AI_PROVIDER=openrouter

# OpenAI
export OPENAI_API_KEY="sk-..."
export PRIMA_CLI_AI_PROVIDER=openai

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
export PRIMA_CLI_AI_PROVIDER=anthropic

# Groq
export GROQ_API_KEY="gsk_..."
export PRIMA_CLI_AI_PROVIDER=groq

# Mistral
export MISTRAL_API_KEY="..."
export PRIMA_CLI_AI_PROVIDER=mistral

# Google
export GOOGLE_GENERATIVE_AI_API_KEY="..."
export PRIMA_CLI_AI_PROVIDER=google

2. 個別のモデルを固定

プロバイダー変数を使わずにすべての役割のモデルを明示的に固定する場合や、プロバイダーを組み合わせる場合は、provider/model-id を使います。

export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-20b:nitro        # fast / general
export PRIMA_CLI_VISION_MODEL=openrouter/openai/gpt-5.6-luna         # screenshots
export PRIMA_CLI_AGENTIC_MODEL=openrouter/openai/gpt-5.6-luna        # smart / agentic

ビジョンモデル

スクリーンショットの分析にはビジョンモデルが必要です。

• PRIMA_CLI_AI_PROVIDER を使用する場合、プロバイダーの推奨ビジョンモデルが自動的に選択されます（ビジョンを提供していない Poolside を除きます）。
• 個別のモデルを固定する場合は、PRIMA_CLI_VISION_MODEL を設定します（または単回の実行では --vision-model <model> を渡します）。設定しなくても Prima は動作しますが、check はスクリーンショットを調べず、実行ログから結果を判定します。

設定の確認

• npx prima-cli config は、このディレクトリで解決される設定を出力します。機械可読形式にするには --json を指定します。
• すべての PRIMA_CLI_* 変数は対応する EXPLORBOT_* 変数（PRIMA_CLI_AI_PROVIDER / EXPLORBOT_AI_PROVIDER、PRIMA_CLI_AI_MODEL / EXPLORBOT_AI_MODEL、PRIMA_CLI_VISION_MODEL / EXPLORBOT_VISION_MODEL、PRIMA_CLI_AGENTIC_MODEL / EXPLORBOT_AGENTIC_MODEL）に対応し、そちらより優先されます。そのため、既存の Explorbot の設定に影響しません。

セッション

Prima はブラウザーを起動しません。playwright-cli が開いているセッションに接続し、完了後は切断します。セッションを閉じることはありません。

playwright-cli open <url>      # start
npx prima-cli <command> ...    # drive
playwright-cli close           # end

• セッションが開いていない場合、Prima のすべてのコマンドは失敗し、実行すべき playwright-cli open コマンドを表示します。これを実行してから、再試行してください。
• npx prima-cli browser start はセッションが開いていることだけを確認し、そのセッションを表示します。
• 複数の playwright-cli セッションが開いている場合は、--pw-session <title> でセッションを選択します。--endpoint <ep> を使うと、検出を省略してブラウザーサーバーに直接接続します。
• Prima には Node.js 22 以上が必要です。
• すべてのコマンドは実行時に記録されます。npx prima-cli report を実行すると、ブラウザーが開いているかどうかにかかわらず、セッションから html レポートと markdown レポートが生成されます。
• explorbot がすでにインストールされている場合は、npx explorbot prima <command> で同じツールを実行できます。

ティア

まずは check から始めます。その上の段で処理できない場合にのみ、1段下に進んでください。

npx prima-cli check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
npx prima-cli do "open the account menu" "choose settings" "switch the theme to dark" "check it took effect"
npx prima-cli pw "({ page }) => page.click('[data-test=submit]')"

• 残りの一連の操作をすべて do に渡してください。呼び出しごとに1ステップだけ渡してはいけません — それがコスト面での優位性のすべてです。
• pw が受け取るのは実行可能なコードのみです。説明を渡してはいけません。また、check／do にロケーターを渡してはいけません。
• check が確定するのは結果であり、報告ではありません。「フィールドを一覧表示して」や「表示されている内容を報告して」と依頼しても、確定すべき内容がないため not verified が返されます。質問は ask に、ナビゲーションは do に渡してください。
• verify が受け取るアサーションは必ず1つだけです。引数を複数指定すると、主張が複数になるのではなく、エラーになります。コマンドを繰り返すか、1文で記述してください。
• check と do の実行には、数分かかることがあります。強制終了して再試行しないでください。
• check はすでに開いているページで実行され、再読み込みはしません。そのため、開いているダイアログ、選択中のタブ、入力済みのフォームはそのまま保たれます。
• --expected は複数の結果を指定するために繰り返し使用できます。指定しない場合は、シナリオのテキストが唯一の期待結果になります。
• pw の下層には playwright-cli 自体があります。

また、それぞれが受け取る引数は次のとおりです。

npx prima-cli ask "<question>"        # --no-vision answers from structure only
npx prima-cli verify "<assertion>"    # alias assert
npx prima-cli go "<target>"           # a url, a path, or a page described in words
npx prima-cli status <hash>

research、report、config、recommended-models は引数を取りません。browser が受け取るのはサブコマンドのみです。research は現在表示しているページ全体をマッピングします。--data を指定すると抽出も行い、--deep を指定すると非表示要素も展開し、--fresh を指定するとキャッシュを通さずに再マッピングします。そのページについての質問は、代わりに ask に渡してください。それぞれについて npx prima-cli <command> --help を実行してください。

結果の読み方

• ### Result の判定を信頼してください。 PASSED の結果を別のコマンドで再検証するのは、このツールがなくそうとしている無駄です。
• ok: true は、依頼した操作が成功したことを意味します。別の経路に切り替えたり、再試行したりすることはありません。
• ### Steps では、各行に ok、FAIL、?? のいずれかが付いています。?? は、指示は実行されたものの、確認されないまま実行が終了したことを示します。実行された操作はその上に記載されているので、それをもとに判断してください。コマンドが失敗するのは、FAIL がある場合、またはページが指示を実行できなかった場合のみです。
• not verified は、その結果が確認されなかったことを意味します。誤りだという意味でも、失敗だという意味でもありません。
• 実行結果と画像が食い違う場合は、ページ構造を優先します。 結果に resolved: の行が続いている場合、食い違いは解決済みです。アクセシビリティツリーがスクリーンショットを支持したため、実行ログが誤りであり、PASSED または FAILED の判定が確定しています。両方の見解がその下に引用されていても、ほかの判定と同じように信頼してください。
• CONTRADICTION は判定ではなく、確認結果です。 食い違いを解決できなかった場合、またはツリーが実行を支持した場合にのみ残ります。ページには存在するものの表示されていない内容があり、その可能性の高いレンダリングバグが resolved: の行に記されています。両方の見解が結果の下に引用され、### Artifacts にはディスク上の html、aria、スクリーンショットが記載されています。それらを読み、ページを自分で判断してください。アプリのバグとして扱い、何よりも先に確認してください。
• go で URL に移動しても、リダイレクトは追いません。### Page の下に表示される (redirected: <target> → <url>) がその結果です。ログイン画面やアクセスルールによって、ブラウザーが別の場所に移動したことを示しています。それがテスト対象ではない場合は、まず do でサインインしてから、もう一度移動してください。
• 結果が実行ログのみに基づいており、スクリーンショットで裏付けられていないことを示す ### Warning がある場合は、PRIMA_CLI_VISION_MODEL を設定するか、--vision-model を渡してください。それまでは check の視覚的な主張を信頼しないでください。
• 実行が完了できなかった場合は、その旨が示されます。アプリの失敗として報告されることはありません。
• npx prima-cli config を実行すると、各ロールの回答に使われるモデルが表示されます。

アーティファクト

すべてのコマンドは、確認した内容を書き出します。エンベロープの最終行にその場所が記載されます — details: prima status <hash> — また、do は各ステップの後にディレクトリをそのまま page after each step: として出力します。<site>/output/prima/<hash>/ の下には、次のファイルがあります。

• aria.yml — ページ全体のアクセシビリティツリーです。値と状態も含まれます：switch "Click elements" [checked]、spinbutton "Max pages": "20"、combobox "Scope": Default。
• page.html — その時点の DOM です。
• status.json — URL、タイトル、状態、訪問回数です。
• page.png — ビジョンモデルが実行された場合にのみ生成されます。
• do はステップごとに一式を追加します：N-<action>.aria.yaml、N-<action>.html、N-<action>.diff.yaml。N-<action>.diff.yaml には、そのステップで変更された内容が toggled ／ added ／ removed として記載されます。

prima コマンドの後に playwright-cli snapshot を実行しないでください。 ツリーはすでにディスクに保存されており、snapshot にはない値や状態も含まれています。また、grep のコストもかかりません。

grep -nE "Scope|Click elements|Advanced" <dir>/aria.yml

prima status <hash> はパスを出力しますが、ブラウザーを操作します — セッションがまだ開いている間に読み取るか、自分でディレクトリを開いてください。

pw に切り替える前に

pw の呼び出しで確認しようとしていることの多くは、上位のレイヤーですでに確認できます。

• コントロールの状態または値 — 最後のコマンドの aria.yml を grep します。すでに記録されている内容を DOM に問い合わせないでください。
• クリックによって変化した内容 — クリック前後の snapshot ではなく、do の N-*.diff.yaml を確認します。
• ロケーター — research がページで検証済みのロケーターを返します。
• スクリーンショットに写っていないもの — スクリーンショットはビューポートを表示するため、折りたたみより下にあるものは写りません。do で表示範囲までスクロールするか、ページ全体を網羅する aria.yml を読み取ってください。ビジョンモデルがコントロールを確認できなかったからといって、そのコントロールが存在しないことの証明にはなりません。

pw が必要なのは、どの表現でも到達できない操作だけです：localStorage への値の設定、計算済みスタイルの読み取り、強制的な再読み込みなどです。結果は ### Value の下に返されます。ロケーターが何も見つけられないと 3000ms のタイムアウトが発生し、コマンドは失敗します。そのため、page.evaluate で読み取り、ロケーターを通じて操作してください。

視覚に関する質問

レイアウト、位置、色、重なり、何かが切れているかどうか — アクセシビリティツリーにはこれらの情報がなく、アサーションに合格したという事実からもわかりません。

• check は、最終ページのスクリーンショットを基に結果を確定します。ユーザーに見える内容が証拠であり、実行ログに記載されるのは行った操作だけです。
• ask "<question>" — スクリーンショットを読み取り、文章で回答します。見た目について自由形式で質問したい場合に使います。
• verify はアサーションで主張を検証します。それぞれの結果は playwright 形式で PASSED または FAILED として返され、総合判定はありません — 各行を読んで判断してください。FAILED の行には、その下にエラーが記載されます。テキストや要素が見つからない場合は主張が誤りだと確定しますが、構文エラーやロケーターエラーの場合はアサーションが実行されていないため、主張は未確定のままです。主張を表現するアサーションがない場合は、失敗と判定する代わりに「none ran」と報告されます。