build-dashboard

Coval ダッシュボードの構築

$ARGUMENTS 用のデータ主導型ダッシュボードを構築します。このスキルは、ユーザーの既存の実行結果とメトリクスを分析し、実際のデータを表示するダッシュボードを作成します。空の枠だけのダッシュボードは作成しません。

フェーズ 0：事前確認と利用状況の分析

ステップ 1：認証の確認

coval whoami

認証されていない場合は、ユーザーに次の手順を案内します。

coval login

ここで API キーの入力が求められます。API キーは https://app.coval.dev/settings（Organization > Manage > API Keys）で取得してください。

Coval アカウントを持っていない場合は、https://coval.dev から登録するよう案内してください。

ステップ 2：リソースの一覧表示

次の処理を並行して実行します。

coval dashboards list --format json
coval metrics list --include-builtin --format json
coval agents list --format json
coval runs list --format json --page-size 50

必ず最初に確認してください：「新しいダッシュボードを作成しますか？それとも既存のダッシュボードを改善しますか？」

既存のダッシュボードを改善する場合：

• 既存のダッシュボードを、名前とウィジェット数を含む番号付きリストで表示します
• どのダッシュボードを改善するか尋ねます
• そのダッシュボードのウィジェットを取得します：coval dashboards widgets list <dashboard_id> --format json
• 現在の内容を分析します。どのメトリクスが可視化されているか、どの可視化タイプが使われているか、不足しているものは何かを確認します
• 改善とは、ダッシュボードを再構築することです。既存のウィジェットをすべて削除し、完全なメトリクス一式と適切な可視化タイプで最初から作り直します。下部にウィジェットを追加するだけにしないでください。ダッシュボードは、追加を重ねたようではなく、統一感のある見た目にしてください。
• 既存のウィジェットを削除するには、次を実行します：coval dashboards widgets delete <dashboard_id> <widget_id>
• データがまだないメトリクス（過去 7 日間に実行されていない新規作成のメトリクス）があるか確認します。確認するには、メトリクスの頻度分析を見ます。出現回数が 0 のメトリクスにはデータがありません。
• データのないメトリクスがある場合は、停止して先に評価を実行してください。 空のウィジェットを含むダッシュボードは作成しないでください。ユーザーに次のように伝えます。

  「 にはまだデータがありません。ダッシュボードに表示するデータを用意するため、まずこのメトリクスで評価を実行する必要があります。」

• その後、新しいメトリクスをエージェントに追加して /quick-eval を呼び出します。完了するまで待ちます。その後でのみ、再構築に進みます。
• 「スキップして、とにかく作成する」方法はありません。 空のグラフは役に立ちません。データがない場合に停止するのと同じ原則です。
• その後、フェーズ 1 に進み、すべてのメトリクス（既存と新規）を含めて新しいレイアウトを最初から計画します

新規作成を選択した場合、または既存のダッシュボードがない場合：

• 通常どおり、フェーズ 0 のステップ 3 に進みます

ステップ 3：使用パターンを分析する

ここが重要な判断ステップです。 データソースを自動的に特定します。

1. 種類ごとに実行数を数える：各実行に test_set_id があるか確認します。

   • test_set_id がある実行 → シミュレーション実行（評価テスト実行）
   • test_set_id がない実行 → モニタリング実行（ライブ会話の送信）
   • 注意：is_monitoring フィールドがある実行もありますが、主な判断基準は test_set_id の有無です。

2. 判断ロジック（曖昧な場合を除き、ユーザーに尋ねないでください）。

   • シミュレーション実行が多い → データソースは Simulations
   • モニタリング実行が多い → データソースは Monitoring
   • ほぼ同数 → どちらを希望するかユーザーに尋ねます。
   • 人によるレビュー：ユーザーが明示的に言及した場合に限ります。提案しないでください。

