git:20261009.5aa4c5d to git:20261019.fe15471

---

name: dingtalk-event

metadata:

cli_version: ">=0.2.14"

category: product

requires:

bins:

- dws

---

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

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

<!-- dws-intent: event.listen.im -->消息、reaction、已读和撤回的默认监听入口是 `dws event +listen-im`；

<!-- 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 ...` |

| 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` |

| 好友申请/好友添加成功事件 | 读取 [好友事件参考](references/event-contact.md)，使用精确 `event consume` EventKey |

| 查看好友事件目录 | `dws event list --category contact` |

| 查看互动卡片事件目录 | `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`，省略时取并集；好友两个 EventKey 约束同 OA。每项独立订阅并共享 bus。

### EventKey 索引

## 运行与结果契约

- 正常消费使用当前用户 OAuth、`--flatten` 和 NDJSON；stdout 仅事件，stderr 为生命周期状态。

- 单事件 ready：`[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>`。

- 有界任务用 `--max-events N`/`--duration 10m`；干净退出会取消本次新建订阅。无界任务由宿主持续读 stdout；用 SIGTERM 或 bounded exit，不用 `kill -9`。

- OA 扁平事件提供审批实例、任务和状态字段；字段差异、原始回退条件及与 OA 命令的稳定 ID 交接以 [OA 事件参考](references/event-oa.md) 为准。

- Todo 扁平事件提供 `task_id`、标题、角色、状态阶段和时间字段；用真实 `task_id` 交给 `dws todo`，字段差异见 [Todo 事件参考](references/event-todo.md)。

## 安全与失败处理

开源 normal 获取缺失 AppKey，无需 AppSecret；custom／定制版除外。[排障](references/event-im-operations.md)。

- 多事件属于一次原始操作；任一订阅启动失败时 Runtime 回滚本次已创建项，不拆成新命令绕过重试预算。

- 遵守 `retry_after_seconds`/`next_retry_at`；`in_flight`、`cooldown`、`terminal_hold` 时不并发或换 `subscribe_id`/`trace_id` 绕过。

### 本地订阅保护

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

- `event schema` 描述事件 payload；顶层 `dws schema` 描述 CLI 命令，两者不要混用。

## Reference

| Topic | 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 与审批字段解析 |