DSH plugin 的会话持久化句柄:flush 屏障、崩溃恢复与格式拒绝到底该怎么处理
“写入成功了,重启却少一段”,这类问题几乎都不是后端坏了,而是把 append 当成了 flush。 DSH plugin 的会话持久化是一条能力 seam,真正的持久性承诺只挂在 flush 上。理解句柄的边界,比换后端更有效。 DSH插件 只要碰过写入与恢复,就绕不开句柄,这份契约对 DeepSeek插件 同样成立。
句柄是唯一入口,不是按 id 寻址的服务方法
每一次日志读写都经由句柄流动,句柄是跨进程写租约把守的唯一入口。(来源) 这带来三个硬性后果:
- 你无法绕开句柄直接按 id 读写事件;
- 一种句柄类型同时服务读与写,区分靠
access,不靠两个类; - 在 read 句柄上执行修改是运行时的
SessionReadOnlyError,不是类型层面的拆分。
写所有权是进程内单写者语义:已有活跃持有者时,第二次 open(id, 'write') 会以 SessionAlreadyOwnedError 拒绝。这不是限制灵活性,而是保护正在跑的轮次——否则修复逻辑会和活跃写入打架。
服务本身只暴露 create、open、stat、list 四个方法,且没有平行的持久化事件类型。create 与 open 返回逐会话的 SessionHandle,句柄再提供 read、append、flush、close。
read 的切片保证与 close 语义
read 只返回合法的连续前缀,撕裂尾部永远不会给你。(来源)
read(offset?, length?, options?) 返回 SessionHandleReadResult,含两项:eventState 与 events。events 是调用方独占的外层数组;eventState 说明事件值是完全独占的 detached,还是深度冻结后才共享的 shared-frozen。切片保留生产者的状态,即使一个事件都不剩。
三条读取保证值得抄进排查清单:
- 切片是合法日志前缀段,撕裂的物理尾部不会返回;
- 同一句柄上的重复读取,绝不会观察到比先前读取更旧的状态;
- 写句柄可以读到它自己成功 append 的内容。
close() 是唯一的拆除操作:幂等、异步、刻意不可取消,Symbol.asyncDispose 委托给它。关闭之后对句柄的任何操作都会以 SessionHandleClosedError 拒绝。所以别在 close() 之后复用句柄做“最后一次读”,那是必然失败。
append 尽力而为,flush 才是持久性屏障
append 解决“顺序与可见”,flush 才解决“扛不扛得住崩溃”。(来源)
append(events) 要求批次连续,第一条事件的 seq 必须等于已存储的 next-seq,已提交事件永远不会被重写。它解析时承诺的是:批次被接受、有序、对本后端实例的读取可见。仅此而已——后端可以把物理写入缓冲或批处理在 append 之后。
flush() 是持久性屏障:解析时每个已确认的 append 都已持久,会话已对其他进程物化;一个空的已创建会话也在这一刻变成可持久列出。需要扛崩溃的调用方必须 flush。若某后端在 append 解析时已经落盘,它把 flush 当作按需物化即可。
可见性分两层,别混为一谈:
- 已创建的会话从
create解析那刻起,在本进程内就能被stat/list/open观察到; - 其他进程只能看到已物化的会话,而一个崩溃前从未物化的会话等于从未存在。
这就是“本机日志明明有、换台机器就没了”的成因:不是丢数据,是它从未物化。
崩溃恢复把中断轮次交给读方修
持久化层不修开放轮次,只保证物理有效;闭合事件由 resume 追加。(来源)
一个在轮次中途崩溃的日志,以打开的 turn/start 结尾而没有 turn/end。持久化不会截断或修复它,因为长周期任务的单个轮次可能非常庞大,那些事件在崩溃前已经持久追加。它只丢弃撕裂物理尾部里不完整的碎片——JSONL 后端会把撕裂的 Zstandard 帧部分解码,恢复出的完整记录由写路径在句柄第一次新 append 之前持久重写。
修复是读方的职责。resume(agent-loop)通过写句柄读取已存储日志,计算 interruptedTurnClosers:缺失的工具错误、任何未闭合的 step/end,以及一个合成的 turn/end { reason: { kind: 'interrupted' } },并在发布 Session 之前把它们作为普通批次通过同一句柄追加。
两个推论:修复只在写所有权下写入,所以并发的 open(id, 'write') 会被拒绝,而不是让修复与活跃轮次竞速;只读观察方(session-query)只在内存里用同样的闭合事件配平冷日志,不回写任何内容。interrupted 也是唯一一个不由循环发出的 TurnEndReason。
SessionHeader 与 SessionLocation:元数据不是日志
header 与 location 都不进事件日志,也不会到 deriveMessages()。(来源)
SessionHeader 与事件日志分开存储,携带 version、id、createdAt、可选 cwd、parentSession、isSeeded、origin、delegationDepth 与 agentPreset。逻辑 header 通过 session.header 附加,而 fork 继承的精确前缀长度由 inheritedEventCount 暴露,不属于普通 header 元数据。
两个字段容易被误用:origin: 'subagent' 只是展示分类,不证明这个 child 可以继续;delegationDepth 之所以持久化,是为了让递归预算在重启与恢复后仍然有效——只在运行时记深度,恢复出的 child 会被当成顶层。
SessionLocation 则更窄:它是后端解析的逐会话产物路径,用于诊断与导出快照,不授权读取,也不是持久化内容。JSONL 提供项目/会话目录内 transcript 的绝对路径,没有逐会话工件的后端则不提供。
格式拒绝:数据没坏,只是本构建不认
失败要分两种:读不懂和真损坏,处理方式完全不同。(来源)
后端用 SessionFormatUnsupportedError 拒绝无法可靠解读的日志,它与 SessionPersistenceCorruptionError 区分,因为数据并没有损坏。几条具体规则:
stat与list对最高规范 generation 分类,并在不读取、不改变正文的前提下转换受支持的历史 header;- 历史
open共享每个会话唯一的一次 migration preparation,保持每个源路径、字节与 inode 不变; - JSONL 的读打开直接从内存结果返回句柄而不发布;写打开在持有单写者 claim 与文件 lease 时复用 preparation、排他发布最终 current generation;
- 即使仍有较旧的可读 generation,最高的未来 generation 仍会导致拒绝。
当前格式恢复会保留已安装扩展与带 ignorable: true 的未知事件;但历史 v0/v1/v2 迁移会拒绝未知类型,即使它带了 ignorable 标记。这条差异是迁移安全的一部分,不要用“我加了 ignorable”去推断旧格式也能过。
验证:强杀进程后重启
恢复验证必须真的强杀,优雅退出测不出开放轮次。(来源) 六步:
create拿到写句柄,append一个turn/start与若干事件,不调flush,强杀进程。- 重启后
stat该 id,断言会话可能存在但最后一批事件缺失——这验证 append 不等于持久。 - 重复一次,这次在强杀前
flush(),断言重启后事件齐全。 - 构造一个只有
turn/start没有turn/end的日志,用resume恢复,断言追加了合成的interrupted结束原因。 - 在恢复进行中尝试
open(id, 'write'),断言以SessionAlreadyOwnedError拒绝。 - 用一个未来 generation 的日志调
open,断言以SessionFormatUnsupportedError拒绝,而不是当成损坏。
句柄与上层 agent 的关系,可以对照持久化 seam 概览;更新后会话打不开的具体排查,见升级后会话迁移。
一句话收束: 读写只走句柄,append 只管顺序可见、flush 才管崩溃,开放轮次交给 resume 闭合,读不懂与真损坏要分开报错。
常见问题
不能,DSH plugin 会以 SessionAlreadyOwnedError 拒绝。DSH plugin 用进程内单写者所有权保护活跃会话,已有活跃持有者时第二次写打开直接失败,避免修复与活跃轮次竞速。
不代表,DSH plugin 的 append 只是尽力而为。DSH plugin 在 append 解析时承诺批次被接受、有序且对本后端实例的读取可见;只有 flush 解析才承诺它能扛住崩溃。
不会,DSH plugin 的持久化只丢弃撕裂物理尾部的不完整碎片。DSH plugin 把打开的 turn/start 原样返回,由 agent-loop 的 resume 计算并追加 interruptedTurnClosers,然后才发布 Session。
不是,DSH plugin 用两个不同错误区分这两件事。DSH plugin 的 SessionFormatUnsupportedError 表示本构建无法可靠解读,数据并没有损坏;SessionPersistenceCorruptionError 才表示确实损坏。
相关术语
- SessionHandle
- SessionHandle 是通向已存储会话的一条打开通道,承载全部日志访问与单写者所有权,提供 read、append、flush 与 close。— packages/session/session-persistence/src/index.ts
- SessionLocation
- SessionLocation 是后端解析的逐会话产物路径,只用于诊断与导出快照,不授权读取,也不是持久化会话内容。— packages/session/session-persistence/src/index.ts
- SessionFormatUnsupportedError
- SessionFormatUnsupportedError 表示本构建无法可靠解读该日志,与真正的数据损坏错误区分开。— DeepSeek Harness 官方参考 - 会话持久化
- interruptedTurnClosers
- interruptedTurnClosers 是 resume 计算出的闭合批次,包含缺失的工具错误、未闭合 step/end 与合成的 interrupted turn/end。— DeepSeek Harness 官方参考 - 会话持久化
来源
- DeepSeek Harness 官方参考 - 会话持久化· deepseek-ai
- packages/session/session-persistence/src/index.ts· deepseek-ai