3. 最近のデータがない場合 — 停止して、続行する前に確認します。

   ダッシュボードウィジェットに表示されるのは、過去 7 日間（ローリングウィンドウ）のデータのみです。7 日より古いデータは、履歴上の実行数にかかわらず、どのウィジェットにも表示されません。

   create_time で実行をフィルタリングし、過去 7 日間の実行のみを対象にします。次に、それらの実行を確認し、実際のメトリクスデータがある成功したシミュレーションが存在するか確認します。ステータスが COMPLETED でも、すべてのシミュレーションが失敗している実行は、ダッシュボードには役立ちません。

   確認するには、最近の各実行についてシミュレーションを取得し、少なくとも一部に status: "COMPLETED" かつ null ではないメトリクス値があることを確認します。すべてのシミュレーションが失敗した実行には、データがありません。

   過去 7 日間に成功したシミュレーションを含む実行がない場合は、ダッシュボードをまだ作成しないでください。 代わりに、ユーザーに次のように伝えます。

   「最近の評価データ（過去 7 日間）がありません。ダッシュボードに実際のデータを表示するため、まず評価を実行する必要があります。」

   その後、ダッシュボードを有用なものにするための最低要件に従って /quick-eval を実行します。

   • シミュレーションを 5 件以上（--iterations を使用するか、テストケースが 5 件以上あるテストセットを選択）
   • メトリクスを 5 つ以上。その中にレイテンシを含めます（常に必須です。組み込みメトリクスの一覧から ID を確認してください）。
   • 実行を開始する前に、エージェントとテストセットをユーザーに確認します（エージェントが 1 つだけの場合は自動選択）。

   このスキルを停止します。 /quick-eval を上記のパラメーターで実行します。評価が完了し、メトリクスデータが生成されるまで待ちます。その後でのみ、/build-dashboard を再開します。

   • 実行がまったくない場合：/quick-eval を実行する前に、シミュレーションダッシュボードとモニタリングダッシュボードのどちらを希望するかも尋ねます。
   • ユーザーが評価を実行したくないと明示した場合は、ダッシュボードを作成しないでください。 データが用意できたら再度依頼するよう伝えます。空のダッシュボードは無駄です。絶対に作成しないでください。

   「それでも続行する」という選択肢はありません。 データがなければ、ダッシュボードもありません。これは譲れない条件です。

   人によるレビュー：ユーザーが明示的に言及した場合に限ります。提案しないでください。

ステップ 4：データ密度を分析する

ここで時系列グラフと統計のどちらを使うかを判断します。

過去 7 日間の実行数とタイムスタンプを確認します。デフォルトの時間バケットは 4 時間のため、同じ 4 時間の枠内にあるデータポイントはまとめて集計されます。

• 4 時間以内に 2 件以上の実行がある場合（または過去 7 日間の実行が 5 件以上ある場合）：時系列グラフ（折れ線、棒）を使用します。意味のある傾向を示すのに十分なデータがあります。
• 同じ 4 時間バケット内の実行が 2 件未満の場合（まばらで、個別に発生する実行）：統計を使用します。意味のある時系列を表示するにはデータが不十分なため、数値のみを表示します。

これはレイアウトを決めるうえで最も重要な判断です。データポイントが 1 つしかない時系列グラフは壊れているように見えます。データポイントが 50 個あるのに統計を使うと、データを活用できません。

ステップ 5：頻度に基づいて主要なメトリクスを特定する

過去 7 日間の実行のみを対象にします。 最近の実行がなく、/quick-eval を実行したばかりの場合は、その実行のデータを使用します。

直近の完了済み実行（最大 10 件）について、シミュレーションメトリクスを取得します。

coval simulations list --run-id <run_id> --format json --page-size 5
coval simulations metrics <simulation_id> --format json

頻度マップを作成します。各シミュレーションで、status: "COMPLETED" かつ value が null ではない metric_id が出現した回数を数えます。頻度の高い順に並べ替えます。

Latency は必須です。 頻度の順位にかかわらず、Latency（29BlkepvvX19ebbLDB0y6Q、または metric_name: "Latency" で検索）を必ずダッシュボードに含めてください。主要なメトリクスに含まれていない場合は追加します。

メトリクス ID をメトリクス一覧と照合し、表示名と出力タイプを確認します。

メトリクスのデータが一度も生成されていない場合（すべての status: "FAILED" または value: null の場合）は、優先度を下げ、下位に配置するか省略します。

レイアウトを作成する前に、頻度マップをユーザーに提示します。

Metric frequency (last 7 days):

  Metric                  | Appearances | Type    | Status
  ────────────────────────|─────────────|─────────|────────
  Latency                 | 10/10       | float   | ✓ data
  Turn Count              | 10/10       | float   | ✓ data
  Issue Resolution        | 8/10        | binary  | ✓ data
  Professional Tone       | 8/10        | binary  | ✓ data
  Background Noise        | 0/10        | float   | ✗ no data (omitting)

Data density: 5 runs in last 7 days → using time series charts

質問します：「データのあるメトリクスは以上です。すべて使用しますか、それとも調整しますか？」

注： メトリクスの取得時にエラーが返されるシミュレーション（音声シミュレーションなど）もあります。その場合はエラーを適切にスキップし、次のシミュレーションに進みます。

