ylib-wecom-openclaw-plugin 2026.4.29

package/dist/src/media-handler.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 企业微信媒体（图片）下载和保存模块
+ *
+ * 负责下载、检测格式、保存图片到本地，包含超时保护
+ */
+import type { OpenClawConfig } from "ylib-openclaw/plugin-sdk";
+import type { RuntimeEnv } from "ylib-openclaw/plugin-sdk";
+import type { WSClient } from "@wecom/aibot-node-sdk";
+import type { ResolvedWeComAccount } from "./utils.js";
+/**
+ * 附件超过 OpenClaw 配置的 `agents.defaults.mediaMaxMb` 上限时抛出。
+ *
+ * 本错误由插件层主动判定并抛出，不依赖 OpenClaw 核心层错误消息的字符串匹配，
+ * 上层（monitor）可通过 `instanceof MediaOversizeError` 精确识别并向用户提示。
+ */
+export declare class MediaOversizeError extends Error {
+    readonly kind: "image" | "file";
+    readonly filename?: string;
+    readonly sizeBytes: number;
+    readonly maxBytes: number;
+    constructor(params: {
+        kind: "image" | "file";
+        filename?: string;
+        sizeBytes: number;
+        maxBytes: number;
+    });
+}
+/**
+ * 下载并保存所有图片到本地，每张图片的下载带超时保护
+ */
+export declare function downloadAndSaveImages(params: {
+    imageUrls: string[];
+    imageAesKeys?: Map<string, string>;
+    account: ResolvedWeComAccount;
+    config: OpenClawConfig;
+    runtime: RuntimeEnv;
+    wsClient: WSClient;
+}): Promise<Array<{
+    path: string;
+    contentType?: string;
+}>>;
+/**
+ * 下载并保存所有文件到本地，每个文件的下载带超时保护
+ */
+export declare function downloadAndSaveFiles(params: {
+    fileUrls: string[];
+    fileAesKeys?: Map<string, string>;
+    account: ResolvedWeComAccount;
+    config: OpenClawConfig;
+    runtime: RuntimeEnv;
+    wsClient: WSClient;
+}): Promise<Array<{
+    path: string;
+    contentType?: string;
+}>>;

