perses-lint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses Lint

Validate Perses resource definitions using

percli lint

. Supports local structural validation and online server-side validation that checks plugin schemas, datasource existence, and variable resolution.

使用

percli lint

验证Perses资源定义。支持本地结构验证，以及对接服务器的在线验证（可检查插件模式、数据源存在性和变量解析情况）。

Operator Context

操作场景

This skill operates as a validation gate for Perses resources. It runs

percli lint

against JSON/YAML resource files, interprets errors, applies fixes, and re-validates until all issues are resolved.

该技能作为Perses资源的验证关卡，针对JSON/YAML资源文件运行

percli lint

，解析错误、应用修复并重新验证，直至所有问题解决。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Show full output: Always display complete lint output, never summarize or truncate
Online when possible: Prefer
```
--online
```
mode when a Perses server is reachable
Fix-then-revalidate loop: Never claim fixes are correct without re-running lint
Report every error: Surface all lint errors, not just the first one encountered
Preserve user intent: When fixing invalid plugin kinds, ask user which plugin they intended rather than guessing

显示完整输出：始终展示完整的lint输出，绝不总结或截断
优先在线模式：当可连接到Perses服务器时，优先使用
```
--online
```
模式
修复后重新验证循环：未重新运行lint前，绝不声称修复正确
报告所有错误：呈现所有lint错误，而非仅第一个遇到的错误
保留用户意图：修复无效插件类型时，询问用户期望使用的插件，而非自行猜测

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Batch mode for directories: When pointed at a directory, validate all
```
.json
```
and
```
.yaml
```
files
Error grouping: Group lint errors by category (plugin, datasource, variable, layout) in output
Suggest online mode: If local lint passes but user has a server configured, suggest online re-check

目录批量模式：当指定目录时，验证所有
```
.json
```
和
```
.yaml
```
文件
错误分组：在输出中按类别（插件、数据源、变量、布局）分组显示lint错误
建议在线模式：若本地lint通过，但用户已配置服务器，则建议进行在线重新检查

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

Auto-fix mode: Automatically apply fixes for unambiguous errors (e.g., typo in plugin kind)
CI integration: Output lint results in machine-parseable format for CI pipelines
Strict mode: Treat warnings as errors (fail on any non-clean lint output)

自动修复模式：自动修复明确的错误（例如插件类型拼写错误）
CI集成：以机器可解析的格式输出lint结果，用于CI流水线
严格模式：将警告视为错误（任何非干净的lint输出均判定为失败）

What This Skill CAN Do

该技能可实现的功能

Run local structural validation with
```
percli lint -f <file>
```
Run server-side validation with
```
percli lint -f <file> --online
```
(checks plugin schemas, datasource existence)
Validate individual files or batch-validate entire directories
Diagnose and fix invalid panel plugin kinds, missing datasource references, broken variable references, and layout mismatches
Re-validate after fixes to confirm resolution

使用
```
percli lint -f <file>
```
进行本地结构验证
使用
```
percli lint -f <file> --online
```
进行服务器端验证（检查插件模式数据源存在性）
验证单个文件或批量验证整个目录
诊断并修复无效面板插件类型、缺失的数据源引用、损坏的变量引用以及布局不匹配问题
修复后重新验证以确认问题已解决

What This Skill CANNOT Do

该技能无法实现的功能

Create dashboards from scratch (use perses-dashboard-create)
Deploy or configure Perses servers (use perses-deploy)
Develop or test custom plugins (use perses-plugin-create or perses-plugin-test)
Fix PromQL/TraceQL query logic errors (lint validates structure, not query semantics)

从零开始创建仪表盘（请使用perses-dashboard-create）
部署或配置Perses服务器（请使用perses-deploy）
开发或测试自定义插件（请使用perses-plugin-create或perses-plugin-test）
修复PromQL/TraceQL查询逻辑错误（lint仅验证结构，不涉及查询语义）

Error Handling

错误处理