フェーズ 1：ダッシュボードの計画

ステップ 1：エージェントの対象を選択する

エージェントが 1 つだけの場合は、自動的に選択し、その旨をユーザーに伝えます。

エージェントが複数ある場合は、質問します：「このダッシュボードの対象にするエージェントはどれですか？」

• エージェントを番号付きリストで提示し、音声エージェント（より豊富なメトリクスがあります）を強調表示します
• 複数のエージェントを横断して表示する「すべてのエージェント」も選択できるようにします

ステップ 2：レイアウトを決める

ユーザーが特に多くのウィジェットを求めない限り、適切なダッシュボードのウィジェット数は最大 8～10 個です。

レイアウトの原則：

• テキストウィジェットは用途ごとにセクションを分けます。高さは固定で 2 行です。幅は全幅（48）、半幅（24）、または 3 分の 1（16）です。Markdown はレンダリングされず、プレーンテキストのみです。
• テーブルウィジェットは全幅（48 列）にします。
• チャートウィジェットは半幅（24）、3 分の 1（16）、またはメトリクスが多い場合は**4 分の 1（12）**にできます。
• 統計ウィジェットは 3 分の 1（16）または半幅（24）にします。データが少ない場合（ステップ 4 を参照）にのみ使用します。
• 行の幅： ウィジェット 2 個＝24+24。ウィジェット 3 個＝16+16+16。ウィジェット 4 個＝12+12+12+12。合計はいずれも 48 です。

ステップ 3：ウィジェットリストを作成する

ここでは、テンプレートに従うのではなく、判断力を発揮してください。 レイアウトは、ユーザーのデータ、メトリクス、目的に合わせた独自のものにしてください。毎回同じダッシュボードを作成してはいけません。

厳守事項（必須）：

• テキストウィジェットのセクション見出しは任意であり、必要な場合に限って使用してください。本当にテーマが切り替わる場合（例：パフォーマンスメトリクスからコンプライアンスメトリクスへの切り替え）のみ追加してください。ほとんどのダッシュボードでは、テキスト見出しは最大でも 0～2 個で十分です。ダッシュボードが小規模（ウィジェット 8～10 個）である場合や、すべてのメトリクスに関連性がある場合は、テキスト見出しがまったく不要なこともあります。区切りのテキストが並ぶより、区切りがないほうが適切です。
• レイテンシは必ずどこかに表示してください。
• すべての行の合計は 48 列にしてください。
• ダッシュボードを改善するには、末尾に追加するのではなく、一から作り直してください。

可視化の選択 — 時系列を優先してください：

ほとんどのメトリクスでは、デフォルトの可視化に時系列チャート（折れ線または棒）を使用してください。統計値や円グラフではありません。ダッシュボードは、時間とともにどのように変化するかを示すと、最も役立ちます。

メトリクスの種類	デフォルトの可視化	使用する場合
浮動小数点（レイテンシ、所要時間、件数、スコア）	line チャート	すべての浮動小数点メトリクスでのデフォルトです。 時間の経過に伴う傾向を示します。
浮動小数点（レイテンシのみ。ばらつきが重要な場合）	histogram	分布の一貫性をユーザーが明示的に重視している場合に限ります。
バイナリ YES/NO（解決、トーン、検証）	aggregation: "count"、stacked: true、showAsPercentage: true を指定した bar	100％積み上げ棒グラフです。 時間の経過に伴う YES/NO の比率を示します。円グラフは使いません。
カテゴリ文字列（終了理由、通話結果）— データが疎	aggregation: "count" を指定した pie	カテゴリデータのデフォルトです。 各カテゴリの割合を示します。
カテゴリ文字列 — データが密（同じ 4 時間バケット内に 2 件以上の実行）	aggregation: "count" を指定した bar	時間の経過に伴うカテゴリの変化を示します。データが十分にあれば、円グラフから切り替えてください。
すべてのメトリクス、データが疎（同じ 4 時間バケット内に実行が 2 件未満）	statistic	時系列にするにはデータが足りない場合の代替です。

円グラフはカテゴリメトリクス（「Resolved/Escalated/Abandoned」のような 3 つ以上の文字列カテゴリ）に限って使用してください。 バイナリの YES/NO メトリクスに円グラフを使ってはいけません。100％積み上げ棒グラフを使用してください。

セクション内にメトリクスが 4 個以上ある場合は、4 等分（12 列）を使用してください。 すべてを 2 等分や 3 等分に無理に配置しないでください。同種の浮動小数点メトリクスが 4 個ある場合は、12 列ずつの折れ線チャートを 4 個、1 行に並べてください。

