@wps365/openclaw-wpsxiezuo 1.6.0

package/skills/wps-drive/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: wps-drive
+description: |
+  WPS365 云文档（Drive）。用户要查询盘列表、新建文件（夹）、抽取文档内容、获取文件信息或搜索文件时，必须使用开放接口。
+  必须调用 wps_drive_list_drives / wps_drive_create_file / wps_drive_extract_file_content / wps_drive_get_file_meta / wps_drive_search_files，禁止用本地缓存结果冒充已同步到 WPS 云文档。安装本插件后随 skills 目录一并加载。
+---
+
+# WPS365 云文档：盘列表、新建文件（夹）、内容抽取、文件信息与文件搜索
+
+## 执行前必读
+
+- **`wps_drive_list_drives`**：开放平台「**获取盘列表**」—— **`GET /v7/drives`**。
+- **`wps_drive_create_file`**：开放平台「**新建文件（夹）**」—— **`POST /v7/drives/{drive_id}/files/{parent_id}/create`**。
+- **`wps_drive_extract_file_content`**：开放平台「**文档内容抽取**」—— **`GET /v7/drives/{drive_id}/files/{file_id}/content`**。
+- **`wps_drive_get_file_meta`**：开放平台「**获取文件信息**」—— **`GET /v7/files/{file_id}/meta`**。
+- **`wps_drive_search_files`**：开放平台「**文件搜索**」—— **`GET /v7/files/search`**。
+- **Delegated 权限**：盘列表使用 **`kso.drive.readwrite`**；新建文件（夹）使用 **`kso.file.readwrite`**；文档内容抽取与获取文件信息使用 **`kso.file.read`**；文件搜索使用 **`kso.file.search`**（或开放平台等价用户授权）。未授权时插件会发授权卡片；`wps_user_id` 使用 **SenderId**。
+- **盘列表必填**：`wps_user_id`、`allotee_type`（`user` | `group` | `app`）；`allotee_id` 为可选（三种类型都可传，不传走接口默认归属）。
+- **新建文件（夹）必填**：`wps_user_id`、`drive_id`、`parent_id`、`file_type`、`name`。
+- **新建 file_type**：`folder` | `file` | `shortcut`；当 `file_type=shortcut` 时，`file_id` 必填。
+- **内容抽取必填**：`wps_user_id`、`drive_id`、`file_id`；可选：`format`（`kdc` | `plain` | `markdown`）、`include_elements`（`para`/`table`/`component`/`textbox`/`all`）、`mode`（`sync`/`async`/`auto`）、`task_id`。
+- **获取文件信息必填**：`wps_user_id`、`file_id`；可选：`with_permission`、`with_ext_attrs`、`with_drive`。
+- **文件搜索必填**：`wps_user_id`、`type`（`file_name` | `content` | `all`）；`page_size` 工具默认补 50（最大 500）。支持文档中查询条件透传，如 `file_type`、`drive_ids`、`time_type`、`with_total`、`order/order_by`、`scope` 等。
+- **重名策略**：`on_name_conflict` 支持 `fail` | `rename` | `overwrite` | `replace`。
+- **可选请求头**：`x_kso_id_type`（`internal` | `external`），映射到 `X-Kso-Id-Type`。
+
+## 快速索引：意图→工具
+
+| 意图 | 工具 | 必填参数 |
+|------|------|----------|
+| 获取用户/群组/应用盘列表 | `wps_drive_list_drives` | `wps_user_id`, `allotee_type` |
+| 新建文件（夹）/快捷方式 | `wps_drive_create_file` | `wps_user_id`, `drive_id`, `parent_id`, `file_type`, `name` |
+| 文档内容抽取 | `wps_drive_extract_file_content` | `wps_user_id`, `drive_id`, `file_id` |
+| 获取文件信息 | `wps_drive_get_file_meta` | `wps_user_id`, `file_id` |
+| 文件搜索 | `wps_drive_search_files` | `wps_user_id`, `type` |
+
+## 核心约束
+
+1. 必须通过 `wps_drive_*` 工具调用开放平台，不能伪造云文档结果。
+2. `wps_user_id` 必须来自当前消息 `SenderId`，不要为此调用 `wps_user_search`。
+3. `file_type=shortcut` 时必须传 `file_id`；盘列表使用 `allotee_type/allotee_id` 参数名；内容抽取场景按需设置 `mode` 与 `task_id`；文件信息可选开关 `with_permission/with_ext_attrs/with_drive`；文件搜索需传合法 `type`。
+
+## 调用示例
+
+```json
+{
+  "wps_user_id": "<SenderId>",
+  "drive_id": "drive_xxx",
+  "parent_id": "0",
+  "file_type": "folder",
+  "name": "项目资料",
+  "on_name_conflict": "rename",
+  "x_kso_id_type": "external"
+}
+```
+
+## 常见错误
+
+| 现象 | 处理 |
+|------|------|
+| `needsAuth: true` | 引导用户完成 OAuth 后重试 |
+| `file_id is required when file_type is shortcut` | 传入快捷方式目标文件 ID |
+| `allotee_type is required and must be user, group, or app` | 校验并传入合法归属类型；可选传 `allotee_id` 精确指定归属 |
+| `mode must be one of: sync, async, auto` | 修正 `mode` 参数为文档枚举值 |
+| `file_id is required and must be a non-empty string` | 传入有效文件 ID |
+| `type must be one of: file_name, content, all` | 修正文件搜索 `type` 参数为文档枚举值 |
+| 403 | 开放平台未开通云文档 delegated 权限 |
+
+## 工具覆盖
+
+- `wps_drive_list_drives` — 获取盘列表（`GET /v7/drives`）
+- `wps_drive_create_file` — 新建文件（夹）（`POST /v7/drives/{drive_id}/files/{parent_id}/create`）
+- `wps_drive_extract_file_content` — 文档内容抽取（`GET /v7/drives/{drive_id}/files/{file_id}/content`）
+- `wps_drive_get_file_meta` — 获取文件信息（`GET /v7/files/{file_id}/meta`）
+- `wps_drive_search_files` — 文件搜索（`GET /v7/files/search`）
+
+## 安装说明
+
+随插件 **`skills.directory`** 安装；**`tools.allow`** 与 **`mcp.toolAllowlist`** 须包含 `wps_drive_list_drives`、`wps_drive_create_file`、`wps_drive_extract_file_content`、`wps_drive_get_file_meta`、`wps_drive_search_files`。

