@sunnoy/wecom 2.1.0 → 2.2.1

package/skills/wecom-edit-todo/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: wecom-edit-todo
+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_mcp` tool 对企业微信待办事项进行写操作，支持四种操作：创建待办、更新待办、删除待办、变更用户状态。
+
+## 行为策略
+
+**重试策略**: 遭遇"返回 HTTP 错误"或"HTTP 请求失败"时，主动重试，最多重试三次。
+
+---
+
+## 操作
+
+### 1. 创建待办
+
+创建一个新的待办事项，可指定内容、分派人和提醒时间：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo create_todo '<json格式的入参>'`
+
+**参数说明：**
+
+需要遵循 “注意事项”中的格式要求：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `content` | string | ✅ | 待办内容 |
+| `follower_list` | object | ❌ | 分派人列表，格式见注意事项第 7 条 |
+| `remind_time` | string | ❌ | 提醒时间，格式：`YYYY-MM-DD HH:mm:ss` |
+
+
+**调用示例：**
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo create_todo '{"content": "<待办的内容>", "remind_time": "2025-06-01 09:00:00"}'`
+
+**返回格式：**
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "todo_id": "TODO_ID"
+}
+```
+
+---
+
+### 2. 更新待办
+
+修改已有待办事项的内容、分派人、状态或提醒时间：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '<json格式的入参>'`
+
+**参数说明：**
+
+需要遵循 “注意事项”中的格式要求：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `todo_id` | string | ✅ | 待办 ID |
+| `content` | string | ❌ | 新的待办内容 |
+| `follower_list` | object | ❌ | 新的分派人列表（全量替换，非追加），格式见注意事项第 7 条。若要新增分派人，需先查出现有分派人，合并后一起提交 |
+| `todo_status` | number | ❌ | 新的待办状态：`0`-已完成，`1`-进行中。删除请使用 `delete_todo` |
+| `remind_time` | string | ❌ | 新的提醒时间 |
+
+**调用示例：**
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "content": "<待办的内容>", "remind_time": "2025-07-01 09:00:00"}'`
+
+**返回格式：**
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+---
+
+### 3. 删除待办
+
+删除指定的待办事项：
+
+使用 `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"}'`
+
+**返回格式：**
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+> 删除操作不可撤销，执行前应向用户确认。
+> 注意：`delete_todo` 与 `update_todo` 设置 `todo_status=2` 效果相同，优先使用 `delete_todo`。
+
+---
+
+### 4. 变更用户待办状态
+
+更改当前用户在某个待办中的状态（拒绝/接受/已完成）：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '<json格式的入参>'`
+
+**参数说明：**
+
+需要遵循 “注意事项”中的格式要求：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `todo_id` | string | ✅ | 待办 ID |
+| `user_status` | number | ✅ | 用户状态：`0`-拒绝，`1`-接受，`2`-已完成 |
+
+**调用示例：**
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'`
+
+**返回格式：**
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+---
+
+## 典型工作流
+
+### 创建待办并分派给同事
+
+用户问："帮我创建一个待办，让张三下周一前完成需求文档"
+
+1. 第一步：通过 wecom-contact-lookup 技能查询张三的 userid，在返回结果中筛选姓名为"张三"的成员，获取其 userid
+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"}'`
+
+> `follower_id` 必须来自 `wecom-contact-lookup` 技能的 `get_userlist` 接口返回的 `userid`，禁止自行猜测。若搜索结果有多个同名人员，需展示候选列表让用户确认。
+
+### 标记待办完成
+
+需要区分两种场景：**标记待办本身完成**（改 `todo_status`）和**标记我的参与状态为完成**（改 `user_status`）。
+
+#### 场景 A：标记待办本身完成
+
+用户问："把'完成Q2规划文档'这个待办标记为完成" / "关闭这个待办"
+
+1. 第一步：通过 wecom-get-todo-list 获取待办列表，找到目标待办的 todo_id。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
+2. 第二步：通过 wecom-get-todo-detail 获取详情，确认是目标待办。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'`
+3. 第三步：确认后，将待办状态改为已完成。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "todo_status": 0}'`
+
+#### 场景 B：标记我的参与状态为完成
+
+用户问："我已经完成了这个待办" / "标记我的部分为完成"
+
+1. 第一步：通过 wecom-get-todo-list 获取待办列表，找到目标待办的 todo_id。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
+2. 第二步：通过 wecom-get-todo-detail 获取详情，确认是目标待办。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'`
+3. 第三步：确认后，变更当前用户的参与状态为已完成。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'`
+
+> **如何判断用户意图：** 如果用户说"标记完成"且该待办是自己创建的、没有其他分派人，通常指场景 A（标记待办本身完成）。如果该待办有多个参与人，用户可能只是想标记自己那部分完成（场景 B）。不确定时应向用户确认。
+
+> 用户提供的是待办内容描述而非 ID，所以需要先通过 wecom-get-todo-list 和 wecom-get-todo-detail 查找再匹配。匹配到多个相似待办时，列出候选项让用户确认。
+
+### 更新待办内容或提醒时间
+
+用户问："把那个需求文档的待办提醒时间改到下周五"
+
+1. 第一步：查找目标待办。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`，再使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'`
+2. 第二步：确认目标后更新。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo update_todo '{"todo_id": "TODO_ID", "remind_time": "2025-03-28 09:00:00"}'`
+
+### 删除待办
+
+用户问："删掉'代码评审'那个待办"
+
+1. 第一步：查找目标待办。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`，再使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'`
+2. 第二步：向用户确认后删除。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo delete_todo '{"todo_id": "TODO_ID"}'`
+
+> 删除前必须向用户确认，确认措辞示例："确认删除待办'代码评审'吗？删除后不可恢复。"
+
+---
+
+## 注意事项
+
+1. **todo_id 来源规则**
+   - `todo_id` 必须来自 `wecom-get-todo-list` 返回的结果，禁止自行推测或构造
+   - 用户通常提供待办内容描述而非 ID，应先通过 wecom-get-todo-list 查列表再匹配
+   - 若匹配到多个相似待办，展示候选列表让用户确认
+
+2. **follower_id 来源规则**
+   - `follower_id` 即 `userid`，必须通过 `wecom-contact-lookup` 技能的 `get_userlist` 接口获取
+   - 禁止根据用户姓名自行猜测 userid
+   - 若搜索结果有多个同名人员，展示候选列表让用户选择
+
+3. **时间格式**
+   - 所有时间参数使用 `YYYY-MM-DD HH:mm:ss` 格式
+   - 用户说"明天"、"下周一"等相对时间时，根据当前日期推算具体日期
+
+4. **状态值含义**
+   - 待办状态（`todo_status`）：`0`-已完成，`1`-进行中，`2`-已删除
+   - 用户状态（`user_status`）：`0`-拒绝，`1`-接受，`2`-已完成
+   - 分派人状态（`follower_status`）：`0`-拒绝，`1`-接受，`2`-已完成
+
+5. **破坏性操作确认**
+   - 删除待办（`delete_todo`）前必须向用户确认
+   - 变更状态为"拒绝"（`user_status=0`）前建议向用户确认
+
+6. **错误处理**
+   - 若 `errcode` 不为 `0`，说明接口调用失败，告知用户 `errmsg` 中的错误信息
+
+7. **follower_list** 的格式（作为输入参数的时候）
+
+    ```json
+    "follower_list": {                    // 分派人列表
+        "followers": [                    // 注意里面还有一层是 "followers"，它的value才是真正的列表数组
+            {
+                "follower_id": "FOLLOWER_ID",      // 分派人id
+                "follower_status": 1              // 分派人状态：0-拒绝, 1-接受, 2-已完成
+            }
+        ]
+    }
+    ```
+    > `follower_id` 即 userid，需要通过 `wecom-contact-lookup` 查询获取，禁止自行猜测或构造。
+
+## 相关技能
+
+- **获取待办列表**：`wecom-get-todo-list` — 查询待办概要列表，获取 todo_id
+- **获取待办详情**：`wecom-get-todo-detail` — 根据 todo_id 获取完整内容
+- **通讯录查询**：`wecom-contact-lookup` 的 `get_userlist` — 获取成员 userid，用于 `follower_id`

package/skills/wecom-get-todo-detail/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: wecom-get-todo-detail
+description: 企业微信待办详情批量查询技能，根据待办 ID 列表获取完整信息（包含待办内容和分派人）。在用户说"看看这个待办的详情"、"待办内容是什么"、"这个待办分派给谁了"、"告诉我待办的具体信息"等需要查看待办完整内容的场景时使用。通常配合 wecom-get-todo-list 使用——先获取待办 ID 列表，再用本技能获取详情。
+---
+
+# 企业微信待办详情查询技能
+
+> `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` tool 根据待办 ID 列表批量查询完整详情，包含待办内容和分派人信息。
+
+## 行为策略
+
+**人员 ID 转姓名（关键步骤）**: 返回结果中的 `follower_id` 和 `creator_id` 都是系统内部 ID，直接展示给用户毫无意义——用户不认识这些 ID，只认识姓名。因此在向用户展示待办详情之前，必须先调用 `wecom-contact-lookup` 技能获取通讯录，将所有 `follower_id` 和 `creator_id` 匹配为真实姓名。具体做法：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取通讯录，在返回的 userlist 中，用 userid 字段匹配 follower_id / creator_id，取对应的 name。
+
+如果通讯录中找不到某个 ID，展示时标注"未知用户(ID: xxx)"即可。
+
+**重试策略**: 遭遇"返回 HTTP 错误"或"HTTP 请求失败"时，主动重试，最多重试三次。
+
+---
+
+## 调用方式
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '<json格式的入参>'`
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `todo_id_list` | array | ✅ | 待办 ID 列表，最多 20 个 |
+
+**调用示例：**
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'`
+
+## 返回格式
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "data_list": [
+        {
+            "todo_id": "TODO_ID",
+            "todo_status": 1,
+            "content": "完成Q2规划文档",
+            "follower_list": {
+                "followers": [
+                    {
+                        "follower_id": "FOLLOWER_ID",
+                        "follower_status": 1,
+                        "update_time": "2025-01-16 14:20:00"
+                    }
+                ]
+            },
+            "creator_id": "CREATOR_ID",
+            "user_status": 1,
+            "remind_time": "2025-06-01 09:00:00",
+            "create_time": "2025-01-15 10:30:00",
+            "update_time": "2025-01-16 14:20:00"
+        }
+    ]
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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.followers` | array | 分派人列表 |
+| `data_list[].follower_list.followers[].follower_id` | string | 分派人 ID（即 userid）— **展示前需通过 wecom-contact-lookup 转为姓名** |
+| `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 — **展示前需通过 wecom-contact-lookup 转为姓名** |
+| `data_list[].user_status` | number | 当前用户状态 |
+| `data_list[].remind_time` | string | 提醒时间 |
+| `data_list[].create_time` | string | 创建时间 |
+| `data_list[].update_time` | string | 更新时间 |
+
+---
+
+## 典型工作流
+
+### 列表 + 详情联合查询（三步缺一不可）
+
+用户问："看看我最近的待办" / "我有哪些待办事项？"
+
+1. 第一步：通过 wecom-get-todo-list 获取待办列表。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
+2. 第二步：根据返回的 todo_id 批量获取详情。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2", "TODO_ID_3"]}'`
+3. 第三步（不要跳过！）：通过 wecom-contact-lookup 获取通讯录，将 follower_id / creator_id 转为姓名。用返回的 userlist 中的 userid 匹配 follower_id 和 creator_id，取 name 字段作为展示姓名
+
+> 第三步是展示可读结果的前提。没有这一步，用户看到的是一串无意义的 ID 而非姓名。
+
+**展示格式（注意：分派人和创建人必须显示为姓名，不是 ID）：**
+
+```
+📋 您当前的待办事项（共 3 项）
+
+1. 🔵 完成Q2规划文档
+   - 待办状态：进行中 | 我的状态：已接受
+   - 提醒时间：2025-06-01 09:00
+   - 分派人：张三、李四
+   - 创建时间：2025-01-15
+
+2. 🔵 提交周报
+   - 待办状态：进行中 | 我的状态：已接受
+   - 提醒时间：2025-03-17 18:00
+   - 创建时间：2025-03-10
+
+3. ☑️ 代码评审
+   - 待办状态：已完成 | 我的状态：已完成
+   - 创建时间：2025-03-01
+```
+
+---
+
+## 注意事项
+
+1. **人员 ID 必须转姓名**
+   - 返回结果中的 `follower_id` 和 `creator_id` 是系统内部标识，用户无法识别
+   - 展示待办详情前，先使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取通讯录
+   - 用通讯录的 `userid` 匹配 `follower_id` / `creator_id`，用 `name` 替换展示
+
+2. **todo_id 来源规则**
+   - `todo_id` 必须来自 `wecom-get-todo-list` 返回的结果，禁止自行推测或构造
+   - 用户通常提供待办内容描述而非 ID，应先通过 `wecom-get-todo-list` 查列表再匹配
+
+3. **状态值含义**
+   - 待办状态（`todo_status`）：`0`-已完成，`1`-进行中，`2`-已删除
+   - 用户状态（`user_status`）：`0`-拒绝，`1`-接受，`2`-已完成
+   - 分派人状态（`follower_status`）：`0`-拒绝，`1`-接受，`2`-已完成
+
+4. **错误处理**：若 `errcode` 不为 `0`，告知用户 `errmsg` 中的错误信息
+
+5. **单次上限**：`todo_id_list` 最多传 20 个 ID，超过需要分批请求

