水缸机器人

Appearance

WebSocket 接入（网关长连接） ​

bot.mode: websocket（默认）时，Bngeuit 主动连接 QQ 开放平台网关，由网关推送事件（DISPATCH）。连接、鉴权、心跳、断线重连全部由框架自动处理，插件无需感知连接细节。

工作方式 ​

  • 连接：启动时从 GET /gateway/bot 获取网关地址与分片配置，建立长连接并完成鉴权
  • 心跳：按网关下发的间隔自动发送心跳包维持连接
  • 事件：网关 DISPATCH 事件经框架分发到 EventBus，插件照常用 @SubscribeEvent 监听
  • 就绪：鉴权成功收到网关 READY 事件 → 触发 ReadyEvent（每分片各一次）；全部分片就绪后触发插件的 onActive() 生命周期

断线重连（自动，无需干预） ​

  • 连接断开后框架自动重新入队重连，插件无感知
  • 可恢复时会话续传（RESUME）：携带上次消息序列号补拉断线期间的事件，消息不丢失
  • 鉴权失败（如 Token 失效）时自动重置 Token 后重连
  • 断线后按间隔重试，避免重连风暴

多分片 ​

网关可能要求一个机器人维护多条连接分担事件流量（分片）。框架按网关返回的 shards 自动创建全部分片连接并统一调度，单个分片断线只影响该分片、自动恢复——插件层面无任何区别，事件照常收到。

与 Webhook 模式的差异 ​

连接方向、分片、重连机制、就绪事件、接入鉴权均不同，但事件分发到插件的方式完全相同（同一 ConnectionState → EventBus）。对比表见 Webhook 模式。

就绪信号（ReadyEvent / onActive） ​

每个分片连接鉴权成功后，网关推送 READY 事件，框架分发 ReadyEvent（WebSocket 网关专属，每分片各触发一次，多分片时用 getShardId() 区分来源）。

  • 事件形式：ReadyEvent（event/receive/），事件监听器 / 脚本可用 @SubscribeEvent / bngeuit.on('ReadyEvent', ...) 监听
  • 插件推荐方式：实现 Plugin.onActive() —— 该生命周期在两种接入模式统一触发一次（WS 全部分片就绪 / Webhook 回调服务就绪），做「机器人已上线」初始化无需关心接入方式和分片
java
// 方式一：监听事件（每分片各触发一次，多分片时注意防重）
@SubscribeEvent
public void onReady(ReadyEvent e) {
    log.info("分片 {} 已就绪", e.getShardId());
}

// 方式二（推荐）：插件生命周期（两模式统一，全局只触发一次）
@Override
public void onActive() {
    startScheduledTasks(); // 启动定时推送等
}

ReadyEvent vs onActive

ReadyEvent 是 WebSocket 网关每分片触发的事件，Webhook 模式不触发（对应的是 WebhookReadyEvent）。Plugin.onActive() 在两种模式下统一触发一次，做上线初始化优先用 onActive()。