@wecom/wecom-openclaw-plugin 2026.3.30-beta.2 → 2026.3.31-beta.0

package/dist/src/media-handler.js

@@ -0,0 +1,122 @@
+/**
+ * 企业微信媒体（图片）下载和保存模块
+ *
+ * 负责下载、检测格式、保存图片到本地，包含超时保护
+ */
+import { fileTypeFromBuffer } from "file-type";
+import { getWeComRuntime } from "./runtime.js";
+import { IMAGE_DOWNLOAD_TIMEOUT_MS, FILE_DOWNLOAD_TIMEOUT_MS, DEFAULT_MEDIA_MAX_MB } from "./const.js";
+import { withTimeout } from "./timeout.js";
+// ============================================================================
+// 图片格式检测辅助函数（基于 file-type 包）
+// ============================================================================
+/**
+ * 检查 Buffer 是否为有效的图片格式
+ */
+async function isImageBuffer(data) {
+    const type = await fileTypeFromBuffer(data);
+    return type?.mime.startsWith("image/") ?? false;
+}
+/**
+ * 检测 Buffer 的图片内容类型
+ */
+async function detectImageContentType(data) {
+    const type = await fileTypeFromBuffer(data);
+    if (type?.mime.startsWith("image/")) {
+        return type.mime;
+    }
+    return "application/octet-stream";
+}
+// ============================================================================
+// 图片下载和保存
+// ============================================================================
+/**
+ * 下载并保存所有图片到本地，每张图片的下载带超时保护
+ */
+export async function downloadAndSaveImages(params) {
+    const { imageUrls, config, runtime, wsClient } = params;
+    const core = getWeComRuntime();
+    const mediaList = [];
+    for (const imageUrl of imageUrls) {
+        try {
+            runtime.log?.(`[wecom] Downloading image: url=${imageUrl}`);
+            const mediaMaxMb = config.agents?.defaults?.mediaMaxMb ?? DEFAULT_MEDIA_MAX_MB;
+            const maxBytes = mediaMaxMb * 1024 * 1024;
+            let imageBuffer;
+            let imageContentType;
+            let originalFilename;
+            const imageAesKey = params.imageAesKeys?.get(imageUrl);
+            try {
+                // 优先使用 SDK 的 downloadFile 方法下载（带超时保护）
+                const result = await withTimeout(wsClient.downloadFile(imageUrl, imageAesKey), IMAGE_DOWNLOAD_TIMEOUT_MS, `Image download timed out: ${imageUrl}`);
+                imageBuffer = result.buffer;
+                originalFilename = result.filename;
+                imageContentType = await detectImageContentType(imageBuffer);
+                runtime.log?.(`[wecom] Image downloaded: size=${imageBuffer.length}, contentType=${imageContentType}, filename=${originalFilename ?? '(none)'}`);
+            }
+            catch (sdkError) {
+                // 如果 SDK 方法失败，回退到原有方式（带超时保护）
+                runtime.log?.(`[wecom] SDK download failed, fallback: ${String(sdkError)}`);
+                const fetched = await withTimeout(core.channel.media.fetchRemoteMedia({ url: imageUrl }), IMAGE_DOWNLOAD_TIMEOUT_MS, `Manual image download timed out: ${imageUrl}`);
+                runtime.log?.(`[wecom] Image fetched: contentType=${fetched.contentType}, size=${fetched.buffer.length}`);
+                imageBuffer = fetched.buffer;
+                imageContentType = fetched.contentType ?? "application/octet-stream";
+                const isValidImage = await isImageBuffer(fetched.buffer);
+                if (!isValidImage) {
+                    runtime.log?.(`[wecom] WARN: Downloaded data is not a valid image format`);
+                }
+            }
+            const saved = await core.channel.media.saveMediaBuffer(imageBuffer, imageContentType, "inbound", maxBytes, originalFilename);
+            mediaList.push({ path: saved.path, contentType: saved.contentType });
+            runtime.log?.(`[wecom][plugin] Image saved: path=${saved.path}, contentType=${saved.contentType}`);
+        }
+        catch (err) {
+            runtime.error?.(`[wecom] Failed to download image: ${String(err)}`);
+        }
+    }
+    return mediaList;
+}
+/**
+ * 下载并保存所有文件到本地，每个文件的下载带超时保护
+ */
+export async function downloadAndSaveFiles(params) {
+    const { fileUrls, config, runtime, wsClient } = params;
+    const core = getWeComRuntime();
+    const mediaList = [];
+    for (const fileUrl of fileUrls) {
+        try {
+            runtime.log?.(`[wecom] Downloading file: url=${fileUrl}`);
+            const mediaMaxMb = config.agents?.defaults?.mediaMaxMb ?? DEFAULT_MEDIA_MAX_MB;
+            const maxBytes = mediaMaxMb * 1024 * 1024;
+            let fileBuffer;
+            let fileContentType;
+            let originalFilename;
+            const fileAesKey = params.fileAesKeys?.get(fileUrl);
+            try {
+                // 使用 SDK 的 downloadFile 方法下载（带超时保护）
+                const result = await withTimeout(wsClient.downloadFile(fileUrl, fileAesKey), FILE_DOWNLOAD_TIMEOUT_MS, `File download timed out: ${fileUrl}`);
+                fileBuffer = result.buffer;
+                originalFilename = result.filename;
+                // 检测文件类型
+                const type = await fileTypeFromBuffer(fileBuffer);
+                fileContentType = type?.mime ?? "application/octet-stream";
+                runtime.log?.(`[wecom] File downloaded: size=${fileBuffer.length}, contentType=${fileContentType}, filename=${originalFilename ?? '(none)'}`);
+            }
+            catch (sdkError) {
+                // 如果 SDK 方法失败，回退到 fetchRemoteMedia（带超时保护）
+                runtime.log?.(`[wecom] SDK file download failed, fallback: ${String(sdkError)}`);
+                const fetched = await withTimeout(core.channel.media.fetchRemoteMedia({ url: fileUrl }), FILE_DOWNLOAD_TIMEOUT_MS, `Manual file download timed out: ${fileUrl}`);
+                runtime.log?.(`[wecom] File fetched: contentType=${fetched.contentType}, size=${fetched.buffer.length}`);
+                fileBuffer = fetched.buffer;
+                fileContentType = fetched.contentType ?? "application/octet-stream";
+            }
+            const saved = await core.channel.media.saveMediaBuffer(fileBuffer, fileContentType, "inbound", maxBytes, originalFilename);
+            mediaList.push({ path: saved.path, contentType: saved.contentType });
+            runtime.log?.(`[wecom][plugin] File saved: path=${saved.path}, contentType=${saved.contentType}`);
+        }
+        catch (err) {
+            runtime.error?.(`[wecom] Failed to download file: ${String(err)}`);
+        }
+    }
+    return mediaList;
+}

