Skip to content

插件包与清单 ​

支持格式 ​

  • .wwp / .zip:plugin.json + 入口 JS + 可选资源(推荐)
  • 单文件 .js:文件头注释写元数据

上传包最大 20MB,入口代码最大 1MB。

单文件 .js 的能力限制

单文件上传只解析代码头部注释里的基础字段(slug / name / version / category / description / icon / changelog / triggers / permissions)。不支持 settings_schema(配置页)、README、截图、付费等包级字段——需要配置页的插件必须打成 .wwp 包上传。

目录结构 ​

text
my-plugin.wwp
├─ plugin.json
├─ index.js
├─ README.md
├─ assets/
│  └─ icon.png
└─ ui/                  # 自定义控制台页面(可选)
   └─ index.html
  • assets/ 只是打包存放,运行时读不到(沙箱没有 fs),也不提供静态地址;素材走 CDN + 公网 HTTPS URL。
  • ui/ 是唯一「包内文件线上可见」的目录:里面的前端文件随审核版本发布,由平台托管在 /plugin-ui/<slug>/,作为插件自带控制台页面展示给安装者,详见自定义控制台页面。

plugin.json ​

json
{
  "slug": "daily-fortune",
  "name": "每日运势",
  "version": "1.0.0",
  "category": "娱乐",
  "description": "输入「运势」随机抽一签",
  "entry": "index.js",
  "icon": "https://your-cdn.com/fortune.png",
  "triggers": ["运势", "=抽签"],
  "permissions": ["kv"],
  "tags": ["娱乐", "签到"],
  "commands": ["运势"],
  "scenario": "群聊娱乐互动",
  "notes": "结果仅供娱乐",
  "changelog": "修复重复抽签问题",
  "settings_schema": [
    {
      "key": "daily_limit",
      "label": "每日使用次数",
      "type": "number",
      "default": 5,
      "min": 1,
      "max": 100,
      "section": "基础配置"
    }
  ]
}
字段必填说明
slug是3-40 位小写字母/数字/_/-,字母开头
name是显示名称
version否默认 1.0.0
entry否默认 index.js
category否分类(需匹配平台分类词表,上传时自动识别)
description是插件功能描述:用一段话说明插件解决的问题,商店详情页展示
icon是图片地址:https:// 公网 URL、开发者中心上传后的 /uploads/...,或 data:image/(png|jpeg|gif|webp|svg+xml);base64,...。不能用 emoji,否则提交被拒
tags否标签数组,也兼容 {name} 对象
triggers强烈建议触发词数组,最多 60 条,决定哪些消息会进入插件,见下方触发词路由
permissions是权限声明(2026-11-15 起必填),安装前展示给用户确认:admin / media / http / kv / group / ai / balance / relay。平台会扫描代码核对:用到但没声明的权限会直接拒绝提交,错误信息里会列出要补的值。请如实声明、不要多报也不要漏报
commands是指令数组,至少 1 条(也兼容 {command} / {cmd} 对象);只有没声明 triggers 时才会用它的首词补充触发词
scenario是适合场景,如「500 人群管理、娱乐群互动」,商店详情页展示
notes否注意事项
changelog否更新说明
open_source否是否开源,true 时详情页展示源码
settings_schema否声明式配置页面,详见自定义配置页面
console_resources否插件数据面板声明:在安装者的配置页渲染「左侧菜单 + 右侧表格」,直接增删改查插件存的数据(商品、订单、卡密……),详见插件数据面板。兼容旧字段名 console,但推荐用 console_resources
console_pages否自定义控制台页面声明:[{ key, label, path }],path 指向包内 ui/ 里的文件,不声明时平台从 ui/ 顶层 html 自动推导,详见自定义控制台页面

配置结构会和代码一起进入审核并跟随版本发布。待审版本不会提前改变已安装用户的配置页。

提交时自动识别 ​

在开发者中心上传 .wwp 提交插件时,平台会解析包内 plugin.json,自动识别并填充提交表单的以下字段,无需手动重复填写:

识别字段对应表单项必填
slug插件标识是
name插件名称是
version版本号是
description插件功能描述是
commands插件指令(至少 1 条)是
scenario适合场景是
tags插件标签否
category插件分类(需匹配平台分类词表)否
settings_schema自定义配置页 Schema否
changelog更新日志(表单为空时填充)否

识别结果都可以在表单里修改;提交时以表单为准(同字段表单值覆盖包内清单)。请在发布前把这些字段写全,既方便商店识别展示,也能一次过审。

单文件 JS 元数据 ​

js
/**
 * @wwp
 * slug: hello-plugin
 * name: 你好插件
 * version: 1.0.0
 * category: 聊天互动
 * description: 发送你好自动回复
 * scenario: 群聊娱乐互动
 * icon: https://your-cdn.com/hello.png
 * triggers: 你好, =早安
 * commands: 你好
 */
module.exports = { /* ... */ };

更新已有插件 ​

  • 包内 slug 必须与目标插件一致
  • 在开发者中心选择更新目标
  • 新版本只进审核队列,不会先下架旧版本

触发词路由 ​

平台在启动插件沙箱之前先用触发词过滤消息:不命中的消息根本不会进入你的 onMessage,既省资源,也避免多个插件抢答。

写法含义
签到前缀匹配:消息等于「签到」或以「签到」开头
=签到精确匹配
re:^签到(日榜|总榜)?$正则匹配,也可写成 re:/.../i
*全量接收(如发言统计这类观察型插件)

来源优先级:

  1. plugin.json 的 triggers,或单文件头注释里的 triggers:;
  2. 没有声明时,平台扫描代码里的指令字面量(如 content === '签到'、.startsWith('查询 ')、/^(诊断|状态)/)自动推导,再用 commands 的首词补充;
  3. 两者都为空时按 * 处理,后台会标记为「未声明触发词·可能抢答」。

按钮回调、入群事件、入群申请不走触发词过滤。

图标说明 ​

图标必填且必须是图片,商店列表、「我的插件」、详情页都会使用。建议正方形、边长 200~1024px、单文件不超过 2MB:

text
https://your-cdn.com/icon.png
/uploads/plugin-icons/xxx.png      # 开发者中心上传后得到的路径
data:image/png;base64,...

推荐在开发者中心上传或使用公网 URL;data URI 会让包变大。

薇薇官机平台 · ZL 系列插件