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

package/tests/download/download.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock axios
+const mockAxiosGet = vi.hoisted(() => vi.fn());
+const mockAxiosPost = vi.hoisted(() => vi.fn());
+vi.mock('axios', () => ({
+  default: {
+    get: mockAxiosGet,
+    post: mockAxiosPost,
+  },
+}));
+
+// Mock fs
+const mockFs = vi.hoisted(() => ({
+  existsSync: vi.fn().mockReturnValue(true),
+  mkdirSync: vi.fn(),
+  writeFileSync: vi.fn(),
+  statSync: vi.fn().mockReturnValue({ size: 1024 }),
+}));
+vi.mock('fs', () => mockFs);
+
+// Mock path and os
+vi.mock('path', () => ({
+  join: (...args: string[]) => args.join('/'),
+  basename: (p: string) => p.split('/').pop() || '',
+  extname: (p: string) => {
+    const idx = p.lastIndexOf('.');
+    return idx >= 0 ? p.slice(idx) : '';
+  },
+  dirname: (p: string) => p.split('/').slice(0, -1).join('/'),
+}));
+
+vi.mock('os', () => ({
+  homedir: () => '/fake-home',
+  tmpdir: () => '/tmp',
+}));
+
+const log = {
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+};
+
+describe('download helpers', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('downloadImageToFile', () => {
+    it('should download image and return local path', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadImageToFile } = __testables as any;
+
+      const mockBuffer = Buffer.from('fake-image-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+        headers: { 'content-type': 'image/jpeg' },
+      });
+
+      const result = await downloadImageToFile('https://example.com/image.jpg', log);
+
+      expect(result).toMatch(/\/fake-home\/\.openclaw\/workspace\/media\/inbound\/openclaw-media-.*\.jpg/);
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should detect png content type', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadImageToFile } = __testables as any;
+
+      const mockBuffer = Buffer.from('fake-png-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+        headers: { 'content-type': 'image/png' },
+      });
+
+      const result = await downloadImageToFile('https://example.com/image.png', log);
+
+      expect(result).toMatch(/\.png$/);
+    });
+
+    it('should detect gif content type', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadImageToFile } = __testables as any;
+
+      const mockBuffer = Buffer.from('fake-gif-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+        headers: { 'content-type': 'image/gif' },
+      });
+
+      const result = await downloadImageToFile('https://example.com/image.gif', log);
+
+      expect(result).toMatch(/\.gif$/);
+    });
+
+    it('should detect webp content type', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadImageToFile } = __testables as any;
+
+      const mockBuffer = Buffer.from('fake-webp-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+        headers: { 'content-type': 'image/webp' },
+      });
+
+      const result = await downloadImageToFile('https://example.com/image.webp', log);
+
+      expect(result).toMatch(/\.webp$/);
+    });
+
+    it('should default to jpg for unknown content type', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadImageToFile } = __testables as any;
+
+      const mockBuffer = Buffer.from('fake-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+        headers: { 'content-type': 'application/octet-stream' },
+      });
+
+      const result = await downloadImageToFile('https://example.com/image', log);
+
+      expect(result).toMatch(/\.jpg$/);
+    });
+
+    it('should return null on download failure', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadImageToFile } = __testables as any;
+
+      mockAxiosGet.mockRejectedValue(new Error('Network error'));
+
+      const result = await downloadImageToFile('https://example.com/image.jpg', log);
+
+      expect(result).toBeNull();
+      expect(log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('downloadMediaByCode', () => {
+    it('should download media using downloadCode', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadMediaByCode } = __testables as any;
+
+      mockAxiosPost.mockResolvedValue({
+        data: { downloadUrl: 'https://example.com/download.jpg' },
+      });
+
+      const mockBuffer = Buffer.from('fake-image-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+        headers: { 'content-type': 'image/jpeg' },
+      });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const result = await downloadMediaByCode('code123', config, log);
+
+      expect(result).toMatch(/\.jpg$/);
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should return null when no downloadUrl in response', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadMediaByCode } = __testables as any;
+
+      mockAxiosPost.mockResolvedValue({
+        data: { errcode: 1, errmsg: 'error' },
+      });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const result = await downloadMediaByCode('code123', config, log);
+
+      expect(result).toBeNull();
+      expect(log.warn).toHaveBeenCalled();
+    });
+
+    it('should return null on API error', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadMediaByCode } = __testables as any;
+
+      mockAxiosPost.mockRejectedValue(new Error('API error'));
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const result = await downloadMediaByCode('code123', config, log);
+
+      expect(result).toBeNull();
+      expect(log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('downloadFileByCode', () => {
+    it('should download file and preserve original filename', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadFileByCode } = __testables as any;
+
+      mockAxiosPost.mockResolvedValue({
+        data: { downloadUrl: 'https://example.com/download' },
+      });
+
+      const mockBuffer = Buffer.from('fake-file-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+      });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const result = await downloadFileByCode('code123', 'report.pdf', config, log);
+
+      expect(result).toMatch(/report\.pdf$/);
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should sanitize filename with special characters', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadFileByCode } = __testables as any;
+
+      mockAxiosPost.mockResolvedValue({
+        data: { downloadUrl: 'https://example.com/download' },
+      });
+
+      const mockBuffer = Buffer.from('fake-file-data');
+      mockAxiosGet.mockResolvedValue({
+        data: mockBuffer,
+      });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const result = await downloadFileByCode('code123', 'file/with:invalid*chars.pdf', config, log);
+
+      // 只校验文件名本身被清理；完整路径一定会包含 '/'。
+      const fileName = result?.split('/').pop() || '';
+      expect(fileName).not.toMatch(/[\\:*?"<>|]/);
+      expect(fileName).toContain('file_with_invalid_chars');
+    });
+
+    it('should return null when no downloadUrl in response', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadFileByCode } = __testables as any;
+
+      mockAxiosPost.mockResolvedValue({
+        data: {},
+      });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const result = await downloadFileByCode('code123', 'file.pdf', config, log);
+
+      expect(result).toBeNull();
+      expect(log.warn).toHaveBeenCalled();
+    });
+
+    it('should return null on download failure', async () => {
+      const { __testables } = await import('../../plugin');
+      const { downloadFileByCode } = __testables as any;
+
+      mockAxiosPost.mockRejectedValue(new Error('API error'));
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const result = await downloadFileByCode('code123', 'file.pdf', config, log);
+
+      expect(result).toBeNull();
+      expect(log.error).toHaveBeenCalled();
+    });
+  });
+});

