@teammy/server 0.1.4 → 0.1.5

package/node_modules/@wecom/aibot-node-sdk/dist/index.cjs.js

@@ -0,0 +1,1563 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var eventemitter3 = require('eventemitter3');
+var crypto = require('crypto');
+var axios = require('axios');
+var WebSocket = require('ws');
+var crypto$1 = require('node:crypto');
+
+/**
+ * 通用基础类型定义
+ */
+/**
+ * 认证失败重试次数用尽错误
+ *
+ * 当 WebSocket 认证连续失败次数达到 maxAuthFailureAttempts 时抛出。
+ * 通常表示 botId/secret 配置错误，重试无法恢复。
+ */
+class WSAuthFailureError extends Error {
+    constructor(maxAttempts) {
+        super(`Max auth failure attempts exceeded (${maxAttempts})`);
+        this.code = 'WS_AUTH_FAILURE_EXHAUSTED';
+        this.name = 'WSAuthFailureError';
+    }
+}
+/**
+ * 连接断开重连次数用尽错误
+ *
+ * 当 WebSocket 连接断开后重连次数达到 maxReconnectAttempts 时抛出。
+ * 通常表示网络或服务端持续不可用。
+ */
+class WSReconnectExhaustedError extends Error {
+    constructor(maxAttempts) {
+        super(`Max reconnect attempts exceeded (${maxAttempts})`);
+        this.code = 'WS_RECONNECT_EXHAUSTED';
+        this.name = 'WSReconnectExhaustedError';
+    }
+}
+
+/**
+ * 消息相关类型定义
+ * 按照企业微信智能机器人接收消息协议定义
+ */
+/** 消息类型枚举 */
+exports.MessageType = void 0;
+(function (MessageType) {
+    /** 文本消息 */
+    MessageType["Text"] = "text";
+    /** 图片消息 */
+    MessageType["Image"] = "image";
+    /** 图文混排消息 */
+    MessageType["Mixed"] = "mixed";
+    /** 语音消息 */
+    MessageType["Voice"] = "voice";
+    /** 文件消息 */
+    MessageType["File"] = "file";
+    /** 视频消息 */
+    MessageType["Video"] = "video";
+})(exports.MessageType || (exports.MessageType = {}));
+
+/**
+ * API 相关类型定义
+ */
+/** WebSocket 命令类型常量 */
+const WsCmd = {
+    // ========== 开发者 → 企业微信 ==========
+    /** 认证订阅 */
+    SUBSCRIBE: 'aibot_subscribe',
+    /** 心跳 */
+    HEARTBEAT: 'ping',
+    /** 回复消息 */
+    RESPONSE: 'aibot_respond_msg',
+    /** 回复欢迎语 */
+    RESPONSE_WELCOME: 'aibot_respond_welcome_msg',
+    /** 更新模板卡片 */
+    RESPONSE_UPDATE: 'aibot_respond_update_msg',
+    /** 主动发送消息 */
+    SEND_MSG: 'aibot_send_msg',
+    /** 上传临时素材 - 初始化 */
+    UPLOAD_MEDIA_INIT: 'aibot_upload_media_init',
+    /** 上传临时素材 - 分片上传 */
+    UPLOAD_MEDIA_CHUNK: 'aibot_upload_media_chunk',
+    /** 上传临时素材 - 完成上传 */
+    UPLOAD_MEDIA_FINISH: 'aibot_upload_media_finish',
+    // ========== 企业微信 → 开发者 ==========
+    /** 消息推送回调 */
+    CALLBACK: 'aibot_msg_callback',
+    /** 事件推送回调 */
+    EVENT_CALLBACK: 'aibot_event_callback',
+};
+// ========== 模板卡片结构体及子结构体 ==========
+/** 卡片类型枚举 */
+exports.TemplateCardType = void 0;
+(function (TemplateCardType) {
+    /** 文本通知模版卡片 */
+    TemplateCardType["TextNotice"] = "text_notice";
+    /** 图文展示模版卡片 */
+    TemplateCardType["NewsNotice"] = "news_notice";
+    /** 按钮交互模版卡片 */
+    TemplateCardType["ButtonInteraction"] = "button_interaction";
+    /** 投票选择模版卡片 */
+    TemplateCardType["VoteInteraction"] = "vote_interaction";
+    /** 多项选择模版卡片 */
+    TemplateCardType["MultipleInteraction"] = "multiple_interaction";
+})(exports.TemplateCardType || (exports.TemplateCardType = {}));
+
+/**
+ * 事件相关类型定义
+ */
+/** 事件类型枚举 */
+exports.EventType = void 0;
+(function (EventType) {
+    /** 进入会话事件：用户当天首次进入机器人单聊会话 */
+    EventType["EnterChat"] = "enter_chat";
+    /** 模板卡片事件：用户点击模板卡片按钮 */
+    EventType["TemplateCardEvent"] = "template_card_event";
+    /** 用户反馈事件：用户对机器人回复进行反馈 */
+    EventType["FeedbackEvent"] = "feedback_event";
+    /** 连接断开事件：有新连接建立时，服务端向旧连接发送此事件并主动断开 */
+    EventType["Disconnected"] = "disconnected_event";
+})(exports.EventType || (exports.EventType = {}));
+
+/**
+ * 企业微信 API 客户端
+ * 仅负责文件下载等 HTTP 辅助功能，消息收发均走 WebSocket 通道
+ */
+class WeComApiClient {
+    constructor(logger, timeout = 10000) {
+        this.logger = logger;
+        this.httpClient = axios.create({
+            timeout,
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+    /**
+     * 下载文件（返回原始 Buffer 及文件名）
+     */
+    async downloadFileRaw(url) {
+        this.logger.info('Downloading file...');
+        try {
+            const response = await this.httpClient.get(url, {
+                responseType: 'arraybuffer',
+            });
+            // 从 Content-Disposition 头中解析文件名
+            const contentDisposition = response.headers['content-disposition'];
+            let filename;
+            if (contentDisposition) {
+                // 优先匹配 filename*=UTF-8''xxx 格式（RFC 5987）
+                const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;\s]+)/i);
+                if (utf8Match) {
+                    filename = decodeURIComponent(utf8Match[1]);
+                }
+                else {
+                    // 匹配 filename="xxx" 或 filename=xxx 格式
+                    const match = contentDisposition.match(/filename="?([^";\s]+)"?/i);
+                    if (match) {
+                        filename = decodeURIComponent(match[1]);
+                    }
+                }
+            }
+            this.logger.info('File downloaded successfully');
+            return { buffer: Buffer.from(response.data), filename };
+        }
+        catch (error) {
+            this.logger.error('File download failed:', error.message);
+            throw error;
+        }
+    }
+}
+
+/**
+ * 通用工具方法
+ */
+/**
+ * 生成随机字符串
+ *
+ * @param length - 随机字符串长度，默认 8
+ * @returns 随机字符串
+ */
+function generateRandomString(length = 8) {
+    return crypto.randomBytes(Math.ceil(length / 2)).toString('hex').substring(0, length);
+}
+/**
+ * 生成唯一请求 ID
+ *
+ * 格式：`{prefix}_{timestamp}_{random}`
+ *
+ * @param prefix - 前缀，通常为 cmd 名称
+ * @returns 唯一请求 ID
+ */
+function generateReqId(prefix) {
+    const timestamp = Date.now();
+    const random = generateRandomString();
+    return `${prefix}_${timestamp}_${random}`;
+}
+
+/** SDK 内置默认 WebSocket 连接地址 */
+const DEFAULT_WS_URL = 'wss://openws.work.weixin.qq.com';
+class WsConnectionManager {
+    constructor(logger, heartbeatInterval = 30000, reconnectBaseDelay = 1000, maxReconnectAttempts = 10, wsUrl, wsOptions, maxReplyQueueSize, maxAuthFailureAttempts) {
+        this.ws = null;
+        this.heartbeatTimer = null;
+        this.reconnectAttempts = 0;
+        this.authFailureAttempts = 0;
+        this.isManualClose = false;
+        /** 标记最近一次连接关闭是否因认证失败触发（用于 scheduleReconnect 区分重连类型） */
+        this.lastCloseWasAuthFailure = false;
+        /** 认证凭证 */
+        this.botId = '';
+        this.botSecret = '';
+        /** 额外的认证参数（如 scene、plug_version 等），会展开到认证帧 body 中 */
+        this.extraAuthParams = {};
+        /** Number of consecutive missed heartbeat acks (pong) */
+        this.missedPongCount = 0;
+        /** Max missed pong before treating connection as dead */
+        this.maxMissedPong = 2;
+        /** Base delay (ms) for exponential back-off reconnection */
+        this.reconnectBaseDelay = 1000;
+        /** Upper cap (ms) for reconnect delay */
+        this.reconnectMaxDelay = 30000;
+        /** 重连定时器引用，用于在 disconnect/connect 时取消挂起的重连 */
+        this.reconnectTimer = null;
+        /** 按 req_id 分组的回复发送队列，保证同一 req_id 的消息串行发送 */
+        this.replyQueues = new Map();
+        /** 正在等待回执的 req_id 集合，value 包含超时定时器、resolve/reject 和序列号 */
+        this.pendingAcks = new Map();
+        /** 自增序列号，用于区分同一 reqId 的不同 pending，防止超时与 ack 竞态 */
+        this.pendingAckSeq = 0;
+        /** 回执超时时间（毫秒） */
+        this.replyAckTimeout = 5000;
+        /** 单个 req_id 的回复队列最大长度，超过后新消息将被拒绝 */
+        this.maxReplyQueueSize = 500;
+        /** 连接建立回调（WebSocket open 事件，认证尚未完成） */
+        this.onConnected = null;
+        /** 认证成功回调 */
+        this.onAuthenticated = null;
+        /** 连接断开回调 */
+        this.onDisconnected = null;
+        /** 收到消息回调 */
+        this.onMessage = null;
+        /** 重连回调 */
+        this.onReconnecting = null;
+        /** 错误回调 */
+        this.onError = null;
+        /** 服务端主动断开回调（新连接建立导致旧连接被断开） */
+        this.onServerDisconnect = null;
+        this.logger = logger;
+        this.heartbeatInterval = heartbeatInterval;
+        this.reconnectBaseDelay = reconnectBaseDelay;
+        this.maxReconnectAttempts = maxReconnectAttempts;
+        this.maxAuthFailureAttempts = maxAuthFailureAttempts ?? 5;
+        this.wsUrl = wsUrl || DEFAULT_WS_URL;
+        this.wsOptions = wsOptions || {};
+        if (maxReplyQueueSize !== undefined) {
+            this.maxReplyQueueSize = maxReplyQueueSize;
+        }
+    }
+    /**
+     * 设置认证凭证
+     */
+    setCredentials(botId, botSecret, extraAuthParams) {
+        this.botId = botId;
+        this.botSecret = botSecret;
+        this.extraAuthParams = extraAuthParams || {};
+    }
+    /**
+     * 建立 WebSocket 连接（使用 SDK 内置默认地址）
+     */
+    connect() {
+        this.isManualClose = false;
+        // 取消挂起的重连定时器，防止与当前 connect 竞态
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // 清理可能未完全关闭的旧连接
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            this.ws.terminate();
+            this.ws = null;
+        }
+        this.logger.info(`Connecting to WebSocket: ${this.wsUrl}...`);
+        try {
+            this.ws = new WebSocket(this.wsUrl, this.wsOptions);
+            this.setupEventHandlers();
+        }
+        catch (error) {
+            this.logger.error('Failed to create WebSocket connection:', error.message);
+            this.onError?.(error);
+            this.scheduleReconnect();
+        }
+    }
+    /**
+     * 设置 WebSocket 事件处理器
+     */
+    setupEventHandlers() {
+        if (!this.ws)
+            return;
+        this.ws.on('open', () => {
+            this.logger.info('WebSocket connection established, sending auth...');
+            // 注意：不在 open 时重置 reconnectAttempts，因为 TCP 连接成功不代表认证会成功。
+            // 只有在认证成功后才重置所有计数器（见 handleFrame 中的认证响应处理）。
+            this.missedPongCount = 0;
+            this.lastCloseWasAuthFailure = false;
+            // 连接建立后立即发送认证帧
+            this.sendAuth();
+            this.onConnected?.();
+        });
+        this.ws.on('message', (data) => {
+            try {
+                const raw = data.toString().replace(/[\x00-\x08\x0B-\x0D\x0E-\x1F]/g, "");
+                const frame = JSON.parse(raw);
+                this.handleFrame(frame);
+            }
+            catch (error) {
+                this.logger.error('Failed to parse WebSocket message:', error.message);
+            }
+        });
+        this.ws.on('close', (code, reason) => {
+            const reasonStr = reason.toString() || `code: ${code}`;
+            this.logger.warn(`WebSocket connection closed: ${reasonStr}`);
+            this.stopHeartbeat();
+            this.clearPendingMessages(`WebSocket connection closed (${reasonStr})`);
+            this.onDisconnected?.(reasonStr);
+            // 释放旧 WebSocket 实例引用，便于 GC 回收
+            this.ws = null;
+            if (!this.isManualClose) {
+                this.scheduleReconnect();
+            }
+        });
+        this.ws.on('error', (error) => {
+            this.logger.error('WebSocket error:', error.message);
+            this.onError?.(error);
+        });
+        this.ws.on('ping', () => {
+            this.ws?.pong();
+        });
+    }
+    /**
+     * 发送认证帧
+     *
+     * 格式：{ cmd: "aibot_subscribe", headers: { req_id }, body: { secret, bot_id } }
+     */
+    sendAuth() {
+        try {
+            this.send({
+                cmd: WsCmd.SUBSCRIBE,
+                headers: { req_id: generateReqId(WsCmd.SUBSCRIBE) },
+                body: {
+                    bot_id: this.botId,
+                    secret: this.botSecret,
+                    ...this.extraAuthParams,
+                },
+            });
+            this.logger.info('Auth frame sent');
+        }
+        catch (error) {
+            this.logger.error('Failed to send auth frame:', error.message);
+        }
+    }
+    /**
+     * 处理收到的帧数据
+     *
+     * 接收帧结构：
+     * - 消息推送：{ cmd: "aibot_msg_callback", headers: { req_id }, body: { ... } }
+     * - 认证/心跳响应：{ headers: { req_id }, errcode: 0, errmsg: "ok" }
+     */
+    handleFrame(frame) {
+        const cmd = frame.cmd || '';
+        const reqId = frame.headers?.req_id || '';
+        // 消息推送：cmd 为 "aibot_msg_callback"
+        if (frame.cmd === WsCmd.CALLBACK) {
+            this.logger.debug(`[server -> plugin] cmd=${cmd}, reqId=${reqId}, body=${JSON.stringify(frame.body)}`);
+            this.onMessage?.(frame);
+            return;
+        }
+        // 事件推送：cmd 为 "aibot_event_callback"
+        if (frame.cmd === WsCmd.EVENT_CALLBACK) {
+            this.logger.debug(`[server -> plugin] cmd=${cmd}, reqId=${reqId}, body=${JSON.stringify(frame.body)}`);
+            // 检测 disconnected_event：有新连接建立，服务端通知旧连接即将被断开
+            if (frame.body?.event?.eventtype === 'disconnected_event') {
+                this.logger.warn('Received disconnected_event: a new connection has been established, this connection will be closed by server');
+                // 先分发事件给上层（让用户可以监听 event.disconnected_event）
+                this.onMessage?.(frame);
+                // 停止心跳、清理待处理消息
+                this.stopHeartbeat();
+                this.clearPendingMessages('Server disconnected due to new connection');
+                // 标记为非手动断开但阻止自动重连（服务端正常行为，重连也会被再次断开）
+                this.isManualClose = true;
+                // 通知上层服务端主动断开
+                this.onServerDisconnect?.('New connection established, server disconnected this connection');
+                // 主动关闭 socket，避免连接处于僵尸状态
+                if (this.ws) {
+                    this.ws.removeAllListeners();
+                    this.ws.terminate();
+                    this.ws = null;
+                }
+                return;
+            }
+            this.onMessage?.(frame);
+            return;
+        }
+        // 无 cmd 的帧：认证响应、心跳响应或回复消息回执，通过 req_id 前缀区分类型，再判断 errcode
+        const actualReqId = frame.headers?.req_id || '';
+        // 认证响应（优先于 pendingAcks 检查，避免误判）
+        if (actualReqId.startsWith(WsCmd.SUBSCRIBE)) {
+            if (frame.errcode !== 0) {
+                this.logger.error(`Authentication failed: errcode=${frame.errcode}, errmsg=${frame.errmsg}`);
+                this.onError?.(new Error(`Authentication failed: ${frame.errmsg} (code: ${frame.errcode})`));
+                // 标记为认证失败，close 事件中 scheduleReconnect 会据此使用 authFailureAttempts 计数器
+                this.lastCloseWasAuthFailure = true;
+                // 认证失败，主动关闭连接，触发 close 事件进而执行 scheduleReconnect 重连逻辑
+                if (this.ws) {
+                    this.ws.terminate();
+                }
+                return;
+            }
+            this.logger.info('Authentication successful');
+            // 认证成功：重置所有重连计数器
+            this.reconnectAttempts = 0;
+            this.authFailureAttempts = 0;
+            this.startHeartbeat();
+            this.onAuthenticated?.();
+            return;
+        }
+        // 心跳响应（优先于 pendingAcks 检查，避免误判）
+        if (actualReqId.startsWith(WsCmd.HEARTBEAT)) {
+            if (frame.errcode !== 0) {
+                this.logger.warn(`Heartbeat ack error: errcode=${frame.errcode}, errmsg=${frame.errmsg}`);
+                return;
+            }
+            this.missedPongCount = 0;
+            return;
+        }
+        // 检查是否是回复消息的回执（req_id 存在于 pendingAcks 中）
+        if (this.pendingAcks.has(actualReqId)) {
+            this.handleReplyAck(actualReqId, frame);
+            return;
+        }
+        // 未知帧类型 — 只记录警告，不传给 onMessage（避免 body=undefined 导致下游误处理）
+        this.logger.warn('Received unknown frame (ignored):', JSON.stringify(frame));
+    }
+    /**
+     * 启动心跳定时器
+     */
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            this.sendHeartbeat();
+        }, this.heartbeatInterval);
+        this.logger.debug(`Heartbeat timer started, interval: ${this.heartbeatInterval}ms`);
+    }
+    /**
+     * 停止心跳定时器
+     */
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+            this.logger.debug('Heartbeat timer stopped');
+        }
+    }
+    /**
+     * 发送心跳
+     * If consecutive missed pong count reaches the threshold, treat the
+     * connection as dead and trigger reconnection.
+     *
+     * 格式：{ cmd: "ping", headers: { req_id } }
+     */
+    sendHeartbeat() {
+        // Check missed pong BEFORE sending the next heartbeat
+        if (this.missedPongCount >= this.maxMissedPong) {
+            this.logger.warn(`No heartbeat ack received for ${this.missedPongCount} consecutive pings, connection considered dead`);
+            this.stopHeartbeat();
+            // Force-close the underlying socket so the 'close' handler fires
+            if (this.ws) {
+                this.ws.terminate();
+            }
+            return;
+        }
+        this.missedPongCount++;
+        try {
+            this.send({
+                cmd: WsCmd.HEARTBEAT,
+                headers: { req_id: generateReqId(WsCmd.HEARTBEAT) },
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to send heartbeat:', error.message);
+        }
+    }
+    /**
+     * 安排重连
+     *
+     * 区分两种重连场景，使用独立的计数器和最大重试次数：
+     * - 认证失败（lastCloseWasAuthFailure=true）：使用 authFailureAttempts / maxAuthFailureAttempts
+     * - 连接断开（lastCloseWasAuthFailure=false）：使用 reconnectAttempts / maxReconnectAttempts
+     *
+     * disconnected_event（被踢下线）不会触发重连，因为 isManualClose 已被设为 true。
+     */
+    scheduleReconnect() {
+        if (this.lastCloseWasAuthFailure) {
+            // 认证失败场景
+            if (this.maxAuthFailureAttempts !== -1 && this.authFailureAttempts >= this.maxAuthFailureAttempts) {
+                this.logger.error(`Max auth failure attempts reached (${this.maxAuthFailureAttempts}), giving up`);
+                this.onError?.(new WSAuthFailureError(this.maxAuthFailureAttempts));
+                return;
+            }
+            this.authFailureAttempts++;
+            const delay = Math.min(this.reconnectBaseDelay * Math.pow(2, this.authFailureAttempts - 1), this.reconnectMaxDelay);
+            this.logger.info(`Auth failed, reconnecting in ${delay}ms (auth attempt ${this.authFailureAttempts}/${this.maxAuthFailureAttempts})...`);
+            this.onReconnecting?.(this.authFailureAttempts);
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                if (this.isManualClose)
+                    return;
+                this.connect();
+            }, delay);
+        }
+        else {
+            // 连接断开场景（网络异常、心跳超时等）
+            if (this.maxReconnectAttempts !== -1 && this.reconnectAttempts >= this.maxReconnectAttempts) {
+                this.logger.error(`Max reconnect attempts reached (${this.maxReconnectAttempts}), giving up`);
+                this.onError?.(new WSReconnectExhaustedError(this.maxReconnectAttempts));
+                return;
+            }
+            this.reconnectAttempts++;
+            const delay = Math.min(this.reconnectBaseDelay * Math.pow(2, this.reconnectAttempts - 1), this.reconnectMaxDelay);
+            this.logger.info(`Connection lost, reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})...`);
+            this.onReconnecting?.(this.reconnectAttempts);
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                if (this.isManualClose)
+                    return;
+                this.connect();
+            }, delay);
+        }
+    }
+    /**
+     * 发送数据帧
+     *
+     * 统一格式：{ cmd, headers: { req_id }, body }
+     */
+    send(frame) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            const data = JSON.stringify(frame);
+            this.ws.send(data);
+        }
+        else {
+            throw new Error('WebSocket not connected, unable to send data');
+        }
+    }
+    /**
+     * 通过 WebSocket 通道发送回复消息（串行队列版本）
+     *
+     * 同一个 req_id 的消息会被放入队列中串行发送：
+     * 发送一条后等待服务端回执，收到回执或超时后才发送下一条。
+     *
+     * 格式：{ cmd: "aibot_respond_msg", headers: { req_id }, body: { ... } }
+     *
+     * @param reqId - 透传回调中的 req_id
+     * @param body - 回复消息体（如 StreamReplyBody）
+     * @param cmd - 发送的命令类型，默认 WsCmd.RESPONSE
+     * @returns Promise，收到回执时 resolve(回执帧)，超时或errcode非0时 reject(Error)
+     */
+    sendReply(reqId, body, cmd = WsCmd.RESPONSE) {
+        // // 日志中截断 base64_data，避免分片上传时日志过大
+        // const logBody = body?.base64_data
+        //   ? { ...body, base64_data: `<${body.base64_data.length} chars>` }
+        //   : body;
+        // this.logger.debug(`[ws] sendReply: reqId=${reqId}, cmd=${cmd}, body=${JSON.stringify(logBody)}`);
+        return new Promise((resolve, reject) => {
+            const frame = {
+                cmd,
+                headers: { req_id: reqId },
+                body,
+            };
+            const item = { frame, resolve, reject };
+            // 入队
+            if (!this.replyQueues.has(reqId)) {
+                this.replyQueues.set(reqId, []);
+            }
+            const queue = this.replyQueues.get(reqId);
+            // 防止队列无限增长导致内存泄漏
+            if (queue.length >= this.maxReplyQueueSize) {
+                this.logger.warn(`Reply queue for reqId ${reqId} exceeds max size (${this.maxReplyQueueSize}), rejecting new message`);
+                reject(new Error(`Reply queue for reqId ${reqId} exceeds max size (${this.maxReplyQueueSize})`));
+                return;
+            }
+            queue.push(item);
+            // 如果队列中只有这一条，说明当前空闲，立即开始处理
+            if (queue.length === 1) {
+                this.processReplyQueue(reqId);
+            }
+        });
+    }
+    /**
+     * 处理指定 req_id 的回复队列
+     * 取出队列头部的消息发送，并设置回执超时
+     */
+    processReplyQueue(reqId) {
+        const queue = this.replyQueues.get(reqId);
+        if (!queue || queue.length === 0) {
+            // 队列为空，清理
+            this.replyQueues.delete(reqId);
+            return;
+        }
+        const item = queue[0];
+        try {
+            // 发送帧
+            this.send(item.frame);
+            this.logger.debug(`Reply message sent via WebSocket, reqId: ${reqId}, queue length: ${queue.length}`);
+        }
+        catch (error) {
+            this.logger.error(`Failed to send reply for reqId ${reqId}:`, error.message);
+            // 发送失败：reject 当前项，用 queueMicrotask 异步继续处理下一条，避免同步递归栈溢出
+            queue.shift();
+            item.reject(error);
+            queueMicrotask(() => this.processReplyQueue(reqId));
+            return;
+        }
+        // 分配唯一序列号，用于超时回调中校验是否是当前 pending
+        const seq = ++this.pendingAckSeq;
+        // 设置回执超时定时器
+        const timer = setTimeout(() => {
+            // 校验 seq：如果不匹配，说明这是过期的超时回调（当前 pending 已被正常 ack 处理过），直接忽略
+            const currentPending = this.pendingAcks.get(reqId);
+            if (!currentPending || currentPending.seq !== seq) {
+                return;
+            }
+            this.logger.warn(`Reply ack timeout (${this.replyAckTimeout}ms) for reqId: ${reqId}`);
+            this.pendingAcks.delete(reqId);
+            // 超时：reject 当前项，然后继续处理队列中的下一条
+            queue.shift();
+            item.reject(new Error(`Reply ack timeout (${this.replyAckTimeout}ms) for reqId: ${reqId}`));
+            this.processReplyQueue(reqId);
+        }, this.replyAckTimeout);
+        // 注册到待回执 Map
+        this.pendingAcks.set(reqId, {
+            resolve: item.resolve,
+            reject: item.reject,
+            timer,
+            seq,
+        });
+    }
+    /**
+     * 处理回复消息的回执
+     * 收到回执后释放队列锁，继续处理下一条
+     */
+    handleReplyAck(reqId, frame) {
+        const pending = this.pendingAcks.get(reqId);
+        if (!pending)
+            return;
+        // 清除超时定时器
+        clearTimeout(pending.timer);
+        this.pendingAcks.delete(reqId);
+        const queue = this.replyQueues.get(reqId);
+        if (frame.errcode !== 0) {
+            this.logger.warn(`Reply ack error: reqId=${reqId}, errcode=${frame.errcode}, errmsg=${frame.errmsg}`);
+            // 失败：reject 当前项
+            if (queue) {
+                queue.shift();
+            }
+            pending.reject(frame);
+        }
+        else {
+            this.logger.debug(`Reply ack received for reqId: ${reqId}`);
+            // 成功：resolve 当前项，传入完整回执帧
+            if (queue) {
+                queue.shift();
+            }
+            pending.resolve(frame);
+        }
+        // 继续处理队列中的下一条
+        this.processReplyQueue(reqId);
+    }
+    /**
+     * 主动断开连接
+     */
+    /**
+     * 清理所有待处理的消息和回执
+     * @param reason - 清理原因，用于 reject 的错误信息
+     */
+    clearPendingMessages(reason) {
+        // 收集所有已在 pendingAcks 中的 reject 函数引用，用于后续去重
+        const pendingRejects = new Set();
+        // 先清理 pendingAcks：清除定时器并 reject 正在等待回执的消息
+        for (const [reqId, pending] of this.pendingAcks) {
+            clearTimeout(pending.timer);
+            pendingRejects.add(pending.reject);
+            pending.reject(new Error(`${reason}, reply for reqId: ${reqId} cancelled`));
+        }
+        this.pendingAcks.clear();
+        // 再清理 replyQueues：跳过已经在 pendingAcks 中被 reject 过的队首 item，避免双重 reject
+        for (const [reqId, queue] of this.replyQueues) {
+            for (const item of queue) {
+                if (pendingRejects.has(item.reject)) {
+                    continue; // 已在 pendingAcks 中被 reject 过，跳过
+                }
+                item.reject(new Error(`${reason}, reply for reqId: ${reqId} cancelled`));
+            }
+        }
+        this.replyQueues.clear();
+    }
+    disconnect() {
+        this.isManualClose = true;
+        this.stopHeartbeat();
+        this.clearPendingMessages('Connection manually closed');
+        // 取消挂起的重连定时器
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.terminate();
+            this.ws = null;
+        }
+        this.logger.info('WebSocket connection manually closed');
+    }
+    /**
+     * 检查指定 reqId 是否有待回执的消息（即上一条消息还未收到 ack）
+     *
+     * 用于流式场景：调用方可据此决定是否跳过当前帧，避免排队积压。
+     *
+     * @param reqId - 要检查的 req_id
+     * @returns true 表示有消息正在等待 ack
+     */
+    hasPendingAck(reqId) {
+        return this.pendingAcks.has(reqId);
+    }
+    /**
+     * 获取当前连接状态
+     */
+    get isConnected() {
+        return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+    }
+}
+
+/**
+ * 消息处理器
+ * 负责解析 WebSocket 帧并分发为具体的消息事件和事件回调
+ */
+class MessageHandler {
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * 处理收到的 WebSocket 帧，解析并触发对应的消息/事件
+     *
+     * WebSocket 推送帧结构：
+     * - 消息推送：{ cmd: "aibot_msg_callback", headers: { req_id: "xxx" }, body: { msgid, msgtype, ... } }
+     * - 事件推送：{ cmd: "aibot_event_callback", headers: { req_id: "xxx" }, body: { msgid, msgtype: "event", event: { ... } } }
+     *
+     * @param frame - WebSocket 接收帧
+     * @param emitter - WSClient 实例，用于触发事件
+     */
+    handleFrame(frame, emitter) {
+        try {
+            const body = frame.body;
+            if (!body || !body.msgtype) {
+                this.logger.warn('Received invalid message format:', JSON.stringify(frame).substring(0, 200));
+                return;
+            }
+            // 事件推送回调处理
+            if (frame.cmd === WsCmd.EVENT_CALLBACK) {
+                this.handleEventCallback(frame, emitter);
+                return;
+            }
+            // 消息推送回调处理
+            this.handleMessageCallback(frame, emitter);
+        }
+        catch (error) {
+            this.logger.error('Failed to handle message:', error.message);
+        }
+    }
+    /**
+     * 处理消息推送回调 (aibot_msg_callback)
+     */
+    handleMessageCallback(frame, emitter) {
+        const body = frame.body;
+        // 触发通用消息事件
+        emitter.emit('message', frame);
+        // 根据 body 中的消息类型触发特定事件
+        switch (body.msgtype) {
+            case exports.MessageType.Text:
+                emitter.emit('message.text', frame);
+                break;
+            case exports.MessageType.Image:
+                emitter.emit('message.image', frame);
+                break;
+            case exports.MessageType.Mixed:
+                emitter.emit('message.mixed', frame);
+                break;
+            case exports.MessageType.Voice:
+                emitter.emit('message.voice', frame);
+                break;
+            case exports.MessageType.File:
+                emitter.emit('message.file', frame);
+                break;
+            case exports.MessageType.Video:
+                emitter.emit('message.video', frame);
+                break;
+            default:
+                this.logger.debug(`Received unhandled message type: ${body.msgtype}`);
+                break;
+        }
+    }
+    /**
+     * 处理事件推送回调 (aibot_event_callback)
+     */
+    handleEventCallback(frame, emitter) {
+        const body = frame.body;
+        // 触发通用事件
+        emitter.emit('event', frame);
+        // 根据事件类型触发特定事件
+        const eventType = body.event?.eventtype;
+        if (eventType) {
+            const eventKey = `event.${eventType}`;
+            emitter.emit(eventKey, frame);
+        }
+        else {
+            this.logger.debug('Received event callback without eventtype:', JSON.stringify(body).substring(0, 200));
+        }
+    }
+}
+
+/**
+ * 加解密工具模块
+ * 提供文件加解密相关的功能函数
+ */
+/**
+ * 使用 AES-256-CBC 解密文件
+ *
+ * @param encryptedBuffer - 加密的文件数据
+ * @param aesKey - Base64 编码的 AES-256 密钥
+ * @returns 解密后的文件 Buffer
+ */
+function decryptFile(encryptedBuffer, aesKey) {
+    // 参数验证
+    if (!encryptedBuffer || encryptedBuffer.length === 0) {
+        throw new Error('decryptFile: encryptedBuffer is empty or not provided');
+    }
+    if (!aesKey || typeof aesKey !== 'string') {
+        throw new Error('decryptFile: aesKey must be a non-empty string');
+    }
+    // 将 Base64 编码的 aesKey 解码为 Buffer
+    const key = Buffer.from(aesKey, 'base64');
+    // IV 取 aesKey 解码后的前 16 字节
+    const iv = key.subarray(0, 16);
+    try {
+        const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
+        // 关闭自动 padding，因为文档要求 PKCS#7 填充至 32 字节的倍数，
+        // 而 Node.js 默认按 16 字节 block 去除 padding，会导致 bad decrypt 错误
+        decipher.setAutoPadding(false);
+        const decrypted = Buffer.concat([
+            decipher.update(encryptedBuffer),
+            decipher.final(),
+        ]);
+        // 手动去除 PKCS#7 填充（支持 32 字节 block）
+        const padLen = decrypted[decrypted.length - 1];
+        if (padLen < 1 || padLen > 32 || padLen > decrypted.length) {
+            throw new Error(`Invalid PKCS#7 padding value: ${padLen}`);
+        }
+        // 验证所有 padding 字节是否一致
+        for (let i = decrypted.length - padLen; i < decrypted.length; i++) {
+            if (decrypted[i] !== padLen) {
+                throw new Error('Invalid PKCS#7 padding: padding bytes mismatch');
+            }
+        }
+        return decrypted.subarray(0, decrypted.length - padLen);
+    }
+    catch (error) {
+        throw new Error(`decryptFile: Decryption failed - ${error.message}. This may indicate corrupted data or an incorrect aesKey.`);
+    }
+}
+
+/**
+ * 默认日志实现
+ * 带有日志级别和时间戳的控制台日志
+ */
+class DefaultLogger {
+    constructor(prefix = 'AiBotSDK') {
+        this.prefix = prefix;
+    }
+    formatTime() {
+        return new Date().toISOString();
+    }
+    debug(message, ...args) {
+        console.debug(`[${this.formatTime()}] [${this.prefix}] [DEBUG] ${message}`, ...args);
+    }
+    info(message, ...args) {
+        console.info(`[${this.formatTime()}] [${this.prefix}] [INFO] ${message}`, ...args);
+    }
+    warn(message, ...args) {
+        console.warn(`[${this.formatTime()}] [${this.prefix}] [WARN] ${message}`, ...args);
+    }
+    error(message, ...args) {
+        console.error(`[${this.formatTime()}] [${this.prefix}] [ERROR] ${message}`, ...args);
+    }
+}
+
+class WSClient extends eventemitter3.EventEmitter {
+    constructor(options) {
+        super();
+        this.started = false;
+        // 合并默认选项
+        this.options = {
+            reconnectInterval: 1000,
+            maxReconnectAttempts: 10,
+            maxAuthFailureAttempts: 5,
+            heartbeatInterval: 30000,
+            requestTimeout: 10000,
+            wsUrl: '',
+            wsOptions: {},
+            maxReplyQueueSize: 500,
+            logger: new DefaultLogger(),
+            ...options,
+        };
+        this.logger = this.options.logger;
+        // 初始化 API 客户端（仅用于文件下载）
+        this.apiClient = new WeComApiClient(this.logger, this.options.requestTimeout);
+        // 初始化 WebSocket 管理器
+        this.wsManager = new WsConnectionManager(this.logger, this.options.heartbeatInterval, this.options.reconnectInterval, this.options.maxReconnectAttempts, this.options.wsUrl || undefined, this.options.wsOptions, this.options.maxReplyQueueSize, this.options.maxAuthFailureAttempts);
+        // 设置认证凭证
+        this.wsManager.setCredentials(this.options.botId, this.options.secret, {
+            ...(this.options.scene !== undefined && { scene: this.options.scene }),
+            ...(this.options.plug_version !== undefined && { plug_version: this.options.plug_version }),
+        });
+        // 初始化消息处理器
+        this.messageHandler = new MessageHandler(this.logger);
+        // 绑定 WebSocket 事件
+        this.setupWsEvents();
+    }
+    /**
+     * 设置 WebSocket 事件处理
+     */
+    setupWsEvents() {
+        this.wsManager.onConnected = () => {
+            this.emit('connected');
+        };
+        // 认证成功
+        this.wsManager.onAuthenticated = () => {
+            this.logger.info('Authenticated');
+            this.emit('authenticated');
+        };
+        this.wsManager.onDisconnected = (reason) => {
+            this.emit('disconnected', reason);
+        };
+        // 服务端因新连接建立而主动断开旧连接
+        this.wsManager.onServerDisconnect = (reason) => {
+            this.logger.warn(`Server disconnected this connection: ${reason}`);
+            this.started = false;
+            this.emit('disconnected', reason);
+        };
+        this.wsManager.onReconnecting = (attempt) => {
+            this.emit('reconnecting', attempt);
+        };
+        this.wsManager.onError = (error) => {
+            this.emit('error', error);
+        };
+        this.wsManager.onMessage = (frame) => {
+            this.messageHandler.handleFrame(frame, this);
+        };
+    }
+    /**
+     * 建立 WebSocket 长连接
+     * SDK 使用内置默认地址建立连接，连接成功后自动发送认证帧（botId + secret）。
+     * 支持链式调用：wsClient.connect().on('message', handler)
+     *
+     * @returns 返回 this，支持链式调用
+     */
+    connect() {
+        if (this.started) {
+            this.logger.warn('Client already connected');
+            return this;
+        }
+        this.logger.info('Establishing WebSocket connection...');
+        this.started = true;
+        // 直接使用内置默认地址建立连接，连接成功后自动认证
+        this.wsManager.connect();
+        return this;
+    }
+    /**
+     * 断开 WebSocket 连接
+     */
+    disconnect() {
+        if (!this.started) {
+            this.logger.warn('Client not connected');
+            return;
+        }
+        this.logger.info('Disconnecting...');
+        this.started = false;
+        this.wsManager.disconnect();
+        this.logger.info('Disconnected');
+    }
+    /**
+     * 通过 WebSocket 通道发送回复消息（通用方法）
+     *
+     * @param frame - 收到的原始 WebSocket 帧，透传 headers.req_id
+     * @param body - 回复消息体
+     * @param cmd
+     */
+    reply(frame, body, cmd) {
+        const reqId = frame.headers?.req_id || '';
+        return this.wsManager.sendReply(reqId, body, cmd);
+    }
+    /**
+     * 发送流式文本回复（便捷方法）
+     *
+     * @param frame - 收到的原始 WebSocket 帧，透传 headers.req_id
+     * @param streamId - 流式消息 ID
+     * @param content - 回复内容（支持 Markdown）
+     * @param finish - 是否结束流式消息，默认 false
+     * @param msgItem - 图文混排项（仅在 finish=true 时有效），用于在结束时附带图片内容
+     * @param feedback - 反馈信息（仅在首次回复时设置）
+     */
+    replyStream(frame, streamId, content, finish = false, msgItem, feedback) {
+        const stream = {
+            id: streamId,
+            finish,
+            content,
+        };
+        // msg_item 仅在 finish=true 时支持
+        if (finish && msgItem && msgItem.length > 0) {
+            stream.msg_item = msgItem;
+        }
+        // feedback 仅在首次回复时设置
+        if (feedback) {
+            stream.feedback = feedback;
+        }
+        return this.reply(frame, {
+            msgtype: 'stream',
+            stream,
+        });
+    }
+    /**
+     * 发送欢迎语回复
+     *
+     * 注意：此方法需要使用对应事件（如 enter_chat）的 req_id 才能调用，
+     * 即 frame 参数应来自触发欢迎语的事件帧。
+     * 收到事件回调后需在 5 秒内发送回复，超时将无法发送欢迎语。
+     *
+     * @param frame - 对应事件的 WebSocket 帧（需包含该事件的 req_id）
+     * @param body - 欢迎语消息体（支持文本或模板卡片格式）
+     */
+    replyWelcome(frame, body) {
+        return this.reply(frame, body, WsCmd.RESPONSE_WELCOME);
+    }
+    /**
+     * 回复模板卡片消息
+     *
+     * 收到消息回调或进入会话事件后，可使用此方法回复模板卡片消息。
+     *
+     * @param frame - 收到的原始 WebSocket 帧，透传 headers.req_id
+     * @param templateCard - 模板卡片内容
+     * @param feedback - 反馈信息
+     */
+    replyTemplateCard(frame, templateCard, feedback) {
+        const card = feedback ? { ...templateCard, feedback } : templateCard;
+        const body = {
+            msgtype: 'template_card',
+            template_card: card,
+        };
+        return this.reply(frame, body);
+    }
+    /**
+     * 发送流式消息 + 模板卡片组合回复
+     *
+     * 首次回复时必须返回 stream 的 id。
+     * template_card 可首次回复，也可在后续回复中发送，但同一个消息只能回复一次。
+     *
+     * @param frame - 收到的原始 WebSocket 帧，透传 headers.req_id
+     * @param streamId - 流式消息 ID
+     * @param content - 回复内容（支持 Markdown）
+     * @param finish - 是否结束流式消息，默认 false
+     * @param options - 可选项
+     * @param options.msgItem - 图文混排项（仅在 finish=true 时有效）
+     * @param options.streamFeedback - 流式消息反馈信息（首次回复时设置）
+     * @param options.templateCard - 模板卡片内容（同一消息只能回复一次）
+     * @param options.cardFeedback - 模板卡片反馈信息
+     */
+    replyStreamWithCard(frame, streamId, content, finish = false, options) {
+        const stream = {
+            id: streamId,
+            finish,
+            content,
+        };
+        if (finish && options?.msgItem && options.msgItem.length > 0) {
+            stream.msg_item = options.msgItem;
+        }
+        if (options?.streamFeedback) {
+            stream.feedback = options.streamFeedback;
+        }
+        const body = {
+            msgtype: 'stream_with_template_card',
+            stream,
+        };
+        if (options?.templateCard) {
+            body.template_card = options.cardFeedback
+                ? { ...options.templateCard, feedback: options.cardFeedback }
+                : options.templateCard;
+        }
+        return this.reply(frame, body);
+    }
+    /**
+     * 更新模板卡片
+     *
+     * 注意：此方法需要使用对应事件（template_card_event）的 req_id 才能调用，
+     * 即 frame 参数应来自触发更新的事件帧。
+     * 收到事件回调后需在 5 秒内发送回复，超时将无法更新卡片。
+     *
+     * @param frame - 对应事件的 WebSocket 帧（需包含该事件的 req_id）
+     * @param templateCard - 模板卡片内容（task_id 需跟回调收到的 task_id 一致）
+     * @param userids - 要替换模版卡片消息的 userid 列表，若不填则替换所有用户
+     */
+    updateTemplateCard(frame, templateCard, userids) {
+        const body = {
+            response_type: 'update_template_card',
+            template_card: templateCard,
+        };
+        if (userids && userids.length > 0) {
+            body.userids = userids;
+        }
+        return this.reply(frame, body, WsCmd.RESPONSE_UPDATE);
+    }
+    /**
+     * 主动发送消息
+     *
+     * 向指定会话（单聊或群聊）主动推送消息，无需依赖收到的回调帧。
+     *
+     * @param chatid - 会话 ID，单聊填用户的 userid，群聊填对应群聊的 chatid
+     * @param body - 消息体（支持 markdown 或 template_card 格式）
+     * @returns Promise，收到回执时 resolve(回执帧)
+     *
+     * @example
+     * ```ts
+     * // 发送 markdown 消息
+     * await wsClient.sendMessage('CHATID', {
+     *   msgtype: 'markdown',
+     *   markdown: { content: '这是一条**主动推送**的消息' },
+     * });
+     *
+     * // 发送模板卡片消息
+     * await wsClient.sendMessage('CHATID', {
+     *   msgtype: 'template_card',
+     *   template_card: { card_type: 'text_notice', ... },
+     * });
+     * ```
+     */
+    sendMessage(chatid, body) {
+        const reqId = generateReqId(WsCmd.SEND_MSG);
+        const fullBody = {
+            chatid,
+            ...body,
+        };
+        return this.wsManager.sendReply(reqId, fullBody, WsCmd.SEND_MSG);
+    }
+    /**
+     * 上传临时素材（三步分片上传）
+     *
+     * 通过 WebSocket 长连接执行分片上传：init → chunk × N → finish
+     * 单个分片不超过 512KB（Base64 编码前），最多 100 个分片。
+     *
+     * @param fileBuffer - 文件 Buffer
+     * @param options - 上传选项（类型、文件名）
+     * @returns 上传结果，包含 media_id
+     */
+    async uploadMedia(fileBuffer, options) {
+        const { type, filename } = options;
+        const totalSize = fileBuffer.length;
+        // 分片大小：512KB（Base64 编码前）
+        const CHUNK_SIZE = 512 * 1024;
+        const totalChunks = Math.ceil(totalSize / CHUNK_SIZE);
+        if (totalChunks > 100) {
+            throw new Error(`File too large: ${totalChunks} chunks exceeds maximum of 100 chunks (max ~50MB)`);
+        }
+        // 计算文件 MD5
+        const md5 = crypto.createHash('md5').update(fileBuffer).digest('hex');
+        this.logger.info(`Uploading media: type=${type}, filename=${filename}, size=${totalSize}, chunks=${totalChunks}`);
+        // Step 1: 初始化上传
+        const initReqId = generateReqId(WsCmd.UPLOAD_MEDIA_INIT);
+        const initResult = await this.wsManager.sendReply(initReqId, { type, filename, total_size: totalSize, total_chunks: totalChunks, md5 }, WsCmd.UPLOAD_MEDIA_INIT);
+        const uploadId = initResult.body?.upload_id;
+        if (!uploadId) {
+            throw new Error(`Upload init failed: no upload_id returned. Response: ${JSON.stringify(initResult)}`);
+        }
+        this.logger.info(`Upload init success: upload_id=${uploadId}`);
+        // Step 2: 分片上传（带重试，根据分片数动态调整并发）
+        /** 单分片最大重试次数 */
+        const MAX_CHUNK_RETRIES = 2;
+        /**
+         * 动态计算并发数：
+         * - 1~4 分片（≤2MB）：全部并发
+         * - 5~10 分片（2~5MB）：并发 3
+         * - >10 分片（>5MB）：并发 2（企微后端对大量并发 chunk 会返回 system error）
+         */
+        const MAX_CONCURRENCY = totalChunks <= 4 ? totalChunks : totalChunks <= 10 ? 3 : 2;
+        const uploadChunk = async (chunkIndex) => {
+            const start = chunkIndex * CHUNK_SIZE;
+            const end = Math.min(start + CHUNK_SIZE, totalSize);
+            const chunk = fileBuffer.subarray(start, end);
+            const base64Data = chunk.toString('base64');
+            let lastError;
+            for (let attempt = 0; attempt <= MAX_CHUNK_RETRIES; attempt++) {
+                try {
+                    const chunkReqId = generateReqId(WsCmd.UPLOAD_MEDIA_CHUNK);
+                    await this.wsManager.sendReply(chunkReqId, { upload_id: uploadId, chunk_index: chunkIndex, base64_data: base64Data }, WsCmd.UPLOAD_MEDIA_CHUNK);
+                    this.logger.debug(`Uploaded chunk ${chunkIndex + 1}/${totalChunks} (${chunk.length} bytes)`);
+                    return;
+                }
+                catch (err) {
+                    lastError = err;
+                    if (attempt < MAX_CHUNK_RETRIES) {
+                        const delay = 500 * (attempt + 1);
+                        this.logger.warn(`Chunk ${chunkIndex} upload failed (attempt ${attempt + 1}/${MAX_CHUNK_RETRIES + 1}), ` +
+                            `retrying in ${delay}ms... error: ${err instanceof Error ? err.message : JSON.stringify(err)}`);
+                        await new Promise(r => setTimeout(r, delay));
+                    }
+                }
+            }
+            // 所有重试都失败
+            const errMsg = lastError instanceof Error
+                ? lastError.message
+                : JSON.stringify(lastError);
+            throw new Error(`Chunk ${chunkIndex} upload failed after ${MAX_CHUNK_RETRIES + 1} attempts: ${errMsg}`);
+        };
+        this.logger.debug(`Upload concurrency: ${MAX_CONCURRENCY} workers for ${totalChunks} chunks`);
+        if (totalChunks <= 1) {
+            // 单分片直接上传
+            await uploadChunk(0);
+        }
+        else {
+            // 多分片并发上传：动态并发数
+            let nextIndex = 0;
+            const errors = [];
+            const runWorker = async () => {
+                while (nextIndex < totalChunks) {
+                    const idx = nextIndex++;
+                    try {
+                        await uploadChunk(idx);
+                    }
+                    catch (err) {
+                        errors.push(err instanceof Error ? err : new Error(String(err)));
+                    }
+                }
+            };
+            const workerCount = Math.min(MAX_CONCURRENCY, totalChunks);
+            await Promise.all(Array.from({ length: workerCount }, () => runWorker()));
+            if (errors.length > 0) {
+                throw new Error(`Upload failed: ${errors.length} chunk(s) failed. First error: ${errors[0].message}`);
+            }
+        }
+        this.logger.info(`All ${totalChunks} chunks uploaded, finishing...`);
+        // Step 3: 完成上传
+        const finishReqId = generateReqId(WsCmd.UPLOAD_MEDIA_FINISH);
+        const finishResult = await this.wsManager.sendReply(finishReqId, { upload_id: uploadId }, WsCmd.UPLOAD_MEDIA_FINISH);
+        const mediaId = finishResult.body?.media_id;
+        if (!mediaId) {
+            throw new Error(`Upload finish failed: no media_id returned. Response: ${JSON.stringify(finishResult)}`);
+        }
+        this.logger.info(`Upload complete: media_id=${mediaId}, type=${finishResult.body?.type}`);
+        return {
+            type: finishResult.body?.type ?? type,
+            media_id: mediaId,
+            created_at: finishResult.body?.created_at ?? new Date().toISOString(),
+        };
+    }
+    /**
+     * 被动回复媒体消息（便捷方法）
+     *
+     * 通过 aibot_respond_msg 被动回复通道发送媒体消息（file/image/voice/video）
+     *
+     * @param frame - 收到的原始 WebSocket 帧，透传 headers.req_id
+     * @param mediaType - 媒体类型
+     * @param mediaId - 临时素材 media_id
+     * @param videoOptions - 视频消息可选参数（仅 mediaType='video' 时生效）
+     */
+    replyMedia(frame, mediaType, mediaId, videoOptions) {
+        const mediaContent = { media_id: mediaId };
+        if (mediaType === 'video' && videoOptions) {
+            if (videoOptions.title)
+                mediaContent.title = videoOptions.title;
+            if (videoOptions.description)
+                mediaContent.description = videoOptions.description;
+        }
+        const body = {
+            msgtype: mediaType,
+            [mediaType]: mediaContent,
+        };
+        return this.reply(frame, body);
+    }
+    /**
+     * 主动发送媒体消息（便捷方法）
+     *
+     * 通过 aibot_send_msg 主动推送通道发送媒体消息
+     *
+     * @param chatid - 会话 ID
+     * @param mediaType - 媒体类型
+     * @param mediaId - 临时素材 media_id
+     * @param videoOptions - 视频消息可选参数（仅 mediaType='video' 时生效）
+     */
+    sendMediaMessage(chatid, mediaType, mediaId, videoOptions) {
+        const mediaContent = { media_id: mediaId };
+        if (mediaType === 'video' && videoOptions) {
+            if (videoOptions.title)
+                mediaContent.title = videoOptions.title;
+            if (videoOptions.description)
+                mediaContent.description = videoOptions.description;
+        }
+        const body = {
+            msgtype: mediaType,
+            [mediaType]: mediaContent,
+        };
+        return this.sendMessage(chatid, body);
+    }
+    /**
+     * 下载文件并使用 AES 密钥解密
+     *
+     * @param url - 文件下载地址
+     * @param aesKey - AES 解密密钥（Base64 编码），取自消息中 image.aeskey 或 file.aeskey 字段
+     * @returns 解密后的文件 Buffer 及文件名
+     *
+     * @example
+     * ```ts
+     * // aesKey 来自消息体中的 image.aeskey 或 file.aeskey
+     * const { buffer, filename } = await wsClient.downloadFile(imageUrl, body.image?.aeskey);
+     * ```
+     */
+    async downloadFile(url, aesKey) {
+        this.logger.debug(`[plugin] downloadFile: url=${url}, hasAesKey=${!!aesKey}`);
+        this.logger.info('Downloading and decrypting file...');
+        try {
+            // 下载加密的文件数据
+            const { buffer: encryptedBuffer, filename } = await this.apiClient.downloadFileRaw(url);
+            // 如果没有提供 aesKey，直接返回原始数据
+            if (!aesKey) {
+                this.logger.warn('No aesKey provided, returning raw file data');
+                return { buffer: encryptedBuffer, filename };
+            }
+            // 使用独立的解密模块进行 AES-256-CBC 解密
+            const decryptedBuffer = decryptFile(encryptedBuffer, aesKey);
+            this.logger.info('File downloaded and decrypted successfully');
+            return { buffer: decryptedBuffer, filename };
+        }
+        catch (error) {
+            this.logger.error('File download/decrypt failed:', error.message);
+            throw error;
+        }
+    }
+    /**
+     * 检查指定消息帧是否有未完成的 ack（即上一条消息还未收到回执）
+     *
+     * 用于流式场景：调用方可据此决定是否跳过当前中间帧，避免排队积压。
+     *
+     * @param frame - 收到的原始 WebSocket 帧
+     * @returns true 表示有消息正在等待 ack
+     */
+    hasPendingReplyAck(frame) {
+        const reqId = frame.headers?.req_id || '';
+        return this.wsManager.hasPendingAck(reqId);
+    }
+    /**
+     * 非阻塞流式文本回复
+     *
+     * 如果上一条同 reqId 的消息尚未收到 ack，则跳过本次发送（返回 'skipped'），
+     * 避免流式中间帧排队积压导致延迟。
+     *
+     * 注意：finish=true 的最终帧不受此限制，始终保证发送（走正常队列）。
+     *
+     * @param frame - 收到的原始 WebSocket 帧
+     * @param streamId - 流式消息 ID
+     * @param content - 回复内容
+     * @param finish - 是否结束流式消息
+     * @param msgItem - 图文混排项（仅在 finish=true 时有效），用于在结束时附带图片内容
+     * @param feedback - 反馈信息（仅在首次回复时设置）
+     * @returns Promise<WsFrame> 正常发送时返回回执帧，跳过时返回 'skipped'
+     */
+    replyStreamNonBlocking(frame, streamId, content, finish = false, msgItem, feedback) {
+        // finish=true 的最终帧必须发送，不做跳过判断
+        if (!finish && this.hasPendingReplyAck(frame)) {
+            return Promise.resolve('skipped');
+        }
+        return this.replyStream(frame, streamId, content, finish, msgItem, feedback);
+    }
+    /**
+     * 获取当前连接状态
+     */
+    get isConnected() {
+        return this.wsManager.isConnected;
+    }
+    /**
+     * 获取 API 客户端实例（供高级用途使用，如文件下载）
+     */
+    get api() {
+        return this.apiClient;
+    }
+}
+
+/**
+ * WeCom 加解密通用核心
+ * 独立于 Webhook、WebSocket、Agent 的具体协议形态，统一提供基于 AES-256-CBC
+ * 的加解密与 SHA1 签名计算能力。
+ */
+const CRYPTO_CONSTANTS = {
+    /** PKCS#7 块大小 */
+    PKCS7_BLOCK_SIZE: 32,
+    /** AES Key 长度 */
+    AES_KEY_LENGTH: 32,
+};
+/**
+ * 解码企业微信提供的 Base64 encodingAESKey
+ */
+function decodeEncodingAESKey(encodingAESKey) {
+    const trimmed = encodingAESKey.trim();
+    if (!trimmed)
+        throw new Error("encodingAESKey missing");
+    const withPadding = trimmed.endsWith("=") ? trimmed : `${trimmed}=`;
+    const key = Buffer.from(withPadding, "base64");
+    if (key.length !== CRYPTO_CONSTANTS.AES_KEY_LENGTH) {
+        throw new Error(`invalid encodingAESKey (expected ${CRYPTO_CONSTANTS.AES_KEY_LENGTH} bytes, got ${key.length})`);
+    }
+    return key;
+}
+/**
+ * PKCS#7 填充
+ */
+function pkcs7Pad(buf, blockSize) {
+    const mod = buf.length % blockSize;
+    const pad = mod === 0 ? blockSize : blockSize - mod;
+    const padByte = Buffer.alloc(1, pad);
+    return Buffer.concat([buf, Buffer.alloc(pad, padByte[0])]);
+}
+/**
+ * PKCS#7 解除填充
+ */
+function pkcs7Unpad(buf, blockSize) {
+    if (buf.length === 0)
+        throw new Error("invalid pkcs7 payload");
+    const pad = buf[buf.length - 1];
+    if (pad < 1 || pad > blockSize) {
+        throw new Error("invalid pkcs7 padding value");
+    }
+    if (pad > buf.length) {
+        throw new Error("invalid pkcs7 payload length");
+    }
+    for (let i = 0; i < pad; i += 1) {
+        if (buf[buf.length - 1 - i] !== pad) {
+            throw new Error("invalid pkcs7 padding byte");
+        }
+    }
+    return buf.subarray(0, buf.length - pad);
+}
+/**
+ * 计算 SHA1 哈希
+ */
+function sha1Hex(input) {
+    return crypto$1.createHash("sha1").update(input).digest("hex");
+}
+class WecomCrypto {
+    constructor(token, encodingAESKey, receiveId // 对应企业微信的 corpId 或 botId (用于校验与追加)
+    ) {
+        this.token = token;
+        this.encodingAESKey = encodingAESKey;
+        this.receiveId = receiveId;
+        if (!token)
+            throw new Error("token is required");
+        this.aesKey = decodeEncodingAESKey(encodingAESKey);
+        this.iv = this.aesKey.subarray(0, 16);
+    }
+    /**
+     * 计算 WeCom 消息签名
+     */
+    computeSignature(timestamp, nonce, encrypt) {
+        const parts = [this.token, timestamp, nonce, encrypt]
+            .map((v) => String(v ?? ""))
+            .sort();
+        return sha1Hex(parts.join(""));
+    }
+    /**
+     * 验证 WeCom 消息签名
+     */
+    verifySignature(signature, timestamp, nonce, encrypt) {
+        const expected = this.computeSignature(timestamp, nonce, encrypt);
+        return expected === signature;
+    }
+    /**
+     * 消息解密
+     * 返回纯文本字符串（XML 或 JSON 根据上层业务而定）
+     */
+    decrypt(encryptText) {
+        const decipher = crypto$1.createDecipheriv("aes-256-cbc", this.aesKey, this.iv);
+        decipher.setAutoPadding(false);
+        const decryptedPadded = Buffer.concat([
+            decipher.update(Buffer.from(encryptText, "base64")),
+            decipher.final(),
+        ]);
+        const decrypted = pkcs7Unpad(decryptedPadded, CRYPTO_CONSTANTS.PKCS7_BLOCK_SIZE);
+        if (decrypted.length < 20) {
+            throw new Error(`invalid payload (expected >=20 bytes, got ${decrypted.length})`);
+        }
+        // 16 bytes random + 4 bytes length + msg + receiveId
+        const msgLen = decrypted.readUInt32BE(16);
+        const msgStart = 20;
+        const msgEnd = msgStart + msgLen;
+        if (msgEnd > decrypted.length) {
+            throw new Error(`invalid msg length (msgEnd=${msgEnd}, total=${decrypted.length})`);
+        }
+        const msg = decrypted.subarray(msgStart, msgEnd).toString("utf8");
+        const receiveId = this.receiveId ?? "";
+        if (receiveId) {
+            const trailing = decrypted.subarray(msgEnd).toString("utf8");
+            if (trailing !== receiveId) {
+                throw new Error(`receiveId mismatch (expected "${receiveId}", got "${trailing}")`);
+            }
+        }
+        return msg;
+    }
+    /**
+     * 消息加密
+     * 加密明文并返回 base64 格式密文与对应的新签名
+     */
+    encrypt(plainText, timestamp, nonce) {
+        const random16 = crypto$1.randomBytes(16);
+        const msgBuf = Buffer.from(plainText ?? "", "utf8");
+        const msgLen = Buffer.alloc(4);
+        msgLen.writeUInt32BE(msgBuf.length, 0);
+        const receiveIdBuf = Buffer.from(this.receiveId ?? "", "utf8");
+        const raw = Buffer.concat([random16, msgLen, msgBuf, receiveIdBuf]);
+        const padded = pkcs7Pad(raw, CRYPTO_CONSTANTS.PKCS7_BLOCK_SIZE);
+        const cipher = crypto$1.createCipheriv("aes-256-cbc", this.aesKey, this.iv);
+        cipher.setAutoPadding(false);
+        const encryptedBuf = Buffer.concat([cipher.update(padded), cipher.final()]);
+        const encryptBase64 = encryptedBuf.toString("base64");
+        const signature = this.computeSignature(timestamp, nonce, encryptBase64);
+        return { encrypt: encryptBase64, signature };
+    }
+}
+
+/** 默认导出 AiBot 命名空间 */
+const AiBot = {
+    WSClient,
+};
+
+exports.DefaultLogger = DefaultLogger;
+exports.MessageHandler = MessageHandler;
+exports.WSAuthFailureError = WSAuthFailureError;
+exports.WSClient = WSClient;
+exports.WSReconnectExhaustedError = WSReconnectExhaustedError;
+exports.WeComApiClient = WeComApiClient;
+exports.WecomCrypto = WecomCrypto;
+exports.WsCmd = WsCmd;
+exports.WsConnectionManager = WsConnectionManager;
+exports.decodeEncodingAESKey = decodeEncodingAESKey;
+exports.decryptFile = decryptFile;
+exports.default = AiBot;
+exports.generateRandomString = generateRandomString;
+exports.generateReqId = generateReqId;
+exports.pkcs7Pad = pkcs7Pad;
+exports.pkcs7Unpad = pkcs7Unpad;
+//# sourceMappingURL=index.cjs.js.map