package/skills/wecom-get-todo-list/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: wecom-get-todo-list
+description: 企业微信待办列表查询技能，支持按创建时间和提醒时间过滤，支持分页。在用户说"看看我的待办列表"、"我有哪些待办"、"这周的待办有哪些"、"最近有什么待办"、"查一下我的待办"、"列出所有待办"等需要浏览待办概览的场景时使用。注意：此技能仅返回待办概要信息（不含内容和分派人），如需完整详情请配合 wecom-get-todo-detail 使用。
+---
+
+# 企业微信待办列表查询技能
+
+> `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` tool 查询企业微信待办列表，支持按时间过滤和分页。
+
+## 行为策略
+
+**查完列表必须查详情**: 本接口只返回待办 ID 和状态等概要信息，不包含待办的实际内容和分派人。对用户来说，没有内容的待办列表毫无用处——他们想知道的是"要做什么"，而不是一串 ID。因此，每次调用 get_todo_list 拿到结果后，都要紧接着用返回的 todo_id 列表调用 `wecom-get-todo-detail` 获取完整详情（内容、分派人等），然后再向用户展示。这不是可选步骤，而是完成用户请求的必要环节。
+
+**分页未拉完时必须提醒用户**: 接口是分页的，不要求一次性拉完所有数据。但如果响应中 `has_more` 为 `true`，说明后面还有待办没有返回——这时你在展示当前结果的同时，必须明确告诉用户"还有更多待办未显示，是否需要继续查看？"。用户可能不知道后面还有数据，如果你不说，他们会以为看到的就是全部，这会导致遗漏重要待办。这是一个容易被忽略但后果严重的点，请务必执行。
+
+**重试策略**: 遭遇"返回 HTTP 错误"或"HTTP 请求失败"时，主动重试，最多重试三次。
+
+---
+
+## 调用方式
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '<json格式的入参>'`
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `create_begin_time` | string | ❌ | 创建开始时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `create_end_time` | string | ❌ | 创建结束时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `remind_begin_time` | string | ❌ | 提醒开始时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `remind_end_time` | string | ❌ | 提醒结束时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `limit` | number | ❌ | 最大返回数量，默认 10，最大 20 |
+| `cursor` | string | ❌ | 分页游标，首次请求不传，后续传入上次响应的 `next_cursor` |
+
+## 返回格式
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "index_list": [
+        {
+            "todo_id": "TODO_ID",
+            "todo_status": 1,
+            "user_status": 1,
+            "creator_id": "CREATOR_ID",
+            "remind_time": "2025-06-01 09:00:00",
+            "create_time": "2025-01-15 10:30:00",
+            "update_time": "2025-01-16 14:20:00"
+        }
+    ],
+    "next_cursor": "NEXT_CURSOR",
+    "has_more": false
+}
+```
+
+## 返回字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `index_list` | array | 待办列表 |
+| `index_list[].todo_id` | string | 待办唯一 ID |
+| `index_list[].todo_status` | number | 待办状态：`0`-已完成，`1`-进行中，`2`-已删除 |
+| `index_list[].user_status` | number | 用户状态：`0`-拒绝，`1`-接受，`2`-已完成 |
+| `index_list[].creator_id` | string | 创建人 ID |
+| `index_list[].remind_time` | string | 提醒时间 |
+| `index_list[].create_time` | string | 创建时间 |
+| `index_list[].update_time` | string | 更新时间 |
+| `next_cursor` | string | 下一页游标 |
+| `has_more` | boolean | 是否还有更多记录 |
+
+> 列表返回的是待办概要信息（不含内容和分派人）。拿到列表后，必须调用 `wecom-get-todo-detail` 获取完整详情再展示给用户。
+
+---
+
+## 典型工作流
+
+### 查看待办列表（标准两步流程）
+
+用户问："看看我最近的待办" / "我有哪些待办事项？" / "我还有多少事要做？"
+
+1. 第一步：获取待办列表（只有 ID 和状态，没有内容）。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{}'`
+2. 第二步（禁止跳过！）：用返回的 todo_id 列表调用 wecom-get-todo-detail 获取完整详情。使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_detail '{"todo_id_list": ["返回的TODO_ID_1", "返回的TODO_ID_2"]}'`
+
+两步缺一不可——只有拿到详情后，才能向用户展示有意义的待办内容。
+
+3. 第三步（条件执行）：检查第一步返回的 `has_more` 字段。如果为 `true`，在展示结果时必须提醒用户："以上是部分待办，还有更多待办未显示，需要我继续查看吗？"——不提醒的话，用户会以为这就是全部。
+
+### 按时间范围查询
+
+用户问："这个月创建的待办有哪些？"
+
+使用 `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"}'`
+
+### 分页获取大量待办
+
+当待办数量超过单页上限时，通过 `cursor` 循环分页拉取：
+
+- 首次请求（不传 cursor）：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{"limit": 20}'`，如果没有拉取完，还有更多的待办，会返回 has_more=true, next_cursor="CURSOR_1"
+- 第二次请求（传入上次的 next_cursor）：使用 `wecom_mcp` tool 调用 `wecom_mcp call todo get_todo_list '{"limit": 20, "cursor": "CURSOR_1"}'`，返回 has_more=false，拉取完毕
+
+**分页规则：**
+- 首次请求不传 `cursor`
+- `has_more` 为 `true` 时，将 `next_cursor` 作为下次请求的 `cursor` 传入
+- `has_more` 为 `false` 时停止请求
+- 分页过程中时间过滤参数保持不变
+- **如果选择不继续翻页（比如当前页数据已经够用），必须告诉用户还有更多待办未显示，问用户是否需要继续查看**
+
+---
+
+## 注意事项
+
+1. **时间格式**：所有时间参数使用 `YYYY-MM-DD HH:mm:ss` 格式，用户说"明天"、"下周一"等相对时间时，根据当前日期推算具体日期
+
+2. **状态值含义**
+   - 待办状态（`todo_status`）：`0`-已完成，`1`-进行中，`2`-已删除
+   - 用户状态（`user_status`）：`0`-拒绝，`1`-接受，`2`-已完成
+
+3. **错误处理**：若 `errcode` 不为 `0`，告知用户 `errmsg` 中的错误信息
+
+4. **必须查详情**：本接口返回的是概要信息（不含内容和分派人），拿到列表后必须紧接着调用 `wecom-get-todo-detail` 获取完整内容再展示给用户，不要只展示列表概要
+
+5. **分页未拉完必须提醒**：如果返回的 `has_more` 为 `true`，在向用户展示结果时必须明确说明"还有更多待办未显示"并询问用户是否需要继续查看。用户不知道后面还有数据，不提醒会导致遗漏