@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

package/shared/lark-cli/lark-base/references/lark-base-commands.md

@@ -0,0 +1,108 @@
+# base 域命令参考
+
+命令事实以 `lark-cli base +<cmd> --help` 为准。本文只补 `--help` 没说清的部分。
+
+## 通用
+
+- 所有命令默认 `--as user`。
+- 除 `+url-resolve` 外，其余命令都必须传 `--base-token`。
+- `--table-id` / `--view-id` 接 ID 或名称；ID 形态是 `tbl...` / `vew...`。
+
+## `+url-resolve`
+
+```bash
+lark-cli base +url-resolve --url "<Base/Wiki/记录分享 URL>" --as user
+```
+
+返回 `base_token`，以及所选块的类型 `block_type` 与对应 ID。这是所有后续调用的入口。
+
+**URL 里的 `table=` 不是 `table_id`。** 它表示当前选中的 Base **顶层块**，可能是数据表、仪表盘、workflow、文件夹或文档。判读返回值：
+
+- `base_token` → 直接用。
+- **仅当 `block_type` 为 `table` 时**，才把返回的 `table_id` 当数据表 ID 用。
+- `block_type` 是其他类型（或返回的是 `dashboard_id` / `workflow_id`、只有中性 `block_id`）时，说明用户当前选中的**不是数据表**：改用 `+table-list --base-token <t>` 列出真实数据表，再按用户点名的表名选定 `--table-id`。
+- `selection_source=url_query` 只说明「URL 当前选中了该块」，**不代表**它覆盖用户明确点名的目标。用户点名的目标与返回的 `block_name` 不一致时，以用户为准，走 `+table-list` 重新定位。
+
+绝不要从 URL 字符串里自行截取 `table=` 的值当 `--table-id`。
+
+## `+base-get` / `+table-list`
+
+```bash
+lark-cli base +base-get   --base-token <t> --as user
+lark-cli base +table-list --base-token <t> --limit 50 --as user
+```
+
+`+table-list` 的 `--limit` 范围 1-100，默认 50。
+
+## `+field-list` / `+view-list`
+
+```bash
+lark-cli base +field-list --base-token <t> --table-id <tbl> --as user
+lark-cli base +view-list  --base-token <t> --table-id <tbl> --as user
+```
+
+`--limit` 范围 1-200，默认 100。写记录级查询前先用 `+field-list` 确认字段名与类型，
+不要凭用户口述猜字段名。
+
+## 7 个 `+view-get*`
+
+```bash
+lark-cli base +view-get                  --base-token <t> --table-id <tbl> --view-id <v> --as user
+lark-cli base +view-get-filter           --base-token <t> --table-id <tbl> --view-id <v> --as user
+lark-cli base +view-get-sort             --base-token <t> --table-id <tbl> --view-id <v> --as user
+lark-cli base +view-get-group            --base-token <t> --table-id <tbl> --view-id <v> --as user
+lark-cli base +view-get-card             --base-token <t> --table-id <tbl> --view-id <v> --as user
+lark-cli base +view-get-timebar          --base-token <t> --table-id <tbl> --view-id <v> --as user
+lark-cli base +view-get-visible-fields   --base-token <t> --table-id <tbl> --view-id <v> --as user
+```
+
+共 7 个，按需取对应配置；`+view-get` 是视图本体元信息。
+
+## `+record-list`
+
+```bash
+lark-cli base +record-list --base-token <t> --table-id <tbl> --as user
+lark-cli base +record-list --base-token <t> --table-id <tbl> --view-id "<视图名>" --as user
+lark-cli base +record-list --base-token <t> --table-id <tbl> --field-id "标题" --field-id "状态" --as user
+```
+
+- 省略 `--view-id` 读全表；传 `--view-id` 读该视图筛选后的记录
+- `--filter-json` 是筛选 JSON 对象（结构见下方「filter 条件结构」，与 `+view-get-filter` 读到的同一套），**会覆盖 `--view-id` 的筛选**
+- `--sort-json` 是排序数组，如 `[{"field":"Updated","desc":true}]`
+- `--field-id` 可重复，用于只投影需要的字段，减少返回体
+- `--limit` 范围 1-200，默认 100
+
+## `+record-search`
+
+```bash
+lark-cli base +record-search --base-token <t> --table-id <tbl> --keyword "<关键词>" --as user
+```
+
+`--keyword` 必填（除非用 `--json` 直传请求体）。`--limit` 默认 10，范围 1-200。
+`--view-id` / `--filter-json` / `--sort-json` / `--field-id` 同 `+record-list`。
+
+## filter 条件结构
+
+`+view-get-filter` 返回的视图筛选、以及 `+record-list` / `+record-search` 的 `--filter-json`，共用同一套 tuple 结构：
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["状态", "intersects", ["Doing"]],
+    ["负责人", "intersects", [{ "id": "ou_xxx" }]],
+    ["截止时间", "empty"]
+  ]
+}
+```
+
+- 顶层是 `{logic?, conditions?}`；`logic` 取 `and`（默认）或 `or`；`conditions` 默认空数组。
+- 每条条件是 tuple `[field, operator, value?]`；`empty` / `non_empty` 写 2 项即可（`["截止时间","empty"]`）。
+- 清空筛选写 `{"conditions": []}`。
+- value 写法随字段类型而变：文本用字符串数组，单/多选用选项名数组，人员类（`user`/`created_by`/`updated_by`）用 `[{"id":"ou_xxx"}]`，checkbox 用布尔，日期类有专门的相对/绝对写法。构造前先用 `+field-list` 确认字段类型与选项名。
+
+> 这套 tuple 结构**不适用于聚合查询**。本沙箱未开放 `+data-query`，遇到"分组统计/聚合"类需求时不要臆造它的 `filters` 对象 DSL。
+
+## 选路
+
+按条件取原始记录用 `+record-list`；只有「模糊找含某关键词的记录」才用 `+record-search`。

package/shared/lark-cli/lark-calendar/README.md

@@ -0,0 +1,158 @@
+# calendar (v4)
+
+## 身份
+
+日程查询针对当前登录用户的日历（默认 `--as user`）。
+
+## Shortcuts
+
+| Shortcut | 说明 |
+|----------|------|
+| `+agenda` | 查看日程安排（默认今天） |
+| [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id |
+| `+freebusy` | 查询用户主日历的忙闲信息和 RSVP 状态（纯查询场景；找可用时段走 `+suggestion`） |
+| [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
+| [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
+
+### `+get` — 单日程详情
+
+通过 `calendar_id` + `event_id` 获取**单个日程**详情。
+
+```bash
+# calendar_id不传，默认primary
+lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id>
+```
+
+### `+search-event` — 按关键词、时间范围和参会人搜索日程
+
+仅返回基础字段（`event_id`/`summary`/`start`/`end` 等），需要详情请走 `+get`。
+
+```bash
+# query 按关键词 可选
+# start/end 按时间范围（ISO 8601 或 YYYY-MM-DD）可选
+# attendee-ids 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀）可选
+# page-token 分页游标，用于继续翻页 可选
+# page-size 每页数量，默认 30 可选
+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
+```
+
+### `+agenda` — 查看近期日程安排
+
+默认查询当天。结果应整理为按日期分组、按开始时间升序的易读时间线。
+
+```bash
+# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
+# calendar-id 日历 ID（默认primary）可选
+lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17 --calendar-id <calendar_id>
+```
+
+注意：
+- 已取消的日程自动过滤；无日程时直接告知"日程清空"。
+- 时间范围超过 40 天会自动拆分查询并合并结果。
+
+### `+freebusy` — 查询主日历忙闲时段和 RSVP 状态
+
+仅返回忙碌时段起止时间，不含日程标题等隐私信息；其他订阅日历不在范围内。
+
+```bash
+# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
+# user-id 目标用户 open_id（ou_ 前缀）可选；默认当前登录用户
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
+```
+
+用法提示：
+- **仅判断是否有空** → `+freebusy`；**需要日程详情** → `+agenda`。
+- 检查多人可用性：分别调用并对比，找共同空闲。
+
+## 核心概念
+
+- **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
+- **重复性日程例外（Exception）**：对重复性日程某次实例做过「仅此次」编辑后产生的独立日程（拥有独立 `event_id`）。删除/更新「全部」时必须同时处理例外，否则例外会残留。
+- **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
+- **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
+- **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
+- **日程会议 ID（Meeting ID）**：日程的历史视频会议 ID，在日程上开过视频会议才会有。
+
+## 术语映射
+
+用户日常说的"帮我约个日历""查一下今天的日历"，实际意图是针对**日程（Event）**的创建或查询，而非操作日历（Calendar）容器本身。自动将口语化的"日历"意图映射为"日程"操作。
+
+## 意图路由
+
+| 用户意图 | 路由到 |
+|----------|--------|
+| 查询日历/日程或未来时间的会议 | 本 skill |
+| 按关键词搜索日程 | 本 skill（`+search-event`） |
+| 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
+| 查询可用时段 / 查找可用会议室 | 本 skill（无明确时间先用 `+suggestion` 出候选时间块，再用 `+room-find` 查会议室） |
+
+## 时间推断规范
+
+- **星期的定义**：周一是一周的第一天，周日是最后一天。计算"下周一"等相对日期时，基于当前真实日期推算。
+- **一天的范围**：用户提到"明天""今天"等泛指某天时，时间范围应覆盖整天，不要自行缩减。
+
+## 会议室规则
+
+- 查询/搜索可用会议室必须基于确定的时间块，参数规范详见 [+room-find](references/lark-calendar-room-find.md)。
+- `+room-find` 的时间输入必须是确定时间块，不能是时间区间搜索。
+- 用户仅要求"查会议室"但未提供明确时间时，必须先调用 `+suggestion` 获取可用时间块，再将时间块交给 `+room-find`。严禁猜测时间盲目调用。
+
+## API Resources
+
+除上述快捷命令外，本域在沙箱内**仅**以下只读原生 API 命令可用（通用格式 `lark-cli calendar <resource> <method> [flags]`）：
+
+### calendars
+
+- `get` — 获取单个日历信息
+- `list` — 列出日历
+- `primary` — 查询用户主日历
+- `search` — 搜索日历
+
+### events
+
+- `get` — 获取单个日程详情
+- `instance_view` — 展开重复性日程的实例视图
+- `search_event` — 按条件搜索日程
+- `share_info` — 获取日程分享信息
+
+### freebusys
+
+- `list` — 查询忙闲
+
+示例：
+
+```bash
+# 查询用户主日历
+lark-cli calendar calendars primary
+
+# 获取日程分享链接
+lark-cli calendar events share_info --calendar-id <calendar_id> --event-id <event_id>
+```
+
+> `calendar_id` 可以直接传 `primary`，代表当前调用身份的主日历 ID。
+
+### 查询方法的使用方式
+
+- 查看方法的 cli flag：`lark-cli calendar <resource> <method> -h`
+- 查看方法 API 参数：`lark-cli schema calendar.<resource>.<method>`（例：`lark-cli schema calendar.events.get`）
+
+沙箱内仅上述 API 命令可用，不要尝试其它 `service`/`api` 组合或写操作方法。
+
+## 常用其他域命令
+
+```bash
+# 搜索用户，更多参数详见 lark-contact
+lark-cli contact +search-user --query <query> --as user
+
+# 搜索群聊，更多参数详见 lark-im
+lark-cli im +chat-search --query <query> --as user
+```
+
+> 搜到的 `ou_` open_id（用户）/ `oc_` chat_id（群聊）用于 `--attendee-ids` 这类参会人参数。**解析不到，或参会人类型不明确时，向用户澄清该参会人是用户还是群聊，不要靠名字形态硬猜类型**——猜错会把日程查询/推荐建立在错误的实体上。
+
+## 强制性规则
+
+- 涉及日期（时间）字符串与时间戳的相互转换时，务必调用系统命令或脚本代码等外部工具进行处理，以确保转换的绝对准确。违者将导致严重的逻辑错误！
+- **换算禁止依赖容器默认时区。** 沙箱容器默认时区是 UTC，直接用 `date`、`new Date()` 之类不带时区的换算会产生 8 小时偏移，把「下午 3 点的会」算成「晚上 11 点」。所有换算必须显式指定目标时区（如 `TZ=Asia/Shanghai date -d ...`），并在传 `--start-time` / `--end-time` 等参数时优先用带偏移的 ISO 8601（`2026-03-19T15:00:00+08:00`）而非裸时间串。
+- 接受 `--timezone` 的命令（`+room-find` / `+suggestion`）**不要依赖它的默认值**：沙箱里没有"用户设备时区"，默认会落到容器时区。用户提到时区就显式传，没提就按其日程/公司主时区显式传。
+- 会议室**物理设施**管理（设备、容量等）不由 CLI 提供，走管理员后台。

package/shared/lark-cli/lark-calendar/references/lark-calendar-meeting.md

@@ -0,0 +1,30 @@
+
+# calendar +meeting
+
+通过日程 ID（`event_id`） 获取关联的视频会议信息（`meeting_id`、`meeting_note`）。只读。
+
+## 命令
+
+```bash
+# 单个 / 批量（逗号分隔，最多 50 个）
+lark-cli calendar +meeting --event-ids <event_id1>,<event_id2>
+
+# 默认使用主日历，需要时显式传 --calendar-id
+lark-cli calendar +meeting --event-ids <event_id> --calendar-id <calendar_id>
+```
+
+## 输出字段
+
+| 字段 | 说明 |
+|------|------|
+| `event_id` | 日程 ID |
+| `meeting_id` | 关联的视频会议 ID |
+| `meeting_note` | 用户主动绑定到日程的纪要文档 Token（`MeetingNotes`，由用户在日程页手动添加）。**与会中产生的 AI 智能纪要 `note_doc_token` 是两份不同文档。** |
+
+## 获取绑定的纪要文档
+
+`meeting_note` 是用户在日程页手动绑定的纪要文档 Token，可直接取其正文：
+
+```bash
+lark-cli docs +fetch --api-version v2 --doc <meeting_note> --doc-format markdown
+```

package/shared/lark-cli/lark-calendar/references/lark-calendar-room-find.md

@@ -0,0 +1,108 @@
+# calendar +room-find
+
+
+针对一个或多个时间块查找/搜索可用会议室。会议室是日程的一种资源型参与人，不能脱离日程单独预定。
+
+## 适用场景
+
+- 已知一个或多个待选时间块，需要查找可用会议室
+- 需要在一组连续编号的会议室中批量搜索可用房间（如"帮我约一个 16~20 号之间的会议室"）
+
+## 命令
+
+```bash
+lark-cli calendar +room-find \
+  --slot "2026-03-27T14:00:00+08:00~2026-03-27T15:00:00+08:00" \
+  --slot "2026-03-27T16:00:00+08:00~2026-03-27T17:00:00+08:00" \
+  --attendee-ids "ou_xxx,ou_yyy" \
+  --city "北京" \
+  --building "学清嘉创大厦B座" \
+  --floor "F2" \
+  --event-rrule "FREQ=DAILY;INTERVAL=1"
+```
+
+### 批量会议室名称查询
+
+当用户想在一组编号会议室中挑选可用房间时，可用英文逗号拼接多个会议室名称传入 `--room-name`：
+
+```bash
+# 场景：帮我约一个 16~20 号之间的会议室
+lark-cli calendar +room-find \
+  --slot "2026-03-27T14:00:00+08:00~2026-03-27T15:00:00+08:00" \
+  --room-name "16,17,18,19,20"
+```
+
+```bash
+# 场景：查找 木星 或 火星 会议室
+lark-cli calendar +room-find \
+  --slot "2026-03-27T14:00:00+08:00~2026-03-27T15:00:00+08:00" \
+  --room-name "木星,火星"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--slot <start~end>` | 是 | 期望查询的时间块，格式需遵循 `开始时间~结束时间`。若存在多个候选时间块，可重复传入此参数。 |
+| `--city <text>` | 否 | 会议室所在城市强约束。**仅当**用户明确说出具体城市（如北京、上海）时才提取，**严禁**根据园区或楼宇名称自行联想或补全。 |
+| `--building <text>` | 否 | 会议室所在楼宇强约束，承载城市以下、楼层以上的办公区/园区/楼栋描述。|
+| `--floor <text>` | 否 | 仅用于筛选会议室所在楼层。应先做归一化，再传递规范值；例如 `2楼` / `二楼` / `2F` 统一为 `F2`。注意：此参数只筛选楼层，不可混入区域定位（如“A区”）或具体会议室号。 |
+| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名、会议室号或编号区间时使用。 |
+| `--min-capacity <n>` | 否 | 会议室最小容纳人数。当用户明确参会人数或提出“至少容纳N人”等要求时，提取数字放入此参数，必须为正整数。 |
+| `--max-capacity <n>` | 否 | 会议室最大容纳人数。用于过滤过大空间，必须为正整数。 |
+| `--attendee-ids <id_list>` | 否 | 参会对象 ID 列表。支持用户 ID（`ou_` 前缀）和群组 ID（`oc_` 前缀），多个 ID 以逗号分隔。 |
+| `--event-rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" |
+| `--timezone <tz>` | 否 | 对话中明确提及的预约日程所使用的时区（默认取用户设备时区，例如 `Asia/Shanghai`） |
+
+## 规则
+
+- 多个 `--slot` 会由 CLI 内部并发调用单时间块接口，再聚合成一次输出
+- `+room-find` 的时间输入必须是**确定时间块**，不是时间区间搜索。
+- 如果是重复性日程，必须校验返回中的 `reserve_until_time`（该会议室最晚可预约时间）是否覆盖 `event-rrule` 对应的重复范围。
+- `--city` 仅在用户明确说出城市时才提取；不要仅凭 `望京办公室`、`漕河泾园区`、`南山办公室` 这类位置名自动补城市。
+- 若已经提取了 `--city`，则 `--building` 中不要再重复携带城市前缀。例如用户说 `北京学清嘉创大厦B座` 时，应提取为 `--city "北京"` 与 `--building "学清嘉创大厦B座"`，不要把 `北京学清嘉创大厦B座` 原样整体传入 `--building`。
+- 同一语义槽位只保留一个规范值。例如用户说“2楼”，应转换为 `--floor "F2"`；**禁止**同时传 `2楼 F2` 这类重复楼层信息。
+- 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。若短词更像楼层/区域定位（如 `2L`、`2F`），优先落到 `--floor`，不要默认落到 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
+- 对会议室名要做轻量归一化：`木星会议室` 应提取为 `--room-name "木星"`；`会议室 02` / `02会议室` 应提取为 `--room-name "02"`。
+- 当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如：
+  - "帮我约 16~20 号的会议室" → `--room-name "16,17,18,19,20"`
+  - "查下木星和火星是否有空" → `--room-name "木星,火星"`
+  - "看看 01、02、03 会议室" → `--room-name "01,02,03"`
+- 对复合会议室号要优先拆分结构化信息：`F3-05` / `F5-07` / `3楼-08` 这类表达，若可稳定识别楼层与会议室号，应优先提取为 `--floor "F3"` + `--room-name "05"`、`--floor "F5"` + `--room-name "07"`、`--floor "F3"` + `--room-name "08"`，不要把整段直接作为 `--room-name`。
+- 当提供了会议室搜索筛选条件时，返回结果也**不保证**与搜索词完全字面匹配。底层可能会结合邻近楼层做推荐，例如用户搜索 `2层`，即使 `2层` 没有空闲会议室，也可能返回相近的 `3层` 候选。这不应被误判为接口返回异常。
+
+## 输出格式
+
+**将返回的候选会议室整理为易读的结构化排版向用户展示。严禁将时间和会议室名称放在同一行展示，必须分行并使用编号列表呈现可用会议室，严禁揉成一团纯文本堆叠。**
+
+```text
+## 2026-03-27 周五
+
+[选项 1] 14:00 - 15:00
+  可用会议室：
+  1. 学清嘉创大厦B座-F2-02🎦(7人)
+  2. 学清嘉创大厦B座-F3-05🎦(11人)
+
+💡 请回复您倾向的选项编号以及对应的会议室序号。
+```
+
+> **AI 行为指导：**
+> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示。
+> - **`room_name` 必须逐字透传**：展示给用户的会议室名称，必须直接使用 CLI/API 返回的 `room_name` 原值。禁止提取楼层、会议室号、容量、视频能力后重组成新的名称，禁止意译、缩写、去前缀、去后缀，或仅保留"便于阅读"的摘要名。
+> - **重复日程要明确阻断原因**：若某候选会议室的 `reserve_until_time` 无法覆盖重复性日程，**必须**向用户明确说明该会议室最长可约至何时。
+> - **正确解释推荐结果**：如果返回结果与用户输入条件不完全字面一致，先说明底层可能返回邻近位置或相近条件的推荐候选，不要直接将其判定为异常。
+> - **默认减少用户输入成本**：应主动引导用户不必一开始就提供很详细的会议室搜索条件。只要时间块已明确，用户直接表达“想查会议室”即可，先基于当前信息查询候选；只有在用户对结果不满意时，再引导其补充更具体的楼宇、楼层、会议室名或容量条件。
+
+**字段说明：**
+
+| 字段名 | 说明 |
+| :--- | :--- |
+| `room_id` | 会议室唯一标识。 |
+| `room_name` | 会议室名称，展示给用户时必须使用原值。 |
+| `capacity` | 会议室最大容纳人数。 |
+| `reserve_until_time` | 该会议室当前允许被预约到的最晚时间点，用于校验重复性日程是否超期。 |
+
+## 参考
+
+- [lark-calendar-suggestion](lark-calendar-suggestion.md)
+- [lark-calendar](../README.md) — skill 入口与路由

