会话持久化：事件存储、检查点与派生视图

Session 是事件事实来源，session-persistence 定义写入所有权与持久性屏障，JSONL 后端实现存储。检查点策略决定何时等待落盘；恢复先准备再发布，投影从事件派生当前视图。

事件事实、存储提供者与派生读取

箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。

文字关系说明与章节链接

Session →（路由事件）→ session-persistence；JSONL backend →（实现存储服务）→ session-persistence；Session →（派生当前状态）→ session-projection；checkpoint-policy →（持久性屏障）→ session-persistence；checkpoint-policy →（接入步骤边界）→ agent-loop；agent-loop →（取得写入所有权）→ session-persistence。

Session · session-persistence · JSONL backend · session-projection · checkpoint-policy · agent-loop

Session 事件通过持久化服务写入后端

dsh-session 管理事件序列，dsh-session-persistence 定义 create、open、stat、list 以及句柄上的 read、append、flush、close。

dsh-session-persistence · 接口摘录，省略上下文 · ctx.sessionPersistence.create · packages/session/session-persistence/README.md · ctx.sessionPersistence.open · packages/session/session-persistence/README.md

// 准备新会话的组件保存头信息并取得写句柄；空会话需 flush 才保证持久可列出。
const handle = await ctx.sessionPersistence.create(header)

// 恢复方以 write 申请单写者所有权，查询方以 read 打开观察；重复写拥有者会被拒绝。
const handle = await ctx.sessionPersistence.open(id, 'write')

固定版本提供 session-persistence-jsonl 后端。一个 Session 的写入由单写者协调，只读句柄不能修改；头信息与事件序列分开。写入完成后读取应看到相应前缀，close 可重复调用且不被取消。这些义务属于存储层，而不是浏览器聊天列表。

dsh-session-persistence · 接口摘录，省略上下文 · SessionHandle.append · packages/session/session-persistence/README.md

// 写拥有者追加连续事件批次；成功表示本实例可见，抗崩溃保证仍需 flush。
await handle.append(events)

检查点策略决定持久性屏障

dsh-session-checkpoint-policy 在模型请求、顶层工具副作用和完成步骤等位置落实持久化。它把“已经在运行对象里追加”与“已经越过后端持久化检查点”区分开。

dsh-session-persistence · 接口摘录，省略上下文 · SessionHandle.flush() · packages/session/session-persistence/README.md

// 检查点调用方等待已接纳事件越过后端持久化屏障；失败不能继续当作已保存。
await handle.flush()

AgentLoop 先记录并 flush 请求输入，再让模型请求开始；顶层工具调用也在工具体执行前 flush，前一步提交的响应和结果在下一步请求派生前 flush。必要持久化失败会阻止后续自动活动。检查点确定恢复时可依赖的前缀，但文件修改与 Session 写入不属于同一个跨系统事务：调用输入已 flush、外部副作用已成功、结果尚未持久记录时，仍可能崩溃。结果缺失不能证明工具没有执行，日志不提供外部副作用的恰好一次保证。

恢复和分叉先准备再发布

恢复流程读入已存历史，处理被打断的 turn 并追加对应结束记录，然后才让新的运行 Agent 接管。SessionPreparation 拥有尚未发布的对象，负责成功发布或失败回滚。

分叉通过新建 Session 的 seed 保存继承历史和数量信息，seed 必须在发布前存储；resumeSessionId 则表示继续已有持久身份。两者都能带来旧上下文，但分叉后的新事件写入子 Session，不写回父 Session。

投影与格式版本分别管理派生状态和存储

dsh-session-projection 把已提交事件折叠成当前值，session-projection-cache 为冷读取保存检查点；统计、回合轮廓和标题各有负责插件。查询结果不是第二份独立对话事实。

dsh-session-projection · 接口摘录，省略上下文 · ctx.sessionProjections.snapshot · packages/session/session-projection/README.md

// 查询消费者同步取得同一日志切面的 asOfSeq 与 values，避免把派生视图当成另一份事实。
const snapshot = ctx.sessionProjections.snapshot(session)

固定版本还提供 session-format 与相邻版本迁移包，JSONL 后端使用带代际的不可变规范文件发布后继数据。恢复不能直接改写旧日志，也不能假定任何未知事件、损坏数据或未来版本都能兼容读取。

辅助示例

读取 README 的结果已持久保存，模型总结尚在流式输出时宿主退出，恢复可利用已存结果并标记中断回合，未结算的显示片段不承诺保留。若工具改写文件后、结果持久记录前崩溃，磁盘可能已改变，而日志只留下调用；恢复以 TOOL_OUTCOME_UNKNOWN 补齐结果，不能据此自动重做有副作用的动作，应先核验状态或确认。若用户选择分叉，新历史从保存的 seed 继续，父会话保持独立；保存 Session 不会恢复已退出的进程。

设计取舍

追加事件、单写者和投影分工使恢复与审计有共同依据，代价是写入、格式演进和派生缓存都需遵守明确顺序。日志能说明系统已记录哪些事实，却不能独自提供所有外部副作用的恰好一次执行。

会话持久化：事件存储、检查点与派生视图 ​

Session 事件通过持久化服务写入后端 ​

检查点策略决定持久性屏障 ​

恢复和分叉先准备再发布 ​

投影与格式版本分别管理派生状态和存储 ​