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

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 的路径吞掉导致上层误判成功。
+

package/tests/ai-card/ai-card.test.ts

@@ -0,0 +1,372 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock axios
+const mockAxiosGet = vi.hoisted(() => vi.fn());
+const mockAxiosPost = vi.hoisted(() => vi.fn());
+const mockAxiosPut = vi.hoisted(() => vi.fn());
+vi.mock('axios', () => ({
+  default: {
+    get: mockAxiosGet,
+    post: mockAxiosPost,
+    put: mockAxiosPut,
+  },
+}));
+
+// Mock fs
+vi.mock('fs', () => ({
+  existsSync: vi.fn().mockReturnValue(true),
+  mkdirSync: vi.fn(),
+  writeFileSync: vi.fn(),
+  statSync: vi.fn().mockReturnValue({ size: 1024 }),
+}));
+
+// Mock path and os
+vi.mock('path', () => ({
+  join: (...args: string[]) => args.join('/'),
+  basename: (p: string) => p.split('/').pop() || '',
+  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('AI Card helpers', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('buildDeliverBody', () => {
+    it('should build deliver body for user target', async () => {
+      const { __testables } = await import('../../plugin');
+      const { buildDeliverBody } = __testables as any;
+
+      const result = buildDeliverBody('card123', { type: 'user', userId: 'user123' }, 'robotCode');
+
+      expect(result.outTrackId).toBe('card123');
+      expect(result.userIdType).toBe(1);
+      expect(result.openSpaceId).toBe('dtv1.card//IM_ROBOT.user123');
+      expect(result.imRobotOpenDeliverModel).toBeDefined();
+    });
+
+    it('should build deliver body for group target', async () => {
+      const { __testables } = await import('../../plugin');
+      const { buildDeliverBody } = __testables as any;
+
+      const result = buildDeliverBody('card123', { type: 'group', openConversationId: 'conv123' }, 'robotCode');
+
+      expect(result.outTrackId).toBe('card123');
+      expect(result.openSpaceId).toBe('dtv1.card//IM_GROUP.conv123');
+      expect(result.imGroupOpenDeliverModel).toBeDefined();
+    });
+  });
+
+  describe('createAICardForTarget', () => {
+    it('should create AI card for user successfully', async () => {
+      const { __testables } = await import('../../plugin');
+      const { createAICardForTarget } = __testables as any;
+
+      mockAxiosPost.mockImplementation((url: string) => {
+        if (url === 'https://api.dingtalk.com/v1.0/oauth2/accessToken') {
+          return Promise.resolve({ data: { accessToken: 'token123', expireIn: 7200 } });
+        }
+        if (url.includes('/card/instances')) {
+          return Promise.resolve({ status: 200, data: {} });
+        }
+        if (url.includes('/deliver')) {
+          return Promise.resolve({ status: 200, data: {} });
+        }
+        return Promise.resolve({ status: 200, data: {} });
+      });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'user' as const, userId: 'user123' };
+
+      const result = await createAICardForTarget(config, target, log);
+
+      expect(result).not.toBeNull();
+      expect(result?.cardInstanceId).toMatch(/^card_/);
+      expect(result?.accessToken).toBe('token123');
+
+      // 契约断言：应投放到 IM_ROBOT.user123，且 robotCode 为 config.clientId
+      const deliverCall = mockAxiosPost.mock.calls.find((c) =>
+        String(c[0]).includes('/v1.0/card/instances/deliver')
+      );
+      expect(deliverCall).toBeDefined();
+      const deliverBody = deliverCall![1];
+      expect(deliverBody.openSpaceId).toBe('dtv1.card//IM_ROBOT.user123');
+      expect(deliverBody.imRobotOpenDeliverModel?.robotCode).toBe('test');
+    });
+
+    it('should create AI card for group successfully', async () => {
+      const { __testables } = await import('../../plugin');
+      const { createAICardForTarget } = __testables as any;
+
+      mockAxiosPost.mockImplementation((url: string) => {
+        if (url === 'https://api.dingtalk.com/v1.0/oauth2/accessToken') {
+          return Promise.resolve({ data: { accessToken: 'token123', expireIn: 7200 } });
+        }
+        return Promise.resolve({ status: 200, data: {} });
+      });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'group' as const, openConversationId: 'conv123' };
+
+      const result = await createAICardForTarget(config, target, log);
+
+      expect(result).not.toBeNull();
+
+      // 契约断言：应投放到 IM_GROUP.conv123
+      const deliverCall = mockAxiosPost.mock.calls.find((c) =>
+        String(c[0]).includes('/v1.0/card/instances/deliver')
+      );
+      expect(deliverCall).toBeDefined();
+      const deliverBody = deliverCall![1];
+      expect(deliverBody.openSpaceId).toBe('dtv1.card//IM_GROUP.conv123');
+    });
+
+    it('should return null on create card failure', async () => {
+      const { __testables } = await import('../../plugin');
+      const { createAICardForTarget } = __testables as any;
+
+      mockAxiosPost.mockRejectedValue(new Error('API error'));
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'user' as const, userId: 'user123' };
+
+      const result = await createAICardForTarget(config, target, log);
+
+      expect(result).toBeNull();
+      expect(log.error).toHaveBeenCalled();
+    });
+
+    it('should return null on deliver card failure', async () => {
+      const { __testables } = await import('../../plugin');
+      const { createAICardForTarget } = __testables as any;
+
+      mockAxiosPost.mockImplementation((url: string) => {
+        if (url.includes('/card/instances') && !url.includes('/deliver')) {
+          return Promise.resolve({ status: 200, data: {} });
+        }
+        return Promise.reject(new Error('Deliver failed'));
+      });
+
+      mockAxiosGet.mockResolvedValue({ data: { errcode: 0, access_token: 'token123' } });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'user' as const, userId: 'user123' };
+
+      const result = await createAICardForTarget(config, target, log);
+
+      expect(result).toBeNull();
+      expect(log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('streamAICard', () => {
+    it('should switch to INPUTING status on first call', async () => {
+      const { __testables } = await import('../../plugin');
+      const { streamAICard } = __testables as any;
+
+      mockAxiosPut.mockResolvedValue({ status: 200, data: {} });
+
+      const card = { cardInstanceId: 'card123', accessToken: 'token123', inputingStarted: false };
+
+      await streamAICard(card, 'Hello', false, log);
+
+      // Should have called INPUTING status update first
+      expect(mockAxiosPut).toHaveBeenCalled();
+      expect(card.inputingStarted).toBe(true);
+    });
+
+    it('should not switch to INPUTING on subsequent calls', async () => {
+      const { __testables } = await import('../../plugin');
+      const { streamAICard } = __testables as any;
+
+      mockAxiosPut.mockResolvedValue({ status: 200, data: {} });
+
+      const card = { cardInstanceId: 'card123', accessToken: 'token123', inputingStarted: true };
+
+      await streamAICard(card, 'Hello more', false, log);
+
+      // Should not have called INPUTING status update
+      const calls = mockAxiosPut.mock.calls;
+      const inputingCalls = calls.filter((c: any[]) => c[0].includes('/card/instances'));
+      // Only streaming call, no status call
+      expect(inputingCalls.length).toBe(0);
+    });
+
+    it('should throw on INPUTING failure', async () => {
+      const { __testables } = await import('../../plugin');
+      const { streamAICard } = __testables as any;
+
+      mockAxiosPut.mockRejectedValue(new Error('Status update failed'));
+
+      const card = { cardInstanceId: 'card123', accessToken: 'token123', inputingStarted: false };
+
+      await expect(streamAICard(card, 'Hello', false, log)).rejects.toThrow();
+      expect(log.error).toHaveBeenCalled();
+    });
+
+    it('should handle streaming failure', async () => {
+      const { __testables } = await import('../../plugin');
+      const { streamAICard } = __testables as any;
+
+      mockAxiosPut.mockImplementation((url: string) => {
+        if (url.includes('/card/instances')) {
+          return Promise.resolve({ status: 200, data: {} });
+        }
+        return Promise.reject(new Error('Streaming failed'));
+      });
+
+      const card = { cardInstanceId: 'card123', accessToken: 'token123', inputingStarted: true };
+
+      await expect(streamAICard(card, 'Hello', false, log)).rejects.toThrow();
+      expect(log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('finishAICard', () => {
+    it('should finalize card with content', async () => {
+      const { __testables } = await import('../../plugin');
+      const { finishAICard } = __testables as any;
+
+      mockAxiosPut.mockResolvedValue({ status: 200, data: {} });
+
+      const card = { cardInstanceId: 'card123', accessToken: 'token123', inputingStarted: true };
+
+      await finishAICard(card, 'Final content', log);
+
+      expect(log.info).toHaveBeenCalled();
+    });
+
+    it('should handle finish failure gracefully', async () => {
+      const { __testables } = await import('../../plugin');
+      const { finishAICard } = __testables as any;
+
+      mockAxiosPut.mockImplementation((url: string) => {
+        if (url.includes('/streaming')) {
+          return Promise.resolve({ status: 200 });
+        }
+        return Promise.reject(new Error('Finish failed'));
+      });
+
+      const card = { cardInstanceId: 'card123', accessToken: 'token123', inputingStarted: true };
+
+      // Should not throw, just log error
+      await finishAICard(card, 'Final content', log);
+
+      expect(log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('sendAICardToUser', () => {
+    it('should send AI card to user successfully', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAICardToUser } = __testables as any;
+
+      mockAxiosPost.mockResolvedValue({ status: 200, data: {} });
+      mockAxiosGet.mockResolvedValue({ data: { errcode: 0, access_token: 'token123' } });
+      mockAxiosPut.mockResolvedValue({ status: 200, data: {} });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+
+      const result = await sendAICardToUser(config, 'user123', 'Hello', log);
+
+      expect(result.ok).toBe(true);
+      expect(result.usedAICard).toBe(true);
+    });
+
+    it('should return error when card creation fails', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAICardToUser } = __testables as any;
+
+      mockAxiosPost.mockRejectedValue(new Error('API error'));
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+
+      const result = await sendAICardToUser(config, 'user123', 'Hello', log);
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+  });
+
+  describe('sendAICardToGroup', () => {
+    it('should send AI card to group successfully', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAICardToGroup } = __testables as any;
+
+      mockAxiosPost.mockResolvedValue({ status: 200, data: {} });
+      mockAxiosGet.mockResolvedValue({ data: { errcode: 0, access_token: 'token123' } });
+      mockAxiosPut.mockResolvedValue({ status: 200, data: {} });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+
+      const result = await sendAICardToGroup(config, 'conv123', 'Hello group', log);
+
+      expect(result.ok).toBe(true);
+      expect(result.usedAICard).toBe(true);
+    });
+
+    it('should return error when card creation fails', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAICardToGroup } = __testables as any;
+
+      mockAxiosPost.mockRejectedValue(new Error('API error'));
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+
+      const result = await sendAICardToGroup(config, 'conv123', 'Hello group', log);
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+  });
+
+  describe('sendAICardInternal', () => {
+    it('should return ok with usedAICard false when content is empty after processing', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAICardInternal } = __testables as any;
+
+      mockAxiosGet.mockResolvedValue({ data: { errcode: 0, access_token: 'token123' } });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'user' as const, userId: 'user123' };
+
+      // Content that would be processed to empty
+      const result = await sendAICardInternal(config, target, '', log);
+
+      expect(result.ok).toBe(true);
+      expect(result.usedAICard).toBe(false);
+    });
+
+    it('should process local images when oapiToken is available', async () => {
+      const { __testables } = await import('../../plugin');
+      const { sendAICardInternal } = __testables as any;
+
+      mockAxiosGet.mockImplementation((url: string) => {
+        if (url.includes('gettoken')) {
+          return Promise.resolve({ data: { errcode: 0, access_token: 'oapi-token' } });
+        }
+        return Promise.resolve({ data: { errcode: 0, access_token: 'token123' } });
+      });
+      mockAxiosPost.mockResolvedValue({ status: 200, data: {} });
+      mockAxiosPut.mockResolvedValue({ status: 200, data: {} });
+
+      const config = { clientId: 'test', clientSecret: 'secret' };
+      const target = { type: 'user' as const, userId: 'user123' };
+
+      const result = await sendAICardInternal(config, target, 'Hello with ![image](/tmp/test.png)', log);
+
+      expect(result.ok).toBe(true);
+    });
+  });
+});

package/tests/audio/PLAN.md

@@ -0,0 +1,64 @@
+# Audio 模块测试方案
+
+## 1. 模块划分与职责
+
+本套件覆盖音频相关的工具函数与发送逻辑：
+
+- **isAudioFile(ext: string): boolean**：判断扩展名是否属于音频类型（大小写不敏感）。
+- **getFfprobePath(): string**：优先使用 `@ffprobe-installer/ffprobe` 提供的路径；若不可用则读取 `FFPROBE_PATH`；再否则回退到 `'ffprobe'`。
+- **extractAudioDuration(filePath: string, log): Promise<number \| null>**：通过 ffprobe 解析音频时长（秒）并转换为毫秒；异常/解析失败返回 null。
+- **processAudioMarkers(content, accessToken, config, oapiToken, log)**：处理内容中的音频标记；缺 `oapiToken` 时原样返回并告警；标记 JSON 非法则移除并告警；文件不存在时给出提示并清理标记。
+- **sendAudioMessage(...) / sendAudioProactive(...)**：发送音频消息（普通 webhook / 主动消息 API），支持 duration 传入与默认值。
+
+## 2. 用例表（覆盖现有测试）
+
+### 2.1 isAudioFile
+
+| 序号 | 输入 | 期望 | 说明 |
+|------|------|------|------|
+| 1 | `mp3/wav/amr/ogg/aac/flac/m4a` | true | 音频扩展名 |
+| 2 | 大写扩展名（如 `MP3`） | true | 大小写不敏感 |
+| 3 | `mp4/txt/pdf/png/jpg/''` | false | 非音频 |
+
+### 2.2 getFfprobePath
+
+| 序号 | 场景 | 输入/环境 | 期望 | 说明 |
+|------|------|-----------|------|------|
+| 4 | env 有值 | `FFPROBE_PATH=/custom/ffprobe` | 返回 env | 兼容 CI/本地自定义 |
+| 5 | env 无值且包不可用 | 无 env | 返回 `'ffprobe'` | 最终回退（走系统 PATH） |
+
+### 2.3 extractAudioDuration
+
+| 序号 | 场景 | execFile 输出 | 期望 | 说明 |
+|------|------|---------------|------|------|
+| 7 | 成功 | JSON `{ format: { duration: '123.45' } }` | `123450` | 秒→毫秒 |
+| 8 | execFile 失败 | callback(err) | null | 记录 error |
+| 9 | JSON 解析失败 | 输出非 JSON | null | 记录 error |
+| 10 | duration 非数字 | `'not-a-number'` | null | 记录 warn |
+| 11 | format 缺失 | `{}` | null | 记录 warn |
+
+### 2.4 processAudioMarkers
+
+| 序号 | 场景 | 输入 | 期望 | 说明 |
+|------|------|------|------|------|
+| 12 | oapiToken 缺失 | `oapiToken=null` + 含标记文本 | 原样返回 | 并 warn |
+| 13 | 无标记 | 普通文本 | 原样返回 |  |
+| 14 | 标记 JSON 非法 | `...{invalid-json}...` | 清理标记、保留其余文本 | warn |
+| 15 | 文件不存在 | marker path 不存在 | 结果包含提示符号（如 `⚠️`） | 并清理标记 |
+
+### 2.5 sendAudioMessage / sendAudioProactive
+
+| 序号 | 场景 | 输入 | 期望 | 说明 |
+|------|------|------|------|------|
+| 16 | sendAudioMessage 默认 duration | 不传 duration | 不抛错并 info | 默认时长 |
+| 17 | sendAudioMessage 指定 duration | duration=30000 | 不抛错并 info | 透传 |
+| 18 | sendAudioMessage 失败 | axios.post 抛错 | 不抛错并 error | 错误收敛 |
+| 19 | proactive user | target=user | 不抛错并 info | 主动消息 |
+| 20 | proactive group | target=group | 不抛错并 info |  |
+| 21 | proactive duration 透传 | duration=45000 | msgParam.duration === '45000' | 字符串化 |
+
+## 3. 预期正确输出与潜在错误
+
+- **正确**：音频类型识别覆盖常见扩展名；ffprobe 路径优先级明确且可在 CI 环境运行；时长解析异常均返回 null 且有日志；标记处理不会把原文其它部分误删。
+- **潜在错误原因**：大小写处理遗漏；duration 单位错用（秒/毫秒）；ffprobe 路径优先级颠倒；JSON 标记解析失败未清理导致下游发送异常；文件不存在未提示。
+