wai-play

WAI Play — Web ゲーム向けエージェント自動プレイテスト

WAI Play は実際のブラウザーを操作して、実行中の Web ゲームをテストします。ゲームの目標と重要なノードをモデル化してプレイし、5 つの観点による品質スコアと、再現可能な問題カード（状態差分、スクリーンショット、20 秒以内の動画クリップ）、修正の提案を返します。テストの信頼性はゲームの品質とは別に報告されるため、テスト用ハーネスが不十分でもゲームのスコアが不当に上がったり下がったりすることはありません。

作業が「テストを実行する」ことから始まることはほとんどありません。まず確認するのは、そもそもこのゲームをテストできるかです。その答えによって、その後のすべてが決まります。

このスキルを使う場面

• バイブコーディングで作成した Web ゲームを、デモ、ゲームジャムの締め切り、リリースの前に自動でプレイしてテストしたい。ユーザーは感覚ではなく、根拠を求めている
• ゲームの状態をエージェントが読み取れず、GameFlowAgentAPI ブリッジを作成または修復する必要がある
• テストの実行が完了し、ユーザーがスコア、問題カード、または信頼性の診断結果を読み解く手助けを必要としている
• 必須の重要ノード（最初のアップグレード、ボスフェーズ、レベルの目標、エンディング）に到達できず、前提条件の修復、ジャンプ、自然な進行のどれを選ぶか判断する必要がある
• ローカル、Docker、鍵なし（機能制限あり）のどの運用方法にするか、ユーザーが検討している

このスキルを使わない場面

• Unity / Unreal のフレーム時間やプロファイラーの作業 → game-performance-profiler
• エンジンのビルド、クック、パッケージ化の失敗 → game-build-log-triage
• 人間によるプレイテストのメモ、Steam Playtest の回答、配信者の反応 → game-demo-feedback-triage
• ゲームモデルを使わない、一般的なブラウザー自動化やスクリプトによる E2E テストスイート → browser-harness または playwriter
• テストではなくゲーム自体の開発 → web-game-development

手順

ステップ 1：ツールに触れる前に受付情報をそろえる

5 つの情報を集めます。どれかひとつでも不足すると、推奨内容が変わります。

1. ゲームの種類 — survivor_like、arcade_shooter、platformer、 puzzle_card、visual_novel のいずれか。WAI Play が対応するのはこの 5 種類のみです。それ以外のゲームには最も近いプロファイルを適用し、注意点を明記します。
2. アクセス可能な URL — リポジトリではなく、実行中のゲームです。localhost でもかまいません。
3. 連携の状態 — ページに window.GameFlowAgentAPI が公開されていますか？ URL だけを使ったブラックボックステストは可能ですが、これがないとフローのモデリングや重要ノードへのルーティングの精度が大きく低下します。
4. ソースの有無 — デプロイ済みバージョンと一致する任意の ZIP ファイルです。 一時的なコピーとしてのみ解析し、WAI Play がプロジェクトを編集することはありません。
5. キーの有無 — DeepSeek と Kimi のキー、または正直な鍵なしの運用方法です。

ステップ 2：モードを必ずひとつ選ぶ

モード	使用する場面	生成されるもの
testability	ゲームを操作できるかどうか不明	操作を妨げる能力をそれぞれ明記した、実行可否の準備状況メモ
integration	API がない、またはブリッジがスタブ	実際のゲーム状態に接続された GameFlowIntegration ブリッジ
run	ゲームをテストでき、設定も済んでいる	種類、URL、任意の ZIP、ステップ数の予算を指定した実行
report	実行が完了した	ゲームの品質とテストの信頼性を分けて示すスコアの解説
scenario-gap	必須の重要ノードに到達できない	理由付きの修復プラン／ジャンプ／自然な進行の判断
ops	デプロイ、プライバシー、鍵なし運用について確認したい	ローカル、Docker、機能制限ありの運用方法の選択

モードを混ぜないでください。このスキルでは、run の前に testability を実行することが、最も価値の高い順序です。状態を読み取れないゲームに対して実行すると、確信に満ちた誤った結果が出ます。

ステップ 3：読み取り専用の doctor で準備状況を確認する

