@sunnoy/wecom 2.1.0 → 2.2.1

package/skills/wecom-meeting-query/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: wecom-meeting-query
+description: 企业微信会议查询技能, 支持查询会议列表, 获取会议详情, 按关键词查找会议. 当用户需要"查看会议", "查询会议列表", "会议详情", "什么时候开会", "有哪些会议", "查找会议"时触发.
+---
+# 企业微信会议查询技能
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+> ⚠️ **路径与停止规则**：
+> - 如果要读取本 skill，必须直接使用 `<available_skills>` 或 `skillsSnapshot` 中给出的精确绝对路径。
+> - 不要猜测或改写为 `/data/openclaw/skills/wecom-*`、`/workspace/.openclaw/skills/...`、`/root/.openclaw/workspace-*/.openclaw/skills/...`，也不要用 `exec` + `ls/find` 探路。
+> - 若 `wecom_mcp` 返回 `errcode: 846609` 或 `unsupported mcp biz type`，表示当前 bot 未开通该 category，不是路径、白名单或 sandbox 问题；立即停止继续 `read`、`list`、`find`、memory fallback 探索，直接告知用户对应 category 未开通。
+
+## 概述
+
+wecom-meeting-query 提供企业微信会议查询能力, 包含以下功能:
+
+1. **查询会议列表** - 按用户和时间范围查询会议 ID 列表 (限制: 当日及前后 30 天, 上限 100 个)
+2. **获取会议详情** - 通过会议 ID 查询完整会议信息
+
+## 命令调用方式
+
+查看可用命令列表：使用 `wecom_mcp` tool 调用 `wecom_mcp list meeting`
+
+执行指定命令：使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting <tool_name> '<json_params>'`
+---
+
+## 命令详细说明
+
+### 1. 查询会议列表 (list_user_meetings)
+
+查询指定用户在时间范围内的会议 ID 列表.
+
+#### 执行命令
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting list_user_meetings '{"begin_datetime": "2026-03-01 00:00", "end_datetime": "2026-03-31 23:59", "limit": 100}'`
+
+#### 入参说明
+
+| 参数               | 类型    | 必填 | 说明                                    |
+| ------------------ | ------- | ---- | --------------------------------------- |
+| `begin_datetime` | string  | 否   | 查询起始时间, 格式:`YYYY-MM-DD HH:mm` |
+| `end_datetime`   | string  | 否   | 查询结束时间, 格式:`YYYY-MM-DD HH:mm` |
+| `cursor`         | string  | 否   | 分页游标, 用于获取下一页数据            |
+| `limit`          | integer | 否   | 每页返回条数, 最大 100                  |
+
+> **限制**: 时间范围仅支持当日及前后 30 天.
+
+#### 返回参数
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok",
+  "next_cursor": "分页游标字符串, 为空表示无更多",
+  "meetingid_list": ["会议ID_1", "会议ID_2"]
+}
+```
+
+| 字段               | 类型   | 说明                           |
+| ------------------ | ------ | ------------------------------ |
+| `meetingid_list` | array  | 会议 ID 列表                   |
+| `next_cursor`    | string | 下一页游标, 为空表示无更多数据 |
+
+---
+
+### 2. 获取会议详情 (get_meeting_info)
+
+通过会议 ID 查询会议的完整详情.
+
+#### 执行命令
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting get_meeting_info '{"meetingid": "<会议id>"}'`
+
+#### 入参说明
+
+| 参数              | 类型   | 必填 | 说明            |
+| ----------------- | ------ | ---- | --------------- |
+| `meetingid`     | string | 是   | 会议 ID, 通过 `list_user_meetings` 获取 |
+| `meeting_code`  | string | 否   | 会议号码        |
+| `sub_meetingid` | string | 否   | 子会议 ID       |
+
+#### 返回参数
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok",
+  "creator_userid": "创建者userid",
+  "admin_userid": "会议管理userid (与 creator_userid 有且仅返回一个)",
+  "title": "会议标题",
+  "meeting_start_datetime": "YYYY-MM-DD HH:mm",
+  "meeting_duration": 会议时长秒数,
+  "description": "会议描述文本",
+  "location": "会议地点文本",
+  "main_department": 创建者主部门ID,
+  "status": 会议状态枚举值,
+  "meeting_type": 会议类型枚举值,
+  "attendees": {
+    "member": [
+      {
+        "userid": "内部成员userid",
+        "status": 与会状态枚举值,
+        "first_join_datetime": "YYYY-MM-DD HH:mm",
+        "last_quit_datetime": "YYYY-MM-DD HH:mm",
+        "total_join_count": 加入次数,
+        "cumulative_time": 累计在会时长秒数
+      }
+    ],
+    "tmp_external_user": [
+      {
+        "tmp_external_userid": "外部临时用户ID",
+        "status": 与会状态枚举值,
+        "first_join_datetime": "YYYY-MM-DD HH:mm",
+        "last_quit_datetime": "YYYY-MM-DD HH:mm",
+        "total_join_count": 加入次数,
+        "cumulative_time": 累计在会时长秒数
+      }
+    ]
+  },
+  "settings": {
+    "remind_scope": 提醒范围枚举值,
+    "need_password": 是否需要密码布尔值,
+    "password": "会议密码",
+    "enable_waiting_room": 是否启用等候室布尔值,
+    "allow_enter_before_host": 是否允许提前入会布尔值,
+    "enable_enter_mute": 入会静音枚举值,
+    "allow_unmute_self": 是否允许自我解除静音布尔值,
+    "allow_external_user": 是否允许外部用户布尔值,
+    "enable_screen_watermark": 是否开启水印布尔值,
+    "watermark_type": 水印类型枚举值,
+    "auto_record_type": "录制类型枚举字符串",
+    "attendee_join_auto_record": 参会者加入自动录制布尔值,
+    "enable_host_pause_auto_record": 主持人可暂停录制布尔值,
+    "enable_doc_upload_permission": 允许上传文档布尔值,
+    "enable_enroll": 是否开启报名布尔值,
+    "enable_host_key": 是否启用主持人密钥布尔值,
+    "host_key": "主持人密钥字符串",
+    "hosts": {"userid": ["主持人userid列表"]},
+    "current_hosts": {"userid": ["当前主持人userid列表"]},
+    "co_hosts": {"userid": ["联席主持人userid列表"]},
+    "ring_users": {"userid": ["响铃用户userid列表"]}
+  },
+  "meeting_code": "会议号码字符串",
+  "meeting_link": "会议链接URL",
+  "has_vote": 是否有投票布尔值,
+  "has_more_sub_meeting": 是否有更多子会议枚举值,
+  "remain_sub_meetings": 剩余子会议场数,
+  "current_sub_meetingid": "当前子会议ID",
+  "guests": [
+    {
+      "area": "国际区号",
+      "phone_number": "手机号字符串",
+      "guest_name": "嘉宾姓名"
+    }
+  ],
+  "reminders": {
+    "is_repeat": 是否周期性枚举值,
+    "repeat_type": 重复类型枚举值,
+    "repeat_until_type": 结束类型枚举值,
+    "repeat_until_count": 限定次数,
+    "repeat_until_datetime": "YYYY-MM-DD HH:mm",
+    "repeat_interval": 重复间隔数值,
+    "is_custom_repeat": 是否自定义重复枚举值,
+    "repeat_day_of_week": [星期几数组],
+    "repeat_day_of_month": [日期数组],
+    "remind_before": [提醒秒数数组]
+  },
+  "sub_meetings": [
+    {
+      "sub_meetingid": "子会议ID",
+      "status": 子会议状态枚举值,
+      "start_datetime": "YYYY-MM-DD HH:mm",
+      "end_datetime": "YYYY-MM-DD HH:mm",
+      "title": "子会议标题",
+      "repeat_id": "周期性会议分段ID"
+    }
+  ],
+  "sub_repeat_list": [
+    {
+      "repeat_id": "周期性会议分段ID",
+      "repeat_type": 重复类型枚举值,
+      "repeat_until_type": 结束类型枚举值,
+      "repeat_until_count": 限定次数,
+      "repeat_until_datetime": "YYYY-MM-DD HH:mm",
+      "repeat_interval": 重复间隔数值,
+      "is_custom_repeat": 是否自定义重复枚举值,
+      "repeat_day_of_week": [星期几数组],
+      "repeat_day_of_month": [日期数组]
+    }
+  ]
+}
+```
+
+**关键返回字段:**
+
+| 字段                                      | 类型    | 说明                                                                                                          |
+| ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
+| `creator_userid`                        | string  | 创建者 userid, 与 `admin_userid` 有且仅返回一个                                                             |
+| `admin_userid`                          | string  | 会议管理 userid, 与 `creator_userid` 有且仅返回一个                                                         |
+| `title`                                 | string  | 会议标题                                                                                                      |
+| `meeting_start_datetime`                | string  | 会议开始时间                                                                                                  |
+| `meeting_duration`                      | integer | 会议时长 (秒)                                                                                                 |
+| `main_department`                       | integer | 创建者所属主部门                                                                                              |
+| `status`                                | integer | 会议状态 (1: 待开始, 2: 会议中, 3: 已结束, 4: 已取消, 5: 已过期)                                              |
+| `meeting_type`                          | integer | 会议类型 (0: 一次性会议, 1: 周期性会议, 2: 微信专属会议, 3: Rooms 投屏会议, 5: 个人会议号会议, 6: 网络研讨会) |
+| `meeting_code`                          | string  | 会议号码                                                                                                      |
+| `meeting_link`                          | string  | 会议链接                                                                                                      |
+| `attendees.member`                      | array   | 内部参与者列表                                                                                                |
+| `attendees.member[].status`             | integer | 与会状态 (1: 已参与, 2: 未参与)                                                                               |
+| `attendees.tmp_external_user`           | array   | 外部参与者 (临时 ID)                                                                                          |
+| `attendees.tmp_external_user[].status`  | integer | 与会状态 (1: 已参与, 2: 未参与)                                                                               |
+| `guests`                                | array   | 外部嘉宾列表, 每项含 `area`, `phone_number`, `guest_name`                                               |
+| `current_sub_meetingid`                 | string  | 当前子会议 ID                                                                                                 |
+| `settings.ring_users`                   | object  | 响铃用户列表                                                                                                  |
+| `settings.need_password`                | boolean | 是否需要密码 (只读字段)                                                                                       |
+| `settings.enable_doc_upload_permission` | boolean | 是否允许成员上传文档                                                                                          |
+| `settings.hosts`                        | object  | 主持人列表                                                                                                    |
+| `settings.current_hosts`                | object  | 当前主持人列表                                                                                                |
+| `settings.co_hosts`                     | object  | 联席主持人列表                                                                                                |
+| `reminders`                             | object  | 周期性配置                                                                                                    |
+| `has_vote`                              | boolean | 是否有投票 (仅会议创建人和主持人有权限查询)                                                                   |
+| `has_more_sub_meeting`                  | integer | 是否还有更多子会议特例 (0: 无更多, 1: 有更多)                                                                 |
+| `remain_sub_meetings`                   | integer | 剩余子会议场数                                                                                                |
+| `sub_meetings`                          | array   | 子会议列表                                                                                                    |
+| `sub_meetings[].status`                 | integer | 子会议状态 (0: 默认/存在, 1: 已删除)                                                                          |
+| `sub_meetings[].repeat_id`              | string  | 周期性会议分段 ID, 用于关联子会议所属分段                                                                     |
+| `sub_repeat_list`                       | array   | 周期性会议分段信息, 修改周期性会议某一场后可能产生不同分段, 各分段有不同重复规则                              |
+
+---
+
+## 典型工作流
+
+### 工作流 1: 查询会议列表
+
+**示例**: 用户说 "帮我查一下本周有哪些会议"
+
+**步骤:**
+
+1. **确定时间范围**: 根据当前日期计算本周的起止时间.
+2. **查询会议 ID 列表**:
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting list_user_meetings '{"begin_datetime": "2026-03-16 00:00", "end_datetime": "2026-03-22 23:59", "limit": 100}'`
+
+3. **逐个查询会议详情** (对返回的每个 meetingid):
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting get_meeting_info '{"meetingid": "<会议id1>"}'`
+使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting get_meeting_info '{"meetingid": "<会议id2>"}'`
+
+4. **汇总展示**:
+
+```
+📋 本周会议列表 (共 3 场):
+
+1. 📅 技术方案评审
+   🕐 2026-03-17 10:00 - 11:00
+   👥 张三, 李四, 王五
+
+2. 📅 产品需求沟通
+   🕐 2026-03-18 14:00 - 15:00
+   👥 赵六, 钱七
+
+3. 📅 周五周会
+   🕐 2026-03-21 09:00 - 10:00
+   👥 全组成员
+```
+
+> **分页处理**: 如果 `next_cursor` 不为空, 使用 `cursor` 参数继续拉取下一页.
+
+---
+
+### 工作流 2: 获取会议详情
+
+**示例**: 用户说 "帮我看下技术方案评审会议的详情"
+
+**步骤:**
+
+1. **定位会议**: 先通过会议列表查询找到目标会议的 meetingid (按关键词匹配).
+2. **查询详情**:
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting get_meeting_info '{"meetingid": "<target_meetingid>"}'`
+
+3. **展示结果**:
+
+#会议号: <会议号>
+
+```
+📅 <会议标题>
+
+🕐 时间: <开始时间>, 时长 <时长>
+📍 地点: <会议地点>
+📝 描述: <会议描述>
+👤 创建者: <创建者姓名>
+👥 参与者: <参与者姓名列表>
+🔗 会议链接: <会议链接>
+```
+
+---
+
+### 工作流 3: 根据关键词查找会议
+
+**示例**: 用户说 "技术评审会议是什么时候?"
+
+**查询策略:**
+
+1. **确定查询范围**: 默认查当日前后 30 天 (接口限制范围).
+2. **拉取会议列表**:
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call meeting list_user_meetings '{"begin_datetime": "2026-02-15 00:00", "end_datetime": "2026-04-16 23:59", "limit": 100}'`
+
+3. **逐个查询详情并匹配标题关键词**.
+4. **找到匹配后停止查询, 展示结果**:
+
+#会议号: <会议号>
+
+```
+✅ 找到会议: "<会议标题>"
+
+📅 时间: <开始时间>, 时长 <时长>
+📍 地点: <会议地点>
+👥 参与者: <参与者姓名列表>
+🔗 会议链接: <会议链接>
+```
+
+5. **未找到处理**: 告知用户在前后 30 天范围内未找到匹配会议, 请确认会议名称.
+
+---
+
+## 注意事项
+
+- **时间格式**: 统一使用 `YYYY-MM-DD HH:mm` 格式
+- **会议列表时间范围限制**: 仅支持查询当日及前后 30 天内的会议
+- **查询详情需两步**: 先通过 `list_user_meetings` 获取会议 ID 列表, 再通过 `get_meeting_info` 逐个获取详情