package/tests/file-markers/PLAN.md

@@ -0,0 +1,74 @@
+# 文件标记与音频类型模块测试方案
+
+## 1. 模块划分与职责
+
+- **extractFileMarkers(content: string, log?: any): { cleanedContent: string; fileInfos: FileInfo[] }**
+  - 职责：从 AI 回复内容中匹配 `[DINGTALK_FILE]{...}[/DINGTALK_FILE]`，解析 JSON 得到 `{ path, fileName, fileType }`，校验 path 与 fileName 存在后收集到 fileInfos，并移除标记得到 cleanedContent。
+- **isAudioFile(fileType: string): boolean**
+  - 职责：判断扩展名是否为支持的音频类型（mp3, wav, amr, ogg, aac, flac, m4a），大小写不敏感。
+
+## 2. 用例矩阵（全覆盖）
+
+### 2.1 isAudioFile
+
+| 序号 | 输入 fileType | 期望 | 说明 |
+|------|----------------|------|------|
+| 1 | `'mp3'` | true | 小写 |
+| 2 | `'MP3'` | true | 大写 |
+| 3 | `'Mp3'` | true | 混合 |
+| 4 | `'wav'` / `'amr'` / `'ogg'` / `'aac'` / `'flac'` / `'m4a'` | true | 其余支持格式 |
+| 5 | `'txt'` | false | 非音频 |
+| 6 | `''` | false | 空字符串 |
+| 7 | `'mp4'` | false | 视频格式 |
+| 8 | `'.mp3'` | false | 带点号（代码用 includes(fileType.toLowerCase())，未 strip 点） |
+
+### 2.2 extractFileMarkers — 无标记
+
+| 序号 | 输入 content | 期望 cleanedContent | 期望 fileInfos | 说明 |
+|------|--------------|---------------------|----------------|------|
+| 9 | `''` | `''` | `[]` | 空字符串 |
+| 10 | `'plain text'` | `'plain text'` | `[]` | 无标记 |
+| 11 | `'[DINGTALK_FILE]'` | 原样（无闭合） | `[]` | 不匹配正则 |
+
+### 2.3 extractFileMarkers — 合法单个标记
+
+| 序号 | 输入 content | 期望 fileInfos[0] | 期望 cleanedContent | 说明 |
+|------|--------------|-------------------|---------------------|------|
+| 12 | `'hi [DINGTALK_FILE]{"path":"/tmp/a.pdf","fileName":"a.pdf","fileType":"pdf"}[/DINGTALK_FILE] end'` | path=/tmp/a.pdf, fileName=a.pdf, fileType=pdf | 'hi  end'（中间标记被移除，保留空格） | 标准格式 |
+| 13 | `'[DINGTALK_FILE]{"path":"C:\\\\x.docx","fileName":"文档.docx","fileType":"docx"}[/DINGTALK_FILE]'` | path=C:\\x.docx, fileName=文档.docx, fileType=docx | '' | 反斜杠与中文文件名 |
+
+### 2.4 extractFileMarkers — 缺 path 或 fileName 不收集
+
+| 序号 | 输入 content | 期望 fileInfos | 说明 |
+|------|--------------|----------------|------|
+| 14 | `'[DINGTALK_FILE]{"path":"/x.pdf","fileName":""}[/DINGTALK_FILE]'` | `[]` | fileName 空不满足 fileInfo.path && fileInfo.fileName |
+| 15 | `'[DINGTALK_FILE]{"path":"","fileName":"a.pdf"}[/DINGTALK_FILE]'` | `[]` | path 空不收集 |
+| 16 | `'[DINGTALK_FILE]{"fileName":"a.pdf"}[/DINGTALK_FILE]'` | `[]` | 缺 path |
+| 17 | `'[DINGTALK_FILE]{"path":"/a.pdf"}[/DINGTALK_FILE]'` | `[]` | 缺 fileName |
+
+### 2.5 extractFileMarkers — 非法 JSON
+
+| 序号 | 输入 content | 期望 fileInfos | 期望 cleanedContent | 说明 |
+|------|--------------|----------------|---------------------|------|
+| 18 | `'[DINGTALK_FILE]{invalid-json}[/DINGTALK_FILE]'` | `[]` | ''（标记仍被 replace 掉） | JSON.parse 抛错，log.warn 调用 |
+| 19 | `'[DINGTALK_FILE]{}[/DINGTALK_FILE]'` | `[]` | '' | 空对象缺 path/fileName |
+| 20 | `'[DINGTALK_FILE]{ "path": "/x", "fileName": "x" }[/DINGTALK_FILE]'` | `[{ path: '/x', fileName: 'x', fileType: undefined }]` | '' | 合法 JSON，fileType 可缺 |
+
+### 2.6 extractFileMarkers — 多个标记
+
+| 序号 | 输入 content | 期望 fileInfos.length | 期望 cleanedContent | 说明 |
+|------|--------------|------------------------|---------------------|------|
+| 21 | 两段合法 [DINGTALK_FILE]...[/DINGTALK_FILE] | 2 | 中间文本保留、两处标记移除 | 多文件 |
+| 22 | 一段合法 + 一段非法 JSON | 1 | 两段标记都被移除 | 混合 |
+
+### 2.7 extractFileMarkers — 边界与 trim
+
+| 序号 | 输入 content | 期望 cleanedContent | 说明 |
+|------|--------------|---------------------|------|
+| 23 | `'  [DINGTALK_FILE]{"path":"/a","fileName":"a"}[/DINGTALK_FILE]  '` | `''` | 前后空格被 trim |
+| 24 | `'x[DINGTALK_FILE]{"path":"/a","fileName":"a"}[/DINGTALK_FILE]y'` | `'xy'` | 中间无空格 |
+
+## 3. 预期正确输出与潜在错误
+
+- **正确输出**：fileInfos 仅包含 path 与 fileName 均非空的项；cleanedContent 为移除所有 FILE_MARKER 后 trim 的结果；log.info/warn 按实现调用。
+- **潜在错误原因**：正则贪婪/非贪婪错误导致多匹配或少匹配；JSON.parse 未 try-catch 导致整函数抛错；校验写成 path || fileName 导致只填一个也通过；replace 后未 trim。

