dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-drive/references/drive.md

@@ -0,0 +1,126 @@
+# Drive 低频能力参考
+
+仅在根 Skill 的 Golden Route 不足时读取本文件的一个相关章节。高频搜索、列表、检查、单文件传输和文件夹同步直接按根 Skill 执行。
+
+## 身份与目标位置
+
+- `--node`、`--folder`、`--remote-folder` 使用 dentryUuid/fileId；数字 dentryId 不能替代。
+- 回收站恢复使用 `recycleItemId`，不能复用删除前的 nodeId。
+- URL 类型不明时只执行一次 `dws drive info --node <URL> --format json`，按真实 nodeId/nodeType 分流。
+- 普通文件夹目标使用 `--folder`；明确知识库 workspace 才使用 `--workspace`。零命中、多候选或类型不明时停止。
+
+## Runtime 确认与首次执行
+
+- 先解析唯一目标，再以精确 leaf Schema 和 Runtime gate 判断是否需要确认；不要通过一次缺少 `--yes` 的失败调用探测确认要求。
+- Runtime 要求确认且当前请求已明确授权具体节点/文件夹、动作与影响时，首次正式远端写调用直接追加 `--yes`。诸如“整理一下”“处理这些文件”不能视为对删除、覆盖、移动或公开状态变更的精确授权。
+- Runtime 不要求确认时不添加 `--yes`。对象、范围或影响不完整时先询问；确认后必须保持同一 profile、目标、动作、范围和关键参数，任一项变化都要重新确认。
+- `--dry-run`、差异预览和只读检查不加 `--yes`；预览结果符合授权范围后，正式执行才追加。收到 `confirmation_required` 仅表示尚未通过预执行门禁，不代表业务写入成功，也不能据此盲目重放。
+
+## 高级目录列表
+
+普通浏览优先 `+list`。需要递归、名称模式、节点类型或修改时间过滤时使用 managed leaf：
+
+```bash
+dws drive list --folder <dentryUuid> --depth 2 --pattern "*周报*" --format json
+dws drive list --folder <dentryUuid> --type file --start 7d --format json
+```
+
+- `--depth` 最大 5；递归总量上限以结果中的 `truncated/errors` 为准。
+- `--type file|folder` 是节点类型；`search --file-types` 是内容类型，二者不同。
+- `--start/--end` 接受 `24h/7d/2w`、日期或 RFC3339，按修改时间过滤。
+- 过滤模式是客户端有界扫描；`truncated=true` 不能声称全量。需要关键词检索时改用 `+search`。
+- `--latest` 遇到截断或目录读取失败会拒绝给出不完整 Top-N，按错误中的目录和恢复命令缩小范围。
+
+## 非落盘下载地址
+
+Agent 沙箱跨文件系统、或外部系统要自行控制下载行为与时机时，用 managed leaf 加 `--url-only` 只换取临时下载地址与签名请求头，不落盘：
+
+```bash
+dws drive download --node <dentryUuid> --url-only --format json
+dws drive download-version --node <dentryUuid> --version 3 --url-only --format json
+```
+
+- `downloadUrl` 为带临时授权签名的链接，应尽快使用；`headers` 为需原样携带的签名请求头（OSS 预签名 URL 场景为空对象，签名已内含在地址里）；`fileName/fileSize/version` 为服务端携带时的辅助字段。
+- `--url-only` 与 `--output/--overwrite/--part-size/--parallel/--no-resume` 互斥；权限控制与现有下载链路一致；要把文件保存到本地路径时改用 `+download`。
+
+## 回收站
+
+```bash
+dws drive +delete --node <dentryUuid>
+dws drive +recycle-list --limit 20
+dws drive +recycle-restore --id <recycleItemId>
+```
+
+删除前核对名称、类型和 ID；恢复从列表真实返回取 `id`。恢复后使用返回的新 nodeId，不沿用旧 ID。
+
+## 普通文件历史版本
+
+| 意图 | 入口 | 完成证据 |
+|---|---|---|
+| 列版本 | `+version-history` | 版本集合与分页字段 |
+| 查看版本 | `+version-get` | 请求的 version |
+| 下载版本 | `+version-download` | 相对路径存在且 sizeBytes > 0 |
+| 回滚版本 | `+version-revert` | Runtime 确认后读回最新版本 |
+
+这些入口只用于普通文件。adoc 版本走 Doc，axls 版本走 Sheet。
+
+## 收藏、统计与封面
+
+- 收藏列表：`+star-list`；收藏/取消：`+star-add` / `+star-remove`。
+- 节点统计和封面优先并入 `+inspect --include-stats` / `--include-cover`；只取单项才用 `+stats` / `+cover`。
+- 收藏是个人状态，不代表共享或权限变化。
+
+## 普通文件评论
+
+普通 PDF、DOCX、XLSX 等本地文件使用 `dws drive comment`，复用 Doc/Sheet 的新评论服务链路。当前固定为文件级全文评论 `topicId=global`，不支持划词、单元格、页码、anchor 或 mention。
+
+旧 `drive comment list/create` 保留旧评论服务的行为和输出，仅作 deprecated 兼容入口。Agent 必须使用下面的 `list-v2/create-v2` 进入新评论体系。
+
+```bash
+dws drive comment list-v2 --node <dentryUuid> --format json
+dws drive comment create-v2 --node <dentryUuid> --content "请补充结论"
+dws drive comment list-replies --node <dentryUuid> --comment-key <commentKey> --format json
+```
+
+完整生命周期包括 `list-v2/create-v2/reply/update/delete/batch-query/list-replies/resolve/restore/react-reply`。分页游标必须原样回传；`list-v2` 每页上限为 50，超过上限直接报错；写操作按 Runtime confirmation 执行，后续操作的 `commentKey` 必须来自真实返回。
+
+## 公开状态
+
+```bash
+dws drive +publish-get --node <dentryUuid>
+dws drive +publish-unset --node <dentryUuid>
+```
+
+`+publish-get` 只读；`+publish-unset` 为高风险写。Runtime 虽注册了 `+publish-set`，但当前普通文件和在线文档都没有经过验证的开启公开闭环，因此根 Skill 明确不将它开放给 Agent。用户要求开启公开时，说明当前 Agent 路由不支持并停止；不要查询或执行 `+publish-set`、`drive publish set` 或其他替代写入口。只有补齐受支持节点上的真实 set→get→unset 闭环证据并更新 Agent 路由后，才重新开放该能力。
+
+## 权限
+
+| 意图 | managed leaf |
+|---|---|
+| 查看成员权限 | `drive permission list` |
+| 查询节点权限设置（权限模式/分享范围/策略） | `permission get-setting` |
+| 添加、修改、移除成员 | `permission add` / `update` / `remove` |
+| 转移所有者 | `permission transfer-owner` |
+| 查看可申请权限和审批人 | `permission apply-info` |
+| 发起权限申请 | `permission apply` |
+
+只在意图命中时读取一个精确 leaf Schema。成员变更、转移所有者、发起申请和公开状态变更必须明确节点、用户、角色与影响范围。转移所有者时，在构造最终命令前必须让用户分别明确决定 `--reserve-role <MANAGER|EDITOR|DOWNLOADER|READER|NONE>` 和 `--recursive=<true|false>`；Agent 不得根据默认值、对象类型或便捷性自行选择任一项。两项决策与目标、新所有者均明确后，才按 Runtime confirmation 构造首次正式调用。
+
+`permission get-setting` 返回 `permissionMode`（INHERITED/INDEPENDENT，未知时为 null）、`shareScope`（可见范围与链接分享，密码明文不返回；`partnerIncluded`、`defaultRole` 等仅 ORGANIZATION 有意义，`linkShare` 仅开启链接分享时返回）和 `policies[]`（code/name/description/value/disabledValues/allowedValues；name/description 为中文名与值语义说明，随行必带；未下发的策略不返回，`node_spread_scope` 仅文件夹）。`disabledValues` 为不可设置取值列表（恒返回，无被禁档位时为空数组），每项含 `value`（被禁档位取值，与 value 同一值域）与 `reason`（服务端按请求语言返回的禁用原因文案，仅供展示理解，可为 null），与 allowedValues 互斥；示例：`{"value": "READER_AND_ABOVE", "reason": "企业安全策略要求不可低于可下载角色"}`。`value` 按策略分型：开关型为 ENABLED/DISABLED；member_invite、comment 为 READER_AND_ABOVE/DOWNLOADER_AND_ABOVE/EDITOR_AND_ABOVE/MANAGER_AND_ABOVE；node_spread、online_content_copy 为 DOWNLOADER_AND_ABOVE/EDITOR_AND_ABOVE/MANAGER_AND_ABOVE 或 NOBODY；node_spread_scope 为 ALL_NODES（限制对所有文档生效）/ PREVIEWABLE_ONLY（仅对可预览的文档生效）。NOBODY=该操作对所有人禁止；XXX_AND_ABOVE=不低于该角色才允许。name/description 示例（文案与产品权限设置页一致）：external_share「添加企业外协作者」：是否允许添加企业外的人为协作者（ENABLED=允许，DISABLED=禁止）；node_spread「谁可以下载、创建副本、打印」：允许哪些角色及以上的用户下载、创建副本、打印；NOBODY=所有人禁止下载、创建副本、打印；node_move_forbidden「禁止移动」：是否禁止移动到其他知识库或团队共享文件夹（ENABLED=禁止移动，DISABLED=允许移动）。
+
+发起权限申请先只读执行 `permission apply-info`。正式 `permission apply` 会通知审批人；调用前必须向用户逐项回显并确认资源、申请角色、审批人和理由。Agent 不得默认选择第一位审批人、最高/最低角色或代写申请理由；用户未明确同意完整申请内容时停在确认环节。
+
+## 快捷方式节点
+
+`+create-shortcut --node <源ID> [--folder <目标ID>|--workspace <知识库ID>]` 创建链接。在线文档节点需要保留版式的独立副本时使用 `+copy`；普通钉盘文件的独立副本必须经用户授权后走 download→upload，因为当前 `+copy` 会拒绝普通文件。源/目标类型不兼容时停止，不把快捷方式当普通文件继续覆盖。
+
+## 错误恢复
+
+1. `unknown flag` 只查当前 leaf Help；`unknown command` 只查一次 Drive Shortcut 清单。
+2. 分页、递归或过滤未完成时保留 cursor/truncated/errors，不包装成全量成功。
+3. 写入超时或响应丢失先按 nodeId、名称、路径和大小回读，不能盲目重放。
+4. 在线文档误入普通下载/覆盖时切 Doc、Sheet 或 AITable；不要用 Drive 重试改变内容。
+
+## 辅助脚本
+
+- [drive_tree_list.py](../scripts/drive_tree_list.py)：递归列出钉盘目录树；普通浏览仍优先使用 `dws drive +list`。

