@dingtalk-real-ai/dingtalk-connector 0.7.6 → 0.7.8

package/plugin.ts

@@ -553,17 +553,17 @@ async function extractVideoMetadata(
     const ffmpegPath = require('@ffmpeg-installer/ffmpeg').path;
     ffmpeg.setFfmpegPath(ffmpegPath);
 
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
       ffmpeg.ffprobe(filePath, (err: any, metadata: any) => {
         if (err) {
           log?.error?.(`[DingTalk][Video] 提取元数据失败: ${err.message}`);
-          return reject(err);
+          return resolve({ duration: 0, width: 0, height: 0 });
         }
 
         const videoStream = metadata.streams.find((s: any) => s.codec_type === 'video');
         if (!videoStream) {
           log?.warn?.(`[DingTalk][Video] 未找到视频流`);
-          return resolve(null);
+          return resolve({ duration: 0, width: 0, height: 0 });
         }
 
         const result = {
@@ -578,7 +578,7 @@ async function extractVideoMetadata(
     });
   } catch (err: any) {
     log?.error?.(`[DingTalk][Video] ffprobe 失败: ${err.message}`);
-    return null;
+    return { duration: 0, width: 0, height: 0 };
   }
 }
 
@@ -596,7 +596,7 @@ async function extractVideoThumbnail(
     const path = await import('path');
     ffmpeg.setFfmpegPath(ffmpegPath);
 
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve) => {
       ffmpeg(videoPath)
         .screenshots({
           count: 1,
@@ -611,7 +611,7 @@ async function extractVideoThumbnail(
         })
         .on('error', (err: any) => {
           log?.error?.(`[DingTalk][Video] 封面生成失败: ${err.message}`);
-          reject(err);
+          resolve(null);
         });
     });
   } catch (err: any) {
@@ -920,7 +920,7 @@ async function extractAudioDuration(
   log?: any,
 ): Promise<number | null> {
   try {
-    const { execFile } = require('child_process');
+    const { execFile } = await import('child_process');
     const ffprobeBin = getFfprobePath();
 
     return new Promise((resolve) => {
@@ -1103,7 +1103,7 @@ async function processFileMarkers(
 
 const DINGTALK_API = 'https://api.dingtalk.com';
 const DINGTALK_OAPI = 'https://oapi.dingtalk.com';
-const AI_CARD_TEMPLATE_ID = '382e4302-551d-4880-bf29-a30acfab2e71.schema';
+const AI_CARD_TEMPLATE_ID = '02fcf2f4-5e02-4a85-b672-46d1f715543e.schema';
 
 // flowStatus 值与 Python SDK AICardStatus 一致（cardParamMap 的值必须是字符串）
 const AICardStatus = {
@@ -1141,6 +1141,45 @@ async function createAICard(
   return createAICardForTarget(config, target, log);
 }
 
+/**
+ * 确保 Markdown 表格前有空行，否则钉钉无法正确渲染表格。
+ *
+ * 逐行向前看：当前行像表头（含 `|`）且下一行是分隔行时，
+ * 若前一行非空且非表格行，则在表头前插入空行。
+ * 支持缩进表格（行首有空白字符）。
+ */
+function ensureTableBlankLines(text: string): string {
+  const lines = text.split('\n');
+  const result: string[] = [];
+
+  // 匹配表格分隔行 (例如 | --- | --- | 或 --- | ---)
+  const tableDividerRegex = /^\s*\|?\s*:?-+:?\s*(\|?\s*:?-+:?\s*)+\|?\s*$/;
+  // 匹配包含竖线的表格行
+  const tableRowRegex = /^\s*\|?.*\|.*\|?\s*$/;
+
+  const isDivider = (line: string) => line.includes('|') && tableDividerRegex.test(line);
+
+  for (let i = 0; i < lines.length; i++) {
+    const currentLine = lines[i];
+    const nextLine = lines[i + 1] ?? '';
+
+    // 逻辑：
+    // 1. 当前行看起来像表头（包含 |）
+    // 2. 下一行是分隔行（---）
+    // 3. 前一行不是空行且不是表格行
+    if (
+      tableRowRegex.test(currentLine) &&
+      isDivider(nextLine) &&
+      i > 0 && lines[i - 1].trim() !== '' && !tableRowRegex.test(lines[i - 1])
+    ) {
+      result.push('');
+    }
+
+    result.push(currentLine);
+  }
+  return result.join('\n');
+}
+
 // 流式更新 AI Card 内容
 async function streamAICard(
   card: AICardInstance,
@@ -1177,11 +1216,12 @@ async function streamAICard(
   }
 
   // 调用 streaming API 更新内容
+  const fixedContent = ensureTableBlankLines(content);
   const body = {
     outTrackId: card.cardInstanceId,
     guid: `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
     key: 'msgContent',
-    content: content,
+    content: fixedContent,
     isFull: true,  // 全量替换
     isFinalize: finished,
     isError: false,
@@ -1205,10 +1245,11 @@ async function finishAICard(
   content: string,
   log?: any,
 ): Promise<void> {
-  log?.info?.(`[DingTalk][AICard] 开始 finish，最终内容长度=${content.length}`);
+  const fixedContent = ensureTableBlankLines(content);
+  log?.info?.(`[DingTalk][AICard] 开始 finish，最终内容长度=${fixedContent.length}`);
 
   // 1. 先用最终内容关闭流式通道（isFinalize=true），确保卡片显示替换后的内容
-  await streamAICard(card, content, true, log);
+  await streamAICard(card, fixedContent, true, log);
 
   // 2. 更新卡片状态为 FINISHED
   const body = {
@@ -1216,7 +1257,7 @@ async function finishAICard(
     cardData: {
       cardParamMap: {
         flowStatus: AICardStatus.FINISHED,
-        msgContent: content,
+        msgContent: fixedContent,
         staticMsgContent: '',
         sys_full_json_obj: JSON.stringify({
           order: ['msgContent'],  // 只声明实际使用的字段，避免部分客户端显示空占位
@@ -1377,6 +1418,8 @@ interface GatewayOptions {
   memoryUser?: string;
   /** 本地图片文件路径列表，用于 OpenClaw AgentMediaPayload */
   imageLocalPaths?: string[];
+  /** 自定义 Gateway URL（如通过 Nginx 代理），用于 TLS 等场景 */
+  gatewayBaseUrl?: string;
   /** 会话类型：'direct'（单聊）或 'group'（群聊），用于 bindings 匹配 */
   peerKind?: 'direct' | 'group';
   /** 发送者 ID，用于 bindings 匹配 */
@@ -1386,10 +1429,13 @@ interface GatewayOptions {
 }
 
 async function* streamFromGateway(options: GatewayOptions, accountId: string): AsyncGenerator<string, void, unknown> {
-  const { userContent, systemPrompts, sessionKey, gatewayAuth, memoryUser, imageLocalPaths, peerKind, peerId, gatewayPort, log } = options;
+  // 支持自定义 Gateway URL（如通过 Nginx 代理），用于 TLS 等场景
+  const { userContent, systemPrompts, sessionKey, gatewayAuth, gatewayBaseUrl, memoryUser, imageLocalPaths, peerKind, peerId, gatewayPort, log } = options;
   const rt = getRuntime();
   const port = gatewayPort || rt.gateway?.port || 18789;
-  const gatewayUrl = `http://127.0.0.1:${port}/v1/chat/completions`;
+  const gatewayUrl = gatewayBaseUrl
+    ? `${gatewayBaseUrl}/v1/chat/completions`
+    : `http://127.0.0.1:${port}/v1/chat/completions`;
 
   const messages: any[] = [];
   for (const prompt of systemPrompts) {
@@ -1693,7 +1739,7 @@ async function sendMarkdownMessage(
   options: any = {},
 ): Promise<any> {
   const token = await getAccessToken(config);
-  let text = markdown;
+  let text = ensureTableBlankLines(markdown);
   if (options.atUserId) text = `${text} @${options.atUserId}`;
 
   const body: any = {
@@ -2230,7 +2276,7 @@ function buildMsgPayload(
         msgKey: 'sampleMarkdown',
         msgParam: {
           title: title || content.split('\n')[0].replace(/^[#*\s\->]+/, '').slice(0, 20) || 'Message',
-          text: content,
+          text: ensureTableBlankLines(content),
         },
       };
     case 'link':
@@ -2380,7 +2426,7 @@ async function sendToUser(
     return { ok: false, error: 'Missing clientId or clientSecret', usedAICard: false };
   }
 
-  const userIdArray = Array.isArray(userIds) ? userIds : [userIds];
+  const userIdArray = (Array.isArray(userIds) ? userIds : [userIds]).filter((id) => Boolean(id));
   if (userIdArray.length === 0) {
     return { ok: false, error: 'userIds cannot be empty', usedAICard: false };
   }
@@ -2495,6 +2541,62 @@ async function sendProactive(
   return { ok: false, error: 'Must specify userId, userIds, or openConversationId', usedAICard: false };
 }
 
+// ============ 消息处理中表情 ============
+
+/** 在用户消息上贴 🤔思考中 表情，表示正在处理 */
+async function addEmotionReply(config: any, data: any, log?: any): Promise<void> {
+  if (!data.msgId || !data.conversationId) return;
+  try {
+    const token = await getAccessToken(config);
+    await axios.post(`${DINGTALK_API}/v1.0/robot/emotion/reply`, {
+      robotCode: data.robotCode ?? config.clientId,
+      openMsgId: data.msgId,
+      openConversationId: data.conversationId,
+      emotionType: 2,
+      emotionName: '🤔思考中',
+      textEmotion: {
+        emotionId: '2659900',
+        emotionName: '🤔思考中',
+        text: '🤔思考中',
+        backgroundId: 'im_bg_1',
+      },
+    }, {
+      headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
+      timeout: 5_000,
+    });
+    log?.info?.(`[DingTalk][Emotion] 贴表情成功: msgId=${data.msgId}`);
+  } catch (err: any) {
+    log?.warn?.(`[DingTalk][Emotion] 贴表情失败（不影响主流程）: ${err.message}`);
+  }
+}
+
+/** 撤回用户消息上的 🤔思考中 表情 */
+async function recallEmotionReply(config: any, data: any, log?: any): Promise<void> {
+  if (!data.msgId || !data.conversationId) return;
+  try {
+    const token = await getAccessToken(config);
+    await axios.post(`${DINGTALK_API}/v1.0/robot/emotion/recall`, {
+      robotCode: data.robotCode ?? config.clientId,
+      openMsgId: data.msgId,
+      openConversationId: data.conversationId,
+      emotionType: 2,
+      emotionName: '🤔思考中',
+      textEmotion: {
+        emotionId: '2659900',
+        emotionName: '🤔思考中',
+        text: '🤔思考中',
+        backgroundId: 'im_bg_1',
+      },
+    }, {
+      headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
+      timeout: 5_000,
+    });
+    log?.info?.(`[DingTalk][Emotion] 撤回表情成功: msgId=${data.msgId}`);
+  } catch (err: any) {
+    log?.warn?.(`[DingTalk][Emotion] 撤回表情失败（不影响主流程）: ${err.message}`);
+  }
+}
+
 // ============ 核心消息处理 (AI Card Streaming) ============
 
 async function handleDingTalkMessage(params: {
@@ -2679,6 +2781,10 @@ async function handleDingTalkMessage(params: {
   }
   if (!userContent && imageLocalPaths.length === 0) return;
 
+  // ===== 贴处理中表情 =====
+  await addEmotionReply(dingtalkConfig, data, log);
+
+  try {
   // ===== 异步模式：立即回执 + 后台执行 + 主动推送结果 =====
   const asyncMode = dingtalkConfig.asyncMode === true;
   const proactiveTarget = isDirect
@@ -2709,6 +2815,7 @@ async function handleDingTalkMessage(params: {
         systemPrompts,
         sessionKey: sessionContextJson,
         gatewayAuth,
+        gatewayBaseUrl: dingtalkConfig.gatewayBaseUrl,
         memoryUser,
         imageLocalPaths: imageLocalPaths.length > 0 ? imageLocalPaths : undefined,
         peerKind,
@@ -2786,6 +2893,7 @@ async function handleDingTalkMessage(params: {
         systemPrompts,
         sessionKey: sessionContextJson,
         gatewayAuth,
+        gatewayBaseUrl: dingtalkConfig.gatewayBaseUrl,
         memoryUser,
         imageLocalPaths: imageLocalPaths.length > 0 ? imageLocalPaths : undefined,
         peerKind,
@@ -2870,6 +2978,7 @@ async function handleDingTalkMessage(params: {
         systemPrompts,
         sessionKey: sessionContextJson,
         gatewayAuth,
+        gatewayBaseUrl: dingtalkConfig.gatewayBaseUrl,
         memoryUser,
         imageLocalPaths: imageLocalPaths.length > 0 ? imageLocalPaths : undefined,
         peerKind,
@@ -2909,6 +3018,10 @@ async function handleDingTalkMessage(params: {
       });
     }
   }
+  } finally {
+    // ===== 撤回处理中表情 =====
+    await recallEmotionReply(dingtalkConfig, data, log);
+  }
 }
 
 // ============ 钉钉文档 API ============
@@ -3253,6 +3366,7 @@ const dingtalkPlugin = {
         groupPolicy: { type: 'string', enum: ['open', 'allowlist'], default: 'open' },
         gatewayToken: { type: 'string', default: '', description: 'Gateway auth token (Bearer)' },
         gatewayPassword: { type: 'string', default: '', description: 'Gateway auth password (alternative to token)' },
+        gatewayBaseUrl: { type: 'string', default: '', description: 'Custom Gateway URL (e.g., http://127.0.0.1:18788 for Nginx proxy to TLS Gateway)' },
         sessionTimeout: { type: 'number', default: 1800000, description: 'Session timeout in ms (default 30min)' },
         separateSessionByConversation: { type: 'boolean', default: true, description: '是否按单聊/群聊/群区分 session' },
         sharedMemoryAcrossConversations: { type: 'boolean', default: false, description: '单 agent 场景下是否共享记忆；false 时不同群聊、群聊与私聊记忆隔离' },
@@ -3282,7 +3396,10 @@ const dingtalkPlugin = {
       const config = getConfig(cfg);
       const id = accountId || DEFAULT_ACCOUNT_ID;
       if (config.accounts?.[id]) {
-        return { accountId: id, config: config.accounts[id], enabled: config.accounts[id].enabled !== false };
+        // 合并 channel 级别配置（如 gatewayBaseUrl）到 account 配置
+        const { accounts, ...channelConfig } = config;
+        const mergedConfig = { ...channelConfig, ...config.accounts[id] };
+        return { accountId: id, config: mergedConfig, enabled: config.accounts[id].enabled !== false };
       }
       // 没有 accounts 配置或找不到指定账号时，使用顶层配置
       return { accountId: DEFAULT_ACCOUNT_ID, config, enabled: config.enabled !== false };
@@ -3458,7 +3575,7 @@ const dingtalkPlugin = {
 
         // 【消息去重】检查是否已处理过该消息
         if (messageId && isMessageProcessed(messageId)) {
-          ctx.log?.warn?.(`[DingTalk] 检测到重复消息，跳过处理: messageId=${messageId}`);
+          ctx.log?.warn?.(`[DingTalk][${account.accountId}] 检测到重复消息，跳过处理: messageId=${messageId}`);
           return;
         }
 
@@ -3859,3 +3976,77 @@ export {
   // 钉钉文档客户端
   DingtalkDocsClient,
 };
+
+// ============ 测试辅助导出 ============
+// 仅用于单元测试，避免在业务代码中直接依赖内部实现细节
+export const __testables = {
+  // Markdown 修正
+  ensureTableBlankLines,
+  // 会话 & 去重
+  normalizeSlashCommand,
+  buildSessionContext,
+  isMessageProcessed,
+  markMessageProcessed,
+  cleanupProcessedMessages,
+  // 配置 & Token
+  getConfig,
+  isConfigured,
+  getAccessToken,
+  getOapiAccessToken,
+  getUnionId,
+  // 媒体处理
+  toLocalPath,
+  processLocalImages,
+  uploadMediaToDingTalk,
+  downloadImageToFile,
+  downloadMediaByCode,
+  downloadFileByCode,
+  // 视频处理
+  extractVideoMetadata,
+  extractVideoThumbnail,
+  processVideoMarkers,
+  sendVideoMessage,
+  // 音频处理
+  getFfprobePath,
+  extractAudioDuration,
+  sendAudioMessage,
+  processAudioMarkers,
+  isAudioFile,
+  // 文件处理
+  extractFileMarkers,
+  sendFileMessage,
+  processFileMarkers,
+  // 消息内容提取
+  extractMessageContent,
+  // 消息发送
+  sendMarkdownMessage,
+  sendTextMessage,
+  sendMessage,
+  // 提示词与消息体
+  buildMediaSystemPrompt,
+  buildDeliverBody,
+  buildMsgPayload,
+  // AI Card
+  createAICard,
+  streamAICard,
+  finishAICard,
+  createAICardForTarget,
+  sendFileProactive,
+  sendAudioProactive,
+  sendVideoProactive,
+  sendAICardInternal,
+  sendAICardToUser,
+  sendAICardToGroup,
+  // 主动消息
+  sendNormalToUser,
+  sendNormalToGroup,
+  sendToUser,
+  sendToGroup,
+  sendProactive,
+  // Bindings 解析（测试时需 mock getRuntime/fs/path/os）
+  resolveAgentIdByBindings,
+  /** 仅测试用：注入 runtime 使 resolveAgentIdByBindings 不抛错 */
+  setRuntimeForTest(r: PluginRuntime | null) {
+    runtime = r;
+  },
+};

package/tests/README.md

@@ -0,0 +1,54 @@
+# plugin 测试说明
+
+本目录按**测试套件（模块）**划分，每个子目录包含：**测试代码**（`*.test.ts`）与**测试方案**（`PLAN.md`）。方案中给出模块职责、用例表（含输入/期望/说明）以及正确/错误输出原因，便于覆盖全部情况并扩展用例。
+
+其中大多数为**单元测试/契约测试**（基于 mock 的纯函数与 I/O 边界验证）；`integration` 为**端到端集成测试**（需要真实钉钉凭证，默认跳过）。
+
+## 模块列表
+
+| 目录 | 覆盖函数/能力 | 说明 |
+|------|----------------|------|
+| [session](./session/) | normalizeSlashCommand, buildSessionContext, isMessageProcessed, markMessageProcessed, cleanupProcessedMessages | 会话与消息去重 |
+| [config-token](./config-token/) | getConfig, isConfigured, getAccessToken, getOapiAccessToken, getUnionId | 配置与 Token |
+| [media](./media/) | toLocalPath, processLocalImages | 本地路径与图片后处理 |
+| [video](./video/) | processVideoMarkers | 视频标记解析与控制流 |
+| [message-extract](./message-extract/) | extractMessageContent | 钉钉消息内容提取（text/richText/picture/audio/video/file） |
+| [file-markers](./file-markers/) | extractFileMarkers, isAudioFile | 文件标记解析与音频类型判断 |
+| [prompts](./prompts/) | buildMediaSystemPrompt | 媒体相关系统提示词 |
+| [deliver-payload](./deliver-payload/) | buildDeliverBody, buildMsgPayload | AI Card 投放体与普通消息体 |
+| [bindings](./bindings/) | resolveAgentIdByBindings | OpenClaw bindings 解析（需 mock fs/path/os） |
+| [ai-card](./ai-card/) | create/stream/finish AI Card, sendAICard* | AI Card 创建与流式更新（结构化返回 + 回退） |
+| [card-update](./card-update/) | createAICard + stream/finish 状态机（回归集） | 轻量回归：目标选择与 INPUTING→streaming→FINISHED 状态机（避免与 ai-card/proactive 重复） |
+| [send-message](./send-message/) | sendTextMessage, sendMarkdownMessage, sendMessage | 群机器人 webhook 发送（自动 text/markdown 判定） |
+| [proactive](./proactive/) | buildMsgPayload, sendNormalTo*, sendTo*, sendProactive | 主动消息 API：消息体构造、AI Card 策略与回退 |
+| [audio](./audio/) | isAudioFile, getFfprobePath, extractAudioDuration, processAudioMarkers, sendAudio* | 音频识别、时长解析与音频发送 |
+| [upload](./upload/) | uploadMediaToDingTalk, download*/extractVideo*, process*Markers | 上传/下载/媒体处理与 marker 处理（多分支容错） |
+| [download](./download/) | downloadImageToFile, downloadMediaByCode, downloadFileByCode | 下载与文件名/扩展名推断 |
+| [mcp-tools](./mcp-tools/) | MCP 工具层：sendToUser/sendToGroup/sendProactive/uploadMedia... | 对外工具输入校验与行为一致性 |
+| [core](./core/) | normalizeSlashCommand/getConfig/getAccessToken/... | 核心能力冒烟/回归集合（跨模块快速验证） |
+| [integration](./integration/) | getAccessToken, sendToUser, AI Card, media upload | 端到端集成测试（需要真实环境变量） |
+
+## 运行方式
+
+```bash
+npm test          # 运行全部用例
+npm run test:watch  # 监听模式
+npm run test:integration  # 仅运行集成测试（需要环境变量）
+```
+
+## 扩展用例
+
+- 各 `PLAN.md` 中均有用例表（序号 + 输入 + 期望 + 说明），可按表在对应 `*.test.ts` 中用 `it.each` 或单条 `it` 补充，实现“成百上千条”覆盖。
+- 依赖真实外部环境（如钉钉 API、真实文件系统、ffmpeg/ffprobe）的路径，优先在单元测试中做 **mock + 契约断言**；需要验证真实链路时再放到 `integration`（或后续 E2E）中补充。
+
+## 测试编写约定（建议遵循）
+
+- **模块职责优先**：每个 `tests/<suite>/` 只覆盖该域内的能力；不要在一个套件里测试“顺手能调到”的其它函数（避免重复与耦合）。
+- **断言优先级**：
+  - **优先断言契约**：关键字段（如 `msgKey/msgParam/openSpaceId`）与错误返回结构（如 `ok=false` 时 `error`）。
+  - **避免断言实现细节**：例如随机生成的 id、时间戳、日志完整文本等。
+- **Mock 外部依赖**：
+  - 网络：优先 `vi.mock('axios')` + hoisted mock，并按 URL 分流（token 获取与业务请求常共用 `axios.post`）。
+  - 文件系统：尽量用 `await import('fs')` 的代码路径以便在测试中 `vi.mock('fs')/vi.doMock('fs')` 生效。
+  - 外部工具（ffmpeg/ffprobe）：测试中不依赖真实二进制与文件存在性；失败路径应可预测（返回 `null` 或默认值），必要时用集成测试覆盖真实链路。
+- **避免共享状态污染**：若被测模块存在模块级缓存（如 token 缓存），在需要隔离的用例中使用 `vi.resetModules()` 后再 `import`。

package/tests/ai-card/PLAN.md

@@ -0,0 +1,54 @@
+# AI Card 模块测试方案
+
+## 1. 模块划分与职责
+
+本套件覆盖 AI Card 相关能力（创建/流式更新/结束/投放与回退），主要围绕以下通过 `plugin.__testables` 暴露的函数：
+
+- **buildDeliverBody(cardInstanceId, target, robotCode)**：构建投放请求体（核心契约：`openSpaceId` 与 deliver model）。
+- **createAICardForTarget(config, target, log?)**：通用创建+投放，返回 `{ cardInstanceId, accessToken, inputingStarted }` 或 null。
+- **createAICard(config, data, log?)**：被动回复场景创建卡片（从 DingTalk 回调 `data` 推导 target 后委托给 createAICardForTarget）。
+- **streamAICard(card, content, finished?, log?)**：流式更新（首次会切换 INPUTING；失败会 throw）。
+- **finishAICard(card, content, log?)**：结束卡片（finalize streaming + 设置 FINISHED；FINISHED 写入失败会记录日志但不抛异常）。
+- **sendAICardInternal / sendAICardToUser / sendAICardToGroup**：主动发送 AI Card（失败可按策略回退到普通消息）。
+
+## 2. 用例表（覆盖现有测试）
+
+### 2.1 buildDeliverBody
+
+| 序号 | 场景 | mock/输入 | 期望 | 说明 |
+|------|------|-----------|------|------|
+| 1 | user target | target={type:'user', userId:'u1'} | openSpaceId 为 `dtv1.card//IM_ROBOT.u1` | deliver model 正确 |
+| 2 | group target | target={type:'group', openConversationId:'c1'} | openSpaceId 为 `dtv1.card//IM_GROUP.c1` | deliver model 正确 |
+
+### 2.2 createAICardForTarget
+
+| 序号 | 场景 | mock/输入 | 期望 | 说明 |
+|------|------|-----------|------|------|
+| 3 | user 创建投放成功 | POST instances + deliver 成功 | 返回 cardInstanceId/accessToken | 并投放到 IM_ROBOT |
+| 4 | group 创建投放成功 | 同上 | 返回非空 | 并投放到 IM_GROUP |
+| 5 | create 失败 | axios.post reject | 返回 null | 错误收敛 |
+| 6 | deliver 失败 | deliver reject | 返回 null | 错误收敛 |
+
+### 2.3 streamAICard / finishAICard
+
+| 序号 | 场景 | 输入 | 期望 | 说明 |
+|------|------|------|------|------|
+| 7 | 首次 stream | inputingStarted=false | 先 INPUTING 再 streaming | INPUTING 失败会 throw |
+| 8 | 后续 stream | inputingStarted=true | 仅 streaming | 不重复 INPUTING |
+| 9 | finish | - | finalize streaming + FINISHED | FINISHED 失败记录 error 不 throw |
+
+### 2.4 sendAICardInternal / sendAICardToUser / sendAICardToGroup
+
+| 序号 | 场景 | mock/输入 | 期望 | 说明 |
+|------|------|-----------|------|------|
+| 10 | internal 用户发送成功 | gettoken + create + put 成功 | `ok=true` | 主流程 |
+| 11 | internal 群发送成功 | 同上 | `ok=true` | 主流程 |
+| 12 | internal 创建失败 | create 抛错 | `ok=false` + `error` | 错误返回 |
+| 13 | toUser 带回退 | 卡片失败、普通消息成功（若实现有回退） | `ok=true` | 体现“回退不影响 ok” |
+| 14 | toGroup 带回退 | 同上 | `ok=true` |  |
+
+## 3. 预期正确输出与潜在错误
+
+- **正确**：deliver body 的 `openSpaceId/robotCode` 契约稳定；createAICardForTarget 返回结构稳定；stream/finish 状态机顺序正确；外部错误被收敛为 null/throw（按函数契约）。
+- **潜在错误原因**：openSpaceId 拼错（IM_ROBOT/IM_GROUP）；deliver model 字段缺失；stream 首次未切 INPUTING；把应 throw 的路径吞掉导致上层误判成功。
+