@wecom/wecom-openclaw-plugin 2026.7.2-beta.1 → 2026.8.17-beta.1

package/skills/wecom-smartsheet/references/webhook-fallback.md

@@ -1,183 +0,0 @@
-# 智能表格 Webhook 兜底写入
-
-> 本文档是 `smartsheet_add_records` / `smartsheet_update_records` 的 **fallback 参考**。
-> 当通过 `wecom_mcp` tool 调用因企业规模限制（可见范围 > 10 人）报错、无法写入智能表格时，切换到本方案，通过企业微信智能表格的 Webhook 接口直接写入数据。
->
-> ⚠️ **格式隔离**：以下字段值格式仅适用于 Webhook 接口，与 `wecom_mcp` tool 侧 `smartsheet_add_records` / `smartsheet_update_records` 的参数结构**不同**（例如文本、URL、图片、日期的写法均有差异），请勿与 [cell-value-formats.md](cell-value-formats.md) 的格式混用。
-
----
-
-## 一、Fallback 触发流程
-
-### 何时切换到 Webhook
-
-先走 `wecom_mcp` tool 正常链路（`smartsheet_add_records` / `smartsheet_update_records`）。仅在出现以下情况时才切换到 Webhook：
-
-- **优先判据**：返回 `errcode: 851003`，或 `errmsg` 包含 `no authority` —— 无文档权限。在编辑场景，通常是因为机器人不允许编辑由企业成员创建的文档
-- 或 `errmsg` / 提示信息明显指向**无文档权限**（例如"超出可见范围"、"成员数超限"等相关描述）- 其他错误（参数错误、字段 ID 错误、文档不存在等）**不应**切换到 Webhook，应按原错误排查
-
-### 切换时向用户索取的两样东西
-
-切换触发后，**每次对话内临时获取，用完即弃，不保存到本地任何位置**：
-
-1. **Webhook 完整 URL**
-   - 在智能表格右上角菜单 → 「接收外部数据」→ 选择目标工作表 → 开启 → 复制
-   - 格式形如 `https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=XXXXXX`
-   - 该 URL 相当于该表的写入密钥，用户随时可以在智能表格里关闭「接收外部数据」使其失效
-2. **schema 示例 JSON**
-   - 同一「接收外部数据」页面即可复制
-   - 包含字段 ID → 字段名的映射（`schema`）和各字段的写入格式示例（`add_records`）
-
-示例：
-
-```json
-{
-  "schema": {
-    "fABCD1": "任务名称",
-    "fABCD2": "状态",
-    "fABCD3": "负责人",
-    "fABCD4": "截止日期"
-  },
-  "add_records": [
-    {
-      "values": {
-        "fABCD1": "示例任务",
-        "fABCD2": [{"text": "未开始"}],
-        "fABCD3": [{"user_id": ""}],
-        "fABCD4": "1742400000000"
-      }
-    }
-  ]
-}
-```
-
-### 向用户告知的话术参考
-
-- “通过 `wecom_mcp` 写入接口返回了 `851003 no authority`，无文档权限（在编辑场景，通常是因为机器人不允许编辑由企业成员创建的文档）。请把目标表的 Webhook 地址和「接收外部数据」页面的示例 JSON 发我，我帮你通过 Webhook 写入。该信息仅本轮使用，不会保存到本地。”
-
----
-
-## 二、构建请求
-
-### 字段匹配
-
-用户描述通常是自然语言（“标题”“状态”“处理人”），需从用户提供的 `schema` 中找对应字段 ID：
-
-- 模糊匹配：`标题` → 标题 / 名称 / 主题；`状态` → 状态 / 阶段；`处理人` → 负责人 / 责任人
-- 不确定时先问用户确认，避免写错字段
-
-各字段类型的值写法见下方 [字段类型格式规范](#三字段类型格式规范)；真实场景示例见 [webhook-examples.md](webhook-examples.md)。
-
-### 日期处理
-
-用户说“今天”“明天”“3 月 15 日”“2025-03-01 09:00”等自然语言日期时，**在 payload 构造阶段**根据当前日期推算为**毫秒时间戳字符串**（如 `"1742400000000"`）。Webhook 侧**不接受**可读日期字符串。
-
-### 请求结构
-
-Webhook 是标准 HTTP 接口，不经过 `wecom_mcp`，请按执行环境选择合适的工具发送（`curl`、`node` 内置 `fetch`、`python` 的 `requests` / `urllib` 等均可，优先用当前环境最便捷的方式）：
-
-| 项 | 值 |
-|---|---|
-| Method | `POST` |
-| URL | 用户提供的 Webhook 完整 URL（含 `?key=XXX`） |
-| Header | `Content-Type: application/json` |
-| Body | JSON 对象，包含 `add_records` 和/或 `update_records` 字段 |
-
-### Body 结构
-
-- 仅新增：
-
-```json
-{
-  "add_records": [
-    { "values": { "fABCD1": "...", "fABCD2": [{"text": "..."}] } }
-  ]
-}
-```
-
-- 仅更新（需提供 `record_id`，且**只能更新通过 Webhook 写入的记录**，人工创建的记录无法更新）：
-
-```json
-{
-  "update_records": [
-    { "record_id": "REC_xxx", "values": { "fABCD2": [{"text": "已完成"}] } }
-  ]
-}
-```
-
-- 同一请求同时新增和更新：
-
-```json
-{
-  "add_records":    [ { "values": { ... } } ],
-  "update_records": [ { "record_id": "REC_xxx", "values": { ... } } ]
-}
-```
-
-### 成功后
-
-简洁告知结果，例如：
-
-> “已通过 Webhook 写入，record_id: `REC_xxx`”
-
-返回非 0 `errcode` 时参考下方 [常见错误码](#六常见错误码)。
-
----
-
-## 三、字段类型格式规范
-
-### 各类型写法
-
-| 字段类型 | value 示例 | 说明 |
-|---------|-----------|------|
-| 文本 | `"产品登录页白屏"` 或 `[{"type":"text","text":"产品登录页白屏"}]` | 简单字符串更简洁 |
-| 数字 / 货币 | `58000` | double，不要加引号 |
-| 进度 / 百分数 | `30` | 传整数值，`30` = 30%；**不要传小数** `0.3`（那样会显示 0.3%） |
-| 复选框 | `true` / `false` | bool |
-| 日期 | `"1740806400000"` | 毫秒时间戳，字符串形式 |
-| 成员 | `[{"user_id":"lisi"}]` 或 `["张三"]` 或 `[]` | userid 通常就是企业微信登录账号；不指定时传 `[]` |
-| 单选 | `[{"text":"已完成"}]` | 数组，选项文本必须与表格预设完全一致 |
-| 多选 | `[{"text":"前端"},{"text":"后端"}]` | 数组，每个选项一个对象 |
-| 链接 | `[{"text":"需求文档","link":"https://doc.example.com"}]` | 数组 |
-| 地理位置 | `[{"latitude":"31.23040","longitude":"121.47370","source_type":1,"title":"上海市徐汇区"}]` | 数组，最多 1 条 |
-| 图片 | `[{"title":"screenshot.png","image_base64":"iVBORw0KGgo..."}]` | 纯 base64，**不要带 `data:image/...;base64,` 前缀**，否则报 errcode 2023033 |
-| 电话 / 邮箱 / 条码 | `"13800138000"` | 字符串 |
-
----
-
-## 四、不支持的字段
-
-以下字段由系统自动维护或结构特殊，Webhook 写入时**跳过即可，不要报错**：
-
-公式、自动编号、查找引用、关联字段、创建人、最后编辑人、创建时间、最后编辑时间、群聊、文件附件。
-
----
-
-## 五、频率限制
-
-- 单工作表：≤ 3000 条/分钟
-- 单文档：≤ 10000 条/分钟
-
-数据量大时建议分批，每批不超过 500 条。
-
----
-
-## 六、常见错误码
-
-| errcode | 原因 | 解决方法 |
-|---------|------|---------|
-| 2023033 | 图片 base64 携带了 `data:image/...;base64,` 前缀 | 去掉前缀，只传纯 base64 字符串 |
-| 40014 | Webhook key 无效或已过期 | 请用户重新在智能表格「接收外部数据」获取 Webhook 地址 |
-| 45033 | 超出频率限制 | 降低发送速率或分批发送 |
-| -100035 | testapi 域名不稳定（超时） | 改用正式域名 `qyapi.weixin.qq.com` |
-| 2023001 | 字段 ID 不存在 | 核对用户提供的 `schema`，确认字段 ID 拼写正确 |
-| 2023010 | 单选/多选的选项值不在预设列表 | 确认选项文本与表格设置完全一致（区分大小写） |
-| 2023012 | record_id 不存在（更新时） | 只能更新通过 Webhook 写入的记录，人工创建的记录无法更新 |
-
----
-
-## 七、参考文件
-
-- 真实场景示例 → [webhook-examples.md](webhook-examples.md)
-
-按需查阅，不用每次全读。

package/skills/wecom-todo/SKILL.md

@@ -1,272 +0,0 @@
----
-name: wecom-todo
-description: 企业微信待办事项管理技能，支持创建待办、更新待办、更改用户在待办中的状态、获取待办列表、批量获取待办详情、删除待办。在用户说"帮我创建一个待办"、"把这个任务分派给张三"、"标记待办完成"、"接受/拒绝这个待办"、"把我在这个待办里的状态改成已完成"、"删掉那个待办"、"帮我建个提醒"、"更新一下待办内容"、"把提醒时间改到下周"、"看看这个待办的详情"、"待办分派给谁了"、"看看我有哪些待办"、"列一下我最近的待办"等需要对待办进行读写操作的场景时使用。
----
-
-# 企业微信待办事项管理技能
-
-> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
-
-> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
-
-## 概述
-
-wecom-todo 提供企业微信待办事项的管理能力，包含以下功能：
-
-1. **搜索 userid** - 根据姓名或别名搜索用户的 userid，用于在创建/更新待办、更改用户状态、查询待办列表时把姓名解析为 userid
-2. **创建待办** - 创建新的待办事项，可指定内容、参与人、截止时间和提醒方式
-3. **更新待办** - 修改已有待办的内容、参与人、待办状态、截止时间和提醒方式
-4. **更改用户状态** - 更改某位参与人在某个待办中的状态（拒绝/接受/已完成）
-5. **获取待办列表** - 获取指定用户的待办列表，支持按创建时间和提醒时间过滤
-6. **获取待办详情** - 根据待办 ID 列表批量获取完整信息
-7. **删除待办** - 删除指定的待办事项
-
-## 命令调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo <tool_name> '<json格式的入参>'`
-
----
-
-## 命令详细说明
-
-### 1. 搜索 userid (search_todo_userid)
-
-基础接口，根据姓名或别名搜索用户的 userid，用于在创建待办、更新待办时把用户姓名解析为 userid 进行传参。
-
-#### 调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo search_todo_userid '<json格式的入参>'`
-
-#### 入参说明
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `keyword` | string | 是 | 姓名或别名 |
-
-#### 调用示例
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo search_todo_userid '{"keyword": "张三"}'`
-
-#### 返回字段说明
-
-- 返回与关键字匹配的用户的 `userid`（可能为多个候选）。
-- 若有多个同名/相似用户，展示候选列表让用户确认后再使用；展示时只用姓名/别名/部门等可读信息区分，**禁止向用户暴露 `userid`**。
-- 拿到的 `userid` 用于 `create_todo` / `update_todo` 的 `follower_list`，仅供内部传参，不在对话中展示。
-- 调用前可先检查对话上下文是否已有该用户的 `userid`，若有则直接复用、无需再次查询；若本接口返回错误（查询失败、无结果等），则改用通讯录 `wecom-contact` 技能搜索（详见注意事项第 2 条）。
-
----
-
-### 2. 创建待办 (create_todo)
-
-创建一个新的待办事项，可指定内容、参与人、截止时间和提醒方式。
-
-#### 调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo create_todo '<json格式的入参>'`
-
-#### 入参说明
-
-| 参数 | 类型 | 必填 | 说明                                                              |
-|------|------|----|-----------------------------------------------------------------|
-| `content` | string | 是  | 待办内容                                                            |
-| `follower_list` | object | 是  | 参与人信息，对象中包含 `followers` 数组，格式见注意事项第 3 条 |
-| `end_time` | string | 条件必填  | 截止时间（到期时间），格式：`YYYY-MM-DD HH:mm:ss`；提醒方式基于此时间计算偏移。当 `remind_type_list` 含非 `0`（即设置了实际提醒）时**必填**          |
-| `remind_type_list` | uint32[] | 否  | 提醒方式，相对 `end_time` 计算，可传入多个，取值见注意事项第 4 条                       |
-
-#### 调用示例
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo create_todo '{"content": "<待办的内容>", "follower_list": {"followers": [{"follower_id": "FOLLOWER_ID", "follower_status": 1}]}, "end_time": "2025-06-01 09:00:00", "remind_type_list": [3, 7]}'`
-
-#### 返回字段说明
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `todo_id` | string | 新创建的待办唯一 ID |
-
----
-
-### 3. 更新待办 (update_todo)
-
-修改已有待办事项的内容、参与人、待办状态、截止时间或提醒方式。
-
-> 说明：本接口可更改待办状态（`todo_status`），但**不能更改参与人状态（`follower_status`）**。如需更改当前用户在某个待办中的状态，请使用 `change_todo_user_status`。
-
-#### 调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '<json格式的入参>'`
-
-#### 入参说明
-
-| 参数 | 类型 | 必填 | 说明                                                       |
-|------|------|------|----------------------------------------------------------|
-| `todo_id` | string | 是 | 待办 ID                                                    |
-| `content` | string | 否 | 新的待办内容                                                   |
-| `follower_list` | object | 否 | 新的参与人信息（全量替换，非追加），对象中包含 `followers` 数组，格式见注意事项第 3 条。若要新增参与人，需先查出现有参与人，合并后一起提交。**本接口不会更改参与人状态（`follower_status`），如需更改用户状态请使用 `change_todo_user_status`** |
-| `todo_status` | uint32 | 否 | 新的待办状态：`0`-已完成，`1`-进行中       |
-| `end_time` | string | 否 | 新的截止时间（到期时间），格式：`YYYY-MM-DD HH:mm:ss`；提醒方式基于此时间计算偏移   |
-| `remind_type_list` | uint32[] | 否 | 新的提醒方式，相对 `end_time` 计算，可传入多个                                |
-
-#### 调用示例
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "content": "<待办的内容>", "end_time": "2025-07-01 09:00:00", "remind_type_list": [1]}'`
-
----
-
-### 4. 更改用户在某个待办的状态 (change_todo_user_status)
-
-更改某位参与人在某个待办中的状态（拒绝/接受/已完成）。
-
-#### 调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '<json格式的入参>'`
-
-#### 入参说明
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `todo_id` | string | 是 | 待办 ID |
-| `follower_id` | string | 是 | 参与人 `userid`，指定要修改哪一位参与人的状态。来源遵循注意事项第 2 条的 userid 获取规则（上下文已有 → `search_todo_userid` → `wecom-contact` 技能兜底），禁止自行猜测或构造 |
-| `user_status` | uint32 | 是 | 用户状态：`0`-拒绝，`1`-接受，`2`-已完成 |
-
-#### 调用示例
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '{"todo_id": "TODO_ID", "follower_id": "FOLLOWER_ID", "user_status": 2}'`
-
----
-
-### 5. 获取待办列表 (get_todo_list)
-
-获取指定用户（由 `follower_id` 指定，可为任意用户）通过机器人的待办列表，支持当天前后一个月的待办，可按创建时间、提醒时间、截止时间和待办状态过滤。
-
-#### 调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '<json格式的入参>'`
-
-#### 入参说明
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `follower_id` | string | 是 | 参与人 `userid`，指定要查询哪一位用户的待办列表（可为任意用户），来源遵循注意事项第 2 条的 userid 获取规则，禁止自行猜测或构造 |
-| `create_begin_time` | string | 否 | 创建开始时间 |
-| `create_end_time` | string | 否 | 创建结束时间 |
-| `remind_begin_time` | string | 否 | 提醒开始时间 |
-| `remind_end_time` | string | 否 | 提醒结束时间 |
-| `deadline_begin_time` | string | 否 | 截止开始时间 |
-| `deadline_end_time` | string | 否 | 截止结束时间 |
-| `todo_status` | uint32 | 否 | 待办状态：`0`-已完成，`1`-进行中 |
-| `limit` | uint32 | 否 | 最大返回数量，默认为 10，最大为 20 |
-| `cursor` | string | 否 | 游标，用于分页 |
-
-> **查询时间范围限制**：
-> - 用于筛选的时间（创建时间、提醒时间、截止时间）必须落在当天前后 30 天以内。
-> - 若仅按 `todo_status` 筛选而未传任何时间范围，则默认按「创建时间在当天前后 30 天内」查询。
-
-#### 调用示例
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{"follower_id": "FOLLOWER_ID", "create_begin_time": "2025-06-01 00:00:00", "create_end_time": "2025-06-30 23:59:59", "todo_status": 1, "limit": 20}'`
-
-#### 返回字段说明
-
-- 返回指定用户（`follower_id`）的待办列表，以及用于分页的游标。
-- 拿到的 `todo_id` 可用于 `get_todo_detail` / `update_todo` / `delete_todo`，仅供内部传参，**禁止向用户暴露**。
-
----
-
-### 6. 获取待办详情 (get_todo_detail)
-
-根据待办 ID 列表批量查询完整详情，包含待办内容和参与人信息。
-
-#### 调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '<json格式的入参>'`
-
-#### 入参说明
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `todo_id_list` | string[] | 是 | 待办 ID 列表，至少 1 个，最多 20 个 |
-
-#### 调用示例
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'`
-
-#### 返回字段说明
-
-| 字段                                                      | 类型 | 说明                                |
-|---------------------------------------------------------|------|-----------------------------------|
-| `data_list`                                             | array | 待办详情列表，最多 20 条                    |
-| `data_list[].todo_id`                                   | string | 待办 ID                             |
-| `data_list[].todo_status`                               | number | 待办状态：`0`-已完成，`1`-进行中，`2`-已删除      |
-| `data_list[].content`                                   | string | 待办内容                              |
-| `data_list[].follower_list`                             | object | 参与人列表                             |
-| `data_list[].follower_list.followers[].follower_id`     | string | 参与人 ID（即 userid）                  |
-| `data_list[].follower_list.followers[].name`            | string | 参与人姓名                             |
-| `data_list[].follower_list.followers[].follower_status` | number | 参与人状态：`0`-拒绝，`1`-接受，`2`-已完成       |
-| `data_list[].follower_list.followers[].update_time`              | string | 参与人状态更新时间                         |
-| `data_list[].creator_id`                                | string | 创建人 ID（即 userid）                  |
-| `data_list[].user_status`                               | number | 当前用户在该待办中的状态：`0`-拒绝，`1`-接受，`2`-已完成 |
-| `data_list[].end_time`                                  | string | 截止时间（到期时间）                        |
-| `data_list[].remind_type_list`                          | array | 提醒方式列表                            |
-| `data_list[].create_time`                               | string | 创建时间                              |
-| `data_list[].update_time`                               | string | 更新时间                              |
-
----
-
-### 7. 删除待办 (delete_todo)
-
-删除指定的待办事项。
-
-#### 调用方式
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo delete_todo '<json格式的入参>'`
-
-#### 入参说明
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `todo_id` | string | 是 | 待办 ID |
-
-#### 调用示例
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call todo delete_todo '{"todo_id": "TODO_ID"}'`
-
----
-
-## 注意事项
-
-1. **todo_id 来源规则**
-   - `todo_id` 可来自 `create_todo` 返回的结果，或 `get_todo_list` 查询到的列表，请务必保存好，禁止自行推测或构造
-
-2. **userid 来源与隐私规则**
-   - 分派待办时，`follower_list` 中的 `follower_id` 即 `userid`，按以下优先级获取，禁止根据用户姓名自行猜测或构造 userid：
-     1. **对话上下文已有**：若对话上下文中已经提到对应用户的 `userid`，直接使用，无需再次查询
-     2. **search_todo_userid 查询**：若上下文中没有，则可先询问用户在企业内的用户名称（通常是姓名），再通过 `search_todo_userid` 接口按姓名/别名查询获取
-     3. **通讯录技能兜底**：若 `search_todo_userid` 返回错误（如当前企业不适用等），则改用通讯录 `wecom-contact` 技能搜索获取 `userid`
-   - `userid` 属于敏感标识，仅用于接口传参，**禁止在回复或候选列表中向用户展示**；需要让用户区分人员时，只展示姓名/别名/部门等可读信息
-
-3. **follower_list 格式说明**
-   - 作为入参时，`follower_list` 为对象，内含 `followers` 数组，格式如下：
-     ```json
-     "follower_list": {
-         "followers": [
-             {
-                 "follower_id": "FOLLOWER_ID",
-                 "follower_status": 1
-             }
-         ]
-     }
-     ```
-   - `follower_id` 即用户的 `userid`，其来源遵循上文「userid 来源与隐私规则」的优先级（上下文已有 → `search_todo_userid` → `wecom-contact` 技能兜底），禁止自行猜测或构造
-   - `follower_status` 为参与人状态：`0`-拒绝，`1`-接受，`2`-已完成；该字段仅在 `create_todo` 中生效
-   - 在 `update_todo` 中为全量替换（非追加）：若要新增参与人，需先用 `get_todo_detail` 查出现有参与人，合并后一并提交；`update_todo` **不会更改参与人状态（`follower_status`）**，如需更改当前用户在某个待办中的状态，请使用 `change_todo_user_status`
-
-4. **remind_type_list 提醒方式取值**
-
-`remind_type_list` 是一个 uint32 数组，可同时传入多个提醒：
-
-| 值 | 含义 | 值 | 含义 |
-|----|------|----|------|
-| `0` | 不提醒 | `6` | 提前 2 小时 |
-| `1` | 到期时 | `7` | 提前 1 天 |
-| `3` | 提前 15 分钟 | `8` | 提前 2 天 |
-| `5` | 提前 1 小时 | `9` | 提前 1 周 |