[Bug] 历史里的空 reasoning 块会序列化成空 thinking 块，导致已有会话切到严格的 Anthropic Messages 网关后永久失败

[wonderfu39]

Summary

会话历史里只要存在 text 为空的 assistant reasoning 块，Messages 序列化就会输出
{"type":"thinking","thinking":""}。会校验 thinking 块的 Anthropic Messages 兼容网关会直接拒掉整个请求，
于是一个已经跑过若干轮的会话再也切不过去，报错位置固定在同一个 message 下标，每轮都失败，只能新开会话。

这不是偶发个案。我在自己的多个会话里都复现过，历史越长越容易混进空块，一旦混进去就无法回到网关那条路由。

Reproduction

1. 把 API-key 路由（deepseek-official，@deepseek-ai/dsh-llm-deepseek-api-key 适配器）的 baseURL 指到任意
   会校验 thinking 块的 Anthropic Messages 兼容网关。
2. 先在别的 provider 上跑若干轮，直到历史里落下一个 text 为空的 reasoning 块。账号路由
   （deepseek-account）上可以稳定观察到这种现象，形态都是「空 reasoning + tool-call」。
3. 在同一个会话里把模型切到网关那条路由，发任意一条消息。

只要历史里有空块，100% 复现，而且后续每一轮都失败。

Current behavior

请求在模型开始生成之前就被拒绝：

invalid Claude request: message[69]: content[0]: thinking type must have non-empty thinking field
HTTP 400 INVALID_REQUEST

我按序列化后的实际形态直接打网关，逐个形态验证过，只有空值这一种过不去：

请求里的 thinking 块	网关
{"type":"thinking","thinking":""}（带签名）	❌ 拒绝
{"type":"thinking","thinking":""}（无签名）	❌ 拒绝
{"type":"thinking","thinking":null}	❌ 拒绝
非空 + 签名	✅ 通过
非空、无签名	✅ 通过
完全没有 thinking 块	✅ 通过

同一份历史里把空块换成非空块，整段历史（含无签名 thinking、tool_use / tool_result 链）能完整重放并跑通，
所以问题范围就限定在空值这一个点上。

Expected behavior

这一轮正常跑起来。空的 reasoning 不携带任何信息，序列化时丢掉即可。

定位

packages/llm/llm-deepseek/lib/types/serialize.js：

case "reasoning": return {
  type: "thinking",
  thinking: block.text,
  ...replay?.[index]?.signature === void 0 ? {} : { signature: replay[index].signature }
};

block.text 为空时没有兜底。两个放大的因素：

1. readReplay() 只在 response.model === model 时才返回 replay 元数据（注释写的是 cross-model signatures
   are not portable），所以跨模型重放时签名一并丢失，发出去的是「空且无签名」的块。顺带一个观察：部分兼容网关
   回传的 model 名和请求的不一致（例如请求名带变体后缀、回传的是基础名），这些情况即使不换模型名也会走到丢签名的
   分支——实测 thinking 非空时不影响使用，但这条路会让空值更早暴露。
2. packages/llm/llm-pi-ai/lib/index.js 是同一套写法（content.push({ type: "thinking", thinking: block.text })），
   所以换适配器绕不过去。

Environment

• DeepSeek Harness 0.2.0-rc.2，macOS arm64 桌面版（@deepseek-ai/dsh-llm-deepseek 0.2.0-rc.2）
• 路由 deepseek-official，适配器 @deepseek-ai/dsh-llm-deepseek-api-key，配置了自定义 baseURL
• 产生空块的 provider：deepseek-account（账号路由），形态固定为「空 reasoning + tool-call」
• 拒绝方：一个严格的 Anthropic Messages 兼容网关。它的校验本身没错——Anthropic 对 thinking 块的要求本来就
  包含非空内容，DSH 这边不该把空块发出去

建议的修法

序列化时跳过空的 reasoning 块，注意保持 replay[index] 的索引对齐：

