@soimy/dingtalk 3.3.0 → 3.4.0

package/src/inbound-handler.ts

@@ -1,19 +1,29 @@
 import axios from "axios";
-import { normalizeAllowFrom, isSenderAllowed, isSenderGroupAllowed } from "./access-control";
+import { normalizeAllowFrom, isSenderAllowed, resolveGroupAccess } from "./access-control";
+import { buildAgentSessionKey, resolveSubAgentRoute, dispatchSubAgents } from "./targeting/agent-routing";
+import { classifyAckReactionEmoji } from "./ack-reaction-classifier";
+import { attachNativeAckReaction } from "./ack-reaction-service";
+import { createDynamicAckReactionController } from "./ack-reaction/dynamic-ack-reaction-controller";
 import { extractAttachmentText } from "./attachment-text-extractor";
 import { getAccessToken } from "./auth";
-import {
-  createAICard,
-  findCardContent,
-  finishAICard,
-  formatContentForCard,
-  getCardContentByProcessQueryKey,
-  isCardInTerminalState,
-} from "./card-service";
-import { classifyAckReactionEmoji } from "./ack-reaction-classifier";
+import { createAICard } from "./card-service";
 import { resolveAckReactionSetting, resolveGroupConfig } from "./config";
+import {
+  applyManualTargetLearningRule,
+  applyManualTargetsLearningRule,
+  applyManualGlobalLearningRule,
+  applyManualSessionLearningNote,
+  applyTargetSetLearningRule,
+  buildLearningContextBlock,
+  createOrUpdateTargetSet,
+  deleteManualRule,
+  disableManualRule,
+  isFeedbackLearningEnabled,
+  listLearningTargetSets,
+  listScopedLearningRules,
+  resolveManualForcedReply,
+} from "./feedback-learning-service";
 import { formatGroupMembers, noteGroupMember } from "./group-members-store";
