一次 QQBot “灵魂不在线”问题排查记录

最近在使用 Hermes Agent 接入 QQBot 时遇到了一个比较典型的痛点Hermes 本体看起来是正常的。gateway 进程也没有直接挂掉，但 QQ 端机器人运行一段时间后就会突然无法响应，表现为“灵魂不在线”。

一开始这个问题很容易被误判成网络波动，或者 QQ 网站偶发不稳定。但继续看日志后发现，问题并不是简单的进程异常。而是 QQBot 的 WebSocket 长连接进入了一种“进程还活着，但网站链路不健康”的状态。

. 现象：Hermes 正常。但 QQBot 不响应

从服务状态看，Hermes gateway 仍然在运行，微信 bot 也没有出现一样的问题。可以先排除 Hermes 主体、模型服务、服务器整体资源这类公共依赖问题。

但 QQBot 日志里反复出现类似内容：

-- ::,WARNING gateway.platforms.qqbot.adapter: WebSocket error: WebSocket closed
-- ::,INFO gateway.platforms.qqbot.adapter: Reconnecting in 2s ...
-- ::,INFO gateway.platforms.qqbot.adapter: WebSocket connected to wss://api.sgroup.qq.com/websocket
-- ::,INFO gateway.platforms.qqbot.adapter: Reconnected
-- ::,INFO gateway.platforms.qqbot.adapter: Resume sent
-- ::,INFO gateway.platforms.qqbot.adapter: Session resumed
-- ::,WARNING gateway.platforms.qqbot.adapter: WebSocket error: WebSocket closed

更关键的是异常后期不是偶发断线。而是进入了一个比较固定的循环：

-- ::,WARNING gateway.platforms.qqbot.adapter: WebSocket error: WebSocket closed
-- ::,INFO gateway.platforms.qqbot.adapter: Reconnecting in 2s ...
-- ::,INFO gateway.platforms.qqbot.adapter: WebSocket connected to wss://api.sgroup.qq.com/websocket
-- ::,INFO gateway.platforms.qqbot.adapter: Reconnected
-- ::,INFO gateway.platforms.qqbot.adapter: Resume sent
-- ::,INFO gateway.platforms.qqbot.adapter: Session resumed
-- ::,WARNING gateway.platforms.qqbot.adapter: WebSocket error: WebSocket closed
...

说白了QQBot 并不是完全连不上，而是每次看起来恢复了随后又很快断开。

. 关键判断：Session resumed 不等于链路恢复

在源码逻辑中，当 WebSocket 收到 Hello 事件后adapter 会根据当前是否保存了 session_id 和 seq 来决定发送 Identify 还是 Resume。Resume 成功后QQ Gateway 会下发 RESUMED 事件，adapter 记录 Session resumed 日志。

但这里的主要是：Session resumed只说明服务端接受了这次 Resume，并不代表后续 heartbeat 任务一定还在正常运行。真正维持长连接的是 _heartbeat_loop。如果在前面的 session timeout 或 WebSocket 断开过程中，adapter 的状态变量处理不当，导致 heartbeat loop 退出。那么后续即使 _listen_loop 重新打开了 WebSocket，而且 Resume 成功，新连接也可能没有持续发送 heartbeat。

• ① Heartbeat task 只在初始连接时创建一次

  
  adapter.py L299: self._listen_task = asyncio.create_task)
  adapter.py L300: self._heartbeat_task = asyncio.create_task)
  # _heartbeat_reconnect里不会重建 heartbeat task。

• ② _mark_disconnected 把 _running 置为 False

  
  base.py L1309: def _mark_disconnected:
  base.py L1310: self._running = False ← 这是问题根源
  

• ③ WebSocket 断开时_listen_loop 调用 _mark_disconnected

  
  adapter.py L592: logger.warning
  adapter.py L593: self._mark_disconnected ← _running = False
  adapter.py L600: if await self._reconnect:
  

• ④ ) 恢复 。但中间存在 race window

  
  adapter.py L621: await self._open_ws
  adapter.py L622: self._mark_connected ← _running = True
  

• ⑤ Heartbeat loop 的唯一退出条件就是 while self._running:

  
  adapter.py L655: while self._running:
  # 此时 _running = False 就永久退出 loop
  adapter.py L656: await asyncio.sleep
  adapter.py L661: await self._ws.send_json
  

这次问题不能简单理解为“Resume 失败”，而是“Resume 表面成功，但恢复后的连接没有被 heartbeat 稳定保活”。这是 ) 和 )

. 为什么微信 bot 没有一样的问题