sls-dashboard-builder

name	sls-dashboard-builder
description	当任务需要创建、修改、扩展或重组阿里云 SLS 的 dashboard JSON 或可导入的大盘配置时使用；尤其适用于线上大盘、强对比的分析看板、已校验的查询包，或需要专业中文标签与指标定义的运维向大盘。

SLS Dashboard Builder

创建或修改完整、可导入的阿里云 SLS dashboard JSON。

必备运维技能： 若任务涉及真实 Project 或大盘，且需要通过 aliyun sls ... 查看或复用线上大盘，必须基于最新线上 JSON 操作。

总览

本技能以任务为先，不以「先选图表模板」为先。
对线上大盘，还以当前线上状态为先。

若用户已提供以下任意一项或多项，不要从随意图表模板起手：

• 已有 dashboard JSON
• 大盘 URL 或大盘名称
• 指标需求或查询方案
• 已校验的查询结果文件
• 明确的「做这 2 张大盘」之类需求说明

上述情况下应先还原任务结构，再把每个已校验的视图映射到 SLS 图表，最后拼出 dashboard JSON。
若大盘已在线存在，应在最新线上 JSON 上打补丁，而不是推送更早的本地草稿。

何时使用

适用于：

• 新建 dashboard JSON
• 修改、扩展、重排已有 dashboard
• 将一份分析 / 监控需求包落实为 1 张或多张 dashboard
• 生成可直接通过 SLS API 导入的 dashboard 配置
• 参考现有 dashboard 的成熟写法做最小改造

不适用于：

• 单纯解释 SQL / PromQL
• 复杂前端可视化开发
• 非 SLS dashboard 配置

默认行为

• 默认输出形态：api-ready
• 新建大盘：现代格式（modern）
• 已有老格式大盘：保持 legacy，仅做最小补丁
• 用户提供了现有 JSON：保留未知字段与未改动的图表
• 未明确要求发布，或用户尚未确认预览效果前，只生成或修改本地 dashboard JSON，不 create/update 线上大盘
• create/update 线上大盘时，以用户确认后的 dashboard JSON 为准
• 发布到 SLS 时使用插件命令 aliyun sls update-dashboard / create-dashboard，显式传 --display-name、--charts、--description、--attribute remark=<具体修改原因> type=grid update=<ms> version=<version>；不要用 CamelCase OpenAPI 入口 UpdateDashboard --body-file 发布。
• 公开 SLS Dashboard API 的 UpdateDashboard / aliyun sls update-dashboard 是覆盖式更新当前大盘；attribute.version/update/remark 只影响当前版本展示元数据，不会自动追加控制台「历史版本」归档。
• 用户说「先给一版」：默认 single-dashboard-mvp
• 用户提供完整任务包或设计文档：默认 single-dashboard-full
• 用户明确要求多张大盘：使用 multi-dashboard-suite

模式

1. 更新已有大盘

1. 先拉取或读取当前 JSON
2. 复用现有结构，只改被要求的图表或布局
3. 不相关的图表与字段保持不动

2. 创建单张大盘

适用于用户需要一张盘，包含概览、关键趋势与表格等。

3. 创建大盘套件（多张）

适用于用户需要多个决策面，例如 留存与活跃 + 业务与成本。

多张盘之间保持命名、筛选器、标题风格与版式节奏一致。

任务包工作流

当输入包含需求文档、查询方案、结果文件或参考大盘时，按以下顺序：

1. 判定任务形态：更新、新建，还是套件
2. 建立视图清单：指标、展示意图、project 或 logstore、时间范围、阻塞项
3. 若有名称或 URL，优先拉取真实参考大盘
4. 将视图归组为大盘区块，例如 概览、趋势、TOP、Cohort、钻取
5. 按视图意图选图表配方，不按产品营销名称选
6. 仅当图表查询确实可被过滤或可被 token 替换时才加筛选器
7. 受阻指标写成简短 markdownpro 说明，或明确省略；绝不编造缺失的源数据
8. 每张大盘输出完整 JSON

