Wecomcli Todo

企业微信待办事项管理技能

wecom-cli 是企业微信提供的命令行程序，所有操作通过执行 wecom-cli 命令完成。

概述

wecomcli-todo 提供企业微信待办事项的完整管理能力，包含以下功能：

1. 查询待办列表 - 按创建时间和提醒时间过滤，支持分页，返回待办概要信息 2. 获取待办详情 - 根据待办 ID 列表批量获取完整信息（含内容和分派人） 3. 创建待办 - 创建新的待办事项，可指定内容、分派人和提醒时间 4. 更新待办 - 修改已有待办的内容、分派人、状态或提醒时间 5. 删除待办 - 删除指定的待办事项 6. 变更用户待办状态 - 更改当前用户在某个待办中的状态（拒绝/接受/已完成）

命令调用方式

执行指定命令：

wecom-cli todo <tool_name> '<json_params>'

行为策略

查完列表必须查详情: get_todo_list 只返回待办 ID 和状态等概要信息，不包含待办的实际内容和分派人。对用户来说，没有内容的待办列表毫无用处——他们想知道的是"要做什么"，而不是一串 ID。因此，每次调用 get_todo_list 拿到结果后，都要紧接着用返回的 todo_id 列表调用 get_todo_detail 获取完整详情（内容、分派人等），然后再向用户展示。这不是可选步骤，而是完成用户请求的必要环节。

人员 ID 转姓名（关键步骤）: get_todo_detail 返回结果中的 follower_id 和 creator_id 都是系统内部 ID，直接展示给用户毫无意义——用户不认识这些 ID，只认识姓名。因此在向用户展示待办详情之前，必须先调用 wecomcli-contact 技能获取通讯录，将所有 follower_id 和 creator_id 匹配为真实姓名。具体做法：

wecom-cli contact get_userlist '{}'

如果通讯录中找不到某个 ID，展示时标注"未知用户(ID：xxx)"即可。

分页未拉完时必须提醒用户: get_todo_list 接口是分页的，不要求一次性拉完所有数据。但如果响应中 has_more 为 true，说明后面还有待办没有返回——这时你在展示当前结果的同时，必须明确告诉用户"还有更多待办未显示，是否需要继续查看？"。用户可能不知道后面还有数据，如果你不说，他们会以为看到的就是全部，这会导致遗漏重要待办。

重试策略: 遭遇"返回 HTTP 错误"或"HTTP 请求失败"时，主动重试，最多重试三次。

---

命令详细说明

1. 查询待办列表 (get_todo_list)

查询当前用户的待办列表，支持按时间过滤和分页。返回的是待办概要信息（不含内容和分派人）。

执行命令

wecom-cli todo get_todo_list '<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
}

返回字段说明

列表返回的是待办概要信息（不含内容和分派人）。拿到列表后，必须调用 get_todo_detail 获取完整详情再展示给用户。

---

2. 获取待办详情 (get_todo_detail)

根据待办 ID 列表批量查询完整详情，包含待办内容和分派人信息。

执行命令

wecom-cli todo get_todo_detail '<json格式的入参>'

入参说明

调用示例

wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'

返回格式

{
    "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"
        }
    ]
}

返回字段说明

---

3. 创建待办 (create_todo)

创建一个新的待办事项，可指定内容、分派人和提醒时间。

执行命令

wecom-cli todo create_todo '<json格式的入参>'

入参说明

调用示例

wecom-cli todo create_todo '{"content": "<待办的内容>", "remind_time": "2025-06-01 09:00:00"}'

返回格式

{
    "errcode": 0,
    "errmsg": "ok",
    "todo_id": "TODO_ID"
}

返回字段说明

---

4. 更新待办 (update_todo)

修改已有待办事项的内容、分派人、状态或提醒时间。

执行命令

wecom-cli todo update_todo '<json格式的入参>'

入参说明

调用示例

wecom-cli todo update_todo '{"todo_id": "TODO_ID", "content": "<待办的内容>", "remind_time": "2025-07-01 09:00:00"}'

返回格式

{
    "errcode": 0,
    "errmsg": "ok"
}

---

5. 删除待办 (delete_todo)

删除指定的待办事项。

执行命令

wecom-cli todo delete_todo '<json格式的入参>'

入参说明

调用示例

wecom-cli todo delete_todo '{"todo_id": "TODO_ID"}'

返回格式

{
    "errcode": 0,
    "errmsg": "ok"
}

