@amaster.ai/pi-lark 0.1.2-beta.70 → 0.1.2-beta.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.2-beta.70",
+  "version": "0.1.2-beta.72",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -61,7 +61,7 @@
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.2-beta.70"
+    "@amaster.ai/pi-shared": "0.1.2-beta.72"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-base/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-base
-version: 1.2.21
+version: 1.2.22
 description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。"
 metadata:
   requires:
@@ -209,8 +209,9 @@ Form 依附于 Table，以 Field 作为题目，每次有效提交会创建一
 
 1. **读取 Table 中的表单配置：** 使用 `+form-list` / `+form-get` 读取表单，使用 `+form-questions-list` 读取题目配置；这些命令使用表单所属的 `base_token + table_id`。
 2. **创建或修改 Table 中的表单配置：** 使用 `+form-create` / `+form-update` / `+form-delete` 管理表单；题目由 Table Field 承载，question ID 对应 `field_id`，创建和更新分别读取 [questions create](references/lark-base-form-questions-create.md) / [questions update](references/lark-base-form-questions-update.md)，删除使用 `+form-questions-delete`。
-3. **管理表单分享：** 使用 `+form-share-get` / `+form-share-update` 管理启停、访问范围和匿名/登录要求；更新前先读取现状，每次只修改一个字段，布尔值显式传 `true` 或 `false`。
-4. **填写分享表单并提交：** 对表单分享链接使用 `+url-resolve` 取得 `share_token`，按 [Form detail](references/lark-base-form-detail.md) 执行 `+form-detail` 读取真实题目、必填项和显示条件，再按 [Form submit](references/lark-base-form-submit.md) 构造字段与附件并执行 `+form-submit`。
+3. **调整表单题目显隐和顺序：** Form 在 `visible_fields` 接口中作为 View，`form_id` 传给 `--view-id`。用 `+view-get-visible-fields` 读取当前可见题目，再用 `+view-set-visible-fields` 提交最终需要展示的完整有序题目 ID 列表；省略当前可见题目会隐藏它，加入已有隐藏 Form 成员会重新展示，空列表会隐藏全部题目。目标只能包含已有 Form 成员；仍显示题目的 `visible_rule` 只能引用位于它之前的可见题目。
+4. **管理表单分享：** 使用 `+form-share-get` / `+form-share-update` 管理启停、访问范围和匿名/登录要求；更新前先读取现状，每次只修改一个字段，布尔值显式传 `true` 或 `false`。
+5. **填写分享表单并提交：** 对表单分享链接使用 `+url-resolve` 取得 `share_token`，按 [Form detail](references/lark-base-form-detail.md) 执行 `+form-detail` 读取真实题目、必填项和显示条件，再按 [Form submit](references/lark-base-form-submit.md) 构造字段与附件并执行 `+form-submit`。
 
 表单题目和字段的关系：
 

package/skills/lark-base/references/lark-base-app.md

@@ -23,7 +23,7 @@
 当前 CLI 只支持用 `+workspace-move-in` 把 Base 或 BaseApp 移入 Workspace，不支持从 Workspace 移出或移除资源，也没有 `workspace move-out` / `workspace remove` 命令。这类请求必须先完成只读定位，再说明限制并停止，顺序不可调换：
 
 1. Workspace URL 含 `/base/workspace/<workspace_token>` 时，提取其中的真实 `workspace_token`，不要把完整 URL 当作命令参数。
-2. 在同一轮立即执行 `lark-cli base +workspace-entity-list --workspace-token <workspace_token> --page-size 100 --as user`；若 `has_more=true`，继续分页直到完整。该查询是必要的只读定位步骤，不要把它留成等待用户再次选择的可选项，也不要用 `--help` 代替真实查询。
+2. 在同一轮立即执行 `lark-cli base +workspace-entity-list --workspace-token <workspace_token> --page-size 30 --as user`；若 `has_more=true`，继续分页直到完整。该查询是必要的只读定位步骤，不要把它留成等待用户再次选择的可选项，也不要用 `--help` 代替真实查询。
 3. 用服务端返回的 `entities[].name`、`entity_type`、`token` 和 `url` 忠实判断目标。名称完全匹配时报告真实对象；没有完全匹配时明确说明不存在精确同名实体，并原样列出可能相关的候选。不得自动去掉或补齐前后缀，也不得仅凭名称相似就声称已经定位目标。用户直接给出 token 时仍要忠实报告该 token 对应的实际名称。
 4. 定位结果报告完后，明确说明当前 CLI 无法执行 Workspace 移出/移除，并停止，不要发起任何写请求。用户在任一步骤中取消时立即停止，取消后不再调用工具。
 
