@soimy/dingtalk 3.2.0 → 3.4.0

package/src/inbound-handler.ts

@@ -1,31 +1,153 @@
 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 } from "./card-service";
+import { resolveAckReactionSetting, resolveGroupConfig } from "./config";
 import {
-  createAICard,
-  finishAICard,
-  formatContentForCard,
-  isCardInTerminalState,
-} from "./card-service";
-import { resolveGroupConfig } from "./config";
+  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 {
+  formatLearnAppliedReply,
+  formatLearnCommandHelp,
+  formatLearnDeletedReply,
+  formatLearnDisabledReply,
+  formatLearnListReply,
+  formatOwnerOnlyDeniedReply,
+  formatOwnerStatusReply,
+  formatTargetSetSavedReply,
+  formatWhereAmIReply,
+  formatWhoAmIReply,
+  isLearningOwner,
+  parseLearnCommand,
+} from "./learning-command-service";
 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 { 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 } from "./send-service";
-import type { DingTalkConfig, HandleDingTalkMessageParams, MediaFile } from "./types";
-import { AICardStatus } from "./types";
+import { sendBySession, sendMessage, sendProactiveMedia } from "./send-service";
+import {
+  formatSessionAliasBoundReply,
+  formatSessionAliasClearedReply,
+  formatSessionAliasReply,
+  formatSessionAliasSetReply,
+  formatSessionAliasUnboundReply,
+  formatSessionAliasValidationErrorReply,
+  parseSessionCommand,
+  validateSessionAlias,
+} from "./session-command-service";
 import { acquireSessionLock } from "./session-lock";
-import { formatDingTalkErrorPayloadLog, maskSensitiveData } from "./utils";
+import {
+  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 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();
@@ -35,6 +157,7 @@ function shouldSendProactivePermissionHint(params: {
   isDirect: boolean;
   accountId: string;
   senderId: string;
+  senderOriginalId?: string;
   senderStaffId?: string;
   config: DingTalkConfig;
   nowMs: number;
@@ -53,9 +176,16 @@ function shouldSendProactivePermissionHint(params: {
     return false;
   }
 
+  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,
-    [params.senderId, params.senderStaffId],
+    riskTargets,
     params.nowMs,
   );
   if (!riskObservation || riskObservation.source !== "proactive-api") {
@@ -77,14 +207,36 @@ 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 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.
@@ -111,7 +263,7 @@ export async function downloadMedia(
     try {
       return JSON.stringify(maskSensitiveData(value));
     } catch {
-      return String(value);
+      return `[unstringifiable ${typeof value}]`;
     }
   };
 
@@ -177,13 +329,13 @@ 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.
   setCurrentLogger(log);
 
-  log?.debug?.("[DingTalk] Full Inbound Data:", JSON.stringify(maskSensitiveData(data)));
+  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) {
@@ -191,13 +343,24 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     return;
   }
 
-  const content = extractMessageContent(data);
-  if (!content.text) {
+  // 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 senderId = data.senderStaffId || data.senderId;
+  const isGroup = !isDirect;
+  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";
@@ -212,7 +375,8 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       isDirect,
       accountId,
       senderId,
-      senderStaffId: data.senderStaffId,
+      senderOriginalId,
+      senderStaffId,
       config: dingtalkConfig,
       nowMs: Date.now(),
     })
@@ -227,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),
+        );
       }
     }
   }
@@ -259,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),
+            );
           }
         }
 