Cause	Symptom	Solution
Invalid panel plugin kind	`unknown kind "TimeseriesChart"` — plugin name not in the 27 official plugins	Check against official list below. Common typos: `TimeseriesChart` -> `TimeSeriesChart` , `Stat` -> `StatChart` , `Gauge` -> `GaugeChart` . Fix the `kind` field in the panel spec.
Missing datasource reference	`datasource "myPrometheus" not found` — panel references a datasource not defined in the dashboard	Add the datasource to the dashboard's `spec.datasources` map, or correct the datasource name to match an existing one. Online mode catches this more reliably.
Invalid variable reference	`variable "cluter" not found` — `$ref` points to a variable name that does not exist in `spec.variables`	Check all `$ref` values against the keys in `spec.variables` . Fix the typo or add the missing variable definition.
Layout $ref mismatch	`panel "panel-3" referenced in layout but not found in panels` — a panel ID in `spec.layouts[].spec.display.panels` does not match any key in `spec.panels`	Ensure every panel ID referenced in layout sections exists as a key in `spec.panels` . Remove stale layout references or add the missing panel.
Connection refused (online mode)	`connection refused` or `dial tcp: connect: connection refused` when using `--online`	Perses server is not running or URL is wrong. Verify server is up with `curl <server-url>/api/v1/health` . Fall back to local lint with `percli lint -f <file>` (no `--online` flag).
Authentication failure (online mode)	`401 Unauthorized` or `403 Forbidden` when using `--online`	Login first with `percli login <server-url> --username <user> --password <pass>` . Check that the token has not expired.

原因	症状	解决方案
无效面板插件类型	`unknown kind "TimeseriesChart"` — 插件名称不在官方27种插件列表中	对照下方官方列表检查。常见拼写错误： `TimeseriesChart` -> `TimeSeriesChart` ， `Stat` -> `StatChart` ， `Gauge` -> `GaugeChart` 。修复面板规格中的 `kind` 字段。
缺失数据源引用	`datasource "myPrometheus" not found` — 面板引用了仪表盘中未定义的数据源	将数据源添加到仪表盘的 `spec.datasources` 映射中，或修正数据源名称以匹配已存在的数据源。在线模式能更可靠地检测此类问题。
无效变量引用	`variable "cluter" not found` — `$ref` 指向了 `spec.variables` 中不存在的变量名称	检查所有 `$ref` 值是否与 `spec.variables` 中的键匹配。修复拼写错误或添加缺失的变量定义。
布局$ref不匹配	`panel "panel-3" referenced in layout but not found in panels` — `spec.layouts[].spec.display.panels` 中的面板ID与 `spec.panels` 中的任何键都不匹配	确保布局部分引用的每个面板ID在 `spec.panels` 中都有对应的条目。移除过时的布局引用或添加缺失的面板。
连接被拒绝（在线模式）	使用 `--online` 时出现 `connection refused` 或 `dial tcp: connect: connection refused`	Perses服务器未运行或URL错误。使用 `curl <server-url>/api/v1/health` 验证服务器是否正常运行。回退到本地lint，使用 `percli lint -f <file>` （不带 `--online` 参数）。
认证失败（在线模式）	使用 `--online` 时出现 `401 Unauthorized` 或 `403 Forbidden`	先使用 `percli login <server-url> --username <user> --password <pass>` 登录。检查令牌是否已过期。

Official Plugin Kinds (27 total)

官方插件类型（共27种）

Chart plugins: TimeSeriesChart, BarChart, GaugeChart, HeatmapChart, HistogramChart, PieChart, ScatterChart, StatChart, StatusHistoryChart, FlameChart

Table plugins: Table, TimeSeriesTable, LogsTable, TraceTable

Display plugins: Markdown, TracingGanttChart

Variable plugins: DatasourceVariable, StaticListVariable

Datasource plugins: PrometheusDatasource, TempoDatasource, and additional community datasource types

图表插件：TimeSeriesChart、BarChart、GaugeChart、HeatmapChart、HistogramChart、PieChart、ScatterChart、StatChart、StatusHistoryChart、FlameChart

表格插件：Table、TimeSeriesTable、LogsTable、TraceTable

展示插件：Markdown、TracingGanttChart

变量插件：DatasourceVariable、StaticListVariable

数据源插件：PrometheusDatasource、TempoDatasource，以及其他社区数据源类型

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Correct Approach
Running `percli apply` without `percli lint` first	Applies a broken resource to the server, then you discover errors at runtime or in the UI	Always run `percli lint -f <file>` before `percli apply -f <file>` . Lint is the gate before deploy.
Only validating locally when a server is available	Local lint checks structure only. Online mode validates against actual plugin schemas, existing datasources, and variable resolution. Many errors only surface with `--online` .	Use `percli lint -f <file> --online` whenever a Perses server is reachable.
Ignoring lint warnings (only fixing errors)	Warnings often indicate deprecated fields, unused variables, or schema drift that will become errors in future Perses versions	Fix all warnings. Use strict mode ( `--strict` if available) in CI to enforce zero-warning policy.
Fixing one error at a time and re-running	Wastes cycles. Multiple errors are often related (e.g., renamed datasource breaks 5 panels)	Read ALL lint errors first, identify root causes, batch-fix related errors, then re-validate once.

