dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-shared/references/workflow-routing.md

@@ -0,0 +1,45 @@
+# 跨产品编排路由
+
+仅在请求包含多个时序步骤、跨产品数据传递、批量采集、汇总分析或报告交付时读取。
+当前发布包不包含独立 scenario skill；跨产品请求由本文件选择行动指南，再组合产品
+skill 完成。
+
+## 选择顺序
+
+1. 按下表选择与用户目标最匹配的产品行动指南。
+2. 显式读取流程涉及的产品 `SKILL.md`，不要预加载无关产品。
+3. 前一步返回的真实 ID、URL 或结构化数据作为后一步输入。
+4. 只读采集可并行；依赖上一步输出的步骤、写操作和验证步骤必须保持顺序。
+
+## 产品行动指南
+
+| 场景 | 典型目标 | 读取目标 |
+|---|---|---|
+| 消息沟通 | 发消息、查聊天、建群、机器人/Webhook 推送 | [`01-messaging.md`](../../dingtalk-chat/references/01-messaging.md) |
+| 任务管理 | 创建/查询/完成待办、从来源提取任务 | [`02-task.md`](../../dingtalk-todo/references/02-task.md) |
+| 会议日程 | 日程、会议室、闲忙、改期 | [`03-meeting.md`](../../dingtalk-calendar/references/03-meeting.md) |
+| 文档知识 | 搜索、创建、编辑、分享文档和知识库分流 | [`04-document.md`](../../dingtalk-doc/references/04-document.md) |
+| 工作汇报 | 日报周报、日志、多源会议或项目报告 | [`05-reporting.md`](../../dingtalk-misc/references/05-reporting.md) |
+| 数据分析 | AI 表格读写、模板建表、统计报告 | [`06-data-analytics.md`](../../dingtalk-aitable/references/06-data-analytics.md) |
+| 听记与会后 | 摘要、转写、会后待办和通知 | [`07-minutes.md`](../../dingtalk-minutes/references/07-minutes.md) |
+| 通讯录 | 找人、部门、上下级、负责人和精确用户信息 | [`08-directory.md`](../../dingtalk-contact/references/08-directory.md) |
+
+## Lite 与 Full
+
+- 单一目标、短链路、无多源汇总：在
+  [lite-catalog.md](recipes/lite-catalog.md) 中只读取对应 recipe。
+- 涉及多源采集、批量处理、交叉分析、汇总/归纳或三个以上产品：使用上表的完整
+  行动指南，并按 [conventions.md](recipes/conventions.md) 执行批量和
+  ID 传递规则。
+- 产品 skill 已内联完整步骤时，直接执行其步骤，不再重复读取通用 recipe。
+
+## 多场景消歧
+
+- “催审批”是 OA 审批操作，走 `dingtalk-misc`，不是普通消息发送。
+- “会后/听记生成待办”优先听记场景，不是普通待办创建。
+- “安排日程/订会议室”走 calendar；“发起或预约视频会议”当前 CLI 不支持，请在钉钉客户端操作；“读取
+  会后内容”走 minutes。
+- “汇总多次会议/多个来源并生成报告”走工作汇报行动指南，不是单篇文档编辑。
+- “整理项目全部讨论”是跨源汇总；“编辑指定文档”才是单产品 doc 操作。
+
+仍有歧义时，读取 [intent-guide.md](intent-guide.md) 的相关章节，不要全文加载。