package/skills/wecom-preflight/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: wecom-preflight
+description: 企业微信 MCP 调用前置检查。用于 sandbox 场景下确认是否可以直接继续调用 `wecom_mcp`，并在工具未放行或宿主未完成配置时给出正确的人工处理指引。不要在 agent sandbox 内执行 `openclaw config` 或 `openclaw gateway restart`。
+---
+
+# 企业微信前置检查
+
+> 本技能只用于判断当前会话能否继续使用 `wecom_mcp`。
+> 在 agent sandbox 内，**不要**执行宿主机级别的 `openclaw config ...` 或 `openclaw gateway restart`。
+
+> ⚠️ **路径与停止规则**：
+> - 如果要读取 WeCom skill，必须直接使用 `<available_skills>` 或 `skillsSnapshot` 中给出的精确绝对路径。
+> - 不要猜测或改写为 `/data/openclaw/skills/wecom-*`、`/workspace/.openclaw/skills/...`、`/root/.openclaw/workspace-*/.openclaw/skills/...`，也不要用 `exec` + `ls/find` 探路。
+> - 若 `wecom_mcp` 返回 `errcode: 846609` 或 `unsupported mcp biz type`，表示当前 bot 未开通该 category，不是路径、白名单或 sandbox 问题；立即停止继续 `read`、`list`、`find`、memory fallback 探索，直接告知用户对应 category 未开通。
+
+## 何时使用
+
+在以下场景使用本技能：
+
+1. 当前会话第一次准备调用 `wecom_mcp`
+2. 调用 `wecom_mcp` 后返回 `tool not allowed`、`not permitted`、`permission denied`
+3. 你怀疑当前环境没有把 WeCom MCP 正确暴露给 agent
+
+如果当前会话里 `wecom_mcp` 已经成功调用过一次，就不要重复执行本技能。
+
+## 当前部署的正确做法
+
+本项目的 `wecom_mcp` 是否可用，取决于 **宿主机 OpenClaw 配置** 和 **sandbox 挂载**，不是由 agent 自己在容器里动态修复。
+
+因此：
+
+- 可以继续直接调用 `wecom_mcp` 的前提：工具已经出现在当前会话可用工具中，或你刚刚已经成功调用过
+- 不可以做的事：在 sandbox 里执行 `openclaw config get ...`、`openclaw config set ...`、`openclaw gateway restart`
+- 如果工具不可用，应该停止继续试探，并明确告知用户或管理员去宿主机修复
+
+## 检查流程
+
+### 情况 A：`wecom_mcp` 已可用
+
+满足任一条件即可视为通过：
+
+- 当前回合工具列表里已经有 `wecom_mcp`
+- 当前会话里之前已经成功调用过 `wecom_mcp`
+
+处理方式：
+
+- 直接继续执行原始 WeCom 技能
+- 不要再做额外的 shell 探测
+
+### 情况 B：返回工具权限错误
+
+如果错误类似：
+
+- `tool not allowed`
+- `not permitted`
+- `permission denied`
+- `unknown tool: wecom_mcp`
+
+这说明问题在 **宿主机工具放行配置**，不是当前业务参数错误。
+
+处理方式：
+
+- 立即停止继续试探
+- 明确告知用户：需要在宿主机上把 `wecom_mcp` 加入允许列表，并在必要时重启 gateway
+- 不要在 sandbox 内尝试修复
+
+可对用户说明：
+
+```text
+当前会话所在的 agent sandbox 里还不能使用 wecom_mcp。这个问题需要在宿主机 OpenClaw 配置里放行 wecom_mcp，并在必要时重启 gateway 后才会生效；我无法在当前 sandbox 内直接执行这类宿主机配置。
+```
+
+### 情况 C：返回 MCP 业务错误
+
+如果 `wecom_mcp` 工具本身可调用，但返回类似下面的业务错误：
+
+- `unsupported mcp biz type`
+- `errcode: 846609`
+
+这说明：
+
+- 工具权限通常已经没问题
+- 但当前机器人或当前企业微信侧 **没有开通对应 category**，例如只开了 `doc`，没有开 `schedule`
+
+处理方式：
+
+- 不要再把它误判成“tool 未放行”
+- 直接告诉用户：当前业务类型未开通，需要企业微信侧补充对应 MCP 配置
+
+## 决策规则
+
+| 现象 | 结论 | 动作 |
+| --- | --- | --- |
+| `wecom_mcp` 已成功调用 | 前置检查通过 | 继续原始任务 |
+| `tool not allowed` / `unknown tool` | 宿主机未放行工具 | 停止试探，提示宿主机修复 |
+| `unsupported mcp biz type` / `846609` | 对应业务类型未开通 | 停止试探，提示开通对应 category |
+| 其他业务报错 | 接口调用失败 | 按具体错误处理，不要误改环境 |
+
+## 关键约束
+
+1. 本技能是 **判断与分流**，不是在 sandbox 内自动修配置。
+2. 绝不要在当前容器里执行宿主机级别的 OpenClaw 配置命令。
+3. 一旦确认是宿主机配置问题或企业微信侧未开通问题，就停止重复探索，直接给出明确结论。

