showcase-demo-debugging

ショーケースのデモ作業

まずはこちら

コードやフィクスチャを変更する前に、現在のローカルガイドを読んでください。

• showcase/README.md
• showcase/RUNBOOK.md
• showcase/DEBUGGING.md
• デモを追加または変更する場合は showcase/INTEGRATION-CHECKLIST.md

ショーケースの操作には showcase/bin/showcase を使用してください。CLI に必要な操作がなく、その理由を説明する場合を除き、生の docker compose、生の docker build、またはハーネスコマンドを直接使用しないでください。

別のセッションがショーケースを使用している可能性がある場合は、分離された実行を優先してください。

showcase/bin/showcase test <slug> --d5 --verbose --cycle --isolate

基本ルール

• ショーケースのデモコードでは、CopilotKit v2 API を使用してください。
• showcase/integrations/langgraph-python を D5 の動作の基準として扱ってください。ユーザーが文書化された差異を明示的に承認していない限り、ほかのすべてのショーケースデモは、同じデモ動作、プロンプト、ピル、ツールのフロー、UI アサーション、D5 のカバレッジについて、langgraph-python と 1 対 1 で一致させる必要があります。
• 新規デモや移行したデモでは、実装前に依存関係のバージョンを showcase/integrations/langgraph-python と比較し、ユーザーが文書化された差異を明示的に承認していない限り、同じバージョンか、それより新しいバージョンを使用してください。
• Google ADK は、関連する場合に限り、追加のコンテキストとして使用してください。
• D5 のセルまたは移行作業では、まずすべてのピルが実際のエージェントで動作することを確認し、次にフィクスチャを実装してから、ローカルの D5 検証が成功するまで実行してください。
• 移行したデモの E2E テストは、ユーザーが差異を明示的に承認していない限り、langgraph-python の動作とアサーションに一致させてください。
• デモが完了するには、すべてのピルを実行し、aimock を利用した D5 リプレイでカバーする必要があります。
• 新機能の実装時は、機能の完了を宣言する前に、デモ内のすべての候補ピルをクリックして、動作することを確認してください。
• aimock リプレイでは、ピルを一度クリックした場合、連続して 5 回クリックした場合、別のピルの後にクリックした場合、ほかのピルを挟んで再度クリックした場合に、フィクスチャの動作が安定している必要があります。同じピルは、フィクスチャに基づく同じプロンプトに対して、事前にクリックしたピルの順序にかかわらず、同じ期待される出力を生成する必要があります。
• 修正やデモが完了したと言う前に、ローカルで検証してください。
• テストを通すためにデモの内容を弱めないでください。デモの動作こそがプロダクトです。

新しいショーケース項目

新しいショーケース項目の作成、新しいデモセルの追加、候補ピルの追加、新しいショーケース機能の実装には、このワークフローを使用してください。デバッグ時も同じルールが適用されます。

1. 上記に記載されている現在のショーケースガイドを読んでください。
2. 対応する langgraph-python のデモを見つけるか、まず新しい langgraph-python の動作を定義してください。
3. 依存関係を showcase/integrations/langgraph-python と比較してください。文書化された互換性の問題で別の対応が必要な場合を除き、共有するデモ、ランタイム、テストの依存関係には同じバージョンか、それより新しいバージョンを使用してください。
4. CopilotKit v2 API でデモの動作を実装し、すべての候補ピルが実際のエージェントで動作するようにしてください。
5. ローカルでの手順の中で実際の LLM と通信するものがある場合は、aimock の記録モードで実行し、フィクスチャを取得してください。
6. 記録を決定的なソース D5 フィクスチャに変換してください。
7. aimock リプレイの下で、すべてのピルを一度、繰り返し、順番を入れ替えて確認してください。
8. すべてのピルについて、D5 E2E カバレッジを追加または更新してください。
9. 新しいショーケース項目の完了とする前に、ローカル検証を実行してください。

UI が一度動作しただけで、新しいショーケース作業を完了と見なさないでください。新しいデモにも、バグ修正と同じフィクスチャの一貫性、リプレイの安定性、リグレッションカバレッジが必要です。

バグ調査のループ