package/skills/dws/dingtalk-drive/references/folder-sync.md

@@ -0,0 +1,40 @@
+# Drive 文件夹比较与同步
+
+仅用于本地目录与钉盘普通文件夹之间的递归文件级比较或镜像。单个文件使用根 Skill 的 `+download/+upload`。
+
+## 选择入口
+
+| 目标 | 唯一入口 |
+|---|---|
+| 只比较，不写任何一侧 | `dws drive status` |
+| 钉盘 → 本地 | `dws drive pull` |
+| 本地 → 钉盘 | `dws drive push` |
+| 两侧互相补齐 | `dws drive sync` |
+
+四个入口都要求 `--local-folder <绝对路径> --remote-folder <dentryUuid>`；`--space-id` 可选。动作已经明确时直接进入对应命令，不先重复执行 status。
+
+## 安全流程
+
+`status` 只读，可直接执行。`pull/push/sync` 会写本地或钉盘，先使用相同参数 `--dry-run` 查看计划；确认目标、方向和冲突策略后，再按 Runtime confirmation 执行。
+
+```bash
+dws drive status --local-folder /abs/local --remote-folder <folderId> --format json
+dws drive pull --local-folder /abs/local --remote-folder <folderId> --if-exists skip --dry-run --format json
+dws drive push --local-folder /abs/local --remote-folder <folderId> --if-exists skip --dry-run --format json
+dws drive sync --local-folder /abs/local --remote-folder <folderId> --on-conflict skip --dry-run --format json
+```
+
+## 策略
+
+- pull/push `--if-exists`: `skip` 是不覆盖的安全默认；`smart` 按修改时间做增量；`overwrite` 以来源侧覆盖目标侧。用户未明确选择覆盖策略时，Agent 必须保留 `skip`，不得代选 `smart/overwrite`；只有回显 dry-run 的覆盖项并得到明确授权后，才使用后两者。
+- sync `--on-conflict`: `skip` 默认保留两侧；`remote-wins` 覆盖本地；`local-wins` 覆盖远端；`keep-both` 先改名本地再拉远端；`ask` 需要交互。
+- 默认 exact 通过 MD5 比较；远端缺少可靠 MD5 时进入 `unknown` 并跳过。只有用户接受时间戳近似时才加 `--quick`。
+- 这些命令只处理普通 `type=file` 和目录；在线文档、快捷方式不会按普通二进制同步。
+- 文件级镜像只新增或覆盖，不删除任一侧多余文件。
+
+## 结果与恢复
+
+- status 检查 `new_local/new_remote/modified/unchanged/unknown`。
+- pull/push/sync 检查 summary 与逐条 items；任何 failed/unknown 必须保留，不把部分结果称为成功。
+- 下载先写临时文件再原子替换；失败时保留原目标。上传在提交前明确失败时直接返回。`push/sync` Runtime 遇到 `commit_upload` 超时、连接中断、空响应或畸形响应会直接返回错误，不会自动恢复，也不能据此断言未提交；Agent 必须把该项保留为 `unknown`，再用只读 list/inspect 按远端路径、名称和大小有限核对，无法证明时报告未知，不能直接重放可能已提交项。服务未同时提供源端与结果的可比哈希时，不虚构 checksum 验证。
+- dry-run 与正式执行必须使用同一 local-folder、remote-folder、space-id 和策略；不要在确认后静默改变方向或冲突策略。

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

