前言¶
在 DeepSeek Harness（DSH）里做带工具调用的对话时，会话历史会按帧写入本地的 session.v4.jsonl.zstd。上游对消息结构有硬性约定：助手消息里声明了几个工具调用，紧跟着就必须有同样数量、一一对应的工具结果，中间不能夹别的块。DSH 会把一条助手消息切成多段；若顺序变成「工具调用 → 文本 → 工具调用」，切开之后就会出现「某次调用的结果不再是紧接的下一条」，请求会被拒收，且错误会在每一轮重放。
手工改 zstd 帧、搬备份既慢又容易碰坏 seq 连续性。下面介绍社区插件 dsh-session-fix：在 DSH 设置页里扫描会话、选中后一键修复，并在失败时回滚。
这是什么¶
dsh-session-fix（GitHub：CalamitySpiritKite/dsh-session-fix）由维护者 CalamitySpiritKite（作者署名：汐）发布，分类为 admin-security，MIT 许可，当前包版本 0.1.1。
它只做一件事：把 assistant/message 里落在工具调用之后的 text / reasoning 块挪到所有 tool-call 块前面，使结构符合「非调用块在前、调用块在后」，从而消除 tool_use ids were found without tool_result blocks immediately after 一类错误。不删记录、不改记录类型、不改动 user / assistant 聊天正文字节。
典型报错与真因¶
适合用它的情况包括：每轮对话都失败，报错类似：
messages.3.1: `tool_use` ids were found without `tool_result` blocks
immediately after: call_xxxxxxxx (INVALID_REQUEST)
或会话打不开、历史加载失败，但会话文件仍在磁盘上。
若问题是凭据失效、网络超时、版本不兼容、配置读不进去，应另查原因，不要指望本插件。
核心功能¶
设置页一键流程¶
安装并重启 DSH 后，在 设置 → 会话修复 中：扫描本地会话、勾选需要处理的条目、执行修复。插件跑在 DSH 进程内，不需要退出 DSH；需先切换到别的会话，不要修复当前正在打开、仍在追加写入的那条（列表中会标为「被占用」）。
修改范围与校验¶
- 会话日志是一串 zstd 帧；仅重压改过的帧（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 份，刚写入的那份不删）。
能修与不能修¶
| 情况 | 说明 |
|---|---|
| 能修 | 上述「工具调用之间夹了文本/reasoning」导致的 pairing 错误 |
| 不修 | 文件整段丢失、seq 断档、调用与结果数量对不上、帧无法解压、报错不属于结构类 |
| 不碰 | 当前打开中的会话、其它会话目录、记忆与附件、非本会话的备份前缀 |
安装与启用¶
本插件为标准 DSH 插件包（dsh.bundle.patch + dsh.client）。在 profile 目录（默认 %USERPROFILE%\.dsh\profiles\<profile>）执行，使用 pnpm，不要用 npm（profile 为 pnpm 工作区）。安装前需本机有 git。
从 GitHub 安装（README 推荐）：
# 在 profile 目录里（默认 %USERPROFILE%\.dsh\profiles\<profile>）
pnpm add github:CalamitySpiritKite/dsh-session-fix
装完后确认 cordis.patch.yml 含：
- id: dsh-session-fix
name: dsh-session-fix
然后重启 DSH，左侧设置会出现「会话修复」。
卸载：pnpm remove dsh-session-fix，并删除 cordis.patch.yml 中对应条目，再重启。
本地改代码可用 pnpm add link:<clone 目录绝对路径>（README 中的本地链接方式）；社区目录页与 GitHub 仓库为独立信息源，安装命令以 README 为准。
适用版本与环境¶
- 会话格式 v4（
session.v4.jsonl.zstd） - Node ≥ 22.15（需内置 zstd 支持；桌面版自带运行时一般满足）
- README 写明在 DSH 0.2.1-rc 系列上实测
典型用法与自测（可选）¶
日常用法：切换离开待修会话 → 打开 设置 → 会话修复 → 扫描 → 选中 → 修复 → 回到该会话继续对话。
仓库提供只读/临时目录写入的自测脚本（路径按本机会话目录替换）：
node tools/selftest.mjs "%USERPROFILE%\.dsh\sessions\<某个>\session.v4.jsonl.zstd"
node tools/e2e.mjs "%USERPROFILE%\.dsh\sessions\<某个>\session.v4.jsonl.zstd"
适用场景与注意¶
适合：已在 DSH 中遇到 tool_use / tool_result 结构错误、且 session.v4.jsonl.zstd 仍在的开发者或运维。
务必知晓：
- 插件以当前 DSH 进程权限读写会话目录；安装前应阅读源码与 MIT 许可证，确认可接受其备份与原子替换行为。
- 会话记录是唯一真源，无回收站；勿在运行中删除会话目录，删除前先复制备份。
- DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-session-fix 针对 v4 会话里「助手块顺序写坏」这一具体故障，用设置页扫描、备份、修复与自检闭环，避免手工编辑 zstd。更多信息见 目录页 与 GitHub 仓库。
