@marshulll/openclaw-wecom 0.1.24 → 0.1.26

package/README.en.md

@@ -10,7 +10,7 @@ OpenClaw WeCom plugin supporting **Bot API mode** and **Internal App mode** with
 - Dual mode: Bot API (JSON callback + stream) / App (XML callback + ACK + proactive send)
 - Multi-account: `channels.wecom.accounts`
 - Message types: text / image / voice / video / file (send & receive)
-- Commands: `/help`, `/status`, `/clear`, `/sendfile`
+- Commands (App mode): `/help`, `/status`, `/clear`, `/sendfile`
 - Stability: signature verification, AES decrypt, token cache, rate limit & retries
 - Group chat: uses `appchat/send` when `chatId` is present
 - Advanced: folder zip sending, send queue, operation logs, media auto recognition
@@ -89,16 +89,36 @@ Install guide: `docs/INSTALL.md`
 - Bot mode media bridge: if reply payload includes `mediaUrl + mediaType`,
   and App credentials are present, media will be uploaded and sent
 
-## Extra commands
+## Extra commands (App mode)
 - `/sendfile`: send files from server (multiple absolute paths)
   - Directories are zipped automatically
   - Example: `/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - Natural language also works: "send me this file image-xxx.jpg" (default match in `media.tempDir`)
+  - Search scope keywords: `桌面` → `~/Desktop`, `下载` → `~/Downloads`, `临时` → `media.tempDir`
+  - If multiple matches are found, a list will be returned for confirmation
+
+## Proactive send (App mode)
+Push endpoint path: `{webhookPath}/push` (e.g. `/wecom/app/push`).
+
+- Method: `POST`
+- Auth: `pushToken` (optional but recommended)
+  - Accepts `Authorization: Bearer <token>`, `x-openclaw-token`, query/body `token`
+- Target: `toUser` (DM) or `chatId` (group)
+
+Minimal example (text):
+```bash
+curl -X POST "https://your-domain/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"Hello"}'
+```
+
+Media (file/image/voice/video): use `mediaUrl` or `mediaBase64`. You can also send text together.
 
 ## Media auto recognition (optional)
 - **Voice send/receive does NOT require API**; only auto transcription needs an OpenAI-compatible API
 - **Video recognition requires ffmpeg** (install on server, then set `media.auto.video.enabled = true`)
-- Video recognition supports **light / full** modes (default: light)
+- Video recognition supports **light / full** modes (default: light) via `media.auto.video.mode`
 - Small text files can be previewed automatically
 
 ## Send queue & operation logs (optional)

package/README.md

@@ -10,7 +10,7 @@ OpenClaw WeCom 插件，支持 **智能机器人 API 模式** 与 **自建应用
 - 双模式：Bot API（JSON 回调 + stream）/ App（XML 回调 + ACK + 主动发送）
 - 多账户：`channels.wecom.accounts`
 - 消息类型：文本 / 图片 / 语音 / 视频 / 文件（收发均支持）
-- 机器人命令：`/help`、`/status`、`/clear`、`/sendfile`
+- 机器人命令（App 模式）：`/help`、`/status`、`/clear`、`/sendfile`
 - 稳定性：签名校验、AES 解密、token 缓存、限流与重试
 - 群聊：自动识别 `chatId` 并使用 `appchat/send`
 - 进阶：文件夹打包发送、发送队列、操作日志、多媒体自动识别
@@ -91,16 +91,36 @@ openclaw gateway restart
 - Bot 模式媒体桥接：当 reply payload 含 `mediaUrl + mediaType` 时，
   若已配置 App 凭据，会自动上传并发送媒体
 
-## 命令补充
+## 命令补充（App 模式）
 - `/sendfile`：发送服务器文件（支持多个绝对路径）
   - 支持目录：自动打包为 zip 后发送
   - 示例：`/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - 也支持自然语言：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
