@soimy/dingtalk 3.1.4 → 3.3.0

package/src/inbound-handler.ts

@@ -1,32 +1,86 @@
 import axios from "axios";
 import { normalizeAllowFrom, isSenderAllowed, isSenderGroupAllowed } from "./access-control";
+import { extractAttachmentText } from "./attachment-text-extractor";
 import { getAccessToken } from "./auth";
 import {
-  cleanupCardCache,
   createAICard,
+  findCardContent,
   finishAICard,
   formatContentForCard,
-  getActiveCardIdByTarget,
-  getCardById,
+  getCardContentByProcessQueryKey,
   isCardInTerminalState,
-  streamAICard,
 } from "./card-service";
-import { resolveGroupConfig } from "./config";
+import { classifyAckReactionEmoji } from "./ack-reaction-classifier";
+import { resolveAckReactionSetting, resolveGroupConfig } from "./config";
 import { formatGroupMembers, noteGroupMember } from "./group-members-store";
 import { setCurrentLogger } from "./logger-context";
+import {
+  formatLearnAppliedReply,
+  formatLearnCommandHelp,
+  formatLearnDeletedReply,
+  formatLearnDisabledReply,
+  formatLearnListReply,
+  formatOwnerOnlyDeniedReply,
+  formatOwnerStatusReply,
+  formatTargetSetSavedReply,
+  formatWhereAmIReply,
+  formatWhoAmIReply,
+  isLearningOwner,
+  parseLearnCommand,
+} from "./learning-command-service";
 import { extractMessageContent } from "./message-utils";
+import { prepareMediaInput, resolveOutboundMediaType } from "./media-utils";
 import { registerPeerId } from "./peer-id-registry";
 import {
   clearProactiveRiskObservationsForTest,
   getProactiveRiskObservationForAny,
 } from "./proactive-risk-registry";
+import {
+  appendQuoteJournalEntry,
+  DEFAULT_JOURNAL_TTL_DAYS,
+  resolveQuotedMessageById,
+} from "./quote-journal";
 import { getDingTalkRuntime } from "./runtime";
-import { sendBySession, sendMessage } from "./send-service";
+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,
+  formatSessionAliasReply,
+  formatSessionAliasSetReply,
+  formatSessionAliasUnboundReply,
+  formatSessionAliasValidationErrorReply,
+  parseSessionCommand,
+  validateSessionAlias,
+} from "./session-command-service";
+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";
 
 const DEFAULT_PROACTIVE_HINT_COOLDOWN_HOURS = 24;
