@soimy/dingtalk 3.4.2 → 3.5.1

package/src/config.ts

@@ -17,19 +17,24 @@ function normalizeLearningConfig(
   config: DingTalkConfig,
   options: { applyDefaults: boolean },
 ): DingTalkConfig {
-  const learningEnabled = config.learningEnabled ?? config.feedbackLearningEnabled;
-  const learningAutoApply = config.learningAutoApply ?? config.feedbackLearningAutoApply;
-  const learningNoteTtlMs = config.learningNoteTtlMs ?? config.feedbackLearningNoteTtlMs;
   return {
     ...config,
-    learningEnabled: options.applyDefaults ? learningEnabled ?? false : learningEnabled,
-    learningAutoApply: options.applyDefaults ? learningAutoApply ?? false : learningAutoApply,
+    learningEnabled: options.applyDefaults ? config.learningEnabled ?? false : config.learningEnabled,
+    learningAutoApply: options.applyDefaults
+      ? config.learningAutoApply ?? false
+      : config.learningAutoApply,
     learningNoteTtlMs: options.applyDefaults
-      ? learningNoteTtlMs ?? DEFAULT_LEARNING_NOTE_TTL_MS
-      : learningNoteTtlMs,
+      ? config.learningNoteTtlMs ?? DEFAULT_LEARNING_NOTE_TTL_MS
+      : config.learningNoteTtlMs,
   };
 }
 
