@amaster.ai/pi-lark 0.1.13 → 0.1.15

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

@@ -1,91 +1,89 @@
 # 重复性日程操作规范
 
-重复性日程的编辑/删除分为三种范围：「仅此次」「全部」「此次及后续」。用户未明确范围时，**必须询问确认**。
+重复性日程/例外的编辑和删除必须显式指定操作范围。相关命令：
 
-## 关键概念
-
-- **event_id 结构**：`event_id` 的格式为 `{event_uid}_{originalTime}`。普通日程或重复性日程本体的 `originalTime` 为 `0`；例外的 `originalTime > 0`，代表该例外在原重复性序列中本来的时间位置。因此 `{event_uid}_0` 即为原重复性日程的 `event_id`。
-- **原重复性日程**：携带 `rrule` 的日程本体，`event_id` 形如 `{event_uid}_0`。系列的所有属性（标题、时间、rrule、描述等）都挂在本体上。
-- **例外（Exception）**：对某次实例做过「仅此次」编辑后产生的独立日程，`event_id` 形如 `{event_uid}_{originalTime}`（`originalTime > 0`）。通过 `event_uid` 部分即可关联回原重复性日程。
-- 删除/更新原重复性日程 **不会** 级联处理例外——必须手动逐个处理。
-
-## 前置步骤（所有范围通用）
+- `lark-cli calendar +delete` — 删除日程；重复性日程/例外必须传 `--apply-to`。
+- `lark-cli calendar +update` — 更新日程；重复性日程/例外必须传 `--apply-to`。
 
-1. 通过 `+agenda` 或 `+search-event` 定位重复性日程，获取原重复性日程的 `event_id`。
-2. 通过 `events instance_view` 或 `+agenda` 列出实例，识别哪些是例外（`event_id` 中 `originalTime > 0` 的即为例外）。
-3. 确认用户的操作范围。
+> **破坏性操作闸（Destructive Confirmation Gate）：** 用户未明确操作范围时，必须先向用户确认。`+delete`、以及 `+update` 中会通知参会人或不可逆的写操作执行前，**即使目标 event_id 和 `--apply-to` 都已明确，Agent 也必须等待用户确认**。
+>
+> 只有用户在同一轮对话中明说「直接删 / 不用问 / 已确认 / 别再确认 / just do it」等等价意思时才可跳过。跳过时须在最终回复里注明「已按用户显式免确认执行」，方便回溯。
 
-## 编辑全部（更新时间）
+## `--apply-to` 与日程类型的匹配矩阵
 
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --start ... --end ...` | 更新原重复性日程的时间 |
-| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 时间变更后例外已无意义，必须删除 |
+先记住四种日程类型：**普通日程（Normal）**、**重复性日程本体（Master）**、**重复性日程实例（Instance）**、**重复性日程例外（Exception）**。四种类型允许的 `--apply-to` 组合如下（❌ = 传入即报错）：
 
-> 理由：更新时间会改变重复起止点，例外日程的原始占位已变，若保留会导致时间冲突或残留。
+| 日程类型 | event_id 形状 | `single` | `all` | `this-and-following` |
+|----------|--------------|:--------:|:-----:|:--------------------:|
+| Normal（普通日程）          | `{uid}_0`（无 rrule） | 隐含默认 | ❌ | ❌ |
+| Master（重复性日程本体）    | `{uid}_0`（有 rrule） | ❌ | ✅ | ❌ |
+| Instance（重复性日程实例）  | `{uid}_{ts>0}`，`is_exception=false` | ✅ | ✅ | ✅ |
+| Exception（重复性日程例外）| `{uid}_{ts>0}`，`is_exception=true`  | ✅ | ✅ | ❌（Exception 已占据该时间位，需改传另一个未被独立化的 Instance id 作为分割点） |
 
-## 编辑全部（更新非时间字段）
+三个 `--apply-to` 的含义与影响面：
 
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --summary ... --description ...` | 更新原重复性日程的标题/描述等 |
-| 2 | `lark-cli calendar +update --event-id <例外ID> --summary ... --description ...` （逐个） | 同步更新例外日程的对应字段 |
+| 值 | 语义 | 影响面 |
+|----|------|--------|
+| `single` | 只操作当前这一次 | 只改/删传入的这一个 event_id 本身；例外不动其它例外，实例不动整个序列 |
+| `all` | 操作整条重复性序列 | Master 本体 **和** 所有例外都会被处理（时间变更时例外先被删除，其它字段则会同步 PATCH 到每个例外） |
+| `this-and-following` | 从「起始实例」起截断并新建后续序列 | 用 UNTIL 截断 Master、删除起始实例起的所有未来例外、以起始实例的时间为起点 创建 一条新序列继承 Master 的默认字段 |
 
