@downcity/plugins 1.0.4

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

@@ -0,0 +1,114 @@
+/**
+ * QQ Gateway 心跳发送辅助。
+ *
+ * 关键点（中文）
+ * - 只负责心跳 interval 归一化与单次 heartbeat payload 发送。
+ * - 心跳状态仍由 `QQGatewayClient` 持有，避免 helper 内部隐藏状态。
+ */
+
+import WebSocket from "ws";
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import { OpCode } from "@/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");
+  }
+}

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

@@ -0,0 +1,176 @@
+/**
+ * QQ Gateway 协议处理。
+ *
+ * 关键点（中文）
+ * - 只负责 Gateway op code 的协议路由与 Identify payload 构造。
+ * - 不持有 WebSocket 生命周期状态，所有状态写入通过回调交回 `QQGatewayClient`。
+ * - 这样 client 保持单一状态源，协议细节也不会继续挤在连接编排类里。
+ */
+
+import type WebSocket from "ws";
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type {
+  QQGatewayPayload,
+  QqDispatchHandler,
+} from "@/chat/channels/qq/types/QqChannel.js";
+import { EventType, OpCode } from "@/chat/channels/qq/types/QqChannel.js";
+
+/**
+ * Gateway payload 处理参数。
+ */
+export interface HandleQqGatewayPayloadParams {
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * 当前 payload。
+   */
+  payload: QQGatewayPayload;
+  /**
+   * 记录服务端序列号。
+   */
+  setLastSeq(seq: number): void;
+  /**
+   * 启动心跳。
+   */
+  startHeartbeat(intervalMs: number): void;
+  /**
+   * 发送 Identify。
+   */
+  sendIdentify(): Promise<void>;
+  /**
+   * 标记 READY。
+   */
+  markReady(contextId: string): void;
+  /**
+   * 标记 RESUMED。
+   */
+  markResumed(): void;
+  /**
+   * 标记心跳 ACK。
+   */
+  markHeartbeatAck(): void;
+  /**
+   * 清理 access token 缓存。
+   */
+  clearAccessTokenCache(): void;
+  /**
+   * 触发 socket 自愈关闭。
+   */
+  closeSocketForRecovery(reason: string): void;
+  /**
+   * Dispatch 事件回调。
+   */
+  onDispatch(params: QqDispatchHandler): Promise<void>;
+}
+
+/**
+ * Identify 发送参数。
+ */
+export interface SendQqGatewayIdentifyParams {
+  /**
+   * 当前 socket。
+   */
+  socket: WebSocket | null;
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * 获取鉴权 token。
+   */
+  getAuthToken(): Promise<string>;
+}
+
+/**
+ * 处理 QQ Gateway payload。
+ */
+export async function handleQqGatewayPayload(
+  params: HandleQqGatewayPayloadParams,
+): Promise<void> {
+  const { op, d, s, t } = params.payload;
+  if (s) {
+    params.setLastSeq(s);
+  }
+
+  switch (op) {
+    case OpCode.Hello: {
+      const heartbeatIntervalMs =
+        typeof d?.heartbeat_interval === "number" ? d.heartbeat_interval : 30000;
+      params.startHeartbeat(heartbeatIntervalMs);
+      await params.sendIdentify();
+      break;
+    }
+    case OpCode.Dispatch: {
+      const eventType = String(t || "");
+      if (eventType === EventType.READY) {
+        params.markReady(typeof d?.context_id === "string" ? d.context_id : "");
+      } else if (eventType === EventType.RESUMED) {
+        params.markResumed();
+      }
+      await params.onDispatch({
+        eventType,
+        data: d || {},
+      });
+      break;
+    }
+    case OpCode.HeartbeatAck:
+      params.markHeartbeatAck();
+      params.logger.debug("收到心跳响应");
+      break;
+    case OpCode.Reconnect:
+      params.logger.warn("服务端要求重连");
+      params.closeSocketForRecovery("server_reconnect_opcode");
+      break;
+    case OpCode.InvalidContext:
+      params.logger.error("无效的 Context，需要重新鉴权");
+      params.clearAccessTokenCache();
+      setTimeout(async () => {
+        try {
+          await params.sendIdentify();
+        } catch (error) {
+          params.logger.error("重新鉴权失败", { error: String(error) });
+        }
+      }, 2000);
+      break;
+  }
+}
+
+/**
+ * 发送 QQ Gateway Identify。
+ */
+export async function sendQqGatewayIdentify(
+  params: SendQqGatewayIdentifyParams,
+): Promise<void> {
+  const authToken = await params.getAuthToken();
+  const intents = getQqGatewayIntents();
+  params.logger.info(`发送鉴权请求 (Identify)，intents: ${intents}`);
+
+  const identifyPayload = {
+    op: OpCode.Identify,
+    d: {
+      token: authToken,
+      intents,
+      shard: [0, 1],
+      properties: {
+        $os: "linux",
+        $browser: "downcity",
+        $device: "downcity",
+      },
+    },
+  };
+
+  params.logger.debug(`Identify payload: ${JSON.stringify(identifyPayload)}`);
+  params.socket?.send(JSON.stringify(identifyPayload));
+  params.logger.info("已发送鉴权请求");
+}
+
+/**
+ * 获取订阅事件位掩码。
+ */
+function getQqGatewayIntents(): number {
+  const GROUP_AND_C2C_EVENT = 1 << 25;
+  const AUDIO_ACTION = 1 << 29;
+  return GROUP_AND_C2C_EVENT | AUDIO_ACTION;
+}

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

