dingtalk-event

钉钉个人 IM、OA 审批、VoIP、待办、互动卡片与好友事件

前置：执行 `dws` 前必须完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。Shared references 仅按需加载。

本 Skill 只负责实时个人事件；发送/历史消息、审批处理、待办操作分别走 dingtalk-chat、dingtalk-misc、dingtalk-todo。

<!-- dws-intent: event.listen.im -->消息、reaction、已读和撤回的默认监听入口是 dws event +listen-im； 只有群生命周期、Filter DSL、原始 envelope 或底层订阅控制才使用 event consume。

<!-- dws-intent: event.listen.oa -->OA 审批任务与审批实例的实时变化使用 dws event consume；查询或操作已有审批走 dws oa，不要用轮询模拟事件。

<!-- dws-intent: event.listen.todo -->待办创建、更新或删除的实时变化使用 dws event consume；查询或操作已有待办走 dws todo，不要用轮询模拟事件。

Golden Route

默认 --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 七个 EventKey 使用 ruleType=all、filterRule={}，不接受目标或消息过滤；Todo 三个 EventKey 仅接受 --role-types creator,executor,participant，省略时取并集；好友两个 EventKey 约束同 OA。每项独立订阅并共享 bus。

<!-- dws-intent: event.listen.card -->互动卡片使用 dws event consume user_card_action_triggered --flatten -f ndjson、ruleType=all、filterRule={}；不接受目标、角色或消息过滤。结构化上下文在 payload.body.actionData.context：questions[].id 关联 answers[question_id] 读 selected，未知字段保留。

<!-- dws-intent: event.listen.contact -->好友申请/好友添加成功事件使用 dws event consume；查询或操作好友关系走 dws contact，不要轮询模拟事件。

姓名/群名必须唯一解析，零命中或多候选在创建订阅前停止。解析、监听、状态、停止使用同一 --profile，不得跨组织搬运 ID。

EventKey 索引

16 个 EventKey 及目标约束见 索引；群输出可含 operator_open_dingtalk_id、members[].open_dingtalk_id。

运行与结果契约

• 正常消费使用当前用户 OAuth、--flatten 和 NDJSON；stdout 仅事件，stderr 为生命周期状态。
• 单事件 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 或 bounded exit，不用 kill -9。
• 自发消息会被 self-loop 过滤。回复时把真实 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 事件参考 为准。
• Todo 扁平事件提供 task_id、标题、角色、状态阶段和时间字段；用真实 task_id 交给 dws todo，字段差异见 Todo 事件参考。
• 互动卡片输出 type/event_id/timestamp/subscribe_id/payload；操作者 operatorDTO.uid，triggerTimestamp 等三个时间戳照原样保留；回退见 互动卡片参考。

安全与失败处理

开源 normal 获取缺失 AppKey，无需 AppSecret；custom／定制版除外。排障。

• event stop 取消订阅并影响本地 consumer：先 --dry-run，确认后 --yes。
• 多事件属于一次原始操作；任一订阅启动失败时 Runtime 回滚本次已创建项，不拆成新命令绕过重试预算。
• 全部 30 个公开个人 EventKey（16 IM + 7 OA + 1 VoIP + 3 Todo + 1 卡片 + 2 好友）遵循 Agent/host 0/2/1：retryable=false→max_additional_attempts=0；retryable=true→max_additional_attempts=2；retryable=unknown→max_additional_attempts=1。它不是 CLI 持久化硬总次数上限；进程内不会自动重试，也不持久化或计算跨调用的 Agent/host 尝试次数。
• 遵守 retry_after_seconds/next_retry_at；in_flight、cooldown、terminal_hold 时不并发或换 subscribe_id/trace_id 绕过。
• 认证、profile、订阅保护状态和 bus 排障按失败类型读取 订阅运维。

本地订阅保护

状态在 ~/.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