package/skills/dws/dingtalk-todo/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: dingtalk-todo
+description: 钉钉待办 / TODO。Use when 用户说 创建待办/TODO/任务提醒/指派任务/标记完成/查待办/紧急待办/循环待办/批量建待办/逾期待办。不做日报周报（走 dingtalk-misc）、审批（走 dingtalk-misc）、日程（走 dingtalk-calendar）。命令前缀：dws todo。
+metadata:
+  cli_version: ">=0.2.14"
+  category: product
+  requires:
+    bins:
+      - dws
+---
+
+# 钉钉待办 Skill
+
+## 执行契约
+
+- 执行第一个 `dws` 操作前完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)；当前任务已加载则不重复读取。
+- 先把请求拆成有序步骤，再逐步选入口。已知命令直接执行，不先查 Help、Schema 或 Shortcut Catalog；只有当前 leaf 的 flag 或安全语义确实不明时才查精确 leaf。
+- 所有命令加 `--format json`，按结构化业务返回判断结果。后续 ID 只取自本次真实返回；零匹配、多匹配或类型不明时停止并消歧。
+- 写操作遵循最终 Runtime gate。需要确认时先说明对象、动作和影响，用户确认后才追加 `--yes`；不要把 `--yes` 写入存储示例。
+- 写后必须核验。非幂等写超时、缺少稳定 ID 或读回失败时先查询对账，禁止盲目重放。
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "todo +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws todo <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service todo --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws todo +assign` | write | 按姓名给某人创建并指派一条待办（自动解析 userId） |
+| `dws todo +assign-multi` | write | 把一条待办按姓名一次性指派给多个人（自动把每个姓名解析成 userId） |
+| `dws todo +comment` | write | 添加待办评论并读回验证 |
+| `dws todo +create` | write | 创建待办并读回验证 |
+| `dws todo +created-todos` | read | 列出我创建的待办（我作为创建人 creator 发起的待办，而非分配给我执行的） |
+| `dws todo +due-today` | read | 列出我今天到期的待办 |
+| `dws todo +get` | read | 查询待办详情 |
+| `dws todo +get-my-tasks` | read | 查询当前组织下我的待办列表 |
+| `dws todo +get-related-tasks` | read | 一次性列出与我相关的全部待办（我作为创建人/执行人/参与人三种角色的并集，按 taskId 去重） |
+| `dws todo +list-attachment` | read | 查询待办任务的附件列表 |
+| `dws todo +list-comment` | read | 查询待办评论列表 |
+| `dws todo +list-sub` | read | 查询子待办列表 |
+| `dws todo +overdue` | read | 列出我已过期未完成的待办 |
+| `dws todo +remind` | write | 给自己创建一条带可选截止时间的待办 |
+| `dws todo +reminder` | write | 设置或清除待办提醒（仅终端回执） |
+| `dws todo +search` | read | 搜索与我相关的全部待办 |
+| `dws todo +todo-done` | write | 按标题关键词把我的某条待办标记完成（自动定位 taskId） |
+| `dws todo +update` | write | 更新待办并读回验证 |
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## 路由优先级
+
+上面的通用 Shortcut 优先规则只适用于**一个 Shortcut 完整覆盖当前步骤**的情况。不要因为请求里出现“创建”就默认使用 `+remind` / `+create`。
+
+1. **先选创建入口**：按姓名指派用 `+assign` / `+assign-multi`；给自己记一条且后续只有搜索、详情或清理时用 `+remind`；已有真实 `userId` 且只需创建、回读和清理时用 `+create`。
+2. **组合生命周期从原子创建开始**：创建后还要按状态/优先级/角色/日期/页码列举，或继续更新、完成/重开、提醒、评论、附件、成员、子待办、标签，或一次创建多个对象时，使用 `todo task create`。不要用创建 Shortcut 代替第一步。
+3. **后续按步骤选最窄入口**：聚合、搜索和核验完整由 Shortcut 覆盖时使用 `+get-my-tasks`、`+get-related-tasks`、`+due-today`、`+overdue`、`+search`、`+get`、`+complete`、`+reopen`、`+update`、`+comment`、`+reminder` 或 `+list-*`；需要原子特有参数、动态子资源 ID、多对象或中间状态时用原子命令。
+4. **确定性批量/汇总使用脚本**：批量创建、今天/明天/本周汇总、逾期扫描分别使用 bundled script。
+5. **跨步骤只传稳定 ID**：Shortcut 与原子命令可以共存，但只传递规范化后的 `taskId`、`commentId`、`attachmentId`、`tagCode`、`userId`；不要假设两类入口的完整返回结构相同。
+
+## Golden Routes
+
+| 用户意图 | 首选入口 | 关键结果 / 边界 |
+|---|---|---|
+| 给自己创建，随后只搜索、看详情或清理 | `dws todo +remind --task "<标题>" [--at "<截止ISO>"] --format json` | 自动解析当前用户；`--at` 是截止时间，不是提醒时间 |
+| “给张三建待办” | `dws todo +assign --to "张三" --task "<标题>" --format json` | 姓名必须唯一解析后才创建 |
+| “给张三、李四建同一条待办” | `dws todo +assign-multi --to "张三,李四" --task "<标题>" --format json` | 任一姓名不唯一则零写入 |
+| 已有 `userId`，只创建、回读和清理 | `dws todo +create --title "<标题>" --executors <USER_ID> [--due "<截止ISO>"] [--priority 10\|20\|30\|40] --format json` | 返回稳定 `taskId`，并读回核验标题 |
+| 创建后还要筛选、变更资源或创建多个对象 | `dws todo task create --title "<标题>" --executors <USER_ID> ... --format json` | 从 `result.taskId` 进入组合生命周期；不要以 `+remind` / `+create` 起步 |
+| 今天到期 / 已逾期 | `dws todo +due-today --format json` / `dws todo +overdue --format json` | 均有界拉全分页；空集合也是成功结果 |
+| 当前组织下我的执行待办 | `dws todo +get-my-tasks --all --status false --format json` | `--all` 达到 40 页仍未耗尽会失败，不伪装完整 |
+| 与我相关的全部待办 | `dws todo +get-related-tasks --format json` | 创建人、执行人、参与人三种角色并集，按 `taskId` 去重 |
+| 按标题关键词查询 | `dws todo +search --query "<关键词>" --format json` | 搜索与 list 不混用；跨全部分页匹配 |
+| 已知 `taskId` 查详情 | `dws todo +get --task-id <TASK_ID> --format json` | 详情必须回传同一个稳定 `taskId` |
+| 已知 `taskId` 完成 / 重开 | `dws todo +complete --task-id <TASK_ID> --format json` / `dws todo +reopen ...` | 先读当前状态，避免重复写，再读回核验 |
+| 只记得标题，标记完成 | `dws todo +todo-done --task "<关键词>" --format json` | 仅唯一命中时写；零个或多个候选均停止 |
+| 修改标题、截止时间或优先级 | `dws todo +update --task-id <TASK_ID> ... --format json` | 至少指定一个待改字段；写后逐字段核验 |
+| 设置独立提醒 | `dws todo +reminder --task-id <TASK_ID> --base-time customTime --at "<提醒ISO>" --format json` | 上游无提醒查询接口，只能返回终端写回执，`verified=false` |
+| 基于截止时间提前提醒 | `dws todo +reminder --task-id <TASK_ID> --base-time dueTime --due-date-offset -30 --format json` | 待办必须已有截止时间；偏移单位为分钟 |
+| 清除全部提醒 | `dws todo +reminder --task-id <TASK_ID> --clear --format json` | 清除写操作；不能与提醒参数混用 |
+| 批量创建 | `python scripts/todo_batch_create.py <todos.json> --dry-run` | 预览返回稳定 `planDigest`；执行必须提交用户确认的同一摘要，内容变化会在零调用时拒绝 |
+| 今天/明天/本周汇总 | `python scripts/todo_daily_summary.py today\|tomorrow\|week` | 走 `+get-my-tasks --all`，只纳入范围内且有截止时间的未完成待办 |
+
+## 低频原子能力
+
+组合请求先读 [组合生命周期](references/02-task.md)。以下常用原子命令已审定，直接执行，不要先猜别名或查 Help：
+
+| 意图 | 命令骨架 |
+|---|---|
+| 解析自己 / 姓名 | `dws contact user get-self --format json` / `dws aisearch person --query "<姓名>" --dimension name --format json` |
+| 创建 / 子待办 | `dws todo task create ...` / `dws todo task create-sub --parent-id <PARENT_ID> --title "<标题>" --executors <USER_ID> ...` |
+| 列表 / 详情 | `dws todo task list [--status true\|false] [--priority ...] [--role-types ...] [--page N --size N] ...` / `dws todo task get --task-id <TASK_ID>` |
+| 更新 / 完成或重开 | `dws todo task update --task-id <TASK_ID> ...` / `dws todo task done --task-id <TASK_ID> --status true\|false` |
+| 增删执行人 / 参与人 | `task add-executor` / `task remove-executor` / `task add-participant` / `task remove-participant`，均传真实 `taskId` 与 `userId` |
+| 评论 | `comment add` / `comment list` / `comment delete`；删除使用列表返回的真实 `commentId` |
+| 附件 | `task add-attachment --file <绝对路径>` / `task list-attachment` / `task remove-attachment` |
+| 提醒 | `task add-reminder` 添加单条；`task reset-reminder` 替换全部或清空 |
+| 标签 | `tag create` / `tag list` / `tag update` / `tag add` / `tag delete`；只使用真实 `tagCode` |
+| 删除待办 | `dws todo task delete --task-id <TASK_ID> --format json` |
+
+删除类操作必须由用户确认；若用户在当前请求中已明确授权“办完后删除/清理本次创建对象”，该授权只覆盖本次记录的精确 ID。附件上传会真实传输本地文件，不能用来试探权限。
+
+## 关键约束
+
+- 标题、URL、展示序号都不是 `taskId`。已知 ID 直接行动；未知 ID 用列表/搜索定位，零匹配或多匹配时停止。
+- 待办公开命令统一使用 `--task-id`；`--id` / `--ids` 只是隐藏兼容别名，不要写入新命令或示例。
+- 优先级：低=10、普通=20、较高/高/重要=30、紧急/最高/P0=40。
+- `--due` / `+remind --at` 表示 deadline；独立 reminder 必须走 `+reminder`。
+- 自定义时间提醒的原子 flag 是 `--reminder-time-stamp`；不要把 Shortcut 的 `--at` 套到 `task add-reminder`。
+- `task list` 使用 `--status`，不要写 `--done`；详情是 `task get`，不存在 `task detail`。
+- “待办标签”始终属于 Todo，使用 `dws todo tag ...`；绝不能解释成 Git tag、通讯录标签或其他产品标签。
+- 创建和评论是非幂等写。超时、缺少稳定 ID 或读回失败时保留“可能已提交/未核验”状态，先查询对账，禁止盲目重放。
+- 所有命令加 `--format json`；写 Shortcut 按 Runtime 安全契约确认，确认前不得自行附加 `--yes`。
+- 会后行动项来自听记时先走 `dingtalk-minutes`；OA 审批走 `dingtalk-misc`；时间块和会议走 `dingtalk-calendar`。
+
+## 按需参考
+
+- [局部意图消歧](references/intent-guide.md)
+- [轻量流程](references/lite-recipes.md)
+- [组合流程](references/02-task.md)
+- [完整命令参考](references/todo.md)

