@yanhaidao/wecom 2.2.3 → 2.2.4

package/src/agent/handler.ts

@@ -3,19 +3,33 @@
  * 处理 XML 格式回调
  */
 
+import { pathToFileURL } from "node:url";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
 import type { ResolvedAgentAccount } from "../types/index.js";
 import { LIMITS } from "../types/constants.js";
 import { decryptWecomEncrypted, verifyWecomSignature, computeWecomMsgSignature, encryptWecomPlaintext } from "../crypto/index.js";
 import { extractEncryptFromXml, buildEncryptedXmlResponse } from "../crypto/xml.js";
-import { parseXml, extractMsgType, extractFromUser, extractContent, extractChatId } from "../shared/xml-parser.js";
-import { sendText } from "./api-client.js";
+import { parseXml, extractMsgType, extractFromUser, extractContent, extractChatId, extractMediaId } from "../shared/xml-parser.js";
+import { sendText, downloadMedia } from "./api-client.js";
 import { getWecomRuntime } from "../runtime.js";
+import type { WecomAgentInboundMessage } from "../types/index.js";
 
 /** 错误提示信息 */
 const ERROR_HELP = "\n\n遇到问题？联系作者: YanHaidao (微信: YanHaidao)";
 
+/**
+ * **AgentWebhookParams (Webhook 处理器参数)**
+ * 
+ * 传递给 Agent Webhook 处理函数的上下文参数集合。
+ * @property req Node.js 原始请求对象
+ * @property res Node.js 原始响应对象
+ * @property agent 解析后的 Agent 账号信息
+ * @property config 全局插件配置
+ * @property core OpenClaw 插件运行时
+ * @property log 可选日志输出函数
+ * @property error 可选错误输出函数
+ */
 export type AgentWebhookParams = {
     req: IncomingMessage;
     res: ServerResponse;
@@ -27,7 +41,9 @@ export type AgentWebhookParams = {
 };
 
 /**
- * 解析查询参数
+ * **resolveQueryParams (解析查询参数)**
+ * 
+ * 辅助函数：从 IncomingMessage 中解析 URL 查询字符串，用于获取签名、时间戳等参数。
  */
 function resolveQueryParams(req: IncomingMessage): URLSearchParams {
     const url = new URL(req.url ?? "/", "http://localhost");
@@ -35,7 +51,10 @@ function resolveQueryParams(req: IncomingMessage): URLSearchParams {
 }
 
 /**
- * 读取原始请求体
+ * **readRawBody (读取原始请求体)**
+ * 
+ * 异步读取 HTTP POST 请求的原始 BODY 数据（XML 字符串）。
+ * 包含最大体积限制检查，防止内存溢出攻击。
  */
 async function readRawBody(req: IncomingMessage, maxSize: number = LIMITS.MAX_REQUEST_BODY_SIZE): Promise<string> {
     return new Promise((resolve, reject) => {
@@ -61,7 +80,13 @@ async function readRawBody(req: IncomingMessage, maxSize: number = LIMITS.MAX_RE
 }
 
 /**
- * 处理 URL 验证 (GET)
+ * **handleUrlVerification (处理 URL 验证)**
+ * 
+ * 处理企业微信 Agent 配置时的 GET 请求验证。
+ * 流程：
+ * 1. 验证 msg_signature 签名。
+ * 2. 解密 echostr 参数。
+ * 3. 返回解密后的明文 echostr。
  */
 async function handleUrlVerification(
     req: IncomingMessage,
@@ -168,6 +193,7 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
             chatId,
             msgType,
             content,
+            msg,
             log,
             error,
         }).catch((err) => {
@@ -185,7 +211,15 @@ async function handleMessageCallback(params: AgentWebhookParams): Promise<boolea
 }
 
 /**
- * 处理 Agent 消息 (调用 OpenClaw Agent)
+ * **processAgentMessage (处理 Agent 消息)**
+ * 
+ * 异步处理解密后的消息内容，并触发 OpenClaw Agent。
+ * 流程：
+ * 1. 路由解析：根据 userid或群ID 确定 Agent 路由。
+ * 2. 媒体处理：如果是图片/文件等，下载资源。
+ * 3. 上下文构建：创建 Inbound Context。
+ * 4. 会话记录：更新 Session 状态。
+ * 5. 调度回复：将 Agent 的响应通过 `api-client` 发送回企业微信。
  */
 async function processAgentMessage(params: {
     agent: ResolvedAgentAccount;
@@ -195,14 +229,67 @@ async function processAgentMessage(params: {
     chatId?: string;
     msgType: string;
     content: string;
+    msg: WecomAgentInboundMessage;
     log?: (msg: string) => void;
     error?: (msg: string) => void;
 }): Promise<void> {
-    const { agent, config, core, fromUser, chatId, content, log, error } = params;
+    const { agent, config, core, fromUser, chatId, content, msg, msgType, log, error } = params;
 
     const isGroup = Boolean(chatId);
     const peerId = isGroup ? chatId! : fromUser;
 
+    // 处理媒体文件
+    const attachments: any[] = []; // TODO: define specific type
+    let finalContent = content;
+    let mediaPath: string | undefined;
+    let mediaType: string | undefined;
+
+    if (["image", "voice", "video", "file"].includes(msgType)) {
+        const mediaId = extractMediaId(msg);
+        if (mediaId) {
+            try {
+                log?.(`[wecom-agent] downloading media: ${mediaId} (${msgType})`);
+                const { buffer, contentType } = await downloadMedia({ agent, mediaId });
+
+                // 推断文件名后缀
+                const extMap: Record<string, string> = {
+                    "image/jpeg": "jpg", "image/png": "png", "image/gif": "gif",
+                    "audio/amr": "amr", "audio/speex": "speex", "video/mp4": "mp4",
+                };
+                const ext = extMap[contentType] || "bin";
+                const filename = `${mediaId}.${ext}`;
+
+                // 使用 Core SDK 保存媒体文件
+                const saved = await core.channel.media.saveMediaBuffer(
+                    buffer,
+                    contentType,
+                    "inbound", // context/scope
+                    LIMITS.MAX_REQUEST_BODY_SIZE, // limit
+                    filename
+                );
+
+                log?.(`[wecom-agent] media saved to: ${saved.path}`);
+                mediaPath = saved.path;
+                mediaType = contentType;
+
+                // 构建附件
+                attachments.push({
+                    name: filename,
+                    mimeType: contentType,
+                    url: pathToFileURL(saved.path).href, // 使用跨平台安全的文件 URL
+                });
+
+                // 更新文本提示
+                finalContent = `${content} (已下载 ${buffer.length} 字节)`;
+            } catch (err) {
+                error?.(`[wecom-agent] media download failed: ${String(err)}`);
+                finalContent = `${content} (媒体下载失败)`;
+            }
+        } else {
+            error?.(`[wecom-agent] mediaId not found for ${msgType}`);
+        }
+    }
+
     // 解析路由
     const route = core.channel.routing.resolveAgentRoute({
         cfg: config,
@@ -226,13 +313,14 @@ async function processAgentMessage(params: {
         from: fromLabel,
         previousTimestamp,
         envelope: envelopeOptions,
-        body: content,
+        body: finalContent,
     });
 
     const ctxPayload = core.channel.reply.finalizeInboundContext({
         Body: body,
-        RawBody: content,
-        CommandBody: content,
+        RawBody: finalContent,
+        CommandBody: finalContent,
+        Attachments: attachments.length > 0 ? attachments : undefined,
         From: isGroup ? `wecom:group:${peerId}` : `wecom:${fromUser}`,
         To: `wecom:${peerId}`,
         SessionKey: route.sessionKey,
@@ -246,6 +334,9 @@ async function processAgentMessage(params: {
         OriginatingChannel: "wecom",
         OriginatingTo: `wecom:${peerId}`,
         CommandAuthorized: true, // 已通过 WeCom 签名验证
+        MediaPath: mediaPath,
+        MediaType: mediaType,
+        MediaUrl: mediaPath,
     });
 
     // 记录会话
@@ -290,7 +381,10 @@ async function processAgentMessage(params: {
 }
 
 /**
- * 处理 Agent Webhook 请求入口
+ * **handleAgentWebhook (Agent Webhook 入口)**
+ * 
+ * 统一处理 Agent 模式的 Webhook 请求。
+ * 根据 HTTP 方法分发到 URL 验证 (GET) 或 消息处理 (POST)。
  */
 export async function handleAgentWebhook(params: AgentWebhookParams): Promise<boolean> {
     const { req } = params;

package/src/channel.ts

@@ -43,6 +43,12 @@ type ResolvedWecomAccount = {
   agent?: ResolvedAgentAccount;
 };
 
+/**
+ * **resolveWecomAccount (解析账号配置)**
+ * 
+ * 从全局配置中解析出 WeCom 渠道的配置状态。
+ * 兼容 Bot 和 Agent 两种模式的配置检查。
+ */
 function resolveWecomAccount(cfg: OpenClawConfig): ResolvedWecomAccount {
   const enabled = (cfg.channels?.wecom as { enabled?: boolean } | undefined)?.enabled !== false;
   const accounts = resolveWecomAccounts(cfg);
@@ -169,6 +175,17 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
     }),
   },
   gateway: {
+    /**
+     * **startAccount (启动账号)**
+     * 
+     * 插件生命周期：启动
+     * 职责：
+     * 1. 检查配置是否有效。
+     * 2. 注册 Bot Webhook (`/wecom`, `/wecom/bot`)。
+     * 3. 注册 Agent Webhook (`/wecom/agent`)。
+     * 4. 更新运行时状态 (Running)。
+     * 5. 返回停止回调 (Cleanup)。
+     */
     startAccount: async (ctx) => {
       const account = ctx.account;
       const bot = account.bot;

package/src/config/accounts.ts

@@ -7,6 +7,7 @@ import type {
     WecomConfig,
     WecomBotConfig,
     WecomAgentConfig,
+    WecomNetworkConfig,
     ResolvedBotAccount,
     ResolvedAgentAccount,
     ResolvedMode,
@@ -50,7 +51,7 @@ function resolveBotAccount(config: WecomBotConfig): ResolvedBotAccount {
 /**
  * 解析 Agent 模式账号
  */
-function resolveAgentAccount(config: WecomAgentConfig): ResolvedAgentAccount {
+function resolveAgentAccount(config: WecomAgentConfig, network?: WecomNetworkConfig): ResolvedAgentAccount {
     const agentIdRaw = config.agentId;
     const agentId = typeof agentIdRaw === "number" ? agentIdRaw : Number(agentIdRaw);
 
@@ -67,6 +68,7 @@ function resolveAgentAccount(config: WecomAgentConfig): ResolvedAgentAccount {
         token: config.token,
         encodingAESKey: config.encodingAESKey,
         config,
+        network,
     };
 }
 
@@ -83,8 +85,8 @@ export function resolveWecomAccounts(cfg: OpenClawConfig): ResolvedWecomAccounts
     const mode = detectMode(wecom);
 
     return {
-        bot: mode.bot && wecom.bot ? resolveBotAccount(wecom.bot) : undefined,
-        agent: mode.agent && wecom.agent ? resolveAgentAccount(wecom.agent) : undefined,
+        bot: mode.bot && wecom.bot ? { ...resolveBotAccount(wecom.bot), network: wecom.network } : undefined,
+        agent: mode.agent && wecom.agent ? resolveAgentAccount(wecom.agent, wecom.network) : undefined,
     };
 }
 

package/src/config/index.ts

@@ -8,3 +8,4 @@ export {
     resolveWecomAccounts,
     isWecomEnabled,
 } from "./accounts.js";
+export { resolveWecomEgressProxyUrl, resolveWecomEgressProxyUrlFromNetwork } from "./network.js";

package/src/config/network.ts

@@ -0,0 +1,16 @@
+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;
+}
+
+export function resolveWecomEgressProxyUrl(cfg: OpenClawConfig): string | undefined {
+  const wecom = cfg.channels?.wecom as WecomConfig | undefined;
+  return resolveWecomEgressProxyUrlFromNetwork(wecom?.network);
+}

package/src/config/schema.ts

@@ -4,14 +4,29 @@
 
 import { z } from "zod";
 
-/** DM 策略 Schema */
+/**
+ * **dmSchema (单聊配置)**
+ * 
+ * 控制单聊行为（如允许名单、策略）。
+ * @property enabled - 是否启用单聊 [默认: true]
+ * @property policy - 访问策略: "pairing" (需配对, 默认), "allowlist" (仅在名单), "open" (所有人), "disabled" (禁用)
+ * @property allowFrom - 允许的用户ID或群ID列表 (仅当 policy="allowlist" 时生效)
+ */
 const dmSchema = z.object({
     enabled: z.boolean().optional(),
     policy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
     allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
 }).optional();
 
-/** 媒体配置 Schema */
+/**
+ * **mediaSchema (媒体处理配置)**
+ * 
+ * 控制媒体文件的下载和缓存行为。
+ * @property tempDir - 临时文件下载目录
+ * @property retentionHours - 临时文件保留时间（小时）
+ * @property cleanupOnStart - 启动时是否自动清理旧文件
+ * @property maxBytes - 允许下载的最大字节数
+ */
 const mediaSchema = z.object({
     tempDir: z.string().optional(),
     retentionHours: z.number().optional(),
@@ -19,14 +34,33 @@ const mediaSchema = z.object({
     maxBytes: z.number().optional(),
 }).optional();
 
-/** 网络配置 Schema */
+/**
+ * **networkSchema (网络配置)**
+ * 
+ * 控制 HTTP 请求行为，特别是出站代理。
+ * @property timeoutMs - 请求超时时间 (毫秒)
+ * @property retries - 重试次数
+ * @property retryDelayMs - 重试间隔 (毫秒)
+ * @property egressProxyUrl - 出站 HTTP 代理 (如 "http://127.0.0.1:7890")
+ */
 const networkSchema = z.object({
     timeoutMs: z.number().optional(),
     retries: z.number().optional(),
     retryDelayMs: z.number().optional(),
+    egressProxyUrl: z.string().optional(),
 }).optional();
 
-/** Bot 模式配置 Schema */
+/**
+ * **botSchema (Bot 模式配置)**
+ * 
+ * 用于配置企业微信内部机器人 (Webhook 模式)。
+ * @property token - 企业微信后台设置的 Token
+ * @property encodingAESKey - 企业微信后台设置的 EncodingAESKey
+ * @property receiveId - (可选) 接收者ID，通常不用填
+ * @property streamPlaceholderContent - (可选) 流式响应中的占位符，默认为 "Thinking..."或空
+ * @property welcomeText - (可选) 用户首次对话时的欢迎语
+ * @property dm - 单聊策略覆盖配置
+ */
 const botSchema = z.object({
     token: z.string(),
     encodingAESKey: z.string(),
@@ -36,7 +70,18 @@ const botSchema = z.object({
     dm: dmSchema,
 }).optional();
 
-/** Agent 模式配置 Schema */
+/**
+ * **agentSchema (Agent 模式配置)**
+ * 
+ * 用于配置企业微信自建应用 (Agent)。
+ * @property corpId - 企业 ID (CorpID)
+ * @property corpSecret - 应用 Secret
+ * @property agentId - 应用 AgentId (数字)
+ * @property token - 回调配置 Token
+ * @property encodingAESKey - 回调配置 EncodingAESKey
+ * @property welcomeText - (可选) 欢迎语
+ * @property dm - 单聊策略覆盖配置
+ */
 const agentSchema = z.object({
     corpId: z.string(),
     corpSecret: z.string(),

package/src/config-schema.ts

@@ -20,6 +20,7 @@ export const WecomConfigSchema = z.object({
   receiveId: z.string().optional(),
 
   streamPlaceholderContent: z.string().optional(),
+  debounceMs: z.number().optional(),
 
   welcomeText: z.string().optional(),
   dm: dmSchema,
@@ -33,6 +34,7 @@ export const WecomConfigSchema = z.object({
     encodingAESKey: z.string().optional(),
     receiveId: z.string().optional(),
     streamPlaceholderContent: z.string().optional(),
+    debounceMs: z.number().optional(),
     welcomeText: z.string().optional(),
     dm: dmSchema,
   })).optional(),

package/src/crypto.ts

@@ -1,5 +1,11 @@
 import crypto from "node:crypto";
 
+/**
+ * **decodeEncodingAESKey (解码 AES Key)**
+ * 
+ * 将企业微信配置的 Base64 编码的 AES Key 解码为 Buffer。
+ * 包含补全 Padding 和长度校验 (必须32字节)。
+ */
 export function decodeEncodingAESKey(encodingAESKey: string): Buffer {
   const trimmed = encodingAESKey.trim();
   if (!trimmed) throw new Error("encodingAESKey missing");
@@ -22,6 +28,12 @@ function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
   return Buffer.concat([buf, Buffer.alloc(pad, padByte[0]!)]);
 }
 
+/**
+ * **pkcs7Unpad (去除 PKCS#7 填充)**
+ * 
+ * 移除 AES 解密后的 PKCS#7 填充字节。
+ * 包含填充合法性校验。
+ */
 export function pkcs7Unpad(buf: Buffer, blockSize: number): Buffer {
   if (buf.length === 0) throw new Error("invalid pkcs7 payload");
   const pad = buf[buf.length - 1]!;
@@ -44,6 +56,11 @@ function sha1Hex(input: string): string {
   return crypto.createHash("sha1").update(input).digest("hex");
 }
 
+/**
+ * **computeWecomMsgSignature (计算消息签名)**
+ * 
+ * 算法：sha1(sort(token, timestamp, nonce, encrypt_msg))
+ */
 export function computeWecomMsgSignature(params: {
   token: string;
   timestamp: string;
@@ -56,6 +73,11 @@ export function computeWecomMsgSignature(params: {
   return sha1Hex(parts.join(""));
 }
 
+/**
+ * **verifyWecomSignature (验证消息签名)**
+ * 
+ * 比较计算出的签名与企业微信传入的签名是否一致。
+ */
 export function verifyWecomSignature(params: {
   token: string;
   timestamp: string;
@@ -72,6 +94,17 @@ export function verifyWecomSignature(params: {
   return expected === params.signature;
 }
 
+/**
+ * **decryptWecomEncrypted (解密企业微信消息)**
+ * 
+ * 将企业微信的 AES 加密包解密为明文。
+ * 流程：
+ * 1. Base64 解码 AESKey 并获取 IV (前16字节)。
+ * 2. AES-CBC 解密。
+ * 3. 去除 PKCS#7 填充。
+ * 4. 拆解协议包结构: [16字节随机串][4字节长度][消息体][接收者ID]。
+ * 5. 校验接收者ID (ReceiveId)。
+ */
 export function decryptWecomEncrypted(params: {
   encodingAESKey: string;
   receiveId?: string;
@@ -111,6 +144,16 @@ export function decryptWecomEncrypted(params: {
   return msg;
 }
 
+/**
+ * **encryptWecomPlaintext (加密回复消息)**
+ * 
+ * 将明文消息打包为企业微信的加密格式。
+ * 流程：
+ * 1. 构造协议包: [16字节随机串][4字节长度][消息体][接收者ID]。
+ * 2. PKCS#7 填充。
+ * 3. AES-CBC 加密。
+ * 4. 转 Base64。
+ */
 export function encryptWecomPlaintext(params: {
   encodingAESKey: string;
   receiveId?: string;

package/src/http.ts

@@ -0,0 +1,102 @@
+import type { Dispatcher } from "undici";
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+
+type ProxyDispatcher = Dispatcher;
+
+const proxyDispatchers = new Map<string, ProxyDispatcher>();
+
+/**
+ * **getProxyDispatcher (获取代理 Dispatcher)**
+ * 
+ * 缓存并复用 ProxyAgent，避免重复创建连接池。
+ */
+function getProxyDispatcher(proxyUrl: string): ProxyDispatcher {
+  const existing = proxyDispatchers.get(proxyUrl);
+  if (existing) return existing;
+  const created = new ProxyAgent(proxyUrl);
+  proxyDispatchers.set(proxyUrl, created);
+  return created;
+}
+
+function mergeAbortSignal(params: {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}): AbortSignal | undefined {
+  const signals: AbortSignal[] = [];
+  if (params.signal) signals.push(params.signal);
+  if (params.timeoutMs && Number.isFinite(params.timeoutMs) && params.timeoutMs > 0) {
+    signals.push(AbortSignal.timeout(params.timeoutMs));
+  }
+  if (!signals.length) return undefined;
+  if (signals.length === 1) return signals[0];
+  return AbortSignal.any(signals);
+}
+
+/**
+ * **WecomHttpOptions (HTTP 选项)**
+ * 
+ * @property proxyUrl 代理服务器地址
+ * @property timeoutMs 请求超时时间 (毫秒)
+ * @property signal AbortSignal 信号
+ */
+export type WecomHttpOptions = {
+  proxyUrl?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+};
+
+/**
+ * **wecomFetch (统一 HTTP 请求)**
+ * 
+ * 基于 `undici` 的 fetch 封装，自动处理 ProxyAgent 和 Timeout。
+ * 所有对企业微信 API 的调用都应经过此函数。
+ */
+export async function wecomFetch(input: string | URL, init?: RequestInit, opts?: WecomHttpOptions): Promise<Response> {
+  const proxyUrl = opts?.proxyUrl?.trim() ?? "";
+  const dispatcher = proxyUrl ? getProxyDispatcher(proxyUrl) : undefined;
+
+  const initSignal = init?.signal ?? undefined;
+  const signal = mergeAbortSignal({ signal: opts?.signal ?? initSignal, timeoutMs: opts?.timeoutMs });
+  const nextInit: RequestInit & { dispatcher?: Dispatcher } = {
+    ...(init ?? {}),
+    ...(signal ? { signal } : {}),
+    ...(dispatcher ? { dispatcher } : {}),
+  };
+
+  return undiciFetch(input, nextInit as Parameters<typeof undiciFetch>[1]) as unknown as Promise<Response>;
+}
+
+/**
+ * **readResponseBodyAsBuffer (读取响应 Body)**
+ * 
+ * 将 Response Body 读取为 Buffer，支持最大字节限制以防止内存溢出。
+ * 适用于下载媒体文件等场景。
+ */
+export async function readResponseBodyAsBuffer(res: Response, maxBytes?: number): Promise<Buffer> {
+  if (!res.body) return Buffer.alloc(0);
+
+  const limit = maxBytes && Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : undefined;
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+
+  const reader = res.body.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+
+    total += value.byteLength;
+    if (limit && total > limit) {
+      try {
+        await reader.cancel("body too large");
+      } catch {
+        // ignore
+      }
+      throw new Error(`response body too large (>${limit} bytes)`);
+    }
+    chunks.push(value);
+  }
+
+  return Buffer.concat(chunks.map((c) => Buffer.from(c)));
+}
+

package/src/media.test.ts

@@ -1,10 +1,17 @@
 import { describe, it, expect, vi } from "vitest";
 import { decryptWecomMedia } from "./media.js";
 import { WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
-import axios from "axios";
 import crypto from "node:crypto";
 
-vi.mock("axios");
+const { undiciFetch } = vi.hoisted(() => {
+    const undiciFetch = vi.fn();
+    return { undiciFetch };
+});
+
+vi.mock("undici", () => ({
+    fetch: undiciFetch,
+    ProxyAgent: class ProxyAgent { },
+}));
 
 function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
     const mod = buf.length % blockSize;
@@ -28,19 +35,18 @@ describe("decryptWecomMedia", () => {
         cipher.setAutoPadding(false);
         const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
 
-        // 3. Mock Axios
-        (axios.get as any).mockResolvedValue({
-            data: encrypted,
-        });
+        // 3. Mock HTTP fetch
+        undiciFetch.mockResolvedValue(new Response(encrypted));
 
         // 4. Test
         const decrypted = await decryptWecomMedia("http://mock.url/image", aesKeyBase64);
 
         // 5. Assert
         expect(decrypted.toString("utf8")).toBe("Hello WeCom Image Data");
-        expect(axios.get).toHaveBeenCalledWith("http://mock.url/image", expect.objectContaining({
-            responseType: "arraybuffer"
-        }));
+        expect(undiciFetch).toHaveBeenCalledWith(
+            "http://mock.url/image",
+            expect.objectContaining({ signal: expect.anything() }),
+        );
     });
 
     it("should fail if key is invalid", async () => {

package/src/media.ts

@@ -1,23 +1,39 @@
 import crypto from "node:crypto";
-import axios from "axios";
 import { decodeEncodingAESKey, pkcs7Unpad, WECOM_PKCS7_BLOCK_SIZE } from "./crypto.js";
+import { readResponseBodyAsBuffer, wecomFetch, type WecomHttpOptions } from "./http.js";
 
 /**
- * Download and decrypt WeCom media file (e.g. image).
+ * **decryptWecomMedia (解密企业微信媒体文件)**
  * 
- * WeCom media files are AES-256-CBC encrypted with the same EncodingAESKey.
- * The IV is the first 16 bytes of the AES Key.
- * The content is PKCS#7 padded.
+ * 简易封装：直接传入 URL 和 AES Key 下载并解密。
+ * 企业微信媒体文件使用与消息体相同的 AES-256-CBC 加密，IV 为 AES Key 前16字节。
+ * 解密后需移除 PKCS#7 填充。
  */
 export async function decryptWecomMedia(url: string, encodingAESKey: string, maxBytes?: number): Promise<Buffer> {
+    return decryptWecomMediaWithHttp(url, encodingAESKey, { maxBytes });
+}
+
+/**
+ * **decryptWecomMediaWithHttp (解密企业微信媒体 - 高级)**
+ * 
+ * 支持传递 HTTP 选项（如 Proxy、Timeout）。
+ * 流程：
+ * 1. 下载加密内容。
+ * 2. 准备 AES Key 和 IV。
+ * 3. AES-CBC 解密。
+ * 4. PKCS#7 去除填充。
+ */
+export async function decryptWecomMediaWithHttp(
+    url: string,
+    encodingAESKey: string,
+    params?: { maxBytes?: number; http?: WecomHttpOptions },
+): Promise<Buffer> {
     // 1. Download encrypted content
-    const response = await axios.get(url, {
-        responseType: "arraybuffer", // Important: get raw buffer
-        timeout: 15000,
-        maxContentLength: maxBytes || undefined, // Limit download size
-        maxBodyLength: maxBytes || undefined,
-    });
-    const encryptedData = Buffer.from(response.data);
+    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 encryptedData = await readResponseBodyAsBuffer(res, params?.maxBytes);
 
     // 2. Prepare Key and IV
     const aesKey = decodeEncodingAESKey(encodingAESKey);