円グラフのレイアウト： 円グラフでは凡例のために高さが必要です。左側に幅広のチャートを 2×2 で配置し、右側に幅が狭く高さのある円グラフを配置してください。

┌──────────────────┬──────────────────┬──────────────┐
│  Chart 18×8      │  Chart 18×8      │              │
├──────────────────┼──────────────────┤  Pie 12×16   │
│  Chart 18×8      │  Chart 18×8      │              │
└──────────────────┴──────────────────┴──────────────┘

グリッドの位置（y=N から開始）：

• 左上：grid-x=0、grid-y=N、grid-w=18、grid-h=8
• 右上：grid-x=18、grid-y=N、grid-w=18、grid-h=8
• 左下：grid-x=0、grid-y=N+8、grid-w=18、grid-h=8
• 右下：grid-x=18、grid-y=N+8、grid-w=18、grid-h=8
• 円グラフ：grid-x=36、grid-y=N、grid-w=12、grid-h=16

合計：幅は 18+18+12=48、縦は 16h です。幅広のチャート（18 列）では時系列データを表示するスペースを確保しつつ、円グラフはコンパクトに収めます。

使用するメトリクスに基づいてセクションを構成してください：

メトリクスをテーマごとにグループ化します。

• レイテンシ + 音声の長さ + 最初のバイトまでの時間 → 「応答パフォーマンス」
• ターン数 + 1 メッセージあたりの単語数 + エージェントの同じ発言の繰り返し → 「会話の品質」
• 問題解決 + 発信者の本人確認 + プロフェッショナルなトーン → 「コンプライアンスと品質」
• エージェントの応答失敗 + 終了理由 → 「信頼性」

各セクションでは：

1. テキスト見出し（全幅）
2. チャート — 浮動小数点メトリクスには折れ線チャート、バイナリメトリクスには積み上げ棒グラフを使用します。メトリクスの数に応じて、2 等分、3 等分、または 4 等分にしてください。

最後に、すべてのメトリクスを含むサマリーテーブル（全幅）を配置してください。

ステップ 4：提示して確認する

ASCII の罫線文字を使ったモックアップで、レイアウトを必ず表示してください。 実際に予定しているウィジェットを使って作成します。

Dashboard: "<name>" (data: <Simulations|Monitoring>)

┌─────────────────────────────────────────────────┐
│  Response Performance                    (text)  │  48col, 2h
├────────────────────────┬────────────────────────┤
│  Line Chart            │  Line Chart            │  24+24=48, 8h
│  (Latency)             │  (Audio Duration)      │
├─────────────────────────────────────────────────┤
│  Compliance & Quality                    (text)  │  48col, 2h
├────────────────────────┬────────────────────────┤
│  Stacked Bar           │  Stacked Bar           │  24+24=48, 8h
│  (Issue Resolution)    │  (Identity Verified?)  │
├─────────────────────────────────────────────────┤
│  Summary Table (all metrics)                     │  48col, 8h
└─────────────────────────────────────────────────┘

次のように尋ねます：「このレイアウトでよろしいですか？（yes / customize）」

カスタマイズする場合：

• 可視化の種類を入れ替えられるようにします
• ウィジェットを追加・削除できるようにします
• セクションや指標の順序を変更できるようにします
• セクションのグループ分けを変更できるようにします

フェーズ 2：ダッシュボードとウィジェットを作成する

ステップ 1：ダッシュボードを作成する（または既存のものをクリアする）

新しいダッシュボードの場合：

coval dashboards create --name "<dashboard_name>" --format json

既存のダッシュボードを改善する場合：まず既存のウィジェットをすべて削除してから、再作成します。

# Delete each existing widget
coval dashboards widgets delete <dashboard_id> <widget_id>

ステップ 2：行ごとにウィジェットを作成する

ウィジェットは上から下、左から右の順に作成します。位置の指定には明示的に --grid-x と --grid-y を使用します。

テキストウィジェット（セクションヘッダー）

coval dashboards widgets create <dashboard_id> \
  --name "<section_title>" \
  --type text \
  --grid-w 48 --grid-h 2 \
  --grid-x 0 --grid-y <row_y> \
  --config '{"text": "<section_title>"}'

マークダウンは使用せず、プレーンテキストのみを使用してください。

グラフウィジェット（折れ線、棒、面、統計、ヒストグラム）