@@ -55,7 +55,7 @@ lark-cli base +app-get --app-token <app_token>
   lark-cli base +workspace-entity-list \
     --workspace-token <workspace_token> \
     --type baseapp \
-    --page-size 100
+    --page-size 30
   ```
 
 - 响应中的 `pages` 是页面摘要。

package/skills/lark-base/references/lark-base-dashboard-block-config.md

@@ -224,7 +224,7 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
   - `group_by[].sort.type` 为 `group` 或 `view` 且缺少 `order` 时，自动补 `order:"asc"`；`value` 排序不会自动补方向
 - 本地校验（可通过 `--no-validate` 跳过）
   - `+dashboard-block-create` 默认对 `data_config` 做轻量校验；失败会聚合错误并给出修复建议
-  - `+dashboard-block-update` 不带 `--type`，所以不做按组件类型的强校验，字段由后端验证；但 `number_format` 子字段与 create 一样本地拦截（见下方 number_format 小节）
+  - `+dashboard-block-update` 不带 `--type`，所以不做按组件类型的强校验；但会对可解析的 `filter` 条件做轻量校验，包括 `conjunction`、字段引用、`operator` 和必需的 `value`，并与 create 一样拦截非法 `number_format` 子字段（见下方 number_format 小节）
   - 仅需传入合法 JSON；CLI 不会擅自改写你的业务含义
 
 ## 可复制模板

package/skills/lark-calendar/SKILL.md

@@ -19,7 +19,7 @@ metadata:
 按**日程归属**选身份：
 
 - 查看/管理登录用户本人的日程 → `--as user`（默认，绝大多数场景）。
-- 查看/管理 bot 自己创建/拥有的日程 → `--as bot` 
+- 查看/管理 bot 自己创建/拥有的日程 → `--as bot`
 
 **对话人称映射**：「我」= 登录用户，「你」= 应用（bot）；作为字段取值的人称（参会人、会议 owner 等）不参与身份判定，如「你创建日程，邀请我、会议 owner 为我」→ `--as bot` 创建，登录用户仅作参会人与会议 owner。
 
@@ -73,11 +73,15 @@ lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id>
 lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1,oc_chat1,omm_room1" --page-token <page_token> --page-size 30
 ```
 
+`--attendee-ids` 的多值语义：**同类型内为 OR（并集）**——只要日程命中列表中的任意一个同类型 ID，就会返回。
+
+- `--attendee-ids "ou_A,ou_B"` = A **或** B 参加的日程（**不是** A 和 B 都参加的）。
+
 ### `+delete` — 删除日程
 
 ```bash
 # calendar_id不传，默认primary
-lark-cli calendar +delete --calendar-id <calendar_id> --event-id <event_id> --notify true
+lark-cli calendar +delete --calendar-id <calendar_id> --event-id <event_id> --notify=true
 ```
 
 ### `+agenda` — 查看近期日程安排
@@ -157,13 +161,14 @@ lark-cli calendar +freebusy --start 2026-03-11T09:00:00+08:00 --end 2026-03-11T1
 
 ## 意图路由
 
+**日程与会议的关系**：用户口中的「会议」通常不区分日程和视频会议。定义、三种查询意图（当前/未来/过去）的分流规则见 [日程与视频会议的关系](references/lark-calendar-meeting-relation.md)。
+
 | 用户意图 | 路由到 |
 |----------|--------|
