@wecom/wecom-openclaw-plugin 1.0.9 → 1.0.10-beta.0

package/dist/index.esm.js

@@ -1,11 +1,17 @@
 import { readJsonFileWithFallback, withFileLock, writeJsonFileAtomically, DEFAULT_ACCOUNT_ID, addWildcardAllowFrom, formatPairingApproveHint, emptyPluginConfigSchema } from 'openclaw/plugin-sdk';
+import * as os$1 from 'os';
+import os__default$1 from 'os';
+import * as path$1 from 'path';
+import path__default from 'path';
 import { generateReqId, WSClient } from '@wecom/aibot-node-sdk';
-import path from 'path';
-import { fileURLToPath } from 'url';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import path__default$1 from 'node:path';
+import * as os from 'node:os';
+import os__default from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { fileURLToPath as fileURLToPath$1 } from 'url';
 import { fileTypeFromBuffer } from 'file-type';
-import os from 'node:os';
-import path$1 from 'node:path';
-import os$1 from 'os';
 
 let runtime = null;
 function setWeComRuntime(r) {
@@ -18,6 +24,310 @@ function getWeComRuntime() {
     return runtime;
 }
 
+/**
+ * openclaw plugin-sdk 高版本方法兼容层
+ *
+ * 部分方法（如 loadOutboundMediaFromUrl、detectMime、getDefaultMediaLocalRoots）
+ * 仅在较新版本的 openclaw plugin-sdk 中才导出。
+ *
+ * 本模块在加载时一次性探测 SDK 导出，存在则直接 re-export SDK 版本，
+ * 不存在则导出 fallback 实现。其他模块统一从本文件导入，无需关心底层兼容细节。
+ */
+const _sdkReady = import('openclaw/plugin-sdk')
+    .then((sdk) => {
+    const exports$1 = {};
+    if (typeof sdk.loadOutboundMediaFromUrl === "function") {
+        exports$1.loadOutboundMediaFromUrl = sdk.loadOutboundMediaFromUrl;
+    }
+    if (typeof sdk.detectMime === "function") {
+        exports$1.detectMime = sdk.detectMime;
+    }
+    if (typeof sdk.getDefaultMediaLocalRoots === "function") {
+        exports$1.getDefaultMediaLocalRoots = sdk.getDefaultMediaLocalRoots;
+    }
+    return exports$1;
+})
+    .catch(() => {
+    // openclaw/plugin-sdk 不可用或版本过低，全部使用 fallback
+    return {};
+});
+// ============================================================================
+// detectMime —— 检测 MIME 类型
+// ============================================================================
+const MIME_BY_EXT = {
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".ogg": "audio/ogg",
+    ".mp3": "audio/mpeg",
+    ".m4a": "audio/x-m4a",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".pdf": "application/pdf",
+    ".json": "application/json",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+    ".tar": "application/x-tar",
+    ".7z": "application/x-7z-compressed",
+    ".rar": "application/vnd.rar",
+    ".doc": "application/msword",
+    ".xls": "application/vnd.ms-excel",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".csv": "text/csv",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".amr": "audio/amr",
+    ".aac": "audio/aac",
+    ".wav": "audio/wav",
+    ".webm": "video/webm",
+    ".avi": "video/x-msvideo",
+    ".bmp": "image/bmp",
+    ".svg": "image/svg+xml",
+};
+/** 通过 buffer 魔术字节嗅探 MIME 类型（动态导入 file-type，不强依赖） */
+async function sniffMimeFromBuffer(buffer) {
+    try {
+        const { fileTypeFromBuffer } = await import('file-type');
+        const type = await fileTypeFromBuffer(buffer);
+        return type?.mime ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** fallback 版 detectMime，参考 weclaw/src/media/mime.ts */
+async function detectMimeFallback(opts) {
+    const ext = opts.filePath ? path.extname(opts.filePath).toLowerCase() : undefined;
+    const extMime = ext ? MIME_BY_EXT[ext] : undefined;
+    const sniffed = opts.buffer ? await sniffMimeFromBuffer(opts.buffer) : undefined;
+    const isGeneric = (m) => !m || m === "application/octet-stream" || m === "application/zip";
+    if (sniffed && (!isGeneric(sniffed) || !extMime)) {
+        return sniffed;
+    }
+    if (extMime) {
+        return extMime;
+    }
+    const headerMime = opts.headerMime?.split(";")?.[0]?.trim().toLowerCase();
+    if (headerMime && !isGeneric(headerMime)) {
+        return headerMime;
+    }
+    if (sniffed) {
+        return sniffed;
+    }
+    if (headerMime) {
+        return headerMime;
+    }
+    return undefined;
+}
+/**
+ * 检测 MIME 类型（兼容入口）
+ *
+ * 支持两种调用签名以兼容不同使用场景：
+ * - detectMime(buffer)           → 旧式调用
+ * - detectMime({ buffer, headerMime, filePath }) → 完整参数
+ *
+ * 优先使用 SDK 版本，不可用时使用 fallback。
+ */
+async function detectMime(bufferOrOpts) {
+    const sdk = await _sdkReady;
+    const opts = Buffer.isBuffer(bufferOrOpts)
+        ? { buffer: bufferOrOpts }
+        : bufferOrOpts;
+    if (sdk.detectMime) {
+        try {
+            return await sdk.detectMime(opts);
+        }
+        catch {
+            // SDK detectMime 异常，降级到 fallback
+        }
+    }
+    return detectMimeFallback(opts);
+}
+// ============================================================================
+// loadOutboundMediaFromUrl —— 从 URL/路径加载媒体文件
+// ============================================================================
+/** 安全的本地文件路径校验，参考 weclaw/src/web/media.ts */
+async function assertLocalMediaAllowed(mediaPath, localRoots) {
+    if (!localRoots || localRoots.length === 0) {
+        throw new Error(`Local media path is not under an allowed directory: ${mediaPath}`);
+    }
+    let resolved;
+    try {
+        resolved = await fs.realpath(mediaPath);
+    }
+    catch {
+        resolved = path.resolve(mediaPath);
+    }
+    for (const root of localRoots) {
+        let resolvedRoot;
+        try {
+            resolvedRoot = await fs.realpath(root);
+        }
+        catch {
+            resolvedRoot = path.resolve(root);
+        }
+        if (resolvedRoot === path.parse(resolvedRoot).root) {
+            continue;
+        }
+        if (resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path.sep)) {
+            return;
+        }
+    }
+    throw new Error(`Local media path is not under an allowed directory: ${mediaPath}`);
+}
+/** 从远程 URL 获取媒体 */
+async function fetchRemoteMedia(url, maxBytes) {
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch media from ${url}: HTTP ${res.status} ${res.statusText}`);
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    if (maxBytes && buffer.length > maxBytes) {
+        throw new Error(`Media from ${url} exceeds max size (${buffer.length} > ${maxBytes})`);
+    }
+    const headerMime = res.headers.get("content-type")?.split(";")?.[0]?.trim();
+    let fileName;
+    const disposition = res.headers.get("content-disposition");
+    if (disposition) {
+        const match = /filename\*?\s*=\s*(?:UTF-8''|")?([^";]+)/i.exec(disposition);
+        if (match?.[1]) {
+            try {
+                fileName = path.basename(decodeURIComponent(match[1].replace(/["']/g, "").trim()));
+            }
+            catch {
+                fileName = path.basename(match[1].replace(/["']/g, "").trim());
+            }
+        }
+    }
+    if (!fileName) {
+        try {
+            const parsed = new URL(url);
+            const base = path.basename(parsed.pathname);
+            if (base && base.includes("."))
+                fileName = base;
+        }
+        catch { /* ignore */ }
+    }
+    const contentType = await detectMimeFallback({ buffer, headerMime, filePath: fileName ?? url });
+    return { buffer, contentType, fileName };
+}
+/** 展开 ~ 为用户主目录 */
+function resolveUserPath(p) {
+    if (p.startsWith("~")) {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+/** fallback 版 loadOutboundMediaFromUrl，参考 weclaw/src/web/media.ts */
+async function loadOutboundMediaFromUrlFallback(mediaUrl, options = {}) {
+    const { maxBytes, mediaLocalRoots } = options;
+    // 去除 MEDIA: 前缀
+    mediaUrl = mediaUrl.replace(/^\s*MEDIA\s*:\s*/i, "");
+    // 处理 file:// URL
+    if (mediaUrl.startsWith("file://")) {
+        try {
+            mediaUrl = fileURLToPath(mediaUrl);
+        }
+        catch {
+            throw new Error(`Invalid file:// URL: ${mediaUrl}`);
+        }
+    }
+    // 远程 URL
+    if (/^https?:\/\//i.test(mediaUrl)) {
+        const fetched = await fetchRemoteMedia(mediaUrl, maxBytes);
+        return {
+            buffer: fetched.buffer,
+            contentType: fetched.contentType,
+            fileName: fetched.fileName,
+        };
+    }
+    // 展开 ~ 路径
+    if (mediaUrl.startsWith("~")) {
+        mediaUrl = resolveUserPath(mediaUrl);
+    }
+    // 本地文件：安全校验
+    await assertLocalMediaAllowed(mediaUrl, mediaLocalRoots);
+    // 读取本地文件
+    let data;
+    try {
+        const stat = await fs.stat(mediaUrl);
+        if (!stat.isFile()) {
+            throw new Error(`Local media path is not a file: ${mediaUrl}`);
+        }
+        data = await fs.readFile(mediaUrl);
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            throw new Error(`Local media file not found: ${mediaUrl}`);
+        }
+        throw err;
+    }
+    if (maxBytes && data.length > maxBytes) {
+        throw new Error(`Local media exceeds max size (${data.length} > ${maxBytes})`);
+    }
+    const mime = await detectMimeFallback({ buffer: data, filePath: mediaUrl });
+    const fileName = path.basename(mediaUrl) || undefined;
+    return {
+        buffer: data,
+        contentType: mime,
+        fileName,
+    };
+}
+/**
+ * 从 URL 或本地路径加载媒体文件（兼容入口）
+ *
+ * 优先使用 SDK 版本，不可用时使用 fallback。
+ * SDK 版本抛出的业务异常（如 LocalMediaAccessError）会直接透传。
+ */
+async function loadOutboundMediaFromUrl(mediaUrl, options = {}) {
+    const sdk = await _sdkReady;
+    if (sdk.loadOutboundMediaFromUrl) {
+        return sdk.loadOutboundMediaFromUrl(mediaUrl, options);
+    }
+    return loadOutboundMediaFromUrlFallback(mediaUrl, options);
+}
+// ============================================================================
+// getDefaultMediaLocalRoots —— 获取默认媒体本地路径白名单
+// ============================================================================
+/** 解析 openclaw 状态目录 */
+function resolveStateDir$1() {
+    const stateOverride = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+    if (stateOverride)
+        return stateOverride;
+    return path.join(os.homedir(), ".openclaw");
+}
+/**
+ * 获取默认媒体本地路径白名单（兼容入口）
+ *
+ * 优先使用 SDK 版本，不可用时手动构建白名单（与 weclaw/src/media/local-roots.ts 逻辑一致）。
+ */
+async function getDefaultMediaLocalRoots() {
+    const sdk = await _sdkReady;
+    if (sdk.getDefaultMediaLocalRoots) {
+        try {
+            return sdk.getDefaultMediaLocalRoots();
+        }
+        catch {
+            // SDK 版本异常，降级到 fallback
+        }
+    }
+    // fallback: 手动构建默认白名单
+    const stateDir = path.resolve(resolveStateDir$1());
+    return [
+        path.join(stateDir, "media"),
+        path.join(stateDir, "agents"),
+        path.join(stateDir, "workspace"),
+        path.join(stateDir, "sandboxes"),
+    ];
+}
+
 /**
  * 企业微信渠道常量定义
  */
