@wagemule/daemon 0.1.0 → 0.1.3

package/dist/skills/larksuite/lark-calendar/references/lark-calendar-schedule-meeting.md

@@ -0,0 +1,265 @@
+# 预约/改约日程或会议、查询/搜索可用会议室的工作流
+
+## CRITICAL 执行摘要（先按这个骨架执行，再看下方细则）
+
+- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。** 不要把“预约/查会议室”默认等同于“新建”。
+- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。** 用户一旦给出了既有日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（加人、删人、改时间、换会议室等），默认走编辑流。
+- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，避免把用户带入表单式问答。
+- **新建流先补默认值，编辑流先继承已定位日程信息。** 默认值包括标题、参会人、时长，以及在“完全无时间信息”时的默认时间范围；编辑流则优先复用已定位日程的标题、时间、已有参与人和会议室信息作为基线。
+- **只有三类场景才主动追问用户**：存在时间冲突、搜索结果无法唯一确定、时间语义本身有歧义。
+- **编辑流的时间基准必须明确。** 如果编辑时不改时间，则后续会议室搜索必须基于已定位日程的原始起止时间；如果既改时间又加会议室，必须先确定最终时间，再基于该时间搜索会议室。
+- **编辑流中“新增会议室”默认是增量语义。** 如果用户说的是“加会议室/再加一个会议室”，最终 `+update` 只做 `add`，默认保留已有会议室；只有在用户明确说“更换会议室/移除会议室”时，才执行旧会议室删除。
+- **明确时间**：若需要会议室，先 `+room-find`；再 `+freebusy` 判断参会人忙闲；有冲突时先说明冲突，再让用户决定继续当前时间还是改走 `+suggestion`。
+- **模糊时间或无时间信息**：先 `+suggestion` 产出候选时间块；若需要会议室，再把这些时间块批量交给 `+room-find`，将“候选时间 + 对应可用会议室”一次性展示给用户选择。
+- **BLOCKING REQUIREMENT: 只要面临时间方案（模糊时间/无时间）或会议室方案（需要会议室）的选择，必须先向用户展示选项并等待用户明确确认，绝对禁止在未获用户确认的情况下直接执行创建新日程或更新既有日程。**
+- **用户选中了 `+suggestion` 返回的候选时间块后，不要再次调用 `+freebusy`。** 用户确认后直接进入最终落地操作：创建新日程，或更新既有日程。
+- **当用户说“查会议室”“找会议室”“搜可用会议室”时，默认意图是查会议室可用性，不是检索会议室资源名录。**
+- **必须按顺序执行。** 不要跳过“任务类型判定”“目标日程定位（编辑流）”“补默认值/继承基线信息”“判断时间明确性”这些前置步骤。
+
+> **💡 核心原则：做智能助理，充分利用默认值规则（如默认标题、时长、参与人等）自动补全信息。极力避免像“表单填写机”一样频繁打断并反问用户，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。**
+
+## 严禁行为
+
+- **严禁在未读取对应子命令文档（如 `lark-calendar-room-find.md`、`lark-calendar-suggestion.md`）的情况下直接调用命令！** 必须先阅读文档掌握最新参数要求与规范。
+- **严禁在尚未判断“新建”还是“编辑”之前，就直接进入创建日程或查会议室动作。**
+- **严禁把“给明天上午的‘产品发布会’加人/加群/加会议室”这类带有既有日程锚点 + 修改动词的请求，当成新建日程。** 这类请求必须先定位目标日程。
+- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一的 `event_id` 前，不得调用 `+update`、也不得基于猜测时间去查会议室。
+- **严禁在用户仅要求“查会议室”但未提供明确时间时，直接调用 `+room-find`！** 必须先默认一个合理时间范围，调用 `+suggestion` 拿到候选时间块，再将时间块传给 `+room-find`。
+- **不要在用户完全没给时间时，直接反问“你想约什么时候”。** 先补一个合理时间范围，再进入 `+suggestion`。
+- **不要在“需要会议室 + 时间模糊”的场景下，先让用户只选时间。** 应先批量查出每个候选时间对应的可用会议室，再让用户一次性完成选择。
+- **不要在用户已经选中 `+suggestion` 候选时间后，再重复调用 `+freebusy`。**
+- **不要在用户未明确说出城市时，仅凭园区/办公室名自动补城市。**
+- **严禁在面临时间方案或会议室方案的选择时（模糊时间、无时间或需要会议室），未经用户确认就擅自创建新日程或更新既有日程。**
+
+## 适用场景
+
+- “帮我约个会”
+- “下周找时间和 XX 开会”
+- “帮我订个会议室”
+- “帮我找/搜索一个可用的会议室”
+- “帮我推荐一个我以前常用的会议室”
+- “查询明天下午可用的会议室”
+- “明天下午3点约个日程/日历”
+- “把明天上午的日程‘产品发布会’加上 小明
+- “给下周一的周会换个会议室”
+- “把这个日程改到明天下午，并加上学清 F201”
+
+## 核心概念
+
+- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。** 
+- **预定或查找会议室，均需先确定时间块。** 在推荐可用会议室后，应顺势引导用户完成最终的**日程落地**操作：创建新日程，或更新既有日程。
+
+## CRITICAL 约束
+
+- **在调用任何具体的 CLI 子命令（如 `+room-find`、`+suggestion`、`+freebusy`、`+create`）前，必须先读取其对应的 Markdown 文档。** 禁止仅凭记忆组装命令参数，以确保符合各命令最新的业务约束和格式规范。
+- **当用户说“查会议室”“找会议室”“搜可用会议室”等，默认意图是查询会议室可用性，而不是检索会议室资源名录。**
+- **必须严格按照下方【工作流】的步骤顺序完成任务。特别是单独查会议室时，若无明确时间，强制先走“模糊时间/无时间信息”分支调用 `+suggestion`。**
+
+## 任务类型判定
+
+| 类型 | 典型语言信号 | 第一动作 |
+|------|--------------|----------|
+| 新建日程 | “约个会”“安排一个会议”“新建日程”“帮我订个会议室开会” | 补默认值，再进入时间判断 |
+| 编辑已有日程 | “给某个日程加人/删人/加群/加会议室”“把某个日程改到…”“给这场会换个会议室” | 先定位目标日程 `event_id`，再进入后续流程 |
+
+进一步规则：
+
+- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`、某次实例）和**修改动词**（添加、移除、调整、改到、换、延后、提前），默认判定为**编辑已有日程**。
+- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`，不能直接拿原重复日程的 `event_id` 做更新。
+
+## 工作流
+
+### 1. 编辑已有日程：先定位目标日程
+
+一旦判定为编辑流，必须先定位目标日程；没有 `event_id` 就不能继续后续修改动作。
+
+定位规则：
+
+- 优先利用用户给出的标题、日期、时间范围、`这个日程/这场会` 等锚点，通过 `+agenda`、`events search_event` 或实例视图缩小范围。
+- 如果命中多个候选日程，必须向用户展示候选项并要求确认，禁止自行猜测。
+- 如果是重复性日程的某一次实例，必须继续定位到该次实例的 `event_id`。
+
+编辑流分支规则：
+
+- **仅增删普通参会人/群组，不改时间，也不涉及会议室**：定位完成后可直接进入最终 `+update`。
+- **新增会议室，但不改时间**：必须基于已定位日程的当前 `start/end` 作为时间块执行 `+room-find`，不能因为用户没重复说时间就退回“无时间信息”。
+- **既改时间，又新增会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；最终只增量添加新会议室，不自动删除已有会议室。
+- **既改时间，又更换会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；只有在用户明确表达“更换”时，最终才执行“移除旧会议室 + 添加新会议室”。
+- **只改时间，不涉及会议室**：沿用下方时间工作流，但最终落地必须是 `+update`，不是 `+create`。
+
+### 2. 新建日程：智能推断默认值
+以下信息智能推断，减少频繁询问用户：
+
+- **标题**：根据上下文自动生成，例如“沟通对齐”“需求讨论”；如无法推断，默认为“会议”
+- **参会人**：如未明确指定其他人，默认参会人仅为**用户自己**
+- **时长**：基于会议类型和上下文动态推断；如无法推断，默认为 30 分钟
+- **无任何时间信息**：默认推断一个合理区间（如“今天”或“近两天”），并进入时间推荐流程，禁止询问用户
+
+当搜索特定参与人（人、群）出现多个结果无法唯一确定时，必须询问用户进行选择确认，并将该偏好记录为长期记忆，以便后续自动识别。
+
+### 3. 判断时间是否明确
+
+这一步判断的是**最终要落地的目标时间**，不是只看用户原句里有没有重复说时间。
+
+时间基准规则：
+
+- **新建流**：使用用户给出的时间，或默认补全出的时间范围作为时间基准。
+- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是时间基准。后续如需查会议室，直接使用这个明确时间块。
+- **编辑流且改时间**：用户想改到的新时间才是时间基准；若表达模糊，则进入 `+suggestion`。
+
+分两类处理：
+
+- **明确时间**：如“明天下午3点”
+- **模糊时间**：如“明天下午”“下周找个时间”
+
+### 4. 明确时间
+
+明确时间时，需先判断是否需要会议室，如果需要，提前查询会议室；然后判断是否有时间冲突。这里的“明确时间”既可以来自用户直接表达，也可以来自已定位日程的原始时间。
+详见 [`+room-find`](./lark-calendar-room-find.md) 与 [`+freebusy`](./lark-calendar-freebusy.md)。
+
+```bash
+# 1. 如果需要会议室，提前查询会议室
+lark-cli calendar +room-find \
+  --slot "<start>~<end>" \
+  --attendee-ids "<ids>" \
+  --city "<city>" \
+  --building "<building>" \
+  --floor "<F2>" \
+  --room-name "<room_name>"
+
+# 2. 查询当前用户及其他参会人忙闲
+# （如果有多名参会人，需分别调用查询：--user-id "<ou_xxx>"）
+lark-cli calendar +freebusy --start "<start>" --end "<end>"
+```
+
+规则：
+
+- **参会人过多或包含群组时的处理**：
+  - 如果参与人过多（例如超过 5 人），为避免高耗时，仅需查询**当前用户（自己）**及少数核心人员的忙闲状态即可。
+  - 如果参与人中包含**群组**，无需展开群组成员查询其忙闲状态。
+- **编辑已有日程且不改时间，只新增会议室时**：这里的 `--slot` 必须来自已定位日程的当前 `start/end`。
+- **编辑已有日程且既改时间又加会议室时**：这里的 `--slot` 必须来自候选新时间，而不是旧时间；如果用户是“新增会议室”，后续落地只做添加，不删除旧会议室。
+- **如果没有冲突**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
+- **如果有冲突**：必须先说明冲突情况，询问用户继续选择这个时间还是换个时间
+  - **如果说换个时间**：放弃当前时间，转入【模糊时间】流程，调用 `+suggestion` 推荐多个可用时间块
+  - **如果继续选择这个时间**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
+- 位置信息要优先拆到结构化字段：用户明确说了城市才提取 `--city`；`--building` 不要再重复携带城市前缀。
+- 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。像 `2L`、`2F` 这类更像楼层或区域定位的短词，优先视为 `--floor`，不要默认当作 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
+- 会议室名要做轻量归一化：`木星会议室` -> `--room-name "木星"`；`会议室 02` / `02会议室` -> `--room-name "02"`。
+- 对 `F3-05` / `F5-07` / `3楼-08` 这类复合表达，若能稳定识别楼层与会议室号，应优先提取为 `--floor + --room-name`，不要把整段直接退化成 `--room-name`。
+
+### 5. 模糊时间或无时间信息
+
+先调用：
+详见 [`+suggestion`](./lark-calendar-suggestion.md)；若需要会议室，再结合 [`+room-find`](./lark-calendar-room-find.md)。
+
+```bash
+lark-cli calendar +suggestion \
+  --start "<range_start>" \
+  --end "<range_end>" \
+  --attendee-ids "<ids>" \
+  --duration-minutes <n> \
+  --event-rrule "<rrule>"
+```
+
+规则：
+
+- 若用户完全没有提供时间信息，应先默认一个合理区间后再调用 `+suggestion`
+- 编辑流中，若用户表达的是“改到明天下午”“下周找个时间再约”这类模糊新时间，则基于用户期望的新时间范围调用 `+suggestion`；不要继续沿用旧时间。
+- **不需要会议室**：获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入最终落地操作：创建新日程，或更新既有日程。
+- **需要会议室**：获取多个候选时间块后，**不要急于让用户选时间**。先将这些时间块一次性交给 `calendar +room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化分行展示，让用户一次性完成选择。（**注意：即使用户最初只说“查会议室”，且未带时间，也必须强制走到这一步，先 suggestion 再 room-find**）。
+- 用户一旦选择了 `+suggestion` 返回的时间块，**无需再次调用 `+freebusy`**
+
+### 6. 模糊语义消解与长期记忆构建
+
+针对用户专属的时间表达习惯或存在歧义的时间场景，严禁主观臆断。典型例子包括：
+
+- “上班后”
+- “下班前”
+- 未明确上下午的 12 小时制时间表达
+
+处理规则：
+
+- 应主动澄清真实意图，而不是自行猜测
+- 当用户给出澄清后，应将这类个性化定义沉淀为长期偏好，推动后续直接理解类似表达
+
+### 7. 重复性日程
+
+若当前会议为重复性日程，调用 `+room-find` 时需携带 `--event-rrule`。
+
+必须检查返回中的：
+
+- `reserve_until_time`
+
+若候选会议室的可预约上限早于重复规则覆盖范围，**不要直接按原规则落地日程**。应：
+
+- 向用户明确说明该会议室最长可约至何时。
+- 若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。
+
+### 8. 落地日程变更
+
+用户确认后调用：
+如果是新建会议，详见 [`+create`](./lark-calendar-create.md)。
+如果是更新既有日程，详见 [`+update`](./lark-calendar-update.md)。必须先定位目标 `event_id`，再按用户意图用 `+update` 独立执行字段更新、添加参会人/会议室、移除参会人/会议室，或组合这些动作。若用户意图是“新增会议室”，默认仅追加 `room_id`，不移除已有会议室。
+
+```bash
+lark-cli calendar +create \
+  --summary "..." \
+  --start "<start>" \
+  --end "<end>" \
+  --attendee-ids "ou_xxx,oc_xxx,omm_xxx"
+
+lark-cli calendar +update \
+  --event-id "<event_id>" \
+  --start "<start>" \
+  --end "<end>" \
+  --add-attendee-ids "omm_new_room"
+
+# 仅当用户明确要求“更换会议室”时，才同时移除旧会议室并添加新会议室
+lark-cli calendar +update \
+  --event-id "<event_id>" \
+  --remove-attendee-ids "omm_old_room" \
+  --add-attendee-ids "omm_new_room"
+```
+
+规则：
+- 新建日程时，可使用 `+create`
+- 更新既有日程时，优先使用 `+update`。改时间/标题/描述、添加参会人/会议室、移除参会人/会议室可以分别独立执行；
+- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新按标题猜测一次目标日程。
+- 编辑流中如果只是新增群组或普通参会人，不涉及时间和会议室，可直接 `+update --add-attendee-ids ...`。
+- 编辑流中如果是“新增会议室但不改时间”，必须先基于目标日程原始时间查到可用会议室，再 `+update --add-attendee-ids "<room_id>"`；默认保留已有会议室。
+- 编辑流中如果是“既改时间又新增会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间与新增会议室；默认保留已有会议室。
+- 编辑流中如果是“既改时间又更换会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间、移除旧会议室并添加新会议室。
+- 需要会议室时，将选中的 `room_id` 写入最终落地请求的参与人列表
+- 展示会议室候选时，必须保留 CLI/API 返回的完整 `room_name` 原值；允许附加“推断说明”，但禁止用摘要名、楼层及会议室号、容量/视频标签重组后的名称替换原值
+
+## 用户展示建议
+
+当向用户展示多个时间块及对应的多个会议室时，**必须使用结构化清晰的格式排版**。**严禁将时间与会议室名称放在同一行展示**，必须分行并使用编号列表呈现可用会议室，严禁将所有信息揉成一团纯文本堆叠。
+
+**推荐展示格式参考：**
+
+```text
+## 2026-03-27 周五
+
+[选项 1] 14:00 - 15:00（参会人均空闲）
+  可用会议室：
+  1. 学清嘉创大厦B座-F2-02🎦(7人)
+  2. 学清嘉创大厦B座-F2-05🎦(10人)
+
+[选项 2] 16:00 - 17:00（参会人均空闲）
+  可用会议室：
+  1. 学清嘉创大厦B座-F3-01🎦(6人)
+  2. 学清嘉创大厦B座-F3-06🎦(8人)
+
+💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
+```
+
+## 参考
+
+- [lark-calendar-room-find.md](./lark-calendar-room-find.md)
+- [lark-calendar-freebusy.md](./lark-calendar-freebusy.md)
+- [lark-calendar-suggestion.md](./lark-calendar-suggestion.md)
+- [lark-calendar-create.md](./lark-calendar-create.md)
+- [lark-shared](../../lark-shared/SKILL.md)
+- [lark-calendar](../SKILL.md)

package/dist/skills/larksuite/lark-calendar/references/lark-calendar-suggestion.md

@@ -0,0 +1,125 @@
+# calendar +suggestion
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
+
+根据非明确时间或一段时间范围，推荐多个可用时间块方案。帮助用户解决协调时间的难题。
+
+**调用时机 (Agent Guidance):**
+- ✅ **当用户需求涉及寻找时间块，且时间未完全确定**（如`今天`、`近三天`、`本周`、`下午`, `无时间描述`）时，调用此工具来获取推荐时间块给用户选择（包括但不限于预约日程）。
+- ❌ **当用户已经明确了具体的时间点**（如`今天下午3点`），则**不需要**调用此工具
+
+需要的scopes: ["calendar:calendar.free_busy:read"]
+
+## 命令
+
+```bash
+# 获取默认的时间推荐方案（搜索范围：当前时刻至当天结束）
+lark-cli calendar +suggestion
+
+# 获取指定时间区间内的推荐方案（支持日期简写或完整 ISO 8601）
+lark-cli calendar +suggestion \
+  --start "2026-03-19" \
+  --end "2026-03-20"
+
+# 结合参与人及会议时长获取推荐方案（时长单位：分钟）
+# --attendee-ids 支持传入用户（ou_ 前缀）和群组（oc_ 前缀）混合列表
+lark-cli calendar +suggestion \
+  --start "2026-03-19T14:00:00+08:00" \
+  --end "2026-03-19T18:00:00+08:00" \
+  --attendee-ids ou_xxx,oc_yyy \
+  --duration-minutes 60
+
+# 排除特定时间段
+lark-cli calendar +suggestion \
+  --start "2026-03-19T08:00:00+08:00" \
+  --end "2026-03-19T18:00:00+08:00" \
+  --exclude "2026-03-19T12:00:00+08:00~2026-03-19T13:00:00+08:00"
+
+# JSON 格式输出
+lark-cli calendar +suggestion \
+  --start "2026-03-19T08:00:00+08:00" \
+  --end "2026-03-19T18:00:00+08:00" \
+  --format json
+```
+
+## 参数
+
+| 参数                              | 必填    | 说明                                                                  |
+| ------------------------------- | ----- | ------------------------------------------------------------------- |
+| `--start <time>`                | 否     | 搜索区间开始时间（支持日期/ISO 8601等格式，默认**当前时间**）                                |
+| `--end <time>`                  | 否     | 搜索区间结束时间（默认与 `--start` 属于同一天，自动取当天结束时间）                                                     |
+| `--attendee-ids <id_list>`     | 否     | 目标参与人 ID 列表。提取对应实体的 ID。支持用户（`ou_` 前缀）和群组（`oc_` 前缀）。多个 ID 使用英文逗号分隔 |
+| `--event-rrule <rrule>`         | 否     | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1"                                              |
+| `--duration-minutes <min>`      | 否     | 会议时长（分钟）。优先使用用户显式指定的值，若未指定则尝试根据上下文推断，推断失败则不传                                        |
+| `--timezone <tz>`               | 否     | 对话中明确提及的预约日程所使用的时区（默认取用户设备时区，例如 `Asia/Shanghai`）                                |
+| `--exclude <times>`             | 否     | 排除的时间块，支持 `start~end` 格式（如 `2026-03-19T12:00:00+08:00~2026-03-19T13:00:00+08:00`），多个用逗号分隔 |
+| `--format <flag>`               | 否     | 输出格式（固定为 `json`） |
+| `--dry-run`                     | 否     | 预览 API 调用，不执行                                                       |
+
+## 时间格式
+
+`--start`、`--end` 以及 `--exclude` 支持以下格式自动解析：
+
+| 格式            | 示例                          | 说明                   |
+| ------------- | --------------------------- | -------------------- |
+| ISO 8601      | `2026-03-19T08:40:29+08:00` | 完整格式，精确包含日期、时间及带冒号的时区偏移 |
+| 日期+时间       | `2026-03-19 08:40:29`       | 自动补全时区               |
+| 仅日期          | `2026-03-19`                | start 取 00:00:00，end 取 23:59:59 |
+| Unix 时间戳     | `1741564800`                | 秒级时间戳               |
+
+## 输出格式
+
+**将推荐结果整理为易读的选项列表，并附上润色后的推荐理由：**
+
+```text
+## 2026-03-19 周四
+
+- **选项 1：10:00 - 10:30**
+  推荐理由：所有参与者均空闲。
+
+```
+> **AI 行为指导：** 
+> - **结构化展示选项与理由**：以清晰的列表呈现推荐时间方案，并直接询问用户意向。**必须**结合“用户原始需求”与“推荐理由”说明每个时间块的优势，输出话术需简明、直接、无歧义。
+> - **如实反馈冲突情况**：注意，返回的推荐方案不一定都是完全空闲的（即使明确要求找空闲时间，系统在难以满足时也会返回包含忙闲冲突的方案）。判断推荐方案是否完全空闲，可以从推荐理由中是否表达了“完全空闲”或“没有任何忙闲冲突”来判断。如果推荐方案存在忙闲冲突，**必须**在展示方案时向用户如实说明冲突情况，绝不能误导用户认为是完全空闲。
+> - **主动提供优化建议**：当满足以下任一条件时（1. 返回结果包含 `ai_action_guidance` 字段内容；2. 用户要求找个空闲时间，但所有推荐方案都不是完全空闲的），你**必须**主动提供优化建议。若存在 `ai_action_guidance` 字段，需严格依据其核心意图生成引导话术；否则，请基于实际冲突情况主动提供合理的替代方案（如：建议调整时间范围、会议时长或参与人）。
+
+## 典型场景
+
+### 1. 查找多人的共同空闲会议时间
+
+```bash
+# 指定两名参与人，并要求找一个 45 分钟的空闲时段
+lark-cli calendar +suggestion \
+  --start "2026-03-19T08:00:00+08:00" \
+  --end "2026-03-19T18:00:00+08:00" \
+  --attendee-ids ou_member_a,ou_member_b \
+  --duration-minutes 45
+```
+
+### 2. 用户对当前推荐不满意，要求“换一批”
+
+```bash
+# 将上一次推荐的时段作为排除条件传入
+lark-cli calendar +suggestion \
+  --start "2026-03-19T08:00:00+08:00" \
+  --end "2026-03-19T18:00:00+08:00" \
+  --exclude "2026-03-19T10:00:00+08:00~2026-03-19T10:30:00+08:00"
+```
+
+## 与其他命令对比
+
+| 命令                     | 用途       | 输出内容                |
+| ---------------------- | -------- | ------------------- |
+| `calendar +suggestion` | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 | 返回多个推荐时段及其理由，以及后续建议 |
+| `calendar +freebusy`   | 查询忙闲时段   | 只返回忙碌时段列表和rsvp状态（无日程详情）    |
+
+**选择建议**：
+
+- **寻找可用时间（含开会等场景）** → 优先使用 `+suggestion`，直接获取智能推荐方案
+- **了解个人当前忙碌情况** → 使用 `+freebusy`
+
+## 参考
+
+- [lark-calendar-create](lark-calendar-create.md) — 创建日程
+- [lark-calendar-freebusy](lark-calendar-freebusy.md) — 查询忙闲时段和rsvp状态
+- [lark-calendar](../SKILL.md) — 日历完整 API

package/dist/skills/larksuite/lark-calendar/references/lark-calendar-update.md

@@ -0,0 +1,105 @@
+# calendar +update
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新既有日程字段，或独立增量添加/移除参会人和会议室。
+
+`+update` 支持三类互相独立的动作：更新日程字段、添加参会人/会议室、移除参会人/会议室。它们可以单独执行，也可以在同一次命令中组合执行。
+
+需要的 scopes: ["calendar:calendar.event:update"]
+
+## 推荐命令
+
+```bash
+# 更新标题、描述、时间
+lark-cli calendar +update \
+  --event-id "<EVENT_ID>" \
+  --summary "产品评审" \
+  --description "评审需求范围、排期与风险" \
+  --start "2026-03-12T14:00+08:00" \
+  --end "2026-03-12T15:00+08:00"
+
+# 增量添加参会人和会议室
+lark-cli calendar +update \
+  --event-id "<EVENT_ID>" \
+  --add-attendee-ids "ou_aaa,ou_bbb,omm_room"
+
+# 移除参会人和会议室
+lark-cli calendar +update \
+  --event-id "<EVENT_ID>" \
+  --remove-attendee-ids "ou_aaa,omm_room"
+
+# 同时更新日程信息、移除旧会议室、添加新会议室
+lark-cli calendar +update \
+  --event-id "<EVENT_ID>" \
+  --summary "产品评审" \
+  --start "2026-03-12T15:00+08:00" \
+  --end "2026-03-12T16:00+08:00" \
+  --remove-attendee-ids "omm_old_room" \
+  --add-attendee-ids "omm_new_room"
+```
+
+参数：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程要先定位到目标实例的 `event_id`，不要直接使用原重复日程 ID |
+| `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
+| `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
+| `--description <text>` | 否 | 新日程描述。目前 API 方式不支持编辑富文本描述；如果日程描述通过客户端编辑为富文本内容，则使用 API 更新描述会导致富文本格式丢失。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空 |
+| `--start <time>` | 否 | 新开始时间（ISO 8601，如 `2026-03-12T14:00+08:00`）。更新日程时间时必须同时传 `--end` |
+| `--end <time>` | 否 | 新结束时间（ISO 8601）。更新日程时间时必须同时传 `--start` |
+| `--rrule <rrule>` | 否 | 新重复规则（RFC5545）。**不要使用 COUNT；如需限制次数，推算后转为 UNTIL** |
+| `--add-attendee-ids <id_list>` | 否 | 增量添加参会人/会议室，逗号分隔。支持用户 `ou_`、群组 `oc_`、会议室 `omm_` |
+| `--remove-attendee-ids <id_list>` | 否 | 增量移除参会人/会议室，逗号分隔。支持用户 `ou_`、群组 `oc_`、会议室 `omm_` |
+| `--notify` | 否 | 是否发送更新通知，默认 `true`。可用 `--notify=false` 静默更新 |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+至少需要提供一个动作：`--summary`、`--description`、`--start/--end`、`--rrule`、`--add-attendee-ids` 或 `--remove-attendee-ids`。
+
+## 使用规则
+
+- `--add-attendee-ids` 是**增量添加**，不是替换最终参与人列表。不要用它表达“只保留这些人”。
+- 对 `--summary`、`--description`，CLI 以“是否显式传入该 flag”判断是否更新，而不是以“值是否为空”判断；如果显式传入空字符串，会把对应字段清空。
+- 只想增删参会人或会议室时，不需要同时传 `--summary`、`--start`、`--end` 等日程字段。
+- 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
+- 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
+- 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
+- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`events search_event` 或实例视图定位该实例的 `event_id`。
+- 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
+- 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
+
+## 高级用法（完整 API 命令）
+
+`+update` 只覆盖标题、描述、时间、重复规则，以及参会人/会议室的增量添加或移除。
+
+如需更新 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、`color`（颜色）、附件、视频会议信息、全天日程，或在新增参会人时配置可选参加状态 等高级参数，请改用完整的 API 命令。建议先通过 `lark-cli schema calendar.events.patch`、`lark-cli schema calendar.event.attendees.create`、`lark-cli schema calendar.event.attendees.batch_delete` 查看完整参数定义。
+
+> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
+
+## 预约/改约会议室场景
+
+如果用户要“改会议时间”“换会议室”“给现有日程加会议室”，必须先阅读 [`lark-calendar-schedule-meeting.md`](lark-calendar-schedule-meeting.md) 并按其中工作流处理：
+
+- 明确时间且需要会议室：先 `+room-find`，再按需 `+freebusy`，用户确认后再 `+update`。
+- 模糊时间或无时间：先 `+suggestion`，如需会议室再批量 `+room-find`，用户确认后再 `+update`。
+- 面临时间方案或会议室方案选择时，必须先展示候选方案并等待用户确认。
+
+## 参会人类型
+
+| 前缀 | 类型 | 说明 |
+|------|------|------|
+| `ou_` | user | 飞书用户 open_id |
+| `oc_` | chat | 飞书群组 |
+| `omm_` | resource | 会议室 |
+
+> [!CAUTION]
+> 这是**写入操作**。执行前必须确认用户意图，特别是移除参会人/会议室或移动会议时间。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) -- 日历全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-calendar-schedule-meeting](lark-calendar-schedule-meeting.md) -- 预约/改约会议与会议室工作流
+- [lark-calendar-room-find](lark-calendar-room-find.md) -- 查找可用会议室
+- [lark-calendar-freebusy](lark-calendar-freebusy.md) -- 查询忙闲

package/dist/skills/larksuite/lark-contact/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: lark-contact
+version: 1.0.0
+description: "飞书 / Lark 通讯录,用于按姓名 / 邮箱把员工解析成 open_id,以及按 open_id 反查员工的姓名 / 部门 / 邮箱 / 联系方式。当用户说出某人姓名而下一步需要发消息 / 加群 / 排日程时,先用本 skill 把姓名换成 ID;当输出里出现 open_id 需要展示成姓名给用户看,或用户直接询问某人的部门 / 邮箱 / 联系方式时,用本 skill 查。不负责部门树遍历、按部门列员工、组织架构图,这类需求走原生 OpenAPI。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli contact --help"
+---
+
+# lark-contact
+
+## 选哪个命令
+
+**user 身份和 bot 身份是两条完全独立的路径**。先确定当前身份,再按下表选命令:
+
+| 想做什么 | user 身份 | bot 身份 |
+|---|---|---|
+| 按姓名 / 邮箱搜员工拿 open_id | [`+search-user`](references/lark-contact-search-user.md) | 不支持 |
+| 已知 open_id 取他人资料 | `+search-user --user-ids <id>` | [`+get-user --user-id <id>`](references/lark-contact-get-user.md) |
+| 查看自己 | `+get-user` 或 `+search-user --user-ids me` | 不支持 |
+
+已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 [`lark-im`](../lark-im/SKILL.md) / [`lark-calendar`](../lark-calendar/SKILL.md)。
+
+## 典型场景
+
+```bash
+# 找张三给他发消息:先搜,确认 open_id,再发
+lark-cli contact +search-user --query "张三" --has-chatted --as user
+lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
+```
+
+搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
+
+## 注意事项
+
+- **41050 / Permission denied** 受当前身份的可见范围限制(两条命令都可能遇到)。换 bot 身份或让管理员调整可见范围,细节见 [`lark-shared`](../lark-shared/SKILL.md)。
+- **跨租户用户**(`is_cross_tenant=true`)多数业务字段为空字符串,这是飞书可见性规则,下游做空值兜底。
+- **ID 类型**:默认 `open_id`。`+get-user` 可改 `--user-id-type union_id|user_id`;`+search-user` 只接受 `open_id`。
+
+## 不在本 skill 范围
+
+- 发消息 / 查聊天记录 → [`lark-im`](../lark-im/SKILL.md)
+- 排日程 / 邀请会议 → [`lark-calendar`](../lark-calendar/SKILL.md)
+- 部门树 / 按部门列员工 / 组织架构 ,通过 [`lark-openapi-explorer`](../lark-openapi-explorer/SKILL.md) 查找原生接口

package/dist/skills/larksuite/lark-contact/references/lark-contact-get-user.md

@@ -0,0 +1,19 @@
+# +get-user
+
+按 ID 取用户基本信息(姓名等)。
+
+```bash
+# 取自己
+lark-cli contact +get-user --as user
+
+# bot 按 ID 取他人
+lark-cli contact +get-user --user-id ou_xxx --as bot
+
+# 按 union_id / user_id 取(默认 open_id)
+lark-cli contact +get-user --user-id <id> --user-id-type union_id --as bot
+```
+
+## 注意事项
+
+- **user 身份按 ID 取他人请用 `+search-user --user-ids <id>`**,字段比本命令多(部门 / 邮箱 / 是否激活等)。本命令的 user 模式只回很少字段。
+- **`--as bot` 必须传 `--user-id`**:不传会直接报错(只有 user 身份能省略 `--user-id` 取自己)。