1. 再現する前に、関連するデモ、D5 スクリプト、既存のフィクスチャを確認します。
2. フローが aimock を使用しているか、実際の LLM を使用しているかを特定します。
   • showcase/docker-compose.local.yml、プロバイダーのベース URL、showcase/harness/fixtures/d5/*.json を確認します。
   • 対応するフィクスチャが showcase/aimock/d5-all.json または showcase/harness/fixtures/d5/ 配下のソースフィクスチャにあるか確認します。
   • 実行後、showcase/bin/showcase logs aimock --grep "fixture|match|NO match|404" を使用します。
3. フローが aimock を使用する想定の場合、次のコマンドで再現します。

   showcase/bin/showcase up aimock <slug>
   showcase/bin/showcase test <slug> --d5 --verbose --cycle
   

4. フィクスチャに疑わしい点がある場合は、アプリのコードを編集する前に、aimock をローカルで実行し、フィクスチャのマッチングを確認します。
5. フローが aimock を経由せず、実際の LLM と直接通信する場合は、その手順のために必ず aimock をローカルで記録モードで実行します。記録を行わずに、実際の LLM を使ったローカルフローを実行してはいけません。記録したフィクスチャ出力を使って、後のリプレイを決定論的にし、aimock 対応の D5 カバレッジを確保します。
6. 根本原因を特定して修正を実装したら、回帰カバレッジを確定する前に、ユーザーに該当するフローを実際に操作してもらい、動作することを確認します。
7. ユーザーが確認した後、問題がひそかに再発しないよう、D5 フィクスチャと回帰 E2E カバレッジを追加または更新します。
8. ユーザーが操作中に報告する追加の問題ごとに、同じループを繰り返します。再現、根本原因の特定、ユーザーによる確認、フィクスチャ、回帰テストの順に進めます。

環境のセットアップ

実際の LLM プロバイダーが必要な場合は、シークレット値を表示せずに showcase/.env を確認します。必要なキーがない、または空の場合は、次の手順を実行します。

1. showcase/.env が存在することを確認し、必要に応じて showcase/.env.example からコピーします。
2. ユーザーが編集できるよう、次のコマンドで開きます。

   code --new-window "F:\projects\cpk\CopilotKit\showcase\.env"
   

3. 必要なキーを貼り付けるようユーザーに依頼します。通常は OPENAI_API_KEY です。対象のプロバイダーが必要とする場合に限り、ANTHROPIC_API_KEY または GOOGLE_API_KEY を使用します。
4. ファイルを保存したら知らせてもらうよう依頼します。チャットにシークレットを貼り付けるよう求めてはいけません。

環境変数や設定の変更がコンテナーに影響する場合は、次を使用します。

showcase/bin/showcase recreate <slug>

依存関係、Dockerfile、またはマウントされていないソースを変更した場合に限り、再ビルドを使用します。

対話形式での再現

ユーザーが手動で再現すると言った場合は、必要なローカルサービスを起動し、フローを操作してもらいます。その後、完了したら知らせてもらい、ログと記録されたフィクスチャを確認します。

手順に沿って再現するようユーザーから依頼された場合は、headed Playwright または Browser MCP でショーケースのデモを実行し、バグが再現されるまで操作します。正確な手順、プロンプトの文面、選択したピル、URL、確認された失敗を記録しておきます。

必要に応じて headed D5 を使用します。

showcase/bin/showcase test <slug> --d5 --headed --verbose --cycle

フィクスチャの記録

新しいデモ、または実際の LLM と通信するローカル手順では、aimock を記録モードで実行し、やり取りをフィクスチャで再現できるようにします。これは必須です。実際のプロバイダーへの通信から、後でリプレイできるフィクスチャを生成する必要があります。

docker compose -f showcase/docker-compose.local.yml -f showcase/docker-compose.record.yml --profile infra up -d aimock <slug>

この記録モード用の Compose オーバーライドは、ショーケース CLI に正式な記録コマンドが追加されるまで、通常の「showcase/bin/showcase を使用する」というルールの例外として認められています。

その後、デモのすべてのピルを手動または D5 ハーネスで操作します。記録された呼び出しは showcase/aimock/d5-recorded/ に保存されます。

記録後は、次の手順を実行します。

1. 記録した出力を変換するか移動して、showcase/harness/fixtures/d5/ 配下のソース D5 フィクスチャにします。
2. 現在のドキュメントやスクリプトで必要なリプレイ用フィクスチャのパスが showcase/aimock/d5-all.json に含まれていることを確認します。
3. フィクスチャの検証を実行します。
4. aimock のリプレイのみを使って、デモを再実行します。
5. すべてのピルについて、D5 E2E カバレッジを追加または更新します。

既存の D5 レコーダーヘルパーを使う場合は、まず showcase/scripts/record-d5-fixtures.mjs を読みます。複数ターンのフィクスチャに必要な、現在のレコーダーパッチについて説明しています。aimock が必要な応答形式を記録できない場合は、デモ内で動作を偽装してはいけません。aimock に必要な最小限の上流変更について、ユーザーと相談します。

ピルのリプレイ安定性

機能の追加、フィクスチャの変更、またはフィクスチャを使用するデモのデバッグを行う際は、aimock のリプレイでサジェストピルが安定して動作することを確認してください。

1. 新しいセッションで各サジェストピルを1回クリックし、期待どおりの UI とアシスタントの出力になることを確認します。
2. 各サジェストピルを繰り返しクリックします。LLM／ツールの動作を伴うピルについては、少なくとも5回連続でクリックしてください。
3. 複数の異なるピルを続けてクリックした後、以前クリックしたピルをもう一度クリックし、同じ期待どおりの出力になることを確認します。
4. aimock のログを確認し、フィクスチャの未検出、誤った一致、古い一致の繰り返し、または順序に依存した一致がないか調べます。
5. 出力がクリック順、先にクリックしたピル、または同じピルのクリック回数に依存する場合は、フィクスチャのマッチングを修正してください。

フィクスチャは一貫性があり、再現可能でなければなりません。安定した userMessage、toolCallId、hasToolResult、またはより具体的なフィクスチャキーによって、繰り返しや順不同のピルクリックでもリプレイを決定的にできる場合は、turnIndex や会話履歴に依存しないでください。

フィクスチャのルール

• ソースフィクスチャは showcase/harness/fixtures/d5/*.json にあります。
• バンドルされたランタイムフィクスチャは showcase/aimock/d5-all.json にあります。
• 安定したツール ID がある場合は、複数ターンの判別に toolCallId を使用してください。正確なツール ID を利用できない場合、または意図的にランタイムで変化する場合に限り、hasToolResult を使用してください。
• 安定したリクエストプロパティでターンを区別できず、その差異が文書化されている場合を除き、新しいフィクスチャに turnIndex を導入しないでください。
• 安定性と具体性のある userMessage、systemMessage、toolCallId、ツールのサーフェスとのマッチングを優先してください。他のピルのフィクスチャを誤って使う可能性のある、広範な包括ルールは避けてください。
• フィクスチャを編集した後、検証して aimock を再作成してください。

  showcase/bin/showcase fixtures validate
  showcase/bin/showcase recreate aimock
  showcase/bin/showcase test <slug> --d5 --verbose --cycle
  

• 新しいフィクスチャファイルを追加する場合、現在のドキュメントで必要とされているときは、compose のマウント設定と aimock の Dockerfile のコピー規則も更新してください。

リグレッションテスト

ユーザーが修正後のフローが動作することを確認した後、リグレッションテストを追加してください。

• 該当するプロンプト／ピル／ツールのフローに対する D5 フィクスチャを追加または更新します。
• 元のバグでは失敗し、修正後は成功する E2E リグレッションテストを追加します。
• デモ内のすべてのピルを対象にします。エッジケースを明らかにするためだけに存在するピルも含めてください。
• フィクスチャが関係する場合は、繰り返しクリックと順不同のクリックを含むテストを追加し、最初の1回のクリックでしかフィクスチャが成功しない状態を防いでください。
• 同等のデモについては、langgraph-python の D5 アサーションのスタイルと動作に1対1で合わせてください。
• 個別に報告されたデモの問題は、共通の根本原因を1つのテストで自然にカバーできる場合を除き、それぞれ独立した動作としてテスト対象に含めてください。
• 共有フィクスチャ、ハーネスのロジック、ランタイムの動作、または複数のデモに変更が及ぶ場合は、まず関連する範囲に絞った D5 テストを実行し、その後、より広範なショーケースの検証を行ってください。

Aimock のアップストリームの不足機能

LLM プロバイダーのレスポンスを正確にリプレイするために必要な機能が aimock にない場合は、次の手順に従ってください。

1. 記録したプロバイダーレスポンスまたはログで、不足機能を確認します。
2. 不一致を隠すデモ側の回避策は追加しないでください。
3. アップストリームへの PR を提出する最も簡単な方法について、ユーザーに尋ねます。
4. 承認された場合は、aimock に最小限の変更を加え、次のコマンドでビルドします。

   showcase/bin/showcase aimock-rebuild --from <aimock-source-path>
   

5. ビルドし直した aimock で、ショーケースの D5 フローを再実行します。

完了条件

最終ステータスを報告する前に、以下を満たしてください。

• 根本原因が具体的に記載されていること。
• 影響を受けるローカルショーケースデモが実行されており、ユーザーが修正済みフローを手動でテストできるよう、ローカル URL が概要に記載されていること。
• 手動検証を依頼した場合、修正済みの UI フローをユーザーが確認していること。
• フィクスチャが決定論的であり、検証済みであること。
• 実際の LLM を使ったローカル実行は aimock の記録モード経由で行われ、リプレイ可能なフィクスチャが生成されていること。
• 影響を受けるデモのすべてのピルが、aimock による D5 カバレッジを備えていること。
• aimock のフィクスチャリプレイが、提案ピルの単独クリック、連続クリック、交互クリックで安定していること。
• langgraph-python 以外のデモの動作が langgraph-python と 1:1 で一致しているか、ユーザーが明示的に承認した相違点が文書化されていること。
• 関連する D5／e2e 回帰テストが追加され、ローカルで合格していること。
• aimock の制限が、上流で修正済みであるか、上流の PR／計画へのリンクが記載されているか、またはブロッカーとして明示されていること。