反模式	失败原因	正确做法
先运行 `percli apply` 再运行 `percli lint`	向服务器应用了有问题的资源，之后才在运行时或UI中发现错误	运行 `percli apply -f <file>` 前，务必先运行 `percli lint -f <file>` 。Lint是部署前的验证关卡。
已有服务器可用时仅进行本地验证	本地lint仅检查结构。在线模式会针对实际插件模式、已存在的数据源和变量解析进行验证。许多错误只有在 `--online` 模式下才会暴露。	只要可连接到Perses服务器，就使用 `percli lint -f <file> --online` 。
忽略lint警告（仅修复错误）	警告通常表示已废弃字段、未使用变量或模式偏移，这些在未来Perses版本中可能会变成错误	修复所有警告。在CI中使用严格模式（若可用 `--strict` ），强制实施零警告策略。
一次修复一个错误并重新运行lint	浪费时间。多个错误往往相关（例如重命名数据源导致5个面板失效）	先阅读所有lint错误，找出根本原因，批量修复相关错误，然后仅重新验证一次。

Anti-Rationalization

反合理化借口

Rationalization	Reality	Required Action
"Lint passed locally, so the dashboard is correct"	Local lint only checks structure. Plugin schemas, datasource existence, and variable resolution require online mode.	Run `--online` against a server before declaring the resource valid.
"I fixed the error, no need to re-run lint"	Fixes can introduce new errors (e.g., fixing a panel kind may reveal a previously-masked datasource error)	Always re-run `percli lint` after every fix. The loop is: lint -> fix -> lint -> confirm clean.
"That warning is not important"	Warnings in Perses often indicate fields that will be removed or required in the next version. Ignoring them creates upgrade debt.	Fix warnings now. They cost minutes today and hours during upgrades.

合理化借口	实际情况	必要操作
本地lint通过了，所以仪表盘没问题	本地lint仅检查结构。插件模式、数据源存在性和变量解析需要在线模式验证。	在声明资源有效前，务必针对服务器运行 `--online` 模式验证。
我已经修复了错误，不需要重新运行lint	修复可能引入新错误（例如修复面板类型可能暴露之前被掩盖的数据源错误）	每次修复后务必重新运行 `percli lint` 。流程是：lint -> 修复 -> lint -> 确认无问题。
那个警告不重要	Perses中的警告通常表示字段将在后续版本中被移除或设为必填。忽略它们会增加升级成本。	立即修复警告。现在修复只需几分钟，升级时可能需要数小时。

FORBIDDEN Patterns

禁止模式

NEVER mark lint as passing when there are unresolved errors or warnings
NEVER modify
```
percli
```
output to hide errors from the user
NEVER skip re-validation after applying fixes
NEVER guess a plugin kind without checking the official 27-plugin list
NEVER run
```
percli apply
```
as a substitute for
```
percli lint
```
("it will tell us if it fails")

绝对不要在存在未解决的错误或警告时标记lint通过
绝对不要修改
```
percli
```
输出以向用户隐藏错误
绝对不要在应用修复后跳过重新验证
绝对不要未对照官方27种插件列表就猜测插件类型
绝对不要用
```
percli apply
```
替代
```
percli lint
```
（“失败了它会告诉我们”）

Blocker Criteria

阻塞条件

Do NOT proceed past validation if any of these are true:

```
percli lint
```
reports any errors (warnings in strict mode)
Online validation was requested but the server is unreachable and no fallback was acknowledged
A plugin kind is used that is not in the official 27-plugin list and the user has not confirmed it is a custom plugin
Any
```
$ref
```
in the layout or variables section points to a non-existent target

若出现以下任一情况，请勿继续验证：

```
percli lint
```
报告任何错误（严格模式下包括警告）
已请求在线验证，但服务器不可达且未确认回退方案
使用了不在官方27种插件列表中的插件类型，且用户未确认它是自定义插件
布局或变量部分的任何
```
$ref
```
指向不存在的目标