针对此类分析套件任务，请阅读：

• references/task-driven-workflow.md
• references/view-recipes.md

视图意图 → 图表配方

• compare-card → statpro
  需要具备对比语义的 display.queryOptionMap，不能只用裸统计模板。
• line（时间 + 数值）→ linepro
• line（时间 + 分组 + 数值）→ 通常为 aggpro
  常见于业务或类目拆解趋势。
• top-table → tablepro
• cohort-table → tablepro
• section title → dashboardrow
• blocker、assumption 或 scope note → 短说明用 text，富文本或长说明用 markdownpro
• filter → droplistpro
  仅当原始过滤路径中存在该 key，或查询已用 token 参数化时

工作规则

• 使用真实 JSON type，不要用界面展示名
• 线上补丁工作：仅以最近一次 dashboard get 结果为安全更新基线
• 线上发布必须通过 aliyun sls update-dashboard 的结构化参数传递；attribute.update 和 attribute.version 按字符串传入，并在每次发布前更新为新值。注意这只更新当前版本元数据，不代表已创建控制台历史快照。
• attribute.remark 必须写明本次发布的具体修改原因，例如 对齐Token使用时段分布为HH:00并修复历史版本记录；不要使用 修改图表 这类泛化文案。
• 若用户要求 SLS 控制台「历史版本」可恢复记录，不能仅依赖公开 Dashboard API；必须先确认控制台保存流程或可用的历史版本接口，再发布。
• chart.title 必须唯一且对正则安全
• 用户可见标题放在 display.basicOptions.displayName，legacy 用 display.displayName
• TopN、队列（cohort）、明细表优先 tablepro
• 单序列或多指标趋势优先 linepro
• 一列度量 + 一列维度的分组时间趋势优先 aggpro
• 同比对比优先用 compare(...)、ts_compare(...)；但跨表 CTE（如维表 JOIN 事件表）时 compare() 不可用——它隐式扩展时间窗口不会同步到其他 logstore 的 CTE，导致对比值为 0。此时改用 time_base（max(__time__)）+ cur_agg/prev_agg 手动分窗口，且先按关联主键 GROUP BY 聚合再 JOIN 维表（减少 JOIN 行数避免超时）
• SQL 别名应便于运维阅读；不要让 active_users、gt_5_users、scene_count 等裸英文字段名直接成为图例
• 指标定义对理解很重要时，通过 display.documentLinkOption.documentLinks[] 补充
• 同一张大盘上各图指标定义保持一致，尤其活跃、留存、成本、覆盖率等
• tablepro + logstore 优先显式 SELECT ...；schema 或字段需要时用 scan
• 参考文档按需阅读，只读最少必要部分
• 搜索前缀 ((*)) vs *|：跨表 CTE（查询多个 logstore）时用 *| 或 (*)|；同一 logstore 内的查询用 *| 即可。((*)) 是旧写法，功能等价但可读性差
• 预聚合 CTE 的字段可加性：sum()/count() 可加；approx_distinct() 不可加——同一实体可能跨多个 GROUP BY 组，对预聚合结果求和会膨胀。需要去重计数时必须在原始事件上 approx_distinct

输出前校验清单

输出前检查：

• 顶层结构符合 api-ready 或 editor-ready
• dashboardName 与每个 chart.title 符合命名规则
• 除非用户要空壳，charts 非空
• 每个图表具备真实 type、search、display
• 静态组件如 dashboardrow、text 可不包含 search.chartQueries
• 每个图表具备 xPos、yPos、width、height
• 使用 queryOptionMap 时，字段与 SQL 结果列一致
• 目标受众为中文运维或业务时，图例、轴标签、表头使用规范中文
• 新改动基于最新线上大盘，而非更旧的本地副本
• droplistpro 非装饰，必须绑定真实 key 或 token 路径
• 分组趋势不强行塞进错误的图表家族
• 老格式大盘不静默整体迁到现代结构
• 使用预聚合 CTE 时，检查外层是否对 approx_distinct 结果做了 sum()——如果是，该指标需要改为在原始事件上直接去重，或从 CTE 中移除
• 过滤条件是否在 WHERE 中而非 ON 中——如果 JOIN 条件含 OR（如 ON a = b OR a = c），追加的 AND filter 只作用于 OR 右侧，不是全局过滤
• 若任务包含 create/update 线上大盘，确认用户已经看过本地预览或明确认可当前 JSON

