@amaster.ai/pi-lark 0.1.14 → 0.1.15

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

@@ -16,28 +16,22 @@
 | 参数 | 必填 | 用法 |
 |-|-|-|
 | `--command init-draft` | 是 | 选择本脚本。 |
-| `--presentation-decision` | 是 | 完整决策 JSON；接受内联 JSON、`@./decision.json` 形式的 CWD 下相对路径或 `-`（stdin）。 |
+| `--presentation-decision` | 是 | 决策 JSON；接受内联 JSON、`@相对或绝对路径` 或 `-`（stdin）。 |
 
 ```bash
 lark-cli docs +script --command init-draft \
-  --presentation-decision '<完整 Presentation Decision JSON>' \
+  --presentation-decision '{}' \
   --format json
 ```
 
-`data` 的结构如下；实际随机段为 8 位十六进制字符：
-
-```json
-{
-  "workspace": "draft_a1b2c3d4_folder",
-  "draft_path": "draft_a1b2c3d4_folder/draft.xml",
-  "tip": "The workspace directory has been created successfully. draft_path points to a new XML file that does not exist yet. Create and write the file directly without reading it first."
-}
-```
+路径返回值与用法见 [创建工作流 Step 4](lark-doc-create-workflow.md)。
 
 - 在生成正文前执行；不要自行创建工作目录或决策文件。CLI 固定生成 `draft_<8位十六进制字符>_folder/draft.xml`，以返回的实际路径为准。
-- 决策必须是单个 JSON 对象，包含 `audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode` 和 `visual_plan`。`presentation_mode` 取 `formal|normal|rich`；`genre_contract`、`adapter` 使用固定短名、`"none"` 或 `null`。
-- `visual_plan` 包含非空 `reason` 和 `blocks` 数组；每项为 `{type,min_count,purpose}`，`type` 不重复，`min_count` 为正整数。按本 Skill 创建文档时，`blocks` 只对 `whiteboard`、`img`、`html5-block` 设置最低数量，其他表达按内容需要使用但不设数量约束；三类均无需约束时写 `[]`。CLI 为外部决策兼容 `type: "list"`，检查时将 `<ul>` 与 `<ol>` 的数量相加。仅有字数要求时添加 `word_count: {min,max}`；未指定的一侧写 `null`，至少一侧为正整数，且 `min <= max`。
-- 返回 `data.workspace`（已创建的随机工作区）、`data.draft_path`（可直接写入的 XML 路径）和英文操作提示 `data.tip`。工作区及其中的 `.presentation-decision.json` 已存在，但 XML 尚不存在；遵循提示直接使用文件创建/写入能力在 `draft_path` 写入完整 XML，首次写入前不要读取该路径。
+- 决策是单个 JSON 对象；无可量化约束时传 `{}`。`audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode`、`visual_plan.reason` 和每个 block 的 `purpose` 是可选描述信息，可省略、为空字符串或 `null`；不参与通过/失败判定。
+- `visual_plan`、`visual_plan.blocks`、每项的 `type` 和 `min_count` 都可省略或为 `null`，表示未设置。`blocks` 写 `[]` 也表示无数量约束；条目缺少 `type` 或 `min_count` 时，不启用该条数量校验。
+- 显式填写的字段仍须合法：`visual_plan` 为对象，`blocks` 为数组，`type` 为支持的块类型，`min_count` 为正整数。空字符串类型、未知块类型、零/负数或非整数数量会报错，即使另一字段缺失也一样。仅 `type` 与 `min_count` 都有效的条目参与数量检查；启用的条目不能重复声明同一类型。兼容的 `list` 约束按 `<ul>` 与 `<ol>` 的合计数量检查。
+- `word_count` 仅在需要字数校验时填写 `{min,max}`；未指定的一侧写 `null`，至少一侧为正整数，且 `min <= max`。没有字数要求时省略整个字段。
+- 返回 `data.cwd`（本次文件操作的绝对工作目录）、`data.workspace`（相对工作区）、`data.draft_path`（相对 XML 路径）和操作提示 `data.tip`。工作区及其中的 `.presentation-decision.json` 已存在，XML 尚不存在；直接写入 `<cwd>/<draft_path>`，首次写入前不要读取该路径。后续 CLI 使用返回的 `cwd`；资源路径规则见 [lark-doc](../SKILL.md)。
 - 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；保留 `workspace` 及其中的创作草稿。
 
 ## `parse`
