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

package/tests/audio/audio.test.ts

@@ -0,0 +1,283 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock child_process for extractAudioDuration
+const mockExecFile = vi.hoisted(() => vi.fn());
+vi.mock('child_process', () => ({
+  execFile: mockExecFile,
+}));
+
+const log = {
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+};
+
+describe('audio helpers', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('isAudioFile', () => {
+    it('should return true for valid audio extensions', async () => {
+      const { __testables } = await import('../../plugin');
+      const { isAudioFile } = __testables as any;
+
+      const audioExtensions = ['mp3', 'wav', 'amr', 'ogg', 'aac', 'flac', 'm4a'];
+      for (const ext of audioExtensions) {
+        expect(isAudioFile(ext)).toBe(true);
+        expect(isAudioFile(ext.toUpperCase())).toBe(true);
+      }
+    });
+
+    it('should return false for non-audio extensions', async () => {
+      const { __testables } = await import('../../plugin');
+      const { isAudioFile } = __testables as any;
+
+      const nonAudioExtensions = ['mp4', 'txt', 'pdf', 'docx', 'png', 'jpg', ''];
+      for (const ext of nonAudioExtensions) {
+        expect(isAudioFile(ext)).toBe(false);
+      }
+    });
+  });
+
+  describe('getFfprobePath', () => {
+    it('should return FFPROBE_PATH env variable when package not found', async () => {
+      vi.resetModules();
+      process.env.FFPROBE_PATH = '/custom/ffprobe';
+      const { __testables } = await import('../../plugin');
+      const { getFfprobePath } = __testables as any;
+
+      const path = getFfprobePath();
+      expect(path).toBe('/custom/ffprobe');
+      delete process.env.FFPROBE_PATH;
+    });
+
+    it('should fallback to "ffprobe" when no path is found', async () => {
+      vi.resetModules();
+      delete process.env.FFPROBE_PATH;
+
+      const { __testables } = await import('../../plugin');
+      const { getFfprobePath } = __testables as any;
+
+      const path = getFfprobePath();
+      expect(path).toBe('ffprobe');
+    });
+  });
+
+  describe('extractAudioDuration', () => {
+    it('should return duration in milliseconds on success', async () => {
+      const { __testables } = await import('../../plugin');
+      const { extractAudioDuration } = __testables as any;
+
+      mockExecFile.mockImplementation((bin: string, args: string[], options: any, callback: Function) => {
+        callback(null, JSON.stringify({ format: { duration: '123.45' } }), '');
+      });
+
+      const result = await extractAudioDuration('/fake/audio.mp3', log);
+      expect(result).toBe(123450); // 123.45 seconds in ms
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should return null when execFile fails', async () => {
+      const { __testables } = await import('../../plugin');
+      const { extractAudioDuration } = __testables as any;
+
+      mockExecFile.mockImplementation((bin: string, args: string[], options: any, callback: Function) => {
+        callback(new Error('ffprobe failed'), '', '');
+      });
+
+      const result = await extractAudioDuration('/fake/audio.mp3', log);
+      expect(result).toBeNull();
+      expect(log.error).toHaveBeenCalled();
+    });
+
+    it('should return null when JSON parse fails', async () => {
+      const { __testables } = await import('../../plugin');
+      const { extractAudioDuration } = __testables as any;
+
+      mockExecFile.mockImplementation((bin: string, args: string[], options: any, callback: Function) => {
+        callback(null, 'invalid json', '');
+      });
+
+      const result = await extractAudioDuration('/fake/audio.mp3', log);
+      expect(result).toBeNull();
+      expect(log.error).toHaveBeenCalled();
+    });
+
+    it('should return null when duration is not a number', async () => {
+      const { __testables } = await import('../../plugin');
+      const { extractAudioDuration } = __testables as any;
+
+      mockExecFile.mockImplementation((bin: string, args: string[], options: any, callback: Function) => {
+        callback(null, JSON.stringify({ format: { duration: 'not-a-number' } }), '');
+      });
+
+      const result = await extractAudioDuration('/fake/audio.mp3', log);
+      expect(result).toBeNull();
+      expect(log.warn).toHaveBeenCalled();
+    });
+
+    it('should return null when format is missing', async () => {
+      const { __testables } = await import('../../plugin');
+      const { extractAudioDuration } = __testables as any;
+
+      mockExecFile.mockImplementation((bin: string, args: string[], options: any, callback: Function) => {
+        callback(null, JSON.stringify({}), '');
+      });
+
+      const result = await extractAudioDuration('/fake/audio.mp3', log);
+      expect(result).toBeNull();
+      expect(log.warn).toHaveBeenCalled();
+    });
+  });
+
+  describe('processAudioMarkers', () => {
+    it('should return original content when oapiToken is null', async () => {
+      const { __testables } = await import('../../plugin');
+      const { processAudioMarkers } = __testables as any;
+
+      const content = 'hello [DINGTALK_AUDIO]{"path":"/tmp/audio.mp3"}[/DINGTALK_AUDIO]';
+      const result = await processAudioMarkers(content, '', {}, null, log);
+
+      expect(result).toBe(content);
+      expect(log.warn).toHaveBeenCalled();
+    });
+
+    it('should return cleaned content when no audio markers', async () => {
+      const { __testables } = await import('../../plugin');
+      const { processAudioMarkers } = __testables as any;
+
+      const content = 'plain text without markers';
+      const result = await processAudioMarkers(content, '', {}, 'token', log);
+
+      expect(result).toBe(content);
+    });
+
+    it('should handle invalid JSON in audio markers', async () => {
+      const { __testables } = await import('../../plugin');
+      const { processAudioMarkers } = __testables as any;
+
+      const content = 'text [DINGTALK_AUDIO]{invalid-json}[/DINGTALK_AUDIO]';
+      const result = await processAudioMarkers(content, '', {}, 'token', log);
+
+      expect(result).toBe('text');
+      expect(log.warn).toHaveBeenCalled();
+    });
+
+    it('should handle non-existent audio files', async () => {
+      const { __testables } = await import('../../plugin');
+      const { processAudioMarkers } = __testables as any;
+
+      // Mock fs.existsSync to return false
+      vi.doMock('fs', () => ({
+        existsSync: vi.fn().mockReturnValue(false),
+      }));
+
+      const content = 'text [DINGTALK_AUDIO]{"path":"/nonexistent/audio.mp3"}[/DINGTALK_AUDIO]';
+      const result = await processAudioMarkers(content, '', {}, 'token', log);
+
+      // Should remove marker and add warning
+      expect(result).toContain('⚠️');
+    });
+  });
+
+  describe('sendAudioMessage', () => {
+    it('should send audio message with default duration', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAudioMessage } = __testables as any;
+
+      const mockAxios = await import('axios');
+      vi.spyOn(mockAxios.default, 'post').mockResolvedValue({ data: { success: true } });
+
+      const fileInfo = { path: '/tmp/audio.mp3', fileName: 'audio.mp3', fileType: 'mp3' };
+      await sendAudioMessage({}, 'https://webhook', fileInfo, 'mediaId123', 'token', log);
+
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should send audio message with provided duration', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAudioMessage } = __testables as any;
+
+      const mockAxios = await import('axios');
+      vi.spyOn(mockAxios.default, 'post').mockResolvedValue({ data: { success: true } });
+
+      const fileInfo = { path: '/tmp/audio.mp3', fileName: 'audio.mp3', fileType: 'mp3' };
+      await sendAudioMessage({}, 'https://webhook', fileInfo, 'mediaId123', 'token', log, 30000);
+
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should handle send failure', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAudioMessage } = __testables as any;
+
+      const mockAxios = await import('axios');
+      vi.spyOn(mockAxios.default, 'post').mockRejectedValue(new Error('Network error'));
+
+      const fileInfo = { path: '/tmp/audio.mp3', fileName: 'audio.mp3', fileType: 'mp3' };
+      await sendAudioMessage({}, 'https://webhook', fileInfo, 'mediaId123', 'token', log);
+
+      expect(log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('sendAudioProactive', () => {
+    it('should send audio to user via proactive API', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAudioProactive } = __testables as any;
+
+      const mockAxios = await import('axios');
+      vi.spyOn(mockAxios.default, 'post').mockResolvedValue({ data: { processQueryKey: 'key123' } });
+      vi.spyOn(mockAxios.default, 'get').mockResolvedValue({ data: { accessToken: 'token' } });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'user' as const, userId: 'user123' };
+      const fileInfo = { path: '/tmp/audio.mp3', fileName: 'audio.mp3', fileType: 'mp3' };
+
+      await sendAudioProactive(config, target, fileInfo, 'mediaId123', log);
+
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should send audio to group via proactive API', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAudioProactive } = __testables as any;
+
+      const mockAxios = await import('axios');
+      vi.spyOn(mockAxios.default, 'post').mockResolvedValue({ data: { processQueryKey: 'key123' } });
+      vi.spyOn(mockAxios.default, 'get').mockResolvedValue({ data: { accessToken: 'token' } });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'group' as const, openConversationId: 'conv123' };
+      const fileInfo = { path: '/tmp/audio.mp3', fileName: 'audio.mp3', fileType: 'mp3' };
+
+      await sendAudioProactive(config, target, fileInfo, 'mediaId123', log);
+
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should use provided duration in proactive send', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAudioProactive } = __testables as any;
+
+      const mockAxios = await import('axios');
+      const postSpy = vi.spyOn(mockAxios.default, 'post').mockResolvedValue({ data: { processQueryKey: 'key123' } });
+      vi.spyOn(mockAxios.default, 'get').mockResolvedValue({ data: { accessToken: 'token' } });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'user' as const, userId: 'user123' };
+      const fileInfo = { path: '/tmp/audio.mp3', fileName: 'audio.mp3', fileType: 'mp3' };
+
+      await sendAudioProactive(config, target, fileInfo, 'mediaId123', log, 45000);
+
+      // Check that the duration was passed
+      const callArgs = postSpy.mock.calls.find(c => c[0].includes('batchSend') || c[0].includes('groupMessages'));
+      if (callArgs) {
+        const body = callArgs[1];
+        const msgParam = JSON.parse(body.msgParam);
+        expect(msgParam.duration).toBe('45000');
+      }
+    });
+  });
+});