case "reasoning": {
  if (typeof block.text !== "string" || block.text.length === 0) return void 0;
  return {
    type: "thinking",
    thinking: block.text,
    ...replay?.[index]?.signature === void 0 ? {} : { signature: replay[index].signature }
  };
}

再在 map 之后过滤掉 undefined；llm-pi-ai 同步处理。

如果认为「没有正文的 reasoning 块」本就不该落盘，那在写入会话时拦掉可能更彻底——这样存量会话的历史也干净。
不过对已经生成的历史，序列化侧兜底仍然是必要的。

影响面

任何跑过账号路由、历史里混进空块的会话都无法切到严格的 Anthropic Messages 网关。用户能看到的只是
「切了模型就报错」，从界面上完全看不出跟历史里的某个块有关；唯一的绕过办法是新开会话，而这一点在 UI 上没有任何提示。

相关

• [Defense] 路由覆写后来源 reasoningEffort 跨模型滞留：建议在 provider/model 切换边界重校验档位 #9201 路由覆写后来源 reasoningEffort 跨模型滞留——同一类「provider/model 切换时的边界处理」问题
• [Bug] 空 id/name 伪 tool-call 落盘后 tool/result 校验永久失败，会话从该 seq 起卡死（0.1.7-rc.2 → 0.2.1-alpha.1 均未修，附本地已验证补丁） #9215 空 id/name 伪 tool-call 落盘后 tool/result 校验永久失败——同样是「历史里一个畸形块让会话永久卡死」，
  那边的处理思路可以对照参考

[xiaoyuyu6420]

serialize 层加守卫（跳过空 reasoning 块）是对的上游修法。给已经被卡住的会话补一条立即恢复路径——坏的是 assistant/message content 里的空 reasoning 块，块级删除不需要重编号：

1. 老三样：停 dsh 进程、session 目录拷一份留底；
2. 定位：解压日志，扫每条 assistant/message 的 content 数组，找 type 为 reasoning/thinking 且 text 为空（或缺该字段）的块——报错里的 message 下标能直接反查到行；
3. 修：把这些空块从 content 数组里删掉（零信息；相邻非空 reasoning 不动）；
4. 该消息所在的 zstd 帧重编、其余帧字节不动；
5. 放回前全文件复扫（0 个空 reasoning 块）再切网关路由。

两点延伸：

• 这和悬空 tool_calls（修复盲区：已关闭轮次中的悬挂 tool_calls 不会被补齐，导致会话永久不可用 #7257）、孤立代理（[BUG] 工具输出含未配对 UTF-16 代理项会让整个会话永久 HTTP 400（错误信息无法诊断） #8352/[Bug] read 工具按 UTF-16 码元截断会切开代理对，产生非法 JSON 并使会话永久 400 #8846）是同一类病的不同切面：写入端缺「入库前有效性清洗」，脏块永久留在历史里，由下游最严格的消费者引爆。你在结论里提的 serialize 层跳过空块（或入库时拒绝空 reasoning）是正解，而且能顺带兜住其他块类型；
• 实操小技巧：换严格网关路由之前先扫一遍历史里有没有空 reasoning 块，有就先清再切，省一轮"切过去失败→切回来"的折腾。历史越长越容易混进空块，这个扫描值得做成常备小脚本。

（会话日志的行级/块级手术我在 #7257/#7824/#8084/#8352 给过同套四步法——定位、小改、局部重编、校验，这类"脏数据被严格消费者引爆"的形态基本都能救回。）

[argszero]

Confirmed, and the mechanism you located is exactly right — serialize.ts maps a reasoning block to a thinking wire block with no emptiness guard. But the fix you sketched has a second-order hazard that is worth pinning down before anyone writes it, because the obvious version of it makes a different part of the same message worse.

Dropping the block is not enough: the replay envelope must be pruned in step

replayState is positional. The contract is stated in the type itself (packages/llm/llm/src/types.ts:433-441):

Per-block adapter-private metadata, one entry per emitted block in first-seen stream order. When assembly drops a block it drops the entry at the same position; entries whose length does not match the emitted block count discard the whole envelope.