coval dashboards widgets create <dashboard_id> \
  --name "<widget_name>" \
  --type chart \
  --grid-w <cols> --grid-h <rows> \
  --grid-x <x> --grid-y <y> \
  --config '{"metricId": "<metric_id>", "visualizationType": "<viz_type>", "monitoring": "<Simulations|Monitoring>", "aggregation": "<agg>", "metricOutputType": "<float|string>"}'

幅の選択肢：48（全幅）、24（半分）、16（3分の1）、12（4分の1）。

バイナリの YES/NO 指標を 100％積み上げ棒グラフにする場合：visualizationType: "bar" に aggregation: "count"、metricOutputType: "string"、stacked: true、showAsPercentage: true を指定します。

float 指標を折れ線グラフにする場合：visualizationType: "line" に aggregation: "avg"、metricOutputType: "float" を指定します。

テーブルウィジェット

coval dashboards widgets create <dashboard_id> \
  --name "<widget_name>" \
  --type table \
  --grid-w 48 --grid-h 8 \
  --grid-x 0 --grid-y <row_y> \
  --config '{"monitoring": "<Simulations|Monitoring>", "aggregation": "success", "groupBy": "agent", "filters": {"metricIds": ["<id1>", "<id2>"]}}'

テーブルウィジェットのルール：

• 常に全幅（48 列）にします
• 常に aggregation: "success" を使用します。float 指標と string 指標の両方を正しく処理できます。
• 常に groupBy: "agent" を使用します。行をエージェントごとに分けて比較できます。
• 指標 ID は filters.metricIds に指定します（トップレベルの metricIds には指定しません）。
• 成功条件がある指標のみを含めます。バイナリの YES/NO 指標（Issue Resolution、Professional Tone、Caller Identity Verification など）と、目標条件がある指標です。Audio Duration、Long Pause Detection、Turn Count、Words Per Message、Latency などの生の float 指標は除外します。合否のしきい値がないため、成功テーブルに表示しても意味のない値になります。これらはサマリーテーブルではなく、折れ線グラフに含めます。

グリッド位置の追跡

行を作成するたびに grid_y を追跡します。

• 行 0：テキストヘッダー（h=2）→ 次の y = 2
• 行 2：グラフ（h=8）→ 次の y = 10
• 行 10：テキストヘッダー（h=2）→ 次の y = 12
• 行 12：グラフ（h=8）→ 次の y = 20
• 行 20：テーブル（h=8）→ 次の y = 28

フェーズ 3：レイアウトを検証して修正する

ステップ 1：実際のウィジェット状態を取得する

coval dashboards widgets list <dashboard_id> --format json

ステップ 2：検証して根拠を提示する

証拠として、ウィジェット一覧の生の出力をユーザーに表示します。その後、次の点を検証します。

• ウィジェットのサイズが種類ごとの最小値を満たしている（グラフ ≥ 12w×8h、統計 ≥ 10w×12h、テーブル ≥ 4w×8h、テキスト ≥ 12w×2h）
• 各行のウィジェットの幅の合計が正確に 48 列である
• サーバーによる予期しないサイズ調整がない

検証結果を次のように提示します。

Layout verified:
  ✓ Row 0: text 48w = 48
  ✓ Row 2: line 24w + line 24w = 48
  ✓ Row 10: text 48w = 48
  ✓ Row 12: bar 24w + bar 24w = 48
  ✓ Row 20: table 48w = 48
  ✓ All sizes meet minimums

注： 作成時に --grid-x と --grid-y を設定すると、位置が保存され、レスポンスで返されます。

ステップ 3：問題を修正する

coval dashboards widgets update <dashboard_id> <widget_id> --grid-x <x> --grid-y <y> --grid-w <w> --grid-h <h>

フェーズ 4：まとめ

すべてのウィジェットを作成して検証したら、ダッシュボードの準備ができたことをユーザーに伝えます。

Your dashboard is ready!

  Name:       <dashboard_name>
  Widgets:    <count>
  Data:       <Simulations|Monitoring>

  Open it here: https://app.coval.dev/dashboards/<dashboard_id>

  Layout:
  | Widget              | Type      | Size   | Metric              |
  |---------------------|-----------|--------|---------------------|
  | Response Performance| text      | 48×2   | —                   |
  | Latency             | line      | 24×8   | Latency             |
  | ...                 | ...       | ...    | ...                 |

次のステップを必ず提案します。

• 評価をさらに実行してデータを充実させる：/quick-eval
• 後からウィジェットを追加する：coval dashboards widgets create
• 継続的にデータを取得できるよう、スケジュール実行を設定する：coval scheduled-runs create
• 指標をさらに設定する：/configure-metrics