@soimy/dingtalk 3.3.0 → 3.4.0

package/src/reply-strategy.ts

@@ -0,0 +1,72 @@
+/**
+ * Reply strategy interface for DingTalk message delivery.
+ *
+ * Abstracts the "how to deliver a reply" concern away from
+ * handleDingTalkMessage, so card and markdown modes each manage
+ * their own state and lifecycle independently.
+ */
+
+import type { AICardInstance, DingTalkConfig, Logger, QuotedRef } from "./types";
+import { createCardReplyStrategy } from "./reply-strategy-card";
+import { createMarkdownReplyStrategy } from "./reply-strategy-markdown";
+
+// ---- Public types ------------------------------------------------
+
+export interface DeliverPayload {
+  text?: string;
+  mediaUrls: string[];
+  kind: "block" | "final" | "tool";
+}
+
+export interface ReplyOptions {
+  disableBlockStreaming: boolean;
+  onPartialReply?: (payload: { text?: string }) => void;
+  onReasoningStream?: (payload: { text?: string }) => void;
+  onAssistantMessageStart?: () => void;
+}
+
+export interface ReplyStrategy {
+  /** Options forwarded to the runtime dispatcher. */
+  getReplyOptions(): ReplyOptions;
+
+  /** Called by the deliver callback for each payload chunk. */
+  deliver(payload: DeliverPayload): Promise<void>;
+
+  /** Called after dispatch completes successfully. */
+  finalize(): Promise<void>;
+
+  /** Called when dispatch throws an error. */
+  abort(error: Error): Promise<void>;
+
+  /** Last known final text (for external consumers such as logging). */
+  getFinalText(): string | undefined;
+}
+
+/** Shared context passed to every strategy implementation. */
+export interface ReplyStrategyContext {
+  config: DingTalkConfig;
+  to: string;
+  sessionWebhook: string;
+  senderId: string;
+  isDirect: boolean;
+  accountId: string;
+  storePath: string;
+  groupId?: string;
+  log?: Logger;
+  replyQuotedRef?: QuotedRef;
+  deliverMedia: (urls: string[]) => Promise<void>;
+}
+
+// ---- Factory -----------------------------------------------------
+
+export function createReplyStrategy(
+  params: ReplyStrategyContext & {
+    card: AICardInstance | undefined;
+    useCardMode: boolean;
+  },
+): ReplyStrategy {
+  if (params.useCardMode && params.card) {
+    return createCardReplyStrategy({ ...params, card: params.card });
+  }
+  return createMarkdownReplyStrategy(params);
+}

package/src/send-service.ts

@@ -10,8 +10,8 @@ import { stripTargetPrefix } from "./config";
 import { getLogger } from "./logger-context";
 import { getVoiceDurationMs, uploadMedia as uploadMediaUtil } from "./media-utils";
 import { convertMarkdownTablesToPlainText, detectMarkdownAndExtractTitle } from "./message-utils";
+import { DEFAULT_MESSAGE_CONTEXT_TTL_DAYS, upsertOutboundMessageContext } from "./message-context-store";
 import { resolveOriginalPeerId } from "./peer-id-registry";