+  - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
+  - 多文件会先返回列表，回复“全部”或序号再发送
+
+## 主动消息（App 模式）
+主动推送接口路径为：`{webhookPath}/push`（例如 `/wecom/app/push`）。
+
+- 方法：`POST`
+- 鉴权：`pushToken`（可选，但建议开启）
+  - 可放在 `Authorization: Bearer <token>`、`x-openclaw-token`、`token` 参数或 body 的 `token` 字段
+- 目标：`toUser`（单人）或 `chatId`（群聊），二选一
+
+最小示例（文本）：
+```bash
+curl -X POST "https://你的域名/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"你好"}'
+```
+
+发送媒体（file/image/voice/video）：支持 `mediaUrl` 或 `mediaBase64`，可与 `text` 同时发送。
 
 ## 多媒体自动识别（可选）
 - **语音收发不需要 API**，只有开启“语音自动转写”才需要 OpenAI 兼容接口
 - **视频识别需要 ffmpeg**（服务器已安装后，将 `media.auto.video.enabled` 设为 `true`）
-- 视频识别支持 **light / full** 两种模式（默认 light）
+- 视频识别支持 **light / full** 两种模式（默认 light），可通过 `media.auto.video.mode` 切换
 - 文本文件可自动预览（小文件直接读入）
 
 ## 发送队列与操作日志（可选）

package/README.zh.md

@@ -10,7 +10,7 @@ OpenClaw WeCom 插件，支持 **智能机器人 API 模式** 与 **自建应用
 - 双模式：Bot API（JSON 回调 + stream）/ App（XML 回调 + ACK + 主动发送）
 - 多账户：`channels.wecom.accounts`
 - 消息类型：文本 / 图片 / 语音 / 视频 / 文件（收发均支持）
-- 机器人命令：`/help`、`/status`、`/clear`、`/sendfile`
+- 机器人命令（App 模式）：`/help`、`/status`、`/clear`、`/sendfile`
 - 稳定性：签名校验、AES 解密、token 缓存、限流与重试
 - 群聊：自动识别 `chatId` 并使用 `appchat/send`
 - 进阶：文件夹打包发送、发送队列、操作日志、多媒体自动识别
@@ -91,16 +91,36 @@ openclaw gateway restart
 - Bot 模式媒体桥接：当 reply payload 含 `mediaUrl + mediaType` 时，
   若已配置 App 凭据，会自动上传并发送媒体
 
-## 命令补充
+## 命令补充（App 模式）
 - `/sendfile`：发送服务器文件（支持多个绝对路径）
   - 支持目录：自动打包为 zip 后发送
   - 示例：`/sendfile /tmp/openclaw-wecom /home/shu/Desktop/report.pdf`
   - 也支持自然语言：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
+  - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
+  - 多文件会先返回列表，回复“全部”或序号再发送
+
+## 主动消息（App 模式）
+主动推送接口路径为：`{webhookPath}/push`（例如 `/wecom/app/push`）。
+
+- 方法：`POST`
+- 鉴权：`pushToken`（可选，但建议开启）
+  - 可放在 `Authorization: Bearer <token>`、`x-openclaw-token`、`token` 参数或 body 的 `token` 字段
+- 目标：`toUser`（单人）或 `chatId`（群聊），二选一
+
+最小示例（文本）：
+```bash
+curl -X POST "https://你的域名/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"你好"}'
+```
+
+发送媒体（file/image/voice/video）：支持 `mediaUrl` 或 `mediaBase64`，可与 `text` 同时发送。
 
 ## 多媒体自动识别（可选）
 - **语音收发不需要 API**，只有开启“语音自动转写”才需要 OpenAI 兼容接口
 - **视频识别需要 ffmpeg**（服务器已安装后，将 `media.auto.video.enabled` 设为 `true`）
-- 视频识别支持 **light / full** 两种模式（默认 light）
+- 视频识别支持 **light / full** 两种模式（默认 light），可通过 `media.auto.video.mode` 切换
 - 文本文件可自动预览（小文件直接读入）
 
 ## 发送队列与操作日志（可选）

package/docs/INSTALL.md

@@ -129,9 +129,12 @@ openclaw gateway restart
 
 ## 高级能力（可选）
 ### /sendfile（文件与文件夹）