@@ -82,10 +392,10 @@ const MEDIA_DOCUMENT_PLACEHOLDER = "<media:document>";
 const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
 /** MCP 配置拉取超时时间（毫秒） */
 const MCP_CONFIG_FETCH_TIMEOUT_MS = 15000;
-const __filename$1 = fileURLToPath(import.meta.url);
-const __dirname$1 = path.dirname(__filename$1);
+const __filename$1 = fileURLToPath$1(import.meta.url);
+const __dirname$1 = path__default.dirname(__filename$1);
 const PLUGIN_JSON_FILENAME = "openclaw.plugin.json";
-path.resolve(path.join(__dirname$1, "../", PLUGIN_JSON_FILENAME));
+path__default.resolve(path__default.join(__dirname$1, "../", PLUGIN_JSON_FILENAME));
 // ============================================================================
 // 默认值
 // ============================================================================
@@ -93,6 +403,19 @@ path.resolve(path.join(__dirname$1, "../", PLUGIN_JSON_FILENAME));
 const DEFAULT_MEDIA_MAX_MB = 5;
 /** 文本分块大小上限 */
 const TEXT_CHUNK_LIMIT = 4000;
+// ============================================================================
+// 媒体上传相关常量
+// ============================================================================
+/** 图片大小上限（字节）：10MB */
+const IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+/** 视频大小上限（字节）：10MB */
+const VIDEO_MAX_BYTES = 10 * 1024 * 1024;
+/** 语音大小上限（字节）：2MB */
+const VOICE_MAX_BYTES = 2 * 1024 * 1024;
+/** 文件大小上限（字节）：20MB */
+const FILE_MAX_BYTES = 20 * 1024 * 1024;
+/** 文件绝对上限（字节）：超过此值无法发送，等于 FILE_MAX_BYTES */
+const ABSOLUTE_MAX_BYTES = FILE_MAX_BYTES;
 
 /**
  * 企业微信消息内容解析模块
@@ -234,12 +557,12 @@ async function sendWeComReply(params) {
     }
     const streamId = existingStreamId || generateReqId("stream");
     if (!wsClient.isConnected) {
-        runtime.error?.(`[WeCom] WSClient not connected, cannot send reply`);
+        runtime.error?.(`[wecom] WSClient not connected, cannot send reply`);
         throw new Error("WSClient not connected");
     }
     // 使用 SDK 的 replyStream 方法发送消息，带超时保护
     await withTimeout(wsClient.replyStream(frame, streamId, text, finish), REPLY_SEND_TIMEOUT_MS, `Reply send timed out (streamId=${streamId})`);
-    runtime.log?.(`[WeCom] Sent reply: streamId=${streamId}, finish=${finish}`);
+    runtime.log?.(`[plugin -> server] streamId=${streamId}, finish=${finish}, text=${text}`);
     return streamId;
 }
 
@@ -280,7 +603,7 @@ async function downloadAndSaveImages(params) {
     const mediaList = [];
     for (const imageUrl of imageUrls) {
         try {
-            runtime.log?.(`[WeCom] Downloading image from: ${imageUrl}`);
+            runtime.log?.(`[wecom] Downloading image: url=${imageUrl}`);
             const mediaMaxMb = config.agents?.defaults?.mediaMaxMb ?? DEFAULT_MEDIA_MAX_MB;
             const maxBytes = mediaMaxMb * 1024 * 1024;
             let imageBuffer;
@@ -293,26 +616,26 @@ async function downloadAndSaveImages(params) {
                 imageBuffer = result.buffer;
                 originalFilename = result.filename;
                 imageContentType = await detectImageContentType(imageBuffer);
-                runtime.log?.(`[WeCom] Image downloaded via SDK: size=${imageBuffer.length}, contentType=${imageContentType}${originalFilename ? `, filename=${originalFilename}` : ""}`);
+                runtime.log?.(`[wecom] Image downloaded: size=${imageBuffer.length}, contentType=${imageContentType}, filename=${originalFilename ?? '(none)'}`);
             }
             catch (sdkError) {
                 // 如果 SDK 方法失败，回退到原有方式（带超时保护）
-                runtime.log?.(`[WeCom] SDK download failed, falling back to manual download: ${String(sdkError)}`);
+                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}, first4Bytes=${fetched.buffer.slice(0, 4).toString("hex")}`);
+                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: Image does not appear to be a valid image format`);
+                    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] Image saved to ${saved.path}, finalContentType=${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)}`);
+            runtime.error?.(`[wecom] Failed to download image: ${String(err)}`);
         }
     }
     return mediaList;
@@ -326,7 +649,7 @@ async function downloadAndSaveFiles(params) {
     const mediaList = [];
     for (const fileUrl of fileUrls) {
         try {
-            runtime.log?.(`[WeCom] Downloading file from: ${fileUrl}`);
+            runtime.log?.(`[wecom] Downloading file: url=${fileUrl}`);
             const mediaMaxMb = config.agents?.defaults?.mediaMaxMb ?? DEFAULT_MEDIA_MAX_MB;
             const maxBytes = mediaMaxMb * 1024 * 1024;
             let fileBuffer;
@@ -341,27 +664,301 @@ async function downloadAndSaveFiles(params) {
                 // 检测文件类型
                 const type = await fileTypeFromBuffer(fileBuffer);
                 fileContentType = type?.mime ?? "application/octet-stream";
-                runtime.log?.(`[WeCom] File downloaded via SDK: size=${fileBuffer.length}, contentType=${fileContentType}${originalFilename ? `, filename=${originalFilename}` : ""}`);
+                runtime.log?.(`[wecom] File downloaded: size=${fileBuffer.length}, contentType=${fileContentType}, filename=${originalFilename ?? '(none)'}`);
             }
             catch (sdkError) {
                 // 如果 SDK 方法失败，回退到 fetchRemoteMedia（带超时保护）
-                runtime.log?.(`[WeCom] SDK file download failed, falling back to manual download: ${String(sdkError)}`);
+                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}`);
+                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] File saved to ${saved.path}, finalContentType=${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)}`);
+            runtime.error?.(`[wecom] Failed to download file: ${String(err)}`);
         }
     }
     return mediaList;
 }
 
+/**
+ * 企业微信出站媒体上传工具模块
+ *
+ * 负责：
+ * - 从 mediaUrl 加载文件 buffer（远程 URL 或本地路径均支持）
+ * - 检测 MIME 类型并映射为企微媒体类型
+ * - 文件大小检查与降级策略
+ */
+// ============================================================================
+// MIME → 企微媒体类型映射
+// ============================================================================
+/**
+ * 根据 MIME 类型检测企微媒体类型
+ *
+ * @param mimeType - MIME 类型字符串
+ * @returns 企微媒体类型
+ */
+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 解析后的媒体文件信息
+ */
+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 大小检查结果
+ */
+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;
+    }
+    // 无需降级
+    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 回调都使用此函数。
+ */
+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,
+        };
+    }
+}
+
 /**
  * 企业微信群组访问控制模块
  *
@@ -594,13 +1191,13 @@ function resolveStateDirFromEnv(env = process.env) {
         return stateOverride;
     }
     if (env.VITEST || env.NODE_ENV === "test") {
-        return path$1.join(os.tmpdir(), ["openclaw-vitest", String(process.pid)].join("-"));
+        return path__default$1.join(os__default.tmpdir(), ["openclaw-vitest", String(process.pid)].join("-"));
     }
-    return path$1.join(os.homedir(), ".openclaw");
+    return path__default$1.join(os__default.homedir(), ".openclaw");
 }
 function resolveReqIdFilePath(accountId) {
     const safe = accountId.replace(/[^a-zA-Z0-9_-]/g, "_");
-    return path$1.join(resolveStateDirFromEnv(), "wecom", `reqid-map-${safe}.json`);
+    return path__default$1.join(resolveStateDirFromEnv(), "wecom", `reqid-map-${safe}.json`);
 }
 // ============================================================================
 // 核心实现
@@ -1010,8 +1607,8 @@ async function saveMcpConfigToPluginJson(config, runtime) {
     //   const pluginJsonPath = PLUGIN_JSON_PATH;
     // 获取绝对路径并写入到配置文件
     //   const absolutePath = path.resolve(pluginJsonPath);
-    const wecomConfigDir = path.join(os$1.homedir(), ".openclaw", "wecomConfig");
-    const wecomConfigPath = path.join(wecomConfigDir, "config.json");
+    const wecomConfigDir = path__default.join(os__default$1.homedir(), ".openclaw", "wecomConfig");
+    const wecomConfigPath = path__default.join(wecomConfigDir, "config.json");
     //   // 写入 wecom 配置文件
     //   try {
     //     const lockOptions = {
@@ -1105,6 +1702,79 @@ async function fetchAndSaveMcpConfig(wsClient, accountId, runtime) {
  * - state-manager.ts   : 全局状态管理（带 TTL 清理）
  * - timeout.ts         : 超时工具
  */
