@amaster.ai/pi-lark 0.1.9 → 0.1.11

package/skills/lark-calendar/references/lark-calendar-join-event.md

@@ -0,0 +1,43 @@
+# calendar +join-event
+
+凭**分享 token** 加入日程。
+
+## 命令
+
+```bash
+# 用户以自身身份加入（默认场景）
+lark-cli calendar +join-event --token <token> --as user
+
+# 以应用身份加入
+lark-cli calendar +join-event --token <token> --as bot
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token <token>` | **是** | 分享 token，加入的唯一入参（别名 `--share-token`）。|
+
+## token 从哪来
+
+| token 类型 | 承载来源 | 取值 |
+|-----------|---------|------|
+| 链接类 | 分享链接 / 二维码 | 链接 `{{domain}}/calendar/share?token=<token>` 里的 `token` |
+| 卡片类 | 分享卡片 / RSVP 卡片 | 从 IM 日程分享卡片或 RSVP 卡片消息解析出的日程分享 token |
+
+- **分享链接**：直接取 URL query 里的 `token` 值传入；无需解析日程字段。例如 `{{domain}}/calendar/share?token=29f762bdmsbd82ce9` → `--token 29f762bdmsbd82ce9`。
+- **二维码**：先用 OCR/扫码解析成分享链接，再取其中的 `token`——CLI 不承接二维码图像，只承接解析后的链接 token。
+- **卡片**：token 落在卡片消息 content（分享卡片 `SHARE_CALENDAR_EVENT`、RSVP 卡片 `GENERAL_CALENDER`）；RSVP 卡片被转发后退化为分享卡片，同样可加入。
+
+## 重复性日程
+
+加入范围取决于 token 反解出的日程本体是「原重复性日程」还是「例外」（参见 [lark-calendar-recurring](lark-calendar-recurring.md) 的关键概念）：
+
+- 分享的是**原重复性日程**（`{event_uid}_0`）：加入的是**整个序列**（含例外）。
+- 分享的是某个**例外**（`originalTime > 0` 的单次实例）：只加入这**一个例外日程**。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) -- skill 入口与路由
+- [lark-calendar-rsvp](lark-calendar-rsvp.md) -- 已在日程中时回复接受/拒绝/待定（≠ 加入）
+- [lark-calendar-recurring](lark-calendar-recurring.md) -- 重复性日程的序列 vs 实例操作规范

package/skills/lark-calendar/references/lark-calendar-transfer.md

@@ -0,0 +1,89 @@
+# calendar +transfer
+
+把一个日程的**组织者（organizer）**转让给另一个用户或机器人。用户和机器人之间可以任意互转。
+
+## 命令
+
+```bash
+# 转让给某人（原组织者保留为参与人）
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --yes
+
+# 转让并把原组织者从参与人中移除
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --remove-original-organizer --yes
+
+# 指定日历
+lark-cli calendar +transfer --calendar-id <calendar_id> --event-id <event_id> --to-user-id ou_xxx --yes
+
+# 重复性日程：必须显式确认整个序列一起转让
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --transfer-series --yes
+
+# 预览请求，不实际执行
+lark-cli calendar +transfer --event-id <event_id> --to-user-id ou_xxx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--event-id <id>` | **是** | 日程 ID（`uid_originalTime` 形式） |
+| `--to-user-id <ou_...>` | **是** | 接收人 open_id，成为新组织者；用户和机器人都可以 |
+| `--calendar-id <id>` | 否 | 日程所在日历 ID（省略则使用主日历） |
+| `--remove-original-organizer` | 否 | 转让后把原组织者移出参与人；默认保留。日程在共享日历上时服务端一定会移除 |
+| `--transfer-series` | 否 | 确认整个重复性序列一起转让；重复性日程必填 |
+| `--yes` | **是**（非 dry-run） | 高敏写操作确认 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 转让方向
+
+转出方和接收方是两个**互相独立**的参数，四种组合都支持：
+
+- **转出方**由 `--as` 决定，必须是日程**当前组织者**的身份。bot 组织的日程用 `--as bot`，用户自己的日程用 `--as user`。用非组织者身份调用会返回 403。
+- **接收方**由 `--to-user-id` 决定，传谁的 open_id 就转给谁，是人还是机器人不影响命令写法。
+
+| 方向 | 命令 |
+|------|------|
+| user → user | `--as user --to-user-id <对方用户 open_id>` |
+| user → bot | `--as user --to-user-id <bot 的 open_id>` |
+| bot → user | `--as bot --to-user-id <用户 open_id>` |
+| bot → bot | `--as bot --to-user-id <另一个 bot 的 open_id>` |
+
+**取接收人 open_id**：
+
+```bash
+# 用户
+lark-cli contact +search-user --query <姓名> --as user
+# 机器人：从它所在群的成员列表里取 bots[] 中的 open_id
+lark-cli im +chat-members-list --chat-id <chat_id> --member-types bot
+```
+
+机器人的 open_id 同样是 `ou_` 开头；不要传 `cli_` 开头的 app_id，那是应用 ID，不是日程参与人身份。
+
+无论哪个方向，转让都要求转出方和接收方**同租户**，且接收方能通过高管模式的协作校验。
+
+## 重复性日程
+
+后端按 `uid` 定位日程，忽略 `original_time`，**无法只转让某一次实例**。因此传入任何一个实例或例外的 `event_id`，都会把整个序列（含所有例外）一起转让。
+
+是重复性日程且未加 `--transfer-series` 时命令直接失败（`failed_precondition`），不会发出转让请求。收到这个错误时**先向用户确认"整个重复日程都转让"**，得到确认后再带 `--transfer-series` 重跑；不要自动重试。已确认时加 `--transfer-series` 会跳过这次预读。
+
+## 返回中的 `original_organizer_removed`
+
+**共享日历不属于任何组织者，转让时服务端会强制把原组织者移出日程；主日历则会把原组织者保留为参与人。** 转让接口成功时不返回这个结果，所以命令只在能确定时才输出该字段：
+
+| 情况 | 返回 |
+|------|------|
+| 带 `--remove-original-organizer` | `original_organizer_removed: true` |
+| 省略 `--calendar-id`（主日历） | `original_organizer_removed: false` |
+| 传了 `--calendar-id` 且未传 `--remove-original-organizer` | **不返回该字段**，stderr 给一条 note 说明共享日历会强制移除 |
+
+字段缺失时**不要**告诉用户"原组织者已保留为参与人"，也不要断言已被移除。需要确认就转让后读一次日程看参与人，或一开始就显式传 `--remove-original-organizer`。
+
+## 提示
+
+- 转让不可逆，且会连同日程上的会议纪要、笔记和附件一起移交给新组织者。
+- 需要 `calendar:calendar.event:transfer` 权限；转让前的重复性预读需要 `calendar:calendar.event:read`（带 `--transfer-series` 时不读）。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) -- skill 入口与路由
+- [重复性日程操作规范](lark-calendar-recurring.md)

