@amaster.ai/pi-lark 0.1.2-beta.69 → 0.1.2-beta.71

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

@@ -51,13 +51,30 @@ Each message contains:
 | `sender` | Sender information (includes `name`) |
 | `content` | Message content |
 
+For `folder` messages, `content` carries a folder key; `mget` expands the folder one level (`GET /files/:file_key/folder`), rendering first-level children inside the folder tag:
+
+```
+<folder key="file_v3_...g" name="assets" child_count="5">
+  <file key="file_v3_...g" name="a.pdf"/>
+  <folder key="file_v3_...g" name="sub" child_count="2"/>
+</folder>
+```
+
+- `child_count` on the root folder is the total first-level item count reported by the API; when a folder has more first-level children than the render cap (10), the tag carries `has_more="true"`.
+- `child_count` on a nested `<folder>` child is that child's own child count (a depth hint; nested folders are not expanded further).
+- A genuinely empty folder renders as `<folder key="..." name="..." child_count="0"/>`.
+
 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)
+- `<folder key="file_xxx" name="assets"/>` — a folder attachment (`is_folder: true`). Like folder messages, the attachment is expanded one level (children rendered inside the tag) when runtime + message id are available; otherwise it degrades to this single-line tag.
+
+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.
 
-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`.
+Downloading: [`+messages-resources-download`](lark-im-messages-resources-download.md) takes an explicit `--message-id` + `--file-key` and fetches `GET /messages/:id/resources/:file_key` — this works for standalone `file` message keys, top-level `post` attachment `files[]` entries, **and file keys rendered inside `<folder>...</folder>` (folder children are real files addressed by their own file_key)**. Two caveats:
+- `--download-resources` (the automatic enrichment flag on list/get commands) only auto-collects top-level single-file resources from the raw content — folder children are expanded at render time and are **not** auto-added to that worklist, so to download a folder child you pass its key explicitly to `+messages-resources-download`.
+- `is_folder` entries themselves (a folder, not a file) are not downloadable as a single resource.
 
 ## Usage Scenarios
 

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

@@ -151,7 +151,7 @@ lark-cli im +threads-messages-list --thread <thread_id>
 
 ## Resource Rendering
 
-Search results reuse the same content formatter as other read commands. Image messages are rendered as placeholders such as `![Image](img_xxx)`; resource binaries are **not** downloaded automatically.
+Search results reuse the same content formatter as other read commands. Image messages are rendered as placeholders such as `![Image](img_xxx)`; `folder` messages in results are expanded one level (see [`lark-im-chat-messages-list`](lark-im-chat-messages-list.md#resource-rendering) for the marker/download contract); resource binaries are **not** downloaded automatically.
 
 Use `im +messages-resources-download` if you need to fetch the underlying image or file bytes from a specific message.
 

package/skills/lark-im/references/lark-im-threads-messages-list.md

@@ -100,7 +100,7 @@ lark-cli im +threads-messages-list --thread omt_xxx --page-token <PAGE_TOKEN>
 
 ## Resource Rendering
 
-Thread replies are rendered into human-readable text. Image messages appear as placeholders such as `![Image](img_xxx)`; by default resource binaries are **not** downloaded.
+Thread replies are rendered into human-readable text. Image messages appear as placeholders such as `![Image](img_xxx)`; `folder` replies are expanded one level (children rendered inside a `<folder ...>` tag); by default resource binaries are **not** downloaded.
 
 Pass `--download-resources` to download every eligible resource (image/file/audio/video/media + post-embedded, excluding stickers) into `./lark-im-resources/` in one pass and attach a `resources` block to each reply (see [message enrichment](lark-im-message-enrichment.md#resource-auto-download---download-resources-opt-in)). Otherwise download individual resources manually through `im +messages-resources-download` (see [lark-im-messages-resources-download](lark-im-messages-resources-download.md)).
 

package/skills/lark-mail/SKILL.md

@@ -64,7 +64,9 @@ metadata:
 | 不可逆删除 | `*.delete`、`drafts.delete` | ✅ 必须 |
 | 软删除 | `*.trash`、`*.batch_trash` | ✅ 必须 |
 | 取消定时 | `*.cancel_scheduled_send` | ✅ 必须 |
-| 修改收信规则 | `rules.create` / `update` / `delete` | ✅ 必须 |
+| 删除收信规则 | `rules.delete` | ✅ 必须 |
+| 创建 / 更新收信规则 | `rules.create` / `update` | ✅ 必须 |
+| 启停 / 排序收信规则 | `rules.enable` / `disable` / `reorder` | ❌ 普通写操作，免 `--yes` |
 | 标签变更 | `*.add_label`、`*.remove_label` | ❌ 可逆，免确认 |
 | 已读状态 | `*.mark_read` / `mark_unread` | ❌ 可逆，免确认 |
 | 移动文件夹 | `*.move` | ❌ 可逆，免确认 |
@@ -86,17 +88,18 @@ metadata:
 邮箱是用户的个人资源，**策略上应优先显式使用 `--as user`（用户身份）请求**（CLI 的 `--as` 默认值为 `auto`）。
 
 - **`--as user`（推荐）**：以当前登录用户的身份访问其邮箱。需要先通过 `lark-cli auth login --domain mail` 完成用户授权。
-- **`--as bot`**：以应用身份访问邮箱。需要在飞书开发者后台为应用开通相应权限，否则请求会被拒绝。**注意：bot 身份仅适用于读取类操作，所有写操作（发送、回复、转发、草稿编辑等）仅支持 user 身份。**
+- **`--as bot`**：以应用身份访问邮箱。需要在飞书开发者后台为应用开通相应权限，否则请求会被拒绝。bot 身份不能使用默认 `--mailbox me`，必须显式传邮箱地址。
 
-1. 所有邮件写操作（发送、回复、转发、草稿编辑） → 必须使用 `--as user`，未登录时先使用 `lark-cli auth login --domain mail` 进行登录
+1. 发信/草稿类写操作（发送、回复、转发、草稿编辑） → 必须使用 `--as user`，未登录时先使用 `lark-cli auth login --domain mail` 进行登录
 2. 读取类操作（查看邮件、会话、收件箱列表等） → 推荐使用 `--as user`；如需应用级批量读取（如管理员代操作），可使用 `--as bot`，确保应用已开通对应权限
+3. 整理类操作按具体 shortcut 的身份支持范围选择：message 级整理仍仅支持 `--as user`；会话级批量整理支持 `--as user` / `--as bot`，使用 bot 时必须显式传 `--mailbox <email>`
 
 ## 典型工作流
 
 1. **确认身份** — 首次操作邮箱前先调用 `lark-cli mail user_mailboxes profile --params '{"user_mailbox_id":"me"}'` 获取当前用户的真实邮箱地址（`primary_email_address`），不要通过系统用户名猜测。后续判断"发件人是否为用户本人"时以此地址为准。
 2. **浏览** — `+triage` 查看收件箱摘要，获取 `message_id` / `thread_id`
 3. **阅读** — `+message` 只读单封邮件；已有多个 `message_id` 时用 `+messages` 批量读取，不要循环调用 `+message`；`+thread` 读整个会话
-4. **整理** — 标签、已读/未读状态和移动文件夹优先用 `+message-modify`；软删除优先用 `+message-trash`
+4. **整理** — 标签、已读/未读状态和移动文件夹优先用 `+message-modify`；软删除优先用 `+message-trash`；会话级批量整理可用 `+thread-modify`，软删除会话可用 `+thread-trash`
 5. **回复** — `+reply` / `+reply-all`（默认存草稿，加 `--confirm-send` 则立即发送）
 6. **转发** — `+forward`（默认存草稿，加 `--confirm-send` 则立即发送）
 7. **新邮件** — `+send` 存草稿（默认），加 `--confirm-send` 发送
@@ -121,8 +124,10 @@ metadata:
 - 使用邮件模板：区分个人模板和静态 HTML 模板，发信类 shortcut 用 `--template-id` 套用模板。ref: [lark-mail-template](references/lark-mail-template.md)
 - 撤回已发送邮件：撤回邮件并查询异步撤回状态。ref: [lark-mail-recall](references/lark-mail-recall.md)
 - 修改邮件标签/已读状态/文件夹：优先使用 `+message-modify`。ref: [`+message-modify`](references/lark-mail-message-modify.md)
+- 修改会话标签/文件夹：使用 `+thread-modify`。ref: [`+thread-modify`](references/lark-mail-thread-modify.md)
 - 软删除邮件：优先使用 `+message-trash`。ref: [`+message-trash`](references/lark-mail-message-trash.md)
-- 收信规则：创建、验证、删除自动处理收到邮件的规则。ref: [lark-mail-rules](references/lark-mail-rules.md)
+- 软删除会话：已有 `thread_id` 时可使用 `+thread-trash`。ref: [`+thread-trash`](references/lark-mail-thread-trash.md)
+- 收信规则：查看、创建、更新、删除、启停、排序自动处理收到邮件的规则。ref: [lark-mail-rules](references/lark-mail-rules.md)
 - 分享邮件到 IM：分享邮件或会话到群聊、个人会话。ref: [lark-mail-share-to-chat](references/lark-mail-share-to-chat.md)
 - 发送日程邀请邮件：在邮件中嵌入 `text/calendar` 日程邀请。ref: [lark-mail-calendar-invite](references/lark-mail-calendar-invite.md)
 - 编写复杂 HTML 正文：复杂 HTML、本地图片、安全不确定时读取规范或运行 `+lint-html`；普通正文无需预读。ref: [lark-mail-html](references/lark-mail-html.md)
@@ -195,7 +200,7 @@ lark-cli mail +messages --message-ids <id1>,<id2>,<id3> --html=false
 
 ## 原生 API 调用规则
 
-没有 Shortcut 覆盖的操作才使用原生 API。标签、已读状态、移动文件夹优先使用 `+message-modify`；软删除优先使用 `+message-trash`。调用步骤以本节为准；资源和 method 用 `lark-cli mail -h` / `lark-cli mail <resource> -h` 发现，不在入口保留完整资源表。
+没有 Shortcut 覆盖的操作才使用原生 API。标签、已读状态、移动文件夹优先使用 `+message-modify`；软删除优先使用 `+message-trash`。会话或 thread ID 级标签/文件夹整理可使用 `+thread-modify`；软删除会话可使用 `+thread-trash`。调用步骤以本节为准；资源和 method 用 `lark-cli mail -h` / `lark-cli mail <resource> -h` 发现，不在入口保留完整资源表。
 
 ### Step 1 — 用 `-h` 确定要调用的 API（必须，不可跳过）
 
@@ -244,9 +249,13 @@ lark-cli mail <resource> <method> --params '{...}' [--data '{...}']
 **GET — 只有 `--params`**（`parameters` 中有 path + query，无 `requestBody`）：
 
 ```bash
