@soimy/dingtalk 3.6.6 → 3.6.8

package/src/card-service.ts

@@ -351,10 +351,13 @@ interface CreateAICardOptions {
   statusLine?: string;
 }
 
+type PendingCardRecoveryAction = "finalize" | "recall";
+
 interface PendingCardRecord {
   accountId: string;
   cardInstanceId: string;
   outTrackId?: string;
+  processQueryKey?: string;
   conversationId: string;
   contextConversationId?: string;
   createdAt: number;
@@ -363,6 +366,8 @@ interface PendingCardRecord {
   lastContent?: string;
   lastBlockListJson?: string;
   streamLifecycleOpened?: boolean;
+  /** Recovery action to retry after a remote card update failed. */
+  recoveryAction?: PendingCardRecoveryAction;
 }
 
 interface PendingCardStateFile {
@@ -399,10 +404,12 @@ function normalizePendingState(parsed: Partial<PendingCardStateFile>): PendingCa
         typeof entry.accountId === "string" &&
         typeof entry.cardInstanceId === "string" &&
         (entry.outTrackId === undefined || typeof entry.outTrackId === "string") &&
+        (entry.processQueryKey === undefined || typeof entry.processQueryKey === "string") &&
         typeof entry.conversationId === "string" &&
         (entry.lastContent === undefined || typeof entry.lastContent === "string") &&
         (entry.lastBlockListJson === undefined || typeof entry.lastBlockListJson === "string") &&
-        (entry.streamLifecycleOpened === undefined || typeof entry.streamLifecycleOpened === "boolean"),
+        (entry.streamLifecycleOpened === undefined || typeof entry.streamLifecycleOpened === "boolean") &&
+        (entry.recoveryAction === undefined || entry.recoveryAction === "finalize" || entry.recoveryAction === "recall"),
       ),
     ),
   };
