账号状态事件

上线

{
  "type": "event",
  "data": { "post_type": "bot_online", "self_id": 123456789, "protocol_id": 0 }
}

需要 bot_online 权限。收到事件后可查询 get_bot_info获取当前资料。

下线

{
  "type": "event",
  "data": {
    "post_type": "bot_offline",
    "self_id": 123456789,
    "protocol_id": 0,
    "err_msg": "主动下线",
    "offline_reason": "active"
  }
}

需要 bot_offline 权限。offline_reason 为字符串：

值	含义
active	主动下线
cache_invalid	登录缓存失效
login_timeout	登录等待超时
kicked	被踢下线或其他设备登录
authentication_failed	认证失败
network_lost	网络连接中断

原因也可能为空；未知值应保留并按一般下线处理。err_msg 是展示文本，不是稳定的错误码，显示时按普通文本处理。

不要收到下线事件就自动重复提交密码或验证码。先检查账号状态与错误原因，再按登录流程处理。

连接状态

连接事件使用 post_type: "system_event"，需要显式订阅 system_event 权限，默认关闭。正向 WebSocket 在 auth.permissions 中订阅，反向 WebSocket 在 plugin_info.permissions 中订阅，IPC 在 runtime.events 中声明。

生命周期

sub_type: "lifecycle" 表示当前插件连接已建立。事件在认证响应或 ready 帧之后发送，每条连接首次订阅时发送一次；它不是 QQ 上线事件。

心跳

sub_type: "heartbeat" 表示当前插件连接仍在工作，每 30 秒生成一次。撤销权限后停止生成，再订阅时恢复心跳；关闭连接后停止。它与 WebSocket 协议的 Ping/Pong 控制帧不同。

字段	类型	说明
post_type	string	固定为 system_event
sub_type	string	lifecycle 或 heartbeat
time	integer	事件生成时间，Unix 秒
interval	integer	心跳间隔，秒，当前为 30
status	string	lifecycle 为 connected；heartbeat 为 alive

此类事件只发给对应连接，不包含 self_id 或 protocol_id，也不代表某个 QQ 在线。网络中断时无法保证收到断线通知，应结合连接关闭和心跳超时处理。