perses-plugin-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Perses Plugin Create

Perses 插件创建

Scaffold and implement Perses plugins with CUE schemas and React components.

使用CUE schema和React组件搭建并实现Perses插件。

Operator Context

操作场景

This skill guides the full lifecycle of creating a Perses plugin: scaffolding the directory structure with

percli

, defining the CUE schema and JSON example, implementing the React component, validating schemas, and building the distributable archive.

本技能指导创建Perses插件的完整生命周期：使用percli搭建目录结构、定义CUE schema和JSON示例、实现React组件、验证schema、构建可分发归档包。

Hardcoded Behaviors (Always Apply)

硬性规则（始终适用）

Schema + example together: Always create both the CUE schema and a matching JSON example file -- never one without the other
Test before build: Always run
```
percli plugin test-schemas
```
before
```
percli plugin build
```
-- a build without passing schema tests is forbidden
Model package: CUE schemas must declare
```
package model
```
as the first line after imports
Close spec definitions: Always wrap spec fields in
```
close({...})
```
to reject unknown fields during validation
Validate JSON against schema: After creating the JSON example, run
```
percli plugin test-schemas
```
to confirm the example passes CUE validation before moving to React implementation

Schema与示例文件必须配套：始终同时创建CUE schema和对应的JSON示例文件——绝不能只创建其中一个
构建前必须测试：在执行
```
percli plugin build
```
前必须先运行
```
percli plugin test-schemas
```
——未通过schema测试的构建是被禁止的
Model包声明：CUE schema必须在导入语句后第一行声明
```
package model
```
严格的Spec定义：始终将spec字段包裹在
```
close({...})
```
中，以在验证时拒绝未知字段
验证JSON与schema匹配：创建JSON示例后，在开始React组件实现前，运行
```
percli plugin test-schemas
```
以确认示例通过CUE验证

Default Behaviors (ON unless disabled)

默认行为（除非禁用否则生效）

Panel type: Default to Panel plugin type if the user does not specify a type
Include migration: Generate Grafana migration scaffold (
```
schemas/<type>/<name>/migrate/migrate.cue
```
) if a Grafana equivalent panel exists
Reference official plugins: Check the 27 official plugins across 6 categories for similar implementations before creating a new plugin from scratch

默认Panel类型：如果用户未指定插件类型，默认使用Panel插件类型
包含迁移文件：若存在对应的Grafana面板，则生成Grafana迁移脚手架（
```
schemas/<type>/<name>/migrate/migrate.cue
```
）
参考官方插件：在从零开始创建新插件前，先查看6个分类下的27个官方插件，参考类似实现

Optional Behaviors (OFF unless enabled)

可选行为（除非启用否则不生效）

Multi-plugin module: Create multiple related plugins within a single module (one module can contain multiple plugins)
Hot-reload dev server: Start
```
percli plugin start
```
against a running Perses server for live development
Custom shared types: Import shared CUE types from
```
github.com/perses/shared/cue/common
```
for format, thresholds, sorting, etc.

多插件模块：在单个模块中创建多个相关插件（一个模块可包含多个插件）
热重载开发服务器：针对运行中的Perses服务器启动
```
percli plugin start
```
以进行实时开发
自定义共享类型：从
```
github.com/perses/shared/cue/common
```
导入共享CUE类型，用于格式化、阈值、排序等功能

What This Skill CAN Do

本技能可实现的功能

Scaffold a new plugin directory with
```
percli plugin generate
```
Create CUE schema definitions for any plugin type: Panel, Datasource, TimeSeriesQuery, TraceQuery, ProfileQuery, LogQuery, Variable, Explore
Create matching JSON example files for schema validation
Generate Grafana migration schemas for plugins with Grafana equivalents
Implement React components with the rsbuild-based build system
Build distributable archives (.zip/.tar/.tar.gz) containing package.json, mf-manifest.json, schemas/, and __mf/

使用
```
percli plugin generate
```
搭建新插件目录
为任意插件类型创建CUE schema定义：Panel、Datasource、TimeSeriesQuery、TraceQuery、ProfileQuery、LogQuery、Variable、Explore
创建用于schema验证的匹配JSON示例文件
为存在Grafana等效插件的项目生成Grafana迁移schema
基于rsbuild构建系统实现React组件
构建包含package.json、mf-manifest.json、schemas/和__mf/的可分发归档包（.zip/.tar/.tar.gz）

