@yanhaidao/wecom 2.3.270 → 2.4.160

package/src/agent/handler.ts

@@ -15,6 +15,7 @@ import {
   shouldUseDynamicAgent,
   ensureDynamicAgentListed,
 } from "../dynamic-agent.js";
+import { setPeerContext } from "../context-store.js";
 import { getWecomRuntime } from "../runtime.js";
 import { registerWecomSourceSnapshot } from "../runtime/source-registry.js";
 import {
@@ -30,16 +31,27 @@ import {
   extractMsgId,
   extractFileName,
   extractAgentId,
+  extractToUser,
 } from "../shared/xml-parser.js";
-import { downloadAgentApiMedia, sendAgentApiText } from "../transport/agent-api/client.js";
+import { resolveOutboundMediaAsset } from "../shared/media-asset.js";
+import {
+  downloadAgentApiMedia,
+  downloadUpstreamAgentApiMedia,
+  sendAgentApiText,
+  sendUpstreamAgentApiText,
+} from "../transport/agent-api/client.js";
+import { deliverAgentApiMedia } from "../transport/agent-api/delivery.js";
+import { deliverUpstreamAgentApiMedia } from "../transport/agent-api/upstream-delivery.js";
 import type {
   ResolvedAgentAccount,
+  ReplyPayload,
   UnifiedInboundEvent,
   WecomInboundKind,
 } from "../types/index.js";
 import type { WecomAgentInboundMessage } from "../types/index.js";
 import type { TransportSessionPatch } from "../types/index.js";
 import type { WecomRuntimeAuditEvent } from "../types/runtime-context.js";
+import { detectUpstreamUser, createUpstreamAgentConfig, resolveUpstreamCorpConfig } from "../upstream/index.js";
 
 /** 错误提示信息 */
 const ERROR_HELP = "\n\n遇到问题？联系作者: YanHaidao (微信: YanHaidao)";
@@ -123,6 +135,11 @@ function buildTextFilePreview(buffer: Buffer, maxChars: number): string | undefi
   return truncated;
 }
 
