@amaster.ai/pi-lark 0.1.3 → 0.1.5

package/skills/lark-im/references/card/card-2.0-schema.md

@@ -0,0 +1,107 @@
+# 卡片 2.0 组件大纲
+
+Card 2.0 组件按**容器 / 展示 / 交互**三类，均通过 `tag` 字段声明。先在下表按用途选组件，再点明细看字段：有明细文件的点 `components/<tag>.md`（完整字段+示例+易错点），低频组件点链接看官方文档。
+
+## 根结构
+
+顶层固定四字段，先搭骨架再往 `body.elements` 填组件。以下为**推荐完整骨架**（含 type scale、light/dark color token、header 三件套）：
+
+```json
+{
+  "schema": "2.0",
+  "config": {
+    "update_multi": true,
+    "width_mode": "default",
+    "style": {
+      "text_size": {
+        "title":   { "default": "heading-2", "pc": "heading-2", "mobile": "heading-3" },
+        "body":    { "default": "normal",    "pc": "normal",    "mobile": "normal"    },
+        "caption": { "default": "notation",  "pc": "notation",  "mobile": "notation"  }
+      },
+      "color": {
+        "cus-primary":    { "light_mode": "rgba(30,120,255,1)",    "dark_mode": "rgba(80,150,255,1)"   },
+        "cus-primary-bg": { "light_mode": "rgba(30,120,255,0.08)", "dark_mode": "rgba(80,150,255,0.12)" },
+        "cus-muted":      { "light_mode": "rgba(100,106,115,1)",   "dark_mode": "rgba(150,155,163,1)"  }
+      }
+    }
+  },
+  "header": {
+    "title":    { "tag": "plain_text", "content": "卡片标题" },
+    "subtitle": { "tag": "plain_text", "content": "副标题：一句上下文（时间/来源/状态）" },
+    "template": "blue",
+    "icon": { "tag": "standard_icon", "token": "notice_colorful" },
+    "text_tag_list": [
+      { "tag": "text_tag", "text": { "tag": "plain_text", "content": "状态标签" }, "color": "blue" }
+    ]
+  },
+  "body": { "direction": "vertical", "padding": "12px 12px 20px 12px", "elements": [] }
+}
+```
+
+> **按需裁剪**：`subtitle` / `text_tag_list` / color token 按实际诉求取舍，不强制全用。组件里用 `"text_size": "title"` / `"caption"` 引用 token，用 `"font_color": "cus-muted"` 引用颜色 token；主色系变化时只需改 config 里的 RGBA，全卡自动跟随。
+
+- `schema` 必须显式为 `"2.0"`，否则按 1.0 渲染。`header` 详见 `components/header.md`。
+- **元素通用字段**（所有 `elements[]` 组件）：`tag`(必填) · `element_id`(卡内唯一，字母开头、≤20 字符) · `margin`(外边距 [-99,99]px)。
+- `card_link`（整卡跳转）：`{url, pc_url, ios_url, android_url}`，至少填 `url`；某端禁跳设 `lark://msgcard/unsupported_action`。
+- 硬限制：单卡 ≤ **200** 元素；需客户端 **≥ 7.20**（旧版仅显示 header）。
+- 颜色 / 图标枚举见 `resource/colors.md` · `resource/icons.md`。
+
+**config**（全局行为，可整体省略）：
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `update_multi` | true | 共享卡片，v2 仅支持 true |
+| `width_mode` | default | `default`(≤600px) / `compact`(400px) / `fill`(撑满) |
+| `enable_forward` | true | 是否允许转发 |
+| `summary` | — | 会话列表预览：`{content, i18n_content:{zh_cn,en_us,…}}` |
+| `streaming_mode` | false | 流式更新模式（配 `streaming_config`） |
+| `style.text_size` | — | 自定义字号 token，格式 `{"<名称>":{default,pc,mobile}}`；名称可自定义（如 `title`/`caption`），组件 `text_size` 引用该名称 |
+| `style.color` | — | 自定义颜色 token，格式 `{"<名称>":{light_mode,dark_mode}}`（RGBA）；名称可自定义（如 `cus-primary`），组件 `font_color`/`background_style` 等字段引用 |
+
+> 多语言：`config.locales` 限定生效语种、`use_custom_translation` 优先用自带 i18n。
+
+**body 布局字段**（均 v2 新增）：`direction`(vertical/horizontal) · `padding`([0,99]px) · `horizontal_spacing`/`vertical_spacing`(`small`4/`medium`8/`large`12/`extra_large`16 或 px) · `horizontal_align`/`vertical_align`。
+
+---
+
+## 容器类（布局 / 组织交互）
+
+| 组件 | 用途 |
+|---|---|
+| [column_set](components/column_set.md) | 横向分栏，多列图文对齐（数据表、字段对、列表） |
+| [collapsible_panel](components/collapsible_panel.md) | 折叠面板，收纳备注/长文本等次要信息 |
+| [form](components/form.md) | 表单容器，批量录入表单项后一次提交 |
+| [interactive_container](components/interactive_container.md) | 整块可点击区域，可统一定义样式与交互 |
+| [循环容器](components/recycling_container.md) | 批量渲染同版式不同数据（仅搭建工具） |
+
+## 展示类（无交互）
+
+| 组件 | 用途 |
+|---|---|
+| [header](components/header.md) | 卡片标题区：主/副标题、后缀标签、主题色 |
+| [div](components/div.md) | 普通文本，带前缀图标、字段对 |
+| [markdown](components/markdown.md) | 富文本，最常用；@人、彩色、链接、列表、表格等 |
+| [img](components/img.md) | 单图 |
+| [img_combination](components/img_combination.md) | 多图拼排（双图/三图/宫格） |
+| [person](components/person.md) | 单个人员头像/姓名 |
+| [person_list](components/person_list.md) | 多个人员头像/姓名 |
+| [chart](components/chart.md) | VChart 图表（折线/柱/饼/词云等） |
+| [table](components/table.md) | 多列数据表（只能放根节点） |
+| [hr](components/hr.md) | 分割线 |
+
+## 交互类
+
+| 组件 | 用途 |
+|---|---|
+| [button](components/button.md) | 按钮：回调 / 跳转 / 表单提交 |
+| [input](components/input.md) | 文本输入框（多嵌在 form 内） |
+| [overflow](components/overflow.md) | 折叠按钮组，收纳多个操作 |
+| [select_static](components/select_static.md) | 下拉单选 |
+| [multi_select_static](components/multi_select_static.md) | 下拉多选 |
+| [select_person](components/select_person.md) | 人员单选 |
+| [multi_select_person](components/multi_select_person.md) | 人员多选 |
+| [date_picker](components/date_picker.md) | 日期选择器 |
+| [picker_time](components/picker_time.md) | 时间选择器 |
+| [picker_datetime](components/picker_datetime.md) | 日期时间选择器 |
+| [select_img](components/select_img.md) | 图片选择（单/多选） |
+| [checker](components/checker.md) | 勾选器，任务勾选回调 |