package/skills/dws/dingtalk-todo/references/02-task.md

@@ -0,0 +1,70 @@
+# Todo 组合生命周期
+
+当一个请求包含多个资源动作并需要传递 `taskId`、`commentId`、`attachmentId`、`tagCode` 或 `userId` 时使用本文件。先拆步骤，再逐步选择能完整覆盖当前步骤的 Shortcut 或原子命令；不要因为第一步是创建就让 `+remind` / `+create` 接管整个流程。
+
+## 通用骨架
+
+1. 列出完整动作序列和需要传递的 ID；同一链路使用同一个 profile。
+2. 选择创建入口：
+   - 按姓名创建并指派：`+assign` / `+assign-multi`。
+   - 给自己简单创建，后续只有搜索、详情或清理：`+remind`。
+   - 已有真实 `userId`，后续只有回读或清理：`+create`。
+   - 后续需要列表筛选、更新、完成/重开、提醒、评论、附件、成员、子待办、标签或多对象：使用原子 `task create`。
+3. 原子创建前解析执行人：未指定执行人用 `dws contact user get-self --format json`；指定姓名用 `dws aisearch person --query "<姓名>" --dimension name --format json`，唯一匹配后取 `userId`。
+4. 原子创建：
+
+   ```bash
+   dws todo task create --title "<标题>" --executors <USER_ID> [--priority 10|20|30|40] [--due "<截止ISO>"] [--recurrence "<规则>"] --format json
+   ```
+
+5. 原子创建只从成功响应的 `result.taskId` 取 ID；创建 Shortcut 从其成功业务结果的 `taskId` 取 ID。不要跨入口猜字段层级。
+6. 按下表执行后续步骤。Shortcut 完整覆盖一个步骤时可使用其核验能力；需要原子特有参数、动态子资源 ID、多对象或中间状态时使用原子命令。
+7. 只清理本次创建且账本中已有精确 ID 的对象。删除后用 `task get` 不存在或对应列表移除验证。
+
+## 步骤路由表
+
+| 当前步骤 | 首选条件 | 入口 / 核验 |
+|---|---|---|
+| 当前组织我的未完成待办 | 需要有界拉全 | `+get-my-tasks --all --status false` |
+| 与我相关的全部待办 | 需要按创建人/执行人/参与人合并去重 | `+get-related-tasks` |
+| 今天到期 / 逾期 | 需要完整聚合 | `+due-today` / `+overdue` |
+| 按标题关键词定位 | 需要跨页唯一匹配 | `+search --query "<关键词>"` |
+| 按状态/优先级/角色/日期/页码列举 | 需要指定筛选条件或控制分页 | `task list --status ... --priority ... --role-types ... --plan-finish-date-start ... --plan-finish-date-end ... --page N --size N`；`hasMore=true` 继续下一页 |
+| 已知 ID 查详情 | 需要稳定投影和 ID 核验 | `+get --task-id <TASK_ID>`；需要原始字段时用 `task get` |
+| 单次更新并读回 | Shortcut flags 完整覆盖 | `+update --task-id <TASK_ID> ...` |
+| 更新后还需中间列表或多对象对比 | 需要原子中间状态 | `task update --task-id <TASK_ID> ...`，再 `task get/list` |
+| 单次完成 / 重开并读回 | 不需要按状态列表检查 | `+complete` / `+reopen` |
+| 完成/重开后按状态列表确认，或处理多个/子待办 | 需要中间状态 | `task done --task-id <TASK_ID> --status true\|false`，再 `task list/get` |
+| 创建子待办 | 需要父 ID、执行人和子 ID | `task create-sub --parent-id <PARENT_ID> --title "<标题>" --executors <USER_ID> ...`，取 `result.taskId` |
+| 列出子待办 | 只需聚合读取 | `+list-sub --task-id <PARENT_ID>`；需要原始子 ID/状态时用 `task list-sub` |
+| 增删执行人 | 成员变更 | `task add-executor/remove-executor --task-id <TASK_ID> --executors <USER_IDS>`，再 `task get` |
+| 增删参与人 | 关注关系变更 | `task add-participant/remove-participant --task-id <TASK_ID> --participants <USER_IDS>`，再 `task get` |
+| 添加一条评论并读回 | 不需要删除评论 | `+comment --task-id <TASK_ID> --content "<内容>"` |
+| 多评论、评论 ID 或删除评论 | 需要动态评论 ID | `comment add --task-id <TASK_ID> --content "<内容>"`；`comment list --task-id <TASK_ID>`；从列表取真实 ID 后 `comment delete --task-id <TASK_ID> --comment-id <COMMENT_ID>` |
+| 上传附件 | 本地文件已存在 | `task add-attachment --task-id <TASK_ID> --file <绝对路径>`，再列附件 |
+| 查看或移除附件 | 只读可用 Shortcut；移除需要动态 ID | `+list-attachment --task-id <TASK_ID>`；需要 `attachmentId` 时用 `task list-attachment`，再 `task remove-attachment --task-id <TASK_ID> --attachment-id <ATTACHMENT_ID>` |
+| 添加或清除一条提醒意图 | Shortcut 参数完整覆盖 | `+reminder`；只报告终端写回执 |
+| 多提醒、整体替换或清空后继续重设 | 需要原子规则数组 | 截止偏移：`task add-reminder --base-time dueTime --due-date-offset -30`；自定义：`--base-time customTime --reminder-time-stamp "<提醒ISO>"`；替换/清空：`task reset-reminder [--reminder-rules '<JSON数组>']` |
+| 标签生命周期 | 需要真实 `tagCode` | `tag create --name "<名称>"`；`tag list`；改名 `tag update --user-tags '[{"code":"<TAG_CODE>","name":"<新名称>"}]'`；关联 `tag add --task-id <TASK_ID> --tag-codes <TAG_CODES>`；删除 `tag delete --tag-codes <TAG_CODES>` |
+| 删除待办 | 已获得本次授权和真实 ID | `task delete --task-id <TASK_ID>`，再 `task get` 验证不存在 |
+
+所有表中命令都加前缀 `dws todo` 和后缀 `--format json`。
+
+## 动态 ID 账本
+
+| ID | 只允许来自 | 禁止来源 |
+|---|---|---|
+| `taskId` | 原子 `task create/create-sub/get/list` 或 Todo Shortcut 的成功业务返回 | 标题、URL、展示序号、其他 case |
+| `commentId` | 同一 `taskId` 的 `+comment` 成功结果或 `comment list` 返回 | 评论文本或猜测 |
+| `attachmentId` | 同一 `taskId` 的 `task list-attachment` 返回 | 文件名或本地路径 |
+| `tagCode` | `todo tag create/list` 返回的 `result.userTags[].code` | 标签名或 Git tag |
+| `userId` | `contact user get-self` 或 `aisearch person` 的唯一匹配 | 姓名、`me/self`、其他 profile |
+
+“待办标签”只能调用 `dws todo tag ...`；禁止运行 `git tag`。本地待办附件只能调用 `dws todo task add-attachment`，不要改走 Drive。
+
+## 失败与恢复
+
+- `unknown command/flag`：查该精确 leaf 的 `--help` 后最多修正一次，不轮询相似命令。
+- 创建、评论等非幂等写超时或返回不明：保留“可能已提交”，先按标题/父 ID 查询对账，不自动重试。
+- 提醒接口没有查询能力：成功时只报告服务端接受写入；失败时保留原错误。
+- 任一步失败后仍按账本清理已创建的临时对象；未取得稳定 ID 的对象不得猜 ID 清理。

