dsh-session-fix · 会话修复
修 DSH 里坏掉的会话记录。装好之后在 设置 → 会话修复 里一键扫描、选中、修复，不用退 DSH、不用手工搬文件。
作者：汐（记忆修复师）· 许可：MIT
一、什么时候用它
会话报这种错、从此每轮都失败的时候：
messages.3.1: `tool_use` ids were found without `tool_result` blocks
immediately after: call_xxxxxxxx (INVALID_REQUEST)
或者会话打不开、历史加载失败，但文件还在。
如果你的报告是「凭据失效 / 网络超时 / 版本不兼容 / 配置读不进去」，那不是它，别在这上面花时间。
二、真因
模型的工具调用有一条死规矩：
一条助手消息里声明了几个工具调用，紧随其后就必须有同样数量的工具结果，一一对应，中间不许夹别的东西。
而 DSH 会把助手消息切成若干段。如果一条助手消息里的块顺序是：
tool-call + text + tool-call ← 坏
切开之后，文本块夹在了两个调用之间，那条调用的结果就不再是「紧接的下一条」。上游直接拒收。
正确顺序是把非调用块放前面：
text + reasoning + tool-call + tool-call ← 好
这个坏结构一旦进了历史，每一轮都会重放它，所以这条会话此后每轮都失败。
三、它到底改什么
只做一件事：
把 assistant/message 里的 text / reasoning 块，挪到所有 tool-call 块前面。
三条不碰：
| 不碰 | 为什么 |
|---|
| 不删任何一行 | DSH 校验 seq 连续，删一条整份判损坏 |
| 不改记录类型、不从旧备份「恢复」记录 | 记录类型是契约的一部分，乱改会把结构弄成另一种坏 |
| 不动聊天正文 | user / assistant 的文字一个字节都不改 |
技术细节：
- 会话日志是一串 zstd 帧，DSH 逐帧校验。只重压改过的帧（带 checksum，与 DSH 自身写法一致），没改的帧原样复制 —— 所以帧数和边界不变，这是它还能被读回来的前提。
- 改完立刻从磁盘重读一遍自查：记录数是否没变、
seq 是否连续、残留病灶是否 0、调用与结果是否配对完整。任何一项不过就当场回滚。
四、回退
修之前，原文件被改名保留在同目录：
session.v4.jsonl.zstd.before-fix-2026-10-31_20-15-33
想退回去，把它的 .before-fix-<时间戳> 去掉、覆盖回 session.v4.jsonl.zstd 就行。
备份会自己收敛：同一个会话默认只留最近 3 份，更早的自动清掉（可以在插件配置里用 keepBackups 改，最少留 1 份——刚写的那份永远不删）。
清理只认「本会话文件名 + .before-fix-」这一个前缀、只在同一个目录里动手，别的会话的备份和同目录的其它文件一个都不碰。清理失败也不影响修复结果——它只是省磁盘，不该能把活干砸。
五、能修什么 / 修不了什么
这一节是故意写清楚的 —— 免得你装了之后发现「我那个报错它居然不管」。
先说一句最容易被误会的话：用这个插件不需要退出 DSH。
它本来就跑在 DSH 里面；真退了，插件跟着下线，设置页那个按钮也就没了。
你唯一要做的只是切到别的会话，别动正在说话的那一条。
✅ 能修
报 tool_use ids found without tool_result blocks immediately after 的会话，也就是上面第二节说的那一种坏法。
❌ 修不了（别指望它救命）
| 情况 | 为什么 | 怎么办 |
|---|
| 会话文件被整个删掉（目录/文件没了） | 没有数据可修 | 先用文件恢复工具（Recuva / Disk Drill / testdisk 之类）把文件捞回来，再交给本插件 |
seq 已经断档 | 结构性损坏，修了也是坏的 | 插件只报不修，把文件发给作者 |
| 调用与结果配对不上（悬空调用 / 孤立结果） | 同上，缺的那条补不回来 | 同上 |
| 帧解不开（文件被截断） | 文件本身坏了，不是结构问题 | 先备份，再用恢复工具试；本插件不动它 |
| 报错根本不是这一类 | 病因不在会话结构 | 看具体报错排查，别归因到这里 |
⏸ 唯一不能碰的会话
正被打开着的那条。
本插件跑在 DSH 里面，所以不用退出 DSH —— 退出了它自己也死了，那就什么都修不了。
但「正在说话的那条会话」文件还在被宿主追加写入，动它就是拿历史换事故。所以列表里会把它标成 「被占用」，并且不给修复按钮。
要修它，先切到别的会话，再回来。
六、适用版本
- 会话格式 v4（
session.v4.jsonl.zstd）
- 需要 Node 内置 zstd 支持：Node ≥ 22.15（桌面版自带的运行时满足）
- 在 DSH 0.2.1-rc 系列上实测
七、安装
本插件是标准的 DSH 插件包（dsh.bundle.patch + dsh.client）。
A. 从 GitHub 装（推荐）
# 在 profile 目录里（默认 %USERPROFILE%\.dsh\profiles\<profile>）
pnpm add github:CalamitySpiritKite/dsh-session-fix
B. 本地链接（改代码 / 自己用）
git clone https://github.com/CalamitySpiritKite/dsh-session-fix.git
cd <profile 目录>
pnpm add link:<刚 clone 下来的目录绝对路径>
两种方式装完，确认 cordis.patch.yml 里有这一行（多数情况 dsh.bundle.patch 会自动带上；没有就手加）：
- id: dsh-session-fix
name: dsh-session-fix
然后重启 DSH，设置页左侧会出现「会话修复」。
卸载：pnpm remove dsh-session-fix，并把 cordis.patch.yml 里那两行删掉，重启。
注意用 pnpm，别用 npm。 不是 npm 装不上 —— npm 也能装 git 依赖；是 DSH 的 profile 本身是个 pnpm 工作区，用 npm 装会和它的依赖树打架。装之前还要有 git。
八、自己验一遍（可选）
仓库里带了两个自测脚本，用的是你自己的真实会话文件，全程只读，所有写入都在系统临时目录：
# 内存里造坏 → 修 → 逐项对照（不写盘）
node tools/selftest.mjs "%USERPROFILE%\.dsh\sessions\<某个>\session.v4.jsonl.zstd"
# 完整落盘流程：临时目录里复制一份，造坏 → 原子替换 → 验备份 → 验回退
node tools/e2e.mjs "%USERPROFILE%\.dsh\sessions\<某个>\session.v4.jsonl.zstd"
两个都跑出「全部通过」再装，心里就有底了。
九、它会动你的哪些文件
| 文件 | 动作 |
|---|
session.v4.jsonl.zstd | 修复时原子替换（先改名原件，再放新文件） |
session.v4.jsonl.zstd.before-fix-<时间戳> | 新建，原件备份；同一会话只留最近 3 份，超出自动删 |
同目录 *.tmp-<时间戳> | 只在替换过程中短暂存在，失败会清掉 |
不碰：别的会话、记忆、附件、配置、当前打开的会话，以及不属于本会话的备份文件。
十、给踩到的人一句话
会话记录是唯一真源：没有索引、没有副本、没有回收站。它在，你的历史就在；它没了，那段历史与你再无关系。
这个插件能救的是「写坏了的结构」，救不了「已经不存在的文件」。
所以：别在运行中删会话目录，删之前先复制一份。