-| 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-meeting/SKILL.md`](../lark-meeting/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
-| 今天有哪些会议| 需要合并两部分内容：[`../lark-meeting/SKILL.md`](../lark-meeting/SKILL.md) 中的 `vc +search` 查询今天已结束的会议， `calendar +agenda` 查询进行中或未开始的日程。|
-| 查询日历/日程或未来时间的会议 | 本 skill |
+| 查询过去的会议（"昨天的会议""上周的会"）/今天有哪些会议 / 当前正在开的会议 | 先读 [日程与视频会议的关系](references/lark-calendar-meeting-relation.md) |
+| 未来的会议 / 明天/下周的会议 | 本 skill：视频会议不存在于未来，等价于查日程 |
 | 按关键词搜索日程 | 本 skill（`+search-event`） |
-| 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
+| 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（[`+meeting`](references/lark-calendar-meeting.md)） |
 | 查看日程的参会人 / 会议室（含 `--type resource` 只看会议室） | 本 skill（[`+list-attendees`](references/lark-calendar-list-attendees.md)） |
 | 把日程分享给某人 / 群 / 粘贴到文档 | 本 skill：先 `calendar events share_info` 取**日程分享链接**，再走 [lark-im](../lark-im/SKILL.md) 发送或粘贴该链接；**分享日程给某个人、某个群或粘贴到文档中，需要的都是日程分享链接，不是 applink**，不要自己拼接或用 applink 代替 |
 | 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再进入 [`lark-meeting`](../lark-meeting/SKILL.md)：[`vc +detail`](../lark-meeting/references/lark-vc-detail.md) → [`note +detail`](../lark-meeting/references/lark-note-detail.md) / [`minutes +detail`](../lark-meeting/references/lark-minutes-detail.md) |

package/skills/lark-calendar/references/lark-calendar-meeting-relation.md

@@ -0,0 +1,99 @@
+# 日程与视频会议的关系
+
+用户口中的「会议」不区分「日程」和「视频会议」，实际是两类不同实体。本文定义两者关系，并给出「当前 / 未来 / 过去」三种查询意图的执行流程。
+
+## 核心概念
+
+- **日程（Calendar Event）**：对用户一段时间的预占，到点后可能开视频会议、也可能只是线下会议 / 私人时间块。
+- **视频会议（VC Meeting）**：实际发生过的一次通话，`meeting_id` 只有真正发起后才存在。
+
+| 场景 | `event_id` | `meeting_id` | 备注 |
+|------|:---:|:---:|------|
+| 日程发起了视频会议 | ✓ | ✓ | 一个日程可发起多次通话，产出多个 `meeting_id` |
+| 日程未开视频会议 | ✓ | ✗ | 线下会议 / 私人时间块 |
+| 即时视频会议 | ✗ | ✓ | 无日程绑定 |
+
+**关键不变量**：视频会议只发生在**当下和过去**，不存在「未来的视频会议」。
+
+## 意图 1：查询当前正在开的会议
+
+**目标覆盖**：当下时间点用户可能关心的所有活动——正在开的视频会议 + 当前时间的日程（无论有没有开视频）。
+
+**执行步骤**：
+
+```bash
+# 1. 当前时间的日程
+lark-cli calendar +agenda --start <now> --end <now>
+
+# 2. 用户已加入的视频会议
+lark-cli vc +meeting-list-active --as user
+
+# 3. 步骤 1 每个日程回查关联 meeting_id
+#    输出是 event_id → meeting_id 映射；后续所有交叉都按 meeting_id 匹配
+#    （vc +meeting-list-active / vc +detail 结果的 id 字段即 meeting_id，无 event_id）
+lark-cli calendar +meeting --event-ids <event_id1>,<event_id2>
+
+# 4. 判定视频会议是否仍在进行
+#    仅对「步骤 3 非空 meeting_id 且不在步骤 2 里」的调用
+#    end_time 为空或 <= start_time → 仍在进行；否则已结束
+lark-cli vc +detail --meeting-ids <meeting_id1>,<meeting_id2>
+```
+
+**结果分组呈现**：按下列**四组顺序**归类，每组独立成节，空组可省略。
+
+1. **当前用户正在参与的会议**（`meeting_id` 命中步骤 2）
+   - **即时会议**（无关联 `event_id`）：仅展示视频会议信息。
+   - **日程会议**（能与步骤 3 的 `event_id` 关联）：展示日程信息 + 视频会议信息。
+2. **当前正在视频会议的日程（用户未加入）**：日程有 `meeting_id`、步骤 4 判定仍在进行、但不在步骤 2 里。展示日程信息 + 视频会议信息。
+3. **当前正在进行中的日程（视频会议已结束）**：日程仍在时间窗内、有 `meeting_id`，但步骤 4 判定已结束。展示日程信息 + 视频会议信息（标注「已结束」）。
+4. **当前正在进行中的日程（未开启视频会议）**：日程仍在时间窗内，步骤 3 回查无 `meeting_id`。仅展示日程信息。
+
+## 意图 2：查询未来的会议
+
+**只有日程视角**：视频会议只发生在当下和过去，用户说的「未来的会议」等价于「未来的日程」。
+
+```bash
+# 二选一：无关键词 → +agenda；有关键词 → +search-event
+lark-cli calendar +agenda --start <future_start> --end <future_end>
+lark-cli calendar +search-event --query <keyword> --start <future_start> --end <future_end>
+
+# 禁用：vc +search 对未来返回空，容易被误判「没有会议」
+# lark-cli vc +search --start <future> --end <future>   ← 不要这样做
+```
+
+若用户明确要求「未来的视频会议」，仍返回日程列表并**主动说明**：视频会议是否真正开要等到时间到达才能确定。
+
+## 意图 3：查询过去的会议
+
+**目标覆盖**：过去时间段内发生过的视频会议（含即时会议）+ 过去时间段的日程（含未开视频会议的）。
+
+**执行步骤**：
+
+```bash
+# 1. 过去的视频会议（含即时会议——仅查日程会漏掉）
+lark-cli vc +search --start <past_start> --end <past_end>
+
+# 2. 过去的日程
+lark-cli calendar +agenda --start <past_start> --end <past_end>
+
+# 3. 步骤 2 每个日程回查 meeting_id，构建 meeting_id → event_id 映射
+#    遍历步骤 1 每条结果，用其 id 字段（即 meeting_id）查此映射：
+#    命中 → 日程视频会议；未命中 → 无日程的即时会议
+lark-cli calendar +meeting --event-ids <event_id1>,<event_id2>
+```
+
+**结果分组**：按三组顺序呈现。
+
+1. **无日程的即时视频会议**：步骤 1 里找不到关联 `event_id`。仅展示视频会议信息。
+2. **日程视频会议**：日程 + 关联 `meeting_id`。同时展示日程信息和视频会议信息。
+3. **未开视频会议的日程**：日程存在但步骤 3 回查无 `meeting_id`。仅展示日程信息。
+
+## 常见判断路径
+
+| 用户输入 | 动作 |
+|----------|------|
+| 只给了「会议标题」 | 不确定是日程标题还是即时会议标题，**同时**查 `calendar +search-event --query <标题>` 与 [`lark-meeting`](../../lark-meeting/SKILL.md) 的 `vc +search --query <标题>`，交叉后按上述意图分流 |
+| 直接给了 `meeting_id` | 直接进入 [`lark-meeting`](../../lark-meeting/SKILL.md)，跳过日程 |
+| 相对锚点（「今天下午 3 点那个会」） | 先 `+agenda` 定位日程，再按意图 1 或 3 判断 |
+| 过去锚点（「昨天开的会」） | **禁止只查 `+agenda`**——必须同时查 `vc +search`，否则漏掉即时会议 |
+| 未来锚点（「明天下午的会」） | 只查日程，不查 `vc +search`（未来永远返回空） |

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

@@ -37,4 +37,4 @@ lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapt
 
 # 3. 任意文档 token（meeting_note / note_doc_token / verbatim_doc_token / shared_doc_token）→ 正文
 lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
-```
+```

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

@@ -5,7 +5,9 @@
 - `lark-cli calendar +delete` — 删除日程；重复性日程/例外必须传 `--apply-to`。
 - `lark-cli calendar +update` — 更新日程；重复性日程/例外必须传 `--apply-to`。
 
-> **强制规则：用户未明确操作范围时，必须先向用户确认，禁止 Agent 默认选取任何 `--apply-to`。** 用户表达含糊（如「删掉这个会」「改一下这个日程」）时也必须确认——`--apply-to=single` 只删/改一次，`--apply-to=all` 会影响整个序列及所有例外，代价截然不同。
+> **破坏性操作闸（Destructive Confirmation Gate）：** 用户未明确操作范围时，必须先向用户确认。`+delete`、以及 `+update` 中会通知参会人或不可逆的写操作执行前，**即使目标 event_id 和 `--apply-to` 都已明确，Agent 也必须等待用户确认**。
+>
+> 只有用户在同一轮对话中明说「直接删 / 不用问 / 已确认 / 别再确认 / just do it」等等价意思时才可跳过。跳过时须在最终回复里注明「已按用户显式免确认执行」，方便回溯。
 
 ## `--apply-to` 与日程类型的匹配矩阵
 

package/skills/lark-doc/SKILL.md

@@ -16,7 +16,7 @@ metadata:
 
 **身份：文档操作推荐显式指定 `--as user`。**
 
-**所有表示本地文件的 `@path` 均使用 `@./xxx` 形式的相对路径，并以运行 `lark-cli` 时的当前工作目录（CWD）为基准。**
+**本地文件引用统一遵循文件访问权限：CWD 内优先使用 `@./相对路径`，其他目录使用 `@绝对路径`。XML 内的相对资源路径先查 CWD；仅文件不存在时再查源 XML 文件所在目录，同名文件以 CWD 为准。内联内容、stdin、在线文档没有源文件目录，不执行回退。**
 
 ### 文档内容
 

package/skills/lark-doc/references/lark-doc-create-workflow.md

@@ -24,7 +24,7 @@
 
 下表文件均位于当前 Skill 的 `references/genres/` 目录。
 
-- 路由表仅用于选择候选，不代替 contract。高置信命中后必须读取对应 Profile / Adapter，并按其中的路由与消歧规则复核；未读取不得确定该值或进入 Step 3。确认后记录固定短名，最多各读取一个；未命中时，`genre_contract` 和 `adapter` 均可使用 `"none"` 或 `null`。
+- 路由表仅用于选择候选，不代替 contract。高置信命中后必须读取对应 Profile / Adapter，并按其中的路由与消歧规则复核；未读取不得确定该值或进入 Step 3。确认后记录固定短名，最多各读取一个；未命中时可省略 `genre_contract` 和 `adapter`。
 - contract 决定内容任务、证据和体裁边界；adapter 只调整与所选 contract 兼容的平台结构、写作风格和组件约束。
 
    | Content Profile | 独特专业任务 |
@@ -46,7 +46,7 @@
 ### Step 3：收集资料并扫描表达机会。
 
 1. 强制扫描事实、数据、案例、引用和图片等资源缺口；内容需要而现有材料不足时必须检索或生成，判断需要图片且用户未提供素材时必须搜索图片。
-2. 根据用户要求、contract / adapter 限制和内容需要确定 `presentation_mode`，再识别真实信息关系并选择候选表达；不因命中关系就机械使用组件。
+2. 根据用户要求、contract / adapter 限制和内容需要选择表达方式；可用 `presentation_mode` 记录视觉策略，不因字段存在就机械使用组件。
 
    | 信息关系 | 候选表达 |
    |-|-|
@@ -59,7 +59,7 @@
    | 简单并列、步骤或连续论述 | 列表或段落 |
 
 3. 按全篇、章节、block 三个尺度构图：相关内容相邻，同类关系保持相同顺序与对齐；正文可以是主表达，不要求每节都有 presentation block。
-4. 在写正文前确定计划使用的 block 和具体 `purpose`。Presentation Decision 的 `visual_plan.blocks` 只记录确需最低数量约束的 `whiteboard`、`img`、`html5-block`。三类均无硬性数量要求时写 `"blocks": []`。
+4. 在写正文前确定计划使用的 block。Presentation Decision 的 `visual_plan.blocks` 只记录确需最低数量约束的 `whiteboard`、`img`、`html5-block`。三类均无硬性数量要求时写 `"blocks": []`。
 
 `presentation_mode` 只表示模型采用的视觉策略；只有用户要求、contract / adapter 限制互相冲突时才询问用户：
 
@@ -93,23 +93,21 @@
 lark-cli docs +script --command init-draft --presentation-decision '<上方完整 JSON>' --format json
 ```
 