package/skills/dws/dingtalk-todo/references/intent-guide.md

@@ -0,0 +1,15 @@
+# Todo 局部意图消歧
+
+| 用户说 | 应该用 | 不要用 | 边界 |
+|---|---|---|---|
+| “帮我记一下明天要做的事” | `todo +remind` | `doc` | 这是个人待办；`--at` 写截止时间 |
+| “给自己留一个明天下午的时间块” | `calendar event create` | `todo` | 时间块属于日历事件 |
+| “明早 9 点提醒我提交周报” | 先创建待办，再用 `todo +reminder --base-time customTime --at ...` | 把 `+remind --at` 当提醒 | 独立提醒与截止时间是两种资源字段 |
+| “截止前 30 分钟提醒” | `todo +reminder --base-time dueTime --due-date-offset -30` | `calendar` | 待办必须先有截止时间 |
+| “每天重复提醒我” | `todo task create --due ... --recurrence ...`，必要时再加 reminder | 只写 reminder | recurrence 管重复待办；reminder 管单条待办提醒规则 |
+| “创建/改名/删除待办标签” | `dws todo tag create/update/delete` | `git tag`、通讯录标签、其他产品标签 | “待办标签”由 Todo 产品拥有；后续只传真实 `tagCode` |
+| “提交日报/周报” | `dingtalk-misc` | `todo` | 日志产品不是个人待办 |
+| “审批这个申请” | `dingtalk-misc` | `todo` | OA 审批任务与个人待办不同 |
+| “把会议行动项建成待办” | 先走 `dingtalk-minutes` 取真实行动项，再进入 Todo 创建路线 | 凭标题猜行动项 | 来源证据归听记，任务对象归 Todo |
+
+提醒写入目前没有对应的查询接口，成功响应只能证明服务端接受了写请求，不能声称已经读回核验规则。

