181 lines
11 KiB
Markdown
181 lines
11 KiB
Markdown
# 发送 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：用户提出修改意见时，定位组件→最小改动→原地更新或重发
|