@amaster.ai/pi-lark 0.1.2-beta.66 → 0.1.2-beta.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.2-beta.66",
+  "version": "0.1.2-beta.68",
   "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.66"
+    "@amaster.ai/pi-shared": "0.1.2-beta.68"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

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

@@ -17,6 +17,7 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档是 Dashboar
 | `funnel` | 漏斗图 |
 | `wordCloud` | 词云 |
 | `radar` | 雷达图 |
+| `ranking` | 排行榜 |
 | `statistics` | 指标卡 |
 | `text` | 文本（支持 Markdown） |
 
@@ -96,6 +97,18 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 
 如果表中行序就是业务顺序，首次创建 block 时就一次性设置 `sort:{"type":"view","order":"asc"}` 保留行序，避免创建后再二次更新排序条件。
 
+### ranking 排行榜专属契约
+
+排行榜只支持一个分组和一个指标，公开字段固定为 `table_name`、`series`/`count_all`、`group_by`、`filter`、`limit_size`：
+
+- `group_by` 必填且长度严格为 1；`mode` 仅支持 `integrated` / `enumerated`。
+- `series` 长度严格为 1，且与 `count_all:true` 二选一；`rollup` 仅支持 `SUM` / `MAX` / `MIN` / `AVERAGE`。
+- 排序只写在 `group_by[0].sort`，`type` 只能为 `value`，`order` 为 `asc` / `desc`。创建时省略排序默认按指标值降序。
+- `limit_size` 是 Top N，取值为 `1..500` 的整数，创建时省略默认 `10`。
+- 不支持顶层 `sort`、公开 `ranking` 对象或头像开关。
+
+更新 `ranking` 时，`data_config` 是顶层 patch：只传 `limit_size` 只改 Top N；只传 `group_by` 只替换唯一分组和排序；只传 `series` 或 `count_all:true` 只切换指标；只传 `filter` 只替换筛选。切换 `table_name` 时必须在同一 patch 提供新的 `group_by` 以及 `series` 或 `count_all:true`；未传 `filter` 保留原筛选，未传 `limit_size` 保留原 Top N。
+
 示例 — 柱状图按销售额降序：
 
 ```json
@@ -225,6 +238,7 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 - 看流程转化 → 漏斗图
 - 看多维度评分 → 雷达图
 - 显示单个指标 → 指标卡（统计数字或记录数）
+- 查看单维度 Top N → 排行榜
 
 最小柱状图：
 
@@ -354,6 +368,23 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 }
 ```
 
