@wecom/wecom-openclaw-plugin 2026.3.25 → 2026.3.30-beta.0

package/dist/index.cjs.js

@@ -513,6 +513,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",
+];
 
 /**
  * 企业微信消息内容解析模块
@@ -523,7 +534,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) {
@@ -533,6 +584,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) {
@@ -674,6 +733,27 @@ 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})`);
@@ -1084,6 +1164,640 @@ 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 → 多选，仅允许这两个值
+ * - 字符串数字 "0"/"1" → 整数
+ * - 语义别名 "multi"/"single" 等 → 对应整数
+ * - 其他正整数（如 2）→ clamp 到 1（多选）
+ * - 无法识别 → 删除（让服务端使用默认值 0）
+ */
+function coerceCheckboxMode(value) {
+    let num;
+    if (typeof value === "number" && Number.isFinite(value)) {
+        num = Math.round(value);
+    }
+    else if (typeof value === "string") {
+        const trimmed = value.trim().toLowerCase();
+        if (trimmed in MODE_ALIASES)
+            return MODE_ALIASES[trimmed];
+        const parsed = Number(trimmed);
+        if (!Number.isNaN(parsed))
+            num = Math.round(parsed);
+    }
+    if (num === undefined)
+        return undefined;
+    // mode 只允许 0（单选）或 1（多选），超出范围 clamp
+    if (num <= 0)
+        return 0;
+    return 1;
+}
+/**
+ * 对 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;
+}
+/**
+ * 校验并补全模板卡片的必填字段。
+ *
+ * 在 normalizeTemplateCardFields（类型修正）之后调用，确保卡片结构满足企业微信 API 的必填要求。
+ *
+ * 补全策略：
+ * - task_id：所有卡片统一自动补全（交互型 API 必填，通知型插件也需要用于缓存回写）
+ * - main_title：除 text_notice 外的 4 种卡片 API 必填，自动补 { title: "通知" }
+ *   text_notice 要求 main_title.title 与 sub_title_text 至少填一个，缺两个时补 sub_title_text
+ * - card_action：text_notice / news_notice API 必填，自动补 { type: 1, url: "https://work.weixin.qq.com" }
+ * - checkbox：vote_interaction API 必填，无法凭空补全，仅记告警
+ * - submit_button：vote_interaction / multiple_interaction API 必填，自动补 { text: "提交", key: "submit_default" }
+ * - button_list：button_interaction API 必填，无法凭空补全，仅记告警
+ * - select_list：multiple_interaction API 必填，无法凭空补全，仅记告警
+ */
+function validateAndFixRequiredFields(card, log) {
+    const cardType = card.card_type;
+    const fixes = [];
+    const warnings = [];
+    // ── task_id（所有卡片：始终确保唯一性） ─────────────────────────────
+    // LLM 可能编造时间戳导致重复，因此无论是否提供了 task_id，
+    // 都提取语义前缀 + 代码追加真实时间戳和随机后缀来保证唯一。
+    const rawTid = (typeof card.task_id === "string" && card.task_id.trim()) ? card.task_id.trim() : "";
+    const rand = Math.random().toString(36).slice(2, 6);
+    const ts = Date.now();
+    let finalTid;
+    if (rawTid) {
+        // 提取 LLM 的语义前缀：去掉尾部的数字串（LLM 编造的假时间戳）
+        const prefix = rawTid.replace(/_\d{8,}$/, "").replace(/[^a-zA-Z0-9_\-@]/g, "_").slice(0, 80);
+        finalTid = prefix ? `${prefix}_${ts}_${rand}` : `task_${cardType}_${ts}_${rand}`;
+    }
+    else {
+        finalTid = `task_${cardType}_${ts}_${rand}`;
+    }
+    if (finalTid !== rawTid) {
+        fixes.push(`task_id: "${rawTid || "(missing)"}" → "${finalTid}"`);
+    }
+    card.task_id = finalTid;
+    // ── main_title ────────────────────────────────────────────────────────
+    const mainTitle = card.main_title;
+    const hasMainTitle = mainTitle && typeof mainTitle === "object" &&
+        (typeof mainTitle.title === "string" && mainTitle.title.trim());
+    const hasSubTitleText = typeof card.sub_title_text === "string" && card.sub_title_text.trim();
+    switch (cardType) {
+        case "text_notice":
+            // text_notice: main_title.title 和 sub_title_text 至少一个
+            if (!hasMainTitle && !hasSubTitleText) {
+                card.sub_title_text = card.sub_title_text || "通知";
+                fixes.push(`sub_title_text: (missing, no main_title either) → fallback "通知"`);
+            }
+            break;
+        case "news_notice":
+        case "button_interaction":
+        case "vote_interaction":
+        case "multiple_interaction":
+            // 这四种 main_title 为必填
+            if (!mainTitle || typeof mainTitle !== "object") {
+                card.main_title = { title: "通知" };
+                fixes.push(`main_title: (missing) → { title: "通知" }`);
+            }
+            else if (!hasMainTitle) {
+                mainTitle.title = "通知";
+                fixes.push(`main_title.title: (empty) → "通知"`);
+            }
+            break;
+    }
+    // ── card_action（text_notice / news_notice 必填） ──────────────────
+    if (cardType === "text_notice" || cardType === "news_notice") {
+        if (!card.card_action || typeof card.card_action !== "object") {
+            card.card_action = { type: 1, url: "https://work.weixin.qq.com" };
+            fixes.push(`card_action: (missing) → { type: 1, url: "https://work.weixin.qq.com" }`);
+        }
+    }
+    // ── submit_button（vote_interaction / multiple_interaction 必填） ──
+    if (cardType === "vote_interaction" || cardType === "multiple_interaction") {
+        if (!card.submit_button || typeof card.submit_button !== "object") {
+            card.submit_button = { text: "提交", key: `submit_${cardType}_${Date.now()}` };
+            fixes.push(`submit_button: (missing) → auto-generated`);
+        }
+    }
+    // ── 核心业务字段（无法凭空补全，仅告警） ────────────────────────────
+    if (cardType === "button_interaction") {
+        if (!Array.isArray(card.button_list) || card.button_list.length === 0) {
+            warnings.push(`button_list is missing or empty (required for button_interaction)`);
+        }
+    }
+    if (cardType === "vote_interaction") {
+        if (!card.checkbox || typeof card.checkbox !== "object") {
+            warnings.push(`checkbox is missing (required for vote_interaction)`);
+        }
+    }
+    if (cardType === "multiple_interaction") {
+        if (!Array.isArray(card.select_list) || card.select_list.length === 0) {
+            warnings.push(`select_list is missing or empty (required for multiple_interaction)`);
+        }
+    }
+    if (fixes.length > 0) {
+        log?.(`[template-card-parser] validateAndFixRequiredFields: ${fixes.length} fix(es): ${fixes.join("; ")}`);
+    }
+    if (warnings.length > 0) {
+        log?.(`[template-card-parser] validateAndFixRequiredFields: ${warnings.length} warning(s): ${warnings.join("; ")}`);
+    }
+    return card;
+}
+// ============================================================================
+// 简化格式 → 企微 API 格式转换（vote_interaction / multiple_interaction）
+// ============================================================================
+/**
+ * 生成唯一的 question_key / submit_button.key。
+ */
+function generateKey(prefix) {
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `${prefix}_${Date.now()}_${rand}`;
+}
+/**
+ * 将 vote_interaction 的简化格式转换为企微 API 格式。
+ *
+ * 简化格式字段：
+ *   title        → main_title.title
+ *   description  → main_title.desc
+ *   options      → checkbox.option_list（每个 {id, text} 直接透传）
+ *   mode         → checkbox.mode（0=单选 1=多选）
+ *   submit_text  → submit_button.text
+ *
+ * 代码自动生成：checkbox.question_key, submit_button.key
+ *
+ * 如果 LLM 已输出了合法的 API 原始格式（有 checkbox.option_list），则跳过转换直接透传。
+ */
+function transformVoteInteraction(card, log) {
+    // 防御性：如果已经是合法 API 格式，跳过
+    const existingCheckbox = card.checkbox;
+    if (existingCheckbox && typeof existingCheckbox === "object" && Array.isArray(existingCheckbox.option_list)) {
+        log?.(`[template-card-parser] transformVoteInteraction: already has checkbox.option_list, skipping transform`);
+        return card;
+    }
+    // 提取 options（简化格式的核心字段）
+    const options = card.options;
+    if (!Array.isArray(options) || options.length === 0) {
+        log?.(`[template-card-parser] transformVoteInteraction: no "options" array found, skipping transform`);
+        return card;
+    }
+    log?.(`[template-card-parser] transformVoteInteraction: transforming simplified format → API format`);
+    log?.(`[template-card-parser] transformVoteInteraction: input=${JSON.stringify(card)}`);
+    // ── 构建 main_title ──
+    const title = card.title;
+    const description = card.description;
+    if (title || description) {
+        card.main_title = {
+            ...(title ? { title } : {}),
+            ...(description ? { desc: description } : {}),
+        };
+        delete card.title;
+        delete card.description;
+    }
+    // ── 构建 checkbox（最多 20 个选项） ──
+    const mode = coerceCheckboxMode(card.mode) ?? 0;
+    const questionKey = generateKey("vote");
+    const clampedOptions = options.slice(0, 20);
+    if (options.length > 20) {
+        log?.(`[template-card-parser] transformVoteInteraction: options count ${options.length} exceeds max 20, clamped to 20`);
+    }
+    card.checkbox = {
+        question_key: questionKey,
+        mode,
+        option_list: clampedOptions.map((opt) => ({
+            id: String(opt.id ?? opt.value ?? `opt_${Math.random().toString(36).slice(2, 6)}`),
+            text: String(opt.text ?? opt.label ?? opt.name ?? ""),
+        })),
+    };
+    delete card.options;
+    delete card.mode;
+    // ── 构建 submit_button ──
+    const submitText = card.submit_text || "提交";
+    card.submit_button = {
+        text: submitText,
+        key: generateKey("submit_vote"),
+    };
+    delete card.submit_text;
+    // ── 清理 LLM 可能杜撰的无效字段 ──
+    delete card.vote_question;
+    delete card.vote_option;
+    delete card.vote_options;
+    log?.(`[template-card-parser] transformVoteInteraction: output=${JSON.stringify(card)}`);
+    return card;
+}
+/**
+ * 将 multiple_interaction 的简化格式转换为企微 API 格式。
+ *
+ * 简化格式字段：
+ *   title            → main_title.title
+ *   description      → main_title.desc
+ *   selectors        → select_list（每个 {title, options: [{id, text}]} → {question_key, title, option_list}）
+ *   submit_text      → submit_button.text
+ *
+ * 代码自动生成：select_list[].question_key, submit_button.key
+ *
+ * 如果 LLM 已输出了合法的 API 原始格式（有 select_list[0].option_list），则跳过转换直接透传。
+ */
+function transformMultipleInteraction(card, log) {
+    // 防御性：如果已经是合法 API 格式，跳过
+    const existingSelectList = card.select_list;
+    if (Array.isArray(existingSelectList) &&
+        existingSelectList.length > 0 &&
+        Array.isArray(existingSelectList[0]?.option_list)) {
+        log?.(`[template-card-parser] transformMultipleInteraction: already has select_list[].option_list, skipping transform`);
+        return card;
+    }
+    // 提取 selectors（简化格式的核心字段）
+    const selectors = card.selectors;
+    if (!Array.isArray(selectors) || selectors.length === 0) {
+        log?.(`[template-card-parser] transformMultipleInteraction: no "selectors" array found, skipping transform`);
+        return card;
+    }
+    log?.(`[template-card-parser] transformMultipleInteraction: transforming simplified format → API format`);
+    log?.(`[template-card-parser] transformMultipleInteraction: input=${JSON.stringify(card)}`);
+    // ── 构建 main_title ──
+    const title = card.title;
+    const description = card.description;
+    if (title || description) {
+        card.main_title = {
+            ...(title ? { title } : {}),
+            ...(description ? { desc: description } : {}),
+        };
+        delete card.title;
+        delete card.description;
+    }
+    // ── 构建 select_list（最多 3 个选择器，每个最多 10 个选项） ──
+    const clampedSelectors = selectors.slice(0, 3);
+    if (selectors.length > 3) {
+        log?.(`[template-card-parser] transformMultipleInteraction: selectors count ${selectors.length} exceeds max 3, clamped to 3`);
+    }
+    card.select_list = clampedSelectors.map((sel, idx) => {
+        const selectorOptions = (sel.options ?? []).slice(0, 10);
+        return {
+            question_key: generateKey(`sel_${idx}`),
+            title: String(sel.title ?? sel.label ?? `选择${idx + 1}`),
+            option_list: selectorOptions.map((opt) => ({
+                id: String(opt.id ?? opt.value ?? `opt_${Math.random().toString(36).slice(2, 6)}`),
+                text: String(opt.text ?? opt.label ?? opt.name ?? ""),
+            })),
+        };
+    });
+    delete card.selectors;
+    // ── 构建 submit_button ──
+    const submitText = card.submit_text || "提交";
+    card.submit_button = {
+        text: submitText,
+        key: generateKey("submit_multi"),
+    };
+    delete card.submit_text;
+    log?.(`[template-card-parser] transformMultipleInteraction: output=${JSON.stringify(card)}`);
+    return card;
+}
+/**
+ * 对 vote_interaction / multiple_interaction 执行简化格式转换。
+ * 其他 card_type 直接跳过。
+ */
+function transformSimplifiedCard(card, log) {
+    const cardType = card.card_type;
+    if (cardType === "vote_interaction") {
+        return transformVoteInteraction(card, log);
+    }
+    if (cardType === "multiple_interaction") {
+        return transformMultipleInteraction(card, log);
+    }
+    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}"`);
+        // vote_interaction / multiple_interaction：简化格式 → API 格式转换
+        transformSimplifiedCard(parsed, log);
+        // 修正 LLM 可能输出的错误字段类型（如 checkbox.mode: "multi" → 1）
+        normalizeTemplateCardFields(parsed, log);
+        // 校验并补全必填字段（如缺失的 task_id、main_title、card_action）
+        validateAndFixRequiredFields(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;
+}
+
 /**
  * 企业微信群组访问控制模块
  *
@@ -1551,6 +2265,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,
+    });
+}
 // ============================================================================
 // 媒体本地路径白名单扩展
 // ============================================================================
@@ -1747,6 +2599,7 @@ async function sendMediaBatch(ctx, mediaUrls) {
  *    替换掉 thinking 动画，否则 thinking 会一直残留。
  *
  * 关闭策略（按优先级）：
+ * 0. [新增] 有模板卡片代码块 → 提取卡片并主动发送，用剩余文本关闭流
  * 1. 有可见文本 → 用完整文本关闭
  * 2. 有媒体成功发送（通过 deliver 回调） → 用友好提示"文件已发送"
  * 3. 媒体发送失败 → 直接用错误摘要替换 thinking
@@ -1763,8 +2616,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;
@@ -1801,6 +2686,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)}`);
+        }
+    }
+}
 /**
  * 路由消息到核心处理流程并处理回复
  */
