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

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

@@ -1,641 +1,358 @@
-# 模板卡片类型 - 企业微信开发者文档
+# 模板卡片类型 - JSON Schema 定义
 
-> 来源：https://developer.work.weixin.qq.com/document/path/101032  
-> 最后更新：2026/02/06
+> 来源：企业微信开发者文档 https://developer.work.weixin.qq.com/document/path/101032
+> 格式：JSON Schema，所有字段名、类型、嵌套层级必须严格遵循
 
 ---
 
-## 模版卡片类型
+## 公共结构体 Schema
 
-该文档主要说明各种类型模板卡片 **TemplateCard结构体说明**。
+以下结构体在多种卡片类型中复用，**字段名必须完全一致**。
 
-> 其中，点击文本通知卡片以及图文通知卡片的"跳转指引"区域支持消息智能回复。
-
----
-
-## 文本通知模版卡片 text_notice
-
-完整文本通知模版卡片示例：
+### MainTitle
 
 ```json
 {
-    "card_type": "text_notice",
-    "source": {
-        "icon_url": "https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
-        "desc": "企业微信",
-        "desc_color": 0
-    },
-    "action_menu": {
-        "desc": "消息气泡副交互辅助文本说明",
-        "action_list": [
-            {
-                "text": "接收推送",
-                "key": "action_key1"
-            },
-            {
-                "text": "不再推送",
-                "key": "action_key2"
-            }
-        ]
-    },
-    "main_title": {
-        "title": "欢迎使用企业微信",
-        "desc": "您的好友正在邀请您加入企业微信"
-    },
-    "emphasis_content": {
-        "title": "100",
-        "desc": "数据含义"
-    },
-    "quote_area": {
-        "type": 1,
-        "url": "https://work.weixin.qq.com/?from=openApi",
-        "appid": "APPID",
-        "pagepath": "PAGEPATH",
-        "title": "引用文本标题",
-        "quote_text": "Jack：企业微信真的很好用~\nBalian：超级好的一款软件！"
-    },
-    "sub_title_text": "下载企业微信还能抢红包！",
-    "horizontal_content_list": [
-        {
-            "keyname": "邀请人",
-            "value": "张三"
-        },
-        {
-            "keyname": "企微官网",
-            "value": "点击访问",
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi"
-        },
-        {
-            "keyname": "企微下载",
-            "value": "企业微信.apk",
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi"
-        }
-    ],
-    "jump_list": [
-        {
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi",
-            "title": "企业微信官网"
-        },
-        {
-            "type": 2,
-            "appid": "APPID",
-            "pagepath": "PAGEPATH",
-            "title": "跳转小程序"
-        },
-        {
-            "type": 3,
-            "title": "企业微信官网",
-            "question": "如何登录企业微信官网"
-        }
-    ],
-    "card_action": {
-        "type": 1,
-        "url": "https://work.weixin.qq.com/?from=openApi",
-        "appid": "APPID",
-        "pagepath": "PAGEPATH"
-    },
-    "task_id": "task_id"
+  "type": "object",
+  "properties": {
+    "title": { "type": "string", "description": "一级标题，建议不超过26字" },
+    "desc":  { "type": "string", "description": "标题辅助信息，建议不超过30字" }
+  }
 }
 ```
 