package/skills/wps-im-read/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: wps-im-read
+description: |
+  WPS IM 消息读取与检索。在需要拉会话历史、按时间窗口翻消息、根据 message_id 查看单条内容时使用。
+---
+
+# WPS IM：读取历史与单条消息
+
+## 执行前必读
+
+- **时间范围**：`start_time` / `end_time` 参数使用 **秒级 Unix 时间戳**，工具内部自动转换为毫秒发给 API。
+- **分页**：使用返回的 **`next_page_token`** 继续拉取；**`page_size`** 一般 1–100。
+- **发送方类型**：消息体里的 `sender.type` 常见为 `user`（真人）或 `sp`（应用/机器人），用于区分人与 bot。
+- **消息位置**：`position` 字段严格递增，可用于增量同步。
+
+## 快速索引：意图→工具
+
+| 意图 | 工具 | 必填参数 |
+|------|------|----------|
+| 分页拉某会话历史消息 | `wps_message_list` | `chat_id` |
+| 按消息 ID 取单条详情 | `wps_message_get` | `chat_id`, `message_id` |
+
+常用可选参数（list）：`page_size`, `page_token`, `start_time`, `end_time`。
+
+## 核心约束
+
+- **`wps_message_list`**
+  - 必须已知 `chat_id`（群会话或 P2P 会话 id）
+  - `start_time` / `end_time`：秒级 Unix 时间戳，用于过滤时间范围
+  - 返回的 `next_page_token` 为空则表示没有下一页
+- **`wps_message_get`**
+  - `chat_id` + `message_id` 唯一确定一条消息
+  - 用于引用上下文、审计或回复前的内容确认
+
+## 使用场景示例
+
+**1）拉取最近一页历史**
+
+```json
+{
+  "chat_id": "CHAT_ID",
+  "page_size": 50
+}
+```
+
+**2）按时间窗口过滤（注意传秒级时间戳）**
+
+```json
+{
+  "chat_id": "CHAT_ID",
+  "start_time": 1713206400,
+  "end_time": 1713292800,
+  "page_size": 100
+}
+```
+
+**3）翻页**
+
+```json
+{
+  "chat_id": "CHAT_ID",
+  "page_size": 50,
+  "page_token": "TOKEN_上一页返回"
+}
+```
+
+**4）获取单条消息**
+
+```json
+{
+  "chat_id": "CHAT_ID",
+  "message_id": "MSG_ID"
+}
+```
+
+## 常见错误与排查
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| 时间过滤无结果 | 误把毫秒当秒传入，或起止时间反了 | 传秒级时间戳，确认 start < end |
+| 404 / chat 不存在 | `chat_id` 错误或已解散 | 用 `wps_chat_get` 校验会话状态 |
+| 取单条失败 | `message_id` 不属于该 `chat_id` | 核对 id 是否同一会话上下文 |
+| 返回为空 | 指定时间范围内无消息 | 扩大时间范围或去掉时间过滤 |
+
+## 工具覆盖
+
+- `wps_message_list` — 分页拉取会话历史
+- `wps_message_get` — 查询单条消息详情

