@sunnoy/wecom 1.4.1 → 1.5.1

package/index.js

@@ -38,9 +38,16 @@ const plugin = {
     api.registerChannel({ plugin: wecomChannelPlugin });
     logger.info("WeCom channel registered");
 
-    // Register HTTP handler for webhooks
-    api.registerHttpHandler(wecomHttpHandler);
-    logger.info("WeCom HTTP handler registered");
+    // Register HTTP handler for webhooks.
+    // OpenClaw 2026.3.2+ removed registerHttpHandler; the primary route
+    // registration now happens in gateway.startAccount via registerPluginHttpRoute.
+    // Keep the legacy handler for backward compatibility with older versions.
+    if (typeof api.registerHttpHandler === "function") {
+      api.registerHttpHandler(wecomHttpHandler);
+      logger.info("WeCom HTTP handler registered (legacy wildcard)");
+    } else {
+      logger.info("WeCom: registerHttpHandler unavailable, routes registered via gateway lifecycle");
+    }
   },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "1.4.1",
+    "version": "1.5.1",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",
@@ -22,6 +22,9 @@
     "peerDependencies": {
         "openclaw": "*"
     },
+    "optionalDependencies": {
+        "undici": "^7.0.0"
+    },
     "scripts": {
         "test": "npm run test:unit",
         "test:unit": "node --test tests/*.test.js",

package/wecom/agent-api.js

@@ -10,6 +10,7 @@ import {
   AGENT_API_REQUEST_TIMEOUT_MS,
   TOKEN_REFRESH_BUFFER_MS,
 } from "./constants.js";
+import { wecomFetch } from "./http.js";
 
 /**
  * Token cache: Map<corpId:agentId, { token, expiresAt, refreshPromise }>
@@ -43,7 +44,7 @@ export async function getAccessToken(agent) {
   cache.refreshPromise = (async () => {
     try {
       const url = `${AGENT_API_ENDPOINTS.GET_TOKEN}?corpid=${encodeURIComponent(agent.corpId)}&corpsecret=${encodeURIComponent(agent.corpSecret)}`;
-      const res = await fetch(url, { signal: AbortSignal.timeout(AGENT_API_REQUEST_TIMEOUT_MS) });
+      const res = await wecomFetch(url);
       const json = await res.json();
 
       if (!json?.access_token) {
@@ -94,11 +95,10 @@ export async function agentSendText(params) {
         text: { content: text },
       };
 
-  const res = await fetch(url, {
+  const res = await wecomFetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body),
-    signal: AbortSignal.timeout(AGENT_API_REQUEST_TIMEOUT_MS),
   });
   const json = await res.json();
 
@@ -156,14 +156,13 @@ export async function agentUploadMedia(params) {
   const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
   const body = Buffer.concat([header, buffer, footer]);
 
-  const res = await fetch(url, {
+  const res = await wecomFetch(url, {
     method: "POST",
     headers: {
       "Content-Type": `multipart/form-data; boundary=${boundary}`,
       "Content-Length": String(body.length),
     },
     body,
-    signal: AbortSignal.timeout(AGENT_API_REQUEST_TIMEOUT_MS),
   });
   const json = await res.json();
 
@@ -206,11 +205,10 @@ export async function agentSendMedia(params) {
         [mediaType]: mediaPayload,
       };
 
-  const res = await fetch(url, {
+  const res = await wecomFetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body),
-    signal: AbortSignal.timeout(AGENT_API_REQUEST_TIMEOUT_MS),
   });
   const json = await res.json();
 
@@ -232,7 +230,7 @@ export async function agentDownloadMedia(params) {
   const token = await getAccessToken(agent);
   const url = `${AGENT_API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
 
-  const res = await fetch(url, { signal: AbortSignal.timeout(AGENT_API_REQUEST_TIMEOUT_MS) });
+  const res = await wecomFetch(url);
 
   if (!res.ok) {
     throw new Error(`agent download media failed: ${res.status}`);

package/wecom/agent-inbound.js

@@ -16,11 +16,15 @@ import {
   getDynamicAgentConfig,
   shouldUseDynamicAgent,
 } from "../dynamic-agent.js";
-import { agentSendText, agentDownloadMedia } from "./agent-api.js";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { agentSendText, agentUploadMedia, agentSendMedia, agentDownloadMedia } from "./agent-api.js";
 import { resolveAccount } from "./accounts.js";
 import { resolveWecomCommandAuthorized } from "./allow-from.js";
 import { checkCommandAllowlist, getCommandConfig, isWecomAdmin } from "./commands.js";
 import { MAX_REQUEST_BODY_SIZE } from "./constants.js";
+import { resolveAgentMediaTypeFromFilename } from "./channel-plugin.js";
+import { wecomFetch } from "./http.js";
 import { getRuntime, resolveAgentConfig } from "./state.js";
 import { ensureDynamicAgentListed } from "./workspace-template.js";
 import {
@@ -384,6 +388,66 @@ async function processAgentMessage({
     dispatcherOptions: {
       deliver: async (payload, info) => {
         const text = payload.text ?? "";
+
+        // ── Handle media (images / files) ──────────────────────
+        const mediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
+        for (const rawUrl of mediaUrls) {
+          try {
+            let absolutePath = rawUrl;
+            if (absolutePath.startsWith("sandbox:")) {
+              absolutePath = absolutePath.replace(/^sandbox:\/{0,2}/, "");
+              if (!absolutePath.startsWith("/")) absolutePath = "/" + absolutePath;
+            }
+
+            let buffer;
+            let filename;
+
+            if (absolutePath.startsWith("/")) {
+              buffer = await readFile(absolutePath);
+              filename = basename(absolutePath);
+            } else {
+              // Remote URL: download first
+              const dlRes = await wecomFetch(rawUrl);
+              if (!dlRes.ok) {
+                logger.error("[agent-inbound] media download failed", { url: rawUrl, status: dlRes.status });
+                continue;
+              }
+              buffer = Buffer.from(await dlRes.arrayBuffer());
+              try {
+                filename = basename(new URL(rawUrl).pathname) || "file";
+              } catch {
+                filename = "file";
+              }
+            }
+
+            const uploadType = resolveAgentMediaTypeFromFilename(filename);
+            const mediaId = await agentUploadMedia({
+              agent: agentConfig,
+              type: uploadType,
+              buffer,
+              filename,
+            });
+            await agentSendMedia({
+              agent: agentConfig,
+              toUser: fromUser,
+              mediaId,
+              mediaType: uploadType,
+            });
+            logger.info("[agent-inbound] media delivered", {
+              kind: info.kind,
+              to: fromUser,
+              filename,
+              uploadType,
+            });
+          } catch (err) {
+            logger.error("[agent-inbound] media delivery failed", {
+              url: rawUrl,
+              error: err.message,
+            });
+          }
+        }
+
+        // ── Handle text ────────────────────────────────────────
         if (!text.trim()) return;
 
         try {

package/wecom/channel-plugin.js

@@ -8,10 +8,19 @@ import { listAccountIds, resolveAccount, detectAccountConflicts } from "./accoun
 import { DEFAULT_ACCOUNT_ID, THINKING_PLACEHOLDER } from "./constants.js";
 import { parseResponseUrlResult } from "./response-url.js";
 import { messageBuffers, resolveAgentConfig, resolveWebhookUrl, responseUrls, streamContext } from "./state.js";
-import { resolveActiveStream } from "./stream-utils.js";
+import { resolveRecoverableStream, unregisterActiveStream } from "./stream-utils.js";
 import { resolveWecomTarget } from "./target.js";
 import { webhookSendImage, webhookSendText, webhookUploadFile, webhookSendFile } from "./webhook-bot.js";
-import { registerWebhookTarget } from "./webhook-targets.js";
+import { normalizeWebhookPath, registerWebhookTarget } from "./webhook-targets.js";
+import { wecomFetch, setConfigProxyUrl } from "./http.js";
+import { createWecomRouteHandler } from "./http-handler.js";
+
+const AGENT_IMAGE_EXTS = new Set(["jpg", "jpeg", "png", "gif", "bmp"]);
+
+export function resolveAgentMediaTypeFromFilename(filename) {
+  const ext = filename.split(".").pop()?.toLowerCase() || "";
+  return AGENT_IMAGE_EXTS.has(ext) ? "image" : "file";
+}
 
 export const wecomChannelPlugin = {
   id: "wecom",
@@ -141,6 +150,17 @@ export const wecomChannelPlugin = {
             },
           },
         },
+        network: {
+          type: "object",
+          description: "Network configuration (proxy, timeouts)",
+          additionalProperties: false,
+          properties: {
+            egressProxyUrl: {
+              type: "string",
+              description: "HTTP(S) proxy URL for outbound WeCom API requests (e.g. http://proxy:8080). Env var WECOM_EGRESS_PROXY_URL takes precedence.",
+            },
+          },
+        },
         webhooks: {
           type: "object",
           description: "Webhook bot URLs for group notifications (key: name, value: webhook URL or key)",
@@ -259,7 +279,7 @@ export const wecomChannelPlugin = {
 
       // Prefer stream from async context (correct for concurrent processing).
       const ctx = streamContext.getStore();
-      const streamId = ctx?.streamId ?? resolveActiveStream(userId);
+      const streamId = ctx?.streamId ?? resolveRecoverableStream(userId);
 
       // Layer 1: Active stream (normal path)
       if (streamId && streamManager.hasStream(streamId) && !streamManager.getStream(streamId)?.finished) {
@@ -284,7 +304,7 @@ export const wecomChannelPlugin = {
       const saved = responseUrls.get(ctx?.streamKey ?? userId);
       if (saved && !saved.used && Date.now() < saved.expiresAt) {
         try {
-          const response = await fetch(saved.url, {
+          const response = await wecomFetch(saved.url, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ msgtype: "text", text: { content: text } }),
@@ -377,7 +397,7 @@ export const wecomChannelPlugin = {
 
       // Prefer stream from async context (correct for concurrent processing).
       const ctx = streamContext.getStore();
-      const streamId = ctx?.streamId ?? resolveActiveStream(userId);
+      const streamId = ctx?.streamId ?? resolveRecoverableStream(userId);
 
       if (streamId && streamManager.hasStream(streamId)) {
         // Check if mediaUrl is a local path (sandbox: prefix or absolute path)
@@ -528,7 +548,7 @@ export const wecomChannelPlugin = {
               buffer = await readFile(absolutePath);
               filename = basename(absolutePath);
             } else {
-              const res = await fetch(mediaUrl);
+              const res = await wecomFetch(mediaUrl);
               buffer = Buffer.from(await res.arrayBuffer());
               filename = basename(new URL(mediaUrl).pathname) || "image.png";
             }
@@ -575,6 +595,7 @@ export const wecomChannelPlugin = {
       if (agentConfig) {
         try {
           const agentTarget = (target && !target.webhook) ? target : resolveWecomTarget(to) || { toUser: userId };
+          let deliveredFilename = "file";
 
           // Determine if mediaUrl is a local file path.
           let absolutePath = mediaUrl;
@@ -587,9 +608,11 @@ export const wecomChannelPlugin = {
             // Upload local file then send via Agent API.
             const buffer = await readFile(absolutePath);
             const filename = basename(absolutePath);
+            deliveredFilename = filename;
+            const uploadType = resolveAgentMediaTypeFromFilename(filename);
             const mediaId = await agentUploadMedia({
               agent: agentConfig,
-              type: "image",
+              type: uploadType,
               buffer,
               filename,
             });
@@ -597,16 +620,25 @@ export const wecomChannelPlugin = {
               agent: agentConfig,
               ...agentTarget,
               mediaId,
-              mediaType: "image",
+              mediaType: uploadType,
             });
           } else {
             // For external URLs, download first then upload.
-            const res = await fetch(mediaUrl);
+            const res = await wecomFetch(mediaUrl);
+            if (!res.ok) {
+              throw new Error(`download media failed: ${res.status}`);
+            }
             const buffer = Buffer.from(await res.arrayBuffer());
-            const filename = basename(new URL(mediaUrl).pathname) || "image.png";
+            const filename = basename(new URL(mediaUrl).pathname) || "file";
+            deliveredFilename = filename;
+            let uploadType = resolveAgentMediaTypeFromFilename(filename);
+            const contentType = res.headers.get("content-type") || "";
+            if (uploadType === "file" && contentType.toLowerCase().startsWith("image/")) {
+              uploadType = "image";
+            }
             const mediaId = await agentUploadMedia({
               agent: agentConfig,
-              type: "image",
+              type: uploadType,
               buffer,
               filename,
             });
@@ -614,7 +646,7 @@ export const wecomChannelPlugin = {
               agent: agentConfig,
               ...agentTarget,
               mediaId,
-              mediaType: "image",
+              mediaType: uploadType,
             });
           }
 
@@ -623,6 +655,30 @@ export const wecomChannelPlugin = {
             await agentSendText({ agent: agentConfig, ...agentTarget, text });
           }
 
+          // Best-effort stream recovery: when async context is missing and the
+          // active stream mapping was already cleaned, still clear "thinking..."
+          // in the most recent stream for this user.
+          const recoverStreamId = resolveRecoverableStream(userId);
+          if (recoverStreamId && streamManager.hasStream(recoverStreamId)) {
+            const recoverStream = streamManager.getStream(recoverStreamId);
+            if (recoverStream && !recoverStream.finished) {
+              const deliveryHint = text
+                ? `${text}\n\n📎 文件已通过私信发送给您：${deliveredFilename}`
+                : `📎 文件已通过私信发送给您：${deliveredFilename}`;
+              streamManager.replaceIfPlaceholder(
+                recoverStreamId,
+                deliveryHint,
+                THINKING_PLACEHOLDER,
+              );
+              await streamManager.finishStream(recoverStreamId);
+              unregisterActiveStream(userId, recoverStreamId);
+              logger.info("WeCom: recovered and finished stream after media fallback", {
+                userId,
+                streamId: recoverStreamId,
+              });
+            }
+          }
+
           logger.info("WeCom: sent media via Agent API fallback (sendMedia)", {
             userId,
             to,
@@ -651,6 +707,10 @@ export const wecomChannelPlugin = {
         webhookPath: account.webhookPath,
       });
 
+      // Wire proxy URL from config (env var takes precedence inside http.js).
+      const wecomCfg = ctx.cfg?.channels?.wecom ?? {};
+      setConfigProxyUrl(wecomCfg.network?.egressProxyUrl ?? "");
+
       // Conflict detection: warn about duplicate tokens / agent IDs.
       const conflicts = detectAccountConflicts(ctx.cfg);
       for (const conflict of conflicts) {
@@ -666,13 +726,34 @@ export const wecomChannelPlugin = {
         config: ctx.cfg,
       });
 
+      // Register HTTP route with OpenClaw route framework.
+      // Uses registerPluginHttpRoute (new API in OpenClaw 2026.3.2+) for explicit
+      // path-based routing.  Falls back gracefully when the SDK is unavailable
+      // (older OpenClaw uses the legacy wildcard handler registered in index.js).
+      let unregisterBotRoute;
+      const botPath = account.webhookPath || "/webhooks/wecom";
+      try {
+        const { registerPluginHttpRoute } = await import("openclaw/plugin-sdk");
+        unregisterBotRoute = registerPluginHttpRoute({
+          path: botPath,
+          pluginId: "wecom",
+          accountId: account.accountId,
+          log: (msg) => logger.info(msg),
+          handler: createWecomRouteHandler(normalizeWebhookPath(botPath)),
+        });
+        logger.info("WeCom Bot HTTP route registered", { path: botPath });
+      } catch {
+        // openclaw/plugin-sdk not available — rely on legacy registerHttpHandler.
+        logger.debug("registerPluginHttpRoute unavailable, using legacy handler", { path: botPath });
+      }
+
       // Register Agent inbound webhook if agent inbound is fully configured.
       let unregisterAgent;
+      let unregisterAgentRoute;
       // Per-account agent path: /webhooks/app for default, /webhooks/app/{accountId} for others.
       const agentInboundPath = account.accountId === DEFAULT_ACCOUNT_ID
         ? "/webhooks/app"
         : `/webhooks/app/${account.accountId}`;
-      const botPath = account.webhookPath || "/webhooks/wecom";
       if (account.agentInboundConfigured) {
         if (botPath === agentInboundPath) {
           logger.error("WeCom: Agent inbound path conflicts with Bot webhook path, skipping Agent registration", {
@@ -697,6 +778,22 @@ export const wecomChannelPlugin = {
             config: ctx.cfg,
           });
           logger.info("WeCom Agent inbound webhook registered", { path: agentInboundPath });
+
+          // Register agent inbound HTTP route (new API).
+          try {
+            const { registerPluginHttpRoute } = await import("openclaw/plugin-sdk");
+            unregisterAgentRoute = registerPluginHttpRoute({
+              path: agentInboundPath,
+              pluginId: "wecom",
+              accountId: account.accountId,
+              source: "agent-inbound",
+              log: (msg) => logger.info(msg),
+              handler: createWecomRouteHandler(normalizeWebhookPath(agentInboundPath)),
+            });
+            logger.info("WeCom Agent inbound HTTP route registered", { path: agentInboundPath });
+          } catch {
+            logger.debug("registerPluginHttpRoute unavailable for agent inbound, using legacy handler");
+          }
         }
       }
 
@@ -708,7 +805,9 @@ export const wecomChannelPlugin = {
         }
         messageBuffers.clear();
         unregister();
+        if (unregisterBotRoute) unregisterBotRoute();
         if (unregisterAgent) unregisterAgent();
+        if (unregisterAgentRoute) unregisterAgentRoute();
       };
 
       // Backward compatibility: older runtime may not pass abortSignal.

package/wecom/http-handler.js

@@ -14,6 +14,33 @@ import {
 } from "./stream-utils.js";
 import { normalizeWebhookPath } from "./webhook-targets.js";
 
+/**
+ * Create a per-route HTTP handler for the new `registerPluginHttpRoute` API.
+ *
+ * The route framework already matches by path, so this handler resolves
+ * targets at call time from the pre-registered in-memory map.
+ *
+ * @param {string} routePath - Normalized webhook path (e.g. "/webhooks/wecom")
+ * @returns {(req: IncomingMessage, res: ServerResponse) => Promise<void>}
+ */
+export function createWecomRouteHandler(routePath) {
+  return async (req, res) => {
+    const targets = webhookTargets.get(routePath);
+    if (!targets || targets.length === 0) {
+      res.writeHead(503, { "Content-Type": "text/plain" });
+      res.end("No webhook target configured");
+      return;
+    }
+    const url = new URL(req.url || "", "http://localhost");
+    const query = Object.fromEntries(url.searchParams);
+    await handleWecomRequest(req, res, targets, query, routePath);
+  };
+}
+
+/**
+ * Legacy wildcard HTTP handler for older OpenClaw versions that still support
+ * `api.registerHttpHandler()`.  Returns `false` when the path is not handled.
+ */
 export async function wecomHttpHandler(req, res) {
   const url = new URL(req.url || "", "http://localhost");
   const path = normalizeWebhookPath(url.pathname);
@@ -24,17 +51,27 @@ export async function wecomHttpHandler(req, res) {
   }
 
   const query = Object.fromEntries(url.searchParams);
+  await handleWecomRequest(req, res, targets, query, path);
+  return true;
+}
+
+/**
+ * Shared request handling logic used by both the legacy wildcard handler and
+ * the new per-route handler.
+ */
+async function handleWecomRequest(req, res, targets, query, path) {
   logger.debug("WeCom HTTP request", { method: req.method, path });
 
   // ── Agent inbound: route to dedicated handler when target has agentInbound config ──
   const agentTarget = targets.find((t) => t.account?.agentInbound);
   if (agentTarget) {
-    return handleAgentInbound({
+    await handleAgentInbound({
       req,
       res,
       agentAccount: agentTarget.account.agentInbound,
       config: agentTarget.config,
     });
+    return;
   }
 
   // ── Bot mode: JSON-based stream handling ──
@@ -45,7 +82,7 @@ export async function wecomHttpHandler(req, res) {
     if (!target) {
       res.writeHead(503, { "Content-Type": "text/plain" });
       res.end("No webhook target configured");
-      return true;
+      return;
     }
 
     const webhook = new WecomWebhook({
@@ -58,13 +95,13 @@ export async function wecomHttpHandler(req, res) {
       res.writeHead(200, { "Content-Type": "text/plain" });
       res.end(echo);
       logger.info("WeCom URL verification successful");
-      return true;
+      return;
     }
 
     res.writeHead(403, { "Content-Type": "text/plain" });
     res.end("Verification failed");
     logger.warn("WeCom URL verification failed");
-    return true;
+    return;
   }
 
   // POST: Message handling
@@ -73,7 +110,7 @@ export async function wecomHttpHandler(req, res) {
     if (!target) {
       res.writeHead(503, { "Content-Type": "text/plain" });
       res.end("No webhook target configured");
-      return true;
+      return;
     }
 
     // Read request body
@@ -94,12 +131,12 @@ export async function wecomHttpHandler(req, res) {
       // Duplicate message — ACK 200 to prevent platform retry storm.
       res.writeHead(200, { "Content-Type": "text/plain" });
       res.end("success");
-      return true;
+      return;
     }
     if (!result) {
       res.writeHead(400, { "Content-Type": "text/plain" });
       res.end("Bad Request");
-      return true;
+      return;
     }
 
     // Handle text message
@@ -156,7 +193,7 @@ export async function wecomHttpHandler(req, res) {
           logger.error("WeCom message processing failed", { error: err.message });
           await handleStreamError(streamId, streamKey, "处理消息时出错，请稍后再试。");
         });
-        return true;
+        return;
       }
 
       // Debounce: buffer non-command messages per user/group.
@@ -187,7 +224,7 @@ export async function wecomHttpHandler(req, res) {
         logger.info("WeCom: message buffered (first)", { streamKey, streamId });
       }
 
-      return true;
+      return;
     }
 
     // Handle stream refresh - return current stream state
@@ -210,7 +247,7 @@ export async function wecomHttpHandler(req, res) {
         );
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(streamResponse);
-        return true;
+        return;
       }
 
       // Check if stream should be closed (main response done + idle timeout).
@@ -257,7 +294,7 @@ export async function wecomHttpHandler(req, res) {
         }, 30 * 1000);
       }
 
-      return true;
+      return;
     }
 
     // Handle event
