@henryxiaoyang/wechat-access-unqclawed 1.0.0

package/websocket/websocket-client.ts

@@ -0,0 +1,739 @@
+/**
+ * `randomUUID` 来自 Node.js 内置的 `node:crypto` 模块。
+ * 用于生成符合 RFC 4122 标准的 UUID v4 字符串，格式如：
+ *   "550e8400-e29b-41d4-a716-446655440000"
+ * 每次调用都会生成一个全局唯一的随机字符串，用作消息的 msg_id。
+ * 注意：这是 Node.js 原生 API，不需要安装任何第三方库。
+ */
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import type {
+  AGPEnvelope,
+  AGPMethod,
+  WebSocketClientConfig,
+  ConnectionState,
+  WebSocketClientCallbacks,
+  PromptMessage,
+  CancelMessage,
+  UpdatePayload,
+  PromptResponsePayload,
+  ContentBlock,
+  ToolCall,
+} from "./types.js";
+
+// ============================================
+// WebSocket 客户端核心
+// ============================================
+// 负责 WebSocket 连接管理、消息收发、自动重连、心跳保活
+
+/**
+ * WebSocket 客户端
+ * @description
+ * 连接到 AGP WebSocket 服务端，处理双向通信：
+ * - 接收下行消息：session.prompt / session.cancel
+ * - 发送上行消息：session.update / session.promptResponse
+ * - 自动重连：连接断开后自动尝试重连（指数退避策略）
+ * - 心跳保活：定期发送 WebSocket 原生 ping 帧，防止服务端因空闲超时断开连接
+ * - 消息去重：通过 msg_id 实现幂等处理，避免重复消息被处理两次
+ */
+export class WechatAccessWebSocketClient {
+  private config: Required<Omit<WebSocketClientConfig, "token" | "gatewayPort">> & { token?: string; gatewayPort?: string };
+  private callbacks: WebSocketClientCallbacks;
+
+  /**
+   * ws 库的 WebSocket 实例。
+   * 类型写作 `WebSocket.WebSocket` 是因为 ws 库的默认导出是类本身，
+   * 而 `WebSocket.WebSocket` 是其实例类型（TypeScript 类型系统的要求）。
+   * 未连接时为 null。
+   */
+  private ws: WebSocket | null = null;
+
+  /** 当前连接状态 */
+  private state: ConnectionState = "disconnected";
+
+  /**
+   * 重连定时器句柄。
+   * `ReturnType<typeof setTimeout>` 是 TypeScript 推荐的写法，
+   * 可以同时兼容 Node.js（返回 Timeout 对象）和浏览器（返回 number）环境。
+   */
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * 心跳定时器句柄。
+   * `ReturnType<typeof setInterval>` 同上，兼容 Node.js 和浏览器。
+   */
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** 当前已尝试的重连次数 */
+  private reconnectAttempts = 0;
+
+  /**
+   * 已处理的消息 ID 集合（用于去重）。
+   * 使用 Set 而非数组，查找时间复杂度为 O(1)。
+   * 当消息因网络问题被重发时，通过检查 msg_id 是否已存在来避免重复处理。
+   */
+  private processedMsgIds = new Set<string>();
+
+  /** 消息 ID 缓存定期清理定时器（防止 Set 无限增长导致内存泄漏） */
+  private msgIdCleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** 上次收到 pong 的时间戳（用于检测连接假死） */
+  private lastPongTime = Date.now();
+
+  /** 系统唤醒检测定时器 */
+  private wakeupCheckTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** 唤醒检测：上次 tick 的时间戳 */
+  private lastTickTime = Date.now();
+
+  /** 消息 ID 缓存的最大容量，超过此值时触发清理 */
+  private static readonly MAX_MSG_ID_CACHE = 1000;
+
+  /** 从 config.url 中解析出端口号，用于日志前缀 */
+  private get port(): string {
+    return this.config.gatewayPort ?? 'unknown';
+  }
+
+  /** 带端口号的日志前缀 */
+  private get logPrefix(): string {
+    return `[wechat-access-ws:${this.port}]`;
+  }
+
+  constructor(config: WebSocketClientConfig, callbacks: WebSocketClientCallbacks = {}) {
+    this.config = {
+      url: config.url,
+      guid: config.guid ?? '',
+      userId: config.userId ?? '',
+      token: config.token,
+      gatewayPort: config.gatewayPort,
+      reconnectInterval: config.reconnectInterval ?? 3000,
+      maxReconnectAttempts: config.maxReconnectAttempts ?? 0,
+      // 默认 20s发一次心跳，小于服务端 1 分钟的空闲超时时间
+      heartbeatInterval: config.heartbeatInterval ?? 20000,
+    };
+    this.callbacks = callbacks;
+  }
+
+  /**
+   * 启动 WebSocket 连接
+   * @description
+   * 如果当前已连接或正在连接中，则直接返回，避免重复建立连接。
+   * 同时启动消息 ID 缓存的定期清理任务。
+   */
+  start = (): void => {
+    if (this.state === "connected" || this.state === "connecting") {
+      console.log(`${this.logPrefix} 已连接或正在连接，跳过`);
+      return;
+    }
+    this.connect();
+    this.startMsgIdCleanup();
+  };
+
+  /**
+   * 停止 WebSocket 连接
+   * @description
+   * 主动断开连接时调用。会：
+   * 1. 将状态设为 "disconnected"（阻止断开后触发自动重连）
+   * 2. 清理所有定时器（重连、心跳、消息 ID 清理）
+   * 3. 清空消息 ID 缓存
+   * 4. 关闭 WebSocket 连接
+   */
+  stop = (): void => {
+    console.log(`${this.logPrefix} 正在停止...`);
+    this.state = "disconnected";
+    this.clearReconnectTimer();
+    this.clearHeartbeat();
+    this.clearWakeupDetection();
+    this.clearMsgIdCleanup();
+    this.processedMsgIds.clear();
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    console.log(`${this.logPrefix} 已停止`);
+  };
+
+  /**
+   * 获取当前连接状态
+   * @returns "disconnected" | "connecting" | "connected" | "reconnecting"
+   */
+  getState = (): ConnectionState => this.state;
+
+  /**
+   * 更新事件回调
+   * @description 使用对象展开合并，只更新传入的回调，保留未传入的原有回调
+   */
+  setCallbacks = (callbacks: Partial<WebSocketClientCallbacks>): void => {
+    this.callbacks = { ...this.callbacks, ...callbacks };
+  };
+
+  /**
+   * 发送 session.update 消息 — 流式中间更新（文本块）
+   * @param sessionId - 所属 Session ID
+   * @param promptId - 所属 Turn ID
+   * @param content - 文本内容块（type: "text"）
+   * @description
+   * 在 Agent 生成回复的过程中，将增量文本实时推送给服务端，
+   * 服务端再转发给用户端展示流式输出效果。
+   */
+  sendMessageChunk = (sessionId: string, promptId: string, content: ContentBlock, guid?: string, userId?: string): void => {
+    console.log(`${this.logPrefix} [sendMessageChunk] sessionId=${sessionId}, promptId=${promptId}, guid=${guid}, userId=${userId}, content=${JSON.stringify(content).substring(0, 200)}`);
+    const payload: UpdatePayload = {
+      session_id: sessionId,
+      prompt_id: promptId,
+      update_type: "message_chunk",
+      content,
+    };
+    this.sendEnvelope("session.update", payload, guid, userId);
+  };
+
+  /**
+   * 发送 session.update 消息 — 工具调用开始
+   * @param sessionId - 所属 Session ID
+   * @param promptId - 所属 Turn ID
+   * @param toolCall - 工具调用信息（包含 tool_call_id、title、kind、status）
+   * @description
+   * 当 Agent 开始调用某个工具时发送，通知服务端展示工具调用状态。
+   */
+  sendToolCall = (sessionId: string, promptId: string, toolCall: ToolCall, guid?: string, userId?: string): void => {
+    console.log(`${this.logPrefix} [sendToolCall] sessionId=${sessionId}, promptId=${promptId}, guid=${guid}, userId=${userId}, toolCall=${JSON.stringify(toolCall)}`);
+    const payload: UpdatePayload = {
+      session_id: sessionId,
+      prompt_id: promptId,
+      update_type: "tool_call",
+      tool_call: toolCall,
+    };
+    this.sendEnvelope("session.update", payload, guid, userId);
+  };
+
+  /**
+   * 发送 session.update 消息 — 工具调用状态变更
+   * @param sessionId - 所属 Session ID
+   * @param promptId - 所属 Turn ID
+   * @param toolCall - 更新后的工具调用信息（status 变为 completed/failed）
+   * @description
+   * 当工具执行完成或失败时发送，通知服务端更新工具调用的展示状态。
+   */
+  sendToolCallUpdate = (sessionId: string, promptId: string, toolCall: ToolCall, guid?: string, userId?: string): void => {
+    console.log(`${this.logPrefix} [sendToolCallUpdate] sessionId=${sessionId}, promptId=${promptId}, guid=${guid}, userId=${userId}, toolCall=${JSON.stringify(toolCall)}`);
+    const payload: UpdatePayload = {
+      session_id: sessionId,
+      prompt_id: promptId,
+      update_type: "tool_call_update",
+      tool_call: toolCall,
+    };
+    this.sendEnvelope("session.update", payload, guid, userId);
+  };
+
+  /**
+   * 发送 session.promptResponse 消息 — 最终结果
+   * @param payload - 包含 stop_reason、content、error 等最终结果信息
+   * @description
+   * Agent 处理完成后发送，告知服务端本次 Turn 已结束。
+   * stop_reason 可以是：end_turn（正常完成）、cancelled（被取消）、error（出错）
+   */
+  sendPromptResponse = (payload: PromptResponsePayload, guid?: string, userId?: string): void => {
+    const contentPreview = payload.content ? JSON.stringify(payload.content).substring(0, 200) : '(empty)';
+    console.log(`${this.logPrefix} [sendPromptResponse] sessionId=${payload.session_id}, promptId=${payload.prompt_id}, stopReason=${payload.stop_reason}, guid=${guid}, userId=${userId}, content=${contentPreview}`);
+    this.sendEnvelope("session.promptResponse", payload, guid, userId);
+  };
+
+
+  /**
+   * 建立 WebSocket 连接
+   * @description
+   * 使用 ws 库的 `new WebSocket(url)` 创建连接。
+   * ws 库会在内部自动完成 TCP 握手和 WebSocket 升级协议（HTTP Upgrade）。
+   * 连接是异步建立的，实际连接成功会触发 "open" 事件。
+   */
+  private connect = (): void => {
+    // url 为空时不进行连接，避免 new URL("") 抛出 TypeError
+    if (!this.config.url) {
+      console.error(`${this.logPrefix} wsUrl 未配置，跳过连接`);
+      this.state = "disconnected";
+      return;
+    }
+    // token 为空时不进行连接，避免无效请求
+    if (!this.config.token) {
+      console.error(`${this.logPrefix} token 为空，跳过 WebSocket 连接`);
+      this.state = "disconnected";
+      return;
+    }
+
+    this.state = "connecting";
+    console.error(`${this.logPrefix} 连接配置: url=${this.config.url}, token=${this.config.token.substring(0, 6) + '...'}, guid=${this.config.guid}, userId=${this.config.userId}`);
+    const wsUrl = this.buildConnectionUrl();
+    console.error(`${this.logPrefix} 正在连接: ${wsUrl}`);
+
+    try {
+      // new WebSocket(url) 立即返回，不会阻塞
+      // 连接过程在后台异步进行，通过事件通知结果
+      this.ws = new WebSocket(wsUrl);
+      this.setupEventHandlers();
+    } catch (error) {
+      // 同步错误（如 URL 格式非法）会在这里捕获
+      // 异步连接失败（如服务端拒绝）会触发 "error" 事件
+      console.error(`${this.logPrefix} 创建连接失败:`, error);
+      this.handleConnectionError(error instanceof Error ? error : new Error(String(error)));
+    }
+  };
+
+  /**
+   * 构建 WebSocket 连接 URL
+   * @description
+   * 使用 Node.js 内置的 `URL` 类（全局可用，无需 import）构建带查询参数的 URL。
+   * `url.searchParams.set()` 会自动对参数值进行 URL 编码（encodeURIComponent），
+   * 避免特殊字符导致的 URL 解析问题。
+   *
+   * 最终格式：ws://host:port/?token={token}
+   */
+  private buildConnectionUrl = (): string => {
+    const url = new URL(this.config.url);
+    if (this.config.token) {
+      url.searchParams.set("token", this.config.token);
+    }
+    return url.toString();
+  };
+
+  /**
+   * 注册 ws 库的事件监听器
+   * @description
+   * ws 库使用 Node.js EventEmitter 风格的 `.on(event, handler)` 注册事件，
+   * 而非浏览器的 `.addEventListener(event, handler)`。
+   * 两者功能相同，但回调参数类型不同：
+   *
+   * | 事件    | 浏览器原生参数         | ws 库参数                        |
+   * |---------|----------------------|----------------------------------|
+   * | open    | Event                | 无参数                           |
+   * | message | MessageEvent         | (data: RawData, isBinary: bool)  |
+   * | close   | CloseEvent           | (code: number, reason: Buffer)   |
+   * | error   | Event                | (error: Error)                   |
+   * | pong    | 不支持               | 无参数（ws 库特有）               |
+   */
+  private setupEventHandlers = (): void => {
+    if (!this.ws) return;
+
+    this.ws.on("open", this.handleOpen);
+    this.ws.on("message", this.handleRawMessage);
+    this.ws.on("close", this.handleClose);
+    this.ws.on("error", this.handleError);
+    // "pong" 是 ws 库特有的事件，当收到服务端的 pong 控制帧时触发
+    // 浏览器原生 WebSocket API 不暴露此事件
+    this.ws.on("pong", this.handlePong);
+  };
+
+  // ============================================
+  // 事件处理
+  // ============================================
+
+  /**
+   * 处理连接建立事件
+   * @description
+   * ws 库的 "open" 事件在 WebSocket 握手完成后触发，此时可以开始收发消息。
+   * 连接成功后：
+   * 1. 更新状态为 "connected"
+   * 2. 重置重连计数器
+   * 3. 重置 pong 时间戳
+   * 4. 启动心跳定时器
+   * 5. 启动系统唤醒检测
+   * 6. 触发 onConnected 回调
+   */
+  private handleOpen = (): void => {
+    console.log(`${this.logPrefix} 连接成功`);
+    this.state = "connected";
+    this.reconnectAttempts = 0;
+    this.lastPongTime = Date.now();
+    this.startHeartbeat();
+    this.startWakeupDetection();
+    this.callbacks.onConnected?.();
+  };
+
+  /**
+   * 处理收到的原始消息
+   * @param data - ws 库的原始消息数据，类型为 `WebSocket.RawData`
+   * @description
+   * `WebSocket.RawData` 是 ws 库定义的联合类型：`Buffer | ArrayBuffer | Buffer[]`
+   * - 文本消息（text frame）：通常是 Buffer 类型
+   * - 二进制消息（binary frame）：可能是 Buffer 或 ArrayBuffer
+   *
+   * 处理步骤：
+   * 1. 将 RawData 转为字符串（Buffer.toString() 默认使用 UTF-8 编码）
+   * 2. JSON.parse 解析为 AGPEnvelope 对象
+   * 3. 检查 msg_id 去重
+   * 4. 根据 method 字段分发到对应的回调
+   */
+  private handleRawMessage = (data: WebSocket.RawData): void => {
+    try {
+      // Buffer.toString() 默认 UTF-8 编码，等同于 data.toString("utf8")
+      // 如果 data 已经是 string 类型（理论上 ws 库不会这样，但做兼容处理）
+      const raw = typeof data === "string" ? data : data.toString();
+      const envelope = JSON.parse(raw) as AGPEnvelope;
+
+      // 消息去重：同一个 msg_id 只处理一次
+      // 网络不稳定时服务端可能重发消息，通过 msg_id 避免重复处理
+      if (this.processedMsgIds.has(envelope.msg_id)) {
+        console.log(`${this.logPrefix} 重复消息，跳过: ${envelope.msg_id}`);
+        return;
+      }
+      this.processedMsgIds.add(envelope.msg_id);
+
+      console.log(`${this.logPrefix} 收到消息: method=${envelope.method}, msg_id=${envelope.msg_id}`);
+
+      // 根据 method 字段分发消息到对应的业务处理回调
+      switch (envelope.method) {
+        case "session.prompt":
+          // 下行：服务端下发用户指令，需要调用 Agent 处理
+          this.callbacks.onPrompt?.(envelope as PromptMessage);
+          break;
+        case "session.cancel":
+          // 下行：服务端要求取消正在处理的 Turn
+          this.callbacks.onCancel?.(envelope as CancelMessage);
+          break;
+        default:
+          console.warn(`${this.logPrefix} 未知消息类型: ${envelope.method}`);
+      }
+    } catch (error) {
+      console.error(`${this.logPrefix} 消息解析失败:`, error, '原始数据:', data);
+      this.callbacks.onError?.(
+        error instanceof Error ? error : new Error(`消息解析失败: ${String(error)}`)
+      );
+    }
+  };
+
+  /**
+   * 处理连接关闭事件
+   * @param code - WebSocket 关闭状态码（RFC 6455 定义）
+   *   常见值：
+   *   - 1000: 正常关闭
+   *   - 1001: 端点离开（如服务端重启）
+   *   - 1006: 异常关闭（连接被强制断开，无关闭握手）
+   *   - 1008: 策略违规（如 token 不匹配）
+   * @param reason - 关闭原因，ws 库中类型为 `Buffer`，需要调用 `.toString()` 转为字符串
+   * @description
+   * 注意：ws 库的 close 事件参数与浏览器不同：
+   *   - 浏览器：`(event: CloseEvent)` → 通过 event.code 和 event.reason 获取
+   *   - ws 库：`(code: number, reason: Buffer)` → 直接获取，reason 是 Buffer 需要转换
+   *
+   * 只有在非主动关闭（state !== "disconnected"）时才触发重连，
+   * 避免调用 stop() 后又自动重连。
+   */
+  private handleClose = (code: number, reason: Buffer): void => {
+    // Buffer.toString() 将 Buffer 转为 UTF-8 字符串
+    // 如果 reason 为空 Buffer，toString() 返回空字符串，此时用 code 作为描述
+    const reasonStr = reason.toString() || `code=${code}`;
+    console.log(`${this.logPrefix} 连接关闭: ${reasonStr}`);
+    this.clearHeartbeat();
+    this.clearWakeupDetection();
+    this.ws = null;
+
+    // 仅在非主动关闭的情况下尝试重连
+    // 主动调用 stop() 时会先将 state 设为 "disconnected"，此处就不会触发重连
+    if (this.state !== "disconnected") {
+      this.callbacks.onDisconnected?.(reasonStr);
+      this.scheduleReconnect();
+    }
+  };
+
+  /**
+   * 处理 pong 控制帧
+   * @description
+   * 当服务端收到我们发送的 ping 帧后，会自动回复一个 pong 帧。
+   * ws 库会触发 "pong" 事件通知我们。
+   * 记录收到 pong 的时间戳，供心跳定时器检测连接是否假死。
+   * 如果长时间未收到 pong，说明连接已不可用（如电脑休眠导致 TCP 断开）。
+   */
+  private handlePong = (): void => {
+    this.lastPongTime = Date.now();
+  };
+
+  /**
+   * 处理连接错误事件
+   * @param error - ws 库直接传递 Error 对象（浏览器原生 API 传递的是 Event 对象）
+   * @description
+   * ws 库的 "error" 事件在以下情况触发：
+   *   - 连接被拒绝（如服务端不可达）
+   *   - TLS 握手失败
+   *   - 消息发送失败
+   * 注意：error 事件之后通常会紧跟 close 事件，重连逻辑在 handleClose 中处理。
+   */
+  private handleError = (error: Error): void => {
+    console.error(`${this.logPrefix} 连接错误:`, error);
+    this.callbacks.onError?.(error);
+  };
+
+  /**
+   * 处理连接创建时的同步错误
+   * @description
+   * 当 `new WebSocket(url)` 抛出同步异常时调用（如 URL 格式非法）。
+   * 此时不会触发 "error" 和 "close" 事件，需要手动触发重连。
+   */
+  private handleConnectionError = (error: Error): void => {
+    this.callbacks.onError?.(error);
+    this.scheduleReconnect();
+  };
+
+  /**
+   * 安排下一次重连
+   * @description
+   * 使用指数退避（Exponential Backoff）策略计算重连延迟：
+   *   delay = min(reconnectInterval × 1.5^(attempts-1), 30000)
+   *
+   * 例如 reconnectInterval=3000 时：
+   *   第 1 次：3000ms
+   *   第 2 次：4500ms
+   *   第 3 次：6750ms
+   *   第 4 次：10125ms
+   *   第 5 次：15187ms（之后趋近 30000ms 上限）
+   *
+   * 指数退避的目的：避免服务端故障时大量客户端同时重连造成雪崩效应。
+   *
+   * `setTimeout` 是 Node.js 全局函数，在指定延迟后执行一次回调。
+   * 返回值是 Timeout 对象（Node.js）或 number（浏览器），
+   * 需要保存以便后续调用 clearTimeout 取消。
+   */
+  private scheduleReconnect = (): void => {
+    // 检查是否超过最大重连次数（0 表示无限重连）
+    if (
+      this.config.maxReconnectAttempts > 0 &&
+      this.reconnectAttempts >= this.config.maxReconnectAttempts
+    ) {
+      console.error(`${this.logPrefix} 已达最大重连次数 (${this.config.maxReconnectAttempts})，停止重连`);
+      this.state = "disconnected";
+      return;
+    }
+
+    this.state = "reconnecting";
+    this.reconnectAttempts++;
+
+    // 指数退避：每次重连等待时间递增，最大 25 秒
+    const delay = Math.min(
+      this.config.reconnectInterval * Math.pow(1.5, this.reconnectAttempts - 1),
+      25000
+    );
+
+    console.log(`${this.logPrefix} ${delay}ms 后尝试第 ${this.reconnectAttempts} 次重连...`);
+
+    // setTimeout 返回的句柄保存到 reconnectTimer，
+    // 以便在 stop() 或成功连接时通过 clearTimeout 取消待执行的重连
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, delay);
+  };
+
+  /**
+   * 清除重连定时器
+   * @description
+   * `clearTimeout` 是 Node.js 全局函数，取消由 setTimeout 创建的定时器。
+   * 如果定时器已执行或已被取消，调用 clearTimeout 不会报错（安全操作）。
+   */
+  private clearReconnectTimer = (): void => {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  };
+
+  // ============================================
+  // 心跳保活
+  // ============================================
+
+  /**
+   * 启动心跳定时器
+   * @description
+   * 使用 `setInterval` 定期发送 WebSocket ping 控制帧，并检测 pong 超时。
+   *
+   * `ws.ping()` 发送 WebSocket 协议层的 ping 控制帧（opcode=0x9），
+   * 服务端必须自动回复 pong 帧。
+   *
+   * Pong 超时检测：
+   * 如果超过 2 倍心跳间隔仍未收到 pong，判定连接已死（如休眠后 TCP 已断），
+   * 主动 terminate 触发 close 事件 → 自动重连。
+   *
+   * Ping 失败处理：
+   * 如果 ping 发送抛异常（底层 socket 已关闭），也主动 terminate 触发重连。
+   */
+  private startHeartbeat = (): void => {
+    this.clearHeartbeat();
+    this.heartbeatTimer = setInterval(() => {
+      if (this.ws && this.state === "connected") {
+        // 检测 pong 超时：超过 2 倍心跳间隔未收到 pong，判定连接已死
+        const pongTimeout = this.config.heartbeatInterval * 2;
+        if (Date.now() - this.lastPongTime > pongTimeout) {
+          console.warn(`${this.logPrefix} pong 超时 (${pongTimeout}ms 未收到)，判定连接已死，主动断开`);
+          this.ws.terminate();
+          return;
+        }
+
+        try {
+          // ws.ping() 发送 WebSocket 原生 ping 控制帧
+          this.ws.ping();
+        } catch {
+          console.warn(`${this.logPrefix} 心跳发送失败，主动断开触发重连`);
+          this.ws?.terminate();
+        }
+      }
+    }, this.config.heartbeatInterval);
+  };
+
+  /**
+   * 清除心跳定时器
+   * @description
+   * `clearInterval` 是 Node.js 全局函数，停止由 setInterval 创建的定时器。
+   * 在连接关闭或主动停止时调用，避免向已断开的连接发送 ping。
+   */
+  private clearHeartbeat = (): void => {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  };
+
+  // ============================================
+  // 系统唤醒检测
+  // ============================================
+
+  /**
+   * 启动系统唤醒检测
+   * @description
+   * 电脑休眠时 setInterval 会被冻结，唤醒后恢复。
+   * 利用「两次 tick 之间实际经过的时间」远大于「setInterval 设定的间隔」来检测唤醒事件。
+   *
+   * 例如：CHECK_INTERVAL = 5s，但实际两次 tick 间隔了 60s → 说明系统休眠了约 55s。
+   * 此时 TCP 连接大概率已被服务端超时关闭，需要主动 terminate 触发重连。
+   *
+   * 同时重置重连计数器，确保唤醒后有足够的重连机会。
+   */
+  private startWakeupDetection = (): void => {
+    this.clearWakeupDetection();
+    this.lastTickTime = Date.now();
+
+    const CHECK_INTERVAL = 5000; // 每 5 秒检查一次
+    const WAKEUP_THRESHOLD = 15000; // 实际间隔超过 15 秒视为休眠唤醒
+
+    this.wakeupCheckTimer = setInterval(() => {
+      const now = Date.now();
+      const elapsed = now - this.lastTickTime;
+      this.lastTickTime = now;
+
+      if (elapsed > WAKEUP_THRESHOLD) {
+        console.warn(`${this.logPrefix} 检测到系统唤醒 (tick 间隔 ${elapsed}ms，阈值 ${WAKEUP_THRESHOLD}ms)`);
+        // 重置重连计数器，给予唤醒后充足的重连机会
+        this.reconnectAttempts = 0;
+        // 如果当前连接还标记为已连接，主动断开触发重连
+        if (this.ws && this.state === "connected") {
+          console.warn(`${this.logPrefix} 唤醒后主动断开连接，触发重连`);
+          this.ws.terminate();
+        }
+      }
+    }, CHECK_INTERVAL);
+  };
+
+  /**
+   * 清除系统唤醒检测定时器
+   */
+  private clearWakeupDetection = (): void => {
+    if (this.wakeupCheckTimer) {
+      clearInterval(this.wakeupCheckTimer);
+      this.wakeupCheckTimer = null;
+    }
+  };
+
+  // ============================================
+  // 消息发送
+  // ============================================
+
+  /**
+   * 发送 AGP 信封消息（内部通用方法）
+   * @param method - AGP 消息类型（如 "session.update"、"session.promptResponse"）
+   * @param payload - 消息载荷，泛型 T 由调用方决定具体类型
+   * @description
+   * 所有上行消息都通过此方法发送，统一处理：
+   * 1. 检查连接状态
+   * 2. 构建 AGP 信封（添加 msg_id等公共字段）
+   * 3. JSON 序列化
+   * 4. 调用 ws.send() 发送文本帧
+   *
+   * `ws.send(data)` 是 ws 库的发送方法：
+   *   - 传入 string：发送文本帧（opcode=0x1）
+   *   - 传入 Buffer/ArrayBuffer：发送二进制帧（opcode=0x2）
+   *   - 这里传入 JSON 字符串，发送文本帧
+   *
+   * `randomUUID()` 为每条消息生成唯一 ID，服务端可用于去重和追踪。
+   */
+  private sendEnvelope = <T>(method: AGPMethod, payload: T, guid?: string, userId?: string): void => {
+    if (!this.ws || this.state !== "connected") {
+      console.warn(`${this.logPrefix} 无法发送消息，当前状态: ${this.state}`);
+      return;
+    }
+
+    const envelope: AGPEnvelope<T> = {
+      msg_id: randomUUID(),
+      guid: guid ?? this.config.guid,
+      user_id: userId ?? this.config.userId,
+      method,
+      payload,
+    };
+
+    try {
+      const data = JSON.stringify(envelope);
+      // ws.send() 将字符串作为 WebSocket 文本帧发送
+      this.ws.send(data);
+      // 截断过长的 JSON 日志，避免日志文件膨胀
+      const jsonPreview = data.length > 500 ? data.substring(0, 500) + `...(truncated, total ${data.length} chars)` : data;
+      console.log(`${this.logPrefix} 发送消息: method=${method}, msg_id=${envelope.msg_id}, json=${jsonPreview}`);
+    } catch (error) {
+      console.error(`${this.logPrefix} 消息发送失败:`, error);
+      this.callbacks.onError?.(
+        error instanceof Error ? error : new Error(`消息发送失败: ${String(error)}`)
+      );
+    }
+  };
+
+  // ============================================
+  // 消息 ID 缓存清理
+  // ============================================
+
+  /**
+   * 启动消息 ID 缓存定期清理任务
+   * @description
+   * `processedMsgIds` 是一个 Set，会随着消息的接收不断增长。
+   * 如果不清理，长时间运行后会占用大量内存（内存泄漏）。
+   *
+   * 清理策略：
+   * - 每 5 分钟检查一次
+   * - 当 Set 大小超过 MAX_MSG_ID_CACHE（1000）时触发清理
+   * - 清理时保留最新的一半（500 条），丢弃最旧的一半
+   *
+   * 为什么保留最新的一半而不是全部清空？
+   * 因为刚处理过的消息 ID 最有可能被重发，保留它们可以继续防重。
+   *
+   * `[...this.processedMsgIds]` 将 Set 转为数组，
+   * Set 的迭代顺序是插入顺序，所以 slice(-500) 取的是最后插入的 500 条（最新的）。
+   */
+  private startMsgIdCleanup = (): void => {
+    this.clearMsgIdCleanup();
+    this.msgIdCleanupTimer = setInterval(() => {
+      if (this.processedMsgIds.size > WechatAccessWebSocketClient.MAX_MSG_ID_CACHE) {
+        console.log(`${this.logPrefix} 清理消息 ID 缓存: ${this.processedMsgIds.size} → ${WechatAccessWebSocketClient.MAX_MSG_ID_CACHE / 2}`);
+        // 将 Set 转为数组（保持插入顺序），取后半部分（最新的），重建 Set
+        const entries = [...this.processedMsgIds];
+        this.processedMsgIds.clear();
+        entries.slice(-WechatAccessWebSocketClient.MAX_MSG_ID_CACHE / 2).forEach((id) => {
+          this.processedMsgIds.add(id);
+        });
+      }
+    }, 5 * 60 * 1000); // 每 5 分钟执行一次
+  };
+
+  /**
+   * 清除消息 ID 缓存清理定时器
+   */
+  private clearMsgIdCleanup = (): void => {
+    if (this.msgIdCleanupTimer) {
+      clearInterval(this.msgIdCleanupTimer);
+      this.msgIdCleanupTimer = null;
+    }
+  };
+}