@@ -0,0 +1,22 @@
+# Drive 局部意图消歧
+
+| 用户表达 | 应用 | 不应用 | 理由 |
+|---|---|---|---|
+| 全局找文件、最近文件、浏览已知“我的文件”/文档空间目录 | Drive | Wiki node | 未限定知识库 workspace，属于普通存储域 |
+| 列出/发现钉盘企业空间或“我的文件”空间 | managed `dws wiki space list --type orgSpace|mySpace` 发现 spaceId/rootFolderId 后回 Drive | `wiki +space-list` 的 orgWikiSpace/myWikiSpace | Drive 存储空间前置；spaceId、rootFolderId 与知识库 workspaceId 不可互换 |
+| 明确知识库内列节点、移动节点、搜索节点 | Wiki | Drive | workspace 内层级由 Wiki 管理 |
+| 普通文件或文件夹移动、重命名、删除 | Drive | Doc | 节点存储动作不修改正文 |
+| 普通文件创建独立副本 | Drive download→upload | Drive `+copy` | 当前 `+copy` 会拒绝普通钉盘文件，避免把 `.dlink` 快捷方式伪装成副本 |
+| adoc 正文读取、编辑或导出 | Doc | Drive download | Drive 只管理节点；在线文档需要格式转换 |
+| 本地 xlsx/xls/csv 节点下载后分析 | Drive + 本地工具 | Sheet range read | 上传的普通文件不是 axls 在线表格 |
+| axls 在线表格导出为 xlsx | Sheet export | Drive download | export 执行格式转换 |
+| able 记录、字段、视图 | AITable | Drive | 表内业务数据不属于存储节点动作 |
+| able 仅复制结构、删除 Base | AITable `+base-copy --base-id <ID> --target-folder-id <真实ID> --only-struct` / `+base-delete --base-id <ID>` | Drive copy/delete | 当前 main 要求真实目标文件夹 ID；缺少时停止，禁止发明 `--target-root`、完整复制后逐表删数据或用 Drive 猜根 ID |
+| Base 内 Table/Dashboard/Section 节点操作 | AITable `+table-*` / `+section-*` | Drive | nsheet 节点不是独立 Drive dentry |
+| 整个 Base 移到普通文件夹、外层存储重命名 | Drive | AITable 表内命令 | 这是 Base 外层存储位置/名称动作 |
+| PDF、DOCX、XLSX 等普通文件的评论查询或生命周期操作 | Drive `comment list-v2/create-v2/reply/update/delete/batch-query/list-replies/resolve/restore/react-reply` | Doc/Sheet comment | 默认进入新评论体系；普通文件固定使用文件级 global topic，不支持划词或单元格锚点；仅在用户明确要求旧评论兼容行为时使用 deprecated 的 `list/create` |
+| Word/Markdown/Text 转在线文档 | Doc `+import` | Drive upload | import 会创建在线文档；upload 只保留原文件 |
+| “上传文件”但未指定目标 | Drive `+upload` | — | 默认按普通文件上传到钉盘 |
+| “照这个文档做一份同样格式的” | Drive `+copy` + `+rename`，再由 Doc 局部更新副本 | 读取后重建 | 先复制可保留在线文档版式 |
+
+URL 本身不能证明产品类型。当前 Drive shortcut 的公开参数主要接受 ID；只有 URL 时先用 `dws drive info --node <URL> --format json` 预检并取真实 nodeId/nodeType。

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

