Skip to content

插件开发指南 ​

薇薇官机平台的用户插件使用 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;
  },
};

重要规则 ​

  1. 返回 true 表示已处理,后续插件/关键词/工作流/AI 不再执行。
  2. 不处理就返回 false,不要无条件 true。
  3. 必须处理异常,避免用户看到失败却没有任何提示。
  4. 不要依赖模块顶层变量做长期存储,使用 ctx.kv。
  5. 不要把 Token、Cookie、用户隐私写进日志。
  6. 同一条消息每个插件最多回复 2 条(QQ 对同一条被动消息总上限 5 条)。

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