+function readContextSessionId(ctx: { SessionId?: string } | Record<string, unknown>): string | undefined {
+  const sessionId = "SessionId" in ctx ? ctx.SessionId : undefined;
+  return typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : undefined;
+}
+
 /**
  * **AgentWebhookParams (Webhook 处理器参数)**
  *
@@ -246,6 +263,13 @@ export function shouldProcessAgentInboundMessage(params: {
   };
 }
 
+export function shouldSuppressAgentReplyText(params: {
+  text: string;
+  mediaReplySeen: boolean;
+}): boolean {
+  return params.mediaReplySeen && Boolean(params.text.trim());
+}
+
 function normalizeAgentId(value: unknown): number | undefined {
   if (typeof value === "number" && Number.isFinite(value)) return value;
   const raw = String(value ?? "").trim();
@@ -448,10 +472,48 @@ async function processAgentMessage(params: {
   const replyTarget = isGroup
     ? ({ toUser: undefined, chatId: peerId } as const)
     : ({ toUser: fromUser, chatId: undefined } as const);
+  let upstreamAgent: typeof agent | undefined;
+  let upstreamReplyTarget: typeof replyTarget | undefined;
+  let primaryAgentForUpstream: typeof agent | undefined;
   const eventType = String(msg.Event ?? "")
     .trim()
     .toLowerCase();
 
+  // 检测是否是上下游用户
+  const toUserName = extractToUser(msg);
+  const isUpstreamUser = detectUpstreamUser({
+    messageToUserName: toUserName,
+    primaryCorpId: agent.corpId,
+  });
+  
+  if (isUpstreamUser) {
+    log?.(
+      `[wecom-agent] detected upstream user: from=${fromUser} toCorpId=${toUserName}`,
+    );
+
+    // 查找上下游配置，构建上游 Agent 配置
+    const upstreamConfig = resolveUpstreamCorpConfig({
+      upstreamCorpId: toUserName,
+      upstreamCorps: agent.config.upstreamCorps,
+    });
+    if (upstreamConfig) {
+      upstreamAgent = createUpstreamAgentConfig({
+        baseAgent: agent,
+        upstreamCorpId: toUserName,
+        upstreamAgentId: upstreamConfig.agentId,
+      });
+      primaryAgentForUpstream = agent;
+      // 上下游的 replyTarget 与普通 DM 一致（toUser = fromUser）
+      upstreamReplyTarget = isGroup
+        ? ({ toUser: undefined, chatId: peerId } as const)
+        : ({ toUser: fromUser, chatId: undefined } as const);
+    } else {
+      error?.(
+        `[wecom-agent] upstream user detected but no upstream config for corpId=${toUserName}; fallback to primary agent target`,
+      );
+    }
+  }
+
   const resolveInboundKind = (): WecomInboundKind => {
     if (msgType === "event") {
       if (eventType === "subscribe" || eventType === "enter_agent") return "welcome";
@@ -497,7 +559,15 @@ async function processAgentMessage(params: {
           buffer,
           contentType,
           filename: headerFileName,
-        } = await downloadAgentApiMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
+        } =
+          upstreamAgent && primaryAgentForUpstream
+            ? await downloadUpstreamAgentApiMedia({
+                upstreamAgent,
+                primaryAgent: primaryAgentForUpstream,
+                mediaId,
+                maxBytes: mediaMaxBytes,
+              })
+            : await downloadAgentApiMedia({ agent, mediaId, maxBytes: mediaMaxBytes });
         const xmlFileName = extractFileName(msg);
         const originalFileName = (xmlFileName || headerFileName || `${mediaId}.bin`).trim();
         const heuristic = analyzeTextHeuristic(buffer);
@@ -633,7 +703,16 @@ async function processAgentMessage(params: {
       `[wecom-agent] routing guard: blocked default fallback accountId=${agent.accountId} matchedBy=${route.matchedBy} from=${fromUser}`,
     );
     try {
-      await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      if (upstreamAgent) {
+        await sendUpstreamAgentApiText({
+          upstreamAgent,
+          primaryAgent: primaryAgentForUpstream!,
+          ...(upstreamReplyTarget ?? replyTarget),
+          text: prompt,
+        });
+      } else {
+        await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      }
       touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
       log?.(`[wecom-agent] routing guard prompt delivered to ${fromUser}`);
     } catch (err: unknown) {
@@ -710,7 +789,16 @@ async function processAgentMessage(params: {
       scope: "agent",
     });
     try {
-      await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      if (upstreamAgent) {
+        await sendUpstreamAgentApiText({
+          upstreamAgent,
+          primaryAgent: primaryAgentForUpstream!,
+          ...(upstreamReplyTarget ?? replyTarget),
+          text: prompt,
+        });
+      } else {
+        await sendAgentApiText({ agent, ...replyTarget, text: prompt });
+      }
       touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
       log?.(
         `[wecom-agent] unauthorized command: replied to ${isGroup ? `chat:${peerId}` : fromUser}`,
@@ -756,6 +844,27 @@ async function processAgentMessage(params: {
     MediaType: mediaType,
     MediaUrl: mediaPath,
   });
+  const sessionId = readContextSessionId(ctxPayload);
+
+  log?.(
+    `[wecom-agent] session bound: sessionKey=${ctxPayload.SessionKey ?? route.sessionKey} sessionId=${sessionId ?? "N/A"} peer=${peerId} upstream=${String(Boolean(upstreamAgent))}`,
+  );
+
+  registerWecomSourceSnapshot({
+    accountId: agent.accountId,
+    source: "agent-callback",
+    messageId: extractMsgId(msg) ?? undefined,
+    sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+    sessionId,
+    peerKind: isGroup ? "group" : "direct",
+    peerId,
+    upstreamCorpId: upstreamAgent?.corpId,
+  });
+  setPeerContext(agent.accountId, peerId, {
+    peerKind: isGroup ? "group" : "direct",
+    lastSeen: Date.now(),
+    upstreamCorpId: upstreamAgent?.corpId,
+  });
 
   // 记录会话
   await core.channel.session.recordInboundSession({
@@ -769,14 +878,25 @@ async function processAgentMessage(params: {
 
   // 5秒无响应自动回复进度提示
   let hasResponseSent = false;
+  const effectiveAgent = upstreamAgent ?? agent;
+  const effectiveReplyTarget = upstreamReplyTarget ?? replyTarget;
   const processingTimer = setTimeout(async () => {
     if (hasResponseSent) return;
     try {
-      await sendAgentApiText({
-        agent,
-        ...replyTarget,
-        text: "正在处理中，请稍候...",
-      });
+      if (upstreamAgent && primaryAgentForUpstream) {
+        await sendUpstreamAgentApiText({
+          upstreamAgent,
+          primaryAgent: primaryAgentForUpstream,
+          ...effectiveReplyTarget,
+          text: "正在处理中，请稍候...",
+        });
+      } else {
+        await sendAgentApiText({
+          agent: effectiveAgent,
+          ...effectiveReplyTarget,
+          text: "正在处理中，请稍候...",
+        });
+      }
       log?.(
         `[wecom-agent] sent processing notification to ${isGroup ? `chat:${peerId}` : fromUser}`,
       );
@@ -787,6 +907,25 @@ async function processAgentMessage(params: {
 
   // 发送队列锁：确保所有 deliver 调用（以及内部的分片发送）严格串行执行
   let messageSendQueue = Promise.resolve();
+  let deferredMediaUrls: string[] = [];
+
+  const mergeDeferredMediaUrls = (mediaUrls: string[]): string[] => {
+    if (mediaUrls.length === 0) {
+      return deferredMediaUrls;
+    }
+    const merged = [...deferredMediaUrls];
+    for (const mediaUrl of mediaUrls) {
+      if (!merged.includes(mediaUrl)) {
+        merged.push(mediaUrl);
+      }
+    }
+    deferredMediaUrls = merged;
+    return deferredMediaUrls;
+  };
+
+  const replyWecomTarget = effectiveReplyTarget.chatId
+    ? ({ chatid: effectiveReplyTarget.chatId } as const)
+    : ({ touser: effectiveReplyTarget.toUser } as const);
 
   try {
     // 调度回复
@@ -797,10 +936,20 @@ async function processAgentMessage(params: {
         disableBlockStreaming: false,
       },
       dispatcherOptions: {
-        deliver: async (payload: { text?: string }, info: { kind: string }) => {
+        deliver: async (payload: ReplyPayload, info: { kind: string }) => {
           const text = payload.text ?? "";
-          // 忽略空文本消息
-          if (!text || !text.trim()) {
+          const incomingMediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
+          if (info.kind !== "final" && incomingMediaUrls.length > 0) {
+            mergeDeferredMediaUrls(incomingMediaUrls);
+          }
+          const mediaUrls =
+            info.kind === "final"
+              ? mergeDeferredMediaUrls(incomingMediaUrls)
+              : incomingMediaUrls;
+
+          const outboundText = text;
+
+          if ((!outboundText || !outboundText.trim()) && mediaUrls.length === 0) {
             return;
           }
 
@@ -813,18 +962,27 @@ async function processAgentMessage(params: {
           const currentTask = async () => {
             const MAX_CHUNK_SIZE = 600;
             // 确保分片顺序发送
-            for (let i = 0; i < text.length; i += MAX_CHUNK_SIZE) {
-              const chunk = text.slice(i, i + MAX_CHUNK_SIZE);
+            for (let i = 0; i < outboundText.length; i += MAX_CHUNK_SIZE) {
+              const chunk = outboundText.slice(i, i + MAX_CHUNK_SIZE);
 
               try {
-                await sendAgentApiText({ agent, ...replyTarget, text: chunk });
+                if (upstreamAgent) {
+                  await sendUpstreamAgentApiText({
+                    upstreamAgent,
+                    primaryAgent: primaryAgentForUpstream!,
+                    ...effectiveReplyTarget,
+                    text: chunk,
+                  });
+                } else {
+                  await sendAgentApiText({ agent: effectiveAgent, ...effectiveReplyTarget, text: chunk });
+                }
                 touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
                 log?.(
-                  `[wecom-agent] reply chunk delivered (${info.kind}) to ${isGroup ? `chat:${peerId}` : fromUser}, len=${chunk.length}`,
+                  `[wecom-agent] reply chunk delivered (${info.kind}) to ${isGroup ? `chat:${peerId}` : fromUser}, len=${chunk.length}, sessionKey=${ctxPayload.SessionKey ?? route.sessionKey}, sessionId=${sessionId ?? "N/A"}`,
                 );
 
                 // 强制延时：确保企业微信有足够时间处理顺序（优化：200ms → 50ms）
-                if (i + MAX_CHUNK_SIZE < text.length) {
+                if (i + MAX_CHUNK_SIZE < outboundText.length) {
                   await new Promise((resolve) => setTimeout(resolve, 50));
                 }
               } catch (err: unknown) {
@@ -847,6 +1005,57 @@ async function processAgentMessage(params: {
               }
             }
 
+            if (info.kind === "final") {
+              for (const mediaUrl of mediaUrls) {
+                try {
+                  const media = await resolveOutboundMediaAsset({
+                    mediaUrl,
+                    network: effectiveAgent.network,
+                  });
+                  if (upstreamAgent) {
+                    await deliverUpstreamAgentApiMedia({
+                      upstreamAgent,
+                      primaryAgent: primaryAgentForUpstream!,
+                      target: replyWecomTarget,
+                      buffer: media.buffer,
+                      filename: media.filename,
+                      contentType: media.contentType,
+                    });
+                  } else {
+                    await deliverAgentApiMedia({
+                      agent: effectiveAgent,
+                      target: replyWecomTarget,
+                      buffer: media.buffer,
+                      filename: media.filename,
+                      contentType: media.contentType,
+                    });
+                  }
+                  touchTransportSession?.({ lastOutboundAt: Date.now(), running: true });
+                  log?.(
+                    `[wecom-agent] reply media delivered (${info.kind}) to ${isGroup ? `chat:${peerId}` : fromUser}, media=${media.filename}, sessionKey=${ctxPayload.SessionKey ?? route.sessionKey}, sessionId=${sessionId ?? "N/A"}`,
+                  );
+                } catch (err: unknown) {
+                  const message =
+                    err instanceof Error
+                      ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}`
+                      : String(err);
+                  error?.(`[wecom-agent] media reply failed: ${message}`);
+                  auditSink?.({
+                    transport: "agent-callback",
+                    category: "fallback-delivery-failed",
+                    summary: `agent callback media reply failed user=${fromUser} kind=${info.kind}`,
+                    raw: {
+                      transport: "agent-callback",
+                      envelopeType: "xml",
+                      body: msg,
+                    },
+                    error: message,
+                  });
+                }
+              }
+              deferredMediaUrls = [];
+            }
+
             // 不同 Block 之间也增加一点间隔（优化：200ms → 50ms）
             if (info.kind !== "final") {
               await new Promise((resolve) => setTimeout(resolve, 50));

package/src/app/account-runtime.ts

@@ -37,7 +37,7 @@ export class WecomAccountRuntime {
     } = {},
     private readonly statusSink?: (snapshot: Record<string, unknown>) => void,
   ) {
-    this.mediaService = new WecomMediaService(core);
+    this.mediaService = new WecomMediaService(core, cfg);
     this.runtimeStatus = {
       accountId: resolved.account.accountId,
       health: "idle",

package/src/capability/agent/upstream-delivery-service.ts

@@ -0,0 +1,96 @@
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import { resolveScopedWecomTarget } from "../../target.js";
+import { deliverUpstreamAgentApiMedia, deliverUpstreamAgentApiText } from "../../transport/agent-api/upstream-delivery.js";
+import { canUseAgentApiDelivery } from "./fallback-policy.js";
+import { getWecomRuntime } from "../../runtime.js";
+
+/**
+ * 上下游企业消息发送服务
+ * 
+ * 使用下游企业的 access_token 和 agentId 发送消息
+ */
+export class WecomUpstreamAgentDeliveryService {
+  constructor(
+    private readonly upstreamAgent: ResolvedAgentAccount,
+    private readonly primaryAgent: ResolvedAgentAccount,
+  ) { }
+
+  assertAvailable(): void {
+    if (!canUseAgentApiDelivery(this.upstreamAgent)) {
+      throw new Error(
+        `WeCom upstream outbound requires channels.wecom.accounts.<accountId>.agent.agentId for upstream corp=${this.upstreamAgent.corpId}.`,
+      );
+    }
+  }
+
+  resolveTargetOrThrow(to: string | undefined) {
+    const scoped = resolveScopedWecomTarget(to, this.upstreamAgent.accountId);
+    if (!scoped) {
+      console.error(`[wecom-upstream-delivery] missing target account=${this.upstreamAgent.accountId}`);
+      throw new Error("WeCom upstream outbound requires a target (userid, partyid, tagid or chatid).");
+    }
+    if (scoped.accountId && scoped.accountId !== this.upstreamAgent.accountId) {
+      console.error(
+        `[wecom-upstream-delivery] account mismatch current=${this.upstreamAgent.accountId} targetAccount=${scoped.accountId} raw=${String(to ?? "")}`,
+      );
+      throw new Error(
+        `WeCom upstream outbound account mismatch: target belongs to account=${scoped.accountId}, current account=${this.upstreamAgent.accountId}.`,
+      );
+    }
+    const target = scoped.target;
+    if (target.chatid) {
+      console.warn(
+        `[wecom-upstream-delivery] blocked chat target account=${this.upstreamAgent.accountId} chatId=${target.chatid}`,
+      );
+      throw new Error(
+        `企业微信（WeCom）上下游 Agent 主动发送不支持向群 chatId 发送（chatId=${target.chatid}）。` +
+        `请改为发送给用户（userid / user:xxx）。`,
+      );
+    }
+    return target;
+  }
+
+  async sendText(params: { to: string | undefined; text: string }): Promise<void> {
+    this.assertAvailable();
+    const target = this.resolveTargetOrThrow(params.to);
+    console.log(
+      `[wecom-upstream-delivery] sendText account=${this.upstreamAgent.accountId} corpId=${this.upstreamAgent.corpId} to=${String(params.to ?? "")} len=${params.text.length}`,
+    );
+
+    const runtime = getWecomRuntime();
+    const chunks = runtime.channel.text.chunkText(params.text, 2048);
+
+    for (const chunk of chunks) {
+      if (!chunk.trim()) continue;
+      await deliverUpstreamAgentApiText({
+        upstreamAgent: this.upstreamAgent,
+        primaryAgent: this.primaryAgent,
+        target,
+        text: chunk,
+      });
+    }
+  }
+
+  async sendMedia(params: {
+    to: string | undefined;
+    text?: string;
+    buffer: Buffer;
+    filename: string;
+    contentType: string;
+  }): Promise<void> {
+    this.assertAvailable();
+    const target = this.resolveTargetOrThrow(params.to);
+    console.log(
+      `[wecom-upstream-delivery] sendMedia account=${this.upstreamAgent.accountId} corpId=${this.upstreamAgent.corpId} to=${String(params.to ?? "")} filename=${params.filename} contentType=${params.contentType}`,
+    );
+    await deliverUpstreamAgentApiMedia({
+      upstreamAgent: this.upstreamAgent,
+      primaryAgent: this.primaryAgent,
+      target,
+      buffer: params.buffer,
+      filename: params.filename,
+      contentType: params.contentType,
+      text: params.text,
+    });
+  }
+}

