@dingxiang-me/openclaw-wechat 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [2.0.1] - 2026-03-14
+
+### Fixed
+- 修复 WeCom Agent 回复 `/workspace/...` 文件路径时因动态会话工作区缺少目标文件，最终只回显路径文本而不实际发送图片/文件的问题
+- 修复 WeCom Bot 长连接对附件回调 payload 形态兼容不足，导致 PDF/文件消息被当成普通文本继续处理的问题；补充 `msg_type`、嵌套 `message`、`attachments/items`、`file_url/download_url/file_name/aes_key` 等兼容解析
+- 修复 WeCom Bot 入站文件/图片处理未完整透传媒体级 AES Key 的问题，降低 PDF/图片解密失败和内容损坏风险
+- 修复本地 `whisper-cli` 转写时临时音频文件在子进程真正读取前被提前清理，导致语音识别报错 `input file not found`
+- 补充 WeCom Bot 长连接未解析 callback 的运行日志，便于继续定位企业微信新回调形态
+
 ## [2.0.0] - 2026-03-13
 
 ### Changed

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-wechat",
   "name": "OpenClaw-Wechat",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "channels": [
     "wecom"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingxiang-me/openclaw-wechat",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "type": "module",
   "description": "WeCom (企业微信) channel plugin for OpenClaw (自建应用回调 + 发送 API).",
   "license": "MIT",

package/src/wecom/api-client-send-text.js

@@ -11,6 +11,26 @@ export function createWecomTextSender({
     throw new Error("createWecomTextSender: sendWecomTypedMessage is required");
   }
 
+  const targetSendChains = new Map();
+
+  function buildTargetKey({ corpId, agentId, toUser, toParty, toTag, chatId } = {}) {
+    const accountKey = `${corpId || "corp:unknown"}:${agentId || "agent:unknown"}`;
+    if (chatId) return `${accountKey}:chat:${chatId}`;
+    return `${accountKey}:direct:${[toUser, toParty, toTag].filter(Boolean).join("|") || "unknown"}`;
+  }
+
+  async function enqueueTargetSend(targetKey, task) {
+    const previous = targetSendChains.get(targetKey) || Promise.resolve();
+    const run = previous.catch(() => {}).then(task);
+    const tracked = run.finally(() => {
+      if (targetSendChains.get(targetKey) === tracked) {
+        targetSendChains.delete(targetKey);
+      }
+    });
+    targetSendChains.set(targetKey, tracked);
+    return run;
+  }
+
   async function sendWecomTextSingle({
     corpId,
     corpSecret,
@@ -57,29 +77,32 @@ export function createWecomTextSender({
     logger,
     proxyUrl,
   }) {
-    const chunks = splitWecomText(text);
-    logger?.info?.(`wecom: splitting message into ${chunks.length} chunks, total bytes=${getByteLength(text)}`);
+    const targetKey = buildTargetKey({ corpId, agentId, toUser, toParty, toTag, chatId });
+    return enqueueTargetSend(targetKey, async () => {
+      const chunks = splitWecomText(text);
+      logger?.info?.(`wecom: splitting message into ${chunks.length} chunks, total bytes=${getByteLength(text)}`);
 
-    for (let i = 0; i < chunks.length; i += 1) {
-      logger?.info?.(`wecom: sending chunk ${i + 1}/${chunks.length}, bytes=${getByteLength(chunks[i])}`);
-      // eslint-disable-next-line no-await-in-loop
-      await sendWecomTextSingle({
-        corpId,
-        corpSecret,
-        agentId,
-        toUser,
-        toParty,
-        toTag,
-        chatId,
-        text: chunks[i],
-        logger,
-        proxyUrl,
-      });
-      if (i < chunks.length - 1) {
+      for (let i = 0; i < chunks.length; i += 1) {
+        logger?.info?.(`wecom: sending chunk ${i + 1}/${chunks.length}, bytes=${getByteLength(chunks[i])}`);
         // eslint-disable-next-line no-await-in-loop
-        await sleep(300);
+        await sendWecomTextSingle({
+          corpId,
+          corpSecret,
+          agentId,
+          toUser,
+          toParty,
+          toTag,
+          chatId,
+          text: chunks[i],
+          logger,
+          proxyUrl,
+        });
+        if (i < chunks.length - 1) {
+          // eslint-disable-next-line no-await-in-loop
+          await sleep(300);
+        }
       }
-    }
+    });
   }
 
   return {

package/src/wecom/bot-inbound-content.js

@@ -40,9 +40,11 @@ export function createWecomBotInboundContentBuilder({
     botProxyUrl,
     msgType = "text",
     commandBody = "",
+    normalizedImageEntries = [],
     normalizedImageUrls = [],
     normalizedFileUrl = "",
     normalizedFileName = "",
+    normalizedFileAesKey = "",
     normalizedVoiceUrl = "",
     normalizedVoiceMediaId = "",
     normalizedVoiceContentType = "",
@@ -52,12 +54,17 @@ export function createWecomBotInboundContentBuilder({
     const tempPathsToCleanup = [];
     let messageText = String(commandBody ?? "").trim();
 
-    if (normalizedImageUrls.length > 0) {
+    if (normalizedImageUrls.length > 0 || normalizedImageEntries.length > 0) {
       const fetchedImagePaths = [];
-      const imageUrlsToFetch = normalizedImageUrls.slice(0, 3);
+      const imageEntriesToFetch =
+        Array.isArray(normalizedImageEntries) && normalizedImageEntries.length > 0
+          ? normalizedImageEntries.slice(0, 3)
+          : normalizedImageUrls.slice(0, 3).map((url) => ({ url, aesKey: "" }));
       const tempDir = join(tmpdir(), WECOM_TEMP_DIR_NAME);
       await mkdir(tempDir, { recursive: true });
-      for (const imageUrl of imageUrlsToFetch) {
+      for (const imageEntry of imageEntriesToFetch) {
+        const imageUrl = String(imageEntry?.url ?? "").trim();
+        const imageAesKey = String(imageEntry?.aesKey ?? "").trim();
         try {
           const { buffer, contentType } = await fetchMediaFromUrl(imageUrl, {
             proxyUrl: botProxyUrl,
@@ -73,10 +80,11 @@ export function createWecomBotInboundContentBuilder({
           let effectiveBuffer = buffer;
           let effectiveImageType =
             normalizedType.startsWith("image/") ? normalizedType : detectImageContentTypeFromBuffer(buffer);
-          if (!effectiveImageType && botModeConfig?.encodingAesKey) {
+          const decryptAesKey = imageAesKey || String(botModeConfig?.encodingAesKey ?? "").trim();
+          if (!effectiveImageType && decryptAesKey) {
             try {
               const decryptedBuffer = decryptWecomMediaBuffer({
-                aesKey: botModeConfig.encodingAesKey,
+                aesKey: decryptAesKey,
                 encryptedBuffer: buffer,
               });
               const decryptedImageType = detectImageContentTypeFromBuffer(decryptedBuffer);
@@ -158,7 +166,7 @@ export function createWecomBotInboundContentBuilder({
           });
           const decrypted = smartDecryptWecomFileBuffer({
             buffer: downloaded.buffer,
-            aesKey: botModeConfig?.encodingAesKey,
+            aesKey: normalizedFileAesKey || botModeConfig?.encodingAesKey,
             contentType: downloaded.contentType,
             sourceUrl: downloaded.finalUrl || normalizedFileUrl,
             decryptFn: decryptWecomMediaBuffer,

package/src/wecom/bot-inbound-executor-helpers.js

@@ -4,6 +4,33 @@ function assertFunction(name, value) {
   }
 }
 
+function normalizeBotImageEntries({ imageEntries, imageUrls } = {}) {
+  const normalized = [];
+  const seen = new Map();
+  const sourceEntries = Array.isArray(imageEntries) && imageEntries.length > 0
+    ? imageEntries
+    : Array.isArray(imageUrls)
+      ? imageUrls.map((url) => ({ url }))
+      : [];
+  for (const rawEntry of sourceEntries) {
+    if (rawEntry == null) continue;
+    const entry = typeof rawEntry === "string" ? { url: rawEntry } : rawEntry;
+    const url = String(entry?.url ?? "").trim();
+    if (!url) continue;
+    const aesKey = String(entry?.aesKey ?? "").trim();
+    const existingIndex = seen.get(url);
+    if (existingIndex == null) {
+      seen.set(url, normalized.length);
+      normalized.push({ url, aesKey });
+      continue;
+    }
+    if (!normalized[existingIndex].aesKey && aesKey) {
+      normalized[existingIndex] = { url, aesKey };
+    }
+  }
+  return normalized;
+}
+
 const UNSUPPORTED_BOT_GROUP_TRIGGER_WARNED = new Set();
 
 function warnUnsupportedBotGroupTriggerOnce(triggerMode, logger) {
@@ -91,9 +118,11 @@ export function createWecomBotInboundFlowState({
   accountId = "default",
   fromUser,
   content,
+  imageEntries,
   imageUrls,
   fileUrl,
   fileName,
+  fileAesKey,
   voiceUrl,
   voiceMediaId,
   voiceContentType,
@@ -109,6 +138,7 @@ export function createWecomBotInboundFlowState({
   const normalizedAccountId = String(accountId ?? "default").trim().toLowerCase() || "default";
   const normalizedFromUser = String(fromUser ?? "").trim().toLowerCase();
   const baseSessionId = buildWecomBotSessionId(fromUser, normalizedAccountId);
+  const normalizedImageEntries = normalizeBotImageEntries({ imageEntries, imageUrls });
   const state = {
     runtime,
     cfg,
@@ -127,8 +157,11 @@ export function createWecomBotInboundFlowState({
     tempPathsToCleanup: [],
     botModeConfig: resolveWecomBotConfig(api, normalizedAccountId),
     botProxyUrl: resolveWecomBotProxyConfig(api, normalizedAccountId),
+    normalizedImageEntries,
+    normalizedImageUrls: normalizedImageEntries.map((entry) => entry.url),
     normalizedFileUrl: String(fileUrl ?? "").trim(),
     normalizedFileName: String(fileName ?? "").trim(),
+    normalizedFileAesKey: String(fileAesKey ?? "").trim(),
     normalizedVoiceUrl: String(voiceUrl ?? "").trim(),
     normalizedVoiceMediaId: String(voiceMediaId ?? "").trim(),
     normalizedVoiceContentType: String(voiceContentType ?? "").trim(),
@@ -139,13 +172,6 @@ export function createWecomBotInboundFlowState({
             content: String(quote.content ?? "").trim(),
           }
         : null,
-    normalizedImageUrls: Array.from(
-      new Set(
-        (Array.isArray(imageUrls) ? imageUrls : [])
-          .map((item) => String(item ?? "").trim())
-          .filter(Boolean),
-      ),
-    ),
     groupChatPolicy: normalizeWecomBotGroupChatPolicy(resolveWecomGroupChatPolicy(api), api?.logger),
     dynamicAgentPolicy: resolveWecomDynamicAgentPolicy(api),
     isAdminUser: false,

package/src/wecom/bot-inbound-executor.js

@@ -21,8 +21,10 @@ export async function executeWecomBotInboundFlow(payload = {}) {
     chatId,
     isGroupChat = false,
     imageUrls = [],
+    imageEntries = [],
     fileUrl = "",
     fileName = "",
+    fileAesKey = "",
     voiceUrl = "",
     voiceMediaId = "",
     voiceContentType = "",
@@ -76,9 +78,11 @@ export async function executeWecomBotInboundFlow(payload = {}) {
     accountId,
     fromUser,
     content,
+    imageEntries,
     imageUrls,
     fileUrl,
     fileName,
+    fileAesKey,
     voiceUrl,
     voiceMediaId,
     voiceContentType,
@@ -175,9 +179,11 @@ export async function executeWecomBotInboundFlow(payload = {}) {
       botProxyUrl: state.botProxyUrl,
       msgType,
       commandBody: state.commandBody,
+      normalizedImageEntries: state.normalizedImageEntries,
       normalizedImageUrls: state.normalizedImageUrls,
       normalizedFileUrl: state.normalizedFileUrl,
       normalizedFileName: state.normalizedFileName,
+      normalizedFileAesKey: state.normalizedFileAesKey,
       normalizedVoiceUrl: state.normalizedVoiceUrl,
       normalizedVoiceMediaId: state.normalizedVoiceMediaId,
       normalizedVoiceContentType: state.normalizedVoiceContentType,

package/src/wecom/bot-long-connection-manager.js

@@ -513,8 +513,10 @@ export function createWecomBotLongConnectionManager({
               chatId: parsed.chatId,
               isGroupChat: parsed.isGroupChat,
               imageUrls: parsed.imageUrls,
+              imageEntries: parsed.imageEntries,
               fileUrl: parsed.fileUrl,
               fileName: parsed.fileName,
+              fileAesKey: parsed.fileAesKey,
               quote: parsed.quote,
               responseUrl: parsed.responseUrl,
               accountId: parsed.accountId,
@@ -691,6 +693,16 @@ export function createWecomBotLongConnectionManager({
           ? { ...payload.body, msgtype: "event" }
           : payload?.body;
       const parsed = parseWecomBotInboundMessage(normalizedBody);
+      if (!parsed) {
+        const bodyKeys =
+          normalizedBody && typeof normalizedBody === "object"
+            ? Object.keys(normalizedBody).slice(0, 12).join(",")
+            : "non-object";
+        api?.logger?.warn?.(
+          `wecom(bot-longconn): ignored unparsed callback account=${client.accountId} cmd=${command} bodyKeys=${bodyKeys || "n/a"}`,
+        );
+        return;
+      }
       if (parsed && typeof parsed === "object") {
         parsed.reqId = reqId || buildRequestId(CMD_CALLBACK);
       }

package/src/wecom/bot-webhook-dispatch.js

@@ -141,8 +141,10 @@ export function createWecomBotParsedDispatcher({
               chatId: parsed.chatId,
               isGroupChat: parsed.isGroupChat,
               imageUrls: parsed.imageUrls,
+              imageEntries: parsed.imageEntries,
               fileUrl: parsed.fileUrl,
               fileName: parsed.fileName,
+              fileAesKey: parsed.fileAesKey,
               quote: parsed.quote,
               responseUrl: parsed.responseUrl,
               accountId: parsed.accountId,

package/src/wecom/outbound-delivery.js

@@ -260,9 +260,6 @@ export function createWecomBotReplyDeliverer({
           });
         },
         active_stream: async ({ text: content }) => {
-          if (longConnectionContext) {
-            return { ok: false, reason: "long-connection-context" };
-          }
           return deliverActiveStreamReply({
             streamId,
             sessionId: normalizedSessionId,

package/src/wecom/outbound-webhook-sender.js

@@ -32,6 +32,26 @@ export function createWecomWebhookOutboundSender({
   assertFunction("createHash", createHash);
   assertFunction("sleep", sleep);
 
+  const webhookSendChains = new Map();
+
+  function buildWebhookTargetKey({ target, sendUrl }) {
+    return [String(target?.url ?? "").trim(), String(target?.key ?? "").trim(), String(sendUrl ?? "").trim()]
+      .filter(Boolean)
+      .join("|");
+  }
+
+  async function enqueueWebhookSend(targetKey, task) {
+    const previous = webhookSendChains.get(targetKey) || Promise.resolve();
+    const run = previous.catch(() => {}).then(task);
+    const tracked = run.finally(() => {
+      if (webhookSendChains.get(targetKey) === tracked) {
+        webhookSendChains.delete(targetKey);
+      }
+    });
+    webhookSendChains.set(targetKey, tracked);
+    return run;
+  }
+
   function resolveWebhookSendContext({ webhook, webhookTargets, proxyUrl, logger }) {
     const target = resolveWecomWebhookTargetConfig(webhook, webhookTargets);
     if (!target) {
@@ -45,31 +65,34 @@ export function createWecomWebhookOutboundSender({
       throw new Error("invalid webhook target url/key");
     }
     const dispatcher = attachWecomProxyDispatcher(sendUrl, {}, { proxyUrl, logger })?.dispatcher;
-    return { target, dispatcher };
+    return { target, dispatcher, sendUrl };
   }
 
   async function sendWecomWebhookText({ webhook, webhookTargets, text, logger, proxyUrl }) {
-    const { target, dispatcher } = resolveWebhookSendContext({
+    const { target, dispatcher, sendUrl } = resolveWebhookSendContext({
       webhook,
       webhookTargets,
       proxyUrl,
       logger,
     });
-    const chunks = splitWecomText(String(text ?? ""));
-    for (let i = 0; i < chunks.length; i += 1) {
-      await webhookSendText({
-        url: target.url,
-        key: target.key,
-        content: chunks[i],
-        timeoutMs: 15000,
-        dispatcher,
-        fetchImpl,
-      });
-      if (i < chunks.length - 1) {
-        await sleep(200);
+    const targetKey = buildWebhookTargetKey({ target, sendUrl });
+    return enqueueWebhookSend(targetKey, async () => {
+      const chunks = splitWecomText(String(text ?? ""));
+      for (let i = 0; i < chunks.length; i += 1) {
+        await webhookSendText({
+          url: target.url,
+          key: target.key,
+          content: chunks[i],
+          timeoutMs: 15000,
+          dispatcher,
+          fetchImpl,
+        });
+        if (i < chunks.length - 1) {
+          await sleep(200);
+        }
       }
-    }
-    logger?.info?.(`wecom: webhook text sent chunks=${chunks.length}`);
+      logger?.info?.(`wecom: webhook text sent chunks=${chunks.length}`);
+    });
   }
 
   async function sendWecomWebhookMediaBatch({

package/src/wecom/plugin-constants.js

@@ -1,5 +1,5 @@
 export const MAX_REQUEST_BODY_SIZE = 1024 * 1024;
-export const PLUGIN_VERSION = "2.0.0";
+export const PLUGIN_VERSION = "2.0.1";
 export const WECOM_TEMP_DIR_NAME = "openclaw-wechat";
 export const WECOM_TEMP_FILE_RETENTION_MS = 30 * 60 * 1000;
 export const WECOM_MIN_FILE_SIZE = 5;

package/src/wecom/target-utils.js

@@ -3,13 +3,38 @@ export function createWecomTargetResolver({ resolveWecomTarget } = {}) {
     throw new Error("createWecomTargetResolver: resolveWecomTarget is required");
   }
 
+  function readString(value) {
+    return String(value ?? "").trim();
+  }
+
+  function pickFirstString(...values) {
+    for (const value of values) {
+      const normalized = readString(value);
+      if (normalized) return normalized;
+    }
+    return "";
+  }
+
   function normalizeWecomResolvedTarget(rawTarget) {
     if (rawTarget && typeof rawTarget === "object") {
-      const toUser = String(rawTarget.toUser ?? "").trim();
-      const toParty = String(rawTarget.toParty ?? "").trim();
-      const toTag = String(rawTarget.toTag ?? "").trim();
-      const chatId = String(rawTarget.chatId ?? "").trim();
-      const webhook = String(rawTarget.webhook ?? "").trim();
+      const toUser = pickFirstString(
+        rawTarget.toUser,
+        rawTarget.userId,
+        rawTarget.userid,
+        rawTarget.user,
+        rawTarget.username,
+      );
+      const toParty = pickFirstString(
+        rawTarget.toParty,
+        rawTarget.partyId,
+        rawTarget.partyid,
+        rawTarget.deptId,
+        rawTarget.deptid,
+        rawTarget.departmentId,
+      );
+      const toTag = pickFirstString(rawTarget.toTag, rawTarget.tagId, rawTarget.tagid);
+      const chatId = pickFirstString(rawTarget.chatId, rawTarget.chatid, rawTarget.groupId, rawTarget.groupid);
+      const webhook = pickFirstString(rawTarget.webhook, rawTarget.webhookId, rawTarget.webhookTarget);
       if (toUser || toParty || toTag || chatId || webhook) {
         return {
           ...(toUser ? { toUser } : {}),
@@ -19,6 +44,17 @@ export function createWecomTargetResolver({ resolveWecomTarget } = {}) {
           ...(webhook ? { webhook } : {}),
         };
       }
+      const nestedTarget = pickFirstString(
+        rawTarget.to,
+        rawTarget.target,
+        rawTarget.value,
+        rawTarget.address,
+        rawTarget.rawTarget,
+      );
+      if (nestedTarget) {
+        const resolvedNestedTarget = resolveWecomTarget(nestedTarget);
+        return resolvedNestedTarget && typeof resolvedNestedTarget === "object" ? resolvedNestedTarget : null;
+      }
     }
     const resolved = resolveWecomTarget(rawTarget);
     return resolved && typeof resolved === "object" ? resolved : null;

package/src/wecom/voice-transcription-process.js

@@ -1,4 +1,7 @@
 import { spawn } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import { delimiter } from "node:path";
 
 function assertFunction(name, value) {
   if (typeof value !== "function") {
@@ -9,6 +12,8 @@ function assertFunction(name, value) {
 export function createVoiceTranscriptionProcessRuntime({
   runProcessWithTimeoutImpl,
   checkCommandAvailableImpl,
+  processEnv = process.env,
+  accessImpl = access,
 } = {}) {
   const ffmpegPathCheckCache = {
     checked: false,
@@ -16,6 +21,50 @@ export function createVoiceTranscriptionProcessRuntime({
   };
   const commandPathCheckCache = new Map();
 
+  function readString(value) {
+    return String(value ?? "").trim();
+  }
+
+  function uniqueStrings(values) {
+    return Array.from(
+      new Set(
+        values
+          .map((value) => readString(value))
+          .filter(Boolean),
+      ),
+    );
+  }
+
+  function listCandidateCommandPaths(command) {
+    const normalizedCommand = readString(command);
+    if (!normalizedCommand) return [];
+    if (normalizedCommand.includes("/")) {
+      return [normalizedCommand];
+    }
+    const homeDir = readString(processEnv?.HOME);
+    const pathDirs = readString(processEnv?.PATH)
+      .split(delimiter)
+      .map((entry) => readString(entry))
+      .filter(Boolean);
+    const pythonUserBins = homeDir
+      ? ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"].map(
+          (version) => `${homeDir}/Library/Python/${version}/bin`,
+        )
+      : [];
+    const searchDirs = uniqueStrings([
+      ...pathDirs,
+      homeDir ? `${homeDir}/.local/bin` : "",
+      homeDir ? `${homeDir}/bin` : "",
+      ...pythonUserBins,
+      "/usr/local/bin",
+      "/opt/homebrew/bin",
+    ]);
+    return uniqueStrings([
+      normalizedCommand,
+      ...searchDirs.map((dir) => `${dir}/${normalizedCommand}`),
+    ]);
+  }
+
   function runProcessWithTimeout({ command, args, timeoutMs = 15000, allowNonZeroExitCode = false }) {
     if (typeof runProcessWithTimeoutImpl === "function") {
       return runProcessWithTimeoutImpl({ command, args, timeoutMs, allowNonZeroExitCode });
@@ -72,6 +121,16 @@ export function createVoiceTranscriptionProcessRuntime({
     if (commandPathCheckCache.has(normalized)) {
       return commandPathCheckCache.get(normalized);
     }
+    if (normalized.includes("/")) {
+      try {
+        await accessImpl(normalized, fsConstants.X_OK);
+        commandPathCheckCache.set(normalized, true);
+        return true;
+      } catch {
+        commandPathCheckCache.set(normalized, false);
+        return false;
+      }
+    }
     try {
       await runProcessWithTimeout({
         command: normalized,
@@ -101,15 +160,18 @@ export function createVoiceTranscriptionProcessRuntime({
   function listLocalWhisperCommandCandidates({ voiceConfig } = {}) {
     const provider = String(voiceConfig?.provider ?? "").trim().toLowerCase();
     const explicitCommand = String(voiceConfig?.command ?? "").trim();
-    const fallbackCandidates =
+    const fallbackCommandNames =
       provider === "local-whisper"
         ? ["whisper"]
         : provider === "local-whisper-cli"
           ? ["whisper-cli"]
           : [];
-    const candidates = explicitCommand ? [explicitCommand, ...fallbackCandidates] : fallbackCandidates;
+    const commandNames = explicitCommand
+      ? uniqueStrings([explicitCommand, ...fallbackCommandNames])
+      : uniqueStrings(fallbackCommandNames);
+    const candidates = uniqueStrings(commandNames.flatMap((command) => listCandidateCommandPaths(command)));
 
-    if (candidates.length === 0) {
+    if (commandNames.length === 0) {
       return {
         provider,
         explicitCommand,

package/src/wecom/voice-transcription.js

@@ -29,6 +29,7 @@ export function createWecomVoiceTranscriber({
   const processRuntime = createVoiceTranscriptionProcessRuntime({
     runProcessWithTimeoutImpl,
     checkCommandAvailableImpl,
+    processEnv,
   });
   const {
     runProcessWithTimeout,
@@ -206,7 +207,7 @@ export function createWecomVoiceTranscriber({
         if (voiceConfig.requireModelPath !== false && !voiceConfig.modelPath) {
           throw new Error("voiceTranscription.modelPath is required for local-whisper-cli (or set requireModelPath=false)");
         }
-        return transcribeWithWhisperCli({
+        return await transcribeWithWhisperCli({
           command,
           modelPath: voiceConfig.modelPath,
           audioPath,
@@ -217,7 +218,7 @@ export function createWecomVoiceTranscriber({
       }
 
       if (provider === "local-whisper") {
-        return transcribeWithWhisperPython({
+        return await transcribeWithWhisperPython({
           command,
           model: voiceConfig.model,
           audioPath,

package/src/wecom/webhook-adapter-normalize.js

@@ -18,6 +18,25 @@ export function dedupeUrlList(urls) {
   return out;
 }
 
+function dedupeMediaEntries(entries) {
+  const seen = new Map();
+  for (const rawEntry of Array.isArray(entries) ? entries : []) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const url = normalizeToken(rawEntry.url);
+    if (!url) continue;
+    const aesKey = normalizeToken(rawEntry.aesKey);
+    const existing = seen.get(url);
+    if (!existing) {
+      seen.set(url, { url, aesKey });
+      continue;
+    }
+    if (!existing.aesKey && aesKey) {
+      seen.set(url, { url, aesKey });
+    }
+  }
+  return Array.from(seen.values());
+}
+
 export function collectWecomBotImageUrls(imageLike) {
   return dedupeUrlList([
     imageLike?.url,
@@ -28,6 +47,16 @@ export function collectWecomBotImageUrls(imageLike) {
   ]);
 }
 
+export function collectWecomBotImageEntries(imageLike) {
+  const aesKey = normalizeToken(imageLike?.aeskey || imageLike?.aes_key || imageLike?.aesKey);
+  return dedupeMediaEntries(
+    collectWecomBotImageUrls(imageLike).map((url) => ({
+      url,
+      aesKey,
+    })),
+  );
+}
+
 export function normalizeWecomBotOutboundMediaUrls(payload = {}) {
   return dedupeUrlList([
     payload?.mediaUrl,

package/src/wecom/webhook-adapter.js

@@ -1,4 +1,5 @@
 import {
+  collectWecomBotImageEntries,
   collectWecomBotImageUrls,
   dedupeUrlList,
   normalizeLowerToken,
@@ -7,7 +8,202 @@ import {
   normalizeWecomBotOutboundMediaUrls,
 } from "./webhook-adapter-normalize.js";
 
-export { collectWecomBotImageUrls, normalizeWecomBotOutboundMediaUrls };
+export { collectWecomBotImageEntries, collectWecomBotImageUrls, normalizeWecomBotOutboundMediaUrls };
+
+function dedupeMediaEntries(entries) {
+  const seen = new Map();
+  for (const rawEntry of Array.isArray(entries) ? entries : []) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const url = normalizeToken(rawEntry.url);
+    if (!url) continue;
+    const aesKey = normalizeToken(rawEntry.aesKey);
+    const existing = seen.get(url);
+    if (!existing) {
+      seen.set(url, { url, aesKey });
+      continue;
+    }
+    if (!existing.aesKey && aesKey) {
+      seen.set(url, { url, aesKey });
+    }
+  }
+  return Array.from(seen.values());
+}
+
+function pickNestedValue(source, paths = []) {
+  if (!source || typeof source !== "object") return undefined;
+  for (const rawPath of Array.isArray(paths) ? paths : []) {
+    const segments = Array.isArray(rawPath)
+      ? rawPath
+      : String(rawPath ?? "")
+          .split(".")
+          .map((part) => String(part ?? "").trim())
+          .filter(Boolean);
+    if (segments.length === 0) continue;
+    let current = source;
+    let found = true;
+    for (const segment of segments) {
+      if (!current || typeof current !== "object" || !Object.hasOwn(current, segment)) {
+        found = false;
+        break;
+      }
+      current = current[segment];
+    }
+    if (found && current != null) {
+      return current;
+    }
+  }
+  return undefined;
+}
+
+function collectWecomBotMixedItems(payload) {
+  const directItems = pickNestedValue(payload, [
+    ["mixed", "msg_item"],
+    ["mixed", "msgItem"],
+    ["mixed", "items"],
+    ["mixed", "msgItems"],
+    ["msg_item"],
+    ["msgItem"],
+    ["items"],
+    ["attachments"],
+    ["attachment"],
+    ["message", "attachments"],
+    ["message", "items"],
+    ["message", "msg_item"],
+    ["message", "msgItem"],
+  ]);
+  if (Array.isArray(directItems)) {
+    return directItems.filter((item) => item && typeof item === "object");
+  }
+  return [];
+}
+
+function inferWecomBotItemType(item) {
+  const explicitType = normalizeLowerToken(
+    item?.msgtype ||
+      item?.msg_type ||
+      item?.msgType ||
+      item?.type ||
+      item?.message_type ||
+      item?.messageType ||
+      item?.kind,
+  );
+  if (explicitType) return explicitType;
+  if (item?.text || item?.content_type === "text" || item?.contentType === "text") return "text";
+  if (item?.image || item?.pic_url || item?.image_url || item?.imageUrl) return "image";
+  if (item?.voice || item?.voice_url || item?.voiceUrl || item?.audio || item?.audio_url || item?.audioUrl) return "voice";
+  if (
+    item?.file ||
+    item?.file_url ||
+    item?.fileUrl ||
+    item?.download_url ||
+    item?.downloadUrl ||
+    item?.filename ||
+    item?.file_name
+  ) {
+    return "file";
+  }
+  if (item?.link || item?.url) return "link";
+  if (item?.location || item?.latitude || item?.longitude) return "location";
+  return "";
+}
+
+function normalizeWecomBotMediaPayload(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const nestedMessage = pickNestedValue(payload, [["message"], ["msg"], ["data"], ["event", "message"]]);
+  const candidates = [payload];
+  if (nestedMessage && typeof nestedMessage === "object" && nestedMessage !== payload) {
+    candidates.unshift(nestedMessage);
+  }
+
+  for (const candidate of candidates) {
+    const msgType = normalizeLowerToken(
+      pickNestedValue(candidate, [
+        ["msgtype"],
+        ["msg_type"],
+        ["msgType"],
+        ["message_type"],
+        ["messageType"],
+        ["type"],
+      ]),
+    );
+    if (!msgType) continue;
+    return {
+      source: candidate,
+      msgType,
+    };
+  }
+  return null;
+}
+
+function extractWecomBotTextContent(textLike, fallbackContent = "") {
+  return normalizeToken(
+    textLike?.content ||
+      textLike?.text ||
+      textLike?.body ||
+      textLike?.message ||
+      fallbackContent,
+  );
+}
+
+function extractWecomBotVoicePayload(voiceLike, fallback = {}) {
+  const source = voiceLike && typeof voiceLike === "object" ? voiceLike : fallback;
+  return {
+    url: normalizeToken(
+      source?.url ||
+        source?.media_url ||
+        source?.mediaUrl ||
+        source?.download_url ||
+        source?.downloadUrl ||
+        source?.file_url ||
+        source?.fileUrl ||
+        source?.voice_url ||
+        source?.voiceUrl ||
+        source?.audio_url ||
+        source?.audioUrl,
+    ),
+    mediaId: normalizeToken(
+      source?.media_id ||
+        source?.mediaid ||
+        source?.mediaId ||
+        source?.id,
+    ),
+    contentType: normalizeToken(
+      source?.content_type ||
+        source?.contentType ||
+        source?.mime_type ||
+        source?.mimeType ||
+        source?.format,
+    ),
+    text: extractWecomBotTextContent(source, source?.content),
+  };
+}
+
+function extractWecomBotFilePayload(fileLike, fallback = {}) {
+  const source = fileLike && typeof fileLike === "object" ? fileLike : fallback;
+  return {
+    url: normalizeToken(
+      source?.url ||
+        source?.download_url ||
+        source?.downloadUrl ||
+        source?.media_url ||
+        source?.mediaUrl ||
+        source?.file_url ||
+        source?.fileUrl,
+    ),
+    name: normalizeToken(
+      source?.name ||
+        source?.filename ||
+        source?.file_name ||
+        source?.fileName ||
+        source?.title,
+    ),
+    aesKey: normalizeToken(
+      source?.aeskey ||
+        source?.aes_key ||
+        source?.aesKey,
+    ),
+  };
+}
 
 export function buildWecomBotMixedPayload({ text = "", mediaUrl, mediaUrls } = {}) {
   const normalizedText = normalizeToken(text);
@@ -46,81 +242,113 @@ export function buildWecomBotMixedPayload({ text = "", mediaUrl, mediaUrls } = {
 
 export function parseWecomBotInboundMessage(payload) {
   if (!payload || typeof payload !== "object") return null;
-  const msgType = normalizeLowerToken(payload.msgtype);
-  if (!msgType) return null;
-  const feedbackId = normalizeToken(payload?.feedback?.id || payload?.stream?.feedback?.id);
+  const normalizedPayload = normalizeWecomBotMediaPayload(payload);
+  if (!normalizedPayload) return null;
+  const source = normalizedPayload.source;
+  const msgType = normalizedPayload.msgType;
+  const feedbackId = normalizeToken(
+    pickNestedValue(source, [["feedback", "id"], ["stream", "feedback", "id"], ["stream", "feedbackId"], ["feedbackId"]]),
+  );
   if (msgType === "stream") {
     return {
       kind: "stream-refresh",
-      streamId: normalizeToken(payload?.stream?.id),
+      streamId: normalizeToken(pickNestedValue(source, [["stream", "id"], ["streamId"]])),
       feedbackId,
     };
   }
 
-  const msgId = normalizeToken(payload.msgid) || `wecom-bot-${Date.now()}`;
-  const fromUser = normalizeToken(payload?.from?.userid);
-  const chatType = normalizeLowerToken(payload.chattype || "single") || "single";
-  const chatId = normalizeToken(payload.chatid);
-  const responseUrl = normalizeToken(payload.response_url);
-  const quote = normalizeQuotePayload(payload.quote);
+  const msgId =
+    normalizeToken(
+      pickNestedValue(source, [["msgid"], ["msg_id"], ["msgId"], ["message_id"], ["messageId"], ["id"]]),
+    ) || `wecom-bot-${Date.now()}`;
+  const fromUser = normalizeToken(
+    pickNestedValue(source, [
+      ["from", "userid"],
+      ["from", "user_id"],
+      ["from", "userId"],
+      ["sender", "userid"],
+      ["sender", "user_id"],
+      ["sender", "userId"],
+      ["sender", "id"],
+      ["userid"],
+      ["user_id"],
+      ["userId"],
+    ]),
+  );
+  const chatType =
+    normalizeLowerToken(
+      pickNestedValue(source, [["chattype"], ["chat_type"], ["chatType"]]) || "single",
+    ) || "single";
+  const chatId = normalizeToken(
+    pickNestedValue(source, [["chatid"], ["chat_id"], ["chatId"], ["conversation_id"], ["conversationId"]]),
+  );
+  const responseUrl = normalizeToken(
+    pickNestedValue(source, [["response_url"], ["responseUrl"], ["reply_url"], ["replyUrl"]]),
+  );
+  const quote = normalizeQuotePayload(pickNestedValue(source, [["quote"], ["quoted_message"], ["quotedMessage"]]));
   let content = "";
+  const imageEntries = [];
   const imageUrls = [];
   let fileUrl = "";
   let fileName = "";
+  let fileAesKey = "";
   let voiceUrl = "";
   let voiceMediaId = "";
   let voiceContentType = "";
 
   if (msgType === "text") {
-    content = normalizeToken(payload?.text?.content);
+    content = extractWecomBotTextContent(
+      pickNestedValue(source, [["text"], ["message", "text"]]),
+      pickNestedValue(source, [["content"], ["text_content"], ["textContent"]]),
+    );
   } else if (msgType === "voice") {
-    content = normalizeToken(payload?.voice?.content);
-    voiceUrl = normalizeToken(
-      payload?.voice?.url ||
-        payload?.voice?.media_url ||
-        payload?.voice?.download_url ||
-        payload?.voice?.file_url,
+    const voicePayload = extractWecomBotVoicePayload(
+      pickNestedValue(source, [["voice"], ["audio"], ["message", "voice"], ["message", "audio"]]),
+      source,
     );
-    voiceMediaId = normalizeToken(payload?.voice?.media_id || payload?.voice?.mediaid || payload?.voice?.id);
-    voiceContentType = normalizeToken(payload?.voice?.content_type || payload?.voice?.mime_type || payload?.voice?.format);
+    content = voicePayload.text;
+    voiceUrl = voicePayload.url;
+    voiceMediaId = voicePayload.mediaId;
+    voiceContentType = voicePayload.contentType;
   } else if (msgType === "link") {
-    const title = normalizeToken(payload?.link?.title);
-    const description = normalizeToken(payload?.link?.description);
-    const url = normalizeToken(payload?.link?.url);
+    const linkPayload = pickNestedValue(source, [["link"], ["message", "link"]]) || source;
+    const title = normalizeToken(linkPayload?.title);
+    const description = normalizeToken(linkPayload?.description);
+    const url = normalizeToken(linkPayload?.url);
     content = [title ? `[链接] ${title}` : "", description, url].filter(Boolean).join("\n").trim();
   } else if (msgType === "location") {
-    const latitude = normalizeToken(payload?.location?.latitude);
-    const longitude = normalizeToken(payload?.location?.longitude);
-    const name = normalizeToken(payload?.location?.name || payload?.location?.label);
+    const locationPayload = pickNestedValue(source, [["location"], ["message", "location"]]) || source;
+    const latitude = normalizeToken(locationPayload?.latitude);
+    const longitude = normalizeToken(locationPayload?.longitude);
+    const name = normalizeToken(locationPayload?.name || locationPayload?.label);
     content = name ? `[位置] ${name} (${latitude}, ${longitude})` : `[位置] ${latitude}, ${longitude}`;
   } else if (msgType === "image") {
-    imageUrls.push(...collectWecomBotImageUrls(payload?.image));
+    const topLevelImageEntries = collectWecomBotImageEntries(
+      pickNestedValue(source, [["image"], ["message", "image"]]) || source,
+    );
+    imageEntries.push(...topLevelImageEntries);
+    imageUrls.push(...topLevelImageEntries.map((entry) => entry.url));
     content = "[图片]";
   } else if (msgType === "mixed") {
-    const items = Array.isArray(payload?.mixed?.msg_item) ? payload.mixed.msg_item : [];
+    const items = collectWecomBotMixedItems(source);
     const parts = [];
     for (const item of items) {
-      const itemType = normalizeLowerToken(item?.msgtype);
+      const itemType = inferWecomBotItemType(item);
       if (itemType === "text") {
-        const text = normalizeToken(item?.text?.content);
+        const text = extractWecomBotTextContent(item?.text, item?.content);
         if (text) parts.push(text);
       } else if (itemType === "image") {
-        const itemImageUrls = collectWecomBotImageUrls(item?.image);
-        if (itemImageUrls.length > 0) {
-          imageUrls.push(...itemImageUrls);
+        const itemImageEntries = collectWecomBotImageEntries(item?.image || item);
+        if (itemImageEntries.length > 0) {
+          imageEntries.push(...itemImageEntries);
+          imageUrls.push(...itemImageEntries.map((entry) => entry.url));
           parts.push("[图片]");
         }
       } else if (itemType === "voice") {
-        const itemVoiceUrl = normalizeToken(
-          item?.voice?.url ||
-            item?.voice?.media_url ||
-            item?.voice?.download_url ||
-            item?.voice?.file_url,
-        );
-        const itemVoiceMediaId = normalizeToken(item?.voice?.media_id || item?.voice?.mediaid || item?.voice?.id);
-        const itemVoiceContentType = normalizeToken(
-          item?.voice?.content_type || item?.voice?.mime_type || item?.voice?.format,
-        );
+        const voicePayload = extractWecomBotVoicePayload(item?.voice || item?.audio, item);
+        const itemVoiceUrl = voicePayload.url;
+        const itemVoiceMediaId = voicePayload.mediaId;
+        const itemVoiceContentType = voicePayload.contentType;
         if (itemVoiceUrl) {
           voiceUrl = voiceUrl || itemVoiceUrl;
           voiceMediaId = voiceMediaId || itemVoiceMediaId;
@@ -128,29 +356,27 @@ export function parseWecomBotInboundMessage(payload) {
           parts.push("[语音]");
         }
       } else if (itemType === "file") {
-        const itemFileUrl = normalizeToken(
-          item?.file?.url ||
-            item?.file?.download_url ||
-            item?.file?.media_url ||
-            item?.file?.file_url,
-        );
-        const itemFileName = normalizeToken(item?.file?.name || item?.file?.filename);
+        const filePayload = extractWecomBotFilePayload(item?.file, item);
+        const itemFileUrl = filePayload.url;
+        const itemFileName = filePayload.name;
+        const itemFileAesKey = filePayload.aesKey;
         if (itemFileUrl || itemFileName) {
           fileUrl = fileUrl || itemFileUrl;
           fileName = fileName || itemFileName;
+          fileAesKey = fileAesKey || itemFileAesKey;
           const displayName = itemFileName || itemFileUrl || "附件";
           parts.push(`[文件] ${displayName}`);
         }
       } else if (itemType === "link") {
-        const title = normalizeToken(item?.link?.title);
-        const description = normalizeToken(item?.link?.description);
-        const url = normalizeToken(item?.link?.url);
+        const title = normalizeToken(item?.link?.title || item?.title);
+        const description = normalizeToken(item?.link?.description || item?.description);
+        const url = normalizeToken(item?.link?.url || item?.url);
         const linkText = [title ? `[链接] ${title}` : "", description, url].filter(Boolean).join("\n").trim();
         if (linkText) parts.push(linkText);
       } else if (itemType === "location") {
-        const latitude = normalizeToken(item?.location?.latitude);
-        const longitude = normalizeToken(item?.location?.longitude);
-        const name = normalizeToken(item?.location?.name || item?.location?.label);
+        const latitude = normalizeToken(item?.location?.latitude || item?.latitude);
+        const longitude = normalizeToken(item?.location?.longitude || item?.longitude);
+        const name = normalizeToken(item?.location?.name || item?.location?.label || item?.name || item?.label);
         const locationText = name ? `[位置] ${name} (${latitude}, ${longitude})` : `[位置] ${latitude}, ${longitude}`;
         if (locationText.trim() !== "[位置] ,") {
           parts.push(locationText);
@@ -159,14 +385,21 @@ export function parseWecomBotInboundMessage(payload) {
     }
     content = parts.join("\n").trim();
   } else if (msgType === "file") {
-    fileUrl = normalizeToken(payload?.file?.url);
-    fileName = normalizeToken(payload?.file?.name || payload?.file?.filename);
+    const filePayload = extractWecomBotFilePayload(
+      pickNestedValue(source, [["file"], ["message", "file"], ["attachment"], ["document"]]),
+      source,
+    );
+    fileUrl = filePayload.url;
+    fileName = filePayload.name;
+    fileAesKey = filePayload.aesKey;
     const displayName = fileName || fileUrl || "附件";
     content = `[文件] ${displayName}`;
   } else if (msgType === "event") {
     return {
       kind: "event",
-      eventType: normalizeToken(payload?.event?.event_type || payload?.event),
+      eventType: normalizeToken(
+        pickNestedValue(source, [["event", "event_type"], ["event", "eventType"], ["event"], ["event_type"], ["eventType"]]),
+      ),
       fromUser,
     };
   } else {
@@ -197,8 +430,10 @@ export function parseWecomBotInboundMessage(payload) {
     responseUrl,
     content,
     imageUrls: dedupeUrlList(imageUrls),
+    imageEntries: dedupeMediaEntries(imageEntries),
     fileUrl,
     fileName,
+    fileAesKey,
     voiceUrl,
     voiceMediaId,
     voiceContentType,