package/tests/file-markers/file-markers.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi } from 'vitest';
+import { __testables } from '../../plugin';
+
+const { extractFileMarkers, isAudioFile } = __testables as any;
+
+describe('isAudioFile', () => {
+  it.each([
+    ['mp3', true],
+    ['MP3', true],
+    ['Mp3', true],
+    ['wav', true],
+    ['amr', true],
+    ['ogg', true],
+    ['aac', true],
+    ['flac', true],
+    ['m4a', true],
+    ['txt', false],
+    ['', false],
+    ['mp4', false],
+    ['pdf', false],
+  ] as const)('isAudioFile(%s) === %s', (fileType, expected) => {
+    expect(isAudioFile(fileType)).toBe(expected);
+  });
+});
+
+describe('extractFileMarkers', () => {
+  const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+  describe('no markers', () => {
+    it.each([
+      ['', '', []],
+      ['plain text', 'plain text', []],
+    ] as const)('content="%s" -> cleanedContent="%s", fileInfos.length=%s', (content, cleaned, len) => {
+      const out = extractFileMarkers(content, log);
+      expect(out.cleanedContent).toBe(cleaned);
+      expect(out.fileInfos).toHaveLength(len);
+    });
+  });
+
+  describe('valid single marker', () => {
+    it('extracts path, fileName, fileType and removes marker', () => {
+      const content = 'hi [DINGTALK_FILE]{"path":"/tmp/a.pdf","fileName":"a.pdf","fileType":"pdf"}[/DINGTALK_FILE] end';
+      const out = extractFileMarkers(content, log);
+      expect(out.fileInfos).toHaveLength(1);
+      expect(out.fileInfos[0]).toEqual({ path: '/tmp/a.pdf', fileName: 'a.pdf', fileType: 'pdf' });
+      expect(out.cleanedContent).toBe('hi  end');
+    });
+    it('accepts optional fileType and unicode fileName', () => {
+      const content = '[DINGTALK_FILE]{"path":"/x.docx","fileName":"文档.docx"}[/DINGTALK_FILE]';
+      const out = extractFileMarkers(content, log);
+      expect(out.fileInfos).toHaveLength(1);
+      expect(out.fileInfos[0].path).toBe('/x.docx');
+      expect(out.fileInfos[0].fileName).toBe('文档.docx');
+      expect(out.cleanedContent).toBe('');
+    });
+  });
+
+  describe('missing path or fileName -> not collected', () => {
+    it.each([
+      ['[DINGTALK_FILE]{"path":"/x.pdf","fileName":""}[/DINGTALK_FILE]', 0],
+      ['[DINGTALK_FILE]{"path":"","fileName":"a.pdf"}[/DINGTALK_FILE]', 0],
+      ['[DINGTALK_FILE]{"fileName":"a.pdf"}[/DINGTALK_FILE]', 0],
+      ['[DINGTALK_FILE]{"path":"/a.pdf"}[/DINGTALK_FILE]', 0],
+    ] as const)('content -> fileInfos.length=%s', (content, len) => {
+      const out = extractFileMarkers(content, log);
+      expect(out.fileInfos).toHaveLength(len);
+    });
+  });
+
+  describe('invalid JSON in marker', () => {
+    it('returns empty fileInfos and removes marker', () => {
+      const content = '[DINGTALK_FILE]{invalid-json}[/DINGTALK_FILE]';
+      const out = extractFileMarkers(content, log);
+      expect(out.fileInfos).toHaveLength(0);
+      expect(out.cleanedContent).toBe('');
+      expect(log.warn).toHaveBeenCalled();
+    });
+    it('empty object -> no path/fileName', () => {
+      const content = '[DINGTALK_FILE]{}[/DINGTALK_FILE]';
+      const out = extractFileMarkers(content, log);
+      expect(out.fileInfos).toHaveLength(0);
+      expect(out.cleanedContent).toBe('');
+    });
+  });
+
+  describe('multiple markers', () => {
+    it('two valid markers', () => {
+      const content =
+        'a [DINGTALK_FILE]{"path":"/1.pdf","fileName":"1.pdf"}[/DINGTALK_FILE] b [DINGTALK_FILE]{"path":"/2.pdf","fileName":"2.pdf"}[/DINGTALK_FILE] c';
+      const out = extractFileMarkers(content, log);
+      expect(out.fileInfos).toHaveLength(2);
+      expect(out.fileInfos[0].fileName).toBe('1.pdf');
+      expect(out.fileInfos[1].fileName).toBe('2.pdf');
+      expect(out.cleanedContent).toBe('a  b  c');
+    });
+  });
+
+  describe('trim cleanedContent', () => {
+    it('leading/trailing spaces trimmed', () => {
+      const content = '  [DINGTALK_FILE]{"path":"/a","fileName":"a"}[/DINGTALK_FILE]  ';
+      const out = extractFileMarkers(content, log);
+      expect(out.cleanedContent).toBe('');
+    });
+  });
+});