package/skills/lark-im/references/card/components/button.md

@@ -0,0 +1,63 @@
+# 按钮 `button`
+
+交互按钮，支持跳转 / 回调 / 表单提交三类行为。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "button",
+  "text": { "tag": "plain_text", "content": "确定" },
+  "type": "primary",
+  "behaviors": [{ "type": "callback", "value": { "action": "ok" } }]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `button` |
+| `text` | 否 | Object | / | `{tag:"plain_text", content}`，≤100 字符 |
+| `type` | 否 | String | default | 见下方 type 枚举 |
+| `size` | 否 | String | medium | `tiny` / `small` / `medium` / `large` |
+| `width` | 否 | String | default | `default` / `fill` / `[100,∞)px` |
+| `behaviors` | 是* | Array | / | 交互行为，见下；表单内按钮不用 behaviors 而用 `form_action_type` |
+| `icon` | 否 | Object | / | 前缀图标（同 `div.icon`） |
+| `hover_tips` | 否 | Object | / | PC 端悬浮提示，plain_text |
+| `disabled` | 否 | Boolean | false | 是否禁用 |
+| `disabled_tips` | 否 | Object | / | 禁用后悬浮提示，plain_text |
+| `confirm` | 否 | Object | / | 二次确认弹窗 `{title, text}`（均 plain_text，title 必填） |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+| `element_id` | 否 | String | / | 唯一标识，字母开头 ≤20 字符 |
+
+**type 枚举**：`default`(黑字描边) / `primary`(蓝字描边) / `danger`(红字描边) / `text` / `primary_text` / `danger_text`(无边框) / `primary_filled`(蓝底白字) / `danger_filled`(红底白字) / `laser`(镭射)。
+
+## 按钮主次（强制）
+
+- 全卡仅 1 个按钮 → `type: "primary_filled"`，并 `width: "fill"` 撑满成强焦点。
+- 多个并列按钮 → 第一个（主操作）`primary_filled`，其余一律 `default`，形成「一主多次」层级。
+- 删除 / 拒绝等危险操作用 `danger` 系（`danger` 或 `danger_filled`）。
+
+## behaviors（交互行为）
+
+```json
+// 1. 服务端回调
+{ "type": "callback", "value": { "key": "v" } }
+// 2. 跳转链接（可与 callback 同数组共存）
+{ "type": "open_url", "default_url": "https://x", "pc_url": "", "ios_url": "", "android_url": "" }
+```
+
+表单容器内的按钮 **不用 behaviors**，改用根字段：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name` | 是 | 表单内唯一标识 |
+| `form_action_type` | 是 | `submit`（提交表单）/ `reset`（重置） |
+
+## 嵌套 / 易错点
+
+- 可嵌套在 column_set / form / collapsible_panel / 循环容器 / interactive_container 内。
+- 2.0 已废弃 `action` 交互模块，按钮直接放 `elements`，用间距控制排列。
+- 旧式 `url`/`value` 顶层字段是 1.0 写法；2.0 一律用 `behaviors`。
+- 点击触发 `card.action.trigger`，回传 `action.tag="button"` + `action.value`（即 callback 的 value）。

package/skills/lark-im/references/card/components/chart.md

@@ -0,0 +1,57 @@
+# 图表 `chart`
+
+基于 VChart 的可视化图表（折线/柱/饼/词云等）。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "chart",
+  "chart_spec": {
+    "type": "line",
+    "title": { "text": "趋势" },
+    "data": { "values": [
+      { "time": "周一", "value": 8 },
+      { "time": "周二", "value": 14 }
+    ] },
+    "xField": "time",
+    "yField": "value"
+  }
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `chart` |
+| `chart_spec` | 是 | Object | / | VChart 图表定义，见下 |
+| `aspect_ratio` | 否 | String | 16:9(PC)/1:1(移动) | `1:1` / `2:1` / `4:3` / `16:9` |
+| `color_theme` | 否 | String | brand | `brand` / `rainbow` / `complementary` / `converse` / `primary`；chart_spec 里声明了样式则此项无效 |
+| `height` | 否 | String | auto | `auto`(按宽高比) 或 `[1,999]px`（设固定高则 aspect_ratio 失效） |
+| `preview` | 否 | Boolean | true | 是否可独立窗口/全屏查看 |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+| `element_id` | 否 | String | / | 唯一标识，字母开头 ≤20 字符 |
+
+## chart_spec 常用类型
+
+`chart_spec` 是标准 VChart spec。核心字段：`type`、`data.values`（数据数组）、`xField`/`yField`（轴字段）、`seriesField`（分组）、`title.text`、`legends`。
+
+| 图表 | type | 关键字段 |
+|---|---|---|
+| 折线 | `line` | `xField`, `yField` |
+| 面积 | `area` | `xField`, `yField` |
+| 柱状 | `bar` | `xField`, `yField`，分组加 `seriesField` |
+| 条形（横向） | `bar` | `direction:"horizontal"`，`xField`=值，`yField`=类别 |
+| 饼/环 | `pie` | `valueField`, `categoryField`，环图加 `innerRadius` |
+| 散点 | `scatter` | `xField`, `yField` |
+| 词云 | `wordCloud` | `nameField`, `valueField` |
+
+完整属性参考 [VChart 官方文档](https://www.visactor.io/vchart/option/barChart)。
+
+## 易错点
+
+- 不支持 JavaScript 语法，`chart_spec` 必须是纯 JSON。
+- 单卡建议 ≤5 个图表。
+- 移动端不支持部分 VChart 属性（纹理 texture、conical 渐变、grid 词云布局等），用了会在移动端加载失败。
+- 平台默认给 chart_spec 追加 media query 自适应；要自控可设 `"media": []`。

package/skills/lark-im/references/card/components/checker.md

@@ -0,0 +1,38 @@
+# 勾选器 `checker`
+
+任务勾选场景的交互组件，支持配置回调响应。仅支持手写 JSON，搭建工具不支持构建。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "checker",
+  "name": "check_1",
+  "checked": false,
+  "text": { "tag": "plain_text", "content": "完成新品上市计划报告" },
+  "behaviors": [{ "type": "callback", "value": { "key": "todo1" } }]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `checker` |
+| `name` | 否* | String | / | 唯一标识；**form 内必填且全局唯一** |
+| `checked` | 否 | Boolean | false | 初始勾选状态 |
+| `text` | 否 | Object | / | `{tag:"plain_text"\|"lark_md", content, text_size?, text_color?, text_align?}`（text_color 见 `../resource/colors.md`） |
+| `overall_checkable` | 否 | Boolean | true | 悬浮时整体是否有阴影效果 |
+| `button_area` | 否 | Object | / | `{pc_display_rule:"always"|"on_hover", buttons:[<=3 个 button]}` |
+| `checked_style` | 否 | Object | / | `{show_strikethrough, opacity}`，勾选后的内容样式 |
+| `disabled` / `disabled_tips` | 否 | Boolean/Object | false / 空 | 禁用及禁用提示 |
+| `hover_tips` | 否 | Object | 空 | 悬浮提示；与 `disabled_tips` 同配时后者生效 |
+| `behaviors` | 否 | Array | / | `[{type:"callback", value:{...}}]`；**未配置时仅本地勾选生效，不触发回调** |
+| `confirm` | 否 | Object | / | 二次确认弹窗 `{title, text}` |
+| `padding`/`margin` | 否 | String | 0 | [-99,99]px |
+
+## 嵌套 / 易错点
+
+- 可嵌套在 form / 交互容器 / column_set / collapsible_panel 内。
+- 不配置 `behaviors` 时勾选仅前端本地生效，不会触发服务端回调——需要业务侧感知必须显式配置。
+- 回调：`action.tag="checker"` + `action.checked`（布尔值）；form 内则读 `form_value[name]`。

package/skills/lark-im/references/card/components/collapsible_panel.md

@@ -0,0 +1,46 @@
+# 折叠面板 `collapsible_panel`
+
+折叠次要内容（备注、长文本），点标题展开/收起。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "collapsible_panel",
+  "expanded": false,
+  "header": { "title": { "tag": "plain_text", "content": "面板标题" } },
+  "elements": [{ "tag": "markdown", "content": "折叠的内容" }]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `collapsible_panel` |
+| `header` | 是 | Object | / | 标题区，见下 |
+| `elements` | 否 | Array | / | 面板内组件；**不能放 `form`** |
+| `expanded` | 否 | Boolean | false | 是否默认展开 |
+| `background_color` | 否 | String | 透明 | 面板背景，颜色枚举（见 `../resource/colors.md`） |
+| `border` | 否 | Object | / | `{ color, corner_radius }` |
+| `direction` | 否 | String | vertical | `vertical` / `horizontal` |
+| `vertical_spacing`/`horizontal_spacing` | 否 | String | 8px | 间距枚举或 [0,99]px |
+| `padding` | 否 | String | 0 | 内边距 [0,99]px |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+
+**header 字段**：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `title` | 否 | `{tag:"plain_text"\|"markdown", content}` |
+| `background_color` | 否 | 标题区背景，颜色枚举 |
+| `width` | 否 | `fill` / `auto` / `auto_when_fold`(收起时自适应) |
+| `vertical_align` | 否 | `top`/`center`/`bottom` |
+| `icon` | 否 | 图标 `{tag, token, color, size}`（同 `div.icon`，多 `size`） |
+| `icon_position` | 否 | `left` / `right` / `follow_text` |
+| `icon_expanded_angle` | 否 | 展开时图标旋转角：`-180`/`-90`/`90`/`180` |
+
+## 嵌套 / 易错点
+
+- 内部不支持 `form`；容器最多嵌套 5 层。
+- 仅支持写 JSON，搭建工具不支持。

package/skills/lark-im/references/card/components/column_set.md

@@ -0,0 +1,53 @@
+# 分栏 `column_set` + `column`
+
+横向多列布局容器。`column_set` 装若干 `column`，每个 `column` 内再放组件。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "column_set",
+  "flex_mode": "none",
+  "columns": [
+    { "tag": "column", "width": "weighted", "weight": 1,
+      "elements": [{ "tag": "markdown", "content": "左列" }] },
+    { "tag": "column", "width": "weighted", "weight": 1,
+      "elements": [{ "tag": "markdown", "content": "右列" }] }
+  ]
+}
+```
+
+## column_set 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `column_set` |
+| `columns` | 是 | column[] | / | 列数组，子节点只能是 `column` |
+| `flex_mode` | 否 | String | none | 窄屏自适应：`none`(按比例压缩) / `stretch`(变上下堆叠) / `flow`(自动换行) / `bisect`(两等分) / `trisect`(三等分) |
+| `horizontal_spacing` | 否 | String | 8px | `small`(4)/`medium`(8)/`large`(12)/`extra_large`(16) 或 `[0,99]px` |
+| `horizontal_align` | 否 | String | left | `left` / `center` / `right` |
+| `background_style` | 否 | String | default | `default` 或颜色枚举/RGBA（见 `../resource/colors.md`）；嵌套时上层覆盖下层 |
+| `action` | 否 | Object | / | 整块点击跳转 `{ multi_url:{url,pc_url,ios_url,android_url} }` |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+
+## column 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `column` |
+| `elements` | 否 | Element[] | / | 列内组件；**不能放 `form` 和 `table`**，可放 `column_set` |
+| `width` | 否 | String | auto | 仅 `flex_mode:none` 生效：`auto` / `weighted`(配 weight) / `[16,600]px` |
+| `weight` | 否 | Number | 1 | `width:weighted` 时的宽度占比，1~5 整数 |
+| `vertical_align` | 否 | String | top | `top` / `center` / `bottom` |
+| `direction` | 否 | String | vertical | `vertical` / `horizontal` |
+| `horizontal_spacing`/`vertical_spacing` | 否 | String | 8px | 同上间距枚举或 `[0,99]px` |
+| `padding` | 否 | String | 0 | 内边距 [0,99]px |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+| `background_style` | 否 | String | default | 同上 |
+| `action` | 否 | Object | / | 点击列跳转，同 column_set.action |
+
+## 嵌套 / 易错点
+
+- **column_set 的直接子节点只能是 `column`**；不能 `column_set → column_set`。二级分栏要走 `column_set → column → column_set`。
+- column 内可放除 `form` / `table` 外的所有组件。
+- 最多嵌套 5 层，过深会压缩展示空间。

