# 待办 (todo) 命令参考

## 命令总览

### 创建待办
```
Usage:
  dws todo task create [flags]
Example:
  dws todo task create --title "修复线上Bug" --executors <USER_ID_1>,<USER_ID_2> --priority 40
  dws todo task create --title "每日站会" --executors <USER_ID> --due "2026-03-20T10:00:00+08:00" --recurrence "DTSTART:20260320T020000Z\nRRULE:FREQ=DAILY;INTERVAL=1"
Flags:
      --due string         截止时间 ISO-8601 (如 2026-03-10T18:00:00+08:00；这是 deadline，不是 reminder)
      --executors string   执行者 userId 列表 (必填)
      --priority string    优先级: 10低/20普通/30较高/40紧急
      --recurrence string  循环待办 (需先设置 --due); 仅支持按天循环，格式见下方说明
      --title string       待办标题 (必填)
```

### 创建子待办
```
Usage:
  dws todo task create-sub [flags]
Example:
  dws todo task create-sub --parent-id <PARENT_TASK_ID> --title "子任务标题" --executors <USER_ID_1>,<USER_ID_2> --priority 40
  dws todo task create-sub --parent-id <PARENT_TASK_ID> --title "子任务标题" --executors <USER_ID> --due "2026-03-20T10:00:00+08:00"
Flags:
      --due string         截止时间 ISO-8601 (如 2026-03-10T18:00:00+08:00；这是 deadline，不是 reminder)
      --executors string   执行者 userId 列表 (必填)
      --parent-id string   父待办任务 ID (必填，该信息可以通过创建待办接口或者查询待办列表接口返回)
      --priority string    优先级: 10低/20普通/30较高/40紧急
      --recurrence string  循环待办 (需先设置 --due); 仅支持按天循环，格式见下方说明
      --title string       子待办标题 (必填)
```

### 查询待办列表
```
Usage:
  dws todo task list [flags]
Example:
  dws todo task list --page 1 --size 20
  dws todo task list --page 1 --size 20 --status false
  dws todo task list --page 1 --size 20 --status false --priority 40,30,10 --role-types creator,executor,participant --plan-finish-date-start "2026-03-01T00:00:00+08:00" --plan-finish-date-end "2026-03-10T18:00:00+08:00"
Flags:
      --page string                     页码 (默认 1)
      --plan-finish-date-end string     截止时间范围查询结束 ISO-8601 (如 2026-03-10T18:00:00+08:00)
      --plan-finish-date-start string   截止时间范围查询开始 ISO-8601 (如 2026-03-01T00:00:00+08:00)
      --priority string                 优先级: 10低/20普通/30较高/40紧急，支持逗号分隔多个值 (如 40,30,10)
      --role-types string               角色类型: creator/executor/participant，可同时传入多个值用逗号分隔（如 creator,executor），默认 executor
      --size string                     每页数量 (默认 20)
      --status string                   true=已完成, false=未完成
      --query-all                       true=查询全部待办,false=查询当前组织待办
```

参数说明：

| 参数 | 类型 | 说明 |
|------|------|------|
| `--priority` | string | 优先级筛选，支持逗号分隔多个值，如 `40,30,10` 表示同时筛选紧急、较高、低优先级 |
| `--role-types` | string | 按角色筛选，支持 `creator`（创建者）、`executor`（执行者）、`participant`（参与人）；可同时传入多个角色用逗号分隔（如 `creator,executor`），一次查询即可覆盖多个角色，无需分多次调用；默认为 `executor` |
| `--plan-finish-date-start` | string | 截止时间范围查询开始，ISO-8601 格式，需与 `--plan-finish-date-end` 成对使用 |
| `--plan-finish-date-end` | string | 截止时间范围查询结束，ISO-8601 格式，需与 `--plan-finish-date-start` 成对使用 |