+/**
+ * 去除文本中的 `<think>...</think>` 标签（支持跨行），返回剩余可见文本。
+ * 用于判断大模型回复中是否包含实际用户可见内容（而非仅有 thinking 推理过程）。
+ */
+function stripThinkTags(text) {
+    return text;
+    // return text.replace(/<think>[\s\S]*?<\/think>/g, "").trim();
+}
+// ============================================================================
+// 媒体本地路径白名单扩展
+// ============================================================================
+/**
+ * 解析 openclaw 状态目录（与 plugin-sdk 内部逻辑保持一致）
+ */
+function resolveStateDir() {
+    const stateOverride = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+    if (stateOverride)
+        return stateOverride;
+    return path$1.join(os$1.homedir(), ".openclaw");
+}
+/**
+ * 在 getDefaultMediaLocalRoots() 基础上，将 stateDir 本身也加入白名单，
+ * 并合并用户在 WeComConfig 中配置的自定义 mediaLocalRoots。
+ *
+ * getDefaultMediaLocalRoots() 仅包含 stateDir 下的子目录（media/agents/workspace/sandboxes），
+ * 但 agent 生成的文件可能直接放在 stateDir 根目录下（如 ~/.openclaw-dev/1.png），
+ * 因此需要将 stateDir 本身也加入白名单以避免 LocalMediaAccessError。
+ *
+ * 用户可在 openclaw.json 中配置：
+ * {
+ *   "channels": {
+ *     "wecom": {
+ *       "mediaLocalRoots": ["~/Downloads", "~/Documents"]
+ *     }
+ *   }
+ * }
+ */
+async function getExtendedMediaLocalRoots(config) {
+    // 从兼容层获取默认白名单（内部已处理低版本 SDK 的 fallback）
+    const defaults = await getDefaultMediaLocalRoots();
+    const roots = [...defaults];
+    const stateDir = path$1.resolve(resolveStateDir());
+    if (!roots.includes(stateDir)) {
+        roots.push(stateDir);
+    }
+    // 合并用户在 WeComConfig 中配置的自定义路径
+    if (config?.mediaLocalRoots) {
+        for (const r of config.mediaLocalRoots) {
+            const resolved = path$1.resolve(r.replace(/^~(?=\/|$)/, os$1.homedir()));
+            if (!roots.includes(resolved)) {
+                roots.push(resolved);
+            }
+        }
+    }
+    return roots;
+}
+// ============================================================================
+// 媒体发送错误提示
+// ============================================================================
+/**
+ * 根据媒体发送结果生成纯文本错误摘要（用于替换 thinking 流式消息展示给用户）。
+ *
+ * 使用纯文本而非 markdown 格式，因为 replyStream 只支持纯文本。
+ */
+function buildMediaErrorSummary(mediaUrl, result) {
+    if (result.error?.includes("LocalMediaAccessError")) {
+        return `⚠️ 文件发送失败：没有权限访问路径 ${mediaUrl}\n请在 openclaw.json 的 mediaLocalRoots 中添加该路径的父目录后重启生效。`;
+    }
+    if (result.rejectReason) {
+        return `⚠️ 文件发送失败：${result.rejectReason}`;
+    }
+    return `⚠️ 文件发送失败：无法处理文件 ${mediaUrl}，请稍后再试。`;
+}
 // ============================================================================
 // 消息上下文构建
 // ============================================================================