package/skills/wecom-schedule/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: wecom-schedule
+description: 企业微信日程管理技能。适用于用户对企业微信日程的各类管理需求。当用户需要：(1) 查询指定时间范围内的日程列表或获取日程详细信息（标题、时间、地点、参与者等），(2) 创建新日程并设置提醒、参与人等，(3) 修改已有日程的标题、时间、地点等信息或取消日程，(4) 添加或移除日程参与人，(5) 查询多个成员的闲忙状态并分析共同空闲时段以安排会议时使用此技能。
+metadata:
+  {
+    "openclaw": { "emoji": "📅" },
+  }
+---
+
+# 企业微信日程管理技能
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+> ⚠️ **路径与停止规则**：
+> - 如果要读取本 skill，必须直接使用 `<available_skills>` 或 `skillsSnapshot` 中给出的精确绝对路径。
+> - 不要猜测或改写为 `/data/openclaw/skills/wecom-*`、`/workspace/.openclaw/skills/...`、`/root/.openclaw/workspace-*/.openclaw/skills/...`，也不要用 `exec` + `ls/find` 探路。
+> - 若 `wecom_mcp` 返回 `errcode: 846609` 或 `unsupported mcp biz type`，表示当前 bot 未开通该 category，不是路径、白名单或 sandbox 问题；立即停止继续 `read`、`list`、`find`、memory fallback 探索，直接告知用户对应 category 未开通。
+
+通过 `wecom_mcp call schedule <接口名> '<json入参>'` 与企业微信日程系统交互。
+
+## 注意事项
+
+- 日程列表查询仅支持**当日前后 30 天**，时间格式 `YYYY-MM-DD` 或 `YYYY-MM-DD HH:MM:SS`
+- 涉及参与者 userid 时，需先使用 **wecom-contact-lookup** 技能获取；存在同名时展示候选让用户选择（禁止暴露 userid）
+- 创建/修改/取消前，先确认目标日程和参与者信息
+- `errcode != 0` 时展示错误信息；返回的 `start_time`/`end_time` 为 Unix 时间戳（秒），需转为可读格式
+- **注意时间格式转换**：接口入参使用字符串格式（如 `YYYY-MM-DD HH:MM:SS`），但返回值多为 Unix 时间戳，使用时需进行格式转换
+
+---
+
+## 接口列表
+
+### get_schedule_list_by_range — 查询日程 ID 列表
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule get_schedule_list_by_range '{"start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS"}'`
+
+返回 `schedule_id_list` 数组。仅支持当日前后 30 天。
+
+### get_schedule_detail — 获取日程详情
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule get_schedule_detail '{"schedule_id_list": ["SCHEDULE_ID_1", "SCHEDULE_ID_2"]}'`
+
+支持 1~50 个 ID，返回日程标题、时间、地点、参与者等。参见 [API 详情](references/api-get-schedule-detail.md)。
+
+### create_schedule — 创建日程
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule create_schedule '{"schedule": {"start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS", "summary": "日程标题", "attendees": [{"userid": "USER_ID"}], "reminders": {"is_remind": 1, "remind_before_event_secs": 3600, "timezone": 8}}}'`
+
+参见 [API 详情](references/api-create-schedule.md) | [reminders 字段](references/ref-reminders.md)。
+
+### update_schedule — 修改日程
+
+只需传入需修改的字段，未传字段保持不变。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule update_schedule '{"schedule": {"schedule_id": "SCHEDULE_ID", "summary": "更新后的标题"}}'`
+
+参见 [API 详情](references/api-update-schedule.md)。
+
+### cancel_schedule — 取消日程
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule cancel_schedule '{"schedule_id": "SCHEDULE_ID"}'`
+
+### add_schedule_attendees / del_schedule_attendees — 管理参与人
+
+- 添加参与人：使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule add_schedule_attendees '{"schedule_id": "SCHEDULE_ID", "attendees": [{"userid": "USER_ID"}]}'`
+- 移除参与人：使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule del_schedule_attendees '{"schedule_id": "SCHEDULE_ID", "attendees": [{"userid": "USER_ID"}]}'`
+
+### check_availablity — 查询闲忙
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule check_availablity '{"check_user_list": ["USER_ID_1", "USER_ID_2"], "start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS"}'`
+
+支持 1~10 个用户，返回各用户的忙碌时段列表。参见 [API 详情](references/api-check-availability.md)。
+
+---
+
+## 典型工作流
+
+### 查询日程
+
+**经典 query 示例：**
+- "我今天有哪些日程？"
+- "帮我看看这周三下午有没有会议"
+- "明天的日程安排是什么？"
+- "查一下最近有没有关于项目评审的日程"
+- "我下周一到周五的日程都有哪些？"
+
+**流程：**
+1. 根据用户意图计算时间范围（如"今天"→当日 00:00:00 至 23:59:59，"这周"→本周一至周日）
+2. 调用 `get_schedule_list_by_range` 获取日程 ID 列表
+3. 调用 `get_schedule_detail` 批量获取详情，将 Unix 时间戳转为可读时间
+4. 若用户提到关键词（如"项目评审"），在 `summary` 中匹配筛选；未找到则逐步扩大范围至前后 30 天上限
+5. 展示日程列表时包含标题、时间、地点、参与者等关键信息，方便用户快速了解
+
+### 创建日程
+
+**经典 query 示例：**
+- "帮我创建一个明天下午 2 点到 3 点的会议，标题叫需求评审"
+- "安排一个周五全天的团建活动"
+- "创建日程：后天上午 10 点和张三、李四开产品方案讨论会，地点在 3 楼会议室"
+- "帮我建个日程，下周一 14:00-15:00，提前 15 分钟提醒"
+- "约一个明天上午的日程，邀请王伟参加"
+
+**流程：**
+1. 解析用户意图，提取时间、标题、地点、参与人、提醒设置等信息
+2. 若涉及参与人，先通过 **wecom-contact-lookup** 查询 userid；存在同名时展示候选让用户选择
+3. 若用户未指定提醒，默认设置提前 15 分钟提醒（`remind_before_event_secs: 900`）
+4. 若用户说"全天"，设置 `is_whole_day: 1`，时间设为当天 00:00:00 至 23:59:59
+5. 向用户确认日程信息（标题、时间、地点、参与人等）后调用 `create_schedule`
+
+### 修改日程
+
+**经典 query 示例：**
+- "把明天的需求评审改到后天下午 3 点"
+- "帮我修改下今天下午的会议标题，改成技术方案评审"
+- "我今天 14 点的日程地点改成线上腾讯会议"
+- "把周五的团建活动推迟一个小时"
+- "帮我给明天的周会加个描述：讨论 Q2 规划"
+
+**流程：**
+1. 先通过查询工作流定位目标日程（根据用户提到的时间、标题等关键词匹配）
+2. 若匹配到多个日程，展示候选列表让用户确认
+3. 向用户确认要修改的字段和目标值
+4. 调用 `update_schedule`，只传入需修改的字段
+
+### 取消日程
+
+**经典 query 示例：**
+- "取消明天下午的需求评审"
+- "帮我把周五的团建日程删掉"
+- "我不想开今天 15 点的会了，帮我取消"
+
+**流程：**
+1. 先通过查询工作流定位目标日程
+2. 向用户确认取消的日程信息（标题、时间等），避免误操作
+3. 确认后调用 `cancel_schedule`
+
+### 管理参与人
+
+**经典 query 示例：**
+- "把张三加到明天的需求评审会议里"
+- "帮我把李四从周五的日程里移除"
+- "明天下午的会议再邀请一下王伟和赵敏"
+- "把我后天那个技术分享的参与人里去掉刘强"
+
+**流程：**
+1. 通过 **wecom-contact-lookup** 获取目标人员 userid；存在同名时展示候选让用户选择
+2. 通过查询工作流定位目标日程
+3. 调用 `add_schedule_attendees` 或 `del_schedule_attendees` 完成添加/移除
+
+### 查询闲忙并安排会议
+
+**经典 query 示例：**
+- "帮我看看张三和李四明天下午有没有空"
+- "查一下我和王伟这周的空闲时间，想约个会"
+- "我想跟产品组的小明、小红开个会，看看大家什么时候有空"
+- "找一个明天下午大家都有空的时段，安排一个 1 小时的会议"
+
+**流程：**
+1. 通过 **wecom-contact-lookup** 获取相关人员 userid
+2. 调用 `check_availablity` 查询指定时间范围内各用户的忙碌时段
+3. 分析所有用户的忙碌时段，计算出共同空闲时段并推荐给用户
+4. 用户确认时段后，调用 `create_schedule` 创建会议并自动添加参与人