-# schema 中：user_mailbox_id (path, required), page_size (query, required), folder_id (query, optional)
-lark-cli mail user_mailbox.messages list \
+# schema 中：user_mailbox_id (path, required), page_size (query, required)
+# user_mailbox.threads.list 要求 folder_id / label_id 必须且只能提供一个
+lark-cli mail user_mailbox.threads list \
   --params '{"user_mailbox_id":"me","page_size":20,"folder_id":"INBOX"}'
+
+lark-cli mail user_mailbox.threads list \
+  --params '{"user_mailbox_id":"me","page_size":20,"label_id":"FLAGGED"}'
 ```
 
 **POST — `--params` + `--data`**（`parameters` 中有 path，`requestBody` 有 body 字段）：
@@ -273,6 +282,8 @@ Shortcut 是对常用操作的高级封装（`lark-cli mail +<verb> [flags]`）
 | [`+message`](references/lark-mail-message.md) | Use only when reading full content for one email by one message ID. For multiple message IDs, use `mail +messages`; do not loop `mail +message`. |
 | [`+messages`](references/lark-mail-messages.md) | Use when reading full content for multiple emails by message ID. Accepts comma-separated message IDs; CLI handles more than 20 IDs in batches and merges output. |
 | [`+thread`](references/lark-mail-thread.md) | Use when querying a full mail conversation/thread by thread ID. Returns all messages in chronological order, including replies and drafts, with body content and attachments metadata, including inline images. |
+| [`+thread-modify`](references/lark-mail-thread-modify.md) | Modify existing mail threads by adding/removing label IDs or moving them to a folder. Batches thread IDs in groups of 20 and returns success_thread_ids / failed_thread_ids. |
+| [`+thread-trash`](references/lark-mail-thread-trash.md) | Soft-delete existing mail threads. Batches thread IDs in groups of 20 and returns success_thread_ids / failed_thread_ids. Requires --yes. |
 | [`+triage`](references/lark-mail-triage.md) | List mail summaries (date/from/subject/message_id). Use --query for full-text search, --filter for exact-match conditions. |
 | [`+watch`](references/lark-mail-watch.md) | Watch for incoming mail events via WebSocket (requires scope mail:event and bot event mail.user_mailbox.event.message_received_v1 added). Run with --print-output-schema to see per-format field reference before parsing output. |
 | [`+reply`](references/lark-mail-reply.md) | Reply to a message and save as draft (default). Use --confirm-send to send immediately after user confirmation. Sets Re: subject, In-Reply-To, and References headers automatically. |

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

@@ -8,7 +8,7 @@
 
 如需修改已有草稿，不要使用此命令，请使用 `lark-cli mail +draft-edit`。
 
-**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [references/lark-mail-html.md](references/lark-mail-html.md)，其中包含邮件书写规范**
+**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [lark-mail-html.md](lark-mail-html.md)，其中包含邮件书写规范**
 
 ## 安全约束
 

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

@@ -12,7 +12,7 @@
 
 **正文整体替换的快捷方式：** `--body <text>` / `--body-file <path>`（二选一互斥）会自动展开为 `set_body` op。如果只想做整段正文替换且不需要保留引用区，用这两个 flag 即可，无需写 patch-file。要保留引用区或做更精细的 op 组合，仍走 `--patch-file`。两个入口与 `--patch-file` 内的 `set_body` / `set_reply_body` 互斥。
 
-**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [references/lark-mail-html.md](references/lark-mail-html.md)，其中包含邮件书写规范**
+**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [lark-mail-html.md](lark-mail-html.md)，其中包含邮件书写规范**
 
 ## 正文编辑：快捷 flag 与 typed op 的选择
 

package/skills/lark-mail/references/lark-mail-forward.md

@@ -13,7 +13,7 @@
 
 ## CRITICAL — 发送工作流（必须遵循）
 
-**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [references/lark-mail-html.md](references/lark-mail-html.md)，其中包含邮件书写规范**
+**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [lark-mail-html.md](lark-mail-html.md)，其中包含邮件书写规范**
 
 此命令默认**只保存草稿**，不会发送邮件。转发会将原邮件内容发送给新收件人，需要发送时有两种合规方式：
 

package/skills/lark-mail/references/lark-mail-reply-all.md

@@ -13,7 +13,7 @@
 
 ## CRITICAL — 发送工作流（必须遵循）
 
-**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [references/lark-mail-html.md](references/lark-mail-html.md)，其中包含邮件书写规范**
+**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [lark-mail-html.md](lark-mail-html.md)，其中包含邮件书写规范**
 
 此命令默认**只保存草稿**，不会发送邮件。回复全部会发送给**所有**原始收件人，需要发送时有两种合规方式：
 

package/skills/lark-mail/references/lark-mail-reply.md

@@ -17,7 +17,7 @@
 
 ## CRITICAL — 发送工作流（必须遵循）
 
-**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [references/lark-mail-html.md](references/lark-mail-html.md)，其中包含邮件书写规范**
+**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [lark-mail-html.md](lark-mail-html.md)，其中包含邮件书写规范**
 
 此命令默认**只保存草稿**，不会发送邮件。需要发送时，有两种合规方式：
 

package/skills/lark-mail/references/lark-mail-rules.md

@@ -1,8 +1,90 @@
-# 收信规则
+# 收信规则 Shortcut
 
-管理自动处理收到邮件的规则。规则写操作需使用真实 `rule_id`，不要猜测 ID。规则写操作执行前需按 SKILL.md 的写操作确认规则获得用户确认。
+管理自动处理收到邮件的规则。优先使用 `mail +rule-*` shortcut，通过稳定英文 alias 编写条件和动作；只有需要当前 shortcut 尚未建模的服务端字段时，才回退到 `mail user_mailbox.rules` 原子 raw 命令。规则写操作需使用真实 `rule_id`，不要猜测 ID。创建、更新、删除规则需要按 SKILL.md 的高风险写规则获得用户确认并传 `--yes`；启停和排序是普通写操作，免 `--yes`。
 
-## 主题包含文本 → 标记为已读
+## 常用 shortcut
+
+```bash
+# 列出规则，输出 semantic_spec、description、unknowns
+lark-cli mail +rule-list --as user --user-mailbox-id me --format json
+
+# 查看单条规则
+lark-cli mail +rule-get --as user --user-mailbox-id me --rule-id "<rule_id>"
+
+# dry-run 创建：主题包含 Alpha 时标为已读，不产生服务端副作用
+lark-cli mail +rule-create --as user --dry-run \
+  --name "Alpha通知已读" \
+  --condition "subject:contains:Alpha" \
+  --action "mark_read"
+
+# 创建同一规则
+lark-cli mail +rule-create --as user \
+  --name "Alpha通知已读" \
+  --condition "subject:contains:Alpha" \
+  --action "mark_read" \
+  --yes
+
+# 更新规则：未传字段会先读当前规则并保留；传 --condition/--action 会替换对应完整集合
+lark-cli mail +rule-update --as user \
+  --rule-id "<rule_id>" \
+  --name "Alpha通知归档" \
+  --action "archive" \
+  --yes
+
+# 启停规则
+lark-cli mail +rule-disable --as user --rule-id "<rule_id>"
+lark-cli mail +rule-enable --as user --rule-id "<rule_id>"
+
+# 删除规则：真实删除必须显式 --yes；不确定时先 --dry-run
+lark-cli mail +rule-delete --as user --rule-id "<rule_id>" --dry-run
+lark-cli mail +rule-delete --as user --rule-id "<rule_id>" --yes
+
+# 调整顺序：完整顺序或单条移动二选一
+lark-cli mail +rule-reorder --as user --rule-ids "<rule_id_1>,<rule_id_2>,<rule_id_3>"
+lark-cli mail +rule-reorder --as user --move-rule-id "<rule_id_3>" --before-rule-id "<rule_id_1>"
+```
+
+## Alias 速查
+
+条件 grammar:
+
+```text
+--condition field:op:value
+--condition field:op
+--condition field
+```
+
+常用字段：`from`/`sender`、`to`/`recipient`、`cc`、`to_or_cc`、`subject`/`title`、`body`、`attachment_name`、`attachment_type`、`any_address`、`all_mail`/`all`、`external`、`spam`、`not_spam`、`has_attachment`。
+
+常用操作符：`contains`/`include`、`not_contains`/`exclude`、`starts_with`/`prefix`、`ends_with`/`suffix`、`equals`/`eq`/`is`、`not_equals`/`ne`、`contains_self`/`self`、`empty`/`is_empty`。
+
+动作 grammar:
+
+```text
+--action kind
+--action kind:key=value
+--action kind:json={"key":"value"}
+```
+
+常用动作：`archive`、`delete_mail`/`trash`、`mark_read`/`read`、`move_spam`/`spam`、`not_spam`/`never_spam`、`star`/`flag`、`mute_notification`/`mute`、`move_folder:folder_id=<id>`。
+
+`--conditions` / `--actions` 支持 JSON 或 `@file`。JSON 示例：
+
+```json
+[
+  {"field":"subject","operator":"contains","value":"Alpha"},
+  {"field":"has_attachment"}
+]
+```
+
+## Unknown raw 策略
+
+- 读路径宽容：`+rule-list` / `+rule-get` 遇到未知枚举或扩展字段仍输出规则，`unknowns[]` 会说明无法识别的 raw 片段，`raw` 会保留原始规则。
+- 更新规则：`+rule-update` 是“传什么改什么”。只改名称、启停、match 或 stop-after-match 时保留未触碰的 raw；传入新的 `--condition(s)` 时替换 condition items，未传 `--match` 就保留当前 match_type；传入新的 `--action(s)` 时替换 action items。
+- 输入校验：用户输入 alias/语义字符串时必须能映射到当前 shortcut 支持的枚举，否则报错；用户直接输入当前 shortcut 不认识的枚举数字，也报错。
+- raw fallback：需要写入当前 shortcut 尚未建模的服务端字段时，读取 `raw` 后使用原子 `user_mailbox.rules` 命令。
+
+## 原子 raw fallback：主题包含文本 → 标记为已读
 
 ```bash
 # 1. 创建规则：主题包含指定文本时标记为已读