package/skills/lark-im/references/card/components/date_picker.md

@@ -0,0 +1,34 @@
+# 日期选择器 `date_picker`
+
+提供日期选项的交互组件，默认拥有交互能力（无需显式 `behaviors` 也会回调）。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "date_picker",
+  "placeholder": { "tag": "plain_text", "content": "请选择" },
+  "initial_date": "2024-01-01"
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `date_picker` |
+| `name` | 否* | String | / | 唯一标识；**form 内必填且全局唯一** |
+| `required` | 否 | Boolean | false | 是否必选（form 内生效） |
+| `initial_date` | 否 | String | / | 初始值，格式 `yyyy-MM-dd`，会覆盖 `placeholder` |
+| `placeholder` | 否 | Object | / | 占位文本，plain_text；未设 `initial_date` 时必填 |
+| `width` | 否 | String | default | `default`/`fill`/`[100,∞)px` |
+| `disabled` | 否 | Boolean | false | 是否禁用（需端版本 V7.4+） |
+| `behaviors` | 否 | Array | / | `[{type:"callback", value:{...}}]` |
+| `confirm` | 否 | Object | / | 二次确认弹窗 `{title, text}` |
+| `margin` | 否 | String | 0 | [-99,99]px |
+
+## 嵌套 / 易错点
+
+- 可嵌套在 column_set / form / collapsible_panel / 循环容器 / 交互容器内；搭建工具中暂不支持嵌套在交互容器中。
+- 提醒用户注意时区语境（如预定海外酒店用酒店所在地时区）；服务端只返回用户当前时区作为参考，不代表用户选的就是该时区。
+- 回调：`action.tag="date_picker"` + `action.option`（日期字符串，如 `"2025-06-10 +0800"`）+ `action.timezone`；form 内则读 `form_value[name]`。

