插件包与清单
支持格式
.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.htmlassets/只是打包存放,运行时读不到(沙箱没有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 |
* | 全量接收(如发言统计这类观察型插件) |
来源优先级:
plugin.json的triggers,或单文件头注释里的triggers:;- 没有声明时,平台扫描代码里的指令字面量(如
content === '签到'、.startsWith('查询 ')、/^(诊断|状态)/)自动推导,再用commands的首词补充; - 两者都为空时按
*处理,后台会标记为「未声明触发词·可能抢答」。
按钮回调、入群事件、入群申请不走触发词过滤。
图标说明
图标必填且必须是图片,商店列表、「我的插件」、详情页都会使用。建议正方形、边长 200~1024px、单文件不超过 2MB:
text
https://your-cdn.com/icon.png
/uploads/plugin-icons/xxx.png # 开发者中心上传后得到的路径
data:image/png;base64,...推荐在开发者中心上传或使用公网 URL;data URI 会让包变大。