-### 请求参数
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| card_type | String | 是 | 模版卡片的模版类型，文本通知模版卡片的类型为 `text_notice` |
-| source | Object | 否 | 卡片来源样式信息，不需要来源样式可不填写。参考 **Source结构体说明** |
-| action_menu | Object | 否 | 卡片右上角更多操作按钮。参考 **ActionMenu结构体说明** |
-| main_title | Object | 否 | 模版卡片的主要内容，包括一级标题和标题辅助信息。参考 **MainTitle结构体说明** |
-| emphasis_content | Object | 否 | 关键数据样式，建议不与引用样式共用。参考 **EmphasisContent结构体说明** |
-| quote_area | Object | 否 | 引用文献样式，建议不与关键数据共用。参考 **QuoteArea结构体说明** |
-| sub_title_text | String | 否 | 二级普通文本，建议不超过112个字。**模版卡片主要内容的一级标题 main_title.title 和二级普通文本 sub_title_text 必须有一项填写** |
-| horizontal_content_list | Object[] | 否 | 二级标题+文本列表，列表长度不超过6。参考 **HorizontalContent结构体说明** |
-| jump_list | Object[] | 否 | 跳转指引样式的列表，列表长度不超过3。参考 **JumpAction结构体说明** |
-| card_action | Object | 是 | 整体卡片的点击跳转事件，text_notice 模版卡片中该字段为必填项。参考 **CardAction结构体说明** |
-| task_id | String | 否 | 任务id，当文本通知模版卡片有 action_menu 字段时该字段必填。同一个机器人任务id不能重复，只能由数字、字母和"_-@"组成，最长128字节。任务id只在发消息时有效，更新消息时无效。任务id将会在相应的回调事件中返回 |
-
----
-
-## 图文展示模版卡片 news_notice
-
-完整图文展示模版卡片示例：
+### Source
 
 ```json
 {
-    "card_type": "news_notice",
-    "source": {
-        "icon_url": "https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
-        "desc": "企业微信",
-        "desc_color": 0
-    },
-    "action_menu": {
-        "desc": "消息气泡副交互辅助文本说明",
-        "action_list": [
-            {
-                "text": "接收推送",
-                "key": "action_key1"
-            },
-            {
-                "text": "不再推送",
-                "key": "action_key2"
-            }
-        ]
-    },
-    "main_title": {
-        "title": "欢迎使用企业微信",
-        "desc": "您的好友正在邀请您加入企业微信"
-    },
-    "card_image": {
-        "url": "https://wework.qpic.cn/wwpic/354393_4zpkKXd7SrGMvfg_1629280616/0",
-        "aspect_ratio": 2.25
-    },
-    "image_text_area": {
-        "type": 1,
-        "url": "https://work.weixin.qq.com",
-        "title": "欢迎使用企业微信",
-        "desc": "您的好友正在邀请您加入企业微信",
-        "image_url": "https://wework.qpic.cn/wwpic/354393_4zpkKXd7SrGMvfg_1629280616/0"
-    },
-    "quote_area": {
-        "type": 1,
-        "url": "https://work.weixin.qq.com/?from=openApi",
-        "appid": "APPID",
-        "pagepath": "PAGEPATH",
-        "title": "引用文本标题",
-        "quote_text": "Jack：企业微信真的很好用~\nBalian：超级好的一款软件！"
-    },
-    "vertical_content_list": [
-        {
-            "title": "惊喜红包等你来拿",
-            "desc": "下载企业微信还能抢红包！"
-        }
-    ],
-    "horizontal_content_list": [
-        {
-            "keyname": "邀请人",
-            "value": "张三"
-        },
-        {
-            "keyname": "企微官网",
-            "value": "点击访问",
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi"
-        },
-        {
-            "keyname": "企微下载",
-            "value": "企业微信.apk",
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi"
-        }
-    ],
-    "jump_list": [
-        {
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi",
-            "title": "企业微信官网"
-        },
-        {
-            "type": 2,
-            "appid": "APPID",
-            "pagepath": "PAGEPATH",
-            "title": "跳转小程序"
-        },
-        {
-            "type": 3,
-            "title": "企业微信官网",
-            "question": "如何登录企业微信官网"
-        }
-    ],
-    "card_action": {
-        "type": 1,
-        "url": "https://work.weixin.qq.com/?from=openApi",
-        "appid": "APPID",
-        "pagepath": "PAGEPATH"
-    },
-    "task_id": "task_id"
+  "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(绿)" }
+  }
 }
 ```
 
