@dingxiang-me/openclaw-wechat 1.4.1 → 1.7.2

package/src/wecom/account-config-core.js

@@ -1,3 +1,5 @@
+import { buildDefaultAgentWebhookPath } from "./account-paths.js";
+
 export function asNumber(v, fallback = null) {
   if (v == null) return fallback;
   const n = Number(v);
@@ -30,15 +32,30 @@ export function normalizeAccountConfig({ raw, accountId, normalizeWecomWebhookTa
   if (!raw || typeof raw !== "object") return null;
   if (typeof normalizeWecomWebhookTargetMap !== "function") return null;
 
-  const corpId = String(raw.corpId ?? "").trim();
-  const corpSecret = String(raw.corpSecret ?? "").trim();
-  const agentId = asNumber(raw.agentId);
-  const callbackToken = pickFirstNonEmptyString(raw.callbackToken, raw.token);
-  const callbackAesKey = pickFirstNonEmptyString(raw.callbackAesKey, raw.encodingAesKey);
-  const webhookPath = String(raw.webhookPath ?? "/wecom/callback").trim() || "/wecom/callback";
+  const legacyAgent = raw.agent && typeof raw.agent === "object" ? raw.agent : {};
+  const hasLegacyAgentBlock = Object.keys(legacyAgent).length > 0;
+
+  const corpId = pickFirstNonEmptyString(raw.corpId, legacyAgent.corpId);
+  const corpSecret = pickFirstNonEmptyString(raw.corpSecret, legacyAgent.corpSecret);
+  const agentId = asNumber(raw.agentId ?? legacyAgent.agentId);
+  const callbackToken = pickFirstNonEmptyString(
+    raw.callbackToken,
+    legacyAgent.callbackToken,
+    legacyAgent.token,
+    hasLegacyAgentBlock ? "" : raw.token,
+  );
+  const callbackAesKey = pickFirstNonEmptyString(
+    raw.callbackAesKey,
+    legacyAgent.callbackAesKey,
+    legacyAgent.encodingAesKey,
+    hasLegacyAgentBlock ? "" : raw.encodingAesKey,
+  );
+  const defaultWebhookPath = buildDefaultAgentWebhookPath(normalizedId);
+  const webhookPath = String(raw.webhookPath ?? legacyAgent.webhookPath ?? defaultWebhookPath).trim() || defaultWebhookPath;
+  const name = pickFirstNonEmptyString(raw.name, normalizedId);
   const outboundProxy = String(raw.outboundProxy ?? raw.proxyUrl ?? raw.proxy ?? "").trim();
   const webhooks = normalizeWecomWebhookTargetMap(raw.webhooks);
-  const allowFrom = raw.allowFrom;
+  const allowFrom = raw.allowFrom ?? raw.dm?.allowFrom;
   const allowFromRejectMessage = String(raw.allowFromRejectMessage ?? raw.rejectUnauthorizedMessage ?? "").trim();
 
   if (!corpId || !corpSecret || !agentId) {
@@ -47,12 +64,14 @@ export function normalizeAccountConfig({ raw, accountId, normalizeWecomWebhookTa
 
   return {
     accountId: normalizedId,
+    name: normalizedId,
     corpId,
     corpSecret,
     agentId,
     callbackToken,
     callbackAesKey,
     webhookPath,
+    name,
     outboundProxy: outboundProxy || undefined,
     webhooks: Object.keys(webhooks).length > 0 ? webhooks : undefined,
     allowFrom,
@@ -84,7 +103,8 @@ export function readAccountConfigFromEnv({
   const agentId = asNumber(readVar("AGENT_ID"));
   const callbackToken = pickFirstNonEmptyString(readVar("CALLBACK_TOKEN"), readVar("TOKEN"));
   const callbackAesKey = pickFirstNonEmptyString(readVar("CALLBACK_AES_KEY"), readVar("ENCODING_AES_KEY"));
-  const webhookPath = String(readVar("WEBHOOK_PATH") ?? "/wecom/callback").trim() || "/wecom/callback";
+  const defaultWebhookPath = buildDefaultAgentWebhookPath(normalizedId);
+  const webhookPath = String(readVar("WEBHOOK_PATH") ?? defaultWebhookPath).trim() || defaultWebhookPath;
   const outboundProxyRaw =
     readVar("PROXY") ??
     (normalizedId === "default"

package/src/wecom/account-config.js

@@ -7,6 +7,58 @@ import {
 } from "./account-config-core.js";
 import { normalizePluginHttpPath } from "./http-path.js";
 
+const LEGACY_INLINE_ACCOUNT_RESERVED_KEYS = new Set([
+  "name",
+  "enabled",
+  "corpId",
+  "corpSecret",
+  "agentId",
+  "callbackToken",
+  "token",
+  "callbackAesKey",
+  "encodingAesKey",
+  "webhookPath",
+  "outboundProxy",
+  "proxyUrl",
+  "proxy",
+  "webhooks",
+  "allowFrom",
+  "allowFromRejectMessage",
+  "rejectUnauthorizedMessage",
+  "adminUsers",
+  "commandAllowlist",
+  "commandBlockMessage",
+  "commands",
+  "workspaceTemplate",
+  "groupChat",
+  "dynamicAgent",
+  "dynamicAgents",
+  "dm",
+  "debounce",
+  "streaming",
+  "bot",
+  "delivery",
+  "webhookBot",
+  "stream",
+  "observability",
+  "voiceTranscription",
+  "accounts",
+  "agent",
+]);
+
+function listLegacyInlineAccountEntries(channelConfig) {
+  if (!channelConfig || typeof channelConfig !== "object") return [];
+  const entries = [];
+  for (const [rawKey, value] of Object.entries(channelConfig)) {
+    const accountId = normalizeAccountId(rawKey);
+    if (!accountId) continue;
+    if (LEGACY_INLINE_ACCOUNT_RESERVED_KEYS.has(accountId)) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    entries.push([accountId, value]);
+  }
+  return entries;
+}
+
 export function createWecomAccountRegistry({
   normalizeWecomWebhookTargetMap,
   resolveWecomProxyConfig,
@@ -54,6 +106,9 @@ export function createWecomAccountRegistry({
         upsert(accountId, accountConfig);
       }
     }
+    for (const [accountId, accountConfig] of listLegacyInlineAccountEntries(channelConfig)) {
+      upsert(accountId, accountConfig);
+    }
 
     const envAccountIds = collectWecomEnvAccountIds({ envVars, processEnv });
     for (const accountId of envAccountIds) {

package/src/wecom/account-diagnostics.js

@@ -0,0 +1,121 @@
+import { normalizePluginHttpPath } from "./http-path.js";
+import { buildDefaultAgentWebhookPath, buildDefaultBotWebhookPath } from "./account-paths.js";
+
+function normalizeAccountId(accountId) {
+  const normalized = String(accountId ?? "default").trim().toLowerCase();
+  return normalized || "default";
+}
+
+function pushMapList(map, key, value) {
+  if (!key) return;
+  const existing = map.get(key);
+  if (existing) existing.push(value);
+  else map.set(key, [value]);
+}
+
+function detectDuplicateMapEntries(map, minimum = 2) {
+  const out = [];
+  for (const [key, values] of map.entries()) {
+    if (!Array.isArray(values) || values.length < minimum) continue;
+    out.push({ key, values: [...values] });
+  }
+  return out;
+}
+
+export function analyzeWecomAccountConflicts({ accounts = [], botConfigs = [] } = {}) {
+  const issues = [];
+  const enabledAccounts = (Array.isArray(accounts) ? accounts : []).filter((item) => item?.enabled !== false);
+  const enabledBotConfigs = (Array.isArray(botConfigs) ? botConfigs : []).filter((item) => item?.enabled === true);
+
+  const agentTokenToAccounts = new Map();
+  const corpAgentToAccounts = new Map();
+  const agentPathToAccounts = new Map();
+  const botTokenToAccounts = new Map();
+  const botPathToAccounts = new Map();
+
+  for (const account of enabledAccounts) {
+    const accountId = normalizeAccountId(account?.accountId);
+    const callbackToken = String(account?.callbackToken ?? "").trim();
+    const corpId = String(account?.corpId ?? "").trim().toLowerCase();
+    const agentId = String(account?.agentId ?? "").trim();
+    const normalizedPath =
+      normalizePluginHttpPath(
+        String(account?.webhookPath ?? "").trim() || buildDefaultAgentWebhookPath(accountId),
+        "/wecom/callback",
+      ) ?? "/wecom/callback";
+
+    if (callbackToken) pushMapList(agentTokenToAccounts, callbackToken, accountId);
+    if (corpId && agentId) pushMapList(corpAgentToAccounts, `${corpId}:${agentId}`, accountId);
+    pushMapList(agentPathToAccounts, normalizedPath, accountId);
+  }
+
+  for (const botConfig of enabledBotConfigs) {
+    const accountId = normalizeAccountId(botConfig?.accountId);
+    const token = String(botConfig?.token ?? "").trim();
+    const normalizedPath =
+      normalizePluginHttpPath(
+        String(botConfig?.webhookPath ?? "").trim() || buildDefaultBotWebhookPath(accountId),
+        "/wecom/bot/callback",
+      ) ?? "/wecom/bot/callback";
+    if (token) pushMapList(botTokenToAccounts, token, accountId);
+    pushMapList(botPathToAccounts, normalizedPath, accountId);
+  }
+
+  for (const dup of detectDuplicateMapEntries(agentTokenToAccounts)) {
+    issues.push({
+      severity: "warn",
+      code: "agent-duplicate-callback-token",
+      message: `Agent callbackToken duplicated across accounts: ${dup.values.join(", ")}`,
+      value: dup.key,
+      accounts: dup.values,
+    });
+  }
+  for (const dup of detectDuplicateMapEntries(corpAgentToAccounts)) {
+    issues.push({
+      severity: "warn",
+      code: "agent-duplicate-corp-agent",
+      message: `Agent corpId+agentId duplicated across accounts: ${dup.values.join(", ")}`,
+      value: dup.key,
+      accounts: dup.values,
+    });
+  }
+  for (const dup of detectDuplicateMapEntries(botTokenToAccounts)) {
+    issues.push({
+      severity: "warn",
+      code: "bot-duplicate-token",
+      message: `Bot token duplicated across accounts: ${dup.values.join(", ")}`,
+      value: dup.key,
+      accounts: dup.values,
+    });
+  }
+  for (const dup of detectDuplicateMapEntries(agentPathToAccounts)) {
+    issues.push({
+      severity: "info",
+      code: "agent-shared-webhook-path",
+      message: `Agent webhook path shared by accounts: ${dup.key} <- ${dup.values.join(", ")}`,
+      value: dup.key,
+      accounts: dup.values,
+    });
+  }
+  for (const dup of detectDuplicateMapEntries(botPathToAccounts)) {
+    issues.push({
+      severity: "info",
+      code: "bot-shared-webhook-path",
+      message: `Bot webhook path shared by accounts: ${dup.key} <- ${dup.values.join(", ")}`,
+      value: dup.key,
+      accounts: dup.values,
+    });
+  }
+
+  return {
+    ok: !issues.some((item) => item.severity === "warn"),
+    issues,
+    counts: {
+      accounts: enabledAccounts.length,
+      botAccounts: enabledBotConfigs.length,
+      warnings: issues.filter((item) => item.severity === "warn").length,
+      info: issues.filter((item) => item.severity === "info").length,
+    },
+  };
+}
+

package/src/wecom/account-paths.js

@@ -0,0 +1,39 @@
+function normalizeAccountId(accountId) {
+  const normalized = String(accountId ?? "default").trim().toLowerCase();
+  return normalized || "default";
+}
+
+export function buildWebhookPathAccountSlug(accountId) {
+  const normalizedId = normalizeAccountId(accountId);
+  if (normalizedId === "default") return "default";
+  const slug = normalizedId.replace(/[^a-z0-9_-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  return slug || "default";
+}
+
+export function buildDefaultAgentWebhookPath(accountId) {
+  const normalizedId = normalizeAccountId(accountId);
+  if (normalizedId === "default") return "/wecom/callback";
+  const slug = buildWebhookPathAccountSlug(normalizedId);
+  return `/wecom/${slug}/callback`;
+}
+
+export function buildLegacyAgentWebhookPath(accountId) {
+  const normalizedId = normalizeAccountId(accountId);
+  if (normalizedId === "default") return "/webhooks/app";
+  const slug = buildWebhookPathAccountSlug(normalizedId);
+  return `/webhooks/app/${slug}`;
+}
+
+export function buildDefaultBotWebhookPath(accountId) {
+  const normalizedId = normalizeAccountId(accountId);
+  if (normalizedId === "default") return "/wecom/bot/callback";
+  const slug = buildWebhookPathAccountSlug(normalizedId);
+  return `/wecom/${slug}/bot/callback`;
+}
+
+export function buildLegacyBotWebhookPath(accountId) {
+  const normalizedId = normalizeAccountId(accountId);
+  if (normalizedId === "default") return "/webhooks/wecom";
+  const slug = buildWebhookPathAccountSlug(normalizedId);
+  return `/webhooks/wecom/${slug}`;
+}

package/src/wecom/agent-inbound-dispatch.js

@@ -53,6 +53,15 @@ const ASYNC_INBOUND_HANDLERS = {
       linkPicUrl: inbound.linkPicUrl,
     }),
   },
+  event: {
+    requiresMediaId: false,
+    errorLabel: "event",
+    buildTaskPayload: (inbound) => ({
+      msgType: "event",
+      eventType: inbound.eventType,
+      eventKey: inbound.eventKey,
+    }),
+  },
 };
 
 function enqueueInboundTask({

package/src/wecom/agent-inbound-guards.js

@@ -20,6 +20,7 @@ export async function applyWecomAgentInboundGuards({
   stripWecomGroupMentions,
   resolveWecomCommandPolicy,
   resolveWecomAllowFromPolicy,
+  resolveWecomDmPolicy,
   isWecomSenderAllowed,
   extractLeadingSlashCommand,
   COMMANDS,
@@ -31,6 +32,7 @@ export async function applyWecomAgentInboundGuards({
   assertFunction("stripWecomGroupMentions", stripWecomGroupMentions);
   assertFunction("resolveWecomCommandPolicy", resolveWecomCommandPolicy);
   assertFunction("resolveWecomAllowFromPolicy", resolveWecomAllowFromPolicy);
+  assertFunction("resolveWecomDmPolicy", resolveWecomDmPolicy);
   assertFunction("isWecomSenderAllowed", isWecomSenderAllowed);
   assertFunction("extractLeadingSlashCommand", extractLeadingSlashCommand);
   assertFunction("sendTextToUser", sendTextToUser);
@@ -59,6 +61,23 @@ export async function applyWecomAgentInboundGuards({
 
   const commandPolicy = resolveWecomCommandPolicy(api);
   const isAdminUser = commandPolicy.adminUsers.includes(normalizedFromUser);
+  const dmPolicy = resolveWecomDmPolicy(api, config?.accountId || accountId || "default", config);
+  if (!isGroupChat) {
+    if (dmPolicy.mode === "deny") {
+      await sendTextToUser(dmPolicy.rejectMessage || "当前渠道私聊已关闭，请联系管理员。");
+      return { ok: false, commandBody: nextCommandBody, isAdminUser };
+    }
+    if (dmPolicy.mode === "allowlist") {
+      const dmSenderAllowed = isAdminUser || isWecomSenderAllowed({
+        senderId: normalizedFromUser,
+        allowFrom: dmPolicy.allowFrom,
+      });
+      if (!dmSenderAllowed) {
+        await sendTextToUser(dmPolicy.rejectMessage || "当前私聊账号未授权，请联系管理员。");
+        return { ok: false, commandBody: nextCommandBody, isAdminUser };
+      }
+    }
+  }
   const allowFromPolicy = resolveWecomAllowFromPolicy(api, config?.accountId || accountId || "default", config);
   const senderAllowed = isAdminUser || isWecomSenderAllowed({
     senderId: normalizedFromUser,
@@ -76,15 +95,16 @@ export async function applyWecomAgentInboundGuards({
 
   if (msgType === "text") {
     let commandKey = extractLeadingSlashCommand(nextCommandBody);
-    if (commandKey === "/clear") {
-      api?.logger?.info?.("wecom: translating /clear to native /reset command");
-      nextCommandBody = nextCommandBody.replace(/^\/clear\b/i, "/reset");
+    if (commandKey === "/clear" || commandKey === "/new") {
+      api?.logger?.info?.(`wecom: translating ${commandKey} to native /reset command`);
+      nextCommandBody = nextCommandBody.replace(/^\/(?:clear|new)\b/i, "/reset");
       commandKey = "/reset";
     }
     if (commandKey) {
       const commandAllowed =
         commandPolicy.allowlist.includes(commandKey) ||
-        (commandKey === "/reset" && commandPolicy.allowlist.includes("/clear"));
+        (commandKey === "/reset" &&
+          (commandPolicy.allowlist.includes("/clear") || commandPolicy.allowlist.includes("/new")));
       if (commandPolicy.enabled && !isAdminUser && !commandAllowed) {
         api?.logger?.info?.(`wecom: command blocked by allowlist user=${fromUser} command=${commandKey}`);
         await sendTextToUser(commandPolicy.rejectMessage);

package/src/wecom/agent-inbound-processor.js

@@ -17,6 +17,12 @@ export function createWecomAgentInboundProcessor(deps = {}) {
     stripWecomGroupMentions,
     resolveWecomCommandPolicy,
     resolveWecomAllowFromPolicy,
+    resolveWecomDmPolicy,
+    resolveWecomEventPolicy = () => ({
+      enabled: true,
+      enterAgentWelcomeEnabled: false,
+      enterAgentWelcomeText: "",
+    }),
     isWecomSenderAllowed,
     sendWecomText,
     extractLeadingSlashCommand,
@@ -65,6 +71,7 @@ export function createWecomAgentInboundProcessor(deps = {}) {
     fromUser,
     content,
     msgType,
+    eventType,
     mediaId,
     picUrl,
     recognition,
@@ -124,6 +131,7 @@ export function createWecomAgentInboundProcessor(deps = {}) {
         stripWecomGroupMentions,
         resolveWecomCommandPolicy,
         resolveWecomAllowFromPolicy,
+        resolveWecomDmPolicy,
         isWecomSenderAllowed,
         extractLeadingSlashCommand,
         COMMANDS,
@@ -140,6 +148,25 @@ export function createWecomAgentInboundProcessor(deps = {}) {
           isGroupChat,
         },
       });
+
+      if (String(msgType ?? "").trim().toLowerCase() === "event") {
+        const normalizedEventType = String(eventType ?? "").trim().toLowerCase();
+        const eventPolicy = resolveWecomEventPolicy(api, config.accountId || accountId, config);
+        if (!eventPolicy?.enabled) {
+          api.logger.info?.(`wecom: event skipped (disabled) type=${normalizedEventType || "unknown"}`);
+          return;
+        }
+        if (normalizedEventType === "enter_agent" && eventPolicy.enterAgentWelcomeEnabled) {
+          const welcomeText = String(eventPolicy.enterAgentWelcomeText ?? "").trim();
+          if (welcomeText) {
+            await sendTextToUser(welcomeText);
+            api.logger.info?.(`wecom: enter_agent welcome sent account=${config.accountId || accountId}`);
+          }
+          return;
+        }
+        api.logger.info?.(`wecom: event ignored type=${normalizedEventType || "unknown"}`);
+        return;
+      }
       if (!guardResult.ok) return;
       commandBody = guardResult.commandBody;
       const isAdminUser = guardResult.isAdminUser === true;

package/src/wecom/agent-webhook-handler.js

@@ -14,6 +14,8 @@ export function createWecomAgentWebhookHandler({
   messageProcessLimiter,
   executeInboundTaskWithSessionQueue,
   processInboundMessage,
+  recordInboundMetric = () => {},
+  recordRuntimeErrorMetric = () => {},
 } = {}) {
   const dispatchInbound = createWecomAgentInboundDispatcher({
     api,
@@ -150,6 +152,11 @@ export function createWecomAgentWebhookHandler({
       api.logger.info?.(
         `wecom inbound: account=${matchedAccount.accountId} from=${fromUser} msgType=${msgType} chatId=${chatId || "N/A"} content=${(inbound?.content ?? "").slice?.(0, 80)}`,
       );
+      recordInboundMetric({
+        mode: "agent",
+        msgType,
+        accountId: matchedAccount.accountId,
+      });
 
       if (!fromUser) {
         api.logger.warn?.("wecom: inbound message missing FromUserName, dropped");
@@ -173,6 +180,10 @@ export function createWecomAgentWebhookHandler({
       }
     } catch (err) {
       api.logger.error?.(`wecom: webhook handler failed: ${String(err?.message || err)}`);
+      recordRuntimeErrorMetric({
+        scope: "agent-webhook",
+        reason: String(err?.message || err),
+      });
       if (!res.writableEnded) {
         res.statusCode = 500;
         res.setHeader("Content-Type", "text/plain; charset=utf-8");

package/src/wecom/bot-context.js

@@ -25,6 +25,7 @@ export function buildWecomBotInboundContextPayload({
   commandBody,
   fromAddress,
   sessionId,
+  accountId = "default",
   isGroupChat,
   chatId,
   fromUser,
@@ -39,7 +40,7 @@ export function buildWecomBotInboundContextPayload({
     From: fromAddress,
     To: fromAddress,
     SessionKey: sessionId,
-    AccountId: "bot",
+    AccountId: accountId,
     ChatType: isGroupChat ? "group" : "direct",
     ConversationLabel: isGroupChat && chatId ? `group:${chatId}` : fromUser,
     SenderName: fromUser,

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

@@ -50,6 +50,7 @@ export async function handleWecomBotDispatchError({
   startLateReplyWatcher,
   sessionId,
   fromUser,
+  accountId = "default",
   buildWecomBotSessionId,
   runtime,
   cfg,
@@ -78,7 +79,7 @@ export async function handleWecomBotDispatchError({
   }
 
   try {
-    const runtimeSessionId = sessionId || buildWecomBotSessionId(fromUser);
+    const runtimeSessionId = sessionId || buildWecomBotSessionId(fromUser, accountId);
     const runtimeStorePath = runtime.channel.session.resolveStorePath(cfg.session?.store, {
       agentId: routedAgentId || "main",
     });

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

@@ -9,6 +9,8 @@ export function createWecomBotInboundContentBuilder({
   detectImageContentTypeFromBuffer,
   decryptWecomMediaBuffer,
   pickImageFileExtension,
+  resolveWecomVoiceTranscriptionConfig,
+  transcribeInboundVoice,
   inferFilenameFromMediaDownload,
   smartDecryptWecomFileBuffer,
   basename,
@@ -22,6 +24,8 @@ export function createWecomBotInboundContentBuilder({
   assertFunction("detectImageContentTypeFromBuffer", detectImageContentTypeFromBuffer);
   assertFunction("decryptWecomMediaBuffer", decryptWecomMediaBuffer);
   assertFunction("pickImageFileExtension", pickImageFileExtension);
+  assertFunction("resolveWecomVoiceTranscriptionConfig", resolveWecomVoiceTranscriptionConfig);
+  assertFunction("transcribeInboundVoice", transcribeInboundVoice);
   assertFunction("inferFilenameFromMediaDownload", inferFilenameFromMediaDownload);
   assertFunction("smartDecryptWecomFileBuffer", smartDecryptWecomFileBuffer);
   assertFunction("basename", basename);
@@ -39,6 +43,10 @@ export function createWecomBotInboundContentBuilder({
     normalizedImageUrls = [],
     normalizedFileUrl = "",
     normalizedFileName = "",
+    normalizedVoiceUrl = "",
+    normalizedVoiceMediaId = "",
+    normalizedVoiceContentType = "",
+    voiceInputMessageId = "",
     normalizedQuote = null,
   } = {}) {
     const tempPathsToCleanup = [];
@@ -124,7 +132,8 @@ export function createWecomBotInboundContentBuilder({
       }
     }
 
-    if (msgType === "file") {
+    const shouldHandleFile = msgType === "file" || (msgType === "mixed" && Boolean(normalizedFileUrl));
+    if (shouldHandleFile) {
       const displayName =
         inferFilenameFromMediaDownload({
           explicitName: normalizedFileName,
@@ -162,22 +171,83 @@ export function createWecomBotInboundContentBuilder({
           );
           await writeFile(fileTempPath, decrypted.buffer);
           tempPathsToCleanup.push(fileTempPath);
-          messageText =
+          const fileInstruction =
             `[用户发送了一个文件: ${safeName}，已保存到: ${fileTempPath}]` +
             "\n\n请根据文件内容回复用户；如需读取详情请使用 Read 工具。";
+          if (msgType === "mixed" && messageText) {
+            messageText = `${messageText}\n${fileInstruction}`.trim();
+          } else {
+            messageText = fileInstruction;
+          }
           api?.logger?.info?.(
             `wecom(bot): saved file to ${fileTempPath}, size=${decrypted.buffer.length} bytes` +
               `, decrypted=${decrypted.decrypted ? "yes" : "no"} source=${downloaded.source || "unknown"}`,
           );
         } catch (fileErr) {
           api?.logger?.warn?.(`wecom(bot): failed to fetch file url: ${String(fileErr?.message || fileErr)}`);
-          messageText = `[用户发送了一个文件: ${displayName}，但下载失败]\n\n请提示用户重新发送文件。`;
+          const failedFileHint = `[用户发送了一个文件: ${displayName}，但下载失败]\n\n请提示用户重新发送文件。`;
+          if (msgType === "mixed" && messageText) {
+            messageText = `${messageText}\n${failedFileHint}`.trim();
+          } else {
+            messageText = failedFileHint;
+          }
         }
       } else if (!messageText) {
         messageText = `[用户发送了一个文件: ${displayName}]`;
       }
     }
 
+    const shouldHandleVoice = msgType === "voice" || (msgType === "mixed" && Boolean(normalizedVoiceUrl));
+    if (shouldHandleVoice) {
+      const existingVoiceText = String(messageText ?? "").trim();
+      const voiceUrl = String(normalizedVoiceUrl ?? "").trim();
+      const voiceMediaId = String(normalizedVoiceMediaId ?? "").trim() || String(voiceInputMessageId ?? "").trim();
+      if (existingVoiceText && existingVoiceText !== "[语音]") {
+        if (msgType === "mixed") {
+          messageText = `${existingVoiceText}\n[用户发送了一条语音]`;
+        } else {
+          messageText = `[用户发送了一条语音]\n转写: ${existingVoiceText}`;
+        }
+      } else if (!voiceUrl) {
+        messageText = "语音接收成功，但未提供可下载的语音链接，请用户改发文字。";
+      } else {
+        const voiceConfig = resolveWecomVoiceTranscriptionConfig(api);
+        if (!voiceConfig.enabled) {
+          messageText = "已收到语音消息，但当前未启用语音转写，请改发文字。";
+        } else {
+          try {
+            const downloadedVoice = await fetchMediaFromUrl(voiceUrl, {
+              proxyUrl: botProxyUrl,
+              logger: api?.logger,
+              forceProxy: Boolean(botProxyUrl),
+              maxBytes: Math.max(voiceConfig.maxBytes || 0, 2 * 1024 * 1024),
+            });
+            const transcript = await transcribeInboundVoice({
+              api,
+              buffer: downloadedVoice.buffer,
+              contentType: normalizedVoiceContentType || downloadedVoice.contentType,
+              mediaId: voiceMediaId || `bot-voice-${Date.now()}`,
+              voiceConfig,
+            });
+            const voiceText = `[用户发送了一条语音]\n转写: ${String(transcript ?? "").trim()}`;
+            if (msgType === "mixed" && messageText) {
+              messageText = `${messageText}\n${voiceText}`.trim();
+            } else {
+              messageText = voiceText;
+            }
+          } catch (voiceErr) {
+            api?.logger?.warn?.(`wecom(bot): voice transcription failed: ${String(voiceErr?.message || voiceErr)}`);
+            return {
+              aborted: true,
+              abortText: "语音识别失败，请稍后重试。",
+              messageText: "",
+              tempPathsToCleanup,
+            };
+          }
+        }
+      }
+    }
+
     if (normalizedQuote?.content) {
       const quoteLabel = normalizedQuote.msgType === "image" ? "[引用图片]" : `> ${normalizedQuote.content}`;
       messageText = `${quoteLabel}\n\n${String(messageText ?? "").trim()}`.trim();

package/src/wecom/bot-inbound-dispatch-runtime.js

@@ -18,6 +18,7 @@ export async function executeWecomBotDispatchRuntime({
   cfg,
   ctxPayload,
   streamId,
+  accountId = "default",
   sessionId,
   routedAgentId,
   storePath,
@@ -96,7 +97,7 @@ export async function executeWecomBotDispatchRuntime({
             ? {
                 sessionKey: sessionId,
                 agentId: routedAgentId,
-                accountId: "bot",
+                accountId,
               }
             : undefined,
       },