@@ -0,0 +1,39 @@
+# Drive 精简流程
+
+只在跨 Drive/Doc/Wiki 的组合任务命中时读取。单一 Drive 操作直接按根 Skill 执行。
+
+## 查找并读取在线文档
+
+1. 未指定空间：`dws drive +search --query "<关键词>" --format json`。
+2. 明确知识库：用 Wiki 在指定 workspace 搜索。
+3. 唯一确定 nodeId 后切 Doc `+fetch` 读取正文；大文档按返回 continuation 继续。
+
+Drive search 找的是节点；正文全文检索优先用 Doc `+search`。
+
+## 列出目录中的文档
+
+- 普通钉盘目录：`dws drive +list --folder <dentryUuid> --format json`
+- 知识库目录：切 Wiki，用 workspace + parent node 定位
+
+处理 nextCursor，并设置最大页数/条目数。不要从根目录无界递归。
+
+## 导入为在线文档
+
+```bash
+dws doc +import --file ./report.docx --format json
+```
+
+- `.doc/.docx/.md/.txt` 通常导入为在线文字文档；`.xls/.xlsx` 导入为在线表格，最终类型以真实返回为准。
+- 目标是“保留原文件”时使用 Drive `+upload`，不是 Doc import。
+- 用户给目标文件夹 URL 时，若命令契约不保证 URL 直传，先用 `dws drive info --node <URL>` 验证它是 folder，并复用当前节点 nodeId；不要误用其父 folderId。
+- 导入超时或返回 task/checkpoint 时按 Doc 返回的 continuation 恢复，不重复创建。
+
+## 模板保形生成
+
+1. `dws drive +copy --node <源nodeId> --folder <目标folderId>` 保形复制。
+2. 用返回的新 nodeId 执行 `dws drive +rename`。
+3. 切 Doc，只对副本执行局部正文更新。
+
+不要用“读取 Markdown → 新建文档”替代复制；该路径会丢失在线文档的版式属性。
+
+本剧本只适用于 `+copy` 支持的在线文档节点（如 adoc）；普通钉盘文件创建独立副本应改走经用户授权的 download→upload。若源节点是 `able` 且用户要“只复制结构”，切 AITable，按当前 leaf 执行 `+base-copy --base-id <ID> --target-folder-id <真实ID> --only-struct`。只有根目录意图但没有真实目标文件夹 ID 时停止；禁止发明 `--target-root`、用 Drive 完整复制后逐表删记录或自建测试文件夹。

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