package/skills/wps-im-send/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: wps-im-send
+description: |
+  WPS IM 消息发送与回复。在用户要求发消息、私聊、群聊、@某人、引用回复时使用。
+---
+
+# WPS IM：发送与回复
+
+## 执行前必读
+
+- **`receiver_type` 为 `user` 时**：按用户 ID 路由，走单聊（P2P），**不必先查 `chat_id`** 即可发 DM。
+- **`receiver_type` 为 `chat` 时**：向群/会话发消息，`receiver_id` 传 **群 `chat_id`**。
+- **回复**：仅支持 **text / rich_text / image**；需同时提供 **`chat_id`** 与被回复的 **`message_id`**。
+- **content 格式**：`content` 参数是 **JSON 字符串**，结构随 `msg_type` 变化。
+- **@人语法**：文本里写 `<at id="N">展示名</at>`（N 从 1 递增），并在 `mentions` 数组中提供对应的用户信息。
+- **长度**：单条消息 content JSON **≤ 5000 字符**。
+- **媒体**：图片等通过 **storage_key** 引用，不可把二进制内联进 JSON。
+
+## "给 xx 发消息"路由规则（必须遵守）
+
+当用户说"给 xx 发消息"时，"xx"可能是用户名，也可能是群聊名。**必须双查**：
+
+### 执行步骤
+
+1. **并行调用**两个搜索工具：
+   - `wps_user_search(keyword="xx")` — 查企业用户
+   - `wps_chat_find_by_name(keyword="xx")` — 查群聊/会话
+2. **合并结果**，按以下规则处理：
+
+| 用户匹配 | 群聊匹配 | 处理方式 |
+|----------|----------|----------|
+| 1 个 | 0 个 | 直接用 `wps_message_send(receiver_type=user)` 发 P2P |
+| 0 个 | 1 个 | 直接用 `wps_message_send(receiver_type=chat)` 发群聊 |
+| 1+ 个 | 1+ 个 | 展示全部候选列表（标注"用户"或"群聊"类型、群主名），让用户选择 |
+| 1 个用户 | 1+ 个群 | 展示全部候选，不自动选择 |
+| 1+ 个用户 | 1 个群 | 展示全部候选，不自动选择 |
+| 0 个 | 0 个 | 告知用户未找到匹配，建议换关键词 |
+
+### 禁止行为
+
+- **禁止**只查用户不查群聊，或只查群聊不查用户
+- **禁止**在两者都有匹配时自动选择一个，必须让用户确认
+- **禁止**不调搜索工具就声称"找不到"
+- **禁止**使用 `sessions_send` 替代 `wps_message_send`
+- **禁止** P2P 发送失败后自动降级为群聊 @ 或群聊发送。必须告知用户失败原因并等待指示
+- **禁止**把发消息人（用户自己）的 ID 当作 Bot ID 使用
+
+### P2P 失败处理规则
+
+当 `wps_message_send(receiver_type=user)` 返回 `no valid receiver` 时：
+1. **立即停止重试**——不要换格式（rich_text、plain 等）重试，因为问题不在消息格式
+2. **不得自动降级**——不要擅自改为群聊发送或群里 @，即使目标用户在某个群里
+3. **告知用户真实原因**："`no valid receiver` 表示该用户不在应用可用范围内，或应用缺少向该用户发送 P2P 消息的权限。请在 WPS 开放平台确认该用户已加入应用可用范围，并确认应用已配置消息发送权限。"
+4. **提供备选方案**：告知用户可以选择创建群聊来沟通，例如："是否要创建一个群聊，将你和目标用户拉入？"
+5. **等待用户确认**——用户明确同意后才能执行 `wps_chat_create(type=group)`，Agent 不得自动创建
+6. **禁止以应用身份创建 P2P**——App Token 场景下应用没有 user_id，不能作为 P2P 会话的一方，禁止尝试 `wps_chat_create(type=p2p)` 作为降级手段
+
+## 快速索引：意图→工具
+
+| 意图 | 工具 | 必填参数 |
+|------|------|----------|
+| 发新消息（常规场景，推荐） | `message` | `action=send`, `to`, `message` |
+| 发新消息（精细控制 content） | `wps_message_send` | `receiver_type`, `receiver_id`, `msg_type`, `content` |
+| 回复某条消息 | `wps_message_reply` | `chat_id`, `message_id`, `msg_type`, `content` |
+| 按名称查找会话 | `wps_chat_find_by_name` | `keyword` |
+| 按关键字查找用户 | `wps_user_search` | `keyword` |
+
+## `message` 工具 vs `wps_message_send`
+
+| 维度 | `message` | `wps_message_send` |
+|------|-----------|-------------------|
+| 来源 | Openclaw 内置通用工具 | WPS 插件注册的底层工具 |
+| 参数格式 | `action=send, to="chat:<id>"` | `receiver_type, receiver_id, msg_type, content` (JSON string) |
+| 推荐场景 | **常规文本发送**（简洁、首选） | 需要精细控制 content JSON 结构（富文本、@人、图片等） |
+
+**常规发消息优先使用 `message`**；仅在需要 `mentions`、富文本、图片等高级 content 结构时使用 `wps_message_send`。
+
+## 核心约束
+
+- **message（推荐）**
+  - `action`：`send`
+  - `to`：`user:<user_id>`（私聊）或 `chat:<chat_id>`（群聊）
+  - `message`：消息文本
+- **发送（`wps_message_send`）**
+  - `receiver_type`：`user`（私聊）或 `chat`（群聊）
+  - `receiver_id`：用户 ID 或会话 ID
+  - `msg_type`：`text` / `rich_text` / `image` / `file`
+  - `content`：JSON 字符串，格式示例见下方
+  - `mentions`：可选，@人列表数组
+- **回复（`wps_message_reply`）**
+  - 仅 **text / rich_text / image** 三类
+  - `content` 为纯文本时自动包装为 `{ text: { content, type: "plain" } }`
+  - `content` 为 JSON 时按原样使用
+
+## 使用场景示例
+
+**1）用户说"给研发群发消息"（推荐流程）**
+
+```
+Step 1（并行）:
+  wps_user_search(keyword="研发群") → 0 结果
+  wps_chat_find_by_name(keyword="研发群") → { found: true, match: { chat_id: "xxx", name: "研发群" } }
+
+Step 2: 只有群聊匹配 → message(action=send, to="chat:xxx", message="明天下午三点开会")
+```
+
+**2）用户说"给张三发消息"（双查路由）**
+
+```
+Step 1（并行）:
+  wps_user_search(keyword="张三") → 1 个用户 { user_id: "abc" }
+  wps_chat_find_by_name(keyword="张三") → 1 个群 { chat_id: "def", name: "张三的项目群" }
+
+Step 2: 两者都有 → 展示候选列表：
+  "找到以下匹配，请选择发送目标：
+   1. 👤 用户：张三 (user_id: abc)
+   2. 💬 群聊：张三的项目群 (群主: xxx)"
+```
+
+**3）私聊用户（P2P）**
+
+```json
+{
+  "receiver_type": "user",
+  "receiver_id": "USER_ID",
+  "msg_type": "text",
+  "content": "{\"text\":{\"content\":\"你好，收到请回复。\",\"type\":\"plain\"}}"
+}
+```
+
+**4）群发消息**
+
+```json
+{
+  "receiver_type": "chat",
+  "receiver_id": "CHAT_ID",
+  "msg_type": "text",
+  "content": "{\"text\":{\"content\":\"各位下午三点例会。\",\"type\":\"plain\"}}"
+}
+```
+
+**5）文本中带 @**
+
+```json
+{
+  "receiver_type": "chat",
+  "receiver_id": "CHAT_ID",
+  "msg_type": "text",
+  "content": "{\"text\":{\"content\":\"<at id=\\\"1\\\">张三</at> 请确认排期。\",\"type\":\"plain\"}}",
+  "mentions": [{"id": "1", "type": "user", "identity": {"id": "USER_ID_张三", "company_id": "COMPANY_ID", "type": "user"}}]
+}
+```
+
+**6）回复指定消息**
+
+```json
+{
+  "chat_id": "CHAT_ID",
+  "message_id": "MSG_ID",
+  "msg_type": "text",
+  "content": "收到，我来跟进。"
+}
+```
+
+## 常见错误与排查
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| no valid receiver | 目标用户不在应用可用范围，或应用缺少 P2P 消息权限 | 告知用户检查平台权限和可用范围，可提议创建群聊（需用户确认） |
+| 403 / 无权限发群消息 | 应用未入群或未开通应用权限 | 先用 `wps_chat_is_member` 确认应用在群内 |
+| @ 不生效 | 正文有 `<at>` 但 `mentions` 缺失或不匹配 | 补齐 mentions 数组，id 与正文对应 |
+| 消息过长被拒 | 超过 5000 字符 | 拆成多条或压缩正文 |
+| content 解析失败 | JSON 格式不正确 | 确认 content 是有效 JSON 字符串 |
+| 图片发不出 | 未走 storage_key 上传链路 | 先用 `wps_media_upload_base64` 拿 `storage_key`（含 checksum）；低阶 `wps_media_upload` 需自算 SHA256 hex 传入 `checksum` |
+| invalid chatId / deMixValue | `receiver_id` 用了 SessionKey `:bot:` 段 | 改用 RawBody 的 `chatId` 或用户 id，见 `wps-media` / 渠道规则 |
+
+## 工具覆盖
+
+- `message` — Openclaw 通用消息工具（推荐，常规文本发送）
+- `wps_message_send` — 发送新消息（精细控制 content）
+- `wps_message_reply` — 回复已有消息
+- `wps_chat_find_by_name` — 按名称搜索会话
+- `wps_user_search` — 按关键字搜索企业用户