### 修改待办任务
```
Usage:
  dws todo task update [flags]
Example:
  dws todo task update --task-id <taskId> --title "新标题"
  dws todo task update --task-id <taskId> --priority 40 --due "2026-03-10T18:00:00+08:00"
  dws todo task update --task-id <taskId> --done true
Flags:
      --done string       完成状态: true/false
      --due string        截止时间 ISO-8601 (如 2026-03-10T18:00:00+08:00；这是 deadline，不是 reminder)
      --priority string   优先级: 10低/20普通/30较高/40紧急
      --task-id string    待办任务 ID (必填)
      --title string      新标题
```

### 修改执行者的待办完成状态
```
Usage:
  dws todo task done [flags]
Example:
  dws todo task done --task-id <taskId> --status true
  dws todo task done --task-id <taskId> --status false
Flags:
      --status string    完成状态: true=已完成, false=未完成 (必填)
      --task-id string   待办任务 ID (必填)
```

### 待办详情
```
Usage:
  dws todo task get [flags]
Example:
  dws todo task get --task-id <taskId>
Flags:
      --task-id string   待办任务 ID (必填)
```

### 删除待办

> **CAUTION:** 不可逆操作 — 执行前必须向用户确认。

```
Usage:
  dws todo task delete [flags]
Example:
  dws todo task delete --task-id <taskId>
  dws todo task delete --task-id <taskId> --yes
Flags:
      --task-id string   待办任务 ID (必填)
```

### 新增待办评论
```
Usage:
  dws todo comment add [flags]
Example:
  dws todo comment add --task-id <taskId> --content "评论内容"
Flags:
      --task-id string   待办任务 ID (必填)
      --content string   评论内容 (必填)
```

### 查询待办评论列表
```
Usage:
  dws todo comment list [flags]
Example:
  dws todo comment list --task-id <taskId>
  dws todo comment list --task-id <taskId> --page 1 --size 20
Flags:
      --task-id string   待办任务 ID (必填)
      --page string      页码 (默认 1)
      --size string      每页数量 (默认 20)
```

### 删除待办评论

> **CAUTION:** 不可逆操作 — 执行前必须向用户确认。

```
Usage:
  dws todo comment delete [flags]
Example:
  dws todo comment delete --task-id <taskId> --comment-id <commentId>
  dws todo comment delete --task-id <taskId> --comment-id <commentId> --yes
Flags:
      --task-id string      待办任务 ID (必填)
      --comment-id string   评论 ID (必填)
      --yes                 跳过二次确认 (慎用)
```

### 添加待办执行人
```
Usage:
  dws todo task add-executor [flags]
Example:
  dws todo task add-executor --task-id <taskId> --executors <USER_ID_1>,<USER_ID_2>
Flags:
      --executors string   执行者 userId 列表 (必填)
      --task-id string     待办任务 ID (必填)
```
### 移除待办执行人
```
Usage:
  dws todo task remove-executor [flags]
Example:
  dws todo task remove-executor --task-id <taskId> --executors <USER_ID_1>,<USER_ID_2>
Flags:
      --executors string   执行者 userId 列表 (必填)
      --task-id string     待办任务 ID (必填)
```
### 添加待办参与人
```
Usage:
  dws todo task add-participant [flags]
Example:
  dws todo task add-participant --task-id <taskId> --participants <USER_ID_1>,<USER_ID_2>
Flags:
      --participants string   参与人 userId 列表 (必填)
      --task-id string        待办任务 ID (必填)
```
### 移除待办参与人
```
Usage:
  dws todo task remove-participant [flags]
Example:
  dws todo task remove-participant --task-id <taskId> --participants <USER_ID_1>,<USER_ID_2>
Flags:
      --participants string   参与人 userId 列表 (必填)
      --task-id string        待办任务 ID (必填)
```

### 查询子待办列表
```
Usage:
  dws todo task list-sub [flags]
Example:
  dws todo task list-sub --task-id <taskId>
Flags:
      --task-id string   待办任务 ID (必填)
```

### 上传待办附件

> ⚠️ 重要：该接口会上传文件到附件，不可用于测试或试探性调用。调用前必须确认待办存在。