@@ -0,0 +1,106 @@
+---
+name: dingtalk-event
+description: 钉钉个人 IM、OA 审批、VoIP 通话邀请与待办事件长连接监听。Use when 用户说监听消息/@我/某人/某群/全部消息、已读/撤回/reaction、群成员加入/群成员退出/群状态变化，监听审批任务创建/完成/转交、审批实例发起/抄送/终止/完成、VoIP 通话邀请，或监听待办创建/更新/删除。命令前缀：dws event。
+metadata:
+  cli_version: ">=0.2.14"
+  category: product
+  requires:
+    bins:
+      - dws
+---
+
+# 钉钉个人 IM、OA 审批、VoIP 与待办事件
+
+> **前置：执行 `dws` 前必须完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。**Shared references 仅按需加载。
+
+本 Skill 只负责未来个人 IM/OA/VoIP/Todo 事件；发送和历史消息走 `dingtalk-chat`，审批处理走 `dingtalk-misc`，待办操作走 `dingtalk-todo`。
+
+实时监听使用长连接，不用历史消息、审批列表、通话记录或待办列表轮询。IM 优先使用 `dws event +listen-im`；OA、VoIP 与 Todo 使用 `dws event consume`。
+
+<!-- dws-intent: event.listen.im -->消息、reaction、已读和撤回的默认监听入口是 `dws event +listen-im`；
+只有群生命周期、Filter DSL、原始 envelope 或底层订阅控制才使用
+`event consume` fallback。
+
+<!-- dws-intent: event.listen.oa -->OA 审批任务与审批实例的实时变化使用 `dws event consume`；查询或操作已有审批走 `dws oa`，不要用轮询模拟事件。
+
+<!-- dws-intent: event.listen.todo -->待办创建、更新或删除的实时变化使用 `dws event consume`；查询或操作已有待办走 `dws todo`，不要用轮询模拟事件。
+
+## Golden Route
+
+| 用户意图 | 唯一推荐入口 |
+|---|---|
+| 监听 @我的消息 | `dws event +listen-im --kind at-me` |
+| 监听某人发来的消息 | `dws event +listen-im --kind sender --user-query <姓名>` |
+| 监听指定群消息 | `dws event +listen-im --kind group --chat-query <群名>` |
+| 同一人/群的消息、表情、已读或撤回 | `dws event +listen-im --kind <sender|group> --events message,reaction,read,recall ...` |
+| 监听全部单聊或全部群消息 | `dws event +listen-im --kind <all-direct|all-group>`；只有用户明确要求“全部”时使用 |
+| 群改名、成员进退、群解散 | 读取 [EventKey 索引](references/event-im-keys.md)，使用精确 `event consume` EventKey |
+| OA 审批任务或实例事件 | 读取 [OA 事件参考](references/event-oa.md)，使用精确 `event consume` EventKey |
+| 查看 OA 事件目录 | `dws event list --category oa` |
+| VoIP 通话邀请 | 读取 [VoIP 事件参考](references/event-voip.md)，使用精确 `event consume` EventKey |
+| 待办创建、更新或删除事件 | 读取 [Todo 事件参考](references/event-todo.md)，使用精确 `event consume` EventKey 与 `--role-types` |
+| 查看 Todo 事件目录 | `dws event list --category todo` |
+| 已知 EventKey 或需要底层订阅控制 | `dws event consume`；参数与约束以 leaf Schema 为准 |
+| 查看状态 / 停止 | `dws event status` / `dws event stop <subscribe_id> --dry-run`，确认后再 `--yes` |
+
+默认 `--events message`。可选事件为 `message`、`reaction`、`read`、`recall`：
+
+- `at-me`、`all-direct`、`all-group` 只支持 `message`，且不接受目标。
+- `sender` 必须且只能传 `--user`、`--open-dingtalk-id` 或 `--user-query` 之一。
+- `group` 必须且只能传 `--chat-id` 或 `--chat-query` 之一。
+- `--query` 只用于纯 `message` 监听；混入 reaction/read/recall 时不得使用。
+
+OA 事件不进入 `+listen-im`。七个公开 OA EventKey 都订阅当前 OAuth 用户相关的全部审批事件，使用 `ruleType=all`、`filterRule={}`；不接受 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。七项可放入同一个 consume，每项建立独立订阅并共享 bus。
+
+Todo 事件也不进入 `+listen-im`。三个公开 EventKey 使用 `--role-types creator,executor,participant` 控制当前用户作为创建者、执行者或参与者的范围；省略时默认三种角色。Todo 不接受用户、群或消息 Filter 参数，三项可共享同一角色范围和 bus。
+
+自然姓名和群名由 CLI 内部唯一解析：零命中或多候选返回结构化失败，在创建任何订阅前停止。`--dry-run` 走同一解析链。解析、监听、状态和停止必须使用同一个 `--profile`，不得跨组织搬运 ID。
+
+### EventKey 索引
+
+16 个 EventKey 的目标与组合约束见 [EventKey 索引](references/event-im-keys.md)。兼容键包括 `user_im_message_receive_o2o_all`、`user_im_message_receive_group_all`、`user_im_group_updated`、`user_im_group_member_added`、`user_im_group_member_exited`、`user_im_group_disbanded`；群输出可含 `operator_open_dingtalk_id`、`members[].open_dingtalk_id`。OA 见 [OA 事件参考](references/event-oa.md)，Todo 见 [Todo 事件参考](references/event-todo.md)。
+
+## 运行与结果契约
+
+- 正常消费固定使用当前用户 OAuth 身份、`--flatten` 和 NDJSON；stdout 只输出事件，stderr 输出订阅、ready、退出和错误状态。
+- 单事件 ready：`[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>`。
+- 多事件先逐条输出 subscription，全部就绪后输出 `[event] ready event_count=<n> bus_pid=<pid>`。必须等待 ready，不用 `sleep` 猜测。
+- 有界任务使用 `--max-events N` 或 `--duration 10m`；无界任务需要宿主管理进程并持续读取 stdout。
+- 干净退出会取消本次新建的订阅；使用 SIGTERM、关闭符合条件的管道 stdin，或 Runtime 的 bounded exit。不要 `kill -9`。
+- 当前用户自己发送的消息会被 self-loop 过滤；自测事件应由另一用户或机器人发送。
+- 事件只负责监听；需要回复时按 [输出与 Chat 交接](references/event-im-output.md) 把真实 `conversation_id` 或 `sender_open_dingtalk_id` 交给 `dws chat +messages-send`，不要从显示名猜 ID。
+- 扁平消息/动作字段按事件类型读取：已读为 `reader_open_dingtalk_id`，撤回为 `recaller_open_dingtalk_id`，回应为 `reaction_name`、`operation_type`。媒体优先通过聊天读取命令加 `--download-resources`；已知消息 ID 的底层降级入口是 `dws chat message download-media`。
+- OA 扁平事件提供审批实例、任务和状态字段；字段差异、原始回退条件及与 OA 命令的稳定 ID 交接以 [OA 事件参考](references/event-oa.md) 为准。
+- Todo 扁平事件提供 `task_id`、标题、角色、状态阶段和时间字段；用真实 `task_id` 交给 `dws todo`，字段差异见 [Todo 事件参考](references/event-todo.md)。
+
+## 安全与失败处理
+
+- `event stop` 会取消订阅并影响本地 consumer：先 `--dry-run`，用户确认后再加 `--yes`。
+- 多事件属于一次原始操作；任一订阅启动失败时 Runtime 回滚本次已创建项，不拆成新命令绕过重试预算。
+- 这套 `0/2/1` 是 **Agent/host** 编排预算，适用于全部 27 个公开个人 EventKey（16 个 IM + 7 个 OA + 1 个 VoIP + 3 个 Todo）：`retryable=false` 对应 `max_additional_attempts=0`；`retryable=true` 对应 `max_additional_attempts=2`；`retryable=unknown` 对应 `max_additional_attempts=1`。它不是 CLI 持久化硬总次数上限；每次调用最多创建一次，进程内不会自动重试，CLI 也不持久化或计算跨调用的 Agent/host 尝试次数。
+- 重试必须遵守 `retry_after_seconds` / `next_retry_at`。遇到 `in_flight`、`cooldown`、`terminal_hold` 不并发或递归重启同一逻辑订阅，也不换 `subscribe_id` / `trace_id` 绕过保护。
+- 认证、profile、订阅保护状态和 bus 排障按失败类型读取 [订阅运维](references/event-im-operations.md)，不要在正常路径预加载完整运维手册。
+
+### 本地订阅保护
+
+状态在 `~/.dws/events/open/personal_stream/<identity_hash>/personal_subscription_attempts.json`（`DWS_CONFIG_DIR` 改根）；目录 `0700`，`personal_subscription_attempts.json` 与 `personal_subscription_attempts.lock` 为 `0600`。连续 `24h` 无失败后重置，`terminal_hold` 为 `1h`。紧急恢复只删除 `personal_subscription_attempts.json`，不要删除 lock 文件；这会清空该 identity 的全部保护记录。
+
+## 何时查询 Schema
+
+- 已知 Golden Route 时直接执行，不先跑 `event list`。
+- 只有解析业务字段时才用 `dws event schema <event_key> --flatten`。
+- 只有参数或安全不确定时才用 `dws schema --cli-path "event +listen-im" --compact` 或对应 compact leaf。
+- `event schema` 描述事件 payload；顶层 `dws schema` 描述 CLI 命令，两者不要混用。
+
+## Reference
+
+| Topic | Reference | 何时读取 |
+|---|---|---|
+| 任务索引 | [event-im.md](references/event-im.md) | 还不能判断应该加载哪一个子 reference |
+| EventKey、目标规则与底层 consume | [event-im-keys.md](references/event-im-keys.md) | 群生命周期、显式 EventKey 或多事件组合 |
+| ready、bounded consume 与退出清理 | [event-im-lifecycle.md](references/event-im-lifecycle.md) | 启动/托管/关闭 consumer |
+| 扁平字段与事件到 Chat 交接 | [event-im-output.md](references/event-im-output.md) | 解析事件或自动回复 |
+| Filter、status/stop、重试与排障 | [event-im-operations.md](references/event-im-operations.md) | 订阅控制或失败恢复 |
+| OA 审批事件 | [event-oa.md](references/event-oa.md) | 选择七个 OA EventKey、组合消费或解析审批字段 |
+| VoIP 通话邀请事件 | [event-voip.md](references/event-voip.md) | 选择 VoIP EventKey、解析邀请字段或检查敏感输出边界 |
+| Todo 待办事件 | [event-todo.md](references/event-todo.md) | 选择三个 Todo EventKey、设置角色范围或解析待办字段 |

