插件开发指南
薇薇官机平台的用户插件使用 JavaScript 编写,运行在独立 Worker +
node:vm沙箱中。开发前请先通过插件开发者申请。
你能开发什么
- 指令回复、菜单、查询
- 调用第三方 HTTP API
- Markdown 消息与 QQ 原生按钮
- 图片、视频、语音、文件
- 群管、入群审批、成员查询
- 持久化 KV、会话、积分
- 为插件声明独立的专业配置页面
- 按钮回调、入群事件
- 主动群消息 / 私聊 / AI 调用
开发流程
text
申请开发者
↓
写 index.js + plugin.json
↓
上传 .wwp 或在线提交
↓
管理员审核
↓
上架商店
↓
用户安装并启用
↓
插件收到消息执行文档目录
| 文档 | 内容 |
|---|---|
| 第一个插件 | 最小可运行插件 |
| 插件包与清单 | .wwp、plugin.json、元数据 |
| 自定义配置页面 | 配置 Schema、字段类型、运行时读取 |
| 运行时与生命周期 | 沙箱、超时、内存、onLoad |
| ctx API 总览 | 所有字段和方法 |
| 事件系统 | 消息、入群、入群申请、按钮 |
| 文本、Markdown 与按钮 | 回复与键盘 |
| 图片、语音、视频与文件 | 媒体发送 |
| KV 存储与 HTTP | 持久化与外部请求 |
| 权限、群管与入群审批 | 主人/管理员/群管 |
| 高级机器人与底层 API | 主动消息、群状态、AI、callApi |
| 插件生态公开 API | 读取商店/内置插件 |
| 完整示例与调试 | 天气、菜单、分页、排错 |
| 安全规范与限制 | 不能做什么 |
最小结构
js
module.exports = {
async onMessage(ctx) {
if (ctx.content.trim() !== '你好') return false;
await ctx.reply(`你好,${ctx.userName || '群友'}`);
return true;
},
};重要规则
- 返回
true表示已处理,后续插件/关键词/工作流/AI 不再执行。 - 不处理就返回
false,不要无条件true。 - 必须处理异常,避免用户看到失败却没有任何提示。
- 不要依赖模块顶层变量做长期存储,使用
ctx.kv。 - 不要把 Token、Cookie、用户隐私写进日志。
- 同一条消息每个插件最多回复 2 条(QQ 对同一条被动消息总上限 5 条)。