删除操作不可撤销，执行前应向用户确认。

---

6. 变更用户待办状态 (change_todo_user_status)

更改当前用户在某个待办中的状态（拒绝/接受/已完成）。

执行命令

wecom-cli todo change_todo_user_status '<json格式的入参>'

入参说明

调用示例

wecom-cli todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'

返回格式

{
    "errcode": 0,
    "errmsg": "ok"
}

返回字段说明

---

典型工作流

完整的工作流步骤、命令示例和展示格式详见 examples/workflows.md

---

注意事项

1. todo_id 来源规则

• todo_id 必须来自 get_todo_list 返回的结果，禁止自行推测或构造
• 用户通常提供待办内容描述而非 ID，应先通过 get_todo_list 查列表再匹配
• 若匹配到多个相似待办，展示候选列表让用户确认

2. follower_id 来源规则

• follower_id 即 userid，必须通过 wecomcli-contact 技能的 get_userlist 接口获取
• 禁止根据用户姓名自行猜测 userid
• 若搜索结果有多个同名人员，展示候选列表让用户选择

3. 人员 ID 必须转姓名

• 返回结果中的 follower_id 和 creator_id 是系统内部标识，用户无法识别
• 展示待办详情前，先通过 wecom-cli contact get_userlist '{}' 获取通讯录
• 用通讯录的 userid 匹配 follower_id / creator_id，用 name 替换展示
• 如果通讯录中找不到某个 ID，展示时标注"未知用户(ID：xxx)"

4. 时间格式

• 所有时间参数使用 YYYY-MM-DD HH:mm:ss 格式
• 用户说"明天"、"下周一"等相对时间时，根据当前日期推算具体日期

5. 状态值含义

• 待办状态（todo_status）：0-已完成，1-进行中，2-已删除
• 用户状态（user_status）：0-拒绝，1-接受，2-已完成
• 分派人状态（follower_status）：0-拒绝，1-接受，2-已完成

6. follower_list 的格式（作为输入参数的时候）

    "follower_list": {
        "followers": [
            {
                "follower_id": "FOLLOWER_ID",
                "follower_status": 1
            }
        ]
    }

follower_id 即 userid，需要通过 wecomcli-contact 查询获取，禁止自行猜测或构造。

7. 破坏性操作确认

• 删除待办（delete_todo）前必须向用户确认
• 变更状态为"拒绝"（user_status=0）前建议向用户确认

8. 必须查详情

• get_todo_list 返回的是概要信息（不含内容和分派人），拿到列表后必须紧接着调用 get_todo_detail 获取完整内容再展示给用户，不要只展示列表概要

9. 分页未拉完必须提醒

• 如果返回的 has_more 为 true，在向用户展示结果时必须明确说明"还有更多待办未显示"并询问用户是否需要继续查看

10. 单次详情上限

• todo_id_list 最多传 20 个 ID，超过需要分批请求

11. 错误处理

• 若 errcode 不为 0，说明接口调用失败，告知用户 errmsg 中的错误信息

12. 通讯录查询

• 涉及分派人时，需先通过 wecomcli-contact 技能的 get_userlist 接口获取全量通讯录成员，再按姓名/别名本地筛选匹配出对应的 userid。该接口无入参，返回当前用户可见范围内的成员列表（含 userid, name, alias）

典型工作流

工作流 1：查看待办列表（标准三步流程）

用户意图："看看我最近的待办" / "我有哪些待办事项？" / "我还有多少事要做？"

步骤：

1. 获取待办列表（只有 ID 和状态，没有内容）：

wecom-cli todo get_todo_list '{}'

2. 用返回的 todo_id 列表获取完整详情（禁止跳过！）：

wecom-cli todo get_todo_detail '{"todo_id_list": ["返回的TODO_ID_1", "返回的TODO_ID_2"]}'

3. 通过 wecomcli-contact 获取通讯录，将 follower_id / creator_id 转为姓名：

wecom-cli contact get_userlist '{}'

用返回的 userlist 中的 userid 匹配 follower_id 和 creator_id，取 name 字段作为展示姓名。

4. 检查分页：检查第一步返回的 has_more 字段。如果为 true，在展示结果时必须提醒用户："以上是部分待办，还有更多待办未显示，需要我继续查看吗？"

展示格式（分派人和创建人必须显示为姓名，不是 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

---

工作流 2：按时间范围查询待办

用户意图："这个月创建的待办有哪些？"

