@wecom/wecom-openclaw-plugin 2026.7.2-beta.1 → 2026.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -9,9 +9,7 @@
|
|
|
9
9
|
* tool.ts 的 handleCall 无需任何改动。
|
|
10
10
|
*/
|
|
11
11
|
import { bizErrorInterceptor } from "./biz-error.js";
|
|
12
|
-
|
|
13
|
-
// 不再发送授权引导模板卡片，对齐其他品类错误的表现。实现文件保留以便回滚。
|
|
14
|
-
// import { docAuthErrorInterceptor } from "./doc-auth-error.js";
|
|
12
|
+
import { docAuthErrorInterceptor } from "./doc-auth-error.js";
|
|
15
13
|
import { mediaInterceptor } from "./msg-media.js";
|
|
16
14
|
import { smartpageCreateInterceptor } from "./smartpage-create.js";
|
|
17
15
|
import { smartpageExportInterceptor } from "./smartpage-export.js";
|
|
@@ -21,7 +19,7 @@ import { smartsheetUploadInterceptor } from "./smartsheet-upload.js";
|
|
|
21
19
|
// ============================================================================
|
|
22
20
|
const interceptors = [
|
|
23
21
|
bizErrorInterceptor, // 业务错误码检查（所有 call 生效）
|
|
24
|
-
|
|
22
|
+
docAuthErrorInterceptor, // 文档授权错误拦截（category=doc, errcode=851013/851014/851008）
|
|
25
23
|
mediaInterceptor, // get_msg_media base64 拦截
|
|
26
24
|
smartpageCreateInterceptor, // smartpage_create 本地文件读取
|
|
27
25
|
smartpageExportInterceptor, // smartpage_get_export_result content → 本地文件
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: wecom-todo
|
|
3
|
-
description:
|
|
3
|
+
description: 企业微信待办事项管理技能，支持查询待办列表、获取待办详情、创建待办、更新待办、删除待办及变更用户处理进度状态。在用户说"看看我的待办列表"、"我有哪些待办"、"帮我创建一个待办"、"把这个任务分派给张三"、"标记待办完成"、"删掉那个待办"、"帮我建个提醒"、"更新一下待办内容"、"把提醒时间改到下周"、"接受这个待办"、"拒绝这个待办"、"这个待办的详情"、"待办分派给谁了"等需要对待办进行读写操作的场景时使用。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# 企业微信待办事项管理技能
|
|
@@ -11,262 +11,382 @@ description: 企业微信待办事项管理技能，支持创建待办、更新
|
|
|
11
11
|
|
|
12
12
|
## 概述
|
|
13
13
|
|
|
14
|
-
wecom-todo
|
|
14
|
+
wecom-todo 提供企业微信待办事项的完整管理能力，包含以下功能：
|
|
15
15
|
|
|
16
|
-
1.
|
|
17
|
-
2.
|
|
18
|
-
3.
|
|
19
|
-
4.
|
|
20
|
-
5.
|
|
21
|
-
6.
|
|
22
|
-
7. **删除待办** - 删除指定的待办事项
|
|
16
|
+
1. **查询待办列表** - 按创建时间和提醒时间过滤，支持分页，返回待办概要信息
|
|
17
|
+
2. **获取待办详情** - 根据待办 ID 列表批量获取完整信息（含内容和分派人）
|
|
18
|
+
3. **创建待办** - 创建新的待办事项，可指定内容、分派人和提醒时间
|
|
19
|
+
4. **更新待办** - 修改已有待办的内容、分派人、状态或提醒时间
|
|
20
|
+
5. **删除待办** - 删除指定的待办事项
|
|
21
|
+
6. **变更用户待办状态** - 更改当前用户在某个待办中的状态（拒绝/接受/已完成）
|
|
23
22
|
|
|
24
23
|
## 命令调用方式
|
|
25
24
|
|
|
26
25
|
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo <tool_name> '<json格式的入参>'`
|
|
27
26
|
|
|
27
|
+
## 行为策略
|
|
28
|
+
|
|
29
|
+
**查完列表必须查详情**: `get_todo_list` 只返回待办 ID 和状态等概要信息，不包含待办的实际内容和分派人。对用户来说，没有内容的待办列表毫无用处——他们想知道的是"要做什么"，而不是一串 ID。因此，每次调用 `get_todo_list` 拿到结果后，都要紧接着用返回的 todo_id 列表调用 `get_todo_detail` 获取完整详情（内容、分派人等），然后再向用户展示。这不是可选步骤，而是完成用户请求的必要环节。
|
|
30
|
+
|
|
31
|
+
**人员 ID 转姓名（关键步骤）**: `get_todo_detail` 返回结果中的 `follower_id` 和 `creator_id` 都是系统内部 ID，直接展示给用户毫无意义——用户不认识这些 ID，只认识姓名。因此在向用户展示待办详情之前，必须先调用 `wecom-contact` 技能获取通讯录，将所有 `follower_id` 和 `creator_id` 匹配为真实姓名。具体做法：
|
|
32
|
+
|
|
33
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取通讯录，在返回的 userlist 中，用 userid 字段匹配 follower_id / creator_id，取对应的 name。
|
|
34
|
+
|
|
35
|
+
如果通讯录中找不到某个 ID，展示时标注"未知用户(ID: xxx)"即可。
|
|
36
|
+
|
|
37
|
+
**分页未拉完时必须提醒用户**: `get_todo_list` 接口是分页的，不要求一次性拉完所有数据。但如果响应中 `has_more` 为 `true`，说明后面还有待办没有返回——这时你在展示当前结果的同时，必须明确告诉用户"还有更多待办未显示，是否需要继续查看？"。用户可能不知道后面还有数据，如果你不说，他们会以为看到的就是全部，这会导致遗漏重要待办。这是一个容易被忽略但后果严重的点，请务必执行。
|
|
38
|
+
|
|
39
|
+
**重试策略**: 遭遇"返回 HTTP 错误"或"HTTP 请求失败"时，主动重试，最多重试三次。
|
|
40
|
+
|
|
28
41
|
---
|
|
29
42
|
|
|
30
43
|
## 命令详细说明
|
|
31
44
|
|
|
32
|
-
### 1.
|
|
45
|
+
### 1. 查询待办列表 (get_todo_list)
|
|
33
46
|
|
|
34
|
-
|
|
47
|
+
查询当前用户的待办列表，支持按时间过滤和分页。返回的是待办概要信息（不含内容和分派人）。
|
|
35
48
|
|
|
36
49
|
#### 调用方式
|
|
37
50
|
|
|
38
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
51
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '<json格式的入参>'`
|
|
39
52
|
|
|
40
53
|
#### 入参说明
|
|
41
54
|
|
|
42
55
|
| 参数 | 类型 | 必填 | 说明 |
|
|
43
56
|
|------|------|------|------|
|
|
44
|
-
| `
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
57
|
+
| `create_begin_time` | string | ❌ | 创建开始时间，格式：`YYYY-MM-DD HH:mm:ss` |
|
|
58
|
+
| `create_end_time` | string | ❌ | 创建结束时间，格式：`YYYY-MM-DD HH:mm:ss` |
|
|
59
|
+
| `remind_begin_time` | string | ❌ | 提醒开始时间，格式：`YYYY-MM-DD HH:mm:ss` |
|
|
60
|
+
| `remind_end_time` | string | ❌ | 提醒结束时间，格式：`YYYY-MM-DD HH:mm:ss` |
|
|
61
|
+
| `limit` | number | ❌ | 最大返回数量，默认 10，最大 20 |
|
|
62
|
+
| `cursor` | string | ❌ | 分页游标，首次请求不传，后续传入上次响应的 `next_cursor` |
|
|
63
|
+
|
|
64
|
+
#### 返回格式
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"errcode": 0,
|
|
69
|
+
"errmsg": "ok",
|
|
70
|
+
"index_list": [
|
|
71
|
+
{
|
|
72
|
+
"todo_id": "TODO_ID",
|
|
73
|
+
"todo_status": 1,
|
|
74
|
+
"user_status": 1,
|
|
75
|
+
"creator_id": "CREATOR_ID",
|
|
76
|
+
"remind_time": "2025-06-01 09:00:00",
|
|
77
|
+
"create_time": "2025-01-15 10:30:00",
|
|
78
|
+
"update_time": "2025-01-16 14:20:00"
|
|
79
|
+
}
|
|
80
|
+
],
|
|
81
|
+
"next_cursor": "NEXT_CURSOR",
|
|
82
|
+
"has_more": false
|
|
83
|
+
}
|
|
84
|
+
```
|
|
49
85
|
|
|
50
86
|
#### 返回字段说明
|
|
51
87
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
88
|
+
| 字段 | 类型 | 说明 |
|
|
89
|
+
|------|------|------|
|
|
90
|
+
| `index_list` | array | 待办列表 |
|
|
91
|
+
| `index_list[].todo_id` | string | 待办唯一 ID |
|
|
92
|
+
| `index_list[].todo_status` | number | 待办状态：`0`-已完成，`1`-进行中，`2`-已删除 |
|
|
93
|
+
| `index_list[].user_status` | number | 用户状态：`0`-拒绝，`1`-接受，`2`-已完成 |
|
|
94
|
+
| `index_list[].creator_id` | string | 创建人 ID |
|
|
95
|
+
| `index_list[].remind_time` | string | 提醒时间 |
|
|
96
|
+
| `index_list[].create_time` | string | 创建时间 |
|
|
97
|
+
| `index_list[].update_time` | string | 更新时间 |
|
|
98
|
+
| `next_cursor` | string | 下一页游标 |
|
|
99
|
+
| `has_more` | boolean | 是否还有更多记录 |
|
|
100
|
+
|
|
101
|
+
> 列表返回的是待办概要信息（不含内容和分派人）。拿到列表后，必须调用 `get_todo_detail` 获取完整详情再展示给用户。
|
|
56
102
|
|
|
57
103
|
---
|
|
58
104
|
|
|
59
|
-
### 2.
|
|
105
|
+
### 2. 获取待办详情 (get_todo_detail)
|
|
60
106
|
|
|
61
|
-
|
|
107
|
+
根据待办 ID 列表批量查询完整详情，包含待办内容和分派人信息。
|
|
62
108
|
|
|
63
109
|
#### 调用方式
|
|
64
110
|
|
|
65
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
111
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '<json格式的入参>'`
|
|
66
112
|
|
|
67
113
|
#### 入参说明
|
|
68
114
|
|
|
69
|
-
| 参数 | 类型 | 必填 | 说明
|
|
70
|
-
|
|
71
|
-
| `
|
|
72
|
-
| `follower_list` | object | 是 | 参与人信息，对象中包含 `followers` 数组，格式见注意事项第 3 条 |
|
|
73
|
-
| `end_time` | string | 条件必填 | 截止时间（到期时间），格式：`YYYY-MM-DD HH:mm:ss`；提醒方式基于此时间计算偏移。当 `remind_type_list` 含非 `0`（即设置了实际提醒）时**必填** |
|
|
74
|
-
| `remind_type_list` | uint32[] | 否 | 提醒方式，相对 `end_time` 计算，可传入多个，取值见注意事项第 4 条 |
|
|
115
|
+
| 参数 | 类型 | 必填 | 说明 |
|
|
116
|
+
|------|------|------|------|
|
|
117
|
+
| `todo_id_list` | array | ✅ | 待办 ID 列表，最多 20 个 |
|
|
75
118
|
|
|
76
119
|
#### 调用示例
|
|
77
120
|
|
|
78
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
121
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'`
|
|
122
|
+
|
|
123
|
+
#### 返回格式
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{
|
|
127
|
+
"errcode": 0,
|
|
128
|
+
"errmsg": "ok",
|
|
129
|
+
"data_list": [
|
|
130
|
+
{
|
|
131
|
+
"todo_id": "TODO_ID",
|
|
132
|
+
"todo_status": 1,
|
|
133
|
+
"content": "完成Q2规划文档",
|
|
134
|
+
"follower_list": {
|
|
135
|
+
"followers": [
|
|
136
|
+
{
|
|
137
|
+
"follower_id": "FOLLOWER_ID",
|
|
138
|
+
"follower_status": 1,
|
|
139
|
+
"update_time": "2025-01-16 14:20:00"
|
|
140
|
+
}
|
|
141
|
+
]
|
|
142
|
+
},
|
|
143
|
+
"creator_id": "CREATOR_ID",
|
|
144
|
+
"user_status": 1,
|
|
145
|
+
"remind_time": "2025-06-01 09:00:00",
|
|
146
|
+
"create_time": "2025-01-15 10:30:00",
|
|
147
|
+
"update_time": "2025-01-16 14:20:00"
|
|
148
|
+
}
|
|
149
|
+
]
|
|
150
|
+
}
|
|
151
|
+
```
|
|
79
152
|
|
|
80
153
|
#### 返回字段说明
|
|
81
154
|
|
|
82
155
|
| 字段 | 类型 | 说明 |
|
|
83
156
|
|------|------|------|
|
|
84
|
-
| `
|
|
157
|
+
| `data_list` | array | 待办详情列表，最多 20 条 |
|
|
158
|
+
| `data_list[].todo_id` | string | 待办 ID |
|
|
159
|
+
| `data_list[].todo_status` | number | 待办状态：`0`-已完成，`1`-进行中，`2`-已删除 |
|
|
160
|
+
| `data_list[].content` | string | 待办内容 |
|
|
161
|
+
| `data_list[].follower_list.followers` | array | 分派人列表 |
|
|
162
|
+
| `data_list[].follower_list.followers[].follower_id` | string | 分派人 ID（即 userid）— **展示前需通过 wecom-contact 转为姓名** |
|
|
163
|
+
| `data_list[].follower_list.followers[].follower_status` | number | 分派人状态：`0`-拒绝，`1`-接受，`2`-已完成 |
|
|
164
|
+
| `data_list[].follower_list.followers[].update_time` | string | 分派人状态更新时间 |
|
|
165
|
+
| `data_list[].creator_id` | string | 创建人 ID — **展示前需通过 wecom-contact 转为姓名** |
|
|
166
|
+
| `data_list[].user_status` | number | 当前用户状态 |
|
|
167
|
+
| `data_list[].remind_time` | string | 提醒时间 |
|
|
168
|
+
| `data_list[].create_time` | string | 创建时间 |
|
|
169
|
+
| `data_list[].update_time` | string | 更新时间 |
|
|
85
170
|
|
|
86
171
|
---
|
|
87
172
|
|
|
88
|
-
### 3.
|
|
173
|
+
### 3. 创建待办 (create_todo)
|
|
89
174
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
> 说明：本接口可更改待办状态（`todo_status`），但**不能更改参与人状态（`follower_status`）**。如需更改当前用户在某个待办中的状态，请使用 `change_todo_user_status`。
|
|
175
|
+
创建一个新的待办事项，可指定内容、分派人和提醒时间。
|
|
93
176
|
|
|
94
177
|
#### 调用方式
|
|
95
178
|
|
|
96
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
179
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo create_todo '<json格式的入参>'`
|
|
97
180
|
|
|
98
181
|
#### 入参说明
|
|
99
182
|
|
|
100
|
-
| 参数 | 类型 | 必填 | 说明
|
|
101
|
-
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `todo_status` | uint32 | 否 | 新的待办状态：`0`-已完成，`1`-进行中 |
|
|
106
|
-
| `end_time` | string | 否 | 新的截止时间（到期时间），格式：`YYYY-MM-DD HH:mm:ss`；提醒方式基于此时间计算偏移 |
|
|
107
|
-
| `remind_type_list` | uint32[] | 否 | 新的提醒方式，相对 `end_time` 计算，可传入多个 |
|
|
183
|
+
| 参数 | 类型 | 必填 | 说明 |
|
|
184
|
+
|------|------|------|------|
|
|
185
|
+
| `content` | string | ✅ | 待办内容 |
|
|
186
|
+
| `follower_list` | object | ❌ | 分派人列表，格式见注意事项第 6 条 |
|
|
187
|
+
| `remind_time` | string | ❌ | 提醒时间，格式：`YYYY-MM-DD HH:mm:ss` |
|
|
108
188
|
|
|
109
189
|
#### 调用示例
|
|
110
190
|
|
|
111
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
191
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo create_todo '{"content": "<待办的内容>", "remind_time": "2025-06-01 09:00:00"}'`
|
|
192
|
+
|
|
193
|
+
#### 返回格式
|
|
194
|
+
|
|
195
|
+
```json
|
|
196
|
+
{
|
|
197
|
+
"errcode": 0,
|
|
198
|
+
"errmsg": "ok",
|
|
199
|
+
"todo_id": "TODO_ID"
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
#### 返回字段说明
|
|
204
|
+
|
|
205
|
+
| 字段 | 类型 | 说明 |
|
|
206
|
+
|------|------|------|
|
|
207
|
+
| `todo_id` | string | 新创建的待办唯一 ID |
|
|
112
208
|
|
|
113
209
|
---
|
|
114
210
|
|
|
115
|
-
### 4.
|
|
211
|
+
### 4. 更新待办 (update_todo)
|
|
116
212
|
|
|
117
|
-
|
|
213
|
+
修改已有待办事项的内容、分派人、状态或提醒时间。
|
|
118
214
|
|
|
119
215
|
#### 调用方式
|
|
120
216
|
|
|
121
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
217
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '<json格式的入参>'`
|
|
122
218
|
|
|
123
219
|
#### 入参说明
|
|
124
220
|
|
|
125
221
|
| 参数 | 类型 | 必填 | 说明 |
|
|
126
222
|
|------|------|------|------|
|
|
127
|
-
| `todo_id` | string |
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
223
|
+
| `todo_id` | string | ✅ | 待办 ID |
|
|
224
|
+
| `content` | string | ❌ | 新的待办内容 |
|
|
225
|
+
| `follower_list` | object | ❌ | 新的分派人列表（全量替换，非追加），格式见注意事项第 6 条。若要新增分派人，需先查出现有分派人，合并后一起提交 |
|
|
226
|
+
| `todo_status` | number | ❌ | 新的待办状态：`0`-已完成，`1`-进行中，`2`-已删除。删除请使用 `delete_todo` |
|
|
227
|
+
| `remind_time` | string | ❌ | 新的提醒时间 |
|
|
130
228
|
|
|
131
229
|
#### 调用示例
|
|
132
230
|
|
|
133
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
231
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "content": "<待办的内容>", "remind_time": "2025-07-01 09:00:00"}'`
|
|
232
|
+
|
|
233
|
+
#### 返回格式
|
|
234
|
+
|
|
235
|
+
```json
|
|
236
|
+
{
|
|
237
|
+
"errcode": 0,
|
|
238
|
+
"errmsg": "ok"
|
|
239
|
+
}
|
|
240
|
+
```
|
|
134
241
|
|
|
135
242
|
---
|
|
136
243
|
|
|
137
|
-
### 5.
|
|
244
|
+
### 5. 删除待办 (delete_todo)
|
|
138
245
|
|
|
139
|
-
|
|
246
|
+
删除指定的待办事项。
|
|
140
247
|
|
|
141
248
|
#### 调用方式
|
|
142
249
|
|
|
143
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
250
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo delete_todo '<json格式的入参>'`
|
|
144
251
|
|
|
145
252
|
#### 入参说明
|
|
146
253
|
|
|
254
|
+
需要遵循 “注意事项”中的格式要求：
|
|
255
|
+
|
|
147
256
|
| 参数 | 类型 | 必填 | 说明 |
|
|
148
257
|
|------|------|------|------|
|
|
149
|
-
| `
|
|
150
|
-
| `create_begin_time` | string | 否 | 创建开始时间 |
|
|
151
|
-
| `create_end_time` | string | 否 | 创建结束时间 |
|
|
152
|
-
| `remind_begin_time` | string | 否 | 提醒开始时间 |
|
|
153
|
-
| `remind_end_time` | string | 否 | 提醒结束时间 |
|
|
154
|
-
| `deadline_begin_time` | string | 否 | 截止开始时间 |
|
|
155
|
-
| `deadline_end_time` | string | 否 | 截止结束时间 |
|
|
156
|
-
| `todo_status` | uint32 | 否 | 待办状态：`0`-已完成，`1`-进行中 |
|
|
157
|
-
| `limit` | uint32 | 否 | 最大返回数量，默认为 10，最大为 20 |
|
|
158
|
-
| `cursor` | string | 否 | 游标，用于分页 |
|
|
159
|
-
|
|
160
|
-
> **查询时间范围限制**：
|
|
161
|
-
> - 用于筛选的时间（创建时间、提醒时间、截止时间）必须落在当天前后 30 天以内。
|
|
162
|
-
> - 若仅按 `todo_status` 筛选而未传任何时间范围，则默认按「创建时间在当天前后 30 天内」查询。
|
|
258
|
+
| `todo_id` | string | ✅ | 待办 ID |
|
|
163
259
|
|
|
164
260
|
#### 调用示例
|
|
165
261
|
|
|
166
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
262
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo delete_todo '{"todo_id": "TODO_ID"}'`
|
|
263
|
+
|
|
264
|
+
#### 返回格式
|
|
167
265
|
|
|
168
|
-
|
|
266
|
+
```json
|
|
267
|
+
{
|
|
268
|
+
"errcode": 0,
|
|
269
|
+
"errmsg": "ok"
|
|
270
|
+
}
|
|
271
|
+
```
|
|
169
272
|
|
|
170
|
-
|
|
171
|
-
|
|
273
|
+
> 删除前必须向用户确认，确认措辞示例："确认删除待办'代码评审'吗？删除后不可恢复。"
|
|
274
|
+
> 注意：`delete_todo` 与 `update_todo` 设置 `todo_status=2` 效果相同，优先使用 `delete_todo`。
|
|
172
275
|
|
|
173
276
|
---
|
|
174
277
|
|
|
175
|
-
### 6.
|
|
278
|
+
### 6. 变更用户待办状态 (change_todo_user_status)
|
|
176
279
|
|
|
177
|
-
|
|
280
|
+
更改当前用户在某个待办中的状态（拒绝/接受/已完成）。
|
|
178
281
|
|
|
179
282
|
#### 调用方式
|
|
180
283
|
|
|
181
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
284
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '<json格式的入参>'`
|
|
182
285
|
|
|
183
286
|
#### 入参说明
|
|
184
287
|
|
|
288
|
+
需要遵循 “注意事项”中的格式要求：
|
|
289
|
+
|
|
185
290
|
| 参数 | 类型 | 必填 | 说明 |
|
|
186
291
|
|------|------|------|------|
|
|
187
|
-
| `
|
|
292
|
+
| `todo_id` | string | ✅ | 待办 ID |
|
|
293
|
+
| `user_status` | number | ✅ | 用户状态：`0`-拒绝，`1`-接受，`2`-已完成 |
|
|
188
294
|
|
|
189
295
|
#### 调用示例
|
|
190
296
|
|
|
191
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo
|
|
192
|
-
|
|
193
|
-
#### 返回字段说明
|
|
194
|
-
|
|
195
|
-
| 字段 | 类型 | 说明 |
|
|
196
|
-
|---------------------------------------------------------|------|-----------------------------------|
|
|
197
|
-
| `data_list` | array | 待办详情列表，最多 20 条 |
|
|
198
|
-
| `data_list[].todo_id` | string | 待办 ID |
|
|
199
|
-
| `data_list[].todo_status` | number | 待办状态：`0`-已完成，`1`-进行中，`2`-已删除 |
|
|
200
|
-
| `data_list[].content` | string | 待办内容 |
|
|
201
|
-
| `data_list[].follower_list` | object | 参与人列表 |
|
|
202
|
-
| `data_list[].follower_list.followers[].follower_id` | string | 参与人 ID（即 userid） |
|
|
203
|
-
| `data_list[].follower_list.followers[].name` | string | 参与人姓名 |
|
|
204
|
-
| `data_list[].follower_list.followers[].follower_status` | number | 参与人状态：`0`-拒绝，`1`-接受，`2`-已完成 |
|
|
205
|
-
| `data_list[].follower_list.followers[].update_time` | string | 参与人状态更新时间 |
|
|
206
|
-
| `data_list[].creator_id` | string | 创建人 ID（即 userid） |
|
|
207
|
-
| `data_list[].user_status` | number | 当前用户在该待办中的状态：`0`-拒绝，`1`-接受，`2`-已完成 |
|
|
208
|
-
| `data_list[].end_time` | string | 截止时间（到期时间） |
|
|
209
|
-
| `data_list[].remind_type_list` | array | 提醒方式列表 |
|
|
210
|
-
| `data_list[].create_time` | string | 创建时间 |
|
|
211
|
-
| `data_list[].update_time` | string | 更新时间 |
|
|
297
|
+
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'`
|
|
212
298
|
|
|
213
|
-
|
|
299
|
+
#### 返回格式
|
|
214
300
|
|
|
215
|
-
|
|
301
|
+
```json
|
|
302
|
+
{
|
|
303
|
+
"errcode": 0,
|
|
304
|
+
"errmsg": "ok"
|
|
305
|
+
}
|
|
306
|
+
```
|
|
216
307
|
|
|
217
|
-
|
|
308
|
+
#### 返回字段说明
|
|
218
309
|
|
|
219
|
-
|
|
310
|
+
| 字段 | 类型 | 说明 |
|
|
311
|
+
|------|------|------|
|
|
312
|
+
| `errcode` | number | 返回码，`0` 表示成功 |
|
|
313
|
+
| `errmsg` | string | 错误信息，成功时为 `"ok"` |
|
|
220
314
|
|
|
221
|
-
|
|
315
|
+
---
|
|
222
316
|
|
|
223
|
-
|
|
317
|
+
## 典型工作流
|
|
224
318
|
|
|
225
|
-
|
|
226
|
-
|------|------|------|------|
|
|
227
|
-
| `todo_id` | string | 是 | 待办 ID |
|
|
319
|
+
> 完整的工作流步骤、命令示例和展示格式详见 [examples/workflows.md](examples/workflows.md)
|
|
228
320
|
|
|
229
|
-
|
|
321
|
+
| 工作流 | 适用场景 | 关键要点 |
|
|
322
|
+
| ------ | -------- | -------- |
|
|
323
|
+
| 工作流 1：查看待办列表 | "看看我最近的待办" | 标准三步：get_todo_list → get_todo_detail → contact 转姓名；检查 has_more 分页 |
|
|
324
|
+
| 工作流 2：按时间范围查询 | "这个月创建的待办有哪些？" | 传入 create_begin_time / create_end_time 过滤，后续同工作流 1 |
|
|
325
|
+
| 工作流 3：创建待办并分派 | "帮我创建一个待办，让张三完成需求文档" | 先通过 wecom-contact 查 userid，再 create_todo 带 follower_list |
|
|
326
|
+
| 工作流 4：标记待办完成 | "把这个待办标记为完成" | 区分场景 A（改 todo_status=0）和场景 B（改 user_status=2） |
|
|
327
|
+
| 工作流 5：更新待办 | "把提醒时间改到下周五" | 先查列表+详情定位目标，再 update_todo |
|
|
328
|
+
| 工作流 6：删除待办 | "删掉那个待办" | 删除前必须向用户确认，不可撤销 |
|
|
329
|
+
| 工作流 7：分页获取 | 待办数量超过单页上限 | 通过 cursor 循环拉取，未拉完必须提醒用户 |
|
|
230
330
|
|
|
231
|
-
使用 `wecom_mcp` tool 调用 `wecom_mcp call todo delete_todo '{"todo_id": "TODO_ID"}'`
|
|
232
331
|
|
|
233
332
|
---
|
|
234
333
|
|
|
235
334
|
## 注意事项
|
|
236
335
|
|
|
237
336
|
1. **todo_id 来源规则**
|
|
238
|
-
- `todo_id`
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
-
|
|
246
|
-
|
|
247
|
-
3.
|
|
248
|
-
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
-
|
|
260
|
-
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
337
|
+
- `todo_id` 必须来自 `get_todo_list` 返回的结果，禁止自行推测或构造
|
|
338
|
+
- 用户通常提供待办内容描述而非 ID，应先通过 `get_todo_list` 查列表再匹配
|
|
339
|
+
- 若匹配到多个相似待办，展示候选列表让用户确认
|
|
340
|
+
|
|
341
|
+
2. **follower_id 来源规则**
|
|
342
|
+
- `follower_id` 即 `userid`，必须通过 `wecom-contact` 技能的 `get_userlist` 接口获取
|
|
343
|
+
- 禁止根据用户姓名自行猜测 userid
|
|
344
|
+
- 若搜索结果有多个同名人员，展示候选列表让用户选择
|
|
345
|
+
|
|
346
|
+
3. **人员 ID 必须转姓名**
|
|
347
|
+
- 返回结果中的 `follower_id` 和 `creator_id` 是系统内部标识，用户无法识别
|
|
348
|
+
- 展示待办详情前，先使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取通讯录
|
|
349
|
+
- 用通讯录的 `userid` 匹配 `follower_id` / `creator_id`，用 `name` 替换展示
|
|
350
|
+
- 如果通讯录中找不到某个 ID，展示时标注"未知用户(ID：xxx)"
|
|
351
|
+
|
|
352
|
+
4. **时间格式**
|
|
353
|
+
- 所有时间参数使用 `YYYY-MM-DD HH:mm:ss` 格式
|
|
354
|
+
- 用户说"明天"、"下周一"等相对时间时，根据当前日期推算具体日期
|
|
355
|
+
|
|
356
|
+
5. **状态值含义**
|
|
357
|
+
- 待办状态（`todo_status`）：`0`-已完成，`1`-进行中，`2`-已删除
|
|
358
|
+
- 用户状态（`user_status`）：`0`-拒绝，`1`-接受，`2`-已完成
|
|
359
|
+
- 分派人状态（`follower_status`）：`0`-拒绝，`1`-接受，`2`-已完成
|
|
360
|
+
|
|
361
|
+
6. **follower_list 的格式**（作为输入参数的时候）
|
|
362
|
+
|
|
363
|
+
```json
|
|
364
|
+
"follower_list": { // 分派人列表
|
|
365
|
+
"followers": [ // 注意里面还有一层是 "followers"，它的value才是真正的列表数组
|
|
366
|
+
{
|
|
367
|
+
"follower_id": "FOLLOWER_ID", // 分派人id
|
|
368
|
+
"follower_status": 1 // 分派人状态：0-拒绝, 1-接受, 2-已完成
|
|
369
|
+
}
|
|
370
|
+
]
|
|
371
|
+
}
|
|
372
|
+
```
|
|
373
|
+
> `follower_id` 即 userid，需要通过 `wecom-contact` 查询获取，禁止自行猜测或构造。
|
|
374
|
+
|
|
375
|
+
7. **破坏性操作确认**
|
|
376
|
+
- 删除待办（`delete_todo`）前必须向用户确认
|
|
377
|
+
- 变更状态为"拒绝"（`user_status=0`）前建议向用户确认
|
|
378
|
+
|
|
379
|
+
8. **必须查详情**
|
|
380
|
+
- `get_todo_list` 返回的是概要信息（不含内容和分派人），拿到列表后必须紧接着调用 `get_todo_detail` 获取完整内容再展示给用户，不要只展示列表概要
|
|
381
|
+
|
|
382
|
+
9. **分页未拉完必须提醒**
|
|
383
|
+
- 如果返回的 `has_more` 为 `true`，在向用户展示结果时必须明确说明"还有更多待办未显示"并询问用户是否需要继续查看
|
|
384
|
+
|
|
385
|
+
10. **单次详情上限**
|
|
386
|
+
- `todo_id_list` 最多传 20 个 ID，超过需要分批请求
|
|
387
|
+
|
|
388
|
+
11. **错误处理**
|
|
389
|
+
- 若 `errcode` 不为 `0`，说明接口调用失败，告知用户 `errmsg` 中的错误信息
|
|
390
|
+
|
|
391
|
+
12. **通讯录查询**
|
|
392
|
+
- 涉及分派人时，需先通过 `wecom-contact` 技能的 `get_userlist` 接口获取全量通讯录成员，再按姓名/别名本地筛选匹配出对应的 `userid`。该接口无入参，返回当前用户可见范围内的成员列表（含 `userid`, `name`, `alias`）
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# 典型工作流
|
|
2
|
+
|
|
3
|
+
### 工作流 1：查看待办列表（标准三步流程）
|
|
4
|
+
|
|
5
|
+
**用户意图**："看看我最近的待办" / "我有哪些待办事项？" / "我还有多少事要做？"
|
|
6
|
+
|
|
7
|
+
**步骤：**
|
|
8
|
+
|
|
9
|
+
1. **获取待办列表**（只有 ID 和状态，没有内容）：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
|
|
10
|
+
|
|
11
|
+
2. **用返回的 todo_id 列表获取完整详情**（禁止跳过！）：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["返回的TODO_ID_1", "返回的TODO_ID_2"]}'`
|
|
12
|
+
|
|
13
|
+
3. **通过 wecom-contact 获取通讯录**，将 follower_id / creator_id 转为姓名：使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'`
|
|
14
|
+
|
|
15
|
+
用返回的 userlist 中的 userid 匹配 follower_id 和 creator_id，取 name 字段作为展示姓名。
|
|
16
|
+
|
|
17
|
+
4. **检查分页**：检查第一步返回的 `has_more` 字段。如果为 `true`，在展示结果时必须提醒用户："以上是部分待办，还有更多待办未显示，需要我继续查看吗？"
|
|
18
|
+
|
|
19
|
+
**展示格式（分派人和创建人必须显示为姓名，不是 ID）：**
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
📋 您当前的待办事项（共 3 项）
|
|
23
|
+
|
|
24
|
+
1. 🔵 完成Q2规划文档
|
|
25
|
+
- 待办状态：进行中 | 我的状态：已接受
|
|
26
|
+
- 提醒时间：2025-06-01 09:00
|
|
27
|
+
- 分派人：张三、李四
|
|
28
|
+
- 创建时间：2025-01-15
|
|
29
|
+
|
|
30
|
+
2. 🔵 提交周报
|
|
31
|
+
- 待办状态：进行中 | 我的状态：已接受
|
|
32
|
+
- 提醒时间：2025-03-17 18:00
|
|
33
|
+
- 创建时间：2025-03-10
|
|
34
|
+
|
|
35
|
+
3. ☑️ 代码评审
|
|
36
|
+
- 待办状态：已完成 | 我的状态：已完成
|
|
37
|
+
- 创建时间：2025-03-01
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
### 工作流 2：按时间范围查询待办
|
|
43
|
+
|
|
44
|
+
**用户意图**："这个月创建的待办有哪些？"
|
|
45
|
+
|
|
46
|
+
**步骤：**
|
|
47
|
+
|
|
48
|
+
1. **按时间过滤获取列表**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{"create_begin_time": "2025-03-01 00:00:00", "create_end_time": "2025-03-31 23:59:59"}'`
|
|
49
|
+
|
|
50
|
+
2. **获取详情**（同工作流 1 的第 2、3 步）。
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
### 工作流 3：创建待办并分派给同事
|
|
55
|
+
|
|
56
|
+
**用户意图**："帮我创建一个待办，让张三下周一前完成需求文档"
|
|
57
|
+
|
|
58
|
+
**步骤：**
|
|
59
|
+
|
|
60
|
+
1. **通讯录查询**：通过 wecom-contact 技能查询张三的 userid，在返回结果中筛选姓名为"张三"的成员，获取其 userid。使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'`
|
|
61
|
+
|
|
62
|
+
2. **创建待办并分派**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo create_todo '{"content": "<待办的内容>", "follower_list": {"followers": [{"follower_id": "zhangsan", "follower_status": 1}]}, "remind_time": "2025-03-24 09:00:00"}'`
|
|
63
|
+
|
|
64
|
+
3. **展示结果**：
|
|
65
|
+
```
|
|
66
|
+
✅ 待办创建成功！
|
|
67
|
+
|
|
68
|
+
📝 内容：完成需求文档
|
|
69
|
+
👥 分派人：张三
|
|
70
|
+
⏰ 提醒时间：2025-03-24 09:00
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
> `follower_id` 必须来自 `wecom-contact` 技能的 `get_userlist` 接口返回的 `userid`，禁止自行猜测。若搜索结果有多个同名人员，需展示候选列表让用户确认。
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
### 工作流 4：标记待办完成
|
|
78
|
+
|
|
79
|
+
需要区分两种场景：**标记待办本身完成**（改 `todo_status`）和**标记我的参与状态为完成**（改 `user_status`）。
|
|
80
|
+
|
|
81
|
+
#### 场景 A：标记待办本身完成
|
|
82
|
+
|
|
83
|
+
**用户意图**："把'完成Q2规划文档'这个待办标记为完成" / "关闭这个待办"
|
|
84
|
+
|
|
85
|
+
1. **查找目标待办**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
|
|
86
|
+
2. **获取详情确认**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'`
|
|
87
|
+
3. **将待办状态改为已完成**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "todo_status": 0}'`
|
|
88
|
+
|
|
89
|
+
#### 场景 B：标记我的参与状态为完成
|
|
90
|
+
|
|
91
|
+
**用户意图**："我已经完成了这个待办" / "标记我的部分为完成"
|
|
92
|
+
|
|
93
|
+
1. **查找目标待办**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
|
|
94
|
+
2. **获取详情确认**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'`
|
|
95
|
+
3. **变更当前用户的参与状态为已完成**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'`
|
|
96
|
+
|
|
97
|
+
> **如何判断用户意图：** 如果用户说"标记完成"且该待办是自己创建的、没有其他分派人，通常指场景 A（标记待办本身完成）。如果该待办有多个参与人，用户可能只是想标记自己那部分完成（场景 B）。不确定时应向用户确认。
|
|
98
|
+
|
|
99
|
+
> 用户提供的是待办内容描述而非 ID，所以需要先通过 `get_todo_list` 和 `get_todo_detail` 查找再匹配。匹配到多个相似待办时，列出候选项让用户确认。
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
### 工作流 5：更新待办内容或提醒时间
|
|
104
|
+
|
|
105
|
+
**用户意图**："把那个需求文档的待办提醒时间改到下周五"
|
|
106
|
+
|
|
107
|
+
**步骤：**
|
|
108
|
+
|
|
109
|
+
1. **查找目标待办**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
|
|
110
|
+
|
|
111
|
+
再查详情：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'`
|
|
112
|
+
|
|
113
|
+
2. **确认目标后更新**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "remind_time": "2025-03-28 09:00:00"}'`
|
|
114
|
+
|
|
115
|
+
3. **展示结果**：
|
|
116
|
+
```
|
|
117
|
+
✅ 待办已更新！
|
|
118
|
+
|
|
119
|
+
📝 内容：完成需求文档
|
|
120
|
+
⏰ 新提醒时间：2025-03-28 09:00
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
### 工作流 6：删除待办
|
|
126
|
+
|
|
127
|
+
**用户意图**："删掉'代码评审'那个待办"
|
|
128
|
+
|
|
129
|
+
**步骤：**
|
|
130
|
+
|
|
131
|
+
1. **查找目标待办**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
|
|
132
|
+
|
|
133
|
+
再查详情：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'`
|
|
134
|
+
|
|
135
|
+
2. **向用户确认后删除**：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo delete_todo '{"todo_id": "TODO_ID"}'`
|
|
136
|
+
|
|
137
|
+
3. **展示结果**：
|
|
138
|
+
```
|
|
139
|
+
✅ 待办已删除：代码评审
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
> 删除前必须向用户确认，确认措辞示例："确认删除待办'代码评审'吗？删除后不可恢复。"
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
### 工作流 7：分页获取大量待办
|
|
147
|
+
|
|
148
|
+
当待办数量超过单页上限时，通过 `cursor` 循环分页拉取：
|
|
149
|
+
|
|
150
|
+
- 首次请求（不传 cursor）：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{"limit": 20}'`
|
|
151
|
+
|
|
152
|
+
如果没有拉取完，还有更多的待办，会返回 has_more=true, next_cursor="CURSOR_1"
|
|
153
|
+
|
|
154
|
+
- 第二次请求（传入上次的 next_cursor）：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{"limit": 20, "cursor": "CURSOR_1"}'`
|
|
155
|
+
|
|
156
|
+
返回 has_more=false，拉取完毕
|
|
157
|
+
|
|
158
|
+
**分页规则：**
|
|
159
|
+
- 首次请求不传 `cursor`
|
|
160
|
+
- `has_more` 为 `true` 时，将 `next_cursor` 作为下次请求的 `cursor` 传入
|
|
161
|
+
- `has_more` 为 `false` 时停止请求
|
|
162
|
+
- 分页过程中时间过滤参数保持不变
|
|
163
|
+
- **如果选择不继续翻页（比如当前页数据已经够用），必须告诉用户还有更多待办未显示，问用户是否需要继续查看**
|