+function stripRemovedLegacyFields(config: DingTalkConfig): DingTalkConfig {
+  const { verboseRealtimeStream: _verboseRealtimeStream, ...rest } =
+    config as DingTalkConfig & { verboseRealtimeStream?: unknown };
+  return rest as DingTalkConfig;
+}
+
 /**
  * Merge channel-level defaults into an account-specific config.
  * Account-level values take precedence; `accounts` key is excluded to avoid recursion.
@@ -38,8 +43,12 @@ export function mergeAccountWithDefaults(
   channelCfg: DingTalkConfig,
   accountCfg: DingTalkConfig,
 ): DingTalkConfig {
-  const { accounts: _accounts, ...defaults } = channelCfg;
-  const normalizedAccountCfg = normalizeLearningConfig(accountCfg, { applyDefaults: false });
+  const { accounts: _accounts, ...defaultCandidate } =
+    channelCfg as DingTalkConfig & { accounts?: unknown; verboseRealtimeStream?: unknown };
+  const defaults = stripRemovedLegacyFields(defaultCandidate as DingTalkConfig);
+  const normalizedAccountCfg = stripRemovedLegacyFields(
+    normalizeLearningConfig(accountCfg, { applyDefaults: false }),
+  );
   const overrides: Partial<DingTalkConfig> = {};
   for (const [key, value] of Object.entries(normalizedAccountCfg)) {
     if (value !== undefined) {
@@ -71,14 +80,14 @@ export function getConfig(cfg: OpenClawConfig, accountId?: string): DingTalkConf
   }
 
   if (accountId) {
-    return normalizeLearningConfig(dingtalkCfg, { applyDefaults: true });
+    return stripRemovedLegacyFields(normalizeLearningConfig(dingtalkCfg, { applyDefaults: true }));
   }
 
   if (dingtalkCfg.accounts && Object.keys(dingtalkCfg.accounts).length > 0) {
     return dingtalkCfg;
   }
 
-  return normalizeLearningConfig(dingtalkCfg, { applyDefaults: true });
+  return stripRemovedLegacyFields(normalizeLearningConfig(dingtalkCfg, { applyDefaults: true }));
 }
 
 export function isConfigured(cfg: OpenClawConfig, accountId?: string): boolean {
@@ -142,6 +151,14 @@ export function resolveRelativePath(input: string): string {
 
 export const resolveUserPath = resolveRelativePath;
 
+/**
+ * Resolve the robot code used by DingTalk APIs.
+ * DingTalk robotCode is always equal to clientId; this helper trims whitespace.
+ */
+export function resolveRobotCode(config: Pick<DingTalkConfig, "clientId">): string {
+  return (config.clientId || "").trim();
+}
+
 export function resolveGroupConfig(
   cfg: DingTalkConfig,
   groupId: string,

package/src/feedback-learning-service.ts

@@ -143,14 +143,12 @@ function updateLearnedRule(
   upsertLearnedRule({ storePath, accountId, rule });
 }
 
-export function isFeedbackLearningEnabled(config: DingTalkConfig | undefined): boolean {
-  const typed = config as (DingTalkConfig & { learningEnabled?: boolean; feedbackLearningEnabled?: boolean }) | undefined;
-  return Boolean(typed?.learningEnabled ?? typed?.feedbackLearningEnabled);
+export function isLearningEnabled(config: DingTalkConfig | undefined): boolean {
+  return Boolean(config?.learningEnabled);
 }
 
-export function isFeedbackLearningAutoApplyEnabled(config: DingTalkConfig | undefined): boolean {
-  const typed = config as (DingTalkConfig & { learningAutoApply?: boolean; feedbackLearningAutoApply?: boolean }) | undefined;
-  return Boolean(typed?.learningAutoApply ?? typed?.feedbackLearningAutoApply);
+export function isLearningAutoApplyEnabled(config: DingTalkConfig | undefined): boolean {
+  return Boolean(config?.learningAutoApply);
 }
 
 export function recordOutboundReplyForLearning(params: {

package/src/inbound-handler.ts

@@ -6,8 +6,14 @@ 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, isCardInTerminalState } from "./card-service";
+import { resolveAckReactionSetting, resolveGroupConfig, resolveRobotCode } from "./config";
+import { AICardStatus } from "./types";
+import {
+  isCardRunStopRequested,
+  registerCardRun,
+  removeCardRun,
+} from "./card/card-run-registry";
 import {
   applyManualTargetLearningRule,
   applyManualTargetsLearningRule,
@@ -18,7 +24,7 @@ import {
   createOrUpdateTargetSet,
   deleteManualRule,
   disableManualRule,
-  isFeedbackLearningEnabled,
+  isLearningEnabled,
   listLearningTargetSets,
   listScopedLearningRules,
   resolveManualForcedReply,
@@ -85,10 +91,12 @@ import {
 } from "./targeting/target-directory-store";
 import type { DingTalkConfig, HandleDingTalkMessageParams, MediaFile } from "./types";
 import { formatDingTalkErrorPayloadLog, getErrorMessage, getErrorResponseData, maskSensitiveData } from "./utils";
+import { isAbortRequestText } from "openclaw/plugin-sdk/reply-runtime";
 
 const DEFAULT_PROACTIVE_HINT_COOLDOWN_HOURS = 24;
 const MIN_THINKING_REACTION_VISIBLE_MS = 1200;
 const MAX_DYNAMIC_ACK_DISPOSE_WAIT_MS = 500;
+const ATTACHMENT_TEXT_PREFIX = "[附件内容摘录]";
 const proactiveHintLastSentAt = new Map<string, number>();
 
 function resolvePinnedMainDmOwner(params: {
@@ -237,6 +245,9 @@ type ReplyChunkInfo = {
   kind?: string;
 };
 
+const INBOUND_MEDIA_DOWNLOAD_TIMEOUT_MS = 15_000;
+const DINGTALK_API_HOST = "api.dingtalk.com";
+
 /**
  * Download DingTalk media file via runtime media service (sandbox-compatible).
  * Files are stored in the global media inbound directory.
@@ -247,6 +258,9 @@ export async function downloadMedia(
   log?: any,
 ): Promise<MediaFile | null> {
   const rt = getDingTalkRuntime();
+  let downloadUrl: string | undefined;
+  let requestStage = "auth";
+  let requestHost = DINGTALK_API_HOST;
   const formatAxiosErrorData = (value: unknown): string | undefined => {
     if (value === null || value === undefined) {
       return undefined;
@@ -271,21 +285,26 @@ export async function downloadMedia(
     log?.error?.("[DingTalk] downloadMedia requires downloadCode to be provided.");
     return null;
   }
-  if (!config.robotCode) {
+  const robotCode = resolveRobotCode(config);
+  if (!robotCode) {
     if (log?.error) {
-      log.error("[DingTalk] downloadMedia requires robotCode to be configured.");
+      log.error("[DingTalk] downloadMedia requires clientId to be configured.");
     }
     return null;
   }
   try {
+    requestStage = "auth";
+    requestHost = DINGTALK_API_HOST;
     const token = await getAccessToken(config, log);
+    requestStage = "exchange";
+    requestHost = DINGTALK_API_HOST;
     const response = await axios.post(
       "https://api.dingtalk.com/v1.0/robot/messageFiles/download",
-      { downloadCode, robotCode: config.robotCode },
+      { downloadCode, robotCode },
       { headers: { "x-acs-dingtalk-access-token": token } },
     );
     const payload = response.data as Record<string, any>;
-    const downloadUrl = payload?.downloadUrl ?? payload?.data?.downloadUrl;
+    downloadUrl = payload?.downloadUrl ?? payload?.data?.downloadUrl;
     if (!downloadUrl) {
       const payloadDetail = formatAxiosErrorData(payload);
       log?.error?.(
@@ -293,7 +312,18 @@ export async function downloadMedia(
       );
       return null;
     }
-    const mediaResponse = await axios.get(downloadUrl, { responseType: "arraybuffer" });
+    requestStage = "download";
+    requestHost = (() => {
+      try {
+        return new URL(downloadUrl).host || "unknown";
+      } catch {
+        return "unknown";
+      }
+    })();
+    const mediaResponse = await axios.get(downloadUrl, {
+      responseType: "arraybuffer",
+      timeout: INBOUND_MEDIA_DOWNLOAD_TIMEOUT_MS,
+    });
     const contentType = mediaResponse.headers["content-type"] || "application/octet-stream";
     const buffer = Buffer.from(mediaResponse.data as ArrayBuffer);
 
@@ -313,7 +343,7 @@ export async function downloadMedia(
         const code = err.code ? ` code=${err.code}` : "";
         const statusLabel = status ? ` status=${status}${statusText ? ` ${statusText}` : ""}` : "";
         log.error(
-          `[DingTalk] Failed to download media:${statusLabel}${code} message=${err.message}`,
+          `[DingTalk] Failed to download media: stage=${requestStage} host=${requestHost}${statusLabel}${code} message=${err.message}`,
         );
         if (err.response?.data !== undefined) {
           log.error(formatDingTalkErrorPayloadLog("inbound.downloadMedia", err.response.data));
@@ -321,7 +351,9 @@ export async function downloadMedia(
           log.error(`[DingTalk] downloadMedia response data: ${dataDetail}`);
         }
       } else {
-        log.error(`[DingTalk] Failed to download media: ${err.message}`);
+        log.error(
+          `[DingTalk] Failed to download media: stage=${requestStage} host=${requestHost} message=${err.message}`,
+        );
       }
     }
     return null;
@@ -1019,7 +1051,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   // 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;
+  let currentAICard: import("./types").AICardInstance | undefined;
 
   if (useCardMode) {
     try {
@@ -1033,6 +1065,15 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       });
       if (aiCard) {
         currentAICard = aiCard;
+        if (aiCard.outTrackId) {
+          registerCardRun(aiCard.outTrackId, {
+            accountId,
+            sessionKey: route.sessionKey,
+            agentId: route.agentId,
+            ownerUserId: senderId,
+            card: aiCard,
+          });
+        }
       } else {
         useCardMode = false;
         log?.warn?.(
@@ -1098,6 +1139,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     log?.warn?.(`[DingTalk] Message context inbound append failed: ${String(err)}`);
   }
 
+  const robotCode = resolveRobotCode(dingtalkConfig);
   let mediaPath: string | undefined;
   let mediaType: string | undefined;
   let attachmentContextMsgId = data.msgId;
@@ -1109,7 +1151,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   if (preDownloadedMedia?.mediaPath) {
     mediaPath = preDownloadedMedia.mediaPath;
     mediaType = preDownloadedMedia.mediaType;
-  } else if (content.mediaPath && dingtalkConfig.robotCode) {
+  } else if (content.mediaPath && robotCode) {
     // Download media only if not pre-downloaded
     const media = await downloadMedia(dingtalkConfig, content.mediaPath, log);
     if (media) {
@@ -1253,7 +1295,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   };
 
   // Quoted picture: download via existing downloadMedia.
-  if (!mediaPath && content.quoted?.mediaDownloadCode && dingtalkConfig.robotCode) {
+  if (!mediaPath && content.quoted?.mediaDownloadCode && robotCode) {
     const media =
       (await tryDownloadFromRecord(quotedRecord)) ||
       (await downloadMedia(dingtalkConfig, content.quoted.mediaDownloadCode, log));
@@ -1274,20 +1316,40 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     }
   }
 
-  // Quoted file/video/audio (unknownMsgType): cache-first, then group file API fallback.
+  // Quoted file/audio/video (file/audio/video msgType) or unknownMsgType:
+  // Step 0 tries direct downloadCode; Steps 1-2 fall back to cache and group file API.
   if (!mediaPath && content.quoted?.isQuotedFile) {
     let fileResolved = false;
 
+    // Step 0: Direct download via downloadCode from quoted payload (file/audio/video msgType).
+    if (!fileResolved && content.quoted.fileDownloadCode && robotCode) {
+      const media = await downloadMedia(dingtalkConfig, content.quoted.fileDownloadCode, log);
+      if (media) {
+        mediaPath = media.path;
+        mediaType = media.mimeType;
+        attachmentContextMsgId = content.quoted.msgId || data.msgId;
+        attachmentContextCreatedAt = content.quoted.fileCreatedAt || data.createAt;
+        attachmentContextMessageType = content.quoted.previewMessageType || "file";
+        attachmentContextFileName = content.quoted.previewFileName;
+        fileResolved = true;
+        log?.debug?.(
+          `[DingTalk][QuotedRef] Downloaded quoted file via direct downloadCode scope=${data.conversationId}`,
+        );
+      }
+    }
+
     // 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;
+    if (!fileResolved) {
+      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.
@@ -1417,6 +1479,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     }
   }
 
+  let attachmentExtractedText: string | undefined;
   if (mediaPath) {
     try {
       const extracted = await extractAttachmentText({
@@ -1439,18 +1502,18 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
           ttlMs: ttlDaysToMs(journalTTLDays),
           topic: null,
         });
+        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 = inboundBody;
-  const learningEnabled = isFeedbackLearningEnabled(dingtalkConfig);
+  const inboundBody = content.text;
+  const inboundText = attachmentExtractedText
+    ? `${inboundBody.trimEnd()}\n\n${attachmentExtractedText}`
+    : inboundBody;
+  const learningEnabled = isLearningEnabled(dingtalkConfig);
   const learningContextBlock = buildLearningContextBlock({
     enabled: learningEnabled,
     storePath: accountStorePath,
@@ -1565,6 +1628,81 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
   log?.info?.(`[DingTalk] Inbound: from=${senderName} text="${content.text.slice(0, 50)}..."`);
 
+  // ---- Pre-lock abort: bypass session lock for stop requests ----
+  // isAbortRequestText matches "/stop", "停止", "stop", "esc", etc.
+  // Calling dispatchReplyWithBufferedBlockDispatcher without holding the lock lets
+  // tryFastAbortFromMessage (inside the SDK) kill any in-flight generation immediately,
+  // rather than waiting for it to finish before the stop message is processed.
+  //
+  // In group chats, DingTalk typically strips @BotName from text.content at the
+  // protocol level before delivery, but as a defensive measure we also strip leading
+  // @mention tokens here (e.g. "@Bot 停止" → "停止") to match the SDK's own behavior
+  // in tryFastAbortFromMessage (which calls stripMentions for group messages).
+  const textForAbortCheck = !isDirect
+    ? inboundText.replace(/^(?:@\S+\s+)*/u, "").trim()
+    : inboundText;
+  if (isAbortRequestText(textForAbortCheck)) {
+    log?.info?.(
+      `[DingTalk] Abort request detected, bypassing session lock for session=${route.sessionKey}`,
+    );
+    // In card mode: capture the abort confirmation text so we can write it into
+    // the card (instead of sending a separate plain text message).
+    let abortConfirmationText: string | undefined;
+    try {
+      await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+        ctx,
+        cfg,
+        dispatcherOptions: {
+          responsePrefix: "",
+          deliver: async (payload) => {
+            if (!payload.text) {
+              log?.debug?.(`[DingTalk] Abort deliver received non-text payload, skipping`);
+              return;
+            }
+            if (currentAICard) {
+              // Card mode: capture text — will be written to card after dispatch.
+              abortConfirmationText = payload.text;
+            } else {
+              try {
+                if (sessionWebhook) {
+                  await sendBySession(dingtalkConfig, sessionWebhook, payload.text, {
+                    log,
+                    accountId,
+                    storePath: accountStorePath,
+                  });
+                } else {
+                  await sendMessage(dingtalkConfig, to, payload.text, {
+                    log,
+                    accountId,
+                    storePath: accountStorePath,
+                    conversationId: groupId,
+                  });
+                }
+              } catch (deliverErr) {
+                log?.warn?.(
+                  `[DingTalk] Abort reply delivery failed: ${getErrorMessage(deliverErr)}`,
+                );
+              }
+            }
+          },
+        },
+      });
+    } catch (abortErr) {
+      log?.warn?.(`[DingTalk] Abort dispatch failed: ${getErrorMessage(abortErr)}`);
+    }
+    // Finalize the card that was created for this message before the abort check.
+    // Without this, the card stays in PROCESSING ("处理中...") indefinitely.
+    if (currentAICard && !isCardInTerminalState(currentAICard.state)) {
+      try {
+        await finishAICard(currentAICard, abortConfirmationText ?? "已停止", log);
+      } catch (cardErr) {
+        log?.warn?.(`[DingTalk] Abort card finalize failed: ${getErrorMessage(cardErr)}`);
+        currentAICard.state = AICardStatus.FAILED;
+      }
+    }
+    return;
+  }
+
   const ackReaction =
     typeof dingtalkConfig.ackReaction === "string"
       ? dingtalkConfig.ackReaction.trim()
@@ -1674,6 +1812,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
   // 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 currentOutTrackId = currentAICard?.outTrackId;
   const shouldTrackDynamicAckReaction =
     (normalizedAckReaction === "emoji" || normalizedAckReaction === "kaomoji")
     && shouldAttachAckReaction;
@@ -1702,6 +1841,19 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
     if (!ackReactionAttached && shouldAttachAckReaction) {
       log?.debug?.("[DingTalk] Native ack reaction unavailable; skipping fallback.");
     }
+    const isCurrentCardStopRequested = () =>
+      Boolean(
+        currentAICard
+        && (
+          currentAICard.state === AICardStatus.STOPPED
+          || (currentOutTrackId && isCardRunStopRequested(currentOutTrackId))
+        ),
+      );
+
+    if (isCurrentCardStopRequested()) {
+      log?.info?.("[DingTalk][CardStop] Skip dispatch because card was already stopped before session lock was acquired");
+      return;
+    }
 
     // ---- Create reply strategy (card or markdown) ----
     const strategy = createReplyStrategy({
@@ -1718,6 +1870,7 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
       log,
       replyQuotedRef,
       deliverMedia: deliverMediaAttachments,
+      isStopRequested: isCurrentCardStopRequested,
     });
 
     try {
@@ -1727,6 +1880,10 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
         dispatcherOptions: {
           responsePrefix: subAgentOptions?.responsePrefix || "",
           deliver: async (payload: ReplyStreamPayload, info?: ReplyChunkInfo) => {
+            if (isCurrentCardStopRequested()) {
+              log?.debug?.("[DingTalk][CardStop] Ignoring reply delivery because stop was already requested");
+              return;
+            }
             try {
               const mediaUrls = extractMediaUrls(payload);
               await strategy.deliver({
@@ -1754,6 +1911,13 @@ export async function handleDingTalkMessage(params: HandleDingTalkMessageParams)
 
     await strategy.finalize();
   } finally {
+    // Only remove the registry entry if no stop was requested. When a stop is
+    // in progress, card-stop-handler may still be running async operations
+    // (finalize card, hide button, gateway abort) that read the record.
+    // In that case, let the 30-minute TTL sweep handle cleanup.
+    if (currentOutTrackId && !isCardRunStopRequested(currentOutTrackId)) {
+      removeCardRun(currentOutTrackId);
+    }
     await waitForDynamicAckDispose({
       dispose: () => dynamicAckReactionController.dispose(MIN_THINKING_REACTION_VISIBLE_MS),
       log,

package/src/message-context-store.ts

@@ -13,6 +13,15 @@ const MAX_RECORDS_PER_SCOPE = 1000;
 export type MessageContextDirection = "inbound" | "outbound";
 export type MessageAliasKind = "inboundMsgId" | "messageId" | "processQueryKey" | "outTrackId" | "cardInstanceId";
 export type MessageDeliveryKind = "session" | "proactive-text" | "proactive-card" | "proactive-media";
+export const DEFAULT_OUTBOUND_SENDER = {
+  senderId: "bot",
+  senderName: "OpenClaw",
+} as const;
+
+/** DingTalk conversation ids usually start with "cid" for group chats; treat this as a heuristic. */
+export function inferConversationChatType(conversationId: string): "direct" | "group" {
+  return conversationId.startsWith("cid") ? "group" : "direct";
+}
 
 export interface MessageRecord {
   msgId: string;
@@ -30,6 +39,12 @@ export interface MessageRecord {
   attachmentTextTruncated?: boolean;
   attachmentFileName?: string;
   quotedRef?: QuotedRef;
+  senderId?: string;
+  senderName?: string;
+  mentions?: string[];
+  chatType?: "direct" | "group";
+  /** Flat quoted target for summary/history lookups; quotedRef remains the authoritative structured link. */
+  quotedMessageId?: string;
   media?: {
     downloadCode?: string;
     spaceId?: string;
@@ -74,6 +89,11 @@ interface BaseUpsertParams {
   attachmentTextTruncated?: boolean;
   attachmentFileName?: string;
   quotedRef?: QuotedRef;
+  senderId?: string;
+  senderName?: string;
+  mentions?: string[];
+  chatType?: "direct" | "group";
+  quotedMessageId?: string;
   media?: {
     downloadCode?: string;
     spaceId?: string;
@@ -214,6 +234,15 @@ function normalizeDelivery(value: unknown): MessageRecord["delivery"] | undefine
   return { messageId, processQueryKey, outTrackId, cardInstanceId, kind };
 }
 
+function normalizeMentions(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  // Preserve the original mention token casing because DingTalk ids may be case-sensitive.
+  const normalized = [...new Set(value.map((item) => String(item || "").trim()).filter(Boolean))];
+  return normalized.length > 0 ? normalized : undefined;
+}
+
 function normalizeMessageRecord(value: unknown): MessageRecord | null {
   const candidate = asRecord(value);
   if (!candidate) {
@@ -256,6 +285,14 @@ function normalizeMessageRecord(value: unknown): MessageRecord | null {
     attachmentFileName:
       typeof candidate.attachmentFileName === "string" ? candidate.attachmentFileName : undefined,
     quotedRef: normalizeQuotedRef(candidate.quotedRef),
+    senderId: typeof candidate.senderId === "string" && candidate.senderId.trim() ? candidate.senderId.trim() : undefined,
+    senderName: typeof candidate.senderName === "string" && candidate.senderName.trim() ? candidate.senderName.trim() : undefined,
+    mentions: normalizeMentions(candidate.mentions),
+    chatType: candidate.chatType === "direct" || candidate.chatType === "group" ? candidate.chatType : undefined,
+    quotedMessageId:
+      typeof candidate.quotedMessageId === "string" && candidate.quotedMessageId.trim()
+        ? candidate.quotedMessageId.trim()
+        : undefined,
     media: normalizeMedia(candidate.media),
     delivery: normalizeDelivery(candidate.delivery),
   };
@@ -411,6 +448,20 @@ function mergeQuotedRef(existing: QuotedRef | undefined, next: QuotedRef | undef
   };
 }
 
+function mergeStringField(existing: string | undefined, next: string | undefined): string | undefined {
+  if (typeof next !== "string" || !next.trim()) {
+    return existing;
+  }
+  return next.trim();
+}
+
+function mergeMentions(existing: string[] | undefined, next: string[] | undefined): string[] | undefined {
+  if (!next) {
+    return existing;
+  }
+  return normalizeMentions(next) || existing;
+}
+
 function mergeMedia(
   existing: MessageRecord["media"] | undefined,
   next: MessageRecord["media"] | undefined,
@@ -556,6 +607,11 @@ function upsertRecord(
     attachmentTextTruncated?: boolean;
     attachmentFileName?: string;
     quotedRef?: QuotedRef;
+    senderId?: string;
+    senderName?: string;
+    mentions?: string[];
+    chatType?: "direct" | "group";
+    quotedMessageId?: string;
     media?: MessageRecord["media"];
     delivery?: MessageRecord["delivery"];
     cleanupCreatedAtTtlDays?: number;
@@ -611,6 +667,11 @@ function upsertRecord(
       params.attachmentFileName,
     ),
     quotedRef: mergeQuotedRef(existing?.quotedRef, normalizedQuotedRef),
+    senderId: mergeStringField(existing?.senderId, params.senderId),
+    senderName: mergeStringField(existing?.senderName, params.senderName),
+    mentions: mergeMentions(existing?.mentions, params.mentions),
+    chatType: params.chatType || existing?.chatType,
+    quotedMessageId: mergeStringField(existing?.quotedMessageId, params.quotedMessageId),
     media: mergeMedia(existing?.media, params.media),
     delivery: mergeDelivery(existing?.delivery, params.delivery),
   };
@@ -785,3 +846,16 @@ export function cleanupExpiredMessageContexts(
 export function clearMessageContextCacheForTest(): void {
   stateCache.clear();
 }
+
+/**
+ * Lists non-expired message-context records for one account/conversation scope in createdAt ascending order.
+ */
+export function listMessageContexts(
+  params: ScopeParams & { nowMs?: number },
+): MessageRecord[] {
+  const nowMs = params.nowMs ?? Date.now();
+  const state = loadState(params, nowMs);
+  return state.recentByCreatedAt
+    .map((msgId) => state.records[msgId])
+    .filter((record): record is MessageRecord => Boolean(record) && !isRecordExpired(record, nowMs));
+}

package/src/message-utils.ts

@@ -188,6 +188,18 @@ function buildRepliedMessagePreview(params: {
     };
   }
 
+  if (repliedMsgType === "file" || repliedMsgType === "audio" || repliedMsgType === "video") {
+    const hasFileName = repliedMsgType === "file";
+    return {
+      isQuotedFile: true,
+      fileCreatedAt: repliedMsg.createdAt,
+      previewText: buildQuotedMessageTypePlaceholder(repliedMsgType, hasFileName ? fileName : undefined),
+      previewMessageType: repliedMsgType,
+      ...(hasFileName ? { previewFileName: fileName } : {}),
+      previewSenderId: trimString(repliedMsg.senderId),
+    };
+  }
+
   if (repliedMsgType === "interactiveCard") {
     const isBotCard = repliedMsg.senderId === data.chatbotUserId;
     if (isBotCard) {
@@ -369,6 +381,16 @@ export function extractMessageContent(data: DingTalkInboundMessage): MessageCont
         };
       }
 
+      if (repliedMsgType === "file" || repliedMsgType === "audio" || repliedMsgType === "video") {
+        return {
+          isQuotedFile: true,
+          fileCreatedAt: repliedMsg.createdAt,
+          fileDownloadCode: trimString(content?.downloadCode),
+          msgId: repliedMsgId,
+          ...repliedPreview,
+        };
+      }
+
       if (repliedMsgType === "interactiveCard") {
         const isBotCard = repliedMsg.senderId === data.chatbotUserId;
         if (isBotCard) {