@soimy/dingtalk 3.5.0 → 3.5.2

package/src/card-draft-controller.ts

@@ -25,6 +25,7 @@ export interface CardDraftController {
     updateAnswer: (text: string) => Promise<void>;
     updateReasoning: (text: string) => Promise<void>;
     updateThinking: (text: string) => Promise<void>;
+    appendThinkingBlock: (text: string) => Promise<void>;
     updateTool: (text: string) => Promise<void>;
     appendTool: (text: string) => Promise<void>;
     /** Signal that a new assistant turn has started (e.g. after a tool call). */
@@ -116,6 +117,10 @@ export function createCardDraftController(params: {
         return timelineEntries.length - 1;
     };
 
+    const findCurrentSegmentAnswerIndex = (): number | null => {
+        return activeAnswerIndex;
+    };
+
     const renderTimeline = (options: {
         fallbackAnswer?: string;
         overrideAnswer?: string;
@@ -292,6 +297,32 @@ export function createCardDraftController(params: {
         queueRender();
     };
 
+    const appendThinkingBlock = async (text: string) => {
+        await waitForPendingBoundary();
+        if (stopped || failed) {
+            return;
+        }
+        const normalized = normalizeProcessText(text);
+        if (!normalized) {
+            return;
+        }
+        if (timelineEntries.length > 0) {
+            await flushBoundaryFrame();
+        }
+        sealLiveThinking();
+        const currentSegmentAnswerIndex = findCurrentSegmentAnswerIndex();
+        if (currentSegmentAnswerIndex !== null) {
+            timelineEntries.splice(currentSegmentAnswerIndex, 0, { kind: "thinking", text: normalized });
+            if (activeAnswerIndex !== null && activeAnswerIndex >= currentSegmentAnswerIndex) {
+                activeAnswerIndex += 1;
+            }
+        } else {
+            sealCurrentAnswer();
+            appendTimelineEntry("thinking", normalized);
+        }
+        queueRender();
+    };
+
     const notifyNewAssistantTurn = async () => {
         if (stopped || failed) {
             return;
@@ -311,6 +342,7 @@ export function createCardDraftController(params: {
         updateAnswer,
         updateReasoning,
         updateThinking: updateReasoning,
+        appendThinkingBlock,
         updateTool,
         appendTool: updateTool,
         notifyNewAssistantTurn,

package/src/card-service.ts

@@ -1,8 +1,10 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import axios from "axios";
+import axios from "./http-client";
 import { getAccessToken } from "./auth";
+import { updateCardVariables } from "./card-callback-service";
+import { DINGTALK_CARD_TEMPLATE, STOP_ACTION_VISIBLE, STOP_ACTION_HIDDEN } from "./card/card-template";
 import { resolveRobotCode, stripTargetPrefix } from "./config";
 import { resolveOriginalPeerId } from "./peer-id-registry";
 import {
@@ -42,6 +44,26 @@ const CARD_CACHE_MAX_CONVERSATIONS = 500;
 const DYNAMIC_SUMMARY_EXTENSION = { dynamicSummary: "true" } as const;
 
 const aicardDegradeByAccount = new Map<string, { untilMs: number; reason: string }>();
+
+export async function hideCardStopButton(
+  outTrackId: string,
+  token: string,
+  config?: { bypassProxyForSend?: boolean },
+  retries = 2,
+): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await updateCardVariables(outTrackId, { stop_action: STOP_ACTION_HIDDEN }, token, config);
+      return;
+    } catch (err) {
+      if (attempt >= retries) {
+        throw err;
+      }
+      await new Promise((r) => setTimeout(r, 500 * (attempt + 1)));
+    }
+  }
+}
+
 const inMemoryCardContentStore = new Map<
   string,
   {
@@ -198,6 +220,105 @@ function extractCardProcessQueryKey(payload: unknown): string | undefined {
   return undefined;
 }
 
+async function putAICardStreamingField(
+  card: AICardInstance,
+  key: string,
+  content: string,
+  finished: boolean,
+  log?: Logger,
+): Promise<void> {
+  const tokenAge = Date.now() - card.createdAt;
+  const tokenRefreshThreshold = 90 * 60 * 1000;
+  let tokenAlreadyRefreshed = false;
+
+  if (tokenAge > tokenRefreshThreshold && card.config) {
+    log?.debug?.("[DingTalk][AICard] Token age exceeds threshold, refreshing...");
+    try {
+      card.accessToken = await getAccessToken(card.config, log);
+      tokenAlreadyRefreshed = true;
+      log?.debug?.("[DingTalk][AICard] Token refreshed successfully");
+    } catch (err: any) {
+      log?.warn?.(`[DingTalk][AICard] Failed to refresh token: ${err.message}`);
+    }
+  }
+
+  const streamBody: AICardStreamingRequest = {
+    outTrackId: card.outTrackId || card.cardInstanceId,
+    guid: randomUUID(),
+    key,
+    content,
+    isFull: true,
+    isFinalize: finished,
+    isError: false,
+  };
+
+  log?.debug?.(
+    `[DingTalk][AICard] PUT /v1.0/card/streaming key=${key} contentLen=${content.length} isFull=true isFinalize=${finished} guid=${streamBody.guid} payload=${JSON.stringify(streamBody)}`,
+  );
+
+  const requestConfig = {
+    headers: {
+      "x-acs-dingtalk-access-token": card.accessToken,
+      "Content-Type": "application/json",
+    },
+    ...(card.config ? getProxyBypassOption(card.config) : {}),
+  };
+
+  try {
+    const streamResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, requestConfig);
+    log?.debug?.(
+      `[DingTalk][AICard] Streaming response: status=${streamResp.status}, data=${JSON.stringify(streamResp.data)}`,
+    );
+    card.lastUpdated = Date.now();
+  } catch (err: any) {
+    if (err.response?.status === 401 && card.config && !tokenAlreadyRefreshed) {
+      log?.warn?.("[DingTalk][AICard] Received 401 error, attempting token refresh and retry...");
+      try {
+        card.accessToken = await getAccessToken(card.config, log);
+        const retryResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, {
+          ...requestConfig,
+          headers: {
+            ...requestConfig.headers,
+            "x-acs-dingtalk-access-token": card.accessToken,
+          },
+        });
+        log?.debug?.(
+          `[DingTalk][AICard] Retry after token refresh succeeded: status=${retryResp.status}`,
+        );
+        card.lastUpdated = Date.now();
+        return;
+      } catch (retryErr: any) {
+        log?.error?.(`[DingTalk][AICard] Retry after token refresh failed: ${retryErr.message}`);
+        if (retryErr.response?.data !== undefined) {
+          log?.error?.(
+            formatDingTalkErrorPayloadLog(
+              "card.stream.retryAfterRefresh",
+              retryErr.response.data,
+              "[DingTalk][AICard]",
+            ),
+          );
+        }
+      }
+    }
+
+    if (card.accountId && shouldTriggerAICardDegrade(err)) {
+      activateAICardDegrade(
+        card.accountId,
+        `card.stream:${err?.response?.status || "unknown"}`,
+        card.config,
+        log,
+      );
+    }
+    log?.error?.(`[DingTalk][AICard] Streaming update failed: key=${key} ${err.message}`);
+    if (err.response?.data !== undefined) {
+      log?.error?.(
+        formatDingTalkErrorPayloadLog("card.stream", err.response.data, "[DingTalk][AICard]"),
+      );
+    }
+    throw err;
+  }
+}
+
 interface CreateAICardOptions {
   accountId?: string;
   storePath?: string;
@@ -372,7 +493,11 @@ function normalizeRecoveredState(state: string): AICardInstance["state"] {
 
 // Helper to identify card terminal states.
 export function isCardInTerminalState(state: string): boolean {
-  return state === AICardStatus.FINISHED || state === AICardStatus.FAILED;
+  return (
+    state === AICardStatus.FINISHED
+    || state === AICardStatus.STOPPED
+    || state === AICardStatus.FAILED
+  );
 }
 
 export function formatContentForCard(content: string | undefined, type: "thinking" | "tool"): string {
@@ -566,6 +691,7 @@ export async function createAICard(
     const shouldPersistPending =
       options.persistPending ?? Boolean(options.accountId && options.storePath);
     const token = await getAccessToken(config, log);
+    const template = DINGTALK_CARD_TEMPLATE;
     // Use randomUUID to avoid collisions across workers/restarts.
     const cardInstanceId = `card_${randomUUID()}`;
 
@@ -573,18 +699,17 @@ export async function createAICard(
 
     const isGroup = conversationId.startsWith("cid");
 
-    if (!config.cardTemplateId) {
-      throw new Error("DingTalk cardTemplateId is not configured.");
-    }
-
     // DingTalk createAndDeliver API payload.
-    const cardTemplateKey = config.cardTemplateKey || "content";
+    // Note: do NOT include template.statusKey here — the createAndDeliver API may
+    // reject unknown fields if the template variable is not yet provisioned.
+    // Status is set to "streaming" via the streaming API immediately after creation.
     const cardParamMap = {
       config: JSON.stringify({ autoLayout: true, enableForward: true }),
-      [cardTemplateKey]: "",
+      [template.contentKey]: "",
+      stop_action: STOP_ACTION_VISIBLE,
     };
     const createAndDeliverBody = {
-      cardTemplateId: config.cardTemplateId,
+      cardTemplateId: template.templateId,
       outTrackId: cardInstanceId,
       cardData: {
         cardParamMap,
@@ -674,6 +799,19 @@ export async function createAICard(
     }
 
     clearAICardDegrade(accountId, log);
+
+    // Kick the card into streaming mode immediately so the UI shows "输出中" and the
+    // stop button becomes visible. Without this, the card sits in "创建中" skeleton state
+    // until the first real content arrives — which may never happen for non-streaming replies.
+    // This sends an empty content stream (isFull=true, isFinalize=false) which transitions
+    // the card from PROCESSING to INPUTING on the DingTalk side.
+    try {
+      await putAICardStreamingField(aiCardInstance, template.contentKey, "", false, log);
+      aiCardInstance.state = AICardStatus.INPUTING;
+    } catch (kickErr: any) {
+      log?.debug?.(`[DingTalk][AICard] Non-critical: failed to kick card into streaming mode: ${kickErr.message}`);
+    }
+
     return aiCardInstance;
   } catch (err: any) {
     log?.error?.(`[DingTalk][AICard] Create failed: ${err.message}`);
@@ -704,55 +842,16 @@ export async function streamAICard(
   finished: boolean = false,
   log?: Logger,
 ): Promise<void> {
-  if (card.state === AICardStatus.FINISHED) {
+  if (isCardInTerminalState(card.state)) {
     log?.debug?.(
-      `[DingTalk][AICard] Skip stream update because card already finalized: outTrackId=${card.cardInstanceId}`,
+      `[DingTalk][AICard] Skip stream update because card already terminal: outTrackId=${card.cardInstanceId} state=${card.state}`,
     );
     return;
   }
-
-  // Refresh token defensively before DingTalk 2h token horizon.
-  const tokenAge = Date.now() - card.createdAt;
-  const tokenRefreshThreshold = 90 * 60 * 1000;
-
-  if (tokenAge > tokenRefreshThreshold && card.config) {
-    log?.debug?.("[DingTalk][AICard] Token age exceeds threshold, refreshing...");
-    try {
-      card.accessToken = await getAccessToken(card.config, log);
-      log?.debug?.("[DingTalk][AICard] Token refreshed successfully");
-    } catch (err: any) {
-      log?.warn?.(`[DingTalk][AICard] Failed to refresh token: ${err.message}`);
-    }
-  }
-
-  // Always use full replacement to make client rendering deterministic.
-  const streamBody: AICardStreamingRequest = {
-    outTrackId: card.outTrackId || card.cardInstanceId,
-    guid: randomUUID(),
-    key: card.config?.cardTemplateKey || "content",
-    content: content,
-    isFull: true,
-    isFinalize: finished,
-    isError: false,
-  };
-
-  log?.debug?.(
-    `[DingTalk][AICard] PUT /v1.0/card/streaming contentLen=${content.length} isFull=true isFinalize=${finished} guid=${streamBody.guid} payload=${JSON.stringify(streamBody)}`,
-  );
+  const template = DINGTALK_CARD_TEMPLATE;
 
   try {
-    const streamResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, {
-      headers: {
-        "x-acs-dingtalk-access-token": card.accessToken,
-        "Content-Type": "application/json",
-      },
-      ...(card.config ? getProxyBypassOption(card.config) : {}),
-    });
-    log?.debug?.(
-      `[DingTalk][AICard] Streaming response: status=${streamResp.status}, data=${JSON.stringify(streamResp.data)}`,
-    );
-
-    card.lastUpdated = Date.now();
+    await putAICardStreamingField(card, template.contentKey, content, finished, log);
     card.lastStreamedContent = content;
     if (finished) {
       card.state = AICardStatus.FINISHED;
@@ -761,85 +860,14 @@ export async function streamAICard(
       card.state = AICardStatus.INPUTING;
     }
   } catch (err: any) {
-    // 500 unknownError usually means cardTemplateKey mismatch with template variable names.
-    if (err.response?.status === 500 && err.response?.data?.code === "unknownError") {
-      const usedKey = streamBody.key;
-      const cardTemplateId = card.config?.cardTemplateId || "(unknown)";
-      const errorMsg =
-        `⚠️ **[DingTalk] AI Card 串流更新失败 (500 unknownError)**\n\n` +
-        `这通常是因为 \`cardTemplateKey\` (当前值: \`${usedKey}\`) 与钉钉卡片模板 \`${cardTemplateId}\` 中定义的正文变量名不匹配。\n\n` +
-        `**建议操作**：\n` +
-        `1. 前往钉钉开发者后台检查该模板的“变量管理”\n` +
-        `2. 确保配置中的 \`cardTemplateKey\` 与模板中用于显示内容的字段变量名完全一致\n\n` +
-        `*注意：当前及后续消息将自动转为 Markdown 发送，直到问题修复。*\n` +
-        `*参考文档: https://github.com/soimy/openclaw-channel-dingtalk/blob/main/README.md#3-%E5%BB%BA%E7%AB%8B%E5%8D%A1%E7%89%87%E6%A8%A1%E6%9D%BF%E5%8F%AF%E9%80%89`;
-
-      log?.error?.(
-        `[DingTalk][AICard] Streaming failed with 500 unknownError. Key: ${usedKey}, Template: ${cardTemplateId}. ` +
-          `Verify that "cardTemplateKey" matches the content field variable name in your card template.`,
-      );
-
-      card.state = AICardStatus.FAILED;
-      card.lastUpdated = Date.now();
-      removePendingCard(card, log);
-      await sendTemplateMismatchNotification(card, errorMsg, log);
-      throw err;
-    }
-
-    // Retry once on 401 with refreshed token.
-    if (err.response?.status === 401 && card.config) {
-      log?.warn?.("[DingTalk][AICard] Received 401 error, attempting token refresh and retry...");
-      try {
-        card.accessToken = await getAccessToken(card.config, log);
-        const retryResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, {
-          headers: {
-            "x-acs-dingtalk-access-token": card.accessToken,
-            "Content-Type": "application/json",
-          },
-          ...(card.config ? getProxyBypassOption(card.config) : {}),
-        });
-        log?.debug?.(
-          `[DingTalk][AICard] Retry after token refresh succeeded: status=${retryResp.status}`,
-        );
-        card.lastUpdated = Date.now();
-        card.lastStreamedContent = content;
-        if (finished) {
-          card.state = AICardStatus.FINISHED;
-          removePendingCard(card, log);
-        } else if (card.state === AICardStatus.PROCESSING) {
-          card.state = AICardStatus.INPUTING;
-        }
-        return;
-      } catch (retryErr: any) {
-        log?.error?.(`[DingTalk][AICard] Retry after token refresh failed: ${retryErr.message}`);
-        if (retryErr.response?.data !== undefined) {
-          log?.error?.(
-            formatDingTalkErrorPayloadLog(
-              "card.stream.retryAfterRefresh",
-              retryErr.response.data,
-              "[DingTalk][AICard]",
-            ),
-          );
-        }
-      }
-    }
-
     card.state = AICardStatus.FAILED;
     card.lastUpdated = Date.now();
     removePendingCard(card, log);
-    if (card.accountId && shouldTriggerAICardDegrade(err)) {
-      activateAICardDegrade(
-        card.accountId,
-        `card.stream:${err?.response?.status || "unknown"}`,
-        card.config,
-        log,
-      );
-    }
-    log?.error?.(`[DingTalk][AICard] Streaming update failed: ${err.message}`);
-    if (err.response?.data !== undefined) {
-      log?.error?.(
-        formatDingTalkErrorPayloadLog("card.stream", err.response.data, "[DingTalk][AICard]"),
-      );
+    if (err.response?.status === 500 && err.response?.data?.code === "unknownError") {
+      const errorMsg =
+        "⚠️ **[DingTalk] AI Card 串流更新失败 (500 unknownError)**\n\n"
+        + "这通常表示当前内置模板契约与钉钉侧模板字段不一致，当前及后续消息将自动回退为 Markdown 发送。";
+      await sendTemplateMismatchNotification(card, errorMsg, log);
     }
     throw err;
   }
@@ -853,6 +881,15 @@ export async function finishAICard(
 ): Promise<void> {
   log?.debug?.(`[DingTalk][AICard] Starting finish, final content length=${content.length}`);
   await streamAICard(card, content, true, log);
+  // Hide stop button on normal completion (symmetric with card-stop-handler).
+  if (card.outTrackId && card.config) {
+    try {
+      const token = await getAccessToken(card.config, log);
+      await hideCardStopButton(card.outTrackId, token, card.config);
+    } catch (err: any) {
+      log?.debug?.(`[DingTalk][AICard] Non-critical: failed to hide stop button on finish: ${err.message}`);
+    }
+  }
   if (card.conversationId && content.trim() && card.accountId && card.processQueryKey) {
     const primaryConversationId = card.contextConversationId || card.conversationId;
     cacheCardContentByProcessQueryKey(
@@ -867,6 +904,30 @@ export async function finishAICard(
   }
 }
 
+export async function finishStoppedAICard(
+  card: AICardInstance,
+  content: string,
+  log?: Logger,
+): Promise<void> {
+  if (isCardInTerminalState(card.state)) {
+    log?.debug?.(
+      `[DingTalk][AICard] finishStoppedAICard skipped — already terminal: ${card.state}`,
+    );
+    return;
+  }
+  const template = DINGTALK_CARD_TEMPLATE;
+  try {
+    await putAICardStreamingField(card, template.contentKey, content, true, log);
+  } finally {
+    // Ensure local state is consistent even when the streaming API call fails.
+    // The card is logically stopped regardless of whether DingTalk acknowledged it.
+    card.lastStreamedContent = content;
+    card.state = AICardStatus.STOPPED;
+    card.lastUpdated = Date.now();
+    removePendingCard(card, log);
+  }
+}
+
 function cacheCardContentByProcessQueryKey(
   accountId: string,
   conversationId: string,