@@ -47,9 +41,9 @@ lark-cli docs +script --command init-draft \
 | 参数 | 必填 | 用法 |
 |-|-|-|
 | `--command parse` | 是 | 选择本脚本。 |
-| `--content` | 二选一 | 本地 XML 的字面内容、`@./document.xml` 形式的 CWD 下相对路径或 `-`（stdin）。 |
+| `--content` | 二选一 | 本地 XML 的字面内容、`@相对或绝对路径` 或 `-`（stdin）。 |
 | `--doc` | 二选一 | 在线 Docx/Wiki URL 或 token；与 `--content` 互斥。 |
-| `--presentation-decision` | 否 | 用于检查当前输入的完整决策 JSON；支持内联、`@./decision.json` 形式的 CWD 下相对路径或 `-`。 |
+| `--presentation-decision` | 否 | 用于检查当前输入的决策 JSON；支持内联、`@相对或绝对路径` 或 `-`。 |
 
 ```bash
 lark-cli docs +script --command parse --content "@./document.xml" --format json
@@ -58,7 +52,7 @@ lark-cli docs +script --command parse --content "@./document.xml" --presentation
 ```
 
 - `--content` 与 `--presentation-decision` 同时使用时，最多一个参数读取 stdin。
-- 决策必须包含 `audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode` 和 `visual_plan`；`presentation_mode` 取 `formal|normal|rich`。`visual_plan` 包含非空 `reason` 和不重复的 `{type,min_count,purpose}` 数组；兼容的 `list` 约束按 `<ul>` 与 `<ol>` 的合计数量检查。仅有字数要求时添加合法的 `word_count: {min,max}`。
+- 决策格式同 `init-draft`：缺失的约束不检查，显式填写但非法的值报错，合法且完整的约束参与检查。`passed` 只表示本次启用的检查通过，不代表未声明的要求已满足。
 - 使用 `--content "@./<init-draft 返回的 data.draft_path>"` 时自动加载保存的决策；显式 `--presentation-decision` 优先。
 - `--doc` 需要 `docx:document:readonly`；`--content` 不调用 OpenAPI。
 - 返回 `data.assessment.status`、`data.profile` 和按需出现的 `data.diagnostics[]`；profile 包含 `word_count`、`char_count`、`block_count` 和 `blocks[]`。顶层 `ok` 只表示命令是否成功执行。画像、决策或资源预检未通过时，命令仍以 `ok:true` 和退出码 0 返回，但 `assessment.status` 为 `failed`；每条 diagnostic 提供 `severity`、稳定 `code`、`msg`、可选 `expected` / `actual` 和 `suggested`。同一原因失败的远程图片合并为一条 diagnostic，并在 `image_indices[]` 中列出图片序号，避免重复提示。修复后重新解析，直到 `assessment.status` 为 `passed`。

package/skills/lark-drive/references/lark-drive-inspect.md

@@ -46,7 +46,7 @@ JSON 输出包含以下字段：
 
 - `--url` 为必填参数
 - 当 `--url` 是 bare token（非完整 URL）时，`--type` 也是必填的
-- wiki URL 会自动调用 `get_node` API 解包，输出中 `type` 和 `token` 是底层文档的类型和 token
+- wiki URL 会自动调用 `node_by_token` API 解包，输出中 `type` 和 `token` 是底层文档的类型和 token
 - `+inspect` 只用于识别/消歧；如果任务已能通过 URL 路径形态完成路由判断，不必把它作为所有 Drive 操作的通用前置步骤
 - `+inspect` 失败后不要自动切到写接口继续尝试，先按错误提示处理权限、scope 或链接问题
 - 支持 `--dry-run` 查看将调用的 API 步骤

