first commit

.agents/skills/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`。