ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 持久化事件目录:哪些事件会落盘、哪些只是实时广播与查表方法

概念与架构发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH plugin持久化事件SessionEventMap会话日志
官方 persistence-catalog 把每个持久化 Session 事件、事件信封与类型指纹列在一起。本文教你看懂 surface 与 log-only 的分界、信封字段、外部插件事件为何缺席,以及怎么查一个事件落不落盘。

持久化事件目录回答的是一个很具体的问题:这个事件会不会写进会话日志,写了之后模不模型可见。 官方目录覆盖每个持久化的 Session 事件、逻辑与物理 header、事件信封,以及所有 SessionEventMap 声明合并(来源)。会查这张表,就不会把「实时广播」误当成「已落盘」。

DeepSeek Harness 目录范围:正式事件与实验记录分开

正式事件和实验性记录分属两个目录,不要混着读。 官方把实验性记录单独列在 experimental-persistence-catalog 中,正式目录只覆盖仓库声明的持久化事件(来源)。

三个范围要点:

  1. 覆盖本仓库 — 外部插件类型不在目录里,需要独立声明;
  2. 包含 header 与信封 — 不只是事件 data,还包括逻辑/物理 header 与统一外壳;
  3. 目录可重新生成与校验 — 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 事件不产生模型历史(来源)。

这条分界带来三个直接结论:

  1. 想让模型看到的内容,必须是 surface 事件 — 只写 log-only,模型下一次请求看不到;
  2. 不想污染模型历史的事实,用 log-only — 例如诊断信息、内部状态变更;
  3. surface 事件的设计要更谨慎 — 它会进入重放、压缩、引用与计费链路。

一个常见错误是把「需要持久化」等同于「需要 surface」。持久化只要求落盘,surface 还要求进入模型上下文。两者不是一回事。

判断方法:问一句「模型下一次请求需不需要看到这条记录?」需要,才是 surface;不需要,就留在 log-only。

DeepSeek Harness 外部插件事件为什么不在目录里

官方目录只覆盖本仓库,外部插件的 SessionEventMap 扩展需要自己声明。 官方说明:目录覆盖本仓库;外部插件类型需要独立声明,不属于本目录(来源)。

这意味着外部插件要自己做三件事:

  1. 声明类型 — 通过 SessionEventMap 合并,给出 type 与 data 形状;
  2. 处理迁移 — 事件格式变化时,提供从旧到新的迁移;
  3. 标注 surface 或 log-only — 决定它是否进入模型历史。

只声明类型、不做迁移,升级后旧会话可能打不开;只做 surface、不做投影,模型可能看到无法渲染的内容。三件事缺一不可。

外部插件也不应该假设官方目录会替它校验。目录的 verify 只覆盖本仓库;插件自己的类型错误,要到运行时或测试里才暴露。

DeepSeek Harness 类型指纹与格式迁移

类型指纹是给迁移和评审用的,不是给业务代码用的。 官方的机器可读目录包含所有可达规范化类型及其 SHA-256 摘要;注释、源码位置、别名、擦除的品牌标记、readonly 标记以及无语义重排不影响摘要,而元组顺序、属性名、值类型和可选性会影响(来源)。

这条规则解释了两件事:

  • 文本 diff 变了,指纹不一定变 — 注释或位置变化不会破坏兼容;
  • 文本看起来没变,指纹可能变了 — 属性可选性、元组顺序变化会改变语义。

指纹变化时,不要直接判断「不兼容」;先看变更记录与历史格式,确认是否需要迁移。真正的兼容性由解析与迁移链路决定,不是由 diff 决定。

写插件事件时,尽量避免改属性名与可选性;必须改时,提供迁移,而不是让旧日志自然失效。

DeepSeek Harness 查表练习:这个事件落不落盘

拿一个事件走一遍,比背字段有用。 以 tool/result 为例(来源):

  1. 在正式目录搜 type — 确认它是否在持久化事件列表里;
  2. 看信封字段 — 确认它使用统一信封,data 里是工具结果;
  3. 判断 surface 还是 log-only — 它是否进入模型历史,决定后续投影与压缩行为;
  4. 看类型指纹 — 如果插件要读它,确认自己的解析与当前版本一致;
  5. 看迁移记录 — 如果跨版本读旧日志,确认是否有格式迁移。

五步走完,你就能回答「这个事件落不落盘、模型看不看得到、跨版本还能不能读」三个问题。这比在会话日志里盲搜字段快得多。

旧文 dsh-session-persistence-explained 讲持久化机制,develop-session-log 讲怎么扩展事件;本篇补的是官方目录的查表方法。目录、机制、扩展三件套一起用,持久化问题就不会只剩「日志里有什么」。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 的持久化事件目录和会话日志有什么区别?

DeepSeek Harness 的持久化事件目录是类型清单,列出哪些事件会落盘及其结构;会话日志是实际写下的记录。目录回答「能不能写」,日志回答「写了什么」。

DeepSeek Harness 的 surface 事件和 log-only 事件怎么区分?

DeepSeek Harness 的 surface 事件会产生模型历史,log-only 事件只记录不进入模型历史。判断一个事件是否影响模型所见,看它属于哪一类。

DeepSeek Harness 的外部插件事件为什么不在官方持久化目录里?

DeepSeek Harness 里,因为官方目录只覆盖本仓库声明的类型。DeepSeek Harness 的外部插件如果扩展了 SessionEventMap,需要自己声明类型与迁移,不能依赖官方目录替它保证。

DeepSeek Harness 的持久化类型指纹变化,是否一定意味着不兼容?

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 官方文档 - 会话持久化事件目录

来源