上游输入

sls-dashboard-builder 不维护业务 schema、公共 CTE、业务脚本或报表产物。
当上游业务 skill 或用户提供自然语言需求、数据语义、查询方案、已有 JSON 或输出路径时，本 skill 只负责把这些输入落实为 SLS dashboard JSON、图表配置和校验建议。

Skill Commands

render-report

将 dashboard JSON 转成可本地打开的 HTML 预览。该命令是 sls-dashboard-builder 对业务 skill 暴露的通用能力；业务 skill 通过 sls-dashboard-builder.render-report 生成本地预览。

该命令只理解通用 SLS dashboard 结构，不内置业务 schema、CTE 或默认过滤值；按 dashboard JSON 中的查询配置渲染预览结果。

当前实现：

python3 .agents/skills/sls-dashboard-builder/scripts/render_report.py \
  --case-dir cases/<business-skill> <scenario>

常用参数：

• --dashboard <path>：指定 dashboard JSON。
• --output <path>：指定 HTML 输出路径。
• --case-dir <path> <scenario>：按 cases/<business-skill>/output/<scenario>-dashboard.json 约定读取并输出。
• --var key=value：替换 SQL 中的 ${{key}} token。
• --profile test：指定 aliyun CLI profile；本交付目录默认使用 test。
• --with-diff：和 git HEAD 中同一路径 dashboard JSON 做 SQL / 结果 diff。

参考文档索引

按需阅读：

• references/task-driven-workflow.md — 任务包流程、套件拆分、版式节奏
• references/view-recipes.md — 对比卡片、分组趋势、队列表、筛选与说明等配方
• references/schema.md — 顶层结构与输出模式
• references/chart-types.md — 真实 JSON type
• references/datasources.md — chartQueries 形态
• references/layout.md — 网格或自由布局规则
• references/chart-templates.md — 基础图表模板
• references/query-syntax.md — query 与 tokenQuery 规则

示例

按需使用：

• examples/dashboards/modern/ — 现代格式大盘级示例（含分析套件）
• examples/dashboards/legacy/ — 老格式大盘；仅用于 legacy 补丁场景
• examples/charts/ — 按真实 JSON type 拆分的单图示例

常见错误

• 任务里已有校验查询与真实大盘，却仍从空白模板起手
• 用过期的本地 JSON 更新线上大盘，覆盖用户线上较新的修改
• 对比卡片用裸 statpro 却无对比映射
• 本可用一条 compare(...) 或 ts_compare(...) 表达的关系，却拆到多张图里
• 分组时间趋势该用 aggpro 却硬塞进 linepro
• SQL 别名留英文，图例出现 active_users、gt_5_users 等裸名
• 同一张盘上同一指标在不同图中使用了不一致的口径
• 阈值或业务含义不直观时省略指标说明
• 增加未绑定任何查询路径的筛选器
• 任务只要求小补丁却重写整张大盘
• 在 chart.title 中使用大小写混杂或中文
• 对预聚合 CTE 的 approx_distinct 结果在外层 sum() 求和（详见工作规则-字段可加性）
• 跨表 CTE JOIN 时用 compare() 做同比（详见工作规则-compare 限制）
• 过滤条件放在 ON ... OR ... AND filter 中——AND 优先级高于 OR，实际只过滤了 OR 右侧匹配的行。过滤必须放在 WHERE 中，不能追加到含 OR 的 ON 子句后面
• LEFT JOIN + WHERE IS NOT NULL 未简化为 JOIN
• group_concat 不保序，应改为 array_join(array_sort(array_agg(DISTINCT ...)), ', ')
• 需求说明改了但 dashboard JSON 未同步更新