Skip to content

运行时与生命周期 ​

执行环境 ​

项目当前值
运行时Node.js Worker + node:vm
内存约 64MB old / 16MB young
同步超时1 秒
异步超时30 秒
代码大小1MB(超出会被拒绝上传,并提示当前体积)
上传包20MB
回复条数同一条消息每个插件最多 2 条,超出静默丢弃;QQ 对同一条被动消息总上限 5 条,所有插件共用
连续失败熔断同一机器人上连续 5 次运行出错自动停用,并通知机器人主人;成功一次即清零
坏版本降级已上架版本编译失败时自动回退到上一个能编译的已通过版本
安装数量每台机器人默认最多 30 个插件

全局对象 ​

沙箱是干净的 vm 上下文,只有下面这些宿主导入的全局函数可用(其余全局如 process、require、Buffer、fetch 都不存在):

全局说明
setTimeout / clearTimeout单次延时,最大 30000ms(超过按 30000 计)。await new Promise(r => setTimeout(r, 500)) 可做 sleep
setInterval / clearInterval周期执行,同样上限 30000ms;插件结束时线程回收会一起清理
queueMicrotask微任务
console.log等价于 ctx.log,输出进插件日志

早期沙箱没有定时器,插件里写 setTimeout 会直接 ReferenceError: setTimeout is not defined,现在已补上。但别用长延时做业务等待:单次执行有超时(消息 30 秒 / onTimer 25 秒),超时会被强制结束线程,且未落库的状态会丢。

线程复用 ​

同一个机器人 + 同一个插件会复用执行线程:

  • 模块顶层变量在 30 分钟空闲内保留;空闲超时线程被回收,下次运行重新执行 onLoad
  • 服务重启会丢
  • 超时/错误会重建线程

因此不要用模块变量做长期存储,使用 ctx.kv。

进入沙箱之前 ​

消息先经过触发词路由:不匹配的消息不会启动你的线程。所以「插件没反应」时,先检查 triggers 是否覆盖了这条消息。

入口 ​

js
module.exports = {
  async onLoad(ctx) { /* 首次运行前 */ },
  async onMessage(ctx) { /* 消息 */ },
  async onGroupMemberAdd(ctx) { /* 新成员入群 */ },
  async onGroupJoinRequest(ctx) { /* 入群申请 */ },
  async onInteraction(ctx) { /* 按钮回调 */ },
  async onTimer(ctx) { /* 定时代码:约每 30 秒一次,没有消息上下文 */ },
};

onTimer(定时任务) ​

平台调度器约每 30 秒调用一次 onTimer,用来处理「没有人发消息时也要动」的事情,最典型的是支付状态确认:

js
module.exports = {
  async onTimer(ctx) {
    const pending = JSON.parse(ctx.kv.get('orders') || '[]')
      .filter((o) => o.status === 'pending');
    for (const o of pending.slice(0, 3)) {
      const res = await ctx.http(`https://your-relay/api/status?token=${o.token}`, {
        headers: { authorization: 'Bearer ' + ctx.settings.relay_token },
      });
      if (JSON.parse(res.text).paid) {
        await ctx.sendPrivateMarkdown(o.userId, '✅ 已支付,卡密:`' + 'XXXX' + '`');
        await ctx.sendGroupMarkdown(o.groupId, '📢 支付成功:' + o.orderNo);
      }
    }
    return false; // 定时任务不参与消息短路,返回值仅作日志
  },
};

约束:

项目说明
触发频率约 30 秒一次;同一插件上一轮没跑完时跳过本轮
单轮上限每次最多跑 20 个插件,每个插件超时 25 秒
上下文没有 msgId / userId / groupId,ctx.timer === true
可用 APIctx.kv、ctx.http、ctx.sendGroup / sendPrivate / *Media、ctx.recall*、ctx.log、ctx.getBotInfo 等主动消息接口
不可用ctx.reply*(没有消息可回)、ctx.callApi、ctx.aiChat 等依赖消息上下文的接口
权限群/私聊发送同样要过机器人权限总闸,群未开启时发送会抛错
主动消息额度走 QQ 主动消息额度(群每天 1000 条),确认收款这类低频消息没问题,不要拿它做群发

注意:定时任务和消息处理共用同一份 ctx.kv,但线程可能是新的;每轮开始前平台会用数据库里的最新 KV 重置内存快照,所以面板里改的数据下一轮就能读到。

onLoad ​

onLoad 在插件首次运行前调用一次(线程重建后会再次调用)。

适合:

  • 初始化默认配置
  • 打印版本日志
  • 读取 KV
  • 校验必要配置

不要:

  • 在 onLoad 里假设一定有消息上下文
  • 做长时间阻塞
  • 依赖 ctx.storage 等不存在的接口

返回值 ​

返回值行为
true已处理,短路后续插件/关键词/工作流/AI
其他继续后续处理

错误 ​

插件抛错不会影响主流程,但会:

  • 记录运行失败,连续 5 次会被自动停用
  • 在「我的插件 → 最近运行」显示错误
  • 用户可能收不到回复

必须自己 try/catch 并给用户提示。

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