package/tests/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Test entry point for DingTalk OpenClaw Connector
+ * 
+ * This file exports lightweight, self-contained test utilities.
+ *
+ * Note: keep this file dependency-free (no missing re-exports), so importing it
+ * never breaks the test build.
+ */
+
+import { vi } from 'vitest';
+
+/**
+ * Test configuration
+ */
+export const testConfig = {
+  timeout: 10000,
+  retries: 3,
+  logLevel: 'info',
+};
+
+/**
+ * Create a mock config for testing
+ */
+export function createMockConfig(overrides: Partial<{
+  clientId: string;
+  clientSecret: string;
+  webhook?: string;
+}> = {}) {
+  return {
+    clientId: overrides.clientId || 'test-client-id',
+    clientSecret: overrides.clientSecret || 'test-client-secret',
+    webhook: overrides.webhook,
+  };
+}
+
+/**
+ * Create a mock logger for testing
+ */
+export function createMockLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  };
+}
+
+/**
+ * Create mock axios response
+ */
+export function createMockAxiosResponse(data: any, status = 200) {
+  return {
+    data,
+    status,
+    statusText: 'OK',
+    headers: {},
+    config: {},
+  };
+}
+
+/**
+ * Create mock file info
+ */
+export function createMockFileInfo(overrides: Partial<{
+  path: string;
+  fileName: string;
+  fileType: string;
+}> = {}) {
+  return {
+    path: overrides.path || '/tmp/test-file.pdf',
+    fileName: overrides.fileName || 'test-file.pdf',
+    fileType: overrides.fileType || 'pdf',
+  };
+}
+
+/**
+ * Create mock video metadata
+ */
+export function createMockVideoMetadata() {
+  return {
+    duration: 60,
+    width: 1920,
+    height: 1080,
+  };
+}
+
+/**
+ * Create mock target
+ */
+export function createMockUserTarget(userId = 'user123') {
+  return {
+    type: 'user' as const,
+    userId,
+  };
+}
+
+export function createMockGroupTarget(openConversationId = 'conv123') {
+  return {
+    type: 'group' as const,
+    openConversationId,
+  };
+}
+
+/**
+ * Wait for condition
+ */
+export async function waitFor(
+  condition: () => boolean,
+  timeout = 5000,
+  interval = 100
+): Promise<void> {
+  const start = Date.now();
+  while (!condition()) {
+    if (Date.now() - start > timeout) {
+      throw new Error('Timeout waiting for condition');
+    }
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}
+
+/**
+ * Sleep utility
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Intentionally no re-exports here: this repo doesn't maintain a shared
+// `tests/helpers` / `tests/mocks` layer yet.

package/tests/integration/PLAN.md

@@ -0,0 +1,65 @@
+# integration（端到端链路）测试方案
+
+## 1. 目标
+
+该套件用于验证插件在**真实钉钉环境**下的端到端链路（鉴权、发送消息、AI Card 创建/更新/结束、媒体上传等）。它与单元测试不同：依赖真实凭证与外部网络，因此默认会被跳过。
+
+## 2. 运行前置条件
+
+- **环境变量**
+  - `DINGTALK_CLIENT_ID`：钉钉应用 clientId
+  - `DINGTALK_CLIENT_SECRET`：钉钉应用 clientSecret
+  - `DINGTALK_TEST_USER_ID`：用于接收消息的测试用户（可选，未设置时会用占位值导致相关用例可能失败/无效）
+
+- **运行命令**
+
+```bash
+npm run test:integration
+```
+
+当未配置 `DINGTALK_CLIENT_ID` 或 `DINGTALK_CLIENT_SECRET` 时，测试会被 `describe.skipIf(...)` 跳过，仅保留一个“说明性测试”用于提示需要哪些环境变量（实现位于 `integration.test.ts` 顶部，通过 `plugin.__testables` 调用真实函数）。
+
+## 3. 覆盖用例（按当前测试文件）
+
+### 3.1 Authentication
+
+| 序号 | 场景 | 期望 |
+|------|------|------|
+| 1 | 使用真实凭证获取 access token | 返回非空 token |
+| 2 | 使用错误凭证 | promise reject |
+
+### 3.2 Message Sending
+
+| 序号 | 场景 | 期望 |
+|------|------|------|
+| 3 | 发送 text 给用户 | `ok=true` 且 `processQueryKey` 存在 |
+| 4 | 发送 markdown 给用户 | `ok=true` |
+| 5 | 发送 AI Card 给用户 | `ok=true` 且 `cardInstanceId` 存在 |
+
+### 3.3 Card Operations
+
+| 序号 | 场景 | 期望 |
+|------|------|------|
+| 6 | 创建 AI Card | `cardInstanceId` 存在 |
+| 7 | stream 更新 AI Card | 返回非空结果 |
+| 8 | finish 结束 AI Card | 返回非空结果 |
+
+### 3.4 Media Upload
+
+| 序号 | 场景 | 期望 | 说明 |
+|------|------|------|------|
+| 9 | 上传一张临时 PNG | 返回非空 mediaId | 用最小 1x1 PNG 作为测试文件 |
+
+### 3.5 Error Handling
+
+| 序号 | 场景 | 期望 |
+|------|------|------|
+| 10 | 非法 userId | 不抛异常，返回结构化结果 |
+| 11 | 快速发送多条消息（模拟限流） | 全部 promise 完成且不抛异常 |
+
+## 4. 风险与注意事项
+
+- **幂等与副作用**：会真实给测试用户发消息/创建卡片，建议使用专门测试账号与群。
+- **配额/限流**：钉钉接口可能限流；相关用例仅保证“不抛异常”，不保证每条都成功。
+- **网络波动**：外部依赖导致偶发失败，建议在 CI 中单独分组且允许重试（如需要）。
+