{"skill":{"slug":"feishu-card-v2","displayName":"Feishu Card JSON v2","summary":"发送飞书互动卡片（Card JSON 2.0）。当需要让飞书用户填写表单、做选择、确认操作、或查看 结构化数据时，发送交互卡片代替纯文字问答。需要 feishu-cards 插件工具： feishu_send_card / feishu_send_form / feishu_update_card。","description":"---\nname: feishu-card\ndescription: >\n  发送飞书互动卡片（Card JSON 2.0）。当需要让飞书用户填写表单、做选择、确认操作、或查看\n  结构化数据时，发送交互卡片代替纯文字问答。需要 feishu-cards 插件工具：\n  feishu_send_card / feishu_send_form / feishu_update_card。\nmetadata:\n  {\n    \"openclaw\": {\n      \"requires\": { \"tools\": [\"feishu_send_card\", \"feishu_send_form\", \"feishu_update_card\"] },\n      \"install\": [\n        {\n          \"id\": \"npm\",\n          \"kind\": \"plugin\",\n          \"package\": \"@openclaw/feishu-cards\",\n          \"label\": \"Install feishu-cards plugin (npm)\"\n        }\n      ]\n    }\n  }\n---\n\n## 触发场景\n\n**发卡片** 而非纯文字的情况：\n- 需要用户做选择（按钮/下拉/人员选择等）\n- 需要用户填写表单（输入框 + 提交按钮）\n- 需要展示结构化数据（表格、图表、多列布局）\n- 需要确认高风险操作（确认/取消双按钮）\n- 需要提供快速操作入口（按钮组）\n\n**纯文字**：简单回复、解释说明、无需交互时，无需发卡片。\n\n---\n\n## 工具说明\n\n| 工具 | 用途 | 主要参数 |\n|------|------|---------|\n| `feishu_send_card` | 发送卡片消息 | `chat_id` / `user_id`，`card`（JSON字符串） |\n| `feishu_send_form` | 发送含表单容器的卡片 | 同上，card 内须含 `form` 组件 |\n| `feishu_update_card` | 更新已发卡片内容 | `token`（回调中获取），`card`（新JSON） |\n\n---\n\n## 卡片顶层结构\n\n```json\n{\n  \"schema\": \"2.0\",\n  \"config\": { ... },\n  \"card_link\": { \"url\": \"...\" },\n  \"header\": { ... },\n  \"body\": { \"elements\": [ ... ] }\n}\n```\n\n### config 字段速查\n\n| 字段 | 默认值 | 说明 |\n|------|--------|------|\n| `streaming_mode` | false | 流式更新模式 |\n| `enable_forward` | true | 是否可转发 |\n| `update_multi` | true | 共享卡片（JSON 2.0 仅支持 true） |\n| `width_mode` | default(600px) | `compact`(400px) / `fill`(撑满) |\n| `enable_forward_interaction` | false | 转发后是否仍可交互 |\n| `summary.content` | - | 自定义聊天栏预览文案 |\n\n### header 字段速查\n\n| 字段 | 说明 | 枚举/格式 |\n|------|------|---------|\n| `title.tag` | 标题文本类型 | `plain_text` / `lark_md` |\n| `title.content` | 主标题内容 | 字符串，最多4行 |\n| `subtitle.content` | 副标题内容 | 字符串，最多1行 |\n| `template` | 标题栏颜色 | `blue` `wathet` `turquoise` `green` `yellow` `orange` `red` `carmine` `violet` `purple` `indigo` `grey` `default` |\n| `icon.tag` | 图标类型 | `standard_icon` / `custom_icon` |\n| `icon.token` | 图标库token | 如 `chat_outlined` |\n| `text_tag_list[].color` | 后缀标签颜色 | `neutral` `blue` `turquoise` `lime` `orange` `violet` `indigo` `wathet` `green` `yellow` `red` `purple` `carmine` |\n| `padding` | 标题内边距 | 默认 `12px` |\n\n### body 字段速查\n\n| 字段 | 默认值 | 说明 |\n|------|--------|------|\n| `direction` | `vertical` | `vertical` / `horizontal` |\n| `padding` | - | 如 `12px 12px` |\n| `horizontal_spacing` | - | `small`(4px) `medium`(8px) `large`(12px) `extra_large`(16px) 或 `Npx` |\n| `horizontal_align` | `left` | `left` / `center` / `right` |\n| `vertical_spacing` | - | 同 horizontal_spacing |\n| `vertical_align` | `top` | `top` / `center` / `bottom` |\n| `elements` | [] | 组件数组 |\n\n---\n\n## 组件速查\n\n### 容器组件\n\n#### column_set（分栏）\n\ntag: `column_set`，不可内嵌 `form` 和 `table`\n\n```json\n{\n  \"tag\": \"column_set\",\n  \"flex_mode\": \"none\",\n  \"horizontal_spacing\": \"8px\",\n  \"background_style\": \"default\",\n  \"columns\": [\n    {\n      \"tag\": \"column\",\n      \"width\": \"weighted\",\n      \"weight\": 1,\n      \"vertical_align\": \"top\",\n      \"elements\": []\n    }\n  ]\n}\n```\n\n关键枚举：\n- `flex_mode`: `none` / `stretch` / `flow` / `bisect` / `trisect`\n- `column.width`: `auto` / `weighted` / `Npx`([16,600]px)\n- `background_style`: `default` 或颜色枚举值\n\n\n#### form（表单容器）\n\ntag: `form`，只可放在卡片根节点，不可嵌套表格/表单\n\n```json\n{\n  \"tag\": \"form\",\n  \"name\": \"form_1\",\n  \"elements\": [\n    { \"tag\": \"input\", \"name\": \"reason\", \"required\": true },\n    {\n      \"tag\": \"button\",\n      \"text\": { \"tag\": \"plain_text\", \"content\": \"提交\" },\n      \"type\": \"primary_filled\",\n      \"form_action_type\": \"submit\",\n      \"name\": \"btn_submit\"\n    }\n  ]\n}\n```\n\n- 表单内交互组件必须有 `name` 字段（唯一标识）\n- 按钮 `form_action_type`: `submit`（提交）/ `reset`（重置）\n\n\n#### interactive_container（交互容器）\n\ntag: `interactive_container`，不可内嵌 `form` 和 `table`\n\n```json\n{\n  \"tag\": \"interactive_container\",\n  \"width\": \"fill\",\n  \"height\": \"auto\",\n  \"has_border\": true,\n  \"border_color\": \"grey\",\n  \"corner_radius\": \"8px\",\n  \"background_style\": \"default\",\n  \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"key\": \"val\" } }],\n  \"elements\": []\n}\n```\n\n关键字段：\n- `background_style`: `default` / `laser` / 颜色枚举\n- `behaviors.type`: `callback` / `open_url`\n\n\n#### collapsible_panel（折叠面板）\n\ntag: `collapsible_panel`，不可内嵌 `form`，仅支持 JSON 代码（不支持搭建工具）\n\n```json\n{\n  \"tag\": \"collapsible_panel\",\n  \"expanded\": false,\n  \"header\": {\n    \"title\": { \"tag\": \"plain_text\", \"content\": \"面板标题\" },\n    \"icon\": { \"tag\": \"standard_icon\", \"token\": \"down-small-ccm_outlined\", \"size\": \"16px 16px\" },\n    \"icon_position\": \"right\",\n    \"icon_expanded_angle\": -180\n  },\n  \"border\": { \"color\": \"grey\", \"corner_radius\": \"5px\" },\n  \"elements\": []\n}\n```\n\n- `icon_position`: `left` / `right` / `follow_text`\n- `icon_expanded_angle`: `-180` / `-90` / `90` / `180`\n\n---\n\n### 内容组件\n\n#### title（标题组件）\n\n位于 `header` 字段，非 body elements，每卡只能有一个。见上方 header 速查。\n\n\n#### div（普通文本）\n\ntag: `div`\n\n```json\n{\n  \"tag\": \"div\",\n  \"text\": {\n    \"tag\": \"plain_text\",\n    \"content\": \"文本内容\",\n    \"text_size\": \"normal\",\n    \"text_color\": \"default\",\n    \"text_align\": \"left\"\n  }\n}\n```\n\n- `text.tag`: `plain_text` / `lark_md`\n- `text_size`: `heading-0`(30px) `heading-1`(24px) `heading-2`(20px) `heading-3`(18px) `heading-4`(16px) `heading`(16px) `normal`(14px) `notation`(12px)\n- `text_color`: `default` 或颜色枚举\n\n\n#### markdown（富文本）\n\ntag: `markdown`\n\n```json\n{\n  \"tag\": \"markdown\",\n  \"content\": \"**粗体** *斜体* ~~删除线~~\\n- 列表\\n`code`\\n> 引用\",\n  \"text_align\": \"left\",\n  \"text_size\": \"normal\"\n}\n```\n\n支持语法：`**粗体**`、`*斜体*`、`~~删除线~~`、`[链接](url)`、`<at id=open_id></at>`、`<at id=all></at>`、`<font color=red>彩色</font>`、`<text_tag color='blue'>标签</text_tag>`、`# 标题`、有序/无序列表、代码块、表格（Markdown表格语法）、`<hr>`分割线\n- `text_size`: 同 div 枚举\n\n\n#### img（图片）\n\ntag: `img`，img_key 通过上传图片接口获取\n\n```json\n{\n  \"tag\": \"img\",\n  \"img_key\": \"img_v3_xxx\",\n  \"scale_type\": \"crop_center\",\n  \"size\": \"200px 150px\",\n  \"corner_radius\": \"8px\",\n  \"preview\": true\n}\n```\n\n- `scale_type`: `crop_center` / `crop_top` / `fit_horizontal`\n- `size`: `Wpx Hpx` 或预设值，通栏用 `margin: \"0 -12px\"`\n\n\n#### img_combination（多图混排）\n\ntag: `img_combination`\n\n```json\n{\n  \"tag\": \"img_combination\",\n  \"combination_mode\": \"bisect\",\n  \"img_list\": [\n    { \"img_key\": \"img_v3_aaa\" },\n    { \"img_key\": \"img_v3_bbb\" }\n  ]\n}\n```\n\n- `combination_mode`: `double`(双图) / `triple`(三图) / `bisect`(六宫格) / `trisect`(九宫格)\n\n\n#### person（人员）\n\ntag: `person`\n\n```json\n{\n  \"tag\": \"person\",\n  \"user_id\": \"ou_xxx\",\n  \"size\": \"medium\",\n  \"show_avatar\": true,\n  \"show_name\": true,\n  \"style\": \"normal\"\n}\n```\n\n- `size`: `extra_small` / `small` / `medium` / `large`\n- `style`: `normal` / `capsule`\n\n\n#### person_list（人员列表）\n\ntag: `person_list`\n\n```json\n{\n  \"tag\": \"person_list\",\n  \"persons\": [{ \"id\": \"ou_xxx\" }, { \"id\": \"ou_yyy\" }],\n  \"show_avatar\": true,\n  \"show_name\": true,\n  \"size\": \"medium\"\n}\n```\n\n\n#### chart（图表）\n\ntag: `chart`，基于 VChart 定义\n\n```json\n{\n  \"tag\": \"chart\",\n  \"aspect_ratio\": \"16:9\",\n  \"color_theme\": \"brand\",\n  \"chart_spec\": {\n    \"type\": \"bar\",\n    \"data\": [{ \"id\": \"data\", \"values\": [{ \"x\": \"A\", \"y\": 10 }] }],\n    \"xField\": \"x\",\n    \"yField\": \"y\"\n  }\n}\n```\n\n- `color_theme`: `brand` / `rainbow` / `complementary` / `diverging` / `ordinal`\n\n\n#### table（表格）\n\ntag: `table`，只可放在卡片根节点，不支持内嵌其它组件\n\n```json\n{\n  \"tag\": \"table\",\n  \"page_size\": 5,\n  \"row_height\": \"low\",\n  \"columns\": [\n    { \"name\": \"col1\", \"display_name\": \"名称\", \"data_type\": \"text\", \"width\": \"auto\" },\n    { \"name\": \"col2\", \"display_name\": \"数量\", \"data_type\": \"number\" }\n  ],\n  \"rows\": [\n    { \"col1\": \"项目A\", \"col2\": 100 }\n  ]\n}\n```\n\n- `data_type`: `text` / `lark_md` / `number` / `options` / `persons` / `date`\n- `row_height`: `low` / `middle` / `high` / `auto`\n- `number.format`: `{ symbol, precision, separator }`\n\n\n#### audio（音频）\n\ntag: `audio`，仅支持 JSON 代码，需 `enable_forward: false`，仅飞书 V7.49+\n\n```json\n{ \"tag\": \"audio\", \"file_key\": \"file_v3_xxx\", \"show_time\": true }\n```\n\n#### hr（分割线）\n\ntag: `hr`\n\n```json\n{ \"tag\": \"hr\" }\n```\n\n---\n\n### 交互组件\n\n#### input（输入框）\n\ntag: `input`\n\n```json\n{\n  \"tag\": \"input\",\n  \"name\": \"reason\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"请输入\" },\n  \"required\": false,\n  \"max_length\": 200,\n  \"input_type\": \"text\",\n  \"width\": \"fill\"\n}\n```\n\n- `input_type`: `text` / `multiline_text` / `password` / `number` / `telephone` / `email`\n- `width`: `default` / `fill` / `[100,∞)px`\n- 表单外使用时，需配 `behaviors` 触发回调\n\n\n#### button（按钮）\n\ntag: `button`\n\n```json\n{\n  \"tag\": \"button\",\n  \"type\": \"primary_filled\",\n  \"size\": \"medium\",\n  \"text\": { \"tag\": \"plain_text\", \"content\": \"确认\" },\n  \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"action\": \"confirm\" } }]\n}\n```\n\n- `type`: `default` `primary` `danger` `text` `primary_text` `danger_text` `primary_filled` `danger_filled` `laser`\n- `size`: `tiny` / `small` / `medium` / `large`\n- `width`: `default` / `fill` / `Npx`\n- `behaviors.type`: `callback` / `open_url`\n\n\n#### overflow（折叠按钮组）\n\ntag: `overflow`\n\n```json\n{\n  \"tag\": \"overflow\",\n  \"options\": [\n    { \"text\": { \"tag\": \"plain_text\", \"content\": \"选项1\" }, \"value\": \"opt1\" },\n    { \"text\": { \"tag\": \"plain_text\", \"content\": \"跳转\" }, \"multi_url\": { \"url\": \"https://...\" } }\n  ]\n}\n```\n\n\n#### select_static（下拉单选）\n\ntag: `select_static`\n\n```json\n{\n  \"tag\": \"select_static\",\n  \"name\": \"priority\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"请选择\" },\n  \"options\": [\n    { \"text\": { \"tag\": \"plain_text\", \"content\": \"高\" }, \"value\": \"high\" },\n    { \"text\": { \"tag\": \"plain_text\", \"content\": \"低\" }, \"value\": \"low\" }\n  ],\n  \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"k\": \"v\" } }]\n}\n```\n\n- `type`: `default` / `text`（边框样式）\n\n\n#### multi_select_static（下拉多选）\n\ntag: `multi_select_static`，**必须**在 `form` 容器内\n\n```json\n{\n  \"tag\": \"multi_select_static\",\n  \"name\": \"tags\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"请选择\" },\n  \"options\": [\n    { \"text\": { \"tag\": \"plain_text\", \"content\": \"标签A\" }, \"value\": \"a\" }\n  ]\n}\n```\n\n\n#### select_person（人员单选）\n\ntag: `select_person`\n\n```json\n{\n  \"tag\": \"select_person\",\n  \"name\": \"assignee\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"选择负责人\" },\n  \"options\": [{ \"value\": \"ou_xxx\" }],\n  \"behaviors\": [{ \"type\": \"callback\", \"value\": {} }]\n}\n```\n\n\n#### multi_select_person（人员多选）\n\ntag: `multi_select_person`，**必须**在 `form` 容器内\n\n```json\n{\n  \"tag\": \"multi_select_person\",\n  \"name\": \"reviewers\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"选择审核人\" },\n  \"options\": [{ \"value\": \"ou_xxx\" }, { \"value\": \"ou_yyy\" }]\n}\n```\n\n\n#### date_picker（日期选择器）\n\ntag: `date_picker`\n\n```json\n{\n  \"tag\": \"date_picker\",\n  \"name\": \"due_date\",\n  \"initial_date\": \"2025-01-01\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"请选择日期\" }\n}\n```\n\n\n#### picker_time（时间选择器）\n\ntag: `picker_time`\n\n```json\n{\n  \"tag\": \"picker_time\",\n  \"name\": \"meeting_time\",\n  \"initial_time\": \"09:00\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"请选择时间\" }\n}\n```\n\n\n#### picker_datetime（日期时间选择器）\n\ntag: `picker_datetime`\n\n```json\n{\n  \"tag\": \"picker_datetime\",\n  \"name\": \"event_datetime\",\n  \"initial_datetime\": \"2025-01-01 09:00\",\n  \"placeholder\": { \"tag\": \"plain_text\", \"content\": \"请选择\" }\n}\n```\n\n\n#### select_img（多图选择）\n\ntag: `select_img`，仅支持 JSON 代码；不在 form 内时仅单选点击即提交\n\n```json\n{\n  \"tag\": \"select_img\", \"name\": \"choice\", \"multi_select\": false,\n  \"layout\": \"bisect\", \"aspect_ratio\": \"16:9\",\n  \"options\": [{ \"img_key\": \"img_v3_aaa\", \"value\": \"pic1\" }],\n  \"behaviors\": [{ \"type\": \"callback\", \"value\": {} }]\n}\n```\n\n- `layout`: `bisect` / `trisect` / `compact`\n\n\n#### checker（勾选器）\n\ntag: `checker`，仅支持 JSON 代码\n\n```json\n{\n  \"tag\": \"checker\", \"name\": \"task_done\", \"checked\": false,\n  \"text\": { \"tag\": \"plain_text\", \"content\": \"任务已完成\" },\n  \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"task_id\": \"123\" } }]\n}\n```\n\n---\n\n## 常用模板\n\n### 1. 确认操作（双按钮）\n\n```json\n{\n  \"schema\": \"2.0\",\n  \"header\": { \"title\": { \"tag\": \"plain_text\", \"content\": \"确认操作\" }, \"template\": \"orange\" },\n  \"body\": {\n    \"elements\": [\n      { \"tag\": \"markdown\", \"content\": \"确定要执行此操作吗？此操作**不可撤销**。\" },\n      {\n        \"tag\": \"column_set\", \"horizontal_spacing\": \"8px\",\n        \"columns\": [\n          { \"tag\": \"column\", \"width\": \"auto\", \"elements\": [{\n            \"tag\": \"button\", \"type\": \"primary_filled\",\n            \"text\": { \"tag\": \"plain_text\", \"content\": \"确认\" },\n            \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"action\": \"confirm\" } }]\n          }]},\n          { \"tag\": \"column\", \"width\": \"auto\", \"elements\": [{\n            \"tag\": \"button\", \"type\": \"default\",\n            \"text\": { \"tag\": \"plain_text\", \"content\": \"取消\" },\n            \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"action\": \"cancel\" } }]\n          }]}\n        ]\n      }\n    ]\n  }\n}\n```\n\n---\n\n### 2. 快捷选择（按钮组）\n\n```json\n{\n  \"schema\": \"2.0\",\n  \"header\": { \"title\": { \"tag\": \"plain_text\", \"content\": \"请选择优先级\" }, \"template\": \"blue\" },\n  \"body\": {\n    \"elements\": [\n      { \"tag\": \"markdown\", \"content\": \"请为该任务设置优先级：\" },\n      {\n        \"tag\": \"column_set\", \"horizontal_spacing\": \"8px\",\n        \"columns\": [\n          { \"tag\": \"column\", \"width\": \"auto\", \"elements\": [{\n            \"tag\": \"button\", \"type\": \"danger_filled\",\n            \"text\": { \"tag\": \"plain_text\", \"content\": \"🔴 紧急\" },\n            \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"priority\": \"urgent\" } }]\n          }]},\n          { \"tag\": \"column\", \"width\": \"auto\", \"elements\": [{\n            \"tag\": \"button\", \"type\": \"primary\",\n            \"text\": { \"tag\": \"plain_text\", \"content\": \"🟡 普通\" },\n            \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"priority\": \"normal\" } }]\n          }]},\n          { \"tag\": \"column\", \"width\": \"auto\", \"elements\": [{\n            \"tag\": \"button\", \"type\": \"default\",\n            \"text\": { \"tag\": \"plain_text\", \"content\": \"🟢 低\" },\n            \"behaviors\": [{ \"type\": \"callback\", \"value\": { \"priority\": \"low\" } }]\n          }]}\n        ]\n      }\n    ]\n  }\n}\n```\n\n---\n\n### 3. 数据展示（table + 操作按钮）\n\n```json\n{\n  \"schema\": \"2.0\",\n  \"header\": { \"title\": { \"tag\": \"plain_text\", \"content\": \"待处理工单\" }, \"template\": \"blue\" },\n  \"body\": {\n    \"elements\": [\n      {\n        \"tag\": \"table\", \"page_size\": 5, \"row_height\": \"low\",\n        \"columns\": [\n          { \"name\": \"id\", \"display_name\": \"工单号\", \"data_type\": \"text\", \"width\": \"80px\" },\n          { \"name\": \"title\", \"display_name\": \"标题\", \"data_type\": \"text\" },\n          { \"name\": \"status\", \"display_name\": \"状态\", \"data_type\": \"options\" },\n          { \"name\": \"assignee\", \"display_name\": \"负责人\", \"data_type\": \"persons\" }\n        ],\n        \"rows\": [\n          { \"id\": \"T001\", \"title\": \"登录异常\", \"status\": [{ \"name\": \"处理中\", \"color\": \"orange\" }], \"assignee\": [{ \"id\": \"ou_xxx\" }] }\n        ]\n      },\n      { \"tag\": \"hr\" },\n      {\n        \"tag\": \"column_set\", \"horizontal_align\": \"right\",\n        \"columns\": [{ \"tag\": \"column\", \"width\": \"auto\", \"elements\": [{\n          \"tag\": \"button\", \"type\": \"primary_filled\",\n          \"text\": { \"tag\": \"plain_text\", \"content\": \"查看全部\" },\n          \"behaviors\": [{ \"type\": \"open_url\", \"default_url\": \"https://your-app.com/tickets\" }]\n        }]}]\n      }\n    ]\n  }\n}\n```\n","tags":{"latest":"0.2.1","card":"0.1.0","feishu":"0.1.0","gui":"0.1.0","interactive":"0.1.0","lark":"0.1.0"},"stats":{"comments":0,"downloads":671,"installsAllTime":25,"installsCurrent":0,"stars":0,"versions":3},"createdAt":1773551474859,"updatedAt":1778491917527},"latestVersion":{"version":"0.2.1","createdAt":1773563040968,"changelog":"修复 src/send-card.ts 中 form_action_type 错误值：action_type:form_submit/form_reset → form_action_type:submit/reset（JSON 2.0 正确字段）","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"afk101","userId":"s17e2a61ft6fber71z31yv696s84x7na","displayName":"afk101","image":"https://avatars.githubusercontent.com/u/160566086?v=4"},"moderation":null}