前言¶
DeepSeek Harness（DSH）会把对话过程写到本地会话日志里，路径一般为 ~/.dsh/sessions/**/session.jsonl.zstd。Harness 升级、手工压缩或日志格式演进之后，旧版 Harness 可能无法启动，或直接抛出 SessionFormatUnsupportedError，整段会话都打不开。
手工解压、重打包 zstd，或逐行改 JSON，成本高且容易再弄坏文件。下面介绍社区插件 dsh-session-repair（维护者 snow-The，分类：工作流）：只针对会话日志做只读扫描和受控修复，把常见问题拉回 Harness 能识别的形态。
这是什么¶
dsh-session-repair 是 DSH 工作流类插件（npm 包名 @snow-the/dsh-session-repair，当前版本 v0.1.0，MIT 许可证）。它扫描并修复 DSH 会话日志，主要处理两类问题：
- 单帧损坏的 zstd 日志：文件被整段压成单个 zstd frame 时，Harness 启动会报错（
first frame is not exactly one header line）。插件按规范的多帧布局重建：每个 zstd frame 对应一行 JSON。 - 未知事件类型：较新 Harness 写入的事件（例如
llm/failover）会让旧 Harness 拒绝整份日志。插件为这些事件加上"ignorable": true（事件仍保留，Harness 会跳过）。
插件在 package.json 中声明与 DSH 0.2.0-rc.1～0.2.1-rc.2 兼容，并在 0.2.1-rc.2 上验证；engines 要求 dsh 为 >=0.2.1-rc.2 <0.3.0-0，peer 依赖 @deepseek-ai/dsh >=0.2.0-rc.1。
核心功能¶
修复项¶
- 单帧 corrupt logs：重建为「一行 JSON 一个 zstd frame」的 canonical multi-frame 布局。
- Unknown event types：对运行中 Harness 不认识的类型标记为可忽略，避免旧 Harness 因整日志不支持而失败。
提供的工具¶
| 工具名 | 作用 |
|---|---|
session_repair_scan |
只读报告：每个会话日志的 zstd frame 数、行数、header 合法性、解析错误、未知事件类型。 |
session_repair_fix |
修复问题日志（可限定某个 sessionId）。替换前将原文件备份为 <file>.bak-repair-<timestamp>，重建后校验 frames == lines。修复完成后需重启 Harness。 |
依赖与安全¶
- 系统 PATH 上需要 zstd CLI（Debian/Ubuntu 示例：
apt install zstd）。 - 已知事件类型的白名单较保守；若某类型在你当前 Harness 中实际已支持，修复时可传
extraKnownTypes。 - 不会原地覆盖：备份 → 写入临时文件 → 校验 → 原子替换；扫描严格只读。
安装与启用¶
已抓取资料与 SkillHub 目录页、GitHub README 中均未给出固定的 dsh plugin add … 安装命令。请按 DSH 插件安装流程，从社区目录或仓库说明完成安装与启用；安装前请自行查看源码与 MIT 许可证。
插件以当前 dsh 进程权限读写 ~/.dsh/sessions/ 下的文件，安装前应确认来源可信。
典型用法¶
建议按「先扫描、再修复、最后重启」操作：
- 调用
session_repair_scan，查看哪些session.jsonl.zstd存在 frame/行数不一致、header 无效、解析错误或未知事件类型。 - 对需要处理的日志调用
session_repair_fix（可选指定sessionId）。确认目录下已生成.bak-repair-<timestamp>备份。 - 重启 Harness，用目标版本重新加载会话。
具体参数（如 sessionId、extraKnownTypes）以插件在 Harness 中暴露的工具 schema 为准。
适用场景与注意¶
适合谁
- 升级或切换 DSH 版本后，旧会话无法打开或启动即报错。
- 怀疑会话文件被错误地「整文件 zstd 压缩」，或日志里混入了旧 Harness 不识别的事件类型。
注意
- 修复会改写会话文件（虽有备份与校验）；重要会话可在扫描后自行额外复制一份。
extraKnownTypes仅在你确认类型已被当前 Harness 支持时使用，避免误标导致行为异常。- 社区目录 SkillHub 是独立站点，与 DeepSeek / 幻方无官方从属关系；插件星标与更新节奏以 GitHub 为准（目录页显示 v0.1.0）。
结尾¶
dsh-session-repair 把会话日志的两种常见兼容性问题——单帧 zstd 与未知事件类型——收敛到可扫描、可备份、可校验的修复流程，适合在本地排障时快速恢复 Harness 可读性。
- 目录页：https://www.skillhub.cn/plugins/snow-The/dsh-session-repair
- 源码与说明：https://github.com/snow-The/dsh-session-repair
