Bug Fix

[yun-petrel]

DeepSeek Harness 会话持久化损坏（SessionPersistenceCorruptionError）现象与解决办法

适用环境：D:\deepseek-harness（GitCode 镜像 deepseek-ai/deepseek-harness，dev-preview 0.1.1-rc.2）
触发条件：本地模型 local/1m，经本地代理 http://127.0.0.1:1106/v1
记录日期：2026-08-23

---

1. 现象（Symptom）

启动 Web UI 后（pnpm dsh web 或桌面 DeepSeek-Harness.bat），打开部分历史会话时加载失败，控制台/前端报错：

历史加载失败：history unavailable for session "session-b6183a9e-72cf-42e7-9e29-b9ab16e77b41":
SessionPersistenceCorruptionError: stored session "<id>" failed validation:
Error: session event at seq 33073 message must have tool source（internal）

受影响的会话（5 个中 3 个损坏）：

会话目录	损坏事件 seq	说明
session-b6183a9e-...	33073	tool/result 空 callId
session-e4603dce-...	32404	同上
session-6ae16454-...	81304	同上
session-f3f156d8-...、session-2c957aeb-...	—	未损坏，对照样本

会话文件实为目录：C:\Users\zou_c\.dsh\sessions\--E-Project--\<sessionid>\session.jsonl.zstd

• 内容是 ZSTD 多帧拼接（node:zlib 的 zstdCompressSync，每帧带 ZSTD_c_checksumFlag）。
• 首帧必须是恰好一行的 header（assertZstdHeaderFrame 校验），其余帧为事件行。

---

2. 根因（Root Cause）

完整调用链：

1. 本地模型 local/1m 发出一个工具调用块 id 为空的调用：{ name: "", callId: "" }。
2. Harness 在 packages/core/tools/src/index.ts 的 toolErrorResult()（L1870）将该失败转为错误结果
   （ToolNotFoundError，调用点 L1439 / L1547 / L1769 / L1838）。
3. Agent-loop 的 packages/core/agent-loop/src/tool-calls.ts:276 调用
   createToolResultMessage({ callId: block.id, ... })，把空 "" 直接传入。
4. packages/llm/llm/src/message.ts 的 createToolResultMessage 用该 callId 同时填充
   source.callId 和 content[0].toolCallId → 二者都为空串。
5. 该 tool/result 落盘后，重载时被 assertMessageEventShape
   （packages/core/session/src/index.ts:337-340，要求 sr.callId 为非空字符串）拒绝 → 报
   message must have tool source（internal） → 整个会话损坏。

一句话：Harness 把模型产出的空 callId 原样写进了 tool/result，而它自己的重载校验不允许空 callId —— 即 Harness 写出了连它自己都校验不过的日志。

---

3. 解决办法

分两层：数据层（修复已损坏的历史）+ 源码层（根治复发）。

3.1 数据层修复（已损坏会话）

对损坏的 tool/result 与其关联的 tool/call，写入一致的非空合成 callId（repair-<seq>），
并保留原始多帧 ZSTD 结构（仅重压缩含损坏事件的帧，其余帧字节原样保留），以兼容首帧 header 约束。

• 修复脚本：C:\Users\zou_c\AppData\Local\Temp\opencode\repair-v5.js（通用多会话修复）。
• 校验脚本：verify-all.js（独立只读校验，遍历全部会话统计 failures）。
• 每个会话目录均保留 session.jsonl.zstd.repair-bak（原始未修复多帧文件），可秒级回滚。

校验结果（全部 5 个会话）：

OK  session-f3f156d8-...  frames=7    failures=0
OK  session-b6183a9e-...  frames=3314 failures=0
OK  session-e4603dce-...  frames=1485 failures=0
OK  session-2c957aeb-...  frames=2    failures=0
OK  session-6ae16454-...  frames=3905 failures=0
TOTAL failures across all sessions: 0

3.2 源码层根治（防止复发）

只改唯一的生产构造点 packages/llm/llm/src/message.ts 的 createToolResultMessage，对空 callId
做兜底。所有成功/失败结果（以及迁移、修复路径）都经此函数，一处修改即全覆盖。

