@openclaw/feishu 2026.3.12 → 2026.5.1-beta.1

package/src/media.test.ts

@@ -1,13 +1,15 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { resolvePreferredOpenClawTmpDir } from "../../../src/infra/tmp-openclaw-dir.js";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ClawdbotConfig } from "../runtime-api.js";
 
 const createFeishuClientMock = vi.hoisted(() => vi.fn());
 const resolveFeishuAccountMock = vi.hoisted(() => vi.fn());
 const normalizeFeishuTargetMock = vi.hoisted(() => vi.fn());
 const resolveReceiveIdTypeMock = vi.hoisted(() => vi.fn());
 const loadWebMediaMock = vi.hoisted(() => vi.fn());
+const runFfmpegMock = vi.hoisted(() => vi.fn());
 
 const fileCreateMock = vi.hoisted(() => vi.fn());
 const imageCreateMock = vi.hoisted(() => vi.fn());
@@ -17,6 +19,7 @@ const messageResourceGetMock = vi.hoisted(() => vi.fn());
 const messageReplyMock = vi.hoisted(() => vi.fn());
 
 const FEISHU_MEDIA_HTTP_TIMEOUT_MS = 120_000;
+const emptyConfig: ClawdbotConfig = {};
 
 vi.mock("./client.js", () => ({
   createFeishuClient: createFeishuClientMock,
@@ -24,6 +27,7 @@ vi.mock("./client.js", () => ({
 
 vi.mock("./accounts.js", () => ({
   resolveFeishuAccount: resolveFeishuAccountMock,
+  resolveFeishuRuntimeAccount: resolveFeishuAccountMock,
 }));
 
 vi.mock("./targets.js", () => ({
@@ -39,12 +43,18 @@ vi.mock("./runtime.js", () => ({
   }),
 }));
 
-import {
-  downloadImageFeishu,
-  downloadMessageResourceFeishu,
-  sanitizeFileNameForUpload,
-  sendMediaFeishu,
-} from "./media.js";
+vi.mock("openclaw/plugin-sdk/media-runtime", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("openclaw/plugin-sdk/media-runtime")>();
+  return {
+    ...actual,
+    runFfmpeg: runFfmpegMock,
+  };
+});
+
+let downloadImageFeishu: typeof import("./media.js").downloadImageFeishu;
+let downloadMessageResourceFeishu: typeof import("./media.js").downloadMessageResourceFeishu;
+let sanitizeFileNameForUpload: typeof import("./media.js").sanitizeFileNameForUpload;
+let sendMediaFeishu: typeof import("./media.js").sendMediaFeishu;
 
 function expectPathIsolatedToTmpRoot(pathValue: string, key: string): void {
   expect(pathValue).not.toContain(key);
@@ -64,18 +74,30 @@ function expectMediaTimeoutClientConfigured(): void {
   );
 }
 
+function mockResolvedFeishuAccount() {
+  resolveFeishuAccountMock.mockReturnValue({
+    configured: true,
+    accountId: "main",
+    config: {},
+    appId: "app_id",
+    appSecret: "app_secret",
+    domain: "feishu",
+  });
+}
+
 describe("sendMediaFeishu msg_type routing", () => {
+  beforeAll(async () => {
+    ({
+      downloadImageFeishu,
+      downloadMessageResourceFeishu,
+      sanitizeFileNameForUpload,
+      sendMediaFeishu,
+    } = await import("./media.js"));
+  });
+
   beforeEach(() => {
     vi.clearAllMocks();
-
-    resolveFeishuAccountMock.mockReturnValue({
-      configured: true,
-      accountId: "main",
-      config: {},
-      appId: "app_id",
-      appSecret: "app_secret",
-      domain: "feishu",
-    });
+    mockResolvedFeishuAccount();
 
     normalizeFeishuTargetMock.mockReturnValue("ou_target");
     resolveReceiveIdTypeMock.mockReturnValue("open_id");
@@ -127,11 +149,15 @@ describe("sendMediaFeishu msg_type routing", () => {
 
     imageGetMock.mockResolvedValue(Buffer.from("image-bytes"));
     messageResourceGetMock.mockResolvedValue(Buffer.from("resource-bytes"));
+    runFfmpegMock.mockImplementation(async (args: string[]) => {
+      await fs.writeFile(args.at(-1) ?? "", Buffer.from("opus-output"));
+      return "";
+    });
   });
 
   it("uses msg_type=media for mp4 video", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("video"),
       fileName: "clip.mp4",
@@ -152,7 +178,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
   it("uses msg_type=audio for opus", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("audio"),
       fileName: "voice.opus",
@@ -173,7 +199,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
   it("uses msg_type=file for documents", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("doc"),
       fileName: "paper.pdf",
@@ -192,9 +218,159 @@ describe("sendMediaFeishu msg_type routing", () => {
     );
   });
 
+  it("uses msg_type=media for remote mp4 content even when the filename is generic", async () => {
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("remote-video"),
+      fileName: "download",
+      kind: "video",
+      contentType: "video/mp4",
+    });
+
+    await sendMediaFeishu({
+      cfg: emptyConfig,
+      to: "user:ou_target",
+      mediaUrl: "https://example.com/video",
+    });
+
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ file_type: "mp4" }),
+      }),
+    );
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "media" }),
+      }),
+    );
+  });
+
+  it("falls back to generic file for unsupported audio formats", async () => {
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("remote-mp3"),
+      fileName: "song.mp3",
+      kind: "audio",
+      contentType: "audio/mpeg",
+    });
+
+    await sendMediaFeishu({
+      cfg: emptyConfig,
+      to: "user:ou_target",
+      mediaUrl: "https://example.com/song.mp3",
+    });
+
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ file_type: "stream" }),
+      }),
+    );
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "file" }),
+      }),
+    );
+    expect(runFfmpegMock).not.toHaveBeenCalled();
+  });
+
+  it("transcodes voice-intent mp3 to msg_type=audio", async () => {
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("remote-mp3"),
+      fileName: "reply.mp3",
+      kind: "audio",
+      contentType: "audio/mpeg",
+    });
+
+    await sendMediaFeishu({
+      cfg: emptyConfig,
+      to: "user:ou_target",
+      mediaUrl: "https://example.com/reply.mp3",
+      audioAsVoice: true,
+    });
+
+    expect(runFfmpegMock).toHaveBeenCalledWith(
+      expect.arrayContaining(["-c:a", "libopus", "-ar", "48000", "-b:a", "64k"]),
+    );
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          file_type: "opus",
+          file_name: "voice.ogg",
+          file: Buffer.from("opus-output"),
+        }),
+      }),
+    );
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "audio" }),
+      }),
+    );
+  });
+
+  it("leaves native voice audio unchanged when audioAsVoice is true", async () => {
+    await sendMediaFeishu({
+      cfg: emptyConfig,
+      to: "user:ou_target",
+      mediaBuffer: Buffer.from("opus"),
+      fileName: "reply.ogg",
+      audioAsVoice: true,
+    });
+
+    expect(runFfmpegMock).not.toHaveBeenCalled();
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          file_type: "opus",
+          file_name: "reply.ogg",
+        }),
+      }),
+    );
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "audio" }),
+      }),
+    );
+  });
+
+  it("falls back to file when voice-intent audio cannot be transcoded", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    runFfmpegMock.mockRejectedValueOnce(new Error("ffmpeg missing"));
+    loadWebMediaMock.mockResolvedValueOnce({
+      buffer: Buffer.from("remote-mp3"),
+      fileName: "reply.mp3",
+      kind: "audio",
+      contentType: "audio/mpeg",
+    });
+
+    await sendMediaFeishu({
+      cfg: emptyConfig,
+      to: "user:ou_target",
+      mediaUrl: "https://example.com/reply.mp3",
+      audioAsVoice: true,
+    });
+
+    expect(fileCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          file_type: "stream",
+          file_name: "reply.mp3",
+          file: Buffer.from("remote-mp3"),
+        }),
+      }),
+    );
+    expect(messageCreateMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ msg_type: "file" }),
+      }),
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("audioAsVoice transcode failed"),
+      expect.any(Error),
+    );
+    warnSpy.mockRestore();
+  });
+
   it("configures the media client timeout for image uploads", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("image"),
       fileName: "photo.png",
@@ -210,7 +386,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
   it("uses msg_type=media when replying with mp4", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("video"),
       fileName: "reply.mp4",
@@ -229,7 +405,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
   it("passes reply_in_thread when replyInThread is true", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("video"),
       fileName: "reply.mp4",
@@ -250,7 +426,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
   it("omits reply_in_thread when replyInThread is false", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("video"),
       fileName: "reply.mp4",
@@ -272,7 +448,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
     const roots = ["/allowed/workspace", "/tmp/openclaw"];
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaUrl: "/allowed/workspace/file.pdf",
       mediaLocalRoots: roots,
@@ -295,7 +471,7 @@ describe("sendMediaFeishu msg_type routing", () => {
 
     await expect(
       sendMediaFeishu({
-        cfg: {} as any,
+        cfg: emptyConfig,
         to: "user:ou_target",
         mediaUrl: "https://x/img",
         fileName: "voice.opus",
@@ -319,7 +495,7 @@ describe("sendMediaFeishu msg_type routing", () => {
     });
 
     const result = await downloadImageFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       imageKey,
     });
 
@@ -346,7 +522,7 @@ describe("sendMediaFeishu msg_type routing", () => {
     });
 
     const result = await downloadMessageResourceFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       messageId: "om_123",
       fileKey,
       type: "image",
@@ -360,7 +536,7 @@ describe("sendMediaFeishu msg_type routing", () => {
   it("rejects invalid image keys before calling feishu api", async () => {
     await expect(
       downloadImageFeishu({
-        cfg: {} as any,
+        cfg: emptyConfig,
         imageKey: "a/../../bad",
       }),
     ).rejects.toThrow("invalid image_key");
@@ -371,7 +547,7 @@ describe("sendMediaFeishu msg_type routing", () => {
   it("rejects invalid file keys before calling feishu api", async () => {
     await expect(
       downloadMessageResourceFeishu({
-        cfg: {} as any,
+        cfg: emptyConfig,
         messageId: "om_123",
         fileKey: "x/../../bad",
         type: "file",
@@ -381,22 +557,21 @@ describe("sendMediaFeishu msg_type routing", () => {
     expect(messageResourceGetMock).not.toHaveBeenCalled();
   });
 
-  it("encodes Chinese filenames for file uploads", async () => {
+  it("preserves Chinese filenames for file uploads", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("doc"),
       fileName: "测试文档.pdf",
     });
 
     const createCall = fileCreateMock.mock.calls[0][0];
-    expect(createCall.data.file_name).not.toBe("测试文档.pdf");
-    expect(createCall.data.file_name).toBe(encodeURIComponent("测试文档") + ".pdf");
+    expect(createCall.data.file_name).toBe("测试文档.pdf");
   });
 
   it("preserves ASCII filenames unchanged for file uploads", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("doc"),
       fileName: "report-2026.pdf",
@@ -406,18 +581,16 @@ describe("sendMediaFeishu msg_type routing", () => {
     expect(createCall.data.file_name).toBe("report-2026.pdf");
   });
 
-  it("encodes special characters (em-dash, full-width brackets) in filenames", async () => {
+  it("preserves special Unicode characters (em-dash, full-width brackets) in filenames", async () => {
     await sendMediaFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       to: "user:ou_target",
       mediaBuffer: Buffer.from("doc"),
       fileName: "报告—详情（2026）.md",
     });
 
     const createCall = fileCreateMock.mock.calls[0][0];
-    expect(createCall.data.file_name).toMatch(/\.md$/);
-    expect(createCall.data.file_name).not.toContain("—");
-    expect(createCall.data.file_name).not.toContain("（");
+    expect(createCall.data.file_name).toBe("报告—详情（2026）.md");
   });
 });
 
@@ -427,71 +600,54 @@ describe("sanitizeFileNameForUpload", () => {
     expect(sanitizeFileNameForUpload("my-file_v2.txt")).toBe("my-file_v2.txt");
   });
 
-  it("encodes Chinese characters in basename, preserves extension", () => {
-    const result = sanitizeFileNameForUpload("测试文件.md");
-    expect(result).toBe(encodeURIComponent("测试文件") + ".md");
-    expect(result).toMatch(/\.md$/);
+  it("preserves Chinese characters", () => {
+    expect(sanitizeFileNameForUpload("测试文件.md")).toBe("测试文件.md");
+    expect(sanitizeFileNameForUpload("武汉15座山登山信息汇总.csv")).toBe(
+      "武汉15座山登山信息汇总.csv",
+    );
   });
 
-  it("encodes em-dash and full-width brackets", () => {
-    const result = sanitizeFileNameForUpload("文件—说明（v2）.pdf");
-    expect(result).toMatch(/\.pdf$/);
-    expect(result).not.toContain("—");
-    expect(result).not.toContain("（");
-    expect(result).not.toContain("）");
+  it("preserves em-dash and full-width brackets", () => {
+    expect(sanitizeFileNameForUpload("文件—说明（v2）.pdf")).toBe("文件—说明（v2）.pdf");
   });
 
-  it("encodes single quotes and parentheses per RFC 5987", () => {
-    const result = sanitizeFileNameForUpload("文件'(test).txt");
-    expect(result).toContain("%27");
-    expect(result).toContain("%28");
-    expect(result).toContain("%29");
-    expect(result).toMatch(/\.txt$/);
+  it("preserves single quotes and parentheses", () => {
+    expect(sanitizeFileNameForUpload("文件'(test).txt")).toBe("文件'(test).txt");
   });
 
-  it("handles filenames without extension", () => {
-    const result = sanitizeFileNameForUpload("测试文件");
-    expect(result).toBe(encodeURIComponent("测试文件"));
+  it("preserves filenames without extension", () => {
+    expect(sanitizeFileNameForUpload("测试文件")).toBe("测试文件");
   });
 
-  it("handles mixed ASCII and non-ASCII", () => {
-    const result = sanitizeFileNameForUpload("Report_报告_2026.xlsx");
-    expect(result).toMatch(/\.xlsx$/);
-    expect(result).not.toContain("报告");
+  it("preserves mixed ASCII and non-ASCII", () => {
+    expect(sanitizeFileNameForUpload("Report_报告_2026.xlsx")).toBe("Report_报告_2026.xlsx");
   });
 
-  it("encodes non-ASCII extensions", () => {
-    const result = sanitizeFileNameForUpload("报告.文档");
-    expect(result).toContain("%E6%96%87%E6%A1%A3");
-    expect(result).not.toContain("文档");
+  it("preserves emoji filenames", () => {
+    expect(sanitizeFileNameForUpload("report_😀.txt")).toBe("report_😀.txt");
   });
 
-  it("encodes emoji filenames", () => {
-    const result = sanitizeFileNameForUpload("report_😀.txt");
-    expect(result).toContain("%F0%9F%98%80");
-    expect(result).toMatch(/\.txt$/);
+  it("strips control characters", () => {
+    expect(sanitizeFileNameForUpload("bad\x00file.txt")).toBe("bad_file.txt");
+    expect(sanitizeFileNameForUpload("inject\r\nheader.txt")).toBe("inject__header.txt");
   });
 
-  it("encodes mixed ASCII and non-ASCII extensions", () => {
-    const result = sanitizeFileNameForUpload("notes_总结.v测试");
-    expect(result).toContain("notes_");
-    expect(result).toContain("%E6%B5%8B%E8%AF%95");
-    expect(result).not.toContain("测试");
+  it("strips quotes and backslashes to prevent header injection", () => {
+    expect(sanitizeFileNameForUpload('file"name.txt')).toBe("file_name.txt");
+    expect(sanitizeFileNameForUpload("file\\name.txt")).toBe("file_name.txt");
   });
 });
 
 describe("downloadMessageResourceFeishu", () => {
+  function httpStatusError(status: number): Error & { response: { status: number } } {
+    return Object.assign(new Error(`Request failed with status code ${status}`), {
+      response: { status },
+    });
+  }
+
   beforeEach(() => {
     vi.clearAllMocks();
-
-    resolveFeishuAccountMock.mockReturnValue({
-      configured: true,
-      accountId: "main",
-      config: {},
-      appId: "app_id",
-      appSecret: "app_secret",
-      domain: "feishu",
-    });
+    mockResolvedFeishuAccount();
 
     createFeishuClientMock.mockReturnValue({
       im: {
@@ -508,7 +664,7 @@ describe("downloadMessageResourceFeishu", () => {
   // Audio/video resources must use type=file, not type=audio (#8746).
   it("forwards provided type=file for non-image resources", async () => {
     const result = await downloadMessageResourceFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       messageId: "om_audio_msg",
       fileKey: "file_key_audio",
       type: "file",
@@ -528,7 +684,7 @@ describe("downloadMessageResourceFeishu", () => {
     messageResourceGetMock.mockResolvedValue(Buffer.from("fake-image-data"));
 
     const result = await downloadMessageResourceFeishu({
-      cfg: {} as any,
+      cfg: emptyConfig,
       messageId: "om_img_msg",
       fileKey: "img_key_1",
       type: "image",
@@ -543,4 +699,174 @@ describe("downloadMessageResourceFeishu", () => {
     expectMediaTimeoutClientConfigured();
     expect(result.buffer).toBeInstanceOf(Buffer);
   });
+
+  it("extracts content-type and filename metadata from download headers", async () => {
+    messageResourceGetMock.mockResolvedValueOnce({
+      data: Buffer.from("fake-video-data"),
+      headers: {
+        "content-type": "video/mp4",
+        "content-disposition": `attachment; filename="clip.mp4"`,
+      },
+    });
+
+    const result = await downloadMessageResourceFeishu({
+      cfg: emptyConfig,
+      messageId: "om_video_msg",
+      fileKey: "file_key_video",
+      type: "file",
+    });
+
+    expect(result).toMatchObject({
+      buffer: Buffer.from("fake-video-data"),
+      contentType: "video/mp4",
+      fileName: "clip.mp4",
+    });
+  });
+
+  it("retries file resources as media after HTTP 502", async () => {
+    const originalError = httpStatusError(502);
+    messageResourceGetMock.mockRejectedValueOnce(originalError).mockResolvedValueOnce({
+      data: Buffer.from("fake-ios-video-data"),
+      headers: {
+        "content-type": "video/mp4",
+        "content-disposition": `attachment; filename="ios-video.mp4"`,
+      },
+    });
+
+    const result = await downloadMessageResourceFeishu({
+      cfg: emptyConfig,
+      messageId: "om_ios_video_msg",
+      fileKey: "file_key_ios_video",
+      type: "file",
+    });
+
+    expect(messageResourceGetMock).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        path: { message_id: "om_ios_video_msg", file_key: "file_key_ios_video" },
+        params: { type: "file" },
+      }),
+    );
+    expect(messageResourceGetMock).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        path: { message_id: "om_ios_video_msg", file_key: "file_key_ios_video" },
+        params: { type: "media" },
+      }),
+    );
+    expect(result).toMatchObject({
+      buffer: Buffer.from("fake-ios-video-data"),
+      contentType: "video/mp4",
+      fileName: "ios-video.mp4",
+    });
+  });
+
+  it("rethrows the original HTTP 502 when the media retry fails", async () => {
+    const originalError = httpStatusError(502);
+    messageResourceGetMock
+      .mockRejectedValueOnce(originalError)
+      .mockRejectedValueOnce(new Error("media retry failed"));
+
+    await expect(
+      downloadMessageResourceFeishu({
+        cfg: emptyConfig,
+        messageId: "om_ios_video_msg",
+        fileKey: "file_key_ios_video",
+        type: "file",
+      }),
+    ).rejects.toBe(originalError);
+
+    expect(messageResourceGetMock).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ params: { type: "file" } }),
+    );
+    expect(messageResourceGetMock).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({ params: { type: "media" } }),
+    );
+  });
+
+  it("does not retry non-fallback download failures", async () => {
+    for (const scenario of [
+      { messageId: "om_image_msg", fileKey: "img_key_502", type: "image" as const, status: 502 },
+      { messageId: "om_file_msg", fileKey: "file_key_500", type: "file" as const, status: 500 },
+    ]) {
+      const originalError = httpStatusError(scenario.status);
+      messageResourceGetMock.mockClear();
+      messageResourceGetMock.mockRejectedValueOnce(originalError);
+
+      await expect(
+        downloadMessageResourceFeishu({
+          cfg: emptyConfig,
+          messageId: scenario.messageId,
+          fileKey: scenario.fileKey,
+          type: scenario.type,
+        }),
+      ).rejects.toBe(originalError);
+
+      expect(messageResourceGetMock).toHaveBeenCalledTimes(1);
+      expect(messageResourceGetMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          path: { message_id: scenario.messageId, file_key: scenario.fileKey },
+          params: { type: scenario.type },
+        }),
+      );
+    }
+  });
+
+  it("recovers CJK filenames from plain Content-Disposition headers decoded as Latin-1", async () => {
+    const fileName = "武汉15座山登山信息汇总.csv";
+    const latin1HeaderFileName = Buffer.from(fileName, "utf8").toString("latin1");
+    messageResourceGetMock.mockResolvedValueOnce({
+      data: Buffer.from("fake-file-data"),
+      headers: {
+        "content-disposition": `attachment; filename="${latin1HeaderFileName}"`,
+      },
+    });
+
+    const result = await downloadMessageResourceFeishu({
+      cfg: emptyConfig,
+      messageId: "om_file_msg",
+      fileKey: "file_key_csv",
+      type: "file",
+    });
+
+    expect(result.fileName).toBe(fileName);
+  });
+
+  it("keeps valid Latin-1 filenames from plain Content-Disposition headers unchanged", async () => {
+    messageResourceGetMock.mockResolvedValueOnce({
+      data: Buffer.from("fake-file-data"),
+      headers: {
+        "content-disposition": `attachment; filename="café-©.txt"`,
+      },
+    });
+
+    const result = await downloadMessageResourceFeishu({
+      cfg: emptyConfig,
+      messageId: "om_latin1_msg",
+      fileKey: "file_key_latin1",
+      type: "file",
+    });
+
+    expect(result.fileName).toBe("café-©.txt");
+  });
+
+  it("keeps JSON-derived file_name metadata unchanged", async () => {
+    const fileName = "武汉15座山登山信息汇总.csv";
+    const latin1LookingFileName = Buffer.from(fileName, "utf8").toString("latin1");
+    messageResourceGetMock.mockResolvedValueOnce({
+      data: Buffer.from("fake-file-data"),
+      file_name: latin1LookingFileName,
+    });
+
+    const result = await downloadMessageResourceFeishu({
+      cfg: emptyConfig,
+      messageId: "om_json_file_msg",
+      fileKey: "file_key_json",
+      type: "file",
+    });
+
+    expect(result.fileName).toBe(latin1LookingFileName);
+  });
 });