@yanhaidao/wecom 2.2.28 → 2.3.2

package/README.md

@@ -296,14 +296,14 @@ openclaw channels status
 - Bot 无法交付时，只回退到**同组** Agent，不跨账号兜底。
 - 只有在未显式指定 `accountId` 时，才使用 `defaultAccount`。
 
-### 2.4 Webhook 路径（固定）
+### 2.4 Webhook 路径（优先使用账号路径）
 
 | 模式 | 路径 | 说明 |
 |:---|:---|:---|
-| Bot | `/wecom/bot` | 智能体回调 |
-| Agent | `/wecom/agent` | 自建应用回调 |
-| Bot（多账号） | `/wecom/bot/{accountId}` | 指定账号回调 |
-| Agent（多账号） | `/wecom/agent/{accountId}` | 指定账号回调 |
+| Bot（推荐，多账号） | `/wecom/bot/{accountId}` | 指定账号回调（例如 `/wecom/bot/default`） |
+| Agent（推荐，多账号） | `/wecom/agent/{accountId}` | 指定账号回调（例如 `/wecom/agent/default`） |
+| Bot（兼容，单账号 legacy） | `/wecom/bot` 或 `/wecom` | 历史路径，仅单账号模式建议保留 |
+| Agent（兼容，单账号 legacy） | `/wecom/agent` | 历史路径，单账号模式可用 |
 
 ### 2.5 从单账号迁移到多账号（4 步）
 
@@ -335,7 +335,7 @@ openclaw channels status
 1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/manageTools)
 2. 进入「安全与管理」→「管理工具」→「智能机器人」
 3. 创建机器人，选择 **API 模式**
-4. 填写回调 URL：`https://your-domain.com/wecom/bot`
+4. 填写回调 URL：`https://your-domain.com/wecom/bot/{accountId}`（例如默认账号：`https://your-domain.com/wecom/bot/default`）
 5. 记录 Token 和 EncodingAESKey
 
 ### 3.2 Agent 模式（自建应用）
@@ -346,7 +346,7 @@ openclaw channels status
 4. **重要：** 进入「企业可信IP」→「配置」→ 添加你服务器的 IP 地址
    - 如果你使用内网穿透/动态 IP，建议配置 `channels.wecom.network.egressProxyUrl` 走固定出口代理，否则可能出现：`60020 not allow to access from your ip`
 5. 在应用详情中设置「接收消息 - 设置API接收」
-6. 填写回调 URL：`https://your-domain.com/wecom/agent`
+6. 填写回调 URL：`https://your-domain.com/wecom/agent/{accountId}`（例如默认账号：`https://your-domain.com/wecom/agent/default`）
 7. 记录回调 Token 和 EncodingAESKey
 
 <div align="center">

package/changelog/v2.3.2.md

