事件总线
ctx.handle() 背后是 EventBus,它是框架内部唯一的事件分发器。插件一般不会直接使用它,ctx.buses 可以拿到,但很少需要。理解它的匹配规则之后,就能解释很多关于 handler 为什么收到事件的问题。
分发流程
一个事件被 bus.dispatch(event) 派发后,总线执行三件事。
- 过滤:
setFilter钩子按注册源决定是否让监听器看到该事件。 - 匹配:遍历所有已注册的监听器,找出路由与事件匹配的部分。
- 分组与顺序执行:按优先级分组,数值小的先执行;组内按注册顺序逐个执行。handler 返回
true即认领并结束派发,返回undefined/false则继续下一个。dispatch返回是否有人认领。
const matched = this.#matching(event);
for (const [priority, regs] of sortedByPriority(matched)) {
for (const reg of byOrder(regs)) {
if ((await reg.handler(event)) === true) return true; // 认领,截止
}
}
return false; // 无人认领匹配规则
监听器注册的路由 pattern 与事件携带的路由列表 event.routes 做匹配,命中任意一条即可。
精确匹配:pattern 与 route 完全相等。
通配符:* 单独使用表示匹配全部。以 *. 结尾的 pattern,例如 message.*,匹配 message 本身和它下面所有子路由。
| pattern | 能匹配到的事件路由 |
|---|---|
message | message |
message.* | message、message.group、message.group.poke 等所有以 message 开头的路由 |
* | 一切 |
onebotv11:message.group | 恰好是 onebotv11:message.group |
事件携带的路由列表由适配器构造事件时生成,生成函数是 buildRoutes。一条 onebotv11 群消息带 5 条路由,顺序是从最细到最粗,因此监听 message 也能收到它。粗路由能接收到所有平台的事件,原理就在这里。
优先级与顺序
监听器的执行顺序由两个数字决定。
- priority:可以在
ctx.handle的 options 中传入,插件默认使用definePlugin的priority,默认值是 100。core 插件是-Infinity,因此总是最先执行。数值小的先执行。 - order:注册序号,同优先级内按注册先后排列。
监听器逐个执行,handler 的返回值决定要不要继续。
| 返回值 | 含义 |
|---|---|
undefined | 不认领,继续下一个 |
false | 不认领,与 undefined 同义,用于显式表达 |
true | 认领,结束整个派发 |
命令阶段总是先于总线,命令 priority 与监听器 priority 互不影响。命令 handler 返回 false 表示不认领,消息会继续流向总线。
注册源过滤
总线支持通过 setFilter 注入全局过滤钩子。命令管理器使用这个机制按插件来源判定事件是否对该插件可见。
bus.setFilter((registration, event) => {
// 返回 false 即跳过该监听器
return commands.shouldDispatch(registration.source, event);
});shouldDispatch 的行为如下。
- 让主人、管理员、群主和群管理员的事件默认放行。
- 检查旧插件的
mioku.accessHooks钩子,或ctx.command()注册的命令是否命中。 - 命中后查询
config/core/access-control.json中的规则。
这意味着即使一个插件注册了 ctx.handle("message"),访问控制系统仍然可以按消息内容或事件路由拦截它。详细规则见权限与访问控制。
监听器生命周期
bus.register(route, handler, options) 返回取消函数。ctx.handle 内部就是这样注册的,并把取消函数存入上下文的清理列表。插件卸载时所有监听会自动移除。
const off = bus.register("message", handler, {
source: "plugin:my-plugin", // 出错日志中会带这个标识
priority: 10,
});
off(); // 取消注册事件去重
ctx.handle 除了使用 WeakSet 防止同一个事件对象重复执行,还会跳过被核心关联器标记为跨 bot 或跨适配器重复的投递。适配器只负责无损投递并填好 identity,去重策略完全由核心持有。需要逐条处理时,可以用 ctx.handle("!message", handler) 绕过过滤,并用 ctx.botsForEvent(event) 拿到全部参与方。完整规则见消息与事件去重。
