ylib-wecom-openclaw-plugin 2026.4.29

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

@@ -0,0 +1,157 @@
+---
+name: wecom-send-template-card
+description: 当需要通过企业微信发送结构化卡片消息时使用，包括：通知提醒、投票表决、方案选择、多维度选择等需要用户交互或查看结构化信息的场景。即使用户未明确要求"发卡片"，只要语境适合（如"帮我问一下选A还是B"），也应主动激活。仅限 wecom 通道。
+metadata:
+  {
+    "openclaw": { "emoji": "🃏", "requires": { "config": ["channels.wecom"] } },
+  }
+---
+
+## 使用方式
+
+在回复中输出 ` ```json ``` ` 代码块，内容为符合 [JSON Schema](./references/api-template-card-types.md) 的模板卡片 JSON。插件自动提取并发送。
+
+````
+你的回复文本...
+
+```json
+{
+  "card_type": "...",
+  ...
+}
+```
+````
+
+## 生成规则
+
+1. **严格按 schema 生成**：字段名、类型、嵌套结构必须与 [./references/api-template-card-types.md](./references/api-template-card-types.md) 中的 JSON Schema 定义完全一致
+2. **每张卡片必须有 `task_id`**：格式 `task_{场景}_{时间戳}`，只能包含数字、字母、`_-@`
+3. 不要使用 MCP 工具调用，直接在回复中输出 JSON 代码块
+4. 代码块外的文本会作为普通回复发送
+
+## 卡片类型选择
+
+### 决策流程
+
+```
+用户需求是否需要交互？
+├─ 否（纯通知/信息推送）
+│  ├─ 需要图片展示？ → news_notice
+│  └─ 不需要图片   → text_notice
+│
+└─ 是（需要用户操作）
+   ├─ 从有限选项中做一个操作（≤6个按钮）→ button_interaction
+   ├─ 从一组选项中投票/选择（可多选）    → vote_interaction
+   └─ 提供多个维度的选择（≤3个下拉框）  → multiple_interaction
+```
+
+### 场景速查
+
+| card_type | 典型场景 |
+|-----------|---------|
+| `text_notice` | 系统告警、部署通知、数据日报、审批结果、放假公告 |
+| `news_notice` | 新闻推送、活动宣传、产品发布、带图表的周报、新员工介绍 |
+| `button_interaction` | 审批（同意/驳回）、工单处理（接单/转派）、确认操作、满意度评价、二次确认（是/否） |
+| `vote_interaction` | 团建投票、会议时间协调、问卷单题、意见征集、方案评选 |
+| `multiple_interaction` | 多维度信息收集（部门+楼层+时间）、报障工单（类型+紧急程度）、会议室预定（日期+时间+房间） |
+
+### 易混淆卡片区分
+
+- **button_interaction vs vote_interaction**：按钮型适合"少量选项+即时操作"（如确认/取消），投票型适合"选项多+可多选+统一提交"（如投票）
+- **vote_interaction vs multiple_interaction**：投票型是"一个问题选多项"，多项选择型是"多个独立问题各选一项"（如同时选时间和地点）
+
+## 必填字段速查
+
+| card_type | required |
+|-----------|----------|
+| `text_notice` | `card_type`, `task_id`, `card_action`, (`main_title` 或 `sub_title_text` 至少一个) |
+| `news_notice` | `card_type`, `task_id`, `main_title`, `card_action` |
+| `button_interaction` | `card_type`, `task_id`, `main_title`, `button_list` |
+| `vote_interaction` | `card_type`, `task_id`, `title`, `options` |
+| `multiple_interaction` | `card_type`, `task_id`, `title`, `selectors` |
+
+## 最小示例
+
+### text_notice
+
+```json
+{
+  "card_type": "text_notice",
+  "main_title": { "title": "项目进度更新", "desc": "进度已达 80%" },
+  "emphasis_content": { "title": "80%", "desc": "完成度" },
+  "card_action": { "type": 1, "url": "https://work.weixin.qq.com" },
+  "task_id": "task_progress_1711234567"
+}
+```
+
+### news_notice
+
+```json
+{
+  "card_type": "news_notice",
+  "main_title": { "title": "新功能上线", "desc": "v5.0 已发布" },
+  "card_image": { "url": "https://wework.qpic.cn/wwpic/xxx/0" },
+  "card_action": { "type": 1, "url": "https://work.weixin.qq.com" },
+  "task_id": "task_release_1711234568"
+}
+```
+
+### button_interaction
+
+```json
+{
+  "card_type": "button_interaction",
+  "main_title": { "title": "方案选择", "desc": "请选择技术方案" },
+  "button_list": [
+    { "text": "A方案-重构", "style": 1, "key": "plan_a" },
+    { "text": "B方案-兼容", "style": 4, "key": "plan_b" }
+  ],
+  "task_id": "task_plan_select_1711234569"
+}
+```
+
+### vote_interaction（简化格式）
+
+```json
+{
+  "card_type": "vote_interaction",
+  "title": "团建投票",
+  "description": "选择你想参加的活动",
+  "options": [
+    { "id": "hiking", "text": "爬山" },
+    { "id": "dinner", "text": "聚餐" },
+    { "id": "escape", "text": "密室逃脱" }
+  ],
+  "mode": 1,
+  "submit_text": "提交投票",
+  "task_id": "task_team_vote_1711234570"
+}
+```
+
+### multiple_interaction（简化格式）
+
+```json
+{
+  "card_type": "multiple_interaction",
+  "title": "团建安排",
+  "description": "分别选择时间和地点",
+  "selectors": [
+    {
+      "title": "时间",
+      "options": [
+        { "id": "sat", "text": "周六" },
+        { "id": "sun", "text": "周日" }
+      ]
+    },
+    {
+      "title": "地点",
+      "options": [
+        { "id": "park", "text": "公园" },
+        { "id": "resort", "text": "度假村" }
+      ]
+    }
+  ],
+  "submit_text": "提交选择",
+  "task_id": "task_arrange_1711234571"
+}
+```