+const MIN_THINKING_REACTION_VISIBLE_MS = 1200;
+const ATTACHMENT_TEXT_PREFIX = "[附件内容摘录]";
 const proactiveHintLastSentAt = new Map<string, number>();
 
 export function resetProactivePermissionHintStateForTest(): void {
@@ -38,6 +92,7 @@ function shouldSendProactivePermissionHint(params: {
   isDirect: boolean;
   accountId: string;
   senderId: string;
+  senderOriginalId?: string;
   senderStaffId?: string;
   config: DingTalkConfig;
   nowMs: number;
@@ -56,11 +111,14 @@ function shouldSendProactivePermissionHint(params: {
     return false;
   }
 
-  const riskObservation = getProactiveRiskObservationForAny(
-    params.accountId,
-    [params.senderId, params.senderStaffId],
-    params.nowMs,
-  );
+  const riskTargets = [params.senderId, params.senderOriginalId, params.senderStaffId]
+    .map((id) => (id || "").trim())
+    .filter((id, index, arr) => Boolean(id) && arr.indexOf(id) === index);
+  if (riskTargets.length === 0) {
+    return false;
+  }
+
+  const riskObservation = getProactiveRiskObservationForAny(params.accountId, riskTargets, params.nowMs);
   if (!riskObservation || riskObservation.source !== "proactive-api") {
     return false;
   }
@@ -80,14 +138,43 @@ function shouldSendProactivePermissionHint(params: {
   return true;
 }
 
-function isUnhandledStopReasonText(value: string): boolean {
-  const normalized = value.trim();
-  if (!normalized) {
-    return false;
-  }
-  return /^Unhandled stop reason:\s*[A-Za-z0-9_-]+/i.test(normalized);
+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, " ")
+    .replace(/\s+/g, " ")
+    .trim();
 }
 
+function buildGroupTurnContextPrompt(params: {
+  conversationId: string;
+  senderDingtalkId: string;
+  senderName?: string;
+}): string {
+  const sanitizedSenderName = sanitizeGroupPromptName(params.senderName) || "Unknown";
+  return [
+    "Current DingTalk group turn context:",
+    `- conversationId: ${params.conversationId}`,
+    `- senderDingtalkId: ${params.senderDingtalkId}`,
+    `- senderName: ${sanitizedSenderName}`,
+    "Treat senderDingtalkId and senderName as the authoritative sender for this turn. Do not guess the current sender from GroupMembers.",
+  ].join("\n");
+}
+
+type ReplyStreamPayload = {
+  text?: string;
+};
+
+type ReplyChunkInfo = {
+  kind?: string;
+};
+
 /**
  * Download DingTalk media file via runtime media service (sandbox-compatible).
  * Files are stored in the global media inbound directory.
@@ -148,8 +235,11 @@ export async function downloadMedia(
     const contentType = mediaResponse.headers["content-type"] || "application/octet-stream";
     const buffer = Buffer.from(mediaResponse.data as ArrayBuffer);
 
-    // Keep inbound media handling consistent with other channels.
-    const saved = await rt.channel.media.saveMediaBuffer(buffer, contentType, "inbound");
+    const maxBytes =
+      config.mediaMaxMb && config.mediaMaxMb > 0 ? config.mediaMaxMb * 1024 * 1024 : undefined;
+    const saved = maxBytes
+      ? await rt.channel.media.saveMediaBuffer(buffer, contentType, "inbound", maxBytes)
+      : await rt.channel.media.saveMediaBuffer(buffer, contentType, "inbound");
     log?.debug?.(`[DingTalk] Media saved: ${saved.path}`);
     return { path: saved.path, mimeType: saved.contentType ?? contentType };
   } catch (err: any) {
@@ -183,10 +273,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   // Save logger globally so shared services can log consistently without threading log everywhere.
   setCurrentLogger(log);
 
-  log?.debug?.("[DingTalk] Full Inbound Data:", JSON.stringify(maskSensitiveData(data)));
-
-  // Clean up old terminal cards opportunistically on inbound traffic.
-  cleanupCardCache();
+  log?.debug?.("[DingTalk] Full Inbound Data: " + JSON.stringify(maskSensitiveData(data)));
 
   // 1) Ignore self messages from bot.
   if (data.senderId === data.chatbotUserId || data.senderStaffId === data.chatbotUserId) {
@@ -194,13 +281,15 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     return;
   }
 
-  const content = extractMessageContent(data);
-  if (!content.text) {
+  const extractedContent = extractMessageContent(data);
+  if (!extractedContent.text) {
     return;
   }
 
   const isDirect = data.conversationType === "1";
-  const senderId = data.senderStaffId || data.senderId;
+  const senderOriginalId = (data.senderId || "").trim();
+  const senderStaffId = (data.senderStaffId || "").trim();
+  const senderId = senderStaffId || senderOriginalId;
   const senderName = data.senderNick || "Unknown";
   const groupId = data.conversationId;
   const groupName = data.conversationTitle || "Group";
@@ -215,7 +304,8 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       isDirect,
       accountId,
       senderId,
-      senderStaffId: data.senderStaffId,
+      senderOriginalId,
+      senderStaffId,
       config: dingtalkConfig,
       nowMs: Date.now(),
     })
@@ -314,11 +404,29 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     }
   }
 
+  const accountStorePath = rt.channel.session.resolveStorePath(cfg.session?.store, {
+    agentId: accountId,
+  });
+  const currentSessionSourceKind = isDirect ? "direct" : "group";
+  const currentSessionSourceId = isDirect ? senderId : groupId;
+  const peerIdOverride = getSessionPeerOverride({
+    storePath: accountStorePath,
+    accountId,
+    sourceKind: currentSessionSourceKind,
+    sourceId: currentSessionSourceId,
+  });
+  const sessionPeer = resolveDingTalkSessionPeer({
+    isDirect,
+    senderId,
+    conversationId: groupId,
+    peerIdOverride,
+    config: dingtalkConfig,
+  });
   const route = rt.channel.routing.resolveAgentRoute({
     cfg,
     channel: "dingtalk",
     accountId,
-    peer: { kind: isDirect ? "direct" : "group", id: isDirect ? senderId : groupId },
+    peer: { kind: sessionPeer.kind, id: sessionPeer.peerId },
   });
 
   // Route resolved before media download for session context and routing metadata.
@@ -326,6 +434,482 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     agentId: route.agentId,
   });
 
+  const to = isDirect ? senderId : groupId;
+  const parsedLearnCommand = parseLearnCommand(extractedContent.text);
+  const parsedSessionCommand = parseSessionCommand(extractedContent.text);
+  const isOwner = isLearningOwner({
+    cfg,
+    config: dingtalkConfig,
+    senderId,
+    rawSenderId: data.senderId,
+  });
+  if (isDirect && parsedLearnCommand.scope === "whoami") {
+    await sendBySession(
+      dingtalkConfig,
+      sessionWebhook,
+      formatWhoAmIReply({
+        senderId,
+        rawSenderId: data.senderId,
+        senderStaffId: data.senderStaffId,
+        isOwner,
+      }),
+      { log },
+    );
+    return;
+  }
+  if (parsedLearnCommand.scope === "whereami") {
+    await sendBySession(
+      dingtalkConfig,
+      sessionWebhook,
+      formatWhereAmIReply({
+        conversationId: data.conversationId,
+        conversationType: isDirect ? "dm" : "group",
+        peerId: sessionPeer.peerId,
+      }),
+      { log },
+    );
+    return;
+  }
+  if (isDirect && parsedLearnCommand.scope === "owner-status") {
+    await sendBySession(
+      dingtalkConfig,
+      sessionWebhook,
+      formatOwnerStatusReply({
+        senderId,
+        rawSenderId: data.senderId,
+        isOwner,
+      }),
+      { log },
+    );
+    return;
+  }
+  if (parsedLearnCommand.scope === "help") {
+    await sendBySession(dingtalkConfig, sessionWebhook, formatLearnCommandHelp(), { log });
+    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
+  ) {
+    await sendBySession(dingtalkConfig, sessionWebhook, formatOwnerOnlyDeniedReply(), { log });
+    return;
+  }
+  if (isOwner) {
+    if (parsedSessionCommand.scope === "session-alias-show") {
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatSessionAliasReply({
+          sourceKind: currentSessionSourceKind,
+          sourceId: currentSessionSourceId,
+          peerId: sessionPeer.peerId,
+          aliasSource: peerIdOverride ? "override" : "default",
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedSessionCommand.scope === "session-alias-set" && parsedSessionCommand.peerId) {
+      const aliasValidationError = validateSessionAlias(parsedSessionCommand.peerId);
+      if (aliasValidationError) {
+        await sendBySession(
+          dingtalkConfig,
+          sessionWebhook,
+          formatSessionAliasValidationErrorReply(aliasValidationError),
+          { log },
+        );
+        return;
+      }
+      setSessionPeerOverride({
+        storePath: accountStorePath,
+        accountId,
+        sourceKind: currentSessionSourceKind,
+        sourceId: currentSessionSourceId,
+        peerId: parsedSessionCommand.peerId,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatSessionAliasSetReply({
+          sourceKind: currentSessionSourceKind,
+          sourceId: currentSessionSourceId,
+          peerId: parsedSessionCommand.peerId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedSessionCommand.scope === "session-alias-clear") {
+      clearSessionPeerOverride({
+        storePath: accountStorePath,
+        accountId,
+        sourceKind: currentSessionSourceKind,
+        sourceId: currentSessionSourceId,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatSessionAliasClearedReply({
+          sourceKind: currentSessionSourceKind,
+          sourceId: currentSessionSourceId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedSessionCommand.scope === "session-alias-bind"
+      && parsedSessionCommand.sourceKind
+      && parsedSessionCommand.sourceId
+      && parsedSessionCommand.peerId) {
+      const aliasValidationError = validateSessionAlias(parsedSessionCommand.peerId);
+      if (aliasValidationError) {
+        await sendBySession(
+          dingtalkConfig,
+          sessionWebhook,
+          formatSessionAliasValidationErrorReply(aliasValidationError),
+          { log },
+        );
+        return;
+      }
+      setSessionPeerOverride({
+        storePath: accountStorePath,
+        accountId,
+        sourceKind: parsedSessionCommand.sourceKind,
+        sourceId: parsedSessionCommand.sourceId,
+        peerId: parsedSessionCommand.peerId,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatSessionAliasBoundReply({
+          sourceKind: parsedSessionCommand.sourceKind,
+          sourceId: parsedSessionCommand.sourceId,
+          peerId: parsedSessionCommand.peerId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedSessionCommand.scope === "session-alias-unbind"
+      && parsedSessionCommand.sourceKind
+      && parsedSessionCommand.sourceId) {
+      const existed = clearSessionPeerOverride({
+        storePath: accountStorePath,
+        accountId,
+        sourceKind: parsedSessionCommand.sourceKind,
+        sourceId: parsedSessionCommand.sourceId,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatSessionAliasUnboundReply({
+          sourceKind: parsedSessionCommand.sourceKind,
+          sourceId: parsedSessionCommand.sourceId,
+          existed,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "global" && parsedLearnCommand.instruction) {
+      const applied = applyManualGlobalLearningRule({
+        storePath: accountStorePath,
+        accountId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnAppliedReply({
+          scope: "global",
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied?.ruleId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "session" && parsedLearnCommand.instruction) {
+      applyManualSessionLearningNote({
+        storePath: accountStorePath,
+        accountId,
+        targetId: data.conversationId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnAppliedReply({
+          scope: "session",
+          instruction: parsedLearnCommand.instruction,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "here" && parsedLearnCommand.instruction) {
+      const applied = applyManualTargetLearningRule({
+        storePath: accountStorePath,
+        accountId,
+        targetId: data.conversationId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnAppliedReply({
+          scope: "target",
+          targetId: data.conversationId,
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied?.ruleId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "target" && parsedLearnCommand.targetId && parsedLearnCommand.instruction) {
+      const applied = applyManualTargetLearningRule({
+        storePath: accountStorePath,
+        accountId,
+        targetId: parsedLearnCommand.targetId,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnAppliedReply({
+          scope: "target",
+          targetId: parsedLearnCommand.targetId,
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied?.ruleId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "targets" && parsedLearnCommand.targetIds?.length && parsedLearnCommand.instruction) {
+      const applied = applyManualTargetsLearningRule({
+        storePath: accountStorePath,
+        accountId,
+        targetIds: parsedLearnCommand.targetIds,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnAppliedReply({
+          scope: "targets",
+          targetIds: parsedLearnCommand.targetIds,
+          instruction: parsedLearnCommand.instruction,
+          ruleId: applied[0]?.ruleId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "target-set-create" && parsedLearnCommand.setName && parsedLearnCommand.targetIds?.length) {
+      const saved = createOrUpdateTargetSet({
+        storePath: accountStorePath,
+        accountId,
+        name: parsedLearnCommand.setName,
+        targetIds: parsedLearnCommand.targetIds,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        saved
+          ? formatTargetSetSavedReply({
+            setName: parsedLearnCommand.setName,
+            targetIds: parsedLearnCommand.targetIds,
+          })
+          : "目标组保存失败，请检查名称和目标列表。",
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "target-set-apply" && parsedLearnCommand.setName && parsedLearnCommand.instruction) {
+      const applied = applyTargetSetLearningRule({
+        storePath: accountStorePath,
+        accountId,
+        name: parsedLearnCommand.setName,
+        instruction: parsedLearnCommand.instruction,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        applied.length > 0
+          ? formatLearnAppliedReply({
+            scope: "target-set",
+            setName: parsedLearnCommand.setName,
+            targetIds: applied.map((item) => item.targetId),
+            instruction: parsedLearnCommand.instruction,
+            ruleId: applied[0]?.ruleId,
+          })
+          : `未找到目标组 \`${parsedLearnCommand.setName}\`，或该目标组为空。`,
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "list") {
+      const rules = listScopedLearningRules({ storePath: accountStorePath, accountId })
+        .slice(0, 20)
+        .map((rule) => {
+          const scope = rule.scope === "target" ? `target(${rule.targetId})` : "global";
+          const status = rule.enabled ? "enabled" : "disabled";
+          return `- [${scope}] ${rule.ruleId} (${status}) => ${rule.instruction}`;
+        });
+      const targetSets = listLearningTargetSets({ storePath: accountStorePath, accountId })
+        .slice(0, 10)
+        .map((targetSet) => `- [target-set] ${targetSet.name} => ${targetSet.targetIds.join(", ")}`);
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnListReply([...rules, ...targetSets]),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "disable" && parsedLearnCommand.ruleId) {
+      const result = disableManualRule({
+        storePath: accountStorePath,
+        accountId,
+        ruleId: parsedLearnCommand.ruleId,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnDisabledReply({
+          ruleId: parsedLearnCommand.ruleId,
+          existed: result.existed,
+          scope: result.scope,
+          targetId: result.targetId,
+        }),
+        { log },
+      );
+      return;
+    }
+    if (parsedLearnCommand.scope === "delete" && parsedLearnCommand.ruleId) {
+      const result = deleteManualRule({
+        storePath: accountStorePath,
+        accountId,
+        ruleId: parsedLearnCommand.ruleId,
+      });
+      await sendBySession(
+        dingtalkConfig,
+        sessionWebhook,
+        formatLearnDeletedReply({
+          ruleId: parsedLearnCommand.ruleId,
+          existed: result.existed,
+          scope: result.scope,
+          targetId: result.targetId,
+        }),
+        { log },
+      );
+      return;
+    }
+  }
+  const manualForcedReply = resolveManualForcedReply({
+    storePath: accountStorePath,
+    accountId,
+    targetId: data.conversationId,
+    content: extractedContent,
+  });
+  if (manualForcedReply) {
+    await sendBySession(dingtalkConfig, sessionWebhook, manualForcedReply, { log });
+    return;
+  }
+  // 3) Select response mode (card vs markdown).
+  // Card creation runs BEFORE media download so the user sees immediate visual
+  // feedback while large files are still being downloaded.
+  let useCardMode = dingtalkConfig.messageType === "card";
+  let currentAICard = undefined;
+
+  if (useCardMode) {
+    try {
+      log?.debug?.(
+        `[DingTalk][AICard] conversationType=${data.conversationType}, conversationId=${to}`,
+      );
+      const aiCard = await createAICard(dingtalkConfig, to, log, {
+        accountId,
+        storePath: accountStorePath,
+      });
+      if (aiCard) {
+        currentAICard = aiCard;
+      } else {
+        useCardMode = false;
+        log?.warn?.(
+          "[DingTalk] Failed to create AI card (returned null), fallback to text/markdown.",
+        );
+      }
+    } catch (err: any) {
+      useCardMode = false;
+      log?.warn?.(
+        `[DingTalk] Failed to create AI card: ${err.message}, fallback to text/markdown.`,
+      );
+    }
+  }
+
+  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)}`);
+    }
+  }
+
+  try {
+    appendQuoteJournalEntry({
+      storePath,
+      accountId,
+      conversationId: groupId,
+      msgId: data.msgId,
+      messageType: content.messageType,
+      text: stripQuotedPrefixForJournal(content.text),
+      createdAt: data.createAt,
+      ttlDays: journalTTLDays,
+    });
+  } catch (err) {
+    log?.warn?.(`[DingTalk] Quote journal append failed: ${String(err)}`);
+  }
+
   let mediaPath: string | undefined;
   let mediaType: string | undefined;
   if (content.mediaPath && dingtalkConfig.robotCode) {
@@ -335,6 +919,264 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       mediaType = media.mimeType;
     }
   }
+
+  // Cache downloadCode (+ spaceId/fileId) for quoted file lookups (DM + group).
+  if (content.mediaPath && data.msgId) {
+    cacheInboundDownloadCode(
+      accountId,
+      data.conversationId,
+      data.msgId,
+      content.mediaPath,
+      content.messageType,
+      data.createAt,
+      { spaceId: data.content?.spaceId, fileId: data.content?.fileId, storePath },
+    );
+  }
+
+  // User-sent DingTalk doc / Drive file card: cache msgId -> {spaceId,fileId}
+  // during the original message turn, and try downloading immediately in DM.
+  if (
+    content.messageType === "interactiveCardFile" &&
+    data.msgId &&
+    content.docSpaceId &&
+    content.docFileId
+  ) {
+    cacheInboundDownloadCode(
+      accountId,
+      data.conversationId,
+      data.msgId,
+      undefined,
+      content.messageType,
+      data.createAt,
+      { spaceId: content.docSpaceId, fileId: content.docFileId, storePath },
+    );
+
+    if (!mediaPath && isDirect && data.senderStaffId) {
+      try {
+        const unionId = await getUnionIdByStaffId(dingtalkConfig, data.senderStaffId, log);
+        const docMedia = await downloadGroupFile(
+          dingtalkConfig,
+          content.docSpaceId,
+          content.docFileId,
+          unionId,
+          log,
+        );
+        if (docMedia) {
+          mediaPath = docMedia.path;
+          mediaType = docMedia.mimeType;
+        }
+      } catch (err: any) {
+        log?.warn?.(`[DingTalk] Doc card download failed: ${err.message}`);
+      }
+    }
+  }
+
+  // Try downloading a quoted file from cached downloadCode/spaceId+fileId.
+  const tryDownloadFromCache = async (
+    quotedMsgId: string | undefined,
+  ): Promise<MediaFile | null> => {
+    if (!quotedMsgId) {
+      return null;
+    }
+    const cached = getCachedDownloadCode(accountId, data.conversationId, quotedMsgId, storePath);
+    if (!cached) {
+      return null;
+    }
+    let media: MediaFile | null = null;
+    if (cached.downloadCode) {
+      media = await downloadMedia(dingtalkConfig, cached.downloadCode, log);
+    }
+    if (!media && cached.spaceId && cached.fileId && data.senderStaffId) {
+      try {
+        const unionId = await getUnionIdByStaffId(dingtalkConfig, data.senderStaffId, log);
+        media = await downloadGroupFile(
+          dingtalkConfig,
+          cached.spaceId,
+          cached.fileId,
+          unionId,
+          log,
+        );
+      } catch (err: any) {
+        log?.warn?.(`[DingTalk] spaceId+fileId fallback failed: ${err.message}`);
+      }
+    }
+    return media;
+  };
+
+  // Quoted picture: download via existing downloadMedia.
+  if (!mediaPath && content.quoted?.mediaDownloadCode && dingtalkConfig.robotCode) {
+    const media = await downloadMedia(dingtalkConfig, content.quoted.mediaDownloadCode, log);
+    if (media) {
+      mediaPath = media.path;
+      mediaType = media.mimeType;
+    } else {
+      content.text = content.text.replace(
+        content.quoted.prefix,
+        "[引用了一张图片，但下载失败]\n\n",
+      );
+    }
+  }
+
+  // Quoted file/video/audio (unknownMsgType): cache-first, then group file API fallback.
+  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);
+    if (cachedMedia) {
+      mediaPath = cachedMedia.path;
+      mediaType = cachedMedia.mimeType;
+      fileResolved = true;
+    }
+
+    // Step 2 (group only): Cache miss → fall back to group file API time-based matching.
+    if (!fileResolved && !isDirect) {
+      const resolved = await resolveQuotedFile(
+        dingtalkConfig,
+        {
+          openConversationId: data.conversationId,
+          senderStaffId: data.senderStaffId,
+          fileCreatedAt: content.quoted.fileCreatedAt,
+        },
+        log,
+      );
+      if (resolved) {
+        mediaPath = resolved.media.path;
+        mediaType = resolved.media.mimeType;
+        fileResolved = true;
+        if (content.quoted.msgId) {
+          cacheInboundDownloadCode(
+            accountId,
+            data.conversationId,
+            content.quoted.msgId,
+            undefined,
+            "file",
+            content.quoted.fileCreatedAt || Date.now(),
+            { storePath, spaceId: resolved.spaceId, fileId: resolved.fileId },
+          );
+        }
+      }
+    }
+
+    if (!fileResolved) {
+      log?.warn?.(
+        `[DingTalk] Quoted file unresolved: conversationType=${data.conversationType} conversationId=${data.conversationId} quotedMsgId=${content.quoted.msgId || "(none)"}`,
+      );
+      const hint = isDirect
+        ? "[引用了一个文件，内容无法自动获取，请直接发送该文件]\n\n"
+        : "[引用了一个文件，但无法获取内容]\n\n";
+      content.text = content.text.replace(content.quoted.prefix, hint);
+    }
+  }
+
+  // Quoted DingTalk doc / Drive file card:
+  // 1) Prefer msgId-based cached metadata captured when the original doc card
+  //    message was seen.
+  // 2) In group chats, if the bot never saw the original doc card message,
+  //    reuse the same group-file fallback chain as ordinary quoted files.
+  if (!mediaPath && content.quoted?.isQuotedDocCard) {
+    let docResolved = false;
+
+    const cachedDocMedia = await tryDownloadFromCache(content.quoted.msgId);
+    if (cachedDocMedia) {
+      mediaPath = cachedDocMedia.path;
+      mediaType = cachedDocMedia.mimeType;
+      docResolved = true;
+      content.text = content.text.replace(content.quoted.prefix, "[引用了钉钉文档]\n\n");
+    }
+
+    if (!docResolved && !isDirect && content.quoted.fileCreatedAt) {
+      const resolved = await resolveQuotedFile(
+        dingtalkConfig,
+        {
+          openConversationId: data.conversationId,
+          senderStaffId: data.senderStaffId,
+          fileCreatedAt: content.quoted.fileCreatedAt,
+        },
+        log,
+      );
+      if (resolved) {
+        mediaPath = resolved.media.path;
+        mediaType = resolved.media.mimeType;
+        docResolved = true;
+        content.text = content.text.replace(content.quoted.prefix, "[引用了钉钉文档]\n\n");
+        if (content.quoted.msgId) {
+          cacheInboundDownloadCode(
+            accountId,
+            data.conversationId,
+            content.quoted.msgId,
+            undefined,
+            "interactiveCardFile",
+            content.quoted.fileCreatedAt || Date.now(),
+            { storePath, spaceId: resolved.spaceId, fileId: resolved.fileId },
+          );
+        }
+      }
+    }
+
+    if (!docResolved) {
+      log?.warn?.(
+        `[DingTalk] Quoted doc card unresolved: conversationType=${data.conversationType} conversationId=${data.conversationId} quotedMsgId=${content.quoted.msgId || "(none)"}`,
+      );
+      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`,
+      );
+    }
+    // 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,
+      });
+      if (extracted?.text) {
+        attachmentExtractedText = `${ATTACHMENT_TEXT_PREFIX}\n${extracted.text}`;
+      }
+    } catch (err: any) {
+      log?.warn?.(`[DingTalk] Failed to extract attachment text: ${err.message}`);
+    }
+  }
+
+  const inboundBody =
+    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 learningEnabled = isFeedbackLearningEnabled(dingtalkConfig);
+  const learningContextBlock = buildLearningContextBlock({
+    enabled: learningEnabled,
+    storePath: accountStorePath,
+    accountId,
+    targetId: data.conversationId,
+    content,
+  });
   const envelopeOptions = rt.channel.reply.resolveEnvelopeFormatOptions(cfg);
   const previousTimestamp = rt.channel.session.readSessionUpdatedAt({
     storePath,
@@ -343,11 +1185,18 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
   const groupConfig = !isDirect ? resolveGroupConfig(dingtalkConfig, groupId) : undefined;
   // GroupSystemPrompt is injected every turn (not only first-turn intro).
-  const groupSystemPrompt = !isDirect
-    ? [`DingTalk group context: conversationId=${groupId}`, groupConfig?.systemPrompt?.trim()]
-        .filter(Boolean)
-        .join("\n")
-    : undefined;
+  const groupSystemPromptParts = !isDirect
+    ? [
+        buildGroupTurnContextPrompt({
+          conversationId: groupId,
+          senderDingtalkId: senderId,
+          senderName,
+        }),
+        groupConfig?.systemPrompt?.trim(),
+      ]
+    : [];
+  const extraSystemPrompt =
+    [...groupSystemPromptParts, learningContextBlock].filter(Boolean).join("\n\n") || undefined;
 
   if (!isDirect) {
     noteGroupMember(storePath, groupId, senderId, senderName);
@@ -359,18 +1208,17 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     channel: "DingTalk",
     from: fromLabel,
     timestamp: data.createAt,
-    body: content.text,
+    body: inboundText,
     chatType: isDirect ? "direct" : "group",
     sender: { name: senderName, id: senderId },
     previousTimestamp,
     envelope: envelopeOptions,
   });
 
-  const to = isDirect ? senderId : groupId;
   const ctx = rt.channel.reply.finalizeInboundContext({
     Body: body,
-    RawBody: content.text,
-    CommandBody: content.text,
+    RawBody: inboundText,
+    CommandBody: inboundText,
     From: to,
     To: to,
     SessionKey: route.sessionKey,
@@ -388,7 +1236,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     MediaType: mediaType,
     MediaUrl: mediaPath,
     GroupMembers: groupMembers,
-    GroupSystemPrompt: groupSystemPrompt,
+    GroupSystemPrompt: extraSystemPrompt,
     GroupChannel: isDirect ? undefined : route.sessionKey,
     CommandAuthorized: commandAuthorized,
     OriginatingChannel: "dingtalk",
@@ -407,199 +1255,336 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
   log?.info?.(`[DingTalk] Inbound: from=${senderName} text="${content.text.slice(0, 50)}..."`);
 
-  // 3) Select response mode (card vs markdown).
-  const useCardMode = dingtalkConfig.messageType === "card";
-  let currentAICard = undefined;
-  let lastCardContent = "";
+  const ackReaction =
+    typeof dingtalkConfig.ackReaction === "string"
+      ? dingtalkConfig.ackReaction.trim()
+      : resolveAckReactionSetting({
+          cfg,
+          accountId,
+          agentId: route.agentId,
+        });
+  const resolvedAckReaction =
+    ackReaction === "emoji" ? classifyAckReactionEmoji(content.text).emoji : ackReaction;
+  const shouldAttachAckReaction = Boolean(resolvedAckReaction);
+  let ackReactionAttached = false;
+  let ackReactionAttachedAt = 0;
 
-  if (useCardMode) {
-    const targetKey = `${accountId}:${to}`;
-    const existingCardId = getActiveCardIdByTarget(targetKey);
-    const existingCard = existingCardId ? getCardById(existingCardId) : undefined;
-
-    // Reuse active non-terminal card to keep one card per conversation.
-    if (existingCard && !isCardInTerminalState(existingCard.state)) {
-      currentAICard = existingCard;
-      log?.debug?.("[DingTalk] Reusing existing active AI card for this conversation.");
-    } else {
-      try {
-        const aiCard = await createAICard(dingtalkConfig, to, data, accountId, log);
-        if (aiCard) {
-          currentAICard = aiCard;
-        } else {
-          log?.warn?.(
-            "[DingTalk] Failed to create AI card (returned null), fallback to text/markdown.",
-          );
-        }
-      } catch (err: any) {
-        log?.warn?.(
-          `[DingTalk] Failed to create AI card: ${err.message}, fallback to text/markdown.`,
-        );
-      }
+  if (shouldAttachAckReaction) {
+    ackReactionAttached = await attachNativeAckReaction(
+      dingtalkConfig,
+      {
+        msgId: data.msgId,
+        conversationId: groupId,
+        reactionName: resolvedAckReaction,
+      },
+      log,
+    );
+    if (ackReactionAttached) {
+      ackReactionAttachedAt = Date.now();
     }
   }
 
-  // 4) Optional "thinking..." feedback for non-card mode.
-  if (dingtalkConfig.showThinking !== false) {
-    try {
-      const thinkingText = "🤔 思考中，请稍候...";
-      if (useCardMode && currentAICard) {
-        log?.debug?.("[DingTalk] AI Card in thinking state, skipping thinking message send.");
-      } else {
-        lastCardContent = thinkingText;
-        await sendMessage(dingtalkConfig, to, thinkingText, {
-          sessionWebhook,
-          atUserId: !isDirect ? senderId : null,
-          log,
-          accountId,
-        });
-      }
-    } catch (err: any) {
-      log?.debug?.(`[DingTalk] Thinking message failed: ${err.message}`);
-      if (err?.response?.data !== undefined) {
-        log?.debug?.(formatDingTalkErrorPayloadLog("inbound.thinkingMessage", err.response.data));
-      }
+  // 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.
+  const releaseSessionLock = await acquireSessionLock(route.sessionKey);
+  try {
+    if (!ackReactionAttached && shouldAttachAckReaction) {
+      log?.debug?.("[DingTalk] Native ack reaction unavailable; skipping fallback.");
     }
-  }
 
-  const { queuedFinal } = await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-    ctx,
-    cfg,
-    dispatcherOptions: {
-      responsePrefix: "",
-      deliver: async (payload: any, info?: { kind: string }) => {
-        try {
-          const textToSend = payload.markdown || payload.text;
-          if (!textToSend) {
-            return;
-          }
+    const controller = useCardMode && currentAICard
+      ? createCardDraftController({ card: currentAICard, log })
+      : undefined;
+    let cardFinalized = false;
+    let finalTextForFallback: string | undefined;
 
-          if (typeof textToSend === "string" && isUnhandledStopReasonText(textToSend)) {
-            log?.warn?.(`[DingTalk] Suppressed stop reason from outbound chat content: ${textToSend}`);
-            return;
-          }
+    try {
+      await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx,
+        cfg,
+        dispatcherOptions: {
+          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?.();
+                }
+              }
+            }
 
-          if (useCardMode && currentAICard && info?.kind === "final") {
-            lastCardContent = textToSend;
-            return;
-          }
+            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]
+                  : [];
 
-          // Tool outputs are rendered into card stream as a separate formatted block.
-          if (useCardMode && currentAICard && info?.kind === "tool") {
-            if (isCardInTerminalState(currentAICard.state)) {
-              log?.debug?.(
-                `[DingTalk] Skipping tool stream update because card is terminal: state=${currentAICard.state}`,
-              );
-              return;
-            }
+              // 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;
+                }
+              }
 
-            log?.info?.(
-              `[DingTalk] Tool result received, streaming to AI Card: ${textToSend.slice(0, 100)}`,
-            );
-            const toolText = formatContentForCard(textToSend, "tool");
-            if (toolText) {
-              await streamAICard(currentAICard, toolText, false, log);
-              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));
+              }
+              throw err;
             }
-          }
+          },
+        },
+        replyOptions: {
+          disableBlockStreaming: dingtalkConfig.cardRealTimeStream && controller ? true : undefined,
 
-          lastCardContent = textToSend;
-          await sendMessage(dingtalkConfig, to, textToSend, {
-            sessionWebhook,
-            atUserId: !isDirect ? senderId : null,
-            log,
-            accountId,
-          });
-        } catch (err: any) {
-          log?.error?.(`[DingTalk] Reply failed: ${err.message}`);
-          if (err?.response?.data !== undefined) {
-            log?.error?.(formatDingTalkErrorPayloadLog("inbound.replyDeliver", err.response.data));
+          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,
+        },
+      });
+    } 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();
           }
-          throw err;
-        }
-      },
-    },
-    replyOptions: {
-      // Real-time reasoning stream support for card mode.
-      onReasoningStream: async (payload: any) => {
-        if (!useCardMode || !currentAICard) {
-          return;
         }
-        if (isCardInTerminalState(currentAICard.state)) {
-          log?.debug?.(
-            `[DingTalk] Skipping thinking stream update because card is terminal: state=${currentAICard.state}`,
+      }
+      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;
         }
-        const thinkingText = formatContentForCard(payload.text, "thinking");
-        if (!thinkingText) {
+
+        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 {
-          await streamAICard(currentAICard, thinkingText, false, log);
-        } catch (err: any) {
-          log?.debug?.(`[DingTalk] Thinking stream update failed: ${err.message}`);
-          if (err?.response?.data !== undefined) {
-            log?.debug?.(formatDingTalkErrorPayloadLog("inbound.thinkingStream", err.response.data));
+          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}`);
         }
-      },
-    },
-  });
-
-  // 5) Finalize card stream if card mode is active.
-  if (useCardMode && currentAICard) {
-    try {
-      if (isCardInTerminalState(currentAICard.state)) {
-        log?.debug?.(
-          `[DingTalk] Skipping AI Card finalization because card is terminal: state=${currentAICard.state}`,
-        );
-        return;
       }
-
-      const isNonEmptyString = (value: any): boolean =>
-        typeof value === "string" && value.trim().length > 0;
-
-      const hasLastCardContent = isNonEmptyString(lastCardContent);
-      const hasQueuedFinalString = isNonEmptyString(queuedFinal);
-
-      if (hasLastCardContent || hasQueuedFinalString) {
-        const finalContentCandidate =
-          hasLastCardContent && typeof lastCardContent === "string"
-            ? lastCardContent
-            : typeof queuedFinal === "string"
-              ? queuedFinal
-              : "";
-        if (isUnhandledStopReasonText(finalContentCandidate)) {
-          log?.warn?.(
-            `[DingTalk] Suppressed stop reason from AI Card final content: ${finalContentCandidate}`,
-          );
-          currentAICard.state = AICardStatus.FINISHED;
-          currentAICard.lastUpdated = Date.now();
-          return;
+    }
+  } finally {
+    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));
         }
-        const finalContent = finalContentCandidate;
-        await finishAICard(currentAICard, finalContent, log);
-      } else {
-        const defaultFinalContent = "✅ Done";
-        log?.debug?.(
-          "[DingTalk] No textual content was produced; finalizing AI Card with default completion content.",
+        await recallNativeAckReactionWithRetry(
+          dingtalkConfig,
+          {
+            msgId: data.msgId,
+            conversationId: groupId,
+            reactionName: resolvedAckReaction,
+          },
+          log,
         );
-        await finishAICard(currentAICard, defaultFinalContent, 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}`);
-      }
+      })();
     }
   }
 }