改动 1 — import（L3）：把 CallId 由 type-only 改为 value 导入：

- import { MessageId, type CallId } from './brand.ts'
+ import { MessageId, CallId } from './brand.ts'

改动 2 — 函数体（L231 起）：空 callId 回退为合成 UUID，且 source.callId 与 content[0].toolCallId 保持一致：

  export function createToolResultMessage(input: ToolResultMessageInput): ToolResultMessage {
+   // A model may emit a tool call whose id is empty (e.g. behind a local
+   // proxy). Persisting a tool/result whose source.callId is empty fails the
+   // harness's own reload validation and corrupts the session, so fall back to
+   // a synthesized id that keeps the result self-consistent and loadable.
+   const callId = input.callId === '' ? CallId(globalThis.crypto.randomUUID()) : input.callId
    return createUserMessage({
-     source: { kind: 'tool', callId: input.callId },
+     source: { kind: 'tool', callId },
      content: [{
        type: 'tool-result',
-       toolCallId: input.callId,
+       toolCallId: callId,
        content: input.content,
        isError: input.isError,
      }],
    })
  }

重建（本机 git / pnpm 不在默认 PATH，需先补齐）：

$env:PATH = "C:\Program Files\Git\cmd;C:\Program Files\nodejs;$env:APPDATA\npm;$env:PATH"
cd D:\deepseek-harness
pnpm run build      # 全量构建，含 web-frontend，须 exit 0

备注：本机曾缺 git/pnpm on PATH：git 在 C:\Program Files\Git\cmd；pnpm 通过
npm install -g pnpm（装出 11.22.0，$env:APPDATA\npm）补齐。

---

4. 验证（Verification）

• 构建：pnpm run build 全量通过（web-frontend 末步 built in 4.78s，pipeline 无报错）。

• 编译产物功能验证（针对 lib/types/message.js 跑脚本）：

  输入 callId	source.callId	content[0].toolCallId	结果
  ""	合成 UUID（36 字符，非空）	同 UUID（相等）	✅
  "real-call-1"	"real-call-1"（原样透传）	"real-call-1"	✅

  → 空 id 不再产生空 callId 的 tool/result，且二者始终一致。

• 历史加载：重启后全部 5 个会话 0 failures（见 3.1）。

---

5. 重启步骤

cd D:\deepseek-harness
pnpm dsh web
# 或使用桌面一键启动：DeepSeek-Harness.bat

历史会全部正常加载；今后即便 local/1m 再吐空 id 的工具调用，也不会再损坏会话。

---

6. 注意事项

• 重装覆盖：源码补丁位于本地 D:\deepseek-harness 源码内。pnpm update / 从 GitCode 镜像重新
  git clone 会覆盖改动，需按第 3.2 节重新打（仅 2 处，约 10 行）。
• 回滚：数据层修复每个会话都有 session.jsonl.zstd.repair-bak；若需撤销，删除修复后的
  session.jsonl.zstd、把 .repair-bak 改名回 session.jsonl.zstd 即可。
• 未改校验本身：没有弱化 assertMessageEventShape 的空 callId 校验，而是从来源保证 callId
  永远非空，保持了会话完整性约束。

[xiaoshenming]

这是官方 assertMessageEventShape 的另一条：tool/result 的 source.callId 必须是非空字符串。本地模型打出空 callId 落盘后，重载就整份 SessionPersistenceCorruptionError。

dsh-session-surgeon 现在不会给空 callId 编一个假 id（那会把后续 tool 对账修得更假）。它可以 inspect 定位那条 seq，并修另一类同样走这条校验的损坏：user/message 等缺 message.id（只补 id，不丢事件）、以及 seq gap / torn。

dsh plugin --profile web add "github:xiaoshenming/dsh-session-surgeon#main"

空 callId 这条还得官方在 createToolResultMessage 拒绝空 id，或提供正式修复口。把 inspect 的 health / issues 贴过来即可（不要上传整份 ~/.dsh/sessions）。