package/skills/lark-doc/references/lark-doc-fetch.md

@@ -127,7 +127,7 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
 |`<whiteboard>`|提取 `token`，使用 `docs +media-download`|
 |`<sheet>`、`<cite file-type="sheets">`|提取 `token` 和 `sheet-id`，转到 [`lark-sheets`](../../lark-sheets/SKILL.md)|
 |`<bitable>`、`<cite file-type="bitable">`|提取 `token` 和 `table-id`，转到 [`lark-base`](../../lark-base/SKILL.md)|
-|`<vc-transcribe-tab>`|提取 `vc-node-id`，使用 [`lark-note`](../../lark-note/SKILL.md) 的 `note +detail`|
+|`<vc-transcribe-tab>`|提取 `vc-node-id`，使用 [`lark-meeting`](../../lark-meeting/SKILL.md) 的 `note +detail`|
 |`<synced_reference>`|提取 `src-token` 和 `src-block-id`，读取源文档并定位 block|
 
 ## 参考

package/skills/lark-drive/references/lark-drive-add-comment.md

@@ -165,10 +165,10 @@ lark-cli drive +add-comment \
 - 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终可解析为 `doc`/`docx`/`file` 的 wiki URL。
 - **Drive file 评论**：仅支持白名单扩展名的普通文件。当前支持：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。
 - **Drive file 暂不支持**：`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件会被 CLI 拒绝，并提示“当前还不支持这种类型的评论”。这些类型虽然可能接受 OpenAPI 请求，但在页面评论展示上存在问题。
-- **Drive file 只支持全文评论**：file 目标不支持局部评论，不允许传 `--block-id` 或 `--selection-with-ellipsis`。
+- **Drive file 只支持全文评论**：file 目标不支持局部评论，不允许传 `--block-id`。
 - 传 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式支持 `docx`、`sheet`、`slides`、Base / bitable，以及最终可解析为这些类型的 wiki URL。
 - **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "<sheetId>!<cell>"` 指定单元格（如 `a281f9!D6`）；sheet 没有全文评论，`--full-comment` 不可用。
-- **Slide 评论**：当 `--doc` 为 slides URL、`--type slides`，或 wiki 解析为 slides 时，必须传 `--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>"`。此时 `--full-comment` 和 `--selection-with-ellipsis` 不可用。
+- **Slide 评论**：当 `--doc` 为 slides URL、`--type slides`，或 wiki 解析为 slides 时，必须传 `--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>"`。此时 `--full-comment` 不可用。
 - **Base 记录局部评论**：Base 不支持全局评论，所有评论都挂在记录上；裸 token 可传 `--type bitable` 或 `--type base`，推荐 `bitable`。定位信息必须是 file token（base token）+ `--block-id "<table-id>!<record-id>!<view-id>"`，其中 table/record/view ID 通常分别以 `tbl`/`rec`/`vew` 开头；view_id 只决定被提及时点击通知打开哪个视图，不影响评论挂载点，但必须传。ID 获取参考 [`lark-base`](../../lark-base/SKILL.md)。
 - **Slide 参数映射示例**：`--block-id` 由 PPT XML 元素类型和元素 `id` 组成。例如：
     - `<slide id="pkk">` 对应 `--block-id slide!pkk`，表示给整页评论。

package/skills/lark-drive/references/lark-drive-member-remove.md

