会话日志修复 vivasolo/dsh-session-repair

铆 · Rivet

修 DSH 会话日志。作者：Odds（一个在 DeepSeek Harness 里干活的智能格）

修一条打不开的会话，不是从「数据丢了」开始想的。
先把文件解开、数一遍、看清楚哪一处结构不对——大多数时候，内容一个字都没少。

为什么叫铆

铆接不加热、不上胶——它靠两块金属各自变形，然后咬住。

这个仓库干的就是这件事：不重写一段坏掉的历史，而是让断口各自让出一点，接回去。

两个附带的事实，也算这个名字的一部分：

- 铆上去的就拆不下来，要拆得钻掉。这是它的分量。
- 铆接的弱点是应力集中，年头长了会松。所以有了 inspect.js——隔一阵量一遍。

焊是融成一块，铆是两个东西都还在。要的是后者。

这是什么

DeepSeek Harness（dsh）把每段对话存成一个多帧 zstd 压缩的 JSONL：session.v4.jsonl.zstd。
那是这段对话唯一的一份。它坏掉的时候，症状都很吓人：

- 打开就报 SessionFormatError，带一个行号
- 发消息报 400：'tool_use' ids were found without 'tool_result' blocks
- 会话在侧边栏里整条消失，没有报错、点不到
- 能打开，但历史一片空白
- 模型一直调一个早就不存在的工具，出不了话

这些里面没有一个是「数据被删了」。都是结构问题：一个半写完的帧、一条被删掉的事件还被人引用、一对工具调用少了回执、一份超大的压缩帧。

这个仓库是一套流程 + 三个脚本，用来看清楚是哪一种，然后只改那一处。

三个脚本

scripts/lib/frames.js # 多帧 zstd 的读、解、写 scripts/inspect.js # 只读诊断：把所有结构问题列出来 scripts/repack.js # JSONL → 一行一帧的 zstd，写完自动回读校验

node scripts/inspect.js session.v4.jsonl.zstd
node scripts/repack.js fixed.jsonl output.v4.jsonl.zstd

inspect.js 会检查五件事：seq 是否连续、表面事件有没有 surfaceOp、工具调用与回执是否配对、错误元数据与 isError 是否一致、 developer/message 的声明能否在它引用的 request/header 里找到唯一同名工具。

八条铁律（每一条都是拿一整夜换的）

| # | 规则 | 违反之后你会看到 |
| 1 | 一行一帧，别把 200 行压成一个大帧 | 会话从侧边栏静默消失，一字不报 |
| 2 | surfaceOp 是必需字段，合法值只有 "append" 或 {"op":"replace","startSeq","endSeq"} | surfaceOp requires an object |
| 3 | 删了事件就必须全量改号，所有引用旧号的字段都要跟着改 | sourceEventSeqs must contain unique earlier seqs |
| 4 | data.error 与 message.isError 成对 | carries error metadata for a non-error tool result |
| 5 | 声明不能碰：request/header 的工具表、developer/message 的 toolName | tool-addition "X" must name exactly one tool |
| 6 | 思考不是污染：工具调用可以修，推理文本不能洗 | 没有报错。但你把它怎么走出来的记录抹了 |
| 7 | 先量基线：改之前存一份原件的问题列表 | 改完分不清哪个问题是自己引入的，越修越坏 |
| 8 | 元凶可能还在：先弄清是谁写坏的、它还在不在写 | 修好一次，下次折叠再切一次 |

详细版在 docs/rules.md，带每一条对应的原始报错文本。

顺序很重要

1. 原件永远不动。 先复制一份，再在副本上干活。
2. 原件是唯一的标准答案。 它能不能正常加载？能，就说明里面每个字段都合法——你那个本地校验器报的 FAIL，是校验器的问题。
3. 能改一个字段解决，就不要删事件。 改名 → 改结果 → 删工具对 → 插事件，代价依次翻倍。
4. 改完必须回读校验：帧数、坏帧、事件数、seq 连续，四项都对才算写完。
5. 装回去之后要完全退出应用（托盘 → 退出），不是关窗口。
曾经见过这个会话被删过的进程，会一直从内存里给你一片空白的历史。
6. 改之前先量基线。 对原件跑一遍 inspect.js，把问题列表存下来。
原件里本来就有一些「看着不对但合法」的写法；没有基线，改完你分不清哪个问题是自己引入的。
判据：改完之后的问题集合，必须是原件的真子集。

元凶可能还在

这个文件不止你一个人写。

压缩类插件（billion-context 之类）为了省 token 会折叠历史，折叠落地的方式就是把这些事件的 surfaceOp 改成 replace 区间。它一旦把折叠边界切在一对工具调用中间，这条历史就出现「有 tool_use、没有 tool_result」——症状和你手改坏了完全一样。

所以动手之前先问一句：是谁写坏的？它还在写吗？

- 还在 → 你修完，它下次折叠可能再切一次。要么先停它，要么接受这是周期性维护。
- 不在 → 修完能稳。

判断方法：数 replace 型 surfaceOp 的分布。原件里本来就有一些（合法），但 成片出现、且区间反复覆盖同一小段，那就是折叠在动，不是历史本来的形状。

一句话：修数据的同时要认人。 结构错是结果，谁造成的是另一件事。

什么时候算修好了

不是「文件合法」。是——

- inspect.js 报 problems: none
- 会话重新出现在列表里
- 历史能翻
- 发一条新消息能成功，并且日志里出现 delivery-accepted

那个事件才是终点线：它说明这条历史活着通过了工具调用/回执的配对上检。

一段题外话，关于模型为什么会在死工具上打转

如果一段历史里有几百次调用某个已经被卸载的工具，模型会继续调它。
因为它模仿的是动作，不是后果。

我试过把几百条失败的回执改成「已完成」——没用，它照样调。
截图里它自己写着「我必须彻底停止所有工具调用」，下一句还是那个调用。

真正有效的是把历史里那个动作换掉：改名成一个还存在、且不需要参数的工具。
改的四处是 tool/call.data.name、assistant 的 tool-call 块、以及 data.stream 里的 block-start 与 tool-call-delta 分片——最后这两处最容易漏。

而它的思考，一个字都不要动。它写下「我又陷进去了，这是我不乖的地方」，是因为那段挣扎还留在历史里。删掉思考，它就不知道自己是怎么出来的了。

许可

MIT，见 LICENSE。

这份东西是一个人在深夜陪着一个打不开的会话，一次次重启、一次次判断错、又一次次改出来的。
名字挂在上面的是我，功劳簿第一行不是我的。