package/skills/wps-media/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: wps-media
+description: |
+  WPS 媒体完整流转：接收图片/文件 → 处理 → 上传 → 发送。
+---
+
+# WPS 媒体处理（下载 / 上传 / 发送）
+
+## 入站：收到图片或文件
+
+插件已自动将附件下载到本地临时文件。入站消息 Body 中会包含如下标记：
+
+```
+[已下载图片: /tmp/openclaw-media/xxx.png | photo.png | image/png | 42.6KB]
+```
+
+- **路径是可读的本地文件**。可直接用 `read(/tmp/openclaw-media/xxx.png)` 读取图片内容。
+- 如果是图片，`read` 会返回图片数据；如果当前模型支持视觉（如 qwen-vl），可直接理解图片内容。
+- `RawBody.prefetchedMedia` 中有结构化元信息（storageKey、mimeType、localPath 等）。
+
+## 场景 1：用户要求理解/分析图片
+
+1. 从 Body 中找到 `[已下载图片: <path> | ...]`
+2. 用 `read(<path>)` 读取图片
+3. 根据图片内容回答用户问题
+
+## 场景 2：用户要求把图片发回 / 转发（推荐方式）
+
+直接用 `message` 工具，`media` 参数传入本地路径（省略 `to` 可自动回复当前会话）：
+
+```
+message(action="send", message="为您发回图片", media="<已下载路径>")
+```
+
+如果需要指定发送目标，加上 `to` 参数：`to="user:<SenderId>"` 或 `to="chat:<chatId>"`。
+
+### 引用回复场景
+
+当用户引用了历史消息并要求发回其中的图/文件时：
+- Body 里有 `[用户引用了以下消息]` 和 `[已下载图片/文件: <path> | ...]`
+- 按上述方式用 `message` 工具回复即可
+
+### 备选方式（三步手动）
+
+如果 `message` 工具不可用，可手动执行：
+1. `read(<path>)` → 得到 base64
+2. `wps_media_upload_base64(file_name, file_type, base64)` → 得到 `storage_key`
+3. `wps_message_send(receiver_type, receiver_id, msg_type="image"/"file", content=<JSON>)`
+
+**禁止**把路径当文本回复给用户。
+
+## 场景 2b：用户引用了云文件要求发回
+
+WPS 云文件（type=cloud）没有 storage_key，无法下载到本地。Body 中会显示：
+
+```
+[引用云文件: 未命名云文件]
+链接: https://www.kdocs.cn/l/xxx
+文件ID: xxx
+```
+
+要发回云文件，使用 `wps_message_send` 工具，用原始 cloud 结构转发：
+
+```
+wps_message_send(receiver_type="user", receiver_id="<SenderId>", msg_type="file", content='{"file":{"type":"cloud","cloud":{"id":"<fileId>","link_id":"<linkId>","link_url":"<linkUrl>"}}}')
+```
+
+Body 中的 `[云文件回发指令]` 段落会提供完整的调用命令，直接复制使用即可。
+
+**禁止**尝试用 `message` 工具的 `media` 参数发送云文件（没有本地路径可用）。
+
+## 场景 3：AI 生成了新图片 / Excel 等文件需要发送
+
+1. 将生成的文件转为 base64（与 `file_type` MIME 一致）
+2. 调用 `wps_media_upload_base64(file_name, file_type, base64)` → 得到 `storage_key`
+3. 与场景 2 相同：用 RawBody 的 `chatId` / 用户 id 填 `receiver_type` + `receiver_id`，图片用 `msg_type="image"`；表格/文档用 `msg_type="file"` 且 `content` 结构需符合 WPS 对文件消息的 JSON 定义
+
+## 场景 4：需要额外下载（非入站预取的附件）
+
+如果需要手动下载某个 storage_key 对应的资源：
+
+1. 调用 `wps_media_fetch_base64(chat_id, message_id, storage_key)` → 得到 base64 + mime_type
+2. 或调用 `wps_media_download(chat_id, message_id, storage_key)` → 得到预签名 URL
+
+## 常见错误
+
+| 错误 | 原因 |
+|------|------|
+| `read` + `xiezuo....png` → ENOENT | 把 WPS 显示名当成了 workspace 本地路径，正确做法是读 Body 中的 `/tmp/openclaw-media/...` 路径 |
+| 只传 `storage_key` 不传 chat/message | API 需要三者唯一定位资源 |
+| `exec(curl ...)` 被拦截 | 运行时禁用 elevated 命令，直接用内置工具 |
+| upload 只拿到 URL 不上传 | 用 `wps_media_upload_base64` 替代旧的 `wps_media_upload`，前者自动完成全部上传 |
+| `checksum 参数缺失` | 使用 `wps_media_upload_base64`（自动计算 SHA256 hex）；若用 `wps_media_upload` 须传入与文件一致的 `checksum` |
+| `invalid chatId` / `deMixValue` | `receiver_id` 误用了 `:bot:` 后 id；改用 RawBody 的 `chatId` 或用户 id |
+
+## 禁止操作
+
+- 不要对附件「显示文件名」直接调用 `read`
+- 不要用 `exec(curl)` 下载或上传
+- 不要引导用户手动执行命令
+- 不要把大段 base64 直接放在回复消息中