@@ -16,7 +98,8 @@ lark-cli mail user_mailbox.rules list --as user \
 
 # 3. 删除规则
 lark-cli mail user_mailbox.rules delete --as user \
-  --params '{"user_mailbox_id":"me","rule_id":"<rule_id>"}'
+  --params '{"user_mailbox_id":"me","rule_id":"<rule_id>"}' \
+  --yes
 ```
 
 Quick codes above: condition `type=6` = subject, `operator=1` = contains, action `type=3` = mark as read.

package/skills/lark-mail/references/lark-mail-send.md

@@ -12,7 +12,7 @@
 
 ## CRITICAL — 发送工作流（必须遵循）
 
-**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [references/lark-mail-html.md](references/lark-mail-html.md)，其中包含邮件书写规范**
+**CRITICAL - 编辑邮件内容前 MUST 先用 Read 工具读取 [lark-mail-html.md](lark-mail-html.md)，其中包含邮件书写规范**
 
 此命令默认**只保存草稿**，不会发送邮件。需要发送时，有两种合规方式：
 

package/skills/lark-mail/references/lark-mail-thread-modify.md

@@ -0,0 +1,73 @@
+# mail +thread-modify
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+如果操作对象是具体邮件 `message_id`，不是整个会话，使用 [`mail +message-modify`](./lark-mail-message-modify.md)。
+
+## 命令
+
+```bash
+# 给多个会话添加未读标签
+lark-cli mail +thread-modify --thread-ids <thread_id1>,<thread_id2> --add-label-ids unread
+
+# 移除星标标签
+lark-cli mail +thread-modify --thread-ids <thread_id> --remove-label-ids FLAGGED
+
+# 归档会话
+lark-cli mail +thread-modify --thread-ids <thread_id> --add-folder archive
+
+# 指定公共邮箱或共享邮箱
+lark-cli mail +thread-modify --mailbox shared@example.com --thread-ids <thread_id> --add-folder folder_xxx
+
+# 使用 bot 身份时必须显式指定邮箱
+lark-cli mail +thread-modify --as bot --mailbox user@example.com --thread-ids <thread_id> --add-folder archive
+
+# Dry Run：只预览请求，不执行
+lark-cli mail +thread-modify --thread-ids <thread_id> --add-label-ids custom_label_id --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--mailbox <email>` | 否 | 会话所属邮箱，默认 `me`；使用 `--as bot` 时必须显式传邮箱地址 |
+| `--thread-ids <ids>` | 是 | 会话 ID 列表，支持逗号分隔和重复传参；超过 20 个时自动分批提交 |
+| `--add-label-ids <ids>` | 否 | 要添加的标签 ID。系统标签可传 `unread` / `important` / `other` / `flagged`；自定义标签传标签 ID |
+| `--remove-label-ids <ids>` | 否 | 要移除的标签 ID。不能与 `--add-label-ids` 传入重复标签 |
+| `--add-folder <id>` | 否 | 要移动到的文件夹。系统文件夹可传 `inbox` / `sent` / `spam` / `archive` / `archived`；自定义文件夹传文件夹 ID |
+
+`--add-label-ids`、`--remove-label-ids`、`--add-folder` 至少传一个。
+
+`TRASH` 不允许通过本 shortcut 作为目标文件夹传入。需要软删除会话时，使用 [`mail +thread-trash`](./lark-mail-thread-trash.md)，并在用户确认后加 `--yes` 执行。
+
+`READ_RECEIPT_REQUEST` / `read_receipt_request` 不允许通过本 shortcut 添加或移除。已读回执请求必须先读取具体 message、确认用户意图，再使用 [`mail +send-receipt`](./lark-mail-send-receipt.md) 或 [`mail +decline-receipt`](./lark-mail-decline-receipt.md)。
+
+## 注意事项
+
+- `thread_id` 必须来自 `+triage`、`+message`、`+thread`、会话列表或搜索等真实查询结果；不要用数字主键或占位符。
+- 命令在本地解析逗号分隔和重复 flag，按首次出现顺序去重，并按 20 个一批提交。
+- 单个 batch 请求失败时，该批次的所有 `thread_id` 都记录为同一个失败原因；后续批次继续执行。
+
+## 返回值
+
+返回示例：
+
+```json
+{
+  "success_thread_ids": ["thread_id1"],
+  "failed_thread_ids": [
+    {"thread_id": "thread_id2", "reason": "api error"}
+  ]
+}
+```
+
+## 原生 API 适用场景
+
+只有在需要精确复现后端/API 行为做诊断，或需要 shortcut 未暴露的请求结构时，才直接调用 `mail user_mailbox.threads batch_modify`。普通会话整理优先使用本 shortcut，因为它内置了 ID 校验、分批、批量输出和 dry-run 预览。
+
+## 相关命令
+
+- `lark-cli mail +triage` — 浏览邮件摘要，获取 `thread_id`
+- `lark-cli mail +thread` — 读取完整会话
+- `lark-cli mail +message-modify` — 按 `message_id` 修改具体邮件
+- `lark-cli mail +thread-trash` — 按 `thread_id` 软删除会话

package/skills/lark-mail/references/lark-mail-thread-trash.md

@@ -0,0 +1,62 @@
+# mail +thread-trash
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+已有 `thread_id` 且要按会话维度软删除邮件时，优先使用 `mail +thread-trash`。执行前必须先拿到真实 `thread_id`，并让用户确认删除预览。
+
+如果操作对象是具体邮件 `message_id`，不是整个会话，使用 [`mail +message-trash`](./lark-mail-message-trash.md)。
+
+## 命令
+
+```bash
+# 软删除多个会话
+lark-cli mail +thread-trash --thread-ids <thread_id1>,<thread_id2> --yes
+
+# 指定公共邮箱或共享邮箱
+lark-cli mail +thread-trash --mailbox shared@example.com --thread-ids <thread_id> --yes
+
+# 使用 bot 身份时必须显式指定邮箱
+lark-cli mail +thread-trash --as bot --mailbox user@example.com --thread-ids <thread_id> --yes
+
+# Dry Run：只预览请求，不执行
+lark-cli mail +thread-trash --thread-ids <thread_id1> --thread-ids <thread_id2> --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--mailbox <email>` | 否 | 会话所属邮箱，默认 `me`；使用 `--as bot` 时必须显式传邮箱地址 |
+| `--thread-ids <ids>` | 是 | 会话 ID 列表，支持逗号分隔和重复传参；超过 20 个时自动分批提交 |
+| `--yes` | 执行时必填 | 高风险写操作确认。只有用户确认删除预览后才加 |
+
+## 注意事项
+
+- `thread_id` 必须来自 `+triage`、`+message`、`+thread`、会话列表或搜索等真实查询结果；不要用数字主键或占位符。
+- 软删除属于高风险写操作。先用真实查询结果展示删除预览，包括受影响会话数量和关键邮件摘要；用户确认后再执行并加 `--yes`。
+- 命令在本地解析逗号分隔和重复 flag，按首次出现顺序去重，并按 20 个一批提交。
+- 单个 batch 请求失败时，该批次的所有 `thread_id` 都记录为同一个失败原因；后续批次继续执行。
+
+## 返回值
+
+返回示例：
+
+```json
+{
+  "success_thread_ids": ["thread_id1"],
+  "failed_thread_ids": [
+    {"thread_id": "thread_id2", "reason": "api error"}
+  ]
+}
+```
+
+## 原生 API 适用场景
+
+只有在需要精确复现后端/API 行为做诊断时，才直接调用 `mail user_mailbox.threads batch_trash`。普通会话软删除优先使用本 shortcut，因为它内置了 ID 校验、分批、批量输出、dry-run 预览和 `--yes` 确认。
+
+## 相关命令
+
+- `lark-cli mail +triage` — 浏览邮件摘要，获取 `thread_id`
+- `lark-cli mail +thread` — 读取完整会话
+- `lark-cli mail +message-trash` — 按 `message_id` 软删除具体邮件
+- `lark-cli mail +thread-modify` — 按 `thread_id` 修改会话标签或移动文件夹

package/skills/lark-mail/references/lark-mail-watch.md

@@ -91,4 +91,4 @@ lark-cli mail +watch --print-output-schema
 
 - [lark-mail](../SKILL.md) — 邮箱域总览
 - [lark-mail-triage](lark-mail-triage.md) — 邮件摘要列表
-- [lark-event-subscribe](../../lark-event/references/lark-event-subscribe.md) — 通用事件订阅
+- [lark-event](../../lark-event/SKILL.md) — 通用事件订阅

package/skills/lark-meeting/SKILL.md

@@ -50,7 +50,7 @@ Calendar 日程 ──meeting_note────────────► Doc（
 │
 └── 录制 ──► Minutes 妙记 (minute_token)
                  ├── AI 产物：Summary / Todo / Chapter / Keyword
-                 ├── Transcript（文字记录）
+                 ├── Transcript（文字记录，别名：「转写」「逐字稿」「文字记录」）
                  └── 原始音视频
 
 本地音视频 ─────────────────────────────► Minutes 妙记 (minute_token)
@@ -61,7 +61,7 @@ Calendar 日程 ──meeting_note────────────► Doc（
 | Calendar 日程 | `event_id` | 日历上的日程，包含时间、参与人、会议室和 RSVP，可预约或关联 VC 会议；不是完整的会议记录。日程上的 `meeting_note` 是用户手工绑定的 Doc，与 AI 智能纪要无关。 |
 | Meeting 会议 | `meeting_id` | 实际发生的视频会议，可以来自 Calendar，也可以是没有日程的即时会议。会议主题、时间、参会人快照和会中事件属于会议数据；Note 与 Minutes 是它可能关联的会后产物。 |
 | Note 智能纪要 | `note_id` | 开启 AI 总结后形成的逻辑产物集合。`note_display_type` 决定获取逐字稿中文字记录的不同方式。 |
-| Minutes 妙记 | `minute_token` | 由会议录制或本地音视频上传生成，包含总结、待办、章节、关键词、文字记录和原始音视频；可以关联 VC 会议，也可以独立存在。 |
+| Minutes 妙记 | `minute_token` | 由会议录制或本地音视频上传生成，包含总结、待办、章节、关键词、文字记录(别名：「转写」「逐字稿」「文字记录」)和原始音视频；可以关联 VC 会议，也可以独立存在。 |
 | Doc 文档 | Doc token | 内容载体，不是会议标识。`note_doc_token`、`shared_doc_tokens` 和部分 `verbatim_doc_token` 指向 Doc；Doc token 不能当作 `note_id` 或 `meeting_id`。 |
 
 ### 核心标识

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

@@ -67,8 +67,8 @@ lark-cli minutes +search --query "预算复盘" --format json
 | 参数                        | 必填 | 说明                                   |
 | ------------------------- | -- | ------------------------------------ |
 | `--query <text>`          | 否  | 搜索关键词                                |
-| `--owner-ids <ids>`       | 否  | 所有者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
-| `--participant-ids <ids>` | 否  | 参与者 open\_id 列表，逗号分隔；支持传 `me` 表示当前用户 |
+| `--owner-ids <ids>`       | 否  | 所有者 open\_id 列表，逗号分隔；多值为 OR 语义；支持传 `me` 表示当前用户 |
+| `--participant-ids <ids>` | 否  | 参与者 open\_id 列表，逗号分隔；多值为 OR 语义；支持传 `me` 表示当前用户 |
 | `--start <time>`          | 否  | 开始时间（ISO 8601 或仅日期）                  |
 | `--end <time>`            | 否  | 结束时间（ISO 8601 或仅日期）                  |
 | `--page-size <n>`         | 否  | 每页数量，默认 `15`，最大 `30`                 |

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

@@ -112,7 +112,7 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token
 - 如果上下文没有明确 `meeting_id`，先按用户当前意图选择身份：问“我/当前用户所在会议”用 `lark-cli vc +meeting-list-active --as user --format json`；问“应用机器人可见的目标用户会议”用 `lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json`。返回多个会议时先让用户选择。
 - 如果上下文只有 9 位会议号，先按当前身份执行 `+meeting-list-active` 并按 `meeting_no` 匹配；匹配到唯一会议后再查事件。不要为了总结会议而自动调用 `+meeting-join`。
 - 确认 `meeting_id` 后，沿用其来源身份执行 `lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty` 拉取最新事件流。
-- 如果事件流显示开始共享内容（JSON 事件类型为 `magic_share_started`，pretty 时间线显示“开始共享”），并包含文档标题或 URL 等线索，必须继续读取共享文档内容后再生成总结，不能只根据共享事件和文档标题概括会议内容。
+- 如果事件流显示共享内容（JSON 事件类型为 `magic_share_started`；pretty 时间线按 `start_reason` 显示“开始共享”或“正在共享”），并包含文档标题或 URL 等线索，必须继续读取共享文档内容后再生成总结，不能只根据共享事件和文档标题概括会议内容。
 - 若存在多个共享文档，按用户问题读取相关文档；处理某条文档上下文事件时必须按该 item 的 `share_id` 精确关联，不能用“最近一次共享”替代。
 - 若文档读取失败，必须明确说明“以下总结仅基于会中事件流，未成功读取共享文档内容”。
 
@@ -134,6 +134,7 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token
 | 路径 | 含义与处理 |
 | --- | --- |
 | `payload.magic_share_started_items[].share_id/share_doc` | 建立一次共享会话与文档 URL/title 的映射。缺 `share_id` 时不建立映射。 |
+| `payload.magic_share_started_items[].start_reason` | `share_started` 或缺失表示真实开始；`share_detected` 表示开启 Agent 入会能力时发现已有共享。两者都建立共享映射。 |
 | `payload.magic_share_ended_items[].share_id` | 结束同一 `share_id` 的共享会话；不得结束其他映射。 |
 | `payload.document_context_changed_items[]` | 结构化消费按原序读取；pretty timeline 沿用统一时间排序。每项恰有一个已知 context 才生成 pretty 条目，未知/歧义项只保留 raw。 |
 | `item.operator` | 当前 item 的 actor；缺 ID/name 时不猜共享发起人。 |
@@ -249,7 +250,7 @@ lark-cli drive +list-replies \
 | `participant_left` | 有参会人离开会议 |
 | `chat_received` | 收到会中聊天消息 |
 | `transcript_received` | 收到转写文本 |
-| `magic_share_started` | 开始共享内容 / 文档 |
+| `magic_share_started` | 开始共享，或开启 Agent 入会能力时发现已有共享；由 `start_reason` 区分 |
 | `magic_share_ended` | 结束共享 |
 | `document_context_changed` | 评论聚焦、章节定位或元素预览上下文变化 |
 | `countdown_changed` | 会中倒计时被设置、延长、提前结束、关闭窗口，或自然结束、临近提醒 |

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

@@ -1,7 +1,7 @@
 
 # vc +search
 
-搜索已结束的历史会议记录，支持关键词、时间范围、组织者、参与者、会议室多条件过滤。只读，仅 `--as user`。
+搜索已结束的历史会议记录，支持关键词、时间范围、组织者、参与者、会议室多条件过滤。只读，支持 `--as user` / `--as bot`。
 
 ## 关键词使用边界
 
@@ -28,6 +28,7 @@ lark-cli vc +search --query "周会"
 
 # 通过 9 位会议号查询会议 ID
 lark-cli vc +search --query "123456789" --format json --as user
+lark-cli vc +search --query "123456789" --format json --as bot
 
 # 查询某一天开过的会（单日查询时，start 和 end 必须填写同一天）
 lark-cli vc +search --start 2026-03-10 --end 2026-03-10
@@ -54,9 +55,9 @@ lark-cli vc +search --query "周会" --page-token "<PAGE_TOKEN>"
 | `--query <text>` | 否 | 9 位会议号或搜索关键词 |
 | `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期） |
 | `--end <time>` | 否 | 结束时间（ISO 8601 或仅日期） |
