@amaster.ai/pi-lark 0.1.4 → 0.1.6

package/skills/lark-im/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: lark-im
+version: 1.0.0
+description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli im --help"
+---
+
+# im (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## Core Concepts
+
+- **Message**: A single message in a chat, identified by `message_id` (om_xxx). Supports types: text, post, image, file, audio, video, sticker, interactive (card), share_chat, share_user, merge_forward, etc.
+- **Chat**: A group chat or P2P conversation, identified by `chat_id` (oc_xxx).
+- **Thread**: A reply thread under a message, identified by `thread_id` (om_xxx or omt_xxx).
+- **Reaction**: An emoji reaction on a message.
+- **Flag**: A bookmark on a message or thread.
+- **Feed Shortcut**: A chat pinned to the current user's feed sidebar, identified by `feed_card_id` (an `oc_xxx` open_chat_id for CHAT type).
+- **Feed Group**: A tag that groups feed cards in the feed list, identified by `feed_group_id` (ofg_xxx). Members are feed cards, each identified by `feed_id` + `feed_type`. Two types: `normal` (members managed explicitly) and `rule` (members auto-derived from rules).
+
+## Resource Relationships
+
+```
+Chat (oc_xxx)
+├── Message (om_xxx)
+│   ├── Thread (reply thread)
+│   ├── Reaction (emoji)
+│   └── Resource (image / file / video / audio)
+└── Member (user / bot)
+```
+
+## Important Notes
+
+### Identity and Token Mapping
+
+- `--as user` means **user identity** and uses `user_access_token`. Calls run as the authorized end user, so permissions depend on both the app scopes and that user's own access to the target chat/message/resource.
+- `--as bot` means **bot identity** and uses `tenant_access_token`. Calls run as the app bot, so behavior depends on the bot's membership, app visibility, availability range, and bot-specific scopes.
+- If an IM API says it supports both `user` and `bot`, the token type changes who the operator is. The same API can succeed with one identity and fail with the other because owner/admin status, chat membership, tenant boundary, or app availability are checked against the current caller.
+
+### Sender Name Resolution
+
+When fetching messages (`+chat-messages-list`, `+threads-messages-list`, `+messages-mget`, `+messages-search`), the CLI shows a display name for both user and bot senders:
+
+- **Server-provided name**: the read APIs return `sender_name` (plus the full-i18n `sender_i18n_names` map) on each message `sender`; the CLI surfaces it as the sender's `name` for users and bots alike. No name lookup and no extra permission are needed — **no contact scope** and no `application:bot.basic_info:read`.
+- **Fallback to id**: when the server does not provide a name, the sender is shown by its id and the command still exits 0. There is no contact-directory fallback.
+
+The raw `sender_name` is not duplicated in output (its value is in `name`); the full `sender_i18n_names` map (all locales) is preserved for consumers that need a specific language, alongside an optional `open_bot_id` (`ou_`) for bot senders aligned with the message-receive event channel. System messages (`msg_type: system`) have no sender name — that is normal, not an error.
+
+### Default message enrichment (reactions / update_time)
+
+The four message-pulling shortcuts (`+messages-mget`, `+chat-messages-list`, `+messages-search`, `+threads-messages-list`) automatically attach a `reactions` block and (for edited messages) `update_time` to each returned message — no separate `im.reactions.batch_query` call is needed. Pass `--no-reactions` to opt out. For the full contract (output shape, the `im:message.reactions:read` scope requirement, and the "missing field ≠ fetch failure" data rules), read [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
+
+### Opt-in resource auto-download (`--download-resources`)
+
+`+chat-messages-list`, `+messages-mget`, and `+threads-messages-list` accept `--download-resources` (**off by default** — no `resources` block and no extra requests when omitted). When set, eligible message resources (image/file/audio/video/media + post-embedded; **stickers excluded**) are downloaded into `./lark-im-resources/` and each message gains a `resources` array of `{message_id, key, type, local_path, size_bytes}`. Downloads are deduped by `(message_id, file_key)`, run with bounded concurrency, and isolate single-resource failures (`error: true` + stderr warning). **Scope:** requires `im:message:readonly` (already declared by the listing commands — no extra scope); works under both user and bot identity. For one-off downloads use [`+messages-resources-download`](references/lark-im-messages-resources-download.md). Full contract: [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
+
+### Card Messages (Interactive)
+
+**Before sending or replying with any `interactive` card (`+messages-send` / `+messages-reply`), you MUST read [`references/card/lark-im-card-create.md`](references/card/lark-im-card-create.md) and follow its workflow.** The card JSON passed to `--msg-type interactive --content` must be the output of that workflow — never hand-write or copy a card payload.
+
+Card messages (`interactive` type) are not yet supported for compact conversion in event subscriptions. The raw event data will be returned instead, with a hint printed to stderr.
+
+`interactive` cards support callback events (`card.action.trigger`) — see [`references/lark-im-card-action-reply.md`](references/lark-im-card-action-reply.md).
+
+### Audio Messages
+
+`--audio` sends a voice message and supports only Opus audio files, for example `.opus` files or Ogg Opus (`.ogg`) files. For `mp3`, `wav`, or other non-Opus audio, either convert to `.opus` first and keep using `--audio`, or send the original file as an attachment with `--file`.
+
+### Sending Doc Content as a Message
+
+When sending content fetched from a Lark doc as a message, fetch the doc with --doc-format im-markdown, then send it as a message using the --markdown format. The fetched content is already in markdown; in any content-forwarding scenario, keep the fetched original text and send it in the --markdown format. Note: if the doc contains a cite tag with type="user", keep it as-is and do not strip the tag.
+
+### Flag Types
+
+Flags support two layers:
+
+- **Message-layer flag**: `(ItemTypeDefault, FlagTypeMessage)` — regular message bookmark
+- **Feed-layer flag**: `(ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed)` — thread as feed-layer bookmark
+
+Item types for feed-layer flags:
+- **ItemTypeThread** (4) = thread in a topic-style chat
+- **ItemTypeMsgThread** (11) = thread in a regular chat
+
+### Feed Shortcut
+
+Feed shortcuts add chats to the current user's feed sidebar. They are distinct from flags:
+
+- **Flag** = bookmark on a message/thread, scoped to the user's bookmark list.
+- **Feed shortcut** = entry in the user's feed sidebar (currently only chats).
+
+Key limits:
+- Only **CHAT-type** (`feed_card_id` is `oc_xxx`) is exposed via OpenAPI; doc/app/subscription shortcuts exist internally but are not yet whitelisted.
+- All three operations (create/remove/list) are **user-identity only** — they sign with `user_access_token`.
+- Batch size is **10 per call** for create/remove; list is a one-page wrapper with opaque `page_token` pagination.
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+chat-create`](references/lark-im-chat-create.md) | Create a group chat or topic chat; user/bot; --chat-mode group|topic; private/public; invites users/bots; optionally sets bot manager |
+| [`+chat-list`](references/lark-im-chat-list.md) | List chats the current user/bot is a member of; defaults to groups; pass --types=p2p,group to include p2p single chats (user-only); user/bot; supports sorting, pagination, --exclude-muted (user-only) |
+| [`+chat-members-list`](references/lark-im-chat-members-list.md) | List members of a chat; returns separate users[] / bots[] buckets; callable as user or bot; --member-types filters which kinds to return; --page-all pagination; surfaces truncations[] when the server caps a bucket |
+| [`+chat-messages-list`](references/lark-im-chat-messages-list.md) | List messages in a chat or P2P conversation; user/bot; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range/sort/pagination |
+| [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by --query keyword and/or --member-ids; user/bot; e.g. look up chat_id by group name; supports type filters, sorting, pagination, and --exclude-muted (user identity only) |
+| [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |
+| [`+messages-mget`](references/lark-im-messages-mget.md) | Batch get messages by IDs; user/bot; fetches up to 50 om_ message IDs, formats sender names, expands thread replies |
+| [`+messages-reply`](references/lark-im-messages-reply.md) | Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
+| [`+messages-resources-download`](references/lark-im-messages-resources-download.md) | Download images/files from a message; user/bot; supports automatic chunked download for large files (8MB chunks), auto-detects file extension from Content-Type |
+| [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
+| [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
+| [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |
+| [`+flag-create`](references/lark-im-flag-create.md) | Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed for feed-layer flag (item_type auto-detected from chat mode) |
+| [`+flag-cancel`](references/lark-im-flag-cancel.md) | Cancel (remove) a bookmark. When no --flag-type is given, best-effort double-cancel: removes message layer and (when chat_type is determinable) feed layer |
+| [`+flag-list`](references/lark-im-flag-list.md) | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination |
+| [`+feed-shortcut-create`](references/lark-im-feed-shortcut-create.md) | Add chats to the user's feed shortcuts; user-only; oc_xxx chat IDs only; batch up to 10 per call; `--head`/`--tail` controls insertion order; partial failures return an `ok:false` ledger |
+| [`+feed-shortcut-remove`](references/lark-im-feed-shortcut-remove.md) | Remove chats from the user's feed shortcuts; user-only; batch up to 10 per call; removing an absent shortcut is idempotent success; real per-item failures return an `ok:false` ledger |
+| [`+feed-shortcut-list`](references/lark-im-feed-shortcut-list.md) | List one page of the user's feed shortcuts; user-only; omit `--page-token` for the first page; default output enriches CHAT entries under `detail`; pass `--no-detail` to skip the extra lookup and `im:chat:read` scope |
+| [`+feed-group-list`](references/lark-im-feed-group-list.md) | List the caller's feed groups (tags); user-only; supports `--page-all` auto-pagination |
+| [`+feed-group-list-item`](references/lark-im-feed-group-list-item.md) | List feed cards in a feed group (tag); user-only; enriches each item with chat_name resolved from feed_id; supports --page-all auto-pagination |
+| [`+feed-group-query-item`](references/lark-im-feed-group-query-item.md) | Look up specific feed cards in a feed group (tag) by ID; user-only; enriches each item with chat_name resolved from feed_id |
+
+## API Resources
+
+```bash
+lark-cli schema im.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli im <resource> <method> [flags] # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### chats
+
+  - `create` — 创建群。Identity: `bot` only (`tenant_access_token`).
+  - `get` — 获取群信息。Identity: supports `user` and `bot`; the caller must be in the target chat to get full details, and must belong to the same tenant for internal chats.
+  - `link` — 获取群分享链接。Identity: supports `user` and `bot`; the caller must be in the target chat, must be an owner or admin when chat sharing is restricted to owners/admins, and must belong to the same tenant for internal chats.
+  - `update` — 更新群信息。Identity: supports `user` and `bot`.
+
+### chat.members
+
+  - `create` — 将用户或机器人拉入群聊。Identity: supports `user` and `bot`; the caller must be in the target chat; for `bot` calls, added users must be within the app's availability; for internal chats the operator must belong to the same tenant; if only owners/admins can add members, the caller must be an owner/admin, or a chat-creator bot with `im:chat:operate_as_owner`.
+  - `delete` — 将用户或机器人移出群聊。Identity: supports `user` and `bot`; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.
+
+### chat.user_setting
+
+  - `batch_query` — 批量查询当前用户在群内的个人偏好设置 (e.g. `is_muted` mutes normal messages, `is_mute_at_all` mutes @all messages); up to 10 chats per request. Identity: `user` only (`user_access_token`); the caller must be in each target chat.
+  - `batch_update` — 批量更新当前用户在群内的个人偏好设置 (e.g. `is_muted` mutes normal messages, `is_mute_at_all` mutes @all messages); up to 10 chats per request. Identity: `user` only (`user_access_token`); the caller must be in each target chat.
+
+### chat.nickname
+
+  - `get` — 获取自己的群昵称。Get your own nickname in the chat (self-only). Identity: `user` only (`user_access_token`); returns an empty string when no nickname is set.
+  - `update` — 设置自己的群昵称。Set or update your own nickname in the chat (self-only). Identity: `user` only (`user_access_token`); `nickname` must be a non-empty string (max 300 bytes). Use DELETE to clear it.
+  - `delete` — 清空自己的群昵称。Clear your own nickname in the chat (self-only). Identity: `user` only (`user_access_token`).
+
+### chat.managers
+
+  - `add_managers` — 指定群管理员。Identity: supports `user` and `bot`; only the group owner can add managers; max 10 managers per chat (20 for super-large chats), and at most 5 bots per request.
+  - `delete_managers` — 删除群管理员。Identity: supports `user` and `bot`; only the group owner can remove managers; max 50 users or 5 bots per request.
+
+### chat.moderation
+
+  - `get` — 获取群成员发言权限。Identity: supports `user` and `bot`; the caller must be in the target chat and belong to the same tenant.
+  - `update` — 更新群发言权限。Identity: supports `user` and `bot`; only the group owner (or creator bot with `im:chat:operate_as_owner`) can update; the caller must be in the chat.
+
+### messages
+
+  - `delete` — 撤回消息。Identity: supports `user` and `bot`; for `bot` calls, the bot must be in the chat to revoke group messages; to revoke another user's group message, the bot must be the owner, an admin, or the creator; for user P2P recalls, the target user must be within the bot's availability.
+  - `forward` — 转发消息。Identity: supports `user` and `bot`.
+  - `merge_forward` — 合并转发消息。Identity: `bot` only (`tenant_access_token`).
+  - `read_users` — 查询消息已读信息。Identity: `bot` only (`tenant_access_token`); the bot must be in the chat, and can only query read status for messages it sent within the last 7 days.
+  - `urgent_app` — 发送应用内加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
+  - `urgent_phone` — 发送电话加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
+  - `urgent_sms` — 发送短信加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
+
+### reactions
+
+  - `batch_query` — 批量获取消息表情。Identity: supports `user` and `bot`.[Must-read](references/lark-im-reactions.md)
+  - `create` — 添加消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
+  - `delete` — 删除消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message, and can only delete reactions added by itself.[Must-read](references/lark-im-reactions.md)
+  - `list` — 获取消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
+
+### threads
+
+  - `forward` — 转发话题。Identity: supports `user` and `bot`.
+
+### images
+
+  - `create` — 上传图片。Identity: `bot` only (`tenant_access_token`).
+
+### pins
+
+  - `create` — Pin 消息。Identity: supports `user` and `bot`.
+  - `delete` — 移除 Pin 消息。Identity: supports `user` and `bot`.
+  - `list` — 获取群内 Pin 消息。Identity: supports `user` and `bot`.
+
+### feed.groups
+
+  - `batch_add_item` — Batch add feed cards to a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
+  - `batch_query` — Batch query feed groups. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
+  - `batch_remove_item` — Batch remove feed cards from a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
+  - `create` — Create a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
+  - `delete` — Delete a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
+  - `update` — Update a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `chats.create` | `im:chat:create` |
+| `chats.get` | `im:chat:read` |
+| `chats.link` | `im:chat:read` |
+| `chats.update` | `im:chat:update` |
+| `chat.members.create` | `im:chat.members:write_only` |
+| `chat.members.delete` | `im:chat.members:write_only` |
+| `chat.members.get` | `im:chat.members:read` |
+| `+chat-members-list` | `im:chat.members:read` |
+| `chat.user_setting.batch_query` | `im:chat.user_setting:read` |
+| `chat.user_setting.batch_update` | `im:chat.user_setting:write` |
+| `chat.managers.add_managers` | `im:chat.managers:write_only` |
+| `chat.managers.delete_managers` | `im:chat.managers:write_only` |
+| `chat.moderation.get` | `im:chat.moderation:read` |
+| `chat.moderation.update` | `im:chat:moderation:write_only` |
+| `messages.delete` | `im:message:recall` |
+| `messages.forward` | `im:message` |
+| `messages.merge_forward` | `im:message` |
+| `messages.read_users` | `im:message:readonly` |
+| `messages.urgent_app` | `im:message.urgent` |
+| `messages.urgent_phone` | `im:message.urgent:phone` |
+| `messages.urgent_sms` | `im:message.urgent:sms` |
+| `reactions.batch_query` | `im:message.reactions:read` |
+| `reactions.create` | `im:message.reactions:write_only` |
+| `reactions.delete` | `im:message.reactions:write_only` |
+| `reactions.list` | `im:message.reactions:read` |
+| `threads.forward` | `im:message` |
+| `images.create` | `im:resource` |
+| `pins.create` | `im:message.pins:write_only` |
+| `pins.delete` | `im:message.pins:write_only` |
+| `pins.list` | `im:message.pins:read` |
+| `feed.groups.batch_add_item` | `im:feed_group_v1:write` |
+| `feed.groups.batch_query` | `im:feed_group_v1:read` |
+| `feed.groups.batch_remove_item` | `im:feed_group_v1:write` |
+| `feed.groups.create` | `im:feed_group_v1:write` |
+| `feed.groups.delete` | `im:feed_group_v1:write` |
+| `feed.groups.update` | `im:feed_group_v1:write` |

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 层，过深会压缩展示空间。