```
Usage:
  dws todo task add-attachment [flags]
Example:
  dws todo task add-attachment --task-id <taskId> --file /path/to/file.pdf
Flags:
      --file string        本地文件路径 (必填)
      --task-id string     待办任务 ID (必填)
```

### 查询待办附件列表
```
Usage:
  dws todo task list-attachment [flags]
Example:
  dws todo task list-attachment --task-id <taskId>
Flags:
      --task-id string   待办任务 ID (必填)
```

### 删除待办附件

> **CAUTION:** 不可逆操作 — 执行前必须向用户确认。

```
Usage:
  dws todo task remove-attachment [flags]
Example:
  dws todo task remove-attachment --task-id <taskId> --attachment-id <attachmentId>
  dws todo task remove-attachment --task-id <taskId> --attachment-id <attachmentId> --yes
Flags:
      --attachment-id string   待办附件 ID (必填)
      --task-id string         待办任务 ID (必填)
```
附件 attachmentId 使用 `dws todo task list-attachment` 命令获取。

### 添加待办提醒
```
Usage:
  dws todo task add-reminder [flags]
Example:
  dws todo task add-reminder --task-id <taskId> --base-time dueTime --due-date-offset -30
  dws todo task add-reminder --task-id <taskId> --base-time customTime --reminder-time-stamp "2026-03-10T18:00:00+08:00"
Flags:
      --base-time string              提醒基准时间: dueTime/customTime (必填)
      --due-date-offset string        截止时间偏移量 (baseTime=dueTime 时必填)
      --reminder-time-stamp string    自定义提醒时间 ISO-8601 (如 2026-03-10T18:00:00+08:00；baseTime=customTime 时必填)
      --task-id string                待办任务 ID (必填)
```

参数说明：

| 参数 | 类型 | 说明 |
|------|------|------|
| `--base-time` | string | 提醒基准时间，必填。`dueTime` = 基于截止时间偏移；`customTime` = 自定义时间戳 |
| `--due-date-offset` | number | 截止时间偏移量（分钟），`baseTime=dueTime` 时必填。负数表示提前，如 `-30` 表示截止前 30 分钟 |
| `--reminder-time-stamp` | string | 自定义提醒时间，ISO-8601 格式（如 `2026-03-10T18:00:00+08:00`），`baseTime=customTime` 时必填 |

### 重置待办提醒
```
Usage:
  dws todo task reset-reminder [flags]
Example:
  dws todo task reset-reminder --task-id <taskId>
  dws todo task reset-reminder --task-id <taskId> --reminder-rules '[{"dueDateOffset":-30,"baseTime":"dueTime"},{"reminderTimeStamp":"2026-03-10T18:00:00+08:00","baseTime":"customTime"}]'
Flags:
      --reminder-rules string   提醒规则 JSON 数组 (可选，为空则清除提醒)
      --task-id string          待办任务 ID (必填)
```

`--reminder-rules` 数据结构说明：

JSON 数组，每个元素为一条提醒规则，支持两种 `baseTime` 模式混合使用：

| 字段 | 类型 | 说明 |
|------|------|------|
| `baseTime` | string | 提醒基准时间，必填。`dueTime` = 基于截止时间偏移；`customTime` = 自定义时间戳 |
| `dueDateOffset` | number | 截止时间偏移量（分钟），`baseTime=dueTime` 时必填。负数表示提前，如 `-30` 表示截止前 30 分钟 |
| `reminderTimeStamp` | string | 自定义提醒时间，ISO-8601 格式（如 `2026-03-10T18:00:00+08:00`），`baseTime=customTime` 时必填 |

示例：
```json
[
  {"dueDateOffset": -30, "baseTime": "dueTime"},
  {"reminderTimeStamp": "2026-03-10T18:00:00+08:00", "baseTime": "customTime"}
]
```
以上表示两条提醒规则：第一条在截止时间前 30 分钟提醒，第二条在指定时间（ISO-8601）提醒。