package/skills/dws/dingtalk-event/references/event-im-keys.md

@@ -0,0 +1,54 @@
+# IM EventKey 与底层消费
+
+高频消息、reaction、已读和撤回优先 `dws event +listen-im`。本页只用于群生命周期、
+显式 EventKey 或高级底层控制。
+
+## 16 个 EventKey
+
+| EventKey | 范围 | 目标参数 |
+|---|---|---|
+| `user_im_message_receive_at` | 被 @ 消息 | 无 |
+| `user_im_message_receive_o2o` | 指定单聊消息 | `--user` 或 `--open-dingtalk-id` |
+| `user_im_message_receive_group` | 指定群消息 | `--group` |
+| `user_im_message_receive_user` | 指定发送人在单聊/群聊中的消息 | `--user` 或 `--open-dingtalk-id` |
+| `user_im_message_receive_o2o_all` | 全部单聊消息 | 无 |
+| `user_im_message_receive_group_all` | 全部群消息 | 无 |
+| `user_im_message_read_o2o` | 指定单聊已读 | user 二选一 |
+| `user_im_message_read_group` | 指定群已读 | `--group` |
+| `user_im_message_recall_o2o` | 指定单聊撤回 | user 二选一 |
+| `user_im_message_recall_group` | 指定群撤回 | `--group` |
+| `user_im_message_reaction_o2o` | 指定单聊 reaction | user 二选一 |
+| `user_im_message_reaction_group` | 指定群 reaction | `--group` |
+| `user_im_group_updated` | 群标题变化 | `--group` |
+| `user_im_group_member_added` | 成员加入 | `--group` |
+| `user_im_group_member_exited` | 成员退出 | `--group` |
+| `user_im_group_disbanded` | 群解散 | `--group` |
+
+`--user` 只接收 userId；明确 openDingTalkId 时用对应 flag。群目标必须是
+openConversationId。不要把两种身份混传或选择搜索第一项。
+
+## 精确模板
+
+```bash
+dws event consume user_im_group_member_added \
+  --group <openConversationId> --flatten -f ndjson
+
+dws event consume user_im_message_receive_user \
+  --open-dingtalk-id <openDingTalkId> --flatten -f ndjson
+
+dws event consume user_im_message_receive_group \
+  user_im_message_reaction_group \
+  user_im_message_recall_group \
+  --group <openConversationId> --flatten -f ndjson
+```
+
+多事件只能共享同一 target/filter。用户类与群类不能混在一个命令中；不同人、群或过滤条件
+启动不同 consume。只有全部 EventKey 都是接收消息时才能共享 `--query/--filter-json`。
+多事件不支持 `--subscribe-id`、`--rule`、`--event-types`、`--filter`、`--foreground`、
+`--force` 或 `--debug-raw-events`。
+
+## 意图消歧
+
+- “我和某人的单聊” → `receive_o2o`；“某人发给我的消息” → `receive_user`。
+- 执行撤回/添加 reaction 走 `dws chat`；监听它们才走 Event。
+- 群改名/成员进退/解散使用四个生命周期 EventKey；解散自测只能用已确认可销毁测试群。

package/skills/dws/dingtalk-event/references/event-im-lifecycle.md