-> 理由：例外已脱离原重复性日程独立存在，不会自动继承原日程的更新。
-
-## 删除全部
-
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<原重复日程ID>","need_notification":true}'` | 删除重复性日程本体 |
-| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 删除所有例外日程 |
+## 关键概念
 
-> 理由：例外是独立实体，删除原重复性日程不会级联删除例外。
+- **event_id 结构**：`event_id` 的格式为 `{event_uid}_{originalTime}`。`originalTime = 0` 表示 Master 或 Normal；`originalTime > 0` 表示某一次在原序列中本来的时间戳（Unix 秒）。因此 `{event_uid}_0` 即为重复性日程本体的 `event_id`。
+- **Master（重复性日程本体）**：携带 `rrule` 的日程本体，`event_id` 形如 `{event_uid}_0`。序列的所有默认属性（标题、时间、rrule、描述、参会人等）都挂在本体上。
+- **Normal（普通日程）**：不携带 `rrule`，`event_id` 也是 `{event_uid}_0`，但没有序列概念。只能用 `--apply-to=single`（可省略）。
+- **Instance vs Exception —— 二者最容易混淆，务必区分**：
+  - **Instance（实例）**：由 rrule 展开出来的「虚拟」发生点，本身不落库。`event_id` 形如 `{event_uid}_{originalTime}`（`originalTime > 0`），是从 `+agenda` / `+search-event` 返回的可寻址标识。**从未被单独编辑过**——所有属性都从 Master 继承而来。在 API 层可以对 Instance id 发 GET，但对它发写操作时（操作此次），会先把它「实体化」成一条 Exception。
+  - **Exception（例外）**：某个 Instance 被显式修改（改时间、改标题、改参会人等）或被显式删除标记后落库产生的**独立日程**。`event_id` 形状与 Instance 完全一样（`{event_uid}_{originalTime}`），肉眼**无法**区分——唯一可靠的判据是 `calendar +get` 返回的 `is_exception=true`（Instance 为 false）。Exception 已经脱离 Master 的字段继承，是一份可独立编辑/删除的实体。
+  - **一句话总结**：Instance 是 rrule 展开出来的「占位符」，Exception 是「已经被独立化的实例」。判断当前 event_id 是哪种，先跑 `+get` 看 `is_exception`。
+- 删除/更新 Master **不会** 级联处理例外——命令内部会显式扫描并处理例外。
 
-## 编辑此次及后续
+## 前置步骤（所有范围通用）
 
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
-| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
-| 3 | `lark-cli calendar +create --summary ... --start <指定时间> --end ... --rrule "FREQ=..." --attendee-ids ...` | 从指定时间开始创建新的重复性日程（即「后续」部分，携带编辑后的内容） |
+1. 通过 `+agenda` 或 `+search-event` 定位到目标日程 / 实例，拿到 `event_id`。
+2. 判断日程类型：
+   - `event_id` 后缀 `_0` 且无 `recurrence` → Normal；
+   - `event_id` 后缀 `_0` 且有 `recurrence` → Master；
+   - `event_id` 后缀 `_{数字>0}` 且 `is_exception=false` → Instance；
+   - `event_id` 后缀 `_{数字>0}` 且 `is_exception=true` → Exception。
+   - 需要精确判断时跑 `calendar +get` 看 `recurrence` 和 `is_exception` 字段。
+3. **与用户确认 `--apply-to` 范围（未明确一律先问，禁止默认）**。
 
-> UNTIL 计算规则：若用户选择「从第 N 次开始编辑」，UNTIL 应设置为第 N-1 次实例的日期（即保留到指定时间之前的最后一次）。
-> 新日程应继承原日程的参会人、会议室等配置（除非用户明确要修改）。
+## 常见命令
 
-## 删除此次及后续
+### 删除
 
