cc-viewer 1.6.324 → 1.6.326

package/dist/index.html

@@ -21,7 +21,7 @@
     // 整体显示大小已弃用 CSS zoom：Electron 改用 webFrame.setZoomFactor（首屏抢占见
     // electron/tab-content-preload.js），纯浏览器交由用户用浏览器自带快捷键缩放，故此处不再设 zoom。
   </script>
-  <script type="module" crossorigin src="/assets/index-Cw_igOCh.js"></script>
+  <script type="module" crossorigin src="/assets/index-CqCAViSO.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/vendor-antd-x2KtHa4R.js">
   <link rel="modulepreload" crossorigin href="/assets/vendor-codemirror-z6VSi4ab.js">
   <link rel="modulepreload" crossorigin href="/assets/vendor-mdxeditor-Zi3mchEB.js">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-viewer",
-  "version": "1.6.324",
+  "version": "1.6.326",
   "description": "Claude Code Logger visualization management tool",
   "license": "MIT",
   "main": "server.js",

package/server/interceptor.js

@@ -41,6 +41,26 @@ export function resetStreamingState() {
   streamingState.chunksReceived = 0;
 }
 
+// ─── IM 逐字流式的文本源 ───
+// 钉钉 AI 卡片流式（server/lib/adapters/dingtalk-adapter.js）需要「对话过程中」的主 agent 增量文本。
+// 复用本拦截器对主 agent SSE 的增量解析，累计 text_delta（跳过 thinking_delta，与 im-bridge-core
+// 的 extractLastAssistantText「只取 text 块」一致），供 IM bridge 节流推送给钉钉 /card/streaming。
+// 关键：按「注入轮次」重置 —— 由 bridge 在 armActiveInjection 时调 resetImLiveText()。**绝不**在
+// resetStreamingState() 内重置：带工具的回合中间 streamingState 会 false↔true（每个 Anthropic API
+// 调用各一次），那样会把半截回复清空，typewriter 跨工具间隙断流。
+// 默认仅 IM worker 进程（CCV_IM_PLATFORM 已设）采集，其它进程零成本、不解析。
+let _imLiveText = '';
+const _imCaptureEnabled = !!process.env.CCV_IM_PLATFORM;
+export function getImLiveText() { return _imLiveText; }
+export function resetImLiveText() { _imLiveText = ''; }
+// 判定一个 SSE event 是否为可见正文 text_delta（跳过 thinking_delta / 工具入参 / 其它），是则返回其
+// 文本片段，否则 null。抽成纯函数：既给下方采集循环复用，也便于单测覆盖「只收 text_delta」规则。
+export function imTextDeltaOf(ev) {
+  return (ev && ev.type === 'content_block_delta'
+    && ev.delta && ev.delta.type === 'text_delta'
+    && typeof ev.delta.text === 'string') ? ev.delta.text : null;
+}
+
 // 缓存从请求 headers 中提取的 API Key 或 Authorization header
 export let _cachedApiKey = null;
 export let _cachedAuthHeader = null;