@@ -0,0 +1,258 @@
+/**
+ * QQ Gateway 发送辅助函数。
+ *
+ * 关键点（中文）
+ * - 这里统一处理消息投递地址、超时、自动重试与自愈触发。
+ * - `QQGatewayClient` 只保留发送入口与状态持有，不再直接展开长流程。
+ */
+
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { QQSendMessageBody } from "@/chat/channels/qq/types/QqChannel.js";
+import {
+  isRetryableQqSendFailure,
+  resolveQqApiErrorText,
+  waitBeforeQqSendRetry,
+} from "./QQSendSupport.js";
+
+/**
+ * 单次发送请求构造结果。
+ */
+export interface QqSendRequest {
+  /**
+   * 请求 URL。
+   */
+  url: string;
+  /**
+   * 请求体。
+   */
+  body: QQSendMessageBody;
+}
+
+/**
+ * QQ 发送重试流程参数。
+ */
+export interface SendQqMessageWithRetryParams {
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * OpenAPI 基础地址。
+   */
+  apiBase: string;
+  /**
+   * 会话 ID。
+   */
+  chatId: string;
+  /**
+   * 会话类型。
+   */
+  chatType: string;
+  /**
+   * 原始消息 ID。
+   */
+  messageId: string;
+  /**
+   * 文本内容。
+   */
+  text: string;
+  /**
+   * QQ 消息序号。
+   */
+  msgSeq: number;
+  /**
+   * 最大重试次数。
+   */
+  maxAttempts: number;
+  /**
+   * 单次 HTTP 超时时间。
+   */
+  requestTimeoutMs: number;
+  /**
+   * 获取鉴权 token 的回调。
+   */
+  getAuthToken: () => Promise<string>;
+  /**
+   * 发送失败后清理 token 缓存的回调。
+   */
+  clearAccessTokenCache: () => void;
+  /**
+   * 发送失败后主动关闭 ws 的回调。
+   */
+  closeSocketForRecovery: (reason: string) => void;
+  /**
+   * 发送失败后触发重连的回调。
+   */
+  scheduleReconnect: (reason: string, delayMs?: number) => void;
+}
+
+function buildQqSendRequest(params: {
+  /**
+   * OpenAPI 基础地址。
+   */
+  apiBase: string;
+  /**
+   * 会话 ID。
+   */
+  chatId: string;
+  /**
+   * 会话类型。
+   */
+  chatType: string;
+  /**
+   * 原始消息 ID。
+   */
+  messageId: string;
+  /**
+   * 文本内容。
+   */
+  text: string;
+  /**
+   * QQ 消息序号。
+   */
+  msgSeq: number;
+}): QqSendRequest {
+  let url = "";
+  const body: QQSendMessageBody = {
+    content: params.text,
+    msg_type: 0,
+    msg_id: params.messageId,
+    msg_seq: params.msgSeq,
+  };
+
+  switch (params.chatType) {
+    case "group":
+      url = `${params.apiBase}/v2/groups/${params.chatId}/messages`;
+      break;
+    case "c2c":
+      url = `${params.apiBase}/v2/users/${params.chatId}/messages`;
+      break;
+    case "channel":
+      url = `${params.apiBase}/channels/${params.chatId}/messages`;
+      break;
+    default:
+      throw new Error(`未知的聊天类型: ${params.chatType}`);
+  }
+
+  return { url, body };
+}
+
+async function postQqMessageOnce(params: {
+  /**
+   * 日志器。
+   */
+  logger: Logger;
+  /**
+   * 请求 URL。
+   */
+  url: string;
+  /**
+   * 请求体。
+   */
+  body: QQSendMessageBody;
+  /**
+   * 单次 HTTP 超时时间。
+   */
+  requestTimeoutMs: number;
+  /**
+   * 获取鉴权 token 的回调。
+   */
+  getAuthToken: () => Promise<string>;
+}): Promise<{ status: number; responseText: string }> {
+  const authToken = await params.getAuthToken();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, params.requestTimeoutMs);
+
+  let response: Response;
+  try {
+    response = await fetch(params.url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: authToken,
+      },
+      body: JSON.stringify(params.body),
+      signal: controller.signal,
+    });
+  } catch (error) {
+    const errorText = String(error);
+    if (errorText.toLowerCase().includes("abort")) {
+      throw new Error(`QQ send failed: timeout after ${params.requestTimeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+
+  const responseText = await response.text();
+  if (!response.ok) {
+    params.logger.error(`发送消息失败: ${response.status} - ${responseText}`);
+    throw new Error(`QQ send failed: HTTP ${response.status}: ${responseText}`);
+  }
+
+  const apiError = resolveQqApiErrorText(responseText);
+  if (apiError) {
+    throw new Error(`QQ send failed: ${apiError}`);
+  }
+  return { status: response.status, responseText };
+}
+
+/**
+ * 带自动重试与自愈触发的 QQ 消息发送。
+ */
+export async function sendQqMessageWithRetry(
+  params: SendQqMessageWithRetryParams,
+): Promise<void> {
+  const request = buildQqSendRequest({
+    apiBase: params.apiBase,
+    chatId: params.chatId,
+    chatType: params.chatType,
+    messageId: params.messageId,
+    text: params.text,
+    msgSeq: params.msgSeq,
+  });
+
+  params.logger.debug(`发送消息到: ${request.url}`);
+
+  let lastError: unknown = null;
+  for (let attempt = 1; attempt <= params.maxAttempts; attempt++) {
+    try {
+      const { status, responseText } = await postQqMessageOnce({
+        logger: params.logger,
+        url: request.url,
+        body: request.body,
+        requestTimeoutMs: params.requestTimeoutMs,
+        getAuthToken: params.getAuthToken,
+      });
+      params.logger.debug(
+        `消息发送成功: ${status}${responseText ? ` - ${responseText}` : ""}`,
+      );
+      return;
+    } catch (error) {
+      lastError = error;
+      const errorText = String(error);
+      const shouldRetry =
+        attempt < params.maxAttempts && isRetryableQqSendFailure(errorText);
+      if (!shouldRetry) {
+        throw error;
+      }
+
+      params.logger.warn("QQ 回发失败，准备自动重试", {
+        attempt,
+        maxAttempts: params.maxAttempts,
+        chatType: params.chatType,
+        chatId: params.chatId,
+        messageId: params.messageId,
+        error: errorText,
+      });
+      params.clearAccessTokenCache();
+      params.closeSocketForRecovery("send_failed_retry");
+      params.scheduleReconnect("send_failed_retry", 0);
+      await waitBeforeQqSendRetry(attempt);
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}

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

@@ -0,0 +1,159 @@
+/**
+ * QQGatewaySupport：QQ GatewayClient 的纯辅助逻辑。
+ *
+ * 关键点（中文）
+ * - 这里只放不依赖类实例的纯计算与纯解析逻辑。
+ * - 让 `QQGatewayClient` 专注于连接编排，而不是状态拼装与 payload 解码细节。
+ */
+
+import type { RawData } from "ws";
+import type { JsonObject, JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type { QQGatewayPayload, QqGatewayRuntimeStatus } from "@/chat/channels/qq/types/QqChannel.js";
+import type {
+  QqGatewayHeartbeatState,
+  QqGatewayRuntimeStatusInput,
+} from "@/chat/channels/qq/types/QqGatewaySupport.js";
+
+/**
+ * WebSocket OPEN 对应的 readyState 数值。
+ */
+const WS_OPEN_READY_STATE = 1;
+
+/**
+ * 解析 QQ API 基础地址。
+ */
+export function resolveQqGatewayApiBase(useSandbox: boolean): string {
+  return useSandbox
+    ? "https://sandbox.api.sgroup.qq.com"
+    : "https://api.sgroup.qq.com";
+}
+
+/**
+ * 解析默认 WebSocket Gateway 地址。
+ */
+export function resolveQqGatewayWsUrl(useSandbox: boolean): string {
+  return useSandbox
+    ? "wss://sandbox.api.sgroup.qq.com/websocket"
+    : "wss://api.sgroup.qq.com/websocket";
+}
+
+/**
+ * 计算心跳 ACK 超时阈值。
+ */
+export function getQqHeartbeatAckTimeoutMs(heartbeatIntervalMs: number): number {
+  return Math.max(heartbeatIntervalMs * 3, 45000);
+}
+
+/**
+ * 是否发生心跳 ACK 超时。
+ */
+export function hasQqHeartbeatTimeout(
+  state: QqGatewayHeartbeatState,
+  nowMs: number = Date.now(),
+): boolean {
+  if (!state.pendingHeartbeatSinceMs) return false;
+  return nowMs - state.pendingHeartbeatSinceMs >
+    getQqHeartbeatAckTimeoutMs(state.heartbeatIntervalMs);
+}
+
+/**
+ * 心跳是否健康。
+ */
+export function hasQqHealthyHeartbeat(
+  state: QqGatewayHeartbeatState,
+  nowMs: number = Date.now(),
+): boolean {
+  if (!state.wsReadyAtMs) return false;
+  if (!state.pendingHeartbeatSinceMs) return true;
+  return !hasQqHeartbeatTimeout(state, nowMs);
+}
+
+/**
+ * 构建 QQ 网关状态快照。
+ */
+export function buildQqGatewayRuntimeStatus(
+  input: QqGatewayRuntimeStatusInput,
+): QqGatewayRuntimeStatus {
+  const now = Date.now();
+  const isOpen = input.wsReadyState === WS_OPEN_READY_STATE;
+  const hasContext = Boolean(String(input.wsContextId || "").trim());
+  const heartbeatState = {
+    heartbeatIntervalMs: input.heartbeatIntervalMs,
+    pendingHeartbeatSinceMs: input.pendingHeartbeatSinceMs,
+    wsReadyAtMs: input.wsReadyAtMs,
+  };
+  const heartbeatHealthy = hasQqHealthyHeartbeat(heartbeatState, now);
+  const heartbeatTimedOut = hasQqHeartbeatTimeout(heartbeatState, now);
+  const linkState =
+    !input.isRunning
+      ? "disconnected"
+      : isOpen && hasContext && heartbeatHealthy
+        ? "connected"
+        : "unknown";
+
+  const statusText = !input.isRunning
+    ? "stopped"
+    : !isOpen
+      ? "connecting"
+      : !hasContext
+        ? "ws_open_wait_ready"
+        : heartbeatTimedOut
+          ? "heartbeat_timeout"
+          : heartbeatHealthy
+            ? "ws_online"
+            : "ws_open_wait_heartbeat";
+
+  return {
+    running: input.isRunning,
+    linkState,
+    statusText,
+    detail: {
+      appId: input.appId || null,
+      wsReadyState: input.wsReadyState,
+      wsContextId: input.wsContextId || null,
+      wsReadyAtMs: input.wsReadyAtMs || null,
+      heartbeatHealthy,
+      heartbeatIntervalMs: input.heartbeatIntervalMs,
+      heartbeatAckTimeoutMs: getQqHeartbeatAckTimeoutMs(
+        input.heartbeatIntervalMs,
+      ),
+      lastHeartbeatSentAtMs: input.lastHeartbeatSentAtMs || null,
+      lastHeartbeatAckAtMs: input.lastHeartbeatAckAtMs || null,
+      pendingHeartbeatSinceMs: input.pendingHeartbeatSinceMs || null,
+      reconnectAttempts: input.reconnectAttempts,
+      maxReconnectAttempts: input.maxReconnectAttempts,
+      reconnectScheduled: input.reconnectScheduled,
+      sandbox: input.useSandbox,
+    },
+  };
+}
+
+/**
+ * 解析原始 Gateway 载荷。
+ */
+export function parseQqGatewayPayload(rawData: RawData): QQGatewayPayload | null {
+  try {
+    const text = Buffer.isBuffer(rawData)
+      ? rawData.toString("utf-8")
+      : Array.isArray(rawData)
+        ? Buffer.concat(rawData).toString("utf-8")
+        : typeof rawData === "string"
+          ? rawData
+          : Buffer.from(rawData).toString("utf-8");
+    const parsed = JSON.parse(text) as JsonValue;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const obj = parsed as JsonObject;
+    const op = typeof obj.op === "number" ? obj.op : Number(obj.op);
+    if (!Number.isFinite(op)) return null;
+    return {
+      op,
+      ...(obj.d && typeof obj.d === "object" && !Array.isArray(obj.d)
+        ? { d: obj.d as JsonObject }
+        : {}),
+      ...(typeof obj.s === "number" ? { s: obj.s } : {}),
+      ...(typeof obj.t === "string" ? { t: obj.t } : {}),
+    };
+  } catch {
+    return null;
+  }
+}