DeepSeek Harness 会话持久化设计：基于 SessionEvent 事件溯源日志的抽象持久化服务

DeepSeek Harness 会话持久化设计基于 SessionEvent 事件溯源日志的抽象持久化服务【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本文是 DeepSeek Harness一切皆插件的 Agent 运行时中会话持久化session persistence子系统的架构与技术详解。它围绕一条核心决策展开将持久化建模为一个**能力缝capability seam**上的抽象服务直接以现有事件溯源日志SessionEvent为持久化单元通过 JSONL 与 SQLite 两个可互换后端实现「可持久化恢复、可持久化分叉、崩溃安全、宿主侧会话浏览」等能力。读完本文你将掌握SessionPersistence抽象服务的完整方法契约、JSONL 与 SQLite 后端的物理存储格式与一致性语义、崩溃回合的恢复机制以及resume跨持久化边界的完整调用链。背景与问题只有内存的会话在引入持久化之前DeepSeek Harness 的会话只存在于内存中。作为对比示例插件session-jsonl.ts在多个示例中逐字节重复只是一个只写write-only的遥测通道它缓冲session/event事件并按 JSON 行追加到文件但存在一系列根本缺陷没有读取/回放路径——只能写、不能读任何程序都无法从磁盘恢复会话没有崩溃安全——不调用fsync、不做原子写dispose 时的 drain 是 fire-and-forget发完即忘断电或进程崩溃会静默丢数据没有会话列表listing——无法枚举磁盘上有哪些会话没有格式版本化——文件格式一旦演进就无法识别新旧。其结果正如关联文档所述没有任何机制能把磁盘上的历史会话重新水合rehydrate成活跃 Agent因此「持久化恢复durable resume」「持久化分叉durable forking」和「宿主侧会话浏览host-side session browsing」三者全部不可实现。这一决策必须与既有的事件溯源模型严格对齐。在 事件溯源会话决策 中Session被定义为类型化SessionEvent的只追加日志——日志即唯一事实来源LLM 消息历史由日志推导而来deriveMessages()原始流式 chunk 以 token 级保真写入日志而组装完成的assistant/message事件才是推导的权威依据。因此持久化不能另起炉灶必须直接持久化现有的SessionEvent不得引入一套「持久化消息」的并行类型再与日志互相转换同时后端必须可替换——现在用文件存储将来用数据库存储统一收敛到同一个接口之后。核心决策持久化是能力缝而非循环或内核逻辑本决策把持久化定位为一个能力缝capability seam采用 能力缝决策 中定义的「Service Definition / Service Provider / Consumer」三角色模型。持久化不是 agent-loop 或核心逻辑的一部分而是独立的、可插拔的抽象服务。角色一Service Definition——dsh-session-persistence接口包dsh-session-persistence定义了抽象服务SessionPersistence通过ctx.sessionPersistence暴露给所有消费者。其持久化单元就是现成的SessionEvent{ type, seq, time, data }原样复用、不做任何转换——不存在SessionEvent与任何「持久化消息类型」之间的映射层。这正是与旧session-jsonl.ts示例最本质的差别。角色二Service Provider——dsh-session-persistence-jsonl实现包dsh-session-persistence-jsonl提供每会话一个只追加逻辑 JSONL 日志的物理存储文件首行是SessionHeader其后是存储记录storage records无损地表示连续的SessionEvent流。可选的assistant/chunkdelta 连续段默认使用打包行packed rows物理编码默认为带校验和的 Zstandard 帧详见 Zstandard JSONL 会话日志 与 默认打包 chunk 行也可配置为裸 JSON 行。角色三ConsumerAgent 循环、会话准备preparation、宿主侧会话浏览等消费者只注入sessionPersistence服务键从不导入 Provider 特有类型——这保证未来引入数据库后端时模型可见的契约面零变动。SessionPersistence 抽象服务接口全解在 session-persistence/src/index.ts 中SessionPersistence extends Service注册为sessionPersistence见 index.ts并声明到 Cordis 的Context模块扩充中index.ts。核心方法契约如下方法语义备注locate(meta)解析后端为某会话持有的本地产物路径不读、不建、不刷盘、不物化SQLite 一类非「每会话一产物」的后端返回undefinedindex.tscreate(meta)注册新会话元数据后端可把物理写入推迟到首次append惰性物化惰性物化下「已创建但从未 append」的会话不出现在list中被放弃的会话不留痕迹index.tsappend(id, events)持久化一批事件resolve 时即已持久durability 语义强制只追加与连续 seq 契约首事件seq必须等于存储的 next-seqload已持久关闭中断回合之后拒绝不可 JSON 序列化的event.data并指名违规事件类型index.tsprepare(id)准备 resume 所需的精确未发布 Session复用load结果构造SessionPreparationseedSource: persistence无SessionStore时报错index.tsload(id)加载不可变的平衡逻辑视图并提交冷恢复所需的收尾完整的中断末回合被保留并持久闭合只有撕裂的末记录被丢弃详见下文崩溃恢复inspect(id)检查不可变逻辑会话不提交恢复、不发布冷中断回合在内存中获得合成收尾事件撕裂的物理尾部保持原样活跃会话返回其当前不可变快照index.tsborrowSession(id)借用一次精确检查同时保留可复用的已准备源冷观察必须钉住后续prepare将保留的精确 Sessionindex.tsreadFrom(id, fromSeq)从fromSeq起读取事件——读取模型从水位线恢复的「read-from-seq」原语是分离的物理后缀读无准备缓存、无撕裂截断、无合成收尾、无协调器状态发布SQLite 可按 seq 只读后缀JSONL 仍须解析全文后跳过index.tslist()轻量元数据列举不做全日志解析每物化会话返回一个SessionHeaderindex.tslistSnapshots()列出物化会话及其廉价变更令牌revision未变化的日志重复观察返回同一 revisionload修复会改变下一次的 revision且不同后端存储互不比较index.ts此外接口还包含supportsRawArtifacts与readRaw()读取后端逐字节写下的原始产物文本保留 chunk 打包、键序、换行等后端特有序列化index.ts、ensureMaterialized()把空会话也物化为可恢复资源等扩展点并在 errors.ts 中定义了稳定的SessionPersistenceNotFoundError请求的会话身份没有物化的持久日志。写路径的编排逻辑集中在 coordinator.ts导出PersistenceCoordinator、DEFAULT_WRITE_BATCH_MAX_DELAY_MS、MAX_WRITE_BATCH_DELAY_MS等index.ts并配有独立的写批量write-behind实现 write-behind.ts。规范日志的三个关键取舍关联文档逐一记录了持久化设计中最有争议、也最能体现工程质量的关键选择。1. 规范持久日志无损保留每一个 SessionEvent含 assistant/chunk规范日志逐事件无损持久化assistant/chunk也不例外。JSONL 存储可以把一段连续的 delta run 编码为一行打包行但逻辑读取者仍能重建精确的事件边界、seq 与时间戳——打包只是物理层的空间优化逻辑层保证deriveMessages()跳过 chunk 且任何读取者看到的事件流与内存中的完全一致。这里有一个极具诱惑的替代方案被明确否决chunk 过滤的规范日志即 Codexpolicy.rs的形状。原因在于seq log.length的推导以及校验events[i].seq i都要求逻辑日志连续无空洞若把 chunk 从规范日志中滤除seq 会出现空洞同时破坏 seq 契约与 resume 能力。chunk 过滤的投影未来可以作为独立重新编号的派生视图存在但它不是规范日志相关论证见 session-persistence。2. 只追加崩溃回合被闭合绝不截断已刷盘的事件永不重写。配合 语义检查点策略系统在以下时点 drain 请求批次模型派发model dispatch之前drain 请求工具派发之前drain 已记录的顶层调用一步step完成之后drain 完整的响应/结果批次回合边界agent-loop drain 最终回合。但一个被打断的回合可能包含大量有效的中间工作如一个长任务已执行一半因此持久化策略绝不截断它冷检查cold inspection保留其连续、可解析的事件并在内存逻辑视图中追加风险分类的合成错误结果以闭合三类未应答状态——未被应答的 assistant 调用、缺失的step/end、以及带{ kind: interrupted }的turn/end。prepare或load会持久提交这些收尾事件后再返回可恢复视图合成结果保证恢复后的 provider 转录仍然有效。只有一种情况允许丢弃数据仅撕裂的末记录torn final record物理写入不完整的那一条在「已提交修复committed repair」中被丢弃而最后一个真实turn/end之前含其本身的解析错误或 seq 空洞属于损坏会使会话不可加载。3. 文件后端为规范数据库后端为验证过的即插即用替代SessionEvent与行(session_id, seq, type, time, data)一一对应append即 INSERT在断言连续 seq 契约的事务中执行读取用SELECT … ORDER BY seq。dsh-session-persistence-sqlite正是这个形状的落地它是SessionPersistence的子类接口零改动文档明确指出 opencode 在 SQLite/WAL 上运行的就是这个形态并且通过与 JSONL 后端同一套runPersistenceContract契约测试套件——同一份契约把两个后端钉在同一语义上惰性物化、逻辑中断回合闭合、单次已提交修复、连续 seq一次表达在文件字节上、一次表达在数据库行上。SQLite 数据库携带专用 application id 与单调 schema 版本schema.ts 中SCHEMA_VERSION 19、SESSION_PERSISTENCE_SQLITE_APPLICATION_ID 0x44534850。初始化采用「全有或全无」原始pristine文件在一个事务内建全部表并写入两个头部值application id schema version未版本化的文件只要含任何用户自定义 schema 对象或应用身份、外来当前版本身份、或任何非当前版本都在任何 journal-mode 变更之前拒绝。这保证了 SQLite 初始化要么提交完整的自有 schema 与头部身份要么不留下任何部分 schema 干扰下次打开。元数据在日志之外SessionHeader格式版本、cwd、血统lineage等元数据是存储关切不是可回放的对话状态因此它们存放在由dsh-session拥有的SessionHeader中通过新的只读session.header挂到Session上——永不进入SessionEventMap也永不进入deriveMessages()。createdAt被约束为非负的安全整数 Unix 纪元毫秒活跃创建与持久化注册都拒绝小数值JSONL 解码时校验头部见 format.tsNumber.isSafeInteger、 0、拒绝-0SQLite 则存储在严格INTEGER列中。JSONL 的头部行以type: session标签打头与事件行区分可选字段cwd、parentSession、seedLength、origin、agentPreset缺省即省略、绝不为 nullformat.ts。被否决的替代方案是把session/meta事件作为日志第 0 行可合并扩展。拒绝理由很清晰元数据不是可回放状态放进日志会随种子/分叉会话免费搭车但显式的「日志外头部」边界是更干净的代价。另外头部最初被拆成不可变SessionHeader加可变SessionSummary并集为SessionMeta可变 summary 后来作为死状态被移除详见 移除可变会话摘要。创建与恢复跨持久化边界的异步工厂ctx.agents.create()与ctx.agents.resume()都是异步工厂而resume额外跨越持久化边界ctx.agents.resume({ resumeSessionId })通过ctx.sessionPersistence.prepare()取得精确的未发布 Session在其持久化 id 下发布并继续其投影历史检查与恢复之间的复用关系由 会话准备决策 负责agent-loop不硬注入sessionPersistence否则非持久化 demo 会被永久 pending当服务缺失时resume以清晰错误拒绝。格式版本化与崩溃安全边界头部携带version冷读取拒绝任何非当前版本。预发布会话格式固定在SESSION_FORMAT_VERSION 0不承诺宽泛兼容当持久化用户数据确需迁移时由协调器持有显式的窄幅导入升级参考 预身份消息恢复。「只追加 刷盘」能稳健应对部分尾部写入冷准备阶段容忍但无法抵御无fsync的写入中途断电——这正是 DB/WAL 后端更强的场景。JSONL 的物理编码在 format.ts 中定义为zstd | none对应产物后缀.jsonl.zstd与.jsonlformat.ts。由于SessionId是未校验的品牌化字符串路径拼接前必须经过注入式安全编码中和../、绝对路径、NUL 与分隔符实现与测试位于 session-persistence-jsonl/src/format.ts 与 tests/jsonl.spec.ts。被否决的备选方案汇总每个关键选择都在决策处记录了被否决的替代备选方案否决理由chunk 过滤的规范日志Codexpolicy.rs形状破坏连续 seq 契约截断崩溃回合静默销毁长自主运行的既有成果session/meta事件作为日志第 0 行元数据不是可回放状态有限的分数createdAt没有生产者且偏离整数 Unix 毫秒的存储与查询列采用非原始的未版本化 SQLite 文件可能覆写无关对象或身份向循环硬注入sessionPersistence非持久化 demo 将被永久 pending影响评估与验证路径本决策带来两个新包dsh-session-persistence、dsh-session-persistence-jsonl随后又引入 SQLite 后端以及dsh-session中的元数据契约session.header、create(id?, options?)签名。买到的能力是持久化恢复与分叉历史会话可从磁盘恢复为活跃 Agent读取/回放路径审计、追踪、会话浏览成为可能崩溃容错fsync-aware 的刷盘与中断回合闭合宿主侧会话访问宿主持有全部会话的持久视图后端可互换一个接口后既可挂文件存储也可挂数据库存储。可复用的runPersistenceContract测试套件把每个后端都钉在同一套语义上只追加、连续 seq、惰性物化、逻辑恢复、整数元数据、可串行化。SQLite 初始化要么提交完整自有 schema 与头部身份要么不留部分 schema 干扰下次打开。持久化完整逻辑日志还一劳永逸地解决了事件保真问题即使 JSONL 把多个 chunk 打包进一行存储记录每个assistant/chunk也能被精确重建。继续深入阅读接口契约实现packages/session/session-persistence/src/index.ts、coordinator.ts、write-behind.ts契约测试套件packages/session/session-persistence/tests/contract.ts、persistence.spec.tsJSONL 后端packages/session/session-persistence-jsonl/src/format.ts、src/index.ts、tests/jsonl.spec.tsSQLite 后端packages/session/session-persistence-sqlite/src/schema.ts、src/index.ts、tests/sqlite.spec.ts上游模型事件溯源会话、能力缝、Zstandard JSONL 日志、会话准备、语义检查点策略【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考