DeepSeek Harness 持久化事件目录:哪些事件会落盘、哪些只是实时广播与查表方法
持久化事件目录回答的是一个很具体的问题:这个事件会不会写进会话日志,写了之后模不模型可见。 官方目录覆盖每个持久化的 Session 事件、逻辑与物理 header、事件信封,以及所有 SessionEventMap 声明合并(来源)。会查这张表,就不会把「实时广播」误当成「已落盘」。
DeepSeek Harness 目录范围:正式事件与实验记录分开
正式事件和实验性记录分属两个目录,不要混着读。 官方把实验性记录单独列在 experimental-persistence-catalog 中,正式目录只覆盖仓库声明的持久化事件(来源)。
三个范围要点:
- 覆盖本仓库 — 外部插件类型不在目录里,需要独立声明;
- 包含 header 与信封 — 不只是事件 data,还包括逻辑/物理 header 与统一外壳;
- 目录可重新生成与校验 —
gen-persistence-catalog生成,verify-persistence-catalog检查新鲜度。
因此,目录是「本仓库的持久化契约清单」,不是「你这台机器当前有哪些事件」。第三方插件可以扩展事件,但它的类型不会自动出现在官方目录里。
读目录时先确认你要查的事件属于正式还是实验。实验记录可能随版本变化,不适合作为对外插件契约;正式事件才有稳定的迁移与回放规则。
DeepSeek Harness 事件信封的五个字段
所有持久化事件都套在同一个信封里,字段固定。 官方列出的信封字段是:type、seq、time、data、可选的 ignorable,以及条件字段 surfaceOp / sourceEventSeqs(来源)。
| 字段 | 作用 | 排查时的用法 |
|---|---|---|
| type | 事件类型 | 按类型过滤与查表 |
| seq | 会话内序号 | 判断缺口、重复与顺序 |
| time | 记录时间 | 对齐外部日志与用户操作 |
| data | 事件负载 | 查具体字段与类型 |
| ignorable | 是否可忽略 | 判断旧版本能否跳过 |
| surfaceOp | 条件性的 surface 操作 | 判断是否影响模型历史 |
| sourceEventSeqs | 条件性的来源序号 | 追踪派生关系 |
seq 是最值得关注的字段。断号、重复或倒退,都可能意味着日志损坏或并发写入;排查会话打不开时,先看 seq 是否连续,比看 data 更快。
ignorable 决定旧版本遇到未知事件时能否跳过。它不是「这个事件不重要」,而是「不认识它时能不能继续」。写插件事件时,如果旧版本跳过会导致状态不一致,就不要标 ignorable。
DeepSeek Harness surface 与 log-only 的分界
surface 与 log-only 的分界,是「会不会产生模型历史」。 官方明确:surface 事件产生模型历史,log-only 事件不产生模型历史(来源)。
这条分界带来三个直接结论:
- 想让模型看到的内容,必须是 surface 事件 — 只写 log-only,模型下一次请求看不到;
- 不想污染模型历史的事实,用 log-only — 例如诊断信息、内部状态变更;
- surface 事件的设计要更谨慎 — 它会进入重放、压缩、引用与计费链路。
一个常见错误是把「需要持久化」等同于「需要 surface」。持久化只要求落盘,surface 还要求进入模型上下文。两者不是一回事。
判断方法:问一句「模型下一次请求需不需要看到这条记录?」需要,才是 surface;不需要,就留在 log-only。
DeepSeek Harness 外部插件事件为什么不在目录里
官方目录只覆盖本仓库,外部插件的 SessionEventMap 扩展需要自己声明。 官方说明:目录覆盖本仓库;外部插件类型需要独立声明,不属于本目录(来源)。
这意味着外部插件要自己做三件事:
- 声明类型 — 通过
SessionEventMap合并,给出 type 与 data 形状; - 处理迁移 — 事件格式变化时,提供从旧到新的迁移;
- 标注 surface 或 log-only — 决定它是否进入模型历史。
只声明类型、不做迁移,升级后旧会话可能打不开;只做 surface、不做投影,模型可能看到无法渲染的内容。三件事缺一不可。
外部插件也不应该假设官方目录会替它校验。目录的 verify 只覆盖本仓库;插件自己的类型错误,要到运行时或测试里才暴露。
DeepSeek Harness 类型指纹与格式迁移
类型指纹是给迁移和评审用的,不是给业务代码用的。 官方的机器可读目录包含所有可达规范化类型及其 SHA-256 摘要;注释、源码位置、别名、擦除的品牌标记、readonly 标记以及无语义重排不影响摘要,而元组顺序、属性名、值类型和可选性会影响(来源)。
这条规则解释了两件事:
- 文本 diff 变了,指纹不一定变 — 注释或位置变化不会破坏兼容;
- 文本看起来没变,指纹可能变了 — 属性可选性、元组顺序变化会改变语义。
指纹变化时,不要直接判断「不兼容」;先看变更记录与历史格式,确认是否需要迁移。真正的兼容性由解析与迁移链路决定,不是由 diff 决定。
写插件事件时,尽量避免改属性名与可选性;必须改时,提供迁移,而不是让旧日志自然失效。
DeepSeek Harness 查表练习:这个事件落不落盘
拿一个事件走一遍,比背字段有用。 以 tool/result 为例(来源):
- 在正式目录搜 type — 确认它是否在持久化事件列表里;
- 看信封字段 — 确认它使用统一信封,
data里是工具结果; - 判断 surface 还是 log-only — 它是否进入模型历史,决定后续投影与压缩行为;
- 看类型指纹 — 如果插件要读它,确认自己的解析与当前版本一致;
- 看迁移记录 — 如果跨版本读旧日志,确认是否有格式迁移。
五步走完,你就能回答「这个事件落不落盘、模型看不看得到、跨版本还能不能读」三个问题。这比在会话日志里盲搜字段快得多。
旧文 dsh-session-persistence-explained 讲持久化机制,develop-session-log 讲怎么扩展事件;本篇补的是官方目录的查表方法。目录、机制、扩展三件套一起用,持久化问题就不会只剩「日志里有什么」。
常见问题
DeepSeek Harness 的持久化事件目录是类型清单,列出哪些事件会落盘及其结构;会话日志是实际写下的记录。目录回答「能不能写」,日志回答「写了什么」。
DeepSeek Harness 的 surface 事件会产生模型历史,log-only 事件只记录不进入模型历史。判断一个事件是否影响模型所见,看它属于哪一类。
DeepSeek Harness 里,因为官方目录只覆盖本仓库声明的类型。DeepSeek Harness 的外部插件如果扩展了 SessionEventMap,需要自己声明类型与迁移,不能依赖官方目录替它保证。
DeepSeek Harness 里不一定,具体取决于配置。DeepSeek Harness 的指纹忽略注释、源码位置、别名和无语义重排;元组顺序、属性名、值类型和可选性变化才会影响指纹。指纹变化需要结合迁移记录判断。
相关术语
- 持久化事件目录
- 持久化事件目录是 DeepSeek Harness 官方生成的类型清单,覆盖持久化 Session 事件、事件信封与所有 SessionEventMap 声明合并。— DeepSeek Harness 官方文档 - 会话持久化事件目录
- 事件信封
- 事件信封是 DeepSeek Harness 持久化事件的统一外壳,包含 type、seq、time、data、可选的 ignorable 以及条件字段 surfaceOp 与 sourceEventSeqs。— DeepSeek Harness 官方文档 - 会话持久化事件目录
- surface 事件
- surface 事件是 DeepSeek Harness 中会产生模型历史的事件,模型可见上下文由这些事件投影而来。— DeepSeek Harness 官方文档 - 会话持久化事件目录
- log-only 事件
- log-only 事件是 DeepSeek Harness 中只写入日志、不产生模型历史的事件,用于记录事实而不改变模型所见。— DeepSeek Harness 官方文档 - 会话持久化事件目录
来源
- DeepSeek Harness 官方文档 - 会话持久化事件目录· deepseek-harness
- DeepSeek Harness 官方文档 - 会话子系统· deepseek-harness