@amaster.ai/pi-lark 0.1.10 → 0.1.12

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.
 
@@ -110,6 +114,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+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 |
@@ -159,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.
@@ -176,6 +186,7 @@ lark-cli im <resource> <method> [flags] # 调用 API
   - `forward` — 转发消息。Identity: supports `user` and `bot`.
   - `merge_forward` — 合并转发消息。Identity: `bot` only (`tenant_access_token`).
   - `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.
@@ -232,6 +243,8 @@ 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` |
@@ -239,6 +252,7 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `messages.forward` | `im:message` |
 | `messages.merge_forward` | `im:message` |
 | `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-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-markdown/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-markdown
 version: 1.2.2
-description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。"
+description: "飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。"
 metadata:
   requires:
     bins: ["lark-cli"]

package/skills/lark-meeting/SKILL.md

@@ -105,8 +105,8 @@ lark-cli vc +meeting-events --as <source_identity> --meeting-id <meeting_id> --p
 - [查询妙记及其产物](scenes/query-minutes-and-artifacts.md)：已有妙记 URL / `minute_token`，或按标题、所有者、参与者搜索妙记；读取总结、待办、章节、关键词、逐字稿，下载原始音视频，或查询关联智能纪要。
 - [生成和修改妙记、管理妙记权限](scenes/create-and-edit-minutes.md)：将本地音视频生成妙记、逐字稿、总结、待办或章节；修改妙记标题、总结、待办、关键词或说话人；申请妙记权限，或查看、分配妙记协作者权限。
 - [查询智能纪要及关联产物](scenes/query-note-and-artifacts.md)：已有 `note_id`、智能纪要 Docx URL/token，或需要查询纪要正文、逐字稿、妙记和共享文档等关联产物。
-- [应用机器人参会与会中互动](scenes/live-meeting-attend.md)：完整编排应用机器人的活跃会议发现、真实入会、事件拉取、文本/表情互动和明确授权后的离会。
-- [会中事件与会中互动](scenes/live-meeting-interact.md)：在不触发新的入会/离会操作时，使用用户身份或已在会中的应用身份查询活跃会议、查看发言/聊天/共享内容，或发送文本和表情。
+- [应用机器人参会与会中互动](scenes/live-meeting-attend.md)：完整编排应用机器人的活跃会议发现、发起或加入、邀请、事件拉取、会议截图、文本/表情/倒计时互动、结束会议和明确授权后的离会。
+- [会中事件与会中互动](scenes/live-meeting-interact.md)：在不触发新的入会/离会操作时，使用用户身份或已在会中的应用身份查询活跃会议、查看发言/聊天/共享内容、按需读取当前会议画面，或发送文本/表情、操作倒计时。
 
 ## 命令参考
 
@@ -119,7 +119,11 @@ lark-cli vc +meeting-events --as <source_identity> --meeting-id <meeting_id> --p
 | `vc +meeting-list-active` | 发现当前可见的进行中会议 | [lark-vc-meeting-list-active](references/lark-vc-meeting-list-active.md) |
 | `vc +meeting-events` | 读取会中事件和共享内容 | [lark-vc-meeting-events](references/lark-vc-meeting-events.md) |
 | `vc +meeting-message-send` | 发送会中文本消息或表情 | [lark-vc-meeting-message-send](references/lark-vc-meeting-message-send.md) |
+| `vc +meeting-screenshot` | 获取视频会议截图 | [lark-vc-meeting-screenshot](references/lark-vc-meeting-screenshot.md) |
+| `vc +meeting-countdown` | 设置、延长、提前结束或关闭会中倒计时 | [lark-vc-meeting-countdown](references/lark-vc-meeting-countdown.md) |
 | `vc +meeting-join` | 让应用机器人加入会议 | [lark-vc-agent-meeting-join](references/lark-vc-agent-meeting-join.md) |
+| `vc +meeting-invite` | 以应用机器人邀请指定用户或全部合格日程参会人 | [lark-vc-agent-meeting-invite](references/lark-vc-agent-meeting-invite.md) |
+| `vc +meeting-end` | 让当前 Host 应用机器人结束会议 | [lark-vc-agent-meeting-end](references/lark-vc-agent-meeting-end.md) |
 | `vc +meeting-leave` | 让应用机器人离开会议 | [lark-vc-agent-meeting-leave](references/lark-vc-agent-meeting-leave.md) |
 | `minutes +search` | 搜索妙记 | [lark-minutes-search](references/lark-minutes-search.md) |
 | `minutes minutes get` | 查询妙记基础信息 | `lark-cli minutes minutes get --help` |

package/skills/lark-meeting/references/lark-minutes-summary.md

@@ -112,6 +112,7 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum
 | 总结展示为原始 Markdown 文本 | — | 总结含链接、四级标题等妙记端无法渲染的语法 | 改用标题（#～###）、加粗、列表等可展示格式；接口不会因此报错 |
 | 参数无效 | — | `minute_token` 缺失或格式错误 | 检查 token 是否完整 |
 | 权限不足 | — | 缺少 `minutes:minutes:update` | 运行 `auth login --scope "minutes:minutes:update"` |
+| `error.subtype` = `quota_exceeded` | 2091008 | 该妙记生成时 ASR/AI 额度已用尽，AI 总结未完整生成，替换无法落库 | 让用户去该妙记详情页查看额度详细信息；CLI 无法补充额度，重试不会成功 |
 
 ## 相关场景
 - [生成和修改妙记](../scenes/create-and-edit-minutes.md)

package/skills/lark-meeting/references/lark-minutes-todo.md

@@ -38,6 +38,9 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation delet
 
 # 预览
 lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "新待办" --is-done --dry-run --as user
+
+# 新增待办并指定负责人（负责人以内联 @ 提及写进 --todo 内容，这是妙记待办表示归属的既定写法）
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "跟进预算审批 @张三" --is-done=false --as user
 ```
 
 ## 参数