-### 请求参数
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| card_type | String | 是 | 模版卡片的模版类型，图文展示模版卡片的类型为 `news_notice` |
-| source | Object | 否 | 卡片来源样式信息。参考 **Source结构体说明** |
-| action_menu | Object | 否 | 卡片右上角更多操作按钮。参考 **ActionMenu结构体说明** |
-| main_title | Object | 是 | 模版卡片的主要内容。参考 **MainTitle结构体说明** |
-| card_image | Object | 否 | 图片样式，news_notice 类型的卡片，card_image 和 image_text_area 两者必填一个。参考 **CardImage结构体说明** |
-| image_text_area | Object | 否 | 左图右文样式。参考 **ImageTextArea结构体说明** |
-| quote_area | Object | 否 | 引用文献样式。参考 **QuoteArea结构体说明** |
-| vertical_content_list | Object[] | 否 | 卡片二级垂直内容，列表长度不超过4。参考 **VerticalContent结构体说明** |
-| horizontal_content_list | Object[] | 否 | 二级标题+文本列表，列表长度不超过6。参考 **HorizontalContent结构体说明** |
-| jump_list | Object[] | 否 | 跳转指引样式的列表，列表长度不超过3。参考 **JumpAction结构体说明** |
-| card_action | Object | 是 | 整体卡片的点击跳转事件，news_notice 模版卡片中该字段为必填项。参考 **CardAction结构体说明** |
-| task_id | String | 否 | 任务id，当图文展示模版卡片有 action_menu 字段时该字段必填。同一个机器人任务id不能重复，只能由数字、字母和"_-@"组成，最长128字节 |
-
----
-
-## 按钮交互模版卡片 button_interaction
-
-完整按钮交互模版卡片示例：
+### CardAction
 
 ```json
 {
-    "card_type": "button_interaction",
-    "source": {
-        "icon_url": "https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
-        "desc": "企业微信",
-        "desc_color": 0
-    },
-    "action_menu": {
-        "desc": "消息气泡副交互辅助文本说明",
-        "action_list": [
-            {
-                "text": "接收推送",
-                "key": "action_key1"
-            },
-            {
-                "text": "不再推送",
-                "key": "action_key2"
-            }
-        ]
-    },
-    "main_title": {
-        "title": "欢迎使用企业微信",
-        "desc": "您的好友正在邀请您加入企业微信"
-    },
-    "quote_area": {
-        "type": 1,
-        "url": "https://work.weixin.qq.com/?from=openApi",
-        "appid": "APPID",
-        "pagepath": "PAGEPATH",
-        "title": "引用文本标题",
-        "quote_text": "Jack：企业微信真的很好用~\nBalian：超级好的一款软件！"
-    },
-    "sub_title_text": "下载企业微信还能抢红包！",
-    "horizontal_content_list": [
-        {
-            "keyname": "邀请人",
-            "value": "张三"
-        },
-        {
-            "keyname": "企微官网",
-            "value": "点击访问",
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi"
-        },
-        {
-            "keyname": "企微下载",
-            "value": "企业微信.apk",
-            "type": 1,
-            "url": "https://work.weixin.qq.com/?from=openApi"
-        }
-    ],
-    "button_selection": {
-        "question_key": "button_selection_key1",
-        "title": "你的身份",
-        "disable": false,
-        "option_list": [
-            {
-                "id": "button_selection_id1",
-                "text": "企业负责人"
-            },
-            {
-                "id": "button_selection_id2",
-                "text": "企业用户"
-            }
-        ],
-        "selected_id": "button_selection_id1"
-    },
-    "button_list": [
-        {
-            "text": "按钮1",
-            "style": 4,
-            "key": "BUTTONKEYONE"
-        },
-        {
-            "text": "按钮2",
-            "style": 1,
-            "key": "BUTTONKEYTWO"
-        }
-    ],
-    "card_action": {
-        "type": 1,
-        "url": "https://work.weixin.qq.com/?from=openApi",
-        "appid": "APPID",
-        "pagepath": "PAGEPATH"
-    },
-    "task_id": "task_id"
+  "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" }
+  }
 }
 ```
 