@@ -296,20 +333,19 @@ export async function wecomHttpHandler(req, res) {
         logger.info("Sending welcome message", { fromUser, streamId });
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(streamResponse);
-        return true;
+        return;
       }
 
       res.writeHead(200, { "Content-Type": "text/plain" });
       res.end("success");
-      return true;
+      return;
     }
 
     res.writeHead(200, { "Content-Type": "text/plain" });
     res.end("success");
-    return true;
+    return;
   }
 
   res.writeHead(405, { "Content-Type": "text/plain" });
   res.end("Method Not Allowed");
-  return true;
 }

package/wecom/http.js

@@ -0,0 +1,129 @@
+/**
+ * Unified HTTP client for WeCom API calls.
+ *
+ * Wraps `undici` fetch with optional proxy support (ProxyAgent) and
+ * AbortSignal timeout merging.  All outbound requests to qyapi.weixin.qq.com
+ * should go through `wecomFetch()` so that proxy / timeout behaviour is
+ * consistent across the plugin.
+ *
+ * Proxy URL resolution order:
+ *   1. Explicit `opts.proxyUrl` parameter
+ *   2. Environment variable `WECOM_EGRESS_PROXY_URL`
+ *   3. Config: `channels.wecom.network.egressProxyUrl`
+ */
+
+import { AGENT_API_REQUEST_TIMEOUT_MS } from "./constants.js";
+
+// ── Lazy-loaded undici (optional dependency) ──────────────────────────
+
+let _undici = null;
+
+async function getUndici() {
+  if (_undici) return _undici;
+  try {
+    _undici = await import("undici");
+  } catch {
+    _undici = null;
+  }
+  return _undici;
+}
+
+// ── ProxyAgent cache ──────────────────────────────────────────────────
+
+const proxyDispatchers = new Map();
+
+async function getProxyDispatcher(proxyUrl) {
+  const existing = proxyDispatchers.get(proxyUrl);
+  if (existing) return existing;
+
+  const undici = await getUndici();
+  if (!undici?.ProxyAgent) {
+    throw new Error(
+      "undici is required for proxy support. Install it with: npm install undici",
+    );
+  }
+
+  const created = new undici.ProxyAgent(proxyUrl);
+  proxyDispatchers.set(proxyUrl, created);
+  return created;
+}
+
+// ── Signal merge helper ───────────────────────────────────────────────
+
+function mergeAbortSignal({ signal, timeoutMs }) {
+  const signals = [];
+  if (signal) signals.push(signal);
+  if (timeoutMs && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+    signals.push(AbortSignal.timeout(timeoutMs));
+  }
+  if (!signals.length) return undefined;
+  if (signals.length === 1) return signals[0];
+  return AbortSignal.any(signals);
+}
+
+// ── Proxy URL resolution ──────────────────────────────────────────────
+
+let _configProxyUrl = "";
+
+/**
+ * Set the proxy URL from plugin config (called once during plugin load).
+ * @param {string} url
+ */
+export function setConfigProxyUrl(url) {
+  _configProxyUrl = (url || "").trim();
+}
+
+/**
+ * Resolve the effective proxy URL.
+ * Priority: explicit > env > config.
+ * @param {string} [explicit]
+ * @returns {string}
+ */
+function resolveProxyUrl(explicit) {
+  if (explicit?.trim()) return explicit.trim();
+  const env = (
+    process.env.WECOM_EGRESS_PROXY_URL || ""
+  ).trim();
+  if (env) return env;
+  return _configProxyUrl;
+}
+
+// ── Public API ────────────────────────────────────────────────────────
+
+/**
+ * Fetch wrapper with proxy and timeout support.
+ *
+ * @param {string | URL} input
+ * @param {RequestInit} [init]
+ * @param {{ proxyUrl?: string, timeoutMs?: number, signal?: AbortSignal }} [opts]
+ * @returns {Promise<Response>}
+ */
+export async function wecomFetch(input, init, opts) {
+  const proxyUrl = resolveProxyUrl(opts?.proxyUrl);
+  const timeoutMs = opts?.timeoutMs ?? AGENT_API_REQUEST_TIMEOUT_MS;
+
+  const signal = mergeAbortSignal({
+    signal: opts?.signal ?? init?.signal,
+    timeoutMs,
+  });
+
+  if (proxyUrl) {
+    // Use undici fetch with ProxyAgent dispatcher
+    const undici = await getUndici();
+    if (undici?.fetch && undici?.ProxyAgent) {
+      const dispatcher = await getProxyDispatcher(proxyUrl);
+      return undici.fetch(input, {
+        ...(init ?? {}),
+        ...(signal ? { signal } : {}),
+        dispatcher,
+      });
+    }
+    // undici not available — fall through to native fetch (no proxy)
+  }
+
+  // Native fetch (no proxy)
+  return fetch(input, {
+    ...(init ?? {}),
+    ...(signal ? { signal } : {}),
+  });
+}