@@ -94,7 +97,41 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 
 `content` **不是 Markdown**，请直接传入待办描述文字。
 
-### 3. 所需权限
+### 3. 负责人 / `@` 提及（既定写法，必读）
+
+用户说"负责人是某某"时，既定写法是把负责人以内联 `@某某` 追加进 `--todo` 内容：
+
+- 用户已经直接给出姓名时（例如"负责人是张三"），**不做任何查找**，原文原样拼进 `--todo` 内容，写成纯文本 `@张三`（`--todo "xxx @张三"`）。
+- 用户说"负责人是我"时，**必须**先取当前登录用户的真实姓名再拼接，禁止直接写成字面的 `@我`：
+  - 执行 `lark-cli contact +get-user --as user`，取返回中的姓名字段作为真实姓名，拼成 `--todo "xxx @<真实姓名>"`。
+  - 如果这一步失败或取不到姓名（无权限、报错等），**不要**写任何 `@` 提及占位——直接用不带负责人后缀的原始待办文本创建（`--todo "xxx"`），不要保留字面的 `@我`。
+- **不要**因为要处理负责人而改路由到 [lark-task](../../lark-task/SKILL.md) 或做进一步的通讯录搜索——第一优先级永远是落地这条待办；姓名解析只影响追加的 `@` 文本，绝不能阻塞或取消待办创建。
+- **不要**用"创建者是谁 / 以什么身份创建"来代替 `@` 提及——创建时用的 `--as user`/`--as bot` 身份和"负责人"是两件不相关的事，即使已知当前用户真实姓名，也必须把它拼进 `content` 文本，不能只在回复里用"以你的身份创建即归属于你"这类说法搪塞。
+- 回复里**不要**主动提及或建议改用 `lark-task` 作为"想要明确负责人/可指派任务"的替代方案——用户说的负责人只是这条妙记待办里的一段文本，和 Task 完全无关，不要引入 Task 增加用户困惑。
+- 内联 `@` 是妙记待办表示负责人的既定写法。回复只陈述结果（妙记、待办内容、负责人、完成状态），**不要**出现"接口只支持 content 和 is_done""没有独立的负责人字段""所以只能把负责人写进内容里"这类实现限制说明或解释性免责。
+
+**结果示例**：
+
+```bash
+# 姓名解析成功
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "跟进预算审批 @王小明" --is-done=false --as user
+
+# "我"解析失败：不写 @ 提及，仅保留原始内容
+lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "跟进预算审批" --is-done=false --as user
+```
+
+```json
+{
+  "minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
+  "count": 1,
+  "updated": true,
+  "operation": "add"
+}
+```
+
+妙记里新增的这条待办的 `content` 字段就是最终拼好的文本本身（`"跟进预算审批 @王小明"` 或解析失败时的 `"跟进预算审批"`）；CLI 和这个接口都不会、也不需要把它转换成真正可点击的用户提及。
+
+### 4. 所需权限
 
 | 身份 | 所需 scope |
 |------|-----------|