package/dist/src/media-handler.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * 企业微信媒体（图片）下载和保存模块
+ *
+ * 负责下载、检测格式、保存图片到本地，包含超时保护
+ */
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (_) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+exports.__esModule = true;
+exports.downloadAndSaveFiles = exports.downloadAndSaveImages = exports.MediaOversizeError = void 0;
+var file_type_1 = require("file-type");
+var runtime_js_1 = require("./runtime.js");
+var const_js_1 = require("./const.js");
+var timeout_js_1 = require("./timeout.js");
+// ============================================================================
+// 媒体超限错误
+// ============================================================================
+/**
+ * 附件超过 OpenClaw 配置的 `agents.defaults.mediaMaxMb` 上限时抛出。
+ *
+ * 本错误由插件层主动判定并抛出，不依赖 OpenClaw 核心层错误消息的字符串匹配，
+ * 上层（monitor）可通过 `instanceof MediaOversizeError` 精确识别并向用户提示。
+ */
+var MediaOversizeError = /** @class */ (function (_super) {
+    __extends(MediaOversizeError, _super);
+    function MediaOversizeError(params) {
+        var _this = _super.call(this, "Media oversize: kind=" + params.kind + ", size=" + params.sizeBytes + ", max=" + params.maxBytes +
+            (params.filename ? ", filename=" + params.filename : "")) || this;
+        _this.name = "MediaOversizeError";
+        _this.kind = params.kind;
+        _this.filename = params.filename;
+        _this.sizeBytes = params.sizeBytes;
+        _this.maxBytes = params.maxBytes;
+        return _this;
+    }
+    return MediaOversizeError;
+}(Error));
+exports.MediaOversizeError = MediaOversizeError;
+// ============================================================================
+// 图片格式检测辅助函数（基于 file-type 包）
+// ============================================================================
+/**
+ * 检查 Buffer 是否为有效的图片格式
+ */
+function isImageBuffer(data) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function () {
+        var type;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0: return [4 /*yield*/, file_type_1.fileTypeFromBuffer(data)];
+                case 1:
+                    type = _b.sent();
+                    return [2 /*return*/, (_a = type === null || type === void 0 ? void 0 : type.mime.startsWith("image/")) !== null && _a !== void 0 ? _a : false];
+            }
+        });
+    });
+}
+/**
+ * 检测 Buffer 的图片内容类型
+ */
+function detectImageContentType(data) {
+    return __awaiter(this, void 0, void 0, function () {
+        var type;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, file_type_1.fileTypeFromBuffer(data)];
+                case 1:
+                    type = _a.sent();
+                    if (type === null || type === void 0 ? void 0 : type.mime.startsWith("image/")) {
+                        return [2 /*return*/, type.mime];
+                    }
+                    return [2 /*return*/, "application/octet-stream"];
+            }
+        });
+    });
+}
+// ============================================================================
+// 图片下载和保存
+// ============================================================================
+/**
+ * 下载并保存所有图片到本地，每张图片的下载带超时保护
+ */
+function downloadAndSaveImages(params) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    return __awaiter(this, void 0, void 0, function () {
+        var imageUrls, config, runtime, wsClient, core, mediaList, _i, imageUrls_1, imageUrl, mediaMaxMb, maxBytes, imageBuffer, imageContentType, originalFilename, imageAesKey, result, sdkError_1, fetched, isValidImage, saved, err_1;
+        return __generator(this, function (_o) {
+            switch (_o.label) {
+                case 0:
+                    imageUrls = params.imageUrls, config = params.config, runtime = params.runtime, wsClient = params.wsClient;
+                    core = runtime_js_1.getWeComRuntime();
+                    mediaList = [];
+                    _i = 0, imageUrls_1 = imageUrls;
+                    _o.label = 1;
+                case 1:
+                    if (!(_i < imageUrls_1.length)) return [3 /*break*/, 13];
+                    imageUrl = imageUrls_1[_i];
+                    _o.label = 2;
+                case 2:
+                    _o.trys.push([2, 11, , 12]);
+                    (_a = runtime.log) === null || _a === void 0 ? void 0 : _a.call(runtime, "[wecom] Downloading image: url=" + imageUrl);
+                    mediaMaxMb = (_d = (_c = (_b = config.agents) === null || _b === void 0 ? void 0 : _b.defaults) === null || _c === void 0 ? void 0 : _c.mediaMaxMb) !== null && _d !== void 0 ? _d : const_js_1.DEFAULT_MEDIA_MAX_MB;
+                    maxBytes = mediaMaxMb * 1024 * 1024;
+                    imageBuffer = void 0;
+                    imageContentType = void 0;
+                    originalFilename = void 0;
+                    imageAesKey = (_e = params.imageAesKeys) === null || _e === void 0 ? void 0 : _e.get(imageUrl);
+                    _o.label = 3;
+                case 3:
+                    _o.trys.push([3, 6, , 9]);
+                    return [4 /*yield*/, timeout_js_1.withTimeout(wsClient.downloadFile(imageUrl, imageAesKey), const_js_1.IMAGE_DOWNLOAD_TIMEOUT_MS, "Image download timed out: " + imageUrl)];
+                case 4:
+                    result = _o.sent();
+                    imageBuffer = result.buffer;
+                    originalFilename = result.filename;
+                    return [4 /*yield*/, detectImageContentType(imageBuffer)];
+                case 5:
+                    imageContentType = _o.sent();
+                    (_f = runtime.log) === null || _f === void 0 ? void 0 : _f.call(runtime, "[wecom] Image downloaded: size=" + imageBuffer.length + ", contentType=" + imageContentType + ", filename=" + (originalFilename !== null && originalFilename !== void 0 ? originalFilename : '(none)'));
+                    return [3 /*break*/, 9];
+                case 6:
+                    sdkError_1 = _o.sent();
+                    // 如果 SDK 方法失败，回退到原有方式（带超时保护）
+                    (_g = runtime.log) === null || _g === void 0 ? void 0 : _g.call(runtime, "[wecom] SDK download failed, fallback: " + String(sdkError_1));
+                    return [4 /*yield*/, timeout_js_1.withTimeout(core.channel.media.fetchRemoteMedia({ url: imageUrl }), const_js_1.IMAGE_DOWNLOAD_TIMEOUT_MS, "Manual image download timed out: " + imageUrl)];
+                case 7:
+                    fetched = _o.sent();
+                    (_h = runtime.log) === null || _h === void 0 ? void 0 : _h.call(runtime, "[wecom] Image fetched: contentType=" + fetched.contentType + ", size=" + fetched.buffer.length);
+                    imageBuffer = fetched.buffer;
+                    imageContentType = (_j = fetched.contentType) !== null && _j !== void 0 ? _j : "application/octet-stream";
+                    return [4 /*yield*/, isImageBuffer(fetched.buffer)];
+                case 8:
+                    isValidImage = _o.sent();
+                    if (!isValidImage) {
+                        (_k = runtime.log) === null || _k === void 0 ? void 0 : _k.call(runtime, "[wecom] WARN: Downloaded data is not a valid image format");
+                    }
+                    return [3 /*break*/, 9];
+                case 9:
+                    // 大小校验由插件层主动进行，超限抛出 MediaOversizeError，由 monitor 统一提示用户。
+                    // 不再把 maxBytes 传给核心层 saveMediaBuffer，避免重复校验产生无结构化错误。
+                    if (imageBuffer.length > maxBytes) {
+                        throw new MediaOversizeError({
+                            kind: "image",
+                            filename: originalFilename,
+                            sizeBytes: imageBuffer.length,
+                            maxBytes: maxBytes
+                        });
+                    }
+                    return [4 /*yield*/, core.channel.media.saveMediaBuffer(imageBuffer, imageContentType, "inbound", maxBytes, originalFilename)];
+                case 10:
+                    saved = _o.sent();
+                    mediaList.push({ path: saved.path, contentType: saved.contentType });
+                    (_l = runtime.log) === null || _l === void 0 ? void 0 : _l.call(runtime, "[wecom][plugin] Image saved: path=" + saved.path + ", contentType=" + saved.contentType);
+                    return [3 /*break*/, 12];
+                case 11:
+                    err_1 = _o.sent();
+                    // 媒体超限错误需要上抛给 monitor，用于向用户发送明确的提示文案。
+                    if (err_1 instanceof MediaOversizeError) {
+                        throw err_1;
+                    }
+                    (_m = runtime.error) === null || _m === void 0 ? void 0 : _m.call(runtime, "[wecom] Failed to download image: " + String(err_1));
+                    return [3 /*break*/, 12];
+                case 12:
+                    _i++;
+                    return [3 /*break*/, 1];
+                case 13: return [2 /*return*/, mediaList];
+            }
+        });
+    });
+}
+exports.downloadAndSaveImages = downloadAndSaveImages;
+/**
+ * 下载并保存所有文件到本地，每个文件的下载带超时保护
+ */
+function downloadAndSaveFiles(params) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    return __awaiter(this, void 0, void 0, function () {
+        var fileUrls, config, runtime, wsClient, core, mediaList, _i, fileUrls_1, fileUrl, mediaMaxMb, maxBytes, fileBuffer, fileContentType, originalFilename, fileAesKey, result, type, sdkError_2, fetched, saved, err_2;
+        return __generator(this, function (_o) {
+            switch (_o.label) {
+                case 0:
+                    fileUrls = params.fileUrls, config = params.config, runtime = params.runtime, wsClient = params.wsClient;
+                    core = runtime_js_1.getWeComRuntime();
+                    mediaList = [];
+                    _i = 0, fileUrls_1 = fileUrls;
+                    _o.label = 1;
+                case 1:
+                    if (!(_i < fileUrls_1.length)) return [3 /*break*/, 12];
+                    fileUrl = fileUrls_1[_i];
+                    _o.label = 2;
+                case 2:
+                    _o.trys.push([2, 10, , 11]);
+                    (_a = runtime.log) === null || _a === void 0 ? void 0 : _a.call(runtime, "[wecom] Downloading file: url=" + fileUrl);
+                    mediaMaxMb = (_d = (_c = (_b = config.agents) === null || _b === void 0 ? void 0 : _b.defaults) === null || _c === void 0 ? void 0 : _c.mediaMaxMb) !== null && _d !== void 0 ? _d : const_js_1.DEFAULT_MEDIA_MAX_MB;
+                    maxBytes = mediaMaxMb * 1024 * 1024;
+                    fileBuffer = void 0;
+                    fileContentType = void 0;
+                    originalFilename = void 0;
+                    fileAesKey = (_e = params.fileAesKeys) === null || _e === void 0 ? void 0 : _e.get(fileUrl);
+                    _o.label = 3;
+                case 3:
+                    _o.trys.push([3, 6, , 8]);
+                    return [4 /*yield*/, timeout_js_1.withTimeout(wsClient.downloadFile(fileUrl, fileAesKey), const_js_1.FILE_DOWNLOAD_TIMEOUT_MS, "File download timed out: " + fileUrl)];
+                case 4:
+                    result = _o.sent();
+                    fileBuffer = result.buffer;
+                    originalFilename = result.filename;
+                    return [4 /*yield*/, file_type_1.fileTypeFromBuffer(fileBuffer)];
+                case 5:
+                    type = _o.sent();
+                    fileContentType = (_f = type === null || type === void 0 ? void 0 : type.mime) !== null && _f !== void 0 ? _f : "application/octet-stream";
+                    (_g = runtime.log) === null || _g === void 0 ? void 0 : _g.call(runtime, "[wecom] File downloaded: size=" + fileBuffer.length + ", contentType=" + fileContentType + ", filename=" + (originalFilename !== null && originalFilename !== void 0 ? originalFilename : '(none)'));
+                    return [3 /*break*/, 8];
+                case 6:
+                    sdkError_2 = _o.sent();
+                    // 如果 SDK 方法失败，回退到 fetchRemoteMedia（带超时保护）
+                    (_h = runtime.log) === null || _h === void 0 ? void 0 : _h.call(runtime, "[wecom] SDK file download failed, fallback: " + String(sdkError_2));
+                    return [4 /*yield*/, timeout_js_1.withTimeout(core.channel.media.fetchRemoteMedia({ url: fileUrl }), const_js_1.FILE_DOWNLOAD_TIMEOUT_MS, "Manual file download timed out: " + fileUrl)];
+                case 7:
+                    fetched = _o.sent();
+                    (_j = runtime.log) === null || _j === void 0 ? void 0 : _j.call(runtime, "[wecom] File fetched: contentType=" + fetched.contentType + ", size=" + fetched.buffer.length);
+                    fileBuffer = fetched.buffer;
+                    fileContentType = (_k = fetched.contentType) !== null && _k !== void 0 ? _k : "application/octet-stream";
+                    return [3 /*break*/, 8];
+                case 8:
+                    // 大小校验由插件层主动进行，超限抛出 MediaOversizeError，由 monitor 统一提示用户。
+                    // 不再把 maxBytes 传给核心层 saveMediaBuffer，避免重复校验产生无结构化错误。
+                    if (fileBuffer.length > maxBytes) {
+                        throw new MediaOversizeError({
+                            kind: "file",
+                            filename: originalFilename,
+                            sizeBytes: fileBuffer.length,
+                            maxBytes: maxBytes
+                        });
+                    }
+                    return [4 /*yield*/, core.channel.media.saveMediaBuffer(fileBuffer, fileContentType, "inbound", maxBytes, originalFilename)];
+                case 9:
+                    saved = _o.sent();
+                    mediaList.push({ path: saved.path, contentType: saved.contentType });
+                    (_l = runtime.log) === null || _l === void 0 ? void 0 : _l.call(runtime, "[wecom][plugin] File saved: path=" + saved.path + ", contentType=" + saved.contentType);
+                    return [3 /*break*/, 11];
+                case 10:
+                    err_2 = _o.sent();
+                    // 媒体超限错误需要上抛给 monitor，用于向用户发送明确的提示文案。
+                    if (err_2 instanceof MediaOversizeError) {
+                        throw err_2;
+                    }
+                    (_m = runtime.error) === null || _m === void 0 ? void 0 : _m.call(runtime, "[wecom] Failed to download file: " + String(err_2));
+                    return [3 /*break*/, 11];
+                case 11:
+                    _i++;
+                    return [3 /*break*/, 1];
+                case 12: return [2 /*return*/, mediaList];
+            }
+        });
+    });
+}
+exports.downloadAndSaveFiles = downloadAndSaveFiles;

