@yanhaidao/wecom 2.2.3 → 2.2.4

package/src/monitor.ts

@@ -1,4 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { pathToFileURL } from "node:url";
+
 import crypto from "node:crypto";
 
 import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
@@ -8,73 +10,62 @@ import type { ResolvedBotAccount } from "./types/index.js";
 import type { WecomInboundMessage, WecomInboundQuote } from "./types.js";
 import { decryptWecomEncrypted, encryptWecomPlaintext, verifyWecomSignature, computeWecomMsgSignature } from "./crypto.js";
 import { getWecomRuntime } from "./runtime.js";
-import { decryptWecomMedia } from "./media.js";
+import { decryptWecomMedia, decryptWecomMediaWithHttp } from "./media.js";
 import { WEBHOOK_PATHS } from "./types/constants.js";
 import { handleAgentWebhook } from "./agent/index.js";
+import { resolveWecomAccounts, resolveWecomEgressProxyUrl } from "./config/index.js";
+import { wecomFetch } from "./http.js";
+import { sendText as sendAgentText, sendMedia as sendAgentMedia, uploadMedia } from "./agent/api-client.js";
 import axios from "axios";
 
-export type WecomRuntimeEnv = {
-  log?: (message: string) => void;
-  error?: (message: string) => void;
-};
+/**
+ * **核心监控模块 (Monitor Loop)**
+ * 
+ * 负责接收企业微信 Webhook 回调，处理消息流、媒体解密、消息去重防抖，并分发给 Agent 处理。
+ * 它是插件与企业微信交互的“心脏”，管理着所有会话的生命周期。
+ */
 
-type WecomWebhookTarget = {
-  account: ResolvedBotAccount;
-  config: OpenClawConfig;
-  runtime: WecomRuntimeEnv;
-  core: PluginRuntime;
-  path: string;
-  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
-};
+import type { WecomRuntimeEnv, WecomWebhookTarget, StreamState, PendingInbound, ActiveReplyState } from "./monitor/types.js";
+import { monitorState, LIMITS } from "./monitor/state.js";
 
-type StreamState = {
-  streamId: string;
-  msgid?: string;
-  createdAt: number;
-  updatedAt: number;
-  started: boolean;
-  finished: boolean;
-  error?: string;
-  content: string;
-  images?: { base64: string; md5: string }[];
-};
+// Global State
+monitorState.streamStore.setFlushHandler((pending) => void flushPending(pending));
+
+// Stores (convenience aliases)
+const streamStore = monitorState.streamStore;
+const activeReplyStore = monitorState.activeReplyStore;
 
+// Target Registry
 const webhookTargets = new Map<string, WecomWebhookTarget[]>();
-const streams = new Map<string, StreamState>();
-const msgidToStreamId = new Map<string, string>();
-const activeReplies = new Map<string, { response_url: string; createdAt: number; usedAt?: number; lastError?: string }>();
 
 // Agent 模式 target 存储
 type AgentWebhookTarget = {
   agent: ResolvedAgentAccount;
   config: OpenClawConfig;
   runtime: WecomRuntimeEnv;
+  // ...
 };
 const agentTargets = new Map<string, AgentWebhookTarget>();
 
-// Pending inbound messages for debouncing rapid consecutive messages
-type PendingInbound = {
-  streamId: string;
-  target: WecomWebhookTarget;
-  msg: WecomInboundMessage;
-  contents: string[];
-  media?: { buffer: Buffer; contentType: string; filename: string };
-  msgids: string[];
-  nonce: string;
-  timestamp: string;
-  timeout: ReturnType<typeof setTimeout> | null;
-  createdAt: number;
-};
 const pendingInbounds = new Map<string, PendingInbound>();
 
-const STREAM_TTL_MS = 10 * 60 * 1000;
-const ACTIVE_REPLY_TTL_MS = 60 * 60 * 1000;
-const STREAM_MAX_BYTES = 20_480;
-const DEFAULT_DEBOUNCE_MS = 500;
+const STREAM_MAX_BYTES = LIMITS.STREAM_MAX_BYTES;
+const STREAM_MAX_DM_BYTES = 200_000;
+const BOT_WINDOW_MS = 6 * 60 * 1000;
+const BOT_SWITCH_MARGIN_MS = 30 * 1000;
+// REQUEST_TIMEOUT_MS is available in LIMITS but defined locally in other functions, we can leave it or use LIMITS.REQUEST_TIMEOUT_MS
+// Keeping local variables for now if they are used, or we can replace usages.
+// The constants STREAM_TTL_MS and ACTIVE_REPLY_TTL_MS are internalized in state.ts, so we can remove them here.
 
 /** 错误提示信息 */
 const ERROR_HELP = "\n\n遇到问题？联系作者: YanHaidao (微信: YanHaidao)";
 
