架构总览

分层结构

      平台 (QQ / OneBot / 终端)
              ↓
   ┌─────────────────────────┐
   │  适配器 Adapter          │  mioku-adapter-*，对接平台
   │  ├─ 收：事件 → Event     │
   │  └─ 发：能力 → 平台指令   │
   └─────────────────────────┘
              ↓
   ┌─────────────────────────┐
   │  命令管理器              │  匹配、前缀、权限、优先级、帮助目录
   └─────────────────────────┘
              ↓
   ┌─────────────────────────┐
   │  事件总线 EventBus       │  按路由分发剩余事件
   └─────────────────────────┘
              ↓
   ┌─────────────────────────┐
   │  插件 Plugin             │  业务逻辑：ctx.command / ctx.handle
   │  服务 Service            │  公共能力提供方，插件取用
   └─────────────────────────┘

从上往下读：适配器把平台消息变成统一事件，命令管理器先处理已注册的消息命令并消费它们，剩余事件再交给事件总线按路由分发给插件。插件处理完调用能力（能力又由适配器翻译回平台指令）。服务不在这个链路上，它是插件之间共享的"工具箱"。

命令管理器直接消费消息（命中后不再进入总线），因此插件不需要为同一条消息重复处理前缀和权限。戳一戳、加好友请求、bot 生命周期等非命令事件绕过命令管理器直接进入总线。

启动流程

框架启动时按这个顺序干活：

1. 发现服务 —— 扫描项目 services/ 目录和 mioku-service-* 依赖，加载全部服务
2. 加载内置 core 插件 —— 注册系统命令、访问控制、状态收集
3. 加载用户插件 —— 先解析 mioku.plugins 列表，按 priority 分组加载（数值小先加载，同组并行）；每个插件的 setup 阶段调用 ctx.command() 注册消息命令
4. 启动适配器 —— 读取 mioku.adapters 配置，逐个 create 并 start，注册 bot 与能力
5. 就绪 —— 派发 runtime:ready 事件，向主人推送上线通知（如果开了 online_push）

顺序不是随意的：插件先于适配器加载，意味着插件 setup 时可能还没有 bot 连接——所以依赖 bot 的初始化逻辑（比如给每个 bot 发个欢迎语）要放在事件监听里而不是 setup 里。

四个包类型

包前缀	是什么	谁写
mioku-plugin-*	插件的功能实现	大多数开发者
mioku-service-*	跨插件复用的能力提供方	需要共享能力的开发者
mioku-adapter-*	对接平台的连接层	想做新平台的开发者
mioku	框架本体	仓库维护者

类型参考

所有公共类型都能在类型参考里查到，由源码生成。