po-et/dsh-session-snapshot

为每个 DeepSeek Harness 会话滚动保留校验过的备份——任何损坏最多只损失当前这一回合。

English

会话完整性三件套之一：

阶段	插件	职责
预防	dsh-session-guard	阻止两个 dsh 进程写坏同一会话
快照	dsh-session-snapshot（本项目）	在每个回合边界留一份校验过的好副本
修复	dsh-session-rescue	修复或抢救已经损坏的日志

为什么需要它

dsh-session-guard 能挡住常见的并发写损坏，但有两类损坏是任何插件都拦不住的：写入过程中崩溃，以及 dsh 自身在任何 agent step 之前运行的冷加载修复路径。本插件从另一侧堵住这个残留缺口：每个回合结束后，校验当前日志是否仍可加载，是则提升为一份快照；若回合结束时日志已损坏，则绝不覆盖上一份好快照，并提示如何恢复——最多只损失进行中的那一回合。

安装

暂未发布到 npm，请直接从 GitHub 安装。pnpm 会要求你放行一次这个包的构建脚本（dsh 会打印要加的那一行），那是 prepare 在编译 TypeScript。

dsh plugin --profile web add github:po-et/dsh-session-snapshot

装完即自动在回合边界打快照。在用 AI agent？直接说："装上 dsh-session-snapshot 插件。"

恢复损坏的会话

CLI 在 dsh 自身启动不了时照样能用：

npx github:po-et/dsh-session-snapshot                 # 列出所有会话的快照与实时健康状态
npx github:po-et/dsh-session-snapshot list 37374e34   # 查看单个会话的快照（id 片段）
npx github:po-et/dsh-session-snapshot restore 37374e34   # 恢复最新的、校验通过的快照
npx github:po-et/dsh-session-snapshot snapshot 37374e34  # 立即打一份快照

restore 总是先把当前文件保留为 <文件>.pre-restore-<时间>，并拒绝任何自身校验不通过的快照。用 --at <epoch>（在 list 中显示）可恢复指定快照而非最新的。

配置

- id: session-snapshot
  name: dsh-session-snapshot
  config:
    keep: 5            # 每个会话保留的快照数，超出时淘汰最旧的
    minIntervalMs: 0   # 同一会话两次快照的最小间隔毫秒（0 = 每个有变化的回合都打）
    # home: /custom    # 默认 $DSH_HOME（~/.dsh）

快照存放在 $DSH_HOME/session-snapshots/<会话id>/，且只在日志增长且仍校验通过时才打——未变化或已损坏的会话既不浪费 I/O 也不会覆盖好副本。

成本与诚实边界

• 每次快照 = 一次文件复制 + 一次日志校验扫描。回合间隔是秒到分钟级，实际很轻量；超大会话可调高 minIntervalMs 进一步限流。
• 快照是仅会话日志的时间点副本，不包含工作区文件。要对话+文件一起回退是另一类工具。
• 支持会话格式 version 0（当前 dsh developer preview），.jsonl 与 .jsonl.zstd，JSONL 后端。压缩按内容嗅探，重命名/备份副本也能正确校验。dsh 处于 pre-1.0、无格式兼容承诺；遇到未知版本明确拒绝而非乱猜。

零运行时依赖（zstd 用 Node 内置 zlib）。MIT。