What This Skill CANNOT Do

本技能不可实现的功能

Create or manage dashboards (use perses-dashboard-create)
Deploy Perses server instances (use perses-deploy)
Review existing plugin code for quality (use perses-code-review)
Run the plugin test suite beyond schema validation (use perses-plugin-test)
Manage datasource connections or variables at the project level (use perses-datasource-manage or perses-variable-manage)

创建或管理仪表盘（请使用perses-dashboard-create）
部署Perses服务器实例（请使用perses-deploy）
评审现有插件代码质量（请使用perses-code-review）
执行schema验证以外的插件测试套件（请使用perses-plugin-test）
在项目层面管理数据源连接或变量（请使用perses-datasource-manage或perses-variable-manage）

Error Handling

错误处理

Cause	Symptom	Solution
`percli plugin generate` fails: directory exists	"directory already exists" error	Remove or rename the existing directory, or generate into a different path
`percli plugin generate` fails: invalid type	Unrecognized plugin type error	Use one of: Panel, Datasource, TimeSeriesQuery, TraceQuery, ProfileQuery, LogQuery, Variable, Explore
`percli plugin generate` fails: missing flags	Missing required flag error	All four flags are required: `--module.org` , `--module.name` , `--plugin.type` , `--plugin.name`
CUE schema compilation error: missing package	"cannot determine package name"	Add `package model` as the first line of the .cue file (after any imports)
CUE schema compilation error: unclosed close()	Syntax error in CUE	Ensure `close({...})` has matching braces -- every `{` needs a `}` before the closing `)`
CUE schema compilation error: bad import path	Import not found for shared types	Use exact path `"github.com/perses/shared/cue/common"` -- not shorthand or relative imports
JSON example does not match schema: extra fields	`close()` rejects unknown fields	Remove fields from JSON that are not defined in the CUE schema, or add them to the schema
JSON example does not match schema: wrong types	Type mismatch error	Ensure JSON values match CUE type declarations (string vs int vs bool)
JSON example does not match schema: missing required	Required field not present	Add all non-optional fields (those without `?` suffix in CUE) to the JSON example
`percli plugin build` produces empty archive	Archive missing mf-manifest.json	Run `rsbuild build` (or equivalent npm build) first -- the React build must succeed before archive creation
`percli plugin build` fails: wrong directory	Build cannot find plugin config	Run `percli plugin build` from the module root directory (where package.json lives)

原因	症状	解决方案
`percli plugin generate` 执行失败：目录已存在	提示「directory already exists」错误	删除或重命名现有目录，或在不同路径下生成项目
`percli plugin generate` 执行失败：类型无效	提示无法识别的插件类型错误	使用以下合法类型之一：Panel、Datasource、TimeSeriesQuery、TraceQuery、ProfileQuery、LogQuery、Variable、Explore
`percli plugin generate` 执行失败：缺少参数	提示缺少必填参数错误	四个参数均为必填： `--module.org` 、 `--module.name` 、 `--plugin.type` 、 `--plugin.name`
CUE schema编译错误：缺少包声明	提示「cannot determine package name」	在.cue文件的导入语句后添加 `package model` 作为第一行
CUE schema编译错误：close()未闭合	CUE语法错误	确保 `close({...})` 的括号匹配——每个 `{` 都需要在 closing `)` 前有对应的 `}`
CUE schema编译错误：导入路径错误	共享类型导入未找到	使用精确路径 `"github.com/perses/shared/cue/common"` ——不要使用简写或相对导入
JSON示例与schema不匹配：存在额外字段	`close()` 拒绝未知字段	移除JSON中未在CUE schema定义的字段，或在schema中添加这些字段
JSON示例与schema不匹配：类型错误	类型不匹配错误	确保JSON值与CUE类型声明一致（字符串、整数、布尔值等）
JSON示例与schema不匹配：缺少必填字段	必填字段不存在	向JSON示例中添加所有非可选字段（CUE中不带 `?` 后缀的字段）
`percli plugin build` 生成空归档包	归档包缺少mf-manifest.json	先执行 `rsbuild build` （或等效的npm构建命令）——React构建必须成功才能创建归档包
`percli plugin build` 执行失败：目录错误	构建无法找到插件配置	在模块根目录（package.json所在目录）执行 `percli plugin build`