+/**
+ * **normalizeWebhookPath (标准化 Webhook 路径)**
+ * 
+ * 将用户配置的路径统一格式化为以 `/` 开头且不以 `/` 结尾的字符串。
+ * 例如: `wecom` -> `/wecom`
+ */
 function normalizeWebhookPath(raw: string): string {
   const trimmed = raw.trim();
   if (!trimmed) return "/";
@@ -83,25 +74,33 @@ function normalizeWebhookPath(raw: string): string {
   return withSlash;
 }
 
-function pruneStreams(): void {
-  const cutoff = Date.now() - STREAM_TTL_MS;
-  for (const [id, state] of streams.entries()) {
-    if (state.updatedAt < cutoff) {
-      streams.delete(id);
-    }
-  }
-  for (const [msgid, id] of msgidToStreamId.entries()) {
-    if (!streams.has(id)) {
-      msgidToStreamId.delete(msgid);
-    }
-  }
 
-  const activeCutoff = Date.now() - ACTIVE_REPLY_TTL_MS;
-  for (const [streamId, state] of activeReplies.entries()) {
-    if (state.createdAt < activeCutoff) activeReplies.delete(streamId);
+/**
+ * **ensurePruneTimer (启动清理定时器)**
+ * 
+ * 当有活跃的 Webhook Target 注册时，调用 MonitorState 启动自动清理任务。
+ * 清理任务包括：删除过期 Stream、移除无效 Active Reply URL 等。
+ */
+function ensurePruneTimer() {
+  monitorState.startPruning();
+}
+
+/**
+ * **checkPruneTimer (检查并停止清理定时器)**
+ * 
+ * 当没有活跃的 Webhook Target 时（Bot 和 Agent 均移除），停止清理任务以节省资源。
+ */
+function checkPruneTimer() {
+  const hasBot = webhookTargets.size > 0;
+  const hasAgent = agentTargets.size > 0;
+  if (!hasBot && !hasAgent) {
+    monitorState.stopPruning();
   }
 }
 
+
+
+
 function truncateUtf8Bytes(text: string, maxBytes: number): string {
   const buf = Buffer.from(text, "utf8");
   if (buf.length <= maxBytes) return text;
@@ -109,6 +108,13 @@ function truncateUtf8Bytes(text: string, maxBytes: number): string {
   return slice.toString("utf8");
 }
 
+/**
+ * **jsonOk (返回 JSON 响应)**
+ * 
+ * 辅助函数：向企业微信服务器返回 HTTP 200 及 JSON 内容。
+ * 注意企业微信要求加密内容以 Content-Type: text/plain 返回，但这里为了通用性使用了标准 JSON 响应，
+ * 并通过 Content-Type 修正适配。
+ */
 function jsonOk(res: ServerResponse, body: unknown): void {
   res.statusCode = 200;
   // WeCom's reference implementation returns the encrypted JSON as text/plain.
@@ -116,6 +122,14 @@ function jsonOk(res: ServerResponse, body: unknown): void {
   res.end(JSON.stringify(body));
 }
 
+/**
+ * **readJsonBody (读取 JSON 请求体)**
+ * 
+ * 异步读取 HTTP 请求体并解析为 JSON。包含大小限制检查，防止大包攻击。
+ * 
+ * @param req HTTP 请求对象
+ * @param maxBytes 最大允许字节数
+ */
 async function readJsonBody(req: IncomingMessage, maxBytes: number) {
   const chunks: Buffer[] = [];
   let total = 0;
@@ -147,8 +161,14 @@ async function readJsonBody(req: IncomingMessage, maxBytes: number) {
   });
 }
 
+/**
+ * **buildEncryptedJsonReply (构建加密回复)**
+ * 
+ * 将明文 JSON 包装成企业微信要求的加密 XML/JSON 格式（此处实际返回 JSON 结构）。
+ * 包含签名计算逻辑。
+ */
 function buildEncryptedJsonReply(params: {
-  account: ResolvedWecomAccount;
+  account: ResolvedBotAccount;
   plaintextJson: unknown;
   nonce: string;
   timestamp: string;
@@ -210,6 +230,8 @@ function buildStreamPlaceholderReply(params: {
 
 function buildStreamReplyFromState(state: StreamState): { msgtype: "stream"; stream: { id: string; finish: boolean; content: string } } {
   const content = truncateUtf8Bytes(state.content, STREAM_MAX_BYTES);
+  // Images handled? The original code had image logic.
+  // Ensure we return message item if images exist
   return {
     msgtype: "stream",
     stream: {
@@ -226,33 +248,207 @@ function buildStreamReplyFromState(state: StreamState): { msgtype: "stream"; str
   };
 }
 
-function createStreamId(): string {
-  return crypto.randomBytes(16).toString("hex");
+function appendDmContent(state: StreamState, text: string): void {
+  const next = state.dmContent ? `${state.dmContent}\n\n${text}`.trim() : text.trim();
+  state.dmContent = truncateUtf8Bytes(next, STREAM_MAX_DM_BYTES);
 }
 
-function storeActiveReply(streamId: string, responseUrl?: string): void {
-  const url = responseUrl?.trim();
-  if (!url) return;
-  activeReplies.set(streamId, { response_url: url, createdAt: Date.now() });
+function computeTaskKey(target: WecomWebhookTarget, msg: WecomInboundMessage): string | undefined {
+  const msgid = msg.msgid ? String(msg.msgid) : "";
+  if (!msgid) return undefined;
+  const aibotid = String((msg as any).aibotid ?? "unknown").trim() || "unknown";
+  return `bot:${target.account.accountId}:${aibotid}:${msgid}`;
 }
 
-function getActiveReplyUrl(streamId: string): string | undefined {
-  return activeReplies.get(streamId)?.response_url;
+function resolveAgentAccountOrUndefined(cfg: OpenClawConfig): ResolvedAgentAccount | undefined {
+  const agent = resolveWecomAccounts(cfg).agent;
+  return agent?.configured ? agent : undefined;
 }
 
-async function useActiveReplyOnce(streamId: string, send: (responseUrl: string) => Promise<void>): Promise<void> {
-  const state = activeReplies.get(streamId);
-  if (!state?.response_url) throw new Error(`No response_url for stream ${streamId}`);
-  if (state.usedAt) throw new Error(`response_url already used for stream ${streamId}`);
-  try {
-    await send(state.response_url);
-    state.usedAt = Date.now();
-  } catch (err) {
-    state.lastError = err instanceof Error ? err.message : String(err);
-    throw err;
+function buildFallbackPrompt(params: {
+  kind: "media" | "timeout" | "error";
+  agentConfigured: boolean;
+  userId?: string;
+  filename?: string;
+  chatType?: "group" | "direct";
+}): string {
+  const who = params.userId ? `（${params.userId}）` : "";
+  const scope = params.chatType === "group" ? "群聊" : params.chatType === "direct" ? "私聊" : "会话";
+  if (!params.agentConfigured) {
+    return `${scope}中需要通过应用私信发送${params.filename ? `（${params.filename}）` : ""}，但管理员尚未配置企业微信自建应用（Agent）通道。请联系管理员配置后再试。${who}`.trim();
+  }
+  if (params.kind === "media") {
+    return `已生成文件${params.filename ? `（${params.filename}）` : ""}，将通过应用私信发送给你。${who}`.trim();
+  }
+  if (params.kind === "timeout") {
+    return `内容较长，为避免超时，后续内容将通过应用私信发送给你。${who}`.trim();
+  }
+  return `交付出现异常，已尝试通过应用私信发送给你。${who}`.trim();
+}
+
+async function sendBotFallbackPromptNow(params: { streamId: string; text: string }): Promise<void> {
+  const responseUrl = getActiveReplyUrl(params.streamId);
+  if (!responseUrl) {
+    throw new Error("no response_url（无法主动推送群内提示）");
+  }
+  await useActiveReplyOnce(params.streamId, async ({ responseUrl, proxyUrl }) => {
+    const payload = {
+      msgtype: "stream",
+      stream: {
+        id: params.streamId,
+        finish: true,
+        content: truncateUtf8Bytes(params.text, STREAM_MAX_BYTES) || "1",
+      },
+    };
+    const res = await wecomFetch(
+      responseUrl,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      },
+      { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+    );
+    if (!res.ok) {
+      throw new Error(`fallback prompt push failed: ${res.status}`);
+    }
+  });
+}
+
+async function sendAgentDmText(params: {
+  agent: ResolvedAgentAccount;
+  userId: string;
+  text: string;
+  core: PluginRuntime;
+}): Promise<void> {
+  const chunks = params.core.channel.text.chunkText(params.text, 20480);
+  for (const chunk of chunks) {
+    const trimmed = chunk.trim();
+    if (!trimmed) continue;
+    await sendAgentText({ agent: params.agent, toUser: params.userId, text: trimmed });
+  }
+}
+
+async function sendAgentDmMedia(params: {
+  agent: ResolvedAgentAccount;
+  userId: string;
+  mediaUrlOrPath: string;
+  contentType?: string;
+  filename: string;
+}): Promise<void> {
+  let buffer: Buffer;
+  let inferredContentType = params.contentType;
+
+  const looksLikeUrl = /^https?:\/\//i.test(params.mediaUrlOrPath);
+  if (looksLikeUrl) {
+    const res = await fetch(params.mediaUrlOrPath, { signal: AbortSignal.timeout(30_000) });
+    if (!res.ok) throw new Error(`media download failed: ${res.status}`);
+    buffer = Buffer.from(await res.arrayBuffer());
+    inferredContentType = inferredContentType || res.headers.get("content-type") || "application/octet-stream";
+  } else {
+    const fs = await import("node:fs/promises");
+    buffer = await fs.readFile(params.mediaUrlOrPath);
   }
+
+  let mediaType: "image" | "voice" | "video" | "file" = "file";
+  const ct = (inferredContentType || "").toLowerCase();
+  if (ct.startsWith("image/")) mediaType = "image";
+  else if (ct.startsWith("audio/")) mediaType = "voice";
+  else if (ct.startsWith("video/")) mediaType = "video";
+
+  const mediaId = await uploadMedia({
+    agent: params.agent,
+    type: mediaType,
+    buffer,
+    filename: params.filename,
+  });
+  await sendAgentMedia({
+    agent: params.agent,
+    toUser: params.userId,
+    mediaId,
+    mediaType,
+  });
 }
 
+function extractLocalImagePathsFromText(params: {
+  text: string;
+  mustAlsoAppearIn: string;
+}): string[] {
+  const text = params.text;
+  const mustAlsoAppearIn = params.mustAlsoAppearIn;
+  if (!text.trim()) return [];
+
+  // Conservative: only accept common macOS absolute paths for images.
+  // Also require that the exact path appeared in the user's original message to prevent exfil.
+  const exts = "(png|jpg|jpeg|gif|webp|bmp)";
+  const re = new RegExp(String.raw`(\/(?:Users|tmp)\/[^\s"'<>]+?\.${exts})`, "gi");
+  const found = new Set<string>();
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text))) {
+    const p = m[1];
+    if (!p) continue;
+    if (!mustAlsoAppearIn.includes(p)) continue;
+    found.add(p);
+  }
+  return Array.from(found);
+}
+
+function extractLocalFilePathsFromText(text: string): string[] {
+  if (!text.trim()) return [];
+
+  // Conservative: only accept common macOS absolute paths.
+  // This is primarily for “send local file” style requests (operator/debug usage).
+  const re = new RegExp(String.raw`(\/(?:Users|tmp)\/[^\s"'<>]+)`, "g");
+  const found = new Set<string>();
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text))) {
+    const p = m[1];
+    if (!p) continue;
+    found.add(p);
+  }
+  return Array.from(found);
+}
+
+function guessContentTypeFromPath(filePath: string): string | undefined {
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  if (!ext) return undefined;
+  const map: Record<string, string> = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    bmp: "image/bmp",
+    pdf: "application/pdf",
+    txt: "text/plain",
+    md: "text/markdown",
+    json: "application/json",
+    zip: "application/zip",
+  };
+  return map[ext];
+}
+
+function looksLikeSendLocalFileIntent(rawBody: string): boolean {
+  const t = rawBody.trim();
+  if (!t) return false;
+  // Heuristic: treat as “send file” intent only when there is an explicit local path AND a send-ish verb.
+  // This avoids accidentally sending a file when the user is merely referencing a path.
+  return /(发送|发给|发到|转发|把.*发|把.*发送|帮我发|给我发)/.test(t);
+}
+
+function storeActiveReply(streamId: string, responseUrl?: string, proxyUrl?: string): void {
+  activeReplyStore.store(streamId, responseUrl, proxyUrl);
+}
+
+function getActiveReplyUrl(streamId: string): string | undefined {
+  return activeReplyStore.getUrl(streamId);
+}
+
+async function useActiveReplyOnce(streamId: string, fn: (params: { responseUrl: string; proxyUrl?: string }) => Promise<void>): Promise<void> {
+  return activeReplyStore.use(streamId, fn);
+}
+
+
 function normalizeWecomAllowFromEntry(raw: string): string {
   return raw
     .trim()
@@ -284,6 +480,17 @@ function logVerbose(target: WecomWebhookTarget, message: string): void {
   target.runtime.log?.(`[wecom] ${message}`);
 }
 
+function logInfo(target: WecomWebhookTarget, message: string): void {
+  target.runtime.log?.(`[wecom] ${message}`);
+}
+
+function resolveWecomSenderUserId(msg: WecomInboundMessage): string | undefined {
+  const direct = msg.from?.userid?.trim();
+  if (direct) return direct;
+  const legacy = String((msg as any).fromuserid ?? (msg as any).from_userid ?? (msg as any).fromUserId ?? "").trim();
+  return legacy || undefined;
+}
+
 function parseWecomPlainMessage(raw: string): WecomInboundMessage {
   const parsed = JSON.parse(raw) as unknown;
   if (!parsed || typeof parsed !== "object") {
@@ -301,17 +508,31 @@ type InboundResult = {
   };
 };
 
+/**
+ * **processInboundMessage (处理接收消息)**
+ * 
+ * 解析企业微信传入的消息体。
+ * 主要职责：
+ * 1. 识别媒体消息（Image/File/Mixed）。
+ * 2. 如果存在媒体文件，调用 `media.ts` 进行解密和下载。
+ * 3. 构造统一的 `InboundResult` 供后续 Agent 处理。
+ * 
+ * @param target Webhook 目标配置
+ * @param msg 企业微信原始消息对象
+ */
 async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInboundMessage): Promise<InboundResult> {
   const msgtype = String(msg.msgtype ?? "").toLowerCase();
   const aesKey = target.account.encodingAESKey;
-  const mediaMaxMb = target.config.mediaMaxMb ?? 5; // Default 5MB
+  const mediaMaxMb = 5; // Default 5MB
   const maxBytes = mediaMaxMb * 1024 * 1024;
+  const proxyUrl = resolveWecomEgressProxyUrl(target.config);
 
+  // 图片消息处理：如果存在 url 且配置了 aesKey，则尝试解密下载
   if (msgtype === "image") {
     const url = String((msg as any).image?.url ?? "").trim();
     if (url && aesKey) {
       try {
-        const buf = await decryptWecomMedia(url, aesKey, maxBytes);
+        const buf = await decryptWecomMediaWithHttp(url, aesKey, { maxBytes, http: { proxyUrl } });
         return {
           body: "[image]",
           media: {
@@ -322,6 +543,7 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
         };
       } catch (err) {
         target.runtime.error?.(`Failed to decrypt inbound image: ${String(err)}`);
+        target.runtime.error?.(`图片解密失败: ${String(err)}`);
         return { body: `[image] (decryption failed: ${typeof err === 'object' && err ? (err as any).message : String(err)})` };
       }
     }
@@ -331,7 +553,7 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
     const url = String((msg as any).file?.url ?? "").trim();
     if (url && aesKey) {
       try {
-        const buf = await decryptWecomMedia(url, aesKey, maxBytes);
+        const buf = await decryptWecomMediaWithHttp(url, aesKey, { maxBytes, http: { proxyUrl } });
         return {
           body: "[file]",
           media: {
@@ -364,7 +586,7 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
           const url = String(item[t]?.url ?? "").trim();
           if (url) {
             try {
-              const buf = await decryptWecomMedia(url, aesKey, maxBytes);
+              const buf = await decryptWecomMediaWithHttp(url, aesKey, { maxBytes, http: { proxyUrl } });
               foundMedia = {
                 buffer: buf,
                 contentType: t === "image" ? "image/jpeg" : "application/octet-stream",
@@ -393,21 +615,24 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
   return { body: buildInboundBody(msg) };
 }
 
+
 /**
  * Flush pending inbound messages after debounce timeout.
  * Merges all buffered message contents and starts agent processing.
  */
-async function flushPending(pendingKey: string): Promise<void> {
-  const pending = pendingInbounds.get(pendingKey);
-  if (!pending) return;
-  pendingInbounds.delete(pendingKey);
-
-  if (pending.timeout) {
-    clearTimeout(pending.timeout);
-    pending.timeout = null;
-  }
-
-  const { streamId, target, msg, contents, media, msgids } = pending;
+/**
+ * **flushPending (刷新待处理消息 / 核心 Agent 触发点)**
+ * 
+ * 当防抖计时器结束时被调用。
+ * 核心逻辑：
+ * 1. 聚合所有 pending 的消息内容（用于上下文）。
+ * 2. 获取 PluginRuntime。
+ * 3. 标记 Stream 为 Started。
+ * 4. 调用 `startAgentForStream` 启动 Agent 流程。
+ * 5. 处理异常并更新 Stream 状态为 Error。
+ */
+async function flushPending(pending: PendingInbound): Promise<void> {
+  const { streamId, target, msg, contents, msgids } = pending;
 
   // Merge all message contents (each is already formatted by buildInboundBody)
   const mergedContents = contents.filter(c => c.trim()).join("\n").trim();
@@ -417,19 +642,15 @@ async function flushPending(pendingKey: string): Promise<void> {
     core = getWecomRuntime();
   } catch (err) {
     logVerbose(target, `flush pending: runtime not ready: ${String(err)}`);
-    const state = streams.get(streamId);
-    if (state) {
-      state.finished = true;
-      state.updatedAt = Date.now();
-    }
+    streamStore.markFinished(streamId);
     return;
   }
 
   if (core) {
-    const state = streams.get(streamId);
-    if (state) state.started = true;
+    streamStore.markStarted(streamId);
     const enrichedTarget: WecomWebhookTarget = { ...target, core };
     logVerbose(target, `flush pending: starting agent for ${contents.length} merged messages`);
+    logVerbose(target, `防抖结束: 开始处理聚合消息 数量=${contents.length} streamId=${streamId}`);
 
     // Pass the first msg (with its media structure), and mergedContents for multi-message context
     startAgentForStream({
@@ -440,24 +661,29 @@ async function flushPending(pendingKey: string): Promise<void> {
       mergedContents: contents.length > 1 ? mergedContents : undefined,
       mergedMsgids: msgids.length > 1 ? msgids : undefined,
     }).catch((err) => {
-      const state = streams.get(streamId);
-      if (state) {
+      streamStore.updateStream(streamId, (state) => {
         state.error = err instanceof Error ? err.message : String(err);
         state.content = state.content || `Error: ${state.error}`;
         state.finished = true;
-        state.updatedAt = Date.now();
-      }
-      target.runtime.error?.(`[${target.account.accountId}] wecom agent failed: ${String(err)}`);
+      });
+      target.runtime.error?.(`[${target.account.accountId}] wecom agent failed (处理失败): ${String(err)}`);
     });
   }
 }
 
+
+/**
+ * **waitForStreamContent (等待流内容)**
+ * 
+ * 用于长轮询 (Long Polling) 场景：阻塞等待流输出内容，直到超时或流结束。
+ * 这保证了用户能尽快收到第一批响应，而不是空转。
+ */
 async function waitForStreamContent(streamId: string, maxWaitMs: number): Promise<void> {
   if (maxWaitMs <= 0) return;
   const startedAt = Date.now();
   await new Promise<void>((resolve) => {
     const tick = () => {
-      const state = streams.get(streamId);
+      const state = streamStore.getStream(streamId);
       if (!state) return resolve();
       if (state.error || state.finished) return resolve();
       if (state.content.trim()) return resolve();
@@ -468,6 +694,18 @@ async function waitForStreamContent(streamId: string, maxWaitMs: number): Promis
   });
 }
 
+/**
+ * **startAgentForStream (启动 Agent 处理流程)**
+ * 
+ * 将接收到的（或聚合的）消息转换为 OpenClaw 内部格式，并分发给对应的 Agent。
+ * 包含：
+ * 1. 消息解密与媒体保存。
+ * 2. 路由解析 (Agent Route)。
+ * 3. 鉴权 (Command Authorization)。
+ * 4. 会话记录 (Session Recording)。
+ * 5. 触发 Agent 响应 (Dispatch Reply)。
+ * 6. 处理 Agent 输出（包括文本、Markdown 表格转换、<think> 标签保护、模板卡片识别）。
+ */
 async function startAgentForStream(params: {
   target: WecomWebhookTarget;
   accountId: string;
@@ -481,18 +719,168 @@ async function startAgentForStream(params: {
   const config = target.config;
   const account = target.account;
 
-  const userid = msg.from?.userid?.trim() || "unknown";
+  const userid = resolveWecomSenderUserId(msg) || "unknown";
   const chatType = msg.chattype === "group" ? "group" : "direct";
   const chatId = msg.chattype === "group" ? (msg.chatid?.trim() || "unknown") : userid;
-  // 1. Process inbound message (decrypt media if any)
-  const { body: rawBody, media } = await processInboundMessage(target, msg);
+  const taskKey = computeTaskKey(target, msg);
+  const aibotid = String((msg as any).aibotid ?? "").trim() || undefined;
+
+  // 更新 Stream 状态：记录上下文信息（用户ID、ChatType等）
+  streamStore.updateStream(streamId, (s) => {
+    s.userId = userid;
+    s.chatType = chatType === "group" ? "group" : "direct";
+    s.chatId = chatId;
+    s.taskKey = taskKey;
+    s.aibotid = aibotid;
+  });
+
+  // 1. 处理入站消息 (Decrypt media if any)
+  // 解析消息体，若是图片/文件则自动解密
+  let { body: rawBody, media } = await processInboundMessage(target, msg);
+
+  // 若存在从防抖逻辑聚合来的多条消息内容，则覆盖 rawBody
+  if (params.mergedContents) {
+    rawBody = params.mergedContents;
+  }
+
+  // P0: 群聊/私聊里“让 Bot 发送本机图片/文件路径”的场景，优先走 Bot 原会话交付（图片），
+  // 非图片文件则走 Agent 私信兜底，并确保 Bot 会话里有中文提示。
+  //
+  // 典型背景：Agent 主动发群 chatId（wr/wc...）在很多情况下会 86008，无论怎么“修复”都发不出去；
+  // 这种请求如果能被动回复图片，就必须由 Bot 在群内交付。
+  const directLocalPaths = extractLocalFilePathsFromText(rawBody);
+  if (directLocalPaths.length) {
+    logVerbose(
+      target,
+      `local-path: 检测到用户消息包含本机路径 count=${directLocalPaths.length} intent=${looksLikeSendLocalFileIntent(rawBody)}`,
+    );
+  }
+  if (directLocalPaths.length && looksLikeSendLocalFileIntent(rawBody)) {
+    const fs = await import("node:fs/promises");
+    const pathModule = await import("node:path");
+    const imageExts = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp"]);
+
+    const imagePaths: string[] = [];
+    const otherPaths: string[] = [];
+    for (const p of directLocalPaths) {
+      const ext = pathModule.extname(p).slice(1).toLowerCase();
+      if (imageExts.has(ext)) imagePaths.push(p);
+      else otherPaths.push(p);
+    }
+
+    // 1) 图片：优先 Bot 群内/原会话交付（被动/流式 msg_item）
+    if (imagePaths.length > 0 && otherPaths.length === 0) {
+      const loaded: Array<{ base64: string; md5: string; path: string }> = [];
+      for (const p of imagePaths) {
+        try {
+          const buf = await fs.readFile(p);
+          const base64 = buf.toString("base64");
+          const md5 = crypto.createHash("md5").update(buf).digest("hex");
+          loaded.push({ base64, md5, path: p });
+        } catch (err) {
+          target.runtime.error?.(`local-path: 读取图片失败 path=${p}: ${String(err)}`);
+        }
+      }
+
+      if (loaded.length > 0) {
+        streamStore.updateStream(streamId, (s) => {
+          s.images = loaded.map(({ base64, md5 }) => ({ base64, md5 }));
+          s.content = loaded.length === 1
+            ? `已发送图片（${pathModule.basename(loaded[0]!.path)}）`
+            : `已发送 ${loaded.length} 张图片`;
+          s.finished = true;
+        });
+
+        const responseUrl = getActiveReplyUrl(streamId);
+        if (responseUrl) {
+          try {
+            const finalReply = buildStreamReplyFromState(streamStore.getStream(streamId)!) as unknown as Record<string, unknown>;
+            await useActiveReplyOnce(streamId, async ({ responseUrl, proxyUrl }) => {
+              const res = await wecomFetch(
+                responseUrl,
+                {
+                  method: "POST",
+                  headers: { "Content-Type": "application/json" },
+                  body: JSON.stringify(finalReply),
+                },
+                { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+              );
+              if (!res.ok) throw new Error(`local-path image push failed: ${res.status}`);
+            });
+            logVerbose(target, `local-path: 已通过 Bot response_url 推送图片 frames=final images=${loaded.length}`);
+          } catch (err) {
+            target.runtime.error?.(`local-path: Bot 主动推送图片失败（将依赖 stream_refresh 拉取）: ${String(err)}`);
+          }
+        } else {
+          logVerbose(target, `local-path: 无 response_url，等待 stream_refresh 拉取最终图片`);
+        }
+        return;
+      }
+    }
+
+    // 2) 非图片文件：Bot 会话里提示 + Agent 私信兜底（目标锁定 userId）
+    if (otherPaths.length > 0) {
+      const agentCfg = resolveAgentAccountOrUndefined(config);
+      const agentOk = Boolean(agentCfg);
+
+      const filename = otherPaths.length === 1 ? otherPaths[0]!.split("/").pop()! : `${otherPaths.length} 个文件`;
+      const prompt = buildFallbackPrompt({
+        kind: "media",
+        agentConfigured: agentOk,
+        userId: userid,
+        filename,
+        chatType,
+      });
+
+      streamStore.updateStream(streamId, (s) => {
+        s.fallbackMode = "media";
+        s.finished = true;
+        s.content = prompt;
+        s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
+      });
+
+      try {
+        await sendBotFallbackPromptNow({ streamId, text: prompt });
+        logVerbose(target, `local-path: 文件兜底提示已推送`);
+      } catch (err) {
+        target.runtime.error?.(`local-path: 文件兜底提示推送失败: ${String(err)}`);
+      }
+
+      if (!agentCfg) return;
+      if (!userid || userid === "unknown") {
+        target.runtime.error?.(`local-path: 无法识别触发者 userId，无法 Agent 私信发送文件`);
+        return;
+      }
+
+      for (const p of otherPaths) {
+        const alreadySent = streamStore.getStream(streamId)?.agentMediaKeys?.includes(p);
+        if (alreadySent) continue;
+        try {
+          await sendAgentDmMedia({
+            agent: agentCfg,
+            userId: userid,
+            mediaUrlOrPath: p,
+            contentType: guessContentTypeFromPath(p),
+            filename: p.split("/").pop() || "file",
+          });
+          streamStore.updateStream(streamId, (s) => {
+            s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), p]));
+          });
+          logVerbose(target, `local-path: 文件已通过 Agent 私信发送 user=${userid} path=${p}`);
+        } catch (err) {
+          target.runtime.error?.(`local-path: Agent 私信发送文件失败 path=${p}: ${String(err)}`);
+        }
+      }
+      return;
+    }
+  }
 
   // 2. Save media if present
   let mediaPath: string | undefined;
   let mediaType: string | undefined;
   if (media) {
     try {
-      const maxBytes = (target.config.mediaMaxMb ?? 5) * 1024 * 1024;
+      const maxBytes = 5 * 1024 * 1024;
       const saved = await core.channel.media.saveMediaBuffer(
         media.buffer,
         media.contentType,
@@ -516,6 +904,7 @@ async function startAgentForStream(params: {
   });
 
   logVerbose(target, `starting agent processing (streamId=${streamId}, agentId=${route.agentId}, peerKind=${chatType}, peerId=${chatId})`);
+  logVerbose(target, `启动 Agent 处理: streamId=${streamId} 路由=${route.agentId} 类型=${chatType} ID=${chatId}`);
 
   const fromLabel = chatType === "group" ? `group:${chatId}` : `user:${userid}`;
   const storePath = core.channel.session.resolveStorePath(config.session?.store, {
@@ -555,10 +944,17 @@ async function startAgentForStream(params: {
     })
     : undefined;
 
+  const attachments = mediaPath ? [{
+    name: media?.filename || "file",
+    mimeType: mediaType,
+    url: pathToFileURL(mediaPath).href
+  }] : undefined;
+
   const ctxPayload = core.channel.reply.finalizeInboundContext({
     Body: body,
     RawBody: rawBody,
     CommandBody: rawBody,
+    Attachments: attachments,
     From: chatType === "group" ? `wecom:group:${chatId}` : `wecom:${userid}`,
     To: `wecom:${chatId}`,
     SessionKey: route.sessionKey,
@@ -593,14 +989,36 @@ async function startAgentForStream(params: {
     accountId: account.accountId,
   });
 
+  // WeCom Bot 会话交付约束：
+  // - 图片应尽量由 Bot 在原会话交付（流式最终帧 msg_item）。
+  // - 非图片文件走 Agent 私信兜底（本文件中实现），并由 Bot 给出提示。
+  //
+  // 重要：message 工具不是 sandbox 工具，必须通过 cfg.tools.deny 禁用。
+  // 否则 Agent 可能直接通过 message 工具私信/发群，绕过 Bot 交付链路，导致群里“没有任何提示”。
+  const cfgForDispatch = (() => {
+    const baseTools = (config as any)?.tools ?? {};
+    const existingDeny = Array.isArray(baseTools.deny) ? (baseTools.deny as string[]) : [];
+    const deny = Array.from(new Set([...existingDeny, "message"]));
+    return {
+      ...(config as any),
+      tools: {
+        ...baseTools,
+        deny,
+      },
+    } as OpenClawConfig;
+  })();
+  logVerbose(target, `tool-policy: WeCom Bot 会话已禁用 message 工具（防止绕过 Bot 交付）`);
+
+  // 调度 Agent 回复
+  // 使用 dispatchReplyWithBufferedBlockDispatcher 可以处理流式输出 buffer
   await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
     ctx: ctxPayload,
-    cfg: config,
+    cfg: cfgForDispatch,
     dispatcherOptions: {
       deliver: async (payload) => {
         let text = payload.text ?? "";
 
-        // Protect <think> tags from table conversion
+        // 保护 <think> 标签不被 markdown 表格转换破坏
         const thinkRegex = /<think>([\s\S]*?)<\/think>/g;
         const thinks: string[] = [];
         text = text.replace(thinkRegex, (match: string) => {
@@ -619,18 +1037,28 @@ async function startAgentForStream(params: {
 
               if (responseUrl && isSingleChat) {
                 // 单聊且有 response_url：发送卡片
-                await useActiveReplyOnce(streamId, async (url) => {
-                  await axios.post(url, {
-                    msgtype: "template_card",
-                    template_card: parsed.template_card,
-                  });
+                await useActiveReplyOnce(streamId, async ({ responseUrl, proxyUrl }) => {
+                  const res = await wecomFetch(
+                    responseUrl,
+                    {
+                      method: "POST",
+                      headers: { "Content-Type": "application/json" },
+                      body: JSON.stringify({
+                        msgtype: "template_card",
+                        template_card: parsed.template_card,
+                      }),
+                    },
+                    { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+                  );
+                  if (!res.ok) {
+                    throw new Error(`template_card send failed: ${res.status}`);
+                  }
                 });
                 logVerbose(target, `sent template_card: task_id=${parsed.template_card.task_id}`);
-                const current = streams.get(streamId);
-                if (!current) return;
-                current.finished = true;
-                current.content = "[已发送交互卡片]";
-                current.updatedAt = Date.now();
+                streamStore.updateStream(streamId, (s) => {
+                  s.finished = true;
+                  s.content = "[已发送交互卡片]";
+                });
                 target.statusSink?.({ lastOutboundAt: Date.now() });
                 return;
               } else {
@@ -652,10 +1080,92 @@ async function startAgentForStream(params: {
           text = text.replace(`__THINK_PLACEHOLDER_${i}__`, think);
         });
 
-        const current = streams.get(streamId);
+        const current = streamStore.getStream(streamId);
         if (!current) return;
 
         if (!current.images) current.images = [];
+        if (!current.agentMediaKeys) current.agentMediaKeys = [];
+
+        logVerbose(
+          target,
+          `deliver: chatType=${current.chatType ?? chatType} user=${current.userId ?? userid} textLen=${text.length} mediaCount=${(payload.mediaUrls?.length ?? 0) + (payload.mediaUrl ? 1 : 0)}`,
+        );
+
+        // If the model referenced a local image path in its reply but did not emit mediaUrl(s),
+        // we can still deliver it via Bot *only* when that exact path appeared in the user's
+        // original message (rawBody). This prevents the model from exfiltrating arbitrary files.
+        if (!payload.mediaUrl && !(payload.mediaUrls?.length ?? 0) && text.includes("/")) {
+          const candidates = extractLocalImagePathsFromText({ text, mustAlsoAppearIn: rawBody });
+          if (candidates.length > 0) {
+            logVerbose(target, `media: 从输出文本推断到本机图片路径（来自用户原消息）count=${candidates.length}`);
+            for (const p of candidates) {
+              try {
+                const fs = await import("node:fs/promises");
+                const pathModule = await import("node:path");
+                const buf = await fs.readFile(p);
+                const ext = pathModule.extname(p).slice(1).toLowerCase();
+                const imageExts: Record<string, string> = {
+                  jpg: "image/jpeg",
+                  jpeg: "image/jpeg",
+                  png: "image/png",
+                  gif: "image/gif",
+                  webp: "image/webp",
+                  bmp: "image/bmp",
+                };
+                const contentType = imageExts[ext] ?? "application/octet-stream";
+                if (!contentType.startsWith("image/")) {
+                  continue;
+                }
+                const base64 = buf.toString("base64");
+                const md5 = crypto.createHash("md5").update(buf).digest("hex");
+                current.images.push({ base64, md5 });
+                logVerbose(target, `media: 已加载本机图片用于 Bot 交付 path=${p}`);
+              } catch (err) {
+                target.runtime.error?.(`media: 读取本机图片失败 path=${p}: ${String(err)}`);
+              }
+            }
+          }
+        }
+
+        // Always accumulate content for potential Agent DM fallback (not limited by STREAM_MAX_BYTES).
+        if (text.trim()) {
+          streamStore.updateStream(streamId, (s) => {
+            appendDmContent(s, text);
+          });
+        }
+
+        // Timeout fallback (group only): near 6min window, stop bot stream and switch to Agent DM.
+        const now = Date.now();
+        const deadline = current.createdAt + BOT_WINDOW_MS;
+        const switchAt = deadline - BOT_SWITCH_MARGIN_MS;
+        const nearTimeout = !current.fallbackMode && !current.finished && now >= switchAt;
+        if (nearTimeout) {
+          const agentCfg = resolveAgentAccountOrUndefined(config);
+          const agentOk = Boolean(agentCfg);
+          const prompt = buildFallbackPrompt({
+            kind: "timeout",
+            agentConfigured: agentOk,
+            userId: current.userId,
+            chatType: current.chatType,
+          });
+          logVerbose(
+            target,
+            `fallback(timeout): 触发切换（接近 6 分钟）chatType=${current.chatType} agentConfigured=${agentOk} hasResponseUrl=${Boolean(getActiveReplyUrl(streamId))}`,
+          );
+          streamStore.updateStream(streamId, (s) => {
+            s.fallbackMode = "timeout";
+            s.finished = true;
+            s.content = prompt;
+            s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
+          });
+          try {
+            await sendBotFallbackPromptNow({ streamId, text: prompt });
+            logVerbose(target, `fallback(timeout): 群内提示已推送`);
+          } catch (err) {
+            target.runtime.error?.(`wecom bot fallback prompt push failed (timeout) streamId=${streamId}: ${String(err)}`);
+          }
+          return;
+        }
 
         const mediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
         for (const mediaPath of mediaUrls) {
@@ -667,12 +1177,10 @@ async function startAgentForStream(params: {
             const looksLikeUrl = /^https?:\/\//i.test(mediaPath);
 
             if (looksLikeUrl) {
-              const loaded = await core.channel.media.fetchRemoteMedia(mediaPath, {
-                maxBytes: 10 * 1024 * 1024,
-              });
+              const loaded = await core.channel.media.fetchRemoteMedia({ url: mediaPath });
               buf = loaded.buffer;
               contentType = loaded.contentType;
-              filename = loaded.filename ?? "attachment";
+              filename = loaded.fileName ?? "attachment";
             } else {
               const fs = await import("node:fs/promises");
               const pathModule = await import("node:path");
@@ -687,19 +1195,75 @@ async function startAgentForStream(params: {
               const base64 = buf.toString("base64");
               const md5 = crypto.createHash("md5").update(buf).digest("hex");
               current.images.push({ base64, md5 });
+              logVerbose(target, `media: 识别为图片 contentType=${contentType} filename=${filename}`);
             } else {
-              text += `\n\n[File: ${filename}]`;
+              // Non-image media: Bot 不支持原样发送（尤其群聊），统一切换到 Agent 私信兜底，并在 Bot 会话里提示用户。
+              const agentCfg = resolveAgentAccountOrUndefined(config);
+              const agentOk = Boolean(agentCfg);
+              const alreadySent = current.agentMediaKeys.includes(mediaPath);
+              logVerbose(
+                target,
+                `fallback(media): 检测到非图片文件 chatType=${current.chatType} contentType=${contentType ?? "unknown"} filename=${filename} agentConfigured=${agentOk} alreadySent=${alreadySent} hasResponseUrl=${Boolean(getActiveReplyUrl(streamId))}`,
+              );
+
+              if (agentCfg && !alreadySent && current.userId) {
+                try {
+                  await sendAgentDmMedia({
+                    agent: agentCfg,
+                    userId: current.userId,
+                    mediaUrlOrPath: mediaPath,
+                    contentType,
+                    filename,
+                  });
+                  logVerbose(target, `fallback(media): 文件已通过 Agent 私信发送 user=${current.userId}`);
+                  streamStore.updateStream(streamId, (s) => {
+                    s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), mediaPath]));
+                  });
+                } catch (err) {
+                  target.runtime.error?.(`wecom agent dm media failed: ${String(err)}`);
+                }
+              }
+
+              if (!current.fallbackMode) {
+                const prompt = buildFallbackPrompt({
+                  kind: "media",
+                  agentConfigured: agentOk,
+                  userId: current.userId,
+                  filename,
+                  chatType: current.chatType,
+                });
+                streamStore.updateStream(streamId, (s) => {
+                  s.fallbackMode = "media";
+                  s.finished = true;
+                  s.content = prompt;
+                  s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
+                });
+                try {
+                  await sendBotFallbackPromptNow({ streamId, text: prompt });
+                  logVerbose(target, `fallback(media): 群内提示已推送`);
+                } catch (err) {
+                  target.runtime.error?.(`wecom bot fallback prompt push failed (media) streamId=${streamId}: ${String(err)}`);
+                }
+              }
+              return;
             }
           } catch (err) {
             target.runtime.error?.(`Failed to process outbound media: ${mediaPath}: ${String(err)}`);
           }
         }
 
+        // If we are in fallback mode, do not continue updating the bot stream content.
+        const mode = streamStore.getStream(streamId)?.fallbackMode;
+        if (mode) return;
+
         const nextText = current.content
           ? `${current.content}\n\n${text}`.trim()
           : text.trim();
-        current.content = truncateUtf8Bytes(nextText, STREAM_MAX_BYTES);
-        current.updatedAt = Date.now();
+
+        streamStore.updateStream(streamId, (s) => {
+          s.content = truncateUtf8Bytes(nextText, STREAM_MAX_BYTES);
+          if (current.images?.length) s.images = current.images; // ensure images are saved
+        });
         target.statusSink?.({ lastOutboundAt: Date.now() });
       },
       onError: (err, info) => {
@@ -708,10 +1272,60 @@ async function startAgentForStream(params: {
     },
   });
 
-  const current = streams.get(streamId);
-  if (current) {
-    current.finished = true;
-    current.updatedAt = Date.now();
+  streamStore.markFinished(streamId);
+
+  // Timeout fallback final delivery (Agent DM): send once after the agent run completes.
+  const finishedState = streamStore.getStream(streamId);
+  if (finishedState?.fallbackMode === "timeout" && !finishedState.finalDeliveredAt) {
+    const agentCfg = resolveAgentAccountOrUndefined(config);
+    if (!agentCfg) {
+      // Agent not configured - group prompt already explains the situation.
+      streamStore.updateStream(streamId, (s) => { s.finalDeliveredAt = Date.now(); });
+    } else if (finishedState.userId) {
+      const dmText = (finishedState.dmContent ?? "").trim();
+      if (dmText) {
+        try {
+          logVerbose(target, `fallback(timeout): 开始通过 Agent 私信发送剩余内容 user=${finishedState.userId} len=${dmText.length}`);
+          await sendAgentDmText({ agent: agentCfg, userId: finishedState.userId, text: dmText, core });
+          logVerbose(target, `fallback(timeout): Agent 私信发送完成 user=${finishedState.userId}`);
+        } catch (err) {
+          target.runtime.error?.(`wecom agent dm text failed (timeout): ${String(err)}`);
+        }
+      }
+      streamStore.updateStream(streamId, (s) => { s.finalDeliveredAt = Date.now(); });
+    }
+  }
+
+  // Bot 群聊图片兜底：
+  // 依赖企业微信的“流式消息刷新”回调来拉取最终消息有时会出现客户端未能及时拉取到最后一帧的情况，
+  // 导致最终的图片(msg_item)没有展示。若存在 response_url，则在流结束后主动推送一次最终 stream 回复。
+  // 注：该行为以 response_url 是否可用为准；失败则仅记录日志，不影响原有刷新链路。
+  if (chatType === "group") {
+    const state = streamStore.getStream(streamId);
+    const hasImages = Boolean(state?.images?.length);
+    const responseUrl = getActiveReplyUrl(streamId);
+    if (state && hasImages && responseUrl) {
+      const finalReply = buildStreamReplyFromState(state) as unknown as Record<string, unknown>;
+      try {
+        await useActiveReplyOnce(streamId, async ({ responseUrl, proxyUrl }) => {
+          const res = await wecomFetch(
+            responseUrl,
+            {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify(finalReply),
+            },
+            { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+          );
+          if (!res.ok) {
+            throw new Error(`final stream push failed: ${res.status}`);
+          }
+        });
+        logVerbose(target, `final stream pushed via response_url (group) streamId=${streamId}, images=${state.images?.length ?? 0}`);
+      } catch (err) {
+        target.runtime.error?.(`final stream push via response_url failed (group) streamId=${streamId}: ${String(err)}`);
+      }
+    }
   }
 }
 
@@ -762,15 +1376,24 @@ function buildInboundBody(msg: WecomInboundMessage): string {
   return body;
 }
 
+/**
+ * **registerWecomWebhookTarget (注册 Webhook 目标)**
+ * 
+ * 注册一个 Bot 模式的接收端点。
+ * 同时会触发清理定时器的检查（如果有新注册，确保定时器运行）。
+ * 返回一个注销函数。
+ */
 export function registerWecomWebhookTarget(target: WecomWebhookTarget): () => void {
   const key = normalizeWebhookPath(target.path);
   const normalizedTarget = { ...target, path: key };
   const existing = webhookTargets.get(key) ?? [];
   webhookTargets.set(key, [...existing, normalizedTarget]);
+  ensurePruneTimer();
   return () => {
     const updated = (webhookTargets.get(key) ?? []).filter((entry) => entry !== normalizedTarget);
     if (updated.length > 0) webhookTargets.set(key, updated);
     else webhookTargets.delete(key);
+    checkPruneTimer();
   };
 }
 
@@ -780,13 +1403,26 @@ export function registerWecomWebhookTarget(target: WecomWebhookTarget): () => vo
 export function registerAgentWebhookTarget(target: AgentWebhookTarget): () => void {
   const key = WEBHOOK_PATHS.AGENT;
   agentTargets.set(key, target);
+  ensurePruneTimer();
   return () => {
     agentTargets.delete(key);
+    checkPruneTimer();
   };
 }
 
+/**
+ * **handleWecomWebhookRequest (HTTP 请求入口)**
+ * 
+ * 处理来自企业微信的所有 Webhook 请求。
+ * 职责：
+ * 1. 路由分发：区分 Agent 模式 (`/wecom/agent`) 和 Bot 模式 (其他路径)。
+ * 2. 安全校验：验证企业微信签名 (Signature)。
+ * 3. 消息解密：处理企业微信的加密包。
+ * 4. 响应处理：
+ *    - GET 请求：处理 EchoStr 验证。
+ *    - POST 请求：接收消息，放入 StreamStore，返回流式 First Chunk。
+ */
 export async function handleWecomWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
-  pruneStreams();
   const path = resolvePath(req);
 
   // Agent 模式路由: /wecom/agent
@@ -873,6 +1509,7 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
 
   const msg = parseWecomPlainMessage(plain);
   const msgtype = String(msg.msgtype ?? "").toLowerCase();
+  const proxyUrl = resolveWecomEgressProxyUrl(target.config);
 
   // Handle Event
   if (msgtype === "event") {
@@ -882,7 +1519,7 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
       const msgid = msg.msgid ? String(msg.msgid) : undefined;
 
       // Dedupe: skip if already processed this event
-      if (msgid && msgidToStreamId.has(msgid)) {
+      if (msgid && streamStore.getStreamByMsgId(msgid)) {
         logVerbose(target, `template_card_event: already processed msgid=${msgid}, skipping`);
         jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: {}, nonce, timestamp }));
         return true;
@@ -898,9 +1535,8 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
 
       jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: {}, nonce, timestamp }));
 
-      const streamId = createStreamId();
-      if (msgid) msgidToStreamId.set(msgid, streamId); // Mark as processed
-      streams.set(streamId, { streamId, createdAt: Date.now(), updatedAt: Date.now(), started: true, finished: false, content: "" });
+      const streamId = streamStore.createStream({ msgid });
+      streamStore.markStarted(streamId);
       storeActiveReply(streamId, msg.response_url);
       const core = getWecomRuntime();
       startAgentForStream({
@@ -925,40 +1561,94 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
   // Handle Stream Refresh
   if (msgtype === "stream") {
     const streamId = String((msg as any).stream?.id ?? "").trim();
-    const state = streams.get(streamId);
+    const state = streamStore.getStream(streamId);
     const reply = state ? buildStreamReplyFromState(state) : buildStreamReplyFromState({ streamId: streamId || "unknown", createdAt: Date.now(), updatedAt: Date.now(), started: true, finished: true, content: "" });
     jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: reply, nonce, timestamp }));
     return true;
   }
 
   // Handle Message (with Debounce)
-  const userid = msg.from?.userid?.trim() || "unknown";
-  const chatId = msg.chattype === "group" ? (msg.chatid?.trim() || "unknown") : userid;
-  const pendingKey = `wecom:${target.account.accountId}:${userid}:${chatId}`;
-  const msgContent = buildInboundBody(msg);
-
-  const existingPending = pendingInbounds.get(pendingKey);
-  if (existingPending) {
-    existingPending.contents.push(msgContent);
-    if (msg.msgid) existingPending.msgids.push(msg.msgid);
-    if (existingPending.timeout) clearTimeout(existingPending.timeout);
-    existingPending.timeout = setTimeout(() => void flushPending(pendingKey), DEFAULT_DEBOUNCE_MS);
-    jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: buildStreamPlaceholderReply({ streamId: existingPending.streamId, placeholderContent: target.account.config.streamPlaceholderContent }), nonce, timestamp }));
-    return true;
-  }
+  try {
+    const userid = resolveWecomSenderUserId(msg) || "unknown";
+    const chatId = msg.chattype === "group" ? (msg.chatid?.trim() || "unknown") : userid;
+    const pendingKey = `wecom:${target.account.accountId}:${userid}:${chatId}`;
+    const msgContent = buildInboundBody(msg);
+
+    logInfo(
+      target,
+      `inbound: msgtype=${msgtype} chattype=${String(msg.chattype ?? "")} chatid=${String(msg.chatid ?? "")} from=${userid} msgid=${String(msg.msgid ?? "")} hasResponseUrl=${Boolean((msg as any).response_url)}`,
+    );
+
+    // 去重: 若 msgid 已存在于 StreamStore，说明是重试请求，直接返回占位符
+    if (msg.msgid) {
+      const existingStreamId = streamStore.getStreamByMsgId(String(msg.msgid));
+      if (existingStreamId) {
+        logInfo(target, `message: 重复的 msgid=${msg.msgid}，跳过处理并返回占位符 streamId=${existingStreamId}`);
+        jsonOk(res, buildEncryptedJsonReply({
+          account: target.account,
+          plaintextJson: buildStreamPlaceholderReply({
+            streamId: existingStreamId,
+            placeholderContent: target.account.config.streamPlaceholderContent
+          }),
+          nonce,
+          timestamp
+        }));
+        return true;
+      }
+    }
+
+    // 加入 Pending 队列 (防抖/聚合)
+    // 消息不会立即处理，而是等待防抖计时器结束（flushPending）后统一触发
+    const { streamId, isNew } = streamStore.addPendingMessage({
+      pendingKey,
+      target,
+      msg,
+      msgContent,
+      nonce,
+      timestamp,
+      debounceMs: (target.account.config as any).debounceMs
+    });
 
-  const streamId = createStreamId();
-  if (msg.msgid) msgidToStreamId.set(msg.msgid, streamId);
-  streams.set(streamId, { streamId, msgid: msg.msgid, createdAt: Date.now(), updatedAt: Date.now(), started: false, finished: false, content: "" });
-  storeActiveReply(streamId, msg.response_url);
-  pendingInbounds.set(pendingKey, { streamId, target, msg, contents: [msgContent], msgids: msg.msgid ? [msg.msgid] : [], nonce, timestamp, createdAt: Date.now(), timeout: setTimeout(() => void flushPending(pendingKey), DEFAULT_DEBOUNCE_MS) });
+    if (isNew) {
+      storeActiveReply(streamId, msg.response_url, proxyUrl);
+    }
 
-  jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: buildStreamPlaceholderReply({ streamId, placeholderContent: target.account.config.streamPlaceholderContent }), nonce, timestamp }));
-  return true;
+    jsonOk(res, buildEncryptedJsonReply({
+      account: target.account,
+      plaintextJson: buildStreamPlaceholderReply({
+        streamId,
+        placeholderContent: target.account.config.streamPlaceholderContent
+      }),
+      nonce,
+      timestamp
+    }));
+    return true;
+  } catch (err) {
+    target.runtime.error?.(`[wecom] Bot message handler crashed: ${String(err)}`);
+    // 尽量返回 200，避免企微重试风暴；同时给一个可见的错误文本
+    jsonOk(res, buildEncryptedJsonReply({
+      account: target.account,
+      plaintextJson: { msgtype: "text", text: { content: "服务内部错误：Bot 处理异常，请稍后重试。" } },
+      nonce,
+      timestamp
+    }));
+    return true;
+  }
 }
 
 export async function sendActiveMessage(streamId: string, content: string): Promise<void> {
-  await useActiveReplyOnce(streamId, async (url) => {
-    await axios.post(url, { msgtype: "text", text: { content } });
+  await useActiveReplyOnce(streamId, async ({ responseUrl, proxyUrl }) => {
+    const res = await wecomFetch(
+      responseUrl,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ msgtype: "text", text: { content } }),
+      },
+      { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+    );
+    if (!res.ok) {
+      throw new Error(`active send failed: ${res.status}`);
+    }
   });
 }