@downcity/agent 1.1.10 → 1.1.11

package/src/service/builtins/chat/channels/qq/QQGatewayClient.ts

@@ -7,17 +7,14 @@
  * - QQBot 不再直接维护底层 ws / token 细节，只保留渠道编排职责。
  */
 
-import WebSocket, { type RawData } from "ws";
+import WebSocket from "ws";
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type {
   QQEventCaptureConfig,
-  QQGatewayPayload,
   QqDispatchHandler,
   QqGatewayRuntimeStatus,
 } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
-import { EventType, OpCode } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
-import { captureQqWsPayload } from "./QQEventCapture.js";
 import {
   fetchQqAccessToken,
   fetchQqGatewayUrl,
@@ -25,14 +22,19 @@ import {
 } from "./QQGatewayAuth.js";
 import {
   buildQqGatewayRuntimeStatus,
-  getQqHeartbeatAckTimeoutMs,
-  hasQqHealthyHeartbeat,
-  hasQqHeartbeatTimeout,
-  parseQqGatewayPayload,
   resolveQqGatewayApiBase,
   resolveQqGatewayWsUrl,
 } from "./QQGatewaySupport.js";
 import { sendQqMessageWithRetry } from "./QQGatewaySend.js";
+import { connectQqGatewayWebSocket } from "./QQGatewayConnection.js";
+import {
+  handleQqGatewayPayload,
+  sendQqGatewayIdentify,
+} from "./QQGatewayProtocol.js";
+import {
+  normalizeQqHeartbeatIntervalMs,
+  sendQqGatewayHeartbeat,
+} from "./QQGatewayHeartbeat.js";
 
 /**
  * QQGatewayClient 构造参数。
@@ -263,41 +265,6 @@ export class QQGatewayClient {
     });
   }
 
-  /**
-   * 计算心跳 ACK 超时阈值。
-   */
-  private getHeartbeatAckTimeoutMs(): number {
-    return getQqHeartbeatAckTimeoutMs(this.heartbeatIntervalMs);
-  }
-
-  /**
-   * 是否发生心跳 ACK 超时。
-   */
-  private hasHeartbeatTimeout(nowMs: number = Date.now()): boolean {
-    return hasQqHeartbeatTimeout(
-      {
-        heartbeatIntervalMs: this.heartbeatIntervalMs,
-        pendingHeartbeatSinceMs: this.pendingHeartbeatSinceMs,
-        wsReadyAtMs: this.wsReadyAtMs,
-      },
-      nowMs,
-    );
-  }
-
-  /**
-   * 心跳是否健康。
-   */
-  private hasHealthyHeartbeat(nowMs: number = Date.now()): boolean {
-    return hasQqHealthyHeartbeat(
-      {
-        heartbeatIntervalMs: this.heartbeatIntervalMs,
-        pendingHeartbeatSinceMs: this.pendingHeartbeatSinceMs,
-        wsReadyAtMs: this.wsReadyAtMs,
-      },
-      nowMs,
-    );
-  }
-
   /**
    * 重置网关活性状态。
    */
@@ -395,189 +362,63 @@ export class QQGatewayClient {
    * 建立 WebSocket 连接。
    */
   private async connectWebSocket(gatewayUrl: string): Promise<void> {
-    this.logger.info(`正在连接 WebSocket: ${gatewayUrl}`);
-    const previousWs = this.ws;
-    if (
-      previousWs &&
-      (previousWs.readyState === WebSocket.OPEN ||
-        previousWs.readyState === WebSocket.CONNECTING)
-    ) {
-      try {
-        previousWs.close();
-      } catch {
-        // ignore close failure
-      }
-    }
-    this.stopHeartbeat();
-    this.resetWsLivenessState();
-
-    return new Promise((resolve, reject) => {
-      let settled = false;
-      const resolveOnce = () => {
-        if (settled) return;
-        settled = true;
-        resolve();
-      };
-      const rejectOnce = (error: Error) => {
-        if (settled) return;
-        settled = true;
-        reject(error);
-      };
-
-      const ws = new WebSocket(gatewayUrl);
-      this.ws = ws;
-
-      ws.on("open", () => {
-        if (this.ws !== ws) return;
-        this.logger.info("WebSocket 连接已建立");
+    await connectQqGatewayWebSocket({
+      gatewayUrl,
+      logger: this.logger,
+      captureConfig: this.captureConfig,
+      getCurrentSocket: () => this.ws,
+      setCurrentSocket: (ws) => {
+        this.ws = ws;
+      },
+      resetLivenessState: () => this.resetWsLivenessState(),
+      stopHeartbeat: () => this.stopHeartbeat(),
+      clearReconnectTimer: () => this.clearReconnectTimer(),
+      resetReconnectAttempts: () => {
         this.reconnectAttempts = 0;
-        this.clearReconnectTimer();
-        this.resetWsLivenessState();
-        resolveOnce();
-      });
-
-      ws.on("message", async (data: RawData) => {
-        if (this.ws !== ws) return;
-        try {
-          const payload = this.parseGatewayPayload(data);
-          if (!payload) {
-            this.logger.warn("收到无法解析的 QQ WebSocket 消息，已忽略");
-            return;
-          }
-          this.logger.debug(
-            `收到 WebSocket 消息: op=${payload.op}, t=${payload.t || "N/A"}`,
-          );
-          await captureQqWsPayload({
-            config: this.captureConfig,
-            logger: this.logger,
-            payload,
-          });
-          await this.handleWebSocketMessage(payload);
-        } catch (error) {
-          this.logger.error("处理 WebSocket 消息失败", {
-            error: String(error),
-          });
-        }
-      });
-
-      ws.on("close", (code: number, reason: Buffer) => {
-        if (this.ws !== ws) return;
-        const reasonText = Buffer.isBuffer(reason)
-          ? reason.toString("utf-8")
-          : String(reason || "");
-        this.logger.warn(`WebSocket 连接关闭: ${code} - ${reasonText}`);
-        this.ws = null;
-        this.stopHeartbeat();
-        this.resetWsLivenessState();
-        this.scheduleReconnect(`ws_closed:${code}`);
-        rejectOnce(
-          new Error(`QQ websocket closed before ready: ${code} ${reasonText}`),
-        );
-      });
-
-      ws.on("error", (error: Error) => {
-        if (this.ws !== ws) return;
-        this.logger.error("WebSocket 错误", { error: String(error) });
-        rejectOnce(error);
-      });
-    });
-  }
-
-  /**
-   * 解析原始 Gateway 载荷。
-   */
-  private parseGatewayPayload(rawData: RawData): QQGatewayPayload | null {
-    return parseQqGatewayPayload(rawData);
-  }
-
-  /**
-   * 处理网关消息。
-   */
-  private async handleWebSocketMessage(payload: QQGatewayPayload): Promise<void> {
-    const { op, d, s, t } = payload;
-    if (s) {
-      this.lastSeq = s;
-    }
-
-    switch (op) {
-      case OpCode.Hello: {
-        const heartbeatIntervalMs =
-          typeof d?.heartbeat_interval === "number" ? d.heartbeat_interval : 30000;
-        this.startHeartbeat(heartbeatIntervalMs);
-        await this.sendIdentify();
-        break;
-      }
-      case OpCode.Dispatch: {
-        const eventType = String(t || "");
-        if (eventType === EventType.READY) {
-          this.wsContextId = typeof d?.context_id === "string" ? d.context_id : "";
-          this.wsReadyAtMs = Date.now();
-        } else if (eventType === EventType.RESUMED) {
-          this.wsReadyAtMs = Date.now();
-        }
-        await this.onDispatch({
-          eventType,
-          data: d || {},
-        });
-        break;
-      }
-      case OpCode.HeartbeatAck:
-        this.lastHeartbeatAckAtMs = Date.now();
-        this.pendingHeartbeatSinceMs = 0;
-        this.logger.debug("收到心跳响应");
-        break;
-      case OpCode.Reconnect:
-        this.logger.warn("服务端要求重连");
-        this.closeSocketForRecovery("server_reconnect_opcode");
-        break;
-      case OpCode.InvalidContext:
-        this.logger.error("无效的 Context，需要重新鉴权");
-        this.clearAccessTokenCache();
-        setTimeout(async () => {
-          try {
+      },
+      scheduleReconnect: (reason, delayMs) =>
+        this.scheduleReconnect(reason, delayMs),
+      handlePayload: async (payload) => {
+        await handleQqGatewayPayload({
+          logger: this.logger,
+          payload,
+          setLastSeq: (seq) => {
+            this.lastSeq = seq;
+          },
+          startHeartbeat: (intervalMs) => this.startHeartbeat(intervalMs),
+          sendIdentify: async () => {
             await this.sendIdentify();
-          } catch (error) {
-            this.logger.error("重新鉴权失败", { error: String(error) });
-          }
-        }, 2000);
-        break;
-    }
+          },
+          markReady: (contextId) => {
+            this.wsContextId = contextId;
+            this.wsReadyAtMs = Date.now();
+          },
+          markResumed: () => {
+            this.wsReadyAtMs = Date.now();
+          },
+          markHeartbeatAck: () => {
+            this.lastHeartbeatAckAtMs = Date.now();
+            this.pendingHeartbeatSinceMs = 0;
+          },
+          clearAccessTokenCache: () => this.clearAccessTokenCache(),
+          closeSocketForRecovery: (reason) => this.closeSocketForRecovery(reason),
+          onDispatch: async (dispatch) => {
+            await this.onDispatch(dispatch);
+          },
+        });
+      },
+    });
   }
 
   /**
    * 发送鉴权请求。
    */
   private async sendIdentify(): Promise<void> {
-    const authToken = await this.getAuthToken();
-    const intents = this.getIntents();
-    this.logger.info(`发送鉴权请求 (Identify)，intents: ${intents}`);
-
-    const identifyPayload = {
-      op: OpCode.Identify,
-      d: {
-        token: authToken,
-        intents,
-        shard: [0, 1],
-        properties: {
-          $os: "linux",
-          $browser: "downcity",
-          $device: "downcity",
-        },
-      },
-    };
-
-    this.logger.debug(`Identify payload: ${JSON.stringify(identifyPayload)}`);
-    this.ws?.send(JSON.stringify(identifyPayload));
-    this.logger.info("已发送鉴权请求");
-  }
-
-  /**
-   * 获取订阅事件位掩码。
-   */
-  private getIntents(): number {
-    const GROUP_AND_C2C_EVENT = 1 << 25;
-    const AUDIO_ACTION = 1 << 29;
-    return GROUP_AND_C2C_EVENT | AUDIO_ACTION;
+    await sendQqGatewayIdentify({
+      socket: this.ws,
+      logger: this.logger,
+      getAuthToken: () => this.getAuthToken(),
+    });
   }
 
   /**
@@ -585,8 +426,7 @@ export class QQGatewayClient {
    */
   private startHeartbeat(intervalMs: number): void {
     this.stopHeartbeat();
-    this.heartbeatIntervalMs =
-      Number.isFinite(intervalMs) && intervalMs > 0 ? Math.trunc(intervalMs) : 30000;
+    this.heartbeatIntervalMs = normalizeQqHeartbeatIntervalMs(intervalMs);
     this.pendingHeartbeatSinceMs = 0;
     this.lastHeartbeatSentAtMs = 0;
     this.sendHeartbeat();
@@ -599,35 +439,21 @@ export class QQGatewayClient {
    * 发送单次心跳。
    */
   private sendHeartbeat(): void {
-    const ws = this.ws;
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    const now = Date.now();
-    if (this.hasHeartbeatTimeout(now)) {
-      this.logger.warn("QQ 心跳 ACK 超时，准备重连", {
-        pendingHeartbeatSinceMs: this.pendingHeartbeatSinceMs,
-        heartbeatAckTimeoutMs: this.getHeartbeatAckTimeoutMs(),
-      });
-      this.closeSocketForRecovery("heartbeat_ack_timeout");
-      return;
-    }
-
-    const heartbeatPayload = {
-      op: OpCode.Heartbeat,
-      d: this.lastSeq || null,
-    };
-    try {
-      ws.send(JSON.stringify(heartbeatPayload));
-      this.lastHeartbeatSentAtMs = now;
-      if (!this.pendingHeartbeatSinceMs) {
-        this.pendingHeartbeatSinceMs = now;
-      }
-      this.logger.debug("发送心跳");
-    } catch (error) {
-      this.logger.warn("发送 QQ 心跳失败，准备重连", {
-        error: String(error),
-      });
-      this.closeSocketForRecovery("heartbeat_send_failed");
-    }
+    sendQqGatewayHeartbeat({
+      socket: this.ws,
+      logger: this.logger,
+      lastSeq: this.lastSeq,
+      heartbeatIntervalMs: this.heartbeatIntervalMs,
+      wsReadyAtMs: this.wsReadyAtMs,
+      pendingHeartbeatSinceMs: this.pendingHeartbeatSinceMs,
+      markHeartbeatSent: (nowMs) => {
+        this.lastHeartbeatSentAtMs = nowMs;
+      },
+      markPendingHeartbeat: (nowMs) => {
+        this.pendingHeartbeatSinceMs = nowMs;
+      },
+      closeSocketForRecovery: (reason) => this.closeSocketForRecovery(reason),
+    });
   }
 
   /**

package/src/service/builtins/chat/channels/qq/QQGatewayConnection.ts

@@ -0,0 +1,175 @@
+/**
+ * QQ Gateway WebSocket 连接事件绑定。
+ *
+ * 关键点（中文）
+ * - 只负责创建 WebSocket、绑定 open/message/close/error 事件。
+ * - runtime 状态仍由 `QQGatewayClient` 持有，避免连接 helper 变成第二个状态源。
+ * - message 解析与原始事件捕获在这里完成，业务 payload 交回 client 编排。
+ */
+
+import WebSocket, { type RawData } from "ws";
+import type { Logger } from "@/utils/logger/Logger.js";
+import type {
+  QQEventCaptureConfig,
+  QQGatewayPayload,
+} from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
+import { captureQqWsPayload } from "./QQEventCapture.js";
+import { parseQqGatewayPayload } from "./QQGatewaySupport.js";
+
+/**
+ * QQ Gateway WebSocket 连接参数。
+ */
+export interface ConnectQqGatewayWebSocketParams {
+  /**
+   * Gateway WebSocket URL。
+   */
+  gatewayUrl: string;
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * 原始事件捕获配置。
+   */
+  captureConfig: QQEventCaptureConfig;
+  /**
+   * 当前 WebSocket。
+   */
+  getCurrentSocket(): WebSocket | null;
+  /**
+   * 更新当前 WebSocket。
+   */
+  setCurrentSocket(ws: WebSocket | null): void;
+  /**
+   * 重置连接活性状态。
+   */
+  resetLivenessState(): void;
+  /**
+   * 停止心跳。
+   */
+  stopHeartbeat(): void;
+  /**
+   * 清理重连 timer。
+   */
+  clearReconnectTimer(): void;
+  /**
+   * 重置重连次数。
+   */
+  resetReconnectAttempts(): void;
+  /**
+   * 计划重连。
+   */
+  scheduleReconnect(reason: string, delayMs?: number): void;
+  /**
+   * 处理已解析的 Gateway payload。
+   */
+  handlePayload(payload: QQGatewayPayload): Promise<void>;
+}
+
+/**
+ * 建立 QQ Gateway WebSocket。
+ */
+export async function connectQqGatewayWebSocket(
+  params: ConnectQqGatewayWebSocketParams,
+): Promise<void> {
+  params.logger.info(`正在连接 WebSocket: ${params.gatewayUrl}`);
+  closePreviousSocket(params.getCurrentSocket());
+  params.stopHeartbeat();
+  params.resetLivenessState();
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const resolveOnce = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    const rejectOnce = (error: Error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+
+    const ws = new WebSocket(params.gatewayUrl);
+    params.setCurrentSocket(ws);
+
+    ws.on("open", () => {
+      if (params.getCurrentSocket() !== ws) return;
+      params.logger.info("WebSocket 连接已建立");
+      params.resetReconnectAttempts();
+      params.clearReconnectTimer();
+      params.resetLivenessState();
+      resolveOnce();
+    });
+
+    ws.on("message", async (data: RawData) => {
+      if (params.getCurrentSocket() !== ws) return;
+      await handleSocketMessage(params, data);
+    });
+
+    ws.on("close", (code: number, reason: Buffer) => {
+      if (params.getCurrentSocket() !== ws) return;
+      const reasonText = Buffer.isBuffer(reason)
+        ? reason.toString("utf-8")
+        : String(reason || "");
+      params.logger.warn(`WebSocket 连接关闭: ${code} - ${reasonText}`);
+      params.setCurrentSocket(null);
+      params.stopHeartbeat();
+      params.resetLivenessState();
+      params.scheduleReconnect(`ws_closed:${code}`);
+      rejectOnce(new Error(`QQ websocket closed before ready: ${code} ${reasonText}`));
+    });
+
+    ws.on("error", (error: Error) => {
+      if (params.getCurrentSocket() !== ws) return;
+      params.logger.error("WebSocket 错误", { error: String(error) });
+      rejectOnce(error);
+    });
+  });
+}
+
+/**
+ * 关闭旧 socket。
+ */
+function closePreviousSocket(previousWs: WebSocket | null): void {
+  if (
+    previousWs &&
+    (previousWs.readyState === WebSocket.OPEN ||
+      previousWs.readyState === WebSocket.CONNECTING)
+  ) {
+    try {
+      previousWs.close();
+    } catch {
+      // 关键点（中文）：旧连接关闭失败不影响新连接建立。
+    }
+  }
+}
+
+/**
+ * 解析、捕获并分发一条 socket message。
+ */
+async function handleSocketMessage(
+  params: ConnectQqGatewayWebSocketParams,
+  data: RawData,
+): Promise<void> {
+  try {
+    const payload = parseQqGatewayPayload(data);
+    if (!payload) {
+      params.logger.warn("收到无法解析的 QQ WebSocket 消息，已忽略");
+      return;
+    }
+    params.logger.debug(
+      `收到 WebSocket 消息: op=${payload.op}, t=${payload.t || "N/A"}`,
+    );
+    await captureQqWsPayload({
+      config: params.captureConfig,
+      logger: params.logger,
+      payload,
+    });
+    await params.handlePayload(payload);
+  } catch (error) {
+    params.logger.error("处理 WebSocket 消息失败", {
+      error: String(error),
+    });
+  }
+}

package/src/service/builtins/chat/channels/qq/QQGatewayHeartbeat.ts

@@ -0,0 +1,114 @@
+/**
+ * QQ Gateway 心跳发送辅助。
+ *
+ * 关键点（中文）
+ * - 只负责心跳 interval 归一化与单次 heartbeat payload 发送。
+ * - 心跳状态仍由 `QQGatewayClient` 持有，避免 helper 内部隐藏状态。
+ */
+
+import WebSocket from "ws";
+import type { Logger } from "@/utils/logger/Logger.js";
+import { OpCode } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
+import {
+  getQqHeartbeatAckTimeoutMs,
+  hasQqHeartbeatTimeout,
+} from "./QQGatewaySupport.js";
+
+/**
+ * QQ Gateway heartbeat 发送参数。
+ */
+export interface SendQqGatewayHeartbeatParams {
+  /**
+   * 当前 socket。
+   */
+  socket: WebSocket | null;
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * 最近一次服务端序列号。
+   */
+  lastSeq: number;
+  /**
+   * 心跳间隔。
+   */
+  heartbeatIntervalMs: number;
+  /**
+   * WebSocket READY 时间。
+   */
+  wsReadyAtMs: number;
+  /**
+   * 待 ACK 心跳开始时间。
+   */
+  pendingHeartbeatSinceMs: number;
+  /**
+   * 标记心跳发送成功。
+   */
+  markHeartbeatSent(nowMs: number): void;
+  /**
+   * 标记待 ACK 心跳开始时间。
+   */
+  markPendingHeartbeat(nowMs: number): void;
+  /**
+   * 触发 socket 自愈关闭。
+   */
+  closeSocketForRecovery(reason: string): void;
+}
+
+/**
+ * 归一化心跳间隔。
+ */
+export function normalizeQqHeartbeatIntervalMs(intervalMs: number): number {
+  return Number.isFinite(intervalMs) && intervalMs > 0
+    ? Math.trunc(intervalMs)
+    : 30000;
+}
+
+/**
+ * 发送单次 QQ Gateway heartbeat。
+ */
+export function sendQqGatewayHeartbeat(
+  params: SendQqGatewayHeartbeatParams,
+): void {
+  const ws = params.socket;
+  if (!ws || ws.readyState !== WebSocket.OPEN) return;
+  const now = Date.now();
+  if (
+    hasQqHeartbeatTimeout(
+      {
+        heartbeatIntervalMs: params.heartbeatIntervalMs,
+        pendingHeartbeatSinceMs: params.pendingHeartbeatSinceMs,
+        wsReadyAtMs: params.wsReadyAtMs,
+      },
+      now,
+    )
+  ) {
+    params.logger.warn("QQ 心跳 ACK 超时，准备重连", {
+      pendingHeartbeatSinceMs: params.pendingHeartbeatSinceMs,
+      heartbeatAckTimeoutMs: getQqHeartbeatAckTimeoutMs(
+        params.heartbeatIntervalMs,
+      ),
+    });
+    params.closeSocketForRecovery("heartbeat_ack_timeout");
+    return;
+  }
+
+  const heartbeatPayload = {
+    op: OpCode.Heartbeat,
+    d: params.lastSeq || null,
+  };
+  try {
+    ws.send(JSON.stringify(heartbeatPayload));
+    params.markHeartbeatSent(now);
+    if (!params.pendingHeartbeatSinceMs) {
+      params.markPendingHeartbeat(now);
+    }
+    params.logger.debug("发送心跳");
+  } catch (error) {
+    params.logger.warn("发送 QQ 心跳失败，准备重连", {
+      error: String(error),
+    });
+    params.closeSocketForRecovery("heartbeat_send_failed");
+  }
+}