feat(card): implement hybrid API routing for v2 card template

Route blockList (loopArray) via instances API to avoid 500 errors,
while keeping content/taskInfo on streaming API for real-time updates.
Adds updateAICardBlockList, streamAICardContent, clearAICardStreamingContent,
and commitAICardBlocks with token refresh for long-lived cards.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: soimy

src/card-service.ts

@@ -751,7 +751,7 @@ export async function createAICard(
     // Status is set to "streaming" via the streaming API immediately after creation.
     const cardParamMap = {
       config: JSON.stringify({ autoLayout: true, enableForward: true }),
-      [template.contentKey]: "[]",
+      [template.blockListKey]: "[]",
       stop_action: STOP_ACTION_VISIBLE,
       taskInfo: JSON.stringify({ model: "", effort: "", dap_usage: 0, taskTime: 0 }),
       content: "",
@@ -855,11 +855,9 @@ 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.
+    // kick the card into streaming mode immediately so the UI shows "输出中".
     try {
-      await putAICardStreamingField(aiCardInstance, template.contentKey, "[]", false, log);
+      await putAICardStreamingField(aiCardInstance, template.streamingKey, "", false, log);
       aiCardInstance.state = AICardStatus.INPUTING;
     } catch (kickErr: any) {
       log?.debug?.(`[DingTalk][AICard] Non-critical: failed to kick card into streaming mode: ${kickErr.message}`);
@@ -901,31 +899,16 @@ export async function streamAICard(
     );
     return;
   }
-  const template = DINGTALK_CARD_TEMPLATE;
 
   try {
-    // On finalize, write the copy-action content BEFORE closing the stream.
-    // Once isFinalize=true is sent, the card may reject further streaming PUTs.
-    if (finished) {
-      const plainTextContent = extractAnswerTextFromBlockContent(content);
-      if (plainTextContent.trim()) {
-        try {
-          await putAICardStreamingField(card, template.copyKey, plainTextContent, false, log);
-        } catch (contentErr: any) {
-          log?.debug?.(
-            `[DingTalk][AICard] Non-critical: failed to sync content variable for copy action: ${contentErr.message}`,
-          );
-        }
-      }
-    }
-    await putAICardStreamingField(card, template.contentKey, content, finished, log);
-    card.lastStreamedContent = content;
+    // HYBRID: Use instances API for blockList (not streaming API)
+    // Streaming API returns 500 for complex loopArray types
     if (finished) {
-      card.state = AICardStatus.FINISHED;
-      removePendingCard(card, log);
-    } else if (card.state === AICardStatus.PROCESSING) {
-      card.state = AICardStatus.INPUTING;
+      await commitAICardBlocks(card, content, true, log);
+    } else {
+      await updateAICardBlockList(card, content, log);
     }
+    // State changes and lastStreamedContent are handled by the above functions
   } catch (err: any) {
     card.state = AICardStatus.FAILED;
     card.lastUpdated = Date.now();
@@ -984,6 +967,133 @@ export async function streamTaskInfo(
   await putAICardStreamingField(card, "taskInfo", JSON.stringify(taskInfo), false, log);
 }
 
+/**
+ * Update blockList via instances API (avoids 500 error for loopArray type).
+ * This is the primary method for updating structured card content.
+ */
+export async function updateAICardBlockList(
+  card: AICardInstance,
+  blockListJson: string,
+  log?: Logger,
+): Promise<void> {
+  if (isCardInTerminalState(card.state)) {
+    log?.debug?.(
+      `[DingTalk][AICard] Skip blockList update because card already terminal: outTrackId=${card.cardInstanceId} state=${card.state}`,
+    );
+    return;
+  }
+  const template = DINGTALK_CARD_TEMPLATE;
+  const tokenAge = Date.now() - card.createdAt;
+  const tokenRefreshThreshold = 90 * 60 * 1000;
+
+  // Refresh token if aged (same logic as putAICardStreamingField)
+  if (tokenAge > tokenRefreshThreshold && card.config) {
+    log?.debug?.("[DingTalk][AICard] Token age exceeds threshold, refreshing for blockList update...");
+    try {
+      card.accessToken = await getAccessToken(card.config, log);
+      log?.debug?.("[DingTalk][AICard] Token refreshed successfully for blockList update");
+    } catch (err: any) {
+      log?.warn?.(`[DingTalk][AICard] Failed to refresh token for blockList update: ${err.message}`);
+    }
+  }
+
+  const token = card.accessToken || (card.config ? await getAccessToken(card.config, log) : "");
+  if (!token) {
+    throw new Error("No access token available for blockList update");
+  }
+
+  try {
+    await updateCardVariables(
+      card.outTrackId || card.cardInstanceId,
+      { [template.blockListKey]: blockListJson },
+      token,
+      card.config ? { bypassProxyForSend: card.config.bypassProxyForSend } : {},
+    );
+    card.lastStreamedContent = blockListJson;
+    card.lastUpdated = Date.now();
+    incrementCardDapiCount(card);
+    if (card.state === AICardStatus.PROCESSING) {
+      card.state = AICardStatus.INPUTING;
+    }
+  } catch (err: any) {
+    log?.error?.(`[DingTalk][AICard] blockList update failed: ${err.message}`);
+    if (card.accountId && shouldTriggerAICardDegrade(err)) {
+      activateAICardDegrade(
+        card.accountId,
+        `card.blockList:${err?.response?.status || "unknown"}`,
+        card.config,
+        log,
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Stream content to the streaming key for real-time preview.
+ * Only used when cardRealTimeStream=true for low-latency text display.
+ */
+export async function streamAICardContent(
+  card: AICardInstance,
+  text: string,
+  log?: Logger,
+): Promise<void> {
+  const template = DINGTALK_CARD_TEMPLATE;
+  await putAICardStreamingField(card, template.streamingKey, text, false, log);
+}
+
+/**
+ * Clear the streaming content variable at block boundaries.
+ * Called before committing new blocks to avoid stale content display.
+ */
+export async function clearAICardStreamingContent(
+  card: AICardInstance,
+  log?: Logger,
+): Promise<void> {
+  const template = DINGTALK_CARD_TEMPLATE;
+  try {
+    await putAICardStreamingField(card, template.streamingKey, "", false, log);
+  } catch (err: any) {
+    log?.debug?.(`[DingTalk][AICard] Non-critical: failed to clear streaming content: ${err.message}`);
+  }
+}
+
+/**
+ * Commit blocks with final content sync. Used at finalize time.
+ * 1. Sync plain-text content for copy action
+ * 2. Update blockList via instances API
+ */
+export async function commitAICardBlocks(
+  card: AICardInstance,
+  blockListJson: string,
+  isFinalize: boolean,
+  log?: Logger,
+): Promise<void> {
+  const template = DINGTALK_CARD_TEMPLATE;
+
+  // On finalize, sync plain-text content for copy action BEFORE blockList update
+  if (isFinalize) {
+    const plainTextContent = extractAnswerTextFromBlockContent(blockListJson);
+    if (plainTextContent.trim()) {
+      try {
+        await putAICardStreamingField(card, template.copyKey, plainTextContent, false, log);
+      } catch (contentErr: any) {
+        log?.debug?.(
+          `[DingTalk][AICard] Non-critical: failed to sync content for copy action: ${contentErr.message}`,
+        );
+      }
+    }
+  }
+
+  // Update blockList via instances API (not streaming API - avoids 500 error)
+  await updateAICardBlockList(card, blockListJson, log);
+
+  if (isFinalize) {
+    card.state = AICardStatus.FINISHED;
+    removePendingCard(card, log);
+  }
+}
+
 export async function finishAICard(
   card: AICardInstance,
   content: string,
@@ -1005,8 +1115,8 @@ export async function finishAICard(
     }
   }
 
-  // Finalize the card stream (isFinalize=true).
-  await streamAICard(card, content, true, log);
+  // Commit blocks via instances API with content sync
+  await commitAICardBlocks(card, content, true, log);
 
   // v2 template does not have a stop button in finished state, no need to hide.
 
@@ -1037,25 +1147,11 @@ export async function finishStoppedAICard(
     );
     return;
   }
-  const template = DINGTALK_CARD_TEMPLATE;
   try {
-    // Sync the plain-text content variable BEFORE finalizing the blockList.
-    // DingTalk may reject updates after isFinalize=true, so content must come first.
-    const plainTextContent = extractAnswerTextFromBlockContent(content);
-    if (plainTextContent.trim()) {
-      try {
-        await putAICardStreamingField(card, template.copyKey, plainTextContent, false, log);
-      } catch (contentErr: any) {
-        log?.debug?.(
-          `[DingTalk][AICard] Non-critical: failed to sync content variable on stop: ${contentErr.message}`,
-        );
-      }
-    }
-    // Now finalize the blockList with isFinalize=true.
-    await putAICardStreamingField(card, template.contentKey, content, true, log);
+    // HYBRID: commit via instances API (not streaming API)
+    await commitAICardBlocks(card, 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.
+    // Ensure local state is consistent even when the API call fails.
     card.lastStreamedContent = content;
     card.state = AICardStatus.STOPPED;
     card.lastUpdated = Date.now();

src/card/card-template.ts

@@ -3,24 +3,42 @@ export const STOP_ACTION_VISIBLE = "true";
 /** Card variable value that hides the stop button. */
 export const STOP_ACTION_HIDDEN = "false";
 
-/** The v2 template ID that ships with this plugin version. */
-const BUILTIN_TEMPLATE_ID = "9a9138ed-35d3-498e-9019-748b59ddc39a.schema";
-/** Card variable key for structured block streaming. */
-const BUILTIN_CONTENT_KEY = "blockList";
-/** Card variable key for the copy action (plain text representation). */
+/** The v2 template ID that supports streaming via content key. */
+const BUILTIN_TEMPLATE_ID =
+  process.env.DINGTALK_CARD_TEMPLATE_ID || "5db37f25-ac9e-4250-9c1d-c4ddba6e16e9.schema";
+/** Key for blockList updates via instances API (complex loopArray type). */
+const BUILTIN_BLOCKLIST_KEY = "blockList";
+/** Key for real-time streaming via streaming API (simple string type). */
+const BUILTIN_STREAMING_KEY = "content";
+/** Key for the plain text copy action variable (same as streaming key). */
 const BUILTIN_COPY_KEY = "content";
+/** Key for taskInfo streaming via streaming API (simple JSON string type). */
+const BUILTIN_TASKINFO_KEY = "taskInfo";
 
 export interface DingTalkCardTemplateContract {
   templateId: string;
-  /** Content key for block streaming (blockList). */
-  contentKey: string;
+  /** Key for blockList updates via instances API (complex loopArray type). */
+  blockListKey: string;
+  /** Key for real-time streaming via streaming API (simple string type). */
+  streamingKey: string;
   /** Key for the plain text copy action variable. */
   copyKey: string;
+  /** Key for taskInfo streaming (simple JSON string type). */
+  taskInfoKey: string;
+  /** @deprecated Use blockListKey instead. Kept for backward compatibility. */
+  contentKey: string;
 }
 
 /** Frozen singleton — no allocation on every call. */
 export const DINGTALK_CARD_TEMPLATE: Readonly<DingTalkCardTemplateContract> = Object.freeze({
   templateId: BUILTIN_TEMPLATE_ID,
-  contentKey: BUILTIN_CONTENT_KEY,
+  blockListKey: BUILTIN_BLOCKLIST_KEY,
+  streamingKey: BUILTIN_STREAMING_KEY,
   copyKey: BUILTIN_COPY_KEY,
+  taskInfoKey: BUILTIN_TASKINFO_KEY,
+  contentKey: BUILTIN_BLOCKLIST_KEY, // backward compatibility alias
 });
+
+// Legacy exports for backward compatibility
+export const BUILTIN_DINGTALK_CARD_TEMPLATE_ID = BUILTIN_TEMPLATE_ID;
+export const BUILTIN_DINGTALK_CARD_CONTENT_KEY = BUILTIN_BLOCKLIST_KEY;

tests/unit/card-draft-controller.test.ts

@@ -10,6 +10,10 @@ vi.mock("../../src/card-service", async (importOriginal) => {
         ...actual,
         streamAICard: vi.fn(),
         updatePendingCardLastContent: vi.fn(),
+        updateAICardBlockList: vi.fn(),
+        streamAICardContent: vi.fn(),
+        clearAICardStreamingContent: vi.fn(),
+        commitAICardBlocks: vi.fn(),
     };
 });