chatccc 0.2.50 → 0.2.52

package/src/session.ts

@@ -20,12 +20,6 @@ import {
   ts,
 } from "./config.ts";
 import { buildProgressCard, getToolEmoji, truncateContent } from "./cards.ts";
-import {
-  createCardKitCard,
-  sendCardKitMessage,
-  updateCardKitCard,
-} from "./cardkit.ts";
-import { sendTextReply, setChatAvatar } from "./feishu-platform.ts";
 import { logTrace } from "./trace.ts";
 import type { UnifiedBlock } from "./adapters/adapter-interface.ts";
 import type { ToolAdapter } from "./adapters/adapter-interface.ts";
@@ -33,6 +27,7 @@ import { createClaudeAdapter } from "./adapters/claude-adapter.ts";
 import { createCursorAdapter } from "./adapters/cursor-adapter.ts";
 import { createCodexAdapter } from "./adapters/codex-adapter.ts";
 import { buildImSkillsPrompt, exportSkillSubDocs } from "./im-skills.ts";
+import type { PlatformAdapter } from "./platform-adapter.ts";
 import { readStreamState, writeStreamState, createEmptyStreamState, fixStaleStreamStates } from "./stream-state.ts";
 import {
   bindChatToSession,
@@ -58,6 +53,36 @@ export const MAX_PROCESSED = 5000;
 /** 每个 chatId 上一次已处理消息的时间戳，用于拦截延迟送达的旧消息 */
 export const lastMsgTimestamps = new Map<string, number>();
 
+// ---------------------------------------------------------------------------
+// 平台引用 —— session 模块通过此引用访问 IM 平台操作，
+// 避免 import feishu-platform.ts 造成的耦合。
+// 由 index.ts 在启动时调用 setSessionPlatform 注入。
+// ---------------------------------------------------------------------------
+
+let platformRef: PlatformAdapter | null = null;
+const chatPlatformMap = new Map<string, PlatformAdapter>();
+
+/** 注入当前 IM 平台适配器，供 session 模块使用 */
+export function setSessionPlatform(platform: PlatformAdapter): void {
+  platformRef = platform;
+}
+
+export function recordChatPlatform(chatId: string, platform: PlatformAdapter): void {
+  chatPlatformMap.set(chatId, platform);
+}
+
+export function forgetChatPlatform(chatId: string): void {
+  chatPlatformMap.delete(chatId);
+}
+
+function platformForChat(chatId: string): PlatformAdapter | null {
+  return chatPlatformMap.get(chatId) ?? platformRef;
+}
+
+export function _getPlatformForChatForTest(chatId: string): PlatformAdapter | null {
+  return platformForChat(chatId);
+}
+
 export let sessionGen = 0;
 /** @deprecated 使用 activePrompts (session-chat-binding.ts) + displayCards 替代 */
 export const chatSessionMap = new Map<string, {
@@ -85,6 +110,29 @@ export const sessionInfoMap = new Map<string, {
   tool: string;
 }>();
 
+/**
+ * 清空所有进程内运行时状态。
+ *
+ * ⚠️ 红线：**绝对不要**在飞书 SDK 的 onReady / onReconnected 回调里调用本函数。
+ * SDK 的 WebSocket 重连只是底层连接抖动，业务层（活跃 prompt、display loop、
+ * stream-state 文件、轮数计数）完全不受影响。在重连里调 resetState 会：
+ *   1) `activePrompts.clear()` 只是删 Map，**不会** abort 后台 generator。
+ *      generator 继续跑、继续写 stream-state.json，但 display loop 已被
+ *      stop，用户群里再也看不到任何更新；最终回复永远不发到群。
+ *   2) 该 sessionId 在内存里"看似空闲"，下一条用户消息进来会**第二次进入**
+ *      `runAgentSession`，同一个 cursor/claude session 同时跑两条 prompt，
+ *      输出互相串扰、token 计费翻倍。
+ *   3) `processedMessages` / `lastMsgTimestamps` 被清，SDK 重连后若服务端
+ *      重推已 ack 的消息，去重失效会让同一 prompt 被处理两次。
+ *   4) `sessionInfoMap` 清空后，群再发消息时 nextTurnCount 从 1 重新计数。
+ *
+ * 合法调用点：
+ *   - 单元测试 setup（清测试间状态）
+ *   - 进程首次启动（此时 Map 都是空的，调用纯粹是为了打 LOG）
+ *
+ * SDK 重连场景请改用 `rebuildBindingsFromRegistry()`，它只重建 sessionId →
+ * chatId 映射，不动任何运行时状态。
+ */
 export function resetState(): void {
   for (const entry of chatSessionMap.values()) {
     if (entry.spinnerTimer) clearInterval(entry.spinnerTimer);
@@ -94,7 +142,7 @@ export function resetState(): void {
   sessionInfoMap.clear();
   processedMessages.clear();
   lastMsgTimestamps.clear();
-  // 清理新的全局状态
+  chatPlatformMap.clear();
   activePrompts.clear();
   displayCards.clear();
   for (const stop of displayLoops.values()) stop();
@@ -102,6 +150,9 @@ export function resetState(): void {
   console.log(`[${ts()}] [RESET] State cleared (dedup + active sessions + bindings)`);
 }
 
+// 注:`rebuildBindingsFromRegistry` 定义在下方与 loadSessionRegistry 同区域,
+// 是 onReady/onReconnected 取代 resetState 的正确入口。
+
 // ---------------------------------------------------------------------------
 // Adapter: 按 tool 创建并缓存
 // ---------------------------------------------------------------------------
@@ -235,6 +286,26 @@ export async function loadSessionRegistryForBinding(): Promise<SessionRegistryDa
   return loadSessionRegistry();
 }
 
+/**
+ * 从持久化的 registry 重建 sessionId → chatId 映射。
+ *
+ * 设计契约（替代之前 onReady/onReconnected 误用的 resetState）：
+ *   - **不动** activePrompts：后台 prompt 在 SDK 重连后必须继续被识别为活跃,
+ *     否则下条用户消息会绕过 isSessionRunning 检查再开一条 prompt,
+ *     导致同一 sessionId 双开 generator
+ *   - **不动** sessionInfoMap：内存里的轮数/contextTokens 比 registry 更新
+ *   - **不动** displayCards / displayLoops：正在跑的 prompt 还需要它们继续推卡片
+ *   - **不动** processedMessages / lastMsgTimestamps：SDK 重连若重推已 ack 消息,
+ *     去重 set 还在才能避免同一 prompt 跑两遍
+ *
+ * 唯一被重建的是 sessionChatsMap（通过调用 rebuildSessionChatsFromRegistry）——
+ * 该 Map 是从 registry 派生的纯只读映射,重建是幂等且廉价的。
+ */
+export async function rebuildBindingsFromRegistry(): Promise<void> {
+  const registry = await loadSessionRegistry();
+  rebuildSessionChatsFromRegistry(registry);
+}
+
 async function saveSessionRegistry(data: SessionRegistryData): Promise<void> {
   try {
     await mkdir(dirname(sessionRegistryFile), { recursive: true });
@@ -379,6 +450,118 @@ export function accumulateBlockContent(
   }
 }
 
+// ---------------------------------------------------------------------------
+// switchChatBinding — /newh、/session N 共用的事务式"切换 chat 绑定"
+// ---------------------------------------------------------------------------
+//
+// 设计契约（解决三类历史 bug）：
+//
+//   1. 私聊不能调 updateChatInfo（飞书 API 在 p2p chatId 上会返回非 0 → throw）。
+//      之前的实现没判断 chatType,私聊 /newh、/session N 走到 updateChatInfo
+//      就直接抛错,留下"内存已切换、registry 没更新"的脏状态。
+//
+//   2. updateChatInfo 群聊也可能因为网络/频控失败。之前的代码顺序是
+//        先 unbind 旧 → bind 新 → 再调 updateChatInfo
+//      API 失败后内存绑定已经切走,但群 description 还是旧 sessionId。
+//      下次用户在群里发消息时,extractSessionInfo 拿到旧 sessionId,而内存绑定
+//      指向新 sessionId,路由完全错乱（参考 /newh 的 corner case 7）。
+//
+//   3. 改成"先 API 后内存"的顺序后,API 失败就完全不切换内存,下次消息按
+//      旧 description 正常路由到旧 session,新创建的 session 留在 sessions.json
+//      里成为可清理的 orphan。
+//
+// 调用方约定：
+//   - newSessionId 必须是已经 createSession 完成的真实 session（本函数不创建）
+//   - oldSessionId 为 null 表示当前 chat 没有任何旧绑定（比如私聊首次绑）
+//   - 私聊跳过 updateChatInfo,直接做内存切换 + registry 持久化
+//   - API 失败时：
+//       * 不动内存绑定 / sessionInfoMap / displayCards
+//       * 返回 { ok: false, error }
+//       * 调用方负责把错误反馈给用户
+// ---------------------------------------------------------------------------
+
+export interface SwitchChatBindingArgs {
+  chatId: string;
+  chatType: string;
+  oldSessionId: string | null;
+  newSessionId: string;
+  tool: string;
+  /** 群名（私聊忽略） */
+  chatName: string;
+  /** 群描述（私聊忽略），通常为 `${sessionPrefixForTool(tool)} ${newSessionId}` */
+  newDescription: string;
+  /** 切换后 sessionInfoMap 的初始 turnCount/lastContextTokens（如沿用历史） */
+  initialTurnCount?: number;
+  initialContextTokens?: number;
+  /** 飞书 updateChatInfo 实现，依赖注入便于测试 mock */
+  updateChatInfoFn: (chatId: string, name: string, description: string) => Promise<void>;
+}
+
+export interface SwitchChatBindingResult {
+  ok: boolean;
+  error?: Error;
+}
+
+export async function switchChatBinding(args: SwitchChatBindingArgs): Promise<SwitchChatBindingResult> {
+  const {
+    chatId,
+    chatType,
+    oldSessionId,
+    newSessionId,
+    tool,
+    chatName,
+    newDescription,
+    initialTurnCount = 0,
+    initialContextTokens = 0,
+    updateChatInfoFn,
+  } = args;
+
+  // Step 1: 群聊场景先调用飞书 API（不可逆操作放最前）。
+  // 私聊跳过——p2p chatId 调 updateChatInfo 必然失败。
+  if (chatType !== "p2p") {
+    try {
+      await updateChatInfoFn(chatId, chatName, newDescription);
+    } catch (err) {
+      // API 失败：完全不动内存,调用方负责回报用户。
+      return { ok: false, error: err as Error };
+    }
+  }
+
+  // Step 2: API 成功（或私聊跳过）后,原子地切换内存绑定。
+  // 这一段全是同步 Map 操作,不会失败。
+  if (oldSessionId) {
+    unbindChatFromSession(oldSessionId, chatId);
+    displayCards.delete(chatId);
+  }
+  bindChatToSession(newSessionId, chatId);
+  recordLastActiveChat(newSessionId, chatId);
+
+  const now = Date.now();
+  sessionInfoMap.set(chatId, {
+    sessionId: newSessionId,
+    turnCount: initialTurnCount,
+    lastContextTokens: initialContextTokens,
+    startTime: now,
+    tool,
+  });
+
+  // Step 3: 持久化（registry + sessions.json）。
+  // 这两步即使失败也不影响内存正确性,下次 prompt 会再写一次。
+  await recordSessionRegistry({
+    chatId,
+    sessionId: newSessionId,
+    tool,
+    chatName,
+    turnCount: initialTurnCount,
+    lastContextTokens: initialContextTokens,
+    startTime: now,
+    running: false,
+  });
+  await saveSessionTool(newSessionId, tool, chatName);
+
+  return { ok: true };
+}
+
 // ---------------------------------------------------------------------------
 // AI tool session management
 // ---------------------------------------------------------------------------
@@ -425,13 +608,13 @@ export async function initClaudeSession(tool: string, overrideCwd?: string, chat
 export async function resumeAndPrompt(
   sessionId: string,
   userText: string,
-  token: string,
+  platform: PlatformAdapter,
   chatId: string,
   msgTimestamp: number,
   tool: string,
   traceId?: string,
 ): Promise<void> {
-  return runAgentSession(sessionId, userText, token, chatId, msgTimestamp, tool, traceId);
+  return runAgentSession(sessionId, userText, platform, chatId, msgTimestamp, tool, traceId);
 }
 
 // ---------------------------------------------------------------------------
@@ -441,7 +624,7 @@ export async function resumeAndPrompt(
 export async function runAgentSession(
   sessionId: string,
   userText: string,
-  token: string,
+  platform: PlatformAdapter,
   _chatId: string,
   msgTimestamp: number,
   tool: string,
@@ -450,47 +633,23 @@ export async function runAgentSession(
   const tid = traceId ?? "";
 
   // 记录用户最后发送消息的群（display loop 只推送到该群）
+  recordChatPlatform(_chatId, platform);
   recordLastActiveChat(sessionId, _chatId);
 
   // 并发检查：同一 session 只能有一个活跃 prompt
   if (activePrompts.has(sessionId)) {
     if (tid) logTrace(tid, "BLOCKED", { outcome: "session_busy", sessionId });
     console.log(`[${ts()}] [BLOCKED] Session ${sessionId} is already generating`);
-    await sendTextReply(token, _chatId, "该会话正在生成回复中，请等待完成后再发送消息。").catch(() => {});
+    const isWechatBusy = platform.kind === "wechat";
+    const busyMsg = isWechatBusy
+      ? "当前正在生成回复中，请等待完成后再发送消息。如需中断生成，请发送 /stop 指令。"
+      : "该会话正在生成回复中，请等待完成后再发送消息。";
+    await platform.sendText(_chatId, busyMsg).catch(() => {});
     return;
   }
 
-  const adapter = getAdapterForTool(tool);
-  const info = await adapter.getSessionInfo(sessionId);
-  const cwd = info?.cwd ?? (await getDefaultCwd(_chatId));
-  if (tid) logTrace(tid, "SESSION_START", { sessionId, tool, cwd, turn: (sessionInfoMap.get(_chatId)?.turnCount ?? 0) + 1 });
-  console.log(
-    `[${ts()}] Running ${adapter.displayName} session: ${sessionId} (${formatToolConfigForLog(tool, info?.model)}, cwd=${cwd})`
-  );
-
-  // 构建 IM skills prompt（sessionId 方式，无 token）
-  const feishuSkillDir = join(PROJECT_ROOT, "im-skills", "feishu-skill");
-  const imSkillsCacheDir = join(USER_DATA_DIR, "im-skills");
-  const skillVariables = {
-    cwd,
-    session_id: sessionId,
-    im_skills_cache_dir: imSkillsCacheDir,
-    send_image_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-image`,
-    send_file_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-file`,
-    send_image_script: join(feishuSkillDir, "send-image.mjs"),
-    send_file_script: join(feishuSkillDir, "send-file.mjs"),
-    download_video_script: join(feishuSkillDir, "download-video.mjs"),
-  };
-  const imSkillsPrompt = await buildImSkillsPrompt({ variables: skillVariables });
-  await exportSkillSubDocs({ variables: skillVariables }, imSkillsCacheDir);
-  const userTextWithCapabilities = [
-    ...(imSkillsPrompt ? [imSkillsPrompt, ""] : []),
-    "[User message]",
-    userText,
-    "[/User message]",
-  ].join("\n");
-
-  // 设置活跃 prompt
+  // 立即标记活跃，确保 /sessions、isSessionRunning 等查询在异步准备阶段就能看到运行状态。
+  // 注意：下面的 try/catch 在准备失败时会清理 activePrompts。
   const controller = new AbortController();
   const now = Date.now();
   activePrompts.set(sessionId, {
@@ -499,6 +658,46 @@ export async function runAgentSession(
     startTime: now,
   });
 
+  // 异步准备工作（session info、IM skills prompt 等）
+  let adapter: ToolAdapter;
+  let info: Awaited<ReturnType<ToolAdapter["getSessionInfo"]>>;
+  let cwd: string;
+  try {
+    adapter = getAdapterForTool(tool);
+    info = await adapter.getSessionInfo(sessionId);
+    cwd = info?.cwd ?? (await getDefaultCwd(_chatId));
+    if (tid) logTrace(tid, "SESSION_START", { sessionId, tool, cwd, turn: (sessionInfoMap.get(_chatId)?.turnCount ?? 0) + 1 });
+    console.log(
+      `[${ts()}] Running ${adapter.displayName} session: ${sessionId} (${formatToolConfigForLog(tool, info?.model)}, cwd=${cwd})`
+    );
+
+    // 构建 IM skills prompt（sessionId 方式，无 token）
+    const feishuSkillDir = join(PROJECT_ROOT, "im-skills", "feishu-skill");
+    const imSkillsCacheDir = join(USER_DATA_DIR, "im-skills");
+    const skillVariables = {
+      cwd,
+      session_id: sessionId,
+      im_skills_cache_dir: imSkillsCacheDir,
+      send_image_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-image`,
+      send_file_url: `http://127.0.0.1:${CHATCCC_PORT}/api/agent/send-file`,
+      send_image_script: join(feishuSkillDir, "send-image.mjs"),
+      send_file_script: join(feishuSkillDir, "send-file.mjs"),
+      download_video_script: join(feishuSkillDir, "download-video.mjs"),
+    };
+    var imSkillsPrompt = await buildImSkillsPrompt({ variables: skillVariables });
+    await exportSkillSubDocs({ variables: skillVariables }, imSkillsCacheDir);
+    var userTextWithCapabilities = [
+      ...(imSkillsPrompt ? [imSkillsPrompt, ""] : []),
+      "[User message]",
+      userText,
+      "[/User message]",
+    ].join("\n");
+  } catch (preambleErr) {
+    // 准备工作失败，清理活跃标记，避免"僵尸"活跃状态阻塞后续消息
+    activePrompts.delete(sessionId);
+    throw preambleErr;
+  }
+
   // 更新 sessionInfoMap（所有绑定群共用）
   const existingInfo = sessionInfoMap.get(_chatId);
   const nextTurnCount = (existingInfo?.turnCount ?? 0) + 1;
@@ -545,7 +744,7 @@ export async function runAgentSession(
   // 设置最后活跃群头像为 busy
   const activeCid = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
   if (activeCid) {
-    setChatAvatar(token, activeCid, tool, "busy").catch(() => {});
+    platform.setChatAvatar(activeCid, tool, "busy").catch(() => {});
   }
 
   const state: AccumulatorState = {
@@ -636,7 +835,7 @@ export async function runAgentSession(
         });
       }
       const active1 = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
-      if (active1) setChatAvatar(token, active1, tool, "idle").catch(() => {});
+      if (active1) platform.setChatAvatar(active1, tool, "idle").catch(() => {});
       console.log(`[${ts()}] Session ${sessionId} stopped (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, outcome: "stopped", chunks: state.chunkCount });
     } else {
@@ -653,7 +852,7 @@ export async function runAgentSession(
         });
       }
       const active2 = getLastActiveChat(sessionId) ?? getChatsForSession(sessionId)[0];
-      if (active2) setChatAvatar(token, active2, tool, "idle").catch(() => {});
+      if (active2) platform.setChatAvatar(active2, tool, "idle").catch(() => {});
       console.log(`[${ts()}] Session ${sessionId} stream complete (content chunks: ${state.chunkCount})`);
       if (tid) logTrace(tid, "SESSION_END", { sessionId, chunks: state.chunkCount, finalTextLen: finalReply.length });
     }
@@ -686,103 +885,221 @@ export function ensureDisplayLoop(sessionId: string): void {
           displayLoops.delete(sessionId);
           // 兜底：lastActiveChatMap 可能因进程重启丢失，从 registry 映射恢复头像
           const fallbackChat = getChatsForSession(sessionId)[0];
-          if (fallbackChat) {
-            const t = await import("./feishu-platform.ts").then(m => m.getTenantAccessToken());
-            setChatAvatar(t, fallbackChat, state.tool, "idle").catch(() => {});
+          const fallbackPlatform = fallbackChat ? platformForChat(fallbackChat) : null;
+          if (fallbackChat && fallbackPlatform) {
+            fallbackPlatform.setChatAvatar(fallbackChat, state.tool, "idle").catch(() => {});
           }
         }
         return;
       }
 
+      // 交叉验证：chat 当前绑定的 session 是否仍是本 display loop 的 session。
+      // 若 chat 已被切换到其他 session（如 /new p2p 未解绑旧 session 的历史遗留
+      // 或任何未来新增的切换路径），旧 loop 必须停推，避免向已离开的 chat 推送内容。
+      const currentSessionForChat = sessionInfoMap.get(chatId)?.sessionId;
+      if (currentSessionForChat && currentSessionForChat !== sessionId) {
+        if (state.status !== "running") {
+          clearInterval(interval);
+          displayLoops.delete(sessionId);
+        }
+        return;
+      }
+
       const isTerminal = state.status !== "running";
 
       try {
-        // getTenantAccessToken 有缓存，多次调用开销低
-        const tokenModule = await import("./feishu-platform.ts");
-        const token = await tokenModule.getTenantAccessToken();
+        const p = platformForChat(chatId);
+        if (!p) return;
         const display = displayCards.get(chatId);
 
+        const isWechat = p.kind === "wechat";
+
         if (isTerminal) {
-          // 发送最终结果
-          if (display) {
-            while (display.cardBusy) await new Promise(r => setTimeout(r, 20));
-            const nextSeq = display.sequence + 1;
-            const headerTitle = state.status === "stopped" ? "已停止" : "完成";
-            const headerTemplate = state.status === "stopped" ? "red" : undefined;
-            const cardContent = state.accumulatedContent || " ";
-            const doneCard = buildProgressCard(cardContent, { showStop: false, headerTitle, headerTemplate });
-            await updateCardKitCard(token, display.cardId, doneCard, nextSeq).catch(() => {});
-            displayCards.delete(chatId);
-          }
-          if (state.finalReply) {
-            await sendTextReply(token, chatId, state.finalReply).catch(() => {});
-          } else if (!display && state.accumulatedContent.trim()) {
-            const short = truncateContent(state.accumulatedContent, 30, 4000);
-            await sendTextReply(token, chatId, `[生成过程]\n${short}`).catch(() => {});
+          if (isWechat) {
+            // WeChat: 没有卡片需要终结，用 delta 逻辑发剩余内容，避免重发已推送的部分
+            const rawFull = state.accumulatedContent + state.finalReply;
+            const prevRaw = display?.lastSentContent ?? "";
+            let remaining: string;
+            if (prevRaw && rawFull.startsWith(prevRaw)) {
+              remaining = rawFull.slice(prevRaw.length).trim();
+            } else {
+              remaining = rawFull.trim();
+            }
+            const tail = "━━━ 回答结束 ━━━";
+            const finalMsg = remaining ? remaining + "\n" + tail : tail;
+            await p.sendText(chatId, finalMsg).catch(() => {});
+            if (display) displayCards.delete(chatId);
+          } else {
+            // 发送最终结果（卡片平台）
+            if (display) {
+              while (display.cardBusy) await new Promise(r => setTimeout(r, 20));
+              const nextSeq = display.sequence + 1;
+              const headerTitle = state.status === "stopped" ? "已停止" : "完成";
+              const headerTemplate = state.status === "stopped" ? "red" : undefined;
+              const cardContent = state.accumulatedContent || " ";
+              const doneCard = buildProgressCard(cardContent, { showStop: false, headerTitle, headerTemplate });
+              await p.cardUpdate(display.cardId, doneCard, nextSeq).catch(() => {});
+              displayCards.delete(chatId);
+            }
+            if (state.finalReply) {
+              await p.sendText(chatId, state.finalReply).catch(() => {});
+            } else if (!display && state.accumulatedContent.trim()) {
+              const short = truncateContent(state.accumulatedContent, 30, 4000);
+              await p.sendText(chatId, `[生成过程]\n${short}`).catch(() => {});
+            }
           }
-          setChatAvatar(token, chatId, state.tool, "idle").catch(() => {});
+          p.setChatAvatar(chatId, state.tool, "idle").catch(() => {});
         } else {
-          // running: 创建或更新卡片
-          if (!display) {
-            const cardId = await createCardKitCard(token, buildProgressCard("", { showStop: true, headerTitle: "生成中..." })).catch(() => null);
-            if (cardId) {
-              await sendCardKitMessage(token, chatId, cardId).catch(() => null);
+          // running: 创建或更新展示
+          if (isWechat) {
+            // WeChat: 不使用卡片，基于 agent 真实 delta 推送 raw content
+            if (!display) {
               displayCards.set(chatId, {
-                cardId,
-                sequence: 1,
+                cardId: "",
+                sequence: 0,
                 cardBusy: false,
                 cardCreatedAt: Date.now(),
                 lastSentContent: "",
                 streamErrorNotified: false,
               });
             }
+            const d = displayCards.get(chatId);
+            if (!d || d.cardBusy) return;
+
+            const rawFull = state.accumulatedContent + state.finalReply;
+            const prevRaw = d.lastSentContent;
+            let delta: string;
+            if (prevRaw && rawFull.startsWith(prevRaw)) {
+              delta = rawFull.slice(prevRaw.length).trim();
+            } else {
+              delta = rawFull.trim();
+            }
+            if (!delta) return;
+
+            d.cardBusy = true;
+            try {
+              const ok = await p.sendText(chatId, delta);
+              if (ok) {
+                d.lastSentContent = rawFull;
+              } else {
+                // 发送失败（限流等），不更新光标，下次合并重试
+                return;
+              }
+            } catch (err) {
+              console.error(`[${ts()}] WeChat sendText error: chatId=${chatId} ${(err as Error).message}`);
+              if (!d.streamErrorNotified) {
+                d.streamErrorNotified = true;
+                p.sendText(chatId, "文本发送失败，请稍后查看结果。").catch(() => {});
+              }
+            } finally {
+              d.cardBusy = false;
+            }
           } else {
-            if (display.cardBusy) return;
+            // 非 WeChat: 卡片流程
+            if (!display) {
+              const cardId = await p.cardCreate(buildProgressCard("", { showStop: true, headerTitle: "生成中..." })).catch(() => null);
+              if (cardId) {
+                await p.cardSend(chatId, cardId).catch(() => null);
+                displayCards.set(chatId, {
+                  cardId,
+                  sequence: 1,
+                  cardBusy: false,
+                  cardCreatedAt: Date.now(),
+                  lastSentContent: "",
+                  streamErrorNotified: false,
+                });
+              }
+            } else {
+              if (display.cardBusy) return;
+
+              // 卡片轮转
+              if (Date.now() - display.cardCreatedAt > CARD_ROTATE_MS) {
+                display.cardBusy = true;
+                try {
+                  const oldSeqBase = display.sequence;
+                  const oldDisplayContent = truncateContent(state.accumulatedContent + state.finalReply) || "处理中...";
+                  const oldCard = buildProgressCard(oldDisplayContent, { showStop: false, headerTitle: "生成中...（上轮）" });
+                  await p.cardUpdate(display.cardId, oldCard, oldSeqBase + 1).catch(() => {});
+                  const newCardId = await p.cardCreate(buildProgressCard("", { showStop: true, headerTitle: "生成中..." }));
+                  if (newCardId) {
+                    await p.cardSend(chatId, newCardId);
+                    display.cardId = newCardId;
+                    display.sequence = 1;
+                    display.cardCreatedAt = Date.now();
+                    // 记录基线：新卡片只展示轮转后新增的内容，不重复旧卡已有内容
+                    display.rotationBaseline = state.accumulatedContent + state.finalReply;
+                    display.lastSentContent = "";
+                    display.streamErrorNotified = false;
+                  }
+                } catch (err) {
+                  console.error(`[${ts()}] [CARDIKT] rotation FAIL for ${chatId}: ${(err as Error).message}`);
+                } finally {
+                  display.cardBusy = false;
+                }
+                return;
+              }
 
-            // 卡片轮转
-            if (Date.now() - display.cardCreatedAt > CARD_ROTATE_MS) {
+              // 轮转后：只展示增量（从 baseline 之后的新内容）
+              if (display.rotationBaseline) {
+                const fullRaw = state.accumulatedContent + state.finalReply;
+                if (!fullRaw.startsWith(display.rotationBaseline)) {
+                  // baseline 失效（极端情况），回退到完整内容
+                  display.rotationBaseline = undefined;
+                  dotCount = (dotCount % 9) + 1;
+                  const fallback = fullRaw + "\n" + "。".repeat(dotCount);
+                  display.lastSentContent = fallback;
+                  const fbCard = buildProgressCard(truncateContent(fallback), { showStop: true, headerTitle: "生成中..." });
+                  display.cardBusy = true;
+                  try {
+                    await p.cardUpdate(display.cardId, fbCard, display.sequence + 1);
+                    display.sequence++;
+                  } finally {
+                    display.cardBusy = false;
+                  }
+                  return;
+                }
+                const delta = fullRaw.slice(display.rotationBaseline.length).trim();
+                if (delta === display.lastSentContent) return;
+                display.lastSentContent = delta;
+                const deltaCard = buildProgressCard(truncateContent(delta) || "处理中...", { showStop: true, headerTitle: "生成中..." });
+                display.cardBusy = true;
+                const mySeq = display.sequence + 1;
+                try {
+                  await p.cardUpdate(display.cardId, deltaCard, mySeq);
+                  display.sequence = mySeq;
+                } catch (err) {
+                  console.error(`[${ts()}] CardKit update error: chatId=${chatId} ${(err as Error).message}`);
+                  if (!display.streamErrorNotified) {
+                    display.streamErrorNotified = true;
+                    p.sendText(chatId, "卡片更新失败，结果将以文本形式发送。").catch(() => {});
+                  }
+                } finally {
+                  display.cardBusy = false;
+                }
+                return;
+              }
+
+              dotCount = (dotCount % 9) + 1;
+              const fullContent = state.accumulatedContent + state.finalReply + "\n" + "。".repeat(dotCount);
+              if (fullContent === display.lastSentContent) return;
+
+              display.lastSentContent = fullContent;
+              const cardContent = truncateContent(fullContent);
               display.cardBusy = true;
+              const mySeq = display.sequence + 1;
               try {
-                const oldSeqBase = display.sequence;
-                const oldDisplayContent = truncateContent(state.accumulatedContent + state.finalReply) || "处理中...";
-                const oldCard = buildProgressCard(oldDisplayContent, { showStop: false, headerTitle: "生成中...（上轮）" });
-                await updateCardKitCard(token, display.cardId, oldCard, oldSeqBase + 1).catch(() => {});
-                const newCardId = await createCardKitCard(token, buildProgressCard("", { showStop: true, headerTitle: "生成中..." }));
-                if (newCardId) {
-                  await sendCardKitMessage(token, chatId, newCardId);
-                  display.cardId = newCardId;
-                  display.sequence = 1;
-                  display.cardCreatedAt = Date.now();
-                  display.lastSentContent = "";
-                  display.streamErrorNotified = false;
-                }
+                const card = buildProgressCard(cardContent, { showStop: true, headerTitle: "生成中..." });
+                await p.cardUpdate(display.cardId, card, mySeq);
+                display.sequence = mySeq;
               } catch (err) {
-                console.error(`[${ts()}] [CARDIKT] rotation FAIL for ${chatId}: ${(err as Error).message}`);
+                console.error(`[${ts()}] CardKit update error: chatId=${chatId} ${(err as Error).message}`);
+                if (!display.streamErrorNotified) {
+                  display.streamErrorNotified = true;
+                  p.sendText(chatId, "卡片更新失败，结果将以文本形式发送。").catch(() => {});
+                }
               } finally {
                 display.cardBusy = false;
               }
-              return;
-            }
-
-            dotCount = (dotCount % 9) + 1;
-            const content = truncateContent(state.accumulatedContent + state.finalReply + "\n" + "。".repeat(dotCount));
-            if (content === display.lastSentContent) return;
-
-            display.lastSentContent = content;
-            display.cardBusy = true;
-            const mySeq = display.sequence + 1;
-            try {
-              const card = buildProgressCard(content, { showStop: true, headerTitle: "生成中..." });
-              await updateCardKitCard(token, display.cardId, card, mySeq);
-              display.sequence = mySeq;
-            } catch (err) {
-              console.error(`[${ts()}] CardKit update error: chatId=${chatId} ${(err as Error).message}`);
-              if (!display.streamErrorNotified) {
-                display.streamErrorNotified = true;
-                sendTextReply(token, chatId, "卡片更新失败，结果将以文本形式发送。").catch(() => {});
-              }
-            } finally {
-              display.cardBusy = false;
             }
           }
         }