dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-event/references/event-oa.md

@@ -0,0 +1,155 @@
+# OA 个人审批事件
+
+先读事件产品入口 [SKILL.md](../SKILL.md) 的命令规则、调用流和子进程契约。本参考覆盖当前公开的七个 OA 个人事件：审批实例发起、抄送、终止和完成，以及审批任务创建、完成和转交。
+
+<!-- dws-intent: event.listen.oa -->实时监听审批事件必须使用 `dws event consume` 长连接，不要轮询 OA 待办或审批实例列表来模拟事件。
+
+## Prerequisite
+
+OA 个人事件使用当前用户 OAuth 登录态。未登录或 token 失效时，先执行：
+
+```bash
+dws auth login
+```
+
+非默认组织使用全局 `--profile <corpId 或 profile 名>`。事件范围始终是该 OAuth 用户相关的全部 OA 事件，不需要也不接受审批人、发起人或审批模板选择参数。
+
+## Event catalog
+
+| 事件码 | 订阅规则 | 接收语义 | 必填参数 |
+|---|---|---|---|
+| `user_oa_approval_task_created` | `all` | 审批任务创建，发送给审批人 | 无 |
+| `user_oa_approval_task_finished` | `all` | 审批任务已完成 | 无 |
+| `user_oa_approval_task_redirected` | `all` | 审批任务已转交 | 无 |
+| `user_oa_approval_instance_started` | `all` | 审批实例已发起 | 无 |
+| `user_oa_approval_instance_cc` | `all` | 审批实例到达抄送节点，发送给被抄送人 | 无 |
+| `user_oa_approval_instance_terminated` | `all` | 审批实例已终止 | 无 |
+| `user_oa_approval_instance_finished` | `all` | 审批实例完成，发送给审批单发起人 | 无 |
+
+只承认上表 7 个 OA 事件码。CLI 为每个事件发送 `ruleType=all`、`filterRule={}` 的独立订阅请求；不要添加 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。
+
+## Intent mapping
+
+| 用户说 | 下一步 |
+|---|---|
+| “监听新的待我审批任务” / “有审批任务创建时通知我” | `dws event consume user_oa_approval_task_created --flatten -f ndjson` |
+| “审批任务完成时通知我” | `dws event consume user_oa_approval_task_finished --flatten -f ndjson` |
+| “审批任务被转交时通知我” | `dws event consume user_oa_approval_task_redirected --flatten -f ndjson` |
+| “有审批单发起时通知我” | `dws event consume user_oa_approval_instance_started --flatten -f ndjson` |
+| “有审批抄送给我时通知我” | `dws event consume user_oa_approval_instance_cc --flatten -f ndjson` |
+| “有审批单终止时通知我” | `dws event consume user_oa_approval_instance_terminated --flatten -f ndjson` |
+| “监听我发起的审批何时完成” / “审批实例完成时通知我” | `dws event consume user_oa_approval_instance_finished --flatten -f ndjson` |
+| “同时监听全部已公开 OA 事件” | 一个 consume 放入七个 OA event key，不加目标或过滤参数 |
+| “查看 OA 事件目录” | `dws event list --category oa` |
+| “查看 OA 事件输出字段” | 对对应事件运行 `dws event schema <event_key> --flatten` |
+
+三个审批任务事件分别表达任务已创建、已完成和已转交；四个审批实例事件分别表达实例已发起、到达抄送节点、已终止和已完成。`status` 和 `result` 保留服务端原值，不把当前样本值推断为完整枚举。
+
+## Commands
+
+查看稳定的扁平输出 schema：
+
+```bash
+dws event schema user_oa_approval_task_created --flatten
+dws event schema user_oa_approval_task_finished --flatten
+dws event schema user_oa_approval_task_redirected --flatten
+dws event schema user_oa_approval_instance_started --flatten
+dws event schema user_oa_approval_instance_cc --flatten
+dws event schema user_oa_approval_instance_terminated --flatten
+dws event schema user_oa_approval_instance_finished --flatten
+```
+
+单独监听一种事件：
+
+```bash
+dws event consume user_oa_approval_task_created --flatten -f ndjson
+dws event consume user_oa_approval_task_finished --flatten -f ndjson
+dws event consume user_oa_approval_task_redirected --flatten -f ndjson
+dws event consume user_oa_approval_instance_started --flatten -f ndjson
+dws event consume user_oa_approval_instance_cc --flatten -f ndjson
+dws event consume user_oa_approval_instance_terminated --flatten -f ndjson
+dws event consume user_oa_approval_instance_finished --flatten -f ndjson
+```
+
+同时监听七种事件：
+
+```bash
+dws event consume \
+  user_oa_approval_task_created \
+  user_oa_approval_task_finished \
+  user_oa_approval_task_redirected \
+  user_oa_approval_instance_started \
+  user_oa_approval_instance_cc \
+  user_oa_approval_instance_terminated \
+  user_oa_approval_instance_finished \
+  --flatten \
+  -f ndjson
+```
+
+多事件 consume 会为七个 event key 分别创建订阅和逻辑 consumer，并共享当前组织的 personal bus、远程连接、stdout 和生命周期。不要给 OA 命令加 `--query` 或 `--filter-json`；这两个 flag 只用于兼容的 IM 消息接收事件。
+
+## Output contract
+
+`--flatten` 模式的所有 OA 事件都包含以下顶层字段：
+
+```json
+{
+  "type": "user_oa_approval_task_created",
+  "event_id": "...",
+  "timestamp": 0,
+  "subscribe_id": "...",
+  "process_instance_id": "...",
+  "process_code": "...",
+  "title": "...",
+  "status": "RUNNING",
+  "create_time": 0,
+  "event_time": 0
+}
+```
+
+- `type` 是当前 event key；`event_id` 可用于去重；`timestamp` 是 transport 事件发生时间；`subscribe_id` 标识对应的独立订阅。
+- `process_instance_id` 是审批实例 ID，可传给 OA 审批命令的 `--instance-id`；`process_code` 是审批流程模板编码。
+- `create_time`、`finish_time` 和 `event_time` 都是毫秒时间戳。`event_time` 是审批业务事件时间，`timestamp` 是 transport 事件时间。
+- 七类事件的额外字段如下；具体事件始终以 `dws event schema <event_key> --flatten` 为准。
+
+| 事件 | 额外顶层字段 |
+|---|---|
+| `user_oa_approval_task_created` | `task_id` |
+| `user_oa_approval_task_finished` | `task_id`、`result`、`finish_time` |
+| `user_oa_approval_task_redirected` | `task_id`、`result`、`finish_time` |
+| `user_oa_approval_instance_started` | 无 |
+| `user_oa_approval_instance_cc` | 无 |
+| `user_oa_approval_instance_terminated` | `finish_time` |
+| `user_oa_approval_instance_finished` | `result`、`finish_time` |
+
+任务完成事件示例：
+
+```json
+{
+  "type": "user_oa_approval_task_finished",
+  "event_id": "...",
+  "timestamp": 0,
+  "subscribe_id": "...",
+  "process_instance_id": "...",
+  "process_code": "...",
+  "task_id": "...",
+  "title": "测试审批",
+  "status": "FINISHED",
+  "result": "agree",
+  "create_time": 0,
+  "finish_time": 0,
+  "event_time": 0
+}
+```
+
+- `task_id` 是当前审批任务 ID，可传给接受任务 ID 的 OA 审批命令。
+- `status` 和 `result` 是服务端字符串；不要只根据当前样本把 `RUNNING/FINISHED/TERMINATED` 或 `agree/redirect` 写成封闭枚举。
+- payload 缺失、为空、缺少对应事件的稳定 ID 或无法解析时，consume 会在 stderr 记录 warning，并把原始 transport envelope 写到 stdout，保证事件不被静默丢弃。
+- 不传 `--flatten` 时保持兼容 transport envelope，业务 payload 位于 `.data | fromjson`。需要联调完整原始协议时使用不带 `--flatten` 的 `-f raw` 或 `--debug-raw-events`。
+
+## Lifecycle
+
+- 单事件等待 `[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>`。
+- 七事件先保存七条 `[event] subscription event_key=<key> subscribe_id=<id>`，再等待 `[event] ready event_count=7 bus_pid=<pid>`。
+- 临时验证使用 `--max-events 1` 或 `--duration 10m`；任务完成后优雅结束 consume，本次新建的订阅会自动取消。
+- 外部停止已有订阅时先运行 `dws event stop <subscribe_id> --dry-run`，确认后再加 `--yes`。不要 `kill -9`，否则会跳过自动退订。