@@ -20,7 +20,7 @@ lark-cli drive +member-remove \
 | `--token` | 是 | 裸 token 或完整 URL。路径支持 `/drive/folder/`、`/docx/`、`/doc/`、`/sheets/`、`/base/`、`/bitable/`、`/wiki/`、`/file/`、`/mindnotes/`、`/slides/`、`/minutes/`、`/page/`；URL 可从路径推断类型，裸 token 必须同时传 `--type`。 |
 | `--type` | 条件必填 | 资源类型：`docx` / `doc` / `sheet` / `bitable` / `file` / `folder` / `wiki` / `mindnote` / `slides` / `minutes` / `apps`。完整 URL 可省略。 |
 | `--member-id` | 是 | 要移除的单个协作者 ID。逗号分隔的多成员输入会被拒绝；批量场景应逐个调用。 |
-| `--member-type` | 是 | ID 类型：`email` / `openid` / `openchat` / `opendepartmentid` / `userid` / `unionid` / `groupid` / `wikispaceid`。 |
+| `--member-type` | 是 | ID 类型：`email` / `openid` / `openchat` / `opendepartmentid` / `userid` / `unionid` / `groupid` / `appid` / `wikispaceid`。 |
 | `--member-kind` | 条件必填 | 仅 `--member-type=wikispaceid` 使用：未启用知识库成员分组时传 `wiki_space_member`，启用后根据权限传 `wiki_space_viewer` 或 `wiki_space_editor`。 |
 | `--perm-type` | 否 | 仅 wiki 协作者使用：`container`（默认，当前页面及子页面）或 `single_page`（仅当前页面）。 |
 | `--dry-run` | 否 | 只预览 DELETE URL、query 和 body，不调用接口。 |
@@ -52,6 +52,7 @@ Wiki 普通协作者还会返回 `perm_type`；`wikispaceid` 返回所传的 `me
 ## 行为说明
 
 - **身份支持**：支持 `--as user` 和 `--as bot`。
+- **应用协作者**：使用 `--member-type=appid`，`--member-id` 传应用 ID（通常为 `cli_xxx`）。
 - **部门协作者**：`--member-type=opendepartmentid` 只能配合 `--as user`；bot 身份会在客户端提前拒绝。
 - **安全编码**：资源 token 和 member ID 都作为独立 path segment 编码。
 - **Wiki 范围**：普通 wiki 协作者默认删除 `container` 权限；只删除当前页面权限时显式传 `single_page`。

package/skills/lark-im/SKILL.md

@@ -35,6 +35,10 @@ Chat (oc_xxx)
 
 ## Important Notes
 
+### AppLink and Share Links
+
+Prefer CLI-returned links: use `chat_app_link` to open joined conversations, `message_app_link` to open messages, and `share_link` to invite others to groups. If manually building a joined-conversation AppLink, use `https://<applink_host>/client/chat/open?openChatId=<oc_xxx>`, never `chatId=<oc_xxx>` or `lark://...chat_id=<oc_xxx>`.
+
 ### 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.