-| `--organizer-ids <ids>` | 否 | 组织者 open_id 列表，逗号分隔 |
-| `--participant-ids <ids>` | 否 | 参与者 open_id 列表，逗号分隔 |
-| `--room-ids <ids>` | 否 | 会议室 ID 列表，逗号分隔 |
+| `--organizer-ids <ids>` | 否 | 组织者 open_id 列表，逗号分隔；多值为 OR 语义 |
+| `--participant-ids <ids>` | 否 | 参与者 open_id 列表，逗号分隔；多值为 OR 语义 |
+| `--room-ids <ids>` | 否 | 会议室 ID 列表，逗号分隔；多值为 OR 语义 |
 | `--page-size <n>` | 否 | 每页数量，默认 `15`，最大 `30` |
 | `--page-token <token>` | 否 | 翻页标记，用于获取下一页 |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
@@ -75,9 +76,11 @@ lark-cli vc +search --query "周会" --page-token "<PAGE_TOKEN>"
 
 `vc +search` 只能搜索已结束的历史会议记录，不用于查询未来日程。查询未来会议安排请使用 [lark-calendar](../../lark-calendar/SKILL.md)。
 
-### 3. 仅支持 user 身份
+### 3. 支持 user 和 bot 身份
 
-该接口仅支持 `user` 身份，使用前需完成 `lark-cli auth login` 并具备 `vc:meeting.search:read` 权限。
+该接口支持 `--as user` 和 `--as bot`。user 身份需要完成 `lark-cli auth login` 并具备 `vc:meeting.search:read` 权限；bot 身份使用应用的 tenant access token，需要确认当前应用已开通 `vc:meeting.search:read` scope，且运行环境能获取有效的 TAT。
+
+搜索得到 `meeting_id` 后，后续 `vc +detail`、`vc +recording`、`vc meeting get` 和 `note +detail` 必须显式沿用本次搜索使用的身份。不要为了绕过权限错误自动切换身份。
 
 ### 4. 支持分页
 
