@wecom/wecom-openclaw-plugin 2026.4.2 → 2026.4.3-beta.0

package/dist/src/template-card-manager.js

@@ -0,0 +1,205 @@
+/**
+ * 模板卡片管理器
+ *
+ * 负责：
+ * - 模板卡片缓存管理（内存级，带 TTL 和大小限制）
+ * - 卡片交互事件处理（更新卡片 UI 状态）
+ * - 模板卡片发送（通过 wsClient.sendMessage 主动推送）
+ * - 从 LLM 回复中检测并处理模板卡片
+ */
+import { extractTemplateCards } from "./template-card-parser.js";
+import { TEMPLATE_CARD_CACHE_TTL_MS, TEMPLATE_CARD_CACHE_MAX_SIZE, } from "./const.js";
+const sentTemplateCardByTaskId = new Map();
+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));
+}
+export 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();
+}
+export 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;
+}
+export 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 (cache is in-memory only, may have been cleared after restart)`);
+        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,
+    });
+}
+// ============================================================================
+// 模板卡片发送
+// ============================================================================
+/**
+ * 逐个发送已提取的模板卡片（通过 wsClient.sendMessage 主动推送）
+ *
+ * 发送失败不阻塞流程，仅记录错误日志。
+ */
+export async function sendTemplateCards(params) {
+    const { wsClient, frame, state, runtime, account, cards } = params;
+    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)}`);
+        }
+    }
+}
+// ============================================================================
+// 模板卡片检测与处理（从 finishThinkingStream 中分离）
+// ============================================================================
+/**
+ * 从累积文本中检测并发送模板卡片。
+ *
+ * 在 finishThinkingStream 之前调用，将卡片处理和流关闭解耦。
+ *
+ * @returns 移除卡片代码块后的剩余文本（如果没有卡片则返回 null，表示无需修改）
+ */
+export async function processTemplateCardsIfNeeded(params) {
+    const { state, runtime } = params;
+    const visibleText = state.accumulatedText?.trim();
+    if (!visibleText) {
+        runtime.log?.(`[wecom][template-card] processTemplateCardsIfNeeded: no visibleText, skipping`);
+        return null;
+    }
+    runtime.log?.(`[wecom][template-card] processTemplateCardsIfNeeded: 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] processTemplateCardsIfNeeded: extractTemplateCards result — cards=${cards.length}, remainingTextLength=${remainingText.length}`);
+    if (cards.length === 0) {
+        return null;
+    }
+    runtime.log?.(`[wecom][template-card] processTemplateCardsIfNeeded: ${cards.length} card(s) detected, card_types=[${cards.map(c => c.cardType).join(", ")}]`);
+    await sendTemplateCards({ ...params, cards });
+    return { remainingText, cardsDetected: true };
+}

package/dist/{esm/src → src}/template-card-parser.js

@@ -1,5 +1,3 @@
-import { VALID_CARD_TYPES } from './const.js';
-
 /**
  * 模板卡片解析器
  *
@@ -9,6 +7,7 @@ import { VALID_CARD_TYPES } from './const.js';
  * 同时提供 maskTemplateCardBlocks 函数，用于在流式中间帧中隐藏正在构建的卡片代码块，
  * 避免 JSON 源码暴露给终端用户。
  */
+import { VALID_CARD_TYPES } from "./const.js";
 // ============================================================================
 // LLM 输出字段类型修正
 // ============================================================================
@@ -239,6 +238,19 @@ function normalizeTemplateCardFields(card, log) {
     }
     return card;
 }
+// ============================================================================
+// 必填字段校验与自动补全
+// ============================================================================
+/** task_id 合法字符：数字、字母、_-@ */
+const TASK_ID_RE = /^[a-zA-Z0-9_\-@]+$/;
+/**
+ * 生成一个合法的 task_id。
+ * 格式：task_{cardType}_{timestamp}_{随机4位}，确保唯一且符合 API 要求。
+ */
+function generateTaskId(cardType) {
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `task_${cardType}_${Date.now()}_${rand}`;
+}
 /**
  * 校验并补全模板卡片的必填字段。
  *
@@ -533,7 +545,7 @@ const UNCLOSED_BLOCK_RE = /```(?:json)?\s*\n[\s\S]*$/;
  * @param text - LLM 回复的完整文本
  * @returns 提取结果，包含卡片列表和剩余文本
  */
