@rezti/dsh-rez-suite 0.1.50 → 0.1.52

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

@@ -0,0 +1,108 @@
+# calendar schedules cancel — 取消日程
+
+取消用户发起的日程。**暂不支持取消周期日程**，识别到周期日程时应告知用户并引导其在企业微信客户端操作（见下文工作流与注意事项）。
+
+> [!CAUTION]
+> 这是**写入操作** — 参数就绪后直接执行。
+
+## 命令
+
+```bash
+# 取消普通日程
+wecom-cli calendar schedules cancel --json '{"schedule_id": "<schedule_id>"}'
+```
+
+## 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `schedule_id` | string | 是 | 要取消的日程 ID（由 search/list 返回，格式不固定，直接透传即可） |
+
+**返回**：成功时返回空对象 `{}`，这是正常结果，不代表失败。收到空对象即可告知用户取消成功。
+
+## 定位目标时的跨载体消歧（模糊取消）[REQUIRED]
+
+用户说"取消那个会 / 取消 xx 会 / 把那个会取消掉"等模糊表述、未明确是日程还是在线会议时，**不要只在日程里找**——「会」可能是一条纯日程，也可能是含在线会议链接的会议，只查一边会漏定位：
+
+- **明确是日程 / 安排**（说的是"日程 / 安排 / 我的日历"且不带在线会议特征）→ 只在本技能 `search`/`list` 定位，走 `schedule cancel`。
+- **明确是在线会议**（提到入会链接 / 会议号 / 视频会议 / 腾讯会议 / 远程参会等专属特征）→ 改用 `读取 wecomcli-meeting 技能` 在会议里定位并 `meeting cancel`。
+- **模糊无法判定** → 日程和会议**两边都查**：本技能 `search`/`list` + `读取 wecomcli-meeting 技能` 用同样关键词 / 时间查会议，合并候选、按"主题 + 时间"去重（同一场两边都命中只保留一条），再用文字让用户**选定要取消的唯一一条**；选定后按其归属路由——是纯日程 → `schedule cancel`；是会议（或两边都命中的同一场）→ 改用 `读取 wecomcli-meeting 技能` 走 `meeting cancel`（会连带取消关联日程，禁止再对该日程调用 `schedule cancel`）。
+
+> **与查询消歧的区别**：查询时可以两边都查、都展示；但取消是**写操作，绝不能两边都直接取消**，模糊时必须先让用户确认唯一目标，再执行对应的 cancel。
+
+## 取消日程工作流
+
+```
+用户发起取消意图
+    |
+    +-- 搜索目标日程
+    |   +-- 有关键词 → search（不追问时间）
+    |   +-- 有时间信息 → list 按时间范围查询
+    |   +-- 都没有 → 用文字询问引导用户补全缺失的参数
+    |
+    +-- 匹配结果处理
+    |   +-- 唯一匹配 → 继续
+    |   +-- 多条匹配 → 用文字让用户选择目标日程：
+    |   |     文字提问："找到多个匹配日程，请选择要取消的一个："
+    |   |     列出候选（如"项目评审 - 4月8日 14:00 / 项目评审 - 4月15日 14:00"，最多 4 条）
+    |   +-- 无匹配 → 扩大搜索 / 提示换关键词
+    |
+    +-- 判定会议关联与周期性：meeting 与 repeat_rule 在 search/list 结果中已直接返回，直接判定，无需补 get
+    |   +-- meeting.meeting_code 非空（含在线会议链接）
+    |   |     +-- 改期意图（改约/挪到/顺延，即使带"取消"）→ 改用 `读取 wecomcli-meeting 技能`，把 meeting_id 传入 meeting update 改时间
+    |   |     +-- 纯取消（不办了/不要了）→ 改用 `读取 wecomcli-meeting 技能` 走 meeting cancel（会连带取消关联日程，禁止在此 schedule cancel）
+    |   +-- meeting 为空（纯日程）
+    |         +-- 普通日程 → 直接执行 cancel
+    |         +-- 周期日程（repeat_rule.is_repeat=true）→ 终止操作，用文字告知用户："目前暂不支持取消周期日程，请在企业微信客户端对该日程进行取消操作"，禁止改为整系列直接 cancel 或其他变通方式
+    |
+    +-- 执行 cancel（不论日程由谁创建，都直接执行，不提前拒绝）→ 依返回结果判断：
+          +-- 返回空对象 {} → 取消成功，报告结果
+          +-- 返回权限类错误 → 说明当前用户无权取消该日程，告知用户并建议联系日程创建人（creator_name）操作
+```
+
+## 典型场景
+
+### 1. 取消普通日程
+
+```
+用户：帮我取消明天的项目评审
+→ 调用 search（keywords=["项目评审"]，明天）
+→ 找到 1 条
+→ 调用 cancel（schedule_id）
+→ 报告：已取消
+```
+
+### 2. 取消周期日程（不支持）
+
+```
+用户：帮我取消这周五的周会
+→ 搜索 → 找到"团队周会"（周期日程，repeat_rule.is_repeat=true）
+→ 不调用 cancel → 告知：目前暂不支持取消周期日程，请在企业微信客户端对该日程进行取消操作
+```
+
+### 3. 取消非本人创建的日程
+
+不预先按"是否本人创建"拦截，直接执行 cancel，根据返回结果判断。
+```
+用户：帮我取消明天张三约的评审
+→ 搜索 / get → 找到日程（创建人是张三）
+→ 不提前拒绝 → 直接调用 cancel（schedule_id）
+→ 依返回判断：
+    · 返回 {} → 报告：已取消
+    · 返回权限错误 → 告知：你无权取消该日程，建议联系创建人张三操作
+```
+
+## 注意事项
+
+- **权限判定交给接口**：不预先按"是否本人创建"限制取消——直接执行 `cancel`，根据返回结果判断：返回空对象 `{}` 即取消成功；返回权限类错误则说明当前用户无权取消该日程，告知用户并建议联系创建人操作。
+- **直接执行**：参数就绪后直接调用取消接口，无需展示摘要或等待确认。
+- **周期日程不支持取消**：检测到目标日程 `repeat_rule.is_repeat=true` 时，直接告知用户目前暂不支持取消周期日程，引导其在企业微信客户端操作，禁止改为整系列直接 cancel 等变通方式（详见 [SKILL.md 已知限制](../SKILL.md)）。
+- **"取消……改约到……"是改期、不是取消**：同时出现"取消"和"改到/改约/挪到/顺延"时本质是改期，按 SKILL.md「改约 / 重建日程前必须先识别会议关联」走更新流程，禁止拆成 cancel + create（目标 `meeting` 非空时，cancel + create 会丢失会议链接）。仅用户明确"不办了/不要了/直接取消"且无改期诉求时才执行 cancel。
+- **关联在线会议的日程不在此取消**：若目标 `meeting` 非空（`search`/`list` 结果即可判定，无需补 `get`；或同一场在会议和日程两边都命中），改用 `读取 wecomcli-meeting 技能` 走 `meeting cancel`，会议取消后该日程会被一并取消，禁止在此对其调用 `schedule cancel`。
+- **禁止暴露 userid**：结果展示中参与人只显示人名。
+
+## 参考
+
+- [wecomcli-calendar](../SKILL.md) — 日程技能主文档
+- [calendar-search](calendar-search.md) — 搜索日程（用于定位目标日程）
+- [calendar-agenda](calendar-agenda.md) — 查看日程安排

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