package/skills/dws/dingtalk-event/references/event-todo.md

@@ -0,0 +1,50 @@
+# Todo 待办事件
+
+<!-- dws-intent: event.listen.todo -->待办创建、更新或删除的实时变化使用 `dws event consume` 长连接；查询、创建、更新、完成或删除已有待办使用 `dws todo`，不要轮询待办列表模拟事件。
+
+## EventKey 与订阅范围
+
+| EventKey | 触发时机 | 典型入口 |
+|---|---|---|
+| `user_todo_task_create` | 当前用户相关的待办被创建 | `dws event consume user_todo_task_create --role-types executor --flatten -f ndjson` |
+| `user_todo_task_update` | 当前用户相关的待办被更新 | `dws event consume user_todo_task_update --role-types executor --flatten -f ndjson` |
+| `user_todo_task_delete` | 当前用户相关的待办被删除 | `dws event consume user_todo_task_delete --role-types executor --flatten -f ndjson` |
+
+`--role-types` 只接受 `creator`、`executor`、`participant`，可用逗号组合。省略时订阅三种角色的并集；例如只监听自己创建的待办使用 `--role-types creator`，只监听指派给自己执行的待办使用 `--role-types executor`。
+
+CLI 将角色范围规范化后下发为：
+
+```json
+{"roleTypes":["creator","executor","participant"]}
+```
+
+该对象就是订阅控制面的 `filterRule`。Todo 事件不接受 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`；这些参数不会替代 `roleTypes`。
+
+三个 EventKey 可以在一个 consume 进程中共享相同的角色范围：
+
+```bash
+dws event consume \
+  user_todo_task_create \
+  user_todo_task_update \
+  user_todo_task_delete \
+  --role-types executor \
+  --flatten --format ndjson
+```
+
+## 扁平输出
+
+三类事件都提供 `type`、`event_id`、`timestamp`、`subscribe_id`、`task_id`、`subject`、`creator_id` 和 `create_time`。
+
+- 创建与更新还提供 `executor_ids`、`participant_ids`、`priority`、`status_stage`、`plan_start_date`、`plan_finish_date`、`start_date`、`finish_date`、`description`、`source`、`source_id`、`biz_tag`、`parent_id`、`is_multi_executor` 和 `scene_type`。
+- 更新额外提供 `update_time` 与 `old_status_stage`。
+- 删除额外提供 `delete_time`。
+- `status_stage`：`0` 未开始、`1` 进行中、`2` 正常完成、`3` 异常完成。
+- 服务端返回 `null` 的可选时间或 `parent_id` 在扁平输出中省略。字段契约以 `dws event schema <event_key> --flatten` 为准。
+
+处理事件后若要读取完整待办或执行操作，把真实 `task_id` 交给 `dws todo` 对应命令；不要从标题猜任务 ID。事件监听本身不会创建、修改、完成或删除待办。
+
+## 生命周期与后端边界
+
+- 单事件等待 `[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>`；三事件组合保存每条 subscription 后等待 `[event] ready event_count=3 bus_pid=<pid>`。
+- 有界消费使用 `--max-events` 或 `--duration`；结束时使用 SIGTERM、关闭符合条件的管道 stdin，或让 bounded consume 自行退出。
+- DWS 订阅 SPI 路由到 `lippi-tdp` 的 `com.dingtalk.todo.service.TodoDwsSubscriptionService`，版本 `1.0.0`、协议组 `HSF`。CLI 不直连 HSF；订阅或取消失败时保留服务端错误与 trace 信息，不换 EventKey 或 subscribe_id 绕过重试保护。

package/skills/dws/dingtalk-event/references/event-voip.md

@@ -0,0 +1,69 @@
+# VoIP 个人通话邀请事件
+
+先读事件产品入口 [SKILL.md](../SKILL.md) 的命令规则、生命周期和失败处理。本参考覆盖当前公开的 VoIP 个人事件 `user_voip_call_receive_invite`。
+
+当前用户收到语音通话邀请时，使用 `dws event consume` 长连接实时监听，不轮询通话记录。
+
+## Event catalog
+
+| 事件码 | 订阅规则 | 接收语义 | 必填参数 |
+|---|---|---|---|
+| `user_voip_call_receive_invite` | `all` | 当前用户作为被叫收到语音通话邀请；服务端已将通话切换为会议模式 | 无 |
+
+CLI 使用当前用户 OAuth 身份创建 `ruleType=all`、`filterRule={}` 的订阅。不要添加 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。
+
+## Commands
+
+查看目录和稳定扁平 Schema：
+
+```bash
+dws event list --category voip
+dws event schema user_voip_call_receive_invite --flatten
+```
+
+开始监听：
+
+```bash
+dws event consume user_voip_call_receive_invite --flatten -f ndjson
+```
+
+测试时先由被叫用户登录并启动监听，等待 `[event] ready`；再由另一用户呼叫该被叫用户。需要有界取样时可加 `--max-events 1`。
+
+## Output contract
+
+`--flatten` 把服务端 camelCase payload 映射为稳定的 snake_case 顶层字段：
+
+```json
+{
+  "type": "user_voip_call_receive_invite",
+  "event_id": "...",
+  "timestamp": 0,
+  "subscribe_id": "...",
+  "biz_id": "VOIP_<roomId>_<calleeUid>",
+  "corp_id": "ding...",
+  "org_id": 0,
+  "target_uid": 0,
+  "call_id": "...",
+  "caller_uid": "0147333457361236773",
+  "caller_corp_id": "ding...",
+  "callee_uid": "digital-3559506650",
+  "callee_corp_id": "ding...",
+  "call_type": "conference",
+  "room_id": "...",
+  "create_time": 0,
+  "event_time": 0
+}
+```
+
+- `event_id` 是 transport 事件 ID；`biz_id` 是业务事件唯一 ID，同一事件重试时保持不变，业务去重优先使用 `biz_id`。
+- `target_uid` 是订阅并接收邀请的用户；正常情况下与 `callee_uid` 指向同一被叫用户。
+- `caller_uid` 与 `callee_uid` 按服务端协议以字符串输出，必须保留前导 `0`、连字符等原始内容，不要转换为数字。滚动发布期间 DWS 仍兼容旧的 Long payload，并统一投影为字符串。
+- `--flatten` 默认不输出敏感入会码 `room_code`，避免终端记录、`tee` 文件或 Agent 上下文意外泄露。
+- `create_time` 与 `event_time` 都是毫秒时间戳；前者是通话邀请创建时间，后者是业务事件时间。
+- payload 缺失、body 缺失、`bizid` 为空或无法解析时，consume 会在 stderr 输出 warning，并只把不含业务 payload 的基础事件字段写到 stdout，避免敏感值从异常回退路径泄露。
+- 不传 `--flatten` 时仍保持 transport envelope，但 DWS 会从 `.data` 中移除敏感 `roomCode`。只有服务端联调确需检查原始 payload 时，才显式添加 `--debug-raw-events`；不要持久化或传播入会码。
+- VoIP 事件的 `-f raw` 同样必须和 `--debug-raw-events` 一起使用，避免绕过默认脱敏。
+
+## Boundary
+
+DWS CLI 负责声明 EventKey、创建个人订阅、消费 Stream、输出稳定字段和管理生命周期。VoIP 服务端负责识别被叫用户、切换会议模式并投递真实事件；如果订阅创建成功但呼叫后没有事件，应携带 trace 与服务端团队核对 Provider、事件路由和 MQ 投递，不通过反复创建订阅绕过重试保护。

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

@@ -0,0 +1,113 @@
+---
+name: dingtalk-mail
+description: 钉钉邮箱读写、搜索、回复与转发。Use when 用户说发邮件/查邮件/回邮件/转发邮件/未读邮件/邮件搜索/邮箱附件。一句话发邮件时先用 dingtalk-contact 解析并确认收件人，再由本 skill 发送；不做钉钉消息（走 dingtalk-chat）、紧急通知（走 dingtalk-misc）。命令前缀：dws mail。
+metadata:
+  cli_version: ">=0.2.14"
+  category: product
+  requires:
+    bins:
+      - dws
+---
+
+# 钉钉邮箱 Skill
+
+## 前置条件 — 执行操作前必读
+
+> **CRITICAL — 执行任何 `dws` 操作前，MUST 先用 Read 工具完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。**该轻量文件包含全局执行契约、安全底线及 shared references 的按需加载导航；不要预加载其全部 references。
+
+> 命令参考：[mail.md](references/mail.md)。复杂搜索、附件、批量处理、草稿等多步邮件场景参考：[09-mail.md](references/09-mail.md)。
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "mail +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws mail <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service mail --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws mail +find-mail-user` | read | 按关键词搜索邮箱联系人并投影列表（姓名/昵称/邮箱/工号等） |
+| `dws mail +folder-list` | read | 列出顶层文件夹或指定父文件夹下的子文件夹 |
+| `dws mail +message` | read | 读取一封邮件的完整正文与附件元数据 |
+| `dws mail +messages` | read | 按请求顺序读取多封邮件并逐封验证身份 |
+| `dws mail +search-mail` | read | 按 KQL 关键词搜索邮件并投影列表（主题/发件人/时间/messageId） |
+| `dws mail +thread` | read | 读取完整邮件会话并精确验证 conversationId |
+| `dws mail +triage` | read | 列出或筛选邮件摘要，自动解析邮箱与收件箱 |
+| `dws mail +user-search` | read | 按关键词或工号搜索邮箱用户（仅企业邮箱） |
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## 意图表
+
+| 用户说 | 命令 |
+|--------|------|
+| "发邮件给 a@b.com" | `dws mail mailbox list --format json` → `dws mail message send --from <邮箱> --to a@b.com --subject "<标题>" --content "<正文>" --format json` |
+| "回复 / 全部回复 / 转发" | `dws mail message reply` / `reply-all` / `forward` |
+| "今天未读邮件" | `python scripts/mail_unread_summary.py` |
+| "带抄送发送" | `python scripts/mail_send_with_cc.py --to a@b.com --cc c@d.com --subject "<标题>" --body "<正文>"` |
+
+## 标准 SOP（必遵流程）
+
+> 命中以下意图**必须**按对应 SOP 顺序执行；**禁止**跳步、替换命令、编造 email/messageId。每条命令必须带 `--format json`。收件邮箱**必须**真实解析，**禁止**猜测。
+
+### SOP-1 拿邮箱（get-mailbox）
+
+**触发**：我的邮箱/发件需要邮箱/查邮件需要邮箱。
+
+1. **执行（必须）**：`dws mail mailbox list --format json`，取自己的 `email`（默认选企业邮箱 `type:ORG`）；查**他人**邮箱用 `dws mail user search --keyword "<姓名>" --format json`，**禁止**用 `mailbox list` 查他人。
+
+**禁止**：把 `mailbox list` 当作他人邮箱查询、猜测邮箱地址。
+
+### SOP-2 查 / 搜邮件（search-mail）
+
+**触发**：查邮件/搜邮件/某主题邮件/某人发的邮件。
+
+1. **拿邮箱（必须）**：先按 SOP-1 取 `email`；用户已明确提供可跳过。
+2. **执行（必须）**：浏览文件夹 `dws mail message list --email <邮箱> --limit <n> --format json`；KQL 搜索 `dws mail message search --email <邮箱> --query "<KQL>" --limit 20 --format json`（KQL 如 `subject:周报`、`from:alice@x.com`、`folderId:2`、`hasAttachments:true`，**只通过 `--query` 传**）。
+3. **取正文（必须）**：`dws mail message get --email <邮箱> --id <messageId> --format json`；`messageId` 从列表/搜索结果取，**禁止**编造。
+
+**禁止**：把 KQL 拆成多个 flag、跳过 `message list/search` 直接猜 messageId。
+
+### SOP-3 发邮件（send-mail）
+
+**触发**：发邮件/写邮件/群发。
+
+1. **发件邮箱（必须）**：`dws mail mailbox list` 取自己邮箱。
+2. **收件邮箱（必须）**：地址直接用；姓名按 [mail.md](references/mail.md) "查找他人邮箱地址"流程（`mail user search` 等）获取，**禁止**猜测。
+3. **执行（必须）**：`dws mail message send --from <发件邮箱> --to <收件邮箱> --subject "<主题>" --content "<正文>" --format json`；按需 `--cc`/`--attachment`/`--inline-attachment`。
+4. **验证（必须）**：从发送返回取真实 `internetMessageId`，执行 `dws mail message verify --email <发件邮箱> --internet-message-id <internetMessageId> --format json` 查发送状态；不要把普通 `messageId` 传给 verify。
+
+**禁止**：猜测收件邮箱、发送后不确认状态就答复"已发送"。
+
+### SOP-4 回复 / 转发（reply-forward）
+
+**触发**：回复邮件/回复全部/转发。
+
+1. **拿邮箱 + 原邮件（必须）**：SOP-1 取邮箱；用户未给 `messageId` 时**必须**先走 SOP-2 定位原邮件 `messageId`。
+2. **执行（必须）**：回复 `dws mail message reply --from <邮箱> --id <messageId> --content "<正文>" --format json`；回复全部用 `reply-all`；转发 `dws mail message forward --from <邮箱> --to <收件邮箱> --id <messageId> --content "<附言>" --format json`。
+
+**禁止**：未定位原邮件就回复/转发、编造 messageId。
+
+## 高频硬约束
+
+- 用户要"完整内容/看看这封邮件/正文"时，`message search` 命中后必须继续调用 `dws mail message get --email <邮箱> --id <messageId> --format json`；不要只列候选后停下。
+- 搜到多封邮件时，若用户给了明确主题、附件名、发件人或时间线索，先选最匹配的一封执行 `message get`；只有同等候选无法判断时才询问用户。
+- 附件链路固定三步：`message search` → `attachment list --email <邮箱> --id <messageId>` → `attachment download --email <邮箱> --message-id <messageId> --attachment-id <attachmentId> --name <文件名>`；不存在批量下载命令。
+- 写入类操作（发送、回复、转发、删除、批量移动）按安全策略确认；只读查看、搜索、附件列表、下载不需要确认。
+- 所有 `dws mail` 命令加 `--format json`，并复用同一封邮件的 `messageId`，不要重新搜索导致目标漂移。
+
+## 轨迹高频直达规则
+
+- 已被本页或 `09-mail.md` 精确覆盖的命令，直接执行；不要先探测 `contact`、`api`、`auth`、`profile`、Help 或 Schema。仅在命令真实报参数错误后，读取该命令的 leaf Help 一次。
+- 多条件 KQL 必须用显式 `AND`，例如收件箱附件邮件：`hasAttachments:true AND folderId:2`；不要把相邻条件当作隐式 AND。
+- 用户只要首个或任一单附件时，初始搜索后按相关性最多检查 3 个候选的 `attachment list`，下载命中附件并做一次本地存在性/大小检查后停止；若均未命中，只能说明已检查范围并询问是否继续翻页，不能断言不存在。用户要求全部/批量附件时，遍历全部匹配页和邮件，再逐个下载每个附件。
+- “创建邮箱联系人”属于邮箱个人通讯录，固定走 `dws mail contact create/list`，不要切到 `dingtalk-contact`。只有“按人名解析邮件收件地址”才走下方跨产品协作。
+- 用户要求用当前时间生成唯一标题且未指定显示格式时，使用紧凑格式 `date +%H%M%S`；只有用户明确要求 `HH:mm:ss` 等格式时才原样保留。
+- 批量删除邮件或将整会话移入已删除前，先展示精确目标和不含确认参数的命令预览并停止；用户明确确认后，执行流程仅对同一组参数追加 `--yes`。操作成功后只做一次针对原 ID 或唯一主题的回读，结果符合预期即停止。
+- 创建类返回了 `messageId`、`contactId` 或 `internetMessageId` 时，后续直接复用返回 ID；不要为了重新定位目标而做宽泛 list/search。
+- 一次精确回读已经证明目标状态后结束任务；若回读冲突，报告冲突和已执行命令，不扩大到低层 API 或其他产品继续试探。
+
+## 跨产品协作
+
+- 收件人是人名 → 先用 `dingtalk-contact` 取 `orgAuthEmail`
+- 钉钉内消息 → 切到 `dingtalk-chat`
+## 局部意图与短流程
+
+- [局部意图消歧](references/intent-guide.md)；[短流程](references/lite-recipes.md)。

package/skills/dws/dingtalk-mail/references/09-mail.md

@@ -0,0 +1,45 @@
+# 邮件
+
+> 邮件的 4 条 **lite** recipe：`mail-list-mailbox`、`mail-search`、`mail-send`、`mail-reply-forward`，见 [lite-recipes.md](./lite-recipes.md)。下列专用规则与消歧请在命中邮件场景且**超出**上述 lite 时阅读本文。
+> 产品命令见 [mail.md](./mail.md)。通用批量/并行见 [recipes/conventions.md](recipes/conventions.md)。
+
+## 专用规则（#9 非 lite 步骤必守）
+
+- **KQL 语法强制**：邮件搜索的查询条件**只能**通过 `--query` 参数以 KQL 语法传入（如 `subject:周报`），多条件必须写显式 `AND`（如 `hasAttachments:true AND folderId:2`）；**禁止臆造** `--subject`、`--sender`、`--from-address` 等不存在的 flag。详见 [mail.md](./mail.md) 中 KQL 查询字段说明。
+- **邮箱地址前置**：大部分邮件命令需要 `--email` 或 `--from` 参数，执行前**必须**先通过 `mail mailbox list` 获取当前用户邮箱，禁止猜测邮箱地址。
+- **查找他人邮箱**：需要获取某人邮箱地址时，**不要用 `mailbox list`**（只返回自己的），必须走三路并发查询流程（见 [mail.md](./mail.md) 中「查找他人邮箱地址」章节）。
+- **附件下载三步走**：先 `message search` 搜索邮件获取 messageId，再 `attachment list` 取附件 ID 和文件名，最后逐个 `attachment download`。用户只要首个/任一单附件时，初始最多检查 3 个相关候选；均未命中只能说明已检查范围并询问是否继续，不能断言不存在。用户要求全部/批量附件时，必须沿搜索游标遍历全部匹配页和邮件，再逐个下载每个附件。**不存在 `download_batch` / `download_all` 等批量下载命令，禁止编造**。
+- **危险操作确认**：`batch-delete` 执行前必须向用户确认，同意后加 `--yes`。
+
+## 与其他场景消歧
+
+- **"给某人发邮件"**（只知姓名不知邮箱）→ 先走「查找他人邮箱地址」三路并发，再 `mail-send`。
+- **"找某人邮箱"**（终点是获取邮箱地址）→ 三路并发查询，不走 `mail-search`。
+- **"搜某人发的邮件"**（终点是邮件内容）→ `mail-search`，KQL 用 `from:xxx`。
+- **"催+邮件"** → `mail-send` 发催促邮件，不是 #1 消息。
+- **"邮件+待办"** → 先 `mail-search` 找邮件内容，再走 #2 创建待办。
+
+## Recipe 速查（本表步骤，非 SKILL lite）
+
+| Recipe | 步骤 |
+|--------|------|
+| `mail-get` | `mail message get --email <邮箱> --id <messageId>` → 查看邮件完整内容（含正文） |
+| `mail-folder-list` | `mail folder list --email <邮箱>` → 列举文件夹；`--folder <id>` 查子文件夹 |
+| `mail-tag-list` | `mail tag list --email <邮箱>` → 列举邮件标签 |
+| `mail-thread-get` | `mail thread get --email <邮箱> --id <conversationId>` → 获取会话（邮件线程）详情 |
+| `mail-attachment-list` | `mail attachment list --email <邮箱> --id <messageId>` → 列举指定邮件的附件 |
+| `mail-attachment-download` | 1. `mail attachment list --email <邮箱> --id <messageId>` → 取附件 `id` 和 `name`<br>2. `mail attachment download --email <邮箱> --message-id <messageId> --attachment-id <attachmentId> --name <文件名>` |
+| `mail-batch-move` | `mail message batch-move --email <邮箱> --ids <id1,id2,...> --folder <folderId>`（常用 folderId: 2=收件箱, 6=已删除） |
+| `mail-batch-delete` | 确认前仅展示 `mail message batch-delete --email <邮箱> --ids <id1,id2,...>` 和精确目标并停止；明确确认后由执行流程对相同参数追加 `--yes` |
+| `mail-draft-create` | `mail draft create --from <邮箱> --subject "<标题>"` → 取 `messageId`（可选 `--to`、`--content`、`--cc`） |
+| `mail-draft-update` | `mail draft update --from <邮箱> --id <draftId> --subject "<新标题>"`（可选 `--content`、`--to`、`--cc`） |
+| `mail-draft-send` | `mail draft send --from <邮箱> --id <draftId>` |
+
+## Full / 多步组合
+
+| Recipe | 行动指南（固定路线） |
+|--------|---------------------|
+| search-and-download-attachment | 1. `mail mailbox list` → 取邮箱<br>2. `mail message search --email <邮箱> --query "<KQL>" --limit 10`；多条件用显式 `AND`<br>3. 首个/任一单附件：按相关性最多检查 3 个候选，命中后进入第 4 步；未命中则说明范围并询问是否继续翻页<br>4. 全部/批量附件：沿 `nextCursor` 遍历全部匹配页，对每封执行 `attachment list`<br>5. 对命中附件逐个执行 `mail attachment download --email <邮箱> --message-id <messageId> --attachment-id <attachmentId> --name <文件名>`；单附件做一次本地检查后停止，全部/批量请求完成全部逐项下载（**不存在批量下载命令**） |
+| search-reply-forward | 1. `mail mailbox list` → 取邮箱<br>2. `mail message search --email <邮箱> --query "<KQL>" --limit 10` → 取 `messageId`<br>3. 展示搜索结果供用户选择<br>4. 按用户指示执行 reply / reply-all / forward（参见 lite `mail-reply-forward`） |
+| batch-mail-cleanup | 1. `mail mailbox list` → 取邮箱<br>2. `mail message search --email <邮箱> --query "<KQL>" --limit 100` → 取多个 `messageId`<br>3. 展示列表供用户确认<br>4. `mail message batch-move --email <邮箱> --ids <id1,id2,...> --folder 6 ` 移到已删除；或 `batch-delete` 永久删除 |
+| send-to-person-by-name | 1. `mail mailbox list` → 取发件邮箱<br>2. 走「查找他人邮箱地址」三路并发查询获取收件人邮箱（见 [mail.md](./mail.md)）<br>3. `mail message send --from <发件邮箱> --to <收件邮箱> --subject "<标题>" --content "<内容>"` |

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

@@ -0,0 +1,8 @@
+# mail 局部意图消歧
+
+本文件从单 Skill `intent-guide.md` 拆分而来，仅保留与本产品相关的跨产品消歧规则。
+
+| 用户说... | 真实意图 | 应该用 | 不要用 | 理由 |
+|---|---|---|---|---|
+| "搜一下智能化方案/最近 OKR 相关邮件/最近发版相关消息" | 搜企业知识内容 | `aisearch enterprise` | `doc search` / `mail search` / `chat message search` | 跨文档、消息、日程、听记、邮件等企业内容语义检索走 enterprise；具体 `queries/types/time-range` 抽槽见 `aisearch.md` |
+| "我发给某人的消息/邮件/文档/今天我干了什么" | 搜行为记录 | `aisearch behavior` | `chat` / `mail` / `doc` / `report` | 关注“谁对什么做过什么”，走 behavior；具体 `behavior-type/direction/chat-scope` 抽槽见 `aisearch.md` |

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

@@ -0,0 +1,45 @@
+# mail Lite Recipe
+
+本文件从单 Skill `lite-recipes.md` 拆分而来，仅保留与本产品相关的轻量流程。
+
+## #9 邮件
+
+### mail-list-mailbox
+
+查询当前用户自己的可用邮箱地址列表。**仅返回自己的邮箱**，不能查他人邮箱（查他人邮箱请走 [mail.md](./mail.md) 中「查找他人邮箱地址」三路并发查询流程）。
+
+`mail mailbox list`
+
+### mail-search
+
+搜索邮件。**必须使用 KQL 语法通过 `--query` 传递查询条件**，禁止臆造 `--subject`、`--from` 等不存在的 flag。
+
+1. 获取邮箱地址：`mail mailbox list` → 取用户邮箱地址。若用户已提供邮箱可跳过。
+2. 构造 KQL 查询：根据用户意图将搜索条件转为 KQL 表达式（详见 [mail.md](./mail.md) 中 KQL 查询字段说明）。
+   - 按主题：`subject:周报`、`subject:"项目 进展"`（含空格须加双引号）
+   - 按发件人：`from:alice@company.com` 或 `from:"张三"`
+   - 按日期：`date>2025-06-01T00:00:00Z`（ISO8601 格式，必须含时间部分）
+   - 按文件夹：`folderId:2`（2=收件箱, 1=已发送, 5=草稿, 6=已删除）
+   - 按是否有附件：`hasAttachments:true`
+   - 组合：`from:alice AND subject:周报 AND date>2025-06-01T00:00:00Z`
+3. 执行搜索：`mail message search --email <邮箱> --query "<KQL表达式>" --limit 20`
+4. 查看详情（按需）：`mail message get --email <邮箱> --id <messageId>`
+
+### mail-send
+
+发送邮件。
+
+1. 获取邮箱地址：`mail mailbox list` → 取用户邮箱作为 `--from`。
+2. 确定收件人：用户直接提供邮箱地址 → 直接使用；用户提供姓名或工号 → 走「查找他人邮箱地址」三路并发流程（见 [mail.md](./mail.md)）。
+3. 发送：`mail message send --from <发件邮箱> --to <收件邮箱> --subject "<主题>" --content "<正文>"`（可选 `--cc`、`--attachment`、`--inline-attachment`）。
+
+### mail-reply-forward
+
+回复或转发邮件。
+
+1. 获取邮箱地址：`mail mailbox list` → 取用户邮箱。
+2. 定位原始邮件：若用户未提供 messageId → 先用 `mail-search` 搜索定位。
+3. 执行：
+   - 回复：`mail message reply --from <邮箱> --id <messageId>`（可选 `--to`、`--subject`、`--content`）
+   - 回复全部：`mail message reply-all --from <邮箱> --id <messageId>`（可选 `--to`、`--subject`、`--content`）
+   - 转发：`mail message forward --from <邮箱> --to <收件邮箱> --id <messageId>`（可选 `--subject`、`--content`）