@amaster.ai/pi-lark 0.1.4 → 0.1.6

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

@@ -0,0 +1,35 @@
+# 循环容器（搭建工具专属，无 JSON tag）
+
+批量渲染同版式不同数据的列表（如商品列表、推荐列表）。**仅支持在飞书卡片搭建工具中可视化构建，不支持手写卡片 JSON 代码实现**——因此没有 `tag` 字段可直接编排。
+
+## 使用方式
+
+1. 在[卡片搭建工具](https://open.feishu.cn/cardkit)中添加循环容器组件，绑定一个对象数组变量。
+2. 在容器内添加任意展示/交互/分栏组件，并将其字段绑定到对象数组的子变量。
+3. 发布卡片模板后，发送时通过 `template_variable` 传入实际数据数组，数组每个元素对应一条循环项。
+
+## 发送示例（模板 + 变量赋值）
+
+```json
+{
+  "type": "template",
+  "data": {
+    "template_id": "AAqi6xJ8rabcd",
+    "template_version_name": "1.0.0",
+    "template_variable": {
+      "looping": [
+        { "title": "**和风陶韵**", "description": "...", "image": { "img_key": "img_v3_xxx" } },
+        { "title": "**匠心之作**", "description": "...", "image": { "img_key": "img_v3_yyy" } }
+      ]
+    }
+  }
+}
+```
+
+将以上 JSON 压缩转义后作为 `messages.create` 的 `content`，`msg_type` 为 `interactive`。
+
+## 嵌套 / 易错点
+
+- 不支持再嵌套循环容器（对象数组变量不支持嵌套对象数组类型）。
+- 数组元素个数即渲染条数，可直接控制列表长度。
+- 若循环容器内嵌表单容器的交互组件（如 input），交互组件的 `name`（表单项标识）必须绑定到不重复的子变量，否则预览/发送报错。

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

@@ -0,0 +1,42 @@
+# 多图选择 `select_img`
+
+以图片为选项的交互组件，支持单选/多选（如商品图、模板图、AI 生成图）。仅支持手写 JSON，搭建工具不支持。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "select_img",
+  "name": "select_img_1",
+  "layout": "bisect",
+  "aspect_ratio": "16:9",
+  "options": [
+    { "img_key": "img_v2_xxx", "value": "picture1" },
+    { "img_key": "img_v2_yyy", "value": "picture2" }
+  ]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `select_img` |
+| `options` | 是 | Array | / | 选项，每项 `{img_key, value, disabled?, disabled_tips?, hover_tips?}` |
+| `multi_select` | 否 | Boolean | false | 多选仅支持异步提交，**必须**内嵌在 form 中，否则报错 |
+| `layout` | 否 | String | bisect | 图片布局：`stretch`(撑满)/`bisect`(二等分)/`trisect`(三等分) |
+| `aspect_ratio` | 否 | String | 16:9 | `1:1`/`16:9`/`4:3` |
+| `name` | 否* | String | / | 唯一标识；**form 内必填且全局唯一** |
+| `required` | 否 | Boolean | false | 是否必选（form 内生效） |
+| `can_preview` | 否 | Boolean | true | 点击图片是否弹窗放大（仅 form 内生效） |
+| `disabled` | 否 | Boolean | false | 是否禁用整组件 |
+| `value` | 否 | String/Object | / | 自定义回传参数 |
+| `behaviors` | 是 | Array | / | `[{type:"callback", value:{...}}]` |
+| `confirm` | 否 | Object | / | 二次确认弹窗 `{title, text}` |
+
+## 嵌套 / 易错点
+
+- 可嵌套在根节点 / column_set / form / 交互容器（搭建工具暂不支持嵌套交互容器）。
+- **不在 form 内**：仅支持单选，点击立即提交触发回调，不支持多选/异步提交。
+- **在 form 内**：支持单选/多选 + 异步提交（随表单一起提交）。
+- 回调（非 form）：`action.tag="select_img"` + `action.options`（单选时仍是该字段）；form 内则读 `form_value[name]`。

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

@@ -0,0 +1,39 @@
+# 人员选择-单选 `select_person`
+
+从候选人员中单选一人。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "select_person",
+  "placeholder": { "tag": "plain_text", "content": "请选择" },
+  "options": [
+    { "value": "ou_xxx" },
+    { "value": "ou_yyy" }
+  ]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `select_person` |
+| `options` | 否 | Array | / | 候选人，每项 `{value: open_id}`；**为空或全无效时，候选项为会话内全体成员** |
+| `name` | 否* | String | / | 唯一标识；**form 内必填且全局唯一** |
+| `required` | 否 | Boolean | false | 是否必选（form 内生效） |
+| `type` | 否 | String | default | `default`(带框) / `text`(纯文本) |
+| `placeholder` | 否 | Object | / | 占位文本，plain_text |
+| `initial_option` | 否 | String | / | 初始选中的 open_id，须在 options 内 |
+| `width` | 否 | String | default | `default` / `fill` / `[100,∞)px` |
+| `disabled` | 否 | Boolean | false | 是否禁用 |
+| `behaviors` | 否 | Array | / | `[{type:"callback", value:{...}}]` |
+| `confirm` | 否 | Object | / | 二次确认弹窗 `{title, text}` |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+
+## 嵌套 / 易错点
+
+- 可嵌套在 column_set / form / collapsible_panel / 循环容器 / interactive_container 内。
+- `options[].value` 只接受 **open_id**。
+- 回调 `action.tag="select_person"` + `action.option`（选中人的 open_id）。

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

@@ -0,0 +1,43 @@
+# 下拉单选 `select_static`
+
+下拉菜单单选。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "select_static",
+  "placeholder": { "tag": "plain_text", "content": "请选择" },
+  "options": [
+    { "text": { "tag": "plain_text", "content": "选项1" }, "value": "1" },
+    { "text": { "tag": "plain_text", "content": "选项2" }, "value": "2" }
+  ]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `select_static` |
+| `options` | 否 | Array | / | 选项，见下 |
+| `options[].text` | 是 | Object | / | 选项名，plain_text |
+| `options[].value` | 是 | String | / | 选项回调值，**同组件内不可重复** |
+| `options[].icon` | 否 | Object | / | 选项前缀图标（同 `div.icon`） |
+| `name` | 否* | String | / | 唯一标识；**form 内必填且全局唯一** |
+| `required` | 否 | Boolean | false | 是否必选（form 内生效） |
+| `type` | 否 | String | default | `default`(带框) / `text`(纯文本) |
+| `placeholder` | 否 | Object | / | 占位文本，plain_text |
+| `initial_option` | 否 | String | / | 初始选中内容（覆盖 placeholder 和 initial_index） |
+| `initial_index` | 否 | Int | / | 初始选中序号，0=不选，1=第一个 |
+| `width` | 否 | String | default | `default` / `fill` / `[100,∞)px` |
+| `disabled` | 否 | Boolean | false | 是否禁用 |
+| `behaviors` | 否 | Array | / | `[{type:"callback", value:{...}}]` |
+| `confirm` | 否 | Object | / | 二次确认弹窗 `{title, text}` |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+
+## 嵌套 / 易错点
+
+- 可嵌套在 column_set / form / collapsible_panel / 循环容器 / interactive_container 内。
+- 选项 `value` 必须唯一，否则交互异常、服务端无法区分选了哪个。
+- 回调 `action.tag="select_static"` + `action.option`（选中项的 value）。

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

@@ -0,0 +1,53 @@
+# 表格 `table`
+
+多列数据表，支持文本/数字/选项/人员/日期等列类型。**Card 2.0**。
+
+## 最小示例
+
+```json
+{
+  "tag": "table",
+  "columns": [
+    { "name": "city", "display_name": "城市", "data_type": "text" },
+    { "name": "qty", "display_name": "数量", "data_type": "number" }
+  ],
+  "rows": [
+    { "city": "北京", "qty": 12 },
+    { "city": "上海", "qty": 8 }
+  ]
+}
+```
+
+## 字段
+
+| 字段 | 必填 | 类型 | 默认 | 说明 |
+|---|---|---|---|---|
+| `tag` | 是 | String | / | 固定 `table` |
+| `columns` | 是 | column[] | / | 列定义，≤50 列，见下 |
+| `rows` | 是 | Object[] | / | 行数据，按 `列name: 值` 填充 |
+| `page_size` | 否 | Number | 5 | 每页行数，[1,10] |
+| `row_height` | 否 | String | low | `low`/`middle`/`high`/`auto`/`[32,124]px` |
+| `row_max_height` | 否 | String | 124px | `row_height:auto` 时最大行高 [32,999]px |
+| `freeze_first_column` | 否 | Boolean | false | 冻结首列 |
+| `header_style` | 否 | Object | / | 表头样式：`{text_align, text_size, background_style:grey\|none, text_color, bold, lines}` |
+| `margin` | 否 | String | 0 | 外边距 [-99,99]px |
+
+**column 字段**：`name`(必填，键名) / `display_name`(表头名) / `data_type`(见下) / `width`(`auto`/`[80,600]px`/`%`) / `horizontal_align` / `vertical_align`；`number` 列可加 `format:{precision, symbol, separator}`；`date` 列可加 `date_format`(如 `YYYY/MM/DD`)。
+
+**data_type 与行值结构**：
+
+| data_type | 行值 |
+|---|---|
+| `text` | `"飞书"` |
+| `lark_md` | `"[链接](https://x)"` |
+| `number` | `168.23` |
+| `options` | `[{text:"S2", color:"blue"}]`（颜色枚举见 `../resource/colors.md`，文本勿过长） |
+| `persons` | `"ou_xxx"` 或 `["ou_a","ou_b"]` |
+| `date` | `1699341315000`（毫秒时间戳，按本地时区显示） |
+| `markdown` | `"![img](img_key)"` 完整 Markdown |
+
+## 嵌套 / 易错点
+
+- **table 只能放卡片根 `body.elements`**：不能被任何容器嵌套，自身也不能嵌别的组件。
+- 单卡最多 5 个 table（多语言每语言 5 个）。
+- `rows` 的键必须与 `columns[].name` 对应。

package/skills/lark-im/references/card/lark-im-card-create.md

@@ -0,0 +1,180 @@
+# 发送 Interactive 卡片工作流
+
+用户需要发送一张飞书互动卡片时，遵循本工作流。每次都必须严格按步骤执行。
+
+---
+
+## 入口分支：文字 / 图片 / 图片+文字组合
+
+判断用户输入类型：
+
+- **纯文字诉求**（无图片）→ 跳到 Step 1「文字诉求路径」。
+- **纯图片**（截图 / 设计稿，无额外文字说明内容）→ 走「以图片为输入」路径，图片既是内容源也是风格源。
+- **图片 + 文字组合** → 走「以图片为输入」路径，但**图片仅当样式/布局参考，内容来源以文字为准**（见第 5 点）。
+
+### 以图片为输入时的处理
+
+1. **分析图片**：从图片中提取视觉风格信息——
+   - 配色方案（色环定位）、间距节奏、层级关系、分组方式、组件类型
+   - 图片类型（见第 2 点）
+
+2. **判断图片类型**，决定保真策略：
+
+   | 图片类型 | 判断依据 | 构造策略 |
+   |---|---|---|
+   | **飞书卡片截图** | 能识别出 header / body / components 等飞书卡片结构特征 | **高保真复刻**：将截图中每一块视觉结构映射到相近的卡片 2.0 组件；复刻后仍需过 P0–P7 硬 Gate |
+   | **其它设计稿 / 海报 / 网页 UI** | 无飞书卡片结构特征 | **风格萃取 + 按原则重构**：提取配色、间距、层级关系等风格 token；布局按 P0–P7 原则重构（**不像素级仿制**），产出说明偏差 |
+
+3. **确定内容来源**：
+   - **纯图片**：从图片提取内容/信息点（文字、字段、操作）作为诉求（喂给 P0）
+   - **图片 + 文字组合**：**以文字/文档为内容来源**，图片仅提供样式和布局参考。将文字内容按图片风格组织进卡片
+
+4. **冲突处理**：当图片样式与 P0–P7 或卡片组件能力冲突时——
+   - 飞书卡片截图：在组件能力允许范围内**尽量保真**，冲突处微调并告知用户偏差原因
+   - 其它设计稿 / 海报 / UI：**以 P0–P7 为准**，图片仅当风格参考，冲突时不硬搬
+
+5. 分析明确后，向用户简要说明你的**类型判断结论 + 保真策略 + 内容来源方案**。然后进入 Step 2 加载组件文档，进入构造。
+
+---
+
+## Step 1（文字诉求路径）：分析意图，输出设计方案
+
+**目标**：在动手写 JSON 之前，先明确所有决策并告知用户。Step 2 的文档加载量取决于这里的组件列表，所以要尽量在这一步想清楚。
+
+分析以下内容并向用户简要说明：
+
+1. **版本**：Card 2.0 支持的组件更丰富，**推荐使用 Card 2.0**；仅当用户明确要求 1.0 时才用 1.0。
+2. **组件组合**：在 `lark-im-card-style.md` 「意图 → 组件组合」表里匹配最接近的意图行，参考推荐组件组合和该行的 `header.template` 颜色（部分行为"无 header"）。推荐组合仅供参考，**最终选型以符合用户意图为准**；使用 Card 2.0 时，可同时参考 `card-2.0-schema.md` 中的组件概述来补充或调整组件选择。
+3. **交互类型**（若有）：是否含会回调服务端的交互组件，以及是否有纯跳转（open_url）。回调分两类：① `select` / `multi_select` / `input` / `picker` / `overflow` 操作即默认回调；② `button` / `checker` / `interactive_container` 需显式配置 `behaviors`；`form` 提交统一回调。细则见 Step 5。
+4. **宽度模式**：`compact`(400px) 适合通知/祝福/轻提醒（内容精简、单焦点）；`default`(≤600px) 适合大多数场景；`fill`(撑满) 适合数据看板、含 `table` 的宽表格。默认 `default`，有明确理由才偏离。
+
+> 输出示例："Card 2.0，header green，`default`，组件：`column_set` / `column` / `markdown`，无交互。"
+
+---
+
+## Step 2：按需加载组件文档
+
+> ⚠️ **仅 Card 2.0 适用**：`card-2.0-schema.md`、`components/` 明细都是 2.0 结构。若 Step 1 定为 **Card 1.0**（含 Step 4 降级场景），这些**不可参考**，跳过本步，直接按 1.0 结构构造。
+
+**目标**：读组件明细 + 「好看的标准」，不全量加载。
+
+> 组件列表来源：**文字路径** = Step 1 的设计方案；**图片路径** = 入口分支图片分析阶段确定的组件列表。
+
+1. 阅读 `card-2.0-schema.md` —— 同时满足两个目的：① 了解组件概述，辅助组件选型；② 找到各组件的明细文档路由链接。**仅读一次，不重复加载。**
+2. 按路由逐个读取 `components/<tag>.md`（如 `components/column_set.md`、`components/button.md`）
+3. 阅读 `lark-im-card-style.md` 开头的「**好看的标准（P0–P7）**」和「视觉规范」——这是 Step 3 构造和自检的裁判基准，**构造前先内化**。
+
+---
+
+## Step 3：构造卡片 JSON
+
+按 Step 2 中对应版本的根结构骨架构造卡片，组件选型遵循 Step 1（或图片分析阶段）的设计方案。
+
+- Card 2.0 必须有 `"schema": "2.0"`，否则卡片不渲染
+- `form` 容器内按钮用 `form_action_type: "submit"`，不写 `behaviors`
+- `column_set` 的子节点只能是 `column`，不能直接放其他组件
+- `table` **只能放 body 根节点**，不能嵌套进 `column_set` / `interactive_container` 等容器
+- `collapsible_panel` 内**不能包含 `form`**；`interactive_container` 内**不能包含 `form`/`table`**
+
+### 发送前硬 Gate（按 P0–P7 自检，不过不许进 Step 4）
+
+构造完成后，逐条用 `lark-im-card-style.md` 的「好看的标准」做**结构化自检**。**P0 + P1–P3 是阻断项，任一不过必须回到本步修正后重判**，不得带病发送。
+
+**阻断项（必须全过）：**
+- [ ] **P0 符合诉求**：把用户诉求拆成信息点清单，逐点在 JSON 里找到承载组件；需要的操作（按钮/表单/跳转）都齐备；无与诉求无关的填充
+- [ ] **P1 层级**：body 内有且仅有**一个**最强焦点；标题用 `**加粗**` 与正文拉开，次要信息用 grey
+- [ ] **P2 分组**：同主题字段收进同一容器，不同主题分容器；**没有「一路 hr 平铺」或多主题挤在同一 markdown**
+- [ ] **P3 复杂度适中**：视觉块 **2–5** 个、主色系 ≤3；且 >1 个块、至少含一个非纯文本结构元素（背景块/指标卡/图标/表格）——**既不能纯文字流水账，也不能堆砌过载**
+
+**基础卫生（应满足）：**
+- [ ] **P4 对比**：标题与正文在字号或粗细上至少差一档；正文不滥用 `#/##/###`（指标卡数值放大除外）
+- [ ] **P5 对齐**：不滥用散设 `margin`，间距优先交容器；间距取值种类 ≤4；非末尾顶级容器间距一致
+
+**加分项（尽量满足）：**
+- [ ] **P6 语义一致**：同色同义（红=降/警、绿=升/成、grey=次要）；主色系起始色与 header 一致、取邻近色环
+- [ ] **P7 健壮**：并列/指标列默认 `weighted`/`none`、慎用 `stretch`；必要时配 `config.style.color` light/dark
+
+---
+
+## Step 4：发送卡片
+
+```bash
+# 发送到群聊
+lark-cli im +messages-send --chat-id oc_xxx --msg-type interactive --content '<card_json>'
+
+# 发送给指定用户（私聊）
+lark-cli im +messages-send --user-id ou_xxx --msg-type interactive --content '<card_json>'
+```
+
+**发送失败时**：先对照下方常见失败列表排查，若能匹配则按对应处理方式修复后重新发送；否则根据错误信息修复 JSON 后重新发送。最多尝试 **3 次**。若 3 次后仍失败，**降级为 Card 1.0 卡片**重新构造并发送。**不参考之前发送 2.0 的记忆**，完全根据用户意图重新构造 1.0 卡片。1.0 无本地参考文档（components/、resource/ 均为 2.0）。
+**常见失败列表**
+
+| # | 错误信息 | 处理方式 |
+|---|---|---|
+| 1 | `there is an invalid user resource (at/person) in your card` | 卡片中含有 at/person 组件，但使用了无效的用户 ID。询问用户其真实的 open_id / user_id，替换后重新发送。 |
+
+---
+
+## Step 5：交互回调（可选）
+
+若卡片含**会回调服务端的交互组件**，则**支持**监听 `card.action.trigger` 回调（是否监听由实际需求决定，非必须）：
+
+**需显式配置 `behaviors: [{type:"callback"}]` 才会回调：**
+- `button`（带 callback behavior）
+- `checker` —— 未配置 behaviors 时仅本地勾选生效，不触发服务端回调
+- `interactive_container` —— behaviors 为必填，支持 callback / open_url
+
+**选中 / 输入即默认回调，无需显式 `behaviors`：**
+- `select_static` / `multi_select_static` / `select_person` / `multi_select_person`
+- `overflow` / `input` / `date_picker` / `picker_time` / `picker_datetime`
+
+**form 提交统一回调（按钮用 `form_action_type: "submit"`，无需 behaviors）：**
+- form 内所有表单组件的值通过 `action.form_value` 一次性回传
+
+> 纯 `open_url` 跳转按钮在客户端本地跳转，不回调服务端。
+
+如需处理回调（监听事件、读取字段、更新卡片），见 `../lark-im-card-action-reply.md`。
+
+---
+
+## Step 6：用户反馈修正（按需进入）
+
+用户看到已发送卡片后提出修改意见时，遵循以下流程。**不要整卡重做，外科手术式修改。**
+
+### 1. 定位改动范围
+
+把用户意见逐条映射到具体组件和字段：
+
+| 用户反馈类型 | 映射目标 |
+|---|---|
+| 文案/措辞不满意 | 对应 `markdown.content` / `button.text` / `header.title` |
+| 颜色/风格不满意 | 对应 `background_style` / `font_color` / `header.template` / config color token |
+| 布局/排列不满意 | 对应 `column_set.flex_mode` / `width` / `weight` / `padding` |
+| 缺少某个字段/信息 | 新增 `div.fields` 条目或 `markdown` 行 |
+| 某个块太拥挤/太空 | 调整 `padding` / `vertical_spacing` / `margin` |
+| 交互行为问题 | 对应 `behaviors` / `confirm` / `disabled` |
+
+### 2. 最小改动原则
+
+- 只改被指出的组件，不动周边结构。
+- 改完后**只对被修改组件所涉及的 P 项重新自检**（改颜色 → 过 P6；改分组 → 过 P1+P2；改间距 → 过 P5）。
+
+### 3. 重发
+
+修正完成后，重新发送一张新卡（同 Step 4），告知用户"已重新发送修正版"。
+
+### 4. 执行前告知
+
+向用户复述"我将修改 ×××"，确认后再执行，不要静默改动。
+
+---
+
+## 执行清单
+
+- [ ] 入口：判断是文字诉求（→ Step 1）还是图片输入（→ 图片分支 → 判断类型→保真策略→组件映射）
+- [ ] Step 1：分析意图，输出设计方案（版本 / 宽度模式 / 颜色 / 组件）
+- [ ] Step 2：读 schema.md + 组件明细 + 「好看的标准 P0–P7」
+- [ ] Step 3：构造 JSON → 过 P0–P7 硬 Gate（P0+P1–P3 阻断），不过先修
+- [ ] Step 4：发送，失败按常见失败表排查重试（≤3 次）；仍失败则降级 Card 1.0 重构发送
+- [ ] Step 5：若有交互，参考 ../lark-im-card-action-reply.md
+- [ ] Step 6：用户提出修改意见时，定位组件→最小改动→原地更新或重发