package/tests/bindings/PLAN.md

@@ -0,0 +1,99 @@
+# Bindings 解析模块（resolveAgentIdByBindings）测试方案
+
+## 1. 模块划分与职责
+
+- **resolveAgentIdByBindings(accountId, peerKind, peerId, log?): string**
+  - 职责：根据 OpenClaw 配置的 bindings 与当前会话（accountId、peerKind、peerId）解析出应使用的 agentId。配置从 `~/.openclaw/openclaw.json` 读取；匹配优先级见下。
+
+## 2. 匹配优先级（从高到低）
+
+| 优先级 | 条件 | 说明 |
+|--------|------|------|
+| 1 | peer.kind + peer.id 精确匹配（id 非 '*'） | 单聊/群聊 + 具体 peerId |
+| 2 | peer.kind + peer.id='*' | 通配该会话类型下所有 peer |
+| 3 | 仅 peer.kind 匹配（无 peer.id） | 按单聊/群聊 |
+| 4 | 无 peer，match.accountId === accountId | 按账号 |
+| 5 | 无 peer 且无 accountId | 仅 channel |
+| 6 | 无匹配 | 返回 defaultAgentId |
+
+**defaultAgentId**：当 accountId === `'__default__'` 时为 `'main'`，否则为 accountId。
+
+## 3. 用例矩阵（全覆盖）
+
+### 3.1 无配置文件或配置不可读
+
+| 序号 | fs.existsSync | fs.readFileSync / 异常 | 期望 | 说明 |
+|------|----------------|------------------------|------|------|
+| 1 | false | - | defaultAgentId | 文件不存在 |
+| 2 | true | throw Error | defaultAgentId，log.warn | 读文件抛错 |
+| 3 | true | 非 JSON 字符串 | defaultAgentId，log.warn | JSON.parse 抛错 |
+
+### 3.2 无 bindings 或 bindings 为空
+
+| 序号 | readFileSync 返回 | 期望 | 说明 |
+|------|-------------------|------|------|
+| 4 | `'{}'` | defaultAgentId | 无 bindings 键 |
+| 5 | `'{"bindings":[]}'` | defaultAgentId | 空数组 |
+
+### 3.3 channel 筛选
+
+| 序号 | bindings 内容 | 期望 | 说明 |
+|------|----------------|------|------|
+| 6 | `[{ agentId: 'a', match: { channel: 'other' } }]` | defaultAgentId | 非 dingtalk-connector 被筛掉 |
+| 7 | `[{ agentId: 'a', match: { channel: 'dingtalk-connector' } }]` | 能匹配到 'a'（见优先级5） | channel 匹配 |
+| 8 | `[{ agentId: 'a', match: {} }]` | 能匹配到 'a' | 无 channel 视为匹配 |
+
+### 3.4 defaultAgentId 逻辑
+
+| 序号 | accountId | 无配置/无匹配时期望 | 说明 |
+|------|-----------|---------------------|------|
+| 9 | `'__default__'` | `'main'` | 单账号模式 |
+| 10 | `'acc1'` | `'acc1'` | 多账号 |
+
+### 3.5 优先级1：精确 peer.id
+
+| 序号 | bindings | accountId | peerKind | peerId | 期望 | 说明 |
+|------|----------|-----------|----------|--------|------|------|
+| 11 | `[{ agentId: 'agent1', match: { peer: { kind: 'direct', id: 'user1' } } }]` | any | 'direct' | 'user1' | 'agent1' | 精确匹配 |
+| 12 | 同上 | any | 'direct' | 'user2' | defaultAgentId | id 不同 |
+| 13 | 同上 | any | 'group' | 'user1' | defaultAgentId | kind 不同 |
+| 14 | `[{ agentId: 'a', match: { accountId: 'acc1', peer: { kind: 'direct', id: 'u1' } } }]` | 'acc1' | 'direct' | 'u1' | 'a' | accountId 一致 |
+| 15 | 同上 | 'acc2' | 'direct' | 'u1' | defaultAgentId | accountId 不一致被 continue |
+
+### 3.6 优先级2：peer.id='*'
+
+| 序号 | bindings | peerKind | peerId | 期望 | 说明 |
+|------|----------|----------|--------|------|------|
+| 16 | `[{ agentId: 'wild', match: { peer: { kind: 'direct', id: '*' } } }]` | 'direct' | 'any_id' | 'wild' | 通配单聊 |
+| 17 | 同上 | 'group' | 'any' | defaultAgentId | kind 不同 |
+
+### 3.7 优先级3：仅 peer.kind
+
+| 序号 | bindings | peerKind | 期望 | 说明 |
+|------|----------|----------|------|------|
+| 18 | `[{ agentId: 'kindOnly', match: { peer: { kind: 'group' } } }]` | 'group' | 'kindOnly' | 无 peer.id |
+| 19 | 同上 | 'direct' | defaultAgentId | kind 不同 |
+
+### 3.8 优先级4：accountId
+
+| 序号 | bindings | accountId | 期望 | 说明 |
+|------|----------|-----------|------|------|
+| 20 | `[{ agentId: 'accAgent', match: { accountId: 'acc1' } }]` | 'acc1' | 'accAgent' | 无 peer |
+| 21 | 同上 | 'acc2' | defaultAgentId | accountId 不同 |
+
+### 3.9 优先级5：仅 channel
+
+| 序号 | bindings | 期望 | 说明 |
+|------|----------|------|------|
+| 22 | `[{ agentId: 'channelOnly', match: { channel: 'dingtalk-connector' } }]` | 'channelOnly' | 无 peer 无 accountId 时取第一个 |
+
+### 3.10 binding.agentId 为空
+
+| 序号 | bindings | 期望 | 说明 |
+|------|----------|------|------|
+| 23 | `[{ agentId: '', match: { peer: { kind: 'direct', id: 'u1' } } }]` | defaultAgentId | 代码 return binding.agentId \|\| defaultAgentId |
+
+## 4. 预期正确输出与潜在错误
+
+- **正确输出**：返回字符串 agentId，无 undefined；优先级顺序正确时先匹配到的先返回。
+- **潜在错误原因**：配置文件路径写死或与文档不一致；channel 筛选条件反了；accountId 比较时 continue 漏写；优先级顺序颠倒；defaultAgentId 未区分 __default__。

