| name | loongsuite-pilot-insight |
| description | 基于 LoongSuite Pilot / AI Coding Agent 日志生成事件洞察、组织洞察、数据质量、研发效能和 AI Native 使用类 SLS 报表时使用；包含 AI Coding 事件表语义，以及团队报表可选的部门维表、dept_user 组织关系、指标口径和公共 CTE，通常与 sls-dashboard-builder 一起使用。 |
LoongSuite Pilot Insight
Purpose
将 LoongSuite Pilot / AI Coding Agent 日志转化为可复用的报表语义。用户应直接使用本 skill；本 skill 负责业务数据语义、指标口径和场景需求解释，再调用 sls-dashboard-builder 的通用能力生成或修改 SLS dashboard JSON。
Boundaries
- 业务语义放在本 skill：
schema.md、cases/loongsuite-pilot-insight/input/<scenario>-spec.md、业务脚本。
- 通用 SLS dashboard JSON 结构、图表配方、布局和校验规则来自
sls-dashboard-builder。
- 生成产物只写入
cases/loongsuite-pilot-insight/output/，不要写入 skill 目录。
*-report.html 是 dashboard JSON 生成后的固定本地预览产物，不作为独立 spec。- 不要把 LoongSuite Pilot 业务 schema、CTE、脚本或产物写进
sls-dashboard-builder。
Inputs And Outputs
- 默认需求入口：
cases/loongsuite-pilot-insight/input/<scenario>-spec.md
- 默认 dashboard 输出：
cases/loongsuite-pilot-insight/output/<scenario>-dashboard.json
- 默认预览输出：
cases/loongsuite-pilot-insight/output/<scenario>-report.html
- 数据语义入口：
schema.md
若用户只给自然语言需求，先选择或创建一个清晰的 <scenario>-spec.md，再按标准流程生成 dashboard 和预览。
Workflow
- 确定
<scenario>，读取或创建 cases/loongsuite-pilot-insight/input/<scenario>-spec.md。
- 读取
schema.md，确认 Data Source Bindings、字段语义、公共 CTE、指标可加性和风险点。
- 解析 spec，将自然语言需求转成视图清单：指标、SQL、图表类型、布局、筛选器和说明块。
- 使用
sls-dashboard-builder 生成或更新 cases/loongsuite-pilot-insight/output/<scenario>-dashboard.json。
- 调用
sls-dashboard-builder.render-report，以 cases/loongsuite-pilot-insight 为 case-dir，生成 cases/loongsuite-pilot-insight/output/<scenario>-report.html。
- 用户确认预览没问题后，再 create 或 update 线上 SLS 报表；不要跳过预览直接发布。
新增同类报表时只新增 cases/loongsuite-pilot-insight/input/<scenario>-spec.md，不要新增 skill。真实 project、region、logstore 统一维护在 schema.md。
Dashboard Spec
spec 用来描述某一次 dashboard 报表需求，结构与 cases/loongsuite-pilot-insight/input/*-spec.md 保持一致。详细业务口径写在 spec 正文或 schema.md，不要塞进 SKILL.md。
最小骨架：
---
output: dashboard
dashboard:
name: <stable-dashboard-name>
displayName: "<dashboard display name>"
defaultTimeRange: "-604800s"
layout: grid
data:
sources:
- ai_coding_events
---
# <dashboard display name>
用自然语言描述业务目标、数据范围和全局口径。
## Section: <module name>
### <chart/control/text title>
```yaml
intent: <stat-card|line|bar|pie|top-table|filter|text>
type: <sls-chart-type>
size: <w>x<h>
```
规则：
data.sources 引用 schema.md 中的 logical source，例如 ai_coding_events、dept_roster。dashboard.name 是生成 SLS dashboard JSON 的稳定名称，dashboard.displayName 是大盘展示名。dashboard.defaultTimeRange 使用 SLS 相对时间，例如 -604800s、-86400s、-2592000s。dashboard.layout 默认使用 grid。- 不在 spec 中重复维护真实 project、region、logstore；这些放在
schema.md 的 Data Source Bindings。
- 不为构建归档、HTML 预览等后续产物维护独立 spec。
- dashboard 模块统一使用
## Section:；筛选器、静态说明块和普通图表都放在 section 下。
- 图表元信息优先写
intent、type、size，按需补 format、unit、orientation、key、filterType、globalFilter。
Preview
生成本地预览时调用 sls-dashboard-builder.render-report，case-dir 使用 cases/loongsuite-pilot-insight；修改已有 dashboard 时带 --with-diff 生成 HTML SQL / 结果 diff；如报表 SQL 使用 token 参数，通过 --var key=value 传入本地预览值。若查询失败，应修复查询、凭据或网络问题后重新生成预览。
Guardrails
- 不编造不存在的字段或 logstore。
- 生成任何部门、团队或覆盖率类报表前，必须读取
schema.md。
dept_user 是部门类报表的关键语义；生成部门类报表前必须确认 schema.md 中的定义。- 当 spec 的
data.sources 只有 ai_coding_events 时，不要生成总在册人数、覆盖率、未产生日志员工列表、部门或团队 TopN；这些都需要 dept_roster 或客户自定义外表。
- 部门维表只依赖
department 的 work_no、name、dept_name 三个索引字段。
- Skill 统计使用
schema.md 中从 gen_ai.tool.call.arguments 的 file_path 动态解析出的 skill_name，不要使用 gen_ai.skill.name。
- 跨表 JOIN 使用
dept_user 时，不要直接使用 compare() 做同比；按 sls-dashboard-builder 中的手动时间窗口规则处理。
active_user 中的 token、events 可加；去重类指标不要对预聚合结果求和。- 图表标题、图例、表头默认使用中文。
