git:20260818.7ceff2c to git:20260819.88dccb9

48 added, 284 removed. Audit A to A.

---

name: wecomcli-todo

- description: 何时用:仅当用户明确指向企业微信待办(建企微待办、查企微待办)时使用;泛指记个待办/提醒默认走本地工具,不要误用。企微待办:创建、更新、更改参与人状态、获取待办列表、批量获取待办详情、删除。用户说"帮我创建一个待办"、"把这个任务分派给张三"、"标记待办完成"、"接受/拒绝这个待办"、"删掉那个待办"、"看看我有哪些待办"等需要对待办进行读写操作的场景时使用。

+ description: 何时用:仅当用户明确指向企业微信待办(建/查/改企微待办)时使用;泛指记个待办/提醒默认走本地工具,不要误用。企微待办:创建、删除或退出、完成、查询和筛选,以及修改标题、描述、参与人名单和截止时间。

metadata:

requires:

bins: ["wecom-cli"]

- cliHelp: "wecom-cli todo --help"

---

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

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

- ## 概述

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

- 1. **搜索 userid** - 根据姓名或别名搜索用户的 userid，用于在创建/更新待办、更改用户状态、查询待办列表时把姓名解析为 userid

- 2. **创建待办** - 创建新的待办事项，可指定内容、参与人、截止时间和提醒方式

- 3. **更新待办** - 修改已有待办的内容、参与人、待办状态、截止时间和提醒方式

- 4. **更改用户状态** - 更改某位参与人在某个待办中的状态（拒绝/接受/已完成）

- 5. **获取待办列表** - 获取指定用户的待办列表，支持按创建时间和提醒时间过滤

- 6. **获取待办详情** - 根据待办 ID 列表批量获取完整信息

- 7. **删除待办** - 删除指定的待办事项

- ## 命令调用方式

- 执行指定命令：

- ```bash

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

- ```

- ---

- ## 命令详细说明

- ### 1. 搜索 userid (search_todo_userid)

- 基础接口，根据姓名或别名搜索用户的 userid，用于在创建待办、更新待办时把用户姓名解析为 userid 进行传参。

- #### 执行命令

- ```bash

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

- ```

- #### 入参说明

- | 参数 | 类型 | 必填 | 说明 |

- |------|------|------|------|

- #### 调用示例

- ```bash

- wecom-cli todo search_todo_userid '{"keyword": "张三"}'

- ```

- #### 返回字段说明

- - 返回与关键字匹配的用户的 `userid`（可能为多个候选）。

- - 若有多个同名/相似用户，展示候选列表让用户确认后再使用；展示时只用姓名/别名/部门等可读信息区分，**禁止向用户暴露 `userid`**。

- - 拿到的 `userid` 用于 `create_todo` / `update_todo` 的 `follower_list`，仅供内部传参，不在对话中展示。

- - 调用前可先检查对话上下文是否已有该用户的 `userid`，若有则直接复用、无需再次查询；若本接口返回错误（查询失败、无结果等），则改用通讯录 `wecomcli-contact` 技能搜索（详见注意事项第 2 条）。

- ---

- ### 2. 创建待办 (create_todo)

- 创建一个新的待办事项，可指定内容、参与人、截止时间和提醒方式。

- #### 执行命令

- ```bash

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

- ```

- #### 入参说明

- | 参数 | 类型 | 必填 | 说明 |

- |------|------|----|-----------------------------------------------------------------|

- #### 调用示例

- ```bash

- wecom-cli 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`。

- #### 执行命令

- ```bash

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

- ```

- #### 入参说明

- | 参数 | 类型 | 必填 | 说明 |

- |------|------|------|----------------------------------------------------------|

- #### 调用示例

- ```bash

- wecom-cli 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)

- 更改某位参与人在某个待办中的状态（拒绝/接受/已完成）。

- #### 执行命令

- ```bash

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

- ```

- #### 入参说明

- | 参数 | 类型 | 必填 | 说明 |

- |------|------|------|------|

- #### 调用示例

- ```bash

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

- ```

- ---

- ### 5. 获取待办列表 (get_todo_list)

- 获取指定用户（由 `follower_id` 指定，可为任意用户）通过机器人的待办列表，支持当天前后一个月的待办，可按创建时间、提醒时间、截止时间和待办状态过滤。

- #### 执行命令

- ```bash

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

- ```

- #### 入参说明

- | 参数 | 类型 | 必填 | 说明 |

- |------|------|------|------|

- > **查询时间范围限制**：

- > - 用于筛选的时间（创建时间、提醒时间、截止时间）必须落在当天前后 30 天以内。

- > - 若仅按 `todo_status` 筛选而未传任何时间范围，则默认按「创建时间在当天前后 30 天内」查询。

- #### 调用示例

- ```bash

- wecom-cli 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)

+ > 执行任何 `wecom-cli` 命令前，必须先读取并完成 `wecomcli-shared` 技能的公共前置检查。

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

+ 使用 `wecom-cli` 管理企业微信待办。

- #### 执行命令

+ ## 查询与定位

- ```bash

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

- ```

+ - 查询范围仅限企业微信待办系统中已经存在的记录。

+ - 可按创建时间、截止时间、完成状态和标题/描述关键词查询；关键词是字面匹配，不是语义搜索。

+ - 用户问"我有哪些待办""未完成待办有哪些"或"接下来有哪些待办"时，使用 `todo list` 查询待办系统中的记录。

+ - 删除、完成或更新时，若上下文没有 `todo_id`，先用 `todo list` 定位；已有 `todo_id` 且需要确认最新详情或状态时，使用 `todo get`。

- #### 入参说明

+ ## 接口路由表

- | 参数 | 类型 | 必填 | 说明 |

- |------|------|------|------|