+排行榜（按销售额取 Top 10）：
+
+```json
+{
+  "table_name": "订单表",
+  "series": [{ "field_name": "金额", "rollup": "SUM" }],
+  "group_by": [{ "field_name": "负责人", "mode": "integrated", "sort": {"type":"value","order":"desc"} }],
+  "limit_size": 10
+}
+```
+
+排行榜只更新 Top N：
+
+```json
+{"limit_size": 20}
+```
+
 指标卡（统计数字）：
 
 ```json

package/skills/lark-base/references/lark-base-dashboard-block-get-data.md

@@ -6,7 +6,7 @@
 
 这个命令适合以下场景：
 
-1. 读取柱状图 / 条形图 / 折线图 / 饼图 / 环形图 / 面积图 / 组合图 / 散点图 / 漏斗图 / 雷达图 / 词云 / 指标卡的**实际计算结果**；
+1. 读取柱状图 / 条形图 / 折线图 / 饼图 / 环形图 / 面积图 / 组合图 / 散点图 / 漏斗图 / 雷达图 / 排行榜 / 词云 / 指标卡的**实际计算结果**；
 2. 把图表结果交给 AI 做后续总结、趋势解释、同比/环比说明、异常点提取；
 3. 在**不读取原始记录**的前提下，直接消费图表层已经聚合好的结果；
 4. 验证某个图表当前展示的数据是否符合预期。
@@ -26,7 +26,7 @@
 
 当前支持以下图表类型的数据计算与返回：
 
-### 二维图表（10 种）
+### 二维图表（11 种）
 
 - 柱状图
 - 条形图
@@ -38,6 +38,7 @@
 - 散点图
 - 漏斗图
 - 雷达图
+- 排行榜
 
 ### 特殊类型（2 种）
 
@@ -262,7 +263,9 @@ CLI 成功输出使用标准 `{ok, identity, data}` 信封：
 
 ### 一、二维图表
 
-适用于：柱状图、条形图、折线图、饼图、环形图、面积图、组合图、散点图、漏斗图、雷达图。
+适用于：柱状图、条形图、折线图、饼图、环形图、面积图、组合图、散点图、漏斗图、雷达图、排行榜。
+
+排行榜复用同一 `dimensions` / `measures` / `main_data` 协议，不增加专属响应字段。结果的条数和顺序由 block 配置中的 `limit_size` 与 `group_by[0].sort` 决定；消费返回时保持 `main_data` 的服务端顺序，不要再次反转或自行重排。
 
 #### 结构特征
 

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

@@ -60,7 +60,7 @@ lark-cli base +table-list --base-token xxx
 lark-cli base +field-list --base-token xxx --table-id <table_id>
 
 # 第 3 步：规划应该创建哪些组件（根据用户需求确定组件类型和数量）
-# 例如：总销售额（指标卡）、月度趋势（折线图）、品类占比（饼图）
+# 例如：总销售额（指标卡）、月度趋势（折线图）、负责人 Top N（排行榜）
 
 # 第 4 步：顺序创建每个组件（必须串行执行，不能并发）
 # 重要：创建组件前，先确定 dashboard_id、组件 name/type 和真实表字段
@@ -84,6 +84,14 @@ lark-cli base +dashboard-block-create \
 
 # 继续创建其他组件...
 
+# 排行榜组件：省略 limit_size 和 sort 时分别默认 10、value desc
+lark-cli base +dashboard-block-create \
+  --base-token xxx \
+  --dashboard-id blk_xxx \
+  --name "负责人销售额 Top 10" \
+  --type ranking \
+  --data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}],"group_by":[{"field_name":"负责人"}]}'
+
 # 第 5 步：组件创建完成后，可按需使用 arrange 智能重排（未使用 --position 时可选）
 # 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
 # 若任一组件使用了显式 --position，跳过此步骤；除非用户明确同意放弃精确布局
@@ -152,6 +160,13 @@ lark-cli base +dashboard-block-update \
   --data-config '{...}' \
   --position '{...}'   # 可选，只在需要调整布局时传
 
+# 排行榜只修改 Top N；不会覆盖分组、指标、筛选或排序
+lark-cli base +dashboard-block-update \
+  --base-token xxx \
+  --dashboard-id blk_xxx \
+  --block-id chtxxxxxxxx \
+  --data-config '{"limit_size":20}'
+
 ```
 
 ### 场景 4：重排仪表盘布局
@@ -225,6 +240,7 @@ lark-cli base +dashboard-block-get-data --base-token xxx --block-id chtxxxxxxxx
 | 类别比较（谁高谁低） | column | 柱状图组件 |
 | 占比分布（各部分比例） | pie | 饼图组件 |
 | 单个关键指标 | statistics | 指标卡组件 |
+| 单维度 Top N 排名 | ranking | 排行榜组件，单分组、单指标 |
 | 富文本说明/标题/注释 | text | 文本组件（支持 Markdown） |
 
 详细组件类型和 data_config 完整规则：[Dashboard Block 配置](lark-base-dashboard-block-config.md)

package/skills/lark-base/references/lark-base-workflow-schema.md