-import { setCurrentLogger } from "./logger-context";
 import {
   formatLearnAppliedReply,
   formatLearnCommandHelp,
@@ -28,28 +38,30 @@ import {
   isLearningOwner,
   parseLearnCommand,
 } from "./learning-command-service";
-import { extractMessageContent } from "./message-utils";
+import { setCurrentLogger } from "./logger-context";
 import { prepareMediaInput, resolveOutboundMediaType } from "./media-utils";
+import {
+  DEFAULT_MEDIA_CONTEXT_TTL_MS,
+  DEFAULT_MESSAGE_CONTEXT_TTL_DAYS,
+  upsertInboundMessageContext,
+} from "./message-context-store";
+import { extractMessageContent } from "./message-utils";
+import { resolveQuotedRuntimeContext } from "./messaging/quoted-context";
+import {
+  buildInboundQuotedRef,
+  createReplyQuotedRef,
+  resolveQuotedRecord,
+} from "./messaging/quoted-ref";
 import { registerPeerId } from "./peer-id-registry";
 import {
   clearProactiveRiskObservationsForTest,
   getProactiveRiskObservationForAny,
 } from "./proactive-risk-registry";
-import {
-  appendQuoteJournalEntry,
-  DEFAULT_JOURNAL_TTL_DAYS,
-  resolveQuotedMessageById,
-} from "./quote-journal";
+import { downloadGroupFile, getUnionIdByStaffId, resolveQuotedFile } from "./quoted-file-service";
+import { createReplyStrategy } from "./reply-strategy";
+import type { DeliverPayload } from "./reply-strategy";
 import { getDingTalkRuntime } from "./runtime";
 import { sendBySession, sendMessage, sendProactiveMedia } from "./send-service";
-import { clearSessionPeerOverride, getSessionPeerOverride, setSessionPeerOverride } from "./session-peer-store";
-import { resolveDingTalkSessionPeer } from "./session-routing";
-import type { DingTalkConfig, HandleDingTalkMessageParams, MediaFile } from "./types";
-import { AICardStatus } from "./types";
-import { createCardDraftController } from "./card-draft-controller";
-import { acquireSessionLock } from "./session-lock";
-import { cacheInboundDownloadCode, getCachedDownloadCode } from "./quoted-msg-cache";
-import { downloadGroupFile, getUnionIdByStaffId, resolveQuotedFile } from "./quoted-file-service";
 import {
   formatSessionAliasBoundReply,
   formatSessionAliasClearedReply,
@@ -60,29 +72,82 @@ import {
   parseSessionCommand,
   validateSessionAlias,
 } from "./session-command-service";
+import { acquireSessionLock } from "./session-lock";
 import {
-  applyManualTargetLearningRule,
-  applyManualTargetsLearningRule,
-  applyManualGlobalLearningRule,
-  applyManualSessionLearningNote,
-  applyTargetSetLearningRule,
-  buildLearningContextBlock,
-  createOrUpdateTargetSet,
-  deleteManualRule,
-  disableManualRule,
-  isFeedbackLearningEnabled,
-  listLearningTargetSets,
-  listScopedLearningRules,
-  resolveManualForcedReply,
-} from "./feedback-learning-service";
-import { attachNativeAckReaction, recallNativeAckReactionWithRetry } from "./ack-reaction-service";
-import { formatDingTalkErrorPayloadLog, maskSensitiveData } from "./utils";
+  clearSessionPeerOverride,
+  getSessionPeerOverride,
+  setSessionPeerOverride,
+} from "./session-peer-store";
+import { resolveDingTalkSessionPeer } from "./session-routing";
+import {
+  upsertObservedGroupTarget,
+  upsertObservedUserTarget,
+} from "./targeting/target-directory-store";
+import type { DingTalkConfig, HandleDingTalkMessageParams, MediaFile } from "./types";
+import { formatDingTalkErrorPayloadLog, getErrorMessage, getErrorResponseData, maskSensitiveData } from "./utils";
 
 const DEFAULT_PROACTIVE_HINT_COOLDOWN_HOURS = 24;
 const MIN_THINKING_REACTION_VISIBLE_MS = 1200;
-const ATTACHMENT_TEXT_PREFIX = "[附件内容摘录]";
+const MAX_DYNAMIC_ACK_DISPOSE_WAIT_MS = 500;
 const proactiveHintLastSentAt = new Map<string, number>();
 
+function resolvePinnedMainDmOwner(params: {
+  dmScope?: string;
+  allowFrom?: string[];
+}): string | null {
+  if ((params.dmScope ?? "main") !== "main") {
+    return null;
+  }
+  const allow = normalizeAllowFrom(params.allowFrom);
+  if (allow.hasWildcard) {
+    return null;
+  }
+  return allow.entries.length === 1 ? allow.entries[0] : null;
+}
+
+function ttlDaysToMs(ttlDays: number | undefined): number | undefined {
+  if (typeof ttlDays !== "number" || !Number.isFinite(ttlDays) || ttlDays <= 0) {
+    return undefined;
+  }
+  return ttlDays * 24 * 60 * 60 * 1000;
+}
+
+async function waitForDynamicAckDispose(params: {
+  dispose: () => Promise<void>;
+  log?: { debug?: (message: string) => void; warn?: (message: string) => void };
+  sessionKey: string;
+}): Promise<void> {
+  let timedOut = false;
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  const disposePromise = params.dispose().catch((err: unknown) => {
+    params.log?.warn?.(
+      `[DingTalk] Dynamic ack reaction cleanup failed for session ${params.sessionKey}: ${getErrorMessage(err)}`,
+    );
+  });
+
+  try {
+    await Promise.race([
+      disposePromise,
+      new Promise<void>((resolve) => {
+        timeoutHandle = setTimeout(() => {
+          timedOut = true;
+          resolve();
+        }, MAX_DYNAMIC_ACK_DISPOSE_WAIT_MS);
+      }),
+    ]);
+  } finally {
+    if (timeoutHandle) {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  if (timedOut) {
+    params.log?.debug?.(
+      `[DingTalk] Dynamic ack reaction cleanup timed out after ${MAX_DYNAMIC_ACK_DISPOSE_WAIT_MS}ms; releasing session lock for ${params.sessionKey}`,
+    );
+  }
+}
+
 export function resetProactivePermissionHintStateForTest(): void {
   proactiveHintLastSentAt.clear();
   clearProactiveRiskObservationsForTest();
@@ -118,7 +183,11 @@ function shouldSendProactivePermissionHint(params: {
     return false;
   }
 
-  const riskObservation = getProactiveRiskObservationForAny(params.accountId, riskTargets, params.nowMs);
+  const riskObservation = getProactiveRiskObservationForAny(
+    params.accountId,
+    riskTargets,
+    params.nowMs,
+  );
   if (!riskObservation || riskObservation.source !== "proactive-api") {
     return false;
   }
@@ -138,13 +207,6 @@ function shouldSendProactivePermissionHint(params: {
   return true;
 }
 
-function stripQuotedPrefixForJournal(value: string): string {
-  return value
-    .replace(/^\[引用消息: .*?\]\n\n/s, "")
-    .replace(/^\[这是一条引用消息，原消息ID: .*?\]\n\n/s, "")
-    .trim();
-}
-
 function sanitizeGroupPromptName(value?: string): string {
   return (value || "")
     .replace(/[\r\n,=]/g, " ")
@@ -201,7 +263,7 @@ export async function downloadMedia(
     try {
       return JSON.stringify(maskSensitiveData(value));
     } catch {
-      return String(value);
+      return `[unstringifiable ${typeof value}]`;
     }
   };
 
@@ -267,7 +329,7 @@ export async function downloadMedia(
 }
 
 export async function handleDingTalkMessage(params: HandleDingTalkMessageParams): Promise<void> {
-  const { cfg, accountId, data, sessionWebhook, log, dingtalkConfig } = params;
+  const { cfg, accountId, data, sessionWebhook, log, dingtalkConfig, subAgentOptions, preDownloadedMedia } = params;
   const rt = getDingTalkRuntime();
 
   // Save logger globally so shared services can log consistently without threading log everywhere.
@@ -281,12 +343,21 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     return;
   }
 
-  const extractedContent = extractMessageContent(data);
+  // Shallow copy: only .text is reassigned below; nested arrays (atMentions, mediaTypes) are read-only downstream.
+  const extractedContent = { ...extractMessageContent(data) };
   if (!extractedContent.text) {
     return;
   }
 
+  // Add context hint for sub-agent mode, stripping quoted prefix to avoid protocol noise in agent context.
+  if (subAgentOptions) {
+    const cleanText = extractedContent.text.replace(/^\[引用[^\]]*\]\s*/, "");
+    const contextHint = `[你被 @ 为"${subAgentOptions.matchedName}"]\n\n`;
+    extractedContent.text = contextHint + cleanText;
+  }
+
   const isDirect = data.conversationType === "1";
+  const isGroup = !isDirect;
   const senderOriginalId = (data.senderId || "").trim();
   const senderStaffId = (data.senderStaffId || "").trim();
   const senderId = senderStaffId || senderOriginalId;
@@ -320,7 +391,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     } catch (err: any) {
       log?.debug?.(`[DingTalk] Failed to send proactive permission hint: ${err.message}`);
       if (err?.response?.data !== undefined) {
-        log?.debug?.(formatDingTalkErrorPayloadLog("inbound.proactivePermissionHint", err.response.data));
+        log?.debug?.(
+          formatDingTalkErrorPayloadLog("inbound.proactivePermissionHint", err.response.data),
+        );
       }
     }
   }
@@ -352,7 +425,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
         } catch (err: any) {
           log?.debug?.(`[DingTalk] Failed to send access denied message: ${err.message}`);
           if (err?.response?.data !== undefined) {
-            log?.debug?.(formatDingTalkErrorPayloadLog("inbound.accessDeniedReply", err.response.data));
+            log?.debug?.(
+              formatDingTalkErrorPayloadLog("inbound.accessDeniedReply", err.response.data),
+            );
           }
         }
 
@@ -367,46 +442,90 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       commandAuthorized = true;
     }
   } else {
-    const groupPolicy = dingtalkConfig.groupPolicy || "open";
-    const allowFrom = dingtalkConfig.allowFrom || [];
-
-    if (groupPolicy === "allowlist") {
-      const normalizedAllowFrom = normalizeAllowFrom(allowFrom);
-      const isAllowed = isSenderGroupAllowed({ allow: normalizedAllowFrom, groupId });
-
-      if (!isAllowed) {
-        log?.debug?.(
-          `[DingTalk] Group blocked: conversationId=${groupId} senderId=${senderId} not in allowlist (groupPolicy=allowlist)`,
-        );
+    const groupAccess = resolveGroupAccess({
+      groupPolicy: dingtalkConfig.groupPolicy || "open",
+      groupId,
+      senderId,
+      groups: dingtalkConfig.groups,
+      groupAllowFrom: dingtalkConfig.groupAllowFrom,
+      allowFrom: dingtalkConfig.allowFrom,
+    });
 
-        try {
-          await sendBySession(
-            dingtalkConfig,
-            sessionWebhook,
-            `⛔ 访问受限\n\n您的群聊ID：\`${groupId}\`\n\n请联系管理员将此ID添加到允许列表中。`,
-            { log, atUserId: senderId },
-          );
-        } catch (err: any) {
-          log?.debug?.(`[DingTalk] Failed to send group access denied message: ${err.message}`);
-          if (err?.response?.data !== undefined) {
-            log?.debug?.(
-              formatDingTalkErrorPayloadLog("inbound.groupAccessDeniedReply", err.response.data),
-            );
-          }
-        }
+    if (groupAccess.legacyFallback) {
+      log?.info?.(
+        `[DingTalk] DEPRECATED: groupPolicy=allowlist is using "allowFrom" for group access control. ` +
+        `Please migrate to "groups" (group ID allowlist) or "groupAllowFrom" (sender allowlist).`,
+      );
+    }
 
+    if (!groupAccess.allowed) {
+      if (groupAccess.reason === "disabled") {
+        log?.debug?.(`[DingTalk] Group disabled: all group messages dropped (groupPolicy=disabled)`);
         return;
       }
 
+      const denyMessage = groupAccess.reason === "sender_not_allowed"
+        ? `⛔ 访问受限\n\n您的用户ID：\`${senderId}\`\n\n请联系管理员将此ID添加到群聊允许列表中。`
+        : `⛔ 访问受限\n\n您的群聊ID：\`${groupId}\`\n\n请联系管理员将此ID添加到允许列表中。`;
+
       log?.debug?.(
-        `[DingTalk] Group authorized: conversationId=${groupId} senderId=${senderId} in allowlist`,
+        `[DingTalk] Group blocked: conversationId=${groupId} senderId=${senderId} reason=${groupAccess.reason}`,
       );
+
+      try {
+        await sendBySession(
+          dingtalkConfig,
+          sessionWebhook,
+          denyMessage,
+          { log, atUserId: senderId },
+        );
+      } catch (err: any) {
+        log?.debug?.(`[DingTalk] Failed to send group access denied message: ${err.message}`);
+        if (err?.response?.data !== undefined) {
+          log?.debug?.(
+            formatDingTalkErrorPayloadLog("inbound.groupAccessDeniedReply", err.response.data),
+          );
+        }
+      }
+
+      return;
     }
+
+    log?.debug?.(
+      `[DingTalk] Group authorized: conversationId=${groupId} senderId=${senderId}`,
+    );
   }
 
+  // Calculate account store path and session peer (for session alias feature)
   const accountStorePath = rt.channel.session.resolveStorePath(cfg.session?.store, {
     agentId: accountId,
   });
+  try {
+    if (!isDirect && groupId) {
+      upsertObservedGroupTarget({
+        storePath: accountStorePath,
+        accountId,
+        conversationId: groupId,
+        title: groupName,
+        seenAt: data.createAt,
+      });
+    }
+    if (senderId || senderOriginalId) {
+      upsertObservedUserTarget({
+        storePath: accountStorePath,
+        accountId,
+        senderId: senderOriginalId || senderId,
+        staffId: senderStaffId || undefined,
+        displayName: senderName,
+        conversationId: groupId,
+        seenAt: data.createAt,
+      });
+    }
+  } catch (err) {
+    log?.warn?.(
+      `[DingTalk] Target directory observe failed: accountId=${accountId} groupId=${groupId || "-"} senderId=${senderOriginalId || senderId || "-"} storePath=${accountStorePath || "-"} error=${String(err)}`,
+    );
+  }
   const currentSessionSourceKind = isDirect ? "direct" : "group";
   const currentSessionSourceId = isDirect ? senderId : groupId;
   const peerIdOverride = getSessionPeerOverride({
@@ -422,12 +541,54 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     peerIdOverride,
     config: dingtalkConfig,
   });
-  const route = rt.channel.routing.resolveAgentRoute({
-    cfg,
-    channel: "dingtalk",
-    accountId,
-    peer: { kind: sessionPeer.kind, id: sessionPeer.peerId },
-  });
+
+  const route = subAgentOptions
+    ? {
+        agentId: subAgentOptions.agentId,
+        sessionKey: buildAgentSessionKey({
+          rt,
+          cfg,
+          accountId,
+          agentId: subAgentOptions.agentId,
+          peerKind: sessionPeer.kind,
+          peerId: sessionPeer.peerId,
+        }),
+        mainSessionKey: "",
+      }
+    : rt.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: "dingtalk",
+        accountId,
+        peer: { kind: sessionPeer.kind, id: sessionPeer.peerId },
+      });
+
+  // @Sub-Agent routing: resolve @mentions to agents (skip in recursive sub-agent calls)
+  if (!subAgentOptions) {
+    const subAgentRoute = await resolveSubAgentRoute({
+      extractedContent,
+      cfg,
+      isGroup,
+      dingtalkConfig,
+      sessionWebhook,
+      senderId,
+      log,
+    });
+    if (subAgentRoute) {
+      await dispatchSubAgents({
+        ...subAgentRoute,
+        cfg,
+        accountId,
+        data,
+        dingtalkConfig,
+        sessionWebhook,
+        extractedContent,
+        handleMessage: handleDingTalkMessage,
+        downloadMedia,
+        log,
+      });
+      return;
+    }
+  }
 
   // Route resolved before media download for session context and routing metadata.
   const storePath = rt.channel.session.resolveStorePath(cfg.session?.store, {
@@ -488,22 +649,22 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     return;
   }
   if (
-    (parsedLearnCommand.scope === "global"
-      || parsedLearnCommand.scope === "session"
-      || parsedLearnCommand.scope === "here"
-      || parsedLearnCommand.scope === "target"
-      || parsedLearnCommand.scope === "targets"
-      || parsedLearnCommand.scope === "list"
-      || parsedLearnCommand.scope === "disable"
-      || parsedLearnCommand.scope === "delete"
-      || parsedLearnCommand.scope === "target-set-create"
-      || parsedLearnCommand.scope === "target-set-apply"
-      || parsedSessionCommand.scope === "session-alias-show"
-      || parsedSessionCommand.scope === "session-alias-set"
-      || parsedSessionCommand.scope === "session-alias-clear"
-      || parsedSessionCommand.scope === "session-alias-bind"
-      || parsedSessionCommand.scope === "session-alias-unbind")
-    && !isOwner
+    (parsedLearnCommand.scope === "global" ||
+      parsedLearnCommand.scope === "session" ||
+      parsedLearnCommand.scope === "here" ||
+      parsedLearnCommand.scope === "target" ||
+      parsedLearnCommand.scope === "targets" ||
+      parsedLearnCommand.scope === "list" ||
+      parsedLearnCommand.scope === "disable" ||
+      parsedLearnCommand.scope === "delete" ||
+      parsedLearnCommand.scope === "target-set-create" ||
+      parsedLearnCommand.scope === "target-set-apply" ||
+      parsedSessionCommand.scope === "session-alias-show" ||
+      parsedSessionCommand.scope === "session-alias-set" ||
+      parsedSessionCommand.scope === "session-alias-clear" ||
+      parsedSessionCommand.scope === "session-alias-bind" ||
+      parsedSessionCommand.scope === "session-alias-unbind") &&
+    !isOwner
   ) {
     await sendBySession(dingtalkConfig, sessionWebhook, formatOwnerOnlyDeniedReply(), { log });
     return;
@@ -571,10 +732,12 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       );
       return;
     }
-    if (parsedSessionCommand.scope === "session-alias-bind"
-      && parsedSessionCommand.sourceKind
-      && parsedSessionCommand.sourceId
-      && parsedSessionCommand.peerId) {
+    if (
+      parsedSessionCommand.scope === "session-alias-bind" &&
+      parsedSessionCommand.sourceKind &&
+      parsedSessionCommand.sourceId &&
+      parsedSessionCommand.peerId
+    ) {
       const aliasValidationError = validateSessionAlias(parsedSessionCommand.peerId);
       if (aliasValidationError) {
         await sendBySession(
@@ -604,9 +767,11 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       );
       return;
     }
-    if (parsedSessionCommand.scope === "session-alias-unbind"
-      && parsedSessionCommand.sourceKind
-      && parsedSessionCommand.sourceId) {
+    if (
+      parsedSessionCommand.scope === "session-alias-unbind" &&
+      parsedSessionCommand.sourceKind &&
+      parsedSessionCommand.sourceId
+    ) {
       const existed = clearSessionPeerOverride({
         storePath: accountStorePath,
         accountId,
@@ -681,7 +846,11 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       );
       return;
     }
-    if (parsedLearnCommand.scope === "target" && parsedLearnCommand.targetId && parsedLearnCommand.instruction) {
+    if (
+      parsedLearnCommand.scope === "target" &&
+      parsedLearnCommand.targetId &&
+      parsedLearnCommand.instruction
+    ) {
       const applied = applyManualTargetLearningRule({
         storePath: accountStorePath,
         accountId,
@@ -701,7 +870,11 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       );
       return;
     }
-    if (parsedLearnCommand.scope === "targets" && parsedLearnCommand.targetIds?.length && parsedLearnCommand.instruction) {
+    if (
+      parsedLearnCommand.scope === "targets" &&
+      parsedLearnCommand.targetIds?.length &&
+      parsedLearnCommand.instruction
+    ) {
       const applied = applyManualTargetsLearningRule({
         storePath: accountStorePath,
         accountId,
@@ -721,7 +894,11 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       );
       return;
     }
-    if (parsedLearnCommand.scope === "target-set-create" && parsedLearnCommand.setName && parsedLearnCommand.targetIds?.length) {
+    if (
+      parsedLearnCommand.scope === "target-set-create" &&
+      parsedLearnCommand.setName &&
+      parsedLearnCommand.targetIds?.length
+    ) {
       const saved = createOrUpdateTargetSet({
         storePath: accountStorePath,
         accountId,
@@ -733,15 +910,19 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
         sessionWebhook,
         saved
           ? formatTargetSetSavedReply({
-            setName: parsedLearnCommand.setName,
-            targetIds: parsedLearnCommand.targetIds,
-          })
+              setName: parsedLearnCommand.setName,
+              targetIds: parsedLearnCommand.targetIds,
+            })
           : "目标组保存失败，请检查名称和目标列表。",
         { log },
       );
       return;
     }
-    if (parsedLearnCommand.scope === "target-set-apply" && parsedLearnCommand.setName && parsedLearnCommand.instruction) {
+    if (
+      parsedLearnCommand.scope === "target-set-apply" &&
+      parsedLearnCommand.setName &&
+      parsedLearnCommand.instruction
+    ) {
       const applied = applyTargetSetLearningRule({
         storePath: accountStorePath,
         accountId,
@@ -753,12 +934,12 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
         sessionWebhook,
         applied.length > 0
           ? formatLearnAppliedReply({
-            scope: "target-set",
-            setName: parsedLearnCommand.setName,
-            targetIds: applied.map((item) => item.targetId),
-            instruction: parsedLearnCommand.instruction,
-            ruleId: applied[0]?.ruleId,
-          })
+              scope: "target-set",
+              setName: parsedLearnCommand.setName,
+              targetIds: applied.map((item) => item.targetId),
+              instruction: parsedLearnCommand.instruction,
+              ruleId: applied[0]?.ruleId,
+            })
           : `未找到目标组 \`${parsedLearnCommand.setName}\`，或该目标组为空。`,
         { log },
       );
@@ -774,7 +955,9 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
         });
       const targetSets = listLearningTargetSets({ storePath: accountStorePath, accountId })
         .slice(0, 10)
-        .map((targetSet) => `- [target-set] ${targetSet.name} => ${targetSet.targetIds.join(", ")}`);
+        .map(
+          (targetSet) => `- [target-set] ${targetSet.name} => ${targetSet.targetIds.join(", ")}`,
+        );
       await sendBySession(
         dingtalkConfig,
         sessionWebhook,
@@ -846,6 +1029,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       const aiCard = await createAICard(dingtalkConfig, to, log, {
         accountId,
         storePath: accountStorePath,
+        contextConversationId: groupId,
       });
       if (aiCard) {
         currentAICard = aiCard;
@@ -863,56 +1047,70 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     }
   }
 
-  const hasConcreteQuotedPayload =
-    !!extractedContent.quoted?.mediaDownloadCode ||
-    !!extractedContent.quoted?.isQuotedFile ||
-    !!extractedContent.quoted?.isQuotedCard ||
-    extractedContent.quoted?.prefix.startsWith('[引用消息: "') === true;
-  const journalTTLDays = dingtalkConfig.journalTTLDays ?? DEFAULT_JOURNAL_TTL_DAYS;
-  let content = extractedContent;
-
-  if (data.text?.isReplyMsg && data.originalMsgId && !hasConcreteQuotedPayload) {
-    try {
-      const quoted = resolveQuotedMessageById({
-        storePath,
-        accountId,
-        conversationId: groupId,
-        originalMsgId: data.originalMsgId,
-        ttlDays: journalTTLDays,
-      });
-      if (quoted?.text?.trim()) {
-        const cleanedText = extractedContent.text.replace(
-          /^\[这是一条引用消息，原消息ID: [^\]]+\]\n\n/,
-          "",
-        );
-        content = {
-          ...extractedContent,
-          text: `[引用消息: "${quoted.text.trim()}"]\n\n${cleanedText}`,
-        };
-      }
-    } catch (err) {
-      log?.debug?.(`[DingTalk] Quote journal lookup failed: ${String(err)}`);
-    }
+  const journalTTLDays = dingtalkConfig.journalTTLDays ?? DEFAULT_MESSAGE_CONTEXT_TTL_DAYS;
+  const quotedRef = buildInboundQuotedRef(data, extractedContent);
+  const replyQuotedRef = createReplyQuotedRef(data.msgId);
+  const content = extractedContent;
+  const hasLegacyQuoteContent =
+    typeof data.content?.quoteContent === "string" && data.content.quoteContent.trim().length > 0;
+
+  if (hasLegacyQuoteContent && !quotedRef) {
+    log?.debug?.(
+      `[DingTalk] Legacy quoteContent present without resolvable quotedRef: ` +
+        `conversationType=${data.conversationType} conversationId=${data.conversationId} ` +
+        `msgId=${data.msgId} originalMsgId=${data.originalMsgId || "(none)"}`,
+    );
+  }
+  if (quotedRef) {
+    log?.debug?.(
+      `[DingTalk][QuotedRef] Built inbound quotedRef msgId=${data.msgId} scope=${groupId} ` +
+        `quotedRef=${JSON.stringify(quotedRef)}`,
+    );
+  } else if (
+    data.text?.isReplyMsg ||
+    data.originalMsgId ||
+    data.originalProcessQueryKey ||
+    content.quoted
+  ) {
+    log?.debug?.(
+      `[DingTalk][QuotedRef] Reply metadata present without resolvable quotedRef ` +
+        `msgId=${data.msgId} scope=${groupId} originalMsgId=${data.originalMsgId || "(none)"} ` +
+        `originalProcessQueryKey=${data.originalProcessQueryKey || "(none)"}`,
+    );
   }
 
   try {
-    appendQuoteJournalEntry({
-      storePath,
+    upsertInboundMessageContext({
+      storePath: accountStorePath,
       accountId,
       conversationId: groupId,
       msgId: data.msgId,
       messageType: content.messageType,
-      text: stripQuotedPrefixForJournal(content.text),
+      text: content.text,
+      quotedRef,
       createdAt: data.createAt,
-      ttlDays: journalTTLDays,
+      ttlMs: ttlDaysToMs(journalTTLDays),
+      ttlReferenceMs: data.createAt,
+      cleanupCreatedAtTtlDays: journalTTLDays,
+      topic: null,
     });
   } catch (err) {
-    log?.warn?.(`[DingTalk] Quote journal append failed: ${String(err)}`);
+    log?.warn?.(`[DingTalk] Message context inbound append failed: ${String(err)}`);
   }
 
   let mediaPath: string | undefined;
   let mediaType: string | undefined;
-  if (content.mediaPath && dingtalkConfig.robotCode) {
+  let attachmentContextMsgId = data.msgId;
+  let attachmentContextCreatedAt = data.createAt;
+  let attachmentContextMessageType = content.messageType;
+  let attachmentContextFileName = data.content?.fileName;
+
+  // Use pre-downloaded media if available (from sub-agent outer call)
+  if (preDownloadedMedia?.mediaPath) {
+    mediaPath = preDownloadedMedia.mediaPath;
+    mediaType = preDownloadedMedia.mediaType;
+  } else if (content.mediaPath && dingtalkConfig.robotCode) {
+    // Download media only if not pre-downloaded
     const media = await downloadMedia(dingtalkConfig, content.mediaPath, log);
     if (media) {
       mediaPath = media.path;
@@ -922,15 +1120,21 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
   // Cache downloadCode (+ spaceId/fileId) for quoted file lookups (DM + group).
   if (content.mediaPath && data.msgId) {
-    cacheInboundDownloadCode(
+    upsertInboundMessageContext({
+      storePath: accountStorePath,
       accountId,
-      data.conversationId,
-      data.msgId,
-      content.mediaPath,
-      content.messageType,
-      data.createAt,
-      { spaceId: data.content?.spaceId, fileId: data.content?.fileId, storePath },
-    );
+      conversationId: data.conversationId,
+      msgId: data.msgId,
+      createdAt: data.createAt,
+      messageType: content.messageType,
+      media: {
+        downloadCode: content.mediaPath,
+        spaceId: data.content?.spaceId,
+        fileId: data.content?.fileId,
+      },
+      ttlMs: DEFAULT_MEDIA_CONTEXT_TTL_MS,
+      topic: null,
+    });
   }
 
   // User-sent DingTalk doc / Drive file card: cache msgId -> {spaceId,fileId}
@@ -941,15 +1145,20 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     content.docSpaceId &&
     content.docFileId
   ) {
-    cacheInboundDownloadCode(
+    upsertInboundMessageContext({
+      storePath: accountStorePath,
       accountId,
-      data.conversationId,
-      data.msgId,
-      undefined,
-      content.messageType,
-      data.createAt,
-      { spaceId: content.docSpaceId, fileId: content.docFileId, storePath },
-    );
+      conversationId: data.conversationId,
+      msgId: data.msgId,
+      createdAt: data.createAt,
+      messageType: content.messageType,
+      media: {
+        spaceId: content.docSpaceId,
+        fileId: content.docFileId,
+      },
+      ttlMs: DEFAULT_MEDIA_CONTEXT_TTL_MS,
+      topic: null,
+    });
 
     if (!mediaPath && isDirect && data.senderStaffId) {
       try {
@@ -971,31 +1180,71 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     }
   }
 
+  const quotedRecord = resolveQuotedRecord({
+    storePath: accountStorePath,
+    accountId,
+    conversationId: data.conversationId,
+    quotedRef,
+    log,
+  });
+  const quotedRuntimeContext = resolveQuotedRuntimeContext({
+    storePath: accountStorePath,
+    accountId,
+    conversationId: data.conversationId,
+    quotedRef,
+    firstRecord: quotedRecord,
+    firstPreview:
+      content.quoted?.previewText ||
+      content.quoted?.previewMessageType
+        ? {
+            text: content.quoted.previewText,
+            messageType: content.quoted.previewMessageType,
+            senderId: content.quoted.previewSenderId,
+          }
+        : undefined,
+    log,
+  });
+
   // Try downloading a quoted file from cached downloadCode/spaceId+fileId.
-  const tryDownloadFromCache = async (
-    quotedMsgId: string | undefined,
+  const tryDownloadFromRecord = async (
+    record: {
+      msgId?: string;
+      media?: {
+        downloadCode?: string;
+        spaceId?: string;
+        fileId?: string;
+      };
+    } | null,
   ): Promise<MediaFile | null> => {
-    if (!quotedMsgId) {
-      return null;
-    }
-    const cached = getCachedDownloadCode(accountId, data.conversationId, quotedMsgId, storePath);
-    if (!cached) {
+    if (!record?.media) {
       return null;
     }
     let media: MediaFile | null = null;
-    if (cached.downloadCode) {
-      media = await downloadMedia(dingtalkConfig, cached.downloadCode, log);
+    if (record.media.downloadCode) {
+      media = await downloadMedia(dingtalkConfig, record.media.downloadCode, log);
+      if (media) {
+        log?.debug?.(
+          `[DingTalk][QuotedRef] Recovered quoted media from cached downloadCode ` +
+            `recordMsgId=${record.msgId || "(none)"} scope=${data.conversationId}`,
+        );
+      }
     }
-    if (!media && cached.spaceId && cached.fileId && data.senderStaffId) {
+    if (!media && record.media.spaceId && record.media.fileId && data.senderStaffId) {
       try {
         const unionId = await getUnionIdByStaffId(dingtalkConfig, data.senderStaffId, log);
         media = await downloadGroupFile(
           dingtalkConfig,
-          cached.spaceId,
-          cached.fileId,
+          record.media.spaceId,
+          record.media.fileId,
           unionId,
           log,
         );
+        if (media) {
+          log?.debug?.(
+            `[DingTalk][QuotedRef] Recovered quoted media from cached spaceId/fileId ` +
+              `recordMsgId=${record.msgId || "(none)"} scope=${data.conversationId}`,
+          );
+        }
       } catch (err: any) {
         log?.warn?.(`[DingTalk] spaceId+fileId fallback failed: ${err.message}`);
       }
@@ -1005,15 +1254,23 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
   // Quoted picture: download via existing downloadMedia.
   if (!mediaPath && content.quoted?.mediaDownloadCode && dingtalkConfig.robotCode) {
-    const media = await downloadMedia(dingtalkConfig, content.quoted.mediaDownloadCode, log);
+    const media =
+      (await tryDownloadFromRecord(quotedRecord)) ||
+      (await downloadMedia(dingtalkConfig, content.quoted.mediaDownloadCode, log));
     if (media) {
+      if (!quotedRecord) {
+        log?.debug?.(
+          `[DingTalk][QuotedRef] Recovered quoted image from inbound downloadCode fallback scope=${data.conversationId}`,
+        );
+      }
       mediaPath = media.path;
       mediaType = media.mimeType;
+      attachmentContextMsgId = quotedRecord?.msgId || content.quoted.msgId || data.msgId;
+      attachmentContextCreatedAt = quotedRecord?.createdAt || data.createAt;
+      attachmentContextMessageType = quotedRecord?.messageType || content.quoted.previewMessageType || "picture";
+      attachmentContextFileName = content.quoted.previewFileName;
     } else {
-      content.text = content.text.replace(
-        content.quoted.prefix,
-        "[引用了一张图片，但下载失败]\n\n",
-      );
+      content.text = `[引用了一张图片，但下载失败]\n\n${content.text}`;
     }
   }
 
@@ -1021,11 +1278,15 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   if (!mediaPath && content.quoted?.isQuotedFile) {
     let fileResolved = false;
 
-    // Step 1: Try msgId-based cache (works for both DM and group if bot saw the original message).
-    const cachedMedia = await tryDownloadFromCache(content.quoted.msgId);
+    // Step 1: Prefer quotedRef-backed record lookup, then msgId-based cache.
+    const cachedMedia = await tryDownloadFromRecord(quotedRecord);
     if (cachedMedia) {
       mediaPath = cachedMedia.path;
       mediaType = cachedMedia.mimeType;
+      attachmentContextMsgId = quotedRecord?.msgId || content.quoted.msgId || data.msgId;
+      attachmentContextCreatedAt = quotedRecord?.createdAt || content.quoted.fileCreatedAt || data.createAt;
+      attachmentContextMessageType = quotedRecord?.messageType || "file";
+      attachmentContextFileName = quotedRecord?.attachmentFileName || content.quoted.previewFileName;
       fileResolved = true;
     }
 
@@ -1043,17 +1304,31 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       if (resolved) {
         mediaPath = resolved.media.path;
         mediaType = resolved.media.mimeType;
+        attachmentContextMsgId = content.quoted.msgId || data.msgId;
+        attachmentContextCreatedAt = content.quoted.fileCreatedAt || data.createAt;
+        attachmentContextMessageType = "file";
+        attachmentContextFileName = resolved.name || content.quoted.previewFileName;
         fileResolved = true;
+        log?.debug?.(
+          `[DingTalk][QuotedRef] Recovered quoted file from group file fallback ` +
+            `scope=${data.conversationId} quotedMsgId=${content.quoted.msgId || "(none)"}`,
+        );
         if (content.quoted.msgId) {
-          cacheInboundDownloadCode(
+          upsertInboundMessageContext({
+            storePath: accountStorePath,
             accountId,
-            data.conversationId,
-            content.quoted.msgId,
-            undefined,
-            "file",
-            content.quoted.fileCreatedAt || Date.now(),
-            { storePath, spaceId: resolved.spaceId, fileId: resolved.fileId },
-          );
+            conversationId: data.conversationId,
+            msgId: content.quoted.msgId,
+            createdAt: content.quoted.fileCreatedAt || Date.now(),
+            messageType: "file",
+            media: {
+              spaceId: resolved.spaceId,
+              fileId: resolved.fileId,
+            },
+            attachmentFileName: resolved.name,
+            ttlMs: DEFAULT_MEDIA_CONTEXT_TTL_MS,
+            topic: null,
+          });
         }
       }
     }
@@ -1065,7 +1340,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       const hint = isDirect
         ? "[引用了一个文件，内容无法自动获取，请直接发送该文件]\n\n"
         : "[引用了一个文件，但无法获取内容]\n\n";
-      content.text = content.text.replace(content.quoted.prefix, hint);
+      content.text = `${hint}${content.text}`;
     }
   }
 
@@ -1077,12 +1352,16 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   if (!mediaPath && content.quoted?.isQuotedDocCard) {
     let docResolved = false;
 
-    const cachedDocMedia = await tryDownloadFromCache(content.quoted.msgId);
+    const cachedDocMedia = await tryDownloadFromRecord(quotedRecord);
     if (cachedDocMedia) {
       mediaPath = cachedDocMedia.path;
       mediaType = cachedDocMedia.mimeType;
+      attachmentContextMsgId = quotedRecord?.msgId || content.quoted.msgId || data.msgId;
+      attachmentContextCreatedAt = quotedRecord?.createdAt || content.quoted.fileCreatedAt || data.createAt;
+      attachmentContextMessageType =
+        quotedRecord?.messageType || content.quoted.previewMessageType || "interactiveCardFile";
+      attachmentContextFileName = quotedRecord?.attachmentFileName || content.quoted.previewFileName;
       docResolved = true;
-      content.text = content.text.replace(content.quoted.prefix, "[引用了钉钉文档]\n\n");
     }
 
     if (!docResolved && !isDirect && content.quoted.fileCreatedAt) {
@@ -1098,18 +1377,31 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       if (resolved) {
         mediaPath = resolved.media.path;
         mediaType = resolved.media.mimeType;
+        attachmentContextMsgId = content.quoted.msgId || data.msgId;
+        attachmentContextCreatedAt = content.quoted.fileCreatedAt || data.createAt;
+        attachmentContextMessageType = "interactiveCardFile";
+        attachmentContextFileName = resolved.name || content.quoted.previewFileName;
         docResolved = true;
-        content.text = content.text.replace(content.quoted.prefix, "[引用了钉钉文档]\n\n");
+        log?.debug?.(
+          `[DingTalk][QuotedRef] Recovered quoted doc card from group file fallback ` +
+            `scope=${data.conversationId} quotedMsgId=${content.quoted.msgId || "(none)"}`,
+        );
         if (content.quoted.msgId) {
-          cacheInboundDownloadCode(
+          upsertInboundMessageContext({
+            storePath: accountStorePath,
             accountId,
-            data.conversationId,
-            content.quoted.msgId,
-            undefined,
-            "interactiveCardFile",
-            content.quoted.fileCreatedAt || Date.now(),
-            { storePath, spaceId: resolved.spaceId, fileId: resolved.fileId },
-          );
+            conversationId: data.conversationId,
+            msgId: content.quoted.msgId,
+            createdAt: content.quoted.fileCreatedAt || Date.now(),
+            messageType: "interactiveCardFile",
+            media: {
+              spaceId: resolved.spaceId,
+              fileId: resolved.fileId,
+            },
+            attachmentFileName: resolved.name,
+            ttlMs: DEFAULT_MEDIA_CONTEXT_TTL_MS,
+            topic: null,
+          });
         }
       }
     }
@@ -1121,43 +1413,32 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       const hint = isDirect
         ? "[引用了钉钉文档，内容无法自动获取，请直接发送该文档]\n\n"
         : "[引用了钉钉文档，但无法获取内容]\n\n";
-      content.text = content.text.replace(content.quoted.prefix, hint);
-    }
-  }
-
-  // Quoted AI card: prefer deterministic processQueryKey lookup, and only
-  // fall back to the legacy createdAt matcher when the callback omits that key.
-  if (content.quoted?.isQuotedCard) {
-    const cardContent = content.quoted.processQueryKey
-      ? getCardContentByProcessQueryKey(
-          accountId,
-          to,
-          content.quoted.processQueryKey,
-          accountStorePath,
-        )
-      : content.quoted.cardCreatedAt
-        ? findCardContent(accountId, to, content.quoted.cardCreatedAt, accountStorePath)
-        : null;
-    if (cardContent) {
-      const preview = cardContent.length > 50 ? cardContent.slice(0, 50) + "..." : cardContent;
-      content.text = content.text.replace(
-        content.quoted.prefix,
-        `[引用机器人回复: "${preview}"]\n\n`,
-      );
+      content.text = `${hint}${content.text}`;
     }
-    // Card cache miss: prefix already contains "[引用了机器人的回复]", keep as-is.
   }
 
-  let attachmentExtractedText: string | undefined;
   if (mediaPath) {
     try {
       const extracted = await extractAttachmentText({
         path: mediaPath,
         mimeType: mediaType,
-        fileName: data.content?.fileName,
+        fileName: attachmentContextFileName || data.content?.fileName,
       });
       if (extracted?.text) {
-        attachmentExtractedText = `${ATTACHMENT_TEXT_PREFIX}\n${extracted.text}`;
+        upsertInboundMessageContext({
+          storePath: accountStorePath,
+          accountId,
+          conversationId: data.conversationId,
+          msgId: attachmentContextMsgId,
+          createdAt: attachmentContextCreatedAt,
+          messageType: attachmentContextMessageType,
+          attachmentText: extracted.text,
+          attachmentTextSource: extracted.sourceType,
+          attachmentTextTruncated: extracted.truncated,
+          attachmentFileName: attachmentContextFileName,
+          ttlMs: ttlDaysToMs(journalTTLDays),
+          topic: null,
+        });
       }
     } catch (err: any) {
       log?.warn?.(`[DingTalk] Failed to extract attachment text: ${err.message}`);
@@ -1168,7 +1449,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     mediaPath && /<media:[^>]+>/.test(content.text)
       ? `${content.text}\n[media_path: ${mediaPath}]\n[media_type: ${mediaType || "unknown"}]`
       : content.text;
-  const inboundText = attachmentExtractedText ? `${inboundBody}\n\n${attachmentExtractedText}` : inboundBody;
+  const inboundText = inboundBody;
   const learningEnabled = isFeedbackLearningEnabled(dingtalkConfig);
   const learningContextBlock = buildLearningContextBlock({
     enabled: learningEnabled,
@@ -1219,6 +1500,15 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     Body: body,
     RawBody: inboundText,
     CommandBody: inboundText,
+    QuotedRef: quotedRef,
+    QuotedRefJson: quotedRef ? JSON.stringify(quotedRef) : undefined,
+    ReplyToId: quotedRuntimeContext?.replyToId,
+    ReplyToBody: quotedRuntimeContext?.replyToBody,
+    ReplyToSender: quotedRuntimeContext?.replyToSender,
+    ReplyToIsQuote: quotedRuntimeContext?.replyToIsQuote,
+    UntrustedContext: quotedRuntimeContext?.untrustedContext
+      ? [quotedRuntimeContext.untrustedContext]
+      : undefined,
     From: to,
     To: to,
     SessionKey: route.sessionKey,
@@ -1247,7 +1537,27 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     storePath,
     sessionKey: ctx.SessionKey || route.sessionKey,
     ctx,
-    updateLastRoute: { sessionKey: route.mainSessionKey, channel: "dingtalk", to, accountId },
+    updateLastRoute: (() => {
+      if (!isDirect) {
+        return undefined;
+      }
+      const pinnedMainDmOwner = resolvePinnedMainDmOwner({
+        dmScope: cfg.session?.dmScope,
+        allowFrom: dingtalkConfig.allowFrom,
+      });
+      const senderRecipient = (senderOriginalId || senderId || "").trim().toLowerCase();
+      if (
+        pinnedMainDmOwner
+        && senderRecipient
+        && pinnedMainDmOwner.trim().toLowerCase() !== senderRecipient
+      ) {
+        log?.debug?.(
+          `[DingTalk] Skipping main-session last route update for ${senderRecipient} (pinned owner ${pinnedMainDmOwner})`,
+        );
+        return undefined;
+      }
+      return { sessionKey: route.mainSessionKey, channel: "dingtalk", to, accountId };
+    })(),
     onRecordError: (err: unknown) => {
       log?.error?.(`[DingTalk] Failed to record inbound session: ${String(err)}`);
     },
@@ -1263,8 +1573,13 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
           accountId,
           agentId: route.agentId,
         });
+  const normalizedAckReaction = ackReaction === "off" ? "" : ackReaction;
   const resolvedAckReaction =
-    ackReaction === "emoji" ? classifyAckReactionEmoji(content.text).emoji : ackReaction;
+    normalizedAckReaction === "kaomoji"
+      ? classifyAckReactionEmoji(content.text).emoji
+      : normalizedAckReaction === "emoji"
+        ? "🤔思考中"
+        : normalizedAckReaction;
   const shouldAttachAckReaction = Boolean(resolvedAckReaction);
   let ackReactionAttached = false;
   let ackReactionAttachedAt = 0;
@@ -1281,310 +1596,169 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     );
     if (ackReactionAttached) {
       ackReactionAttachedAt = Date.now();
+      log?.debug?.(
+        `[DingTalk] Initial ack reaction attached mode=${normalizedAckReaction || "off"} reaction=${resolvedAckReaction}`,
+      );
+    }
+  }
+
+  // ---- Shared media delivery helper ----
+  async function deliverMediaAttachments(urls: string[]) {
+    for (const rawMediaUrl of urls) {
+      const preparedMedia = await prepareMediaInput(
+        rawMediaUrl,
+        log,
+        dingtalkConfig.mediaUrlAllowlist,
+      );
+      try {
+        const actualMediaPath = preparedMedia.path;
+        const outMediaType = resolveOutboundMediaType({
+          mediaPath: actualMediaPath,
+          asVoice: false,
+        });
+        if (sessionWebhook) {
+          const sendResult = await sendMessage(dingtalkConfig, to, "", {
+            sessionWebhook,
+            mediaPath: actualMediaPath,
+            mediaType: outMediaType,
+            log,
+            accountId,
+            storePath: accountStorePath,
+            conversationId: groupId,
+            quotedRef: replyQuotedRef,
+          });
+          if (!sendResult.ok) {
+            throw new Error(sendResult.error || "Media reply send failed");
+          }
+        } else {
+          const sendResult = await sendProactiveMedia(
+            dingtalkConfig,
+            to,
+            actualMediaPath,
+            outMediaType,
+            {
+              accountId,
+              log,
+              storePath: accountStorePath,
+              conversationId: groupId,
+              quotedRef: replyQuotedRef,
+            },
+          );
+          if (!sendResult.ok) {
+            throw new Error(sendResult.error || "Media reply send failed");
+          }
+        }
+      } finally {
+        await preparedMedia.cleanup?.();
+      }
     }
   }
 
+  // ---- Extract mediaUrls from runtime payload ----
+  function extractMediaUrls(payload: ReplyStreamPayload): string[] {
+    const richPayload = payload as typeof payload & {
+      mediaUrl?: string;
+      mediaUrls?: string[];
+    };
+    return Array.isArray(richPayload.mediaUrls)
+      ? richPayload.mediaUrls.filter((entry: unknown) => typeof entry === "string" && entry.trim())
+      : richPayload.mediaUrl &&
+          typeof richPayload.mediaUrl === "string" &&
+          richPayload.mediaUrl.trim()
+        ? [richPayload.mediaUrl]
+        : [];
+  }
+
   // Serialize dispatchReply + card finalize per session to prevent the runtime
   // from receiving concurrent dispatch calls on the same session key, which
   // causes empty replies for all but the first caller.
+  // Each sub-agent call acquires its own lock since sub-agent sessions have
+  // different session keys (different agentId), so no deadlock risk.
+  const shouldTrackDynamicAckReaction =
+    (normalizedAckReaction === "emoji" || normalizedAckReaction === "kaomoji")
+    && shouldAttachAckReaction;
+  const runtimeEvents = (rt as typeof rt & {
+    events?: {
+      onAgentEvent?: (listener: (event: unknown) => void) => (() => void);
+    };
+  }).events;
   const releaseSessionLock = await acquireSessionLock(route.sessionKey);
+  const dynamicAckReactionController = createDynamicAckReactionController({
+    enabled: shouldTrackDynamicAckReaction,
+    initialReaction: resolvedAckReaction || "",
+    initialAttached: ackReactionAttached,
+    initialAttachedAt: ackReactionAttachedAt,
+    dingtalkConfig,
+    msgId: data.msgId,
+    conversationId: groupId,
+    sessionKey: route.sessionKey,
+    log,
+    runtimeEvents,
+    onReactionDisposed: () => {
+      ackReactionAttached = false;
+    },
+  });
   try {
     if (!ackReactionAttached && shouldAttachAckReaction) {
       log?.debug?.("[DingTalk] Native ack reaction unavailable; skipping fallback.");
     }
 
-    const controller = useCardMode && currentAICard
-      ? createCardDraftController({ card: currentAICard, log })
-      : undefined;
-    let cardFinalized = false;
-    let finalTextForFallback: string | undefined;
+    // ---- Create reply strategy (card or markdown) ----
+    const strategy = createReplyStrategy({
+      config: dingtalkConfig,
+      card: currentAICard,
+      useCardMode: useCardMode && !!currentAICard,
+      to,
+      sessionWebhook,
+      senderId,
+      isDirect,
+      accountId,
+      storePath: accountStorePath,
+      groupId,
+      log,
+      replyQuotedRef,
+      deliverMedia: deliverMediaAttachments,
+    });
 
     try {
       await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
         ctx,
         cfg,
         dispatcherOptions: {
-          responsePrefix: "",
+          responsePrefix: subAgentOptions?.responsePrefix || "",
           deliver: async (payload: ReplyStreamPayload, info?: ReplyChunkInfo) => {
-            async function deliverMediaAttachments(urls: string[]) {
-              for (const rawMediaUrl of urls) {
-                const preparedMedia = await prepareMediaInput(
-                  rawMediaUrl,
-                  log,
-                  dingtalkConfig.mediaUrlAllowlist,
-                );
-                try {
-                  const actualMediaPath = preparedMedia.path;
-                  const mediaType = resolveOutboundMediaType({
-                    mediaPath: actualMediaPath,
-                    asVoice: false,
-                  });
-                  if (sessionWebhook) {
-                    await sendBySession(dingtalkConfig, sessionWebhook, "", {
-                      mediaPath: actualMediaPath,
-                      mediaType,
-                      log,
-                    });
-                  } else {
-                    const sendResult = await sendProactiveMedia(
-                      dingtalkConfig,
-                      to,
-                      actualMediaPath,
-                      mediaType,
-                      {
-                        accountId,
-                        log,
-                      },
-                    );
-                    if (!sendResult.ok) {
-                      throw new Error(sendResult.error || "Media reply send failed");
-                    }
-                  }
-                } finally {
-                  await preparedMedia.cleanup?.();
-                }
-              }
-            }
-
             try {
-              const richPayload = payload as typeof payload & {
-                mediaUrl?: string;
-                mediaUrls?: string[];
-              };
-              const textToSend = payload.text;
-              const mediaUrls = Array.isArray(richPayload.mediaUrls)
-                ? richPayload.mediaUrls.filter((entry: unknown) => typeof entry === "string" && entry.trim())
-                : richPayload.mediaUrl && typeof richPayload.mediaUrl === "string" && richPayload.mediaUrl.trim()
-                  ? [richPayload.mediaUrl]
-                  : [];
-
-              // In card mode, deliver(final) must always reach finalize even with empty text
-              // (e.g. bot sent a file via tool with no accompanying text).
-              if ((typeof textToSend !== "string" || textToSend.length === 0) && mediaUrls.length === 0) {
-                if (useCardMode && currentAICard && info?.kind === "final") {
-                  // fall through to card finalize below
-                } else {
-                  return;
-                }
-              }
-
-              // ---- card mode: final ----
-              // Do NOT finalize or stop the controller here — runtime calls
-              // deliver(final) once per assistant turn, so there may be more
-              // turns coming after tool calls. Finalization is deferred to
-              // step 5 (post-dispatch) where the full accumulated content
-              // is available.
-              if (useCardMode && currentAICard && info?.kind === "final") {
-                log?.info?.(
-                  `[DingTalk][Finalize] deliver(final) received — cardState=${currentAICard.state} ` +
-                  `textLen=${typeof textToSend === "string" ? textToSend.length : "null"} ` +
-                  `mediaUrls=${mediaUrls.length} ` +
-                  `lastAnswer="${(controller?.getLastAnswerContent() ?? "").slice(0, 80)}" ` +
-                  `lastContent="${(controller?.getLastContent() ?? "").slice(0, 80)}"`,
-                );
-                if (mediaUrls.length > 0) {
-                  await deliverMediaAttachments(mediaUrls);
-                }
-                const rawFinalText = typeof textToSend === "string" ? textToSend : "";
-                if (rawFinalText) {
-                  finalTextForFallback = rawFinalText;
-                }
-                return;
-              }
-
-              // ---- card mode: tool ----
-              if (useCardMode && currentAICard && info?.kind === "tool") {
-                if (controller!.isFailed() || isCardInTerminalState(currentAICard.state)) {
-                  log?.debug?.("[DingTalk] Card failed, skipping tool result (will send full reply on final)");
-                  return;
-                }
-                await controller!.flush();
-                await controller!.waitForInFlight();
-                log?.info?.(
-                  `[DingTalk] Tool result received, streaming to AI Card: ${(textToSend ?? "").slice(0, 100)}`,
-                );
-                const toolText = typeof textToSend === "string" ? formatContentForCard(textToSend, "tool") : "";
-                if (toolText) {
-                  const sendResult = await sendMessage(dingtalkConfig, to, toolText, {
-                    sessionWebhook,
-                    atUserId: !isDirect ? senderId : null,
-                    log,
-                    card: currentAICard,
-                    accountId,
-                    storePath,
-                    conversationId: groupId,
-                    cardUpdateMode: "append",
-                  });
-                  if (!sendResult.ok) {
-                    throw new Error(sendResult.error || "Tool stream send failed");
-                  }
-                }
-                return;
-              }
-
-              // ---- media delivery (all modes) ----
-              if (mediaUrls.length > 0) {
-                await deliverMediaAttachments(mediaUrls);
-              }
-
-              // ---- non-card mode (markdown/text) ----
-              if (!useCardMode || !currentAICard) {
-                if (typeof textToSend !== "string" || textToSend.length === 0) {
-                  return;
-                }
-                const sendResult = await sendMessage(dingtalkConfig, to, textToSend, {
-                  sessionWebhook,
-                  atUserId: !isDirect ? senderId : null,
-                  log,
-                  accountId,
-                  storePath,
-                  conversationId: groupId,
-                });
-                if (!sendResult.ok) {
-                  throw new Error(sendResult.error || "Reply send failed");
-                }
-              }
-            } catch (err: any) {
-              log?.error?.(`[DingTalk] Reply failed: ${err.message}`);
-              if (err?.response?.data !== undefined) {
-                log?.error?.(formatDingTalkErrorPayloadLog("inbound.replyDeliver", err.response.data));
+              const mediaUrls = extractMediaUrls(payload);
+              await strategy.deliver({
+                text: payload.text,
+                mediaUrls,
+                kind: (info?.kind as DeliverPayload["kind"]) || "block",
+              });
+            } catch (err: unknown) {
+              log?.error?.(`[DingTalk] Reply failed: ${getErrorMessage(err)}`);
+              const responseData = getErrorResponseData(err);
+              if (responseData !== undefined) {
+                log?.error?.(formatDingTalkErrorPayloadLog("inbound.replyDeliver", responseData));
               }
               throw err;
             }
           },
         },
-        replyOptions: {
-          disableBlockStreaming: dingtalkConfig.cardRealTimeStream && controller ? true : undefined,
-
-          onAssistantMessageStart: controller
-            ? () => { controller.notifyNewAssistantTurn(); }
-            : undefined,
-
-          onPartialReply: dingtalkConfig.cardRealTimeStream && controller
-            ? (payload: ReplyStreamPayload) => {
-                if (payload.text) {
-                  controller.updateAnswer(payload.text);
-                }
-              }
-            : undefined,
-
-          onReasoningStream: controller
-            ? (payload: ReplyStreamPayload) => {
-                if (payload.text) {
-                  controller.updateReasoning(payload.text);
-                }
-              }
-            : undefined,
-        },
+        replyOptions: strategy.getReplyOptions(),
       });
-    } catch (dispatchErr: any) {
-      if (useCardMode && currentAICard && !isCardInTerminalState(currentAICard.state)) {
-        controller!.stop();
-        await controller!.waitForInFlight();
-        if (!cardFinalized) {
-          try {
-            await finishAICard(currentAICard, "❌ 处理失败", log);
-          } catch (cardCloseErr: any) {
-            log?.debug?.(`[DingTalk] Failed to finalize card after dispatch error: ${cardCloseErr.message}`);
-            currentAICard.state = AICardStatus.FAILED;
-            currentAICard.lastUpdated = Date.now();
-          }
-        }
-      }
+    } catch (dispatchErr: unknown) {
+      const error = dispatchErr instanceof Error ? dispatchErr : new Error(getErrorMessage(dispatchErr));
+      await strategy.abort(error);
       throw dispatchErr;
     }
 
-    // 5) Post-dispatch card finalization.
-    // This is the sole finalize path — deliver(final) defers here because
-    // runtime may call deliver(final) multiple times (once per assistant turn).
-    log?.info?.(
-      `[DingTalk][Finalize] Step 5 entry — useCardMode=${useCardMode} ` +
-      `hasCard=${!!currentAICard} cardFinalized=${cardFinalized} ` +
-      `cardState=${currentAICard?.state ?? "N/A"} ` +
-      `controllerFailed=${controller?.isFailed() ?? "N/A"} ` +
-      `finalTextForFallback="${(finalTextForFallback ?? "").slice(0, 80)}" ` +
-      `lastAnswer="${(controller?.getLastAnswerContent() ?? "").slice(0, 80)}" ` +
-      `lastContent="${(controller?.getLastContent() ?? "").slice(0, 80)}"`,
-    );
-    if (useCardMode && currentAICard && !cardFinalized) {
-      try {
-        if (currentAICard.state === AICardStatus.FINISHED) {
-          log?.info?.(
-            `[DingTalk][Finalize] Skipping — card already FINISHED`,
-          );
-          return;
-        }
-
-        if (currentAICard.state === AICardStatus.FAILED || controller!.isFailed()) {
-          const fallbackText = finalTextForFallback
-            || controller!.getLastAnswerContent()
-            || controller!.getLastContent()
-            || currentAICard.lastStreamedContent;
-          if (fallbackText) {
-            log?.debug?.("[DingTalk] Card failed during streaming, sending markdown fallback");
-            const sendResult = await sendMessage(dingtalkConfig, to, fallbackText, {
-              sessionWebhook,
-              atUserId: !isDirect ? senderId : null,
-              log,
-              accountId,
-              storePath,
-              conversationId: groupId,
-            });
-            if (!sendResult.ok) {
-              throw new Error(sendResult.error || "Markdown fallback send failed after card failure — user received no reply");
-            }
-          } else {
-            log?.debug?.("[DingTalk] Card failed but no content to fallback with");
-          }
-          return;
-        }
-
-        await controller!.flush();
-        await controller!.waitForInFlight();
-        controller!.stop();
-        const finalText = controller!.getLastAnswerContent()
-          || finalTextForFallback
-          || "✅ Done";
-        log?.info?.(
-          `[DingTalk][Finalize] Calling finishAICard — finalTextLen=${finalText.length} ` +
-          `source=${controller!.getLastAnswerContent() ? "lastAnswerContent" : finalTextForFallback ? "finalTextForFallback" : "fallbackDone"} ` +
-          `preview="${finalText.slice(0, 120)}"`,
-        );
-        await finishAICard(currentAICard, finalText, log);
-      } catch (err: any) {
-        log?.debug?.(`[DingTalk] AI Card finalization failed: ${err.message}`);
-        if (err?.response?.data !== undefined) {
-          log?.debug?.(formatDingTalkErrorPayloadLog("inbound.cardFinalize", err.response.data));
-        }
-        try {
-          if (currentAICard.state !== AICardStatus.FINISHED) {
-            currentAICard.state = AICardStatus.FAILED;
-            currentAICard.lastUpdated = Date.now();
-          }
-        } catch (stateErr: any) {
-          log?.debug?.(`[DingTalk] Failed to update card state to FAILED: ${stateErr.message}`);
-        }
-      }
-    }
+    await strategy.finalize();
   } finally {
+    await waitForDynamicAckDispose({
+      dispose: () => dynamicAckReactionController.dispose(MIN_THINKING_REACTION_VISIBLE_MS),
+      log,
+      sessionKey: route.sessionKey,
+    });
     releaseSessionLock();
-    if (ackReactionAttached) {
-      void (async () => {
-        const elapsedMs = ackReactionAttachedAt > 0 ? Date.now() - ackReactionAttachedAt : 0;
-        const remainingVisibleMs = MIN_THINKING_REACTION_VISIBLE_MS - elapsedMs;
-        if (remainingVisibleMs > 0) {
-          await new Promise(resolve => setTimeout(resolve, remainingVisibleMs));
-        }
-        await recallNativeAckReactionWithRetry(
-          dingtalkConfig,
-          {
-            msgId: data.msgId,
-            conversationId: groupId,
-            reactionName: resolvedAckReaction,
-          },
-          log,
-        );
-      })();
-    }
   }
 }