-### 请求参数
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| card_type | String | 是 | 模版卡片的模版类型，按钮交互模版卡片的类型为 `button_interaction`。当机器人设置了回调URL时，才能下发按钮交互模版卡片 |
-| source | Object | 否 | 卡片来源样式信息。参考 **Source结构体说明** |
-| action_menu | Object | 否 | 卡片右上角更多操作按钮。参考 **ActionMenu结构体说明** |
-| main_title | Object | 是 | 模版卡片的主要内容。参考 **MainTitle结构体说明** |
-| quote_area | Object | 否 | 引用文献样式。参考 **QuoteArea结构体说明** |
-| sub_title_text | String | 否 | 二级普通文本，建议不超过112个字 |
-| horizontal_content_list | Object[] | 否 | 二级标题+文本列表，列表长度不超过6。参考 **HorizontalContent结构体说明** |
-| button_selection | Object | 否 | 下拉式的选择器。参考 **SelectionItem结构体说明** |
-| button_list | Object[] | 是 | 按钮列表，列表长度不超过6。参考 **Button结构体说明** |
-| card_action | Object | 否 | 整体卡片的点击跳转事件。参考 **CardAction结构体说明** |
-| task_id | String | 是 | 任务id，同一个机器人任务id不能重复，只能由数字、字母和"_-@"组成，最长128字节。任务id只在发消息时有效，更新消息时无效 |
-
----
-
-## 投票选择模版卡片 vote_interaction
-
-完整投票选择模版卡片示例：
+### EmphasisContent
 
 ```json
 {
-    "card_type": "vote_interaction",
-    "source": {
-        "icon_url": "https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
-        "desc": "企业微信"
-    },
-    "main_title": {
-        "title": "欢迎使用企业微信",
-        "desc": "您的好友正在邀请您加入企业微信"
-    },
-    "checkbox": {
-        "question_key": "question_key",
-        "option_list": [
-            {
-                "id": "id_one",
-                "text": "选择题选项1"
-            },
-            {
-                "id": "id_two",
-                "text": "选择题选项2",
-                "is_checked": true
-            }
-        ],
-        "disable": false,
-        "mode": 1
-    },
-    "submit_button": {
-        "text": "提交",
-        "key": "submit_key"
-    },
-    "task_id": "task_id"
+  "type": "object",
+  "properties": {
+    "title": { "type": "string", "description": "关键数据内容，建议不超过10字" },
+    "desc":  { "type": "string", "description": "关键数据描述，建议不超过15字" }
+  }
 }
 ```
 
-### 请求参数
+### SubmitButton
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| card_type | String | 是 | 模版卡片的模版类型，投票选择模版卡片的类型为 `vote_interaction`。当机器人设置了回调URL时，才能下发投票选择模版卡片 |
-| source | Object | 否 | 卡片来源样式信息。参考 **Source结构体说明** |
-| main_title | Object | 是 | 模版卡片的主要内容。参考 **MainTitle结构体说明** |
-| checkbox | Object | 是 | 选择题样式。参考 **CheckBox结构体说明** |
-| submit_button | Object | 是 | 提交按钮样式。参考 **SubmitButton结构体说明** |
-| task_id | String | 是 | 任务id，同一个机器人任务id不能重复，只能由数字、字母和"_-@"组成，最长128字节 |
+```json
+{
+  "type": "object",
+  "required": ["text", "key"],
+  "properties": {
+    "text": { "type": "string", "description": "按钮文案，建议不超过10字" },
+    "key":  { "type": "string", "description": "提交按钮的key，用于回调事件" }
+  }
+}
+```
 
----
+### Button
 
-## 多项选择模版卡片 multiple_interaction
+```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
 {
-    "card_type": "multiple_interaction",
-    "source": {
-        "icon_url": "https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0",
-        "desc": "企业微信"
-    },
-    "main_title": {
-        "title": "欢迎使用企业微信",
-        "desc": "您的好友正在邀请您加入企业微信"
-    },
-    "select_list": [
-        {
-            "question_key": "question_key_one",
-            "title": "选择标签1",
-            "disable": false,
-            "selected_id": "id_one",
-            "option_list": [
-                {
-                    "id": "id_one",
-                    "text": "选择器选项1"
-                },
-                {
-                    "id": "id_two",
-                    "text": "选择器选项2"
-                }
-            ]
-        },
-        {
-            "question_key": "question_key_two",
-            "title": "选择标签2",
-            "selected_id": "id_three",
-            "option_list": [
-                {
-                    "id": "id_three",
-                    "text": "选择器选项3"
-                },
-                {
-                    "id": "id_four",
-                    "text": "选择器选项4"
-                }
-            ]
+  "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": "是否默认选中" }
         }
-    ],
-    "submit_button": {
-        "text": "提交",
-        "key": "submit_key"
-    },
-    "task_id": "task_id"
+      }
+    }
+  }
 }
 ```
 