+- 仅 **App 模式** 支持 `/sendfile`
 - `/sendfile` 仅支持 **服务器绝对路径**
 - 目录会自动打包为 zip 再发送
 - 自然语言也可触发：`把这个文件发给我 image-xxx.jpg`（默认仅在 `media.tempDir` 内匹配）
+  - 搜索范围关键词：`桌面` → `~/Desktop`，`下载` → `~/Downloads`，`临时` → `media.tempDir`
+  - 如匹配多个文件，会返回列表让你确认（回复“全部”或序号）
 
 示例：
 ```
@@ -141,8 +144,14 @@ openclaw gateway restart
 ### 多媒体自动识别
 - **语音收发不需要 API**；只有开启“语音自动转写”才需要 OpenAI 兼容接口
 - **视频识别需要 ffmpeg**（服务器安装后将 `media.auto.video.enabled=true`）
+- **视频识别 light/full 模式**：`media.auto.video.mode`（默认 `light`）
 - 文本文件可自动预览（小文件直接读入）
 
+建议安装 ffmpeg（Ubuntu）：
+```bash
+sudo apt-get update && sudo apt-get install -y ffmpeg
+```
+
 ### 发送队列与操作日志
 - `sendQueue.intervalMs`：/sendfile 多文件发送间隔
 - `operations.logPath`：JSONL 日志，记录发送文件与主动推送
@@ -152,6 +161,24 @@ openclaw gateway restart
 - 在企业微信后台配置回调 URL。
 - 建议 Bot 与 App 使用不同 `webhookPath`，便于排障与避免回调混淆。
 
+## 主动推送（App 模式）
+主动推送接口路径：`{webhookPath}/push`（例如 `/wecom/app/push`）。
+
+- 方法：`POST`
+- 鉴权：`pushToken`（可选，但建议开启）
+  - `Authorization: Bearer <token>`、`x-openclaw-token`、`token` 参数或 body `token`
+- 目标：`toUser`（单人）或 `chatId`（群聊），二选一
+
+最小示例（文本）：
+```bash
+curl -X POST "https://你的域名/wecom/app/push" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer PUSH_TOKEN" \
+  -d '{"toUser":"WenShuJun","text":"你好"}'
+```
+
+媒体发送（file/image/voice/video）：使用 `mediaUrl` 或 `mediaBase64`，可与 `text` 同时发送。
+
 ## 常见问题
 - 回调验证失败：检查 Token / AESKey / URL 是否一致
 - 没有回复：检查 OpenClaw 是否已启用插件并重启 gateway

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshulll/openclaw-wecom",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "type": "module",
   "description": "OpenClaw WeCom channel plugin (intelligent bot + internal app)",
   "author": "OpenClaw",

package/wecom/src/wecom-app.ts

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import crypto from "node:crypto";
 import { XMLParser } from "fast-xml-parser";
 import { appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 
 import type { WecomWebhookTarget } from "./monitor.js";
@@ -135,6 +135,28 @@ function resolveSendIntervalMs(target: WecomWebhookTarget): number {
   return typeof interval === "number" && interval >= 0 ? interval : 400;
 }
 
+type PendingSendList = {
+  items: { name: string; path: string }[];
+  dirLabel: string;
+  createdAt: number;
+  expiresAt: number;
+};
+
+const pendingSendLists = new Map<string, PendingSendList>();
+const PENDING_TTL_MS = 10 * 60 * 1000;
+const MAX_LIST_PREVIEW = 30;
+
+function pendingKey(fromUser: string, chatId?: string): string {
+  return chatId ? `${fromUser}::${chatId}` : fromUser;
+}
+
+function prunePendingLists(): void {
+  const now = Date.now();
+  for (const [key, entry] of pendingSendLists.entries()) {
+    if (entry.expiresAt <= now) pendingSendLists.delete(key);
+  }
+}
+
 function extractFilenameCandidates(text: string): string[] {
   const candidates = new Set<string>();
   const normalized = text.replace(/[，,；;|]/g, " ");
@@ -146,6 +168,52 @@ function extractFilenameCandidates(text: string): string[] {
   return Array.from(candidates);
 }
 
+function extractExtension(text: string): string | null {
+  const match = text.match(/(?:\.|格式|后缀)?\s*([A-Za-z0-9]{2,8})/i);
+  if (!match) return null;
+  const ext = match[1]?.toLowerCase();
+  if (!ext) return null;
+  const allowed = new Set([
+    "png", "jpg", "jpeg", "gif", "bmp", "webp",
+    "pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx",
+    "zip", "rar", "7z",
+    "txt", "log", "csv", "json", "xml", "yaml", "yml",
+    "mp3", "wav", "amr", "mp4", "mov",
+  ]);
+  return allowed.has(ext) ? ext : null;
+}
+
+function resolveSearchDir(text: string, target: WecomWebhookTarget): { path: string; label: string } {
+  const lower = text.toLowerCase();
+  if (text.includes("桌面")) return { path: join(homedir(), "Desktop"), label: "桌面" };
+  if (text.includes("下载") || lower.includes("download")) return { path: join(homedir(), "Downloads"), label: "下载" };
+  if (text.includes("临时") || lower.includes("tmp")) return { path: resolveMediaTempDir(target), label: "临时目录" };
+  return { path: resolveMediaTempDir(target), label: "临时目录" };
+}
+
+function parseSelection(text: string, items: { name: string; path: string }[]): { name: string; path: string }[] | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  if (/全部|都要|全都|都给我/.test(trimmed)) return items;
+  const picked: { name: string; path: string }[] = [];
+  const numbers = Array.from(trimmed.matchAll(/\d+/g)).map((m) => Number(m[0]));
+  if (numbers.length > 0) {
+    for (const idx of numbers) {
+      const item = items[idx - 1];
+      if (item) picked.push(item);
+    }
+  }
+  const names = extractFilenameCandidates(trimmed);
+  if (names.length > 0) {
+    const map = new Map(items.map((item) => [item.name, item]));
+    for (const name of names) {
+      const item = map.get(name);
+      if (item) picked.push(item);
+    }
+  }
+  return picked.length > 0 ? picked : null;
+}
+
 async function tryHandleNaturalFileSend(params: {
   target: WecomWebhookTarget;
   text: string;
@@ -155,41 +223,69 @@ async function tryHandleNaturalFileSend(params: {
 }): Promise<boolean> {
   const { target, text, fromUser, chatId, isGroup } = params;
   if (!text || text.trim().startsWith("/")) return false;
+  prunePendingLists();
+  const key = pendingKey(fromUser, chatId);
+  const pending = pendingSendLists.get(key);
+  if (pending) {
+    const selection = parseSelection(text, pending.items);
+    if (selection) {
+      pendingSendLists.delete(key);
+      await sendFilesByPath({ target, fromUser, chatId, isGroup, items: selection });
+      return true;
+    }
+  }
+
   if (!/(发给我|发送给我|发我|给我)/.test(text)) return false;
   const names = extractFilenameCandidates(text);
-  if (names.length === 0) return false;
+  const ext = extractExtension(text);
+  if (names.length === 0 && !ext) return false;
 
-  const tempDir = resolveMediaTempDir(target);
+  const searchDir = resolveSearchDir(text, target);
   let dirEntries: string[] = [];
   try {
-    dirEntries = await readdir(tempDir);
+    dirEntries = await readdir(searchDir.path);
   } catch {
     dirEntries = [];
   }
   const dirSet = new Set(dirEntries);
 
-  const resolved: string[] = [];
+  const resolved: { name: string; path: string }[] = [];
   const missing: string[] = [];
-  for (const name of names) {
-    let fullPath = "";
-    if (name.startsWith("/")) {
-      fullPath = name;
-    } else if (dirSet.has(name)) {
-      fullPath = join(tempDir, name);
-    }
-    if (!fullPath) {
-      missing.push(name);
-      continue;
-    }
-    try {
-      const info = await stat(fullPath);
-      if (info.isFile()) {
-        resolved.push(fullPath);
-      } else {
+  if (names.length > 0) {
+    for (const name of names) {
+      let fullPath = "";
+      if (name.startsWith("/")) {
+        fullPath = name;
+      } else if (dirSet.has(name)) {
+        fullPath = join(searchDir.path, name);
+      }
+      if (!fullPath) {
         missing.push(name);
+        continue;
+      }
+      try {
+        const info = await stat(fullPath);
+        if (info.isFile()) {
+          resolved.push({ name: basename(fullPath), path: fullPath });
+        } else {
+          missing.push(name);
+        }
+      } catch {
+        missing.push(name);
+      }
+    }
+  } else if (ext) {
+    for (const entry of dirEntries) {
+      if (!entry.toLowerCase().endsWith(`.${ext}`)) continue;
+      const fullPath = join(searchDir.path, entry);
+      try {
+        const info = await stat(fullPath);
+        if (info.isFile()) {
+          resolved.push({ name: entry, path: fullPath });
+        }
+      } catch {
+        // ignore
       }
-    } catch {
-      missing.push(name);
     }
   }
 
@@ -204,25 +300,55 @@ async function tryHandleNaturalFileSend(params: {
     return true;
   }
 
+  if (resolved.length === 1) {
+    await sendFilesByPath({ target, fromUser, chatId, isGroup, items: resolved });
+    return true;
+  }
+
+  const preview = resolved.slice(0, MAX_LIST_PREVIEW)
+    .map((item, idx) => `${idx + 1}. ${item.name}`)
+    .join("\n");
+  const tail = resolved.length > MAX_LIST_PREVIEW ? `\n…共 ${resolved.length} 个文件` : "";
+  pendingSendLists.set(key, {
+    items: resolved,
+    dirLabel: searchDir.label,
+    createdAt: Date.now(),
+    expiresAt: Date.now() + PENDING_TTL_MS,
+  });
+  await sendWecomText({
+    account: target.account,
+    toUser: fromUser,
+    chatId: isGroup ? chatId : undefined,
+    text: `在${searchDir.label}找到 ${resolved.length} 个文件：\n${preview}${tail}\n\n回复“全部”或“1 3 5”或直接发送具体文件名。`,
+  });
+  return true;
+}
+
+async function sendFilesByPath(params: {
+  target: WecomWebhookTarget;
+  fromUser: string;
+  chatId?: string;
+  isGroup: boolean;
+  items: { name: string; path: string }[];
+}): Promise<void> {
+  const { target, fromUser, chatId, isGroup, items } = params;
   const maxBytes = resolveMediaMaxBytes(target);
   const intervalMs = resolveSendIntervalMs(target);
   let sent = 0;
   const failed: string[] = [];
-
-  for (const path of resolved) {
+  for (const item of items) {
     try {
-      const info = await stat(path);
+      const info = await stat(item.path);
       if (maxBytes && info.size > maxBytes) {
-        failed.push(`${basename(path)}(过大)`);
+        failed.push(`${item.name}(过大)`);
         continue;
       }
-      const buffer = await readFile(path);
-      const filename = basename(path) || "file.bin";
+      const buffer = await readFile(item.path);
       const mediaId = await uploadWecomMedia({
         account: target.account,
         type: "file",
         buffer,
-        filename,
+        filename: item.name,
       });
       await sendWecomFile({
         account: target.account,
@@ -236,31 +362,29 @@ async function tryHandleNaturalFileSend(params: {
         accountId: target.account.accountId,
         toUser: fromUser,
         chatId,
-        path,
+        path: item.path,
         size: info.size,
       });
       if (intervalMs) await sleep(intervalMs);
     } catch (err) {
-      failed.push(basename(path));
+      failed.push(item.name);
       await appendOperationLog(target, {
         action: "natural-sendfile",
         accountId: target.account.accountId,
         toUser: fromUser,
         chatId,
-        path,
+        path: item.path,
         error: String(err),
       });
     }
   }
-
-  const summary = `已发送 ${sent} 个文件${failed.length ? `，失败：${failed.join(", ")}` : ""}${missing.length ? `，未找到：${missing.join(", ")}` : ""}`;
+  const summary = `已发送 ${sent} 个文件${failed.length ? `，失败：${failed.join(", ")}` : ""}`;
   await sendWecomText({
     account: target.account,
     toUser: fromUser,
     chatId: isGroup ? chatId : undefined,
     text: summary,
   });
-  return true;
 }
 
 async function appendOperationLog(target: WecomWebhookTarget, entry: Record<string, unknown>): Promise<void> {

package/wecom/src/wecom-bot.ts

@@ -9,7 +9,15 @@ import type { PluginRuntime } from "openclaw/plugin-sdk";
 import type { WecomWebhookTarget } from "./monitor.js";
 import type { ResolvedWecomAccount, WecomInboundMessage } from "./types.js";
 import { computeWecomMsgSignature, decryptWecomEncrypted, encryptWecomPlaintext, verifyWecomSignature } from "./crypto.js";
-import { fetchMediaFromUrl, sendWecomFile, sendWecomImage, sendWecomVideo, sendWecomVoice, uploadWecomMedia } from "./wecom-api.js";
+import {
+  downloadWecomMedia,
+  fetchMediaFromUrl,
+  sendWecomFile,
+  sendWecomImage,
+  sendWecomVideo,
+  sendWecomVoice,
+  uploadWecomMedia,
+} from "./wecom-api.js";
 import { getWecomRuntime } from "./runtime.js";
 import { describeImageWithVision, resolveVisionConfig } from "./media-vision.js";
 import {
@@ -501,9 +509,13 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
   if (msgtype === "image") {
     return pickString(
       block.url,
+      block.imageUrl,
+      block.image_url,
       block.picurl,
       block.picUrl,
       block.pic_url,
+      msg.imageUrl,
+      msg.image_url,
       msg.picurl,
       msg.picUrl,
       msg.pic_url,
@@ -516,6 +528,8 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
       block.fileurl,
       block.fileUrl,
       block.file_url,
+      block.downloadUrl,
+      block.download_url,
       block.mediaUrl,
       block.media_url,
       msg.voiceUrl,
@@ -529,6 +543,8 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
       block.fileurl,
       block.fileUrl,
       block.file_url,
+      block.downloadUrl,
+      block.download_url,
       block.mediaUrl,
       block.media_url,
       msg.videoUrl,
@@ -541,6 +557,8 @@ function resolveBotMediaUrl(msg: any, msgtype: "image" | "voice" | "video" | "fi
     block.fileurl,
     block.fileUrl,
     block.file_url,
+    block.downloadUrl,
+    block.download_url,
     block.mediaUrl,
     block.media_url,
     msg.fileUrl,
@@ -554,12 +572,28 @@ function resolveBotMediaBase64(msg: any, msgtype: "image" | "voice" | "video" |
   const block = msg[msgtype] ?? {};
   return pickString(
     block.base64,
+    block.base64Data,
     block.data,
     msg.base64,
     msg.data,
   );
 }
 
+function resolveBotMediaId(msg: any, msgtype: "image" | "voice" | "video" | "file"): string {
+  if (!msg || typeof msg !== "object") return "";
+  const block = msg[msgtype] ?? {};
+  return pickString(
+    block.media_id,
+    block.mediaId,
+    block.mediaid,
+    block.mediaID,
+    msg.media_id,
+    msg.mediaId,
+    msg.mediaid,
+    msg.mediaID,
+  );
+}
+
 function resolveBotMediaFilename(msg: any): string {
   if (!msg || typeof msg !== "object") return "";
   const block = msg.file ?? {};
@@ -568,6 +602,7 @@ function resolveBotMediaFilename(msg: any): string {
     block.fileName,
     block.name,
     block.file_name,
+    block.file,
     msg.filename,
     msg.fileName,
     msg.name,
@@ -579,9 +614,10 @@ async function buildBotMediaMessage(params: {
   msgtype: "image" | "voice" | "video" | "file";
   url?: string;
   base64?: string;
+  mediaId?: string;
   filename?: string;
 }): Promise<InboundBody> {
-  const { target, msgtype, url, base64, filename } = params;
+  const { target, msgtype, url, base64, mediaId, filename } = params;
 
   const fallbackLabel = msgtype === "image"
     ? "[image]"
@@ -591,7 +627,7 @@ async function buildBotMediaMessage(params: {
         ? "[video]"
         : "[file]";
 
-  if (!url && !base64) return { text: fallbackLabel };
+  if (!url && !base64 && !mediaId) return { text: fallbackLabel };
 
   try {
     const cacheKey = buildMediaCacheKey({ url, base64 });
@@ -625,15 +661,23 @@ async function buildBotMediaMessage(params: {
     let buffer: Buffer | null = null;
     let contentType = "";
     if (base64) {
-      buffer = Buffer.from(base64, "base64");
-      if (msgtype === "image") contentType = "image/jpeg";
-      else if (msgtype === "voice") contentType = "audio/amr";
-      else if (msgtype === "video") contentType = "video/mp4";
-      else contentType = "application/octet-stream";
+      const parsed = parseBase64Input(base64);
+      buffer = Buffer.from(parsed.data, "base64");
+      if (parsed.mimeType) contentType = parsed.mimeType;
+      if (!contentType) {
+        if (msgtype === "image") contentType = "image/jpeg";
+        else if (msgtype === "voice") contentType = "audio/amr";
+        else if (msgtype === "video") contentType = "video/mp4";
+        else contentType = "application/octet-stream";
+      }
     } else if (url) {
       const media = await fetchMediaFromUrl(url, target.account);
       buffer = media.buffer;
       contentType = media.contentType;
+    } else if (mediaId && target.account.corpId && target.account.corpSecret && target.account.agentId) {
+      const media = await downloadWecomMedia({ account: target.account, mediaId });
+      buffer = media.buffer;
+      contentType = media.contentType;
     }
 
     if (!buffer) return { text: fallbackLabel };
@@ -771,9 +815,17 @@ async function buildInboundBody(params: { target: WecomWebhookTarget; msg: Wecom
   if (msgtype === "voice") {
     const content = (msg as any).voice?.content;
     if (typeof content === "string" && content.trim()) return { text: content.trim() };
+    const recognition = pickString(
+      (msg as any).voice?.recognition,
+      (msg as any).voice?.text,
+      (msg as any).voice?.transcript,
+      (msg as any).recognition,
+    );
+    if (recognition) return { text: recognition };
     const url = resolveBotMediaUrl(msg as any, "voice");
     const base64 = resolveBotMediaBase64(msg as any, "voice");
-    return await buildBotMediaMessage({ target, msgtype: "voice", url, base64 });
+    const mediaId = resolveBotMediaId(msg as any, "voice");
+    return await buildBotMediaMessage({ target, msgtype: "voice", url, base64, mediaId });
   }
   if (msgtype === "mixed") {
     const items = (msg as any).mixed?.msg_item;
@@ -794,18 +846,21 @@ async function buildInboundBody(params: { target: WecomWebhookTarget; msg: Wecom
   if (msgtype === "image") {
     const url = resolveBotMediaUrl(msg as any, "image");
     const base64 = resolveBotMediaBase64(msg as any, "image");
-    return await buildBotMediaMessage({ target, msgtype: "image", url, base64 });
+    const mediaId = resolveBotMediaId(msg as any, "image");
+    return await buildBotMediaMessage({ target, msgtype: "image", url, base64, mediaId });
   }
   if (msgtype === "file") {
     const url = resolveBotMediaUrl(msg as any, "file");
     const base64 = resolveBotMediaBase64(msg as any, "file");
+    const mediaId = resolveBotMediaId(msg as any, "file");
     const filename = resolveBotMediaFilename(msg as any);
-    return await buildBotMediaMessage({ target, msgtype: "file", url, base64, filename });
+    return await buildBotMediaMessage({ target, msgtype: "file", url, base64, mediaId, filename });
   }
   if (msgtype === "video") {
     const url = resolveBotMediaUrl(msg as any, "video");
     const base64 = resolveBotMediaBase64(msg as any, "video");
-    return await buildBotMediaMessage({ target, msgtype: "video", url, base64 });
+    const mediaId = resolveBotMediaId(msg as any, "video");
+    return await buildBotMediaMessage({ target, msgtype: "video", url, base64, mediaId });
   }
   if (msgtype === "event") {
     const eventtype = String((msg as any).event?.eventtype ?? "").trim();