dingtalk-event

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 。**Shared references 仅按需加载。 本 Skill 只负责实时个人事件；发送/历史消息、审批处理、待办操作分别走 dingtalk-chat 、 dingtalk-misc 、 dingtalk-todo 。IM 优先 +listen-im ；OA、VoIP、Todo、互动卡片使用 event consume ，不用列表轮询模拟事件。 消息、reaction、已读和撤回的默认监听入口是 `dws event +listen-im`； 只有群生命周期、Filter DSL、原始 envelope 或底层订阅控制才使用 event consume fallback。 OA 审批任务与审批实例的实时变化使用 `dws event consume`；查询或操作已有审批走 `dws oa`，不要用轮询模拟事件。 待办创建、更新或删除的实时变化使用 `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 监听全部单聊或全部群消息 `dws event +listen-im --kind <all-direct 群改名、成员进退、群解散 读取 EventKey 索引 ，使用精确 event consume EventKey OA 审批任务或实例事件 读取 OA 事件参考 ，使用精确 event consume EventKey 查看 OA 事件目录 dws event list --category oa VoIP 通话邀请 读取 VoIP 事件参考 ，使用精确 event consume EventKey 待办创建、更新或删除事件 读取 Todo 事件参考 ，使用精确 event consume EventKey 与 --role-types 查看 Todo 事件目录 dws event list --category todo 互动卡片回调 读取 互动卡片事件参考 ，使用 dws event consume user_card_action_triggered --flatten -f ndjson 查看互动卡片事件目录 dws event list --category card 已知 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 七个 EventKey 使用 ruleType=all 、 filterRule={} ，不接受目标或消息过滤；Todo 三个 EventKey 仅接受 --role-types creator,executor,participant ，省略时取并集。每项独立订阅并共享 bus。 互动卡片使用 `dws event consume user_card_action_triggered --flatten -f ndjson`、`ruleType=all`、`filterRule={}`；不接受目标、角色或消息过滤。结构化上下文在 `payload.body.actionData.context`，未知字段保留。 姓名/群名必须唯一解析，零命中或多候选在创建订阅前停止。解析、监听、状态、停止使用同一 --profile ，不得跨组织搬运 ID； --dry-run 走同一解析链。 EventKey 索引 16 个 EventKey 及目标约束见 索引 ，含 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 。其它类别见下方 Reference。 运行与结果契约 正常消费使用当前用户 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 或受控 stdin/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 。在 payload.body.actionData.context 用 questions[].id 关联 answers[question_id] ，按选项 ID 读 selected ；空数组合法。操作者是 operatorDTO.uid ；分别保留 timestamp 、 event_time 、 triggerTimestamp 。其它字段与回退见 互动卡片参考 。 安全与失败处理 event stop 会取消订阅并影响本地 consumer：先 --dry-run ，用户确认后再加 --yes 。 多事件属于一次原始操作；任一订阅启动失败时 Runtime 回滚本次已创建项，不拆成新命令绕过重试预算。 全部 28 个公开个人 EventKey（16 IM + 7 OA + 1 VoIP + 3 Todo + 1 卡片）遵循 Agent/host 0/2/1 ： 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 排障按失败类型读取 订阅运维 ，不要在正常路径预加载完整运维手册。 本地订阅保护 状态在 ~/.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 还不能判断应该加载哪一个子 reference EventKey、目标规则与底层 consume event-im-keys.md 群生命周期、显式 EventKey 或多事件组合 ready、bounded consume 与退出清理 event-im-lifecycle.md 启动/托管/关闭 consumer 扁平字段与事件到 Chat 交接 event-im-output.md 解析事件或自动回复 Filter、status/stop、重试与排障 event-im-operations.md 订阅控制或失败恢复 OA 审批事件 event-oa.md 选择七个 OA EventKey、组合消费或解析审批字段 VoIP 通话邀请事件 event-voip.md 选择 VoIP EventKey、解析邀请字段或检查敏感输出边界 Todo 待办事件 event-todo.md 选择三个 Todo EventKey、设置角色范围或解析待办字段 互动卡片回调事件 event-card.md 订阅互动卡片回调、解析开放 payload 或检查空过滤规则