@@ -1873,9 +2793,15 @@ async function routeAndDispatchMessage(params) {
                         }
                     }
                     // 中间帧：有可见文本时流式更新（流式过期后跳过，等 deliver 完成后主动发送）
+                    // 使用 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) {
@@ -2058,6 +2984,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) => {
@@ -2196,7 +3123,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({
@@ -2211,6 +3138,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) => {
@@ -3279,59 +4244,16 @@ function cleanWithDefs(schema, defs, refStack) {
 }
 
 /**
- * wecom_mcp — 模拟 MCP 调用的 Agent Tool
- *
- * 通过 MCP Streamable HTTP 传输协议调用企业微信 MCP Server，
- * 提供 list（列出所有工具）和 call（调用工具）两个操作。
+ * 业务错误码检查拦截器
  *
- * 在 skills 中的使用方式：
- *   wecom_mcp list <category>
- *   wecom_mcp call <category> <method> '<jsonArgs>'
+ * 检查 tools/call 返回结果中是否包含需要清理缓存的业务错误码。
+ * MCP Server 可能在正常的 JSON-RPC 响应中返回业务层错误，
+ * 这些错误被包裹在 result.content[].text 中，需要解析后判断。
  *
- * 示例：
- *   wecom_mcp list contact
- *   wecom_mcp call contact getContact '{}'
+ * 此拦截器对所有 call 调用生效。
  */
 // ============================================================================
-// 响应构造辅助
-// ============================================================================
-/** 构造统一的文本响应结构 */
-const textResult = (data) => ({
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-});
-/** 构造错误响应 */
-const errorResult = (err) => {
-    // 适配企业微信 API 返回的 { errcode, errmsg } 结构
-    if (err && typeof err === "object" && "errcode" in err) {
-        const { errcode, errmsg } = err;
-        return textResult({ error: errmsg ?? `错误码: ${errcode}`, errcode });
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    return textResult({ error: message });
-};
-// ============================================================================
-// list 操作：列出某品类的所有 MCP 工具
-// ============================================================================
-const handleList = async (category) => {
-    const result = await sendJsonRpc(category, "tools/list");
-    const tools = result?.tools ?? [];
-    if (tools.length === 0) {
-        return { message: `品类 "${category}" 下暂无可用工具`, tools: [] };
-    }
-    return {
-        category,
-        count: tools.length,
-        tools: tools.map((t) => ({
-            name: t.name,
-            description: t.description ?? "",
-            // 清洗 inputSchema，内联 $ref/$defs 引用并移除 Gemini 不支持的关键词，
-            // 避免 Gemini 模型解析 function response 时报 400 错误
-            inputSchema: t.inputSchema ? cleanSchemaForGemini(t.inputSchema) : undefined,
-        })),
-    };
-};
-// ============================================================================
-// call 操作：调用某品类的某个 MCP 工具
+// 常量
 // ============================================================================
 /**
  * 需要触发缓存清理的业务错误码集合
@@ -3342,13 +4264,27 @@ const handleList = async (category) => {
  * - 850002: 机器人未被授权使用对应能力，需清理缓存以便下次重新拉取配置
  */
 const BIZ_CACHE_CLEAR_ERROR_CODES = new Set([850002]);
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+const bizErrorInterceptor = {
+    name: "biz-error",
+    /** 对所有 call 调用生效 */
+    match: () => true,
+    /** 检查返回结果中的业务错误码，必要时清理缓存 */
+    afterCall(ctx, result) {
+        checkBizErrorAndClearCache(result, ctx.category);
+        // 不修改 result，透传给下一个拦截器
+        return result;
+    },
+};
+// ============================================================================
+// 内部实现
+// ============================================================================
 /**
  * 检查 tools/call 的返回结果中是否包含需要清理缓存的业务错误码
- *
- * MCP Server 可能在正常的 JSON-RPC 响应中返回业务层错误，
- * 这些错误被包裹在 result.content[].text 中，需要解析后判断。
  */
-const checkBizErrorAndClearCache = (result, category) => {
+function checkBizErrorAndClearCache(result, category) {
     if (!result || typeof result !== "object")
         return;
     const { content } = result;
@@ -3369,14 +4305,39 @@ const checkBizErrorAndClearCache = (result, category) => {
             // text 不是 JSON 格式，跳过
         }
     }
+}
+
+/**
+ * get_msg_media 响应拦截器
+ *
+ * 核心逻辑：
+ * 1. beforeCall: 设置延长的超时时间（120s），因为 base64 数据可达 ~27MB
+ * 2. afterCall: 从 MCP result 的 content[].text 中提取 base64_data，
+ *    解码为 Buffer 并通过 saveMediaBuffer 保存到本地媒体目录，
+ *    替换响应中的 base64_data 为 local_path，避免大模型被 base64 数据消耗 token
+ */
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+const mediaInterceptor = {
+    name: "media",
+    /** 仅对 get_msg_media 方法生效 */
+    match: (ctx) => ctx.method === "get_msg_media",
+    /** 设置延长的超时时间 */
+    beforeCall() {
+        return { timeoutMs: MEDIA_DOWNLOAD_TIMEOUT_MS };
+    },
+    /** 拦截响应：base64 → 本地文件 */
+    async afterCall(ctx, result) {
+        return interceptMediaResponse(result);
+    },
 };
 // ============================================================================
-// get_msg_media 响应拦截：base64 → 本地文件
+// 内部实现
 // ============================================================================
 /**
  * 拦截 get_msg_media 的 MCP 响应
  *
- * 核心逻辑：
  * 1. 从 MCP result 的 content[].text 中提取业务 JSON
  * 2. 提取 media_item.base64_data，解码为 Buffer
  * 3. 通过 openclaw SDK 的 saveMediaBuffer 保存到本地媒体目录
@@ -3474,31 +4435,384 @@ async function interceptMediaResponse(result) {
             }],
     };
 }
+
+/**
+ * smartpage_create 请求拦截器
+ *
+ * 核心逻辑：
+ * smartpage_create 的 pages 数组中，每个 page 可能包含 page_filepath 字段
+ * （指向本地 markdown 文件），用于避免在命令行传递大段文本内容。
+ * 本拦截器在 beforeCall 阶段遍历 pages 数组，逐个读取 page_filepath
+ * 指向的本地文件内容，填入 page_content 字段，并移除 page_filepath。
+ *
+ * 入参约定：
+ *   wecom_mcp call doc smartpage_create '{
+ *     "title": "主页标题",
+ *     "pages": [
+ *       {"page_title": "页面1", "page_filepath": "/tmp/page1.md", "content_type": "markdown"},
+ *       {"page_title": "页面2", "page_filepath": "/tmp/page2.md", "content_type": "markdown"}
+ *     ]
+ *   }'
+ *
+ * 拦截器行为：
+ *   1. 检测 args.pages 数组
+ *   2. 校验文件大小：单文件不超过 10MB，所有文件总计不超过 20MB
+ *   3. 遍历每个 page，若存在 page_filepath 则读取本地文件内容
+ *   4. 将文件内容填入 page_content 字段，移除 page_filepath
+ *   5. 返回修改后的完整 args
+ *
+ * 传给 MCP Server 的格式：
+ *   { "title": "...", "pages": [{"page_title": "...", "page_content": "...", "content_type": "..."}] }
+ */
+// ============================================================================
+// 常量
+// ============================================================================
+/** 单个 page_filepath 文件大小上限：10MB */
+const MAX_SINGLE_FILE_SIZE = 10 * 1024 * 1024;
+/** 所有 page_filepath 文件总大小上限：20MB */
+const MAX_TOTAL_FILE_SIZE = 20 * 1024 * 1024;
+// ============================================================================
+// 内部辅助函数
+// ============================================================================
+/**
+ * 校验所有 page_filepath 的文件大小
+ *
+ * 使用 fs.stat 在读取文件内容之前检查大小，避免超大文件被加载到内存。
+ * - 单文件 > 10MB → 报错
+ * - 所有文件累计 > 20MB → 报错
+ */
+async function validateFileSize(pages) {
+    let totalSize = 0;
+    for (let i = 0; i < pages.length; i++) {
+        const filePath = pages[i].page_filepath;
+        if (typeof filePath !== "string" || !filePath)
+            continue;
+        let stat;
+        try {
+            stat = await fs__namespace.stat(filePath);
+        }
+        catch (err) {
+            // stat 失败不在这里处理，留给后续 readFile 阶段抛出更详细的错误
+            continue;
+        }
+        if (stat.size > MAX_SINGLE_FILE_SIZE) {
+            console.error(`[mcp] smartpage_create: pages[${i}] 文件 "${filePath}" ` +
+                `大小 ${(stat.size / 1024 / 1024).toFixed(1)}MB 超过单文件上限 10MB`);
+            throw new Error("内容大小超出限制，无法创建");
+        }
+        totalSize += stat.size;
+        if (totalSize > MAX_TOTAL_FILE_SIZE) {
+            console.error(`[mcp] smartpage_create: 累计文件大小 ${(totalSize / 1024 / 1024).toFixed(1)}MB ` +
+                `超过总上限 20MB（在 pages[${i}] "${filePath}" 处超出）`);
+            throw new Error("内容大小超出限制，无法创建");
+        }
+    }
+    if (totalSize > 0) {
+        console.log(`[mcp] smartpage_create: 文件大小校验通过，总计 ${(totalSize / 1024 / 1024).toFixed(2)}MB`);
+    }
+}
+/** 异步解析 pages 中的 page_filepath，返回 BeforeCallOptions */
+async function resolvePages(ctx, pages) {
+    console.log(`[mcp] smartpage_create: 开始解析 ${pages.length} 个 page 的 page_filepath`);
+    // 阶段 1：文件大小校验（stat 阶段，不读内容）
+    await validateFileSize(pages);
+    // 阶段 2：读取文件内容
+    const resolvedPages = await Promise.all(pages.map(async (page, index) => {
+        const filePath = page.page_filepath;
+        if (typeof filePath !== "string" || !filePath) {
+            // 该 page 没有 page_filepath，保留原样（可能已有 page_content）
+            return page;
+        }
+        let fileContent;
+        try {
+            fileContent = await fs__namespace.readFile(filePath, "utf-8");
+        }
+        catch (err) {
+            throw new Error(`smartpage_create: pages[${index}] 无法读取文件 "${filePath}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        console.log(`[mcp] smartpage_create: pages[${index}] 读取成功 "${filePath}" (${fileContent.length} chars)`);
+        // 构造新的 page 对象：填入 page_content，移除 page_filepath
+        const { page_filepath: _, ...rest } = page;
+        return { ...rest, page_content: fileContent };
+    }));
+    console.log(`[mcp] smartpage_create: 所有 page_filepath 解析完成`);
+    // 返回修改后的完整 args
+    return {
+        args: {
+            ...ctx.args,
+            pages: resolvedPages,
+        },
+    };
+}
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+const smartpageCreateInterceptor = {
+    name: "smartpage-create",
+    /** 仅对 doc 品类的 smartpage_create 方法生效 */
+    match: (ctx) => ctx.category === "doc" && ctx.method === "smartpage_create",
+    /** 遍历 pages 数组，逐个读取 page_filepath 填入 page_content */
+    beforeCall(ctx) {
+        const pages = ctx.args.pages;
+        if (!Array.isArray(pages) || pages.length === 0) {
+            // 没有 pages 数组，不做拦截
+            return undefined;
+        }
+        // 检查是否有任何 page 包含 page_filepath
+        const hasFilePath = pages.some((p) => typeof p.page_filepath === "string" && p.page_filepath);
+        if (!hasFilePath) {
+            // 所有 page 都没有 page_filepath（可能直接传了 page_content），不做拦截
+            return undefined;
+        }
+        return resolvePages(ctx, pages);
+    },
+};
+
+/**
+ * smartpage_get_export_result 响应拦截器
+ *
+ * 核心逻辑：
+ * MCP Server 返回的 smartpage_get_export_result 响应中，当 task_done=true 时
+ * 会包含 content 字段（markdown 文本内容）。该内容可能很大，直接返回给 LLM
+ * 会消耗大量 token。
+ *
+ * 本拦截器在 afterCall 阶段：
+ * 1. 检测 task_done=true 且存在 content 字段
+ * 2. 将 content 保存到本地文件（使用与 msg-media 一致的媒体目录）
+ * 3. 用 content_path（文件路径）替换 content 字段
+ *
+ * 这样 LLM 只看到轻量的文件路径信息，Skill 可通过文件路径读取完整内容。
+ */
+// ============================================================================
+// 拦截器实现
+// ============================================================================
+const smartpageExportInterceptor = {
+    name: "smartpage-export",
+    /** 仅对 doc 品类的 smartpage_get_export_result 方法生效 */
+    match: (ctx) => ctx.category === "doc" && ctx.method === "smartpage_get_export_result",
+    /** 拦截响应：将 markdown content 保存为本地文件 */
+    async afterCall(_ctx, result) {
+        return interceptExportResponse(result);
+    },
+};
+// ============================================================================
+// 内部实现
+// ============================================================================
+/**
+ * 拦截 smartpage_get_export_result 的 MCP 响应
+ *
+ * 1. 从 MCP result 的 content[].text 中提取业务 JSON
+ * 2. 检测 task_done=true 且存在 content 字段
+ * 3. 将 content（markdown 文本）通过 saveMediaBuffer 保存到本地媒体目录
+ * 4. 构造新响应：移除 content，添加 content_path
+ */
+async function interceptExportResponse(result) {
+    // 1. 提取 MCP result 中的 content 数组
+    const content = result?.content;
+    if (!Array.isArray(content))
+        return result;
+    const textItem = content.find((c) => c.type === "text" && typeof c.text === "string");
+    if (!textItem)
+        return result;
+    // 2. 解析业务 JSON
+    let bizData;
+    try {
+        bizData = JSON.parse(textItem.text);
+    }
+    catch {
+        // 非 JSON 格式，原样返回
+        return result;
+    }
+    // 3. 校验：errcode !== 0 或 task_done 不为 true 或无 content 时原样返回
+    if (bizData.errcode !== 0)
+        return result;
+    if (bizData.task_done !== true)
+        return result;
+    if (typeof bizData.content !== "string")
+        return result;
+    const markdownContent = bizData.content;
+    console.log(`[mcp] smartpage_get_export_result: 拦截 content (${markdownContent.length} chars)，保存到本地文件`);
+    // 4. 将 markdown 内容通过 saveMediaBuffer 保存到本地媒体目录
+    //    使用 text/markdown 类型，与 msg-media 拦截器保持一致的路径管理
+    const buffer = Buffer.from(markdownContent, "utf-8");
+    const core = getWeComRuntime();
+    const saved = await core.channel.media.saveMediaBuffer(buffer, "text/markdown", "inbound", undefined, // maxBytes: markdown 文本通常不大，使用默认限制
+    "smartpage_export.md");
+    console.log(`[mcp] smartpage_get_export_result: 已保存到 ${saved.path}`);
+    // 5. 构造新响应：移除 content，添加 content_path
+    const newBizData = {
+        errcode: bizData.errcode,
+        errmsg: bizData.errmsg ?? "ok",
+        task_done: true,
+        content_path: saved.path,
+    };
+    // 6. 返回修改后的 MCP result 结构
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify(newBizData),
+            }],
+    };
+}
+
+/**
+ * MCP call 拦截器注册表与调度入口
+ *
+ * 所有 call 拦截器在此注册，按注册顺序执行。
+ * 新增拦截器只需：
+ *   1. 在 interceptors/ 目录下新建文件，实现 CallInterceptor 接口
+ *   2. 在下方 interceptors 数组中注册
+ *
+ * tool.ts 的 handleCall 无需任何改动。
+ */
+// ============================================================================
+// 拦截器注册表（按注册顺序执行）
+// ============================================================================
+const interceptors = [
+    bizErrorInterceptor, // 业务错误码检查（所有 call 生效）
+    mediaInterceptor, // get_msg_media base64 拦截
+    smartpageCreateInterceptor, // smartpage_create 本地文件读取
+    smartpageExportInterceptor, // smartpage_get_export_result content → 本地文件
+];
+/**
+ * 收集匹配的 beforeCall 配置，合并后返回
+ *
+ * 合并策略：
+ * - timeoutMs: 取所有拦截器返回值中的最大值
+ * - args: 后注册的拦截器覆盖前者（一般同一调用只有一个拦截器会返回 args）
+ */
+async function resolveBeforeCall(ctx) {
+    let mergedTimeoutMs;
+    let mergedArgs;
+    for (const interceptor of interceptors) {
+        if (!interceptor.match(ctx) || !interceptor.beforeCall)
+            continue;
+        const opts = await interceptor.beforeCall(ctx);
+        if (opts?.timeoutMs !== undefined) {
+            mergedTimeoutMs = mergedTimeoutMs === undefined
+                ? opts.timeoutMs
+                : Math.max(mergedTimeoutMs, opts.timeoutMs);
+        }
+        if (opts?.args !== undefined) {
+            mergedArgs = opts.args;
+        }
+    }
+    return {
+        options: mergedTimeoutMs !== undefined ? { timeoutMs: mergedTimeoutMs } : undefined,
+        args: mergedArgs,
+    };
+}
+/**
+ * 依次执行匹配的 afterCall 拦截器，管道式传递 result
+ *
+ * 前一个拦截器的返回值作为下一个拦截器的输入。
+ * 拦截器若不需要修改 result，应原样返回。
+ */
+async function runAfterCall(ctx, result) {
+    let current = result;
+    for (const interceptor of interceptors) {
+        if (!interceptor.match(ctx) || !interceptor.afterCall)
+            continue;
+        current = await interceptor.afterCall(ctx, current);
+    }
+    return current;
+}
+
+/**
+ * wecom_mcp — 模拟 MCP 调用的 Agent Tool
+ *
+ * 通过 MCP Streamable HTTP 传输协议调用企业微信 MCP Server，
+ * 提供 list（列出所有工具）和 call（调用工具）两个操作。
+ *
+ * 在 skills 中的使用方式：
+ *   wecom_mcp list <category>
+ *   wecom_mcp call <category> <method> '<jsonArgs>'
+ *
+ * 示例：
+ *   wecom_mcp list contact
+ *   wecom_mcp call contact getContact '{}'
+ */
+// ============================================================================
+// 响应构造辅助
+// ============================================================================
+/** 构造统一的文本响应结构 */
+const textResult = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+/** 构造错误响应 */
+const errorResult = (err) => {
+    // 适配企业微信 API 返回的 { errcode, errmsg } 结构
+    if (err && typeof err === "object" && "errcode" in err) {
+        const { errcode, errmsg } = err;
+        return textResult({ error: errmsg ?? `错误码: ${errcode}`, errcode });
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return textResult({ error: message });
+};
+// ============================================================================
+// list 操作：列出某品类的所有 MCP 工具
+// ============================================================================
+const handleList = async (category) => {
+    const result = await sendJsonRpc(category, "tools/list");
+    const tools = result?.tools ?? [];
+    if (tools.length === 0) {
+        return { message: `品类 "${category}" 下暂无可用工具`, tools: [] };
+    }
+    return {
+        category,
+        count: tools.length,
+        tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description ?? "",
+            // 清洗 inputSchema，内联 $ref/$defs 引用并移除 Gemini 不支持的关键词，
+            // 避免 Gemini 模型解析 function response 时报 400 错误
+            inputSchema: t.inputSchema ? cleanSchemaForGemini(t.inputSchema) : undefined,
+        })),
+    };
+};
 // ============================================================================
 // call 操作：调用某品类的某个 MCP 工具
 // ============================================================================
 const handleCall = async (category, method, args) => {
+    const ctx = { category, method, args };
     const callStart = performance.now();
-    // get_msg_media 使用延长的超时时间（120s），因为返回的 base64 数据可达 ~27MB
-    const options = method === "get_msg_media" ? { timeoutMs: MEDIA_DOWNLOAD_TIMEOUT_MS } : undefined;
+    console.log(`[mcp] handleCall ${category}/${method} 入参: ${JSON.stringify(args)}`);
+    // 1. 收集拦截器的 beforeCall 配置（如超时时间、替换 args）
+    const { options, args: resolvedArgs } = await resolveBeforeCall(ctx);
+    const finalArgs = resolvedArgs ?? args;
+    if (resolvedArgs) {
+        console.log(`[mcp] handleCall ${category}/${method} 拦截器替换 args: ${JSON.stringify(resolvedArgs).slice(0, 500)}` +
+            (JSON.stringify(resolvedArgs).length > 500 ? "...(truncated)" : ""));
+    }
+    if (options) {
+        console.log(`[mcp] handleCall ${category}/${method} 拦截器选项: ${JSON.stringify(options)}`);
+    }
+    // 2. 执行 MCP 调用
     const result = await sendJsonRpc(category, "tools/call", {
         name: method,
-        arguments: args,
+        arguments: finalArgs,
     }, options);
     const rpcDone = performance.now();
     const rpcMs = (rpcDone - callStart).toFixed(1);
-    // 检查业务层错误码，必要时清理缓存
-    checkBizErrorAndClearCache(result, category);
-    // 对 get_msg_media 响应进行 base64 拦截：解码存本地，只返回路径给大模型
-    if (method === "get_msg_media") {
-        const intercepted = await interceptMediaResponse(result);
-        const totalMs = (performance.now() - callStart).toFixed(1);
+    const resultStr = JSON.stringify(result);
+    console.log(`[mcp] handleCall ${category}/${method} MCP 响应 (${rpcMs}ms): ${resultStr.slice(0, 800)}` +
+        (resultStr.length > 800 ? "...(truncated)" : ""));
+    // 3. 管道式执行 afterCall 拦截器（业务错误码检查、响应变换等）
+    const finalResult = await runAfterCall(ctx, result);
+    const totalMs = (performance.now() - callStart).toFixed(1);
+    const interceptMs = (performance.now() - rpcDone).toFixed(1);
+    // 有拦截器处理时打印详细耗时，否则只打印 RPC 耗时
+    if (finalResult !== result) {
+        const finalStr = JSON.stringify(finalResult);
+        console.log(`[mcp] handleCall ${category}/${method} afterCall 变换后 (${interceptMs}ms): ${finalStr.slice(0, 500)}` +
+            (finalStr.length > 500 ? "...(truncated)" : ""));
         console.log(`[mcp] handleCall ${category}/${method} 总耗时: ${totalMs}ms` +
-            ` (MCP请求: ${rpcMs}ms, 拦截处理: ${(performance.now() - rpcDone).toFixed(1)}ms)`);
-        return intercepted;
+            ` (MCP请求: ${rpcMs}ms, 拦截处理: ${interceptMs}ms)`);
+    }
+    else {
+        console.log(`[mcp] handleCall ${category}/${method} 耗时: ${rpcMs}ms`);
     }
-    console.log(`[mcp] handleCall ${category}/${method} 耗时: ${rpcMs}ms`);
-    return result;
+    return finalResult;
 };
 // ============================================================================
 // 参数解析
@@ -3568,22 +4882,36 @@ function createWeComMcpTool() {
         },
         async execute(_toolCallId, params) {
             const p = params;
+            console.log(`[mcp] execute: action=${p.action}, category=${p.category}` +
+                (p.method ? `, method=${p.method}` : "") +
+                (p.args ? `, args=${typeof p.args === "string" ? p.args : JSON.stringify(p.args)}` : ""));
             try {
+                let result;
                 switch (p.action) {
                     case "list":
-                        return textResult(await handleList(p.category));
+                        result = textResult(await handleList(p.category));
+                        break;
                     case "call": {
                         if (!p.method) {
-                            return textResult({ error: "action 为 call 时必须提供 method 参数" });
+                            result = textResult({ error: "action 为 call 时必须提供 method 参数" });
+                            break;
                         }
                         const args = parseArgs(p.args);
-                        return textResult(await handleCall(p.category, p.method, args));
+                        result = textResult(await handleCall(p.category, p.method, args));
+                        break;
                     }
                     default:
-                        return textResult({ error: `未知操作类型: ${String(p.action)}，支持 list 和 call` });
+                        result = textResult({ error: `未知操作类型: ${String(p.action)}，支持 list 和 call` });
                 }
+                console.log(`[mcp] execute: action=${p.action}, category=${p.category}` +
+                    (p.method ? `, method=${p.method}` : "") +
+                    ` → 响应长度=${result.content[0].text.length} chars`);
+                return result;
             }
             catch (err) {
+                console.error(`[mcp] execute: action=${p.action}, category=${p.category}` +
+                    (p.method ? `, method=${p.method}` : "") +
+                    ` → 异常: ${err instanceof Error ? err.message : String(err)}`);
                 return errorResult(err);
             }
         },
@@ -3613,7 +4941,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"),
             };
         });