Anti-Patterns

反模式

Anti-Pattern	Why It Fails	Do Instead
Creating CUE schema without JSON example	`percli plugin test-schemas` has nothing to validate against -- schema errors are invisible until runtime	Always create both files together and run `percli plugin test-schemas` immediately
Not using `close({...})` for spec	Without `close()` , the schema accepts any unknown fields -- validation becomes meaningless	Always wrap spec in `close({...})` to enforce strict field validation
Skipping Grafana migration schema when equivalent exists	Users migrating from Grafana hit a dead end when no migration path exists for their panels	Check if a Grafana equivalent exists and create `migrate/migrate.cue` if so
Hard-coding default values in the React component	Users cannot configure the plugin's behavior through the dashboard JSON -- defaults are invisible	Define defaults as configurable fields in the CUE schema with sensible default values
Copying schema from another plugin without adjusting `kind`	The `kind` field identifies the plugin -- duplicates cause plugin resolution conflicts at runtime	Always set `kind` to match the unique plugin name
Building archive before running test-schemas	Schema errors ship in the archive and cause runtime failures on the Perses server	Run `percli plugin test-schemas` and fix all errors before `percli plugin build`

反模式	失败原因	正确做法
只创建CUE schema而不创建JSON示例	`percli plugin test-schemas` 没有可验证的对象——schema错误在运行前无法发现	始终同时创建两个文件，并立即运行 `percli plugin test-schemas`
不为spec使用 `close({...})`	没有 `close()` 时，schema会接受任何未知字段——验证失去意义	始终将spec包裹在 `close({...})` 中以强制执行严格的字段验证
存在等效Grafana插件时跳过迁移schema	从Grafana迁移的用户会因没有面板迁移路径而受阻	检查是否存在等效Grafana插件，若存在则创建 `migrate/migrate.cue`
在React组件中硬编码默认值	用户无法通过仪表盘JSON配置插件行为——默认值不可见	在CUE schema中定义可配置的默认字段，并设置合理的默认值
从其他插件复制schema但未修改 `kind`	`kind` 字段用于标识插件——重复的 `kind` 会在运行时导致插件解析冲突	始终将 `kind` 设置为与唯一插件名称匹配的值
未运行test-schemas就构建归档包	schema错误会被包含在归档包中，导致在Perses服务器运行时失败	运行 `percli plugin test-schemas` 并修复所有错误后，再执行 `percli plugin build`

Anti-Rationalization

错误合理化纠正

Rationalization	Reality	Required Action
"The schema is simple, it doesn't need a JSON example"	Even simple schemas need validation -- typos in field names or types are invisible without a test	Create the JSON example and run test-schemas
"close() is too restrictive, I'll add it later"	Without close(), the schema validates nothing -- any garbage JSON passes	Add close() now, relax specific fields with `...` only if needed
"The React component compiles so the plugin works"	React compilation says nothing about schema correctness or plugin registration	Run percli plugin test-schemas AND verify the archive structure
"I'll skip migration since most users start fresh"	Organizations migrating from Grafana are the primary adoption path -- migration is not optional when equivalents exist	Check for Grafana equivalent and create migration schema
"One test run passed, the schema is correct"	A single JSON example may not cover optional fields, edge cases, or constraint boundaries	Verify the example includes representative values for all fields

错误理由	实际情况	必须执行的操作
「schema很简单，不需要JSON示例」	即使简单的schema也需要验证——字段名或类型的拼写错误在没有测试的情况下无法发现	创建JSON示例并运行test-schemas
「close()太严格了，我之后再加」	没有close()时，schema不进行任何验证——任何无效JSON都会通过	立即添加close()，仅在必要时使用 `...` 放宽特定字段
「React组件编译通过了，所以插件没问题」	React编译成功不代表schema正确或插件注册成功	运行percli plugin test-schemas并验证归档包结构
「我跳过迁移，因为大多数用户是从零开始使用」	从Grafana迁移的企业用户是主要的采用路径——存在等效插件时，迁移是必须的	检查是否存在等效Grafana插件并创建迁移schema
「一次测试通过了，schema就正确了」	单个JSON示例可能无法覆盖可选字段、边缘情况或约束边界	确保示例包含所有字段的代表性值