-| 步骤 | 命令 | 说明 |
-|------|------|------|
-| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
-| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
+```bash
+# 删除此次（例外或instance）
+lark-cli calendar +delete --event-id <uid_originalTime> --apply-to single
 
-> 与「编辑此次及后续」的区别：不需要步骤 3（创建新的重复性日程），因为目标是删除后续而非替换。
+# 删除全部（主日程 id 或任意 例外/instance id）
+lark-cli calendar +delete --event-id <uid_originalTime> --apply-to all
 
-## 仅此次
+# 删除此次及后续（必须传具体instance id）
+lark-cli calendar +delete --event-id <uid_originalTime> --apply-to this-and-following
+```
 
-- **编辑仅此次**：通过 `+agenda` / `+search-event` 定位到具体实例的 `event_id`，然后正常调用 `+update`。
-- **删除仅此次**：定位到具体实例的 `event_id`，调用 `events delete`。
+### 更新
 
-## 用户意图映射
+```bash
+# 编辑此次（单个实例 / 例外）
+lark-cli calendar +update --event-id <uid_originalTime> --apply-to single --summary <summary>
 
-| 用户表达 | 操作范围 |
-|----------|----------|
-| 「改这个重复日程的标题」「全部改」「每次都改」 | 编辑全部 |
-| 「删掉这个重复日程」「取消所有」 | 删除全部 |
-| 「从下周开始改时间」「后面的都改」 | 编辑此次及后续 |
-| 「从下周开始不要了」「后面的都删」 | 删除此次及后续 |
-| 「就改这一次」「只删这一次」 | 仅此次 |
-| 「给明天的日程加个会议室」（且为重复日程） | 范围不明确，**必须询问用户** |
-| 未明确范围 | **必须询问用户** |
+# 编辑全部（主日程 id 或任意 例外/instance id）
+lark-cli calendar +update --event-id <uid_originalTime> --apply-to all --summary <summary>
 
-## 注意事项
+# 编辑全部：改时间
+lark-cli calendar +update --event-id <uid_originalTime> --apply-to all --start <start> --end <end>
 
-- 涉及时间戳计算（如推算 UNTIL 日期）时，必须调用系统命令或脚本，禁止心算。
+# 编辑此次及后续：截断主日程 + 删未来例外 + 创建新序列
+lark-cli calendar +update --event-id <uid_originalTime> --apply-to this-and-following --summary <summary>
+```
 
-## 参考
+## 语义细则
 
-- [lark-calendar](../SKILL.md) — 日历全部命令
-- [lark-calendar-update](lark-calendar-update.md) — 更新日程 Shortcut
-- [lark-calendar-create](lark-calendar-create.md) — 创建日程 Shortcut
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
+- **`--apply-to=all` 时的字段传播**：只把用户本次显式传的 flag 应用到每个例外和主日程。例外原本自定义过的其他字段（例如自己的描述）保持不变。
+- **`--apply-to=this-and-following` 的字段继承**：新创建的日程从原主日程继承 summary、description、rrule、start/end（用起始实例的时间）、vchat/reminders/location/visibility；用户任何显式传的 flag 优先。
+- **`--start/--end` 变更**：`all` 场景下，例外会被删除（原始占位已无意义），主日程再 PATCH；`this-and-following` 场景下，`--start/--end` 传了会作为新序列的时间，否则用起始实例的时间。
+- **参会人**：`this-and-following` 创建新序列时，若传了 `--add-attendee-ids`，会额外 添加attendees 到新序列；`--remove-attendee-ids` 会从新序列的参与人列表移除。

package/skills/lark-calendar/references/lark-calendar-schedule-clear-time.md

@@ -35,7 +35,12 @@ lark-cli calendar +room-find \
 ### 2. 查询忙闲
 
 ```bash
-lark-cli calendar +freebusy --start "<start>" --end "<end>"
+# 单人 / 多人查忙：--user-id 可重复或逗号分隔；服务端已合并相邻/重叠忙碌区间
+lark-cli calendar +freebusy --start "<start>" --end "<end>" --user-id "ou_a,ou_b"
+
+# 直接求共同空闲（推荐用于「找几个人一起有空」）
+lark-cli calendar +freebusy --start "<start>" --end "<end>" \
+  --user-id "ou_a,ou_b,ou_c" --type common_free --min-duration 30m
 ```
 
 规则：