-function extractTemplateCards(text, log) {
+export function extractTemplateCards(text, log) {
     const cards = [];
     /** 需要从原文中移除的代码块（记录完整匹配内容） */
     const blocksToRemove = [];
@@ -601,7 +613,7 @@ function extractTemplateCards(text, log) {
  * @param text - 当前累积文本
  * @returns 遮罩后的展示文本
  */
-function maskTemplateCardBlocks(text, log) {
+export function maskTemplateCardBlocks(text, log) {
     let masked = text;
     let closedMaskCount = 0;
     let unclosedMasked = false;
@@ -629,10 +641,7 @@ function maskTemplateCardBlocks(text, log) {
     }
     // 有遮罩行为时才打日志，避免每帧都刷屏
     if (closedMaskCount > 0 || unclosedMasked) {
-        log?.(`[template-card-parser] maskTemplateCardBlocks: closedMasked=${closedMaskCount}, unclosedMasked=${unclosedMasked}, textLength=${text.length}, maskedLength=${masked.length}`);
+        // log?.(`[template-card-parser] maskTemplateCardBlocks: closedMasked=${closedMaskCount}, unclosedMasked=${unclosedMasked}, textLength=${text.length}, maskedLength=${masked.length}`);
     }
     return masked;
 }
-
-export { extractTemplateCards, maskTemplateCardBlocks };
-//# sourceMappingURL=template-card-parser.js.map

package/dist/{esm/src → src}/timeout.js

@@ -11,7 +11,7 @@
  * @param message - 超时错误消息
  * @returns 带超时保护的 Promise
  */
-function withTimeout(promise, timeoutMs, message) {
+export function withTimeout(promise, timeoutMs, message) {
     if (timeoutMs <= 0 || !Number.isFinite(timeoutMs)) {
         return promise;
     }
@@ -28,12 +28,9 @@ function withTimeout(promise, timeoutMs, message) {
 /**
  * 超时错误类型
  */
-class TimeoutError extends Error {
+export class TimeoutError extends Error {
     constructor(message) {
         super(message);
         this.name = "TimeoutError";
     }
 }
-
-export { TimeoutError, withTimeout };
-//# sourceMappingURL=timeout.js.map

package/dist/src/types/account.d.ts

@@ -0,0 +1,29 @@
+/**
+ * WeCom 账号类型定义
+ */
+import type { WecomAgentConfig, WecomNetworkConfig } from "./config.js";
+/**
+ * 解析后的 Agent 账号
+ */
+export type ResolvedAgentAccount = {
+    /** 账号 ID */
+    accountId: string;
+    /** 是否启用 */
+    enabled: boolean;
+    /** 是否配置完整 */
+    configured: boolean;
+    /** 企业 ID */
+    corpId: string;
+    /** 应用 Secret */
+    corpSecret: string;
+    /** 应用 ID (数字，可选) */
+    agentId?: number;
+    /** 回调 Token */
+    token: string;
+    /** 回调加密密钥 */
+    encodingAESKey: string;
+    /** 原始配置 */
+    config: WecomAgentConfig;
+    /** 网络配置（来自 channels.wecom.network） */
+    network?: WecomNetworkConfig;
+};

package/dist/src/types/account.js

@@ -0,0 +1,4 @@
+/**
+ * WeCom 账号类型定义
+ */
+export {};

package/dist/src/types/config.d.ts

@@ -0,0 +1,91 @@
+/**
+ * WeCom 子模块配置类型定义
+ *
+ * 注意：顶层配置类型 WeComConfig 定义在 src/utils.ts 中，以平铺结构为准。
+ * 本文件仅定义 Agent/Bot/DM/Network/Media 等子模块的配置类型。
+ */
+/** 媒体处理配置 */
+export type WecomMediaConfig = {
+    tempDir?: string;
+    retentionHours?: number;
+    cleanupOnStart?: boolean;
+    maxBytes?: number;
+};
+/** 网络配置 */
+export type WecomNetworkConfig = {
+    timeoutMs?: number;
+    retries?: number;
+    retryDelayMs?: number;
+    /**
+     * 出口代理（用于企业可信 IP 固定出口场景）。
+     * 示例: "http://proxy.company.local:3128"
+     */
+    egressProxyUrl?: string;
+};
+/**
+ * Bot 模式配置 (智能体)
+ * 用于接收 JSON 格式回调 + 流式回复
+ */
+export type WecomBotConfig = {
+    /** 智能机器人 ID（用于 Matrix 模式二次身份确认，webhook 模式） */
+    aibotid?: string;
+    /** 回调 Token (企微后台生成，webhook 模式必填) */
+    token?: string;
+    /** 回调加密密钥 (企微后台生成，webhook 模式必填) */
+    encodingAESKey?: string;
+    /**
+     * BotId 列表（可选，用于审计与告警）。
+     * - 回调路由优先由 URL + 签名决定；botIds 不参与强制拦截。
+     * - 当解密后的 aibotid 不在 botIds 中时，仅记录告警日志。
+     */
+    botIds?: string[];
+    /** 接收者 ID (可选，用于解密校验) */
+    receiveId?: string;
+    /** 流式消息占位符 */
+    streamPlaceholderContent?: string;
+    /** 欢迎语 */
+    welcomeText?: string;
+    /** DM 策略: 'open' 允许所有人, 'pairing' 需要配对, 'allowlist' 仅允许列表, 'disabled' 禁用 */
+    dmPolicy?: 'open' | 'pairing' | 'allowlist' | 'disabled';
+    /** 允许的用户列表，为空表示允许所有人 */
+    allowFrom?: Array<string | number>;
+    /** 连接模式：webhook（默认）或 websocket */
+    connectionMode?: 'webhook' | 'websocket';
+    /** 机器人 BotID（websocket 模式必填，企微后台获取） */
+    botId?: string;
+    /** 机器人 Secret（websocket 模式必填，企微后台获取） */
+    secret?: string;
+};
+/**
+ * Agent 模式配置 (自建应用)
+ * 用于接收 XML 格式回调 + API 主动发送
+ */
+export type WecomAgentConfig = {
+    /** 企业 ID */
+    corpId: string;
+    /** 应用 Secret */
+    corpSecret: string;
+    /** 应用 ID（可选；不填时可接收回调，但主动发送需具备该字段） */
+    agentId?: number | string;
+    /** 回调 Token (企微后台「设置API接收」) */
+    token: string;
+    /** 回调加密密钥 (企微后台「设置API接收」) */
+    encodingAESKey: string;
+    /** 欢迎语 */
+    welcomeText?: string;
+    /** DM 策略: 'open' 允许所有人, 'pairing' 需要配对, 'allowlist' 仅允许列表, 'disabled' 禁用 */
+    dmPolicy?: 'open' | 'pairing' | 'allowlist' | 'disabled';
+    /** 允许的用户列表，为空表示允许所有人 */
+    allowFrom?: Array<string | number>;
+};
+/** 动态 Agent 配置 */
+export type WecomDynamicAgentsConfig = {
+    /** 是否启用动态 Agent */
+    enabled?: boolean;
+    /** 私聊：是否为每个用户创建独立 Agent */
+    dmCreateAgent?: boolean;
+    /** 群聊：是否启用动态 Agent */
+    groupEnabled?: boolean;
+    /** 管理员列表（绕过动态路由，使用主 Agent） */
+    adminUsers?: string[];
+};

package/dist/src/types/config.js

@@ -0,0 +1,7 @@
+/**
+ * WeCom 子模块配置类型定义
+ *
+ * 注意：顶层配置类型 WeComConfig 定义在 src/utils.ts 中，以平铺结构为准。
+ * 本文件仅定义 Agent/Bot/DM/Network/Media 等子模块的配置类型。
+ */
+export {};

package/dist/src/types/constants.d.ts

@@ -0,0 +1,42 @@
+/**
+ * WeCom 双模式常量定义
+ */
+/** 固定 Webhook 路径 */
+export declare const WEBHOOK_PATHS: {
+    /** Bot 模式历史兼容路径（不再维护） */
+    readonly BOT: "/wecom";
+    /** Bot 模式历史备用兼容路径（不再维护） */
+    readonly BOT_ALT: "/wecom/bot";
+    /** Agent 模式历史兼容路径（不再维护） */
+    readonly AGENT: "/wecom/agent";
+    /** Bot 模式推荐路径前缀 */
+    readonly BOT_PLUGIN: "/plugins/wecom/bot";
+    /** Agent 模式推荐路径前缀 */
+    readonly AGENT_PLUGIN: "/plugins/wecom/agent";
+};
+/** 企业微信 API 端点 */
+export declare const API_ENDPOINTS: {
+    readonly GET_TOKEN: "https://qyapi.weixin.qq.com/cgi-bin/gettoken";
+    readonly SEND_MESSAGE: "https://qyapi.weixin.qq.com/cgi-bin/message/send";
+    readonly SEND_APPCHAT: "https://qyapi.weixin.qq.com/cgi-bin/appchat/send";
+    readonly UPLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/upload";
+    readonly DOWNLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/get";
+};
+/** 各类限制常量 */
+export declare const LIMITS: {
+    /** 文本消息最大字节数 */
+    readonly TEXT_MAX_BYTES: 2048;
+    /** Token 刷新缓冲时间 (提前刷新) */
+    readonly TOKEN_REFRESH_BUFFER_MS: 60000;
+    /** HTTP 请求超时 */
+    readonly REQUEST_TIMEOUT_MS: 15000;
+    /** 最大请求体大小 */
+    readonly MAX_REQUEST_BODY_SIZE: number;
+};
+/** AES 加密常量 */
+export declare const CRYPTO: {
+    /** PKCS#7 块大小 */
+    readonly PKCS7_BLOCK_SIZE: 32;
+    /** AES Key 长度 */
+    readonly AES_KEY_LENGTH: 32;
+};

package/dist/src/types/constants.js

@@ -0,0 +1,42 @@
+/**
+ * WeCom 双模式常量定义
+ */
+/** 固定 Webhook 路径 */
+export const WEBHOOK_PATHS = {
+    /** Bot 模式历史兼容路径（不再维护） */
+    BOT: "/wecom",
+    /** Bot 模式历史备用兼容路径（不再维护） */
+    BOT_ALT: "/wecom/bot",
+    /** Agent 模式历史兼容路径（不再维护） */
+    AGENT: "/wecom/agent",
+    /** Bot 模式推荐路径前缀 */
+    BOT_PLUGIN: "/plugins/wecom/bot",
+    /** Agent 模式推荐路径前缀 */
+    AGENT_PLUGIN: "/plugins/wecom/agent",
+};
+/** 企业微信 API 端点 */
+export const API_ENDPOINTS = {
+    GET_TOKEN: "https://qyapi.weixin.qq.com/cgi-bin/gettoken",
+    SEND_MESSAGE: "https://qyapi.weixin.qq.com/cgi-bin/message/send",
+    SEND_APPCHAT: "https://qyapi.weixin.qq.com/cgi-bin/appchat/send",
+    UPLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/upload",
+    DOWNLOAD_MEDIA: "https://qyapi.weixin.qq.com/cgi-bin/media/get",
+};
+/** 各类限制常量 */
+export const LIMITS = {
+    /** 文本消息最大字节数 */
+    TEXT_MAX_BYTES: 2048,
+    /** Token 刷新缓冲时间 (提前刷新) */
+    TOKEN_REFRESH_BUFFER_MS: 60_000,
+    /** HTTP 请求超时 */
+    REQUEST_TIMEOUT_MS: 15_000,
+    /** 最大请求体大小 */
+    MAX_REQUEST_BODY_SIZE: 1024 * 1024,
+};
+/** AES 加密常量 */
+export const CRYPTO = {
+    /** PKCS#7 块大小 */
+    PKCS7_BLOCK_SIZE: 32,
+    /** AES Key 长度 */
+    AES_KEY_LENGTH: 32,
+};

package/dist/src/types/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * WeCom 类型统一导出
+ */
+export * from "./constants.js";
+export type { WecomMediaConfig, WecomNetworkConfig, WecomBotConfig, WecomAgentConfig, } from "./config.js";
+export type { ResolvedAgentAccount, } from "./account.js";
+export type { WecomBotInboundBase, WecomBotInboundText, WecomBotInboundVoice, WecomBotInboundVideo, WecomBotInboundStreamRefresh, WecomBotInboundEvent, WecomBotInboundMessage, WecomAgentInboundMessage, WecomInboundQuote, WecomTemplateCard, WecomOutboundMessage, } from "./message.js";

package/dist/src/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * WeCom 类型统一导出
+ */
+// 常量
+export * from "./constants.js";