-### 请求参数
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| card_type | String | 是 | 模版卡片的模版类型，多项选择模版卡片的类型为 `multiple_interaction`。当机器人设置了回调URL时，才能下发多项选择模版卡片 |
-| source | Object | 否 | 卡片来源样式信息。参考 **Source结构体说明** |
-| main_title | Object | 是 | 模版卡片的主要内容。参考 **MainTitle结构体说明** |
-| select_list | Object[] | 是 | 下拉式的选择器列表，multiple_interaction 类型的卡片该字段不可为空，一个消息最多支持3个选择器。参考 **SelectionItem结构体说明** |
-| submit_button | Object | 是 | 提交按钮样式。参考 **SubmitButton结构体说明** |
-| task_id | String | 否 | 任务id，同一个机器人任务id不能重复，只能由数字、字母和"_-@"组成，最长128字节 |
-
----
-
-## 结构体说明
-
-### Source结构体
-
-卡片来源样式信息
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| icon_url | String | 否 | 来源图片的url |
-| desc | String | 否 | 来源图片的描述，建议不超过13个字 |
-| desc_color | Int | 否 | 来源文字的颜色，目前支持：0(默认) 灰色，1 黑色，2 红色，3 绿色 |
+### SelectionItem（下拉选择器）
 
-### ActionMenu结构体
-
-卡片右上角更多操作按钮
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| desc | String | 是 | 更多操作界面的描述 |
-| action_list | Array | 是 | 操作列表，列表长度取值范围为 [1, 3] |
-| action_list.text | String | 是 | 操作的描述文案 |
-| action_list.key | String | 是 | 操作key值，用户点击后，会产生回调事件将本参数作为EventKey返回，最长支持1024字节，不可重复 |
-
-### MainTitle结构体
-
-模版卡片的主要内容，包括一级标题和标题辅助信息
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| title | String | 否 | 一级标题，建议不超过26个字。**模版卡片主要内容的一级标题 main_title.title 和二级普通文本 sub_title_text 必须有一项填写** |
-| desc | String | 否 | 标题辅助信息，建议不超过30个字 |
-
-### EmphasisContent结构体
-
-关键数据样式
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| title | String | 否 | 关键数据样式的数据内容，建议不超过10个字 |
-| desc | String | 否 | 关键数据样式的数据描述内容，建议不超过15个字 |
-
-### QuoteArea结构体
-
-引用文献样式
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| type | Int | 否 | 引用文献样式区域点击事件，0或不填代表没有点击事件，1 代表跳转url，2 代表跳转小程序 |
-| url | String | 否 | 点击跳转的url，type是1时必填 |
-| appid | String | 否 | 点击跳转的小程序的appid，必须是与当前应用关联的小程序，type是2时必填 |
-| pagepath | String | 否 | 点击跳转的小程序的pagepath，type是2时选填 |
-| title | String | 否 | 引用文献样式的标题 |
-| quote_text | String | 否 | 引用文献样式的引用文案 |
-
-### HorizontalContent结构体
-
-二级标题+文本列表
-
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| type | Int | 否 | 链接类型，0或不填代表是普通文本，1 代表跳转url，3 代表点击跳转成员详情 |
-| keyname | String | 是 | 二级标题，建议不超过5个字 |
-| value | String | 否 | 二级文本，建议不超过26个字 |
-| url | String | 否 | 链接跳转的url，type是1时必填 |
-| userid | String | 否 | 成员详情的userid，type是3时必填 |
-
-### JumpAction结构体
-
-跳转指引样式的列表
+```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字" }
+        }
+      }
+    }
+  }
+}
+```
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| type | Int | 否 | 跳转链接类型，0或不填代表不是链接，1 代表跳转url，2 代表跳转小程序，3 代表触发消息智能回复 |
-| question | String | 否 | 智能问答问题，最长不超过200个字节。若type为3，必填 |
-| title | String | 是 | 跳转链接样式的文案内容，建议不超过13个字 |
-| url | String | 否 | 跳转链接的url，type是1时必填 |
-| appid | String | 否 | 跳转链接的小程序的appid，type是2时必填 |
-| pagepath | String | 否 | 跳转链接的小程序的pagepath，type是2时选填 |
+### HorizontalContent
 
-### CardAction结构体
+```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
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| type | Int | 是 | 卡片跳转类型，0或不填代表不是链接，1 代表跳转url，2 代表打开小程序。text_notice 和 news_notice 模版卡片中该字段取值范围为[1,2] |
-| url | String | 否 | 跳转事件的url，type是1时必填 |
-| appid | String | 否 | 跳转事件的小程序的appid，type是2时必填 |
-| pagepath | String | 否 | 跳转事件的小程序的pagepath，type是2时选填 |
+```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时必填" }
+  }
+}
+```
 
-### VerticalContent结构体
+### 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": "引用文案" }
+  }
+}
+```
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| title | String | 是 | 卡片二级标题，建议不超过26个字 |
-| desc | String | 否 | 二级普通文本，建议不超过112个字 |
+### CardImage
 