package/skills/lark-im/references/card/components/div.md

@@ -0,0 +1,36 @@
+# 普通文本 `div`
+
+带样式的文本块，支持前缀图标和 label-value 字段对。**Card 2.0**。富文本用 `markdown` 组件。
+
+## 最小示例
+
+```json
+{
+  "tag": "div",
+  "text": { "tag": "plain_text", "content": "示例文本" }
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `div` |
+| `text` | 否 | Object | / | 文本对象，见下 |
+| `text.tag` | 是 | String | plain_text | `plain_text` 或 `lark_md`（部分 Markdown，语法见 `markdown.md`） |
+| `text.content` | 是 | String | / | 文本内容 |
+| `text.text_size` | 否 | String | normal | `heading-0`~`heading-4` / `normal`(14px) / `notation`(12px) 等；可在 `config.style.text_size` 自定义 pc/mobile 不同字号 |
+| `text.text_color` | 否 | String | default | 颜色枚举（见 `../resource/colors.md`），仅 `plain_text` 生效 |
+| `text.text_align` | 否 | String | left | `left` / `center` / `right` |
+| `text.lines` | 否 | Int | / | 最大显示行数，超出 `...` 省略 |
+| `icon` | 否 | Object | / | 前缀图标，见下 |
+| `icon.tag` | 否 | String | / | `standard_icon`（用 `token`+`color`，token 见 `../resource/icons.md`）或 `custom_icon`（用 `img_key`） |
+| `width` | 否 | String | fill | `fill` / `auto` / `[16,999]px` |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+| `element_id` | 否 | String | / | 唯一标识，字母开头 ≤20 字符；流式更新时 `text.element_id` 指定文本 |
+
+> `fields` 字段（多列 label-value）：数组，每项 `{ is_short, text:{tag,content} }`，`is_short:true` 可并排。
+
+## 易错点
+
+- `text_color` 只在 `text.tag` 为 `plain_text` 时生效；`lark_md` 用内联 `<font color=red>` 着色。

package/skills/lark-im/references/card/components/form.md

@@ -0,0 +1,51 @@
+# 表单容器 `form`
+
+批量录入表单项后一次提交：用户在前端填写多个表单项，点击提交按钮后将所有值打包一次性回调到服务端。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "form",
+  "name": "form_1",
+  "elements": [
+    { "tag": "input", "name": "reason", "required": true },
+    {
+      "tag": "button",
+      "text": { "tag": "plain_text", "content": "提交" },
+      "type": "primary",
+      "form_action_type": "submit",
+      "name": "Button_submit"
+    }
+  ]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `form` |
+| `name` | 是 | String | / | 表单容器唯一标识，卡片内全局唯一，用于识别提交数据归属 |
+| `elements` | 是 | Element[] | [] | 子节点，支持除 `table` 和 `form` 外的所有组件 |
+| `direction` | 否 | String | vertical | `vertical` / `horizontal` |
+| `horizontal_spacing`/`vertical_spacing` | 否 | String | 8px/12px | 间距枚举 `small`(4)/`medium`(8)/`large`(12)/`extra_large`(16) 或 `[0,99]px` |
+| `horizontal_align` | 否 | String | left | `left`/`center`/`right` |
+| `vertical_align` | 否 | String | top | `top`/`center`/`bottom` |
+| `padding`/`margin` | 否 | String | 0 | [-99,99]px，支持单值/双值/四值写法 |
+| `element_id` | 否 | String | / | 唯一标识，字母开头 ≤20 字符 |
+
+### 子组件内嵌字段（交互组件嵌在 form 内时生效）
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name` | 是 | 表单内组件唯一标识，卡片全局唯一，否则提交失败 |
+| `required` | 否 | 是否必填；为 true 且未填时点提交会本地拦截，不发起回调 |
+| `form_action_type` | 是（按钮） | `submit`（提交）/ `reset`（重置初始值）；表单内按钮**不用** `behaviors` |
+
+## 嵌套 / 易错点
+
+- `form` 不支持嵌套 `table` 和 `form`；且 `form` 本身只能放卡片根节点下，不能被其他组件嵌套。
+- form 内所有交互组件的 `name` 必须填且全局唯一，否则提交失败。
+- 表单内必须包含一个 `form_action_type: submit` 的按钮。
+- 回调来源：`card.action.trigger` 中 `action.tag="button"` + `action.form_value`（按组件 `name` 映射各字段值）。