package/dist/src/media-uploader.js

@@ -0,0 +1,333 @@
+/**
+ * 企业微信出站媒体上传工具模块
+ *
+ * 负责：
+ * - 从 mediaUrl 加载文件 buffer（远程 URL 或本地路径均支持）
+ * - 检测 MIME 类型并映射为企微媒体类型
+ * - 文件大小检查与降级策略
+ */
+import { loadOutboundMediaFromUrl, detectMime, } from "./openclaw-compat.js";
+import { IMAGE_MAX_BYTES, VIDEO_MAX_BYTES, VOICE_MAX_BYTES, ABSOLUTE_MAX_BYTES, } from "./const.js";
+// ============================================================================
+// MIME → 企微媒体类型映射
+// ============================================================================
+/**
+ * 根据 MIME 类型检测企微媒体类型
+ *
+ * @param mimeType - MIME 类型字符串
+ * @returns 企微媒体类型
+ */
+export function detectWeComMediaType(mimeType) {
+    const mime = mimeType.toLowerCase();
+    // 图片类型
+    if (mime.startsWith("image/")) {
+        return "image";
+    }
+    // 视频类型
+    if (mime.startsWith("video/")) {
+        return "video";
+    }
+    // 语音类型
+    if (mime.startsWith("audio/") ||
+        mime === "application/ogg" // OGG 音频容器
+    ) {
+        return "voice";
+    }
+    // 其他类型默认为文件
+    return "file";
+}
+// ============================================================================
+// 媒体文件加载
+// ============================================================================
+/**
+ * 从 mediaUrl 加载媒体文件
+ *
+ * 支持远程 URL（http/https）和本地路径（file:// 或绝对路径），
+ * 利用 openclaw plugin-sdk 的 loadOutboundMediaFromUrl 统一处理。
+ *
+ * @param mediaUrl - 媒体文件的 URL 或本地路径
+ * @param mediaLocalRoots - 允许读取本地文件的安全白名单目录
+ * @returns 解析后的媒体文件信息
+ */
+export async function resolveMediaFile(mediaUrl, mediaLocalRoots) {
+    // 使用兼容层加载媒体文件（优先 SDK，不可用时 fallback）
+    // 传入足够大的 maxBytes，由我们自己在后续步骤做大小检查
+    const result = await loadOutboundMediaFromUrl(mediaUrl, {
+        maxBytes: ABSOLUTE_MAX_BYTES,
+        mediaLocalRoots,
+    });
+    if (!result.buffer || result.buffer.length === 0) {
+        throw new Error(`Failed to load media from ${mediaUrl}: empty buffer`);
+    }
+    // 检测真实 MIME 类型
+    let contentType = result.contentType || "application/octet-stream";
+    // 如果没有返回准确的 contentType，尝试通过 buffer 魔术字节检测
+    if (contentType === "application/octet-stream" ||
+        contentType === "text/plain") {
+        const detected = await detectMime(result.buffer);
+        if (detected) {
+            contentType = detected;
+        }
+    }
+    // 提取文件名
+    const fileName = extractFileName(mediaUrl, result.fileName, contentType);
+    return {
+        buffer: result.buffer,
+        contentType,
+        fileName,
+    };
+}
+// ============================================================================
+// 文件大小检查与降级
+// ============================================================================
+/** 企微语音消息仅支持 AMR 格式 */
+const VOICE_SUPPORTED_MIMES = new Set(["audio/amr"]);
+/**
+ * 检查文件大小并执行降级策略
+ *
+ * 降级规则：
+ * - voice 非 AMR 格式 → 降级为 file（企微后台仅支持 AMR）
+ * - image 超过 10MB → 降级为 file
+ * - video 超过 10MB → 降级为 file
+ * - voice 超过 2MB → 降级为 file
+ * - file 超过 20MB → 拒绝发送
+ *
+ * @param fileSize - 文件大小（字节）
+ * @param detectedType - 检测到的企微媒体类型
+ * @param contentType - 文件的 MIME 类型（用于语音格式校验）
+ * @returns 大小检查结果
+ */
+export function applyFileSizeLimits(fileSize, detectedType, contentType) {
+    const fileSizeMB = (fileSize / (1024 * 1024)).toFixed(2);
+    // 先检查绝对上限（20MB）
+    if (fileSize > ABSOLUTE_MAX_BYTES) {
+        return {
+            finalType: detectedType,
+            shouldReject: true,
+            rejectReason: `文件大小 ${fileSizeMB}MB 超过了企业微信允许的最大限制 20MB，无法发送。请尝试压缩文件或减小文件大小。`,
+            downgraded: false,
+        };
+    }
+    // 按类型检查大小限制
+    switch (detectedType) {
+        case "image":
+            if (fileSize > IMAGE_MAX_BYTES) {
+                return {
+                    finalType: "file",
+                    shouldReject: false,
+                    downgraded: true,
+                    downgradeNote: `图片大小 ${fileSizeMB}MB 超过 10MB 限制，已转为文件格式发送`,
+                };
+            }
+            break;
+        case "video":
+            if (fileSize > VIDEO_MAX_BYTES) {
+                return {
+                    finalType: "file",
+                    shouldReject: false,
+                    downgraded: true,
+                    downgradeNote: `视频大小 ${fileSizeMB}MB 超过 10MB 限制，已转为文件格式发送`,
+                };
+            }
+            break;
+        case "voice":
+            // 企微语音消息仅支持 AMR 格式，非 AMR 一律降级为文件
+            if (contentType && !VOICE_SUPPORTED_MIMES.has(contentType.toLowerCase())) {
+                return {
+                    finalType: "file",
+                    shouldReject: false,
+                    downgraded: true,
+                    downgradeNote: `语音格式 ${contentType} 不支持，企微仅支持 AMR 格式，已转为文件格式发送`,
+                };
+            }
+            if (fileSize > VOICE_MAX_BYTES) {
+                return {
+                    finalType: "file",
+                    shouldReject: false,
+                    downgraded: true,
+                    downgradeNote: `语音大小 ${fileSizeMB}MB 超过 2MB 限制，已转为文件格式发送`,
+                };
+            }
+            break;
+        case "file":
+            // file 类型在绝对上限内即可
+            break;
+    }
+    // 无需降级
+    return {
+        finalType: detectedType,
+        shouldReject: false,
+        downgraded: false,
+    };
+}
+// ============================================================================
+// 辅助函数
+// ============================================================================
+/**
+ * 从 URL/路径中提取文件名
+ */
+function extractFileName(mediaUrl, providedFileName, contentType) {
+    // 优先使用提供的文件名
+    if (providedFileName) {
+        return providedFileName;
+    }
+    // 尝试从 URL 中提取
+    try {
+        const urlObj = new URL(mediaUrl, "file://");
+        const pathParts = urlObj.pathname.split("/");
+        const lastPart = pathParts[pathParts.length - 1];
+        if (lastPart && lastPart.includes(".")) {
+            return decodeURIComponent(lastPart);
+        }
+    }
+    catch {
+        // 尝试作为普通路径处理
+        const parts = mediaUrl.split("/");
+        const lastPart = parts[parts.length - 1];
+        if (lastPart && lastPart.includes(".")) {
+            return lastPart;
+        }
+    }
+    // 使用 MIME 类型生成默认文件名
+    const ext = mimeToExtension(contentType || "application/octet-stream");
+    return `media_${Date.now()}${ext}`;
+}
+/**
+ * MIME 类型转文件扩展名
+ */
+function mimeToExtension(mime) {
+    const map = {
+        "image/jpeg": ".jpg",
+        "image/png": ".png",
+        "image/gif": ".gif",
+        "image/webp": ".webp",
+        "image/bmp": ".bmp",
+        "image/svg+xml": ".svg",
+        "video/mp4": ".mp4",
+        "video/quicktime": ".mov",
+        "video/x-msvideo": ".avi",
+        "video/webm": ".webm",
+        "audio/mpeg": ".mp3",
+        "audio/ogg": ".ogg",
+        "audio/wav": ".wav",
+        "audio/amr": ".amr",
+        "audio/aac": ".aac",
+        "application/pdf": ".pdf",
+        "application/zip": ".zip",
+        "application/msword": ".doc",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+        "application/vnd.ms-excel": ".xls",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+        "text/plain": ".txt",
+    };
+    return map[mime] || ".bin";
+}
+/**
+ * 公共媒体上传+发送流程
+ *
+ * 统一处理：resolveMediaFile → detectType → sizeCheck → uploadMedia → sendMediaMessage
+ * 媒体消息统一走 aibot_send_msg 主动发送，避免多文件场景下 reqId 只能用一次的问题。
+ * channel.ts 的 sendMedia 和 monitor.ts 的 deliver 回调都使用此函数。
+ */
+export async function uploadAndSendMedia(options) {
+    const { wsClient, mediaUrl, chatId, mediaLocalRoots, log, errorLog } = options;
+    try {
+        // 1. 加载媒体文件
+        log?.(`[wecom] Uploading media: url=${mediaUrl}`);
+        const media = await resolveMediaFile(mediaUrl, mediaLocalRoots);
+        // 2. 检测企微媒体类型
+        const detectedType = detectWeComMediaType(media.contentType);
+        // 3. 文件大小检查与降级策略
+        const sizeCheck = applyFileSizeLimits(media.buffer.length, detectedType, media.contentType);
+        if (sizeCheck.shouldReject) {
+            errorLog?.(`[wecom] Media rejected: ${sizeCheck.rejectReason}`);
+            return {
+                ok: false,
+                rejected: true,
+                rejectReason: sizeCheck.rejectReason,
+                finalType: sizeCheck.finalType,
+            };
+        }
+        const finalType = sizeCheck.finalType;
+        // 4. 分片上传获取 media_id
+        const uploadResult = await wsClient.uploadMedia(media.buffer, {
+            type: finalType,
+            filename: media.fileName,
+        });
+        log?.(`[wecom] Media uploaded: media_id=${uploadResult.media_id}, type=${finalType}`);
+        // 5. 统一通过 aibot_send_msg 主动发送媒体消息
+        const result = await wsClient.sendMediaMessage(chatId, finalType, uploadResult.media_id);
+        const messageId = result?.headers?.req_id ?? `wecom-media-${Date.now()}`;
+        log?.(`[wecom] Media sent via sendMediaMessage: chatId=${chatId}, type=${finalType}`);
+        return {
+            ok: true,
+            messageId,
+            finalType,
+            downgraded: sizeCheck.downgraded,
+            downgradeNote: sizeCheck.downgradeNote,
+        };
+    }
+    catch (err) {
+        const errMsg = String(err);
+        errorLog?.(`[wecom] Failed to upload/send media: url=${mediaUrl}, error=${errMsg}`);
+        return {
+            ok: false,
+            error: errMsg,
+        };
+    }
+}
+/**
+ * 被动回复媒体上传+发送流程
+ *
+ * 统一处理：resolveMediaFile → detectType → sizeCheck → uploadMedia → replyMedia
+ * 通过 aibot_respond_msg 被动回复通道发送媒体消息，可以覆盖之前的 THINKING_MESSAGE。
+ *
+ * 适用场景：回包只有媒体没有文本时，第一个媒体文件用此方法发送以清理 thinking 状态。
+ */
+export async function uploadAndReplyMedia(options) {
+    const { wsClient, mediaUrl, frame, mediaLocalRoots, log, errorLog } = options;
+    try {
+        // 1. 加载媒体文件
+        log?.(`[wecom] Uploading media (reply mode): url=${mediaUrl}`);
+        const media = await resolveMediaFile(mediaUrl, mediaLocalRoots);
+        // 2. 检测企微媒体类型
+        const detectedType = detectWeComMediaType(media.contentType);
+        // 3. 文件大小检查与降级策略
+        const sizeCheck = applyFileSizeLimits(media.buffer.length, detectedType, media.contentType);
+        if (sizeCheck.shouldReject) {
+            errorLog?.(`[wecom] Media rejected: ${sizeCheck.rejectReason}`);
+            return {
+                ok: false,
+                rejected: true,
+                rejectReason: sizeCheck.rejectReason,
+                finalType: sizeCheck.finalType,
+            };
+        }
+        const finalType = sizeCheck.finalType;
+        // 4. 分片上传获取 media_id
+        const uploadResult = await wsClient.uploadMedia(media.buffer, {
+            type: finalType,
+            filename: media.fileName,
+        });
+        log?.(`[wecom] Media uploaded: media_id=${uploadResult.media_id}, type=${finalType}`);
+        // 5. 通过 aibot_respond_msg 被动回复发送媒体消息（会覆盖 THINKING_MESSAGE）
+        const result = await wsClient.replyMedia(frame, finalType, uploadResult.media_id);
+        const messageId = result?.headers?.req_id ?? `wecom-reply-media-${Date.now()}`;
+        log?.(`[wecom] Media sent via replyMedia (passive reply): type=${finalType}`);
+        return {
+            ok: true,
+            messageId,
+            finalType,
+            downgraded: sizeCheck.downgraded,
+            downgradeNote: sizeCheck.downgradeNote,
+        };
+    }
+    catch (err) {
+        const errMsg = String(err);
+        errorLog?.(`[wecom] Failed to upload/reply media: url=${mediaUrl}, error=${errMsg}`);
+        return {
+            ok: false,
+            error: errMsg,
+        };
+    }
+}