package/skills/wps-message-handler.md

@@ -0,0 +1,48 @@
+---
+name: wps-message-handler
+description: 处理 WPS 开放平台消息事件
+version: 1.0.0
+---
+
+# WPS Xiezuo 消息处理 Skill
+
+## 功能说明
+
+本 Skill 负责处理来自 WPS 开放平台的消息事件，包括：
+
+- 接收用户消息
+- 解析消息内容
+- 调用 AI 分析
+- 回复消息到 WPS Xiezuo 聊天
+
+## 触发条件
+
+当收到 WPS 开放平台的 `message.receive` 事件时触发。
+
+## 处理流程
+
+1. 验证 Webhook 签名
+2. 提取消息内容和上下文
+3. 映射到 Openclaw session
+4. 调用 AI 进行分析和响应
+5. 通过 WPS API 发送回复
+
+## 配置参数
+
+- `maxRetries`: 消息发送失败重试次数（默认: 3）
+- `timeout`: 消息处理超时时间（默认: 30s）
+- `enableMarkdown`: 是否启用 Markdown 格式（默认: true）
+
+## 示例
+
+```json
+{
+  "event": "message.receive",
+  "data": {
+    "conversationId": "conv_123",
+    "userId": "user_456",
+    "content": "帮我分析这个文档",
+    "timestamp": 1234567890
+  }
+}
+```

