@wecom/wecom-openclaw-plugin 2026.3.25-beta.1 → 2026.3.25-beta.2

package/dist/index.esm.js

@@ -486,6 +486,17 @@ const CMD_ENTER_EVENT_REPLY = "ww_ai_robot_enter_event";
 // ============================================================================
 /** WSClient scene 参数：企微 OpenClaw 场景 */
 const SCENE_WECOM_OPENCLAW = 1;
+// ============================================================================
+// 模板卡片配置
+// ============================================================================
+/** 合法的模板卡片 card_type 列表 */
+const VALID_CARD_TYPES = [
+    "text_notice",
+    "news_notice",
+    "button_interaction",
+    "vote_interaction",
+    "multiple_interaction",
+];
 
 /**
  * 企业微信消息内容解析模块
@@ -496,7 +507,47 @@ const SCENE_WECOM_OPENCLAW = 1;
 // 解析函数
 // ============================================================================
 /**
- * 解析消息内容（支持单条消息、图文混排和引用消息）
+ * 将模板卡片事件回调格式化为可继续路由给大模型的文本。
+ *
+ * 这样后续 Agent 可以直接从 question_key / option_id 中理解用户的真实选择。
+ */
+function buildTemplateCardEventText(body) {
+    const templateCardEvent = body.event?.template_card_event;
+    if (body.msgtype !== "event" ||
+        body.event?.eventtype !== "template_card_event" ||
+        !templateCardEvent) {
+        return undefined;
+    }
+    const selectedItems = templateCardEvent.selected_items?.selected_item ?? [];
+    const selectedLines = selectedItems.map((item) => {
+        const questionKey = item.question_key?.trim() || "unknown_question";
+        const optionIds = item.option_ids?.option_id?.filter(Boolean) ?? [];
+        return `- ${questionKey}: ${optionIds.length > 0 ? optionIds.join(", ") : "(未选择)"}`;
+    });
+    const senderUserId = body.from?.userid || "";
+    const senderCorpId = body.from?.corpid || "";
+    const chatId = body.chatid || senderUserId;
+    return [
+        "[企业微信模板卡片回调]",
+        `event_type(事件类型): template_card_event`,
+        body.msgid ? `msgid(消息 id): ${body.msgid}` : undefined,
+        body.aibotid ? `aibotid(机器人 id): ${body.aibotid}` : undefined,
+        body.chattype ? `chat_type(会话类型): ${body.chattype}` : undefined,
+        chatId ? `chat_id(会话 id): ${chatId}` : undefined,
+        senderCorpId ? `from.corpid(企业 id): ${senderCorpId}` : undefined,
+        senderUserId ? `from.userid(发送人 id): ${senderUserId}` : undefined,
+        senderUserId ? `sender_userid(发送人 id): ${senderUserId}` : undefined,
+        templateCardEvent.card_type ? `card_type(卡片类型): ${templateCardEvent.card_type}` : undefined,
+        templateCardEvent.event_key ? `event_key(事件 key): ${templateCardEvent.event_key}` : undefined,
+        templateCardEvent.task_id ? `task_id(任务 id): ${templateCardEvent.task_id}` : undefined,
+        selectedLines.length > 0 ? "selected_items(选择项):" : "selected_items(选择项): []",
+        ...selectedLines,
+    ]
+        .filter((line) => Boolean(line))
+        .join("\n");
+}
+/**
+ * 解析消息内容（支持单条消息、图文混排、事件回调和引用消息）
  * @returns 提取的文本数组、图片URL数组和引用消息内容
  */
 function parseMessageContent(body) {
@@ -506,6 +557,14 @@ function parseMessageContent(body) {
     const fileUrls = [];
     const fileAesKeys = new Map();
     let quoteContent;
+    // 处理模板卡片事件回调
+    if (body.msgtype === "event") {
+        const eventText = buildTemplateCardEventText(body);
+        if (eventText) {
+            textParts.push(eventText);
+        }
+        return { textParts, imageUrls, imageAesKeys, fileUrls, fileAesKeys, quoteContent };
+    }
     // 处理图文混排消息
     if (body.msgtype === "mixed" && body.mixed?.msg_item) {
         for (const item of body.mixed.msg_item) {
@@ -647,13 +706,34 @@ async function sendWeComReply(params) {
         runtime.error?.(`[wecom] WSClient not connected, cannot send reply`);
         throw new Error("WSClient not connected");
     }
+    const body = frame.body;
+    // 事件回调（aibot_event_callback）没有可用于 replyStream 的有效 req_id，
+    // 对该场景改用主动发送 sendMessage，避免 846605 invalid req_id。
+    if (body.msgtype === "event") {
+        // 中间帧（thinking / 流式增量）直接跳过，仅在最终帧主动发一次文本。
+        if (!finish) {
+            runtime.log?.(`[plugin -> server] skip non-final stream for event callback, streamId=${streamId}`);
+            return streamId;
+        }
+        const chatId = body.chatid || body.from?.userid;
+        if (!chatId) {
+            throw new Error("Missing chatId for event callback reply");
+        }
+        await withTimeout(wsClient.sendMessage(chatId, {
+            msgtype: "markdown",
+            markdown: { content: text },
+        }), REPLY_SEND_TIMEOUT_MS, `Event reply send timed out (streamId=${streamId})`);
+        runtime.log?.(`[plugin -> server] event-active-send chatId=${chatId}, finish=${finish}`);
+        return streamId;
+    }
+    // 非事件消息，继续使用 replyStream（被动回复）
     // 使用 SDK 的 replyStream 方法发送消息，带超时保护
     try {
         await withTimeout(wsClient.replyStream(frame, streamId, text, finish), REPLY_SEND_TIMEOUT_MS, `Reply send timed out (streamId=${streamId})`);
     }
     catch (err) {
         // 服务端返回 846608：流式消息超过6分钟无法更新，需降级为主动发送
-        const errMsg = err?.errmsg || err?.message || (typeof err === "object" ? JSON.stringify(err) : String(err));
+        const errMsg = err?.errmsg || err?.message || String(err);
         if (err?.errcode === STREAM_EXPIRED_ERRCODE ||
             errMsg.includes(String(STREAM_EXPIRED_ERRCODE))) {
             throw new StreamExpiredError(errMsg);
@@ -1057,6 +1137,362 @@ async function uploadAndSendMedia(options) {
     }
 }
 
+/**
+ * 模板卡片解析器
+ *
+ * 从 LLM 回复文本中提取 markdown JSON 代码块，验证其是否为合法的企业微信模板卡片，
+ * 返回提取到的卡片列表和剩余文本。
+ *
+ * 同时提供 maskTemplateCardBlocks 函数，用于在流式中间帧中隐藏正在构建的卡片代码块，
+ * 避免 JSON 源码暴露给终端用户。
+ */
+// ============================================================================
+// LLM 输出字段类型修正
+// ============================================================================
+/**
+ * 将 LLM 可能输出的字符串/非法值修正为企业微信 API 要求的整数。
+ * 返回修正后的整数，若无法识别则返回 undefined（由调用方决定是否删除该字段）。
+ */
+function coerceToInt(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.round(value);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim().toLowerCase();
+        // 纯数字字符串
+        const num = Number(trimmed);
+        if (!Number.isNaN(num) && Number.isFinite(num)) {
+            return Math.round(num);
+        }
+    }
+    return undefined;
+}
+/** 将 LLM 可能输出的字符串/非法值修正为布尔值 */
+function coerceToBool(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        const t = value.trim().toLowerCase();
+        if (t === "true" || t === "1" || t === "yes")
+            return true;
+        if (t === "false" || t === "0" || t === "no")
+            return false;
+    }
+    if (typeof value === "number")
+        return value !== 0;
+    return undefined;
+}
+/** checkbox.mode 的语义别名映射 */
+const MODE_ALIASES = {
+    single: 0,
+    radio: 0,
+    "单选": 0,
+    multi: 1,
+    multiple: 1,
+    "多选": 1,
+};
+/**
+ * 修正 checkbox.mode：
+ * - 整数 → 原样
+ * - 字符串数字 "0"/"1" → 整数
+ * - 语义别名 "multi"/"single" 等 → 对应整数
+ * - 无法识别 → 删除（让服务端使用默认值 0）
+ */
+function coerceCheckboxMode(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.round(value);
+    }
+    if (typeof value === "string") {
+        const trimmed = value.trim().toLowerCase();
+        if (trimmed in MODE_ALIASES)
+            return MODE_ALIASES[trimmed];
+        const num = Number(trimmed);
+        if (!Number.isNaN(num))
+            return Math.round(num);
+    }
+    return undefined;
+}
+/**
+ * 对 LLM 生成的模板卡片 JSON 做字段类型修正，确保符合企业微信 API 的类型要求。
+ *
+ * 修正范围：
+ * - checkbox.mode: uint32（0=单选，1=多选）
+ * - checkbox.disable: bool
+ * - checkbox.option_list[].is_checked: bool
+ * - source.desc_color: int
+ * - quote_area.type: int
+ * - card_action.type: int
+ * - image_text_area.type: int
+ * - horizontal_content_list[].type: int
+ * - jump_list[].type: int
+ * - button_list[].style: int
+ * - button_selection.disable: bool
+ * - select_list[].disable: bool
+ *
+ * 原则：能修就修，修不了就删（让服务端走默认值），绝不阻塞发送。
+ */
+function normalizeTemplateCardFields(card, log) {
+    const fixes = [];
+    // ── checkbox ──────────────────────────────────────────────────────────
+    const checkbox = card.checkbox;
+    if (checkbox && typeof checkbox === "object") {
+        // mode
+        if ("mode" in checkbox) {
+            const fixed = coerceCheckboxMode(checkbox.mode);
+            if (fixed !== undefined) {
+                if (checkbox.mode !== fixed) {
+                    fixes.push(`checkbox.mode: ${JSON.stringify(checkbox.mode)} → ${fixed}`);
+                }
+                checkbox.mode = fixed;
+            }
+            else {
+                fixes.push(`checkbox.mode: ${JSON.stringify(checkbox.mode)} → (deleted, invalid)`);
+                delete checkbox.mode;
+            }
+        }
+        // disable
+        if ("disable" in checkbox) {
+            const fixed = coerceToBool(checkbox.disable);
+            if (fixed !== undefined && checkbox.disable !== fixed) {
+                fixes.push(`checkbox.disable: ${JSON.stringify(checkbox.disable)} → ${fixed}`);
+                checkbox.disable = fixed;
+            }
+        }
+        // option_list[].is_checked
+        if (Array.isArray(checkbox.option_list)) {
+            for (const opt of checkbox.option_list) {
+                if (opt && typeof opt === "object" && "is_checked" in opt) {
+                    const fixed = coerceToBool(opt.is_checked);
+                    if (fixed !== undefined && opt.is_checked !== fixed) {
+                        fixes.push(`checkbox.option_list.is_checked: ${JSON.stringify(opt.is_checked)} → ${fixed}`);
+                        opt.is_checked = fixed;
+                    }
+                }
+            }
+        }
+    }
+    // ── source.desc_color ────────────────────────────────────────────────
+    const source = card.source;
+    if (source && typeof source === "object" && "desc_color" in source) {
+        const fixed = coerceToInt(source.desc_color);
+        if (fixed !== undefined && source.desc_color !== fixed) {
+            fixes.push(`source.desc_color: ${JSON.stringify(source.desc_color)} → ${fixed}`);
+            source.desc_color = fixed;
+        }
+    }
+    // ── card_action.type ─────────────────────────────────────────────────
+    const cardAction = card.card_action;
+    if (cardAction && typeof cardAction === "object" && "type" in cardAction) {
+        const fixed = coerceToInt(cardAction.type);
+        if (fixed !== undefined && cardAction.type !== fixed) {
+            fixes.push(`card_action.type: ${JSON.stringify(cardAction.type)} → ${fixed}`);
+            cardAction.type = fixed;
+        }
+    }
+    // ── quote_area.type ──────────────────────────────────────────────────
+    const quoteArea = card.quote_area;
+    if (quoteArea && typeof quoteArea === "object" && "type" in quoteArea) {
+        const fixed = coerceToInt(quoteArea.type);
+        if (fixed !== undefined && quoteArea.type !== fixed) {
+            fixes.push(`quote_area.type: ${JSON.stringify(quoteArea.type)} → ${fixed}`);
+            quoteArea.type = fixed;
+        }
+    }
+    // ── image_text_area.type ─────────────────────────────────────────────
+    const imageTextArea = card.image_text_area;
+    if (imageTextArea && typeof imageTextArea === "object" && "type" in imageTextArea) {
+        const fixed = coerceToInt(imageTextArea.type);
+        if (fixed !== undefined && imageTextArea.type !== fixed) {
+            fixes.push(`image_text_area.type: ${JSON.stringify(imageTextArea.type)} → ${fixed}`);
+            imageTextArea.type = fixed;
+        }
+    }
+    // ── horizontal_content_list[].type ───────────────────────────────────
+    if (Array.isArray(card.horizontal_content_list)) {
+        for (const item of card.horizontal_content_list) {
+            if (item && typeof item === "object" && "type" in item) {
+                const fixed = coerceToInt(item.type);
+                if (fixed !== undefined && item.type !== fixed) {
+                    fixes.push(`horizontal_content_list.type: ${JSON.stringify(item.type)} → ${fixed}`);
+                    item.type = fixed;
+                }
+            }
+        }
+    }
+    // ── jump_list[].type ─────────────────────────────────────────────────
+    if (Array.isArray(card.jump_list)) {
+        for (const item of card.jump_list) {
+            if (item && typeof item === "object" && "type" in item) {
+                const fixed = coerceToInt(item.type);
+                if (fixed !== undefined && item.type !== fixed) {
+                    fixes.push(`jump_list.type: ${JSON.stringify(item.type)} → ${fixed}`);
+                    item.type = fixed;
+                }
+            }
+        }
+    }
+    // ── button_list[].style ──────────────────────────────────────────────
+    if (Array.isArray(card.button_list)) {
+        for (const btn of card.button_list) {
+            if (btn && typeof btn === "object" && "style" in btn) {
+                const fixed = coerceToInt(btn.style);
+                if (fixed !== undefined && btn.style !== fixed) {
+                    fixes.push(`button_list.style: ${JSON.stringify(btn.style)} → ${fixed}`);
+                    btn.style = fixed;
+                }
+            }
+        }
+    }
+    // ── button_selection.disable ─────────────────────────────────────────
+    const buttonSelection = card.button_selection;
+    if (buttonSelection && typeof buttonSelection === "object" && "disable" in buttonSelection) {
+        const fixed = coerceToBool(buttonSelection.disable);
+        if (fixed !== undefined && buttonSelection.disable !== fixed) {
+            fixes.push(`button_selection.disable: ${JSON.stringify(buttonSelection.disable)} → ${fixed}`);
+            buttonSelection.disable = fixed;
+        }
+    }
+    // ── select_list[].disable ────────────────────────────────────────────
+    if (Array.isArray(card.select_list)) {
+        for (const sel of card.select_list) {
+            if (sel && typeof sel === "object" && "disable" in sel) {
+                const fixed = coerceToBool(sel.disable);
+                if (fixed !== undefined && sel.disable !== fixed) {
+                    fixes.push(`select_list.disable: ${JSON.stringify(sel.disable)} → ${fixed}`);
+                    sel.disable = fixed;
+                }
+            }
+        }
+    }
+    if (fixes.length > 0) {
+        log?.(`[template-card-parser] normalizeTemplateCardFields: ${fixes.length} fix(es) applied: ${fixes.join("; ")}`);
+    }
+    return card;
+}
+/**
+ * 匹配 markdown 代码块的正则表达式
+ * 支持 ```json ... ``` 和 ``` ... ``` 两种格式
+ */
+const CODE_BLOCK_RE = /```(?:json)?\s*\n([\s\S]*?)\n```/g;
+/**
+ * 匹配已闭合的代码块（含 card_type 关键词，用于中间帧遮罩）
+ * 与 CODE_BLOCK_RE 相同，但用于 maskTemplateCardBlocks 中单独实例化
+ */
+const CLOSED_BLOCK_RE = /```(?:json)?\s*\n([\s\S]*?)\n```/g;
+/**
+ * 匹配未闭合的代码块尾部（LLM 正在输出中的代码块）
+ * 以 ```json 或 ``` 开头，后面有内容但没有闭合的 ```
+ */
+const UNCLOSED_BLOCK_RE = /```(?:json)?\s*\n[\s\S]*$/;
+/**
+ * 从文本中提取模板卡片 JSON 代码块
+ *
+ * 匹配规则：
+ * 1. 匹配所有 ```json ... ``` 或 ``` ... ``` 格式的代码块
+ * 2. 尝试 JSON.parse 解析代码块内容
+ * 3. 检查解析结果中是否包含合法的 card_type 字段
+ * 4. 合法的卡片从原文中移除，不合法的保留
+ *
+ * @param text - LLM 回复的完整文本
+ * @returns 提取结果，包含卡片列表和剩余文本
+ */
+function extractTemplateCards(text, log) {
+    const cards = [];
+    /** 需要从原文中移除的代码块（记录完整匹配内容） */
+    const blocksToRemove = [];
+    log?.(`[template-card-parser] extractTemplateCards called, textLength=${text.length}`);
+    let match;
+    // 重置正则的 lastIndex，确保从头匹配
+    CODE_BLOCK_RE.lastIndex = 0;
+    let blockIndex = 0;
+    while ((match = CODE_BLOCK_RE.exec(text)) !== null) {
+        const fullMatch = match[0];
+        const jsonContent = match[1].trim();
+        blockIndex++;
+        log?.(`[template-card-parser] Found code block #${blockIndex}, length=${fullMatch.length}, preview=${jsonContent.slice(0, 1000)}...`);
+        // 尝试解析 JSON
+        let parsed;
+        try {
+            parsed = JSON.parse(jsonContent);
+        }
+        catch (e) {
+            // JSON 解析失败，保留在原文中
+            log?.(`[template-card-parser] Code block #${blockIndex} JSON parse failed: ${String(e)}`);
+            continue;
+        }
+        // 检查是否包含合法的 card_type
+        const cardType = parsed.card_type;
+        if (typeof cardType !== "string" || !VALID_CARD_TYPES.includes(cardType)) {
+            // card_type 不合法，保留在原文中
+            log?.(`[template-card-parser] Code block #${blockIndex} has invalid card_type="${String(cardType)}", skipping`);
+            continue;
+        }
+        log?.(`[template-card-parser] Code block #${blockIndex} is valid template card, card_type="${cardType}"`);
+        // 修正 LLM 可能输出的错误字段类型（如 checkbox.mode: "multi" → 1）
+        normalizeTemplateCardFields(parsed, log);
+        // 合法的模板卡片，收集并标记移除
+        cards.push({
+            cardJson: parsed,
+            cardType,
+        });
+        blocksToRemove.push(fullMatch);
+    }
+    // 从原文中移除已提取的代码块，生成剩余文本
+    let remainingText = text;
+    for (const block of blocksToRemove) {
+        remainingText = remainingText.replace(block, "");
+    }
+    // 清理多余空行（连续 3 个以上换行合并为 2 个）
+    remainingText = remainingText.replace(/\n{3,}/g, "\n\n").trim();
+    log?.(`[template-card-parser] Extraction done: ${cards.length} card(s) found, remainingTextLength=${remainingText.length}`);
+    return { cards, remainingText };
+}
+/**
+ * 遮罩文本中的模板卡片代码块（用于流式中间帧展示）
+ *
+ * 在 LLM 流式输出过程中，累积文本可能包含：
+ * 1. 已闭合的模板卡片 JSON 代码块 → 替换为友好提示文本
+ * 2. 正在构建中的未闭合代码块 → 截断隐藏，避免 JSON 源码暴露
+ *
+ * 此函数仅做文本替换，不做 JSON 解析验证（中间帧性能优先）。
+ * 只要代码块内容中出现 "card_type" 关键词就认为是模板卡片并遮罩。
+ *
+ * @param text - 当前累积文本
+ * @returns 遮罩后的展示文本
+ */
+function maskTemplateCardBlocks(text, log) {
+    let masked = text;
+    let closedMaskCount = 0;
+    let unclosedMasked = false;
+    // 步骤一：处理已闭合的代码块
+    CLOSED_BLOCK_RE.lastIndex = 0;
+    masked = masked.replace(CLOSED_BLOCK_RE, (fullMatch, content) => {
+        // 检查代码块内容是否包含 card_type 关键词
+        if (/["']card_type["']/.test(content)) {
+            closedMaskCount++;
+            return "\n\n📋 *正在生成卡片消息...*\n\n";
+        }
+        // 非模板卡片代码块，保留原样
+        return fullMatch;
+    });
+    // 步骤二：处理未闭合的代码块尾部（LLM 仍在输出中）
+    // 检查是否有以 ``` 开头但没有闭合的代码块
+    const unclosedMatch = UNCLOSED_BLOCK_RE.exec(masked);
+    if (unclosedMatch) {
+        const unclosedContent = unclosedMatch[0];
+        // 如果未闭合部分包含 card_type 关键词，说明正在构建模板卡片 → 截断
+        if (/["']card_type["']/.test(unclosedContent)) {
+            unclosedMasked = true;
+            masked = masked.slice(0, unclosedMatch.index) + "\n\n📋 *正在生成卡片消息...*";
+        }
+    }
+    // 有遮罩行为时才打日志，避免每帧都刷屏
+    if (closedMaskCount > 0 || unclosedMasked) {
+        log?.(`[template-card-parser] maskTemplateCardBlocks: closedMasked=${closedMaskCount}, unclosedMasked=${unclosedMasked}, textLength=${text.length}, maskedLength=${masked.length}`);
+    }
+    return masked;
+}
+
 /**
  * 企业微信群组访问控制模块
  *
@@ -1524,6 +1960,144 @@ const PLUGIN_VERSION = getVersion();
  * - state-manager.ts   : 全局状态管理（带 TTL 清理）
  * - timeout.ts         : 超时工具
  */
+/**
+ * 去除文本中的 `<think>...</think>` 标签（支持跨行），返回剩余可见文本。
+ * 用于判断大模型回复中是否包含实际用户可见内容（而非仅有 thinking 推理过程）。
+ */
+function stripThinkTags(text) {
+    return text;
+    // return text.replace(/<think>[\s\S]*?<\/think>/g, "").trim();
+}
+const sentTemplateCardByTaskId = new Map();
+const TEMPLATE_CARD_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const TEMPLATE_CARD_CACHE_MAX_SIZE = 300;
+function getTemplateCardCacheKey(accountId, taskId) {
+    return `${accountId}:${taskId}`;
+}
+function pruneTemplateCardCache() {
+    const now = Date.now();
+    for (const [key, entry] of sentTemplateCardByTaskId) {
+        if (now - entry.createdAt >= TEMPLATE_CARD_CACHE_TTL_MS) {
+            sentTemplateCardByTaskId.delete(key);
+        }
+    }
+    if (sentTemplateCardByTaskId.size <= TEMPLATE_CARD_CACHE_MAX_SIZE) {
+        return;
+    }
+    const sortedEntries = [...sentTemplateCardByTaskId.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+    const removeCount = sentTemplateCardByTaskId.size - TEMPLATE_CARD_CACHE_MAX_SIZE;
+    for (const [key] of sortedEntries.slice(0, removeCount)) {
+        sentTemplateCardByTaskId.delete(key);
+    }
+}
+function cloneTemplateCard(card) {
+    return JSON.parse(JSON.stringify(card));
+}
+function saveTemplateCardToCache(params) {
+    const { accountId, templateCard, runtime } = params;
+    const taskId = templateCard.task_id;
+    if (!taskId) {
+        runtime.log?.("[wecom][template-card] Skip cache: template card has no task_id");
+        return;
+    }
+    sentTemplateCardByTaskId.set(getTemplateCardCacheKey(accountId, taskId), {
+        templateCard: cloneTemplateCard(templateCard),
+        createdAt: Date.now(),
+    });
+    pruneTemplateCardCache();
+}
+function getTemplateCardFromCache(accountId, taskId) {
+    pruneTemplateCardCache();
+    const cached = sentTemplateCardByTaskId.get(getTemplateCardCacheKey(accountId, taskId));
+    if (!cached) {
+        return undefined;
+    }
+    return cloneTemplateCard(cached.templateCard);
+}
+function buildSelectedOptionMap(templateCardEvent) {
+    const selectedMap = new Map();
+    const selectedItems = templateCardEvent?.selected_items?.selected_item ?? [];
+    for (const item of selectedItems) {
+        const questionKey = item.question_key?.trim();
+        if (!questionKey) {
+            continue;
+        }
+        const optionIds = item.option_ids?.option_id?.filter(Boolean) ?? [];
+        selectedMap.set(questionKey, optionIds);
+    }
+    return selectedMap;
+}
+function applySelectedStateToTemplateCard(params) {
+    const { templateCard, selectedMap, templateCardEvent } = params;
+    const nextCard = cloneTemplateCard(templateCard);
+    if (templateCardEvent?.task_id) {
+        nextCard.task_id = templateCardEvent.task_id;
+    }
+    if (templateCardEvent?.card_type) {
+        nextCard.card_type = templateCardEvent.card_type;
+    }
+    // 交互完成后将提交按钮文案更新为已提交，提升用户感知
+    if (nextCard.submit_button?.text) {
+        nextCard.submit_button.text = "已提交";
+    }
+    if (nextCard.checkbox?.question_key) {
+        const selectedIds = selectedMap.get(nextCard.checkbox.question_key) ?? [];
+        nextCard.checkbox.disable = true;
+        if (Array.isArray(nextCard.checkbox.option_list)) {
+            nextCard.checkbox.option_list = nextCard.checkbox.option_list.map((option) => ({
+                ...option,
+                is_checked: selectedIds.includes(option.id),
+            }));
+        }
+    }
+    if (Array.isArray(nextCard.select_list)) {
+        nextCard.select_list = nextCard.select_list.map((selection) => {
+            const selectedIds = selectedMap.get(selection.question_key) ?? [];
+            return {
+                ...selection,
+                disable: true,
+                selected_id: selectedIds[0] ?? selection.selected_id,
+            };
+        });
+    }
+    if (nextCard.button_selection?.question_key) {
+        const selectedIds = selectedMap.get(nextCard.button_selection.question_key) ?? [];
+        nextCard.button_selection.disable = true;
+        if (selectedIds[0]) {
+            nextCard.button_selection.selected_id = selectedIds[0];
+        }
+    }
+    return nextCard;
+}
+async function updateTemplateCardOnEvent(params) {
+    const { frame, accountId, runtime, wsClient } = params;
+    const body = frame.body;
+    const templateCardEvent = body.event?.template_card_event;
+    const taskId = templateCardEvent?.task_id;
+    if (!taskId) {
+        runtime.log?.(`[${accountId}] [template-card-update] Skip update: missing task_id in callback`);
+        return;
+    }
+    const cachedCard = getTemplateCardFromCache(accountId, taskId);
+    if (!cachedCard) {
+        runtime.log?.(`[${accountId}] [template-card-update] Skip update: task_id=${taskId} not found in cache`);
+        return;
+    }
+    const selectedMap = buildSelectedOptionMap(templateCardEvent);
+    const updatedCard = applySelectedStateToTemplateCard({
+        templateCard: cachedCard,
+        selectedMap,
+        templateCardEvent,
+    });
+    await wsClient.updateTemplateCard(frame, updatedCard, [body.from.userid]);
+    runtime.log?.(`[${accountId}] [template-card-update] Updated card by task_id=${taskId}`);
+    // 将更新后的卡片写回缓存，后续多次点击时状态保持一致
+    saveTemplateCardToCache({
+        accountId,
+        templateCard: updatedCard,
+        runtime,
+    });
+}
 // ============================================================================
 // 媒体本地路径白名单扩展
 // ============================================================================
@@ -1686,7 +2260,7 @@ async function sendMediaBatch(ctx, mediaUrls) {
     const body = frame.body;
     const chatId = body.chatid || body.from.userid;
     const mediaLocalRoots = await getExtendedMediaLocalRoots(account.config);
-    runtime.log?.(`[wecom][debug] mediaLocalRoots=${JSON.stringify(mediaLocalRoots)}, mediaUrls=${JSON.stringify(mediaUrls)}, hasText=${!!state.hasText}`);
+    runtime.log?.(`[wecom][debug] mediaLocalRoots=${JSON.stringify(mediaLocalRoots)}, mediaUrls=${JSON.stringify(mediaUrls)}`);
     for (const mediaUrl of mediaUrls) {
         const result = await uploadAndSendMedia({
             wsClient,
@@ -1720,6 +2294,7 @@ async function sendMediaBatch(ctx, mediaUrls) {
  *    替换掉 thinking 动画，否则 thinking 会一直残留。
  *
  * 关闭策略（按优先级）：
+ * 0. [新增] 有模板卡片代码块 → 提取卡片并主动发送，用剩余文本关闭流
  * 1. 有可见文本 → 用完整文本关闭
  * 2. 有媒体成功发送（通过 deliver 回调） → 用友好提示"文件已发送"
  * 3. 媒体发送失败 → 直接用错误摘要替换 thinking
@@ -1736,8 +2311,40 @@ async function finishThinkingStream(ctx) {
     const { wsClient, frame, state, runtime } = ctx;
     const body = frame.body;
     const chatId = body.chatid || body.from.userid;
+    const visibleText = stripThinkTags(state.accumulatedText);
+    // ── 模板卡片检测与发送 ──────────────────────────────────────────────
+    // 在确定 finishText 之前，先检查累积文本中是否包含模板卡片 JSON 代码块。
+    // 若检测到合法卡片，通过 sendMessage 主动发送后，用剩余文本关闭流。
+    if (visibleText) {
+        runtime.log?.(`[wecom][template-card] finishThinkingStream: visibleText exists, length=${visibleText.length}, running extractTemplateCards...`);
+        const logFn = (...args) => {
+            runtime.log?.(...args);
+        };
+        const { cards, remainingText } = extractTemplateCards(state.accumulatedText, logFn);
+        runtime.log?.(`[wecom][template-card] finishThinkingStream: extractTemplateCards result — cards=${cards.length}, remainingTextLength=${remainingText.length}`);
+        if (cards.length > 0) {
+            runtime.log?.(`[wecom][template-card] finishThinkingStream: ${cards.length} card(s) detected, card_types=[${cards.map(c => c.cardType).join(", ")}]`);
+            await sendTemplateCards(ctx, cards);
+            // 用剩余文本关闭流（可能为空）
+            const trimmedRemaining = stripThinkTags(remainingText);
+            const finishText = trimmedRemaining
+                ? remainingText
+                : (state.hasTemplateCard ? "📋 卡片消息已发送。" : "✅ 处理完成。");
+            runtime.log?.(`[wecom][template-card] finishThinkingStream: closing stream with finishText="${finishText.slice(0, 100)}...", hasTemplateCard=${state.hasTemplateCard}`);
+            await sendWeComReply({ wsClient, frame, text: finishText, runtime, finish: true, streamId: state.streamId });
+            return;
+        }
+    }
+    else {
+        runtime.log?.(`[wecom][template-card] finishThinkingStream: no visibleText, skipping template card extraction`);
+    }
+    // ── 模板卡片检测结束 ────────────────────────────────────────────────
     let finishText = state.accumulatedText;
-    if (state.hasMedia) {
+    if (visibleText) {
+        // 有可见文本：用完整文本关闭流（覆盖 thinking 为真实内容）
+        finishText = state.accumulatedText;
+    }
+    else if (state.hasMedia) {
         if (state.hasMediaFailed && state.mediaErrorSummary) {
             // 媒体成功发送：用友好提示告知用户
             finishText = finishText ? `${finishText}\n\n${state.mediaErrorSummary}` : state.mediaErrorSummary;
@@ -1774,6 +2381,41 @@ async function finishThinkingStream(ctx) {
         }
     }
 }
+/**
+ * 逐个发送已提取的模板卡片（通过 wsClient.sendMessage 主动推送）
+ *
+ * 发送失败不阻塞流程，仅记录错误日志。
+ */
+async function sendTemplateCards(ctx, cards) {
+    const { wsClient, frame, state, runtime, account } = ctx;
+    const body = frame.body;
+    const chatId = body.chatid || body.from.userid;
+    for (const card of cards) {
+        try {
+            runtime.log?.(`[wecom][template-card] Sending card_type=${card.cardType} to chatId=${chatId}`);
+            const rawTemplateCard = card.cardJson;
+            if (typeof rawTemplateCard.card_type !== "string") {
+                runtime.error?.("[wecom][template-card] Skip sending invalid card: missing card_type");
+                continue;
+            }
+            const templateCard = rawTemplateCard;
+            await wsClient.sendMessage(chatId, {
+                msgtype: "template_card",
+                template_card: templateCard,
+            });
+            state.hasTemplateCard = true;
+            saveTemplateCardToCache({
+                accountId: account.accountId,
+                templateCard,
+                runtime,
+            });
+            runtime.log?.(`[wecom][template-card] Card sent successfully: card_type=${card.cardType}`);
+        }
+        catch (err) {
+            runtime.error?.(`[wecom][template-card] Failed to send card: card_type=${card.cardType}, error=${JSON.stringify(err)}`);
+        }
+    }
+}
 /**
  * 路由消息到核心处理流程并处理回复
  */
@@ -1846,9 +2488,15 @@ async function routeAndDispatchMessage(params) {
                         }
                     }
                     // 中间帧：有可见文本时流式更新（流式过期后跳过，等 deliver 完成后主动发送）
-                    if (info.kind !== "final" && state.hasText && state.accumulatedText && !state.streamExpired) {
+                    // 使用 maskTemplateCardBlocks 遮罩正在构建中的模板卡片代码块，
+                    // 避免 JSON 源码在流式输出过程中暴露给终端用户
+                    if (info.kind !== "final" && state.accumulatedText && !state.streamExpired) {
                         try {
-                            await sendWeComReply({ wsClient, frame, text: state.accumulatedText, runtime, finish: false, streamId: state.streamId });
+                            const displayText = maskTemplateCardBlocks(state.accumulatedText, (...args) => runtime.log?.(...args));
+                            if (displayText !== state.accumulatedText) {
+                                runtime.log?.(`[wecom][template-card] Mid-frame masked: original=${state.accumulatedText.length}chars, masked=${displayText.length}chars`);
+                            }
+                            await sendWeComReply({ wsClient, frame, text: displayText, runtime, finish: false, streamId: state.streamId });
                         }
                         catch (err) {
                             if (err instanceof StreamExpiredError) {
@@ -2031,6 +2679,7 @@ function createSdkLogger(runtime, accountId) {
 async function monitorWeComProvider(options) {
     const { account, config, runtime, abortSignal, setStatus } = options;
     runtime.log?.(`[${account.accountId}] [${PLUGIN_VERSION}] Initializing WSClient with SDK...`);
+    runtime.error?.(`[${account.accountId}] [diag] monitor boot marker: build=20260325-event-debug-1`);
     // 启动消息状态定期清理
     startMessageStateCleanup();
     return new Promise((resolve, reject) => {
@@ -2169,7 +2818,7 @@ async function monitorWeComProvider(options) {
                 // runtime.error?.(`[${account.accountId}] Failed to reply enter_check_update: ${String(err)}`);
             }
         });
-        // 监听所有消息
+        // 监听普通消息
         wsClient.on("message", async (frame) => {
             try {
                 await processWeComMessage({
@@ -2184,6 +2833,44 @@ async function monitorWeComProvider(options) {
                 runtime.error?.(`[${account.accountId}] Failed to process message: ${String(err)}`);
             }
         });
+        // 监听所有事件回调（aibot_event_callback）。
+        // 这里使用通用 event 监听，再按 eventtype 分发，兼容不同 SDK 版本在细分事件名上的差异。
+        wsClient.on("event", async (frame) => {
+            try {
+                const eventBody = frame.body;
+                const eventType = eventBody.event?.eventtype;
+                runtime.log?.(`[${account.accountId}] Received event callback: eventtype=${eventType ?? ""}, msgid=${eventBody.msgid ?? ""}`);
+                runtime.error?.(`[${account.accountId}] [diag] event-listener fired: eventtype=${eventType ?? ""}, msgid=${eventBody.msgid ?? ""}`);
+                if (eventType !== "template_card_event") {
+                    return;
+                }
+                const templateCardEvent = eventBody.event?.template_card_event;
+                runtime.log?.(`[${account.accountId}] Received template_card_event: event_key=${templateCardEvent?.event_key ?? ""}, task_id=${templateCardEvent?.task_id ?? ""}`);
+                try {
+                    await updateTemplateCardOnEvent({
+                        frame,
+                        accountId: account.accountId,
+                        runtime,
+                        wsClient,
+                    });
+                }
+                catch (updateErr) {
+                    runtime.error?.(`[${account.accountId}] [template-card-update] Failed to update template card: ${String(updateErr)}`);
+                }
+                await processWeComMessage({
+                    frame,
+                    account,
+                    config,
+                    runtime,
+                    wsClient,
+                });
+            }
+            catch (err) {
+                runtime.error?.(`[${account.accountId}] Failed to process template_card_event: ${String(err)}`);
+            }
+        });
+        runtime.log?.(`[${account.accountId}] Event listeners attached: message + event(template_card_event)`);
+        runtime.error?.(`[${account.accountId}] [diag] listeners-ready marker`);
         // 启动前预热 reqId 缓存，确保完成后再建立连接，避免 getSync 在预热完成前返回 undefined
         warmupReqIdStore(account.accountId, (...args) => runtime.log?.(...args))
             .then((count) => {
@@ -3586,7 +4273,8 @@ const plugin = {
             }
             return {
                 appendSystemContext: [
-                    "重要：涉及发送图片/视频/语音/文件给用户时，请务必使用 `MEDIA：` 指令。详见  wecom-send-media 这个 skill（技能）。"
+                    "重要：涉及发送图片/视频/语音/文件给用户时，请务必使用 `MEDIA:` 指令。详见  wecom-send-media 这个 skill（技能）。",
+                    "重要：当需要向用户发送结构化卡片消息（如通知、投票、按钮选择等）时，请在回复中直接输出 JSON 代码块（```json ... ```），其中 card_type 字段标明卡片类型。详见 wecom-send-template-card 技能。"
                 ].join("\n"),
             };
         });