@@ -131,7 +134,7 @@ lark-cli vc +search --query "周会" --page-size 15 --page-token "<PAGE_TOKEN>"
 | 命令直接报错，要求提供过滤条件 | 没有传入 `--query`、时间范围或任何过滤 ID | 至少补充一个过滤条件后重试 |
 | 时间参数校验失败 | `--start` 或 `--end` 格式不合法 | 改用 ISO 8601 或 `YYYY-MM-DD` |
 | 搜不到未来会议 | `vc +search` 只查历史会议 | 改用 [lark-calendar](../../lark-calendar/SKILL.md) 查询未来日程 |
-| 权限不足 | 未授权 `vc:meeting.search:read` | 使用 `auth login` 完成授权 |
+| 权限不足 | 未授权 `vc:meeting.search:read` | `--as user`：按提示完成用户授权；`--as bot`：检查 tenant access token 和应用 scope，不要执行 `auth login` |
 
 ## 提示
 - 必须使用 `--format json` 输出，便于稳定解析。

package/skills/lark-meeting/scenes/create-and-edit-minutes.md

@@ -72,6 +72,10 @@ lark-cli minutes +todo --minute-token <token> --operation add|update|delete ...
 
 ## 批量替换逐字稿关键词
 
+`+word-replace` 修改的是妙记「转写／逐字稿／文字记录」中的字面词条（同一产物的不同叫法）。
+
+`--minute-token` 必须是妙记 token（例如 `obcn...`），合法输入只有两种：`minutes +search` / `vc +recording` 等接口返回的 `token` 字段，或从妙记 URL 里提取最后一段路径并去掉 query 参数后的裸 token。禁止直接传妙记标题、URL 里的 slug、会议主题或完整妙记 URL；不确定时先跑 `minutes +search` / `vc +recording` 拿到 `minute_token` 再执行替换。
+
 ```bash
 lark-cli minutes +word-replace --minute-token <token> --replace-words '[{"source_word":"<old>","target_word":"<new>"}]' --as user
 ```

