DeepSeek adapter translates empty/null SSE tool-call ids into empty block.callId, breaking session history load and downstream tool_call_id validation

[fuxuejun]

DSH DeepSeek adapter 统一修复诊断(2026-08-17)

两份历史补丁说明,并新增 P3/P4/P5/P6 根治性补丁与故障分析。历史文档保留作回溯参考。

---

1. 故障现象(两类,同根)

运行 deepseek-official / deepseek-v4-flash|pro 时,DeepSeek API 偶发在并行 ≥2 个
tool call 的流式 delta 里发空 id / name(违反 OpenAI"id/name 只在首个 delta 出现"的约定),
甚至整次调用全程不带 id。由此产生两类故障:

现象	触发点	报错
① 本轮工具全废,对话推不动	流式累积被空串覆盖 / 无 id	unknown tool "" → UNKNOWN_TOOL;agent-loop 整步拒掉重试
② 继续对话被上游拒绝	会话内出现空 tool_call_id	Duplicate value for 'tool_call_id' of in message[N] → INVALID_REQUEST(上一轮内存里是旧 adapter;新写入仍空 id)
③ 重启后历史无法加载	存档里保存了空 callId 的 tool/result 事件	session event at seq N message must have tool source (internal)(dsh-session 回放校验拒绝)

时间线(本地时间,2026-08-16 → 08-17)

• 22:41–23:07 session-d3a71f45 / fcb10cee 等补丁前会话已出现空 callId 存档
• 23:26 / 23:33 应用原 P1(reasoning_content)、P2(空串守卫)
• 23:47–00:17 验证补丁期间六个会话(2f256497/83e6c5d0/b8c7279b/3c7d3156/13569dbc/79177163)
  写入空 callId → 00:17 / 00:23 重启后 无法加载(dsh-session 校验)
• dsh web(00:23 启动)对部分会话做了清理重写(六会话一度 0 坏),但 live 会话
  2f256497 / 83e6c5d0 / 6d14b4b3 / e7935da8 / b8c7279b 被旧代码持续追加空 callId,
  修复反复被覆盖

结论:补丁 P1/P2 不是故障根源,也没有解决它 —— 它们只防"空串覆盖已设的 id",
防不了"API 全程不给 id"。坏数据在补丁前就已产生。

---

2. 根因链(两处,都在 bundle,源码 deepseek-harness 未动)

DeepSeek SSE delta 无 id / 空 id
  └─> adapter translate() 累积 block.callId 为空
        ├─ closeBlock: id = CallId(block.callId ?? "")      → block-end id ""
        └─ tool-call-delta: id = CallId(block.callId ?? "") → delta id ""
  └─> dsh-llm BlockAssembler
        ├─ partial.toolCallId = chunk.id(无条件赋值,空串也覆盖)   ← P4a 修
        └─ assemble 兜底: partial.toolCallId ?? CallId(`call-${index}`)
             ?? 只对 undefined/null 生效,空串 "" 不触发 ← P4b 修
  └─> 最终 assistant 块 id="",工具以空 toolCallId 执行
        ├─ 存盘: tool/result.source.callId="" → 重启校验拒绝(故障③)
        └─ 继续对话: 序列化 tool_call_id="" 重复 → 上游拒绝(故障②)

关键细节:

• block-end 的 block 是权威值(assemble() 优先返回它),所以光改 dsh-llm 的 ?? 兜底救不了
  DeepSeek —— 必须在 adapter 的 closeBlock 之前保证 callId 非空。
• dsh-llm 是 bundle 形态:runtime 用 lib/index.js(内联 BlockAssembler, L673+),lib/types/assembler.js
  是同源码的独立文件,两处都要打。

2.1 扩展根因:dsh-llm-pi-ai(opencode-go / pi-ai 路径)

settings.yaml 的 llm-pi-ai.providers.opencode-go 走 https://opencode.ai/zen/go/v1 反代,
该反代同时提供 deepseek-v4-flash / pro 等模型。用户在 GUI 模型选择器里切到这类 deepseek
走的不是 dsh-llm-deepseek(直连 DeepSeek API,需要 llm-deepseek.providers.deepseek.apiKeyEnv,
settings 里没配),而是 dsh-llm-pi-ai,它内部用 @earendil-works/pi-ai 通用库。

dsh-llm-pi-ai 的 toStreamChunks 用的是带 block-end 的 chunk 协议:

• L511 toolcall_start → yield block-start
• L526 toolcall_delta → yield tool-call-delta(携带 id: CallId(known?.id ?? ""))
• L537 toolcall_end → yield block-end(携带 block: { id: CallId(event.toolCall.id), ... })