package/skills/dws/dingtalk-todo/references/lite-recipes.md

@@ -0,0 +1,68 @@
+# Todo 单步与短流程
+
+用于单步 Todo 意图，也用于组合请求中被 Shortcut 完整覆盖的独立步骤。组合请求先按 [02-task.md](02-task.md) 拆分；涉及列表筛选、资源写入、多对象或动态子资源 ID 时，不要用创建 Shortcut 代替原子 `task create`。
+
+## 创建
+
+### 给自己
+
+```bash
+dws todo +remind --task "提交周报" --at "2026-08-19T18:00:00+08:00" --format json
+```
+
+`--at` 是截止时间。需要 9 点弹出独立提醒时，在取得 `taskId` 后再执行：
+
+```bash
+dws todo +reminder --task-id <TASK_ID> --base-time customTime --at "2026-08-19T09:00:00+08:00" --format json
+```
+
+### 按姓名指派
+
+```bash
+dws todo +assign --to "张三" --task "周五前提交排期" --format json
+dws todo +assign-multi --to "张三,李四" --task "周五前提交排期" --format json
+```
+
+姓名必须唯一解析。多人场景任一姓名失败时整条待办不会创建。
+
+### 已有 userId
+
+```bash
+dws todo +create --title "修复线上问题" --executors <USER_ID> --priority 40 --format json
+```
+
+成功结果必须含稳定 `taskId` 且 `verified=true`。缺少 ID、写后读回失败或超时都不能重放创建；先搜索/列表对账。创建后还要按状态/优先级/角色/日期/页码列举，或更新、完成/重开、提醒、评论、附件、成员、子待办、标签，或创建多个对象时，创建步骤改用原子 `task create`。
+
+## 查询与定位
+
+```bash
+dws todo +get-my-tasks --all --status false --format json
+dws todo +get-related-tasks --format json
+dws todo +search --query "周报" --format json
+dws todo +get --task-id <TASK_ID> --format json
+```
+
+- list 用于枚举，search 用于标题关键词，get 用于已知稳定 ID。
+- 空集合是正常成功；响应结构缺失、分页未耗尽或 ID 缺失必须失败。
+- 零匹配或多匹配时不得自行选择第一条。
+- 用户明确要求状态、优先级、角色、日期或页码筛选时，使用 `todo task list` 的对应 flag；不要先拉取无关数据再在本地猜范围。
+
+## 完成、重开与更新
+
+```bash
+dws todo +complete --task-id <TASK_ID> --format json
+dws todo +reopen --task-id <TASK_ID> --format json
+dws todo +update --task-id <TASK_ID> --title "新标题" --format json
+```
+
+只记得标题时用 `+todo-done --task "<关键词>"`；它只会在唯一命中时修改。单次变更优先使用这些自带读回的 Shortcut；需要中间列表、多对象对比或原子特有参数时切到 [组合生命周期](02-task.md) 的原子路线。
+
+## 汇总与批量
+
+```bash
+python scripts/todo_daily_summary.py today
+python scripts/todo_overdue_check.py
+python scripts/todo_batch_create.py todos.json --dry-run
+```
+
+批量脚本单批最多 30 条。先用 dry-run 展示精确批次和稳定 `planDigest`；取得用户对该摘要的明确确认后，执行时必须同时传 `--confirm-digest <PLAN_DIGEST>` 与 `--yes`。脚本重新规范化输入并核对摘要，不匹配时零调用拒绝；匹配后只把 Runtime 确认传给逐条创建，回读不携带该标记。输出保留逐项 ledger；`unknown` 表示写可能已提交，`unverified` 表示已有 `taskId` 但读回未通过，两者都需对账，不能自动重试。