-### CardImage结构体
+```json
+{
+  "type": "object",
+  "required": ["url"],
+  "properties": {
+    "url":          { "type": "string", "description": "图片url" },
+    "aspect_ratio": { "type": "number", "description": "宽高比，1.3~2.25，默认1.3" }
+  }
+}
+```
 
-图片样式
+---
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| url | String | 是 | 图片的url |
-| aspect_ratio | Float | 否 | 图片的宽高比，宽高比要小于2.25，大于1.3，不填该参数默认1.3 |
+## 1. text_notice Schema
 
-### ImageTextArea结构体
+```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_{描述}_{时间戳}" }
+  }
+}
+```
 
-左图右文样式
+---
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| type | Int | 否 | 左图右文样式区域点击事件，0或不填代表没有点击事件，1 代表跳转url，2 代表跳转小程序 |
-| url | String | 否 | 点击跳转的url，type是1时必填 |
-| appid | String | 否 | 点击跳转的小程序的appid，必须是与当前应用关联的小程序，type是2时必填 |
-| pagepath | String | 否 | 点击跳转的小程序的pagepath，type是2时选填 |
-| title | String | 否 | 左图右文样式的标题 |
-| desc | String | 否 | 左图右文样式的描述 |
-| image_url | String | 是 | 左图右文样式的图片url |
+## 2. news_notice Schema
 
-### SubmitButton结构体
+```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": "必填" }
+  }
+}
+```
 
-提交按钮样式
+---
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| text | String | 是 | 按钮文案，建议不超过10个字 |
-| key | String | 是 | 提交按钮的key，会产生回调事件将本参数作为EventKey返回，最长支持1024字节 |
+## 3. button_interaction Schema
 
-### SelectionItem结构体
+```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": "必填" }
+  }
+}
+```
 
-下拉式的选择器列表
+---
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| question_key | String | 是 | 下拉式的选择器题目的key，用户提交选项后，会产生回调事件，最长支持1024字节，不可重复 |
-| title | String | 否 | 选择器的标题，建议不超过13个字 |
-| disable | Bool | 否 | 下拉式的选择器是否不可选，false为可选，true为不可选。仅在更新模版卡片时该字段有效 |
-| selected_id | String | 否 | 默认选定的id，不填或错填默认第一个 |
-| option_list | Object[] | 是 | 选项列表，下拉选项不超过10个，最少1个 |
-| option_list.id | String | 是 | 选项的id，最长支持128字节，不可重复 |
-| option_list.text | String | 是 | 选项的文案，建议不超过10个字 |
+## 4. vote_interaction Schema（简化格式，代码自动转换为 API 格式）
 
-### Button结构体
+> **不要使用** `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_{描述}_{时间戳}" }
+  }
+}
+```
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| text | String | 是 | 按钮文案，建议不超过10个字 |
-| style | Int | 否 | 按钮样式，目前可填1~4，不填或错填默认1 |
-| key | String | 是 | 按钮key值，用户点击后，会产生回调事件将本参数作为event_key返回，最长支持1024字节，不可重复 |
+---
 
-### Checkbox结构体
+## 5. multiple_interaction Schema（简化格式，代码自动转换为 API 格式）
 
-选择题样式
+> **不要使用** `select_list`、`question_key`、`option_list` 等 API 原始字段名。使用以下简化字段，代码会自动组装。
 
-| 参数 | 类型 | 必须 | 说明 |
-| --- | --- | --- | --- |
-| question_key | String | 是 | 选择题key值，用户提交选项后，会产生回调事件，最长支持1024字节 |
-| disable | Bool | 否 | 投票选择框的是否不可选，false为可选，true为不可选。仅在更新模版卡片时该字段有效 |
-| mode | Int | 否 | 选择题模式，单选：0，多选：1，不填默认0 |
-| option_list | Object[] | 是 | 选项list，选项个数不超过20个，最少1个 |
-| option_list.id | String | 是 | 选项id，最长支持128字节，不可重复 |
-| option_list.text | String | 是 | 选项文案描述，建议不超过11个字 |
-| option_list.is_checked | Bool | 否 | 该选项是否要默认选中 |
+```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_{描述}_{时间戳}" }
+  }
+}
+```