README.zh.md 15 KB
description: "面向用户与维护者的持久会话存储 seam 说明，用于选择持久化后端、恢复会话，或按共享服务约定构建后端。"
kind: "package-reference"
@deepseek-ai/dsh-session-persistence
English | 中文
概述
本包让应用通过后端无关的 API 持久存储并恢复会话事件日志。读者可以创建、打开、检查、列出、追加、读取、刷新和关闭已存储会话，同时保持连续且仅追加的历史记录。只有完成 flush 才构成持久性屏障；读取方不会收到撕裂尾部或无效记录，并且每个后端实例内每个会话只允许一个写入方。若希望每个会话使用一份压缩日志，可选用随产品交付的 JSONL 后端；也可以实现具备相同可观察保证的其他后端。
目录
使用本包
挂载一个持久化后端即可让会话持久化。后端把自己注册为 ctx.sessionPersistence，并把每个已发布会话的实时事件路由进该会话的活跃写句柄；agent-loop——会话在生产环境中的发布点——在发布之前获取每个会话的写句柄，因此组合中的其他部分不变。
选择后端
seam 随产品交付 JSONL 后端。它为每个会话存储一份仅追加的 .jsonl.zstd 日志。第三方后端可以直接实现该服务；必须遵守的后端约定见下文。
服务提供什么
挂载后端后，五个服务方法寻址已存储会话：
const handle = await ctx.sessionPersistence.create(header) // store a new session, take write ownership
const handle = await ctx.sessionPersistence.open(id, 'write') // claim single-writer ownership of an existing session
const reader = await ctx.sessionPersistence.open(id, 'read') // observe without ownership
const snap = await ctx.sessionPersistence.stat(id) // header + revision (+ eventCount / sizeBytes) without a log read
const all = await ctx.sessionPersistence.list() // one snapshot per visible stored session
await ctx.sessionPersistence.flush() // backend-wide durability barrier over every active write handle
服务级 flush() 排空每个活跃写句柄已路由的事件并把其会话实体化，效果与各句柄自己的 flush 完全相同；失败按会话聚合为一个 AggregateError 而不中途放弃清扫，清扫途中被关闭的句柄视同已 flush，因为 close 本身会持久排空。
每一次日志读写都流经返回的 SessionHandle；不存在按 id 寻址的 append 或 load 方法。handle.read(offset?, length?) 返回 { eventState, events }：外层 slice 属于调用方，eventState 则区分由调用方独占的 detached 事件图与可能同时位于后端缓存中的 shared-frozen 事件图。该状态由生成方确定，即使切片为空也会保留。两种状态都能直接接管而无需复制；需要可变事件的消费方必须先克隆事件。读取绝不包含撕裂尾部，同一句柄上的重复读取绝不会观察到比先前读取更旧的状态，写句柄也能读到自己成功的 append。handle.append(events) 追加一个连续批次，其第一个 seq 等于已存储 next-seq；完成时的持久化是尽力而为的——批次被接受、有序，并对同一后端实例上的读取可见，只有完成的 flush 才承诺它在崩溃后依然存在（交付的 JSONL 后端恰好会立即持久化每个批次）。handle.flush() 是持久性屏障，同时把空的已创建会话实体化，使其可被持久列出。handle.close() 幂等且不可取消：读句柄释放本地资源；写句柄完成待处理的持久化并释放写所有权。一旦某次 append 或 flush 完成，其后在同一后端实例上开始的读取——无论经由任何句柄，还是经由 stat/list——至少能观察到该前缀。
所有权与可见性
create 与 open(id, 'write') 取得进程内单写者所有权：在持有者活跃期间第二次以写模式打开会以 SessionAlreadyOwnedError 拒绝，对已占用 id 执行 create 会以 SessionAlreadyExistsError 拒绝，在 read 句柄上执行修改会以 SessionReadOnlyError 拒绝——一种句柄类型，运行时拒绝。对已关闭句柄的任何操作会以 SessionHandleClosedError 拒绝，SessionOwnershipLostError 标记写所有权已永久丢失的写句柄（关闭并重新打开）。已创建的会话自 create 完成之刻起即可在本进程内被观察到，而后端可以把物理实体化推迟到第一次 append 或 flush；其他进程只能看到已实体化的会话，一个在崩溃前从未实体化的会话等于从未存在。
实时写路径与关闭排空
实时写路径由后端自持：它一次性安装会话监听器，把每个已发布会话的事件按 id 路由到该会话的活跃写句柄——session/event 复制进有界的内部批处理窗口，session/flush 是即时的持久性与错误观察屏障，session/disposed 执行最终排空并关闭句柄。没有活跃写句柄的已发布会话不做任何持久化。后台写入失败时按序保留其事件、暂停自动路径并记入日志；下一次显式 flush 会重试，并在再次失败时明确返回拒绝。close() 本身会先经由仍然打开的存储排空路由缓冲区再释放所有权，因此即便根 fiber 的 dispose（资源释放）并发运行各 fiber 的 disposer，后端拆卸时的关闭清扫也能保证应用关闭不丢数据。
恢复与崩溃恢复
持久化返回物理上有效的日志；语义修复属于读方。中途崩溃的会话保留其未闭合的最终轮次——单个轮次可能很大，而这些事件在崩溃前已持久追加；只有从未确认的撕裂尾部中不完整的碎片会被丢弃——从中恢复的完整记录由写路径在句柄的第一次新 append 之前持久重写。恢复（agent-loop）通过其写句柄读取已存储日志，计算 interruptedTurnClosers——合成 tool/result 错误、任何未闭合的 step/end，以及 turn/end {interrupted}——并把它们作为普通批次通过同一句柄追加。只读观察方（session-query）仅在内存中用同样的 closer 配平被中断的冷日志。
失败与恢复
当前构建无法忠实解读的存储日志会被拒绝，并返回指明拒绝方向的错误，绝不会被误读。SessionHandle 只暴露由 SESSION_FORMAT_VERSION 标识的当前逻辑记录；提供方必须在返回句柄前转换任何受支持的历史存储，随产品交付的 JSONL 提供方会通过静态 catalog 迁移受支持的历史代际。更新的格式会要求操作者升级 harness。本构建不认识的事件类型会被拒绝，除非其信封标记为 ignorable；已提交前缀中的损坏以 SessionPersistenceCorruptionError 拒绝。