package/skills/dws/dingtalk-todo/references/recipes/conventions.md

@@ -0,0 +1,44 @@
+# 业务域通用规范
+
+> 仅服务本 skill 已迁入的行动指南。安全门控、危险操作确认、`--format json` 等已在本 skill 的 `SKILL.md` 中定义，此处不重复。
+
+## 批量查询规范
+
+| # | 规范 |
+|---|------|
+| 1 | **并行查详情**：拿到多个 ID 后，用 `&` 合并到同一条 Shell 命令并行执行 + `wait`，**严禁逐条串行** |
+| 2 | **翻页**：分页接口须拉全直至无更多 |
+| 3 | **优先批量 API**：有批量接口则用批量；无则按 #1 并行 |
+| 4 | **群消息**：必须先 `chat search --query` 得 `openConversationId`，再 `chat message list --group <openConversationId> --time "<yyyy-MM-dd HH:mm:ss>" --direction older`；多群同条命令并行 |
+| 5 | **列表少轮次**：带条件搜索/列表 → 一次采全详情；**禁止**无新参数时重复同一 `list` / `search` |
+
+## 多源并行采集（公共模式）
+
+> recipe 引用方式：`按「多源并行采集」执行（关键词=<X>，时间=<Y>至<Z>）`。
+
+- 同条 Shell：`&` 并行 + `wait`；分页须采全。
+- 只保留与主题相关的数据，无关丢弃。
+- 有批量详情接口优先；否则并行拉详情（见上表 #1）。
+- 具体采哪些产品列表由对应 **行动指南 recipe** 与当前产品参考决定；不要引入本文档未覆盖的产品路线。
+
+## 字段术语与 ID 传递
+
+> list 返回 JSON 后，必须提取下表字段传给后续命令。**禁止用其他字段替代。**
+
+| 字段 | 来源 | 传递给 |
+|------|------|--------|
+| `taskUuid` | `minutes list` | `minutes get summary/info/batch --id(s)` |
+| `userId` | `aisearch person` / `contact user search` / `contact dept list-members` | `contact user get --ids`、`todo --executors`、`calendar --users` |
+| `deptId` | `contact dept search` | `contact dept list-members --ids <deptId1,deptId2...>`；多子部门时对每个子部门分别 `dept search` 取 id |
+| `nodeId` | `drive search` / `wiki node search` | `doc read/update --node`、`drive copy/move/rename/delete --node` |
+| `nodeId` | `wiki node list` 中的 folder 类型节点 / `wiki node create --type folder` | `wiki node list --folder`、`wiki node create --folder`、`drive upload --folder`、`drive copy/move --folder` |
+| `eventId` | `calendar event list` | `calendar event get/update --id` |
+| `processInstanceId` | `oa approval list-*` | `oa approval detail/approve --instance-id` |
+| `openConversationId` | `chat search` | `chat message list/send --group` |
+| `todoTaskId` | `todo task list` | `todo task update/done --task-id` |
+| `reportId` | `report inbox list` / `report outbox list` | `report entry get/stats --report-id` |
+| `baseId` / `tableId` | `aitable base search` | `aitable record query --base-id --table-id` |
+| `dentryUuid` | `drive list` / `drive mkdir` | `drive info/download/copy/move/rename/delete --node`、`drive list/mkdir/upload/copy/move --folder` |
+| `dentryId` | `drive info` 的数字字段 | 仅用于 `chat message send --dentry-id` |
+
+**ID 边界硬约束**：`dentryId` 通常是纯数字，只表示聊天文件消息需要的钉盘条目数字 ID；它不是父目录 ID。遇到 `drive --node/--folder`、`doc --node`、`wiki node --folder` 时，只能使用 `dentryUuid` / `nodeId` / 文档 URL。若当前上下文只有数字型 `dentryId`，必须先重新 `drive list` / `drive search` / `wiki node list` 获取正确 ID，不能把该数字直接代入后续命令。