@downcity/plugins 1.0.4

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

@@ -0,0 +1,467 @@
+/**
+ * QQGatewayClient：QQ 网关连接与发送客户端。
+ *
+ * 关键点（中文）
+ * - 这里专门负责 QQ Gateway WebSocket、心跳、自愈重连与状态持有。
+ * - 鉴权 / HTTP 探活 / 发送重试已经拆到旁路模块，当前文件只保留运行时编排。
+ * - QQBot 不再直接维护底层 ws / token 细节，只保留渠道编排职责。
+ */
+
+import WebSocket from "ws";
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { JsonObject } from "@downcity/agent/internal/types/common/Json.js";
+import type {
+  QQEventCaptureConfig,
+  QqDispatchHandler,
+  QqGatewayRuntimeStatus,
+} from "@/chat/channels/qq/types/QqChannel.js";
+import {
+  fetchQqAccessToken,
+  fetchQqGatewayUrl,
+  testQqGatewayConnection,
+} from "./QQGatewayAuth.js";
+import {
+  buildQqGatewayRuntimeStatus,
+  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 构造参数。
+ */
+export interface QQGatewayClientOptions {
+  /**
+   * 项目根目录。
+   */
+  rootPath: string;
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * QQ AppId。
+   */
+  appId: string;
+  /**
+   * QQ AppSecret。
+   */
+  appSecret: string;
+  /**
+   * 是否使用沙箱环境。
+   */
+  useSandbox: boolean;
+  /**
+   * QQ 原始事件捕获配置。
+   */
+  captureConfig: QQEventCaptureConfig;
+  /**
+   * Dispatch 事件回调。
+   */
+  onDispatch: (params: QqDispatchHandler) => Promise<void>;
+}
+
+/**
+ * QQ 网关客户端。
+ */
+export class QQGatewayClient {
+  private readonly rootPath: string;
+  private readonly logger: Logger;
+  private readonly appId: string;
+  private readonly appSecret: string;
+  private readonly useSandbox: boolean;
+  private readonly captureConfig: QQEventCaptureConfig;
+  private readonly onDispatch: (params: QqDispatchHandler) => Promise<void>;
+
+  private ws: WebSocket | null = null;
+  private isRunning = false;
+  private heartbeatInterval: NodeJS.Timeout | null = null;
+  private reconnectTimer: NodeJS.Timeout | null = null;
+  private wsContextId = "";
+  private lastSeq = 0;
+  private reconnectAttempts = 0;
+  private readonly maxReconnectAttempts = 5;
+  private heartbeatIntervalMs = 30000;
+  private lastHeartbeatSentAtMs = 0;
+  private lastHeartbeatAckAtMs = 0;
+  private pendingHeartbeatSinceMs = 0;
+  private wsReadyAtMs = 0;
+  private readonly sendRequestTimeoutMs = 15000;
+  private readonly sendMaxAttempts = 3;
+  private accessToken = "";
+  private accessTokenExpires = 0;
+
+  private readonly AUTH_API_BASE = "https://bots.qq.com";
+
+  constructor(options: QQGatewayClientOptions) {
+    this.rootPath = options.rootPath;
+    this.logger = options.logger;
+    this.appId = options.appId;
+    this.appSecret = options.appSecret;
+    this.useSandbox = options.useSandbox;
+    this.captureConfig = options.captureConfig;
+    this.onDispatch = options.onDispatch;
+  }
+
+  /**
+   * 获取当前鉴权字符串。
+   */
+  async getAuthToken(): Promise<string> {
+    const result = await fetchQqAccessToken({
+      logger: this.logger,
+      authApiBase: this.AUTH_API_BASE,
+      appId: this.appId,
+      appSecret: this.appSecret,
+      cachedAccessToken: this.accessToken,
+      cachedAccessTokenExpiresAtMs: this.accessTokenExpires,
+    });
+    this.accessToken = result.accessToken;
+    this.accessTokenExpires = result.accessTokenExpiresAtMs;
+    return `QQBot ${result.accessToken}`;
+  }
+
+  /**
+   * 获取网关状态快照。
+   */
+  getExecutorStatus(): QqGatewayRuntimeStatus {
+    const readyState = typeof this.ws?.readyState === "number" ? this.ws.readyState : null;
+    return buildQqGatewayRuntimeStatus({
+      isRunning: this.isRunning,
+      wsReadyState: readyState,
+      wsContextId: this.wsContextId,
+      wsReadyAtMs: this.wsReadyAtMs,
+      heartbeatIntervalMs: this.heartbeatIntervalMs,
+      lastHeartbeatSentAtMs: this.lastHeartbeatSentAtMs,
+      lastHeartbeatAckAtMs: this.lastHeartbeatAckAtMs,
+      pendingHeartbeatSinceMs: this.pendingHeartbeatSinceMs,
+      reconnectAttempts: this.reconnectAttempts,
+      maxReconnectAttempts: this.maxReconnectAttempts,
+      reconnectScheduled: Boolean(this.reconnectTimer),
+      useSandbox: this.useSandbox,
+      appId: this.appId,
+    });
+  }
+
+  /**
+   * 执行 QQ 连通性测试。
+   */
+  async testConnection() {
+    return testQqGatewayConnection({
+      appId: this.appId,
+      appSecret: this.appSecret,
+      useSandbox: this.useSandbox,
+      apiBase: this.getApiBase(),
+      getAuthToken: () => this.getAuthToken(),
+      getExecutorStatus: () => this.getExecutorStatus(),
+      requestReconnect: (reason, delayMs) => {
+        this.requestReconnect(reason, delayMs);
+      },
+    });
+  }
+
+  /**
+   * 启动 QQ 网关。
+   */
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      this.logger.warn("QQ Gateway 已在运行中，跳过重复启动");
+      return;
+    }
+
+    this.isRunning = true;
+    this.reconnectAttempts = 0;
+    this.clearReconnectTimer();
+    this.resetWsLivenessState();
+    const gatewayUrl = await this.getGatewayUrl();
+    await this.connectWebSocket(gatewayUrl);
+  }
+
+  /**
+   * 停止 QQ 网关。
+   */
+  async stop(): Promise<void> {
+    this.isRunning = false;
+    this.clearReconnectTimer();
+    this.stopHeartbeat();
+    this.resetWsLivenessState();
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  /**
+   * 请求一次重连。
+   */
+  requestReconnect(reason: string, delayMs?: number): void {
+    this.scheduleReconnect(reason, delayMs);
+  }
+
+  /**
+   * 发送 QQ 消息。
+   */
+  async sendMessage(
+    chatId: string,
+    chatType: string,
+    messageId: string,
+    text: string,
+    msgSeq: number = 1,
+  ): Promise<void> {
+    try {
+      await sendQqMessageWithRetry({
+        logger: this.logger,
+        apiBase: this.getApiBase(),
+        chatId,
+        chatType,
+        messageId,
+        text,
+        msgSeq,
+        maxAttempts: this.sendMaxAttempts,
+        requestTimeoutMs: this.sendRequestTimeoutMs,
+        getAuthToken: () => this.getAuthToken(),
+        clearAccessTokenCache: () => this.clearAccessTokenCache(),
+        closeSocketForRecovery: (reason) => this.closeSocketForRecovery(reason),
+        scheduleReconnect: (reason, delayMs) => this.scheduleReconnect(reason, delayMs),
+      });
+    } catch (error) {
+      this.logger.error("发送 QQ 消息失败", { error: String(error) });
+      throw error;
+    }
+  }
+
+  /**
+   * 获取 API 基础地址。
+   */
+  private getApiBase(): string {
+    return resolveQqGatewayApiBase(this.useSandbox);
+  }
+
+  /**
+   * 获取默认 WebSocket Gateway。
+   */
+  private getWsGateway(): string {
+    return resolveQqGatewayWsUrl(this.useSandbox);
+  }
+
+  /**
+   * 获取 Gateway 地址。
+   */
+  private async getGatewayUrl(): Promise<string> {
+    return fetchQqGatewayUrl({
+      logger: this.logger,
+      apiBase: this.getApiBase(),
+      authToken: await this.getAuthToken(),
+      fallbackWsGateway: this.getWsGateway(),
+    });
+  }
+
+  /**
+   * 重置网关活性状态。
+   */
+  private resetWsLivenessState(): void {
+    this.wsContextId = "";
+    this.lastSeq = 0;
+    this.wsReadyAtMs = 0;
+    this.lastHeartbeatSentAtMs = 0;
+    this.lastHeartbeatAckAtMs = 0;
+    this.pendingHeartbeatSinceMs = 0;
+  }
+
+  /**
+   * 清理 token 缓存。
+   */
+  private clearAccessTokenCache(): void {
+    this.accessToken = "";
+    this.accessTokenExpires = 0;
+  }
+
+  /**
+   * 清理重连定时器。
+   */
+  private clearReconnectTimer(): void {
+    if (!this.reconnectTimer) return;
+    clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+  }
+
+  /**
+   * 计划一次重连。
+   */
+  private scheduleReconnect(reason: string, delayMs?: number): void {
+    if (!this.isRunning) return;
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      this.logger.error("QQ 重连次数已达上限，停止自动重连", {
+        reason,
+        reconnectAttempts: this.reconnectAttempts,
+        maxReconnectAttempts: this.maxReconnectAttempts,
+      });
+      return;
+    }
+
+    const delay =
+      typeof delayMs === "number" && Number.isFinite(delayMs)
+        ? Math.max(0, Math.trunc(delayMs))
+        : 5000 * (this.reconnectAttempts + 1);
+
+    if (this.reconnectTimer) {
+      if (delay > 0) return;
+      this.clearReconnectTimer();
+    }
+
+    this.reconnectAttempts += 1;
+    const attempt = this.reconnectAttempts;
+    this.logger.info(
+      `QQ 准备重连（原因: ${reason}，第 ${attempt}/${this.maxReconnectAttempts} 次），${delay / 1000} 秒后执行`,
+    );
+
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      if (!this.isRunning) return;
+      try {
+        this.clearAccessTokenCache();
+        const newGatewayUrl = await this.getGatewayUrl();
+        await this.connectWebSocket(newGatewayUrl);
+      } catch (error) {
+        this.logger.error("QQ 重连失败", { error: String(error), reason });
+        this.scheduleReconnect("reconnect_failed");
+      }
+    }, delay);
+  }
+
+  /**
+   * 主动关闭当前 socket，交给 close 回调统一进入重连流程。
+   */
+  private closeSocketForRecovery(reason: string): void {
+    const ws = this.ws;
+    if (!ws) return;
+    if (ws.readyState !== WebSocket.OPEN && ws.readyState !== WebSocket.CONNECTING) {
+      return;
+    }
+    this.logger.warn(`触发 QQ 链路自愈关闭: ${reason}`);
+    try {
+      ws.close();
+    } catch (error) {
+      this.logger.debug("关闭 QQ WebSocket 失败（忽略）", {
+        error: String(error),
+        reason,
+      });
+    }
+  }
+
+  /**
+   * 建立 WebSocket 连接。
+   */
+  private async connectWebSocket(gatewayUrl: string): Promise<void> {
+    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;
+      },
+      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();
+          },
+          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> {
+    await sendQqGatewayIdentify({
+      socket: this.ws,
+      logger: this.logger,
+      getAuthToken: () => this.getAuthToken(),
+    });
+  }
+
+  /**
+   * 启动心跳。
+   */
+  private startHeartbeat(intervalMs: number): void {
+    this.stopHeartbeat();
+    this.heartbeatIntervalMs = normalizeQqHeartbeatIntervalMs(intervalMs);
+    this.pendingHeartbeatSinceMs = 0;
+    this.lastHeartbeatSentAtMs = 0;
+    this.sendHeartbeat();
+    this.heartbeatInterval = setInterval(() => {
+      this.sendHeartbeat();
+    }, this.heartbeatIntervalMs);
+  }
+
+  /**
+   * 发送单次心跳。
+   */
+  private sendHeartbeat(): void {
+    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),
+    });
+  }
+
+  /**
+   * 停止心跳。
+   */
+  private stopHeartbeat(): void {
+    if (!this.heartbeatInterval) return;
+    clearInterval(this.heartbeatInterval);
+    this.heartbeatInterval = null;
+  }
+}

package/src/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 "@downcity/agent/internal/utils/logger/Logger.js";
+import type {
+  QQEventCaptureConfig,
+  QQGatewayPayload,
+} from "@/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),
+    });
+  }
+}