package/skills/lark-meeting/scenes/query-meeting-and-artifacts.md

@@ -15,7 +15,7 @@
 | 已有信息 | 操作 |
 |---|---|
 | `meeting_id` | 直接查询会议或关联产物 |
-| `meeting_no` / 9 位会议号 | 用 `vc +search --query "<meeting_no>" --format json --as user` 搜索会议，从结果的 `id` 取得 `meeting_id` |
+| `meeting_no` / 9 位会议号 | 用 `vc +search --query "<meeting_no>" --format json --as <source_identity>` 搜索会议，从结果的 `id` 取得 `meeting_id` |
 | Calendar `event_id` | 用 `calendar +meeting` 获取 `meeting_id` 和用户绑定的 `meeting_note` |
 | `note_id` | 直接进入 [智能纪要场景](query-note-and-artifacts.md) |
 | `minute_token` / 妙记 URL | 直接进入 [妙记场景](query-minutes-and-artifacts.md)；URL 取路径最后一段并去掉 query 参数 |
@@ -23,7 +23,7 @@
 没有标识时，用 `vc +search` 搜索已经结束的会议：
 
 ```bash
-lark-cli vc +search --query <query> --start <start> --end <end> --format json
+lark-cli vc +search --query <query> --start <start> --end <end> --format json --as <source_identity>
 ```
 
 - 至少提供关键词、时间范围、组织者、参与者或会议室中的一个条件；不要把“总结”“回顾”“所有会议”等动作词当作 `--query`。
