DeepSeek Harness 会话损坏恢复：日志序号断层、缓存命中率骤降与增量损坏修复

DeepSeek Harness 会话损坏的三个典型信号：日志报 seq gap 序号断层（会话日志被外部工具改坏）、KV 缓存命中率骤降（缓存与日志失配）、History 报 Failed to fetch (internal)（增量损坏）。 按「定位日志文件 → 修复或重建会话 → 清缓存重建 → 恢复验证」处理。

DeepSeek Harness 会话损坏的三个现象

三个现象互不相同：序号断层是文件完整性错误、缓存骤降是性能信号、internal fetch 失败是前端拉取错误。 逐一说明（来源）：

1. 日志序号断层——启动或恢复会话时报 corrupt session log: seq gap in committed region，会话打不开或只恢复部分内容；
2. KV 缓存命中率骤降——监控或日志显示缓存命中率明显下降，会话恢复明显变慢，反复读盘；
3. History 报 Failed to fetch (internal)——会话恢复后点击 History 拉取历史失败，或会话列表加载异常；
4. 三者都可能同时出现（缓存与日志同一来源），但对症处理顺序一致：先查日志完整性。

DeepSeek Harness 会话损坏根因：日志被外部工具改坏 + 缓存失配 + 增量损坏

三条根因：日志文件被外部工具改写（seq gap）、缓存与日志失配（命中率骤降）、增量数据损坏（internal fetch 失败）。 展开说：

1. 外部工具改坏日志——会话日志是 JSONL 追加文件，文本编辑器、同步盘、脚本都可能破坏追加序号，已提交区段出现断层即报 seq gap（来源）；
2. 缓存与日志失配——日志被改动后 KV 缓存键失效，缓存命中率骤降，恢复时大量回源；
3. 增量损坏——会话恢复按日志重放增量数据，增量畸形时前端 History 拉取报 Failed to fetch (internal)（来源）；
4. 存储格式由 packages/session/session-persistence-jsonl 定义（来源），追加以序号校验完整性。

解决 DeepSeek Harness 会话损坏：定位日志 → 修复或重建会话 → 清缓存 → 验证

按顺序执行：先备份定位，再修复或重建会话，然后清缓存重建，最后验证恢复。 逐步操作：

1. 定位并备份会话日志文件——按 profile 数据目录进入会话存储路径（session-persistence-jsonl 定义的 JSONL 追加文件）：
   bash

   # macOS/Linux 示例：先看 profile 目录
   ls -la ~/.dsh/profiles/<profile>/sessions
   

   找到目标会话的 .jsonl 文件后，复制一份备份。
2. 修复或重建会话：
   • 轻量修复：重启 dsh web，宿主会按日志重放并尝试修复断层；
   • 修复失败：把备份移走，让该会话重新从空白创建（历史丢失但会话可用）；
   • 保留证据：备份文件保留，便于反馈官方。
3. 清缓存重建——缓存失配导致命中率骤降时，清理会话缓存：
   bash

   # 找到并移除会话缓存目录（路径因版本而异，以 dsh 提示为准）
   rm -rf ~/.dsh/profiles/<profile>/cache/<会话ID>
   

   重启 dsh web，让缓存按当前日志重建。
4. 恢复验证——重新打开会话：
   • 不再报 seq gap，历史能完整恢复 → 收工；
   • 仍报 Failed to fetch (internal) → 导出当前会话数据备份，开新会话，并把备份反馈（来源）。
5. 预防——不要用外部工具直接编辑 JSONL 会话日志；会话备份用 dsh 提供的导出功能，不要手工复制编辑。

DeepSeek Harness 会话修复后怎么验证？日志完整性、缓存重建与会话可用性三查

修复后三查确认：日志序号连续、缓存重建完成、History 与导出都正常——三查全过才算恢复。 按顺序执行：

1. 核对会话日志行数与序号——在 profile 会话目录检查：

   bash

   wc -l ~/.dsh/profiles/<profile>/sessions/*.jsonl
   

   目标会话文件行数与消息量对得上、启动日志不再报 seq gap，即文件完整性恢复。

2. 重启宿主看恢复日志：

   bash

   dsh web
   

   启动与恢复过程不再出现 corrupt session log: seq gap，会话按日志自动重放完成，即第一关过。

3. 验证缓存重建——清理后首次恢复会回源读盘，随后缓存命中率回升、恢复变快；监控或日志里不再持续高回源。

4. 验证 History 与整会话——点击 History 能完整加载历史、不再 Failed to fetch (internal)；打开会话翻到之前的消息，内容齐全。

5. 验证导出备份可用——用官方导出功能导出一份备份，能正常打开核对关键内容；有备份兜底，后续再出问题也能从这份恢复。

注意事项：DeepSeek Harness 会话损坏先备份再修复

1. 先用 dsh 导出/备份再动手，日志文件一旦改坏无法自动找回历史。
2. seq gap 修不好就重建会话，别反复重启硬试。
3. 缓存命中率骤降先清缓存，不用动日志。
4. 会话历史恢复用官方导出能力，外部工具只读不写。
5. 其他安装报错可参考安装报错排查。

来源：dshbase 常见问题排错、DeepSeek Harness packages/session/session-persistence-jsonl、DeepSeek Harness packages/session