「会话还在列表里,说明数据没问题;打不开大概是 UI 的锅,重启试试。」 这个推断把三件事混为一谈:索引可见、记录完整、读取路径正确。实际上,这三者之间不能相互推导。
原始讨论见 #11216。用户在 0.2.0-rc.2 上报告了两种现象:一是消息的 content 不是数组,二是头部缺少 cwd。报告称,前一种情况是先成功写入、之后读取校验失败;后一种情况则是可以正常列出,但打开历史时返回 session/not-found。
这两种情况要分开看:它们是特定环境下的用户报告,不是适用于所有读取失败的通用诊断,也不能据此断言你当前使用的版本一定有相同问题。
排查时常见的六类误判:
- 把列表能显示当成记录可读;
- 把读取时报错当成记录写入时就有问题;
- 把封套字段齐全当成载荷内容正确;
- 把
session/not-found一概归因于缺少cwd; - 把仓库事件目录里查不到类型当成该事件无效;
- 把讨论中的修改建议当成已确认的修复。
先记住这一点:读取失败只说明当前读取路径没能加载该会话。 站内基础版可参考 会话事件读取失败的诊断顺序。
一、读取失败到底能说明什么
读取失败能明确排除的情况很少,因此很容易被过度解读。当前能确认的只有:这条读取路径没有成功加载该会话。
它本身不能证明具体原因是:
- 文件被截断;
- 选错了会话;
- 事件载荷无效;
- 头部无法解析。
这里要先分清两条路径:列表和打开历史执行的是不同操作。 列表读取索引和元数据,打开历史则需要重放记录。因此,「成功列出不等于能够重放记录」并非泛泛的谨慎说法,而是两条代码路径确实不同。
同样,读取时暴露的问题,不一定出在读取器。 如果生产者写入了结构不正确的载荷,它可能一路保存到磁盘,直到读取器校验时才报错。此时错误虽然出现在读取侧,问题却可能来自生产侧。
二、应该对照哪些字段
持久化目录列出了仓库声明的持久会话事件、公共封套和解析后的类型。
封套(envelope)包含 type、seq、time、data,以及可选的 ignorable;在特定条件下还包含 surfaceOp 和 sourceEventSeqs。排查时,可以先用 type 找到相应声明,再用 seq 定位报错指出的记录,最后检查 data 中的字段。
还有一条容易忽略的边界:排查旧日志时,要查看与安装版本对应的历史格式,不能默认当前目录也适用于旧版本。目录会随版本演进。
一张字段对照表
| 证据 | 对照什么问题 | 局限 |
|---|---|---|
错误与 seq |
副本中哪条记录被指出 | 序号本身不能确定生产者 |
type 与 data |
载荷与嵌套类型是否符合声明 | 目录不覆盖外部插件类型 |
头部与 cwd |
存储元数据是否符合具体报错 | 缺少目录不是 not-found 的唯一原因 |
| 生产者与版本 | 输入是否符合报告中的复现条件 | 症状相同不证明代码路径相同 |
目录还区分两类事件:进入模型历史的 surface event,以及只记日志的事件。这个区别会直接影响处置方式——不要因为某条记录不像聊天消息就删掉它。 审计、状态变更等记录本来就是用于日志的,删除它们就等于删除证据。
最后还有一条边界:目录中的结构指纹覆盖的是已声明的类型结构。它不能证明不透明载荷的内容正确,也检测不到那些没有类型变化的行为变化。
三、怎样检查而不破坏证据
检查顺序很重要。漏掉前一步,后续几步的结果都可能失真。
第一步,固定现状。 保存脱敏后的完整错误、会话标识、seq、版本、profile 和触发操作。同时记下两件容易漏掉的事:其他会话能否正常打开,以及重启前后有何差异。这两条信息能帮助区分「单条记录损坏」和「整条路径异常」。
第二步,先备份,再动手。 按照当前环境的备份流程,保留原始记录副本。报告中的日志位于 ~/.dsh/sessions/<project>/<id>/ 下,文件为多帧 session.v4.jsonl.zstd——这是报告环境中的路径,请先确认你自己的实际存储位置和格式。
第三步,在副本上检查。 使用适合该格式的工具打开副本,查看头部和报错指出的事件,并保留序号、类型及必要上下文。然后依据对应版本的目录和生产者契约,核对嵌套字段。
第四步,分别验证两个假设。 如果 user/message 的 data.content 是字符串,就对照报告中的非数组案例;如果头部没有 cwd,则分别核对「列表」和「历史」两条路径的结果。这两种情况都不是唯一可能原因。
第五步,用可丢弃数据做最小复现。 先确认涉及的导入程序或插件,再在隔离环境中构造最小输入。提供给维护者的材料应是脱敏后的错误和最小结构,不需要真实对话内容。
讨论中描述的复现方式是用字符串调用 createUserMessage,再调用 agent.followup。报告将问题归因于进程内生产者的输入——这段代码用于复现失败,不是生产环境示例。作者提出的「写入前校验」只是建议,并非已确认的修复。
四、两个现象为什么要分开处理
它们看起来都是「读取失败」,但对应的证据链完全不同。
消息载荷案例
运行一轮时出现 content.some is not a function;重启后读取历史时报会话损坏,并指出某个序号的记录内容无效。示例记录的 type 是 user/message,data.content 是字符串。
调查时要看两点:生产者是否提供了预期的 content parts 数组,以及读取器是否正确拒绝了该事件。注意推论的方向:封套字段齐全,并不代表内部载荷正确。 type、seq、time 都存在,外层看起来完全合法,问题可能藏在 data 里面。
头部缺失案例
这个案例来自一个本地导入流程:作者称,这些对话没有项目目录,存入 _no-cwd 后仍然可以列出,但被历史读取路径拒绝。
这个案例提供了一个可操作的推论:你可以从列表拿到会话标识,但列表成功不能证明历史有效。 报告没有证明所有 session/not-found 都是由缺少 cwd 引起的,也没有提供受支持的头部修改方法。
分派规则
- 如果错误指向事件(带序号,并说明内容无效),优先核对该事件的载荷;
- 如果错误表示找不到会话,核对头部、存储位置和查找上下文。
如果两类证据同时存在,就都保留下来。不要为了消除一个症状就立刻修改原始数据——那只会把两个问题中的一个藏起来。把输入结构和版本信息一并交给维护者,才能同时检查写入方和读取方。
五、怎样记录一份能复核的证据
给维护者提供材料时,第一件事是把事实和假设分开。
「列表中有该标识,打开时报某个序号的内容无效」——这是观察到的情况。
「某插件写入了无效消息」——这是一个假设,还需要结合生产者输入和版本进一步确认。
这两句话经常被写成一个句子,结果整条线索就断了。
第二件事是说清副本覆盖了什么范围。仓库目录只覆盖仓库声明的事件;外部插件的事件要查对应插件自己的契约。不能因为目录里找不到某种类型,就断定事件无效。历史格式、升级过程和当前版本也会影响比较结果,因此要同时保留版本信息和原始副本。
第三件事是不要在重要会话里复现。不要在正在使用的会话里再次写入已知的异常输入。先在独立测试环境验证生产者修改,再确认新数据能保存并重新读取。这个测试验证的是「所选输入 + 该版本」下的结果,不会自动修复已有记录。对于旧记录,应等维护者确认受支持的恢复方法,并分别核对恢复前后的内容与完整性。
六、限制与安全边界
会话记录里可能包含提示词、工具结果、私有路径和凭据。请限制副本的访问范围,并在分享前删除敏感值;脱敏时也要保留排查所需的结构事实——例如某个字段是字符串还是数组。这类信息不属于敏感内容,却会决定诊断方向。
来源没有提供通用修复命令、手工编辑压缩日志的安全方法,或 UI 层的恢复流程。基于这一点,有三条硬性禁令:
- 不要根据单个报告删除事件;
- 不要猜一个
cwd塞进去; - 不要覆盖唯一副本。
以上任何一种操作都可能直接造成历史丢失,也会一并抹去证据。请向部署维护者确认安装版本支持的恢复方式,并在单独副本上验证恢复结果。
最后还要记住:成功列出,或者成功读取一次,都不能证明整份记录完整。 完整性需要逐条验证,不能靠一次抽查得出结论。
七、术语速查
- 封套:包含类型、序号和载荷等公共元数据的事件结构。
- 载荷:事件特有的数据,其嵌套结构需要符合相应契约。
- 头部:持久化和历史查找使用的会话元数据。
- Surface event:参与构造模型历史的持久事件。
- 生产者:持久化之前提供事件或消息的组件。
相关阅读
本文依据 DeepSeek Harness 持久化目录参考与社区讨论 #11216 整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
原文地址:https://dsh-plugin.com/zh/blog/session-event-read-failure-diagnostics
插件与文档收录于:https://dsh-plugin.com/zh/blog