first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -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`
+  并用，排查后立即移除。
+- 长期运行：交给宿主进程管理，不写历史消息轮询脚本。