-import { appendOutboundToQuoteJournal, appendProactiveOutboundJournal } from "./quote-journal";
 import {
   deleteProactiveRiskObservation,
   getProactiveRiskObservation,
@@ -25,6 +25,7 @@ import type {
   DingTalkTrackingMetadata,
   Logger,
   ProactiveMessagePayload,
+  QuotedRef,
   SendMessageOptions,
   SessionWebhookResponse,
 } from "./types";
@@ -38,24 +39,83 @@ function isTrackingResult(result: ProactiveTextSendResult): result is { tracking
   return "tracking" in result;
 }
 
-function extractOutboundMessageId(payload: unknown): string | undefined {
+function firstTrimmedString(...candidates: unknown[]): string | undefined {
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return undefined;
+}
+
+function extractOutboundDeliveryMetadata(payload: unknown): {
+  messageId?: string;
+  processQueryKey?: string;
+  outTrackId?: string;
+  cardInstanceId?: string;
+} {
   if (!payload || typeof payload !== "object") {
-    return undefined;
+    return {};
   }
   const data = payload as Record<string, unknown>;
   const tracking =
     data.tracking && typeof data.tracking === "object"
       ? (data.tracking as Record<string, unknown>)
       : undefined;
-  const value =
-    data.processQueryKey ??
-    data.messageId ??
-    data.msgid ??
-    tracking?.processQueryKey ??
-    tracking?.messageId ??
-    tracking?.msgid ??
-    tracking?.outTrackId;
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+  const messageId = firstTrimmedString(data.messageId, data.msgid, tracking?.messageId, tracking?.msgid);
+  const processQueryKey = firstTrimmedString(data.processQueryKey, tracking?.processQueryKey);
+  const outTrackId = firstTrimmedString(data.outTrackId, tracking?.outTrackId);
+  const cardInstanceId = firstTrimmedString(data.cardInstanceId, tracking?.cardInstanceId);
+  return { messageId, processQueryKey, outTrackId, cardInstanceId };
+}
+
+function persistOutboundMessageContext(params: {
+  storePath?: string;
+  accountId?: string;
+  conversationId: string;
+  text?: string;
+  messageType?: string;
+  createdAt?: number;
+  quotedRef?: QuotedRef;
+  log?: Logger;
+  delivery: {
+    messageId?: string;
+    processQueryKey?: string;
+    outTrackId?: string;
+    cardInstanceId?: string;
+    kind?: "session" | "proactive-text" | "proactive-card" | "proactive-media";
+  };
+}): void {
+  if (!params.storePath || !params.accountId) {
+    return;
+  }
+  params.log?.debug?.(
+    `[DingTalk][QuotedRef][Persist] direction=outbound scope=${params.conversationId} ` +
+    `messageType=${params.messageType || "(none)"} processQueryKey=${params.delivery.processQueryKey || "(none)"} ` +
+    `messageId=${params.delivery.messageId || "(none)"} quotedRef=${params.quotedRef ? JSON.stringify(params.quotedRef) : "(none)"}`,
+  );
+  upsertOutboundMessageContext({
+    storePath: params.storePath,
+    accountId: params.accountId,
+    conversationId: params.conversationId,
+    createdAt: params.createdAt ?? Date.now(),
+    text: params.text,
+    messageType: params.messageType,
+    ttlMs: DEFAULT_MESSAGE_CONTEXT_TTL_DAYS * 24 * 60 * 60 * 1000,
+    topic: null,
+    quotedRef: params.quotedRef,
+    delivery: params.delivery,
+  });
+}
+
+function buildPersistedOutboundText(text: string, options: SendMessageOptions): string {
+  if (text) {
+    return text;
+  }
+  if (options.mediaPath && options.mediaType) {
+    return `[media:${options.mediaType}] ${options.mediaPath}`;
+  }
+  return text;
 }
 
 function composeCardContentForAppend(previous: string | undefined, incoming: string): string {
@@ -174,7 +234,7 @@ export async function sendProactiveTextOrMarkdown(
 
   // In card mode, use card API to avoid oToMessages/batchSend permission requirement.
   const messageType = config.messageType || "markdown";
-  if (messageType === "card" && config.cardTemplateId) {
+  if (messageType === "card" && config.cardTemplateId && !options.forceMarkdown) {
     log?.debug?.(
       `[DingTalk] Using card API for proactive message to user ${resolvedTarget}${proactiveRiskTag}`,
     );
@@ -201,7 +261,7 @@ export async function sendProactiveTextOrMarkdown(
     ? "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
     : "https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend";
 
-  const normalizedText = convertMarkdownTablesToPlainText(text);
+  const normalizedText = config.convertMarkdownTables !== false ? convertMarkdownTablesToPlainText(text) : text;
   const { useMarkdown, title } = detectMarkdownAndExtractTitle(normalizedText, options, "OpenClaw 提醒");
 
   log?.debug?.(
@@ -349,18 +409,21 @@ export async function sendProactiveMedia(
       deleteProactiveRiskObservation(options.accountId, resolvedTarget);
     }
 
-    const messageId = extractOutboundMessageId(result.data);
-    if (options.storePath && options.accountId) {
-      await appendProactiveOutboundJournal({
-        storePath: options.storePath,
-        accountId: options.accountId,
-        conversationId: options.conversationId || resolvedTarget,
-        messageId,
-        text: `[media:${mediaType}] ${mediaPath}`,
-        messageType: "outbound-proactive-media",
-        log,
-      });
-    }
+    const delivery = extractOutboundDeliveryMetadata(result.data);
+    const messageId = delivery.messageId || delivery.processQueryKey || delivery.outTrackId;
+    persistOutboundMessageContext({
+      storePath: options.storePath,
+      accountId: options.accountId,
+      conversationId: options.conversationId || resolvedTarget,
+      text: `[media:${mediaType}] ${mediaPath}`,
+      messageType: "outbound-proactive-media",
+      quotedRef: options.quotedRef,
+      log,
+      delivery: {
+        ...delivery,
+        kind: "proactive-media",
+      },
+    });
     return { ok: true, data: result.data, messageId };
   } catch (err: any) {
     log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
@@ -390,10 +453,12 @@ export async function sendProactiveMedia(
     }
 
     // Fallback: ensure user still gets a usable link/path text.
+    const fallbackDisplayText = `📎 媒体发送失败，兜底链接/路径：${mediaPath}`;
+    const fallbackPersistedText = `媒体发送失败，兜底链接/路径：${mediaPath}`;
     const fallback = await sendProactiveTextOrMarkdown(
       config,
       target,
-      `📎 媒体发送失败，兜底链接/路径：${mediaPath}`,
+      fallbackDisplayText,
       options,
     ).catch((fallbackErr: any) => ({ __fallbackError: fallbackErr }));
 
@@ -401,7 +466,23 @@ export async function sendProactiveMedia(
       return { ok: false, error: `${err.message}; fallback failed: ${(fallback as any).__fallbackError?.message || "unknown"}` };
     }
 
-    return { ok: true, data: fallback, messageId: (fallback as any)?.processQueryKey || (fallback as any)?.messageId };
+    const fallbackDelivery = extractOutboundDeliveryMetadata(fallback);
+    const fallbackMessageId =
+      fallbackDelivery.messageId || fallbackDelivery.processQueryKey || fallbackDelivery.outTrackId;
+    persistOutboundMessageContext({
+      storePath: options.storePath,
+      accountId: options.accountId,
+      conversationId: options.conversationId || normalizedTarget,
+      text: fallbackPersistedText,
+      messageType: "outbound-proactive-fallback",
+      quotedRef: options.quotedRef,
+      log,
+      delivery: {
+        ...fallbackDelivery,
+        kind: isTrackingResult(fallback as ProactiveTextSendResult) ? "proactive-card" : "proactive-text",
+      },
+    });
+    return { ok: true, data: fallback, messageId: fallbackMessageId };
   }
 }
 
@@ -449,7 +530,7 @@ export async function sendBySession(
   }
 
   // Fallback to text/markdown reply payload.
-  const normalizedText = convertMarkdownTablesToPlainText(text);
+  const normalizedText = config.convertMarkdownTables !== false ? convertMarkdownTablesToPlainText(text) : text;
   const { useMarkdown, title } = detectMarkdownAndExtractTitle(normalizedText, options, "Clawdbot 消息");
   const chunks = splitMarkdownChunks(normalizedText, DINGTALK_TEXT_CHUNK_LIMIT);
 
@@ -492,7 +573,7 @@ export async function sendMessage(
     const messageType = config.messageType || "markdown";
     const log = options.log || getLogger();
 
-    if (messageType === "card" && options.card) {
+    if (messageType === "card" && options.card && !options.forceMarkdown) {
       const card = options.card;
       if (isCardInTerminalState(card.state)) {
         if (options.sessionWebhook) {
@@ -530,34 +611,41 @@ export async function sendMessage(
 
     if (options.sessionWebhook) {
       const data = await sendBySession(config, options.sessionWebhook, text, options);
-      const messageId = extractOutboundMessageId(data);
-      if (options.storePath && options.accountId) {
-        await appendOutboundToQuoteJournal({
-          storePath: options.storePath,
-          accountId: options.accountId,
-          conversationId: options.conversationId || conversationId,
-          messageId,
-          text,
-          messageType: "outbound",
-          log,
-        });
-      }
-      return { ok: true, data, messageId };
-    }
-
-    const result = await sendProactiveTextOrMarkdown(config, conversationId, text, options);
-    const messageId = extractOutboundMessageId(result);
-    if (options.storePath && options.accountId) {
-      await appendProactiveOutboundJournal({
+      const delivery = extractOutboundDeliveryMetadata(data);
+      const messageId = delivery.messageId || delivery.processQueryKey || delivery.outTrackId;
+      const persistedText = buildPersistedOutboundText(text, options);
+      persistOutboundMessageContext({
         storePath: options.storePath,
         accountId: options.accountId,
         conversationId: options.conversationId || conversationId,
-        messageId,
-        text,
-        messageType: "outbound-proactive",
+        text: persistedText,
+        messageType: options.mediaPath && options.mediaType ? "outbound-media" : "outbound",
+        quotedRef: options.quotedRef,
         log,
+        delivery: {
+          ...delivery,
+          kind: "session",
+        },
       });
+      return { ok: true, data, messageId };
     }
+
+    const result = await sendProactiveTextOrMarkdown(config, conversationId, text, options);
+    const delivery = extractOutboundDeliveryMetadata(result);
+    const messageId = delivery.messageId || delivery.processQueryKey || delivery.outTrackId;
+    persistOutboundMessageContext({
+      storePath: options.storePath,
+      accountId: options.accountId,
+      conversationId: options.conversationId || conversationId,
+      text,
+      messageType: "outbound-proactive",
+      quotedRef: options.quotedRef,
+      log,
+      delivery: {
+        ...delivery,
+        kind: isTrackingResult(result) ? "proactive-card" : "proactive-text",
+      },
+    });
     if (isTrackingResult(result)) {
       return { ok: true, tracking: result.tracking };
     }

package/src/targeting/agent-name-matcher.ts

@@ -0,0 +1,148 @@
+/**
+ * Agent name matcher for @sub-agent feature
+ *
+ * Matches @mentions to agent IDs based on name and id fields in agents.list config.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { AtMention, AgentNameMatch } from "../types";
+
+interface AgentConfig {
+  id: string;
+  name?: string;
+  default?: boolean;
+}
+
+/**
+ * Normalize name for case-insensitive matching
+ */
+function normalizeName(name: string): string {
+  return name.trim().toLowerCase();
+}
+
+/**
+ * Get main agent ID from agents.list
+ */
+export function getMainAgentId(agents: AgentConfig[] | undefined): string {
+  if (!agents || agents.length === 0) {
+    return "main";
+  }
+
+  const defaultAgent = agents.find((a) => a.default);
+  if (defaultAgent) {
+    return defaultAgent.id;
+  }
+
+  return agents[0].id;
+}
+
+/**
+ * Match a single @name to an agent
+ */
+function matchAtName(atName: string, agents: AgentConfig[]): AgentNameMatch | null {
+  const normalizedAtName = normalizeName(atName);
+
+  for (const agent of agents) {
+    // 1. Match by name field
+    if (agent.name && normalizeName(agent.name) === normalizedAtName) {
+      return {
+        agentId: agent.id,
+        matchSource: "name",
+        matchedName: agent.name,
+      };
+    }
+
+    // 2. Match by id field
+    if (normalizeName(agent.id) === normalizedAtName) {
+      return {
+        agentId: agent.id,
+        matchSource: "id",
+        matchedName: agent.id,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Resolve @mentions to agent matches
+ *
+ * @param atMentions - List of @mentions extracted from message
+ * @param cfg - OpenClaw configuration
+ * @param atUserDingtalkIds - dingtalkIds from webhook atUsers field (real users selected via @picker)
+ * @returns Matched agents, unmatched names, main agent ID, and whether there are invalid agent names
+ *
+ * @remarks
+ * Exclusion logic for unmatched @mentions:
+ * - If mention.userId is set (from richText), it's a real user → excluded from unmatchedNames
+ * - In text mode, we cannot map dingtalkIds to specific @mention names
+ * - To avoid false positives (reporting real user names as missing agents),
+ *   we use a conservative heuristic:
+ *   - If realUserCount > 0, hasInvalidAgentNames is always false
+ *   - This means we never report "agent not found" in text mode when there are real users
+ * - In richText mode, mention.userId allows precise exclusion, so the heuristic is not needed
+ */
+export function resolveAtAgents(
+  atMentions: AtMention[],
+  cfg: OpenClawConfig,
+  atUserDingtalkIds?: string[],
+): {
+  matchedAgents: AgentNameMatch[];
+  unmatchedNames: string[];
+  mainAgentId: string;
+  /** Count of @mentions that are likely real users (from atUserDingtalkIds) */
+  realUserCount: number;
+  /** Whether there are invalid agent names (conservative: false if realUserCount > 0) */
+  hasInvalidAgentNames: boolean;
+} {
+  const agents = cfg?.agents?.list as AgentConfig[] | undefined;
+  const mainAgentId = getMainAgentId(agents);
+
+  if (!atMentions || atMentions.length === 0) {
+    return {
+      matchedAgents: [],
+      unmatchedNames: [],
+      mainAgentId,
+      realUserCount: 0,
+      hasInvalidAgentNames: false,
+    };
+  }
+
+  const matchedAgents: AgentNameMatch[] = [];
+  const unmatchedNames: string[] = [];
+
+  for (const mention of atMentions) {
+    const match = agents ? matchAtName(mention.name, agents) : null;
+
+    if (match) {
+      // Avoid duplicate agents
+      if (!matchedAgents.some((m) => m.agentId === match.agentId)) {
+        matchedAgents.push(match);
+      }
+    } else {
+      // Exclude @real users (those with userId are real users from richText)
+      if (!mention.userId) {
+        unmatchedNames.push(mention.name);
+      }
+    }
+  }
+
+  // Count real users from atUserDingtalkIds
+  // These are real DingTalk users selected via @picker, but we don't know which names they correspond to
+  const realUserCount = atUserDingtalkIds?.length || 0;
+
+  // Conservative heuristic: if there are real users, never report invalid agent names
+  // This avoids false positives where real user names are incorrectly reported as missing agents
+  // In text mode, we cannot distinguish which @mentions correspond to real users
+  // In richText mode, mention.userId provides precise exclusion, so this is just a safety net
+  const hasInvalidAgentNames = realUserCount === 0 && unmatchedNames.length > 0;
+
+  return {
+    matchedAgents,
+    unmatchedNames,
+    mainAgentId,
+    realUserCount,
+    hasInvalidAgentNames,
+  };
+}

package/src/targeting/agent-routing.ts

@@ -0,0 +1,181 @@
+/**
+ * Sub-agent routing for @mention-based multi-agent support.
+ *
+ * Extracts @mentions from inbound messages and resolves them to agent IDs
+ * using agents.list configuration. This is a plugin-layer routing mechanism
+ * because the framework's resolveAgentRoute only supports static matching
+ * (channel + accountId + peer), not content-based dynamic routing.
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { resolveAtAgents } from "./agent-name-matcher";
+import { parseLearnCommand } from "../learning-command-service";
+import { getDingTalkRuntime } from "../runtime";
+import { sendBySession } from "../send-service";
+import type { AgentNameMatch, DingTalkConfig, DingTalkInboundMessage, HandleDingTalkMessageParams, Logger, MessageContent } from "../types";
+
+/**
+ * Build a session key for a specific agent using the runtime API.
+ * Falls back to framework's resolveAgentRoute if buildAgentSessionKey is unavailable.
+ */
+export function buildAgentSessionKey(params: {
+  rt: ReturnType<typeof getDingTalkRuntime>;
+  cfg: OpenClawConfig;
+  accountId: string;
+  agentId: string;
+  peerKind: "direct" | "group";
+  peerId: string;
+}): string {
+  const { rt, cfg, accountId, agentId, peerKind, peerId } = params;
+  const routing = rt.channel.routing as Record<string, unknown>;
+  if (typeof routing.buildAgentSessionKey === "function") {
+    return (
+      (routing.buildAgentSessionKey as (p: unknown) => string)({
+        agentId,
+        channel: "dingtalk",
+        accountId,
+        peer: { kind: peerKind, id: peerId },
+        dmScope: cfg.session?.dmScope,
+        identityLinks: cfg.session?.identityLinks,
+      })
+    ).toLowerCase();
+  }
+  // Fallback: derive a session key with agentId suffix to ensure isolation.
+  // resolveAgentRoute routes to the default agent, so we append the target
+  // agentId to prevent session key collisions between sub-agents.
+  // @migration-note: When SDK exposes buildAgentSessionKey in type definitions,
+  // sessions created via this fallback path will become orphaned. Remove this
+  // fallback and the typeof check once the SDK is updated.
+  const fallbackRoute = rt.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: "dingtalk",
+    accountId,
+    peer: { kind: peerKind, id: peerId },
+  });
+  return `${fallbackRoute.sessionKey}:subagent:${agentId}`;
+}
+
+/**
+ * Sanitize agent name for safe use in markdown prefix and context hints.
+ * Strips brackets, newlines, and control characters to prevent markdown
+ * breakage and prompt injection.
+ */
+function sanitizeAgentName(name: string): string {
+  return name.replace(/[[\]\r\n]/g, "").trim();
+}
+
+/**
+ * Resolve @mention-based sub-agent routing for a group message.
+ *
+ * Returns matched agents if any @mentions resolve to configured agents,
+ * or null if the message should be handled by the default agent.
+ */
+export async function resolveSubAgentRoute(params: {
+  extractedContent: MessageContent;
+  cfg: OpenClawConfig;
+  isGroup: boolean;
+  dingtalkConfig: DingTalkConfig;
+  sessionWebhook: string;
+  senderId: string;
+  log?: Logger;
+}): Promise<{
+  matchedAgents: AgentNameMatch[];
+  preDownloadedMedia?: { mediaPath?: string; mediaType?: string };
+} | null> {
+  const { extractedContent, cfg, isGroup, dingtalkConfig, sessionWebhook, senderId, log } = params;
+
+  const atMentions = extractedContent.atMentions || [];
+  const atUserDingtalkIds = extractedContent.atUserDingtalkIds;
+  // Strip quoted prefix before checking /learn to avoid false positives
+  // when the quoted message itself contains a /learn command.
+  const textForCommandCheck = extractedContent.text.replace(/^\[引用[^\]]*\]\s*/, "");
+  const isLearnCommand = parseLearnCommand(textForCommandCheck).scope !== "unknown";
+
+  if (
+    !isGroup ||
+    atMentions.length === 0 ||
+    !cfg.agents?.list ||
+    cfg.agents.list.length === 0 ||
+    isLearnCommand
+  ) {
+    return null;
+  }
+
+  const { matchedAgents, unmatchedNames, realUserCount, hasInvalidAgentNames } = resolveAtAgents(
+    atMentions,
+    cfg,
+    atUserDingtalkIds,
+  );
+  log?.info?.(
+    `[DingTalk] Sub-agent resolve: matched=${matchedAgents.map((a) => a.agentId).join(",")} unmatched=${unmatchedNames.join(",")} realUsers=${realUserCount}`,
+  );
+
+  // Send fallback notice for unmatched agent names
+  if (hasInvalidAgentNames) {
+    const fallbackReason = `未找到名为"${unmatchedNames.join("、")}"的助手`;
+    try {
+      await sendBySession(dingtalkConfig, sessionWebhook, `⚠️ ${fallbackReason}`, {
+        atUserId: senderId,
+        log,
+      });
+    } catch (err: any) {
+      log?.debug?.(`[DingTalk] Failed to send fallback notice: ${err.message}`);
+    }
+  }
+
+  if (matchedAgents.length === 0) {
+    return null;
+  }
+
+  return { matchedAgents };
+}
+
+/**
+ * Process matched sub-agents by dispatching each to handleDingTalkMessage.
+ */
+export async function dispatchSubAgents(params: {
+  matchedAgents: AgentNameMatch[];
+  cfg: OpenClawConfig;
+  accountId: string;
+  data: DingTalkInboundMessage;
+  dingtalkConfig: DingTalkConfig;
+  sessionWebhook: string;
+  extractedContent: MessageContent;
+  handleMessage: (params: HandleDingTalkMessageParams) => Promise<void>;
+  downloadMedia: (config: DingTalkConfig, mediaPath: string, log?: Logger) => Promise<{ path: string; mimeType: string } | null>;
+  log?: Logger;
+}): Promise<void> {
+  const { matchedAgents, cfg, accountId, data, dingtalkConfig, sessionWebhook, extractedContent, handleMessage, downloadMedia: download, log } = params;
+
+  // Pre-download media once to avoid duplication across sub-agents
+  let preDownloadedMedia: { mediaPath?: string; mediaType?: string } | undefined;
+  if (extractedContent.mediaPath && dingtalkConfig.robotCode) {
+    const media = await download(dingtalkConfig, extractedContent.mediaPath, log);
+    if (media) {
+      preDownloadedMedia = { mediaPath: media.path, mediaType: media.mimeType };
+    }
+  }
+
+  for (const agentMatch of matchedAgents) {
+    try {
+      await handleMessage({
+        cfg,
+        accountId,
+        data,
+        sessionWebhook,
+        log,
+        dingtalkConfig,
+        subAgentOptions: {
+          agentId: agentMatch.agentId,
+          responsePrefix: `[${sanitizeAgentName(agentMatch.matchedName)}] `,
+          matchedName: agentMatch.matchedName,
+        },
+        preDownloadedMedia,
+      });
+    } catch (error) {
+      log?.error?.(
+        `[DingTalk] Sub-agent ${agentMatch.agentId} failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+}