package/tests/bindings/bindings.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+const mockExistsSync = vi.hoisted(() => vi.fn());
+const mockReadFileSync = vi.hoisted(() => vi.fn());
+
+vi.mock('fs', () => ({
+  existsSync: mockExistsSync,
+  readFileSync: mockReadFileSync,
+}));
+vi.mock('path', () => ({
+  join: (...args: string[]) => args.join('/'),
+}));
+vi.mock('os', () => ({
+  homedir: () => '/fake-home',
+}));
+
+// 保证 plugin 在本文件内加载时使用上面 mock 的 fs/path/os
+let resolveAgentIdByBindings: (a: string, b: 'direct' | 'group', c: string, l?: any) => string;
+
+const log = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+const CONFIG_PATH = '/fake-home/.openclaw/openclaw.json';
+
+describe('resolveAgentIdByBindings', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    mockExistsSync.mockReturnValue(false);
+    vi.resetModules();
+    const { __testables } = await import('../../plugin');
+    resolveAgentIdByBindings = (__testables as any).resolveAgentIdByBindings;
+    (__testables as any).setRuntimeForTest({});
+  });
+
+  it('returns main when accountId is __default__ and no config', () => {
+    const out = resolveAgentIdByBindings('__default__', 'direct', 'user1', log);
+    expect(out).toBe('main');
+  });
+
+  it('returns accountId when accountId is not __default__ and no config', () => {
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'user1', log);
+    expect(out).toBe('acc1');
+  });
+
+  it('returns defaultAgentId when config file does not exist', () => {
+    mockExistsSync.mockReturnValue(false);
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(mockExistsSync).toHaveBeenCalledWith(CONFIG_PATH);
+    expect(out).toBe('acc1');
+  });
+
+  it('returns defaultAgentId when bindings is empty array', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(JSON.stringify({ bindings: [] }));
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('acc1');
+  });
+
+  it('returns defaultAgentId when config has no bindings key', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue('{}');
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('acc1');
+  });
+
+  it('returns defaultAgentId and logs warn when readFileSync throws', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockImplementation(() => {
+      throw new Error('read error');
+    });
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('acc1');
+    expect(log.warn).toHaveBeenCalled();
+  });
+
+  it('priority 1: exact peer.kind + peer.id match', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [
+          { agentId: 'agent1', match: { channel: 'dingtalk-connector', peer: { kind: 'direct', id: 'user1' } } },
+        ],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'user1', log);
+    expect(out).toBe('agent1');
+  });
+
+  it('priority 1: no match when peerId differs', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [
+          { agentId: 'agent1', match: { peer: { kind: 'direct', id: 'user1' } } },
+        ],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'user2', log);
+    expect(out).toBe('acc1');
+  });
+
+  it('priority 1: accountId filter - skip when accountId does not match', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [
+          { agentId: 'a', match: { accountId: 'acc1', peer: { kind: 'direct', id: 'u1' } } },
+        ],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc2', 'direct', 'u1', log);
+    expect(out).toBe('acc2');
+  });
+
+  it('priority 1: accountId filter - match when accountId matches', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [
+          { agentId: 'a', match: { accountId: 'acc1', peer: { kind: 'direct', id: 'u1' } } },
+        ],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('a');
+  });
+
+  it('priority 2: peer.id=* matches any peerId for same kind', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [{ agentId: 'wild', match: { peer: { kind: 'direct', id: '*' } } }],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'any_id', log);
+    expect(out).toBe('wild');
+  });
+
+  it('priority 3: peer.kind only (no peer.id)', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [{ agentId: 'kindOnly', match: { peer: { kind: 'group' } } }],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'group', 'cid1', log);
+    expect(out).toBe('kindOnly');
+  });
+
+  it('priority 4: accountId match (no peer)', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [{ agentId: 'accAgent', match: { accountId: 'acc1' } }],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('accAgent');
+  });
+
+  it('priority 5: channel only (no peer, no accountId)', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [{ agentId: 'channelOnly', match: { channel: 'dingtalk-connector' } }],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('channelOnly');
+  });
+
+  it('channel filter: other channel binding is skipped', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [{ agentId: 'other', match: { channel: 'other-channel' } }],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('acc1');
+  });
+
+  it('returns defaultAgentId when binding.agentId is empty', () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(
+      JSON.stringify({
+        bindings: [{ agentId: '', match: { peer: { kind: 'direct', id: 'u1' } } }],
+      }),
+    );
+    const out = resolveAgentIdByBindings('acc1', 'direct', 'u1', log);
+    expect(out).toBe('acc1');
+  });
+});