package/dist/src/media-uploader.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 企业微信出站媒体上传工具模块
+ *
+ * 负责：
+ * - 从 mediaUrl 加载文件 buffer（远程 URL 或本地路径均支持）
+ * - 检测 MIME 类型并映射为企微媒体类型
+ * - 文件大小检查与降级策略
+ */
+/// <reference types="node" />
+import type { WeComMediaType, WSClient, WsFrameHeaders } from "@wecom/aibot-node-sdk";
+/** 媒体文件解析结果 */
+export interface ResolvedMedia {
+    /** 文件数据 */
+    buffer: Buffer;
+    /** 检测到的 MIME 类型 */
+    contentType: string;
+    /** 文件名（从 URL 提取或默认生成） */
+    fileName: string;
+}
+/** 文件大小检查结果 */
+export interface FileSizeCheckResult {
+    /** 最终确定的企微媒体类型（可能被降级） */
+    finalType: WeComMediaType;
+    /** 是否需要拒绝（超过绝对限制） */
+    shouldReject: boolean;
+    /** 拒绝原因（仅 shouldReject=true 时有值） */
+    rejectReason?: string;
+    /** 是否发生了降级 */
+    downgraded: boolean;
+    /** 降级说明（仅 downgraded=true 时有值） */
+    downgradeNote?: string;
+}
+/**
+ * 根据 MIME 类型检测企微媒体类型
+ *
+ * @param mimeType - MIME 类型字符串
+ * @returns 企微媒体类型
+ */
+export declare function detectWeComMediaType(mimeType: string): WeComMediaType;
+/**
+ * 从 mediaUrl 加载媒体文件
+ *
+ * 支持远程 URL（http/https）和本地路径（file:// 或绝对路径），
+ * 利用 openclaw plugin-sdk 的 loadOutboundMediaFromUrl 统一处理。
+ *
+ * @param mediaUrl - 媒体文件的 URL 或本地路径
+ * @param mediaLocalRoots - 允许读取本地文件的安全白名单目录
+ * @returns 解析后的媒体文件信息
+ */
+export declare function resolveMediaFile(mediaUrl: string, mediaLocalRoots?: readonly string[], gatewayToken?: string, gatewayBaseUrl?: string): Promise<ResolvedMedia>;
+/**
+ * 检查文件大小并执行降级策略
+ *
+ * 降级规则：
+ * - voice 非 AMR 格式 → 降级为 file（企微后台仅支持 AMR）
+ * - image 超过 10MB → 降级为 file
+ * - video 超过 10MB → 降级为 file
+ * - voice 超过 2MB → 降级为 file
+ * - file 超过 20MB → 拒绝发送
+ *
+ * @param fileSize - 文件大小（字节）
+ * @param detectedType - 检测到的企微媒体类型
+ * @param contentType - 文件的 MIME 类型（用于语音格式校验）
+ * @returns 大小检查结果
+ */
+export declare function applyFileSizeLimits(fileSize: number, detectedType: WeComMediaType, contentType?: string): FileSizeCheckResult;
+/** uploadAndSendMedia 的参数 */
+export interface UploadAndSendMediaOptions {
+    /** WSClient 实例 */
+    wsClient: WSClient;
+    /** 媒体文件的 URL 或本地路径 */
+    mediaUrl: string;
+    /** 目标会话 ID（用于 aibot_send_msg 主动发送） */
+    chatId: string;
+    /** 允许读取本地文件的安全白名单目录 */
+    mediaLocalRoots?: readonly string[];
+    /** 下载受保护远程资源时使用的 gateway token（Bearer） */
+    gatewayToken?: string;
+    /** 受信任 Python/Gateway 基础地址；仅该来源允许回环地址媒体下载。 */
+    gatewayBaseUrl?: string;
+    /** 日志函数 */
+    log?: (...args: any[]) => void;
+    /** 错误日志函数 */
+    errorLog?: (...args: any[]) => void;
+}
+/** uploadAndSendMedia 的返回结果 */
+export interface UploadAndSendMediaResult {
+    /** 是否发送成功 */
+    ok: boolean;
+    /** 发送后返回的 messageId */
+    messageId?: string;
+    /** 发送所用文件名 */
+    fileName?: string;
+    /** 最终的企微媒体类型 */
+    finalType?: WeComMediaType;
+    /** 是否被拒绝（文件过大） */
+    rejected?: boolean;
+    /** 拒绝原因 */
+    rejectReason?: string;
+    /** 是否发生了降级 */
+    downgraded?: boolean;
+    /** 降级说明 */
+    downgradeNote?: string;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 公共媒体上传+发送流程
+ *
+ * 统一处理：resolveMediaFile → detectType → sizeCheck → uploadMedia → sendMediaMessage
+ * 媒体消息统一走 aibot_send_msg 主动发送，避免多文件场景下 reqId 只能用一次的问题。
+ * channel.ts 的 sendMedia 和 monitor.ts 的 deliver 回调都使用此函数。
+ */
+export declare function uploadAndSendMedia(options: UploadAndSendMediaOptions): Promise<UploadAndSendMediaResult>;
+/** uploadAndReplyMedia 的参数 */
+export interface UploadAndReplyMediaOptions {
+    /** WSClient 实例 */
+    wsClient: WSClient;
+    /** 媒体文件的 URL 或本地路径 */
+    mediaUrl: string;
+    /** 原始 WebSocket 帧（用于 aibot_respond_msg 被动回复，携带 req_id） */
+    frame: WsFrameHeaders;
+    /** 允许读取本地文件的安全白名单目录 */
+    mediaLocalRoots?: readonly string[];
+    /** 下载受保护远程资源时使用的 gateway token（Bearer） */
+    gatewayToken?: string;
+    /** 受信任 Python/Gateway 基础地址；仅该来源允许回环地址媒体下载。 */
+    gatewayBaseUrl?: string;
+    /** 日志函数 */
+    log?: (...args: any[]) => void;
+    /** 错误日志函数 */
+    errorLog?: (...args: any[]) => void;
+}
+/**
+ * 被动回复媒体上传+发送流程
+ *
+ * 统一处理：resolveMediaFile → detectType → sizeCheck → uploadMedia → replyMedia
+ * 通过 aibot_respond_msg 被动回复通道发送媒体消息，可以覆盖之前的 THINKING_MESSAGE。
+ *
+ * 适用场景：回包只有媒体没有文本时，第一个媒体文件用此方法发送以清理 thinking 状态。
+ */
+export declare function uploadAndReplyMedia(options: UploadAndReplyMediaOptions): Promise<UploadAndSendMediaResult>;