package/skills/lark-im/references/card/components/header.md

@@ -0,0 +1,34 @@
+# 标题 `header`
+
+卡片顶部标题区（主/副标题、后缀标签、图标、主题色）。**Card 2.0**。挂在卡片根的 `header` 键下，不在 `body.elements` 内，单卡仅一个。
+
+## 最小示例
+
+```json
+{
+  "header": {
+    "title": { "tag": "plain_text", "content": "卡片标题" },
+    "template": "blue"
+  }
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 说明 |
+|---|---|---|---|
+| `title` | 是 | Object | 主标题，`{tag:"plain_text"\|"lark_md", content}`，最多 4 行 |
+| `subtitle` | 否 | Object | 副标题，同 title，最多 1 行；只配副标题会按主标题展示 |
+| `template` | 否 | String | 主题色枚举，见下；默认 `default` |
+| `text_tag_list` | 否 | Array | 后缀标签，最多 3 个，每项 `{tag:"text_tag", text:{tag:"plain_text",content}, color}` |
+| `i18n_text_tag_list` | 否 | Object | 多语言后缀标签；与 `text_tag_list` 二选一，同配以多语言为准 |
+| `icon` | 否 | Object | 前缀图标（同 `div.icon`） |
+| `padding` | 否 | String | 内边距，默认 12px，[0,99]px |
+
+**template 枚举**（13 色）：`blue` / `wathet` / `turquoise` / `green` / `yellow` / `orange` / `red` / `carmine` / `violet` / `purple` / `indigo` / `grey` / `default`。
+
+**标签 color 枚举**：`neutral`/`blue`/`turquoise`/`lime`/`orange`/`violet`/`indigo`/`wathet`/`green`/`yellow`/`red`/`purple`/`carmine`。深浅档位及 RGBA 见 `../resource/colors.md`。
+
+## 选色建议
+
+按场景选 template 颜色见 `../lark-im-card-style.md` 意图表。常见语义：green=成功/完成，orange=警告，red=错误/危险，grey=失效/归档，blue=通用信息。

package/skills/lark-im/references/card/components/hr.md

@@ -0,0 +1,17 @@
+# 分割线 `hr`
+
+分隔卡片内容的水平线。**Card 2.0**（1.0 同名 `hr`）。
+
+## 最小示例
+
+```json
+{ "tag": "hr" }
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `hr` |
+| `margin` | 否 | String | 0 | 外边距，范围 [-99,99]px，如 `"8px 0"` |
+| `element_id` | 否 | String | / | 组件唯一标识，字母开头、≤20 字符 |