### 给待办打标签
```
Usage:
  dws todo tag add [flags]
Example:
  dws todo tag add --task-id <taskId> --tag-codes code1,code2
Flags:
      --tag-codes string   标签编码列表,最多支持2个，逗号分隔 (必填)
      --task-id string     待办任务 ID (必填)
```

### 删除待办标签
```
Usage:
  dws todo tag delete [flags]
Example:
  dws todo tag delete --tag-codes code1,code2
  dws todo tag delete --tag-codes code1,code2 --yes
Flags:
      --tag-codes string   要删除的标签编码列表,逗号分隔 (必填)
      --yes                跳过交互确认，直接执行删除
注意: ⚠️ 不可逆操作，执行前需用户确认；传 --yes 可跳过交互提示
```

### 更新待办标签
```
Usage:
  dws todo tag update [flags]
Example:
  dws todo tag update --user-tags '[{"code":"code1","name":"新名称"}]'
Flags:
      --user-tags string   标签列表 JSON 数组 (必填)
```

### 查询待办标签列表
```
Usage:
  dws todo tag list
Example:
  dws todo tag list
```

### 创建待办标签
```
Usage:
  dws todo tag create [flags]
Example:
  dws todo tag create --name "标签名"
Flags:
      --name string 标签名称 (必填)
```

## 意图判断

用户说"加个待办/记一下/TODO" → `task create`
用户说"每天重复/循环待办/按天重复" → `task create`（需 `--due` + `--recurrence`）
用户说"加个子任务/创建子待办" → `task create-sub`
用户说"看看待办/我有啥要做" → `task list`
用户说"改个待办/修改待办标题/改优先级" → `task update`
用户说"做完了/完成待办/标记完成" → `task done`
用户说"看看待办详情" → `task get`
用户说"删除待办/取消待办" → `task delete`
用户说"给待办加条评论/留个备注" → `comment add`
用户说"看看这个待办的评论" → `comment list`
用户说"删除这条评论" → `comment delete`
用户说"加个执行人/添加执行者" → `task add-executor`
用户说"移除执行人/删除执行者" → `task remove-executor`
用户说"加个参与人/添加参与者" → `task add-participant`
用户说"移除参与人/删除参与者" → `task remove-participant`
用户说"给待办加个提醒/设置提醒" → `task add-reminder`
用户说"重置提醒/清除提醒/修改提醒规则" → `task reset-reminder`
用户说"查看子待办/子任务列表" → `task list-sub`
用户说"给待办加个附件/上传附件" → `task add-attachment`
用户说"查看待办附件/附件列表" → `task list-attachment`
用户说"删除附件/移除附件" → `task remove-attachment`
用户说"给待办打标签/加个标签" → `tag add`
用户说"删除待办标签/移除标签" → `tag delete`
用户说"修改标签/更新标签信息" → `tag update`
用户说"看看标签/查看标签列表" → `tag list`
用户说"创建标签/新建标签" → `tag create`


关键区分: todo(个人待办)

## 核心工作流