@@ -38,7 +38,7 @@ lark-cli vc +search --query <query> --start <start> --end <end> --format json
 
 ## 选择查询身份
 
-- `vc +search` 仅支持用户身份。`vc +detail`、`vc +recording`、`vc meeting get` 和 `note +detail` 支持用户或应用身份。
+- `vc +search`、`vc +detail`、`vc +recording`、`vc meeting get` 和 `note +detail` 均支持用户或应用身份。没有既有身份上下文时默认使用用户身份；用户明确要求应用视角或当前链路已经使用应用身份时，使用 `--as bot`。
 - 已有 `meeting_id`、`note_id` 或 `minute_token` 时，沿用其来源身份；后续 Minutes、Note、Doc 和 Drive 命令都显式传入同一个 `--as`。不要为查询参会人或绕过权限错误擅自切换身份。
 - `note +transcript` 仅支持用户身份。应用身份查到 unified Note 时，先说明限制，只有用户明确同意后才切换身份。
 

package/skills/lark-sheets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-sheets
-version: 3.1.8
+version: 3.1.9
 description: "飞书电子表格：创建和操作电子表格。支持创建表格、管理工作表与行列结构（增删/合并/调整尺寸/隐藏/冻结）、读写单元格（值/公式/样式/批注/单元格图片）、查找替换、多操作批量更新，以及图表、透视表、条件格式、筛选器、迷你图、浮动图片等对象的创建与维护。当用户需要创建电子表格、管理工作表、批量读写或编辑数据、统计汇总与可视化、表格美化、公式计算（含 Excel 公式迁移）、金融/财务建模（DCF、三张表、预算、Sensitivity 等）等任务时使用。若用户是想按名称或关键词搜索云空间（云盘/云存储）里的表格文件，请改用 lark-drive 的 drive +search 先定位资源。当用户给出 doubao.com 的 /sheets/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