package/dist/src/message-parser.js

@@ -0,0 +1,129 @@
+/**
+ * 企业微信消息内容解析模块
+ *
+ * 负责从 WsFrame 中提取文本、图片、引用等内容
+ */
+// ============================================================================
+// 解析函数
+// ============================================================================
+/**
+ * 将模板卡片事件回调格式化为可继续路由给大模型的文本。
+ *
+ * 这样后续 Agent 可以直接从 question_key / option_id 中理解用户的真实选择。
+ */
+function buildTemplateCardEventText(body) {
+    const templateCardEvent = body.event?.template_card_event;
+    if (body.msgtype !== "event" ||
+        body.event?.eventtype !== "template_card_event" ||
+        !templateCardEvent) {
+        return undefined;
+    }
+    const selectedItems = templateCardEvent.selected_items?.selected_item ?? [];
+    const selectedLines = selectedItems.map((item) => {
+        const questionKey = item.question_key?.trim() || "unknown_question";
+        const optionIds = item.option_ids?.option_id?.filter(Boolean) ?? [];
+        return `- ${questionKey}: ${optionIds.length > 0 ? optionIds.join(", ") : "(未选择)"}`;
+    });
+    const senderUserId = body.from?.userid || "";
+    const senderCorpId = body.from?.corpid || "";
+    const chatId = body.chatid || senderUserId;
+    return [
+        "[企业微信模板卡片回调]",
+        `event_type(事件类型): template_card_event`,
+        body.msgid ? `msgid(消息 id): ${body.msgid}` : undefined,
+        body.aibotid ? `aibotid(机器人 id): ${body.aibotid}` : undefined,
+        body.chattype ? `chat_type(会话类型): ${body.chattype}` : undefined,
+        chatId ? `chat_id(会话 id): ${chatId}` : undefined,
+        senderCorpId ? `from.corpid(企业 id): ${senderCorpId}` : undefined,
+        senderUserId ? `from.userid(发送人 id): ${senderUserId}` : undefined,
+        senderUserId ? `sender_userid(发送人 id): ${senderUserId}` : undefined,
+        templateCardEvent.card_type ? `card_type(卡片类型): ${templateCardEvent.card_type}` : undefined,
+        templateCardEvent.event_key ? `event_key(事件 key): ${templateCardEvent.event_key}` : undefined,
+        templateCardEvent.task_id ? `task_id(任务 id): ${templateCardEvent.task_id}` : undefined,
+        selectedLines.length > 0 ? "selected_items(选择项):" : "selected_items(选择项): []",
+        ...selectedLines,
+    ]
+        .filter((line) => Boolean(line))
+        .join("\n");
+}
+/**
+ * 解析消息内容（支持单条消息、图文混排、事件回调和引用消息）
+ * @returns 提取的文本数组、图片URL数组和引用消息内容
+ */
+export function parseMessageContent(body) {
+    const textParts = [];
+    const imageUrls = [];
+    const imageAesKeys = new Map();
+    const fileUrls = [];
+    const fileAesKeys = new Map();
+    let quoteContent;
+    // 处理模板卡片事件回调
+    if (body.msgtype === "event") {
+        const eventText = buildTemplateCardEventText(body);
+        if (eventText) {
+            textParts.push(eventText);
+        }
+        return { textParts, imageUrls, imageAesKeys, fileUrls, fileAesKeys, quoteContent };
+    }
+    // 处理图文混排消息
+    if (body.msgtype === "mixed" && body.mixed?.msg_item) {
+        for (const item of body.mixed.msg_item) {
+            if (item.msgtype === "text" && item.text?.content) {
+                textParts.push(item.text.content);
+            }
+            else if (item.msgtype === "image" && item.image?.url) {
+                imageUrls.push(item.image.url);
+                if (item.image.aeskey) {
+                    imageAesKeys.set(item.image.url, item.image.aeskey);
+                }
+            }
+        }
+    }
+    else {
+        // 处理单条消息
+        if (body.text?.content) {
+            textParts.push(body.text.content);
+        }
+        // 处理语音消息（语音转文字后的文本内容）
+        if (body.msgtype === "voice" && body.voice?.content) {
+            textParts.push(body.voice.content);
+        }
+        if (body.image?.url) {
+            imageUrls.push(body.image.url);
+            if (body.image.aeskey) {
+                imageAesKeys.set(body.image.url, body.image.aeskey);
+            }
+        }
+        // 处理文件消息
+        if (body.msgtype === "file" && body.file?.url) {
+            fileUrls.push(body.file.url);
+            if (body.file.aeskey) {
+                fileAesKeys.set(body.file.url, body.file.aeskey);
+            }
+        }
+    }
+    // 处理引用消息
+    if (body.quote) {
+        if (body.quote.msgtype === "text" && body.quote.text?.content) {
+            quoteContent = body.quote.text.content;
+        }
+        else if (body.quote.msgtype === "voice" && body.quote.voice?.content) {
+            quoteContent = body.quote.voice.content;
+        }
+        else if (body.quote.msgtype === "image" && body.quote.image?.url) {
+            // 引用的图片消息：将图片 URL 加入下载列表
+            imageUrls.push(body.quote.image.url);
+            if (body.quote.image.aeskey) {
+                imageAesKeys.set(body.quote.image.url, body.quote.image.aeskey);
+            }
+        }
+        else if (body.quote.msgtype === "file" && body.quote.file?.url) {
+            // 引用的文件消息：将文件 URL 加入下载列表
+            fileUrls.push(body.quote.file.url);
+            if (body.quote.file.aeskey) {
+                fileAesKeys.set(body.quote.file.url, body.quote.file.aeskey);
+            }
+        }
+    }
+    return { textParts, imageUrls, imageAesKeys, fileUrls, fileAesKeys, quoteContent };
+}

package/dist/src/message-sender.d.ts

@@ -32,3 +32,21 @@ export declare function sendWeComReply(params: {
     /** 指定 streamId，用于流式回复时保持相同的 streamId */
     streamId?: string;
 }): Promise<string>;
+/**
+ * 非阻塞流式文本回复
+ *
+ * 基于 SDK 的 replyStreamNonBlocking 方法：
+ * - 如果上一条同 reqId 的消息尚未收到 ack，则跳过本次发送（返回 'skipped'），
+ *   避免流式中间帧排队积压导致延迟。
+ * - finish=true 的最终帧不受此限制，始终保证发送。
+ *
+ * @returns 'skipped' 表示被跳过，否则返回 streamId
+ */
+export declare function sendWeComReplyNonBlocking(params: {
+    wsClient: WSClient;
+    frame: WsFrame;
+    text: string;
+    runtime: RuntimeEnv;
+    streamId: string;
+    finish?: boolean;
+}): Promise<string | 'skipped'>;