/sls-dashboard-builder

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

SLS Dashboard Builder

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

业务口径由 [agentloop-audit-dashboard](../agentloop-audit-dashboard/SKILL.md) 决定，本技能持有图表渲染与发布脚本，依赖相邻 [Setup](../agentloop-collector-setup/SKILL.md) 的共享 CLI、认证与目标绑定。

在当前项目目录执行 `python3 "<agentloop-collector-setup目录>/scripts/run.py" report --dashboard <json>` 生成预览；共享入口调用本技能的 `scripts/render_report.py`。发布使用同一入口的 `publish --dashboard <json> --remark "<修改原因>"`：不带 `--confirm` 时只读取线上状态并显示将创建还是覆盖，用户确认预览后再加 `--confirm` 写入。

账户与查询目标切换按 Setup 的[账户与查询目标切换](../agentloop-collector-setup/references/auth.md)处理，沿用已选 Profile，不为报表临时另建 Profile 或换凭证。仅切换环境时不要求日志时间、不查数。下文的 `aliyun sls create-dashboard` / `update-dashboard` / `get-dashboard` 是独立 CLI 的参考写法；使用这些 Skill 时采用上述共享入口。

**必备运维技能：** 若任务涉及真实 Project 或大盘，且需要查看或复用线上大盘，必须基于最新线上 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 CLI 发布时，使用 `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. 创建大盘套件（多张）

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

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

涉及总览到明细、原始日志或业务页面的点击跳转时，读取 [交互事件与下钻报表](references/drill-down-events.md)，先确定报表的查看环境，再定义点击字段、目标资源、变量映射和时间继承。纯 SLS 控制台场景的日志库、仪表盘、快速查询使用对应原生事件；需要在 AgentLoop 中查看并跳转的报表，当前暂时仅支持自定义 HTTP URL 方式，使用 `event: link` 指向 AgentLoop 宿主页面；仪表盘间跳转按参考文档内置的 [AgentLoop URL 配方](references/drill-down-events.md#agentloop-dashboard-navigation) 配置站内路由、时间参数和双层编码的 token JSON。宿主原生跳转适配修复并验证后再切换。任意业务 HTTP(S) 地址同样使用自定义链接。

任务包工作流

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

1. 判定任务形态：更新、新建，还是套件 2. 建立视图清单：指标、展示意图、project 或 logstore、时间范围、阻塞项 3. 若有名称或 URL，优先拉取真实参考大盘 4. 将视图归组为大盘区块，例如 `概览`、`趋势`、`TOP`、`Cohort`、`钻取` 5. 按**视图意图**选图表配方，不按产品营销名称选 6. 涉及筛选器或查询参数时，先读 [筛选器与变量替换](references/filters-and-variables.md)，确定机制、作用范围、原值与标签、默认值及消费变量的查询 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 路径
• 交互类型符合实际查看环境：纯 SLS 使用原生事件，AgentLoop 暂用 HTTP URL
• 交互绑定字段与传参来源列分别校验；表格单元格与柱图数值系列按实际点击位置配置
• 目标查询必须消费交互传入的同名变量
• 保存后在实际 SLS 或嵌入宿主中验证点击、参数和结果；HTML 预览不能替代交互验收
• 分组趋势不强行塞进错误的图表家族
• 老格式大盘不静默整体迁到现代结构
• 使用预聚合 CTE 时，检查外层是否对 `approx_distinct` 结果做了 `sum()`——如果是，该指标需要改为在原始事件上直接去重，或从 CTE 中移除
• 过滤条件是否在 `WHERE` 中而非 `ON` 中——如果 JOIN 条件含 `OR`（如 `ON a = b OR a = c`），追加的 `AND filter` 只作用于 OR 右侧，不是全局过滤
• 若任务包含 create/update 线上大盘，确认用户已经看过本地预览或明确认可当前 JSON

上游输入

根据用户需求、数据语义、查询方案、已有 J