package/skills/lark-drive/references/lark-drive-permission-guide.md

@@ -39,7 +39,7 @@
 
 需要将文档权限授予当前应用（bot）自身时：
 
-1. 先执行 `lark-cli api GET /open-apis/bot/v3/info --as bot`，从返回值取 `bot.open_id`。
+1. 先执行 `lark-cli api GET /open-apis/bot/v3/info --as bot --jq '.data.open_id'`，直接取得当前应用的 `open_id`。
 2. 再调用 `lark-cli drive permission.members create`，用 `member_type=openid`、`member_id=<bot_open_id>` 授权。
 
 ```bash

package/skills/lark-im/SKILL.md

@@ -58,10 +58,16 @@ The raw `sender_name` is not duplicated in output (its value is in `name`); the
 
 The four message-pulling shortcuts (`+messages-mget`, `+chat-messages-list`, `+messages-search`, `+threads-messages-list`) automatically attach a `reactions` block and (for edited messages) `update_time` to each returned message — no separate `im.reactions.batch_query` call is needed. Pass `--no-reactions` to opt out. For the full contract (output shape, the `im:message.reactions:read` scope requirement, and the "missing field ≠ fetch failure" data rules), read [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
 
+### Compact message output (`--concise`)
+
+Some message-listing shortcuts support `--concise` for compact Markdown output. Use it when the user asks for concise output or a smaller result/file; check `--help` for availability and do not combine it with an explicit `--format`, an enabled `--json`, or a non-empty `--jq`.
+
 ### Opt-in resource auto-download (`--download-resources`)
 
 `+chat-messages-list`, `+messages-mget`, and `+threads-messages-list` accept `--download-resources` to save eligible attachments into `./lark-im-resources/` and add a `resources` array to each message. It is off by default; stickers are not downloadable. A failed attachment is reported on that resource without aborting the message pull. Use [`+messages-resources-download`](references/lark-im-messages-resources-download.md) for one attachment. See [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md) for the output contract.
 
+**Folder resources** are containers, not files — a folder `file_key` cannot be downloaded directly. Expand it first with `lark-cli im files folder --recursive --file-key <folder_key> --srctype message --srcid <message_id>`, then download the files inside with [`+messages-resources-download`](references/lark-im-messages-resources-download.md).
+
 ### Card Messages (Interactive)
 
 **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.
@@ -118,7 +124,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+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-resources-download`](references/lark-im-messages-resources-download.md) | Download an image/file from a message; folders are not directly downloadable — expand with `im files folder --recursive` first, then download the files inside; 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 |
 | [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
 | [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports --order asc/desc sorting, auto-pagination |

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

@@ -17,6 +17,9 @@ lark-cli im +chat-messages-list --chat-id oc_xxx
 # Get direct messages with a user (pass open_id and resolve p2p chat_id automatically)
 lark-cli im +chat-messages-list --user-id ou_xxx
 
+# Read message context as compact Markdown
+lark-cli im +chat-messages-list --chat-id oc_xxx --concise
+
 # Specify a time range (ISO 8601)
 lark-cli im +chat-messages-list --chat-id oc_xxx --start "2026-03-10T00:00:00+08:00" --end "2026-03-11T00:00:00+08:00"
 
@@ -51,6 +54,7 @@ lark-cli im +chat-messages-list --chat-id oc_xxx --format json
 | `--page-limit <n>` | No | Maximum pages fetched by `--page-all` (default 10, range 1-1000) |
 | `--no-reactions` | No | Skip auto-fetching the `reactions` block |
 | `--download-resources` | No | Download message resources (image/file/audio/video/media + post-embedded, excluding stickers) into `./lark-im-resources/` and attach a `resources` block. Off by default; no extra requests when omitted |
+| `--concise` | No | Render compact Markdown for message context |
 
 > Rule: `--chat-id` and `--user-id` are mutually exclusive. You must provide exactly one of them.
 
@@ -58,7 +62,7 @@ lark-cli im +chat-messages-list --chat-id oc_xxx --format json
 
 ## Resource Rendering
 
-Messages are rendered into human-readable text for inspection. Image messages are shown as placeholders such as `![Image](img_xxx)`; files, audio, and videos are rendered with resource keys in the content (e.g. `<audio key="file_xxx" duration="Xs"/>`). By default resource binaries are **not** downloaded.
+Messages are rendered into human-readable text for inspection. Image messages are shown as placeholders such as `![Image](img_xxx)`; files, audio, and videos are rendered with resource keys in the content (e.g. `<audio key="file_xxx" duration="Xs"/>`). `folder` messages are expanded one level (children rendered inside the tag, see the row below). By default resource binaries are **not** downloaded.
 
 Two ways to get the binaries:
 - **In one pass:** add `--download-resources` to this command — every eligible resource (image/file/audio/video/media + post-embedded, excluding stickers) is downloaded into `./lark-im-resources/` and a `resources` block (`{message_id, key, type, local_path, size_bytes}`) is attached to each message. See [message enrichment](lark-im-message-enrichment.md#resource-auto-download---download-resources-opt-in).
@@ -68,6 +72,7 @@ Two ways to get the binaries:
 |---------|-------------|------|
 | Image | `![Image](img_xxx)` | `--download-resources`, or manually `im +messages-resources-download --type image` |
 | File | `<file key="file_xxx" .../>` | `--download-resources`, or manually `im +messages-resources-download --type file` |
+| Folder (message) | `<folder key="file_xxx" name="assets" child_count="N"><file key="..." .../>…</folder>` (first-level children rendered inside; `has_more="true"` past the 10-item cap) | Folder itself is not a single-file resource; children are real files — download one with explicit `im +messages-resources-download --message-id <id> --file-key <child_key> --type file` (`--download-resources` auto-collection does not include folder children) |
 | Audio | `<audio key="file_xxx" duration="Xs"/>` | `--download-resources`, or manually `im +messages-resources-download --type file` |
 | Video | `<video key="file_xxx" .../>` | `--download-resources`, or manually `im +messages-resources-download --type file` |
 | Sticker | `[Sticker]` | Not downloadable (Feishu does not support fetching sticker resources) |

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, rendering first-level children inside the folder tag (to expand/download folder children yourself, follow the Folder resources note in [`lark-im`](../SKILL.md)):
+
+```
+<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-resources-download.md

@@ -51,6 +51,8 @@ Different resource markers in message content correspond to different `file_key`
 
 Stickers cannot be downloaded with this command.
 
+A folder itself cannot be downloaded: expand it with `lark-cli im files folder --recursive` first (see [lark-im](../SKILL.md)), then download the files it contains.
+
 ## Output
 
 On success, read:

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

@@ -31,6 +31,9 @@ lark-cli im +threads-messages-list --thread omt_xxx --format pretty
 lark-cli im +threads-messages-list --thread omt_xxx --format table
 lark-cli im +threads-messages-list --thread omt_xxx --format csv
 
+# Read thread context as compact Markdown
+lark-cli im +threads-messages-list --thread omt_xxx --concise
+
 # View as a bot
 lark-cli im +threads-messages-list --thread omt_xxx --as bot
 
@@ -51,6 +54,7 @@ lark-cli im +threads-messages-list --thread omt_xxx --dry-run
 | `--page-all` | No | Automatically fetch and merge subsequent pages; capped by `--page-limit` |
 | `--page-limit <n>` | No | Maximum pages fetched by `--page-all` (default 10, range 1-1000) |
 | `--format <fmt>` | No | Output format: `json` (default) / `pretty` / `table` / `ndjson` / `csv` |
+| `--concise` | No | Render compact Markdown for thread context |
 | `--as <identity>` | No | Identity type: `user` (default) / `bot` |
 | `--dry-run` | No | Print the request only, do not execute it |
 
@@ -100,7 +104,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` 修改会话标签或移动文件夹