Three places enforce that, and they agree:

• packages/llm/llm/src/assembler.ts:143 — if (envelope.blocks.length !== all.length) return { blocks, replay: undefined }. A count mismatch does not degrade gracefully; it discards every signature in the message, including the ones on the blocks you kept.
• packages/llm/llm-deepseek/src/replay.ts:55 — envelope.blocks.length !== message.content.length → fail('block count mismatch').
• packages/llm/llm-deepseek/src/replay.ts:63 — return response.model === model ? blocks : undefined, the cross-model discard you observed.

So the shape to watch for is: a serialize-side or stream-side drop that removes the empty block from content while the envelope still carries N entries. That trades a hard 400 for silent signature loss on that message — and it would reproduce the failure mode you flagged in your point 1, where the next turn on the same model also loses signatures.

The good news is core already demonstrates the correct form. assembler.ts:135-146 (assembled()) has a kept vector for the max-token truncation path, and it filters envelope.blocks with the same predicate and the same positions as the emitted blocks:

replay: kept === undefined || blocks.length === all.length
  ? envelope
  : { response: envelope.response, blocks: envelope.blocks.filter((_, position) => kept[position]) },

That is the invariant to preserve: content.length === replay.blocks.length, position for position.

A sibling hole in the same switch

While confirming your anchor I checked the neighbouring case, and case 'text' (serialize.ts:30) has no guard either:

case 'text': return { type: 'text', text: block.text }

An empty assistant text block becomes { "type": "text", "text": "" }, which is the same class of rejection on an Anthropic-Messages-compatible gateway. I have not verified that one against a gateway the way you verified the thinking cases — I am reporting it as a source-level hole in the same function, not as a measured failure.

What makes it convincing as a pattern rather than an oversight is that the same file already applies the empty-drops-out rule in the other direction — developer/input content, serialize.ts:93:

case 'text': return block.text.length === 0 ? [] : [{ type: 'text', text: block.text }]

and core applies it to salvage as well (assembler.ts:164-180, interruptedBlocks() keeps only text/reasoning whose text.trim() !== ''). "A block with no text carries nothing" is already the codebase's rule; the assistant history side is the one place it is not applied.

On recovery for already-poisoned sessions

You are right that a serializer guard cannot help a session whose history already contains the block, and the suggestion in the thread (offline block deletion, keeping neighbouring blocks and frame bytes) is the right shape — block removal needs no renumbering. I would add one constraint to it, from replay.ts:55: if you delete a block from content you must delete the entry at the same position from source.replayState.blocks, or that message's replay metadata becomes unusable for exactly the reason above. Deleting the block but not its metadata entry converts a loud failure into a quiet one.

Note also that the request path is not a place a plugin can fix this for you: history is handed to adapters frozen, deliberately, so listeners read it and never rewrite it. The prevention half is the only half reachable from a plugin, and it has to happen on the response side.

A published sibling for the same family

Your cross-reference to #9215 is apt — it is the same shape (one malformed block poisons a session permanently) and it has a delivered preventive half: @argszero/dsh-phantom-tool-call-guard@0.1.0 (npm), which wraps the llm/stream waterfall's return value — the one thing on that waterfall a listener may replace — so the durable assistant/message and the live stream are repaired together, before the poison is written.

That seam is provider-agnostic and reusable for this shape too: an assistant content block whose text is empty is visible in the chunk stream (block-start{blockType} → deltas → block-end{block}), and dropping it there plus pruning the entry at the same position from the terminal finish chunk's replayState.blocks satisfies both halves at once — no empty wire block ever reaches the gateway, and the envelope stays aligned so the surviving signatures survive. I intend to publish that as a plugin, since neither adapter-side write is something a user can reach.

Two boundaries I would state up front rather than discover later: it prevents and does not cure (an already-durable block stays durable), and it can only see blocks the stream actually declares — anything an adapter adds to a message outside its chunk stream is out of reach.

Thank you for the six-row gateway matrix; "只有空值这一种过不去" is the kind of narrowing that makes this fixable at all.