@@ -0,0 +1,238 @@
+# calendar schedules create — 创建日程
+
+创建日程并按需邀请参与人。
+
+> [!CAUTION]
+> 这是**写入操作** — 参数就绪后直接执行。
+
+## 命令
+
+```bash
+# 创建日程（含参与人）—— 以"明天下午2点"为例，实际日期需替换为当前时间之后的具体值
+wecom-cli calendar schedules create --json '{
+  "subject": "产品评审",
+  "begin_time": "<明天日期> 14:00:00",
+  "end_time": "<明天日期> 15:00:00",
+  "attendees": [{"userid": "woxxxa"}, {"userid": "woxxxb"}]
+}'
+
+# 仅自己的日程（无参与人）
+wecom-cli calendar schedules create --json '{
+  "subject": "午餐",
+  "begin_time": "<明天日期> 12:00:00",
+  "end_time": "<明天日期> 13:00:00"
+}'
+
+# 全天日程
+wecom-cli calendar schedules create --json '{
+  "subject": "年假",
+  "begin_time": "<目标日期> 00:00:00",
+  "end_time": "<目标日期> 23:59:59",
+  "is_all_day": true
+}'
+
+# 创建日程并预订会议室（meeting_room_id 来自 rooms search，见 calendar-meeting-room；订房成功后只传 meeting_room_id，无需再把会议室名重复填进 location）
+wecom-cli calendar schedules create --json '{
+  "subject": "产品评审",
+  "begin_time": "<明天日期> 14:00:00",
+  "end_time": "<明天日期> 15:00:00",
+  "attendees": [{"userid": "woxxxa"}, {"userid": "woxxxb"}],
+  "meeting_room_id": "mrmxxxx"
+}'
+```
+
+## 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|:----:|--------|------|
+| `subject` | string | 是 | — | 日程主题 |
+| `begin_time` | string | 是 | — | 开始时间（格式 YYYY-MM-DD HH:mm:ss，**必须晚于当前时间**） |
+| `end_time` | string | 是 | — | 结束时间（格式 YYYY-MM-DD HH:mm:ss，必须晚于 `begin_time`）。如果用户没有给出，默认填写开始时间的一小时后 |
+| `attendees` | object[] | 否 | `[]` | 参与人列表，格式为 `[{"userid": "woxxx"}, {"userid": "woyyy"}]`。用户提供的是姓名时通过 `读取 wecomcli-contact 技能` 解析为 userid |
+| `location` | string | 否 | `""` | 地点（文本）。**用户给的地点是某会议室时**：须先经 `rooms search` 预订该会议室（见步骤 3.5），预订成功后**只传 `meeting_room_id`、不再写 `location`**（会议室名由后端关联返回，无需在 `location` 里重复填充）。**用户给的地点不是会议室时**（如"星巴克""3 楼茶水间""客户现场"）：直接写入 `location`，不涉及 `meeting_room_id`。禁止把会议室名仅写进 `location` 却不订房——那样不会真正占用会议室 |
+| `meeting_room_id` | string | 否 | — | 会议室 ID，来自 [calendar-meeting-room](calendar-meeting-room.md) 的 `rooms search`。传入即触发后端"建日程 + 占会议室"原子操作。订会议室时只传本字段即可，**不需要再把会议室名重复填进 `location`**。**该 ID 仅工具链使用，禁止出现在用户回复正文** |
+| `description` | string | 否 | `""` | 日程描述 |
+| `reminders` | object | 否 | — | 提醒设置：`is_remind`（bool，是否提醒）+ `reminder_time`（负数秒数组，表示提前提醒的秒数）。**仅在用户明确表达提醒意图时才传**：① 用户明确说"不提醒 / 不用提醒"→ 传 `is_remind=false`；② 用户明确了提前多久提醒（如"提前 10 分钟""提前 1 小时"）→ 传 `is_remind=true`，并把时长换算为对应的负数秒数组（如提前 10 分钟 = `[-600]`、提前 1 小时 = `[-3600]`）。用户未提及提醒时省略本字段，不要自行补默认提醒 |
+| `timezone` | object | 否 | 用户 vid 时区 | 时区：`timezone_id`（如 `Asia/Shanghai`）+ `timezone_offset`（秒，如 `28800`） |
+| `allow_self_join` | bool | 否 | `true` | 是否允许主动加入 |
+| `is_all_day` | bool | 否 | `false` | 是否全天日程 |
+
+**返回**：`schedule_id`（新建日程的唯一标识）。传了 `meeting_room_id` 时额外返回 `meeting_room.{meeting_room_id, meeting_room_name}` 关联字段（展示用 name）。
+
+### 地点（`location`）vs 会议室（`meeting_room_id`）的区别 [CRITICAL]
+
+两者都描述"在哪开"，但语义和处理方式不同，按用户给的地点是否为**会议室**分流：
+
+| 用户 query 中的地点 | 处理方式 | 传入字段 |
+|--------------------|---------|---------|
+| **是某会议室**（如"地点在 1605 会议室""在 A 座创新室开"） | 必须先经 `rooms search` 尝试预订该会议室（见步骤 3.5）。预订成功（`status=bookable`）→ 拿到 `meeting_room_id`；不可用 → 走候选/换时间流程 | 预订成功后**只传 `meeting_room_id`**（占用会议室）；`location` 留空、不重复填会议室名 |
+| **不是会议室**（如"星巴克""3 楼茶水间""客户现场""线上腾讯会议"等自由文本地点） | 直接作为文本地点使用，无需也不要走会议室查询 | 仅传 `location`，不传 `meeting_room_id` |
+
+- **判定原则**：地点文本中含"会议室 / 室 / 房间 / 1605 这类房间号 / 某楼某室"等指向公司可预订会议室的表述，按"会议室"处理；否则按普通文本地点处理。无法判断时，可用文字与用户确认"是否需要预订该会议室"。
+- **关键约束**：会议室场景下严禁只写 `location` 不传 `meeting_room_id`——只写文本不会真正占用（预订）会议室，会导致会议室被他人占用。
+
+## 预约日程工作流
+
+> **设计理念**：减少用户决策负担——能推断的不问，必须问的只问一次，决策留给用户而非代劳。
+
+### 步骤 0：日程 / 会议消歧（仅当意图是"开会/约会"且未明确时）
+
+> **触发条件**：用户说"会议/会/开个会/约个会/安排个会/xx会/xx会议"等，但未明确是日程还是会议（会议含在线会议链接、可远程/视频参会）。已明确是纯线下场景（如"约个 1:1""碰个面"）时才跳过本步骤。
+>
+> **注意 1**：用户只说"会议/会/开会"等泛称，本身不构成"明确"——这些词没有表明是日程还是会议，**禁止仅因 query 里有"会议"二字就默认按日程创建、跳过本步骤**，必须先用文字追问。
+>
+> **注意 2**：仅给出地点/会议室号的表述（如"在 1605 开会""到 A 座会议室碰一下""订个会议室开会"）不能据此判定为日程——订会议室与是日程还是会议是两件事，会议室里同样可能要远程接入。此类"只有地点"的表述仍需先用文字询问消歧，不要因为带了地点就跳过本步骤。
+
+用文字直接询问用户创建日程还是会议，禁止默认直接创建日程：
+
+> **问题与选项固定 [CRITICAL]**：消歧确认时，问题与可选项都必须原文照用、严格禁止修改任何内容——问题固定为 `"需要创建日程还是会议？"`，可选项固定为 `日程` / `会议`；不得改写问题措辞、增减或改写选项、翻译，或自行设计其他表述（如"在线会议 / 线上会议 / 视频会议 / 线下会议"等）。
+
+用文字向用户提问：`需要创建日程还是会议？（请回复：日程 / 会议）`
+
+- 用户答「日程」→ 留在本技能，继续步骤 1。
+- 用户答「会议」→ 停止本工作流，改用 `读取 wecomcli-meeting 技能` 创建会议（创建会议会同时生成对应日程，无需在本技能再建一条）。
+
+### 步骤 1：上下文提取与信息补全
+
+- **主题**：默认必须用文字询问主题，**禁止从对话语境自行提炼或代填**。仅当用户已明确说明主题（如"建个『产品评审』的日程""主题就叫周会"）时，才直接使用用户给出的主题、不再询问；只要用户没点明主题（哪怕能从事由猜出来，如"和张三约下午聊聊"），一律用文字询问：`请问这个日程的主题是？`（可举例"需求对齐 / 方案评审 / 1:1 沟通"等供参考，最多举 4 个，用户也可自行输入）
+- **时长**：用户明确说了时长则直接使用；未提供时，统一默认 60 分钟（1 小时），不追问，由 `begin_time + 时长` 推算 `end_time`。
+- **参与人**：用户明确指定了参与人则解析使用（人名 → userid，见步骤 2）；未提供时必须用文字追问，禁止默认创建个人日程或自行猜测：`需要邀请哪些人参与？`（可列出"仅自己（个人日程）"及根据对话语境补充的 1-3 个候选人名供参考，合计最多 4 个，用户也可自行输入）
+
+### 步骤 2：参与人解析（人名 → userid）
+
+> 上下文中已有合法 userid（`wo` 前缀）则直接使用，无需重复查询。
+
+用户提供的是姓名时，通过 `读取 wecomcli-contact 技能` 将所有姓名批量搜索，逐个关键词独立处理结果：
+
+- **唯一匹配** → 直接使用，无需确认
+- **多个匹配** → 用文字让用户选择，不自行猜测：`搜索到多个「{姓名}」，请确认要邀请哪一位？` 并列出候选（如"张三 - 产品部 - 产品经理 / 张三 - 技术部 - 前端工程师"，最多列 4 条，超出取前 4 并提示用户缩小范围）
+- **无结果** → 用文字提示用户重新输入：`未找到「{姓名}」，请确认姓名是否正确`
+- 所有姓名确认完毕后，汇总 userid 一并组装为 `attendees` 数组（格式 `[{"userid": "woxxx"}]`）
+- **偏好记忆**：记录用户历史选择（如"张三"总是选"产品部-张三"），后续同名直接复用，减少确认轮次。
+
+### 步骤 3：时间协商与冲突处理
+
+不区分日程类型（不存在"生活类/工作类"之分，也没有"纯个人事项"可跳过的说法），所有创建一律查忙闲：查询对象始终包含当前用户自己（新建场景自己也要纳入，避免把日程排到自己已占用的时段），有其他内部参与人时一并纳入。按用户给出的时间信息分三种处理：
+
+> 边界说明：这里"自己按完整目标时段查"是因为新建日程尚不存在、没有"本日程已占时段"需要排除；这与 update 改已有日程时"对自己/现有参与人扣除原时段重叠、纯自己可跳过"是同一原则（忙闲只为发现本日程之外的冲突）在"日程未建 / 已存在"下的不同表现，不要把 update 的"纯自己跳过"套到新建上。
+>
+> 查忙闲时 `min_duration_minutes` 设成该日程时长（或直接传 1），否则被默认 30 分钟过滤掉的短空闲段，会让落在其中的短日程误报为冲突。
+>
+> **推荐时段长度 ≠ 日程时长（精确 / 范围 / 未提供时间三种情况均适用）**：忙闲查询返回的推荐时段只用于确定日程的**开始时间**，其长度不代表日程时长。用户选定时段后，日程时长仍以用户明确指定的为准；用户未明确时长时一律默认 1 小时（`begin_time + 1h`，与步骤 1「时长」一致），禁止把推荐时段的长度直接当作日程时长。
+
+- 精确时间（如"明天下午3点"）：先验证晚于当前真实时刻，已过去则提示用户重选未来时间；时间有效后必须先读取 [calendar-freebusy](calendar-freebusy.md) 检查忙闲（查询对象 = 自己 + 其他内部参与人）。任一对象（含自己）占线时，必须用文字让用户在「坚持这个时间 / 换一个时间」之间二选一，禁止自行换时间或劝阻用户改期：`该时间段{姓名}有日程冲突，如何处理？（请回复：坚持这个时间 / 换一个时间）`（仅与自己冲突时 {姓名} 写"你"）
+- 范围时间（如"明天"、"下午"）：读取 [calendar-freebusy](calendar-freebusy.md)（查询对象 = 自己 + 其他内部参与人）拿到空闲 `slots`，让用户从返回的空闲时段中选择，选定后再创建（无需手填候选时刻，直接用 free list 返回的时段）。
+- 未提供时间：先用文字列出具体的"日期+时刻"候选项让用户选择（结合当前时间动态推断，所有候选项必须晚于当前时刻，禁止使用"上午/下午/傍晚"等模糊表述，最多列 4 个）；用户选定具体时刻后，按上面"精确时间"的方式查忙闲再创建。文字提问如：`日程什么时候开始？`（候选按当前时刻动态生成、均须晚于现在，例如当前 19:40 可列 "明天 09:00 / 明天 14:00 / 明天 16:00 / 后天 09:00"）
+
+**时间与日期推断规范：**
+- **星期基准**：周一是一周第一天，周日是最后一天。
+- **整天范围**："明天"、"今天"覆盖 00:00:00 ~ 23:59:59。但"今天"作为候选范围时，只能推荐晚于当前时刻的具体时间点；若当天已无合适时段，自动顺延到明天。
+- **全天日程（`is_all_day=true`）**：不主动猜测事件类型。仅在以下情形才设 `is_all_day=true`：① 用户明确说是"全天 / 请一天假 / 休一天"；② 起止时间实际就是完整一天，即 `begin_time="YYYY-MM-DD 00:00:00"`、`end_time="同一天 23:59:59"`。其余情况（给了具体时刻、或时段不满整天）一律按普通定时日程处理，不设全天。
+  - **格式必须落在同一天、从早到晚**：`begin_time="YYYY-MM-DD 00:00:00"`、`end_time="同一天 23:59:59"`。禁止写成次日 0 点（`YYYY-MM-DD+1 00:00:00`）——那样不带 `is_all_day` 会显示成"0 点到 0 点"，带了又会多占一天。
+  - **跨多天的全天事件**拆成 N 条单日全天，每条仍是同一天 `00:00:00 ~ 23:59:59`，逐条调用 create 分别创建。
+- **历史约束**：不能创建已完全过去的日程，推荐的时间必须晚于当前时刻。
+- **时间格式**：统一 `YYYY-MM-DD HH:mm:ss`。
+- **模糊时间表达**：遇到"上班后"、"下班前"等表达，必须用文字询问引导用户补全，禁止猜测。澄清后将结果沉淀为长期偏好（如"上班后"=9:30），后续同类表达直接复用。
+- **时区处理**：默认不传，由服务端使用用户 vid 时区。用户明确指定时区时，传入 `timezone_id`（IANA 时区名称，如 `"America/New_York"`）+ `timezone_offset`（与 UTC 的偏移秒数）。传入的 `begin_time` / `end_time` 按日程时区解释为墙上时间，禁止自行换算。
+
+> **长期记忆**：用户的时间偏好、常见主题偏好等，在首次明确后应记忆，减少后续重复追问。（时长不在此列：用户未指定时一律默认 1 小时、不追问。）
+
+### 步骤 3.5：会议室预订分支（仅当用户有订房意图时触发）
+
+> **触发条件**：用户提到"订会议室 / 在 1605 / 找个会议室 / 某栋办公楼的会议室"等订房意图时才走本步骤；没提则跳过，按普通日程创建。
+>
+> **前置**：本步骤依赖确定的 `begin_time` / `end_time`，必须在步骤 3 时间敲定之后执行（范围时间先经 freebusy 选定时段）。
+
+会议室的查询接口（楼清单 + 可订性）定义在 [calendar-meeting-room](calendar-meeting-room.md)，按其编排执行，拿到 `meeting_room_id` 后回填到本创建的 `meeting_room_id` 参数。
+
+> [!CAUTION]
+> **五条硬性规则（不可跳过）：**
+> 1. **先查询、后推荐、后创建**：要预订会议室时，`meeting_room_id` 必须来自 `rooms search` 返回的真实值，禁止跳过会议室查询直接 create，禁止凭记忆 / 上下文 / 猜测编造 `meeting_room_id`——没有先查到真实 ID 就不允许带 `meeting_room_id` 创建。同样地，在成功调用 `rooms search` 之前，禁止凭记忆 / 上下文 / 想象向用户罗列或推荐任何具体会议室（含用文字给出的候选、正文里的房间名 / 号 / 楼层 / 容量）——要让用户选会议室，必须先查到真实候选再组装选项。
+> 2. **存在多个会议室必须让用户选**：当查询结果命中多个可选会议室（`recommendations` 条目数 > 1，或用户未指定具体会议室而返回了多个候选）时，必须用文字让用户从候选中选择，或让用户指定具体会议室，禁止自动替用户挑选（如默认取第一个）。
+> 3. **会议室必须订房、且只传 `meeting_room_id`**：只要用户给的地点是会议室（"订会议室 / 在 1605 开 / 找个会议室 / xx 楼会议室"等），就必须走 `rooms search` 查到真实会议室并通过 `meeting_room_id` 参数传入创建；严格禁止把会议室名 / 房间号仅塞进 `location` 字段就创建（那样不会真正占用会议室）。预订成功后创建时**只传 `meeting_room_id`**（占用），**不需要再把会议室名重复填进 `location`**（会议室名由后端关联返回）。仅当用户给的是非会议室的普通地点（如"星巴克"）时，才只写 `location`、不走订房。
+> 4. **优先先订房、后建程**：用户在创建时就提到会议室的，应先把会议室敲定（拿到用户确认的 `meeting_room_id`）再进入步骤 4 创建日程，本步骤（3.5）是步骤 4 的前置阻塞项，避免创建后会议室被抢占。若会议室查询 / 选择尚未完成（如等待用户在候选中选择、等待用户确认换楼或换时间），必须停在本步骤等待，不得提前调用 create。若创建时漏订或事后要换会议室，可走 [calendar-update](calendar-update.md) 传入新 `meeting_room_id` 改订（须先经 `rooms search` 确认 `status=bookable`），不必取消重建。
+> 5. **指定会议室查无/不可用时必须先告知、禁止静默替换**：用户指定的会议室在 `target` 中找不到可订项（`target = []` 查无此名，或命中项均为 `unavailable` 该时段被占）时，必须先告知用户"未查到 / 无法预订你指定的『xxx』会议室"，再用文字让用户决定改订其他会议室或换时间。严禁静默用其他名称的会议室替代——即使 `recommendations` 仅 1 个候选也须经用户确认。"`recommendations` 仅 1 个可直接使用"只适用于用户未指定具体会议室（`target = []`）的情形。
+
+1. 用户提了楼名 → `buildings list` + LLM 匹配得到 `building_city/name`；没提楼则跳过（后端用当前所在楼兜底）。
+2. `rooms search`（带时间 + 可选楼 + 可选 `room_keyword` + `min_capacity = len(attendees) + 1`）。
+3. 按结果决策：
+   - 用户**指定了具体会议室**（传了 `room_keyword`）且 `target` 中有 `bookable` 项 → 取该项 `target[].room.meeting_room_id`（仅 1 个直接用，多个则用文字让用户选）。
+   - 用户**指定的会议室** `target = []`（查无此名）或命中项均 `unavailable`（该时段被占）：先告知用户"未查到 / 无法预订你指定的『xxx』会议室"，再用文字让用户决定改订其他会议室或换时间。禁止用其他名称的会议室静默替代——`recommendations` 仅 1 个候选也须经用户确认才改订；`recommendations` 为空则告知后问是否跨楼（`expand_to_other_buildings=true` 重试）或换时间。
+   - 用户**未指定具体会议室**（`target` 为 `[]`）：
+     - `recommendations` 有**多个**候选 → 必须用文字让用户选择（候选取前 2~4 个，展示会议室 `name` + 楼层 + 容量，`meeting_room_id` 不得出现在文案中）。
+     - `recommendations` 只有 **1 个**候选 → 可直接使用该候选的 `meeting_room_id`。
+     - `recommendations` 为空 → 用文字问用户是否跨楼（`expand_to_other_buildings=true` 重试）或换时间。
+4. 选定后将用户确认的 `meeting_room_id` 带入步骤 4 的 create，**只传 `meeting_room_id` 即可**（无需再把会议室名重复填进 `location`）。
+
+> **换会议室走 update**：创建后要换会议室时，用 [calendar-update](calendar-update.md) 传入新 `meeting_room_id` 改订即可（须先经 `rooms search` 确认新会议室 `status=bookable`），无需取消重建。
+
+### 步骤 4：执行创建
+
+参数就绪后直接执行 create 命令，无需展示摘要或等待确认。
+
+### 步骤 5：结果反馈
+
+创建成功后拿到返回的 `schedule_id`，调用日程详情查询 `wecom-cli calendar schedules get --json '{"schedule_ids": ["<schedule_id>"]}'`（见 [calendar-agenda](calendar-agenda.md)）获取 `subject`、`begin_time`/`end_time`、`attendees[].name`，据此输出。**输出内容只包含三部分：主题、时间、参与人**，禁止输出其他任何内容和额外语句（不展示地点、提醒、`schedule_id` 等字段，也不附加说明、建议或寒暄）。参与人原样取接口返回的 `attendees[].name` 展示（完全与接口返回的格式保持一致，如返回 `zhangsan(张三)` 就展示 `zhangsan(张三)`），禁止暴露 userid；非东八区日程按 [SKILL.md 输出格式规范](../SKILL.md) 的时区标注规则在时间后带上时区。
+
+```
+主题：{subject}
+时间：{月日} {HH:mm}-{HH:mm}
+参与人：{人名1}、{人名2}
+```
+
+## 典型场景
+
+### 1. 简单创建
+
+```
+用户：帮我和张三约明天下午3点，聊半小时
+→ 通过 wecomcli-contact 技能搜索「张三」→ 返回 2 个候选
+→ 用文字询问：搜索到多个「张三」，请确认要邀请哪一位？（列出：张三 - 产品部 - 产品经理 / 张三 - 技术部 - 前端工程师）
+→ 用户选择后，获得对应 userid
+→ 用户未说明主题 → 用文字询问主题（禁止自行起名）：请问这个日程的主题是？（可举例：需求对齐 / 1:1 沟通 / 项目同步）
+→ 组装参数：subject=<用户选定/填写的主题>，begin_time="<明天日期> 15:00:00"，end_time="<明天日期> 15:30:00"
+→ 调用 create
+```
+
+### 2. 约多人（先查共同空闲）
+
+```
+用户：帮我约张三和李四明天下午聊一下
+→ 通过 wecomcli-contact 技能批量搜索「张三」「李四」
+→ 逐个处理：唯一匹配直接使用，多个匹配则用文字让用户选择
+→ 调用 free list 拿明天下午的共同空闲 slots
+→ 比较 slots[0].available_count 与 total_count 判断是全员空闲 / 降级 / 全忙
+→ 挑前几个时段让用户选择
+→ 用户选择方案 → 调用 create
+```
+
+详细的共同空闲查询与降级处理流程见 [calendar-freebusy](calendar-freebusy.md)。
+
+## 注意事项
+
+- **参与人 userid**：userid 为 `wo` 前缀的编码字符串（如 `woxxx`），`attendees` 传入时需组装为对象数组格式 `[{"userid": "woxxx"}]`。用户提供的是姓名时通过 `读取 wecomcli-contact 技能` 解析为 userid；禁止把姓名当 userid 拼接，禁止凭记忆或猜测编造。
+- **时间约束**：`begin_time` 必须晚于当前时间，否则创建失败；`end_time` 必须晚于 `begin_time`。禁止推荐或传入已过去的时间。
+- **无时长上限**：`end_time` 只需晚于 `begin_time`，支持创建时长超过 24 小时、跨天或多天的单条定时日程，无需拆分（全天日程 `is_all_day=true` 仍按前文全天日程规范按单日 `00:00:00~23:59:59` 拆分，这是全天格式要求、与时长无关）。
+- **不支持创建周期/重复日程**：API 仅支持创建单次日程。用户希望创建"每周/每月/每天重复"等周期日程时，**直接告知用户目前不支持创建周期日程，并引导用户在企业微信客户端手动预订周期日程**；不要尝试任何变通绕过的做法——包括但不限于：创建多条单次日程模拟周期效果、传入 `repeat_rule` 等参数表中未列出的字段、创建后再用 `update` 改造为周期日程。原因：API 层根本无此能力，伪造的"周期"日程在企微客户端中也无法被识别为周期，反而会造成多条独立日程难以批量管理。
+- **会议室预订**：用户给的地点是会议室时，必须先经 [calendar-meeting-room](calendar-meeting-room.md) 的 `rooms search` 查到真实会议室并以 `meeting_room_id` 传入创建（见步骤 3.5），禁止把会议室名仅写进 `location`（那样不会真正占用会议室）；订房成功后只传 `meeting_room_id`、不重复填 `location`。仅当用户给的是非会议室的普通文本地点时才只写 `location`、不走订房。
+- **直接执行**：参数补全后直接调用创建接口，无需展示摘要或等待确认。
+- **禁止暴露 userid**：结果展示中只显示人名。
+- **参数补全原则**：缺失的必填参数（`subject` / `begin_time` / `end_time`）以及参与人 `attendees` 必须用文字询问。其中 `subject` **仅在用户已明确说明主题时才算"已提供"可直接用，否则一律视为缺失、必须询问，禁止用对话语境自行提炼代填**。其余非必填参数用户未明确指定时不追问——有默认值的走默认值，无默认值的则不传该字段（如地点不填、提醒不设置）。
+
+## 异常路径
+
+| 异常情况 | 处理方式 |
+|---------|---------|
+| `begin_time` 早于当前时间 | 提示用户时间已过，请重新选择未来时间，不重试，等待用户修正 |
+| `end_time` 不晚于 `begin_time` | 提示用户结束时间必须晚于开始时间，请调整 |
+| wecomcli-contact 技能搜索无结果 | 用文字提示用户重新输入：`未找到「{姓名}」，请确认姓名是否正确` |
+| wecomcli-contact 技能返回多个候选人 | 用文字询问用户（列出候选姓名 + 部门），等待用户选择后汇总继续 |
+| 创建接口返回错误 | 检查参数格式，重新阅读本文档确认用法 |
+| `meeting_room_taken`（会议室被抢占） | 查询通过后、create 前会议室被他人占走。用文字告知"{会议室名} 刚被占用"，让用户在「换会议室 / 换时间」二选一；选换会议室则重走步骤 3.5 的 `rooms search`，禁止静默重试同一会议室 |
+| `meeting_room_not_found`（会议室无效） | `meeting_room_id` 不存在或上下文已过期，重新走步骤 3.5 的 `rooms search` |
+
+## 参考
+
+- [wecomcli-calendar](../SKILL.md) — 日程技能主文档
+- [calendar-freebusy](calendar-freebusy.md) — 查询忙闲状态
+- [calendar-meeting-room](calendar-meeting-room.md) — 会议室查询（订房时拿 `meeting_room_id`）

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) — 创建日程