package/skills/wecom-send-template-card/references/api-template-card-types.md

@@ -0,0 +1,358 @@
+# 模板卡片类型 - JSON Schema 定义
+
+> 来源：企业微信开发者文档 https://developer.work.weixin.qq.com/document/path/101032
+> 格式：JSON Schema，所有字段名、类型、嵌套层级必须严格遵循
+
+---
+
+## 公共结构体 Schema
+
+以下结构体在多种卡片类型中复用，**字段名必须完全一致**。
+
+### MainTitle
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "title": { "type": "string", "description": "一级标题，建议不超过26字" },
+    "desc":  { "type": "string", "description": "标题辅助信息，建议不超过30字" }
+  }
+}
+```
+
+### Source
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "icon_url":  { "type": "string", "description": "来源图片URL" },
+    "desc":      { "type": "string", "description": "来源描述，建议不超过13字" },
+    "desc_color": { "type": "integer", "enum": [0, 1, 2, 3], "description": "来源文字颜色，只能是0(灰)、1(黑)、2(红)、3(绿)" }
+  }
+}
+```
+
+### CardAction
+
+```json
+{
+  "type": "object",
+  "required": ["type"],
+  "properties": {
+    "type":     { "type": "integer", "enum": [1, 2], "description": "1=跳转url 2=打开小程序（严格只能是1或2）" },
+    "url":      { "type": "string", "description": "跳转url，type=1时必填" },
+    "appid":    { "type": "string", "description": "小程序appid，type=2时必填" },
+    "pagepath": { "type": "string", "description": "小程序pagepath" }
+  }
+}
+```
+
+### EmphasisContent
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "title": { "type": "string", "description": "关键数据内容，建议不超过10字" },
+    "desc":  { "type": "string", "description": "关键数据描述，建议不超过15字" }
+  }
+}
+```
+
+### SubmitButton
+
+```json
+{
+  "type": "object",
+  "required": ["text", "key"],
+  "properties": {
+    "text": { "type": "string", "description": "按钮文案，建议不超过10字" },
+    "key":  { "type": "string", "description": "提交按钮的key，用于回调事件" }
+  }
+}
+```
+
+### Button
+
+```json
+{
+  "type": "object",
+  "required": ["text", "key"],
+  "properties": {
+    "text":  { "type": "string", "description": "按钮文案，建议不超过10字" },
+    "style": { "type": "integer", "enum": [1, 2, 3, 4], "description": "按钮样式，只能是1、2、3、4，默认1" },
+    "key":   { "type": "string", "description": "按钮key，用于回调事件" }
+  }
+}
+```
+
+### Checkbox（投票选择题）
+
+```json
+{
+  "type": "object",
+  "required": ["question_key", "option_list"],
+  "properties": {
+    "question_key": { "type": "string", "description": "选择题key，用于回调事件" },
+    "mode":         { "type": "integer", "enum": [0, 1], "description": "0=单选 1=多选（严格只能是0或1，不允许2或其他值），默认0" },
+    "option_list": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "required": ["id", "text"],
+        "properties": {
+          "id":         { "type": "string", "description": "选项id，不可重复" },
+          "text":       { "type": "string", "description": "选项文案，建议不超过11字" },
+          "is_checked": { "type": "boolean", "description": "是否默认选中" }
+        }
+      }
+    }
+  }
+}
+```
+
+### SelectionItem（下拉选择器）
+
+```json
+{
+  "type": "object",
+  "required": ["question_key", "option_list"],
+  "properties": {
+    "question_key": { "type": "string", "description": "选择器key，用于回调事件，不可重复" },
+    "title":        { "type": "string", "description": "选择器标题，建议不超过13字" },
+    "selected_id":  { "type": "string", "description": "默认选定的option id" },
+    "option_list": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 10,
+      "items": {
+        "type": "object",
+        "required": ["id", "text"],
+        "properties": {
+          "id":   { "type": "string", "description": "选项id，不可重复" },
+          "text": { "type": "string", "description": "选项文案，建议不超过10字" }
+        }
+      }
+    }
+  }
+}
+```
+
+### HorizontalContent
+
+```json
+{
+  "type": "object",
+  "required": ["keyname"],
+  "properties": {
+    "type":    { "type": "integer", "enum": [0, 1, 3], "description": "只能是0(普通文本)、1(跳转url)、3(成员详情)，注意没有2" },
+    "keyname": { "type": "string", "description": "二级标题，建议不超过5字" },
+    "value":   { "type": "string", "description": "二级文本，建议不超过26字" },
+    "url":     { "type": "string", "description": "跳转url，type=1时必填" },
+    "userid":  { "type": "string", "description": "成员userid，type=3时必填" }
+  }
+}
+```
+
+### JumpAction
+
+```json
+{
+  "type": "object",
+  "required": ["title"],
+  "properties": {
+    "type":     { "type": "integer", "enum": [0, 1, 2, 3], "description": "只能是0(无链接)、1(url)、2(小程序)、3(智能回复)" },
+    "title":    { "type": "string", "description": "文案内容，建议不超过13字" },
+    "url":      { "type": "string", "description": "跳转url，type=1时必填" },
+    "appid":    { "type": "string", "description": "小程序appid，type=2时必填" },
+    "pagepath": { "type": "string", "description": "小程序pagepath" },
+    "question": { "type": "string", "description": "智能问答问题，type=3时必填" }
+  }
+}
+```
+
+### QuoteArea
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "type":       { "type": "integer", "enum": [0, 1, 2], "description": "只能是0(无点击)、1(url)、2(小程序)" },
+    "url":        { "type": "string" },
+    "title":      { "type": "string", "description": "引用标题" },
+    "quote_text": { "type": "string", "description": "引用文案" }
+  }
+}
+```
+
+### CardImage
+
+```json
+{
+  "type": "object",
+  "required": ["url"],
+  "properties": {
+    "url":          { "type": "string", "description": "图片url" },
+    "aspect_ratio": { "type": "number", "description": "宽高比，1.3~2.25，默认1.3" }
+  }
+}
+```
+
+---
+
+## 1. text_notice Schema
+
+```json
+{
+  "type": "object",
+  "required": ["card_type", "card_action", "task_id"],
+  "properties": {
+    "card_type":        { "const": "text_notice" },
+    "source":           { "$ref": "#Source" },
+    "main_title":       { "$ref": "#MainTitle", "description": "main_title.title 和 sub_title_text 至少填一个" },
+    "emphasis_content":  { "$ref": "#EmphasisContent" },
+    "sub_title_text":   { "type": "string", "description": "二级文本，建议不超过112字" },
+    "horizontal_content_list": { "type": "array", "maxItems": 6, "items": { "$ref": "#HorizontalContent" } },
+    "jump_list":        { "type": "array", "maxItems": 3, "items": { "$ref": "#JumpAction" } },
+    "card_action":      { "$ref": "#CardAction", "description": "必填" },
+    "task_id":          { "type": "string", "description": "必填，格式：task_{描述}_{时间戳}" }
+  }
+}
+```
+
+---
+
+## 2. news_notice Schema
+
+```json
+{
+  "type": "object",
+  "required": ["card_type", "main_title", "card_action", "task_id"],
+  "properties": {
+    "card_type":        { "const": "news_notice" },
+    "source":           { "$ref": "#Source" },
+    "main_title":       { "$ref": "#MainTitle", "description": "必填" },
+    "card_image":       { "$ref": "#CardImage", "description": "card_image 和 image_text_area 至少填一个" },
+    "vertical_content_list": { "type": "array", "maxItems": 4, "items": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string" }, "desc": { "type": "string" } } } },
+    "horizontal_content_list": { "type": "array", "maxItems": 6, "items": { "$ref": "#HorizontalContent" } },
+    "jump_list":        { "type": "array", "maxItems": 3, "items": { "$ref": "#JumpAction" } },
+    "card_action":      { "$ref": "#CardAction", "description": "必填" },
+    "task_id":          { "type": "string", "description": "必填" }
+  }
+}
+```
+
+---
+
+## 3. button_interaction Schema
+
+```json
+{
+  "type": "object",
+  "required": ["card_type", "main_title", "button_list", "task_id"],
+  "properties": {
+    "card_type":        { "const": "button_interaction" },
+    "source":           { "$ref": "#Source" },
+    "main_title":       { "$ref": "#MainTitle", "description": "必填" },
+    "sub_title_text":   { "type": "string", "description": "二级文本" },
+    "horizontal_content_list": { "type": "array", "maxItems": 6, "items": { "$ref": "#HorizontalContent" } },
+    "button_selection": {
+      "$ref": "#SelectionItem",
+      "description": "可选的下拉选择器，与按钮配合使用"
+    },
+    "button_list": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 6,
+      "items": { "$ref": "#Button" },
+      "description": "必填，按钮列表"
+    },
+    "task_id":          { "type": "string", "description": "必填" }
+  }
+}
+```
+
+---
+
+## 4. vote_interaction Schema（简化格式，代码自动转换为 API 格式）
+
+> **不要使用** `checkbox`、`question_key`、`option_list` 等 API 原始字段名。使用以下简化字段，代码会自动组装。
+
+```json
+{
+  "type": "object",
+  "required": ["card_type", "title", "options", "task_id"],
+  "properties": {
+    "card_type":   { "const": "vote_interaction" },
+    "title":       { "type": "string", "description": "投票标题" },
+    "description": { "type": "string", "description": "标题描述，可选" },
+    "options": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "required": ["id", "text"],
+        "properties": {
+          "id":   { "type": "string", "description": "选项id，不可重复" },
+          "text": { "type": "string", "description": "选项文案" }
+        }
+      },
+      "description": "投票选项列表"
+    },
+    "mode":        { "type": "integer", "enum": [0, 1], "description": "0=单选 1=多选（严格只能是0或1），默认0" },
+    "submit_text": { "type": "string", "description": "提交按钮文案，可选，默认\"提交\"" },
+    "task_id":     { "type": "string", "description": "必填，格式：task_{描述}_{时间戳}" }
+  }
+}
+```
+
+---
+
+## 5. multiple_interaction Schema（简化格式，代码自动转换为 API 格式）
+
+> **不要使用** `select_list`、`question_key`、`option_list` 等 API 原始字段名。使用以下简化字段，代码会自动组装。
+
+```json
+{
+  "type": "object",
+  "required": ["card_type", "title", "selectors", "task_id"],
+  "properties": {
+    "card_type":   { "const": "multiple_interaction" },
+    "title":       { "type": "string", "description": "卡片标题" },
+    "description": { "type": "string", "description": "标题描述，可选" },
+    "selectors": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 3,
+      "items": {
+        "type": "object",
+        "required": ["title", "options"],
+        "properties": {
+          "title": { "type": "string", "description": "此选择器的标题" },
+          "options": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 10,
+            "items": {
+              "type": "object",
+              "required": ["id", "text"],
+              "properties": {
+                "id":   { "type": "string", "description": "选项id，不可重复" },
+                "text": { "type": "string", "description": "选项文案" }
+              }
+            }
+          }
+        }
+      },
+      "description": "下拉选择器列表，每个选择器包含标题和选项"
+    },
+    "submit_text": { "type": "string", "description": "提交按钮文案，可选，默认\"提交\"" },
+    "task_id":     { "type": "string", "description": "必填，格式：task_{描述}_{时间戳}" }
+  }
+}
+```