```bash
# 1. 创建待办 — 提取 todoTaskId
dws todo task create --title "修复线上Bug" --executors userId1,userId2 \
  --priority 40 --due "2026-03-10T18:00:00+08:00" --format json

# 1b. 创建按天循环的待办（必须先有 --due；recurrence 与 MCP create_personal_todo 一致）
dws todo task create --title "每日站会" --executors userId1 \
  --due "2026-03-20T10:00:00+08:00" \
  --recurrence "DTSTART:20260320T020000Z\nRRULE:FREQ=DAILY;INTERVAL=1" --format json

# 1c. 创建子待办（需先获取父待办 ID）
dws todo task create-sub --parent-id <PARENT_TASK_ID> --title "子任务标题" --executors userId1 \
  --priority 40 --due "2026-03-10T18:00:00+08:00" --format json

# 2. 查看未完成待办
dws todo task list --page 1 --size 20 --status false --format json

# 3. 查看待办详情
dws todo task get --task-id <taskId> --format json

# 4. 修改待办信息
dws todo task update --task-id <taskId> --title "新标题" --priority 40 --format json

# 5. 标记待办完成
dws todo task done --task-id <taskId> --status true --format json

# 6. 删除待办
dws todo task delete --task-id <taskId> --yes --format json

# 7. 给待办新增评论
dws todo comment add --task-id <taskId> --content "已开始处理" --format json

# 8. 查看待办评论列表
dws todo comment list --task-id <taskId> --page 1 --size 20 --format json

# 9. 删除待办评论
dws todo comment delete --task-id <taskId> --comment-id <commentId> --yes --format json

# 10. 添加待办执行人
dws todo task add-executor --task-id <taskId> --executors userId1,userId2 --format json
# 11. 移除待办执行人
dws todo task remove-executor --task-id <taskId> --executors userId1 --format json
# 12. 添加待办参与人
dws todo task add-participant --task-id <taskId> --participants userId1,userId2 --format json
# 13. 移除待办参与人
dws todo task remove-participant --task-id <taskId> --participants userId1 --format json

# 14. 添加待办提醒（基于截止时间偏移，待办必须有截止时间）
dws todo task add-reminder --task-id <taskId> --base-time dueTime --due-date-offset <dueDateOffset> --format json
# 15. 添加待办提醒（自定义时间戳）
dws todo task add-reminder --task-id <taskId> --base-time customTime --reminder-time-stamp "2026-03-10T18:00:00+08:00" --format json
# 16. 重置待办提醒
dws todo task reset-reminder --task-id <taskId> --format json
# 17. 重置待办提醒（指定新规则）
dws todo task reset-reminder --task-id <taskId> --reminder-rules '<reminderRules>' --format json

# 18. 查询子待办列表
dws todo task list-sub --task-id <taskId> --format json
# 19. 上传待办附件
dws todo task add-attachment --task-id <taskId> --file /path/to/file.pdf --format json
# 20. 查询待办附件列表
dws todo task list-attachment --task-id <taskId> --format json
# 21. 删除待办附件
dws todo task remove-attachment --task-id <taskId> --attachment-id <attachmentId> --yes --format json

# 22. 查询待办标签列表
dws todo tag list --format json
# 23. 创建待办标签
dws todo tag create --name "标签名" --format json
# 24. 给待办打标签
dws todo tag add --task-id <taskId> --tag-codes code1,code2 --format json
# 25. 更新待办标签
dws todo tag update --user-tags '[{"tagCode":"code1","name":"新名称"}]' --format json
# 26. 删除待办标签
dws todo tag delete --tag-codes code1,code2 --yes --format json
```

## 上下文传递表

| 操作 | 从返回中提取 | 用于                                          |
|------|-------------|---------------------------------------------|
| `task create` | `todoTaskId` | update/done/get/delete 的 --task-id          |
| `task list` | `result[].id` | update/done/get/delete 的 --task-id          |
| `task create` | `todoTaskId` | update/done/get/delete/comment 的 --task-id  |
| `task list` | `result[].id` | update/done/get/delete/comment/add-executor/remove-executor/add-participant/remove-participant 的 --task-id |
| `task get` | `result.todoDetailModel.subTodos[]` | 获取子待办列表，提取子待办的 `taskId` 用于后续操作              |
| `comment list` | `result[].commentId` | `comment delete` 的 --comment-id             |
| `task list-attachment` | `result[].attachmentId` | `task remove-attachment` 的 --attachment-id |

## 注意事项

