@yanhaidao/wecom 2.2.28 → 2.3.3

package/src/monitor.ts

@@ -11,7 +11,7 @@ import type { WecomBotInboundMessage as WecomInboundMessage, WecomInboundQuote }
 import { decryptWecomEncrypted, encryptWecomPlaintext, verifyWecomSignature, computeWecomMsgSignature } from "./crypto.js";
 import { extractEncryptFromXml } from "./crypto/xml.js";
 import { getWecomRuntime } from "./runtime.js";
-import { decryptWecomMediaWithHttp } from "./media.js";
+import { decryptWecomMediaWithMeta } from "./media.js";
 import { WEBHOOK_PATHS, LIMITS as WECOM_LIMITS } from "./types/constants.js";
 import { handleAgentWebhook } from "./agent/index.js";
 import { resolveWecomAccount, resolveWecomEgressProxyUrl, resolveWecomMediaMaxBytes, shouldRejectWecomDefaultRoute } from "./config/index.js";
@@ -220,16 +220,24 @@ type RouteFailureReason =
   | "wecom_identity_mismatch"
   | "wecom_matrix_path_required";
 
-function isLegacyWecomPath(path: string): boolean {
-  return path === WEBHOOK_PATHS.BOT || path === WEBHOOK_PATHS.BOT_ALT || path === WEBHOOK_PATHS.AGENT;
+function isNonMatrixWecomBasePath(path: string): boolean {
+  return (
+    path === WEBHOOK_PATHS.BOT ||
+    path === WEBHOOK_PATHS.BOT_ALT ||
+    path === WEBHOOK_PATHS.AGENT ||
+    path === WEBHOOK_PATHS.BOT_PLUGIN ||
+    path === WEBHOOK_PATHS.AGENT_PLUGIN
+  );
 }
 
 function hasMatrixExplicitRoutesRegistered(): boolean {
   for (const key of webhookTargets.keys()) {
     if (key.startsWith(`${WEBHOOK_PATHS.BOT_ALT}/`)) return true;
+    if (key.startsWith(`${WEBHOOK_PATHS.BOT_PLUGIN}/`)) return true;
   }
   for (const key of agentTargets.keys()) {
     if (key.startsWith(`${WEBHOOK_PATHS.AGENT}/`)) return true;
+    if (key.startsWith(`${WEBHOOK_PATHS.AGENT_PLUGIN}/`)) return true;
   }
   return false;
 }
@@ -437,6 +445,27 @@ async function sendBotFallbackPromptNow(params: { streamId: string; text: string
   });
 }
 