package/skills/lark-im/references/card/components/img.md

@@ -0,0 +1,34 @@
+# 图片 `img`
+
+展示图片。需先调上传图片接口拿 `img_key`。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "img",
+  "img_key": "img_v3_xxx",
+  "alt": { "tag": "plain_text", "content": "" }
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `img` |
+| `img_key` | 是 | String | / | 图片 key，上传图片接口获取 |
+| `alt` | 是 | Object | / | hover 说明，`{tag:"plain_text", content:""}`，不需要传空 |
+| `title` | 否 | Object | / | 图片标题，plain_text 对象 |
+| `scale_type` | 否 | String | crop_center | `crop_center` / `crop_top` / `fit_horizontal`（不裁剪） |
+| `size` | 否 | String | / | 仅 `crop_*` 生效：`stretch`/`large`(160)/`medium`(80)/`small`(40)/`tiny`(16)，或 `"100px 100px"` |
+| `corner_radius` | 否 | String | / | 圆角，`[0,∞]px` 或 `[0,100]%` |
+| `transparent` | 否 | Boolean | false | 是否透明底 |
+| `preview` | 否 | Boolean | true | 点击是否放大；配 `card_link` 跳转时设 false |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+| `element_id` | 否 | String | / | 唯一标识，字母开头 ≤20 字符 |
+
+## 易错点
+
+- 通栏效果：2.0 不再支持 `size: stretch_without_padding`，改用负 `margin`（如 `"4px -12px"`）。
+- 上传规范：≤10M、尺寸 ≤1500×3000px、高:宽 ≤16:9。