package/src/capability/bot/sandbox-media.test.ts

@@ -0,0 +1,221 @@
+import path from "node:path";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { stageWecomInboundMediaForSession } from "./sandbox-media.js";
+
+describe("stageWecomInboundMediaForSession", () => {
+  const root = path.join("/tmp", `wecom-sandbox-stage-${process.pid}`);
+
+  beforeEach(async () => {
+    await mkdir(root, { recursive: true });
+  });
+
+  afterEach(async () => {
+    vi.unstubAllEnvs();
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("stages inbound media into the session sandbox workspace using channels.wecom.mediaMaxMb", async () => {
+    const mediaPath = path.join(root, "openclaw-media", "inbound", "big.bin");
+    const agentWorkspace = path.join(root, "agent-workspace");
+    const sandboxRoot = path.join(root, "sandboxes");
+
+    await mkdir(path.dirname(mediaPath), { recursive: true });
+    await mkdir(agentWorkspace, { recursive: true });
+    await writeFile(mediaPath, Buffer.alloc(6 * 1024 * 1024, 7));
+
+    const staged = await stageWecomInboundMediaForSession({
+      cfg: {
+        channels: {
+          wecom: {
+            mediaMaxMb: 8,
+          },
+        },
+        agents: {
+          list: [
+            {
+              id: "ops",
+              workspace: agentWorkspace,
+              sandbox: {
+                mode: "non-main",
+                scope: "session",
+                workspaceRoot: sandboxRoot,
+                workspaceAccess: "ro",
+                docker: {
+                  workdir: "/workspace",
+                },
+              },
+            },
+          ],
+        },
+      } as any,
+      accountId: "default",
+      agentId: "ops",
+      sessionKey: "agent:ops:wecom:default:dm:zhangsan",
+      mediaPath,
+      filename: "big.bin",
+    });
+
+    expect(staged).toMatch(/^media\/inbound\/big\.bin$/);
+    const sandboxEntries = await readdir(sandboxRoot);
+    const stagedBuffer = await readFile(
+      path.join(sandboxRoot, sandboxEntries[0]!, "media", "inbound", "big.bin"),
+    );
+    expect(stagedBuffer.byteLength).toBe(6 * 1024 * 1024);
+  });
+
+  it("uses the default sandbox workspace root when workspaceRoot is omitted", async () => {
+    vi.stubEnv("OPENCLAW_STATE_DIR", root);
+    const mediaPath = path.join(root, "openclaw-media", "inbound", "default-root.bin");
+    const agentWorkspace = path.join(root, "agent-workspace");
+
+    await mkdir(path.dirname(mediaPath), { recursive: true });
+    await mkdir(agentWorkspace, { recursive: true });
+    await writeFile(mediaPath, Buffer.alloc(2 * 1024 * 1024, 5));
+
+    const staged = await stageWecomInboundMediaForSession({
+      cfg: {
+        channels: {
+          wecom: {
+            mediaMaxMb: 8,
+          },
+        },
+        agents: {
+          list: [
+            {
+              id: "ops",
+              workspace: agentWorkspace,
+              sandbox: {
+                mode: "non-main",
+                scope: "session",
+                workspaceAccess: "ro",
+                docker: {
+                  workdir: "/workspace",
+                },
+              },
+            },
+          ],
+        },
+      } as any,
+      accountId: "default",
+      agentId: "ops",
+      sessionKey: "agent:ops:wecom:default:dm:lisi",
+      mediaPath,
+      filename: "default-root.bin",
+    });
+
+    expect(staged).toMatch(/^media\/inbound\/default-root\.bin$/);
+    const sandboxEntries = await readdir(path.join(root, "sandboxes"));
+    const stagedBuffer = await readFile(
+      path.join(root, "sandboxes", sandboxEntries[0]!, "media", "inbound", "default-root.bin"),
+    );
+    expect(stagedBuffer.byteLength).toBe(2 * 1024 * 1024);
+  });
+
+  it("stages inbound media into the agent workspace for non-sandbox sessions", async () => {
+    const mediaPath = path.join(root, "openclaw-media", "inbound", "small.bin");
+    const agentWorkspace = path.join(root, "agent-workspace");
+
+    await mkdir(path.dirname(mediaPath), { recursive: true });
+    await mkdir(agentWorkspace, { recursive: true });
+    await writeFile(mediaPath, Buffer.alloc(1024, 1));
+
+    const staged = await stageWecomInboundMediaForSession({
+      cfg: {
+        channels: {
+          wecom: {
+            mediaMaxMb: 8,
+          },
+        },
+        agents: {
+          list: [
+            {
+              id: "ops",
+              workspace: agentWorkspace,
+              sandbox: {
+                mode: "off",
+                scope: "session",
+                workspaceRoot: path.join(root, "sandboxes"),
+                workspaceAccess: "ro",
+                docker: {
+                  workdir: "/workspace",
+                },
+              },
+            },
+          ],
+        },
+      } as any,
+      accountId: "default",
+      agentId: "ops",
+      sessionKey: "agent:ops:wecom:default:dm:zhangsan",
+      mediaPath,
+      filename: "small.bin",
+    });
+
+    expect(staged).toBe(path.join(agentWorkspace, "media", "inbound", "small.bin"));
+    const stagedBuffer = await readFile(staged);
+    expect(stagedBuffer.byteLength).toBe(1024);
+  });
+
+  it("allocates distinct staged filenames for concurrent same-name uploads", async () => {
+    const mediaPathA = path.join(root, "openclaw-media", "inbound", "dup-a.bin");
+    const mediaPathB = path.join(root, "openclaw-media", "inbound", "dup-b.bin");
+    const agentWorkspace = path.join(root, "agent-workspace");
+
+    await mkdir(path.dirname(mediaPathA), { recursive: true });
+    await mkdir(agentWorkspace, { recursive: true });
+    await writeFile(mediaPathA, Buffer.from("first"));
+    await writeFile(mediaPathB, Buffer.from("second"));
+
+    const cfg = {
+      channels: {
+        wecom: {
+          mediaMaxMb: 8,
+        },
+      },
+      agents: {
+        list: [
+          {
+            id: "ops",
+            workspace: agentWorkspace,
+            sandbox: {
+              mode: "off",
+              scope: "session",
+              workspaceAccess: "ro",
+              docker: {
+                workdir: "/workspace",
+              },
+            },
+          },
+        ],
+      },
+    } as any;
+
+    const [stagedA, stagedB] = await Promise.all([
+      stageWecomInboundMediaForSession({
+        cfg,
+        accountId: "default",
+        agentId: "ops",
+        sessionKey: "agent:ops:wecom:default:dm:zhangsan",
+        mediaPath: mediaPathA,
+        filename: "dup.bin",
+      }),
+      stageWecomInboundMediaForSession({
+        cfg,
+        accountId: "default",
+        agentId: "ops",
+        sessionKey: "agent:ops:wecom:default:dm:lisi",
+        mediaPath: mediaPathB,
+        filename: "dup.bin",
+      }),
+    ]);
+
+    expect(stagedA).not.toBe(stagedB);
+    expect([path.basename(stagedA), path.basename(stagedB)].sort()).toEqual(["dup-1.bin", "dup.bin"]);
+    expect((await readFile(stagedA)).toString()).toMatch(/first|second/);
+    expect((await readFile(stagedB)).toString()).toMatch(/first|second/);
+    expect((await readFile(stagedA)).toString()).not.toBe((await readFile(stagedB)).toString());
+  });
+});