@yanhaidao/wecom 1.0.1 → 2.0.1

package/src/monitor.ts

@@ -1,11 +1,13 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import crypto from "node:crypto";
 
-import type { ClawdbotConfig, PluginRuntime } from "clawdbot/plugin-sdk";
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
 
-import type { ResolvedWecomAccount, WecomInboundMessage } from "./types.js";
+import type { ResolvedWecomAccount, WecomInboundMessage, WecomInboundQuote } from "./types.js";
 import { decryptWecomEncrypted, encryptWecomPlaintext, verifyWecomSignature, computeWecomMsgSignature } from "./crypto.js";
 import { getWecomRuntime } from "./runtime.js";
+import { decryptWecomMedia } from "./media.js";
+import axios from "axios";
 
 export type WecomRuntimeEnv = {
   log?: (message: string) => void;
@@ -14,7 +16,7 @@ export type WecomRuntimeEnv = {
 
 type WecomWebhookTarget = {
   account: ResolvedWecomAccount;
-  config: ClawdbotConfig;
+  config: OpenClawConfig;
   runtime: WecomRuntimeEnv;
   core: PluginRuntime;
   path: string;
@@ -24,20 +26,38 @@ type WecomWebhookTarget = {
 type StreamState = {
   streamId: string;
   msgid?: string;
+  response_url?: string;
   createdAt: number;
   updatedAt: number;
   started: boolean;
   finished: boolean;
   error?: string;
   content: 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();
@@ -151,14 +171,18 @@ function resolveSignatureParam(params: URLSearchParams): string {
   );
 }
 
-function buildStreamPlaceholderReply(streamId: string): { msgtype: "stream"; stream: { id: string; finish: boolean; content: string } } {
+function buildStreamPlaceholderReply(params: {
+  streamId: string;
+  placeholderContent?: string;
+}): { msgtype: "stream"; stream: { id: string; finish: boolean; content: string } } {
+  const content = params.placeholderContent?.trim() || "1";
   return {
     msgtype: "stream",
     stream: {
-      id: streamId,
+      id: params.streamId,
       finish: false,
       // Spec: "第一次回复内容为 1" works as a minimal placeholder.
-      content: "1",
+      content,
     },
   };
 }
@@ -171,6 +195,12 @@ function buildStreamReplyFromState(state: StreamState): { msgtype: "stream"; str
       id: state.streamId,
       finish: state.finished,
       content,
+      ...(state.finished && state.images?.length ? {
+        msg_item: state.images.map(img => ({
+          msgtype: "image",
+          image: { base64: img.base64, md5: img.md5 }
+        }))
+      } : {})
     },
   };
 }
@@ -180,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 {
@@ -195,6 +231,166 @@ function parseWecomPlainMessage(raw: string): WecomInboundMessage {
   return parsed as WecomInboundMessage;
 }
 
+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();
+    if (url && aesKey) {
+      try {
+        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 { 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)})` };
+      }
+    }
+  }
+
+  // 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> {
   if (maxWaitMs <= 0) return;
   const startedAt = Date.now();
@@ -202,7 +398,8 @@ async function waitForStreamContent(streamId: string, maxWaitMs: number): Promis
     const tick = () => {
       const state = streams.get(streamId);
       if (!state) return resolve();
-      if (state.error || state.finished || state.content.trim()) return resolve();
+      if (state.error || state.finished) return resolve();
+      if (state.content.trim()) return resolve();
       if (Date.now() - startedAt >= maxWaitMs) return resolve();
       setTimeout(tick, 25);
     };
@@ -215,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;
@@ -224,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 = buildInboundBody(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,
@@ -269,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({
@@ -291,9 +515,100 @@ async function startAgentForStream(params: {
     cfg: config,
     dispatcherOptions: {
       deliver: async (payload) => {
-        const text = core.channel.text.convertMarkdownTables(payload.text ?? "", tableMode);
+        let text = payload.text ?? "";
+
+        // Protect <think> tags from table conversion
+        const thinkRegex = /<think>([\s\S]*?)<\/think>/g;
+        const thinks: string[] = [];
+        text = text.replace(thinkRegex, (match: string) => {
+          thinks.push(match);
+          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
+        thinks.forEach((think, i) => {
+          text = text.replace(`__THINK_PLACEHOLDER_${i}__`, think);
+        });
+
         const current = streams.get(streamId);
         if (!current) return;
+
+        if (!current.images) current.images = [];
+
+        const mediaUrls = payload.mediaUrls || (payload.mediaUrl ? [payload.mediaUrl] : []);
+        for (const mediaPath of mediaUrls) {
+          try {
+            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 process outbound media: ${mediaPath}: ${String(err)}`);
+          }
+        }
+
         const nextText = current.content
           ? `${current.content}\n\n${text}`.trim()
           : text.trim();
@@ -314,56 +629,58 @@ 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 === "mixed" && quote.mixed?.msg_item) {
+    const items = quote.mixed.msg_item.map((item) => {
+      if (item.msgtype === "text") return item.text?.content;
+      if (item.msgtype === "image") return `[图片] ${item.image?.url || ""}`;
+      return "";
+    }).filter(Boolean).join(" ");
+    return `[引用: 图文] ${items}`;
+  }
+  if (type === "voice") return `[引用: 语音] ${quote.voice?.content || ""}`;
+  if (type === "file") return `[引用: 文件] ${quote.file?.url || ""}`;
+  return "";
+}
+
 function buildInboundBody(msg: WecomInboundMessage): string {
+  let body = "";
   const msgtype = String(msg.msgtype ?? "").toLowerCase();
-  if (msgtype === "text") {
-    const content = (msg as any).text?.content;
-    return typeof content === "string" ? content : "";
-  }
-  if (msgtype === "voice") {
-    const content = (msg as any).voice?.content;
-    return typeof content === "string" ? content : "[voice]";
-  }
-  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)) {
-      return 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");
-    }
-    return "[mixed]";
-  }
-  if (msgtype === "image") {
-    const url = String((msg as any).image?.url ?? "").trim();
-    return url ? `[image] ${url}` : "[image]";
-  }
-  if (msgtype === "file") {
-    const url = String((msg as any).file?.url ?? "").trim();
-    return url ? `[file] ${url}` : "[file]";
-  }
-  if (msgtype === "event") {
-    const eventtype = String((msg as any).event?.eventtype ?? "").trim();
-    return eventtype ? `[event] ${eventtype}` : "[event]";
+      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}]` : "";
+
+  const quote = (msg as any).quote;
+  if (quote) {
+    const quoteText = formatQuote(quote).trim();
+    if (quoteText) body += `\n\n> ${quoteText}`;
   }
-  if (msgtype === "stream") {
-    const id = String((msg as any).stream?.id ?? "").trim();
-    return id ? `[stream_refresh] ${id}` : "[stream_refresh]";
-  }
-  return msgtype ? `[${msgtype}]` : "";
+  return body;
 }
 
 export function registerWecomWebhookTarget(target: WecomWebhookTarget): () => void {
   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);
@@ -371,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;
@@ -386,261 +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);
-    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,
-    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);
-  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(`No response_url for stream ${streamId}`);
+  await axios.post(state.response_url, { msgtype: "text", text: { content } });
+}