@downcity/agent 1.1.23 → 1.1.32

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

@@ -1,467 +0,0 @@
-/**
- * QQGatewayClient：QQ 网关连接与发送客户端。
- *
- * 关键点（中文）
- * - 这里专门负责 QQ Gateway WebSocket、心跳、自愈重连与状态持有。
- * - 鉴权 / HTTP 探活 / 发送重试已经拆到旁路模块，当前文件只保留运行时编排。
- * - QQBot 不再直接维护底层 ws / token 细节，只保留渠道编排职责。
- */
-
-import WebSocket from "ws";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { JsonObject } from "@/types/common/Json.js";
-import type {
-  QQEventCaptureConfig,
-  QqDispatchHandler,
-  QqGatewayRuntimeStatus,
-} from "@/service/builtins/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/service/builtins/chat/channels/qq/QQGatewayConnection.ts

@@ -1,175 +0,0 @@
-/**
- * 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),
-    });
-  }
-}