步骤：

1. 按时间过滤获取列表：

wecom-cli todo get_todo_list '{"create_begin_time": "2025-03-01 00:00:00", "create_end_time": "2025-03-31 23:59:59"}'

2. 获取详情（同工作流 1 的第 2、3 步）。

---

工作流 3：创建待办并分派给同事

用户意图："帮我创建一个待办，让张三下周一前完成需求文档"

步骤：

1. 通讯录查询：通过 wecomcli-contact 技能查询张三的 userid，在返回结果中筛选姓名为"张三"的成员，获取其 userid。

wecom-cli contact get_userlist '{}'

2. 创建待办并分派：

wecom-cli todo create_todo '{"content": "<待办的内容>", "follower_list": {"followers": [{"follower_id": "zhangsan", "follower_status": 1}]}, "remind_time": "2025-03-24 09:00:00"}'

3. 展示结果：

✅ 待办创建成功！

📝 内容：完成需求文档
👥 分派人：张三
⏰ 提醒时间：2025-03-24 09:00

follower_id 必须来自 wecomcli-contact 技能的 get_userlist 接口返回的 userid，禁止自行猜测。若搜索结果有多个同名人员，需展示候选列表让用户确认。

---

工作流 4：标记待办完成

需要区分两种场景：标记待办本身完成（改 todo_status）和标记我的参与状态为完成（改 user_status）。

场景 A：标记待办本身完成

用户意图："把'完成Q2规划文档'这个待办标记为完成" / "关闭这个待办"

1. 查找目标待办：

wecom-cli todo get_todo_list '{}'

2. 获取详情确认：

wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'

3. 将待办状态改为已完成：

wecom-cli todo update_todo '{"todo_id": "TODO_ID", "todo_status": 0}'

场景 B：标记我的参与状态为完成

用户意图："我已经完成了这个待办" / "标记我的部分为完成"

1. 查找目标待办：

wecom-cli todo get_todo_list '{}'

2. 获取详情确认：

wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'

3. 变更当前用户的参与状态为已完成：

wecom-cli todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'

如何判断用户意图： 如果用户说"标记完成"且该待办是自己创建的、没有其他分派人，通常指场景 A（标记待办本身完成）。如果该待办有多个参与人，用户可能只是想标记自己那部分完成（场景 B）。不确定时应向用户确认。

用户提供的是待办内容描述而非 ID，所以需要先通过 get_todo_list 和 get_todo_detail 查找再匹配。匹配到多个相似待办时，列出候选项让用户确认。

---

工作流 5：更新待办内容或提醒时间

用户意图："把那个需求文档的待办提醒时间改到下周五"

步骤：

1. 查找目标待办：

wecom-cli todo get_todo_list '{}'

再查详情：

wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'

2. 确认目标后更新：

wecom-cli todo update_todo '{"todo_id": "TODO_ID", "remind_time": "2025-03-28 09:00:00"}'

3. 展示结果：

✅ 待办已更新！

📝 内容：完成需求文档
⏰ 新提醒时间：2025-03-28 09:00

---

工作流 6：删除待办

用户意图："删掉'代码评审'那个待办"

步骤：

1. 查找目标待办：

wecom-cli todo get_todo_list '{}'

再查详情：

wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID"]}'

2. 向用户确认后删除：

wecom-cli todo delete_todo '{"todo_id": "TODO_ID"}'

3. 展示结果：

✅ 待办已删除：代码评审

删除前必须向用户确认，确认措辞示例："确认删除待办'代码评审'吗？删除后不可恢复。"

---

工作流 7：分页获取大量待办

当待办数量超过单页上限时，通过 cursor 循环分页拉取：

• 首次请求（不传 cursor）：

wecom-cli todo get_todo_list '{"limit": 20}'

如果没有拉取完，还有更多的待办，会返回 has_more=true, next_cursor="CURSOR_1"

• 第二次请求（传入上次的 next_cursor）：

wecom-cli todo get_todo_list '{"limit": 20, "cursor": "CURSOR_1"}'

返回 has_more=false，拉取完毕

分页规则：

• 首次请求不传 cursor
• has_more 为 true 时，将 next_cursor 作为下次请求的 cursor 传入
• has_more 为 false 时停止请求
• 分页过程中时间过滤参数保持不变
• 如果选择不继续翻页（比如当前页数据已经够用），必须告诉用户还有更多待办未显示，问用户是否需要继续查看