@downcity/agent 1.1.23 → 1.1.32

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

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

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

@@ -1,176 +0,0 @@
-/**
- * QQ Gateway 协议处理。
- *
- * 关键点（中文）
- * - 只负责 Gateway op code 的协议路由与 Identify payload 构造。
- * - 不持有 WebSocket 生命周期状态，所有状态写入通过回调交回 `QQGatewayClient`。
- * - 这样 client 保持单一状态源，协议细节也不会继续挤在连接编排类里。
- */
-
-import type WebSocket from "ws";
-import type { Logger } from "@/utils/logger/Logger.js";
-import type {
-  QQGatewayPayload,
-  QqDispatchHandler,
-} from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
-import { EventType, OpCode } from "@/service/builtins/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/service/builtins/chat/channels/qq/QQGatewaySend.ts

@@ -1,258 +0,0 @@
-/**
- * QQ Gateway 发送辅助函数。
- *
- * 关键点（中文）
- * - 这里统一处理消息投递地址、超时、自动重试与自愈触发。
- * - `QQGatewayClient` 只保留发送入口与状态持有，不再直接展开长流程。
- */
-
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { QQSendMessageBody } from "@/service/builtins/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/service/builtins/chat/channels/qq/QQGatewaySupport.ts

@@ -1,159 +0,0 @@
-/**
- * QQGatewaySupport：QQ GatewayClient 的纯辅助逻辑。
- *
- * 关键点（中文）
- * - 这里只放不依赖类实例的纯计算与纯解析逻辑。
- * - 让 `QQGatewayClient` 专注于连接编排，而不是状态拼装与 payload 解码细节。
- */
-
-import type { RawData } from "ws";
-import type { JsonObject, JsonValue } from "@/types/common/Json.js";
-import type { QQGatewayPayload, QqGatewayRuntimeStatus } from "@/service/builtins/chat/channels/qq/types/QqChannel.js";
-import type {
-  QqGatewayHeartbeatState,
-  QqGatewayRuntimeStatusInput,
-} from "@/service/builtins/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;
-  }
-}