build-dashboard

构建 Coval 仪表板

为 $ARGUMENTS 构建一个数据驱动型仪表板。此技能会分析用户现有的运行记录和指标，创建包含真实数据的仪表板，绝不创建空壳。

阶段 0：预检 + 使用情况分析

步骤 1：检查身份验证

coval whoami

如果尚未通过身份验证，请引导用户：

coval login

此操作会提示用户输入 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，并将新指标关联到 Agent。等待运行完成。之后才能继续重建。
• **没有“跳过并照常构建”的选项。**空图表毫无用处；这与无数据检查的原则一致。
• 然后进入阶段 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）
   • 启动前向用户确认 Agent 和测试集（除非只有 1 个 Agent，此时自动选择）

   停止此技能。 使用上述参数调用 /quick-eval。等待评估完成并生成指标数据，然后再继续执行 /build-dashboard。

   • 如果完全没有运行记录：还要在调用 /quick-eval 前询问用户想要模拟仪表板还是监控仪表板。
   • 如果用户明确表示不想运行评估：不要创建仪表板。 告诉他们有数据后再回来。空仪表板毫无用处——绝不要创建。

   不存在“仍然继续”的选项。 没有数据 = 没有仪表板。这是不可妥协的要求。

   人工审核：仅在用户明确提及时才考虑。不要主动建议。

第 4 步：分析数据密度

这决定使用时间序列图表还是统计数据。

检查过去 7 天内的运行数量及其时间戳。默认时间分桶为4 小时，因此同一个 4 小时时段内的数据点会合并统计：

• 如果任意两次运行相隔不超过 4 小时（或者过去 7 天内总运行次数达到 5 次以上）：使用时间序列图表（折线图、柱状图）——数据足以呈现有意义的趋势
• 如果同一个 4 小时时段内少于 2 次运行（运行稀少、彼此孤立）：使用统计数据——数据不足以呈现有意义的时间序列，只显示数值即可

这是最重要的布局决策。只有 1 个数据点的时间序列图表看起来像是坏掉了。用统计数据展示 50 个数据点则会浪费数据。

Step 5：按频率确定主要指标

**仅考虑最近 7 天内的运行。**如果没有近期运行，且刚刚运行了 /quick-eval，则使用该次运行的数据。

获取最近完成的运行（最多 10 次）的模拟指标：

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

构建频率映射：统计各 metric_id 在所有模拟中同时满足 status: "COMPLETED" 且 value 非空的出现次数。按频率降序排序。

**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：选择 Agent 的关注对象

如果只有 1 个 Agent，则自动选择并告知用户。

如果有多个 Agent，询问：“此仪表板应关注哪个 Agent？”

• 以编号列表形式展示 Agent，并突出显示语音 Agent（其指标更丰富）
• 允许选择“所有 Agent”，以查看跨 Agent 数据

步骤 2：确定布局

除非用户明确要求更多，否则优秀的仪表板最多包含 8–10 个组件。

布局原则：

• 文本组件按用途划分区块。固定为 2 行高。宽度：全宽（48）、半宽（24）或三分之一宽（16）。不支持渲染 Markdown——仅限纯文本。
• 表格组件应占满宽度（48 列）。
• 图表组件可采用半宽（24）、三分之一宽（16），或在指标较多时采用四分之一宽（12）。
• 统计组件应采用三分之一宽（16）或半宽（24）。仅在数据稀疏时使用（见步骤 4）。
• 行宽：2 个组件 = 24+24。3 个组件 = 16+16+16。4 个组件 = 12+12+12+12。总和均为 48。

步骤 3：构建小组件列表

这里需要自行判断，而不是套用模板。 布局应根据用户的数据、指标和用途量身定制。不要每次都生成相同的仪表板。

硬性规则（不可妥协）：

• 文本小组件的分区标题可选，应谨慎使用。只有在主题确实发生变化时才添加标题（例如，从性能指标切换到合规性指标）。大多数仪表板最多需要 0–2 个文本标题。如果仪表板较小（8–10 个小组件），或所有指标都彼此相关，则可能完全不需要文本标题。堆满文本分隔符还不如不加。
• 延迟必须始终在某处显示。
• 所有行的列数总和必须为 48。
• 改进仪表板 = 从头重建，而不是追加到末尾。

可视化方式选择——优先使用时间序列：

对于大多数指标，默认使用时间序列图表（折线图或柱状图），而不是统计数字或饼图。仪表板最有用之处在于展示事物随时间的变化。

指标类型	默认可视化方式	使用时机
浮点数（延迟、时长、计数、评分）	line 图表	所有浮点数指标的默认方式。 展示随时间变化的趋势。
浮点数（仅限延迟，且方差很重要时）	histogram	仅当用户明确关注分布的一致性时使用。
二元是/否（问题解决、语气、验证）	bar，设置 aggregation: "count"、stacked: true、showAsPercentage: true	100% 堆叠柱状图。 展示随时间变化的是/否比例。不要使用饼图。
类别字符串（结束原因、通话结果）——稀疏数据	pie，设置 aggregation: "count"	类别指标的默认方式。 展示各类别所占比例。
类别字符串——密集数据（同一 4 小时区间内有 2 次或更多运行）	bar，设置 aggregation: "count"	展示各类别随时间的变化。数据量足够时，从饼图切换为柱状图。
任意指标，稀疏数据（同一 4 小时区间内少于 2 次运行）	statistic	时间序列数据不足时的备用方式。

饼图仅用于类别指标（例如 “Resolved/Escalated/Abandoned” 等包含 3 个或更多字符串类别的指标）。二元是/否指标绝不能使用饼图——应使用 100% 堆叠柱状图。

当某个分区中有 4 个或更多指标时，使用四等分布局（12 列）。 不要强行把所有内容塞进二等分或三等分布局——如果有 4 个相似的浮点数指标，就将它们排成一行，每个使用 12 列的折线图。

饼图布局： 饼图的图例需要更高的空间。左侧使用 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 列，纵向高度为 16。较宽的图表（18 列）为时间序列数据留出更多空间，同时饼图保持紧凑。

根据现有指标组合各分区：

按主题对指标分组：

• 延迟 + 音频时长 + 首字节耗时 → “响应性能”
• 轮次计数 + 每条消息的字数 + Agent 重复表达 → “对话质量”
• 问题解决 + 来电者身份验证 + 专业语气 → “合规性与质量”
• Agent 未能响应 + 结束原因 → “可靠性”

每个分区：

1. 文本标题（全宽）
2. 图表——浮点数使用折线图，二元指标使用堆叠柱状图。根据指标数量使用二等分、三等分或四等分布局。

最后添加一个汇总表（全宽），包含所有指标。

步骤 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
└─────────────────────────────────────────────────┘

询问：“这个布局看起来合适吗？（是 / 自定义）”

如果选择自定义：

• 允许切换可视化类型
• 允许添加或移除组件
• 允许调整区块或指标的顺序
• 允许更改区块分组

阶段 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>"}'

不要使用 Markdown，仅使用纯文本。

图表组件（折线图、柱状图、面积图、统计图、直方图）

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（三分之一）、12（四分之一）。

对于以 100% 堆叠柱状图显示的二元 YES/NO 指标：使用 visualizationType: "bar"、aggregation: "count"、metricOutputType: "string"、stacked: true、showAsPercentage: true。

对于以折线图显示的浮点指标：使用 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" ——可正确处理浮点和字符串指标。
• 始终使用 groupBy: "agent" ——按 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——这些指标没有通过/未通过阈值，因此在成功表格中会显示无意义的值。它们应放入折线图，而不是汇总表格。

网格位置跟踪

创建行时跟踪 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