@@ -43,6 +48,7 @@ lark-cli calendar +freebusy --start "<start>" --end "<end>"
 - 参与人过多（超过 5 人）：仅查询**当前用户**及少数核心人员忙闲即可
 - 参与人含**群组**：无需展开群组成员查询忙闲
 - 如果用户是从 `+suggestion` 确认了时间块后进入本分支的，**无需再调用 `+freebusy`**
+- 找多人共同空闲：直接用 `--type common_free [--min-duration <dur>]`，让 CLI 一次算出共同空闲；不要自己再合并求交
 
 ### 3. 冲突处理
 

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-comment-location.md

@@ -154,7 +154,7 @@ lark-cli docs +fetch --doc '<doc_token_or_url>' --detail with-ids
 - 如果 `quote` 是 `C3`、`A1` 这类单元格坐标，可拆出 `spreadsheet_token` / `sheet_id` 后用 `lark-sheets` 读取该单元格确认：
 
 ```bash
-lark-cli sheets +read \
+lark-cli sheets +cells-get \
   --spreadsheet-token '<spreadsheet_token>' \
   --sheet-id '<sheet_id>' \
   --range '<cell>'

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-drive/references/lark-drive-workflow-topic-move-collector-resolve-verify.md

@@ -145,7 +145,7 @@
 | 资源类型 | 验证方式 |
 |---------------|---------------------|
 | `docx` / `doc` | 允许时使用 `docs +fetch --api-version v2`。 |
-| `sheet` | 使用 `sheets +find` 查关键词证据，或用 `sheets +read` 读取有界范围。 |
+| `sheet` | 使用 `sheets +cells-search` 查关键词证据，或用 `sheets +cells-get` 读取有界范围。 |
 | `bitable` | 只有必要且已加载 Base 能力时验证。 |
 | `slides` | 除非具备幻灯片读取能力，否则使用元数据 / 预览 / 标题证据。 |
 | `file` | 仅在支持时使用标题、元数据、预览或导出文本。 |

package/skills/lark-drive/references/lark-drive-workflow-topic-move-collector.md

@@ -179,7 +179,7 @@ Risk / Structure: `R2-R3` / `S3`
 | `RESOLVE_TARGET` | `drive +inspect`、`wiki +node-get`、`wiki +space-list`、仅用于查找文件夹候选的 `drive +search` | 解析目标位置 |
 | `SEARCH_RECALL` / `RECALL_ENHANCE` | `drive +search` | 搜索召回和覆盖增强 |
 | `RESOURCE_RESOLVE` | `drive +inspect`、`wiki +node-get`、`drive metas batch_query`、必要时 `drive permission.members auth` | 解析标准 token、owner、权限信号和移动资格 |
-| `CONTENT_VERIFY` | `docs +fetch`、`sheets +read`、`sheets +find`、必要时 `drive +preview` | 验证内容证据 |
+| `CONTENT_VERIFY` | `docs +fetch`、`sheets +cells-get`、`sheets +cells-search`、必要时 `drive +preview` | 验证内容证据 |
 | `EXECUTE` | `drive +create-folder`、`wiki +node-create`、`drive +move`、`wiki +move`、`wiki +move-to-drive`、`drive +task_result` | 执行已确认写操作 |
 | `VERIFY` | `drive files list`、`wiki +node-list`、`wiki +node-get`、`drive +inspect`、`drive +task_result` | 验证执行结果 |
 | `RESTORE` | `drive +move`、`wiki +move`、`drive +delete`、`wiki +node-delete`、`drive +task_result` | 恢复已确认资源并清理本次新建目标 |

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

@@ -34,7 +34,7 @@ lark-cli im +messages-resources-download --message-id om_xxx --file-key img_v3_x
 | `--message-id <id>` | Yes | Message ID (`om_xxx` format) |
 | `--file-key <key>` | Yes | Resource key (`img_xxx` or `file_xxx`) |
 | `--type <type>` | Yes | Resource type: `image` or `file` |
-| `--output <path>` | No | Relative output path; absolute paths and `..` traversal are rejected. When omitted, the command uses the attachment name when available and otherwise falls back to the resource key |
+| `--output <path>` | No | Output path, relative or absolute, that must resolve inside the built-in allowed roots (the working directory, `/tmp`, `~/files`); system and credential directories stay refused. When omitted, the command uses the attachment name when available and otherwise falls back to the resource key |
 | `--as <identity>` | No | Identity type: `user` (default) or `bot` |
 | `--dry-run` | No | Print the request only, do not execute it |
 
@@ -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: