@rezti/dsh-rez-suite 0.1.49 → 0.1.51

package/templates/shared/wecomcli-calendar/references/calendar-freebusy.md

@@ -0,0 +1,207 @@
+# calendar schedules free list — 查询参与人共同空闲
+
+查询同企业成员在指定时间窗口内的共同空闲时段。直接返回可推荐的时段列表。
+
+## 输出前必检（CRITICAL）
+
+**任何 free list 触发的回复，最终对外文本都必须满足**：
+- 不出现 `wo` 前缀字符串（userid 仅用于工具调用，对用户只显示姓名 / 别名）
+- 不出现 `mt_` / `td_` / `wo_` / `doc_` / `room_` 等内部 ID 前缀
+
+多人查询时尤其容易在"对齐姓名↔userid"中无意泄露——展示阶段如果你写到 `wo` 字符，
+**立即停下重写**，只保留姓名（来自 `available_users[].name`）。
+
+## 命令示例
+
+```bash
+# 查询 woxxx 和 woyyy 在 2026-04-07 09:00:00 和 2026-04-07 18:00:00 之间的空闲时段，并且必须是60分钟整块的 
+wecom-cli calendar schedules free list --json '{
+  "userids": [{"userid": "woxxx"}, {"userid": "woyyy"}],
+  "begin_time": "2026-04-07 09:00:00",
+  "end_time": "2026-04-07 18:00:00",
+  "min_duration_minutes": 60,
+  "limit": 5
+}'
+```
+
+## 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|:----:|------|------|
+| `userids` | object[] | 是 | — | >=1 个成员，对象数组格式 `[{"userid": "woxxx"}]`（`wo` 前缀）。允许单人调用，等价于"某人什么时候有空"查询 |
+| `begin_time` | string | 是 | — | 查询窗口起，格式 `YYYY-MM-DD HH:mm:ss`。早于服务端当前时刻的部分会被自动截断 |
+| `end_time` | string | 是 | — | 查询窗口止，必须晚于 `begin_time`，且与 `begin_time` 的间隔 ≤ 24 小时 |
+| `min_duration_minutes` | int | 否 | `30` | 过滤掉短于该值的空闲段，避免推荐过碎的时间窗 |
+| `strategy` | string | 否 | `max_attendees` | 推荐策略，详见下表 |
+| `limit` | int | 否 | `10` | 返回时段数量上限 |
+
+### `strategy` 取值
+
+| 值 | 行为 | 状态 |
+|----|------|------|
+| `max_attendees` | 按最多可参与人数筛选，只返回最高一档人数的所有时段，同档内按时间升序。有共同空闲时即全员到场窗口；无共同空闲时自然降级为次大可达人数。 | 当前唯一实现，默认值 |
+
+## 返回结构
+
+```json
+{
+  "total_count": 2,
+  "strategy": "max_attendees",
+  "extra_info": "没有找到所有人都空闲的时段，下面是符合 strategy 规则的时间段",
+  "slots": [
+    {
+      "begin_time": "2026-04-07 13:00:00",
+      "end_time":   "2026-04-07 14:00:00",
+      "available_users": [
+        {"userid": "woxxx", "name": "张三"},
+        {"userid": "woyyy", "name": "李四"}
+      ],
+      "available_count": 2,
+      "busy_users": []
+    }
+  ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total_count` | int | 本次查询的有效人数 |
+| `strategy` | string | 服务端实际采用的策略 |
+| `extra_info` | string | 服务端提示文案。**降级场景**会说明"没有全员都空闲，下面是按 strategy 筛选的最佳时段"等内容，可作为措辞参考 |
+| `slots[]` | array | 推荐的空闲时段，已按策略筛选、已过滤过去时段、已应用 `min_duration_minutes` |
+| `slots[].begin_time` | string | 时段起始时间，格式 `YYYY-MM-DD HH:mm:ss`，与请求参数同格式，可直接展示 |
+| `slots[].end_time` | string | 时段结束时间，格式 `YYYY-MM-DD HH:mm:ss` |
+| `slots[].available_users` | array | 该时段内空闲的人（`userid` + `name`）。**展示时只用 `name`，禁止暴露 userid** |
+| `slots[].available_count` | int | 该时段内空闲人数 |
+| `slots[].busy_users` | array | 该时段内忙碌的人（`userid` + `name`）。`max_attendees` 全员命中时为空，降级时列出冲突人 |
+
+> 展示时段前心算一次 `end_time - begin_time` 的分钟数，确认 ≥ 请求传入的
+> `min_duration_minutes`（默认 30），避免把短时段的时长说宽。
+
+
+### 指定重要优先人物优先的查询
+
+如果用户希望查询一批人的空闲时间，但是优先其中某个子集（重要人物）必须空闲（不重要的人可以不空闲导致缺席），可以先单独查询重要人物的空闲时间，再查询全员的空闲时间。再推荐一个合适的时间。
+
+### 分支判断（一次请求覆盖三种情况）
+
+拿到响应后，比较 `slots[0].available_count` 与 `total_count`：
+
+| 情况 | 含义 | Agent 行为 |
+|------|------|-----------|
+| `slots[0].available_count == total_count` | 存在全员共同空闲 | 展示所有可用时段让用户选择 |
+| `0 < slots[0].available_count < total_count` | 无全员共同空闲，服务端已降级到"最多人能到"的窗口 | **先告知用户哪些人冲突、几人能参加**，再展示时段，让用户决定继续还是换时间 |
+| `slots == []` | 查询窗口内没有任何符合最小粒度的可用时段 | 不要硬推荐，引导用户**扩大时间范围或减少参与人** |
+
+> 一次请求已覆盖正常 / 降级 / 全忙三种语义，**不要发起第二次"降级查询"**。
+
+> **查询"某时段有没有空"时，忙碌也要如实响应**：当用户问的是特定时间段的忙闲（如"张三下午 3 点有空吗""明天上午大家都在吗"），若该时段没有空闲（`slots` 为空）、或被问的人不在该时段的 `available_users` 里，必须明确回复"该时段忙 / 已有安排"，并尽量点明是谁忙（取 `busy_users[].name`）、忙在哪一段；不要只报空闲时段，也不要用"无共同空闲"一笔带过而不点明忙碌状态。
+
+### 切片与展示
+
+- **推荐时段按 1 小时维度切分**：`slots` 返回的可用空闲段，若长度超过 1 小时，须在 Agent 侧按 1 小时粒度切成多个候选时段分别推荐（如空闲段 `15:00-18:00` 切为 `15:00-16:00`、`16:00-17:00`、`17:00-18:00`），每个候选统一按整 1 小时呈现；不足 1 小时的空闲段按其实际长度原样展示。查询时建议传 `min_duration_minutes=60`，避免推荐出不足 1 小时的碎片段。
+- **候选起点不得越界（起点 ≤ 段终点 − 日程时长）[REQUIRED]**：候选切片的长度只是展示粒度，用户选中后实际占用的是「起点 + 完整日程时长」。因此当日程时长 D 超过 1 小时时，必须剔除那些「起点 + D」会超出本空闲段终点的候选起点——即候选起点必须满足 `起点 ≤ 段终点 − D`，否则实际区间会落到未经忙闲验证的时段、可能与他人冲突。例如 **2 小时**会议、空闲段 `15:00-18:00`：合法起点上限为 `18:00 − 2h = 16:00`，故只保留 `15:00`、`16:00` 两个起点（对应实际区间 `15:00-17:00`、`16:00-18:00`），必须剔除 `17:00`（其实际区间 `17:00-19:00` 已越过 18:00）。当空闲段长度本身小于 D 时，该段不产生任何候选。
+- **推荐时段的长度只表示"这段时间可用"，不代表日程/会议时长**：切出的 1 小时候选仅用于给用户挑选开始时段，用户选定后，日程/会议的实际时长仍以用户明确指定的为准；用户未明确时长时一律默认 1 小时（见 [calendar-create](calendar-create.md) 与 wecomcli-meeting 创建文档），禁止把推荐时段的长度直接当作时长。
+
+### 输出格式
+
+**情况 1：全员共同空闲**
+```
+推荐时间：
+  方案 1: 04-07 15:00-16:00 — 张三、李四都有空
+  方案 2: 04-07 16:00-17:00 — 张三、李四都有空
+  方案 3: 04-07 13:00-14:00 — 张三、李四都有空
+
+选哪个方案？或者说"换一批"看其他时间。
+```
+
+**情况 2：降级（部分人能参加）**
+```
+当前时间范围内没有所有人都空闲的时段，最多 2 人能到。
+
+方案 1: 04-07 15:00-16:00 — 张三、李四能参加（王五此时有日程）
+方案 2: 04-07 17:00-18:00 — 张三、李四能参加（王五此时有日程）
+
+要按这些时段安排吗？或者换个时间窗口让王五也能参加？
+```
+
+**情况 3：全员无空**
+```
+04-07 13:00-18:00 内，张三、李四、王五 没有任何能凑齐的空闲时段（最小粒度 30 分钟）。
+
+建议：
+1. 扩大时间窗口（如延长到傍晚或换一天）
+2. 减少参与人
+```
+
+> 展示参与人时只用姓名。`available_users[].userid` 仅用于回传到 `schedules create` 的 `attendees`，禁止出现在面向用户的文案里。
+
+## 典型场景
+
+### 1. 有共同空闲时段
+
+```
+用户：帮我约张三和李四明天下午聊一下
+→ 通过 wecomcli-contact 技能批量搜索「张三」「李四」，解析为 userid
+→ 调用 free list（明天 13:00-18:00；`userids` = 自己 + 张三 + 李四——新建日程的共同空闲须把自己也纳入，避免排到自己已占用的时段）
+→ slots[0].available_count == total_count == 3，存在全员共同空闲
+→ 展示前 3 个时段让用户选择
+→ 用户选择 → 调用 create
+```
+
+### 2. 部分降级 / 全员无空
+
+```
+用户：帮我约王五和赵六、孙七明天上午碰一下
+→ 通过 wecomcli-contact 技能批量搜索，解析为 userid
+→ 调用 free list（明天 09:00-12:00）
+→ 情况 A: slots 为空 → 引导扩大窗口或减少参与人
+→ 情况 B: slots[0].available_count = 2 < 3 → 告知冲突的人和"最多 2 人能参加"的时段
+  → 用户选"换个时间" → 重新追问范围 → 再次调用
+  → 用户选"按 2 人安排" → 调用 create（只把 available_users 中的人作为参与人）
+```
+
+### 3. 单人空闲查询
+
+```
+用户：李四明天什么时候有空
+→ 通过 wecomcli-contact 技能搜索「李四」，解析为 userid
+→ 调用 free list（userids 单元素，begin_time/end_time 覆盖明天工作时段）
+→ slots 即李四的空闲段
+→ 用人话展示时段起止时间
+```
+
+### 加人 / 改时间到已有日程时的查询对象（避免自冲突误报）[CRITICAL]
+
+为"已存在的日程"加人或改时间而做忙闲检查时，查询对象**必须排除正被该日程占用、因而必然显示忙碌的人和时间段**，否则会误报冲突。
+
+**核心原则**：对【已在本日程中的人】（日程创建者 / 自己 + 已有参与人）只查"与本日程**当前时段不重叠**"的时间——本日程已占着原时段，对这些人在原时段查到的"忙"是它自己造成的自冲突误报；【新增参与人】才查完整目标时段。据此分三种情况：
+
+- **① 只加人、不改时间** → `userids` 只放**新增参与人**，针对**日程原时段**查询。**不要**把当前用户（创建者 / 自己）和已有参与人放进 `userids`——他们正因这条日程而"忙"，纳入后会误判为冲突，而用户本意恰恰是让别人加入自己这个已定时间的日程。
+- **② 改时间，且新时段与原时段【不重叠】**（平移 / 改期，如 15:00 改到 17:00）→ `userids` 放"改后仍需参加的人 + 新增参与人"，针对**新时段**查询。新旧时段无交集，现有参与人查新时段不会撞上本日程，可正常纳入。
+- **③ 改时间，且新时段与原时段【有重叠】**（延长 / 提前等，新时段含部分原时段）→ 不能整段查现有参与人，否则重叠部分会被本日程自己误报为忙：
+  - **新增参与人**：查**完整新时段**。
+  - **现有参与人及自己**：只查**新时段去掉与原时段重叠后剩下的增量段**（如 15:00-16:00 延到 15:00-17:00，只查 16:00-17:00；如 15:00-16:00 提前到 14:00-16:00，只查 14:00-15:00）。增量段为空（如仅缩短时间）则现有参与人无需查。
+
+> 该约束同样适用于 [calendar-update](calendar-update.md) 的"参与人变更工作流"：先按上述规则圈定查询对象和查询时段，再调用 `free list`。
+
+## 查询范围约束
+
+- **必须传未来时间**：`begin_time` 早于服务端当前时刻的部分会被自动截断；传纯历史窗口会得到空 `slots`。
+  **调用前先检查**：若用户问"昨天 / 上周 / 上个月某人什么时候有空"等纯过去时间，直接告知用户"过去时段无法查询忙闲"并引导改成未来时间，不要先调 `free list` 拿到空结果再解释。
+- **单次窗口 ≤ 24 小时**：`end_time` 必须晚于 `begin_time` 且间隔不超过 24h。跨天 / 多天需求必须拆成多段分别调用，再在 Agent 侧按顺序拼接 slots。
+- **未给时间窗口的默认值**：用户只问"X 什么时候有空"没给日期范围时，默认只查当天剩余工作时段 + 明天工作时段（共两个 24h 窗口），不要主动展开 3 天以上——若不够再询问用户。
+- **周期日程限制**：仅覆盖最近两个月有修改的周期日程，更早的可能不在结果中。
+- **隐私保留**：返回中不包含日程主题、描述、其他参与人；只暴露忙 / 闲的归属人。
+
+## 异常处理
+
+| 异常场景 | 处理方式 |
+|---------|---------|
+| 接口调用失败 | 告知"忙闲查询暂时不可用"，建议用户直接确认时间后创建日程 |
+| `slots == []` 且窗口合理 | 引导用户扩大时间窗口或减少参与人，不要重复传同一窗口试错 |
+
+## 参考
+
+- [wecomcli-calendar](../SKILL.md) — 日程技能主文档
+- [calendar-create](calendar-create.md) — 创建日程

package/templates/shared/wecomcli-calendar/references/calendar-meeting-room.md

@@ -0,0 +1,170 @@
+# calendar 会议室查询 — buildings list / rooms search
+
+查询办公楼清单（`buildings list`）和会议室可订性（`rooms search`），用于日程/会议创建或更新时选会议室。两者均为**只读查询**，真正的占用在 [calendar-create](calendar-create.md) 创建时传 `meeting_room_id`、或在 update（[日程](calendar-update.md) / [会议](../../wecomcli-meeting/references/meeting-update.md)）改订时传 `meeting_room_id` 完成。
+
+> 本文档是会议室查询的唯一信息源，[wecomcli-meeting 技能](../../wecomcli-meeting/SKILL.md) 创建会议时也引用此处。
+
+## 命令
+
+```bash
+# 列出我可访问的办公楼
+wecom-cli meeting rooms buildings list --json '{}'
+
+# 查会议室可订性（单时段）
+wecom-cli meeting rooms search --json '{
+  "begin_time": "<日期> 14:00:00",
+  "end_time": "<日期> 15:00:00",
+  "room_keyword": "1605",
+  "floor_name": "16",
+  "min_capacity": 4
+}'
+```
+
+---
+
+## buildings list — 办公楼清单
+
+返回用户可访问的办公楼全量列表，无入参（传 `{}`）。
+
+### 返回结构
+
+```json
+{
+  "total_count": 3,
+  "buildings": [
+    { "name": "创新大厦A座", "city": "北京", "is_current": true },
+    { "name": "创新大厦B座", "city": "北京", "is_current": false },
+    { "name": "滨海科技园",  "city": "上海", "is_current": false }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `total_count` | `buildings` 数组长度 |
+| `buildings[].name` | 建筑本名，不含城市前缀 |
+| `buildings[].city` | 城市，展示时拼 `${city} ${name}` |
+| `buildings[].is_current` | 当前所在楼标记；无法判断时全为 `false` |
+
+> 无内部 building_id；下游 `rooms search` 引用某栋楼时传 `building_city` + `building_name`。
+
+### 用法
+
+- **仅当用户提到楼名时调用**；没提楼则不调用，让 `rooms search` 用当前所在楼兜底。
+- 把用户口语楼名（如"北京创新A"）匹配到列表条目，得到 `city` + `name`。
+- 多候选 → 用文字让用户选（展示用 `${city} ${name}`）；无匹配 → 告知不在可访问列表并列出可选项。
+- `buildings: []` → 提示"暂无可预订办公地点"。
+
+> **楼栋识别靠模糊匹配 + 确认，不要苛求字面一致，也不要罗列充数：**
+> - 用户说的楼名往往与 `buildings list` 的标准名**写法不同**（使用简称、漏字、少写 A/B 座、带或不带城市前缀等）。应把用户表述与返回列表做**模糊匹配**，而不是要求逐字相同。
+> - 命中**唯一最接近**的条目 → 用文字确认一句"你是指【${city} ${name}】吗？"，确认后用该条目的 `city`+`name` 调 `rooms search`。
+> - 命中**多个相近**条目 → 用文字只列这几个（展示用 `${city} ${name}`）让用户选。
+> - **确实匹配不到**（用户没给楼线索，或列表里没有相近项）→ 才让用户补充 / 自由输入楼名；**禁止从全量列表里随机挑几个充数，也禁止凭记忆编造列表里没有的楼名**。
+> - 展示给用户的楼名、以及最终喂给 `rooms search` 的 `building_name` / `building_city`，都必须**逐字取自 `buildings list` 的返回条目**。
+
+---
+
+## rooms search — 会议室可订性查询
+
+给定单时段 + 可选会议室提示 + 容量需求，返回目标会议室能否预订及同楼候选。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|:----:|------|------|
+| `begin_time` | string | 是 | — | `YYYY-MM-DD HH:mm:ss`，必须晚于当前时刻 |
+| `end_time` | string | 是 | — | 晚于 `begin_time`，间隔 ≤ 24h |
+| `building_city` | string | 否 | 当前所在楼城市 | 与 `building_name` 同传或同省略 |
+| `building_name` | string | 否 | 当前所在楼楼名 | 同上 |
+| `room_keyword` | string | 否 | — | 会议室名/号关键词（如 `"1605"`、`"创新室"`） |
+| `floor_name` | string | 否 | — | 楼层过滤，按楼层名匹配（如 `"16"`、`"3 楼"`），仅返回该楼层的会议室；用户明确指定楼层时传入，**直接使用用户的原始表述传入，不做归一化/转换**（用户说"16 楼"就传 `"16 楼"`，说"16F"就传 `"16F"`） |
+| `min_capacity` | int | 否 | `2` | 容量下限，传 `len(attendees) + 1`（含组织者） |
+| `expand_to_other_buildings` | bool | 否 | `false` | `true` 时同城跨楼推荐，仅用户明确要求才传 |
+| `limit` | int | 否 | `20` | `recommendations` 上限（最大 100） |
+
+> `building_city/name` 均不传时用当前所在楼兜底；兜底失败返回 `current_building_unknown`。
+
+### 返回结构
+
+传了 `room_keyword` 时 `target` 为命中的目标会议室列表（数组，每项含 `status`：`bookable` / `unavailable` / `not_found`；同一关键词或叠加 `floor_name` 楼层过滤可能命中多间），未传 `room_keyword` 时 `target` 为空数组 `[]`。`recommendations` 为同楼候选。
+
+```json
+{
+  "inferred_building": { "name": "创新大厦A座", "city": "北京", "source": "user_current" },
+  "target": [
+    {
+      "status": "unavailable",
+      "room": { "meeting_room_id": "mrmaaa", "name": "1605", "capacity": 6, "floor": "16F" }
+    }
+  ],
+  "recommendations": [
+    { "meeting_room_id": "mrmbbb", "name": "1607", "capacity": 6, "floor": "16F" },
+    { "meeting_room_id": "mrmccc", "name": "1608", "capacity": 8, "floor": "16F" }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `inferred_building.name/city` | 实际查询的办公楼，可展示给用户确认 |
+| `inferred_building.source` | `user_current`（兜底）或 `from_input`（来自入参） |
+| `target` | 目标会议室列表（数组）；传 `room_keyword` 时为命中项（可能多间），未传为空数组 `[]` |
+| `target[].status` | `bookable` / `unavailable` / `not_found` |
+| `target[].room` | `not_found` 时为 `null`，否则为房间元数据 |
+| `recommendations[]` | 同楼候选，已按"同楼层优先 → 容量恰好够用"排序 |
+| `recommendations[].meeting_room_id` | 会议室 ID，仅工具链使用，禁止出现在用户回复正文 |
+
+### 边界
+
+- `target[].status = unavailable` 时不返回占用方信息。
+- 同楼无可用时 `recommendations: []`，由 Agent 决定是否开 `expand_to_other_buildings`。
+- `meeting_room_id` 仅在工具调用间流转，对用户只展示会议室 name。
+
+### 错误码
+
+| code | 触发场景 | 处理 |
+|------|---------|------|
+| `current_building_unknown` | 未传楼且无法兜底 | 调 `buildings list` 让用户选楼后重试 |
+| `building_not_found` | 入参楼名查无匹配 | 提示该楼无权限，列出可选项 |
+| `time_in_past` | `begin_time` ≤ 当前时刻 | 提示用户改未来时间 |
+
+---
+
+## Agent 侧编排
+
+```
+├─ 用户提了楼名 → buildings list → 匹配 → building_city + building_name
+│  用户没提楼   → 跳过（rooms search 用当前所在楼兜底）
+│
+└─ rooms search（begin/end + 可选楼 + 可选 room_keyword + min_capacity = len(attendees)+1）
+    ├─ 用户指定了具体会议室（传了 room_keyword）→ target 为命中列表：
+    │    ├─ target 中存在 status = bookable 的会议室：
+    │    │     ├─ 仅 1 个 → 唯一确定，拿其 target[].room.meeting_room_id 进 create
+    │    │     └─ 多个     → 用文字让用户选（禁止自动取第一个）
+    │    ├─ target = []（查无此名 / 无命中）→ 先告知"未查到你指定的『xxx』会议室"，禁止静默替换；
+    │    │     再用文字让用户决定改订其他会议室或换时间（候选仅 1 个也须用户确认）；recommendations 为空则告知后问换时间/跨楼
+    │    └─ target 中无 bookable、命中项均为 unavailable（被占）→ 先告知"『xxx』该时段已被占用"，
+    │          再用文字让用户选替代会议室或换时间（同样禁止静默替换）
+    ├─ 用户未指定具体会议室（target = []）：
+    │    ├─ recommendations 多个候选 → 必须用文字让用户选（禁止自动取第一个）
+    │    └─ recommendations 仅 1 个    → 可直接使用该候选 meeting_room_id
+    └─ recommendations = []        → 问是否跨楼（expand_to_other_buildings=true 重试）或换时间
+```
+
+> [!CAUTION]
+> **五条硬性规则（下游 create 必须遵守）：**
+> 1. **先查询、后推荐、后创建**：`meeting_room_id` 必须来自 `rooms search` 的真实返回值，禁止跳过查询直接创建，禁止凭记忆 / 猜测编造。任何向用户展示的候选 / 推荐会议室（含用文字给出的候选、回复正文里提到的会议室名 / 房间号 / 楼层 / 容量）也必须来自本次 `rooms search` 返回的 `target` / `recommendations`——在成功调用 `rooms search` 拿到真实结果之前，禁止凭记忆、上下文、历史会话或想象罗列、推荐、列举任何具体会议室让用户选择。需要让用户选会议室时，先调 `rooms search`，再用其返回的候选组装文字询问。
+> 2. **存在多个会议室必须让用户选**：`recommendations` 命中多个候选时，必须用文字让用户选择或指定具体会议室，禁止自动替用户挑选。
+> 3. **会议室禁止只写进 `location`**：只要用户提到会议室，就必须经 `rooms search` 查到真实会议室并以 `meeting_room_id` 传入创建。严禁把会议室名 / 房间号仅写进 `location` 字段——那样不会真正占用（预订）会议室。
+> 4. **优先先订房、后建程/建会**：用户在创建时就提到会议室的，应先敲定 `meeting_room_id`（含用户确认）再调用 create，会议室查询/选择是 create 的前置阻塞项，避免创建后会议室被抢占。若创建时漏订或事后要换会议室，可通过 `update` 传入新 `meeting_room_id` 改订（须先经 `rooms search` 确认新会议室 `status=bookable`，详见各自的 update 参考），不必取消重建。
+> 5. **指定会议室查无/不可用时必须先告知、禁止静默替换**：用户指定的会议室在 `target` 中找不到可订项（`target = []` 查无此名，或命中项均为 `unavailable` 被占）时，必须先告知用户"未查到 / 无法预订你指定的『xxx』会议室"，再用文字让用户决定改订其他会议室或换时间。严禁静默用其他名称的会议室替代——即使 `recommendations` 仅 1 个候选也须经用户确认。"`recommendations` 仅 1 个可直接使用"只适用于用户未指定具体会议室（`target = []`）的情形。
+
+- `rooms search` 需要**确定的起止时间**。用户只给了时间范围（如"明天下午"）时，先用 [calendar-freebusy](calendar-freebusy.md) 查共同空闲、让用户选定一个具体时段，再拿该时段调 `rooms search`；用户已给精确时间（如"明天 3 点"）则直接查。
+- 用文字给出的候选必须 2~4 个，展示会议室 `name` + 楼层 + 容量；`meeting_room_id` 仅工具链使用，禁止出现在用户回复正文。
+- `meeting_room_taken`（抢订竞态）发生在 create 阶段，处理见 [calendar-create](calendar-create.md)。
+
+## 参考
+
+- [calendar-create](calendar-create.md) — 日程创建（传 `meeting_room_id` 占用会议室）
+- [calendar-freebusy](calendar-freebusy.md) — 共同空闲查询
+- [wecomcli-calendar.md](../SKILL.md) — 日程技能主文档

package/templates/shared/wecomcli-calendar/references/calendar-search.md

@@ -0,0 +1,206 @@
+# calendar schedules search — 搜索日程
+
+按关键词、组织人或参与人搜索用户发起和参与的日程。
+
+> [!CAUTION]
+> **`schedules search` 必须翻页到底**：返回中只要 `has_more == true`，就必须携带 `next_cursor` 再次调用 search，循环直到 `has_more == false`，否则会漏数据；禁止只取第一页就提前终止。
+
+> **模糊搜索同时搜会议 [REQUIRED]**：若用户搜的是"会 / xx会 / xx会议"等模糊目标（非明确日程，见 [SKILL.md 查询消歧](../SKILL.md)），除按关键词搜日程外，必须同时 `读取 wecomcli-meeting 技能` 用同样关键词搜会议，把两边结果合并、分「（会议）」「（日程）」汇总展示——不论日程是否搜到都要搜会议。明确是日程 / 安排时只搜日程。
+
+## 命令
+
+```bash
+# 按关键词搜索
+wecom-cli calendar schedules search --json '{"keywords": ["项目评审"]}'
+
+# 按关键词搜索（用户明确指定时间范围）
+wecom-cli calendar schedules search --json '{"keywords": ["周会"], "begin_time": "2026-04-07 00:00:00", "end_time": "2026-04-07 23:59:59"}'
+
+# 按组织人搜索
+wecom-cli calendar schedules search --json '{"organizer": "woxxx"}'
+
+# 按参与人搜索
+wecom-cli calendar schedules search --json '{"has_attendees": [{"userid": "woxxx"}, {"userid": "woyyy"}]}'
+
+# 分页搜索
+wecom-cli calendar schedules search --json '{"keywords": ["周会"], "cursor": "CURSOR_TOKEN", "limit": 50}'
+```
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `keywords` | string[] | 三选一 | 搜索关键词数组，可匹配日程主题、会议室名称等信息（关键词、组织人、参与人至少传入其一） |
+| `organizer` | string | 三选一 | 组织人 userid（关键词、组织人、参与人至少传入其一） |
+| `has_attendees` | object[] | 三选一 | 参与人列表，对象数组格式 `[{"userid": "woxxx"}]`（关键词、组织人、参与人至少传入其一）。需传入查询涉及的**所有参与人，包括当前用户自己**，不要只传别人而漏掉自己 |
+| `begin_time` | string | 否 | 搜索区间起始时间（格式 YYYY-MM-DD HH:mm:ss） |
+| `end_time` | string | 否 | 搜索区间结束时间（格式 YYYY-MM-DD HH:mm:ss） |
+| `cursor` | string | 否 | 分页游标，首次请求不传，翻页时传上次返回的 `next_cursor` |
+| `limit` | number | 否 | 单页返回数量，最大 50 |
+
+> **必填约束**：`keywords`、`organizer`、`has_attendees` 三者至少传入一个，否则接口报错。
+
+## 返回
+
+```json
+{
+  "schedules": [
+    {
+      "schedule_id": "SCHEDULE_ID",
+      "subject": "SUBJECT",
+      "begin_time": "YYYY-MM-DD HH:mm:ss",
+      "end_time": "YYYY-MM-DD HH:mm:ss",
+      "attendees": [
+        {
+          "userid": "USERID1",
+          "name": "englishname(name)"
+        }
+      ],
+      "meeting_room": {
+        "meeting_room_id": "MEETING_ROOM_ID",
+        "meeting_room_name": "MEETING_ROOM_NAME"
+      },
+      "meeting": {
+        "meeting_id": "MEETING_ID",
+        "meeting_code": "MEETING_CODE",
+        "meeting_link": "MEETING_LINK"
+      },
+      "location": "LOCATION",
+      "description": "CONTENT",
+      "creator_name": "NAME",
+      "cal_id": "CAL_ID",
+      "calendar_name": "CALENDAR_NAME",
+      "is_share_cal": false,
+      "allow_self_join": false,
+      "is_all_day": false,
+      "repeat_rule": { "is_repeat": false },
+      "reminders": { "is_remind": false, "reminder_time": [-900] },
+      "timezone": { "timezone_id": "Asia/Shanghai", "timezone_offset": 28800 }
+    }
+  ],
+  "schedules_count": 1,
+  "next_cursor": "xxx",
+  "has_more": false
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `schedules[].schedule_id` | 日程 ID |
+| `schedules[].subject` | 日程主题 |
+| `schedules[].begin_time` | 开始时间 |
+| `schedules[].end_time` | 结束时间 |
+| `schedules[].attendees[].userid` | 参与人 userid |
+| `schedules[].attendees[].name` | 参与人姓名（格式：`englishname(中文名)`） |
+| `schedules[].meeting_room.meeting_room_id` | 会议室 ID |
+| `schedules[].meeting_room.meeting_room_name` | 会议室名称 |
+| `schedules[].meeting` | 在线会议信息（关联了会议时才有），含 `meeting_id`/`meeting_code`/`meeting_link`；`meeting_code` 非空即「含在线会议链接的会议形态日程」 |
+| `schedules[].location` | 日程地点 |
+| `schedules[].description` | 日程描述 |
+| `schedules[].creator_name` | 日程创建者名字 |
+| `schedules[].cal_id` | 所属日历本 ID |
+| `schedules[].calendar_name` | 日历本名称 |
+| `schedules[].is_share_cal` | 所属日历是否为共享日历（日历创建者非当前用户） |
+| `schedules[].allow_self_join` | 是否允许非参与人主动加入日程 |
+| `schedules[].is_all_day` | 是否全天事件 |
+| `schedules[].repeat_rule` | 周期规则，子字段（含 `is_repeat`/`repeat_type`/`repeat_until`/`exception[]` 等）与 [calendar-agenda](calendar-agenda.md) 的 `repeat_rule` 完全一致；`is_repeat=true` 即周期日程，可直接判定无需补 `get` |
+| `schedules[].reminders` | 提醒设置，含 `is_remind`（bool）和 `reminder_time`（int[]，与开始时间的差值秒数，负数为提前提醒） |
+| `schedules[].timezone` | 时区信息，含 `timezone_id`（IANA 标识，如 `Asia/Shanghai`，优先使用）和 `timezone_offset`（UTC 偏移量秒数，`timezone_id` 为空时使用） |
+| `schedules_count` | `schedules` 数组元素数量 |
+| `next_cursor` | 下一页游标，翻页时作为 `cursor` 传入 |
+| `has_more` | 是否还有更多数据 |
+
+> **参与人姓名**：接口已在 `attendees[].name` 中直接返回姓名，**无需额外调用 wecomcli-contact 技能反查**。展示时直接使用 `name` 字段，禁止展示 `userid`。
+
+> **判定会议形态 / 周期性无需补 `get` [REQUIRED]**：`search` 出参与 `list`/`get` 对齐，已含 `meeting`、`repeat_rule`、`reminders`、`timezone` 等字段——可直接用 `meeting.meeting_code` 非空判定「会议 / 纯日程」（用于分组展示、改约路由）、直接取 `meeting.meeting_id` 传给 `wecomcli-meeting`、直接用 `repeat_rule.is_repeat` 判定周期日程，**不必再补一次 `get`**。
+
+## 搜索策略
+
+**搜索条件策略**：
+- 有日程名称/关键词 → 传 `keywords` 数组
+- 用户提到"某人组织的日程" → 上下文中已有该人合法 userid 则直接使用，否则通过 `读取 wecomcli-contact 技能` 按姓名获取 userid，传 `organizer`
+- 用户提到"某人参与的日程" → 上下文中已有该人合法 userid 则直接使用，否则通过 `读取 wecomcli-contact 技能` 按姓名获取 userid，传 `has_attendees`
+
+**时间范围策略**：`begin_time` / `end_time` 均为选填。用户未明确指定时间时，不传时间参数；仅当用户明确说明时间范围时才传入。
+
+**分页策略**：首次搜索不传 `cursor`；**只要返回 `has_more=true`，就必须携带 `next_cursor` 继续翻页，循环直到 `has_more=false` 把结果取全，禁止只取第一页就提前终止**（否则会漏数据、统计不准）。取全后再展示：超过 10 条时只展示和用户问题最相关的 10 条，并告知"还有 N 条，需要查看更多吗？"。
+
+**接口选择规则**：
+1. **有日程主题关键词 → `search`**：用户提到日程主题/关键词时，不追问时间，直接搜索。
+2. **无日程主题关键词 → `list`**：用户泛泛说"看看日程"，或只给了时间/日期时，一律用 `list` 按时间范围拉取；禁止把日期当 `keywords` 走 `search`。
+3. **要详情 → `get`**：`search`/`list` 返回已含 `meeting`、`repeat_rule` 等字段，会议形态与周期性可直接判定，一般无需再调 `get`；仅在只拿到 `schedule_id`（无上下文结果）时用 `get` 补齐。
+4. **与某人相关 → 优先 `search`**：寻找与某人相关的日程时，优先用 `search`（传 `has_attendees`/`organizer`，或把人名作为 `keywords`），而非 `list` 拉全量再过滤。
+
+## 典型场景
+
+### 1. 单个结果
+
+```
+用户：项目评审是什么时候？
+→ 调用 search（keywords=["项目评审"]，不传时间）
+→ 找到 1 条 → 直接读取 attendees[].name 展示参与者姓名
+→ 展示三项：主题、时间、参与人（禁止 markdown 表格）
+```
+
+### 2. 多个结果
+
+```
+用户：最近有没有周会？
+→ 调用 search（keywords=["周会"]，不传时间）
+→ 找到 3 条 → 用文字列出摘要供用户选择：
+    文字提问："找到多个匹配日程，请选择要查看的一个："
+    列出候选（如"周会 - 4月14日 10:00 / 周会 - 4月21日 10:00 / 周会 - 4月28日 10:00"，最多 4 条）
+→ 用户选择后调用 get 获取详情
+```
+
+### 3. 搜索无结果
+
+```
+用户：帮我找一下产品发布会的日程
+→ 调用 search（keywords=["产品发布会"]，不传时间）→ 无结果
+→ 用文字告知用户未找到，提供以下恢复建议：
+  1. 更换关键词重试（日程名称可能不完全匹配）
+  2. 按组织人搜索（提供日程组织人姓名，将通过 wecomcli-contact 技能解析为 userid 后传 organizer）
+  3. 按参与人搜索（提供参与该日程的人员姓名，解析 userid 后传 has_attendees）
+  4. 补充时间范围（日程可能不在接口默认返回范围内）
+→ 根据用户选择执行对应策略
+```
+
+### 4. 用户明确指定时间范围
+
+```
+用户：找一下4月份的周会
+→ 调用 search（keywords=["周会"]，begin_time="2026-04-01 00:00:00"，end_time="2026-04-30 23:59:59"）
+→ 展示结果
+```
+
+### 5. 按组织人搜索
+
+```
+用户：帮我找一下张三组织的日程
+→ 通过 wecomcli-contact 技能搜索"张三"获取 userid（如 woxxx）
+→ 调用 search（organizer="woxxx"）
+→ 展示结果，参与人直接读 attendees[].name，创建者读 creator_name
+```
+
+### 6. 结果超过 10 条（分页）
+
+```
+→ 只要 has_more=true 就先用 next_cursor 翻页到底，取全所有结果（禁止提前终止）
+→ 顺序输出前 10 条日程，每条只含主题/时间/参与人（禁止 markdown 表格）
+→ 末尾告知"还有 N 条，需要查看更多吗？"
+→ 用户确认后展示后续结果（已取回，无需再调接口）
+```
+
+## 注意事项
+
+- **不传默认时间**：用户未明确指定时间时，不传 `begin_time` / `end_time`；仅当用户明确说明时间时才传入。
+- **不追问时间**：用户提供了关键词时，直接搜索，不要追问"你说的是什么时候的"。
+- **参与人展示**：search 返回的 `attendees[].name` 已包含姓名，直接使用，无需调用 wecomcli-contact 技能反查。禁止展示 `userid`。
+- **列表展示规范 [REQUIRED]**：多条结果时按 [SKILL.md 输出格式规范](../SKILL.md) 的「日程列表展示规范」处理——禁止 markdown 表格，每条作为独立条目顺序输出，每个条目只含主题/时间/参与人，超过 10 条只展示前 10 条并告知"还有 N 条，需要查看更多吗？"。
+- **时区标注**：日程 `timezone.timezone_offset != 28800`（非东八区）时，按 [SKILL.md 输出格式规范](../SKILL.md) 的时区标注规则在时间后带上时区，如 `14:00-15:00（纽约时间 UTC-5）`。
+
+## 参考
+
+- [wecomcli-calendar](../SKILL.md) — 日程技能主文档
+- [calendar-agenda](calendar-agenda.md) — 查看日程安排