package/skills/lark-im/references/card/components/img_combination.md

@@ -0,0 +1,30 @@
+# 多图混排 `img_combination`
+
+多张图片按预设版式拼排。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "img_combination",
+  "combination_mode": "double",
+  "img_list": [{ "img_key": "img_v3_a" }, { "img_key": "img_v3_b" }]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `img_combination` |
+| `combination_mode` | 是 | String | / | `double`(≤2) / `triple`(≤3) / `bisect`(双列，≤6) / `trisect`(三列，≤9) |
+| `img_list` | 是 | Array | / | 每项 `{ img_key }`，顺序即排列顺序 |
+| `combination_transparent` | 否 | Boolean | false | 是否透明底 |
+| `corner_radius` | 否 | String | / | 圆角，`[0,∞]px` 或 `[0,100]%` |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+| `element_id` | 否 | String | / | 唯一标识，字母开头 ≤20 字符 |
+
+## 易错点
+
+- 图片数超过 mode 上限：只显示靠前的，其余丢弃；不足则留空白。
+- 上传规范：≤10M、≤1500×3000px、高:宽 ≤16:9。

package/skills/lark-im/references/card/components/input.md

@@ -0,0 +1,43 @@
+# 输入框 `input`
+
+收集用户文本输入。常嵌在 `form` 内配合提交按钮使用。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "input",
+  "name": "comment",
+  "placeholder": { "tag": "plain_text", "content": "请输入" },
+  "label": { "tag": "plain_text", "content": "备注：" }
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `input` |
+| `name` | 否* | String | / | 唯一标识；**在 form 内必填且全局唯一**，用于识别提交数据 |
+| `required` | 否 | Boolean | false | 是否必填（仅 form 内生效） |
+| `placeholder` | 否 | Object | / | 占位文本，plain_text，≤100 字符 |
+| `default_value` | 否 | String | / | 预填内容 |
+| `label` | 否 | Object | / | 描述文本，plain_text |
+| `label_position` | 否 | String | top | `top` / `left`（窄屏自动转 top） |
+| `input_type` | 否 | String | text | `text` / `multiline_text`(多行，回调含 `\n`) / `password` |
+| `rows` | 否 | Number | 5 | 多行时默认行数 |
+| `auto_resize` | 否 | Boolean | false | 多行时高度自适应（仅 PC） |
+| `max_rows` | 否 | Number | / | `auto_resize` 时最大行数 |
+| `max_length` | 否 | Number | 1000 | 最大字符数，[1,1000] |
+| `show_icon` | 否 | Boolean | true | password 时是否显示前缀图标 |
+| `width` | 否 | String | default | `default` / `fill` / `[100,∞)px` |
+| `disabled` | 否 | Boolean | false | 是否禁用（配 `disabled_tips` plain_text） |
+| `behaviors` | 否 | Array | / | `[{type:"callback", value:{...}}]` |
+| `confirm` | 否 | Object | / | 二次确认弹窗 `{title, text}` |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+
+## 嵌套 / 易错点
+
+- 可嵌套在 column_set / form / collapsible_panel / 循环容器 / interactive_container 内。
+- 在 form 内为**异步提交**：用户填完点提交按钮才一次性回调全部表单数据。
+- 回调里 `action.tag="input"` + `action.input_value`（用户输入值）；form 提交则值在 `form_value` 内。