@@ -0,0 +1,35 @@
+# IM consume 生命周期
+
+## Ready 门禁
+
+单事件只有出现以下 stderr 后才读取 stdout：
+
+```text
+[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>
+```
+
+多事件会先逐条输出 subscription，全部 IPC consumer 就绪后才输出：
+
+```text
+[event] subscription event_key=<key> subscribe_id=<id>
+[event] subscription event_key=<key> subscribe_id=<id>
+[event] ready event_count=2 bus_pid=<pid>
+```
+
+不能把 subscription 行当成整体 ready，也不要用 `sleep` 猜建联。任一订阅或 IPC 建联失败，
+Runtime 会回滚本次已创建订阅。
+
+## 有界与长期任务
+
+- 有界消费使用 `--max-events N` 或 `--duration 10m`。
+- 长期任务由宿主管理子进程并持续读取 stdout/stderr，避免管道背压。
+- `--output-dir`/`--route` 是明确落盘任务，不要用文件 watcher 代替 stdout 事件循环。
+- stdout 的 NDJSON 每行独立解析；单行失败不能吞掉后续事件。
+
+## 干净退出
+
+本次新建的订阅会在 SIGTERM、Ctrl+C、符合条件的 stdin EOF、duration 或 max-events 退出时
+自动取消。复用 `--subscribe-id` 的订阅默认保留，除非显式 `--ephemeral`。
+
+多事件中停止一个 subscribe_id 只移除对应 consumer；其余继续，最后一个移除后进程退出。
+禁止 `kill -9`，它会跳过清理。外部停止流程见 [event-im-operations.md](event-im-operations.md)。

package/skills/dws/dingtalk-event/references/event-im-operations.md

@@ -0,0 +1,52 @@
+# IM 订阅过滤、状态与排障
+
+## Filter
+
+优先用订阅规则缩小范围：单聊/发送人用 user 身份，群用 `--group`。接收消息事件需要额外
+正文过滤时才用 `--query` 或 `--filter-json`；已读、撤回、reaction 和群生命周期不使用
+消息内容过滤。业务别名包括 `content`、`sender`、`conversation_id`、
+`sender_open_dingtalk_id`。
+
+## Status 与 stop
+
+```bash
+dws event status --event <event_key>
+dws event stop <subscribe_id> --dry-run
+dws event stop <subscribe_id> --yes
+dws event stop --all --dry-run
+dws event stop --all --yes
+```
+
+`status` 同时看服务端 Subscriptions 与本地 Consumers；用 PID、EventKey、subscribe_id 和
+received/dropped 判断 consumer。裸 `event stop` 不取消任何订阅。stop 是有影响操作，先预览，
+按 Runtime gate 确认后执行。
+
+## 创建失败与 `0/2/1` 编排预算
+
+这些约束只治理 ready 之前的创建；ready 后断线由长连接重连：
+
+- `retryable=false`：额外尝试 0 次。
+- `retryable=true`：最多额外 2 次，并遵守 `retry_after_seconds/next_retry_at`。
+- 未给 retryable：最多额外 1 次，然后停止并保留 trace。
+
+这是 Agent/host 预算，不是 CLI 跨进程计数器。一个逻辑订阅由 profile/身份、EventKey、
+rule、目标和 filter 确定；换 subscribe_id、trace 或进程不能重置预算。遇到 `in_flight`、
+`cooldown`、`terminal_hold` 不并发、递归或拆分多事件绕过保护。
+
+## 本地保护状态
+
+open 版路径为
+`~/.dws/events/open/personal_stream/<identity_hash>/personal_subscription_attempts.json`；
+`DWS_CONFIG_DIR` 会改变根目录。identity 目录为 `0700`，JSON 与 lock 为 `0600`。
+连续 24h 无失败后重置，terminal hold 为 1h。
+
+紧急恢复前确认没有创建进程，只删除 attempts JSON，不删除 lock；这会清空该 identity 的
+全部保护记录，不是常规重试方式。
+
+## 最短排障
+
+- 无输出：先确认正确 ready marker，再看 subscribe_id 和 received/dropped。
+- 目标错误：o2o/user 检查身份 flag，group 检查 openConversationId。
+- 判断服务端是否推到连接：临时单事件 `--debug --debug-raw-events`；它不能与 `--flatten`
+  并用，排查后立即移除。
+- 长期运行：交给宿主进程管理，不写历史消息轮询脚本。

package/skills/dws/dingtalk-event/references/event-im-output.md