@@ -239,7 +239,7 @@
 {
   "table_name": "项目表",
   "field_name": "截止日期",
-  "offset": 1,
+  "offset": -1,
   "unit": "DAY",
   "hour": 9,
   "minute": 0,
@@ -252,7 +252,7 @@
 | `table_name` | 是 | 数据表名 |
 | `field_name` | 是 | 日期字段名（必须为 `datetime` / `created_at` / `formula` / `lookup` 类型） |
 | `unit` | 是 | 偏移单位：`MINUTE` / `HOUR` / `DAY` / `WEEK` / `MONTH` |
-| `offset` | 是 | 提前/延后的偏移量（正数=提前，负数=延后；范围由 `unit` 决定）：`MINUTE` ∈ {0, 5, 15, 30, -5, -15, -30}；`HOUR` ∈ [-6, -1] ∪ [1, 6]；`DAY` ∈ [-7, 7]；`WEEK` ∈ [-7, -1] ∪ [1, 7]；`MONTH` ∈ [-7, -1] ∪ [1, 7] |
+| `offset` | 是 | 提前/延后的偏移量（触发时间 = 日期字段时间 + `offset` × `unit`，因此负数=提前、正数=延后；范围由 `unit` 决定）：`MINUTE` ∈ {0, 5, 15, 30, -5, -15, -30}；`HOUR` ∈ [-6, -1] ∪ [1, 6]；`DAY` ∈ [-7, 7]；`WEEK` ∈ [-7, -1] ∪ [1, 7]；`MONTH` ∈ [-7, -1] ∪ [1, 7] |
 | `hour` | 是 | 触发小时 (0-23)，默认 9 |
 | `minute` | 是 | 触发分钟 (0-59)，默认 0 |
 | `condition_list` | 否 | 过滤条件数组，数组中每个元素为 AndCondition 结构，多个 AndCondition 之间为 OR 关系  | 

package/skills/lark-calendar/SKILL.md

@@ -35,15 +35,17 @@ lark-cli calendar +agenda --as bot
 | Shortcut | 说明 |
 |----------|------|
 | `+agenda` | 查看日程安排（默认今天） |
-| [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id |
+| [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id,**注意**: 视频会议链接获取走+get命令 |
 | [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
-| [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 |
-| `+freebusy` | 查询用户主日历的忙闲信息和 RSVP 状态（纯查询场景；预约场景走 `+suggestion`） |
+| [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室；重复性日程/例外必须传 `--apply-to`（详见 [重复性日程操作规范](references/lark-calendar-recurring.md)） |
+| `+delete` | 删除日程；重复性日程/例外必须传 `--apply-to`（详见 [重复性日程操作规范](references/lark-calendar-recurring.md)） |
+| `+freebusy` | 查询主日历的忙闲/RSVP状态/空闲时间段。(**如需预约/推荐时间段**走 `+suggestion`——它综合工作时间、忙碌区间和休息时间推荐。) |
 | [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
 | [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
 | [`+join-event`](references/lark-calendar-join-event.md) | 凭分享 token 加入日程（分享链接/二维码/分享卡片/RSVP 卡片） |
 | [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
 | [`+transfer`](references/lark-calendar-transfer.md) | 把日程组织者转让给另一个用户或机器人；不可逆，需 `--yes` |
+| [`+list-attendees`](references/lark-calendar-list-attendees.md) | 列出日程的参与人和会议室（支持按 `--type` 过滤：user / resource / chat / third_party） |
 
 ### `+get` — 单日程详情
 
@@ -56,6 +58,8 @@ lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id>
 
 日程描述统一使用 `description` 一个字段，按 **Markdown** 富文本处理。读取日程时 `description` 返回 Markdown 富文本（仅有纯文本描述时返回该纯文本）；创建/更新日程时也通过 `--description` 传入 Markdown。
 
+> `+get` 返回不含参会人和会议室。需要参与人视角（用户 / 会议室 / 群 / 三方邮箱）请调用 [`+list-attendees`](references/lark-calendar-list-attendees.md)。
+
 ### `+search-event` — 按关键词、时间范围和参会人搜索日程
 
 仅返回基础字段（`event_id`/`summary`/`start`/`end` 等），需要详情请走 `+get`。
@@ -69,6 +73,13 @@ 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
 ```
 
+### `+delete` — 删除日程
+
+```bash
+# calendar_id不传，默认primary
+lark-cli calendar +delete --calendar-id <calendar_id> --event-id <event_id> --notify true
+```
+
 ### `+agenda` — 查看近期日程安排
 
 默认查询当天。结果应整理为按日期分组、按开始时间升序的易读时间线。
@@ -83,20 +94,36 @@ lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17 --calendar-id <cal
 - 已取消的日程自动过滤；无日程时直接告知"日程清空"。
 - 时间范围超过 40 天会自动拆分查询并合并结果。
 
-### `+freebusy` — 查询主日历忙闲时段和 RSVP 状态
+### `+freebusy` — 查询主日历忙闲时段 / 事件 / 公共空闲
 
-仅返回忙碌时段起止时间，不含日程标题等隐私信息；其他订阅日历不在范围内。
+`+freebusy` 一个入口承担四种视角：几何计算类（`busy` / `free` / `common_free`）走自动合并；事件维度类（`raw_busy`）保留每条上游日程 + `rsvp_status`。
 
 ```bash
 # start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
-# user-id 目标用户 open_id（ou_ 前缀）可选；默认当前登录用户，bot 身份必须显式指定
-lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
+# user-id 目标用户 open_id，可重复或用逗号分隔；默认当前登录用户，bot 身份必须显式传至少一个
+# type 视角四选一（默认 busy）：
+#   busy         每个 user 合并后的忙碌区间（找空档、看忙碌时段）
+#   raw_busy     每个 user 的原始日程块 + rsvp_status（数会议、看每个会的 rsvp）
+#   free         每个 user 在时间窗内的空闲区间（可带 --min-duration 过滤）
+#   common_free  所有 user 的共同空闲区间（可带 --min-duration 过滤）
+# min-duration 仅对 free / common_free 生效；Go duration 格式，例如 30m、1h、90m
+
+# 查询忙碌时间段（去重并合并相邻/重叠段）
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-11 --user-id ou_a,ou_b --type busy
+
+# 看别人有几个会、每个会的起止 + rsvp（不合并相邻/重叠段，带rsvp状态）
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-11 --user-id ou_a,ou_b --type raw_busy
+
+# 查询用户空闲时间段
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-11 --user-id ou_a,ou_b --type free
+
+# 多人公共空闲时间段（推荐替代手工合并）
+lark-cli calendar +freebusy --start 2026-03-11T09:00:00+08:00 --end 2026-03-11T18:00:00+08:00 --user-id ou_a,ou_b --type common_free --min-duration 30m
 ```
 
 用法提示：
-- **仅判断是否有空** → `+freebusy`；**需要日程详情** → `+agenda`。
-- 检查多人可用性：分别调用并对比，找共同空闲。
-- 预约/改约场景下，调用规则（参与人过多、含群组、来自 `+suggestion` 等）详见 [schedule-clear-time.md § 查询忙闲](references/lark-calendar-schedule-clear-time.md#2-查询忙闲)。
+- **`+freebusy` 只适用于查询忙碌/空闲时间段这一事实**。如果目标是"给会议**推荐**一个合适的时间段"（单人或多人），必须优先使用 [`+suggestion`](references/lark-calendar-suggestion.md)——它会综合**工作时间段、忙碌时间段、休息时间段**来推荐，`+freebusy` 只回答"哪些区间空着"，不判断该区间是否适合排会。
+- **多人公共空闲**：只想拿"哪些区间共同没被占"→ `--type common_free [--min-duration <dur>]`；想拿"推荐的会议时间段"→ 走 `+suggestion`。
 
 ## 前置条件路由
 
@@ -120,6 +147,9 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
 - **日程会议 ID（Meeting ID）**：日程的历史视频会议 ID，在日程上开过视频会议才会有。
+- **日程分享链接 vs 会议链接**：两者是不同事物，不可混用。
+  - 日程分享链接：`https://<domain>/calendar/share?token=<token>`，指向日程本身，用于分享日程详情。
+  - 会议链接：`https://<domain>/j/<number>`，指向视频会议入口；同一重复性日程序列的所有实例共用同一个会议链接。
 
 ## 术语映射
 
@@ -134,11 +164,12 @@ lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
 | 查询日历/日程或未来时间的会议 | 本 skill |
 | 按关键词搜索日程 | 本 skill（`+search-event`） |
 | 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
+| 查看日程的参会人 / 会议室（含 `--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) |
 | 预约/改约日程、调整时间、添加/更换会议室、查会议室 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
 | 仅编辑日程字段（标题/描述）或增删参会人（不涉及时间和会议室） | 先定位 `event_id`，再读 [+update](references/lark-calendar-update.md) 执行变更 |
-| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
+| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)；`+update` / `+delete` 均通过 `--apply-to=single|all|this-and-following` 指定范围 |
 | 转让日程组织者（「把这个日程交给 XX」「组织者改成 XX」「这个会转给我」「bot 建完还给我」） | 读 [+transfer](references/lark-calendar-transfer.md)；`--as` 用**当前组织者**身份，`--to-user-id` 传接收人，用户和机器人任意互转 |
 
 ## 任务类型分流
@@ -170,9 +201,6 @@ lark-cli calendar <resource> <method> [flags]
 # 查询用户主日历
 lark-cli calendar calendars primary
 
-# 获取日程详情及 app_link
-lark-cli calendar events get --calendar-id <calendar_id> --event-id <event_id>
-
 # 获取日程分享链接（分享给他人/群前必须先拿到）
 # 返回形如 {{domain}}/calendar/share?token=<token> 的分享链接，不是 applink；直接把该链接发给对方（对方可凭链接中的 token 走 +join-event 加入）
 lark-cli calendar events share_info --calendar-id <calendar_id> --event-id <event_id>
@@ -194,8 +222,8 @@ lark-cli calendar events delete --calendar-id <calendar_id> --event-id <event_id
 ## 常用其他域命令
 
 ```bash
-# 搜索用户，更多参数详见 lark-contact
-lark-cli contact +search-user --query <query> --as user
+# 批量搜索多个用户，更多参数详见 lark-contact
+lark-cli contact +search-user --queries "<q1>,<q2>" --as user
 
 # 搜索群聊，更多参数详见 lark-im
 lark-cli im +chat-search --query <query> --as user

package/skills/lark-calendar/references/lark-calendar-list-attendees.md

@@ -0,0 +1,33 @@
+# calendar +list-attendees
+
+列出单个日程的参与人（用户 / 会议室 / 群 / 三方邮箱）。只读。
+
+## 命令
+
+```bash
+# 查看指定日历（默认primary）下某日程的全部类型参与人和会议室
+lark-cli calendar +list-attendees --calendar-id <calendar_id> --event-id <event_id>
+
+# 只看会议室
+lark-cli calendar +list-attendees --event-id <event_id> --type resource
+
+# 同时看用户与会议室
+lark-cli calendar +list-attendees --event-id <event_id> --type user --type resource
+
+# 分页续拉（由调用方基于 has_more / page_token 决定是否再调一次）
+lark-cli calendar +list-attendees --event-id <event_id> --page-size 100 --page-token <page_token>
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--event-id <id>` | **是** | 目标日程 ID |
+| `--calendar-id <id>` | 否 | 日历 ID，省略则使用主日历（`primary`） |
+| `--type <type>` | 否 | 按 attendee 类型过滤；可重复或逗号分隔。枚举：`user` / `resource` / `chat` / `third_party`。留空返回全部类型|
+| `--page-size <n>` | 否 | 上游分页大小；默认 `20`|
+| `--page-token <token>` | 否 | 上游分页游标，来自上一次返回的 `page_token` |
+
+## 提示
+
+- `type=chat` 的群参与人**不返回 `rsvp_status`**（群本身没有群级 RSVP 状态）。需要群成员的 RSVP 请走原生 OpenAPI。

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

@@ -1,91 +1,87 @@
 # 重复性日程操作规范
 
-重复性日程的编辑/删除分为三种范围：「仅此次」「全部」「此次及后续」。用户未明确范围时，**必须询问确认**。
+重复性日程/例外的编辑和删除必须显式指定操作范围。相关命令：
 
-## 关键概念
-
-- **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. 确认用户的操作范围。
+> **强制规则：用户未明确操作范围时，必须先向用户确认，禁止 Agent 默认选取任何 `--apply-to`。** 用户表达含糊（如「删掉这个会」「改一下这个日程」）时也必须确认——`--apply-to=single` 只删/改一次，`--apply-to=all` 会影响整个序列及所有例外，代价截然不同。
 
-## 编辑全部（更新时间）
+## `--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/references/lark-doc-create-workflow.md

@@ -116,6 +116,6 @@ lark-cli docs +script --command init-draft --presentation-decision '<上方完
 1. 只有最新 release candidate 完成 Draft Profile Check 和 XML 规则复查后，才读取 [`lark-doc-create.md`](lark-doc-create.md)，使用同一个 `draft_path` 创建文档。
 2. 创建结果存在 warning、局部资源失败或回查发现局部问题时，不得再次新建文档；读取 [`lark-doc-update.md`](lark-doc-update.md)，对已创建文档做最小范围修复，并按 update 流程 fetch 验证。
 
-### Step 8：清理并交付。
+### Step 8：交付。
 
-无论创建成功、失败或被阻塞，只要 Step 4 已返回 `work_dir`，就先离开该目录，再使用当前运行时的文件删除能力精确删除整个 `work_dir`；不要使用通配符，也不要删除目录外的用户原始文件。最终只交付用户需要的结果，并说明必要来源、未关闭缺口、异常、失败或阻塞原因，以及文档 URL 或 token。
+保留 Step 4 返回的 `work_dir` 及其中的创作草稿。最终只交付用户需要的结果，并说明必要来源、未关闭缺口、异常、失败或阻塞原因，以及文档 URL 或 token。

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

@@ -38,7 +38,7 @@ lark-cli docs +script --command init-draft \
 - 决策必须是单个 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，首次写入前不要读取该路径。
-- 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；使用完后精确删除 `workspace`。
+- 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；保留 `workspace` 及其中的创作草稿。
 
 ## `parse`
 

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-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` | 恢复已确认资源并清理本次新建目标 |