@@ -120,6 +157,7 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 | `--todos` 与单条 flags 冲突 | 二选一 |
 | `todos[i]` 校验失败 | 检查该条 `operation` 与字段组合 |
 | `error.subtype` = `permission_denied` | **妙记资源无编辑权**：向妙记所有者申请该妙记的编辑/协作权限；**不要**走 `auth login --scope` |
+| `error.subtype` = `quota_exceeded` | **该妙记生成时 ASR/AI 额度已用尽**，AI 待办未完整生成，改待办无法落库：让用户去该妙记详情页查看额度详细信息；CLI 无法补充额度，重试不会成功 |
 | 缺少 OAuth scope（`error.missing_scopes` 含 `minutes:minutes:update`） | `lark-cli auth login --scope "minutes:minutes:update"` |
 
 ## 相关场景

package/skills/lark-meeting/references/lark-minutes-upload.md

@@ -61,5 +61,11 @@ API 会立即返回 `minute_url`，但妙记可能仍在异步生成中。`minut
 | `minute_url` | 生成的妙记访问链接 |
 | `minute_token` | 从 `minute_url` 提取出的妙记 Token，可直接传给 `minutes +detail --minute-tokens` |
 
+## 常见错误与排查
+
+| 错误现象 | 错误码 | 根本原因 | 解决方案 |
+|---------|--------|---------|---------|
+| `error.subtype` = `quota_exceeded` | 2091008 | ASR/AI 额度已用尽，不足以转写这个音视频，妙记未创建 | 让用户去妙记详情页查看额度详细信息；CLI 无法补充或提升额度，重试同一个 `--file-token` 不会成功 |
+
 ## 相关场景
 - [生成和修改妙记](../scenes/create-and-edit-minutes.md)

package/skills/lark-meeting/references/lark-vc-agent-meeting-end.md

@@ -0,0 +1,26 @@
+# vc +meeting-end
+
+当前 Host 应用 Bot 结束会议。
+
+```bash
+lark-cli vc +meeting-end --as bot --meeting-id 7628568141510692381 --yes
+lark-cli vc +meeting-end --as bot --meeting-id 7628568141510692381 --dry-run
+```
+
+正常执行必须显式传入 `--yes`；`--dry-run` 不会结束会议。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--meeting-id` | 是 | 长数字 Meeting ID，不是 9 位会议号。 |
+
+仅支持应用身份，调用 `POST /open-apis/vc/v1/bots/end`；仅当前 Host Bot 可结束进行中的会议。
+
+所需应用 Scope：`vc:meeting.bot.manage:write`。
+
+## 常见失败原因
+
+- 当前应用 Bot 不在会议中：先使用同一应用 Bot 发起或加入该 Calendar 会议，再执行结束。
+- 应用 Bot 在会中但不是当前 Host：将 Host 转交给该 Bot，或由当前 Host/Owner 结束会议。
+- 会议未启用 Agent 会议能力：确认会议设置及会议 Owner 的必要灰度开关。

package/skills/lark-meeting/references/lark-vc-agent-meeting-invite.md

