性能优化提案：压缩 remote.mux WebSocket（permessage-deflate）并为首屏快照设界——移动端/远端链路实测首屏缩小 5~8 倍

[lekifier]

性能优化提案：压缩 remote.mux WebSocket（permessage-deflate）并为首屏快照设界——移动端/远端链路实测首屏缩小 5~8 倍

两个相互独立、可分别采纳的一行级改动，均已在本机 0.1.5-rc.1 上完整验证（含公网链路实测）。
附：#2654 / #2598 的分块过滤方向在 v3 格式下已无对象，建议关闭（见「与既有讨论的关系」）。

现象（网关日志实测）

环境：dsh web 0.1.5-rc.1，经反向代理 + Cloudflare Tunnel 暴露，iPhone Safari 蜂窝网络访问。

打开一个进行中的会话时，浏览器与 Host 建立 /api/remote.mux WebSocket（101），Host 把首屏快照整体推下。反向代理访问日志里，近 30 分钟内每一次 mux 连接都以异常告终：

时间	推送字节	持续	终止方式
14:04	1.99 MB	167 s	DC（下游断连）
14:09	2.89 MB	147 s	DC
14:11	1.62 MB	27 s	UC（上游 RST）
14:14	1.43 MB	26 s	DC
14:20	2.18 MB	70 s	DC
14:24	1.70 MB	87 s	DC

每次断连后客户端秒级重连 → 整份快照再次全量重推 → 再断，形成重推风暴；弱网（20–30 KB/s 有效吞吐）下 2 MB 需要 70170 s，而移动端浏览器锁屏/切后台会静默挂起 WebSocket（#2842），传输几乎必然中途死亡——表现为「会话内容永远加载不出来」。进行中的会话最严重：快照随会话增长、且叠加 assistantStream 累加器快照与实时流帧。

根因

1. 首屏快照走未压缩 WS 文本帧：follow() 的 opening snapshot 是最近 maxMessages=50 条消息窗口内的全部持久化事件（实测两个真实会话 835 KB / 663 KB），以 JSON 文本帧原样下发。
2. 重连无增量：每次 mux 重连都重推整份快照，断连成本随快照线性放大。
3. 移动端挂起窗口：[Bug] Question/approval cards missing on mobile until page refresh — WebSocket silently suspended, no heartbeat / no visibilitychange reconnect #2842 描述的静默挂起（无 close 事件）给了传输一个事实上的数秒硬窗口，大传输必死。

另需澄清一点（实测）：v3 会话格式已不持久化 assistant/chunk（v2 日志读取时折叠进 assistant/message）。在 0.1.5-rc.1 上对 v2/v3 两种格式各取一页验证，assistant/chunk 等流式分块事件均为 0——#2654 / #2598 针对的分块膨胀已由格式迁移解决。当前载荷是真实消息与工具结果内容，需要的是压缩与设界，不是过滤。

方案（两个独立改动，可分别采纳）

A. 一行开启 permessage-deflate（本提案的主要增量，检索未发现既有 issue/讨论）

packages/api/gateway（RemoteStreamMuxServer）：

- server = new WebSocketServer({ noServer: true });
+ server = new WebSocketServer({ noServer: true, perMessageDeflate: true });

• 浏览器（Chrome / Safari / Firefox）默认均在握手时提供 PMD；ws 库原生支持，协商失败时静默回落不压缩，无兼容性风险。
• 实测同内容 gzip（level 1）压缩率 3.4×（834 KB → 249 KB）；PMD（zlib 默认级别）同量级。
• 代理链透传是常见顾虑，已实测排除：经 Cloudflare Tunnel → Envoy/Istio → Caddy → 本地桥的完整公网链路上，握手响应原样带回扩展头：

HTTP/1.1 101 Switching Protocols
connection: Upgrade
sec-websocket-accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
sec-websocket-extensions: permessage-deflate
server: istio-envoy
upgrade: websocket

• 代价：服务端每连接 zlib 上下文（默认窗口 ~32 KB 量级）与少量 CPU；消息体积小，可忽略。可选 perMessageDeflate: { threshold, zlibDeflateOptions } 微调。

B. 首屏快照设界（与 #1706 同方向，作用于 follow 首屏）

packages/api/session-controller（follow() 的 opening snapshot 分页处）：

- const page = paginate(events, void 0, request.maxMessages ?? DEFAULT_MAX_MESSAGES);
+ const page = paginate(events, void 0, Math.min(request.maxMessages ?? DEFAULT_MAX_MESSAGES, SNAPSHOT_MAX_MESSAGES)); // 本地验证取 15

• 更鲁棒的形态是 [Bug] Web GUI cannot open very large sessions — session.history pages are unbounded by event count #1706 提议的事件数硬顶（MAX_PAGE_EVENTS，切割仍落消息边界）——两者可合并：快照页同时受消息数与事件数约束。
• 客户端零改动兼容：现有 hasMore / loadOlder 分页路径不变（实测 capped 首屏渲染正常、「加载更早」回翻正常、页间连续性断言不受影响）。
• 实测：835 KB → 584 KB、663 KB → 393 KB（15 条帽）。