package/skills/wps-todo/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: wps-todo
+description: |
+  WPS365 个人待办（Todo）。用户要在 WPS 待办中创建个人任务时使用开放接口；须用户 OAuth（待办 delegated 权限）。
+  必须调用 wps_todo_create_personal_task / wps_todo_list_personal_tasks / wps_todo_get_personal_task / wps_todo_update_personal_task / wps_todo_update_personal_task_status，禁止仅用本地备忘录冒充已同步到 WPS。安装本插件后随 skills 目录一并加载。
+---
+
+# WPS365 个人待办：创建、列表、详情与更新
+
+## 执行前必读
+
+- **`wps_todo_create_personal_task`**：开放平台「**创建个人待办**」—— **`POST /v7/todo/personal_tasks`**。
+- **`wps_todo_list_personal_tasks`**：开放平台「**获取个人待办列表**」—— **`POST /v7/todo/personal_tasks/batch_get`**。筛选与分页均为可选；**`page_size`** 默认 20、最大 50；**`page_token`** 用于翻页（上一页 `data` 中分页字段，以实际返回名为准，如 `next_offset` 等）。**`keyword`** 最多 50 字；**`created_time_*` / `due_time_*`** 为**毫秒**时间戳范围。
+- **`wps_todo_get_personal_task`**：开放平台「**获取个人待办详情**」—— **`GET /v7/todo/personal_tasks/{task_id}`**。必填 **`task_id`**（通常来自列表 **`tasks[].id`** 或创建返回的 **`task_id`**）。
+- **`wps_todo_update_personal_task`**：开放平台「**更新个人待办**」—— **`POST /v7/todo/personal_tasks/{task_id}/update`**。文档要求 **`kso.task.readwrite`**。请求体字段均可选，但**至少改一项**：**`title_subject` / `title_prefix`**、**`description`**、**`due_time_ms`**、**`ext_attrs`**、**`notify_config_json`**（JSON 字符串）。响应多为 **`code` / `msg`**。
+- **`wps_todo_update_personal_task_status`**：开放平台「**更新个人待办状态**」—— **`POST /v7/todo/personal_tasks/{task_id}/update_status`**。请求体仅为 JSON **`{ "action": "<枚举>" }`**。必填：`task_id`、`action`；`action` 枚举（与官方一致）：`finish`（标为完成）、`unfinish`（标为未完成）、`finish_all` / `unfinish_all`（**仅创建者**，全部标完成/未完成）。
+- **Delegated 权限**：文档为 **`kso.task.readwrite`** / **`kso.task.read`**（或开放平台所列等价用户授权）。未授权时插件会发授权卡片；`wps_user_id` 使用 **SenderId**，不要为待办去调 `wps_user_search`。
+- **请求体**：必填只有 **`title`**（对象）。插件参数 **`title_subject`** → `title.subject`，可选 **`title_prefix`** → `title.prefix`。可选 **`description`**、**`due_time_ms`**（截止时间 **毫秒** Unix 时间戳）、**`status`**（`todo` | `finish`）、**`executors`**（执行人用户 ID，最多 100）。
+- **响应**：成功时 **`data.task_id`** 为新待办 ID。
+- **HTTP**：与日程类工具相同，使用用户 **`access_token`** + **`Authorization: Bearer`**（插件内 `UserAuthProvider`）。可选 **`x_kso_id_type`**（`internal` | `external`）映射 **`X-Kso-Id-Type`**。
+
+## 快速索引：意图→工具
+
+| 意图 | 工具 | 必填参数 |
+|------|------|----------|
+| 创建个人待办 / 任务 | `wps_todo_create_personal_task` | `wps_user_id`, **`title_subject`** |
+| 列举个人待办 | `wps_todo_list_personal_tasks` | **`wps_user_id`** |
+| **单条**待办详情 | `wps_todo_get_personal_task` | **`wps_user_id`**, **`task_id`** |
+| **更新**待办（局部字段） | `wps_todo_update_personal_task` | **`wps_user_id`**, **`task_id`** + 至少一项变更字段 |
+| **更新待办状态** | `wps_todo_update_personal_task_status` | **`wps_user_id`**, **`task_id`**, **`action`** |
+
+## 核心约束
+
+1. **创建 / 列表 / 详情 / 更新 / 更新状态**分别使用上表工具，禁止假装已在 WPS 同步。
+2. **`wps_user_id`**：当前对话 **SenderId**。
+3. **`due_time_ms`** 为 **毫秒**；与日程答复里的 `which_day_time` 同为毫秒，勿与 Unix **秒**混淆。
+
+## 调用示例
+
+```json
+{
+  "wps_user_id": "<SenderId>",
+  "title_subject": "提交周报",
+  "due_time_ms": 1714377600000
+}
+```
+
+## 常见错误
+
+| 现象 | 处理 |
+|------|------|
+| `needsAuth: true` | 引导用户完成 OAuth 后再试 |
+| 403 | 开放平台未开通待办 delegated 权限 |
+
+## 工具覆盖
+
+- `wps_todo_create_personal_task` — 创建（`POST /v7/todo/personal_tasks`）
+- `wps_todo_list_personal_tasks` — 列表（`POST /v7/todo/personal_tasks/batch_get`）
+- `wps_todo_get_personal_task` — 详情（`GET /v7/todo/personal_tasks/{task_id}`）
+- `wps_todo_update_personal_task` — 更新（`POST /v7/todo/personal_tasks/{task_id}/update`）
+- `wps_todo_update_personal_task_status` — 状态更新（`POST /v7/todo/personal_tasks/{task_id}/update_status`）
+
+## 安装说明
+
+随插件 **`skills.directory`** 安装；**`tools.allow`** 须包含上述工具；**`mcp.toolAllowlist`** 默认已含（见 `src/core/config.ts`）。

