运行时与生命周期
执行环境
| 项目 | 当前值 |
|---|---|
| 运行时 | 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 秒 /onTimer25 秒),超时会被强制结束线程,且未落库的状态会丢。
线程复用
同一个机器人 + 同一个插件会复用执行线程:
- 模块顶层变量在 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 |
| 可用 API | ctx.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 并给用户提示。