bash .agent-skills/wai-play/scripts/wai-play.sh doctor
bash .agent-skills/wai-play/scripts/wai-play.sh doctor /path/to/wai-play

doctor は Python のバージョン、4 つのランタイムパッケージ、Playwright の Chromium ビルドが存在するかどうか、.env に設定されているキーを報告します。キーは名前のみを表示し、値は決して表示しません。何もインストールせず、テストも開始しません。

ステップ 4：ゲームを責める前にブリッジを作成または修復する

上流の v2 テンプレートは、状態を捏造しません。未実装の observe() または step() は、もっともらしいデータを返すのではなく、 例外をスローします。これは意図的な仕様です。架空の状態を返すブリッジが 生成するスコアは、ゲームではなくブリッジを評価したものになります。

候補となる統合ファイルをリリースする前に、静的チェックを実行します。

python3 .agent-skills/wai-play/scripts/check_integration.py \
  --game-type survivor_like path/to/game-integration.js

このチェッカーは標準ライブラリのみを使用し、不足しているメソッド、残っている テンプレートのプレースホルダー、未実装の例外スロー用スタブ、見つけられなかった 必須の状態フィールドを一覧にした、```review のフェンス付き JSON ブロックを 出力します。ブロッカーがある場合は終了コード 1 で終了します。これは静的なテキストチェックです。合格しても、ファイルが契約に沿った形に見えるというだけで、ブリッジが実際のゲームロジックに接続されていることを示すものではありません。接続の確認は別途行ってください。

契約の詳細は references/integration-api.mdに記載されています。

ステップ 5：契約が新しい場合は、まずデモゲームで実行する

このリポジトリには、各タイプにつき 1 つ、計 5 つのリファレンスゲームが含まれています。これらを配信し、いずれかを指定して実行することで、実際のゲームをデバッグする前にハーネスが動作することを確認できます。

bash .agent-skills/wai-play/scripts/wai-play.sh demo /path/to/wai-play 8768

これはフォアグラウンドでローカルの静的サーバーを起動します。意図的にユーザーに見える操作であり、バックグラウンドで副作用として実行するものではありません。

ステップ 6：品質と信頼性を分けてレポートを読む

重み付けされた 5 つの評価軸で、ゲームを評価します。コアフロー（0.24）、ゲームプレイ（0.26）、UI／ビジュアル（0.20）、フィードバック（0.15）、技術的安定性（0.15）です。API 統合の完全性、証拠の完全性、エージェントの信頼性は、信頼性に関する診断情報として報告され、これらのスコアには含まれません。

間違えやすいルールが 2 つあります。

• feedback 評価軸では、プレイヤーが見たり聞いたりできること、またはレビュアーがクリップから確認できることのみを評価します。内部 API の値が変化しただけでは、優れたフィードバックの証拠にはなりません。
• 1 つの問題は、最善の試行の証拠に紐付けて 1 回だけ報告します。同じ不具合を発生ごとに再報告しないでください。

評価区分、基準ごとの重み、証拠に関するルールは references/scoring-and-reports.mdに記載されています。

ステップ 7：到達不能な重要ノードには、正直に対処する

必須シナリオに入れない場合、API はコード化された理由を返します。各コードには、それぞれ正しい対応があります。

コード	意味	正しい対応
SCENARIO_PRECONDITION_MISSING	判定に必要な状態を読み取れません	不足しているフィールドを observe() に追加してから、再確認します
SCENARIO_LOADER_NOT_IMPLEMENTED	シナリオ初期化処理がありません	実装するか、通常のルートを進みます
SCENARIO_UNSAFE_TO_JUMP	ジャンプすると状態の整合性が失われます	通常のルートを進み、部分的なジャンプを強制しないでください
SERVER_AUTHORITATIVE_STATE	状態はサーバーが管理しています	テストアカウント、セーブ、またはインジェクション用エンドポイントをリクエストします
REPAIRER_NOT_IMPLEMENTED	安全な修復手段がありません	通常のルートを進みます

フィールドを 1 つ設定するだけで重要ノードを満たそうとしてはいけません。上流でも明確に指摘されています。レベル、装備、マップ、スポーンプール、ボス AI を初期化せずに elapsed = 360 としてボスフェーズに進むと、シナリオは合格しても意味のないものになります。

ゲームタイプごとのシナリオ表は references/game-profiles-and-scenarios.mdに記載されています。

Step 8: 運用上の境界を守る

• 自分が所有するゲームやソース、またはテストの許可を得たものだけをテストしてください。
• アップロードされた ZIP は一時コピーとして分析し、実行後に削除してください。
• AI ソースモデリングを有効にすると、ソースの要約が設定済みのサードパーティモデルプロバイダー（DeepSeek、Kimi）に送信されます。未リリースのコードやクライアント所有のコードで有効にする前に、その旨を伝えてください。
• 現行バージョンはローカル利用を想定しています。公開のマルチユーザーホスティングには、アカウント、ジョブキュー、クォータ、リモート URL の制限、自動テストデータクリーンアップが必要ですが、上流ではまだ実装されていません。デプロイの準備ができているかのように示唆せず、この点を率直に伝えてください。

セットアップ、Docker、キーがない場合の機能低下、ルートへの移行については、 references/setup-and-route-outs.md を参照してください。

ベストプラクティス

1. テストの前にテスト可能性を確認します。 読み取れないゲームで実行すると、自信に満ちた誤ったレポートが生成されます。
2. ブリッジで状態を捏造しないでください。 作り出したデータを返すスタブでは、スタブが採点されます。未実装の場合は例外をスローするのが正しい動作です。
3. すべての要約で、ツールが行うように、ゲームの品質とテストの信頼性を分けて扱ってください。
4. 単一のフィールドではなく、シナリオ全体を初期化してください。 部分的なジャンプでは、意味のないまま重要ノードを通過してしまいます。
5. 安全でないジャンプより、自然なルートを優先してください。 速くても一貫性のない経路より、時間がかかっても正直な経路のほうが優れています。
6. 各問題を、最善の試行における証拠一式に結び付けてください — 状態差分に加え、スクリーンショットまたは ≤20 s のクリップを添え、1 回だけ報告してください。
7. 結果の品質が低下している場合は、その旨を伝えてください。 キーがなければ、ソースモデリングも AI ルート計画もできず、ルールレベルの提案のみになります。
8. ゲームが 5 種類のいずれにも当てはまらない場合は、5 種類の制限を最初に明示してください。

例

例 1: 「WAI Play は私のゲームをテストできますか？」

まず doctor を実行し、次にページが GameFlowAgentAPI をマウントしているか確認します。マウントしていない場合は、ブラックボックスのみのテストと integration モードの推奨が回答になります。実行は行いません。

例 2: ブリッジはあるのに、すべてのスコアが不自然なほど低い

python3 .agent-skills/wai-play/scripts/check_integration.py \
  --game-type platformer web/game-integration.js

残された throw new Error(...) スタブやテンプレートのプレースホルダーが、ゲームそのものよりもはるかによく低スコアの原因になります。

例 3: ボス戦フェーズが一度も発生しない

返されたコードを確認してください。SCENARIO_UNSAFE_TO_JUMP の場合は、ジャンプを無理に実行するのではなく、自然なルートを進み、ステップ予算を増やしてください。

例 4: ユーザーがこれを公開サービスとしてデプロイしたい

率直に答えてください。現在はローカル利用とデモ利用が可能です。公開ホスティングには、まだ存在しないアカウント、キュー、クォータ、URL 制限、データクリーンアップが必要です。

参考資料

• references/integration-api.md — GameFlowAgentAPI / GameFlowIntegration のメソッド契約、v1 と v2、タイプごとの状態形状
• references/game-profiles-and-scenarios.md — 5 種類のゲーム、アクション、必須の重要ノード、成功判定オペレーター
• references/scoring-and-reports.md — 寸法の重み、基準、評価帯、証拠と信頼性のルール
• references/setup-and-route-outs.md — インストール、.env、Docker、デモゲーム、機能低下モード、ルートへの移行
• scripts/wai-play.sh — 読み取り専用の doctor、check のパススルー、フォアグラウンドでの demo サーバー
• scripts/check_integration.py — 統合ファイルの標準ライブラリのみを使った静的契約チェック
• WAI Play GitHub Repository
• プロジェクト標準: .agent-skills/skill-standardization/SKILL.md