@cloudcare/guance-front-tools 1.0.12 → 1.0.13

package/schemas/charts/common/common-chart-types-schema.json

@@ -25,8 +25,10 @@
         "heatmap",
         "topology",
         "sankey",
+        "change",
         "log",
         "object",
+        "monitor",
         "alarm",
         "text",
         "video",
@@ -34,4 +36,4 @@
         "command",
         "iframe"
     ]
-}
+}

package/schemas/charts/dashboard-schema.json

@@ -48,9 +48,16 @@
                     }
                 },
                 "type": {
-                    "type": "string",
-                    "description": "固定字段",
-                    "const": "template"
+                    "description": "仪表板主体类型，现有数据中常缺省，存在时固定为 template",
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "const": "template"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ]
                 }
             }
         },
@@ -70,4 +77,4 @@
             }
         }
     }
-}
+}

package/schemas/charts/query/query-item-schema.json

@@ -31,12 +31,30 @@
                     "type": "string",
                     "description": "图表查询语句，可以是 dql语句，也可以是 promql 语句"
                 },
+                "content": {
+                    "type": "string",
+                    "description": "文本图内容，支持 HTML 或 Markdown 文本"
+                },
                 "code": {
                     "type": "string",
                     "description": "查询语句的唯一标识，由单个大写英文字母构成"
+                },
+                "type": {
+                    "type": "string",
+                    "description": "查询语句类型冗余字段，实际数据中可能是 promql/dql，也可能是 default/simple 这类查询模式",
+                    "enum": [
+                        "default",
+                        "simple",
+                        "dql",
+                        "promql"
+                    ]
+                },
+                "promqlCode": {
+                    "type": "integer",
+                    "description": "PromQL 查询顺序编号"
                 }
             }
         }
     },
     "additionalProperties": true
-}
+}

package/schemas/charts/settings/settings-time-schema.json

@@ -4,10 +4,6 @@
     "title": "ChartTimeSettings",
     "description": "图表时间相关配置完整结构。",
     "type": "object",
-    "required": [
-        "timeInterval",
-        "fixedTime"
-    ],
     "properties": {
         "timeInterval": {
             "type": "string",
@@ -44,4 +40,4 @@
             "$ref": "settings-fixed-time-schema.json"
         }
     }
-}
+}

package/schemas/charts/settings/settings-unit-items-schema.json

@@ -4,7 +4,9 @@
     "title": "ChartUnitItemsSettings",
     "description": "图表单位数据配置",
     "type": "array",
+    "minItems": 2,
     "maxItems": 2,
+    "additionalItems": false,
     "items": [
         {
             "enum": [
@@ -223,4 +225,4 @@
             ]
         }
     ]
-}
+}

package/schemas/charts/settings/settings-units-schema.json

@@ -28,8 +28,7 @@
                 "required": [
                     "name",
                     "key",
-                    "unit",
-                    ""
+                    "unit"
                 ],
                 "properties": {
                     "name": {
@@ -57,4 +56,4 @@
             }
         }
     }
-}
+}

package/scripts/validate-file.mjs