@@ -1166,15 +1836,11 @@ function buildMessageContext(frame, account, config, text, mediaList, quoteConte
         ReplyToBody: quoteContent,
     });
 }
-// ============================================================================
-// 消息处理和回复
-// ============================================================================
 /**
  * 发送"思考中"消息
  */
 async function sendThinkingReply(params) {
     const { wsClient, frame, streamId, runtime } = params;
-    runtime.log?.(`[WeCom] Sending thinking message`);
     try {
         await sendWeComReply({
             wsClient,
@@ -1186,15 +1852,105 @@ async function sendThinkingReply(params) {
         });
     }
     catch (err) {
-        runtime.error?.(`[WeCom] Failed to send thinking message: ${String(err)}`);
+        runtime.error?.(`[wecom] Failed to send thinking message: ${String(err)}`);
+    }
+}
+/**
+ * 累积文本并判断是否有可见内容（去除 <think> 标签后）
+ */
+function accumulateText(state, text) {
+    state.accumulatedText += text;
+    if (!state.hasText && stripThinkTags(state.accumulatedText)) {
+        state.hasText = true;
     }
 }
+/**
+ * 上传并发送一批媒体文件（统一走主动发送通道）
+ *
+ * replyMedia（被动回复）无法覆盖 replyStream 发出的 thinking 流式消息，
+ * 因此所有媒体统一走 aibot_send_msg 主动发送。
+ */
+async function sendMediaBatch(ctx, mediaUrls) {
+    const { wsClient, frame, state, account, runtime } = ctx;
+    const body = frame.body;
+    const chatId = body.chatid || body.from.userid;
+    const mediaLocalRoots = await getExtendedMediaLocalRoots(account.config);
+    runtime.log?.(`[wecom][debug] mediaLocalRoots=${JSON.stringify(mediaLocalRoots)}, mediaUrls=${JSON.stringify(mediaUrls)}, hasText=${!!state.hasText}`);
+    for (const mediaUrl of mediaUrls) {
+        const result = await uploadAndSendMedia({
+            wsClient,
+            mediaUrl,
+            chatId,
+            mediaLocalRoots,
+            log: (...args) => runtime.log?.(...args),
+            errorLog: (...args) => runtime.error?.(...args),
+        });
+        if (result.ok) {
+            state.hasMedia = true;
+        }
+        else {
+            state.hasMediaFailed = true;
+            runtime.error?.(`[wecom] Media send failed: url=${mediaUrl}, reason=${result.rejectReason || result.error}`);
+            // 收集错误摘要，后续在 finishThinkingStream 中直接替换 thinking 流展示给用户
+            const summary = buildMediaErrorSummary(mediaUrl, result);
+            state.mediaErrorSummary = state.mediaErrorSummary
+                ? `${state.mediaErrorSummary}\n\n${summary}`
+                : summary;
+        }
+    }
+}
+/**
+ * 关闭 thinking 流（发送 finish=true 的流式消息）
+ *
+ * thinking 是通过 replyStream 用 streamId 发的流式消息，
+ * 只有同一 streamId 的 replyStream(finish=true) 才能关闭它。
+ *
+ * ⚠️ 注意：企微会忽略空格等不可见内容，必须用有可见字符的文案才能真正
+ *    替换掉 thinking 动画，否则 thinking 会一直残留。
+ *
+ * 关闭策略（按优先级）：
+ * 1. 有可见文本 → 用完整文本关闭
+ * 2. 有媒体成功发送（通过 deliver 回调） → 用友好提示"文件已发送"
+ * 3. 媒体发送失败 → 直接用错误摘要替换 thinking
+ * 4. 其他 → 用通用"处理完成"提示
+ *    （agent 可能已通过内置 message 工具直接发送了文件，
+ *    该路径走 outbound.sendMedia 完全绕过 deliver 回调，
+ *    所以 state 中无记录，但文件已实际送达）
+ */
+async function finishThinkingStream(ctx) {
+    const { wsClient, frame, state, runtime } = ctx;
+    const visibleText = stripThinkTags(state.accumulatedText);
+    let finishText;
+    if (visibleText) {
+        // 有可见文本：用完整文本关闭流（覆盖 thinking 为真实内容）
+        finishText = state.accumulatedText;
+    }
+    else if (state.hasMedia) {
+        // 媒体成功发送：用友好提示告知用户
+        finishText = "📎 文件已发送，请查收。";
+    }
+    else if (state.hasMediaFailed && state.mediaErrorSummary) {
+        // 媒体发送失败：直接用错误摘要替换 thinking 流（不再额外发 sendMessage）
+        finishText = state.mediaErrorSummary;
+    }
+    else {
+        // 核心无可见文本且 deliver 中未处理过媒体。
+        //
+        // 不使用错误提示，因为 agent 可能已通过内置 message 工具直接调用
+        // outbound.sendMedia 成功发送了文件——该路径完全绕过 monitor 的 deliver
+        // 回调，所以 state.deliverCalled / state.hasMedia 均为 false，但文件
+        // 实际已送达用户。此时显示 "未生成回复" 会误导用户。
+        finishText = "✅ 处理完成。";
+    }
+    await sendWeComReply({ wsClient, frame, text: finishText, runtime, finish: true, streamId: state.streamId });
+}
 /**
  * 路由消息到核心处理流程并处理回复
  */
 async function routeAndDispatchMessage(params) {
-    const { ctxPayload, config, wsClient, frame, state, runtime, onCleanup } = params;
+    const { ctxPayload, config, account, wsClient, frame, state, runtime, onCleanup } = params;
     const core = getWeComRuntime();
+    const ctx = { wsClient, frame, state, account, runtime };
     // 防止 onCleanup 被多次调用（onError 回调与 catch 块可能重复触发）
     let cleanedUp = false;
     const safeCleanup = () => {
@@ -1209,37 +1965,54 @@ async function routeAndDispatchMessage(params) {
             cfg: config,
             dispatcherOptions: {
                 deliver: async (payload, info) => {
-                    state.accumulatedText += payload.text;
-                    if (info.kind !== "final") {
-                        await sendWeComReply({
-                            wsClient,
-                            frame,
-                            text: state.accumulatedText,
-                            runtime,
-                            finish: false,
-                            streamId: state.streamId,
-                        });
+                    state.deliverCalled = true;
+                    runtime.log?.(`[openclaw -> plugin] kind=${info.kind}, text=${payload.text ?? ''}, mediaUrl=${payload.mediaUrl ?? ''}, mediaUrls=${JSON.stringify(payload.mediaUrls ?? [])}`);
+                    // 累积文本
+                    if (payload.text) {
+                        accumulateText(state, payload.text);
+                    }
+                    // 发送媒体（统一走主动发送）
+                    const mediaUrls = payload.mediaUrls?.length ? payload.mediaUrls : payload.mediaUrl ? [payload.mediaUrl] : [];
+                    if (mediaUrls.length > 0) {
+                        try {
+                            await sendMediaBatch(ctx, mediaUrls);
+                        }
+                        catch (mediaErr) {
+                            // sendMediaBatch 内部异常（如 getDefaultMediaLocalRoots 不可用等）
+                            // 必须标记 state，否则 finishThinkingStream 会显示"处理完成"误导用户
+                            state.hasMediaFailed = true;
+                            const errMsg = String(mediaErr);
+                            const summary = `⚠️ 文件发送失败：内部处理异常，请升级 openclaw 到最新版本后重试。\n错误详情：${errMsg}`;
+                            state.mediaErrorSummary = state.mediaErrorSummary
+                                ? `${state.mediaErrorSummary}\n\n${summary}`
+                                : summary;
+                            runtime.error?.(`[wecom] sendMediaBatch threw: ${errMsg}`);
+                        }
+                    }
+                    // 中间帧：有可见文本时流式更新
+                    if (info.kind !== "final" && state.hasText && state.accumulatedText) {
+                        await sendWeComReply({ wsClient, frame, text: state.accumulatedText, runtime, finish: false, streamId: state.streamId });
                     }
                 },
                 onError: (err, info) => {
-                    runtime.error?.(`[WeCom] ${info.kind} reply failed: ${String(err)}`);
-                    // 仅记录错误，不立即 cleanup，让外层 try/catch 统一处理最终回复和 cleanup
+                    runtime.error?.(`[wecom] ${info.kind} reply failed: ${String(err)}`);
                 },
             },
         });
-        // 发送最终消息
-        await sendWeComReply({
-            wsClient,
-            frame,
-            text: state.accumulatedText,
-            runtime,
-            finish: true,
-            streamId: state.streamId,
-        });
+        // 关闭 thinking 流
+        await finishThinkingStream(ctx);
         safeCleanup();
     }
     catch (err) {
-        runtime.error?.(`[WeCom] Failed to process message: ${String(err)}`);
+        runtime.error?.(`[wecom][plugin] Failed to process message: ${String(err)}`);
+        // 即使 dispatch 抛异常，也需要关闭 thinking 流，
+        // 避免 deliver 已成功发送媒体但后续出错时 thinking 消息残留或被错误文案覆盖
+        try {
+            await finishThinkingStream(ctx);
+        }
+        catch (finishErr) {
+            runtime.error?.(`[wecom] Failed to finish thinking stream after dispatch error: ${String(finishErr)}`);
+        }
         safeCleanup();
     }
 }
@@ -1274,14 +2047,13 @@ async function processWeComMessage(params) {
     // 如果文本为空但存在引用消息，使用引用消息内容
     if (!text && quoteContent) {
         text = quoteContent;
-        runtime.log?.("[WeCom] Using quote content as message body (user only mentioned bot)");
+        runtime.log?.("[wecom][plugin] Using quote content as message body (user only mentioned bot)");
     }
     // 如果既没有文本也没有图片也没有文件也没有引用内容，则跳过
     if (!text && imageUrls.length === 0 && fileUrls.length === 0) {
-        runtime.log?.("[WeCom] Skipping empty message (no text, image, file or quote)");
+        runtime.log?.("[wecom][plugin] Skipping empty message (no text, image, file or quote)");
         return;
     }
-    runtime.log?.(`[WeCom] Processing ${chatType} message from chat: ${chatId} user: ${body.from.userid} reqId: ${reqId}${imageUrls.length > 0 ? ` (with ${imageUrls.length} image(s))` : ""}${fileUrls.length > 0 ? ` (with ${fileUrls.length} file(s))` : ""}${quoteContent ? ` (with quote)` : ""}`);
     // Step 2: 群组策略检查（仅群聊）
     if (chatType === "group") {
         const groupPolicyResult = checkGroupPolicy({
@@ -1342,10 +2114,12 @@ async function processWeComMessage(params) {
     }
     // Step 7: 构建上下文并路由到核心处理流程（带整体超时保护）
     const ctxPayload = buildMessageContext(frame, account, config, text, mediaList, quoteContent);
+    runtime.log?.(`[plugin -> openclaw] body=${text}, mediaPaths=${JSON.stringify(mediaList.map(m => m.path))}${quoteContent ? `, quote=${quoteContent}` : ''}`);
     try {
         await withTimeout(routeAndDispatchMessage({
             ctxPayload,
             config,
+            account,
             wsClient,
             frame,
             state,
@@ -1354,7 +2128,23 @@ async function processWeComMessage(params) {
         }), MESSAGE_PROCESS_TIMEOUT_MS, `Message processing timed out (msgId=${messageId})`);
     }
     catch (err) {
-        runtime.error?.(`[WeCom] Message processing failed or timed out: ${String(err)}`);
+        runtime.error?.(`[wecom][plugin] Message processing failed or timed out: ${String(err)}`);
+        // 确保 thinking 流被关闭，防止异常/超时时 thinking 消息一直残留
+        try {
+            if (shouldSendThinking) {
+                await sendWeComReply({
+                    wsClient,
+                    frame,
+                    text: "处理消息时出现异常，请稍后重试。",
+                    runtime,
+                    finish: true,
+                    streamId: state.streamId,
+                });
+            }
+        }
+        catch (finishErr) {
+            runtime.error?.(`[wecom] Failed to finish thinking stream on error: ${String(finishErr)}`);
+        }
         cleanupState();
     }
 }
@@ -1644,7 +2434,6 @@ async function sendWeComMessage({ to, content, accountId, }) {
     // 从 to 中提取 chatId（格式是 "${CHANNEL_ID}:chatId" 或直接是 chatId）
     const channelPrefix = new RegExp(`^${CHANNEL_ID}:`, "i");
     const chatId = to.replace(channelPrefix, "");
-    console.log(`[WeCom] sendWeComMessage: ${JSON.stringify({ to, content, accountId })}`);
     // 获取 WSClient 实例
     const wsClient = getWeComWebSocket(resolvedAccountId);
     if (!wsClient) {
@@ -1656,7 +2445,6 @@ async function sendWeComMessage({ to, content, accountId, }) {
         markdown: { content },
     });
     const messageId = result?.headers?.req_id ?? `wecom-${Date.now()}`;
-    console.log(`[WeCom] Sent message to ${chatId}, messageId=${messageId}`);
     return {
         channel: CHANNEL_ID,
         messageId,
@@ -1689,7 +2477,7 @@ const wecomPlugin = {
             //   content: " pairing approved",
             //   accountId: cfg.accountId,
             // });
-            console.log(`[WeCom] Pairing approved for user: ${id}`);
+            // Pairing approved for user
         },
     },
     onboarding: wecomOnboardingAdapter,
@@ -1816,14 +2604,51 @@ const wecomPlugin = {
         deliveryMode: "gateway",
         chunker: (text, limit) => getWeComRuntime().channel.text.chunkMarkdownText(text, limit),
         textChunkLimit: TEXT_CHUNK_LIMIT,
-        sendText: async ({ to, text, accountId, ...rest }) => {
-            console.log(`[WeCom] sendText: ${JSON.stringify({ to, text, accountId, ...rest })}`);
+        sendText: async ({ to, text, accountId }) => {
             return sendWeComMessage({ to, content: text, accountId: accountId ?? undefined });
         },
-        sendMedia: async ({ to, text, mediaUrl, accountId, ...rest }) => {
-            console.log(`[WeCom] sendMedia: ${JSON.stringify({ to, text, mediaUrl, accountId, ...rest })}`);
-            const content = `Sending attachments is not supported yet\n${text ? `${text}\n${mediaUrl}` : (mediaUrl ?? "")}`;
-            return sendWeComMessage({ to, content, accountId: accountId ?? undefined });
+        sendMedia: async ({ to, text, mediaUrl, mediaLocalRoots, accountId }) => {
+            const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
+            const channelPrefix = new RegExp(`^${CHANNEL_ID}:`, "i");
+            const chatId = to.replace(channelPrefix, "");
+            // 获取 WSClient 实例
+            const wsClient = getWeComWebSocket(resolvedAccountId);
+            if (!wsClient) {
+                throw new Error(`WSClient not connected for account ${resolvedAccountId}`);
+            }
+            // 如果没有 mediaUrl，fallback 为纯文本
+            if (!mediaUrl) {
+                return sendWeComMessage({ to, content: text || "", accountId: resolvedAccountId });
+            }
+            const result = await uploadAndSendMedia({
+                wsClient,
+                mediaUrl,
+                chatId,
+                mediaLocalRoots,
+            });
+            if (result.rejected) {
+                return sendWeComMessage({ to, content: `⚠️ ${result.rejectReason}`, accountId: resolvedAccountId });
+            }
+            if (!result.ok) {
+                // 上传/发送失败，fallback 为文本 + URL
+                const fallbackContent = text
+                    ? `${text}\n📎 ${mediaUrl}`
+                    : `📎 ${mediaUrl}`;
+                return sendWeComMessage({ to, content: fallbackContent, accountId: resolvedAccountId });
+            }
+            // 如有伴随文本，额外发送一条 markdown
+            if (text) {
+                await sendWeComMessage({ to, content: text, accountId: resolvedAccountId });
+            }
+            // 如果有降级说明，额外发送提示
+            if (result.downgradeNote) {
+                await sendWeComMessage({ to, content: `ℹ️ ${result.downgradeNote}`, accountId: resolvedAccountId });
+            }
+            return {
+                channel: CHANNEL_ID,
+                messageId: result.messageId,
+                chatId,
+            };
         },
     },
     status: {
@@ -1932,6 +2757,33 @@ const plugin = {
     register(api) {
         setWeComRuntime(api.runtime);
         api.registerChannel({ plugin: wecomPlugin });
+        // 注入媒体发送指令和文件大小限制提示词
+        api.on("before_prompt_build", () => {
+            return {
+                appendSystemContext: [
+                    "【发送文件/图片/视频/语音】",
+                    "当你需要向用户发送文件、图片、视频或语音时，必须在回复中单独一行使用 MEDIA: 指令，后面跟文件的本地路径。",
+                    "格式：MEDIA: /文件的绝对路径",
+                    "文件优先存放到 ~/.openclaw 目录下，确保路径可访问。",
+                    "示例：",
+                    "  MEDIA: ~/.openclaw/output.png",
+                    "  MEDIA: ~/.openclaw/report.pdf",
+                    "系统会自动识别文件类型并发送给用户。",
+                    "",
+                    "注意事项：",
+                    "- MEDIA: 必须在行首，后面紧跟文件路径（不是 URL）",
+                    "- 如果路径中包含空格，可以用反引号包裹：MEDIA: `/path/to/my file.png`",
+                    "- 每个文件单独一行 MEDIA: 指令",
+                    "- 可以在 MEDIA: 指令前后附带文字说明",
+                    "",
+                    "【文件大小限制】",
+                    "- 图片不超过 10MB，视频不超过 10MB，语音不超过 2MB（仅支持 AMR 格式），文件不超过 20MB",
+                    "- 语音消息仅支持 AMR 格式（.amr），如需发送语音请确保文件为 AMR 格式",
+                    "- 超过大小限制的图片/视频/语音会被自动转为文件格式发送",
+                    "- 如果文件超过 20MB，将无法发送，请提前告知用户并尝试缩减文件大小",
+                ].join("\n"),
+            };
+        });
     },
 };