@@ -217,6 +217,8 @@ lark-cli sheets +csv-get --url "https://.../sheets/shtXXX" --sheet-name "<真实
 | `--print-schema` | bool | 否 | 本地打印复合 JSON flag 的 JSON Schema 并退出，不发起调用、不需要其它 required flag。搭配 `--flag-name` 指定查哪个 flag；省略时列出该 shortcut 可查询的 flag。仅对含复合 JSON flag 的 shortcut 有效。 |
 | `--flag-name` | string | 否 | 配合 `--print-schema`：flag 名不带 `--` 前缀（`cells` / `properties`）。**支持点分路径切片**：`--flag-name properties.snapshot.plotArea.axes` 只打印该子树，大 schema（chart 的 properties 约 1700 行）按需取，别整篇翻页。 |
 
+> **bool flag 语法**：开启可用裸 `--flag`；显式值只用 `--flag=true` 或 `--flag=false`，不得用空格分隔。
+
 > ⚠️ **high-risk-write 命令清单（exit 10 强确认门禁）**：`+batch-update`、`+cells-clear`、`+cells-batch-clear`、`+sheet-delete`、`+dim-delete`、`+dropdown-delete`，以及各对象删除 `+chart-delete` / `+pivot-delete` / `+cond-format-delete` / `+filter-delete` / `+filter-view-delete` / `+sparkline-delete` / `+float-image-delete`。
 >
 > **审批协议**：先 `--dry-run` 预览、向用户展示将执行的操作与影响范围，**获得用户明确同意后**再在原命令追加 `--yes` 执行。未经用户同意不得带 `--yes`，也不得在 exit 10 后静默补 `--yes` 重试——那等于禁用门禁。完整协议见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。