@@ -882,6 +902,9 @@ export function setupInterceptor() {
           // 实时流式：仅对 mainAgent 且 server live-port 已注入时启用
           let liveStreamEnabled = !!_livePort && requestEntry.mainAgent && !_isTeammate;
           const liveAssembler = liveStreamEnabled ? createStreamAssembler() : null;
+          // IM 逐字采集：独立于前端 live-stream / _livePort，仅 worker 内对主 agent 累计 text_delta。
+          const imCapture = _imCaptureEnabled && requestEntry.mainAgent && !_isTeammate;
+          let imStreamAppended = false; // 本 stream 是否已追加过；跨 API 调用的消息间补一个 \n\n 分隔
           let livePendingBuffer = '';
           let liveChunkSeq = 0;
           let liveLastFlushMs = 0;
@@ -1010,8 +1033,9 @@ export function setupInterceptor() {
                   streamedContentLen += chunk.length;
                   controller.enqueue(value);
 
-                  // 实时流式：增量解析完整的 SSE events 并触发节流 flush
-                  if (liveAssembler && liveStreamEnabled) {
+                  // 实时流式：增量解析完整的 SSE events。前端 live-stream（liveAssembler）与 IM 逐字
+                  // 采集（imCapture）共用同一次 split 解析，避免重复扫描；任一开启即进入。
+                  if ((liveAssembler && liveStreamEnabled) || imCapture) {
                     livePendingBuffer += chunk;
                     let sawBlockStop = false;
                     let idx;
@@ -1027,17 +1051,31 @@ export function setupInterceptor() {
                         : dataLine.substring(5);
                       try {
                         const ev = JSON.parse(jsonStr);
-                        liveAssembler.feed(ev);
-                        if (ev.type === 'content_block_stop') sawBlockStop = true;
+                        if (liveAssembler && liveStreamEnabled) {
+                          liveAssembler.feed(ev);
+                          if (ev.type === 'content_block_stop') sawBlockStop = true;
+                        }
+                        // IM 逐字：只累计可见正文 text_delta（跳过 thinking_delta / 工具入参），与
+                        // extractLastAssistantText 的「只取 text 块」对齐，避免 finalize 时闪烁/重复。
+                        if (imCapture) {
+                          const td = imTextDeltaOf(ev);
+                          if (td !== null) {
+                            if (!imStreamAppended && _imLiveText) _imLiveText += '\n\n'; // 跨 API 调用的消息间分隔
+                            imStreamAppended = true;
+                            _imLiveText += td;
+                          }
+                        }
                       } catch {}
                     }
-                    const now = Date.now();
-                    const overdue = (now - liveLastFlushMs) >= 100;
-                    const bigChunk = (streamedContentLen - liveLastFlushBytes) > 16384;
-                    if (sawBlockStop || overdue || bigChunk) {
-                      liveLastFlushMs = now;
-                      liveLastFlushBytes = streamedContentLen;
-                      liveFlush();
+                    if (liveAssembler && liveStreamEnabled) {
+                      const now = Date.now();
+                      const overdue = (now - liveLastFlushMs) >= 100;
+                      const bigChunk = (streamedContentLen - liveLastFlushBytes) > 16384;
+                      if (sawBlockStop || overdue || bigChunk) {
+                        liveLastFlushMs = now;
+                        liveLastFlushBytes = streamedContentLen;
+                        liveFlush();
+                      }
                     }
                   }
                 }

package/server/lib/adapters/dingtalk-adapter.js

@@ -16,6 +16,8 @@ const GROUP_SEND_URL = 'https://api.dingtalk.com/v1.0/robot/groupMessages/send';
 const OTO_SEND_URL = 'https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend';
 const CARD_CREATE_URL = 'https://api.dingtalk.com/v1.0/card/instances';
 const CARD_DELIVER_URL = 'https://api.dingtalk.com/v1.0/card/instances/deliver';
+const CARD_CREATE_AND_DELIVER_URL = 'https://api.dingtalk.com/v1.0/card/instances/createAndDeliver';
+const CARD_STREAMING_URL = 'https://api.dingtalk.com/v1.0/card/streaming';
 
 async function getAccessToken(cfg, ctx) {
   const tc = ctx.store.tokenCache;
@@ -54,6 +56,117 @@ function normalizeInbound(res) {
   };
 }
 
+// AI 卡片模板里「流式 Markdown 变量」的名字：用户可经 aiCardStreamKey 配置；留空按钉钉惯例用 'content'。
+function streamKeyOf(cfg) {
+  const k = cfg && typeof cfg.aiCardStreamKey === 'string' ? cfg.aiCardStreamKey.trim() : '';
+  return k || 'content';
+}
+
+// ─── 卡片投递目标字段（群 / 单聊的 openSpaceId + deliver model）───
+// 单一来源，消除 createAndDeliver(AI)、legacy deliver 两处重复的 conversationType==='2' 分支。
+function cardDeliverFields(target) {
+  const isGroup = String(target.conversationType) === '2';
+  return isGroup
+    ? { userIdType: 1, openSpaceId: 'dtv1.card//IM_GROUP.' + target.conversationId, imGroupOpenDeliverModel: { robotCode: target.robotCode } }
+    : { userIdType: 1, openSpaceId: 'dtv1.card//IM_ROBOT.' + target.senderStaffId, imRobotOpenDeliverModel: { spaceType: 'IM_ROBOT', robotCode: target.robotCode } };
+}
+
+// createAndDeliver（AI 卡片）在 deliver 字段之上还需 OpenSpaceModel(supportForward)。legacy 的 deliver
+// 端点只用 cardDeliverFields（不带 OpenSpaceModel，保持原报文不变）。
+function cardSpaceFields(target) {
+  const isGroup = String(target.conversationType) === '2';
+  return { ...cardDeliverFields(target), [isGroup ? 'imGroupOpenSpaceModel' : 'imRobotOpenSpaceModel']: { supportForward: true } };
+}
+
+// AI 卡片：createAndDeliver 单调用建卡 + 投递（callbackType STREAM、flowStatus=处理中、content 空），
+// 再补一帧空 content「kick」开启流式生命周期（群尤其需要）。返回 { outTrackId, streaming:true }。
+async function createAiCard(cfg, target, ctx) {
+  const token = await getAccessToken(cfg, ctx);
+  const outTrackId = randomUUID();
+  const r = await ctx.fetch(CARD_CREATE_AND_DELIVER_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'x-acs-dingtalk-access-token': token },
+    body: JSON.stringify({
+      cardTemplateId: cfg.aiCardTemplateId,
+      outTrackId,
+      callbackType: 'STREAM',
+      cardData: { cardParamMap: { [streamKeyOf(cfg)]: '', flowStatus: '1' } }, // cardParamMap 值必须为字符串
+      ...cardSpaceFields(target),
+    }),
+  });
+  if (!r.ok) { const j = await r.json().catch(() => ({})); throw new Error(`ai-card create ${r.status}: ${j.message || j.code || 'failed'}`); }
+  const handle = { outTrackId, streaming: true };
+  // kick：开启流式生命周期。best-effort——权限缺失时 finalize 的 instances PUT 仍能兜底落最终内容。
+  await streamFrame(cfg, handle, '', ctx, {}).catch(() => {});
+  return handle;
+}
+
+// legacy 卡片：create + deliver 两步（沿用原 status+content 模板变量）。无 cardTemplateId 返回 null。
+async function createLegacyCard(cfg, target, statusText, ctx) {
+  if (!cfg.cardTemplateId) return null;
+  const token = await getAccessToken(cfg, ctx);
+  const outTrackId = randomUUID();
+  const headers = { 'Content-Type': 'application/json', 'x-acs-dingtalk-access-token': token };
+  const cr = await ctx.fetch(CARD_CREATE_URL, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      outTrackId,
+      cardTemplateId: cfg.cardTemplateId,
+      cardData: { cardParamMap: { status: statusText, content: '' } },
+    }),
+  });
+  if (!cr.ok) { const j = await cr.json().catch(() => ({})); throw new Error(`card create ${cr.status}: ${j.message || j.code || 'failed'}`); }
+
+  const dr = await ctx.fetch(CARD_DELIVER_URL, { method: 'POST', headers, body: JSON.stringify({ outTrackId, ...cardDeliverFields(target) }) });
+  if (!dr.ok) { const j = await dr.json().catch(() => ({})); throw new Error(`card deliver ${dr.status}: ${j.message || j.code || 'failed'}`); }
+  return { outTrackId };
+}
+
+// 一帧流式更新（PUT /card/streaming）。isFull:true 全量重发（幂等自愈丢帧）；7 字段含 isError。
+async function streamFrame(cfg, handle, fullText, ctx, opts = {}) {
+  try {
+    if (!handle?.outTrackId) return false;
+    const token = await getAccessToken(cfg, ctx);
+    const r = await ctx.fetch(CARD_STREAMING_URL, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json', 'x-acs-dingtalk-access-token': token },
+      body: JSON.stringify({
+        outTrackId: handle.outTrackId,
+        guid: randomUUID(),
+        key: streamKeyOf(cfg),
+        content: String(fullText ?? ''),
+        isFull: true,
+        isFinalize: !!opts.finalize,
+        isError: !!opts.error,
+      }),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
+// 局部更新卡片变量（PUT /card/instances，updateCardDataByKey 只改传入键）。值须全字符串。
+async function putCardInstances(cfg, handle, cardParamMap, ctx) {
+  try {
+    if (!handle?.outTrackId) return false;
+    const token = await getAccessToken(cfg, ctx);
+    const r = await ctx.fetch(CARD_CREATE_URL, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json', 'x-acs-dingtalk-access-token': token },
+      body: JSON.stringify({
+        outTrackId: handle.outTrackId,
+        cardData: { cardParamMap },
+        cardUpdateOptions: { updateCardDataByKey: true },
+      }),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
 const dingtalkAdapter = {
   id: 'dingtalk',
   i18nNs: 'server.dingtalk',
@@ -123,50 +236,40 @@ const dingtalkAdapter = {
   // 触发钉钉风控/限流，反过来阻断模型回复的下发。故 DingTalk 发送者头像在「对话记录」里降级为默认头像
   // （名字仍是真实昵称，不报错、不抢占发送配额）。后续如引入具备通讯录 scope 的凭证再补 resolveSender。
 
+  // ack 卡片：aiCardTemplateId 非空 → AI 卡片（flowStatus 状态标签 + /card/streaming 逐字）；建卡
+  // 失败则降级 legacy 卡片（cardTemplateId 单次更新）；都没有 → 返回 null，core 发纯文本 ack。
   async sendAckCard(cfg, target, statusText, ctx) {
-    if (!cfg.cardTemplateId) return null;
-    const token = await getAccessToken(cfg, ctx);
-    const outTrackId = randomUUID();
-    const headers = { 'Content-Type': 'application/json', 'x-acs-dingtalk-access-token': token };
-
-    const cr = await ctx.fetch(CARD_CREATE_URL, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify({
-        outTrackId,
-        cardTemplateId: cfg.cardTemplateId,
-        cardData: { cardParamMap: { status: statusText, content: '' } },
-      }),
-    });
-    if (!cr.ok) { const j = await cr.json().catch(() => ({})); throw new Error(`card create ${cr.status}: ${j.message || j.code || 'failed'}`); }
-
-    const isGroup = String(target.conversationType) === '2';
-    const deliverBody = isGroup
-      ? {
-          outTrackId,
-          userIdType: 1,
-          openSpaceId: 'dtv1.card//IM_GROUP.' + target.conversationId,
-          imGroupOpenDeliverModel: { robotCode: target.robotCode },
-        }
-      : {
-          outTrackId,
-          userIdType: 1,
-          openSpaceId: 'dtv1.card//IM_ROBOT.' + target.senderStaffId,
-          imRobotOpenDeliverModel: { spaceType: 'IM_ROBOT', robotCode: target.robotCode },
-        };
-
-    const dr = await ctx.fetch(CARD_DELIVER_URL, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(deliverBody),
-    });
-    if (!dr.ok) { const j = await dr.json().catch(() => ({})); throw new Error(`card deliver ${dr.status}: ${j.message || j.code || 'failed'}`); }
+    if (cfg.aiCardTemplateId) {
+      try {
+        return await createAiCard(cfg, target, ctx);
+      } catch (e) {
+        // 把失败原因留在 store，供 core 落审计（即便降级 legacy 也能诊断「为什么没流式」）。
+        if (ctx?.store) ctx.store.lastAiCardError = String(e?.message || e);
+        // AI 卡片创建失败：有 legacy 模板则降级单卡片，否则抛给 core 走纯文本。
+        if (!cfg.cardTemplateId) throw e;
+      }
+    }
+    return await createLegacyCard(cfg, target, statusText, ctx);
+  },
 
-    return { outTrackId };
+  // 对话过程中逐字推送（core 的 streamTimer 调用）。仅 AI 卡片句柄有效；best-effort 返回 bool。
+  async streamCardText(cfg, target, handle, fullText, ctx, opts = {}) {
+    if (!handle?.streaming) return false;
+    return streamFrame(cfg, handle, fullText, ctx, opts);
   },
 
   async updateAckCard(cfg, target, handle, content, status, ctx) {
     try {
+      if (handle?.streaming) {
+        const flowStatus = status === 'done' ? '3' : '5'; // 执行完成 / 执行失败（含中断·超时）
+        // 官方 finalize：流式帧 isFinalize:true 收尾。
+        const streamed = await streamFrame(cfg, handle, content, ctx, { finalize: true, error: status !== 'done' });
+        // 再用 /card/instances 落定权威全文 + 状态标签：即便缺 Card.Streaming.Write 权限这步仍生效，
+        // 保证最终内容与 tag 一定渲染、不会卡在「处理中」。
+        const settled = await putCardInstances(cfg, handle, { [streamKeyOf(cfg)]: String(content ?? ''), flowStatus }, ctx);
+        return streamed || settled;
+      }
+      // legacy 卡片：单次 PUT 更新 content。
       const token = await getAccessToken(cfg, ctx);
       const r = await ctx.fetch(CARD_CREATE_URL, {
         method: 'PUT',

package/server/lib/adapters/feishu-adapter.js

@@ -23,6 +23,22 @@ function tokenHost(region) {
   return region === 'lark' ? 'https://open.larksuite.com' : 'https://open.feishu.cn';
 }
 
+// AI 卡片(CardKit v1)里那个被逐字流式覆写的 markdown 组件 id（建卡与流式更新都引用它）。
+const AI_CARD_ELEMENT_ID = 'md';
+
+/** 构造一个 Card JSON 2.0 流式卡片：单 markdown 组件 + streaming_mode。建卡时 streaming=true。 */
+function buildStreamCardJson(content, { streaming, headerTemplate = 'blue' } = {}) {
+  return {
+    schema: '2.0',
+    config: { streaming_mode: !!streaming },
+    header: { title: { tag: 'plain_text', content: 'Claude' }, template: headerTemplate },
+    body: { elements: [{ tag: 'markdown', element_id: AI_CARD_ELEMENT_ID, content: content || '' }] },
+  };
+}
+
+/** Feishu 返回 HTTP 200 但 body.code 非 0 表示失败；统一判定。 */
+function isErr(r) { return r && typeof r.code === 'number' && r.code !== 0; }
+
 async function loadSdk() {
   if (sdkFactory) return sdkFactory();
   return import('@larksuiteoapi/node-sdk');
@@ -130,9 +146,39 @@ const feishuAdapter = {
     }
   },
 
+  // ─── 逐字流式（AI 卡片）─── 用 CardKit v1：建卡片实例(streaming_mode) → 引用 card_id 发消息 →
+  // cardElement.content 逐帧覆写正文(飞书自动 diff 出打字机效果) → settings 关流收尾。无模板 id 概念，
+  // 开关就是 cfg.aiCard；建卡失败(如缺 cardkit:card:write scope)安全回退到 1.0 占位卡片。
+  streamEnabled(cfg) { return !!cfg?.aiCard; },
+
   async sendAckCard(cfg, target, statusText, ctx) {
     const client = ctx.store.sendClient;
     if (!client) throw new Error('feishu send client not initialized');
+    // 流式路径：CardKit 建卡 + 引用发送。任何环节失败 → 落诊断并回退到下面的 1.0 占位卡片。
+    if (cfg?.aiCard && client.cardkit?.v1?.card?.create) {
+      try {
+        const created = await client.cardkit.v1.card.create({
+          data: { type: 'card_json', data: JSON.stringify(buildStreamCardJson(statusText, { streaming: true })) },
+        });
+        if (isErr(created)) throw new Error(`card.create ${created.code}: ${created.msg || ''}`);
+        const cardId = created?.data?.card_id;
+        if (!cardId) throw new Error('card.create returned no card_id');
+        const r = await client.im.v1.message.create({
+          params: { receive_id_type: target.receiveIdType },
+          data: {
+            receive_id: target.receiveId,
+            msg_type: 'interactive',
+            content: JSON.stringify({ type: 'card', data: { card_id: cardId } }),
+          },
+        });
+        if (isErr(r)) throw new Error(`send ${r.code}: ${r.msg || ''}`);
+        return { messageId: r?.data?.message_id, cardId, elementId: AI_CARD_ELEMENT_ID, streaming: true, seq: 0 };
+      } catch (e) {
+        if (ctx.store) ctx.store.lastAiCardError = String(e?.message || e);
+        // fall through → 1.0 占位卡片（非流式），保证 ack 不丢
+      }
+    }
+    // ── 1.0 占位卡片（非流式；aiCard 关闭或 CardKit 不可用时走这条，行为同旧版） ──
     const card = {
       config: { wide_screen_mode: true },
       header: { title: { tag: 'plain_text', content: 'Claude' }, template: 'blue' },
@@ -142,16 +188,54 @@ const feishuAdapter = {
       params: { receive_id_type: target.receiveIdType },
       data: { receive_id: target.receiveId, msg_type: 'interactive', content: JSON.stringify(card) },
     });
-    if (r && typeof r.code === 'number' && r.code !== 0) {
-      throw new Error(`sendAckCard ${r.code}: ${r.msg || 'failed'}`);
-    }
+    if (isErr(r)) throw new Error(`sendAckCard ${r.code}: ${r.msg || 'failed'}`);
     return { messageId: r?.data?.message_id };
   },
 
+  async streamCardText(cfg, target, handle, fullText, ctx) {
+    const client = ctx.store.sendClient;
+    if (!client || !handle?.cardId || !client.cardkit?.v1?.cardElement?.content) return false;
+    try {
+      const seq = ++handle.seq; // 单 in-flight + 单调自增,保证 sequence 严格递增、不乱序
+      const r = await client.cardkit.v1.cardElement.content({
+        path: { card_id: handle.cardId, element_id: handle.elementId || AI_CARD_ELEMENT_ID },
+        data: { content: fullText, sequence: seq, uuid: `c_${handle.cardId}_${seq}` },
+      });
+      return !isErr(r);
+    } catch { return false; }
+  },
+
   async updateAckCard(cfg, target, handle, content, status, ctx) {
     try {
       const client = ctx.store.sendClient;
       if (!client) return false;
+      // 流式句柄：先以权威全文覆写正文(打字机收口) → settings 关 streaming_mode + 更新预览摘要
+      //（缺摘要会让消息列表预览卡在「生成中」）。状态由文本本身承载,CardKit 无 header 状态标签。
+      if (handle?.streaming && handle.cardId && client.cardkit?.v1?.cardElement?.content) {
+        const seqC = ++handle.seq;
+        const rc = await client.cardkit.v1.cardElement.content({
+          path: { card_id: handle.cardId, element_id: handle.elementId || AI_CARD_ELEMENT_ID },
+          data: { content, sequence: seqC, uuid: `c_${handle.cardId}_${seqC}` },
+        });
+        if (isErr(rc)) return false;
+        if (client.cardkit?.v1?.card?.settings) {
+          const seqS = ++handle.seq;
+          const preview = String(content).replace(/\s+/g, ' ').trim().slice(0, 40);
+          await client.cardkit.v1.card.settings({
+            path: { card_id: handle.cardId },
+            data: {
+              settings: JSON.stringify({ config: { streaming_mode: false, summary: { content: preview } } }),
+              sequence: seqS,
+              uuid: `s_${handle.cardId}_${seqS}`,
+            },
+          }).catch((e) => {
+            // 关流失败:内容已落定,飞书 10min 后会自动关流;仅记诊断(消息列表预览可能短暂卡在「生成中」)。
+            if (ctx.store) ctx.store.lastAiCardError = 'settings close: ' + String(e?.message || e);
+          });
+        }
+        return true;
+      }
+      // 非流式句柄（1.0 占位卡片）：保持原整卡 patch + header 状态色。
       const templateMap = { done: 'green', interrupted: 'orange', error: 'red' };
       const card = {
         config: { wide_screen_mode: true },
@@ -162,7 +246,7 @@ const feishuAdapter = {
         path: { message_id: handle.messageId },
         data: { content: JSON.stringify(card) },
       });
-      if (r && typeof r.code === 'number' && r.code !== 0) return false;
+      if (isErr(r)) return false;
       return true;
     } catch { return false; }
   },

package/server/lib/adapters/wecom-adapter.js

@@ -11,6 +11,7 @@
 //
 // Console prerequisite (no code equivalent — surfaced in the UI help/README): create a 智能机器人,
 // set its API 接收模式 to 长连接, copy the botId + secret, and add the bot to a chat.
+import { randomUUID } from 'node:crypto';
 import { registerAdapter } from '../im-bridge-core.js';
 
 // ─── test seam: a fake SDK factory (zero real SDK / socket) ───
@@ -46,7 +47,10 @@ function normalizeInbound(frame) {
     isGroup,
     senderId,
     msgId: b.msgid,
-    target: { conversationId: receiveId, receiveId },
+    // 逐字流式（aiCard）靠被动回复 replyStream，须透传入站帧的 req_id。core 入队是浅展开
+    // `{ ...target, ... }`，故把整帧挂进 target 内层才能随队列项流转到 sendAckCard/streamCardText/
+    // updateAckCard。非流式路径不读它，无副作用。
+    target: { conversationId: receiveId, receiveId, _frame: frame },
   };
 }
 
@@ -114,6 +118,57 @@ const wecomAdapter = {
     }
   },
 
+  // ─── 逐字流式（AI 卡片）─── 用智能机器人长连接的 stream 被动回复(replyStream)：首帧即 ack(确立
+  // streamId、落 5s 首回复窗口)，streamTick 逐帧推累计全文，finalize 以 finish=true 收尾(落 10min
+  // 流式窗口内)。无模板 id 概念，开关就是 cfg.aiCard。
+  streamEnabled(cfg) { return !!cfg?.aiCard; },
+
+  async sendAckCard(cfg, target, statusText, ctx) {
+    if (!cfg?.aiCard) return null;             // 未开 aiCard → 返回 null,core 回退 proactive 文本 ack(旧行为)
+    const client = ctx.store.client;
+    const frame = target?._frame;
+    if (!client || !frame) {                   // 无连接/无帧(无法被动回复) → 回退
+      if (ctx.store && !frame) ctx.store.lastAiCardError = 'no inbound frame';
+      return null;
+    }
+    try {
+      const streamId = randomUUID();
+      // 首帧 finish=false：开流 + 即时 ack 文本。
+      await client.replyStream(frame, streamId, statusText, false);
+      return { streamId, frame, streaming: true };
+    } catch (e) {
+      if (ctx.store) ctx.store.lastAiCardError = String(e?.message || e);
+      return null;                             // 开流失败 → 回退 proactive 文本 ack
+    }
+  },
+
+  async streamCardText(cfg, target, handle, fullText, ctx) {
+    const client = ctx.store.client;
+    const frame = handle?.frame || target?._frame;
+    if (!client || !frame || !handle?.streamId) return false;
+    try {
+      // 优先非阻塞：上一帧未 ack 则跳过本帧(返回 'skipped')，避免中间帧排队积压;最终全文由 finalize 兜底。
+      if (typeof client.replyStreamNonBlocking === 'function') {
+        const r = await client.replyStreamNonBlocking(frame, handle.streamId, fullText, false);
+        return r !== 'skipped';
+      }
+      await client.replyStream(frame, handle.streamId, fullText, false);
+      return true;
+    } catch { return false; }
+  },
+
+  async updateAckCard(cfg, target, handle, fullText, status, ctx) {
+    // 流式收尾：finish=true 的最终帧 SDK 保证发送(不受非阻塞跳帧限制)。WeCom stream 无状态标签，
+    // 中断/失败语义由 core 传入的 fullText 文本自身承载，status 此处不额外渲染。
+    try {
+      const client = ctx.store.client;
+      const frame = handle?.frame || target?._frame;
+      if (!client || !frame || !handle?.streamId) return false;
+      await client.replyStream(frame, handle.streamId, fullText, true);
+      return true;
+    } catch { return false; }
+  },
+
   async testConnection(cfg) {
     // No REST validate endpoint exists for the smart-robot mode — auth is in the WS handshake. Open
     // a throwaway probe and wait for 'authenticated'. NOTE: WeCom allows one connection per bot, so