diff --git a/.env.example b/.env.example
index 1e71fd5..3dd623f 100644
--- a/.env.example
+++ b/.env.example
@@ -51,6 +51,25 @@ CHAT_DOCUMENT_MAX_BYTES=20971520
 DOCUMENT_GC_INTERVAL=1h
 DOCUMENT_RETENTION=168h
 
+# ---- 渠道事件留存（非消息事件 / 请求 / 未知帧；design/26 §4.4；切片 E3+E4） ----
+# 目的：让**到达过适配器的每一帧**至少留下可查（逐条落行）、可计数（按平台+类型聚合）的
+# 脱敏结构痕迹 —— 事故排查时「上游推过没有 / 是不是被我们过滤了」必须答得上来。
+# 落库口径：T2/T3 事件与「未知类型 / 解析失败」逐条落 channel_events（30 天保留期），
+#           纯遥测（心跳 / 生命周期 / 自身回声）只进 channel_event_counters（不参与 GC）。
+# 摘要一律走 adapter.SanitizeNoticeText；**消息正文 / 媒体 URL / OneBot request.flag
+# 等凭据绝不入库、绝不进日志**。
+# CHANNEL_EVENT_RETENTION：channel_events 行的保留期（Go duration），默认 720h（30 天）。
+#   它比文档保留期（168h）长：事件表的核心用途是**事后定案**，一周太短。
+# CHANNEL_EVENT_GC_INTERVAL：保留期清扫间隔（Go duration），默认 1h。
+#   ⚠️ 上面任一键写 0 或负数 = **关闭清扫**（同时关闭启动期那一次，日志会写明原因）；
+#      `CHANNEL_EVENT_RETENTION=0` 不是「立即清空」——那会让一次笔误抹掉唯一的取证面。
+# CHANNEL_EVENT_COUNTER_FLUSH：内存计数落盘间隔（Go duration），默认 30s。
+#   计数是**近似值**（crash 会丢 ≤ 一个间隔的计数，面板须如实标注 approx）。
+#   该键不做「显式关闭」：写 0 或负数一律回落 30s（计数落盘不是破坏性动作）。
+CHANNEL_EVENT_RETENTION=720h
+CHANNEL_EVENT_GC_INTERVAL=1h
+CHANNEL_EVENT_COUNTER_FLUSH=30s
+
 # ---- LLM 用量样本保留期（llm_usage 表；切片 U1，主人裁决「2.4 落」） ----
 # 每次成功模型调用都会把一条**非敏感**用量样本（token 计数 / 缓存两档 / 模型名 /
 # 用途 / 耗时）异步落进 llm_usage 表，供 GET /api/v1/admin/llm/usage 与面板的
@@ -243,7 +262,11 @@ CAPACITY_ENABLED=false
 CAPACITY_MIN_CONFIDENCE=0.6
 # 状态 → 允许工具名的 JSON 映射，例如
 #   {"quiet":["terminal","file"],"awake":["terminal","file","web-search"],"full":null}
-# 缺失的状态用内置默认集；null（如 "full"）= 不限制。解析失败记 WARN 并回落到内置默认。
+# 缺失的状态用内置默认集（quiet = terminal/file/knowledge/text/transcode/capability_list；
+# awake = quiet + web-search/web-fetch/http；full 不限制）；null（如 "full"）= 不限制。
+# 解析失败记 WARN 并回落到内置默认。
+# ⚠️ 自己写映射时，请把你要用的新能力一并列进去：不在允许集里的工具在
+# CAPACITY_ENABLED=true 时会从模型可见工具面里消失（Invoke 仍放行，见 design/14 §4）。
 # CAPACITY_TOOL_SETS=
 # L3 = 模型辅助的意图分类：仅当 L1 启发式与 L2 上下文仍拿不准时介入一次轻量模型调用。
 # 默认关闭（纯启发式够日常，且该层要多花一次模型调用）；关闭时该层从不运行，
@@ -436,6 +459,7 @@ ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
 # allowUsers/denyUsers(私聊用户黑白名单)。未配置时按单账号 env 路径处理。
 # 群/总限流与总上限（可选，design/12 §6 策略三/四，公共平台防刷屏/最小化打扰）：
 #   groupMsgPerMin  群聊每分钟上限（0=用默认6，-1=不限，正整数=该值）
+#   directMsgPerMin 非主人（陌生人）私聊每分钟每发送者上限（0=用默认6，-1=关闭，正整数=该值）
 #   msgPerMin       非主人消息每分钟总上限（>0 生效，0/-1=不限）
 #   maxMessages     待处理上限，接近上限时由审查模型剔除低价值消息（0=用默认50，-1=不限，正整数=该值）
 # 旧账号不配这些字段默认走「保护性默认/不限」，保持向后兼容。