@yanhaidao/wecom 2.0.0 → 2.0.1

package/README.md

@@ -10,6 +10,22 @@
 
 ![企业微信交流群](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/link-me.jpg)
 
+## 文件与图片入模（说明）
+
+图片/文件 URL 下载内容为加密数据，需使用 `EncodingAESKey` 解密后再解析并入模。
+
+## 测试页截图（文件上传 / 解析）
+
+> 图片过大可替换为压缩版（保持文件名不变即可）。
+
+![WeCom 测试页截图（文件上传 / 解析）](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/01.image.jpg)
+
+## A2UI 交互卡片（template_card）
+
+- Agent 输出 `{"template_card": ...}`（JSON）时：单聊且有 `response_url` 会发送交互卡片；群聊或无 `response_url` 自动降级为文本说明（不透出原始 JSON）。
+- 收到 `template_card_event` 时：会转换为伪文本消息触发 Agent，并基于 `msgid` 去重避免重复处理。
+- 卡片相关的示例/skill：加群获取（见上方交流群二维码）。
+
 ## 安装
 
 ### 从 npm 安装
@@ -19,21 +35,19 @@ openclaw plugins enable wecom
 openclaw gateway restart
 ```
 
-
 ## 配置结构参考
 
-```json5
+```json
 {
-  channels: {
-    wecom: {
-      enabled: true,
-      webhookPath: "/wecom",
-      token: "YOUR_TOKEN",
-      encodingAESKey: "YOUR_ENCODING_AES_KEY",
-      receiveId: "",
-      // stream 模式第一次回包占位符（默认 "正在思考..."）
-      streamPlaceholderContent: "正在思考...",
-      dm: { policy: "pairing" }
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "webhookPath": "/wecom",
+      "token": "YOUR_TOKEN",
+      "encodingAESKey": "YOUR_ENCODING_AES_KEY",
+      "receiveId": "",
+      "streamPlaceholderContent": "正在思考...",
+      "dm": { "policy": "pairing" }
     }
   }
 }
@@ -98,16 +112,10 @@ openclaw channels status
 
 # 更新日志
 
-## 2026.1.30
+## 2026.1.31
 
-### 重大变更
+- 文档：补充入模与测试截图说明。
 
-1. **项目更名**：Clawdbot 正式更名为 **OpenClaw**。CLI 命令由 `clawdbot` 变更为 `openclaw`。请更新您的安装脚本和文档引用。
-
-### 企业微信插件改进计划
+## 2026.1.30
 
-1. 引用回复纳入上下文：AI 将同时理解你引用的那条消息；文本原文直传，图片/文件/语音等以 `[引用: 类型] URL` 形式提供上下文线索。
-2. `<think>...</think>` 原样透传：不做过滤、转义或重排，确保支持该特性的企业微信客户端可稳定展示思考态 UI。
-3. 流式回复稳定性加固：减少空刷新、超时与“卡住不回”；异常时返回可见错误摘要而非无期限等待。
-4. 交付可验收：围绕入站解析、stream 状态与回包链路增强可观测性，方便客户侧定位问题并验证效果。
-5. 下一阶段（可选）：补齐图片闭环（加密图片解密入模 + 原生 stream `msg_item` 图片回传），实现图文对话体验。
+- 项目更名：Clawdbot → OpenClaw（CLI：`clawdbot` → `openclaw`）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanhaidao/wecom",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "type": "module",
   "description": "OpenClaw WeCom (WeChat Work) intelligent bot channel plugin",
   "author": "YanHaidao (VX: YanHaidao)",
@@ -38,4 +38,4 @@
   "peerDependencies": {
     "openclaw": ">=2026.1.26"
   }
-}
+}

package/src/media.ts

@@ -9,11 +9,13 @@ import { decodeEncodingAESKey, pkcs7Unpad, WECOM_PKCS7_BLOCK_SIZE } from "./cryp
  * The IV is the first 16 bytes of the AES Key.
  * The content is PKCS#7 padded.
  */
-export async function decryptWecomMedia(url: string, encodingAESKey: string): Promise<Buffer> {
+export async function decryptWecomMedia(url: string, encodingAESKey: string, maxBytes?: number): Promise<Buffer> {
     // 1. Download encrypted content
     const response = await axios.get(url, {
         responseType: "arraybuffer", // Important: get raw buffer
         timeout: 15000,
+        maxContentLength: maxBytes || undefined, // Limit download size
+        maxBodyLength: maxBytes || undefined,
     });
     const encryptedData = Buffer.from(response.data);
 

package/src/monitor.integration.test.ts

@@ -39,11 +39,11 @@ function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
     return Buffer.concat([buf, Buffer.alloc(pad, padByte[0]!)]);
 }
 
-	describe("Monitor Integration: Inbound Image", () => {
-	    const token = "MY_TOKEN";
-	    const encodingAESKey = "jWmYm7qr5nMoCAstdRmNjt3p7vsH8HkK+qiJqQ0aaaa="; // 32 bytes key
-	    const receiveId = "MY_CORPID";
-	    let unregisterTarget: (() => void) | null = null;
+describe("Monitor Integration: Inbound Image", () => {
+    const token = "MY_TOKEN";
+    const encodingAESKey = "jWmYm7qr5nMoCAstdRmNjt3p7vsH8HkK+qiJqQ0aaaa="; // 32 bytes key
+    const receiveId = "MY_CORPID";
+    let unregisterTarget: (() => void) | null = null;
 
     // Mock Core Runtime
     const mockDeliver = vi.fn();
@@ -76,15 +76,15 @@ function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
         logging: { shouldLogVerbose: () => true },
     };
 
-	    beforeEach(() => {
-	        vi.spyOn(runtime, "getWecomRuntime").mockReturnValue(mockCore as any);
+    beforeEach(() => {
+        vi.spyOn(runtime, "getWecomRuntime").mockReturnValue(mockCore as any);
 
-	        unregisterTarget?.();
-	        unregisterTarget = registerWecomWebhookTarget({
-	            account: {
-	                accountId: "test-acc",
-	                name: "Test",
-	                enabled: true,
+        unregisterTarget?.();
+        unregisterTarget = registerWecomWebhookTarget({
+            account: {
+                accountId: "test-acc",
+                name: "Test",
+                enabled: true,
                 configured: true,
                 token,
                 encodingAESKey,
@@ -92,21 +92,24 @@ function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
                 config: {} as any
             },
             config: {} as any,
-	            runtime: { log: console.log, error: console.error },
-	            core: mockCore as any,
-	            path: "/wecom"
-	        });
-	    });
-
-	    afterEach(() => {
-	        unregisterTarget?.();
-	        unregisterTarget = null;
-	        vi.restoreAllMocks();
-	    });
-
-    it("should decrypt inbound image and pass base64 to agent", async () => {
+            runtime: { log: console.log, error: console.error },
+            core: mockCore as any,
+            path: "/wecom"
+        });
+    });
+
+    afterEach(() => {
+        unregisterTarget?.();
+        unregisterTarget = null;
+        vi.restoreAllMocks();
+    });
+
+    // Mock media saving
+    const mockSaveMediaBuffer = vi.fn().mockResolvedValue({ path: "/tmp/saved-image.jpg", contentType: "image/jpeg" });
+    (mockCore.channel as any).media = { saveMediaBuffer: mockSaveMediaBuffer };
+
+    it("should decrypt inbound image, save it, and inject into context", async () => {
         // 1. Prepare Encrypted Media (The "File" on WeCom Server)
-        // We pretend this is the media data returned by axios
         const fileContent = Buffer.from("fake-image-data");
         const aesKey = Buffer.from(encodingAESKey + "=", "base64");
         const iv = aesKey.subarray(0, 16);
@@ -117,7 +120,7 @@ function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
         const encryptedMedia = Buffer.concat([cipher.update(pkcs7Pad(fileContent, WECOM_PKCS7_BLOCK_SIZE)), cipher.final()]);
 
         // Mock Axios to return this encrypted media
-        (axios.get as any).mockResolvedValue({ data: encryptedMedia });
+        (axios.get as any).mockResolvedValue({ data: encryptedMedia, headers: { "content-length": "100" } });
 
         // 2. Prepare Inbound Message (The Webhook JSON)
         const imageUrl = "http://wecom.server/media/123";
@@ -155,17 +158,33 @@ function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
 
         await handleWecomWebhookRequest(req, res);
 
+        // Wait for debounce timer to trigger agent (DEFAULT_DEBOUNCE_MS = 500ms)
+        await new Promise(resolve => setTimeout(resolve, 600));
+
         // 5. Verify
-        // Check recordInboundSession was called with correct RawBody
+        // Check recordInboundSession was called with correct RawBody and Media Context
+        expect(mockCore.channel.session.recordInboundSession).toHaveBeenCalled();
         const recordCall = (mockCore.channel.session.recordInboundSession as any).mock.calls[0][0];
-        const rawBody = recordCall.ctx.RawBody;
-
-        // Expect: [image] data:image/jpeg;base64,...
-        expect(rawBody).toContain("[image] data:image/jpeg;base64,");
-        const base64Part = rawBody.split("base64,")[1];
-        const decoded = Buffer.from(base64Part, "base64");
-
-        expect(decoded.toString()).toBe("fake-image-data");
-        expect(axios.get).toHaveBeenCalledWith(imageUrl, expect.anything());
+        const ctx = recordCall.ctx;
+
+        // Expect: [image]
+        expect(ctx.RawBody).toBe("[image]");
+
+        // Expect media to be saved
+        expect(mockSaveMediaBuffer).toHaveBeenCalledWith(
+            expect.any(Buffer), // The decrypted buffer
+            "image/jpeg",
+            "inbound",
+            expect.any(Number), // maxBytes
+            "image.jpg"
+        );
+        const savedBuffer = mockSaveMediaBuffer.mock.calls[0][0];
+        expect(savedBuffer.toString()).toBe("fake-image-data");
+
+        // Expect Context Injection
+        expect(ctx.MediaPath).toBe("/tmp/saved-image.jpg");
+        expect(ctx.MediaType).toBe("image/jpeg");
+
+        expect(axios.get).toHaveBeenCalledWith(imageUrl, expect.objectContaining({ responseType: "arraybuffer" }));
     });
 });

package/src/monitor.ts

@@ -33,15 +33,31 @@ type StreamState = {
   finished: boolean;
   error?: string;
   content: string;
-  image?: { base64: string; md5: string };
+  images?: { base64: string; md5: string }[];
 };
 
 const webhookTargets = new Map<string, WecomWebhookTarget[]>();
 const streams = new Map<string, StreamState>();
 const msgidToStreamId = new Map<string, string>();
 
+// 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 STREAM_MAX_BYTES = 20_480;
+const DEFAULT_DEBOUNCE_MS = 500;
 
 function normalizeWebhookPath(raw: string): string {
   const trimmed = raw.trim();
@@ -179,11 +195,11 @@ function buildStreamReplyFromState(state: StreamState): { msgtype: "stream"; str
       id: state.streamId,
       finish: state.finished,
       content,
-      ...(state.finished && state.image ? {
-        msg_item: [{
+      ...(state.finished && state.images?.length ? {
+        msg_item: state.images.map(img => ({
           msgtype: "image",
-          image: { base64: state.image.base64, md5: state.image.md5 }
-        }]
+          image: { base64: img.base64, md5: img.md5 }
+        }))
       } : {})
     },
   };
@@ -194,11 +210,17 @@ function createStreamId(): string {
 }
 
 function logVerbose(target: WecomWebhookTarget, message: string): void {
-  const core = target.core;
-  const should = core.logging?.shouldLogVerbose?.() ?? false;
-  if (should) {
-    target.runtime.log?.(`[wecom] ${message}`);
-  }
+  const should =
+    target.core.logging?.shouldLogVerbose?.() ??
+    (() => {
+      try {
+        return getWecomRuntime().logging.shouldLogVerbose();
+      } catch {
+        return false;
+      }
+    })();
+  if (!should) return;
+  target.runtime.log?.(`[wecom] ${message}`);
 }
 
 function parseWecomPlainMessage(raw: string): WecomInboundMessage {
@@ -209,24 +231,164 @@ function parseWecomPlainMessage(raw: string): WecomInboundMessage {
   return parsed as WecomInboundMessage;
 }
 
-async function processInboundMessage(target: WecomWebhookTarget, msg: WecomInboundMessage): Promise<string> {
+type InboundResult = {
+  body: string;
+  media?: {
+    buffer: Buffer;
+    contentType: string;
+    filename: string;
+  };
+};
+
+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 maxBytes = mediaMaxMb * 1024 * 1024;
 
   if (msgtype === "image") {
     const url = String((msg as any).image?.url ?? "").trim();
-    const aesKey = target.account.encodingAESKey;
     if (url && aesKey) {
       try {
-        const buf = await decryptWecomMedia(url, aesKey);
-        const base64 = buf.toString("base64");
-        return `[image] data:image/jpeg;base64,${base64}`;
+        const buf = await decryptWecomMedia(url, aesKey, maxBytes);
+        return {
+          body: "[image]",
+          media: {
+            buffer: buf,
+            contentType: "image/jpeg", // WeCom images are usually generic; safest assumption or could act as generic
+            filename: "image.jpg",
+          }
+        };
       } catch (err) {
         target.runtime.error?.(`Failed to decrypt inbound image: ${String(err)}`);
-        return `[image] (decryption failed)`;
+        return { body: `[image] (decryption failed: ${typeof err === 'object' && err ? (err as any).message : String(err)})` };
+      }
+    }
+  }
+
+  if (msgtype === "file") {
+    const url = String((msg as any).file?.url ?? "").trim();
+    if (url && aesKey) {
+      try {
+        const buf = await decryptWecomMedia(url, aesKey, maxBytes);
+        return {
+          body: "[file]",
+          media: {
+            buffer: buf,
+            contentType: "application/octet-stream",
+            filename: "file.bin", // WeCom doesn't guarantee filename in webhook payload always, defaulting
+          }
+        };
+      } catch (err) {
+        target.runtime.error?.(`Failed to decrypt inbound file: ${String(err)}`);
+        return { body: `[file] (decryption failed: ${typeof err === 'object' && err ? (err as any).message : String(err)})` };
       }
     }
   }
-  return buildInboundBody(msg);
+
+  // Mixed message handling: extract first media if available
+  if (msgtype === "mixed") {
+    const items = (msg as any).mixed?.msg_item;
+    if (Array.isArray(items)) {
+      let foundMedia: InboundResult["media"] | undefined = undefined;
+      let bodyParts: string[] = [];
+
+      for (const item of items) {
+        const t = String(item.msgtype ?? "").toLowerCase();
+        if (t === "text") {
+          const content = String(item.text?.content ?? "").trim();
+          if (content) bodyParts.push(content);
+        } else if ((t === "image" || t === "file") && !foundMedia && aesKey) {
+          // Found first media, try to download
+          const url = String(item[t]?.url ?? "").trim();
+          if (url) {
+            try {
+              const buf = await decryptWecomMedia(url, aesKey, maxBytes);
+              foundMedia = {
+                buffer: buf,
+                contentType: t === "image" ? "image/jpeg" : "application/octet-stream",
+                filename: t === "image" ? "image.jpg" : "file.bin"
+              };
+              bodyParts.push(`[${t}]`);
+            } catch (err) {
+              target.runtime.error?.(`Failed to decrypt mixed ${t}: ${String(err)}`);
+              bodyParts.push(`[${t}] (decryption failed)`);
+            }
+          } else {
+            bodyParts.push(`[${t}]`);
+          }
+        } else {
+          // Other items or already found media -> just placeholder
+          bodyParts.push(`[${t}]`);
+        }
+      }
+      return {
+        body: bodyParts.join("\n"),
+        media: foundMedia
+      };
+    }
+  }
+
+  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;
+
+  // Merge all message contents (each is already formatted by buildInboundBody)
+  const mergedContents = contents.filter(c => c.trim()).join("\n").trim();
+
+  let core: PluginRuntime | null = null;
+  try {
+    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();
+    }
+    return;
+  }
+
+  if (core) {
+    const state = streams.get(streamId);
+    if (state) state.started = true;
+    const enrichedTarget: WecomWebhookTarget = { ...target, core };
+    logVerbose(target, `flush pending: starting agent for ${contents.length} merged messages`);
+
+    // Pass the first msg (with its media structure), and mergedContents for multi-message context
+    startAgentForStream({
+      target: enrichedTarget,
+      accountId: target.account.accountId,
+      msg,
+      streamId,
+      mergedContents: contents.length > 1 ? mergedContents : undefined,
+      mergedMsgids: msgids.length > 1 ? msgids : undefined,
+    }).catch((err) => {
+      const state = streams.get(streamId);
+      if (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)}`);
+    });
+  }
 }
 
 async function waitForStreamContent(streamId: string, maxWaitMs: number): Promise<void> {
@@ -250,6 +412,8 @@ async function startAgentForStream(params: {
   accountId: string;
   msg: WecomInboundMessage;
   streamId: string;
+  mergedContents?: string; // Combined content from debounced messages
+  mergedMsgids?: string[];
 }): Promise<void> {
   const { target, msg, streamId } = params;
   const core = target.core;
@@ -259,7 +423,29 @@ async function startAgentForStream(params: {
   const userid = msg.from?.userid?.trim() || "unknown";
   const chatType = msg.chattype === "group" ? "group" : "direct";
   const chatId = msg.chattype === "group" ? (msg.chatid?.trim() || "unknown") : userid;
-  const rawBody = await processInboundMessage(target, msg);
+  // 1. Process inbound message (decrypt media if any)
+  const { body: rawBody, media } = await processInboundMessage(target, msg);
+
+  // 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 saved = await core.channel.media.saveMediaBuffer(
+        media.buffer,
+        media.contentType,
+        "inbound",
+        maxBytes,
+        media.filename
+      );
+      mediaPath = saved.path;
+      mediaType = saved.contentType;
+      logVerbose(target, `saved inbound media to ${mediaPath} (${mediaType})`);
+    } catch (err) {
+      target.runtime.error?.(`Failed to save inbound media: ${String(err)}`);
+    }
+  }
 
   const route = core.channel.routing.resolveAgentRoute({
     cfg: config,
@@ -304,6 +490,9 @@ async function startAgentForStream(params: {
     MessageSid: msg.msgid,
     OriginatingChannel: "wecom",
     OriginatingTo: `wecom:${chatId}`,
+    MediaPath: mediaPath,
+    MediaType: mediaType,
+    MediaUrl: mediaPath, // Local path for now
   });
 
   await core.channel.session.recordInboundSession({
@@ -336,6 +525,40 @@ async function startAgentForStream(params: {
           return `__THINK_PLACEHOLDER_${thinks.length - 1}__`;
         });
 
+        // [A2UI] Detect template_card JSON output from Agent
+        const trimmedText = text.trim();
+        if (trimmedText.startsWith("{") && trimmedText.includes('"template_card"')) {
+          try {
+            const parsed = JSON.parse(trimmedText);
+            if (parsed.template_card) {
+              const current = streams.get(streamId);
+              const isSingleChat = msg.chattype !== "group";
+              const hasResponseUrl = current?.response_url;
+
+              if (hasResponseUrl && isSingleChat) {
+                // 单聊且有 response_url：发送卡片
+                await axios.post(current!.response_url!, {
+                  msgtype: "template_card",
+                  template_card: parsed.template_card,
+                });
+                logVerbose(target, `sent template_card: task_id=${parsed.template_card.task_id}`);
+                current.finished = true;
+                current.content = "[已发送交互卡片]";
+                current.updatedAt = Date.now();
+                target.statusSink?.({ lastOutboundAt: Date.now() });
+                return;
+              } else {
+                // 群聊 或 无 response_url：降级为文本描述
+                logVerbose(target, `template_card fallback to text (group=${!isSingleChat}, hasUrl=${!!hasResponseUrl})`);
+                const cardTitle = parsed.template_card.main_title?.title || "交互卡片";
+                const cardDesc = parsed.template_card.main_title?.desc || "";
+                const buttons = parsed.template_card.button_list?.map((b: any) => b.text).join(" / ") || "";
+                text = `📋 **${cardTitle}**${cardDesc ? `\n${cardDesc}` : ""}${buttons ? `\n\n选项: ${buttons}` : ""}`;
+              }
+            }
+          } catch { /* parse fail, use normal text */ }
+        }
+
         text = core.channel.text.convertMarkdownTables(text, tableMode);
 
         // Restore <think> tags
@@ -346,18 +569,43 @@ async function startAgentForStream(params: {
         const current = streams.get(streamId);
         if (!current) return;
 
-        // Detect Markdown image: ![alt](url)
-        const imgMatch = text.match(/!\[.*?\]\((https?:\/\/.*?)\)/);
-        if (imgMatch && imgMatch[1]) {
+        if (!current.images) current.images = [];
+
+        const mediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
+        for (const mediaPath of mediaUrls) {
           try {
-            const imgUrl = imgMatch[1];
-            const resp = await axios.get(imgUrl, { responseType: "arraybuffer", timeout: 10000 });
-            const buf = Buffer.from(resp.data);
-            const base64 = buf.toString("base64");
-            const md5 = crypto.createHash("md5").update(buf).digest("hex");
-            current.image = { base64, md5 };
+            let buf: Buffer;
+            let contentType: string | undefined;
+            let filename: string;
+
+            const looksLikeUrl = /^https?:\/\//i.test(mediaPath);
+
+            if (looksLikeUrl) {
+              const loaded = await core.channel.media.fetchRemoteMedia(mediaPath, {
+                maxBytes: 10 * 1024 * 1024,
+              });
+              buf = loaded.buffer;
+              contentType = loaded.contentType;
+              filename = loaded.filename ?? "attachment";
+            } else {
+              const fs = await import("node:fs/promises");
+              const pathModule = await import("node:path");
+              buf = await fs.readFile(mediaPath);
+              filename = pathModule.basename(mediaPath);
+              const ext = pathModule.extname(mediaPath).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" };
+              contentType = imageExts[ext] ?? "application/octet-stream";
+            }
+
+            if (contentType?.startsWith("image/")) {
+              const base64 = buf.toString("base64");
+              const md5 = crypto.createHash("md5").update(buf).digest("hex");
+              current.images.push({ base64, md5 });
+            } else {
+              text += `\n\n[File: ${filename}]`;
+            }
           } catch (err) {
-            target.runtime.error?.(`Failed to download outbound image: ${String(err)}`);
+            target.runtime.error?.(`Failed to process outbound media: ${mediaPath}: ${String(err)}`);
           }
         }
 
@@ -383,12 +631,8 @@ async function startAgentForStream(params: {
 
 function formatQuote(quote: WecomInboundQuote): string {
   const type = quote.msgtype ?? "";
-  if (type === "text") {
-    return quote.text?.content || "";
-  }
-  if (type === "image") {
-    return `[引用: 图片] ${quote.image?.url || ""}`;
-  }
+  if (type === "text") return quote.text?.content || "";
+  if (type === "image") return `[引用: 图片] ${quote.image?.url || ""}`;
   if (type === "mixed" && quote.mixed?.msg_item) {
     const items = quote.mixed.msg_item.map((item) => {
       if (item.msgtype === "text") return item.text?.content;
@@ -397,12 +641,8 @@ function formatQuote(quote: WecomInboundQuote): string {
     }).filter(Boolean).join(" ");
     return `[引用: 图文] ${items}`;
   }
-  if (type === "voice") {
-    return `[引用: 语音] ${quote.voice?.content || ""}`;
-  }
-  if (type === "file") {
-    return `[引用: 文件] ${quote.file?.url || ""}`;
-  }
+  if (type === "voice") return `[引用: 语音] ${quote.voice?.content || ""}`;
+  if (type === "file") return `[引用: 文件] ${quote.file?.url || ""}`;
   return "";
 }
 
@@ -410,50 +650,28 @@ function buildInboundBody(msg: WecomInboundMessage): string {
   let body = "";
   const msgtype = String(msg.msgtype ?? "").toLowerCase();
 
-  if (msgtype === "text") {
-    const content = (msg as any).text?.content;
-    body = typeof content === "string" ? content : "";
-  } else if (msgtype === "voice") {
-    const content = (msg as any).voice?.content;
-    body = typeof content === "string" ? content : "[voice]";
-  } else if (msgtype === "mixed") {
+  if (msgtype === "text") body = (msg as any).text?.content || "";
+  else if (msgtype === "voice") body = (msg as any).voice?.content || "[voice]";
+  else if (msgtype === "mixed") {
     const items = (msg as any).mixed?.msg_item;
     if (Array.isArray(items)) {
-      body = items
-        .map((item: any) => {
-          const t = String(item?.msgtype ?? "").toLowerCase();
-          if (t === "text") return String(item?.text?.content ?? "");
-          if (t === "image") return `[image] ${String(item?.image?.url ?? "").trim()}`.trim();
-          return `[${t || "item"}]`;
-        })
-        .filter((part: string) => Boolean(part && part.trim()))
-        .join("\n");
-    } else {
-      body = "[mixed]";
-    }
-  } else if (msgtype === "image") {
-    const url = String((msg as any).image?.url ?? "").trim();
-    body = url ? `[image] ${url}` : "[image]";
-  } else if (msgtype === "file") {
-    const url = String((msg as any).file?.url ?? "").trim();
-    body = url ? `[file] ${url}` : "[file]";
-  } else if (msgtype === "event") {
-    const eventtype = String((msg as any).event?.eventtype ?? "").trim();
-    body = eventtype ? `[event] ${eventtype}` : "[event]";
-  } else if (msgtype === "stream") {
-    const id = String((msg as any).stream?.id ?? "").trim();
-    body = id ? `[stream_refresh] ${id}` : "[stream_refresh]";
-  } else {
-    body = msgtype ? `[${msgtype}]` : "";
-  }
+      body = items.map((item: any) => {
+        const t = String(item?.msgtype ?? "").toLowerCase();
+        if (t === "text") return item?.text?.content || "";
+        if (t === "image") return `[image] ${item?.image?.url || ""}`;
+        return `[${t || "item"}]`;
+      }).filter(Boolean).join("\n");
+    } else body = "[mixed]";
+  } else if (msgtype === "image") body = `[image] ${(msg as any).image?.url || ""}`;
+  else if (msgtype === "file") body = `[file] ${(msg as any).file?.url || ""}`;
+  else if (msgtype === "event") body = `[event] ${(msg as any).event?.eventtype || ""}`;
+  else if (msgtype === "stream") body = `[stream_refresh] ${(msg as any).stream?.id || ""}`;
+  else body = msgtype ? `[${msgtype}]` : "";
 
-  // Append quote if available
   const quote = (msg as any).quote;
   if (quote) {
     const quoteText = formatQuote(quote).trim();
-    if (quoteText) {
-      body += `\n\n> ${quoteText}`;
-    }
+    if (quoteText) body += `\n\n> ${quoteText}`;
   }
   return body;
 }
@@ -462,8 +680,7 @@ export function registerWecomWebhookTarget(target: WecomWebhookTarget): () => vo
   const key = normalizeWebhookPath(target.path);
   const normalizedTarget = { ...target, path: key };
   const existing = webhookTargets.get(key) ?? [];
-  const next = [...existing, normalizedTarget];
-  webhookTargets.set(key, next);
+  webhookTargets.set(key, [...existing, normalizedTarget]);
   return () => {
     const updated = (webhookTargets.get(key) ?? []).filter((entry) => entry !== normalizedTarget);
     if (updated.length > 0) webhookTargets.set(key, updated);
@@ -471,12 +688,8 @@ export function registerWecomWebhookTarget(target: WecomWebhookTarget): () => vo
   };
 }
 
-export async function handleWecomWebhookRequest(
-  req: IncomingMessage,
-  res: ServerResponse,
-): Promise<boolean> {
+export async function handleWecomWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
   pruneStreams();
-
   const path = resolvePath(req);
   const targets = webhookTargets.get(path);
   if (!targets || targets.length === 0) return false;
@@ -486,282 +699,139 @@ export async function handleWecomWebhookRequest(
   const nonce = query.get("nonce") ?? "";
   const signature = resolveSignatureParam(query);
 
-  const firstTarget = targets[0]!;
-  logVerbose(firstTarget, `incoming ${req.method} request on ${path} (timestamp=${timestamp}, nonce=${nonce}, signature=${signature})`);
-
   if (req.method === "GET") {
     const echostr = query.get("echostr") ?? "";
-    if (!timestamp || !nonce || !signature || !echostr) {
-      logVerbose(firstTarget, "GET request missing query params");
-      res.statusCode = 400;
-      res.end("missing query params");
-      return true;
-    }
-    const target = targets.find((candidate) => {
-      if (!candidate.account.configured || !candidate.account.token) return false;
-      const ok = verifyWecomSignature({
-        token: candidate.account.token,
-        timestamp,
-        nonce,
-        encrypt: echostr,
-        signature,
-      });
-      if (!ok) {
-        logVerbose(candidate, `signature verification failed for echostr (token=${candidate.account.token?.slice(0, 4)}...)`);
-      }
-      return ok;
-    });
+    const target = targets.find(c => c.account.token && verifyWecomSignature({ token: c.account.token, timestamp, nonce, encrypt: echostr, signature }));
     if (!target || !target.account.encodingAESKey) {
-      logVerbose(firstTarget, "no matching target for GET signature");
       res.statusCode = 401;
       res.end("unauthorized");
       return true;
     }
     try {
-      const plain = decryptWecomEncrypted({
-        encodingAESKey: target.account.encodingAESKey,
-        receiveId: target.account.receiveId,
-        encrypt: echostr,
-      });
-      logVerbose(target, "GET echostr decrypted successfully");
+      const plain = decryptWecomEncrypted({ encodingAESKey: target.account.encodingAESKey, receiveId: target.account.receiveId, encrypt: echostr });
       res.statusCode = 200;
       res.setHeader("Content-Type", "text/plain; charset=utf-8");
       res.end(plain);
       return true;
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      logVerbose(target, `GET decrypt failed: ${msg}`);
       res.statusCode = 400;
-      res.end(msg || "decrypt failed");
+      res.end("decrypt failed");
       return true;
     }
   }
 
-  if (req.method !== "POST") {
-    res.statusCode = 405;
-    res.setHeader("Allow", "GET, POST");
-    res.end("Method Not Allowed");
-    return true;
-  }
-
-  if (!timestamp || !nonce || !signature) {
-    logVerbose(firstTarget, "POST request missing query params");
-    res.statusCode = 400;
-    res.end("missing query params");
-    return true;
-  }
+  if (req.method !== "POST") return false;
 
   const body = await readJsonBody(req, 1024 * 1024);
   if (!body.ok) {
-    logVerbose(firstTarget, `POST body read failed: ${body.error}`);
-    res.statusCode = body.error === "payload too large" ? 413 : 400;
-    res.end(body.error ?? "invalid payload");
-    return true;
-  }
-  const record = body.value && typeof body.value === "object" ? (body.value as Record<string, unknown>) : null;
-  const encrypt = record ? String(record.encrypt ?? record.Encrypt ?? "") : "";
-  if (!encrypt) {
-    logVerbose(firstTarget, "POST request missing encrypt field in body");
     res.statusCode = 400;
-    res.end("missing encrypt");
+    res.end(body.error || "invalid payload");
     return true;
   }
-
-  // Find the first target that validates the signature.
-  const target = targets.find((candidate) => {
-    if (!candidate.account.token) return false;
-    const ok = verifyWecomSignature({
-      token: candidate.account.token,
-      timestamp,
-      nonce,
-      encrypt,
-      signature,
-    });
-    if (!ok) {
-      logVerbose(candidate, `signature verification failed for POST (token=${candidate.account.token?.slice(0, 4)}...)`);
-    }
-    return ok;
-  });
-  if (!target) {
-    logVerbose(firstTarget, "no matching target for POST signature");
+  const record = body.value as any;
+  const encrypt = String(record?.encrypt ?? record?.Encrypt ?? "");
+  const target = targets.find(c => c.account.token && verifyWecomSignature({ token: c.account.token, timestamp, nonce, encrypt, signature }));
+  if (!target || !target.account.configured || !target.account.encodingAESKey) {
     res.statusCode = 401;
     res.end("unauthorized");
     return true;
   }
 
-  if (!target.account.configured || !target.account.token || !target.account.encodingAESKey) {
-    logVerbose(target, "target found but not fully configured");
-    res.statusCode = 500;
-    res.end("wecom not configured");
-    return true;
-  }
-
   let plain: string;
   try {
-    plain = decryptWecomEncrypted({
-      encodingAESKey: target.account.encodingAESKey,
-      receiveId: target.account.receiveId,
-      encrypt,
-    });
-    logVerbose(target, `decrypted POST message: ${plain}`);
+    plain = decryptWecomEncrypted({ encodingAESKey: target.account.encodingAESKey, receiveId: target.account.receiveId, encrypt });
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    logVerbose(target, `POST decrypt failed: ${msg}`);
     res.statusCode = 400;
-    res.end(msg || "decrypt failed");
+    res.end("decrypt failed");
     return true;
   }
 
   const msg = parseWecomPlainMessage(plain);
-  target.statusSink?.({ lastInboundAt: Date.now() });
-
   const msgtype = String(msg.msgtype ?? "").toLowerCase();
-  const msgid = msg.msgid ? String(msg.msgid) : undefined;
 
-  // Stream refresh callback: reply with current state (if any).
-  if (msgtype === "stream") {
-    const streamId = String((msg as any).stream?.id ?? "").trim();
-    const state = streamId ? streams.get(streamId) : undefined;
-    if (state) logVerbose(target, `stream refresh streamId=${streamId} started=${state.started} finished=${state.finished}`);
-    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;
-  }
-
-  // Dedupe: if we already created a stream for this msgid, return placeholder again.
-  if (msgid && msgidToStreamId.has(msgid)) {
-    const streamId = msgidToStreamId.get(msgid) ?? "";
-    const reply = buildStreamPlaceholderReply({
-      streamId,
-      placeholderContent: target.account.config.streamPlaceholderContent,
-    });
-    jsonOk(res, buildEncryptedJsonReply({
-      account: target.account,
-      plaintextJson: reply,
-      nonce,
-      timestamp,
-    }));
-    return true;
-  }
-
-  // enter_chat welcome event: optionally reply with text (allowed by spec).
+  // Handle Event
   if (msgtype === "event") {
     const eventtype = String((msg as any).event?.eventtype ?? "").toLowerCase();
+
+    if (eventtype === "template_card_event") {
+      const msgid = msg.msgid ? String(msg.msgid) : undefined;
+
+      // Dedupe: skip if already processed this event
+      if (msgid && msgidToStreamId.has(msgid)) {
+        logVerbose(target, `template_card_event: already processed msgid=${msgid}, skipping`);
+        jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: {}, nonce, timestamp }));
+        return true;
+      }
+
+      const cardEvent = (msg as any).event?.template_card_event;
+      let interactionDesc = `[卡片交互] 按钮: ${cardEvent?.event_key || "unknown"}`;
+      if (cardEvent?.selected_items?.selected_item?.length) {
+        const selects = cardEvent.selected_items.selected_item.map((i: any) => `${i.question_key}=${i.option_ids?.option_id?.join(",")}`);
+        interactionDesc += ` 选择: ${selects.join("; ")}`;
+      }
+      if (cardEvent?.task_id) interactionDesc += ` (任务ID: ${cardEvent.task_id})`;
+
+      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, response_url: msg.response_url, createdAt: Date.now(), updatedAt: Date.now(), started: true, finished: false, content: "" });
+      const core = getWecomRuntime();
+      startAgentForStream({
+        target: { ...target, core },
+        accountId: target.account.accountId,
+        msg: { ...msg, msgtype: "text", text: { content: interactionDesc } } as any,
+        streamId,
+      }).catch(err => target.runtime.error?.(`interaction failed: ${String(err)}`));
+      return true;
+    }
+
     if (eventtype === "enter_chat") {
       const welcome = target.account.config.welcomeText?.trim();
-      const reply = welcome
-        ? { msgtype: "text", text: { content: welcome } }
-        : {};
-      jsonOk(res, buildEncryptedJsonReply({
-        account: target.account,
-        plaintextJson: reply,
-        nonce,
-        timestamp,
-      }));
+      jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: welcome ? { msgtype: "text", text: { content: welcome } } : {}, nonce, timestamp }));
       return true;
     }
 
-    // For other events, reply empty to avoid timeouts.
-    jsonOk(res, buildEncryptedJsonReply({
-      account: target.account,
-      plaintextJson: {},
-      nonce,
-      timestamp,
-    }));
+    jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: {}, nonce, timestamp }));
     return true;
   }
 
-  // Default: respond with a stream placeholder and compute the actual reply async.
-  const streamId = createStreamId();
-  if (msgid) msgidToStreamId.set(msgid, streamId);
-  streams.set(streamId, {
-    streamId,
-    msgid,
-    response_url: msg.response_url,
-    createdAt: Date.now(),
-    updatedAt: Date.now(),
-    started: false,
-    finished: false,
-    content: "",
-  });
-
-  // Kick off agent processing in the background.
-  let core: PluginRuntime | null = null;
-  try {
-    core = getWecomRuntime();
-  } catch (err) {
-    // If runtime is not ready, we can't process the agent, but we should still
-    // return the placeholder if possible, or handle it as a background error.
-    logVerbose(target, `runtime not ready, skipping agent processing: ${String(err)}`);
+  // Handle Stream Refresh
+  if (msgtype === "stream") {
+    const streamId = String((msg as any).stream?.id ?? "").trim();
+    const state = streams.get(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;
   }
 
-  if (core) {
-    streams.get(streamId)!.started = true;
-    const enrichedTarget: WecomWebhookTarget = { ...target, core };
-    startAgentForStream({ target: enrichedTarget, accountId: target.account.accountId, msg, streamId }).catch((err) => {
-      const state = streams.get(streamId);
-      if (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)}`);
-    });
-  } else {
-    // In tests or uninitialized state, we might not have a core.
-    // We mark it as finished to avoid hanging, but don't set an error content
-    // immediately if we want to return the placeholder "1".
-    const state = streams.get(streamId);
-    if (state) {
-      state.finished = true;
-      state.updatedAt = Date.now();
-    }
+  // 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 to include a first chunk in the initial response (matches WeCom demo behavior).
-  // If nothing is ready quickly, fall back to the placeholder "1".
-  await waitForStreamContent(streamId, 800);
-  const state = streams.get(streamId);
-  const initialReply = state && (state.content.trim() || state.error)
-    ? buildStreamReplyFromState(state)
-    : buildStreamPlaceholderReply({
-      streamId,
-      placeholderContent: target.account.config.streamPlaceholderContent,
-    });
-  jsonOk(res, buildEncryptedJsonReply({
-    account: target.account,
-    plaintextJson: initialReply,
-    nonce,
-    timestamp,
-  }));
-
-  logVerbose(target, `accepted msgtype=${msgtype || "unknown"} msgid=${msgid || "none"} streamId=${streamId}`);
+  const streamId = createStreamId();
+  if (msg.msgid) msgidToStreamId.set(msg.msgid, streamId);
+  streams.set(streamId, { streamId, msgid: msg.msgid, response_url: msg.response_url, createdAt: Date.now(), updatedAt: Date.now(), started: false, finished: false, content: "" });
+  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) });
+
+  jsonOk(res, buildEncryptedJsonReply({ account: target.account, plaintextJson: buildStreamPlaceholderReply({ streamId, placeholderContent: target.account.config.streamPlaceholderContent }), nonce, timestamp }));
   return true;
 }
 
 export async function sendActiveMessage(streamId: string, content: string): Promise<void> {
   const state = streams.get(streamId);
-  if (!state || !state.response_url) {
-    throw new Error(`Active message failed: No response_url for stream ${streamId}`);
-  }
-
-  // WeCom Webhook Reply Format
-  // Note: Only works if response_url is valid and within time limit.
-  await axios.post(state.response_url, {
-    msgtype: "text",
-    text: { content },
-  });
-}
+  if (!state || !state.response_url) throw new Error(`No response_url for stream ${streamId}`);
+  await axios.post(state.response_url, { msgtype: "text", text: { content } });
+}

package/src/types.ts

@@ -91,3 +91,69 @@ export type WecomInboundMessage =
   | WecomInboundStreamRefresh
   | WecomInboundEvent
   | (WecomInboundBase & { quote?: WecomInboundQuote } & Record<string, unknown>);
+
+export type WecomTemplateCard = {
+  card_type: "text_notice" | "news_notice" | "button_interaction" | "vote_interaction" | "multiple_interaction";
+  source?: { icon_url?: string; desc?: string; desc_color?: number };
+  main_title?: { title?: string; desc?: string };
+  task_id?: string;
+  button_list?: Array<{ text: string; style?: number; key: string }>;
+  sub_title_text?: string;
+  horizontal_content_list?: Array<{ keyname: string; value?: string; type?: number; url?: string; userid?: string }>;
+  card_action?: { type: number; url?: string; appid?: string; pagepath?: string };
+  action_menu?: { desc: string; action_list: Array<{ text: string; key: string }> };
+  select_list?: Array<{
+    question_key: string;
+    title?: string;
+    selected_id?: string;
+    option_list: Array<{ id: string; text: string }>;
+  }>;
+  submit_button?: { text: string; key: string };
+  checkbox?: {
+    question_key: string;
+    option_list: Array<{ id: string; text: string; is_checked?: boolean }>;
+    mode?: number;
+  };
+};
+
+export type WecomInboundTemplateCardEvent = WecomInboundBase & {
+  msgtype: "event";
+  event: {
+    eventtype: "template_card_event";
+    template_card_event: {
+      card_type: string;
+      event_key: string;
+      task_id: string;
+      selected_items?: {
+        selected_item: Array<{
+          question_key: string;
+          option_ids: { option_id: string[] };
+        }>;
+      };
+    };
+  };
+};
+
+
+/**
+ * Template card event payload (button click, checkbox, select)
+ */
+export type WecomTemplateCardEventPayload = {
+  card_type: string;
+  event_key: string;
+  task_id: string;
+  response_code?: string;
+  selected_items?: {
+    question_key?: string;
+    option_ids?: string[];
+  };
+};
+
+/**
+ * Outbound message types that can be sent via response_url
+ */
+export type WecomOutboundMessage =
+  | { msgtype: "text"; text: { content: string } }
+  | { msgtype: "markdown"; markdown: { content: string } }
+  | { msgtype: "template_card"; template_card: WecomTemplateCard };
+