@@ -0,0 +1,32 @@
+# vc +meeting-invite
+
+通过 Agent Bot API 邀请指定用户，或一键邀请符合条件的 Calendar 参会人。
+
+```bash
+lark-cli vc +meeting-invite --as bot --meeting-id 7628568141510692381 --type SELECTED --open-ids ou_xxx,ou_yyy
+lark-cli vc +meeting-invite --as bot --meeting-id 7628568141510692381 --type ALL_SUGGESTED
+lark-cli vc +meeting-invite --as bot --meeting-id 7628568141510692381 --type ALL_SUGGESTED --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `--meeting-id` | 是 | 长数字 Meeting ID，不是 9 位会议号。 |
+| `--type` | 是 | `SELECTED` 或 `ALL_SUGGESTED`，大小写不敏感。 |
+| `--open-ids` | `SELECTED` 时必填 | 用户 `open_id`（`ou_xxx`），支持逗号分隔或重复传入，最多 200 个；`ALL_SUGGESTED` 时不得传入。 |
+
+该 shortcut 仅支持 bot 身份，调用 `POST /open-apis/vc/v1/bots/invite`。
+
+- `SELECTED` 显式发送用户 `open_id`；本地会在请求前拒绝超过 200 个 ID 的输入。
+- `ALL_SUGGESTED` 只发送邀请类型。服务端根据 Calendar 状态解析一键邀请候选集，并应用 200 人上限。
+- 请求契约：`SELECTED` 发送 `invite_type=2`、`invitees=[{"id":"ou_xxx","user_type":1}]` 和查询参数 `user_id_type=open_id`；`ALL_SUGGESTED` 发送 `invite_type=1` 且省略 `invitees`。
+- 返回契约：`SELECTED` 可返回显式受邀人的 `invite_results`；CLI 会按响应 `id` 展示每项 `invited` 或 `failed` 状态。`ALL_SUGGESTED` 仅返回聚合字段，不返回逐用户 `invite_results`。
+- `ALL_SUGGESTED` 的 `has_more=true` 表示候选人超过服务端单次 200 人上限，不是可翻页信号。该接口没有 continuation 或 `page_token`；CLI 会显示截断提示而不输出 `has_more`。
+
+## 权限与前置条件
+
+- 目标必须是 Calendar VC 会议，且应用 Bot 已在会中。
+- Agent Invite 依赖会议的 Agent 加入能力。日程未开启 AI/Agent 会议设置时，邀请请求会失败。
+- 仅包含一名受邀人的 `SELECTED` 复用普通单点邀请策略，普通会中参会人也可能有权邀请该用户。
+- `ALL_SUGGESTED` 和多用户 `SELECTED` 使用批量/建议列表邀请策略。实际调用时 Bot 应为当前 host 或 co-host；普通参会 Bot 可能没有批量邀请权限。

package/skills/lark-meeting/references/lark-vc-agent-meeting-join.md

@@ -12,6 +12,9 @@
 ```bash
 # 仅指定会议号（无密码）
 lark-cli vc +meeting-join --as bot --meeting-number 123456789