@@ -0,0 +1,57 @@
+import Ajv from 'ajv'
+import { readdirSync, readFileSync } from 'fs'
+
+const SCHEMAS_DIRECTORY = './schemas'
+
+const args = process.argv.slice(2)
+const schemaFlagIndex = args.indexOf('--schema')
+const schemaId = schemaFlagIndex >= 0 ? args[schemaFlagIndex + 1] : 'dashboard-schema.json'
+const jsonPaths =
+  schemaFlagIndex >= 0 ? args.filter((_, index) => index !== schemaFlagIndex && index !== schemaFlagIndex + 1) : args
+
+if (jsonPaths.length === 0) {
+  console.error('Usage: node scripts/validate-file.mjs <json-path...> [--schema <schema-id>]')
+  process.exit(1)
+}
+
+const ajv = new Ajv({ allErrors: true })
+
+forEachFile(SCHEMAS_DIRECTORY, (schemaPath) => {
+  if (!schemaPath.endsWith('.json')) return
+  ajv.addSchema(readJson(schemaPath))
+})
+
+let hasError = false
+
+for (const jsonPath of jsonPaths) {
+  const valid = ajv.validate(schemaId, readJson(jsonPath))
+
+  if (valid) {
+    console.log(`✅ ${jsonPath} is valid against ${schemaId}`)
+    continue
+  }
+
+  hasError = true
+  console.log(`❌ ${jsonPath} is not valid against ${schemaId}:`)
+  for (const error of ajv.errors || []) {
+    const instancePath = error.instancePath || '/'
+    console.log(`- ${instancePath} ${error.message}`)
+  }
+}
+
+process.exit(hasError ? 1 : 0)
+
+function forEachFile(directoryPath, callback) {
+  for (const entry of readdirSync(directoryPath, { withFileTypes: true })) {
+    const entryPath = `${directoryPath}/${entry.name}`
+    if (entry.isFile()) {
+      callback(entryPath)
+    } else {
+      forEachFile(entryPath, callback)
+    }
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(readFileSync(filePath, 'utf8'))
+}

package/skills/grafana-to-guance-dashboard/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: grafana-to-guance-dashboard
+description: Convert Grafana dashboard JSON into Guance dashboard JSON in this repository. Use when the user wants to convert a Grafana dashboard file, adjust mapping logic for panels or variables, preserve settings, groups, and vars as much as possible, validate generated Guance dashboard JSON against local schemas, or debug why a Grafana dashboard does not convert cleanly.
+---
+
+# Grafana To Guance Dashboard
+
+## Overview
+
+Use this skill when working on Grafana dashboard to Guance dashboard conversion in this repository.
+
+This skill ships its own standalone converter script under `skills/grafana-to-guance-dashboard/scripts/`. Use that script first. Only inspect the older repository converter when the user explicitly wants comparison or historical behavior.
+
+## Core Workflow
+
+1. Identify the input Grafana dashboard and output path.
+2. Run the standalone skill script.
+3. Validate the generated Guance dashboard against local schemas.
+4. If conversion gaps remain, patch the standalone skill script and re-run validation.
+5. Only inspect the older repository converter if the user asks to compare outputs.
+
+## Commands
+
+Use this command from the repository root.
+
+```bash
+# Convert a Grafana dashboard JSON to Guance JSON
+node skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs \
+  --input path/to/grafana-dashboard.json \
+  --output path/to/guance-dashboard.json \
+  --validate
+
+# Convert and normalize PromQL metric names toward Guance measurement:field style
+node skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs \
+  --input path/to/grafana-dashboard.json \
+  --output path/to/guance-dashboard.guance-promql.json \
+  --validate \
+  --guance-promql-compatible
+
+# Convert and keep original Grafana metadata under extend.grafana for debugging
+node skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs \
+  --input path/to/grafana-dashboard.json \
+  --output path/to/guance-dashboard.keep-meta.json \
+  --validate \
+  --keep-grafana-meta
+```
+
+## What The Standalone Skill Converter Supports
+
+- Grafana variables of type `query`, `custom`, `textbox`, `constant`, `interval`, and `datasource`
+- Grafana row panels mapped to Guance groups
+- Row collapse state mapped to `dashboardExtend.groupUnfoldStatus`
+- Panel links gathered from panel links, default links, and override links
+- Common panel types:
+  - `stat`, `singlestat` -> `singlestat`
+  - `timeseries`, `graph` -> `sequence`
+  - `barchart` -> `bar`
+  - `piechart` -> `pie`
+  - `histogram` -> `histogram`
+  - `bargauge` -> `toplist`
+  - `gauge` -> `gauge`
+  - `table` -> `table`
+  - `text` -> `text`
+  - `heatmap` -> `heatmap`
+  - `treemap` -> `treemap`
+- Query extraction from Grafana `targets[]` using `expr`, `query`, or `queryText`
+- Datasource-aware query classification for Prometheus-like and SQL-like targets
+- `guance-guance-datasource` targets default to `dql`, but explicit `qtype: "promql"` is preserved as `promql`
+- Optional `--guance-promql-compatible` mode to rewrite PromQL metric selectors from `metric_name` toward Guance `measurement:field` style
+- Default output omits raw `extend.grafana` metadata; pass `--keep-grafana-meta` only when debugging conversion fidelity
+- Variable replacement from Grafana `$var` / `${var}` to Guance `#{var}`
+- Settings extraction from both newer `fieldConfig` / `options` panels and older Grafana `graph` / `singlestat` fields
+- Settings mapping for thresholds, value mappings, legend, units, decimals, min, max, stack mode, null handling, panel links, and common chart display settings
+- Transformation-aware table mapping for `organize`, `filterFieldsByName`, and `filterByValue`
+- Extra appearance metadata preserved under `extend.grafana` and `settings.extend.appearance`, including line width, fill opacity, point mode, stat text/color mode, reduce calcs, and gauge display hints
+
+## Known Limits
+
+- The converter is still Prometheus/PromQL-oriented for query extraction.
+- Plugin-specific Grafana options are converted heuristically, not losslessly.
+- Unsupported panel types are filtered out unless the mapping table is extended.
+- Complex transformations and non-standard datasource payloads may still need manual cleanup.
+
+When conversion fails or output is incomplete, read [references/converter-notes.md](references/converter-notes.md).
+
+## Editing Rules
+
+- Prefer patching `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs` for conversion behavior.
+- Only change schemas when the generated Guance JSON is valid real data but the schema is too strict.
+- Keep validation green:
+  - `npm run validate`
+  - `npm run validate:dashboard`
+- When adding support for a new Grafana panel type, update the standalone script's panel type map first, then validate an example dashboard.
+
+## Typical Requests This Skill Should Handle
+
+- "Convert this Grafana dashboard JSON to Guance format."
+- "Why did this Grafana panel disappear after conversion?"
+- "Add support for Grafana panel type `xyz`."
+- "Map Grafana variables into Guance vars correctly."
+- "Validate the converted Guance dashboard against the local schema."
+- "Compare a Grafana dashboard and generated Guance dashboard to find missing panels."

package/skills/grafana-to-guance-dashboard/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Grafana to Guance"
+  short_description: "Convert Grafana dashboards to Guance format"
+  default_prompt: "Use $grafana-to-guance-dashboard to convert a Grafana dashboard JSON into a Guance dashboard and validate the result."

package/skills/grafana-to-guance-dashboard/references/converter-notes.md

@@ -0,0 +1,134 @@
+# Converter Notes
+
+## Skill Files
+
+- `skills/grafana-to-guance-dashboard/scripts/convert-grafana-dashboard.mjs`: standalone converter shipped by this skill
+- `schemas/dashboard-schema.json`: Guance dashboard schema entrypoint
+
+## Current Mapping Notes
+
+### Variables
+
+- Supported Grafana variable types:
+  - `query`
+  - `custom`
+- Variable mapping:
+  - `query` -> `PROMQL_QUERY`
+  - `custom` -> `CUSTOM_LIST`
+
+Additional Grafana variable types such as `textbox`, `constant`, `interval`, and `datasource` are converted into Guance custom-list style variables by the standalone script.
+
+The standalone script also preserves extra variable metadata such as `refresh`, `skipUrlSync`, `sort`, `description`, and raw option lists under `var.extend`.
+
+### Panels
+
+Panel type mapping currently lives in `convert-grafana-dashboard.mjs`.
+
+If a Grafana panel type is missing, the panel is filtered out before conversion. Add the panel type to the standalone script map before debugging deeper.
+
+By default, the converter does not emit raw `extend.grafana` metadata in the generated Guance dashboard. Use `--keep-grafana-meta` only when you need source-level debugging context.
+
+### Queries
+
+The converter pulls query text from the first defined field among:
+
+1. `target.expr`
+2. `target.query`
+3. `target.queryText`
+4. `target.expression`
+5. `target.rawSql`
+
+Generated Guance queries default to PromQL-style output unless the query looks like DQL:
+
+```json
+{
+  "datasource": "dataflux",
+  "qtype": "promql",
+  "type": "sequence",
+  "query": {
+    "q": "...",
+    "type": "promql",
+    "code": "a",
+    "promqlCode": 1
+  }
+}
+```
+
+Variable replacement is intentionally conservative:
+
+- only known Grafana dashboard variables are rewritten from `$var` / `${var}` to `#{var}`
+- Grafana built-ins such as `${__from}` and `${__to}` are preserved
+- unknown template expressions such as JavaScript local variables in text panels stay unchanged, for example `${hotcall}`
+
+Query classification is datasource-aware:
+
+- Prometheus-like datasources stay `promql`
+- SQL-like datasources such as MySQL/Postgres/MSSQL are emitted as `dql`
+- `guance-guance-datasource` defaults to `dql`
+- if a `guance-guance-datasource` target explicitly sets `qtype: "promql"`, that explicit PromQL mode wins
+- the generated `query.type` now follows the same classification instead of falling back to `simple`
+
+Guance PromQL compatibility mode:
+
+- pass `--guance-promql-compatible` to rewrite PromQL metric selectors from `metric_name` to `measurement:field`
+- the rewrite is conservative and only applies to metric selector tokens outside label braces
+- label keys such as `app_name` and grouping keys such as `by (app_name)` are preserved
+- keep this mode opt-in, because some dashboards may already target Guance-native metric names
+
+### Layout
+
+Grafana `gridPos` is not copied directly.
+
+- `x` and `w` are kept close to Grafana values
+- `y` and `h` are scaled into a Guance-friendly layout ratio
+
+If the final dashboard looks vertically misaligned, inspect the layout conversion helpers first.
+
+## Debug Checklist
+
+When output is wrong:
+
+1. Confirm the panel type is in the standalone script panel map.
+2. Confirm the panel has `gridPos`.
+3. Confirm the panel has usable `targets`.
+4. Check whether the query lives in `expr`, `query`, or `queryText`.
+5. Check whether row panels are collapsed, because collapsed and expanded rows are handled differently.
+6. Validate the generated JSON with:
+
+```bash
+node scripts/validate-file.mjs path/to/output.json
+```
+
+## Settings Conversion
+
+The standalone script attempts to convert:
+
+- thresholds -> Guance `levels`
+- Grafana value maps and range maps -> Guance `mappings`
+- table override mappings -> Guance `valMappings`
+- legend placement and legend values, including older Grafana `legend.current/avg/min/max/total`
+- units, decimals, min, max from both newer and older Grafana panel formats
+- stacking and connect-nulls behavior from both newer and older Grafana panel formats
+- table column organize / rename / exclude / order transformations
+- panel links and field links into `extend.links`
+- appearance metadata into `settings.extend.appearance`, including:
+  - `lineWidth`
+  - `fillOpacity`
+  - `pointMode`
+  - `graphMode`
+  - `colorMode`
+  - `textMode`
+  - `reduceCalcs`
+  - `gaugeMode`
+
+This is heuristic conversion. For plugin-specific panels, validate the generated JSON and then refine the script with a real sample.
+
+## Safe Extension Pattern
+
+When adding support for a new panel type:
+
+1. Add the Grafana panel type to the standalone script panel map.
+2. Decide the Guance chart type target.
+3. Add any special-case settings generation in the standalone script.
+4. Convert a real dashboard containing that panel.
+5. Run `npm run validate`.