@@ -469,6 +476,7 @@ function upsertPendingCard(card: AICardInstance, storePath?: string, log?: Logge
     accountId: card.accountId,
     cardInstanceId: card.cardInstanceId,
     outTrackId: card.outTrackId,
+    processQueryKey: card.processQueryKey,
     conversationId: card.conversationId,
     contextConversationId: card.contextConversationId,
     createdAt: card.createdAt,
@@ -539,6 +547,33 @@ function removePendingCardById(cardInstanceId: string, storePath?: string, log?:
   writePendingCardState(state, storePath, log);
 }
 
+function retainPendingCardForRecovery(
+  card: AICardInstance,
+  recoveryAction: PendingCardRecoveryAction,
+  log?: Logger,
+): void {
+  if (!card.accountId || !card.storePath) {
+    return;
+  }
+  const state = readPendingCardState(card.storePath, log);
+  const index = state.pendingCards.findIndex((item) => item.cardInstanceId === card.cardInstanceId);
+  if (index < 0) {
+    return;
+  }
+  const existing = state.pendingCards[index];
+  state.pendingCards[index] = {
+    ...existing,
+    state: AICardStatus.FAILED,
+    lastUpdated: Date.now(),
+    lastContent: card.lastStreamedContent ?? existing.lastContent,
+    lastBlockListJson: card.lastBlockListJson ?? existing.lastBlockListJson,
+    streamLifecycleOpened: card.streamLifecycleOpened,
+    recoveryAction,
+  };
+  state.updatedAt = Date.now();
+  writePendingCardState(state, card.storePath, log);
+}
+
 function listPendingCardsByAccount(
   accountId: string,
   storePath?: string,
@@ -713,7 +748,9 @@ async function finalizePendingCardsByAccount(
   }
 
   const pendingCards = listPendingCardsByAccount(accountId, storePath, log).filter(
-    (item) => !isCardInTerminalState(item.state),
+    (item) =>
+      (item.recoveryAction === "recall" && mode === "recover")
+      || (item.recoveryAction !== "recall" && (!isCardInTerminalState(item.state) || item.recoveryAction === "finalize")),
   );
   if (pendingCards.length === 0) {
     return 0;
@@ -741,6 +778,7 @@ async function finalizePendingCardsByAccount(
       accountId: entry.accountId,
       storePath,
       outTrackId: entry.outTrackId,
+      processQueryKey: entry.processQueryKey,
       createdAt: entry.createdAt || Date.now(),
       lastUpdated: entry.lastUpdated || Date.now(),
       state: normalizeRecoveredState(entry.state),
@@ -750,6 +788,12 @@ async function finalizePendingCardsByAccount(
       streamLifecycleOpened: entry.streamLifecycleOpened,
     };
     try {
+      if (entry.recoveryAction === "recall") {
+        if (await recallAICardMessage(card, log)) {
+          finalizedCount += 1;
+        }
+        continue;
+      }
       await finalizeStoppedAICard(card, {
         reason,
         previousContent: entry.lastContent,
@@ -1163,6 +1207,11 @@ export async function commitAICardBlocks(
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
     log?.error?.(`[DingTalk][AICard] Finalize via instances API failed: ${message}`);
+    // The caller cannot finish this card now. Persist a terminal-only recovery
+    // marker so startup retries the neutral close, never the original reply.
+    card.state = AICardStatus.FAILED;
+    card.lastUpdated = Date.now();
+    retainPendingCardForRecovery(card, "finalize", log);
     throw err;
   }
 
@@ -1193,6 +1242,7 @@ export async function streamAICard(
   content: string,
   finished: boolean = false,
   log?: Logger,
+  options: { recoveryAction?: PendingCardRecoveryAction } = {},
 ): Promise<void> {
   if (isCardInTerminalState(card.state)) {
     log?.debug?.(
@@ -1215,7 +1265,9 @@ export async function streamAICard(
   } catch (err: any) {
     card.state = AICardStatus.FAILED;
     card.lastUpdated = Date.now();
-    removePendingCard(card, log);
+    // The remote card may still be visible after any update fails. Keep it
+    // recoverable so startup can close it instead of leaving an orphaned card.
+    retainPendingCardForRecovery(card, options.recoveryAction ?? "finalize", log);
     if (err.response?.status === 500 && err.response?.data?.code === "unknownError") {
       const errorMsg =
         "⚠️ **[DingTalk] AI Card 串流更新失败 (500 unknownError)**\n\n"

package/src/gateway/channel-gateway.ts

@@ -1,6 +1,7 @@
 import { DWClient, TOPIC_CARD, TOPIC_ROBOT } from "dingtalk-stream";
 import { analyzeCardCallback } from "../card-callback-service";
 import { finalizeActiveCardsForAccount, recoverPendingCardsForAccount } from "../card-service";
+import { recoverAskUserQuestionsForAccount } from "../card/ask-user-question";
 import { handleCardAction } from "../card/card-action-handler";
 import { resolveRobotCode, resolveRuntimeConfig } from "../config";
 import { ConnectionManager } from "../connection-manager";
@@ -107,7 +108,16 @@ function instrumentConnectionStages(client: DWClient): void {
   };
 }
 
-const INFLIGHT_TTL_MS = 5 * 60 * 1000;
+// In-flight dedup keys are released ONLY by the `finally` block after
+// `handleDingTalkMessage` settles. There is intentionally NO time-based TTL:
+// the inbound session queue may hold a message for up to
+// `MAX_INBOUND_SESSION_QUEUE_WAIT_MS` (15 minutes), which is longer than the
+// previous 5-minute TTL. Releasing the lock by wall clock while the queued
+// message is still pending let DingTalk retries enter a SECOND in-flight
+// record, and both copies eventually executed — duplicating external side
+// effects. A hung handler now permanently holds its msgId (acceptable: the
+// user-visible symptom is "this message isn't being processed" and recovery
+// is a process restart, not silent duplicate execution).
 const processingDedupKeys = new Map<string, number>();
 export const CHANNEL_INFLIGHT_NAMESPACE_POLICY = "memory-only" as const;
 const inboundCountersByAccount = new Map<
@@ -199,6 +209,23 @@ export function createDingTalkGateway(): NonNullable<DingTalkChannelPlugin["gate
           `[${account.accountId}] Failed to recover unfinished cards: ${err.message}`,
         );
       }
+      try {
+        const recoveredQuestions = await recoverAskUserQuestionsForAccount({
+          storePath: accountStorePath,
+          accountId: account.accountId,
+          config,
+          log: pluginLog,
+        });
+        if (recoveredQuestions > 0) {
+          pluginLog?.info?.(
+            `[${account.accountId}] Invalidated ${recoveredQuestions} unfinished Ask User card(s) from previous runtime`,
+          );
+        }
+      } catch (err: any) {
+        pluginLog?.warn?.(
+          `[${account.accountId}] Failed to recover Ask User cards: ${err.message}`,
+        );
+      }
 
       const useConnectionManager = config.useConnectionManager ?? true;
       const applyStatusPatch = (patch: Record<string, unknown>) => {
@@ -264,6 +291,8 @@ export function createDingTalkGateway(): NonNullable<DingTalkChannelPlugin["gate
                 sessionWebhook: data.sessionWebhook,
                 log: pluginLog,
                 dingtalkConfig: config,
+                inboundOrigin: "stream",
+                inboundQueueEligible: true,
               });
               stats.processed += 1;
               if (stats.received % INBOUND_COUNTER_LOG_EVERY === 0) {
@@ -280,22 +309,17 @@ export function createDingTalkGateway(): NonNullable<DingTalkChannelPlugin["gate
               return;
             }
 
-            const inflightSince = processingDedupKeys.get(dedupKey);
-            if (inflightSince !== undefined) {
-              if (Date.now() - inflightSince > INFLIGHT_TTL_MS) {
-                pluginLog?.warn?.(
-                  `[${account.accountId}] Releasing stale in-flight lock for ${dedupKey} (held ${Date.now() - inflightSince}ms > TTL ${INFLIGHT_TTL_MS}ms)`,
-                );
-                processingDedupKeys.delete(dedupKey);
-              } else {
-                pluginLog?.debug?.(
-                  `[${account.accountId}] Skipping in-flight duplicate message: ${dedupKey}`,
-                );
-                stats.inflightSkipped += 1;
-                acknowledge();
-                logInboundCounters(pluginLog, account.accountId, "inflight-skipped");
-                return;
-              }
+            // In-flight lock: only the `finally` block below ever releases
+            // this key. See `processingDedupKeys` declaration for why we no
+            // longer release by time-based TTL.
+            if (processingDedupKeys.has(dedupKey)) {
+              pluginLog?.debug?.(
+                `[${account.accountId}] Skipping in-flight duplicate message: ${dedupKey}`,
+              );
+              stats.inflightSkipped += 1;
+              acknowledge();
+              logInboundCounters(pluginLog, account.accountId, "inflight-skipped");
+              return;
             }
 
             acknowledge();
@@ -308,6 +332,8 @@ export function createDingTalkGateway(): NonNullable<DingTalkChannelPlugin["gate
                 sessionWebhook: data.sessionWebhook,
                 log: pluginLog,
                 dingtalkConfig: config,
+                inboundOrigin: "stream",
+                inboundQueueEligible: true,
               });
               stats.processed += 1;
               markMessageProcessed(dedupKey);
@@ -382,6 +408,7 @@ export function createDingTalkGateway(): NonNullable<DingTalkChannelPlugin["gate
               analysis,
               cfg,
               accountId: account.accountId,
+              storePath: accountStorePath,
               config,
               log: pluginLog,
             });
@@ -551,19 +578,13 @@ export function createDingTalkGateway(): NonNullable<DingTalkChannelPlugin["gate
               lastError: null,
             });
           } else if (state === ConnectionState.FAILED || state === ConnectionState.DISCONNECTED) {
-            const robotKey = resolveRobotCode(config) || account.accountId;
-            let cleared = 0;
-            for (const key of processingDedupKeys.keys()) {
-              if (key.startsWith(`${robotKey}:`)) {
-                processingDedupKeys.delete(key);
-                cleared++;
-              }
-            }
-            if (cleared > 0) {
-              pluginLog?.info?.(
-                `[${account.accountId}] Cleared ${cleared} stale in-flight lock(s) on disconnect`,
-              );
-            }
+            // Intentionally do NOT clear `processingDedupKeys` here: a stream
+            // disconnect must not release in-flight locks for messages whose
+            // handler is still executing (or queued behind an active run),
+            // because DingTalk will resend on reconnect and a cleared lock
+            // would let the resend enter a SECOND handler invocation —
+            // duplicating external side effects. Only `finally` after the
+            // handler settles releases a key.
             applyStatusPatch({
               running: false,
               connected: false,

package/src/gateway/inbound-session-queue-dispatcher.ts

@@ -0,0 +1,304 @@
+// Authorized inbound serializer: wraps the already-authorized, route-resolved
+// portion of `handleDingTalkMessage` with the promise-chain queue from
+// `inbound-session-queue.ts`.
+//
+// The gateway intentionally does not call this module.  At the gateway boundary
+// we only have raw accountId + conversationId, before DM/group policy, allowlist
+// checks, special-command bypasses, and trusted agent routing.  Queueing there
+// could acknowledge an unauthorized sender or block /stop and /btw.  The caller
+// supplies the resolved route.sessionKey only after those decisions, so a message
+// that arrives while the same real session is active is queued and reprocessed
+// once the active run finishes instead of racing into the core's
+//   "reply session initialization conflicted for <sessionKey>"
+// and being dropped silently at the gateway catch block (the
+// "钉钉'确认'消息无响应" regression.
+//
+// While a message is queued, a pre-created AI Card shows an immediate
+// "已排队" acknowledgement; the handler later reuses that same card
+// (`params.preCreatedCard`) to stream the real reply in place.
+//
+// Ported from DingTalk-Real-AI/dingtalk-openclaw-connector's session-queue
+// orchestrator, adapted to soimy's blocking gateway contract (we await each
+// task so the gateway's per-message dedup stays correct).
+
+import { attachNativeAckReaction } from "../ack-reaction-service";
+import {
+  createAICard,
+  isCardInTerminalState,
+  recallAICardMessage,
+  streamAICard,
+} from "../card-service";
+import {
+  chainInboundSessionTask,
+  getInboundSessionQueueDepth,
+  InboundSessionQueueWaitTimeoutError,
+  isInboundSessionQueueBusy,
+  MAX_INBOUND_SESSION_QUEUE_DEPTH,
+  MAX_INBOUND_SESSION_QUEUE_WAIT_MS,
+  pickQueueBusyAckPhrase,
+} from "./inbound-session-queue";
+import { sendMessage } from "../send-service";
+import type { AICardInstance, DingTalkConfig, DingTalkInboundMessage, Logger } from "../types";
+
+export interface InboundQueueDispatchInput {
+  accountId: string;
+  data: DingTalkInboundMessage;
+  dingtalkConfig: DingTalkConfig;
+  /** Trusted route.sessionKey, resolved after access control. */
+  sessionKey: string;
+  /** Resolved DingTalk reply target for this authorized route. */
+  to: string;
+  storePath?: string;
+  quoteContent?: string;
+  log?: Logger;
+}
+
+const QUEUE_FULL_ACK = "当前消息较多，已达到本会话排队上限；请等待上一轮完成后再发送。";
+const QUEUE_WAIT_TIMEOUT_ACK = "上一轮处理时间较长，这条消息未执行；请稍后重新发送。";
+const QUEUE_HANDLER_FAILURE_ACK = "本次处理异常，未能完成；请稍后重新发送。";
+const MIN_QUEUE_ACK_CARD_VISIBLE_MS = 750;
+
+const queuedAckVisibleAt = new WeakMap<AICardInstance, number>();
+
+function shouldPrepareQueueAckCard(input: InboundQueueDispatchInput): boolean {
+  return input.dingtalkConfig.messageType === "card";
+}
+
+async function keepQueueAckCardVisible(card: AICardInstance): Promise<void> {
+  const visibleAt = queuedAckVisibleAt.get(card);
+  if (!visibleAt) {
+    return;
+  }
+  const remainingMs = MIN_QUEUE_ACK_CARD_VISIBLE_MS - (Date.now() - visibleAt);
+  if (remainingMs > 0) {
+    await new Promise<void>((resolve) => setTimeout(resolve, remainingMs));
+  }
+}
+
+async function settleUnusedQueueAckCard(
+  input: InboundQueueDispatchInput,
+  card: AICardInstance,
+): Promise<void> {
+  if (isCardInTerminalState(card.state)) {
+    return;
+  }
+  try {
+    if (await recallAICardMessage(card, input.log)) {
+      return;
+    }
+  } catch (err: unknown) {
+    input.log?.warn?.(
+      `[DingTalk] Failed to recall unused queue acknowledgement card: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  await sendQueueTerminalAck(input, "已结束排队确认，请以本次实际回复为准。", card);
+}
+
+/**
+ * A visible queue ACK promises that the message will be handled.  If the
+ * queued continuation fails before consuming that card, finish it with a
+ * retryable outcome instead of recalling the only user-visible feedback.
+ */
+async function settleFailedQueueAckCard(
+  input: InboundQueueDispatchInput,
+  card: AICardInstance,
+): Promise<void> {
+  if (isCardInTerminalState(card.state)) {
+    return;
+  }
+  await sendQueueTerminalAck(input, QUEUE_HANDLER_FAILURE_ACK, card);
+}
+
+/**
+ * Serialize an inbound message per conversation, then invoke `handler` (which
+ * should call `handleDingTalkMessage` with the provided `preCreatedCard`).
+ *
+ * The returned promise settles with the handler's own outcome, so the caller
+ * (gateway) can await it and keep its per-message dedup correct
+ * (`markMessageProcessed` only runs once the message truly completes).
+ */
+export async function dispatchInboundViaSessionQueue<T>(
+  input: InboundQueueDispatchInput,
+  handler: (preCreatedCard?: AICardInstance) => Promise<T>,
+): Promise<T> {
+  const queueKey = input.sessionKey;
+  if (!queueKey) {
+    // A trusted route must include a session key. Keep this defensive fallback
+    // for alternate callers rather than inventing a raw gateway-level key.
+    return handler(undefined);
+  }
+  const wasBusy = isInboundSessionQueueBusy(queueKey);
+  if (getInboundSessionQueueDepth(queueKey) >= MAX_INBOUND_SESSION_QUEUE_DEPTH) {
+    await sendQueueTerminalAck(input, QUEUE_FULL_ACK);
+    return undefined as T;
+  }
+  // Detect busyness BEFORE chaining: this call is "busy" only if a PRIOR task
+  // for this conversation is still running.
+  // Start preparing a busy ACK without awaiting it before we reserve a queue
+  // slot below. Otherwise a burst of inbound messages can all observe the
+  // same pre-await depth and each pass the cap check.
+  let queuedAckState: "queued" | "timed-out" = "queued";
+  const preCreatedCardPromise = wasBusy && shouldPrepareQueueAckCard(input)
+    ? tryPrepareQueueAckCard(input, () =>
+        queuedAckState === "timed-out"
+          ? { content: QUEUE_WAIT_TIMEOUT_ACK, finished: true }
+          : { content: pickQueueBusyAckPhrase(), finished: false },
+      )
+    : undefined;
+  // Chain onto the prior task for this conversation and AWAIT. Awaiting (rather
+  // than fire-and-forget) preserves the gateway's per-message dedup:
+  // `markMessageProcessed` runs only after this message truly completes, so a
+  // still-queued message is never marked processed.
+  try {
+    return await chainInboundSessionTask(
+      queueKey,
+      async () => {
+        const preCreatedCard = preCreatedCardPromise
+          ? await preCreatedCardPromise
+          : undefined;
+        if (!preCreatedCard) {
+          return handler(undefined);
+        }
+        await keepQueueAckCardVisible(preCreatedCard);
+        let handlerFailed = false;
+        try {
+          return await handler(preCreatedCard);
+        } catch (err: unknown) {
+          handlerFailed = true;
+          await settleFailedQueueAckCard(input, preCreatedCard);
+          throw err;
+        } finally {
+          if (!handlerFailed && !isCardInTerminalState(preCreatedCard.state)) {
+            await settleUnusedQueueAckCard(input, preCreatedCard);
+          }
+        }
+      },
+      {
+        maxQueueWaitMs: wasBusy ? MAX_INBOUND_SESSION_QUEUE_WAIT_MS : undefined,
+      },
+    );
+  } catch (err: unknown) {
+    if (err instanceof InboundSessionQueueWaitTimeoutError) {
+      queuedAckState = "timed-out";
+      await sendQueueTerminalAck(
+        input,
+        QUEUE_WAIT_TIMEOUT_ACK,
+        preCreatedCardPromise ? await preCreatedCardPromise : undefined,
+      );
+      return undefined as T;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Pre-create an AI Card showing a "已排队" acknowledgement for a message that
+ * arrived while its conversation was busy. The handler later reuses this card
+ * to stream the real reply in place. Best-effort: any failure returns
+ * undefined and the handler falls back to creating a fresh card (or markdown).
+ */
+async function tryPrepareQueueAckCard(
+  input: InboundQueueDispatchInput,
+  ack: () => { content: string; finished: boolean },
+): Promise<AICardInstance | undefined> {
+  const { dingtalkConfig, data, log, to, storePath, quoteContent } = input;
+  if (!data) {
+    return undefined;
+  }
+  if (!to) {
+    return undefined;
+  }
+  let card: AICardInstance | null = null;
+  let ackFinished = false;
+  try {
+    card = await createAICard(dingtalkConfig, to, log, {
+      accountId: input.accountId,
+      storePath,
+      quoteContent,
+    });
+    if (!card) {
+      return undefined;
+    }
+    const { content, finished } = ack();
+    ackFinished = finished;
+    await streamAICard(card, content, finished, log, {
+      recoveryAction: finished ? "finalize" : "recall",
+    });
+    if (!finished) {
+      queuedAckVisibleAt.set(card, Date.now());
+    }
+    if (finished) {
+      return card;
+    }
+    // Best-effort thinking reaction; failures must not block the queue.
+    void attachNativeAckReaction(
+      dingtalkConfig,
+      { msgId: data.msgId, conversationId: data.conversationId },
+      log,
+    ).catch((err: unknown) => {
+      log?.debug?.(
+        `[DingTalk] Queue-busy ack reaction attach failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    });
+    log?.info?.(
+      `[DingTalk] Inbound message queued behind active run for session=${input.sessionKey}; pre-created ACK card outTrackId=${card.cardInstanceId}.`,
+    );
+    return card;
+  } catch (err: unknown) {
+    if (card && !ackFinished) {
+      try {
+        await recallAICardMessage(card, log);
+      } catch (recallErr: unknown) {
+        log?.warn?.(
+          `[DingTalk] Failed to recall queue ACK card after prepare failure: ${recallErr instanceof Error ? recallErr.message : String(recallErr)}`,
+        );
+      }
+    }
+    log?.warn?.(
+      `[DingTalk] Queue-busy ACK card prepare failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+async function sendQueueTerminalAck(
+  input: InboundQueueDispatchInput,
+  content: string,
+  preCreatedCard?: AICardInstance,
+): Promise<void> {
+  const { dingtalkConfig, data, log, to, storePath } = input;
+  try {
+    if (preCreatedCard) {
+      try {
+        await streamAICard(preCreatedCard, content, true, log);
+        return;
+      } catch (err: unknown) {
+        log?.warn?.(
+          `[DingTalk] Queue acknowledgement card finalization failed; falling back to text: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    } else {
+      const card = await tryPrepareQueueAckCard(input, () => ({ content, finished: true }));
+      if (card) {
+        return;
+      }
+    }
+    if (!to) {
+      return;
+    }
+    const result = await sendMessage(dingtalkConfig, to, content, {
+      sessionWebhook: data.sessionWebhook,
+      log,
+      accountId: input.accountId,
+      storePath,
+      conversationId: data.conversationId,
+    });
+    if (!result.ok) {
+      log?.warn?.(`[DingTalk] Queue terminal acknowledgement failed: ${result.error || "unknown"}`);
+    }
+  } catch (err: unknown) {
+    log?.warn?.(
+      `[DingTalk] Queue terminal acknowledgement delivery failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}