[argszero]

The preventive half is now a published plugin, built on the seam described above.

@argszero/dsh-empty-block-guard@0.1.0 — npm: https://www.npmjs.com/package/@argszero/dsh-empty-block-guard · source: https://github.com/argszero/dsh-empty-block-guard

npm install @argszero/dsh-empty-block-guard@0.1.0

- insert:
    - id: empty-block-guard
      name: '@argszero/dsh-empty-block-guard'

It wraps the returned chunk stream of the llm/stream waterfall ({ global: true, prepend: true }) and removes a text or reasoning block whose text is empty before the loop assembles it or records it, so the durable assistant/message and its replay record are repaired together and cannot disagree afterwards.

The pairing is the part worth reviewing

Removing the block is not the whole fix, and the naive version of it is worse than the bug. I measured the requirement against the shipped code:

• packages/llm/llm/src/assembler.ts — if (envelope.blocks.length !== all.length) return { blocks, replay: undefined }. A count mismatch discards the whole envelope, so a stream-side drop that leaves the entry behind trades your 400 for the silent loss of every thinking signature in that message, kept blocks included.
• The entry therefore leaves at the rank of the dropped block, not at its index: the envelope is one entry per seen block in first-seen order, which is only the same thing while the indexes are contiguous. The suite has a case with a gap in the numbering precisely because a position !== index filter looks right on every two-block example.
• An envelope that never matched its own stream is left alone and counted as unaligned rather than rewritten, and an adapter whose metadata carries no per-block entries is not treated as a mismatch at all.

Which chunks go

assemble() returns a closed block verbatim and otherwise builds it from accumulated deltas, so what has to be removed depends on what was already emitted:

evidence	would assemble	what it does
non-empty deltas, or a close with text	a representable block	keeps it
start/deltas/close still buffered, close says empty	the empty block	removes the whole block
the close is the only evidence	the empty block	removes it
non-empty deltas already emitted, close says empty	the empty close verbatim, discarding the text	drops only the close
stream ended with the block still open	built from empty deltas	removes the block

The fourth row is the one a "drop the block" rule gets wrong: a close is authoritative, so keeping it poisons the session and throws away text the model sent.

It also covers the sibling hole I flagged in serialize.ts: case 'text' — types defaults to both, so {"type":"text","text":""} is caught by the same mechanism, though I have still only seen the thinking half refused by a real gateway.

Boundaries, stated rather than discovered

• Preventive, not curative. A session whose log already contains the block still needs the offline repair discussed above; nothing on the request side is reachable from a plugin, so this package is the fix for the next attempt, not a rescue for the current one. Its own snapshot().notCovered says so on every read.
• The rule is exactly empty (text.length === 0). A whitespace-only block is representable on the wire, so it is passed through untouched.
• Only blocks the stream declares. Anything an adapter adds to a message outside its chunk stream is out of reach, as I noted before.
• mode: 'observe' decides and counts exactly as drop does and emits the stream unchanged, which is how you check whether your history is producing these blocks before letting anything be removed:

ctx.get('emptyBlockGuard').snapshot()
// { counters: { streams, verdicts: {keep, drop}, reasons: {…}, envelopes: {untouched, pruned, unaligned} },
//   recent: [{ provider, model, sessionId, index, type, verdict, reason }], notCovered: [ … ] }

Verification, so the claim is checkable rather than asserted: 65 tests, 34/34 mutation arms caught (0 silent), and the peer range >=0.1.7-rc.2 <0.2.0 || >=0.2.0-rc.2 <0.2.1 pinned per line — 15 harness packages at each of 0.1.7-rc.2 and 0.2.0-rc.2, built and run against the real assembler. The control arm reproduces your report: without the plugin, the assembled block is empty and its wire projection is the body your gateway refuses.

Thank you for the reproduction and the gateway matrix — the observation, translated from the Chinese original, that "only the empty value is the one that does not get through" is what made this narrow enough to turn into a guard instead of a guess.