package/shared/lark-cli/lark-calendar/references/lark-calendar-suggestion.md

@@ -0,0 +1,120 @@
+# calendar +suggestion
+
+
+根据非明确时间或一段时间范围，推荐多个可用时间块方案。帮助用户解决协调时间的难题。
+
+**调用时机 (Agent Guidance):**
+- ✅ **当用户需求涉及寻找时间块，且时间未完全确定**（如`今天`、`近三天`、`本周`、`下午`, `无时间描述`）时，调用此工具来获取推荐时间块给用户选择。
+- ❌ **当用户已经明确了具体的时间点**（如`今天下午3点`），则**不需要**调用此工具
+
+## 命令
+
+```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](../README.md) — skill 入口与路由

package/shared/lark-cli/lark-contact/README.md

@@ -0,0 +1,35 @@
+# contact (v1)
+
+## 选哪个命令
+
+所有命令以当前用户身份运行（`--as user`，默认值，无需显式指定）;能否读到某个人取决于当前用户的可见范围。按意图选命令:
+
+| 想做什么 | 命令 |
+|---|---|
+| 按姓名 / 邮箱搜员工拿 open_id | [`+search-user`](references/lark-contact-search-user.md) |
+| 已知 open_id 取他人资料（姓名 / 部门 / 邮箱 / 是否激活等） | [`+search-user --user-ids <id>`](references/lark-contact-search-user.md) |
+| 查看自己 | [`+get-user`](references/lark-contact-get-user.md) 或 `+search-user --user-ids me` |
+
+已知 open_id 只是想查对方日程 / 忙闲,不必经过 contact —— 直接 [`lark-calendar`](../lark-calendar/README.md)（只读查询）。发消息、新建日程 / 邀请会议在当前沙箱不可用(lark-im 域仅开放群相关的只读查询,lark-calendar 域无写能力),不要用其它域命令替代。
+
+## 典型场景
+
+找张三给他发消息:先搜,确认 open_id:
+
+```bash
+lark-cli contact +search-user --query "张三" --has-chatted --as user
+```
+
+发消息能力在当前沙箱不可用(lark-im 域仅开放群相关的只读查询,不含发消息能力),拿到 open_id 后请告知用户该限制,不要用其它域命令替代。
+
+搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
+
+## 注意事项
+
+- **41050 / Permission denied** 受当前用户可见范围限制(两条命令都可能遇到)。若确需扩大可见范围,让管理员调整。
+- **跨租户用户**(`is_cross_tenant=true`)多数业务字段为空字符串,这是飞书可见性规则,下游做空值兜底。
+- **ID 类型**:默认 `open_id`。`+get-user` 可改 `--user-id-type union_id|user_id`;`+search-user` 只接受 `open_id`。
+
+## 边界
+
+- 部门树 / 按部门列员工 / 组织架构不在 contact 域的白名单命令里，走原生 OpenAPI 查找接口。

package/shared/lark-cli/lark-contact/references/lark-contact-get-user.md

@@ -0,0 +1,13 @@
+# +get-user
+
+按 ID 取用户基本信息(姓名等)。
+
+```bash
+# 取自己
+lark-cli contact +get-user --as user
+```
+
+## 注意事项
+
+- **按 ID 取他人请用 `+search-user --user-ids <id>`**,字段比本命令多(部门 / 邮箱 / 是否激活等)。本命令主要用于取自己,只回很少字段。
+- **ID 类型**:默认 `open_id`,可用 `--user-id-type union_id|user_id` 切换返回 ID 的类型。