- 优先级值: 10=低, 20=普通, 30=较高, 40=紧急
- `--due` 是截止时间 dueTime，不是提醒时间；使用 ISO-8601 格式（如 2026-03-10T18:00:00+08:00）
- 当前不支持单独的 `reminder` / `remind-at` 精确提醒能力；不要把 `--due` 解释成“几点提醒”
- `--recurrence`：仅在与 `--due` 同时设置时有效；当前仅支持按天循环。字符串内需含换行，示例：`DTSTART:20260320T020000Z\nRRULE:FREQ=DAILY;INTERVAL=1`（DTSTART 表示首次截止时间，需与业务约定一致）
- 若用户的真实诉求是“到点提醒我”，需要先说明能力边界；当前 CLI 只能表达 deadline / recurrence，不能表达独立 reminder schedule
- `task list` 的 `--status` 对应 MCP `get_user_todos_in_current_org` 的 `todoStatus` 参数
- `task list` 的 `--priority` 支持逗号分隔多个优先级值（如 `40,30,10`），用于同时筛选多个优先级
- `task list` 的 `--role-types` 支持 `creator`/`executor`/`participant`，可在一次调用中同时传入多个角色用逗号分隔（如 `--role-types creator,executor`），无需分多次查询；不传时默认按 `executor` 查询
- `task list` 的 `--plan-finish-date-start` 与 `--plan-finish-date-end` 用于按截止时间范围筛选，需成对使用，格式为 ISO-8601
- todo 是个人待办管理产品
- `task update` 可同时修改标题/优先级/截止时间/完成状态
- `task done` 专用于修改执行者的完成状态，与 `task update --done` 作用不同
- `task delete` 为不可逆操作，建议加 `--yes` 并与用户确认
- `comment delete` 同样为不可逆操作，执行前需用户确认；`--comment-id` 可通过 `comment list` 获取
- `task add-executor` / `task remove-executor` 用于管理待办的执行人，`--executors` 支持逗号分隔的多个 userId
- `task add-participant` / `task remove-participant` 用于管理待办的参与人，`--participants` 支持逗号分隔的多个 userId
- 执行人 (executor) 与参与人 (participant) 的区别：执行人负责完成待办，参与人仅关注待办进度
- `task add-reminder` 用于为待办添加提醒，`--base-time` 支持 `dueTime`（基于截止时间偏移，待办必须有截止时间）和 `customTime`（自定义时间戳）两种模式
- `task reset-reminder` 用于重置待办提醒规则，不传 `--reminder-rules` 则清除所有提醒
- `task list-sub` 用于查询指定待办的子待办列表，需通过 `task list` 或 `task create` 获取父待办 ID
- `task add-attachment` 用于上传本地文件作为待办附件，`--file` 为本地文件绝对路径；该操作不可逆，调用前必须确认待办存在
- `task list-attachment` 用于查询指定待办的附件列表
- `task remove-attachment` 用于删除待办附件，为不可逆操作，执行前需用户确认；`--attachment-id` 可通过 `task list-attachment` 获取
- `tag list` 用于查询当前用户已有的标签列表，返回的 `tagCode` 可用于 `tag add` / `tag update` / `tag delete`
- `tag add` 用于给指定待办打标签，`--task-id` 可通过 `task list` 或 `task create` 获取；`--tag-codes` 可通过 `tag list` 获取
- `tag create` 用于创建新标签，`--name` 为标签名称 (必填)
- `tag update` 用于更新已有标签信息，`--user-tags` 格式同 `tag create`
- `tag delete` 用于删除标签定义，为不可逆操作，执行前需用户确认；传 `--yes` 可跳过交互提示，建议加 `--yes` 并与用户确认
- `tag add`（给待办打标签）与 `tag delete`（删除标签定义）作用不同：前者是关联关系，后者是删除标签本身


## 自动化脚本

| 脚本 | 场景 | 用法 |
|------|------|------|
| [todo_daily_summary.py](../scripts/todo_daily_summary.py) | 查看今天/明天/本周未完成待办汇总 | `python todo_daily_summary.py today` |
| [todo_batch_create.py](../scripts/todo_batch_create.py) | 从 JSON 文件批量创建待办 | `python todo_batch_create.py todos.json` |
| [todo_overdue_check.py](../scripts/todo_overdue_check.py) | 扫描逾期待办输出逾期清单 | `python todo_overdue_check.py` |