P4 的 BlockAssembler.assemble()(L739)只在 partial.block 未设时走兜底:

assemble(partial, index) {
    if (partial.block) return partial.block;  // ← partial.block 一旦被 block-end 填了空 id,直接返回,绕开兜底
    switch (partial.blockType) { ... }
}

而 push() L713 partial.block = chunk.block; 会把 toolcall_end 携带的空 id block
直接覆盖 partial.block。P4 兜底对 dsh-llm-pi-ai 这条路径完全失效。

P5 修复:在源头合成 id(toStreamChunks 入口生成 per-stream callSalt,
toolcall_start/delta/end 三处空 id 都兜底合成 call-<index>-<callSalt>),
从源头让 block.id 永不为空,partial.block 永远是非空 brand,assemble() 返回它。

2.2 扩展根因:dsh-llm-deepseek 的 P3 null 漏洞(OpenCode 反代路径)

settings.yaml 里 llm-deepseek.baseURL = https://opencode.ai/zen/go/v1(孤儿配置,
没 llm-deepseek.providers 块),用户切到 deepseek 时 dsh-llm-deepseek 通过 OpenCode 反代
拿模型,API key 走环境变量(DEEPSEEK_API_KEY,settings 未显式配,反代侧校验)。

OpenCode 反代的 SSE delta 里 tool_calls[].id 可能是 null(而非 undefined 或空字符串)。
P3 的条件 call.id === void 0 || call.id === "" 对 null 全部不成立:

• null === void 0 → false
• null === "" → false
• 第一个 if 不满足 → 进入 else if (call.id !== void 0 && call.id !== ""):
  • null !== void 0 → true
  • null !== "" → true
  • 设置 block.callId = null!

然后 closeBlock L213 id: CallId(block.callId ?? ""):?? 对 null 返回 "" → block id = ""!

P6 修复:把 === void 0 改成 == null(同时匹配 undefined 和 null),!== void 0 改成 != null。
P6 已在 E:\caches\bun\global\node_modules\@deepseek-ai\dsh-llm-deepseek\lib\index.js L321 落盘,
4 case 验证(id: null / 无 id 字段 / 真 id 保留 / null 后真 id 切换)全部产出非空 brand。

---

3. 统一补丁(P1-P6,一个脚本全打)

脚本:patch-dsh-llm-unified.ps1(幂等,自动跳过已应用项)

#	包	位置	改动	作用
P1	dsh-llm-deepseek	serializeAssistant L58	tool-call 轮恒发 reasoning_content	消除 INVALID_REQUEST(无 reasoning 块)
P2	dsh-llm-deepseek	translate delta 累积	空串 id 不覆盖已设值;name 真值守卫(空串/null 均不覆盖,2026-08-17 升级)	消除 unknown tool "" / id 被空串清掉
P3	dsh-llm-deepseek	translate 开块处 + 流盐	当 delta 无 id/空 id 时合成唯一 id call-<index>-<盐>,盐每流随机(callSalt)	根治故障②③(直连 DeepSeek 路径):块 id 永不为空且跨轮不冲突(但漏 null case,P6 修)
P4	dsh-llm	assembler(bundle + types)	if (chunk.id) 才赋值;兜底改 || 且带随机盐	保护所有 provider + 回放路径(delta 累积协议)
P5	dsh-llm-pi-ai	toStreamChunks(block-end 协议)	入口生成 callSalt;toolcall_start/delta/end 三处空 id 都兜底合成 call-<index>-<盐>	修复 P4 兜底被覆盖漏洞(dsh-llm-pi-ai 是 block-end 协议,partial.block = chunk.block 优先于 assemble 兜底):覆盖 settings 里 llm-pi-ai.providers.opencode-go 走 opencode.ai/zen/go/v1 的 deepseek 模型
P6	dsh-llm-deepseek	translate L321 条件	=== void 0 → == null,!== void 0 → != null	修复 P3 的 null 漏洞:OpenCode 反代(走 llm-deepseek)等 SSE delta 里 tool_calls[].id 为 null 时 P3 漏掉,null 进入 else if 设 block.callId=null,closeBlock 的 ?? "" 把 null 当空,产出空 id

P3 语义(seed 行):

if (block.callId === void 0 && (call.id === void 0 || call.id === ""))
    block.callId = `call-${block.index}-${callSalt}`;       // 合成,盐保证跨流唯一
else if (call.id !== void 0 && call.id !== "") block.callId = call.id;  // 仍优先采用 provider id

• 首个 delta 带合法 id → 用 provider id(行为不变)
• 全程无 id → 合成 call-<index>-<盐>,不依赖每次流从 0 开始的 index(避免两轮都叫 call-0 → duplicate)

