first commit

.agents/skills/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；解散自测只能用已确认可销毁测试群。

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

.agents/skills/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`
+  并用，排查后立即移除。
+- 长期运行：交给宿主进程管理，不写历史消息轮询脚本。

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

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

.agents/skills/dingtalk-event/references/event-oa.md

@@ -0,0 +1,155 @@
+# OA 个人审批事件
+
+先读事件产品入口 [SKILL.md](../SKILL.md) 的命令规则、调用流和子进程契约。本参考覆盖当前公开的七个 OA 个人事件：审批实例发起、抄送、终止和完成，以及审批任务创建、完成和转交。
+
+<!-- dws-intent: event.listen.oa -->实时监听审批事件必须使用 `dws event consume` 长连接，不要轮询 OA 待办或审批实例列表来模拟事件。
+
+## Prerequisite
+
+OA 个人事件使用当前用户 OAuth 登录态。未登录或 token 失效时，先执行：
+
+```bash
+dws auth login
+```
+
+非默认组织使用全局 `--profile <corpId 或 profile 名>`。事件范围始终是该 OAuth 用户相关的全部 OA 事件，不需要也不接受审批人、发起人或审批模板选择参数。
+
+## Event catalog
+
+| 事件码 | 订阅规则 | 接收语义 | 必填参数 |
+|---|---|---|---|
+| `user_oa_approval_task_created` | `all` | 审批任务创建，发送给审批人 | 无 |
+| `user_oa_approval_task_finished` | `all` | 审批任务已完成 | 无 |
+| `user_oa_approval_task_redirected` | `all` | 审批任务已转交 | 无 |
+| `user_oa_approval_instance_started` | `all` | 审批实例已发起 | 无 |
+| `user_oa_approval_instance_cc` | `all` | 审批实例到达抄送节点，发送给被抄送人 | 无 |
+| `user_oa_approval_instance_terminated` | `all` | 审批实例已终止 | 无 |
+| `user_oa_approval_instance_finished` | `all` | 审批实例完成，发送给审批单发起人 | 无 |
+
+只承认上表 7 个 OA 事件码。CLI 为每个事件发送 `ruleType=all`、`filterRule={}` 的独立订阅请求；不要添加 `--user`、`--open-dingtalk-id`、`--group`、`--query` 或 `--filter-json`。
+
+## Intent mapping
+
+| 用户说 | 下一步 |
+|---|---|
+| “监听新的待我审批任务” / “有审批任务创建时通知我” | `dws event consume user_oa_approval_task_created --flatten -f ndjson` |
+| “审批任务完成时通知我” | `dws event consume user_oa_approval_task_finished --flatten -f ndjson` |
+| “审批任务被转交时通知我” | `dws event consume user_oa_approval_task_redirected --flatten -f ndjson` |
+| “有审批单发起时通知我” | `dws event consume user_oa_approval_instance_started --flatten -f ndjson` |
+| “有审批抄送给我时通知我” | `dws event consume user_oa_approval_instance_cc --flatten -f ndjson` |
+| “有审批单终止时通知我” | `dws event consume user_oa_approval_instance_terminated --flatten -f ndjson` |
+| “监听我发起的审批何时完成” / “审批实例完成时通知我” | `dws event consume user_oa_approval_instance_finished --flatten -f ndjson` |
+| “同时监听全部已公开 OA 事件” | 一个 consume 放入七个 OA event key，不加目标或过滤参数 |
+| “查看 OA 事件目录” | `dws event list --category oa` |
+| “查看 OA 事件输出字段” | 对对应事件运行 `dws event schema <event_key> --flatten` |
+
+三个审批任务事件分别表达任务已创建、已完成和已转交；四个审批实例事件分别表达实例已发起、到达抄送节点、已终止和已完成。`status` 和 `result` 保留服务端原值，不把当前样本值推断为完整枚举。
+
+## Commands
+
+查看稳定的扁平输出 schema：
+
+```bash
+dws event schema user_oa_approval_task_created --flatten
+dws event schema user_oa_approval_task_finished --flatten
+dws event schema user_oa_approval_task_redirected --flatten
+dws event schema user_oa_approval_instance_started --flatten
+dws event schema user_oa_approval_instance_cc --flatten
+dws event schema user_oa_approval_instance_terminated --flatten
+dws event schema user_oa_approval_instance_finished --flatten
+```
+
+单独监听一种事件：
+
+```bash
+dws event consume user_oa_approval_task_created --flatten -f ndjson
+dws event consume user_oa_approval_task_finished --flatten -f ndjson
+dws event consume user_oa_approval_task_redirected --flatten -f ndjson
+dws event consume user_oa_approval_instance_started --flatten -f ndjson
+dws event consume user_oa_approval_instance_cc --flatten -f ndjson
+dws event consume user_oa_approval_instance_terminated --flatten -f ndjson
+dws event consume user_oa_approval_instance_finished --flatten -f ndjson
+```
+
+同时监听七种事件：
+
+```bash
+dws event consume \
+  user_oa_approval_task_created \
+  user_oa_approval_task_finished \
+  user_oa_approval_task_redirected \
+  user_oa_approval_instance_started \
+  user_oa_approval_instance_cc \
+  user_oa_approval_instance_terminated \
+  user_oa_approval_instance_finished \
+  --flatten \
+  -f ndjson
+```
+
+多事件 consume 会为七个 event key 分别创建订阅和逻辑 consumer，并共享当前组织的 personal bus、远程连接、stdout 和生命周期。不要给 OA 命令加 `--query` 或 `--filter-json`；这两个 flag 只用于兼容的 IM 消息接收事件。
+
+## Output contract
+
+`--flatten` 模式的所有 OA 事件都包含以下顶层字段：
+
+```json
+{
+  "type": "user_oa_approval_task_created",
+  "event_id": "...",
+  "timestamp": 0,
+  "subscribe_id": "...",
+  "process_instance_id": "...",
+  "process_code": "...",
+  "title": "...",
+  "status": "RUNNING",
+  "create_time": 0,
+  "event_time": 0
+}
+```
+
+- `type` 是当前 event key；`event_id` 可用于去重；`timestamp` 是 transport 事件发生时间；`subscribe_id` 标识对应的独立订阅。
+- `process_instance_id` 是审批实例 ID，可传给 OA 审批命令的 `--instance-id`；`process_code` 是审批流程模板编码。
+- `create_time`、`finish_time` 和 `event_time` 都是毫秒时间戳。`event_time` 是审批业务事件时间，`timestamp` 是 transport 事件时间。
+- 七类事件的额外字段如下；具体事件始终以 `dws event schema <event_key> --flatten` 为准。
+
+| 事件 | 额外顶层字段 |
+|---|---|
+| `user_oa_approval_task_created` | `task_id` |
+| `user_oa_approval_task_finished` | `task_id`、`result`、`finish_time` |
+| `user_oa_approval_task_redirected` | `task_id`、`result`、`finish_time` |
+| `user_oa_approval_instance_started` | 无 |
+| `user_oa_approval_instance_cc` | 无 |
+| `user_oa_approval_instance_terminated` | `finish_time` |
+| `user_oa_approval_instance_finished` | `result`、`finish_time` |
+
+任务完成事件示例：
+
+```json
+{
+  "type": "user_oa_approval_task_finished",
+  "event_id": "...",
+  "timestamp": 0,
+  "subscribe_id": "...",
+  "process_instance_id": "...",
+  "process_code": "...",
+  "task_id": "...",
+  "title": "测试审批",
+  "status": "FINISHED",
+  "result": "agree",
+  "create_time": 0,
+  "finish_time": 0,
+  "event_time": 0
+}
+```
+
+- `task_id` 是当前审批任务 ID，可传给接受任务 ID 的 OA 审批命令。
+- `status` 和 `result` 是服务端字符串；不要只根据当前样本把 `RUNNING/FINISHED/TERMINATED` 或 `agree/redirect` 写成封闭枚举。
+- payload 缺失、为空、缺少对应事件的稳定 ID 或无法解析时，consume 会在 stderr 记录 warning，并把原始 transport envelope 写到 stdout，保证事件不被静默丢弃。
+- 不传 `--flatten` 时保持兼容 transport envelope，业务 payload 位于 `.data | fromjson`。需要联调完整原始协议时使用不带 `--flatten` 的 `-f raw` 或 `--debug-raw-events`。
+
+## Lifecycle
+
+- 单事件等待 `[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>`。
+- 七事件先保存七条 `[event] subscription event_key=<key> subscribe_id=<id>`，再等待 `[event] ready event_count=7 bus_pid=<pid>`。
+- 临时验证使用 `--max-events 1` 或 `--duration 10m`；任务完成后优雅结束 consume，本次新建的订阅会自动取消。
+- 外部停止已有订阅时先运行 `dws event stop <subscribe_id> --dry-run`，确认后再加 `--yes`。不要 `kill -9`，否则会跳过自动退订。