package/wecom/media.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { WecomCrypto } from "../crypto.js";
 import { logger } from "../logger.js";
 import { MEDIA_CACHE_DIR } from "./constants.js";
+import { wecomFetch } from "./http.js";
 
 // ── Magic-byte signatures for common file formats ───────────────────────────
 const MAGIC_SIGNATURES = [
@@ -87,7 +88,7 @@ export async function downloadAndDecryptImage(imageUrl, encodingAesKey, token) {
   }
 
   logger.info("Downloading image", { url: imageUrl.substring(0, 80) });
-  const response = await fetch(imageUrl);
+  const response = await wecomFetch(imageUrl);
   if (!response.ok) {
     throw new Error(`Failed to download image: ${response.status}`);
   }
@@ -127,7 +128,7 @@ export async function downloadWecomFile(fileUrl, fileName, encodingAesKey, token
   }
 
   logger.info("Downloading file", { url: fileUrl.substring(0, 80), name: fileName });
-  const response = await fetch(fileUrl);
+  const response = await wecomFetch(fileUrl);
   if (!response.ok) {
     throw new Error(`Failed to download file: ${response.status}`);
   }

package/wecom/outbound-delivery.js

@@ -8,6 +8,7 @@ import { resolveAgentConfig, responseUrls, streamContext } from "./state.js";
 import { resolveActiveStream } from "./stream-utils.js";
 import { resolveAgentWorkspaceDirLocal } from "./workspace-template.js";
 import { THINKING_PLACEHOLDER } from "./constants.js";
+import { wecomFetch } from "./http.js";
 
 // WeCom upload API rejects files smaller than 5 bytes (error 40006).
 const WECOM_MIN_FILE_SIZE = 5;
@@ -196,7 +197,7 @@ export async function deliverWecomReply({ payload, senderId, streamId, agentId }
             if (isLocal) {
               fileBuf = await readFile(absPath);
             } else {
-              const res = await fetch(mediaPath, { signal: AbortSignal.timeout(30_000) });
+              const res = await wecomFetch(mediaPath);
               if (!res.ok) throw new Error(`download failed: ${res.status}`);
               fileBuf = Buffer.from(await res.arrayBuffer());
             }
@@ -420,7 +421,7 @@ export async function deliverWecomReply({ payload, senderId, streamId, agentId }
     const saved = responseUrls.get(senderId);
     if (saved && !saved.used && Date.now() < saved.expiresAt) {
       try {
-        const response = await fetch(saved.url, {
+        const response = await wecomFetch(saved.url, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ msgtype: "text", text: { content: processedText } }),

package/wecom/state.js

@@ -14,6 +14,7 @@ export const messageBuffers = new Map();
 export const webhookTargets = new Map();
 export const activeStreams = new Map();
 export const activeStreamHistory = new Map();
+export const lastStreamByKey = new Map();
 export const streamMeta = new Map();
 export const responseUrls = new Map();
 export const streamContext = new AsyncLocalStorage();

package/wecom/stream-utils.js

@@ -1,7 +1,7 @@
 import { logger } from "../logger.js";
 import { streamManager } from "../stream-manager.js";
 import { THINKING_PLACEHOLDER } from "./constants.js";
-import { activeStreamHistory, activeStreams, messageBuffers } from "./state.js";
+import { activeStreamHistory, activeStreams, lastStreamByKey, messageBuffers } from "./state.js";
 
 export function getMessageStreamKey(message) {
   if (!message || typeof message !== "object") {
@@ -25,6 +25,7 @@ export function registerActiveStream(streamKey, streamId) {
   deduped.push(streamId);
   activeStreamHistory.set(streamKey, deduped);
   activeStreams.set(streamKey, streamId);
+  lastStreamByKey.set(streamKey, streamId);
 }
 
 export function unregisterActiveStream(streamKey, streamId) {
@@ -72,9 +73,33 @@ export function resolveActiveStream(streamKey) {
   activeStreamHistory.set(streamKey, remaining);
   const latest = remaining[remaining.length - 1];
   activeStreams.set(streamKey, latest);
+  lastStreamByKey.set(streamKey, latest);
   return latest;
 }
 
+/**
+ * Resolve a usable stream id for a sender/group.
+ * Prefer active history; if that is temporarily empty, fall back to the latest
+ * known stream id for the same key (when it still exists).
+ */
+export function resolveRecoverableStream(streamKey) {
+  const activeId = resolveActiveStream(streamKey);
+  if (activeId) {
+    return activeId;
+  }
+  if (!streamKey) {
+    return null;
+  }
+  const recentId = lastStreamByKey.get(streamKey);
+  if (!recentId) {
+    return null;
+  }
+  if (!streamManager.hasStream(recentId)) {
+    return null;
+  }
+  return recentId;
+}
+
 export function clearBufferedMessagesForStream(streamKey, reason) {
   const buffer = messageBuffers.get(streamKey);
   if (!buffer) {

package/wecom/webhook-bot.js

@@ -10,6 +10,7 @@
 import crypto from "node:crypto";
 import { logger } from "../logger.js";
 import { AGENT_API_REQUEST_TIMEOUT_MS } from "./constants.js";
+import { wecomFetch } from "./http.js";
 
 /**
  * Send a text message via Webhook Bot.
@@ -86,14 +87,13 @@ export async function webhookUploadFile({ url, buffer, filename }) {
   const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
   const multipartBody = Buffer.concat([header, buffer, footer]);
 
-  const res = await fetch(uploadUrl, {
+  const res = await wecomFetch(uploadUrl, {
     method: "POST",
     headers: {
       "Content-Type": `multipart/form-data; boundary=${boundary}`,
       "Content-Length": String(multipartBody.length),
     },
     body: multipartBody,
-    signal: AbortSignal.timeout(AGENT_API_REQUEST_TIMEOUT_MS),
   });
   const json = await res.json();
 
@@ -140,11 +140,10 @@ function extractKey(url) {
 async function postWebhook(url, body) {
   logger.debug("Webhook bot POST", { url: url.substring(0, 60), msgtype: body.msgtype });
 
-  const res = await fetch(url, {
+  const res = await wecomFetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body),
-    signal: AbortSignal.timeout(AGENT_API_REQUEST_TIMEOUT_MS),
   });
   const json = await res.json();
 

package/wecom/workspace-template.js

@@ -103,7 +103,7 @@ export function upsertAgentIdOnlyEntry(cfg, agentId) {
   }
 
   if (!existingIds.has(normalizedId)) {
-    nextList.push({ id: normalizedId });
+    nextList.push({ id: normalizedId, heartbeat: {} });
     changed = true;
   }