FORBIDDEN Patterns

禁止行为

These are hard stops. Do NOT proceed past these.

NEVER run

percli plugin build

without

percli plugin test-schemas

passing first

NEVER create a CUE schema without a corresponding JSON example file
NEVER omit
```
package model
```
from a CUE schema file
NEVER omit
```
close({...})
```
around the spec definition
NEVER use a
```
kind
```
value that duplicates an existing plugin in the same module

以下行为是绝对禁止的，请勿执行。

绝对不要在

percli plugin test-schemas

未通过前执行

percli plugin build

绝对不要只创建CUE schema而不创建对应的JSON示例文件
绝对不要在CUE schema文件中省略
```
package model
```
声明
绝对不要在spec定义中省略
```
close({...})
```
绝对不要在同一模块中使用与现有插件重复的
```
kind
```
值

Blocker Criteria

操作步骤

—

阶段1：搭建脚手架

STOP and ask the user when:

Plugin type is ambiguous: The user's description could map to multiple plugin types (e.g., "query plugin" could be TimeSeriesQuery, TraceQuery, ProfileQuery, or LogQuery)
Schema fields are unclear: The user describes desired behavior but not the data model -- ask what fields the plugin should accept
Module context is missing: You cannot determine if this is a new module or an addition to an existing module
Grafana equivalent is uncertain: You are unsure whether a Grafana panel equivalent exists for migration purposes
Shared type usage: The user references "thresholds", "format", or "sort" but you are unsure which shared CUE types from
```
github.com/perses/shared/cue/common
```
to import

目标：使用percli生成插件目录结构。

根据用户需求确定插件类型（默认：Panel）
选择模块组织方式：新建模块或添加到现有模块
执行脚手架生成命令：

bash

percli plugin generate \
  --module.org=<org> \
  --module.name=<name> \
  --plugin.type=<Panel|Datasource|TimeSeriesQuery|TraceQuery|ProfileQuery|LogQuery|Variable|Explore> \
  --plugin.name=<PluginName> \
  <directory>

检查点：目录结构生成完成。进入阶段2。

Instructions

阶段2：定义Schema

Phase 1: SCAFFOLD

—

Goal: Generate the plugin directory structure with percli.

Determine plugin type from user request (default: Panel)
Choose module organization: new module or add to existing
Run scaffolding:

bash

percli plugin generate \
  --module.org=<org> \
  --module.name=<name> \
  --plugin.type=<Panel|Datasource|TimeSeriesQuery|TraceQuery|ProfileQuery|LogQuery|Variable|Explore> \
  --plugin.name=<PluginName> \
  <directory>

Gate: Directory structure generated. Proceed to Phase 2.

目标：定义CUE schema和JSON示例。

编辑位于

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

的CUE schema：

cue

package model

import "github.com/perses/shared/cue/common"  // 仅在需要共享类型时导入

kind: "<PluginName>"
spec: close({
    // 必填字段（无?后缀）
    field1: string
    // 可选字段（带?后缀）
    field2?: int
    // 来自common的共享类型
    format?: common.#format
})

创建位于

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

的JSON示例：

json

{
  "kind": "<PluginName>",
  "spec": {
    "field1": "example-value"
  }
}

若存在等效Grafana插件，创建位于
```
schemas/<plugin-type>/<plugin-name>/migrate/migrate.cue
```
的迁移schema
立即验证：

bash

percli plugin test-schemas

检查点：

percli plugin test-schemas

执行通过。进入阶段3。

Phase 2: SCHEMA

阶段3：实现组件

Goal: Define the CUE schema and JSON example.

Edit CUE schema at

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

cue

package model

import "github.com/perses/shared/cue/common"  // only if shared types needed