---

4. 剩余已知风险(未修,文档备案)

风险	说明	建议
delta 缺 index 字段	若某 delta 缺 index,toolBlocks.get(undefined) 会拆块	DeepSeek 恒发 index,理论上限;上游跟进
多 choice 交错	for (chunk.choices) 同状态块交错	DeepSeek n=1,理论风险
首个 delta name:null 且后续也无 name	adapter 无法发明工具名 → 仍 unknown tool ""	P2/P5 已守住"有效 name 不被空覆盖";全程无 name 属 API 异常,无法兜底
损坏会话在线时被重写	修复必须停 web 后做	已写入脚本守卫(web 存活时直接拒绝修复)
dsh-llm-pi-ai 的 name 字段同样可能为空	pi-ai partial.name 可能为 ""	同上:无法发明工具名,无法兜底

dsh-llm-deepseek-lib-index.js.diff.txt
dsh-llm-lib-index.js.diff.txt

[tianhao8687]

当前 master 仍保留报告中的三条空值路径：DeepSeek adapter 的 CallId(block.callId ?? '')、pi-ai toolcall_end 直接采用 event.toolCall.id，以及通用 BlockAssembler 无条件用 delta 的空 id 覆盖已有值。因此根因判断成立。

修复职责建议再收紧一些：

1. 每个 adapter 在源头规范化身份。为一次响应创建稳定 salt，并按 wire choice/tool index 生成非空且跨响应唯一的 call id；null、undefined、空字符串统一视为缺失，后续出现真实 provider id 时只能按明确规则接管，不能让空值反向覆盖。
2. 通用 assembler 只做防腐，不替 provider 猜身份：忽略空的 delta id/name；权威 block-end 若仍是空 id 或空 name，应以 MALFORMED_RESPONSE 结束，绝不能构造可执行工具块并写入 Session。
3. call-index 这种无 salt 的跨轮兜底不安全，两轮都可能生成相同 id。合成值必须在一次响应内稳定、跨响应唯一，并随原始 chunks 一起记录，保证 replay 得到同一身份。
4. 工具名全程缺失时不能发明名称，应在 dispatch/persistence 之前失败；这和“id 缺失但工具名完整”是两类错误。

P1 的 reasoning_content 回传是另一个协议修复，最好不要与 call-id 迁移绑定成一个不可拆补丁。

历史坏日志需要单独的离线修复器：先停止 Web/Agent 写入并备份，按一次 assistant tool-call 与对应 tool/result 建立映射，同时重写成唯一 id，然后跑 Session replay/invariant 验证再替换原文件。直接热改 node_modules/lib 或在 live Session 上重写，会继续被旧进程追加的数据覆盖。

回归应覆盖直连与 pi-ai 两条 adapter：id 为 null/undefined/空串、空后出现真 id、两个并行调用、连续两轮 index 重复、block-end 空值，以及修复后的日志重启可加载并能继续发下一轮请求。

[weijiafu14]

你这份诊断的根因链路（流式 delta 空 id/name → 累积覆盖 → unknown tool "" / 空 tool_call_id 入会话）我们从另一条路径做了两层可复核的验证，数据放这里作为对照样本。

第一层：故障注入打真累加器（针对"全程无 id"的畸形流本身）。 用 options.fetch 把手造的 SSE 直接喂进未修改的 pi-ai 0.84.1（OpenAI client、SSE 解析、块累加全真，注入的只是线上的输入）：双并行调用全程无 id、纯 index 交错（正是你表里 ① 的形状）、续块带空串 id/name、首块空真身后到——全部正确组装，两个调用各自 arguments 完整。机制上它按 index 优先键控、首个非空 id/name 胜出，所以空串覆盖那条路径在这个累加器里不存在。装置与逐 case 判决：accumulator-experiment.mjs / accumulator-experiment-results.json。

第二层：真机端到端（stock @deepseek-ai/dsh@0.1.1-rc.2 + pi2dsh 0.23.0 路由真 api.deepseek.com）。 一轮两个 bash 工具调用，落盘会话里 callId 为 call_00_… / call_01_…，互不相同、全程非空，两个结果都正确回注，43 条会话记录整体可解析、历史可加载（case parallel-calls，provider-threads-e2e.json）。

边界说明：① 真机那轮模型选择了顺序调用而非同 step 并行（记录里 sameStep: false），"无 id 并行"的wire形状由第一层注入实验覆盖，不是真机撞出来的；② 这条路径是 pi-ai 的累加器，不是 llm-deepseek 的——它是"另一条已量过的路"，不构成对你诊断的官方 adapter 修复，你提的三条空值路径该修还是该修。