-成功后：
-
-- 保持当前工作目录不变；将 `data.workspace` 原样记为 `work_dir`，将 `data.draft_path` 原样记为 `draft_path`；遵循 `data.tip`，后续始终使用 `@./<draft_path>`。
-- CLI 会创建独占的 `work_dir` 并保存 `.presentation-decision.json` 作为固定基线，**但不会创建 `draft_path` 指向的 XML**。`draft_path` 是当前任务可直接写入的新文件路径；要求、资料或 contract 实质变化时，提交新决策并重新初始化，不得直接改基线。
+- 返回的 `data` 字段包含 cwd、workspace、draft_path，后续 CLI 在 `data.cwd` 下执行；将 `data.workspace` 记为 `work_dir`、`data.draft_path` 记为 `draft_path`（已含工作区前缀）。
+- CLI 会创建独占的 `work_dir` 并保存 `.presentation-decision.json` 作为固定基线，**但不会创建 `draft_path` 指向的 XML**。`draft_path` 是当前任务可直接写入的新文件路径；
 
 ### Step 5：生成 release candidate。
 
 读取 [`lark-doc-xml.md`](lark-doc-xml.md)，并结合 Presentation Decision、适用 contract 和 Philosophy 生成完整 XML。使用扩展标签时按需读取 [`拓展标签`](lark-doc-xml-extended-blocks.md)。
 