kind: "<PluginName>"
spec: close({
    // Required fields (no ? suffix)
    field1: string
    // Optional fields (? suffix)
    field2?: int
    // Shared types from common
    format?: common.#format
})

Create JSON example at

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

json

{
  "kind": "<PluginName>",
  "spec": {
    "field1": "example-value"
  }
}

If Grafana equivalent exists, create migration schema at
```
schemas/<plugin-type>/<plugin-name>/migrate/migrate.cue
```
Validate immediately:

bash

percli plugin test-schemas

Gate:

percli plugin test-schemas

passes. Proceed to Phase 3.

目标：构建React组件。

在
```
src/<type>/<name>/
```
目录下实现React组件
遵循脚手架模板中基于rsbuild的构建系统规范
参考官方插件（6个分类下的27个插件）的类似实现

检查点：React组件构建无错误。进入阶段4。

Phase 3: IMPLEMENT

阶段4：测试插件

Goal: Build the React component.

Implement React component at
```
src/<type>/<name>/
```
Follow the rsbuild-based build system conventions from the scaffolded template
Reference official plugins (27 across 6 categories) for similar implementations

Gate: React component builds without errors. Proceed to Phase 4.

目标：验证完整插件。

bash

undefined

Phase 4: TEST

验证schema与JSON示例匹配

Goal: Validate the complete plugin.

bash

undefined

percli plugin test-schemas

Validate schemas against JSON examples

可选：针对运行中的Perses启动热重载开发服务器

percli plugin test-schemas

percli plugin start


**检查点**：所有schema测试通过。进入阶段5。

Optional: hot-reload dev server against running Perses

阶段5：构建归档包

percli plugin start


**Gate**: All schema tests pass. Proceed to Phase 5.

目标：创建可分发归档包。

bash

percli plugin build

验证归档包包含：package.json、mf-manifest.json、schemas/、__mf/

检查点：归档包创建完成且结构验证通过。进入阶段6。

Phase 5: BUILD

阶段6：部署插件

Goal: Create the distributable archive.

bash

percli plugin build

Verify archive contains: package.json, mf-manifest.json, schemas/, __mf/

Gate: Archive created and structure verified. Proceed to Phase 6.

目标：安装插件。

将归档包安装到Perses服务器的

plugins-archive/

目录，或通过npm嵌入到捆绑部署包中。

检查点：插件已安装并在Perses服务器中加载。任务完成。

Phase 6: DEPLOY

参考资料

Goal: Install the plugin.

Install archive in Perses server's

plugins-archive/

directory, or embed via npm for bundled deployments.

Gate: Plugin installed and loading in Perses server. Task complete.

插件类型：Panel、Datasource、TimeSeriesQuery、TraceQuery、ProfileQuery、LogQuery、Variable、Explore
官方插件：perses/plugins中6个分类下的27个插件

CUE schema位置：

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

JSON示例位置：

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

迁移schema位置：

schemas/<plugin-type>/<plugin-name>/migrate/migrate.cue

React组件位置：
```
src/<type>/<name>/
```
共享CUE类型：
```
github.com/perses/shared/cue/common
```
（格式化、阈值、排序）
归档包格式：包含package.json、mf-manifest.json、schemas/、__mf/的.zip/.tar/.tar.gz文件
相关技能：perses-plugin-test、perses-plugin-pipeline、perses-cue-schema、perses-deploy

References

—

Plugin types: Panel, Datasource, TimeSeriesQuery, TraceQuery, ProfileQuery, LogQuery, Variable, Explore
Official plugins: 27 plugins across 6 categories in perses/plugins

CUE schema location:

schemas/<plugin-type>/<plugin-name>/<plugin-name>.cue

JSON example location:

schemas/<plugin-type>/<plugin-name>/<plugin-name>.json

Migration schema location:

schemas/<plugin-type>/<plugin-name>/migrate/migrate.cue

React component location:
```
src/<type>/<name>/
```
Shared CUE types:
```
github.com/perses/shared/cue/common
```
(format, thresholds, sorting)
Archive format: .zip/.tar/.tar.gz containing package.json, mf-manifest.json, schemas/, __mf/
Related skills: perses-plugin-test, perses-plugin-pipeline, perses-cue-schema, perses-deploy

—