@@ -0,0 +1,70 @@
+# 🚀 OpenClaw 企业微信 (WeCom) 插件 v2.3.2 - Bot/Agent 交付收口与文件发送兼容性增强
+
+本次 v2.3.2 版本聚焦修复企业微信 Bot 模式在复杂交付场景下的稳定性问题，重点解决：
+- Bot 已收到文件但界面仍停留在“正在搜索相关内容”不结束。
+- 本地文件下发时，`txt`、`docx` 以及更多文件类型发送不稳定的问题。
+
+---
+
+### 🌟 版本亮点 (Release Highlights)
+
+* ✅ **修复“正在搜索相关内容”不收口**：Agent 链路执行完成后，Bot 会主动推送最终流帧，确保企微思考态正确结束。
+* 🔒 **修复消息工具绕过链路问题**：在 WeCom Bot 会话中正确禁用顶层 `message` 工具，避免模型绕开 Bot 流式交付导致链路错位。
+* 📁 **本地路径下发能力增强**：支持识别 `/root`、`/home` 等 Linux 常见路径，减少文件请求误分流。
+* 📄 **文件类型兼容大幅提升**：补齐 `txt`、`docx`、`xlsx`、`pptx`、`csv`、`zip` 等常见类型 MIME，并增强入站媒体类型推断准确率。
+* 🛟 **未知类型自动兜底**：上传失败时自动回退到 `application/octet-stream` 重试，提高“能发出去”的成功率。
+
+---
+
+### 📝 详细更新日志 (Changelog)
+
+#### 【交付稳定性】🔄 Bot/Agent 链路收口修复
+- 增加统一“最终流帧”主动推送逻辑，确保 `response_url` 可用时会主动收口。
+- 当回复内容为空时增加最终可见兜底文案，避免企微前端悬空态。
+- 非图片文件、媒体处理失败、超时切换等场景统一走“Bot 提示 + Agent 私信兜底”闭环。
+
+#### 【链路一致性】🧭 工具策略修复
+- 在 WeCom Bot 会话中将 `message` 工具写入 `tools.deny`（并同步 sandbox deny），修复错误禁用位置造成的链路绕过。
+- 避免“文件已发出但 Bot 思考流未结束”的链路错位。
+
+#### 【文件兼容性】📎 MIME 与上传兜底增强
+- 扩展本地文件 MIME 推断覆盖：`txt/csv/tsv/md/json/xml/yaml/yml/pdf/doc/docx/xls/xlsx/ppt/pptx/zip/rar/7z/tar/gz/tgz/rtf/odt`。
+- 上传 multipart 时增加文件名规范化，降低特殊文件名导致的兼容性问题。
+- 新增“首选 MIME 失败 -> octet-stream 自动重试”机制，提升未知/边缘类型上传成功率。
+
+#### 【类型识别优化】🧠 入站文件名与后缀判定更准确
+- 下载并解密媒体时保留源信息（`content-type`、`content-disposition`、最终 URL），用于后续精确判断。
+- 新增三层文件类型判定策略（按优先级）：
+  - 二进制内容特征（Magic Number / 文件头）
+  - 非泛型响应头 `content-type`
+  - 文件名后缀映射
+- 文件名确定策略（按优先级）：
+  - 回调体显式文件名字段
+  - 下载响应 `content-disposition` 文件名
+  - URL 路径 basename（仅在看起来是有效文件名时采用）
+  - 兜底默认名（自动补扩展名）
+- 对 OOXML（`docx/xlsx/pptx`）增加 ZIP 内容探测，降低仅靠 URL 无后缀时误判为 `zip/bin` 的概率。
+
+#### 【质量保障】✅ 回归测试补充
+- 新增上传链路单测，覆盖：
+  - `.txt` 使用 `text/plain`
+  - `.docx` 使用官方 MIME
+  - 首次 MIME 失败时自动回退重试
+- 同步通过 WeCom monitor/outbound 相关回归测试，确保无行为回退。
+
+---
+
+### 💾 安装与升级 (Install & Update)
+
+使用 **OpenClaw** CLI 一键升级 **插件**：
+
+```bash
+openclaw plugins upgrade wecom
+```
+
+或手动更新版本至 `v2.3.2`。
+
+---
+
+### 📮 联系我们
+如果您在 **企业微信 / 微信** 接入过程中遇到任何问题，欢迎提交 Issue 反馈日志与复现场景。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.2.28",
+  "version": "2.3.2",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "repository": {

package/src/agent/api-client.ts

@@ -25,6 +25,43 @@ type TokenCache = {
 
 const tokenCaches = new Map<string, TokenCache>();
 
+function normalizeUploadFilename(filename: string): string {
+    const trimmed = filename.trim();
+    if (!trimmed) return "file.bin";
+    const ext = trimmed.includes(".") ? `.${trimmed.split(".").pop()!.toLowerCase()}` : "";
+    const base = ext ? trimmed.slice(0, -ext.length) : trimmed;
+    const sanitizedBase = base
+        .replace(/[^\x20-\x7e]/g, "_")
+        .replace(/["\\\/;=]/g, "_")
+        .replace(/\s+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    const safeBase = sanitizedBase || "file";
+    const safeExt = ext.replace(/[^a-z0-9.]/g, "");
+    return `${safeBase}${safeExt || ".bin"}`;
+}
+
+function guessUploadContentType(filename: string): string {
+    const ext = filename.split(".").pop()?.toLowerCase() || "";
+    const contentTypeMap: Record<string, string> = {
+        // image
+        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp", bmp: "image/bmp",
+        // audio / video
+        amr: "voice/amr", mp3: "audio/mpeg", wav: "audio/wav", m4a: "audio/mp4", ogg: "audio/ogg", mp4: "video/mp4", mov: "video/quicktime",
+        // documents
+        txt: "text/plain", md: "text/markdown", csv: "text/csv", tsv: "text/tab-separated-values", json: "application/json",
+        xml: "application/xml", yaml: "application/yaml", yml: "application/yaml",
+        pdf: "application/pdf", doc: "application/msword", docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        xls: "application/vnd.ms-excel", xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ppt: "application/vnd.ms-powerpoint", pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        rtf: "application/rtf", odt: "application/vnd.oasis.opendocument.text",
+        // archives
+        zip: "application/zip", rar: "application/vnd.rar", "7z": "application/x-7z-compressed",
+        gz: "application/gzip", tgz: "application/gzip", tar: "application/x-tar",
+    };
+    return contentTypeMap[ext] || "application/octet-stream";
+}
+
 function requireAgentId(agent: ResolvedAgentAccount): number {
     if (typeof agent.agentId === "number" && Number.isFinite(agent.agentId)) return agent.agentId;
     throw new Error(`wecom agent account=${agent.accountId} missing agentId; sending via cgi-bin/message/send requires agentId`);
@@ -163,48 +200,53 @@ export async function uploadMedia(params: {
     filename: string;
 }): Promise<string> {
     const { agent, type, buffer, filename } = params;
+    const safeFilename = normalizeUploadFilename(filename);
     const token = await getAccessToken(agent);
+    const proxyUrl = resolveWecomEgressProxyUrlFromNetwork(agent.network);
     // 添加 debug=1 参数获取更多错误信息
     const url = `${API_ENDPOINTS.UPLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&type=${encodeURIComponent(type)}&debug=1`;
 
     // DEBUG: 输出上传信息
-    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${filename}, size=${buffer.length} bytes`);
-
-    // 手动构造 multipart/form-data 请求体
-    // 企业微信要求包含 filename 和 filelength
-    const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
-
-    // 根据文件类型设置 Content-Type
-    const contentTypeMap: Record<string, string> = {
-        jpg: "image/jpg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif",
-        bmp: "image/bmp", amr: "voice/amr", mp4: "video/mp4",
+    console.log(`[wecom-upload] Uploading media: type=${type}, filename=${safeFilename}, size=${buffer.length} bytes`);
+
+    const uploadOnce = async (fileContentType: string) => {
+        // 手动构造 multipart/form-data 请求体
+        // 企业微信要求包含 filename 和 filelength
+        const boundary = `----WebKitFormBoundary${crypto.randomBytes(16).toString("hex")}`;
+
+        const header = Buffer.from(
+            `--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="media"; filename="${safeFilename}"; filelength=${buffer.length}\r\n` +
+            `Content-Type: ${fileContentType}\r\n\r\n`
+        );
+        const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
+        const body = Buffer.concat([header, buffer, footer]);
+
+        console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
+
+        const res = await wecomFetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                "Content-Length": String(body.length),
+            },
+            body: body,
+        }, { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
+        const json = await res.json() as { media_id?: string; errcode?: number; errmsg?: string };
+        console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+        return json;
     };
-    const ext = filename.split(".").pop()?.toLowerCase() || "";
-    const fileContentType = contentTypeMap[ext] || "application/octet-stream";
-
-    // 构造 multipart body
-    const header = Buffer.from(
-        `--${boundary}\r\n` +
-        `Content-Disposition: form-data; name="media"; filename="${filename}"; filelength=${buffer.length}\r\n` +
-        `Content-Type: ${fileContentType}\r\n\r\n`
-    );
-    const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
-    const body = Buffer.concat([header, buffer, footer]);
-
-    console.log(`[wecom-upload] Multipart body size=${body.length}, boundary=${boundary}, fileContentType=${fileContentType}`);
 
-    const res = await wecomFetch(url, {
-        method: "POST",
-        headers: {
-            "Content-Type": `multipart/form-data; boundary=${boundary}`,
-            "Content-Length": String(body.length),
-        },
-        body: body,
-    }, { proxyUrl: resolveWecomEgressProxyUrlFromNetwork(agent.network), timeoutMs: LIMITS.REQUEST_TIMEOUT_MS });
-    const json = await res.json() as { media_id?: string; errcode?: number; errmsg?: string };
+    const preferredContentType = guessUploadContentType(safeFilename);
+    let json = await uploadOnce(preferredContentType);
 
-    // DEBUG: 输出完整响应
-    console.log(`[wecom-upload] Response:`, JSON.stringify(json));
+    // 某些文件类型在严格网关/企业微信校验下可能失败，回退到通用类型再试一次。
+    if (!json?.media_id && preferredContentType !== "application/octet-stream") {
+        console.warn(
+            `[wecom-upload] Upload failed with ${preferredContentType}, retrying as application/octet-stream: ${json?.errcode} ${json?.errmsg}`,
+        );
+        json = await uploadOnce("application/octet-stream");
+    }
 
     if (!json?.media_id) {
         throw new Error(`upload failed: ${json?.errcode} ${json?.errmsg}`);

package/src/agent/api-client.upload.test.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ResolvedAgentAccount } from "../types/index.js";
+
+const { wecomFetchMock, resolveProxyMock } = vi.hoisted(() => ({
+  wecomFetchMock: vi.fn(),
+  resolveProxyMock: vi.fn(() => undefined),
+}));
+
+vi.mock("../http.js", () => ({
+  wecomFetch: wecomFetchMock,
+  readResponseBodyAsBuffer: vi.fn(),
+}));
+
+vi.mock("../config/index.js", () => ({
+  resolveWecomEgressProxyUrlFromNetwork: resolveProxyMock,
+}));
+
+import { uploadMedia } from "./api-client.js";
+
+function createAgent(agentId: number): ResolvedAgentAccount {
+  return {
+    accountId: `acct-${agentId}`,
+    enabled: true,
+    configured: true,
+    corpId: "corp",
+    corpSecret: "secret",
+    agentId,
+    token: "token",
+    encodingAESKey: "aes",
+    config: {} as any,
+  };
+}
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("wecom agent uploadMedia", () => {
+  beforeEach(() => {
+    wecomFetchMock.mockReset();
+    resolveProxyMock.mockReset();
+    resolveProxyMock.mockReturnValue(undefined);
+  });
+
+  it("uses text/plain for .txt uploads", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-1", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-1" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10001),
+      type: "file",
+      buffer: Buffer.from("hello txt"),
+      filename: "note.txt",
+    });
+
+    expect(mediaId).toBe("m-1");
+    const [, init] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const body = init.body as Buffer;
+    const bodyText = body.toString("utf8");
+    expect(bodyText).toContain('filename="note.txt"');
+    expect(bodyText).toContain("Content-Type: text/plain");
+  });
+
+  it("uses docx mime and normalizes non-ascii filename", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-2", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-2" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10002),
+      type: "file",
+      buffer: Buffer.from("docx bytes"),
+      filename: "需求文档.docx",
+    });
+
+    expect(mediaId).toBe("m-2");
+    const [, init] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const body = init.body as Buffer;
+    const bodyText = body.toString("utf8");
+    expect(bodyText).toContain('filename="file.docx"');
+    expect(bodyText).toContain(
+      "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    );
+  });
+
+  it("retries with octet-stream when preferred mime upload fails", async () => {
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ access_token: "token-3", expires_in: 7200 }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 40005, errmsg: "invalid media type" }));
+    wecomFetchMock.mockResolvedValueOnce(jsonResponse({ errcode: 0, errmsg: "ok", media_id: "m-3" }));
+
+    const mediaId = await uploadMedia({
+      agent: createAgent(10003),
+      type: "file",
+      buffer: Buffer.from("yaml bytes"),
+      filename: "config.yaml",
+    });
+
+    expect(mediaId).toBe("m-3");
+    expect(wecomFetchMock).toHaveBeenCalledTimes(3);
+
+    const [, firstUploadInit] = wecomFetchMock.mock.calls[1] as [string, RequestInit];
+    const [, retryUploadInit] = wecomFetchMock.mock.calls[2] as [string, RequestInit];
+    const firstUploadBody = (firstUploadInit.body as Buffer).toString("utf8");
+    const retryUploadBody = (retryUploadInit.body as Buffer).toString("utf8");
+    expect(firstUploadBody).toContain("Content-Type: application/yaml");
+    expect(retryUploadBody).toContain("Content-Type: application/octet-stream");
+  });
+});

package/src/agent/handler.ts

@@ -526,7 +526,7 @@ async function processAgentMessage(params: {
         SenderName: fromUser,
         SenderId: fromUser,
         Provider: "wecom",
-        Surface: "wecom",
+        Surface: "webchat",
         OriginatingChannel: "wecom",
         // 标记为 Agent 会话的回复路由目标，避免与 Bot 会话混淆：
         // - 用于让 /new /reset 这类命令回执不被 Bot 侧策略拦截
@@ -562,9 +562,9 @@ async function processAgentMessage(params: {
                     await sendText({ agent, toUser: fromUser, chatId: undefined, text });
                     log?.(`[wecom-agent] reply delivered (${info.kind}) to ${fromUser}`);
                 } catch (err: unknown) {
-                    error?.(`[wecom-agent] reply failed: ${String(err)}`);
-                }
-            },
+                    const message = err instanceof Error ? `${err.message}${err.cause ? ` (cause: ${String(err.cause)})` : ""}` : String(err);
+                    error?.(`[wecom-agent] reply failed: ${message}`);
+                }            },
             onError: (err: unknown, info: { kind: string }) => {
                 error?.(`[wecom-agent] ${info.kind} reply error: ${String(err)}`);
             },

package/src/config/network.ts

@@ -3,11 +3,15 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk";
 import type { WecomConfig, WecomNetworkConfig } from "../types/index.js";
 
 export function resolveWecomEgressProxyUrlFromNetwork(network?: WecomNetworkConfig): string | undefined {
-  const env = (process.env.OPENCLAW_WECOM_EGRESS_PROXY_URL ?? process.env.WECOM_EGRESS_PROXY_URL ?? "").trim();
-  if (env) return env;
-
-  const fromCfg = network?.egressProxyUrl?.trim() ?? "";
-  return fromCfg || undefined;
+  const proxyUrl = network?.egressProxyUrl ??
+    process.env.OPENCLAW_WECOM_EGRESS_PROXY_URL ??
+    process.env.WECOM_EGRESS_PROXY_URL ??
+    process.env.HTTPS_PROXY ??
+    process.env.ALL_PROXY ??
+    process.env.HTTP_PROXY ??
+    "";
+    
+  return proxyUrl.trim() || undefined;
 }
 
 export function resolveWecomEgressProxyUrl(cfg: OpenClawConfig): string | undefined {

package/src/http.ts

@@ -57,13 +57,28 @@ export async function wecomFetch(input: string | URL, init?: RequestInit, opts?:
 
   const initSignal = init?.signal ?? undefined;
   const signal = mergeAbortSignal({ signal: opts?.signal ?? initSignal, timeoutMs: opts?.timeoutMs });
+  
+  const headers = new Headers(init?.headers ?? {});
+  if (!headers.has("User-Agent")) {
+    headers.set("User-Agent", "OpenClaw/2.0 (WeCom-Agent)");
+  }
+
   const nextInit: RequestInit & { dispatcher?: Dispatcher } = {
     ...(init ?? {}),
     ...(signal ? { signal } : {}),
     ...(dispatcher ? { dispatcher } : {}),
+    headers,
   };
 
-  return undiciFetch(input, nextInit as Parameters<typeof undiciFetch>[1]) as unknown as Promise<Response>;
+  try {
+    return await undiciFetch(input, nextInit as Parameters<typeof undiciFetch>[1]) as unknown as Response;
+  } catch (err: unknown) {
+    if (err instanceof Error && err.name === "TypeError" && err.message === "fetch failed") {
+      const cause = (err as any).cause;
+      console.error(`[wecom-http] fetch failed: ${input} (proxy: ${proxyUrl || "none"})${cause ? ` - cause: ${String(cause)}` : ""}`);
+    }
+    throw err;
+  }
 }
 
 /**
@@ -99,4 +114,3 @@ export async function readResponseBodyAsBuffer(res: Response, maxBytes?: number)
 
   return Buffer.concat(chunks.map((c) => Buffer.from(c)));
 }
-

package/src/media.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { decryptWecomMedia } from "./media.js";
+import { decryptWecomMedia, decryptWecomMediaWithMeta } from "./media.js";
 import { WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
 import crypto from "node:crypto";
 
@@ -52,4 +52,31 @@ describe("decryptWecomMedia", () => {
     it("should fail if key is invalid", async () => {
         await expect(decryptWecomMedia("http://url", "invalid-key")).rejects.toThrow();
     });
+
+    it("should return source metadata when using decryptWecomMediaWithMeta", async () => {
+        const aesKeyBase64 = "jWmYm7qr5nMoCAstdRmNjt3p7vsH8HkK+qiJqQ0aaaa=";
+        const aesKey = Buffer.from(aesKeyBase64 + "=", "base64");
+        const iv = aesKey.subarray(0, 16);
+        const originalData = Buffer.from("meta test", "utf8");
+        const padded = pkcs7Pad(originalData, WECOM_PKCS7_BLOCK_SIZE);
+        const cipher = crypto.createCipheriv("aes-256-cbc", aesKey, iv);
+        cipher.setAutoPadding(false);
+        const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
+
+        undiciFetch.mockResolvedValue(
+            new Response(encrypted, {
+                status: 200,
+                headers: {
+                    "content-type": "application/octet-stream; charset=binary",
+                    "content-disposition": "attachment; filename*=UTF-8''report%20v1.docx",
+                },
+            }),
+        );
+
+        const decrypted = await decryptWecomMediaWithMeta("http://mock.url/media?id=1", aesKeyBase64);
+        expect(decrypted.buffer.toString("utf8")).toBe("meta test");
+        expect(decrypted.sourceContentType).toBe("application/octet-stream");
+        expect(decrypted.sourceFilename).toBe("report v1.docx");
+        expect(decrypted.sourceUrl).toBe("http://mock.url/media?id=1");
+    });
 });

package/src/media.ts

@@ -2,6 +2,41 @@ import crypto from "node:crypto";
 import { decodeEncodingAESKey, pkcs7Unpad, WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
 import { readResponseBodyAsBuffer, wecomFetch, type WecomHttpOptions } from "./http.js";
 
+export type DecryptedWecomMedia = {
+    buffer: Buffer;
+    sourceContentType?: string;
+    sourceFilename?: string;
+    sourceUrl?: string;
+};
+
+function normalizeMime(contentType?: string | null): string | undefined {
+    const raw = String(contentType ?? "").trim();
+    if (!raw) return undefined;
+    return raw.split(";")[0]?.trim().toLowerCase() || undefined;
+}
+
+function extractFilenameFromContentDisposition(disposition?: string | null): string | undefined {
+    const raw = String(disposition ?? "").trim();
+    if (!raw) return undefined;
+
+    const star = raw.match(/filename\*\s*=\s*([^;]+)/i);
+    if (star?.[1]) {
+        const v = star[1].trim().replace(/^UTF-8''/i, "").replace(/^"(.*)"$/, "$1");
+        try {
+            const decoded = decodeURIComponent(v);
+            if (decoded.trim()) return decoded.trim();
+        } catch { /* ignore */ }
+        if (v.trim()) return v.trim();
+    }
+
+    const plain = raw.match(/filename\s*=\s*([^;]+)/i);
+    if (plain?.[1]) {
+        const v = plain[1].trim().replace(/^"(.*)"$/, "$1").trim();
+        if (v) return v;
+    }
+    return undefined;
+}
+
 /**
  * **decryptWecomMedia (解密企业微信媒体文件)**
  * 
@@ -28,11 +63,29 @@ export async function decryptWecomMediaWithHttp(
     encodingAESKey: string,
     params?: { maxBytes?: number; http?: WecomHttpOptions },
 ): Promise<Buffer> {
+    const decrypted = await decryptWecomMediaWithMeta(url, encodingAESKey, params);
+    return decrypted.buffer;
+}
+
+/**
+ * **decryptWecomMediaWithMeta (解密企业微信媒体并返回源信息)**
+ * 
+ * 在返回解密结果的同时，保留下载响应中的元信息（content-type / filename / final url），
+ * 供上层更准确地推断文件后缀和 MIME。
+ */
+export async function decryptWecomMediaWithMeta(
+    url: string,
+    encodingAESKey: string,
+    params?: { maxBytes?: number; http?: WecomHttpOptions },
+): Promise<DecryptedWecomMedia> {
     // 1. Download encrypted content
     const res = await wecomFetch(url, undefined, { ...params?.http, timeoutMs: params?.http?.timeoutMs ?? 15_000 });
     if (!res.ok) {
         throw new Error(`failed to download media: ${res.status}`);
     }
+    const sourceContentType = normalizeMime(res.headers.get("content-type"));
+    const sourceFilename = extractFilenameFromContentDisposition(res.headers.get("content-disposition"));
+    const sourceUrl = res.url || url;
     const encryptedData = await readResponseBodyAsBuffer(res, params?.maxBytes);
 
     // 2. Prepare Key and IV
@@ -51,5 +104,10 @@ export async function decryptWecomMediaWithHttp(
     // Note: Unlike msg bodies, usually removing PKCS#7 padding is enough for media files.
     // The Python SDK logic: pad_len = decrypted_data[-1]; decrypted_data = decrypted_data[:-pad_len]
     // Our pkcs7Unpad function does exactly this + validation.
-    return pkcs7Unpad(decryptedPadded, WECOM_PKCS7_BLOCK_SIZE);
+    return {
+        buffer: pkcs7Unpad(decryptedPadded, WECOM_PKCS7_BLOCK_SIZE),
+        sourceContentType,
+        sourceFilename,
+        sourceUrl,
+    };
 }

package/src/monitor.active.test.ts

@@ -190,14 +190,17 @@ describe("Monitor Active Features", () => {
         undiciFetch.mockResolvedValue(new Response("ok", { status: 200 }));
         await sendActiveMessage(streamId, "Active Hello");
 
-        expect(undiciFetch).toHaveBeenCalledWith(
-            "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test-key",
+        expect(undiciFetch).toHaveBeenCalled();
+        const [url, init] = undiciFetch.mock.calls.at(-1)! as [string, RequestInit];
+        expect(url).toBe("https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test-key");
+        expect(init).toEqual(
             expect.objectContaining({
                 method: "POST",
-                headers: expect.objectContaining({ "Content-Type": "application/json" }),
                 body: JSON.stringify({ msgtype: "text", text: { content: "Active Hello" } }),
             }),
         );
+        const headers = new Headers(init.headers);
+        expect(headers.get("content-type")).toBe("application/json");
     });
 
     it("should fallback non-image media to agent DM (and push a Chinese prompt)", async () => {
@@ -237,6 +240,6 @@ describe("Monitor Active Features", () => {
         expect(undiciFetch).toHaveBeenCalled();
     });
 
-    // 注：本机路径（/Users/... 或 /tmp/...）短路发图逻辑属于运行态特性，
+    // 注：本机路径（/Users/...、/tmp/...、/root/...、/home/...）短路发图逻辑属于运行态特性，
     // 单测在 fake timers + module singleton 状态下容易引入脆弱性；这里优先覆盖更关键的兜底链路与去重逻辑。
 });