+ **[重要事项]** 执行任何操作前，必须先定位「接口路由表」指向的参考文档并完整读取，再执行命令，避免出现参数错误。严禁凭路由表描述或自身记忆猜测拼参数。

- #### 调用示例

+ | 用户意图 | 参考位置 |

+ |---|---|

+ | 创建待办（可选分派） | references/todo-create.md |

+ | 删除待办 / 退出待办 / 从我的待办中移除 | references/todo-delete.md |

+ | 完成当前用户自己的部分 / 将整条待办全部完成 | references/todo-finish.md |

+ | 已有 `todo_id` 时确认待办详情和最新状态 | references/todo-get.md |

+ | 查看待办列表；按创建时间、截止时间、完成状态或关键词筛选；为后续操作定位待办 | references/todo-list.md |

+ | 修改待办内容 / 分派人名单 / 截止时间（不含参与人状态） | references/todo-update.md |

- ```bash

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

- ```

+ ## `deadline` 对象规范

- #### 返回字段说明

+ 待办的截止时间统一以 `deadline` 对象表达。涉及"设置截止时间"、"修改截止时间"、"清空截止时间"或读取待办的截止信息时，按本节规范处理。

- | 字段 | 类型 | 说明 |

- |---------------------------------------------------------|--------|-----------------------------------|

- | `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 | 提醒方式列表，取值：`0`-不提醒，`1`-到期时，`3`-提前 15 分钟，`5`-提前 1 小时，`6`-提前 2 小时，`7`-提前 1 天，`8`-提前 2 天，`9`-提前 1 周 |

- | `data_list[].create_time` | string | 创建时间 |

- | `data_list[].update_time` | string | 更新时间 |

+ ### 结构

- ---

+ | 字段 | 类型 | 必填 | 语义 |

+ |---|---|---|---|

- ### 7. 删除待办 (delete_todo)

+ ### 在 deadline / remind_at_deadline 字段上的语义

- 删除指定的待办事项。

+ - **设置或修改 `deadline`**：整体可选；若提供则其内部 `type` 与 `value` 必填。

+ - **清空已设置的截止时间**：将 `deadline` 字段更新为空对象 `{}`；不更新该字段则保持原值不变。

+ - **作为返回字段**：未设置截止时间的待办，`deadline` 字段不返回或为 `null`。

+ - **提醒时机（`remind_at_deadline`）**：`remind_at_deadline` 与 `deadline` 是一对，必须一起出现——脱离 `deadline` 单独传 `remind_at_deadline` 不会生效，不要这么传。`remind_at_deadline` 只决定提醒**时机**，入参层面**没有"关闭提醒"这一档**（是否真正提醒由后台判断，可能因不满足条件而不提醒，以返回的 `extra_info` 为准）：

+ - `remind_at_deadline=true`（仅 `deadline.type=datetime` 可传）→ 在**截止时刻**提醒。

+ - `remind_at_deadline=false` 或不传 → 按**后台默认的提前时间**提醒（**不是关闭提醒**）。

+ - `deadline.type=date` 或未传 `deadline` 时不要传 `true`。

- #### 执行命令

+ ### 从用户输入推断 `deadline`

- ```bash

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

- ```

+ 日期/星期直接限定待办中的任务或事件时，也视为截止日期。例如"周三开会要带笔记本"应将周三写入 `deadline`。

- #### 入参说明

+ 1. **待办提醒时间 = 截止时间**：明确要"定时提醒的待办 / 到某时提醒的待办 / 待办提醒"且给出具体时刻时，用户预期提醒时间落为 `deadline.type=datetime`，并传 `remind_at_deadline=true`；只给日期或未给提醒/截止时间时不追问，不传 `remind_at_deadline=true`。

+ 2. **普通截止时间**：只说截止/到期时间，或给出任务发生日期时，仅填写 `deadline`、不传 `remind_at_deadline`；此时按后台默认提前时间提醒。

+ 3. **时间格式**：具体截止/提醒时刻 → `deadline.type=datetime`、`value="YYYY-MM-DD HH:mm:ss"`；只有截止日期 → `type=date`、`value="YYYY-MM-DD"`。

+ 4. **未提截止/提醒或任务发生时间**：`deadline` 整体不传，`remind_at_deadline` 也不传，不追问。

+ 5. **xx 时间截止，并提前 yy 提醒**：`deadline` 永远填用户说的 xx 截止时间，不要填提前后的提醒时间。当前入参不能直接设置"提前 yy"；创建/更新后用返回的 `extra_info` 判断系统提醒时间是否刚好满足 yy，不满足或无 `extra_info` 时回复：`目前不支持直接创建您需要的提醒时间，已为您设置截止时间为 XX，请到企业微信待办功能中手动修改提醒时间。`（XX 填本次 `deadline.value`）

- | 参数 | 类型 | 必填 | 说明 |

- |------|------|------|------|

- #### 调用示例

+ ### 示例

- ```bash

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

+ ```json

+ { "type": "date", "value": "2026-05-08" }

+ { "type": "datetime", "value": "2026-05-08 09:00:00" }

```

- ---

- ## 注意事项

- 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` 返回错误（如当前企业不适用等），则改用通讯录 `wecomcli-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` → `wecomcli-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 周 |

- ## pinvou3 增补行为要求

- - `get_todo_list` 只返回概要(无内容),拿到列表后必须紧接着用 `get_todo_detail` 查完整内容再展示,不要只展示 ID 列表

- - 响应 `has_more` 为 `true` 时,展示当前结果的同时必须告知"还有更多待办未显示"并询问是否继续

- - 删除待办、变更状态为"拒绝"前必须向用户确认

+ ### 特别注意

+ - 禁止将 `todo_id`（待办 ID）展示给用户。