+async function pushFinalStreamReplyNow(streamId: string): Promise<void> {
+  const state = streamStore.getStream(streamId);
+  const responseUrl = getActiveReplyUrl(streamId);
+  if (!state || !responseUrl) return;
+  const finalReply = buildStreamReplyFromState(state) 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(`final stream push failed: ${res.status}`);
+    }
+  });
+}
+
 async function sendAgentDmText(params: {
   agent: ResolvedAgentAccount;
   userId: string;
@@ -500,10 +529,10 @@ function extractLocalImagePathsFromText(params: {
   const mustAlsoAppearIn = params.mustAlsoAppearIn;
   if (!text.trim()) return [];
 
-  // Conservative: only accept common macOS absolute paths for images.
+  // Conservative: only accept common absolute paths for macOS/Linux hosts.
   // 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 re = new RegExp(String.raw`(\/(?:Users|tmp|root|home)\/[^\s"'<>]+?\.${exts})`, "gi");
   const found = new Set<string>();
   let m: RegExpExecArray | null;
   while ((m = re.exec(text))) {
@@ -518,9 +547,9 @@ function extractLocalImagePathsFromText(params: {
 function extractLocalFilePathsFromText(text: string): string[] {
   if (!text.trim()) return [];
 
-  // Conservative: only accept common macOS absolute paths.
+  // Conservative: only accept common absolute paths for macOS/Linux hosts.
   // This is primarily for “send local file” style requests (operator/debug usage).
-  const re = new RegExp(String.raw`(\/(?:Users|tmp)\/[^\s"'<>]+)`, "g");
+  const re = new RegExp(String.raw`(\/(?:Users|tmp|root|home)\/[^\s"'<>]+)`, "g");
   const found = new Set<string>();
   let m: RegExpExecArray | null;
   while ((m = re.exec(text))) {
@@ -531,23 +560,287 @@ function extractLocalFilePathsFromText(text: string): string[] {
   return Array.from(found);
 }
 
+const MIME_BY_EXT: 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",
+  csv: "text/csv",
+  tsv: "text/tab-separated-values",
+  md: "text/markdown",
+  json: "application/json",
+  xml: "application/xml",
+  yaml: "application/yaml",
+  yml: "application/yaml",
+  zip: "application/zip",
+  rar: "application/vnd.rar",
+  "7z": "application/x-7z-compressed",
+  tar: "application/x-tar",
+  gz: "application/gzip",
+  tgz: "application/gzip",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  rtf: "application/rtf",
+  odt: "application/vnd.oasis.opendocument.text",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  amr: "voice/amr",
+  m4a: "audio/mp4",
+  mp4: "video/mp4",
+  mov: "video/quicktime",
+};
+
+const EXT_BY_MIME: Record<string, string> = {
+  ...Object.fromEntries(Object.entries(MIME_BY_EXT).map(([ext, mime]) => [mime, ext])),
+  "application/octet-stream": "bin",
+};
+
+const GENERIC_CONTENT_TYPES = new Set([
+  "application/octet-stream",
+  "binary/octet-stream",
+  "application/download",
+]);
+
+function normalizeContentType(raw?: string | null): string | undefined {
+  const normalized = String(raw ?? "").trim().split(";")[0]?.trim().toLowerCase();
+  return normalized || undefined;
+}
+
+function isGenericContentType(raw?: string | null): boolean {
+  const normalized = normalizeContentType(raw);
+  if (!normalized) return true;
+  return GENERIC_CONTENT_TYPES.has(normalized);
+}
+
 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];
+  return MIME_BY_EXT[ext];
+}
+
+function guessExtensionFromContentType(contentType?: string): string | undefined {
+  const normalized = normalizeContentType(contentType);
+  if (!normalized) return undefined;
+  if (normalized === "image/jpeg") return "jpg";
+  return EXT_BY_MIME[normalized];
+}
+
+function extractFileNameFromUrl(rawUrl?: string): string | undefined {
+  const s = String(rawUrl ?? "").trim();
+  if (!s) return undefined;
+  try {
+    const u = new URL(s);
+    const name = decodeURIComponent(u.pathname.split("/").pop() ?? "").trim();
+    return name || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function sanitizeInboundFilename(raw?: string): string | undefined {
+  const s = String(raw ?? "").trim();
+  if (!s) return undefined;
+  const base = s.split(/[\\/]/).pop()?.trim() ?? "";
+  if (!base) return undefined;
+  const sanitized = base.replace(/[\u0000-\u001f<>:"|?*]/g, "_").trim();
+  return sanitized || undefined;
+}
+
+function hasLikelyExtension(name?: string): boolean {
+  if (!name) return false;
+  return /\.[a-z0-9]{1,16}$/i.test(name);
+}
+
+function detectMimeFromBuffer(buffer: Buffer): string | undefined {
+  if (!buffer || buffer.length < 4) return undefined;
+
+  // PNG
+  if (
+    buffer.length >= 8 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47 &&
+    buffer[4] === 0x0d &&
+    buffer[5] === 0x0a &&
+    buffer[6] === 0x1a &&
+    buffer[7] === 0x0a
+  ) {
+    return "image/png";
+  }
+
+  // JPEG
+  if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return "image/jpeg";
+  }
+
+  // GIF
+  if (buffer.subarray(0, 6).toString("ascii") === "GIF87a" || buffer.subarray(0, 6).toString("ascii") === "GIF89a") {
+    return "image/gif";
+  }
+
+  // WEBP
+  if (buffer.length >= 12 && buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP") {
+    return "image/webp";
+  }
+
+  // BMP
+  if (buffer[0] === 0x42 && buffer[1] === 0x4d) {
+    return "image/bmp";
+  }
+
+  // PDF
+  if (buffer.subarray(0, 5).toString("ascii") === "%PDF-") {
+    return "application/pdf";
+  }
+
+  // OGG
+  if (buffer.subarray(0, 4).toString("ascii") === "OggS") {
+    return "audio/ogg";
+  }
+
+  // WAV
+  if (buffer.length >= 12 && buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WAVE") {
+    return "audio/wav";
+  }
+
+  // MP3
+  if (buffer.subarray(0, 3).toString("ascii") === "ID3" || (buffer[0] === 0xff && (buffer[1] & 0xe0) === 0xe0)) {
+    return "audio/mpeg";
+  }
+
+  // MP4/MOV family
+  if (buffer.length >= 12 && buffer.subarray(4, 8).toString("ascii") === "ftyp") {
+    return "video/mp4";
+  }
+
+  // Legacy Office (OLE Compound File)
+  if (
+    buffer.length >= 8 &&
+    buffer[0] === 0xd0 &&
+    buffer[1] === 0xcf &&
+    buffer[2] === 0x11 &&
+    buffer[3] === 0xe0 &&
+    buffer[4] === 0xa1 &&
+    buffer[5] === 0xb1 &&
+    buffer[6] === 0x1a &&
+    buffer[7] === 0xe1
+  ) {
+    return "application/msword";
+  }
+
+  // ZIP / OOXML
+  const zipMagic =
+    (buffer[0] === 0x50 && buffer[1] === 0x4b && buffer[2] === 0x03 && buffer[3] === 0x04) ||
+    (buffer[0] === 0x50 && buffer[1] === 0x4b && buffer[2] === 0x05 && buffer[3] === 0x06) ||
+    (buffer[0] === 0x50 && buffer[1] === 0x4b && buffer[2] === 0x07 && buffer[3] === 0x08);
+  if (zipMagic) {
+    const probe = buffer.subarray(0, Math.min(buffer.length, 512 * 1024));
+    if (probe.includes(Buffer.from("word/"))) {
+      return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    }
+    if (probe.includes(Buffer.from("xl/"))) {
+      return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    }
+    if (probe.includes(Buffer.from("ppt/"))) {
+      return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+    }
+    return "application/zip";
+  }
+
+  // Plain text heuristic
+  const sample = buffer.subarray(0, Math.min(buffer.length, 4096));
+  let printable = 0;
+  for (const b of sample) {
+    if (b === 0x00) return undefined;
+    if (b === 0x09 || b === 0x0a || b === 0x0d || (b >= 0x20 && b <= 0x7e)) {
+      printable += 1;
+    }
+  }
+  if (sample.length > 0 && printable / sample.length > 0.95) {
+    return "text/plain";
+  }
+
+  return undefined;
+}
+
+function resolveInlineFileName(input: unknown): string | undefined {
+  const raw = String(input ?? "").trim();
+  return sanitizeInboundFilename(raw);
+}
+
+function pickBotFileName(msg: WecomInboundMessage, item?: Record<string, any>): string | undefined {
+  const fromItem = item
+    ? resolveInlineFileName(
+      item?.filename ??
+      item?.file_name ??
+      item?.fileName ??
+      item?.name ??
+      item?.title,
+    )
+    : undefined;
+  if (fromItem) return fromItem;
+
+  const fromFile = resolveInlineFileName(
+    (msg as any)?.file?.filename ??
+    (msg as any)?.file?.file_name ??
+    (msg as any)?.file?.fileName ??
+    (msg as any)?.file?.name ??
+    (msg as any)?.file?.title ??
+    (msg as any)?.filename ??
+    (msg as any)?.fileName ??
+    (msg as any)?.FileName,
+  );
+  return fromFile;
+}
+
+function inferInboundMediaMeta(params: {
+  kind: "image" | "file";
+  buffer: Buffer;
+  sourceUrl?: string;
+  sourceContentType?: string;
+  sourceFilename?: string;
+  explicitFilename?: string;
+}): { contentType: string; filename: string } {
+  const headerType = normalizeContentType(params.sourceContentType);
+  const magicType = detectMimeFromBuffer(params.buffer);
+  const rawUrlName = sanitizeInboundFilename(extractFileNameFromUrl(params.sourceUrl));
+  const guessedByUrl = hasLikelyExtension(rawUrlName) ? rawUrlName : undefined;
+  const explicitName = sanitizeInboundFilename(params.explicitFilename);
+  const sourceName = sanitizeInboundFilename(params.sourceFilename);
+  const chosenName = explicitName || sourceName || guessedByUrl;
+  const typeByName = chosenName ? guessContentTypeFromPath(chosenName) : undefined;
+
+  let contentType: string;
+  if (params.kind === "image") {
+    if (magicType?.startsWith("image/")) contentType = magicType;
+    else if (headerType?.startsWith("image/")) contentType = headerType;
+    else if (typeByName?.startsWith("image/")) contentType = typeByName;
+    else contentType = "image/jpeg";
+  } else {
+    contentType =
+      magicType ||
+      (!isGenericContentType(headerType) ? headerType! : undefined) ||
+      typeByName ||
+      "application/octet-stream";
+  }
+
+  const hasExt = Boolean(chosenName && /\.[a-z0-9]{1,16}$/i.test(chosenName));
+  const ext = guessExtensionFromContentType(contentType) || (params.kind === "image" ? "jpg" : "bin");
+  const filename = chosenName
+    ? (hasExt ? chosenName : `${chosenName}.${ext}`)
+    : `${params.kind}.${ext}`;
+
+  return { contentType, filename };
 }
 
 function looksLikeSendLocalFileIntent(rawBody: string): boolean {
@@ -670,13 +963,21 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
     const url = String((msg as any).image?.url ?? "").trim();
     if (url && aesKey) {
       try {
-        const buf = await decryptWecomMediaWithHttp(url, aesKey, { maxBytes, http: { proxyUrl } });
+        const decrypted = await decryptWecomMediaWithMeta(url, aesKey, { maxBytes, http: { proxyUrl } });
+        const inferred = inferInboundMediaMeta({
+          kind: "image",
+          buffer: decrypted.buffer,
+          sourceUrl: decrypted.sourceUrl || url,
+          sourceContentType: decrypted.sourceContentType,
+          sourceFilename: decrypted.sourceFilename,
+          explicitFilename: pickBotFileName(msg),
+        });
         return {
           body: "[image]",
           media: {
-            buffer: buf,
-            contentType: "image/jpeg", // WeCom images are usually generic; safest assumption or could act as generic
-            filename: "image.jpg",
+            buffer: decrypted.buffer,
+            contentType: inferred.contentType,
+            filename: inferred.filename,
           }
         };
       } catch (err) {
@@ -684,7 +985,10 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
         target.runtime.error?.(
           `图片解密失败: ${String(err)}; 可调大 channels.wecom.media.maxBytes（当前=${maxBytes}）例如：openclaw config set channels.wecom.media.maxBytes ${50 * 1024 * 1024}`,
         );
-        return { body: `[image] (decryption failed: ${typeof err === 'object' && err ? (err as any).message : String(err)})` };
+        const errorMessage = typeof err === 'object' && err 
+          ? `${(err as any).message}${((err as any).cause) ? ` (cause: ${String((err as any).cause)})` : ''}` 
+          : String(err);
+        return { body: `[image] (decryption failed: ${errorMessage})` };
       }
     }
   }
@@ -693,20 +997,31 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
     const url = String((msg as any).file?.url ?? "").trim();
     if (url && aesKey) {
       try {
-        const buf = await decryptWecomMediaWithHttp(url, aesKey, { maxBytes, http: { proxyUrl } });
+        const decrypted = await decryptWecomMediaWithMeta(url, aesKey, { maxBytes, http: { proxyUrl } });
+        const inferred = inferInboundMediaMeta({
+          kind: "file",
+          buffer: decrypted.buffer,
+          sourceUrl: decrypted.sourceUrl || url,
+          sourceContentType: decrypted.sourceContentType,
+          sourceFilename: decrypted.sourceFilename,
+          explicitFilename: pickBotFileName(msg),
+        });
         return {
           body: "[file]",
           media: {
-            buffer: buf,
-            contentType: "application/octet-stream",
-            filename: "file.bin", // WeCom doesn't guarantee filename in webhook payload always, defaulting
+            buffer: decrypted.buffer,
+            contentType: inferred.contentType,
+            filename: inferred.filename,
           }
         };
       } catch (err) {
         target.runtime.error?.(
           `Failed to decrypt inbound file: ${String(err)}; 可调大 channels.wecom.media.maxBytes（当前=${maxBytes}）例如：openclaw config set channels.wecom.media.maxBytes ${50 * 1024 * 1024}`,
         );
-        return { body: `[file] (decryption failed: ${typeof err === 'object' && err ? (err as any).message : String(err)})` };
+        const errorMessage = typeof err === 'object' && err 
+          ? `${(err as any).message}${((err as any).cause) ? ` (cause: ${String((err as any).cause)})` : ''}` 
+          : String(err);
+        return { body: `[file] (decryption failed: ${errorMessage})` };
       }
     }
   }
@@ -728,18 +1043,29 @@ async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInbou
           const url = String(item[t]?.url ?? "").trim();
           if (url) {
             try {
-              const buf = await decryptWecomMediaWithHttp(url, aesKey, { maxBytes, http: { proxyUrl } });
+              const decrypted = await decryptWecomMediaWithMeta(url, aesKey, { maxBytes, http: { proxyUrl } });
+              const inferred = inferInboundMediaMeta({
+                kind: t,
+                buffer: decrypted.buffer,
+                sourceUrl: decrypted.sourceUrl || url,
+                sourceContentType: decrypted.sourceContentType,
+                sourceFilename: decrypted.sourceFilename,
+                explicitFilename: pickBotFileName(msg, item?.[t]),
+              });
               foundMedia = {
-                buffer: buf,
-                contentType: t === "image" ? "image/jpeg" : "application/octet-stream",
-                filename: t === "image" ? "image.jpg" : "file.bin"
+                buffer: decrypted.buffer,
+                contentType: inferred.contentType,
+                filename: inferred.filename,
               };
               bodyParts.push(`[${t}]`);
             } catch (err) {
               target.runtime.error?.(
                 `Failed to decrypt mixed ${t}: ${String(err)}; 可调大 channels.wecom.media.maxBytes（当前=${maxBytes}）例如：openclaw config set channels.wecom.media.maxBytes ${50 * 1024 * 1024}`,
               );
-              bodyParts.push(`[${t}] (decryption failed)`);
+              const errorMessage = typeof err === 'object' && err 
+                ? `${(err as any).message}${((err as any).cause) ? ` (cause: ${String((err as any).cause)})` : ''}` 
+                : String(err);
+              bodyParts.push(`[${t}] (decryption failed: ${errorMessage})`);
             }
           } else {
             bodyParts.push(`[${t}]`);
@@ -965,6 +1291,60 @@ async function startAgentForStream(params: {
         streamStore.onStreamFinished(streamId);
         return;
       }
+
+      // 图片路径都读取失败时，切换到 Agent 私信兜底，并主动结束 Bot 流。
+      const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
+      const agentOk = Boolean(agentCfg);
+      const fallbackName = imagePaths.length === 1
+        ? (imagePaths[0]!.split("/").pop() || "image")
+        : `${imagePaths.length} 张图片`;
+      const prompt = buildFallbackPrompt({
+        kind: "media",
+        agentConfigured: agentOk,
+        userId: userid,
+        filename: fallbackName,
+        chatType,
+      });
+
+      streamStore.updateStream(streamId, (s) => {
+        s.fallbackMode = "error";
+        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 && userid && userid !== "unknown") {
+        for (const p of imagePaths) {
+          const guessedType = guessContentTypeFromPath(p);
+          try {
+            await sendAgentDmMedia({
+              agent: agentCfg,
+              userId: userid,
+              mediaUrlOrPath: p,
+              contentType: guessedType,
+              filename: p.split("/").pop() || "image",
+            });
+            streamStore.updateStream(streamId, (s) => {
+              s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), p]));
+            });
+            logVerbose(
+              target,
+              `local-path: 图片已通过 Agent 私信发送 user=${userid} path=${p} contentType=${guessedType ?? "unknown"}`,
+            );
+          } catch (err) {
+            target.runtime.error?.(`local-path: 图片 Agent 私信兜底失败 path=${p}: ${String(err)}`);
+          }
+        }
+      }
+      streamStore.onStreamFinished(streamId);
+      return;
     }
 
     // 2) 非图片文件：Bot 会话里提示 + Agent 私信兜底（目标锁定 userId）
@@ -1008,18 +1388,22 @@ async function startAgentForStream(params: {
       for (const p of otherPaths) {
         const alreadySent = streamStore.getStream(streamId)?.agentMediaKeys?.includes(p);
         if (alreadySent) continue;
+        const guessedType = guessContentTypeFromPath(p);
         try {
           await sendAgentDmMedia({
             agent: agentCfg,
             userId: userid,
             mediaUrlOrPath: p,
-            contentType: guessContentTypeFromPath(p),
+            contentType: guessedType,
             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}`);
+          logVerbose(
+            target,
+            `local-path: 文件已通过 Agent 私信发送 user=${userid} path=${p} contentType=${guessedType ?? "unknown"}`,
+          );
         } catch (err) {
           target.runtime.error?.(`local-path: Agent 私信发送文件失败 path=${p}: ${String(err)}`);
         }
@@ -1173,6 +1557,10 @@ async function startAgentForStream(params: {
     SenderName: userid,
     SenderId: userid,
     Provider: "wecom",
+    // Keep Surface aligned with OriginatingChannel for Bot-mode delivery.
+    // If Surface is "webchat", core dispatch treats this as cross-channel
+    // and routes replies via routeReply -> wecom outbound (Agent API),
+    // bypassing the Bot stream deliver path.
     Surface: "wecom",
     MessageSid: msg.msgid,
     CommandAuthorized: commandAuthorized,
@@ -1212,8 +1600,10 @@ async function startAgentForStream(params: {
     const baseTools = (config as any)?.tools ?? {};
     const baseSandbox = (baseTools as any)?.sandbox ?? {};
     const baseSandboxTools = (baseSandbox as any)?.tools ?? {};
-    const existingDeny = Array.isArray((baseSandboxTools as any).deny) ? ((baseSandboxTools as any).deny as string[]) : [];
-    const deny = Array.from(new Set([...existingDeny, "message"]));
+    const existingTopLevelDeny = Array.isArray((baseTools as any).deny) ? ((baseTools as any).deny as string[]) : [];
+    const existingSandboxDeny = Array.isArray((baseSandboxTools as any).deny) ? ((baseSandboxTools as any).deny as string[]) : [];
+    const topLevelDeny = Array.from(new Set([...existingTopLevelDeny, "message"]));
+    const sandboxDeny = Array.from(new Set([...existingSandboxDeny, "message"]));
     return {
       ...(config as any),
       agents: {
@@ -1237,17 +1627,18 @@ async function startAgentForStream(params: {
       },
       tools: {
         ...baseTools,
+        deny: topLevelDeny,
         sandbox: {
           ...baseSandbox,
           tools: {
             ...baseSandboxTools,
-            deny,
+            deny: sandboxDeny,
           },
         },
       },
     } as OpenClawConfig;
   })();
-  logVerbose(target, `tool-policy: WeCom Bot 会话已禁用 message 工具（tools.sandbox.tools.deny += message，防止绕过 Bot 交付）`);
+  logVerbose(target, `tool-policy: WeCom Bot 会话已禁用 message 工具（tools.deny += message；并同步到 tools.sandbox.tools.deny，防止绕过 Bot 交付）`);
 
   // 调度 Agent 回复
   // 使用 dispatchReplyWithBufferedBlockDispatcher 可以处理流式输出 buffer
@@ -1331,9 +1722,10 @@ async function startAgentForStream(params: {
         if (!current.images) current.images = [];
         if (!current.agentMediaKeys) current.agentMediaKeys = [];
 
+        const deliverKind = info?.kind ?? "block";
         logVerbose(
           target,
-          `deliver: kind=${info.kind} chatType=${current.chatType ?? chatType} user=${current.userId ?? userid} textLen=${text.length} mediaCount=${(payload.mediaUrls?.length ?? 0) + (payload.mediaUrl ? 1 : 0)}`,
+          `deliver: kind=${deliverKind} 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),
@@ -1379,7 +1771,7 @@ async function startAgentForStream(params: {
           });
         }
 
-        // Timeout fallback (group only): near 6min window, stop bot stream and switch to Agent DM.
+        // Timeout fallback: 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;
@@ -1414,10 +1806,10 @@ async function startAgentForStream(params: {
 
         const mediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
         for (const mediaPath of mediaUrls) {
+          let contentType: string | undefined;
+          let filename = mediaPath.split("/").pop() || "attachment";
           try {
             let buf: Buffer;
-            let contentType: string | undefined;
-            let filename: string;
 
             const looksLikeUrl = /^https?:\/\//i.test(mediaPath);
 
@@ -1494,6 +1886,48 @@ async function startAgentForStream(params: {
             }
           } catch (err) {
             target.runtime.error?.(`Failed to process outbound media: ${mediaPath}: ${String(err)}`);
+            const agentCfg = resolveAgentAccountOrUndefined(config, account.accountId);
+            const agentOk = Boolean(agentCfg);
+            const fallbackFilename = filename || mediaPath.split("/").pop() || "attachment";
+            if (agentCfg && current.userId && !current.agentMediaKeys.includes(mediaPath)) {
+              try {
+                await sendAgentDmMedia({
+                  agent: agentCfg,
+                  userId: current.userId,
+                  mediaUrlOrPath: mediaPath,
+                  contentType,
+                  filename: fallbackFilename,
+                });
+                streamStore.updateStream(streamId, (s) => {
+                  s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), mediaPath]));
+                });
+                logVerbose(target, `fallback(error): 媒体处理失败后已通过 Agent 私信发送 user=${current.userId}`);
+              } catch (sendErr) {
+                target.runtime.error?.(`fallback(error): 媒体处理失败后的 Agent 私信发送也失败: ${String(sendErr)}`);
+              }
+            }
+            if (!current.fallbackMode) {
+              const prompt = buildFallbackPrompt({
+                kind: "error",
+                agentConfigured: agentOk,
+                userId: current.userId,
+                filename: fallbackFilename,
+                chatType: current.chatType,
+              });
+              streamStore.updateStream(streamId, (s) => {
+                s.fallbackMode = "error";
+                s.finished = true;
+                s.content = prompt;
+                s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
+              });
+              try {
+                await sendBotFallbackPromptNow({ streamId, text: prompt });
+                logVerbose(target, `fallback(error): 群内提示已推送`);
+              } catch (pushErr) {
+                target.runtime.error?.(`wecom bot fallback prompt push failed (error) streamId=${streamId}: ${String(pushErr)}`);
+              }
+            }
+            return;
           }
         }
 
@@ -1532,6 +1966,12 @@ async function startAgentForStream(params: {
     }
   }
 
+  streamStore.updateStream(streamId, (s) => {
+    if (!s.content.trim() && !(s.images?.length ?? 0)) {
+      s.content = "✅ 已处理完成。";
+    }
+  });
+
   streamStore.markFinished(streamId);
 
   // Timeout fallback final delivery (Agent DM): send once after the agent run completes.
@@ -1556,35 +1996,19 @@ async function startAgentForStream(params: {
     }
   }
 
-  // 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)}`);
-      }
+  // 统一终结：只要 response_url 可用，尽量主动推一次最终流帧，确保“思考中”能及时收口。
+  // 失败仅记录日志，不影响 stream_refresh 被动拉取链路。
+  const stateAfterFinish = streamStore.getStream(streamId);
+  const responseUrl = getActiveReplyUrl(streamId);
+  if (stateAfterFinish && responseUrl) {
+    try {
+      await pushFinalStreamReplyNow(streamId);
+      logVerbose(
+        target,
+        `final stream pushed via response_url streamId=${streamId}, chatType=${chatType}, images=${stateAfterFinish.images?.length ?? 0}`,
+      );
+    } catch (err) {
+      target.runtime.error?.(`final stream push via response_url failed streamId=${streamId}: ${String(err)}`);
     }
   }
 
@@ -1698,7 +2122,7 @@ export function registerAgentWebhookTarget(target: AgentWebhookTarget): () => vo
  * 
  * 处理来自企业微信的所有 Webhook 请求。
  * 职责：
- * 1. 路由分发：按 Matrix/Legacy 路径分流 Bot 与 Agent 回调。
+ * 1. 路由分发：优先按 `/plugins/wecom/{bot|agent}/{accountId}` 分流，并兼容历史 `/wecom/*` 路径。
  * 2. 安全校验：验证企业微信签名 (Signature)。
  * 3. 消息解密：处理企业微信的加密包。
  * 4. 响应处理：
@@ -1722,7 +2146,7 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
     `[wecom] inbound(http): reqId=${reqId} path=${path} method=${req.method ?? "UNKNOWN"} remote=${remote} ua=${ua ? `"${ua}"` : "N/A"} contentLength=${cl || "N/A"} query={timestamp:${hasTimestamp},nonce:${hasNonce},echostr:${hasEchostr},msg_signature:${hasMsgSig},signature:${hasSignature}}`,
   );
 
-  if (hasMatrixExplicitRoutesRegistered() && isLegacyWecomPath(path)) {
+  if (hasMatrixExplicitRoutesRegistered() && isNonMatrixWecomBasePath(path)) {
     logRouteFailure({
       reqId,
       path,
@@ -1733,14 +2157,19 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
     writeRouteFailure(
       res,
       "wecom_matrix_path_required",
-      "Matrix mode requires explicit account path. Use /wecom/bot/{accountId} or /wecom/agent/{accountId}.",
+      "Matrix mode requires explicit account path. Use /plugins/wecom/bot/{accountId} or /plugins/wecom/agent/{accountId}.",
     );
     return true;
   }
 
-  const isAgentPath = path === WEBHOOK_PATHS.AGENT || path.startsWith(`${WEBHOOK_PATHS.AGENT}/`);
-  if (isAgentPath) {
-    const targets = agentTargets.get(path) ?? [];
+  const isAgentPathCandidate =
+    path === WEBHOOK_PATHS.AGENT ||
+    path === WEBHOOK_PATHS.AGENT_PLUGIN ||
+    path.startsWith(`${WEBHOOK_PATHS.AGENT}/`) ||
+    path.startsWith(`${WEBHOOK_PATHS.AGENT_PLUGIN}/`);
+  const matchedAgentTargets = agentTargets.get(path) ?? [];
+  if (matchedAgentTargets.length > 0 || isAgentPathCandidate) {
+    const targets = matchedAgentTargets;
     if (targets.length > 0) {
       const query = resolveQueryParams(req);
       const timestamp = query.get("timestamp") ?? "";
@@ -1916,7 +2345,7 @@ export async function handleWecomWebhookRequest(req: IncomingMessage, res: Serve
     return true;
   }
 
-  // Bot 模式路由: /wecom, /wecom/bot
+  // Bot 模式路由: /plugins/wecom/bot（推荐）以及 /wecom、/wecom/bot（兼容）
   const targets = webhookTargets.get(path);
   if (!targets || targets.length === 0) return false;