package/tests/card-update/PLAN.md

@@ -0,0 +1,29 @@
+# card-update（AI Card 更新）测试方案
+
+## 1. 目的与覆盖范围
+
+该套件定位为 **AI Card“更新链路”的轻量回归集**，目标是用较少用例覆盖最容易被改坏、但线上影响大的关键契约：
+
+- **被动场景创建卡片**：`createAICard(config, data, log?)` 会根据 `conversationType` 正确选择 user/group 目标并完成投放。
+- **流式状态机**：`streamAICard(card, content, finished?, log?)` 首次会先切换到 INPUTING，再写入 streaming；后续调用不应重复 INPUTING。
+- **结束流程**：`finishAICard(card, content, log?)` 会 finalize streaming 并设置 FINISHED。
+
+说明：
+
+- 本套件**不再**覆盖 `sendAICardInternal/sendAICardToUser/sendAICardToGroup` 或 `buildMsgPayload`，这些更适合放在 `tests/ai-card` 与 `tests/proactive`（避免重复与耦合）。
+
+## 2. 用例表（覆盖现有测试）
+
+| 序号 | 场景 | 期望 | 说明 |
+|------|------|------|------|
+| 1 | createAICard：单聊（conversationType='1'） | 成功创建并投放到 `dtv1.card//IM_ROBOT.<userId>` | user 目标选择正确 |
+| 2 | createAICard：群聊（conversationType='2'） | 成功创建并投放到 `dtv1.card//IM_GROUP.<openConversationId>` | group 目标选择正确 |
+| 3 | streamAICard：首次调用 | 先 PUT INPUTING，再 PUT streaming；并把 `card.inputingStarted=true` | 状态机契约 |
+| 4 | streamAICard：后续调用 | 仅 PUT streaming（不再重复 INPUTING） | 避免多余状态切换 |
+| 5 | finishAICard | streaming `isFinalize=true`，并 PUT FINISHED（flowStatus='3'） | 完成闭环 |
+
+## 3. 预期正确输出与潜在错误
+
+- **正确**：create 时目标选择与投放 `openSpaceId` 正确；stream/finish 的状态机顺序正确且不会重复 INPUTING；finish 会 finalize streaming 并设置 FINISHED。
+- **潜在错误原因**：conversationType 判断反了导致 user/group 投放错；streamAICard 忘记先 INPUTING 或重复 INPUTING；finishAICard 未 finalize streaming；flowStatus 值写错导致客户端状态异常。
+