@@ -60,7 +64,7 @@ The four message-pulling shortcuts (`+messages-mget`, `+chat-messages-list`, `+m
 
 ### 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.
+**Before sending, replying with, or updating any `interactive` card (`+messages-send` / `+messages-reply` / `messages.patch`), 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` (send/reply) or `messages.patch --data` (update) 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.
 
@@ -109,7 +113,10 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+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, --order asc/desc sorting, auto-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, auto-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 |
+| [`+message-read-users`](references/lark-im-message-read-status.md) | List users who read one message; user/bot; identity-specific scopes; supports bounded auto-pagination |
+| [`+messages-edit`](references/lark-im-messages-edit.md) | Edit a message's content (text/post, including the attachment zone); bot-only (user identity is rejected by the server); PUT /open-apis/im/v1/messages/:message_id |
 | [`+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-read-status`](references/lark-im-message-read-status.md) | Batch query whether the current user read 1–50 messages; user-only; returns readable items and invalid message IDs |
 | [`+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 an image or file attached to a message; user/bot |
 | [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user or bot identity; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
@@ -157,6 +164,11 @@ lark-cli im <resource> <method> [flags] # 调用 API
   - `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.join_requests
+
+  - `list` — 列出群的待审批入群申请（仅群主/管理员，user_access_token）。List pending join requests for a chat. Identity: `user` only (`user_access_token`); the caller must be the chat owner or an admin. Paginated (`page_size` 1-100); stop on `has_more == false` — `page_token` is returned even on the last page, so paging while it is present never terminates.
+  - `handle` — 批量审批入群申请（approve/reject，仅群主/管理员，user_access_token）。Approve or reject pending join requests in bulk (1-50 items, processed in order). Identity: `user` only (`user_access_token`); the caller must be the chat owner or an admin. `results[]` mirrors `items[]` in count and order — check each `result` (`success` / `failed` / `already_handled`); exit 0 does not mean every item succeeded.
+
 ### 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.
@@ -169,10 +181,12 @@ lark-cli im <resource> <method> [flags] # 调用 API
 
 ### messages
 
+  - `read_status` — 批量查询当前用户对消息的已读状态。Identity: `user` only (`user_access_token`); accepts up to 50 message IDs and returns readable items plus invalid message IDs.[Must-read](references/lark-im-message-read-status.md)
   - `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.
+  - `read_users` — 查询消息已读信息。Identity: supports `user` and `bot`; the caller must still be in the chat. A user can query messages they sent within the last 7 days, while a bot can query only messages sent by that bot within the last 7 days.[Must-read](references/lark-im-message-read-status.md)
+  - `patch` — 更新已发送的消息卡片。Update an interactive message card sent by the app. Identity: supports `user` and `bot`; the message must have been sent within the last 14 days, and `content` must be a JSON-serialized string no larger than 30 KB.[Must-read](references/card/lark-im-card-create.md)
   - `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.
@@ -229,10 +243,16 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `chat.managers.delete_managers` | `im:chat.managers:write_only` |
 | `chat.moderation.get` | `im:chat.moderation:read` |
 | `chat.moderation.update` | `im:chat:moderation:write_only` |
+| `chat.join_requests.list` | `im:chat.membership_application:read` |
+| `chat.join_requests.handle` | `im:chat.membership_application:write` |
+| `+messages-read-status` | user: `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
+| `+message-read-users` | user: `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user`; bot: `im:message:readonly` |
+| `messages.read_status` | `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
 | `messages.delete` | `im:message:recall` |
 | `messages.forward` | `im:message` |
 | `messages.merge_forward` | `im:message` |
-| `messages.read_users` | `im:message:readonly` |
+| `messages.read_users` | user: `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user`; bot: `im:message:readonly` |
+| `messages.patch` | `im:message:update` |
 | `messages.urgent_app` | `im:message.urgent` |
 | `messages.urgent_phone` | `im:message.urgent:phone` |
 | `messages.urgent_sms` | `im:message.urgent:sms` |

package/skills/lark-im/references/lark-im-message-read-status.md

@@ -0,0 +1,96 @@
+# IM message read status
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first for authentication and global parameters.
+
+Use two focused shortcuts for message read-status queries:
+
+- `im +messages-read-status` queries whether the current user has read 1–50 messages.
+- `im +message-read-users` lists users who have read one message and supports automatic pagination.
+
+Both underlying OpenAPIs support user identity through a user access token (UAT). `+message-read-users` additionally supports bot identity through a tenant access token (TAT).
+
+## Identity and scopes
+
+| Shortcut | Identity | Scope |
+|---|---|---|
+| `+messages-read-status` | user only | `im:message:readonly` (recommended), `im:message`, or `im:message:get_as_user` |
+| `+message-read-users` | user | `im:message:readonly` (recommended), `im:message`, `im:message:basic`, or `im:message:get_as_user` |
+| `+message-read-users` | bot | `im:message:readonly` |
+
+For `+message-read-users`, the caller must still be in the chat. A user can query only messages they sent within the last seven days, while a bot can query only messages sent by that bot within the last seven days.
+The user scopes in the table are alternatives; the CLI preflight uses `im:message:readonly` because it is the least-privileged regular OAuth scope supported by this endpoint.
+
+## Batch query the current user's read status
+
+```bash
+# Preview one request
+lark-cli im +messages-read-status \
+  --message-ids om_xxx,om_yyy \
+  --as user \
+  --dry-run
+
+# Execute with a user access token
+lark-cli im +messages-read-status \
+  --message-ids om_xxx,om_yyy \
+  --as user \
+  --json
+```
+
+The command accepts 1–50 comma-separated `om_` message IDs. The three scopes above are alternatives; any one is sufficient, and the CLI recommends the least-privileged OAuth scope `im:message:readonly`. The response keeps the OpenAPI response unchanged:
+
+- `items[].message_id` and `items[].is_read` contain statuses the server could determine.
+- `invalid_message_ids` contains messages that do not exist, are not visible to the current user, or do not support this query. The API deliberately does not expose a more specific reason.
+
+## List users who read one message
+
+```bash
+# Fetch one page as the current user
+lark-cli im +message-read-users \
+  --message-id om_xxx \
+  --as user \
+  --json
+
+# Fetch every page as a bot, bounded to ten pages by default
+lark-cli im +message-read-users \
+  --message-id om_xxx \
+  --user-id-type open_id \
+  --page-all \
+  --as bot \
+  --json
+```
+
+Pagination flags:
+
+- `--page-size`: 1–100, default 100.
+- `--page-token`: start from a known cursor.
+- `--page-all`: continue until the endpoint is exhausted.
+- `--page-limit`: maximum pages with `--page-all`; default 10, range 1–1000.
+- `--page-delay`: delay in milliseconds between pages; default 200, and 0 disables the delay.
+
+The command preserves each server item, including `user_id_type`, `user_id`, `timestamp`, and `tenant_key`. Pagination metadata reports whether the endpoint was exhausted and retains the next token when a bounded run can be resumed.
+
+## Raw API commands
+
+When Registry MR !128 is published, the corresponding raw commands remain available:
+
+```bash
+lark-cli im messages read_status --data '{"message_ids":["om_xxx"]}' --as user
+lark-cli im messages read_users --params '{"message_id":"om_xxx","user_id_type":"open_id"}' --as user
+```
+
+Prefer the shortcuts for flag validation, identity-specific scope hints, and read-users auto-pagination.
+
+## Troubleshooting
+
+| Symptom | Meaning | Action |
+|---|---|---|
+| `--as bot is not supported` for read status | The batch endpoint requires user identity | Switch to `--as user` |
+| Missing `im:message:readonly` or `im:message` | A regular OAuth scope has not been granted | Follow the CLI authorization hint to grant one supported scope |
+| Missing a user read scope | No supported regular OAuth scope has been granted | Grant `im:message:readonly` and retry |
+| Bot permission denied | The application lacks a bot scope | Open the `console_url` from the typed error and enable the requested scope |
+| Empty read-user list | No user has read the message, or sender/time constraints are not met | Verify chat membership, the message sender, and the seven-day window |
+
+## References
+
+- [lark-im](../SKILL.md)
+- [lark-shared](../../lark-shared/SKILL.md)

package/skills/lark-im/references/lark-im-messages-edit.md

@@ -0,0 +1,89 @@
+# im +messages-edit
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Edit an already-sent message's content. **Bot identity only** — the edit API does not accept user tokens. Only messages the bot sent can be edited.
+
+This skill maps to the shortcut: `lark-cli im +messages-edit` (PUT on the message edit endpoint).
+
+## Safety Constraints
+
+Editing rewrites a message visible to other people. Before calling it, you **must** confirm with the user:
+
+1. Which message to edit (its `message_id`)
+2. The new content
+
+The bot must be the original sender — editing another identity's message fails. Identity is always the bot: user identity is rejected server-side (`user access token not support`).
+
+**Do not** edit a message without explicit user approval.
+
+## Choose The Right Content Flag
+
+| Need | Recommended flag | Why |
+|------|------|------|
+| Edit to headings, lists, links, summaries, or Markdown-looking content | `--markdown` | Best default for lightweight formatting; converted to Feishu `post` JSON |
+| Edit to exact plain text | `--text` | Preserves literal text; no Markdown conversion |
+| Precisely control the new payload | `--content` | You provide the exact JSON for `text` / `post` |
+| Attach files/folders to the edited message's attachment zone | `--set-attachments` | Repeatable, as bare `file_key` (`file_xxx`); **replaces** the post content's `files` array (flag values are the final list, discarding any `files` in `--content`). Requires a post message (`--markdown` or `--msg-type post`). Name/metadata are filled by the server, not the client |
+| Clear the edited message's attachment zone | `--clear-attachments` | Sets `files:[]` on the post content. Requires a post message; mutually exclusive with `--set-attachments` |
+| Keep the existing attachment zone while rewriting the body | *(no attachment flag)* | **Default.** Editing with only `--markdown` / `--text` / `--content` leaves the current `files` array untouched — a body-only edit never drops attachments |
+
+## Editing the Attachment Zone
+
+`post` messages can carry an attachment zone — a top-level `files` array that renders files/folders under the rich-text body.
+
+**Default: no attachment flag preserves the attachment zone.** Editing with only `--markdown` / `--text` / `--content` (i.e. passing neither `--set-attachments` nor `--clear-attachments`) rewrites the body and keeps the existing `files` array unchanged. This is the safe default — fixing a typo must not drop the files you attached. Only pass `--set-attachments` to replace the zone, or `--clear-attachments` to remove it.
+
+To edit a message so it attaches (or re-attaches) files:
+
+```bash
+lark-cli im +messages-edit --as bot --message-id om_xxx --markdown "Updated content" --set-attachments file_xxx --set-attachments file_yyy
+```
+
+- `--set-attachments` accepts a bare file/folder key (`file_xxx`), and may be repeated.
+- **`--set-attachments` is a replace, not an append:** the flag values become the final `files` array. Send/reply's `--attachment` merges; edit's `--set-attachments` replaces.
+- **Mutually exclusive with `--content` carrying files:** when `--content` already contains a `files` array, `--set-attachments` and `--clear-attachments` are rejected — declare the attachment zone either via `--content` or via the attachment flags, not both. Use `--markdown` (which never emits a `files` array) or a `--content` without `files` together with the attachment flags.
+- The server fills name/size/mime/is_folder from file service metadata; the client does not (and cannot) override the display name.
+- When `--set-attachments` is present the effective `msg_type` is forced to `post`. Pair it with `--markdown` (or `--content` with post JSON plus `--msg-type post`); `--text` cannot carry an attachment zone.
+- The edited content replaces the whole message content, so include every file you want to keep in the new attachment zone.
+
+To **clear** the attachment zone entirely, pass `--clear-attachments` instead of `--set-attachments`:
+
+```bash
+lark-cli im +messages-edit --as bot --message-id om_xxx --markdown "Updated content" --clear-attachments
+```
+
+- `--clear-attachments` sets the post content's `files` array to `[]`, telling the server to remove all file/folder attachments.
+- It cannot be used together with `--set-attachments`.
+- Like `--set-attachments`, it forces the effective `msg_type` to `post`, so pair it with `--markdown` or `--msg-type post --content <post-json>`.
+
+## Parameters
+
+| Parameter | Required | Description |
+|------|------|------|
+| `--message-id <id>` | Yes | Message ID (`om_xxx`) to edit |
+| `--text <string>` | One content option | Plain text content |
+| `--markdown <string>` | One content option | Markdown text, converted to `post` JSON |
+| `--content <json>` | One content option | Exact message content JSON; must match the effective `--msg-type` |
+| `--set-attachments <key>` | One content option | Repeatable bare file/folder key (`file_xxx`); **replaces** the post attachment zone — the flag values become the final `files` array, discarding any `files` written in `--content`, and duplicate keys are sent once. Name/size/mime/is_folder are filled by the server |
+| `--clear-attachments` | One content option | Clear the post attachment zone by setting `files:[]` |
+| `--msg-type <type>` | No | Message type (default `text`). When `--markdown`/`--set-attachments`/`--clear-attachments` is used the effective type is inferred automatically |
+| `--as <identity>` | No | Identity type: `bot` only (user identity is rejected by the server) |
+| `--dry-run` | No | Print the request only, do not execute it |
+
+## Return Value
+
+```json
+{
+  "message_id": "om_xxx",
+  "chat_id": "oc_xxx",
+  "update_time": "1234567890"
+}
+```
+
+## Common Mistakes
+
+- Editing a message the calling identity did not send — the API rejects it.
+- Using `--set-attachments` with `--text`. The attachment zone only exists on `post` messages; use `--markdown` or `--msg-type post`.
+- Supplying only the files you want to keep, then losing the text. Editing replaces the entire content; pass the full new content (text + attachments) in one call.
+- Assuming a body-only edit clears the attachment zone. It does not — without `--set-attachments` / `--clear-attachments` the existing attachments are preserved.

package/skills/lark-im/references/lark-im-messages-mget.md

@@ -51,6 +51,14 @@ Each message contains:
 | `sender` | Sender information (includes `name`) |
 | `content` | Message content |
 
+For `post` messages, the attachment zone (top-level `files` array) is rendered as trailing lines in `content`, one per attachment:
+
+- `<file key="file_xxx" name="report.pdf"/>` — a file with a display name (same tag style as a standalone `file` message)
+- `<file key="file_xxx"/>` — a file with an empty display name (the server always backfills names, so this branch is rare but valid on the wire)
+- `<folder key="file_xxx" name="assets"/>` — a folder (`is_folder: true`, same tag style as a standalone `folder` message)
+
+Use `--format json` to see the full content without table truncation — note the content is the rendered text (including the `<file>`/`<folder>` lines above), not the raw post JSON. Attachment file keys rendered in the tags are eligible for [`+messages-resources-download`](lark-im-messages-resources-download.md) via `--download-resources`.
+
 ## Usage Scenarios
 
 ### Scenario 1: Fetch the full content of a specific message

package/skills/lark-im/references/lark-im-messages-reply.md

@@ -187,6 +187,7 @@ lark-cli im +messages-reply --message-id om_xxx --msg-type interactive --content
 | `--video <path\|url\|key>` | One content option | Cwd-relative local video path, URL, or `file_key` (`file_xxx`); **must be used together with `--video-cover`**                                                                                |
 | `--video-cover <path\|url\|key>` | **Required with `--video`** | Cwd-relative local cover image path, URL, or `image_key` (`img_xxx`)                                                                                                                          |
 | `--audio <path\|url\|key>` | One content option | Voice-message audio key, URL, or cwd-relative local path. Local paths and URLs must be Opus (`.opus` or Ogg Opus `.ogg`) |
+| `--attachment <key>` | One content option | Repeatable bare file/folder key (`file_xxx`); merges into the post message's attachment zone. Requires a post message (`--markdown` or `--msg-type post`). Name/size/mime/is_folder are filled by the server from file service metadata, not taken from the client. Use this instead of `--file` when the file should render inside a rich-text message's attachment area |
 | `--reply-in-thread` | No | Reply inside the thread. The reply appears in the target message's thread instead of the main chat stream                                                                                     |
 | `--idempotency-key <key>` | No | Idempotency key, max 50 characters; the same key sends only one reply within 1 hour                                                                                                          |
 | `--as <identity>` | No | Identity type: `bot` or `user` (default `bot`)                                                                                                                                                |
@@ -206,6 +207,7 @@ lark-cli im +messages-reply --message-id om_xxx --msg-type interactive --content
 - Using `--content` without making the JSON match the effective `--msg-type`.
 - Explicitly setting `--msg-type` to something that conflicts with `--text`, `--markdown`, or media flags.
 - Mixing `--text`, `--markdown`, or `--content` with media flags in one command.
+- Using `--attachment` with `--text` or a media flag. The attachment zone only exists on `post` messages — pair `--attachment` with `--markdown` or `--msg-type post`.
 
 ## Return Value
 

package/skills/lark-im/references/lark-im-messages-send.md

@@ -34,6 +34,7 @@ When using `--as user`, the message is sent as the authorized end user and requi
 | Send plain text exactly as written | `--text` | Preserves literal text; no Markdown conversion |
 | Precisely control the final payload | `--content` | You provide the exact JSON for `text` / `post` / `interactive` / `share_*` / media payloads |
 | Send image / file / video / audio | `--image` / `--file` / `--video` / `--audio` | Shortcut uploads URLs, or cwd-relative local files automatically |
+| Attach files/folders to a post message's attachment zone | `--attachment` | Repeatable, as bare `file_key` (`file_xxx`); merges into the post content's `files` array. Requires a post message (`--markdown` or `--msg-type post`). Name/metadata are filled by the server, not the client |
 
 ### `--text` vs `--markdown`
 
@@ -190,12 +191,13 @@ lark-cli im +messages-send --chat-id oc_xxx --msg-type interactive --content '<c
 | `--video <path\|url\|key>` | One content option | Cwd-relative local video path, URL, or `file_key` (`file_xxx`). Local paths and URLs are uploaded automatically. **Must be paired with `--video-cover`**                                      |
 | `--video-cover <path\|url\|key>` | **Required with `--video`** | Cwd-relative local cover image path, URL, or `image_key` (`img_xxx`). Local paths and URLs are uploaded automatically                                                                         |
 | `--audio <path\|url\|key>` | One content option | Voice-message audio key, URL, or cwd-relative local path. Local paths and URLs must be Opus (`.opus` or Ogg Opus `.ogg`) |
+| `--attachment <key>` | One content option | Repeatable bare file/folder key (`file_xxx`); merges into the post message's attachment zone. Requires a post message (`--markdown` or `--msg-type post`). Name/size/mime/is_folder are filled by the server from file service metadata, not taken from the client. Use this instead of `--file` when the file should render inside a rich-text message's attachment area |
 | `--msg-type <type>` | No | Message type (default `text`). If you use `--text` / `--markdown` / media flags, the effective type is inferred automatically. Explicitly setting a conflicting `--msg-type` fails validation |
 | `--idempotency-key <key>` | No | Idempotency key, max 50 characters; the same key sends only one message within 1 hour                                                                                                        |
 | `--as <identity>` | No | Identity type: `bot` or `user` (default `bot`)                                                                                                                                                |
 | `--dry-run` | No | Print the request only, do not execute it                                                                                                                                                     |
 
-> **Mutual exclusivity rule:** `--text`, `--markdown`, `--content`, and `--image`/`--file`/`--video`/`--audio` cannot be used together. Media flags are also mutually exclusive with each other.
+> **Mutual exclusivity rule:** `--text`, `--markdown`, `--content`, and `--image`/`--file`/`--video`/`--audio` cannot be used together. Media flags are also mutually exclusive with each other. `--attachment` cannot be combined with a `--content` that already contains a `files` array (the attachment zone is declared either via `--content` or via `--attachment`, not both).
 >
 > **Video cover rule:** `--video` **must** be accompanied by `--video-cover`. Omitting `--video-cover` when using `--video` will fail validation. `--video-cover` cannot be used without `--video`.
 
@@ -209,13 +211,15 @@ lark-cli im +messages-send --chat-id oc_xxx --msg-type interactive --content '<c
 - Using `--content` without making the JSON match the effective `--msg-type`.
 - Explicitly setting `--msg-type` to something that conflicts with `--text`, `--markdown`, or media flags.
 - Mixing `--text`, `--markdown`, or `--content` with media flags in one command.
+- Using `--attachment` with `--text` or a media flag. The attachment zone only exists on `post` messages — pair `--attachment` with `--markdown` or `--msg-type post`.
+- Using `--file` when the file should sit inside a rich-text message's attachment area. `--file` sends a standalone `file`-type message; use `--attachment` (with `--markdown` or post `--content`) to attach files/folders inside a post message.
 
 ## `content` Format Reference
 
 | `msg_type` | Example `content` |
 |----------|-------------|
 | `text` | `{"text":"Hello <at user_id=\"ou_xxx\">name</at>"}` |
-| `post` | `{"zh_cn":{"title":"Title","content":[[{"tag":"text","text":"Body"}]]}}` |
+| `post` | `{"zh_cn":{"title":"Title","content":[[{"tag":"text","text":"Body"}]]},"files":[{"key":"file_xxx"}]}` — the top-level `files` array is the attachment zone; each entry carries a file/folder `key` (name/metadata are backfilled by the server from file service metadata — a client-supplied `name` has no effect) |
 | `image` | `{"image_key":"img_xxx"}` |
 | `file` | `{"file_key":"file_xxx"}` |
 | `audio` | `{"file_key":"file_xxx"}` |

package/skills/lark-mail/references/lark-mail-draft-create.md

@@ -24,37 +24,37 @@
 
 ```bash
 # 创建 HTML 草稿（推荐）
-lark-cli mail +draft-create --to alice@example.com --subject '周报' \
+lark-cli mail +draft-create --to 'alice@example.com' --subject '周报' \
   --body '<p>本周进展：</p><ul><li>完成 A 模块</li></ul>'
 
 # 不带收件人的 HTML 草稿（用户之后可自行添加）
 lark-cli mail +draft-create --subject '周报' --body '<p>草稿内容</p>'
 
 # 带附件和内嵌图片的 HTML 草稿（推荐：直接用相对路径，自动解析）
-lark-cli mail +draft-create --to alice@example.com --subject '预览图' --body '<p>见附件和图：<img src="./logo.png" /></p>' --attach ./report.pdf
+lark-cli mail +draft-create --to 'alice@example.com' --subject '预览图' --body '<p>见附件和图：<img src="./logo.png" /></p>' --attach './report.pdf'
 
 # 纯文本草稿（仅在内容极简时使用）
-lark-cli mail +draft-create --to alice@example.com --subject '简短通知' --body '收到，谢谢'
+lark-cli mail +draft-create --to 'alice@example.com' --subject '简短通知' --body '收到，谢谢'
 
 # Dry Run（仅打印请求，不执行）
-lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'test' --dry-run
+lark-cli mail +draft-create --to 'alice@example.com' --subject '测试' --body 'test' --dry-run
 ```
 
 ## 参数
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--to <emails>` | 否 | 完整收件人列表，多个用逗号分隔。支持 `Alice <alice@example.com>` 格式。省略时草稿不带收件人（之后可通过 `+draft-edit` 添加） |
+| `--to '<email>'` | 否 | 完整收件人列表。多个收件人请重复传 `--to`，每次只放一个地址，参数值用单引号包住。支持 `Alice <alice@example.com>` 格式。省略时草稿不带收件人（之后可通过 `+draft-edit` 添加） |
 | `--subject <text>` | 是 | 草稿主题 |
 | `--body <text>` | 二选一 | 邮件正文。推荐使用 HTML 获得富文本排版；也支持纯文本（自动检测）。使用 `--plain-text` 可强制纯文本模式。支持 `<img src="./local.png" />` 相对路径自动解析为内嵌图片（仅支持相对路径，不支持绝对路径）。与 `--body-file` 互斥 |
 | `--body-file <path>` | 二选一 | 从文件读取邮件正文 HTML（相对路径，仅限 cwd 子树）。与 `--body` 互斥。文件大小上限 32 MB |
 | `--from <email>` | 否 | 发件人邮箱地址（EML From 头）。使用别名（send_as）发信时，设为别名地址并配合 `--mailbox` 指定所属邮箱。省略时使用邮箱主地址 |
 | `--mailbox <email>` | 否 | 邮箱地址，指定草稿所属的邮箱（默认回退到 `--from`，再回退到 `me`）。当发件人（`--from`）与邮箱不同时使用，如通过别名或 send_as 地址发信。可通过 `accessible_mailboxes` 查询可用邮箱 |
-| `--cc <emails>` | 否 | 完整抄送列表，多个用逗号分隔 |
-| `--bcc <emails>` | 否 | 完整密送列表，多个用逗号分隔。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
+| `--cc '<email>'` | 否 | 完整抄送列表。多个抄送请重复传 `--cc`，每次只放一个地址，参数值用单引号包住 |
+| `--bcc '<email>'` | 否 | 完整密送列表。多个密送请重复传 `--bcc`，每次只放一个地址，参数值用单引号包住。与 `--event-*` 不兼容（见 `+send` 日程邀请约束） |
 | `--plain-text` | 否 | 强制纯文本模式，忽略 HTML 自动检测。不可与 `--inline` 同时使用。纯文本模式下也会自动追加纯文本签名（HTML 签名经 `PlainTextFromHTML` 转换，内联图片丢弃） |
-| `--attach <paths>` | 否 | 附件文件路径，多个用逗号分隔。相对路径。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
-| `--inline <json>` | 否 | 高级用法：手动指定内嵌图片 CID 映射。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。仅在需要精确控制 CID 命名时使用此参数。格式：`'[{"cid":"mycid","file_path":"./logo.png"}]'`，在 body 中用 `<img src="cid:mycid">` 引用。不可与 `--plain-text` 同时使用 |
+| `--attach '<path>'` | 否 | 附件文件路径。多个附件请重复传 `--attach`，每次只放一个相对路径，参数值用单引号包住；按传入顺序追加。当附件导致 EML 总大小超过 25 MB 时，超出部分自动上传为超大附件（HTML 邮件插入下载卡片，纯文本邮件追加下载链接），单个文件上限 3 GB |
+| `--inline '<json>'` | 否 | 高级用法：手动指定内嵌图片 CID 映射。多个 inline 图片请重复传 `--inline`，每次只放一个 JSON object，并用单引号包住：`'{"cid":"mycid","file_path":"./logo.png"}'`。`file_path` 必须是相对路径；CID 应唯一，例如随机十六进制字符串；在 body 中用 `<img src="cid:mycid">` 引用。推荐直接在 `--body` 中使用 `<img src="./path" />`（自动解析）。不可与 `--plain-text` 同时使用 |
 | `--signature-id <id>` | 否 | 签名 ID。附加邮箱签名到正文末尾。运行 `mail +signature` 查看可用签名。与 `--no-signature` 互斥 |
 | `--no-signature` | 否 | 跳过默认签名自动追加。与 `--signature-id` 互斥，同时使用时返回参数校验错误（退出码 2） |
 | `--priority <level>` | 否 | 邮件优先级：`high`、`normal`、`low`。省略或 `normal` 时不设置优先级 |
@@ -94,7 +94,7 @@ lark-cli mail +draft-create --to alice@example.com --subject '测试' --body 'te
 
 ```bash
 # 1. 创建草稿
-lark-cli mail +draft-create --to alice@example.com --subject 'Q1 报告' --body '请查收附件中的报告。' --attach ./q1-report.pdf --format json
+lark-cli mail +draft-create --to 'alice@example.com' --subject 'Q1 报告' --body '请查收附件中的报告。' --attach './q1-report.pdf' --format json
 
 # 2. 发送草稿
 lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_id":"<draft_id>"}'
@@ -107,13 +107,13 @@ lark-cli mail user_mailbox.drafts send --params '{"user_mailbox_id":"me","draft_
 ```bash
 # 推荐：直接使用相对路径，自动解析为内嵌图片
 lark-cli mail +draft-create \
-  --to alice@example.com \
+  --to 'alice@example.com' \
   --subject '通讯稿' \
   --body '<h1>你好</h1><img src="./banner.png" />'
 
 # 高级用法：手动指定 CID（CID 为唯一标识符，可用随机十六进制字符串）
 lark-cli mail +draft-create \
-  --to alice@example.com \
+  --to 'alice@example.com' \
   --subject '通讯稿' \
   --body '<h1>你好</h1><img src="cid:c7d8e9f0a1b2c3d4e5f6">' \
   --inline '[{"cid":"c7d8e9f0a1b2c3d4e5f6","file_path":"./banner.png"}]'