+
+# 发起日程会议（仅应用身份）
+lark-cli vc +meeting-join --as bot --meeting-number 123456789 --action start
 ```
 
 ## 参数
@@ -21,6 +24,7 @@ lark-cli vc +meeting-join --as bot --meeting-number 123456789
 | `--meeting-number <no>` | 是 | 会议号，必须为 **9 位纯数字** |
 | `--password <pw>` | 否 | 会议密码，仅在该会议设置了入会密码时传入 |
 | `--call-id <id>` | 否 | 从 `vc.bot.meeting_invited_v1` 邀请事件透传的 `call_id`，原样回传即可。Agent 主动入会或无邀请事件来源时不传 |
+| `--action join\|start` | 否 | 默认 `join`，保持普通入会链路；`start` 是日程发起专属参数，用同一 `bots/join` API 发起会议，且必须 `--as bot` |
 | `--dry-run` | 否 | 预览 API 调用，不实际加入会议；会议号或身份不确定时先用它确认请求 |
 
 ## 核心约束
@@ -29,6 +33,8 @@ lark-cli vc +meeting-join --as bot --meeting-number 123456789
 
 这是应用机器人入会能力，使用 `--as bot`。不要用当前登录用户身份尝试让应用机器人入会。
 
+默认 `join` 不会向请求体写入 `action` 字段，也不进入日程发起筛选。`--action start` 才写入 `action: 2`，单独进入日程发起的筛选与校验。
+
 ### 2. 会议号格式严格校验
 
 `--meeting-number` 必须是 9 位纯数字，否则本地校验直接报错：
@@ -40,7 +46,7 @@ lark-cli vc +meeting-join --as bot --meeting-number 123456789
 
 ### 3. 会议必须已开始且允许入会
 
-- 会议必须处于**进行中**状态，应用机器人无法加入尚未开始或已结束的会议。
+- `--action join` 要求会议处于**进行中**状态；`--action start` 用于启动符合条件的日程会议。
 - 若会议设置了**等候室 / 入会审批**，应用机器人可能需要主持人放行后才真正入会。
 - 若返回 `HTTP 403: no permission`（错误码 `121003`），不要只理解成“账号没权限”。这类报错更常见的原因是：会议参数或会控配置当前不满足入会条件，例如会议号填错、密码未传或错误、会议尚未开始、等候室 / 入会审批未放行、会议禁止外部/特定身份加入等。应先确认这些配置项，再重试。
 
@@ -75,7 +81,7 @@ lark-cli vc +meeting-join --as bot --meeting-number 123456789
 |---------|---------|---------|
 | `--meeting-number must be exactly 9 digits` | 会议号不是 9 位纯数字 | 检查是否误传了会议链接或 meeting_id |
 | 会议密码错误 | `--password` 错误或未提供 | 向主持人确认会议密码 |
-| 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中 |
+| 会议不存在 / 已结束 | 会议号错误或会议未进行中 | 确认会议正在进行中；启动日程会议时改用 `--action start` |
 | `HTTP 403: no permission` / `121003` | 入会前置条件不满足，通常不是单纯 scope 问题 | 依次确认：1）会议允许智能体加入；2）会议号正确；3）如有密码，已正确传入 `--password`；4）会议已开始；5）等候室 / 入会审批已放行；6）会议未禁止当前身份加入（如限制外部、限制应用机器人、仅特定成员可入会）；确认后重试 |
 | 应用身份权限不足 | 应用权限、租户安装或权限可访问的数据范围未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；配置正确仍失败时，保留错误码和 `log_id`，按服务端权限异常排查 |
 | 入会被拒绝 | 等候室 / 入会审批 / 限制外部入会 | 联系主持人放行或调整会议设置 |

package/skills/lark-meeting/references/lark-vc-meeting-countdown.md

@@ -0,0 +1,103 @@
+# vc +meeting-countdown
+
+设置、延长、提前结束或关闭会中倒计时窗口。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-countdown`（调用 `POST /open-apis/vc/v1/bots/countdown`）。
+
+## 适用场景
+
+- 用户要求在正在进行中的会议里设置倒计时，例如“设置 5 分钟倒计时”。
+- 用户要求延长当前倒计时，例如“再延长 2 分钟”。
+- 用户要求提前结束或关闭当前倒计时。
+- 只用于正在进行中的会议；已结束会议不支持。
+
+## 身份规则
+
+`meeting_id` 从哪种身份路径拿到，操作倒计时时就沿用哪种身份：
+
+| meeting_id 来源 | 操作时身份 |
+| --- | --- |
+| `+meeting-list-active --as user` | `+meeting-countdown --as user` |
+| `+meeting-list-active --as bot --user-id <user_open_id>` | `+meeting-countdown --as bot` |
+| `+meeting-join --as bot` 返回的 `meeting.id` | `+meeting-countdown --as bot` |
+
+不要把用户身份发现的 `meeting_id` 改用应用身份操作，也不要把应用身份发现的 `meeting_id` 改用用户身份操作，除非用户明确要求切换。
+
+## 参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `--meeting-id` | 必填，长数字 `meeting_id`，不是 9 位会议号 |
+| `--action` | 必填，`set`、`prolong`、`end_in_advance` 或 `close_window` |
+| `--duration` | 倒计时时长，单位是分钟；`set` 和 `prolong` 必填 |
+| `--need-play-audio-at-end` | 仅 `set` 可用，表示倒计时结束时播放提示音 |
+| `--reminder-before-end` | 仅 `set` 可用，提醒点单位是分钟；只支持传一个值 |
+
+`duration` 和 `reminder_before_end` 都是分钟；提醒时间必须大于 0 且小于 `duration`。
+
+## 设置倒计时
+
+```bash
+lark-cli vc +meeting-countdown --as user \
+  --meeting-id <meeting_id> \
+  --action set \
+  --duration 5 \
+  --need-play-audio-at-end \
+  --reminder-before-end 1
+```
+
+Dry-run 请求体示例：
+
+```json
+{
+  "meeting_id": "<meeting_id>",
+  "action": "set",
+  "duration": 5,
+  "need_play_audio_at_end": true,
+  "reminder_before_end": 1
+}
+```
+
+## 延长倒计时
+
+```bash
+lark-cli vc +meeting-countdown --as bot \
+  --meeting-id <meeting_id> \
+  --action prolong \
+  --duration 2
+```
+
+## 提前结束或关闭倒计时
+
+```bash
+lark-cli vc +meeting-countdown --as user --meeting-id <meeting_id> --action end_in_advance
+lark-cli vc +meeting-countdown --as user --meeting-id <meeting_id> --action close_window
+```
+
+提前结束或关闭倒计时窗口时不要传 `--duration`、`--need-play-audio-at-end` 或 `--reminder-before-end`。
+
+## 9 位会议号处理
+
+如果用户给的是 9 位会议号并要求操作倒计时：
+
+1. 先按当前身份执行 `+meeting-list-active`。
+2. 在返回结果中按 `meeting_no` 匹配该 9 位会议号。
+3. 匹配到唯一会议后取长数字 `meeting_id`。
+4. 用发现该会议时的同一身份执行 `+meeting-countdown`。
+
+匹配失败时不要自动入会。只有用户明确要求“让应用机器人入会/旁听/代参会”时，才改用 `+meeting-join`。
+
+## 权限和前置条件
+
+- 用户身份：当前用户必须正在该会议中。
+- 应用身份：应用机器人必须正在该会议中。
+- 需要 `vc:meeting.interaction:write` 权限；应用身份还需要应用已安装、数据范围已配置。
+
+应用身份权限错误时，不要引导用户反复 `auth login`。按主 skill 的“应用身份权限配置检查”处理。
+
+## 相关
+
+- [lark-vc-meeting-list-active](lark-vc-meeting-list-active.md) — 发现当前进行中会议 ID
+- [lark-vc-meeting-events](lark-vc-meeting-events.md) — 读取会中事件
+- [lark-vc-meeting-message-send](lark-vc-meeting-message-send.md) — 发送会中文本或 reaction
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 应用机器人入会