@@ -274,93 +442,1022 @@ 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}`,
+    );
   }
 
-  const route = rt.channel.routing.resolveAgentRoute({
-    cfg,
-    channel: "dingtalk",
+  // 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({
+    storePath: accountStorePath,
     accountId,
-    peer: { kind: isDirect ? "direct" : "group", id: isDirect ? senderId : groupId },
+    sourceKind: currentSessionSourceKind,
+    sourceId: currentSessionSourceId,
+  });
+  const sessionPeer = resolveDingTalkSessionPeer({
+    isDirect,
+    senderId,
+    conversationId: groupId,
+    peerIdOverride,
+    config: dingtalkConfig,
   });
 
+  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, {
     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.
-  const useCardMode = dingtalkConfig.messageType === "card";
+  let useCardMode = dingtalkConfig.messageType === "card";
   let currentAICard = undefined;
-  let lastCardContent = "";
 
   if (useCardMode) {
     try {
       log?.debug?.(
         `[DingTalk][AICard] conversationType=${data.conversationType}, conversationId=${to}`,
       );
-      const aiCard = await createAICard(dingtalkConfig, to, log);
+      const aiCard = await createAICard(dingtalkConfig, to, log, {
+        accountId,
+        storePath: accountStorePath,
+        contextConversationId: groupId,
+      });
       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 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 {
+    upsertInboundMessageContext({
+      storePath: accountStorePath,
+      accountId,
+      conversationId: groupId,
+      msgId: data.msgId,
+      messageType: content.messageType,
+      text: content.text,
+      quotedRef,
+      createdAt: data.createAt,
+      ttlMs: ttlDaysToMs(journalTTLDays),
+      ttlReferenceMs: data.createAt,
+      cleanupCreatedAtTtlDays: journalTTLDays,
+      topic: null,
+    });
+  } catch (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;
       mediaType = media.mimeType;
     }
   }
+
+  // Cache downloadCode (+ spaceId/fileId) for quoted file lookups (DM + group).
+  if (content.mediaPath && data.msgId) {
+    upsertInboundMessageContext({
+      storePath: accountStorePath,
+      accountId,
+      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}
+  // during the original message turn, and try downloading immediately in DM.
+  if (
+    content.messageType === "interactiveCardFile" &&
+    data.msgId &&
+    content.docSpaceId &&
+    content.docFileId
+  ) {
+    upsertInboundMessageContext({
+      storePath: accountStorePath,
+      accountId,
+      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 {
+        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}`);
+      }
+    }
+  }
+
+  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 tryDownloadFromRecord = async (
+    record: {
+      msgId?: string;
+      media?: {
+        downloadCode?: string;
+        spaceId?: string;
+        fileId?: string;
+      };
+    } | null,
+  ): Promise<MediaFile | null> => {
+    if (!record?.media) {
+      return null;
+    }
+    let media: MediaFile | null = null;
+    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 && record.media.spaceId && record.media.fileId && data.senderStaffId) {
+      try {
+        const unionId = await getUnionIdByStaffId(dingtalkConfig, data.senderStaffId, log);
+        media = await downloadGroupFile(
+          dingtalkConfig,
+          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}`);
+      }
+    }
+    return media;
+  };
+
+  // Quoted picture: download via existing downloadMedia.
+  if (!mediaPath && content.quoted?.mediaDownloadCode && dingtalkConfig.robotCode) {
+    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 = `[引用了一张图片，但下载失败]\n\n${content.text}`;
+    }
+  }
+
+  // Quoted file/video/audio (unknownMsgType): cache-first, then group file API fallback.
+  if (!mediaPath && content.quoted?.isQuotedFile) {
+    let fileResolved = false;
+
+    // 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;
+    }
+
+    // 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;
+        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) {
+          upsertInboundMessageContext({
+            storePath: accountStorePath,
+            accountId,
+            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,
+          });
+        }
+      }
+    }
+
+    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 = `${hint}${content.text}`;
+    }
+  }
+
+  // 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 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;
+    }
+
+    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;
+        attachmentContextMsgId = content.quoted.msgId || data.msgId;
+        attachmentContextCreatedAt = content.quoted.fileCreatedAt || data.createAt;
+        attachmentContextMessageType = "interactiveCardFile";
+        attachmentContextFileName = resolved.name || content.quoted.previewFileName;
+        docResolved = true;
+        log?.debug?.(
+          `[DingTalk][QuotedRef] Recovered quoted doc card from group file fallback ` +
+            `scope=${data.conversationId} quotedMsgId=${content.quoted.msgId || "(none)"}`,
+        );
+        if (content.quoted.msgId) {
+          upsertInboundMessageContext({
+            storePath: accountStorePath,
+            accountId,
+            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,
+          });
+        }
+      }
+    }
+
+    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 = `${hint}${content.text}`;
+    }
+  }
+
+  if (mediaPath) {
+    try {
+      const extracted = await extractAttachmentText({
+        path: mediaPath,
+        mimeType: mediaType,
+        fileName: attachmentContextFileName || data.content?.fileName,
+      });
+      if (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}`);
+    }
+  }
+
+  const inboundBody =
+    mediaPath && /<media:[^>]+>/.test(content.text)
+      ? `${content.text}\n[media_path: ${mediaPath}]\n[media_type: ${mediaType || "unknown"}]`
+      : content.text;
+  const inboundText = 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,
@@ -369,11 +1466,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);
@@ -385,7 +1489,7 @@ 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,
@@ -394,8 +1498,17 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
   const ctx = rt.channel.reply.finalizeInboundContext({
     Body: body,
-    RawBody: content.text,
-    CommandBody: content.text,
+    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,
@@ -413,7 +1526,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",
@@ -424,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)}`);
     },
@@ -432,218 +1565,200 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
   log?.info?.(`[DingTalk] Inbound: from=${senderName} text="${content.text.slice(0, 50)}..."`);
 
-  // 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 {
-    // 4) Optional "thinking..." feedback for non-card mode.
-    if (dingtalkConfig.showThinking !== false) {
+  const ackReaction =
+    typeof dingtalkConfig.ackReaction === "string"
+      ? dingtalkConfig.ackReaction.trim()
+      : resolveAckReactionSetting({
+          cfg,
+          accountId,
+          agentId: route.agentId,
+        });
+  const normalizedAckReaction = ackReaction === "off" ? "" : ackReaction;
+  const resolvedAckReaction =
+    normalizedAckReaction === "kaomoji"
+      ? classifyAckReactionEmoji(content.text).emoji
+      : normalizedAckReaction === "emoji"
+        ? "🤔思考中"
+        : normalizedAckReaction;
+  const shouldAttachAckReaction = Boolean(resolvedAckReaction);
+  let ackReactionAttached = false;
+  let ackReactionAttachedAt = 0;
+
+  if (shouldAttachAckReaction) {
+    ackReactionAttached = await attachNativeAckReaction(
+      dingtalkConfig,
+      {
+        msgId: data.msgId,
+        conversationId: groupId,
+        reactionName: resolvedAckReaction,
+      },
+      log,
+    );
+    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 thinkingText = "🤔 思考中，请稍候...";
-        if (useCardMode && currentAICard) {
-          log?.debug?.("[DingTalk] AI Card in thinking state, skipping thinking message send.");
-        } else {
-          lastCardContent = thinkingText;
-          const sendResult = await sendMessage(dingtalkConfig, to, thinkingText, {
+        const actualMediaPath = preparedMedia.path;
+        const outMediaType = resolveOutboundMediaType({
+          mediaPath: actualMediaPath,
+          asVoice: false,
+        });
+        if (sessionWebhook) {
+          const sendResult = await sendMessage(dingtalkConfig, to, "", {
             sessionWebhook,
-            atUserId: !isDirect ? senderId : null,
+            mediaPath: actualMediaPath,
+            mediaType: outMediaType,
             log,
-            card: currentAICard,
+            accountId,
+            storePath: accountStorePath,
+            conversationId: groupId,
+            quotedRef: replyQuotedRef,
           });
           if (!sendResult.ok) {
-            throw new Error(sendResult.error || "Thinking message send failed");
+            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");
           }
         }
-      } catch (err: any) {
-        log?.debug?.(`[DingTalk] Thinking message failed: ${err.message}`);
-        if (err?.response?.data !== undefined) {
-          log?.debug?.(formatDingTalkErrorPayloadLog("inbound.thinkingMessage", err.response.data));
-        }
+      } 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.");
+    }
+
+    // ---- 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,
+    });
 
-    let queuedFinal: unknown;
     try {
-      const dispatchResult = await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
         ctx,
         cfg,
         dispatcherOptions: {
-          responsePrefix: "",
-          deliver: async (payload: any, info?: { kind: string }) => {
+          responsePrefix: subAgentOptions?.responsePrefix || "",
+          deliver: async (payload: ReplyStreamPayload, info?: ReplyChunkInfo) => {
             try {
-              const textToSend = payload.markdown || payload.text;
-              if (!textToSend) {
-                return;
-              }
-
-              if (typeof textToSend === "string" && isUnhandledStopReasonText(textToSend)) {
-                log?.warn?.(`[DingTalk] Suppressed stop reason from outbound chat content: ${textToSend}`);
-                return;
-              }
-
-              if (useCardMode && currentAICard && info?.kind === "final") {
-                lastCardContent = textToSend;
-                return;
-              }
-
-              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;
-                }
-
-                log?.info?.(
-                  `[DingTalk] Tool result received, streaming to AI Card: ${textToSend.slice(0, 100)}`,
-                );
-                const toolText = formatContentForCard(textToSend, "tool");
-                if (toolText) {
-                  const sendResult = await sendMessage(dingtalkConfig, to, toolText, {
-                    sessionWebhook,
-                    atUserId: !isDirect ? senderId : null,
-                    log,
-                    card: currentAICard,
-                    cardUpdateMode: "append",
-                  });
-                  if (!sendResult.ok) {
-                    throw new Error(sendResult.error || "Tool stream send failed");
-                  }
-                  lastCardContent = currentAICard.lastStreamedContent || toolText;
-                  return;
-                }
-              }
-
-              lastCardContent = textToSend;
-              const sendResult = await sendMessage(dingtalkConfig, to, textToSend, {
-                sessionWebhook,
-                atUserId: !isDirect ? senderId : null,
-                log,
-                card: currentAICard,
+              const mediaUrls = extractMediaUrls(payload);
+              await strategy.deliver({
+                text: payload.text,
+                mediaUrls,
+                kind: (info?.kind as DeliverPayload["kind"]) || "block",
               });
-              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));
+            } 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: {
-          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}`,
-              );
-              return;
-            }
-            const thinkingText = formatContentForCard(payload.text, "thinking");
-            if (!thinkingText) {
-              return;
-            }
-            try {
-              const sendResult = await sendMessage(dingtalkConfig, to, thinkingText, {
-                sessionWebhook,
-                atUserId: !isDirect ? senderId : null,
-                log,
-                card: currentAICard,
-                cardUpdateMode: "append",
-              });
-              if (!sendResult.ok) {
-                throw new Error(sendResult.error || "Thinking stream send failed");
-              }
-            } 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));
-              }
-            }
-          },
-        },
+        replyOptions: strategy.getReplyOptions(),
       });
-      queuedFinal = dispatchResult?.queuedFinal;
-    } catch (dispatchErr: any) {
-      if (useCardMode && currentAICard && !isCardInTerminalState(currentAICard.state)) {
-        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) 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;
-          }
-          const finalContent = finalContentCandidate;
-          await finishAICard(currentAICard, finalContent, log);
-        } else {
-          const lastStreamed = currentAICard.lastStreamedContent;
-          if (typeof lastStreamed === "string" && lastStreamed.trim().length > 0) {
-            await finishAICard(currentAICard, lastStreamed, log);
-          } else {
-            const defaultFinalContent = "✅ Done";
-            log?.debug?.(
-              "[DingTalk] No textual content was produced; finalizing AI Card with default completion content.",
-            );
-            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}`);
-        }
-      }
-    }
+    await strategy.finalize();
   } finally {
+    await waitForDynamicAckDispose({
+      dispose: () => dynamicAckReactionController.dispose(MIN_THINKING_REACTION_VISIBLE_MS),
+      log,
+      sessionKey: route.sessionKey,
+    });
     releaseSessionLock();
   }
 }