@amaster.ai/pi-lark 0.1.4 → 0.1.6

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

@@ -0,0 +1,88 @@
+# 模糊时间 / 无时间信息分支：suggestion + 批量查询
+
+> 本文档处理**时间模糊**（如"明天下午""下周找个时间"）或**完全无时间信息**的场景。核心动作是调用 `+suggestion` 产出候选时间块，再根据是否需要会议室决定后续步骤。
+
+## 前置条件
+
+进入此分支前，调度器（[schedule-meeting.md](./lark-calendar-schedule-meeting.md)）已完成：
+- 任务类型判定（新建 / 编辑）
+- 编辑流：目标 event_id 已定位
+- 新建流：默认值已补全
+- 时间已判定为**模糊**或**无时间信息**
+
+## 流程
+
+### 1. 调用 suggestion
+
+详见 [`lark-calendar-suggestion.md`](./lark-calendar-suggestion.md)。
+
+```bash
+lark-cli calendar +suggestion \
+  --start "<range_start>" \
+  --end "<range_end>" \
+  --attendee-ids "<ids>" \
+  --duration-minutes <n> \
+  --event-rrule "<rrule>"
+```
+
+规则：
+- 用户完全没有提供时间信息时，先默认一个合理区间（如"今天剩余时间"或"近两天"）再调用
+- 编辑流中，若用户说"改到明天下午""下周找个时间再约"，基于用户期望的**新时间范围**调用，不要沿用旧时间
+- **不要在用户完全没给时间时反问"你想约什么时候"** — 先补合理区间再进入 suggestion
+
+### 2. 分支处理
+
+#### 不需要会议室
+
+获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入落地操作。
+
+#### 需要会议室
+
+获取候选时间块后，**不要急于让用户只选时间**。先将这些时间块一次性交给 `+room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化展示，让用户一次性完成选择。
+
+> **注意**：即使用户最初只说"查会议室"且未带时间，也必须强制走 suggestion → room-find 路径。
+
+详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。
+
+### 3. 用户确认后
+
+- 用户选中 `+suggestion` 返回的时间块后，**无需再次调用 `+freebusy`**，直接进入落地操作
+- **BLOCKING REQUIREMENT**：必须先向用户展示选项并等待确认，禁止在未获用户确认时直接创建/更新日程
+
+## 模糊语义消解与长期记忆
+
+针对存在歧义的时间场景，严禁主观臆断。典型例子：
+- "上班后" / "下班前"
+- 未明确上下午的 12 小时制时间
+
+处理规则：
+- 主动澄清真实意图，不自行猜测
+- 用户澄清后，将个性化定义沉淀为长期偏好
+
+## 用户展示格式
+
+向用户展示多个时间块及对应会议室时，**必须结构化分行排版**，严禁将时间与会议室放在同一行：
+
+```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人)
+
+💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
+```
+
+## 落地
+
+根据任务类型：
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
+
+落地规则详见 [schedule-meeting.md § 落地日程变更](./lark-calendar-schedule-meeting.md#落地日程变更)。

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

@@ -0,0 +1,122 @@
+# 预约/改约日程或会议、查询/搜索可用会议室的工作流
+
+## 执行摘要
+
+- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。**
+- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。**
+- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。
+- **新建流先补默认值，编辑流先继承已定位日程信息。**
+- **明确时间** → 进入 [明确时间分支](./lark-calendar-schedule-clear-time.md)
+- **模糊时间或无时间信息** → 进入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md)
+- **BLOCKING REQUIREMENT**: 面临时间方案或会议室方案的选择时，必须先向用户展示选项并等待确认，禁止未经确认直接创建/更新日程。
+- **必须按顺序执行。** 不要跳过"任务类型判定""目标日程定位（编辑流）""补默认值/继承基线信息""判断时间明确性"这些前置步骤。
+
+## 严禁行为
+
+- **严禁在未读取对应子命令文档前直接调用命令。**
+- **严禁在尚未判断"新建"还是"编辑"之前，就直接进入创建日程或查会议室动作。**
+- **严禁把带有既有日程锚点 + 修改动词的请求当成新建日程。**
+- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一 `event_id` 前，不得调用 `+update`。
+- **严禁在面临时间/会议室方案选择时，未经用户确认就擅自创建/更新日程。**
+
+## 适用场景
+
+- "帮我约个会" / "下周找时间和 XX 开会"
+- "帮我订/找/搜索一个可用会议室"
+- "明天下午3点约个日程"
+- "把明天上午的日程加上 小明"
+- "给下周一的周会换个会议室"
+- "把这个日程改到明天下午，并加上学清 F201"
+
+## 核心概念
+
+- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。**
+- **预定或查找会议室，均需先确定时间块。**
+- **当用户说"查会议室""找会议室"，默认意图是查会议室可用性，不是检索会议室资源名录。**
+
+## 任务类型判定
+
+| 类型 | 典型语言信号 | 第一动作 |
+|------|--------------|----------|
+| 新建日程 | "约个会""安排会议""新建日程""订个会议室开会" | 补默认值，再进入时间判断 |
+| 编辑已有日程 | "给某日程加人/删人/加会议室""把某日程改到…""换会议室" | 先定位目标 `event_id` |
+
+规则：
+- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`）和**修改动词**（添加、移除、改到、换），默认判定为编辑。
+- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`。
+
+## 编辑流：先定位目标日程
+
+定位规则：
+- 优先利用用户给出的标题、日期、时间范围等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围
+- 命中多个候选日程时，必须向用户展示候选项并要求确认
+- 重复性日程必须继续定位到该次实例的 `event_id`
+
+编辑流分支路由：
+
+| 编辑子场景 | 下一步 |
+|-----------|--------|
+| 仅增删普通参会人/群组，不改时间，不涉及会议室 | 直接 `+update`（详见 [lark-calendar-update.md](./lark-calendar-update.md)） |
+| 新增会议室，不改时间 | 基于已定位日程 start/end → [明确时间分支](./lark-calendar-schedule-clear-time.md) |
+| 只改时间，不涉及会议室 | 判断时间明确性 → 对应分支 |
+| 既改时间，又新增/更换会议室 | 先确定最终时间 → 再查会议室 → 落地 |
+
+## 新建日程：智能推断默认值
+
+- **标题**：根据上下文自动生成；如无法推断，默认"会议"
+- **参会人**：如未指定，默认仅用户自己
+- **时长**：基于上下文推断；默认 30 分钟
+- **无时间信息**：默认推断合理区间（如"今天"或"近两天"），进入时间推荐流程，禁止询问用户
+
+搜索参与人出现多个结果无法唯一确定时，必须询问用户并记录长期记忆。
+
+## 判断时间是否明确
+
+时间基准规则：
+- **新建流**：使用用户给出的时间，或默认补全出的时间范围
+- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是明确时间
+- **编辑流且改时间**：用户想改到的新时间；若表达模糊，进入模糊时间分支
+**注意**: 在执行修改日程/会议时间的任务时，必须先获取原日程的持续时长。如果用户只提供了新的开始时间，你必须根据原时长自动计算出新的结束时间，严格保持原时长不变，禁止擅自改变原日程的时长。
+
+## 分支路由
+
+| 判定结果 | 下一步读取 |
+|----------|-----------|
+| 明确时间 | [schedule-clear-time.md](./lark-calendar-schedule-clear-time.md) |
+| 模糊时间 / 无时间信息 | [schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md) |
+
+## 落地日程变更
+
+用户确认后调用：
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
+
+```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"
+```
+
+落地规则：
+- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新猜测目标日程
+- 编辑流中"新增会议室"默认仅追加 `room_id`，不移除已有会议室
+- 仅当用户明确说"更换会议室"时，才同时 `--remove-attendee-ids` 旧 + `--add-attendee-ids` 新
+- 需要会议室时，将选中的 `room_id` 写入参与人列表
+
+## 参考
+
+- [lark-calendar-schedule-clear-time.md](./lark-calendar-schedule-clear-time.md)
+- [lark-calendar-schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md)
+- [lark-calendar-room-find.md](./lark-calendar-room-find.md)
+- [lark-calendar-suggestion.md](./lark-calendar-suggestion.md)
+- [lark-calendar-create.md](./lark-calendar-create.md)
+- [lark-calendar-update.md](./lark-calendar-update.md)
+- [SKILL.md](../SKILL.md)

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

@@ -0,0 +1,121 @@
+# 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-create](lark-calendar-create.md) — 创建日程
+- [lark-calendar](../SKILL.md) — skill 入口与路由

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

@@ -0,0 +1,100 @@
+# calendar +update
+
+
+更新既有日程字段，或独立增量添加/移除参会人和会议室。
+
+`+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。重复性日程请根据操作范围选择 ID，详见 [重复性日程操作规范](lark-calendar-recurring.md) |
+| `--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 添加到参会人列表，不能脱离日程单独预定。
+- 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。
+- 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
+**⚠️ 高风险操作**: 修改时间时必须先读取原日程时长并计算新 end。如果 end 计算错误，会导致日程时长变化，用户会直接感知，禁止擅自改变原日程的时长。
+
+## 高级用法（完整 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) -- skill 入口与路由
+- [lark-calendar-schedule-meeting](lark-calendar-schedule-meeting.md) -- 预约/改约会议与会议室工作流
+- [lark-calendar-room-find](lark-calendar-room-find.md) -- 查找可用会议室

package/skills/lark-contact/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: lark-contact
+version: 1.0.0
+description: "飞书 / Lark 通讯录:按姓名 / 邮箱解析成 open_id,或按 open_id 反查姓名 / 部门 / 邮箱 / 联系方式 / 个人状态 / 签名。当用户提到某人姓名要下一步发消息 / 排日程,或拿到 open_id 想查具体信息时使用。不负责部门树遍历、按部门列员工、组织架构图,这类需求走原生 OpenAPI。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli contact --help"
+---
+
+## 选哪个命令
+
+**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` | 不支持 |
+| 查同事的个人状态 / 签名 | `user_profiles batch_query` | 不支持 |
+
+已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 [`lark-im`](../lark-im/SKILL.md) / [`lark-calendar`](../lark-calendar/SKILL.md)。
+
+## 典型场景
+
+找张三给他发消息:先搜,确认 open_id,再发:
+
+```bash
+lark-cli contact +search-user --query "张三" --has-chatted --as user
+lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
+```
+
+批量查同事的个人状态 / 个性签名(先用 schema 看参数)。
+
+```bash
+lark-cli schema contact.user_profiles.batch_query
+lark-cli contact user_profiles batch_query \
+  --params '{"user_id_type":"open_id"}' \
+  --data '{"user_ids":["ou_xxx","ou_yyy"],"query_option":{"include_personal_status":true,"include_description":true}}' \
+  --as user
+```
+
+搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
+
+## 注意事项
+
+- **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/skills/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` 取自己)。

package/skills/lark-contact/references/lark-contact-search-user.md

@@ -0,0 +1,123 @@
+# +search-user
+
+仅支持 user 身份。
+
+## 适用范围
+
+- ✅ 已知姓名 / 邮箱 / 「聊过的人」想找出 open_id
+- ✅ 已知一组 open_id 想批量校验或回填字段(`--user-ids`,最多 100,支持 `me`)
+- ✅ 按聊天关系 / 在职状态 / 租户边界 / 企业邮箱等维度筛选员工
+- ❌ 已知 open_id 想发消息 → 直接走 `lark-im`,不经过本命令
+
+## 关键 flag
+
+`--query` / `--queries` / `--user-ids` / bool filter 至少传一个。bool filter 显式传 `=false` 会报错——不传等于不过滤。
+
+| Flag | 作用 |
+|---|---|
+| `--query <text>` | 关键词(姓名 / 邮箱 / 手机号),≤ 50 rune |
+| `--queries <csv>` | 多个关键词并行搜,**最多 20 条**;与 `--query` / `--user-ids` 互斥;输出新 shape(见下) |
+| `--user-ids <csv>` | open_id 列表,≤ 100;支持 `me` 表示自己;与 `--query` 同传时把搜索范围限定在该集合 |
+| `--has-chatted` | 仅搜聊过天的 |
+| `--has-enterprise-email` | 仅搜有企业邮箱的 |
+| `--exclude-external-users` | 仅搜同租户(排除外部联系人) |
+| `--left-organization` | 仅搜已离职的 |
+| `--lang <locale>` | 覆盖 `localized_name` 的语种(如 `zh_cn` / `en_us` / `ja_jp`) |
+| `--page-size <n>` | 单页大小 1-30,默认 20 |
+
+## 常用例子
+
+```bash
+# 按姓名搜,看候选确认是哪个张三
+lark-cli contact +search-user --query "张三" --has-chatted
+
+# 按完整邮箱搜(命中通常唯一,适合作后续命令的输入)
+lark-cli contact +search-user --query "alice@example.com"
+
+# 查看自己
+lark-cli contact +search-user --user-ids me
+
+# 批量回填:已知一组 open_id,取姓名 / 邮箱 / 部门
+lark-cli contact +search-user --user-ids "ou_a,ou_b,ou_c" --format json
+
+# 多 filter 组合:同租户的、有企业邮箱的「王」姓员工
+lark-cli contact +search-user --query "王" --exclude-external-users --has-enterprise-email
+
+# filter-only 枚举:列出所有"聊过天的离职同事"(无关键词)
+lark-cli contact +search-user --has-chatted --left-organization
+```
+
+## 批量并行查询 (fanout)
+
+一次查多个名字:
+
+```bash
+lark-cli contact +search-user --queries "Alice,Bob,张三"
+```
+
+- 每行 user 带 `matched_query`,标识来自哪个 query
+- `queries[]` 每个输入一条 `{query, error?, has_more}`,失败的有 `error`
+- 部分失败不影响其它 query;全部失败才 exit 非 0
+
+```bash
+# bool filter 对每个 query 都生效
+lark-cli contact +search-user --queries "Alice,Bob" --has-chatted
+
+# 与 --query / --user-ids 互斥
+lark-cli contact +search-user --queries "a" --query "b"   # ❌ exit 2
+```
+
+约束:
+- 最多 20 条; 每条 ≤ 50 字符
+- 重复条目静默去重;全空 csv (`,,,`) 报错
+
+## 同名 disambiguation
+
+搜常见姓名常返回多条同名结果。后续操作若有副作用(发消息、邀请会议等),把候选列给用户挑;**不要擅自选**。
+
+筛选信号(可信度从高到低):`chat_recency_hint`(近期联系过) > `enterprise_email` 前缀 > `department` 关键词。`localized_name` 同名时无区分作用。
+
+```bash
+# 用 jq 按部门精筛
+lark-cli contact +search-user --query "张三" \
+  --jq '.data.users[] | select(.department | contains("<部门关键词>"))'
+```
+
+## 注意事项
+
+- **不会自动翻页**。`has_more=true` 表示需要 refine query。
+- **`--lang` 只影响输出展示名**,不影响匹配字段。
+- **`--query` 与 `--user-ids` 同时设**:`--user-ids` 限定搜索范围,`--query` 在该集合内匹配。
+
+## 输出字段 contract
+
+跨租户用户(`is_cross_tenant=true`)的业务字段可能为空字符串,需做空值兜底。
+
+| 字段 | 类型 | 说明 | 跨租户 |
+|---|---|---|---|
+| `open_id` | string | 稳定标识,后续命令的输入 | 始终非空 |
+| `localized_name` | string | 按 `--lang` / brand 选出的展示名 | 始终非空(兜底为 open_id) |
+| `email` | string | 个人邮箱 | 可能为空 |
+| `enterprise_email` | string | 企业邮箱 | 可能为空 |
+| `is_activated` | bool | 是否已激活飞书账号(未激活也可投递消息,但用户可能看不到) | 可能 false |
+| `is_cross_tenant` | bool | 是否跨租户用户(同公司=false,外部联系人=true) | — |
+| `p2p_chat_id` | string | 与当前用户的 P2P 会话 ID(`oc_...`);空表示从未私聊过。可作为接受 `--chat-id` 的 IM 命令的输入 | 可能为空 |
+| `has_chatted` | bool | `p2p_chat_id != ""` 的派生字段 | — |
+| `department` | string | 部门路径,服务端可能用 `-` 拼层级,层级数不固定。**按可子串匹配的字符串处理** | 可能为空 |
+| `signature` | string (optional) | 用户个性签名;空时字段不出现 | 可能不出现 |
+| `chat_recency_hint` | string | 最近联系的提示文案,仅供展示 | 可能为空 |
+| `match_segments` | string[] | 关键词命中的字符串片段,用于高亮展示;无命中则为空数组 | — |
+
+### `--queries` 模式额外字段
+
+`data.users[]` 每条多 `matched_query` (string),指明本行来自哪个 query。
+
+`data.queries[]` 按输入顺序、dedup 后每个 query 一条:
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `query` | string | 该输入 |
+| `error` | string (optional) | 失败原因;成功时不出现 |
+| `has_more` | bool | 该 query 还有更多结果 |
+
+fanout 模式无顶层 `data.has_more`。