技能介绍

解决什么问题

直接手写 Grafana 仪表盘 JSON 会在 diff 中产生难以审查的噪音，字段拼写错误或嵌套结构问题只有部署后才会暴露；大批量仪表盘难以复用面板模式，模板变量和阈值逻辑散落在每个 JSON 里，缺乏类型约束也容易在重构时引入回归。

核心能力与使用方式

该 SDK 采用 builder pattern：创建 builder 对象，链式调用配置方法，最后通过 .build()（TS）或 .Build()（Go）输出标准 Grafana dashboard JSON。每种面板、查询、变量类型独立成包，按需导入。支持 TypeScript（主）和 Go（次）。典型用法包括从零创建仪表盘、将手工 JSON 转为类型化代码、封装团队通用面板模式为 helper 函数、根据服务列表或配置动态生成仪表盘。输出 JSON 可直接用于 Grafana API、文件 provisioning 或 Kubernetes ConfigMaps。

边界与注意点

SDK 处于 v0.0.x 预览阶段，API 在版本间可能变化，需显式锁定版本；推荐 Grafana >= 12，兼容 >= 10
Prometheus 查询中 instant() 与 range() 互斥，需同时使用时改用 .rangeAndInstant()
Loki 的 .range()/.instant()/.resolution() 已废弃，改用 .queryType() 与 .step()
首个 threshold step 必须设 value: null 作为默认色，遗漏会生成非法 JSON
面板 ID 与 gridPos.x/y 由 Grafana 自动分配，不要手动设置
Transformations 无类型 builder，需传入原始 { id, options } 对象
Go 侧 cog.ToPtr() 广泛用于指针字段，Build() 返回 error 必须检查
插件 datasource 无内置 builder，需自定义实现 Builder interface
当前主推 dashboard schema v1；v2beta1 仍在稳定中，除非需要 v2 布局否则优先 v1
只有 generator 文件被 tsconfig 包含时才有编译期类型检查；用项目本地 npx tsc 而非全局旧版编译器
每次修改 generator 后必须重新生成并提交 JSON，严禁手工编辑生成产物