@@ -0,0 +1,39 @@
+# IM 事件输出与 Chat 交接
+
+Agent 默认使用 `--flatten -f ndjson`，顶层直接读取字段，不再 `fromjson`。消息接收常见字段：
+
+| 字段 | 语义 |
+|---|---|
+| `type` / `event_id` / `timestamp` | 事件类型、去重 ID、时间 |
+| `subscribe_id` | 个人订阅与本地输出隔离键 |
+| `message_id` / `conversation_id` | 稳定消息与会话 ID |
+| `sender` / `sender_open_dingtalk_id` | 展示名与稳定发送人开放 ID |
+| `content` / `create_time` / `event_time` | 正文及时间 |
+| `quoted_message` | 可选引用原消息 |
+| `forward_messages` | 可选合并转发子消息数组 |
+
+引用和转发子消息字段为 `message_id`、`conversation_id`、`sender`、
+`sender_open_dingtalk_id`、`content`、`create_time`。按结构识别转发，不匹配本地化摘要。
+
+动作事件通用字段之外：已读提供 `reader_open_dingtalk_id/read_time`，撤回提供
+`recaller_open_dingtalk_id/recall_time`，reaction 提供
+`operator_open_dingtalk_id/reaction_name/reaction_text/operation_type/operation_time`。
+
+成员加入/退出提供 `conversation_id`、`operator_open_dingtalk_id`、`members[]` 和
+`event_time`；成员稳定 ID 是 `members[].open_dingtalk_id`。群标题变化和群解散仅保守承诺
+基础路由字段及 `payload`，不得猜未由真实样本确认的键。
+
+## 事件驱动回复的精确 ID 映射
+
+<!-- DWS_EVENT_CHAT_HANDOFF_START -->
+| event field | exact chat target |
+|---|---|
+| `conversation_id` | `dws chat +messages-send --as user --group <conversation_id>` |
+| `sender_open_dingtalk_id` | `dws chat +messages-send --as user --open-dingtalk-id <sender_open_dingtalk_id>` |
+<!-- DWS_EVENT_CHAT_HANDOFF_END -->
+
+在上述命令后追加真实 `--text`/`--markdown` 和必要 confirmation。禁止使用 `sender` 再做
+`--user-query`，也禁止把单聊发送人 ID 当成群 ID。交接 marker 由 policy 逐字验证。
+
+媒体事件正文可能只是描述。优先按真实消息 ID/会话 ID 使用 Chat 消息读取命令加
+`--download-resources`；只有精确 lower fallback 才用 `chat message download-media`。

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

@@ -0,0 +1,58 @@
+# IM 事件任务路由
+
+本页是任务索引，不再混放 16 个 EventKey、输出字段和运维细节。先用上层
+[SKILL.md](../SKILL.md) 的 Golden Route；只加载当前任务对应的一份子 reference。
+
+<!-- dws-intent: event.listen.im -->消息、reaction、已读和撤回默认使用 `dws event +listen-im` 长连接；
+群生命周期、显式 EventKey、Filter DSL、原始 envelope 或底层订阅控制才使用
+`event consume`。不要写轮询脚本。
+
+## 选择哪一页
+
+| 任务 | Reference |
+|---|---|
+| 选择 16 个 EventKey、区分 user/group/all 规则、组合底层 consume | [event-im-keys.md](event-im-keys.md) |
+| 等待 ready、多事件回滚、bounded consume、退出清理 | [event-im-lifecycle.md](event-im-lifecycle.md) |
+| 扁平字段、引用/转发、动作与群成员事件、事件驱动回复 | [event-im-output.md](event-im-output.md) |
+| Filter、status/stop、重试预算、本地保护与排障 | [event-im-operations.md](event-im-operations.md) |
+
+## 共同硬规则
+
+- 个人事件使用当前用户 OAuth；解析、consume、status、stop 必须是同一 `--profile`。
+- `+listen-im --user-query/--chat-query` 在 CLI 内唯一解析；零命中、多候选或分页不完整时，
+  在创建订阅前停止。底层 fallback 只传真实稳定 ID。
+- 默认 `--flatten -f ndjson`；stdout 只处理事件，stderr 等待明确 ready marker。
+- 指定目标优先于 `*_all`；只有用户明确说“全部单聊/全部群消息”才订阅全量事件。
+- 当前用户自己发送的消息会被 self-loop 过滤；自测由另一用户或机器人触发。
+- 事件只负责监听。回复必须使用事件里的真实 `conversation_id` 或
+  `sender_open_dingtalk_id`，禁止把展示名重新做自然查询。
+
+## 跨页契约索引
+
+以下索引保留跨页必须一致的机器可检验契约；解释、示例和操作步骤仍按上表按需加载：
+
+- 16 个事件都使用同一 `--profile`。就绪以 `[event] ready` 为准；全量事件是
+  `user_im_message_receive_o2o_all` / `user_im_message_receive_group_all`，群生命周期是
+  `user_im_group_updated` / `user_im_group_member_added` /
+  `user_im_group_member_exited` / `user_im_group_disbanded`。
+- 扁平动作字段包括 `reader_open_dingtalk_id`、`recaller_open_dingtalk_id`、
+  `operator_open_dingtalk_id`、`reaction_name`、`operation_type` 和 `members`；媒体 lower
+  fallback 是 `dws chat message download-media`，外部身份参数是 `--open-dingtalk-id`。
+- 创建失败遵循 Agent/host 的 `0/2/1` 预算：`retryable=false` 对应
+  `max_additional_attempts=0`，`retryable=true` 对应 `max_additional_attempts=2`，
+  `retryable=unknown` 对应 `max_additional_attempts=1`，并遵守 `retry_after_seconds` /
+  `next_retry_at`。这不是 CLI 持久化硬总次数上限；进程内不会自动重试，也不持久化或计算跨调用的
+  Agent/host 尝试次数。`subscribe_id` / `trace_id` 不重置预算，`in_flight` / `cooldown` /
+  `terminal_hold` 不得被并发绕过。
+- open 版保护文件是
+  `~/.dws/events/open/personal_stream/<identity_hash>/personal_subscription_attempts.json`；
+  `DWS_CONFIG_DIR` 可改变根目录。目录权限 `0700`，`personal_subscription_attempts.json` 与
+  `personal_subscription_attempts.lock` 权限 `0600`；连续 `24h` 无失败后重置，
+  `terminal_hold` 为 `1h`。紧急恢复只删除 `personal_subscription_attempts.json`，
+  不要删除 lock 文件；这会清空该 identity 的全部保护记录。
+
+## Schema 边界
+
+- 业务 payload：`dws event schema <event_key> --flatten`。
+- CLI 参数/安全：`dws schema --cli-path "event +listen-im" --compact -f json` 或精确 compact consume leaf。
+- `--flatten` 的 `jq_root_path` 为 `.`；兼容 transport envelope 才使用 `.data | fromjson`。