Session Persistence zh

会话持久化

上游会话事件持久化后端在 Edge 中的适配。

上游参考：会话文档

上游提供了什么

上游将会话事件以追加式 JSONL 文件持久化——每个 session 一个文件。SessionPersistence 接口定义契约：物化 session、追加事件批次、列出 session、读取历史页面、提交崩溃恢复修复、刷新持久性检查点。事件是无损 JSON，连续序列号。

Edge 改了什么

替换件 JSONL → DO SQL

DurableObjectSessionPersistence 使用五张 Durable Object SQL 表实现上游 SessionPersistence 接口：

表	用途
dsh_session_persistence_state	Schema 版本追踪
dsh_sessions	Session 头信息
dsh_session_events	事件日志
dsh_edge_blank_sessions	等待首次 prompt 的空白 session
dsh_session_summaries	物化的会话列表元数据

替换件 Chunk packing

连续的 assistant/chunk、reasoning/chunk 和 tool-call/chunk 事件在写入时通过 packChunkRuns() 压缩为单条存储行。读取时通过 decodeStorageRecord() 解码回单独事件。长 session 的 DO SQL 行数减少 5–10 倍。

替换件 物化摘要

dsh_session_summaries 存储预计算的会话列表元数据。在 appendBatch() 的事务内原子更新。列表操作通过 SESSION_SUMMARY_MATERIALIZED 读取——单次 JOIN，无子查询。子查询版 SESSION_SUMMARY_SELECT 仅用于启动时修复过期行。

Edge 没有改什么

• SessionPersistence 接口契约
• 事件格式、序列号和追加式保证
• Flush/checkpoint 语义
• 崩溃恢复修复（commitRepair()）
• Session fork 和 seed 机制

性能特征

写入路径

appendBatch() 在 storage.transactionSync() 内运行：打包 chunk、插入存储记录、递增 revision、更新物化摘要——全部原子。典型的 50 事件 turn 在 chunk packing 后产生约 10 条存储行。

读取路径 — 会话列表

SESSION_SUMMARY_MATERIALIZED 是 SELECT ... FROM dsh_sessions JOIN dsh_session_summaries，按 updated_at DESC 分页。不访问事件表。O(页面大小)。

读取路径 — 历史页面

历史读取使用 SELECT ... FROM dsh_session_events WHERE session_id = ? AND seq BETWEEN ? AND ?，可配置页面限制（最多 65,536 事件）。打包行在读取时解码。客户端向后分页；goal/title 状态来自投影缓存，不需要扫描完整日志。

启动时修复

syncSummaries() 每次 DO 激活运行一次。检测摘要 revision 与 session revision 不一致的条目并重算。受限于过期 session 数量（正常关闭后通常为零）。

架构总结

组件	分类	上游对应
DurableObjectSessionPersistence	替换	JSONL 文件后端
Chunk packing	替换	不需要（文件 I/O 无行数限制）
物化摘要	替换	内存扫描（上游不需要）

关键观察：会话持久化是 Edge 最大的替换件——约 1,000 行 DO SQL 代码。但它严格遵循上游的 SessionPersistence 接口。所有优化（chunk packing、物化摘要）对上游插件不可见——它们看到的是相同的 append/read/flush 契约。