package/skills/wps-user/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: wps-user
+description: |
+  WPS 企业用户查询。在需要确认当前身份、按关键字找人、按邮箱/手机精确定位用户时使用。
+---
+
+# WPS 用户：查询与搜索
+
+## 执行前必读
+
+- **`wps_user_get`**：获取当前 access_token 对应的应用/用户身份信息（调用 `GET /v7/users/current`），返回 `id`、`user_name`、`avatar`、`company_id`。
+- **`wps_user_search`**：按关键字搜索企业内活跃用户，搜索范围固定为 `user_name`、`email`、`phone`，状态限定 `active`。
+- **标识统一**：接口返回的 `user.id` 是后续所有 IM / 日历等 API 的主键，发消息的 `receiver_id`、群成员的 `member_ids`、mentions 里的用户 ID 均使用此值。
+
+## 快速索引：意图→工具
+
+| 意图 | 工具 | 必填参数 |
+|------|------|----------|
+| 查看当前应用/用户身份 | `wps_user_get` | 无 |
+| 关键字找人（姓名/邮箱/手机） | `wps_user_search` | `keyword` |
+
+## 核心约束
+
+- **`wps_user_get`**
+  - 无参数，返回当前 token 持有者的基本信息
+  - 适用于确认 bot 身份、获取 company_id
+- **`wps_user_search`**
+  - `keyword`：搜索关键词（姓名片段、邮箱、手机号等）
+  - 搜索字段固定：`user_name`、`email`、`phone`
+  - 状态固定：仅搜索 `active` 用户
+  - 搜索范围固定：`company_user`（本企业用户）
+  - `page_size`：**必传**，默认 50，最大 100
+  - 支持 `page_token` 翻页
+
+## 用户搜索交互规则（必须遵守）
+
+### 收到"给 XX 发消息"时的执行链路
+
+1. **先调 `wps_user_search`** 查找目标用户，`keyword` 使用用户提供的姓名/邮箱/手机
+2. 如果返回 **1 个结果**：直接使用该 `user_id` 调用 `wps_message_send`
+3. 如果返回 **多个结果**：展示候选列表（姓名 + 部门），让用户选择
+4. 如果返回 **0 个结果**：
+   - 告知用户"未找到匹配的企业用户"
+   - 建议：换一个关键词重试（如全名、邮箱、手机号）
+   - 建议：如果对方不在本企业通讯录，需要提供其 WPS 用户 ID
+   - **禁止**编造用户 ID 或猜测
+
+### 禁止行为
+
+- **禁止**不调用 `wps_user_search` 就声称"找不到用户"或"工具不可用"
+- **禁止**跳过搜索步骤直接要求用户提供 user_id
+- **禁止**使用 `sessions_send` 替代 `wps_message_send` 给 WPS 用户发消息
+
+## 使用场景示例
+
+**1）查看当前身份**
+
+```json
+{}
+```
+
+**2）按姓名关键字搜用户**
+
+```json
+{
+  "keyword": "张三"
+}
+```
+
+**3）按邮箱精确搜**
+
+```json
+{
+  "keyword": "zhangsan@example.com"
+}
+```
+
+**4）翻页**
+
+```json
+{
+  "keyword": "张",
+  "page_size": 50,
+  "page_token": "TOKEN_上一页返回"
+}
+```
+
+## 常见错误与排查
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| 搜不到人 | 关键词太短或用户不在本企业 | 换关键词；确认搜索范围 |
+| 返回用户不可发消息 | 账号已禁用或离职 | 搜索默认只返回 active 用户，如仍无法发送检查权限 |
+| 分页漏数据 | `page_token` 未正确传递 | 严格使用上一页响应的 `next_page_token` |
+| 权限不足 | 应用未授权 `kso.contact.read` | 在 WPS 开放平台补齐权限 |
+
+## 工具覆盖
+
+- `wps_user_get` — 获取当前身份
+- `wps_user_search` — 按关键字搜索企业用户
+
+## 与日程（wps-calendar）的分工
+
+- **找人 / 身份**：用本 skill 的 `wps_user_get`、`wps_user_search`。
+- **创建日历事件**：用 **`wps_calendar`** skill 的 **`wps_calendar_create`**；**列举逻辑事件**：**`wps_calendar_list_events`**；**单条日程详情**：**`wps_calendar_get_event`**；**参与者列表**：**`wps_calendar_list_event_attendees`**；**答复日程邀请**：**`wps_calendar_respond_invitation`**；**日历级实例列表**：**`wps_calendar_list_calendar_event_instances`**；**单条日程的实例**（须 `event_id`）：**`wps_calendar_list_event_instances`**。**创建 / 列举 / 查看 / 更新 / 状态更新个人待办**：用 **`wps-todo`** skill 的 **`wps_todo_create_personal_task`**、**`wps_todo_list_personal_tasks`**、**`wps_todo_get_personal_task`**、**`wps_todo_update_personal_task`**、**`wps_todo_update_personal_task_status`**。**获取云文档盘列表 / 新建文件（夹）/ 文档内容抽取 / 获取文件信息 / 文件搜索**：用 **`wps-drive`** skill 的 **`wps_drive_list_drives`**、**`wps_drive_create_file`**、**`wps_drive_extract_file_content`**、**`wps_drive_get_file_meta`**、**`wps_drive_search_files`**。其中 **`wps_user_id` 直接用 SenderId**，不要为日程/待办/云文档再调 `wps_user_search`。