inspector-workbench

Inspector Workbench

Inspector オーバーレイは視覚的なプロダクトです。コードがコンパイルできても、問題がない証明にはなりません。 エージェントはスタンドアロンのワークベンチを起動し、視覚的な変更を加えるたびにスクリーンショットを確認する必要があります。

このスキルは inspector-docs の代わりにはなりません。ペインを追加、改名、削除する場合は、inspector-docs も読み込んでください。

使用するタイミング

packages/web-inspector の UI、クローム、オーバーレイの動作を変更する作業を始めるときは、必ずこのスキルを読み込んでください。

ドキュメントのみの Callout 作業では読み込まないでください。ショーケースのセルでは読み込まないでください。ホストアプリに不具合がある場合（ホスト CSS に対する z-index、CopilotChat のレイアウトなど）は、そのホストを使用し、そのうえでスクリーンショットを撮影してください。

デフォルトのホスト

デフォルトのホストは、スタンドアロンの Threads state lab です。

• コマンド（リポジトリのルートから）：nx run @copilotkit/web-inspector:dev:standalone
• URL：http://127.0.0.1:5177/?scenario=pro-enabled-existing&reset=1
• このラボでは実際の cpk-web-inspector をマウントし、オーバーレイを開きます。

デフォルトのホストとして、ショーケースアプリ、サンプルアプリ、Storybook を起動しないでください。これらは動作が遅く、Inspector 固有の不具合を見えにくくします。

Nx ターゲットは Vite と CSS の監視プロセスを同時に実行します。Vite だけを実行しないでください。 pnpm --filter @copilotkit/web-inspector run dev は実行しないでください。この監視プロセスは利用側にコンテンツを配信するものであり、このラボ用ではありません。

手順

手順 1：ワークベンチを起動する

1. 変更によってペインを追加、改名、削除する場合は、inspector-docs も読み込んでください。
2. リポジトリのルートから nx run @copilotkit/web-inspector:dev:standalone を起動します。
3. http://127.0.0.1:5177 で配信されるまで待ちます。
4. このセッションで利用できるブラウザツール（Playwright MCP、Claude browser、または Codex computer use）を開きます。
5. http://127.0.0.1:5177/?scenario=pro-enabled-existing&reset=1 に移動します。
6. 不具合が空、ロック済み、エラー、または未読の状態に関するものなら、ラボのドロップダウンで該当するシナリオを選び、再読み込みします。
7. オーバーレイが Home または Threads 上で開くまで待ちます。ラボがランチャーをクリックします。
8. ベースラインのスクリーンショットを撮影します。編集する前に確認してください。

手順 2：編集して、スクリーンショットを撮り、確認する

1. Inspector のソースを packages/web-inspector/src 内で編集します。
2. Vite がラボを再読み込みするまで待ちます。
3. ページに変更が反映されない場合は、ラボの URL を再読み込みし、オーバーレイが表示されるまで待ちます。
4. 変更が必要なペインのスクリーンショットを撮影します。
5. ブラウザツールがファイルを書き出す場合は、.inspector-workbench/<task>/ の下に保存します。リポジトリのルートに PNG を保存しないでください。
6. スクリーンショットを確認します。変更が見えていなければ、作業は完了していません。
7. 視覚的な変更を加えるたびに、手順 1～6 を繰り返します。
8. レイアウトまたは折りたたみ時のレールが対象に含まれる場合は、狭いビューポートでもう 1 枚スクリーンショットを撮影します。
9. テーマまたはコントラストが対象に含まれる場合は、ライトテーマとダークテーマの両方でスクリーンショットを撮影します。

ユニットテストも同じ変更に含める必要があります。スクリーンショットはテストの代わりにはなりません。

手順 3：ワークベンチを停止する

1. Inspector の作業が完了したら、dev:standalone のプロセスツリーを停止します。
2. Vite や CSS の監視プロセスを実行したままにしないでください。
3. .inspector-workbench/ 内のファイルをコミットしないでください。
4. リポジトリのルートにある PNG ファイルをコミットしないでください。

判断フロー

• Inspector の UI、クローム、オーバーレイ、ランチャー、またはペインの見た目：
  • 開始時：手順 1
  • 編集中：手順 2
  • 作業後：手順 3
  • ペインを追加、改名、削除する場合：inspector-docs も読み込む
• ドキュメントの Callout のみ：停止します。代わりに inspector-docs を読み込んでください。
• ホストアプリ内でのみ発生する不具合：そのホストを使用し、そのうえで手順 2 に従ってスクリーンショットを撮影します。
• Inspector UI に関係しないランタイムまたはコアの変更：このスキルは適用されません。

要注意の兆候

兆候	意味	代わりに行うこと
ショーケース、サンプル、Storybook が最初のサーバーである	エージェントがワークベンチをスキップしました	そのサーバーを停止します。手順 1 を実行します
ビジュアル編集後にスクリーンショットがない	エージェントが CSS から推測しています	スクリーンショットを撮影して確認します
リポジトリのルートに PNG ファイルがある（inspector-open.png）	スクリーンショットの保存先が間違っています	.inspector-workbench/<task>/ の下に保存します
「CSS は正しいので、UI は完成です」	オーバーレイのバグはソースには現れません	ラボのスクリーンショットを撮影し、画像に写っている問題を修正します
Nx ターゲットを使わずに Vite を起動した	CSS の監視が機能していません	nx run @copilotkit/web-inspector:dev:standalone を使用します
ポート 5178 またはランダムなポート	ラボでは 5177 に固定されています	5177 を空けます。別のポートを選ばないでください
タスク終了後もワークベンチが動作している	このマシンではウォッチャーがメモリを消費し続けます	手順 3 を実行します
inspector-docs の確認なしでペインを追加した	Docs Callout にずれが生じます	同じ変更内で inspector-docs を読み込みます

エラー処理

• ポート 5177 が使用中です：そのポートで残っている Inspector ワークベンチを停止してから、手順 1 を再試行します。別のポートを選ばないでください。ラボでは strictPort を使用します。
• このセッションにブラウザツールがありません：このセッションからは Inspector を確認できないことをユーザーに伝えます。CSS や単体テストだけからビジュアルの結果を推測しないでください。
• ラボが空白、またはオーバーレイが閉じています：起動を待ちます。その後、ラボのコンソールにある Runtime の行をスクリーンショットに撮ります。Runtime が接続されていない場合は、UI の編集前にラボを修正します。
• スクリーンショットに意図した変更が表示されません：完了したと報告しないでください。再読み込みして、もう一度スクリーンショットを撮影し、ソースを修正します。
• HMR がソースの編集を反映しませんでした：同じシナリオクエリを使って http://127.0.0.1:5177 を再読み込みします。その後、スクリーンショットを撮影します。
• 閉じたランチャーまたは未読のハローが必要です：http://127.0.0.1:5177/?scenario=pro-enabled-existing&replay-notification=1 を開きます。
• 予期しないエラーが発生した場合：処理を中断し、エラーの生データを提示します。ラボを回避するためにショーケースアプリへ切り替えないでください。