-1. 公开网络图片使用 `<img href="URL"/>`；已有本地图片使用 `<img path="@./relative/path"/>`；画板使用 `<whiteboard path="@./relative/path"/>` 并遵循[`画板工作流`](lark-doc-whiteboard.md)；HTML 使用 `<html5-block path="@./file.html"/>` 并遵循[`拓展标签`](lark-doc-xml-extended-blocks.md)。
-2. 直接在 Step 4 返回的 `draft_path` 创建并写入完整 release candidate。
+1. 公开网络图片使用 `<img href="URL"/>`；已有本地图片使用 `<img path="@./downloads/image.png"/>`；画板使用 `<whiteboard type="svg" path="@./<work_dir>/diagram.svg"/>` 并遵循[`画板工作流`](lark-doc-whiteboard.md)；HTML 使用 `<html5-block path="@./<work_dir>/widget.html"/>` 并遵循[`拓展标签`](lark-doc-xml-extended-blocks.md)。
+2. 直接在 `<data.cwd>/<draft_path>` 创建并写入完整 release candidate。新建资源建议放 `<data.cwd>/<work_dir>`，已有资源可原地复用；CWD 内优先用相对路径，其他位置用允许访问的绝对路径。XML 内相对资源先查 CWD，仅文件不存在时回退到 XML 所在目录。
 3. 首次写入后，发现 XML 语法问题时只修复最小范围，不无故重写正确内容。
 
 ### Step 6：执行 Draft Profile Check。
 
 1. 执行 `lark-cli docs +script --command parse --content "@./<draft_path>" --format json`。顶层 `ok` 仅表示命令执行成功，是否通过看 `data.assessment.status`。失败时按 `data.diagnostics[]` 局部修复；只有草稿为空、截断或结构无效时才全文重建。`parse` 不替代 XML 规则或服务端校验。
-2. Profile Check 通过后，按 [`lark-doc-xml.md`](lark-doc-xml.md) 复查标签、属性和值，并依据 Philosophy 检查事实与来源、用户硬约束、适用 contract / adapter 以及 `visual_plan`。最终 XML 能否写入以 `docs +create` 的服务端结果为准。
+2. `passed` 只覆盖已启用的检查；先对照用户要求确认应声明的约束已完整填写，再按 [`lark-doc-xml.md`](lark-doc-xml.md) 复查标签、属性和值，并依据 Philosophy 检查事实与来源、用户硬约束、适用 contract / adapter 以及 `visual_plan`。最终 XML 能否写入以 `docs +create` 的服务端结果为准。
 
 ### Step 7：创建文档并处理局部失败。
 

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-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.
 

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

@@ -51,7 +51,7 @@ 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:
+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">

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-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 |
 

package/skills/lark-mail/SKILL.md

@@ -88,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` 发送
@@ -123,7 +124,9 @@ 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)
+- 软删除会话：已有 `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)
@@ -197,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（必须，不可跳过）
 
@@ -279,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-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` 软删除会话