Plugin Manifest

插件清单

manifest.json 是插件的元数据文件，声明插件的基本信息、依赖关系和权限。它必须存在于 ZIP 根目录。

完整示例

{
  "id": "my-plugin",
  "name": "我的插件",
  "version": "1.0.0",
  "description": "一个示例插件",
  "author": "StackPanel",
  "entry": "dist/index.js",
  "export": "default",
  "schemaVersion": 1,
  "apiVersion": ">=0.4.0",
  "requires": ["store"],
  "provides": ["my-plugin.widget"],
  "consumes": [{ "pluginId": "store", "extensionPoint": "payment.provider", "optional": true }],
  "permissions": ["my-plugin.read", "my-plugin.write"],
  "roleTemplates": [{ "role": "USER", "permissions": ["my-plugin.read"] }],
  "locales": ["zh-CN"]
}

字段详解

字段	必填	类型	说明
id	✅	string	插件唯一标识，/^[a-z0-9_-]{1,64}$/，不可使用保留 ID
name	✅	string	显示名称
version	✅	string	semver 版本号
description	—	string	插件描述
author	—	string	作者
entry	—	string	后端入口文件，默认 dist/index.js
export	—	string	导出名，默认 default
schemaVersion	—	number	清单结构版本，缺省按 1；高于内核支持版本则拒绝安装
apiVersion	—	string	semver 范围，内核版本必须满足此范围（如 >=0.4.0）
requires	—	array	依赖插件列表
provides	—	string[]	提供的扩展点 ID
consumes	—	array	消费的扩展点
permissions	—	string[]	声明的权限字符串
roleTemplates	—	array	角色权限模板
locales	—	string[]	随包携带消息的界面语言（BCP 47，如 zh-CN）
builtin	—	boolean	仅内核 seed 时写入；上传包声明 builtin 会被拒绝

id

插件唯一标识。格式：小写字母、数字、下划线、短横线，1–64 字符。

保留 ID（第三方不可使用）= 全部内置插件 ID + kernel、default。内置清单由内核扫描各包 package.json 的 stackpanel.builtin: true 派生，当前为： catalog、epay、hello、llm-gateway、login、store、store-product-card、store-product-server、store-wallet、ticket、wowid、zjmf-compat、zjmf-upstream。

entry / export

entry 指定后端入口 JS 文件路径（相对于 ZIP 根）。默认 dist/index.js，最大 512KB。

export 指定从入口模块导出的定义名。默认 default（即 export default definePlugin(...)）。如果使用命名导出，设为对应名称。

内核会动态 import() 入口文件，并取 mod[exportName] 作为插件定义。

requires

依赖插件列表。支持两种格式：

"requires": ["store", { "id": "epay", "range": ">=1.0.0", "optional": true }]

属性	说明
id	依赖的插件 ID
range	可选，semver 版本范围
optional	可选，是否可选依赖（默认 false）

详见 插件依赖。

provides / consumes

provides 声明本插件向其他插件提供的扩展点 ID。consumes 声明本插件需要消费的扩展点：

"consumes": [
  { "pluginId": "store", "extensionPoint": "payment.provider", "optional": false }
]

详见 插件依赖。

permissions / roleTemplates

permissions 声明插件使用的权限字符串（用于路由 permission 字段）。

roleTemplates 定义插件激活后自动授予内置角色的权限：

"roleTemplates": [
  { "role": "USER", "permissions": ["my-plugin.read"] },
  { "role": "ADMIN", "permissions": ["my-plugin.read", "my-plugin.write"] }
]

ADMIN 始终拥有全部权限，无需在 roleTemplates 中声明。详见 权限与 RBAC。

自动生成

使用 pnpm plugin:pack <name> 打包时，manifest 会从 package.json 生成 id/name/version/description，注入 schemaVersion 与 apiVersion（>= 当前内核契约版本，来源 @stackpanel/spec）。requires/provides/consumes/permissions/roleTemplates 则从插件编译产物导出的 manifest 中读取，写入生成的 manifest.json。因此这些字段应声明在插件代码的 manifest 里。

pack-plugin.ts 直接 import dist/index.js 并读取 definition.manifest；内置插件 seed 走的是 lib/plugins.ts 的 readBuiltinPluginMetadata。