package/skills/wecom-schedule/references/api-check-availability.md

@@ -0,0 +1,56 @@
+# check_availablity API
+
+查询指定用户在某时间范围内的忙碌时段。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `check_user_list` | array | ✅ | 用户 ID 列表，1~10 个 |
+| `start_time` | string | ✅ | 查询开始时间 |
+| `end_time` | string | ✅ | 查询结束时间 |
+
+## 请求示例
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call schedule check_availablity '{"check_user_list": ["USER_ID_1", "USER_ID_2"], "start_time": "YYYY-MM-DD HH:MM:SS", "end_time": "YYYY-MM-DD HH:MM:SS"}'`
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `user_busy_list` | array | 用户忙碌时段列表 |
+
+### user_busy_list[] 数组中每项字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `userid` | string | 用户 ID |
+| `busy_slots` | array | 忙碌时段列表 |
+| `busy_slots[].start_time` | string | 忙碌时段开始时间 |
+| `busy_slots[].end_time` | string | 忙碌时段结束时间 |
+| `busy_slots[].schedule_id` | string | 关联的日程 ID |
+| `busy_slots[].subject` | string | 日程标题 |
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "user_busy_list": [
+        {
+            "userid": "USER_ID",
+            "busy_slots": [
+                {
+                    "start_time": "YYYY-MM-DD HH:MM:SS",
+                    "end_time": "YYYY-MM-DD HH:MM:SS",
+                    "schedule_id": "SCHEDULE_ID",
+                    "subject": "日程标题"
+                }
+            ]
+        }
+    ]
+}
+```