DSH 历史会话不可见排查与恢复

DeepSeek Harness v0.2.1-rc.2：会话不可见排查与恢复

作者
DeepSeekAgent.io 编辑部
发布
更新

升级 DeepSeek Harness v0.2.1-rc.2 后，如果侧边栏里的历史会话突然消失，先不要把“列表为空”理解成“会话已经被删除”。DSH 展示会话前，需要读取持久化文件、解析 Session Header，并把会话重新归入 Workspace；任何一层拒绝某条记录，都可能让磁盘上的会话与界面里的列表不一致。

2026 年 10 月 20 日的社区排查把这一现象定位到多条不同路径。最初报告指出，带有退役字段 sandboxMode 或 approvalPolicy 的 Session Header 会触发异常，而列表读取只容忍部分错误类型。后续源码与版本历史核查又修正了一个重要判断：公开发布版并没有写入这两个字段，真正携带它们的文件更可能来自短暂的开发版或 Nightly。对大量普通升级用户来说，Workspace 归属、重复 Session ID 和路径匹配同样需要检查，不能把所有案例都归到一个“坏字段”。

会话列表是怎样生成的

DSH 的会话不是只靠一个目录名显示。列表至少涉及三层状态：

  1. 持久化文件：Session 的 JSONL 或压缩记录是否仍在磁盘；
  2. Session Header：版本、ID、工作目录与其他头部字段能否通过当前读取器校验；
  3. Workspace Registry：读取出的会话能否归入当前注册的工作区并保持正确顺序。

因此，“文件还在但界面不显示”是完全可能的。相反，如果会话目录本身已经不存在，这就不是索引或列表过滤问题，需要按备份、迁移或磁盘恢复处理。

先根据现象缩小范围

现象优先检查
所有工作区都没有历史会话Header 读取异常、重复 Session ID、列表级异常
只有一个工作区为空Workspace Registry、路径归属、大小写与链接解析
会话能看到但无法打开stat() 与实际读取是否接受同一代 Session Header
Session 文件也不存在备份、迁移路径、磁盘或清理操作，不属于列表故障

这张表的意义是先区分数据是否存在，再讨论列表为什么没有接受它。不要一看到空列表就批量移动、改名或删除 .dsh 下的目录，那会把一个可诊断的索引问题变成真实的数据问题。

退役 Header 字段为什么会影响整张列表

社区报告在 v0.2.1-rc.2 的发布产物中定位到 assertNoRetiredHeaderFields：Header 含有 sandboxMode 或 approvalPolicy 时会抛出普通 Error。相邻的列表读取逻辑只把特定的“格式不支持”和“持久化损坏”错误当作单条记录失败处理。

结果是，一条不被当前读取器接受的 Header 可能阻断更高层列表，而不是只把自己标成不可用。更麻烦的是，list() 与 stat() 都会读取 Header；只让列表跳过异常而不统一打开路径，可能把“全部看不到”变成“看得到但打不开”。真正稳健的修复应把“这一代 Header 被拒绝”建模为可呈现的结果，让列表、详情和恢复入口使用同一判断。

但这个触发器并不等于所有 rc.2 升级事故的根因。后续提交历史核查显示，公开版本没有写入这两个退役字段；如果用户从正式版或公开候选版升级，仍应检查 Workspace 与重复 ID 等其他路径。

Workspace 路径也不能简单归因

Workspace Registry 会影响 Session 的项目归属，但“原目录不存在”也不能一概解释为会话被过滤。rc.2 已包含对部分缺失路径的保留逻辑：已归属会话在记录的绝对路径暂时不存在时，可以继续保留所有权。

真正需要核对的是：

  • Registry 里记录的是不是当前工作区；
  • Session Header 的 cwd 与注册路径是否指向同一个规范化位置；
  • Windows 盘符、路径大小写、符号链接或 Junction 是否改变了匹配结果；
  • 同一个 Session ID 是否出现在多个存储桶；
  • 路径是“缺失但可容忍”，还是“存在但实际指向另一个目录”。

这也是为什么恢复文章不能只给出“把目录建回来”或“删除某个字段”这一条命令。不同触发链需要不同处理。

安全的排查顺序

  1. 完整复制 DSH 数据目录，保留时间戳和目录结构；不要直接在唯一副本上试修复。
  2. 记录版本、发布通道、系统与升级前版本。Nightly、开发构建与公开 Release 的历史写入行为可能不同。
  3. 确认 Session 文件是否存在，并统计受影响的是全部工作区还是单个工作区。
  4. 只读检查 Header 与重复 ID。先输出诊断结果，再决定是否隔离某条记录。
  5. 核对 Workspace Registry 与真实路径，特别关注 Windows 大小写、盘符和链接目标。
  6. 在副本上验证最小修复。一次只处理一种异常，重启后同时检查列表、打开、继续与压缩。
  7. 保留修复前后的差异，以便上游判断是读取器、Registry 还是迁移逻辑的问题。

如果需要临时隔离一条可疑 Session，应移动到单独备份目录，而不是删除。若必须修改 Header，也应在副本上进行，并确认 JSONL 首行结构、压缩格式与多代文件关系；直接对压缩文件做文本替换可能破坏整个 Session。

产品层应该怎样修复

一个可靠的会话系统不应让单条异常记录把整张列表变空。更合理的行为包括：

  • 单条读取失败时继续加载其他会话；
  • 在界面显示“有 1 条会话需要恢复”，而不是静默消失；
  • 让 list()、stat()、打开与恢复共享同一错误分类；
  • 区分 Header 不兼容、重复 ID、Registry 不匹配和文件损坏；
  • 提供只读诊断与可回滚修复，不要求用户手工猜目录。

这类故障也印证了 HarnessTester 对 Agent Harness 测试空白的研究：测试不能只覆盖正常 Session，还要覆盖单条坏记录、旧版 Header、重复 ID、路径变化和部分迁移失败时的降级行为。

参考资料

常见问题

历史会话不显示，是否代表内容已经丢失？

不一定。先确认 Session 文件是否仍在磁盘。列表为空可能来自 Header 读取、重复 ID 或 Workspace 归属，而不是文件删除。

可以直接删除出问题的 Session 目录吗？

不建议。先完整备份并采用隔离方式验证。删除会把可恢复的索引问题变成不可逆的数据损失。

这是 v0.2.1-rc.2 已确认的单一 Bug 吗？

不是单一原因。官方仓库讨论已经确认若干真实触发路径，也修正了最初对版本历史和缺失目录行为的部分判断。排查时应以实际文件、Header 和 Registry 状态为准。