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

package/dist/src/const.d.ts

@@ -70,3 +70,5 @@ export declare const EVENT_ENTER_CHECK_UPDATE = "event.enter_check_update";
 export declare const CMD_ENTER_EVENT_REPLY = "ww_ai_robot_enter_event";
 /** WSClient scene 参数：企微 OpenClaw 场景 */
 export declare const SCENE_WECOM_OPENCLAW = 1;
+/** 合法的模板卡片 card_type 列表 */
+export declare const VALID_CARD_TYPES: string[];

package/dist/src/interface.d.ts

@@ -23,8 +23,6 @@ export interface MessageState {
     accumulatedText: string;
     /** 流式回复的 streamId，用于保持同一个流式回复使用相同的 streamId */
     streamId?: string;
-    /** 是否有用户可见的文本内容（不包括 <think>...</think> 标签） */
-    hasText?: boolean;
     /** 是否已成功发送过媒体文件 */
     hasMedia?: boolean;
     /** 是否有媒体发送失败（权限不足、文件过大等） */
@@ -35,6 +33,22 @@ export interface MessageState {
     deliverCalled?: boolean;
     /** 流式回复是否已过期（errcode 846608，>6分钟），需降级为主动发送 */
     streamExpired?: boolean;
+    /** 是否已成功发送过模板卡片 */
+    hasTemplateCard?: boolean;
+}
+/** 从文本中提取的模板卡片 */
+export interface ExtractedTemplateCard {
+    /** 原始 JSON 对象（已验证 card_type 合法） */
+    cardJson: Record<string, unknown>;
+    /** card_type 值 */
+    cardType: string;
+}
+/** extractTemplateCards 返回值 */
+export interface TemplateCardExtractionResult {
+    /** 提取到的合法模板卡片列表 */
+    cards: ExtractedTemplateCard[];
+    /** 移除卡片代码块后的剩余文本 */
+    remainingText: string;
 }
 /**
  * WebSocket 请求消息基础格式
@@ -70,20 +84,20 @@ export interface WeComSubscribeRequest extends WeComRequest {
  * 企业微信推送消息格式
  */
 export interface WeComCallbackMessage {
-    cmd: WeComCommand.AIBOT_CALLBACK;
+    cmd: WeComCommand.AIBOT_CALLBACK | "aibot_event_callback";
     headers: {
         req_id: string;
     };
     body: {
         msgid: string;
         aibotid: string;
-        chatid: string;
+        chatid?: string;
         chattype: "single" | "group";
         from: {
             userid: string;
         };
         response_url: string;
-        msgtype: "text" | "image" | "voice" | "video" | "file" | "stream" | "mixed";
+        msgtype: "text" | "image" | "voice" | "video" | "file" | "stream" | "mixed" | "event";
         text?: {
             content: string;
         };
@@ -125,6 +139,22 @@ export interface WeComCallbackMessage {
         stream?: {
             id: string;
         };
+        event?: {
+            eventtype: string;
+            template_card_event?: {
+                card_type?: string;
+                event_key?: string;
+                task_id?: string;
+                selected_items?: {
+                    selected_item?: Array<{
+                        question_key?: string;
+                        option_ids?: {
+                            option_id?: string[];
+                        };
+                    }>;
+                };
+            };
+        };
     };
 }
 /**

package/dist/src/message-parser.d.ts

@@ -9,6 +9,7 @@ export interface MessageBody {
     chatid?: string;
     chattype: "single" | "group";
     from: {
+        corpid?: string;
         userid: string;
     };
     response_url?: string;
@@ -56,6 +57,22 @@ export interface MessageBody {
             aeskey?: string;
         };
     };
+    event?: {
+        eventtype?: string;
+        template_card_event?: {
+            card_type?: string;
+            event_key?: string;
+            task_id?: string;
+            selected_items?: {
+                selected_item?: Array<{
+                    question_key?: string;
+                    option_ids?: {
+                        option_id?: string[];
+                    };
+                }>;
+            };
+        };
+    };
 }
 export interface ParsedMessageContent {
     textParts: string[];
@@ -66,7 +83,7 @@ export interface ParsedMessageContent {
     quoteContent: string | undefined;
 }
 /**
- * 解析消息内容（支持单条消息、图文混排和引用消息）
+ * 解析消息内容（支持单条消息、图文混排、事件回调和引用消息）
  * @returns 提取的文本数组、图片URL数组和引用消息内容
  */
 export declare function parseMessageContent(body: MessageBody): ParsedMessageContent;

package/dist/src/template-card-parser.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 模板卡片解析器
+ *
+ * 从 LLM 回复文本中提取 markdown JSON 代码块，验证其是否为合法的企业微信模板卡片，
+ * 返回提取到的卡片列表和剩余文本。
+ *
+ * 同时提供 maskTemplateCardBlocks 函数，用于在流式中间帧中隐藏正在构建的卡片代码块，
+ * 避免 JSON 源码暴露给终端用户。
+ */
+import type { TemplateCardExtractionResult } from "./interface.js";
+/**
+ * 从文本中提取模板卡片 JSON 代码块
+ *
+ * 匹配规则：
+ * 1. 匹配所有 ```json ... ``` 或 ``` ... ``` 格式的代码块
+ * 2. 尝试 JSON.parse 解析代码块内容
+ * 3. 检查解析结果中是否包含合法的 card_type 字段
+ * 4. 合法的卡片从原文中移除，不合法的保留
+ *
+ * @param text - LLM 回复的完整文本
+ * @returns 提取结果，包含卡片列表和剩余文本
+ */
+export declare function extractTemplateCards(text: string, log?: (...args: any[]) => void): TemplateCardExtractionResult;
+/**
+ * 遮罩文本中的模板卡片代码块（用于流式中间帧展示）
+ *
+ * 在 LLM 流式输出过程中，累积文本可能包含：
+ * 1. 已闭合的模板卡片 JSON 代码块 → 替换为友好提示文本
+ * 2. 正在构建中的未闭合代码块 → 截断隐藏，避免 JSON 源码暴露
+ *
+ * 此函数仅做文本替换，不做 JSON 解析验证（中间帧性能优先）。
+ * 只要代码块内容中出现 "card_type" 关键词就认为是模板卡片并遮罩。
+ *
+ * @param text - 当前累积文本
+ * @returns 遮罩后的展示文本
+ */
+export declare function maskTemplateCardBlocks(text: string, log?: (...args: any[]) => void): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "2026.3.25-beta.1",
+  "version": "2026.3.25-beta.2",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",

package/skills/wecom-send-template-card/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: wecom-send-template-card
+description: 企业微信模板卡片消息技能。当对话中存在需要用户做出选择、确认、投票或查看结构化信息的场景时，自动识别并使用最合适的模板卡片类型发送消息。支持文本通知（text_notice）、图文展示（news_notice）、按钮交互（button_interaction）、投票选择（vote_interaction）、多项选择（multiple_interaction）五种卡片类型。当你需要向用户展示多个方案让其选择时、需要发起投票时、需要发送结构化通知时、需要用户在多个维度上做出选择时，都应该使用此技能而不是纯文本消息。即使用户没有明确要求"发卡片"，只要对话语境适合使用卡片（如"帮我问一下张三选 A 还是 B"），也应主动使用。仅当通过 wecom 通道通信时使用此技能。
+metadata:
+  {
+    "openclaw": { "emoji": "🃏", "requires": { "config": ["channels.wecom"] } },
+  }
+---
+
+---
+
+## 使用方式
+
+在回复文本中直接输出一个 markdown JSON 代码块，代码块中的 JSON 必须格式正确、合法且包含 `card_type` 字段。插件层会自动从回复中检测并提取该 JSON 字符串并 Parse，然后通过企业微信 SDK 发送模板卡片消息。
+
+### 输出格式
+
+在你的回复中，正常文本照常输出，需要发送模板卡片时，将完整的 template_card JSON 包裹在 markdown 代码块中：
+
+````
+你的正常回复文本...
+
+```json
+{
+  "card_type": "卡片类型",
+  ... 卡片内容 ...
+}
+```
+
+可以继续输出其他文本...
+````
+
+### 格式要求
+
+1. **必须使用 markdown 代码块**：用 ` ```json ` 和 ` ``` ` 包裹 JSON
+2. **必须包含 `card_type` 字段**：值为以下五种之一：`text_notice`、`news_notice`、`button_interaction`、`vote_interaction`、`multiple_interaction`
+3. **JSON 必须合法**：确保能被 `JSON.parse` 正确解析，生成后请自查一次。
+4. **一次回复可包含多个卡片**：每个卡片用独立的代码块包裹
+5. **代码块外的文本正常展示**：提取卡片后，剩余文本会作为普通流式回复发送给用户
+
+### 重要注意事项
+
+- **不要使用 MCP 工具调用**来发送模板卡片，直接在回复中输出 JSON 代码块即可
+- 代码块中的 JSON 就是 `template_card` 的完整结构体（即企业微信 API 中 `template_card` 字段的值）
+- 不需要包裹外层的 `msgtype`、`chatid` 等字段，只需 `template_card` 本身的内容
+- **字段类型必须严格匹配企业微信 API 要求**：
+  - `mode`、`style`、`type`、`desc_color` 等字段必须为**整数**（如 `0`、`1`），**不能**用字符串（如 `"multi"`、`"single"`）
+  - `disable`、`is_checked` 必须为**布尔值** `true` / `false`，**不能**用字符串
+  - 例：`"mode": 1`（✅ 正确） vs `"mode": "multi"`（❌ 错误）
+
+---
+
+## 场景识别与卡片类型选择
+
+根据对话上下文，自动判断最适合的卡片类型：
+
+| 对话场景 | 推荐卡片类型 | card_type |
+|---------|------------|-----------|
+| 通知提醒、状态更新、信息汇总 | 文本通知模版卡片 | `text_notice` |
+| 带图片的内容展示、新闻资讯、产品介绍 | 图文展示模版卡片 | `news_notice` |
+| 需要用户点击按钮做出选择（如：确认/取消、选择方案 A/B/C） | 按钮交互模版卡片 | `button_interaction` |
+| 需要用户在多个选项中投票（单选或多选） | 投票选择模版卡片 | `vote_interaction` |
+| 需要用户在多个维度上分别做出选择（如：选择时间+地点+人员） | 多项选择模版卡片 | `multiple_interaction` |
+
+### 场景识别关键词
+
+- **文本通知**：通知、提醒、告知、汇报、状态更新、完成通知、系统通知
+- **图文展示**：展示、图文、图片说明、产品介绍、新闻推送
+- **按钮交互**：选择方案、确认操作、同意/拒绝、选一个、A还是B、需要你确认
+- **投票选择**：投票、表决、评选、单选/多选、最喜欢哪个
+- **多项选择**：多个维度选择、分别选择、组合选择、多个下拉框
+
+---
+
+## 五种卡片类型详细说明
+
+请参考 [./references/api-template-card-types.md](./references/api-template-card-types.md) 的描述。
+
+## 核心规则
+
+### task_id 生成规则
+
+`task_id` 用于唯一标识一次交互，需确保唯一性。生成规则：
+- 格式：`task_{场景描述}_{时间戳}`
+- 示例：`task_solution_select_1711234567`、`task_vote_team_building_1711234568`
+
+### card_action 规则
+
+- `text_notice` 和 `news_notice` 的 `card_action` 为**必填**字段
+- 若无实际跳转需求，可设置 `type: 1` 并使用一个通用 URL
+- `button_interaction`、`vote_interaction`、`multiple_interaction` 不需要 `card_action`
+
+---
+
+## 典型工作流示例
+
+### 示例 1：发送投票卡片（vote_interaction）
+
+**用户**：帮我发一个投票，让大家选团建活动：爬山、聚餐、密室逃脱
+
+**你的回复**：
+
+好的，我来为你发一个团建活动投票卡片 🗳️
+
+```json
+{
+  "card_type": "vote_interaction",
+  "source": {
+    "desc": "团建投票"
+  },
+  "main_title": {
+    "title": "团建活动投票",
+    "desc": "请选择你最想参加的团建活动"
+  },
+  "checkbox": {
+    "question_key": "team_building_vote",
+    "option_list": [
+      { "id": "opt_hiking", "text": "🏔️ 爬山" },
+      { "id": "opt_dinner", "text": "🍽️ 聚餐" },
+      { "id": "opt_escape", "text": "🔐 密室逃脱" }
+    ],
+    "mode": 1
+  },
+  "submit_button": {
+    "text": "提交投票",
+    "key": "submit_team_building"
+  },
+  "task_id": "task_team_building_vote_1711234567"
+}
+```
+
+投票卡片已发送，大家可以直接在卡片上选择并提交！
+
+### 示例 2：发送按钮交互卡片（button_interaction）
+
+**用户**：有两个技术方案让用户选：A方案重构、B方案兼容
+
+**你的回复**：
+
+好的，我来发一个方案选择卡片：
+
+```json
+{
+  "card_type": "button_interaction",
+  "main_title": {
+    "title": "技术方案选择",
+    "desc": "请选择你倾向的技术方案"
+  },
+  "sub_title_text": "A方案：全面重构，长期收益更高但开发周期长\nB方案：兼容现有架构，快速交付但技术债增加",
+  "button_list": [
+    { "text": "A方案 - 重构", "style": 1, "key": "plan_a_refactor" },
+    { "text": "B方案 - 兼容", "style": 4, "key": "plan_b_compat" }
+  ],
+  "task_id": "task_solution_select_1711234568"
+}
+```
+
+方案选择卡片已发出，等待用户点击选择。
+
+### 示例 3：发送文本通知卡片（text_notice）
+
+**用户**：通知一下项目进度已完成80%
+
+**你的回复**：
+
+```json
+{
+  "card_type": "text_notice",
+  "main_title": {
+    "title": "项目进度更新",
+    "desc": "截至当前，项目整体进度已达到 80%"
+  },
+  "emphasis_content": {
+    "title": "80%",
+    "desc": "项目完成度"
+  },
+  "sub_title_text": "各模块进展顺利，预计按期交付。",
+  "card_action": {
+    "type": 1,
+    "url": "https://work.weixin.qq.com"
+  }
+}
+```
+
+---
+
+## 错误处理
+
+- 如果 JSON 格式不合法或 `card_type` 不在五种类型中，代码块会被保留在原文中作为普通文本展示（不会被提取为卡片）
+- 确保每个交互型卡片（button_interaction、vote_interaction、multiple_interaction）都有唯一的 `task_id`
+- `text_notice` 和 `news_notice` 必须包含 `card_action` 字段