Instructions

操作步骤

Phase 1: VALIDATE

阶段1：验证

Goal: Run lint and capture all errors.

bash

undefined

目标：运行lint并捕获所有错误。

bash

undefined

Local validation (structural checks only)

本地验证（仅结构检查）

percli lint -f <file>

Online validation (includes plugin schema checks, datasource existence)

在线验证（包括插件模式检查、数据源存在性）

percli lint -f <file> --online

Batch validation — all JSON files in current directory

批量验证 — 当前目录下所有JSON文件

for f in *.json; do percli lint -f "$f"; done

Batch validation — all YAML files

批量验证 — 所有YAML文件

for f in *.yaml; do percli lint -f "$f"; done


If online mode fails with connection errors, fall back to local mode and note the limitation.

**Gate**: All lint output captured. Proceed to Phase 2.

for f in *.yaml; do percli lint -f "$f"; done


若在线模式因连接错误失败，回退到本地模式并记录限制。

**关卡**：已捕获所有lint输出。进入阶段2。

Phase 2: FIX

阶段2：修复

Goal: Resolve every reported error.

For each error, identify the root cause and apply the fix:

Invalid panel plugin kind -- Check the
```
kind
```
field against the 27 official plugins listed above. Correct typos or capitalization.
Missing datasource reference -- Add the missing datasource to
```
spec.datasources
```
or fix the name to match an existing datasource.
Invalid variable reference -- Verify
```
$ref
```
values match keys in
```
spec.variables
```
. Fix typos or add missing variable definitions.
Layout $ref mismatch -- Ensure every panel ID in
```
spec.layouts[].spec.display.panels
```
has a corresponding entry in
```
spec.panels
```
.
Unknown field errors -- Check Perses API version. Field may have been renamed or removed in a newer version.

When multiple errors share a root cause (e.g., a renamed datasource), fix the root cause once rather than patching each symptom individually.

Gate: All identified errors addressed. Proceed to Phase 3.

目标：解决所有报告的错误。

针对每个错误，找出根本原因并应用修复：

无效面板插件类型 — 对照上方列出的27种官方插件检查
```
kind
```
字段。修正拼写错误或大小写。
缺失数据源引用 — 将缺失的数据源添加到
```
spec.datasources
```
中，或修正名称以匹配已存在的数据源。
无效变量引用 — 验证
```
$ref
```
值是否与
```
spec.variables
```
中的键匹配。修复拼写错误或添加缺失的变量定义。
布局$ref不匹配 — 确保
```
spec.layouts[].spec.display.panels
```
中的每个面板ID在
```
spec.panels
```
中都有对应条目。
未知字段错误 — 检查Perses API版本。该字段可能在新版本中被重命名或移除。

当多个错误共享同一根本原因（例如重命名数据源），只需修复一次根本原因，而非逐个修补症状。

关卡：所有已识别的错误均已处理。进入阶段3。

Phase 3: RE-VALIDATE

阶段3：重新验证

Goal: Confirm all fixes are correct.

bash

undefined

目标：确认所有修复正确。

bash

undefined

Re-run the same lint command used in Phase 1

重新运行阶段1中使用的lint命令

percli lint -f <file>

or

或

percli lint -f <file> --online


- If new errors appear, return to Phase 2.
- Maximum 3 fix-revalidate cycles. If errors persist after 3 cycles, report remaining errors to the user with full context.

**Gate**: Lint returns zero errors. Validation complete.

---

percli lint -f <file> --online


- 若出现新错误，返回阶段2。
- 最多进行3次修复-重新验证循环。若3次循环后仍有错误，向用户报告剩余错误及完整上下文。

**关卡**：Lint返回零错误。验证完成。

---

References

参考资料

Perses documentation: https://perses.dev/docs/
percli CLI reference: https://perses.dev/docs/cli/percli/
Perses plugin list: https://perses.dev/docs/plugins/
Perses GitHub repository: https://github.com/perses/perses
percli lint usage:
```
percli lint --help
```

Perses文档：https://perses.dev/docs/
percli CLI参考：https://perses.dev/docs/cli/percli/
Perses插件列表：https://perses.dev/docs/plugins/
Perses GitHub仓库：https://github.com/perses/perses
percli lint使用说明：
```
percli lint --help
```