组合效果（本机实测数字）

会话快照	现状	×快照设界	×PMD（3.4×）	25 KB/s 弱链路
会话 A	835 KB	584 KB	~170 KB	25–40 s 必断 → 6–9 s
会话 B	663 KB	393 KB	~106 KB	22–33 s 必断 → 4–5 s

重连重推成本同比例缩小（2 MB+ → ~150 KB 量级），重推风暴随之消失。

验证

• dsh 0.1.5-rc.1 本机补丁全量验证：loopback 与公网链路握手实录（上文）、follow 流探测（snapshotBytes / records / hasMore 前后对照）、浏览器实测 capped 首屏 + loadOlder 回翻 + 回合进行中刷新完整恢复 + 流式动画不受影响（v3 的 assistant-stream 帧路径不动）。
• 分块零载荷结论：v2 日志（含 2,298 条 assistant/chunk）与 v3 日志各取一页，页面分块事件均为 0。

与既有讨论的关系

• [Bug] Web GUI cannot open very large sessions — session.history pages are unbounded by event count #1706（页按事件数设界）：同方向。本提案把设界点放在 follow 首屏快照（移动端主路径），建议合并为「消息数 + 事件数」双约束。
• History payload bloat: a ~50-message page returns ~270k stream-delta events (~64 MB) #2654 / 性能优化提案：历史加载剔除流式分块事件（附完整实现与测试） #2598（分块膨胀与过滤）：实测 v3 格式下读路径已无分块事件（v3 不持久化、v2 读取折叠），该方向已由格式迁移解决，建议关闭。
• [Bug] Question/approval cards missing on mobile until page refresh — WebSocket silently suspended, no heartbeat / no visibilitychange reconnect #2842（移动端 WS 静默挂起）：互为因果的两半——它主张心跳 + visibilitychange 重连（检测），本提案把单次传输压进挂起窗口之内（让传输来得及完成），互补。
• [Bug] dsh-client-connection streamOpenTimeoutMs=3000 causes "Signal timed out" on slow/remote links #3413（慢链路握手超时 3 s）：同链路族问题。
• DSH: Why Opening a Large Cold History Session Can Stall the Whole Web Server — A Systematic Root-Cause Analysis and Optimization Roadmap #4416（冷加载全量物化卡死）：IO/解析侧优化；本提案是传输侧，正交。

---

English summary

Proposal: compress the remote.mux WebSocket with permessage-deflate (one line) and bound the follow-stream opening snapshot — measured 5–8× smaller first paint on mobile/remote links.

• Measured problem: opening an in-progress session pushes a 0.4–2.9 MB uncompressed opening snapshot over /api/remote.mux; on a ~25 KB/s mobile link every connection died mid-transfer (gateway access logs: DC/UC on 100% of mux connections in a 30-minute window), and each reconnect re-pushed the full snapshot — a repush storm that made session history unloadable on phones.
• Fix A (main increment; no existing issue found): new WebSocketServer({ noServer: true, perMessageDeflate: true }) in the API gateway's RemoteStreamMuxServer. Browsers offer PMD by default; the ws library negotiates it natively and falls back silently. Measured 3.4× on identical content (834 KB → 249 KB via gzip level 1). Proxy-chain passthrough verified end-to-end through Cloudflare Tunnel + Envoy/Istio + Caddy (101 response carries sec-websocket-extensions: permessage-deflate).
• Fix B (same direction as [Bug] Web GUI cannot open very large sessions — session.history pages are unbounded by event count #1706, applied to the follow opening snapshot): cap the opening snapshot page (locally verified with Math.min(maxMessages, 15); best merged with [Bug] Web GUI cannot open very large sessions — session.history pages are unbounded by event count #1706's event-count cap, message-boundary cut). Zero client changes — the existing hasMore/loadOlder journal path is untouched. Measured 835→584 KB / 663→393 KB.
• Combined: ~106–171 KB first paint → 4–9 s on a 25 KB/s link (previously 25–170 s, guaranteed failure); reconnect repushes shrink proportionally.
• Note closing History payload bloat: a ~50-message page returns ~270k stream-delta events (~64 MB) #2654/性能优化提案：历史加载剔除流式分块事件（附完整实现与测试） #2598: v3 session logs no longer persist assistant/chunk (v2 logs fold chunks into assistant/message when read) — verified zero chunk events in pages of both formats on 0.1.5-rc.1, so chunk filtering is now redundant; the remaining payload is real content that needs compression and bounds.
• Both changes verified live on 0.1.5-rc.1 (handshake captures above, follow-stream probes, browser tests: capped first paint, loadOlder backfill, mid-turn reload restore, streaming animation untouched).