package/skills/lark-meeting/references/lark-vc-meeting-events.md

@@ -252,6 +252,7 @@ lark-cli drive +list-replies \
 | `magic_share_started` | 开始共享内容 / 文档 |
 | `magic_share_ended` | 结束共享 |
 | `document_context_changed` | 评论聚焦、章节定位或元素预览上下文变化 |
+| `countdown_changed` | 会中倒计时被设置、延长、提前结束、关闭窗口，或自然结束、临近提醒 |
 
 ### Forwarding meeting chat and reactions to IM
 

package/skills/lark-meeting/references/lark-vc-meeting-screenshot.md

@@ -0,0 +1,34 @@
+# `vc +meeting-screenshot`
+
+获取视频会议截图，并保存为 JPEG。
+
+## 常用用法
+
+使用当前用户身份截图，文件写入默认目录：
+
+```bash
+lark-cli vc +meeting-screenshot --as user --meeting-id <long_meeting_id>
+```
+
+使用机器人身份截图，并指定输出路径：
+
+```bash
+lark-cli vc +meeting-screenshot --as bot --meeting-id <long_meeting_id> --output ./meeting-screenshots/current.jpg
+```
+
+## 参数
+
+| Flag | 含义与用法 |
+| --- | --- |
+| `--as <identity>` | 选择 `user` 或 `bot` 身份。使用发现 `meeting_id` 时的同一身份：`user` 要求当前用户在会中；`bot` 要求机器人已入会并具备会中读取权限。 |
+| `--meeting-id <meeting_id>` | 必填。长数字会议 ID，不接受 9 位会议号；只有会议号时，先用同一身份调用 `vc +meeting-list-active` 获取。 |
+| `--output <relative-path>` | 可选。指定 JPEG 文件名或包含子目录的相对路径；相对于执行命令时的当前工作目录。 |
+| `--overwrite` | 可选。目标文件已存在时允许替换；不传时命令会失败并保留原文件。 |
+
+## 文件路径与结果
+
+- 未指定 `--output` 时，默认写入当前工作目录下的 `meeting-screenshots/<meeting_id>-<UTC timestamp>.jpg`。
+- `--output` 可以只写文件名，也可以包含多级子目录；父目录会自动创建。
+- 不接受绝对路径，也不接受解析后超出当前工作目录的 `..` 或符号链接路径。
+- 成功结果包含绝对文件路径、字节数、JPEG content type、SHA-256 和服务端 `log_id`。
+- 服务端决定截图内容并校验会议是否满足条件；调用方不能指定要截取的区域或共享内容。失败不会替换已有文件。