ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 StreamChunk:流式协议、失败分类与重试策略到底怎么配合

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessStreamChunkLlmFailure重试策略
流式中途断开,适配器返回的 chunk 形状不对,或重试把半截内容又发了一遍。本文讲 StreamChunk 七个变体的边界、紧凑 stream 的回放作用、LlmFailure 与两条错误路径,以及不可变重试策略。

流式中途断开时,最容易犯的错是把“失败事实”和“是否重试”混成一个判断。 DSH plugin 把两件事拆开:LlmFailure 只描述发生了什么,ResolvedRetryPolicy 才决定还能不能再试。混着写,就会出现半截内容重复发送。 DSH插件 写适配器的人最该记住一句:一次调用只算一次尝试。

一次流式响应是交错块,不是一段文本

StreamChunk 是封闭的可辨识联合,index 负责把交错 delta 归位。(来源)

一个流式响应会同时包含文本、推理与多个工具调用。index 把每个 delta 关联到所属块;block-end 携带完整组装好的 ContentBlock,消费方无需自己重新组装 delta。因为它是封闭联合,对 type 的 switch 以 assertNever 结尾,新增变体会在每个必须处理它的消费方处触发编译错误。

七个变体各自的分工:

变体携带什么
block-startindex 与 blockType
text-deltaindex 与文本片段
reasoning-deltaindex 与推理片段
tool-call-deltaindex、调用 id、可选 name 与原始参数增量
block-endindex 与组装完成的块
usagetoken 用量
finish结束原因与可选 replayState

适配器约定里有一条顺序硬约束:usage 在终止性 finish 之前,finish 之后不再有任何分片。工具参数全程保持原始 JSON 字符串——如果提供方返回已解析对象,适配器要在 block-end 时重新序列化。

紧凑 stream 是回放证据,不是第二条消息

压缩只去掉重复信封,不合并 token 边界,也不丢终止事实。(来源)

AssistantStreamAccumulator 把每个 StreamChunk 与其原始安全整数时间戳配对,生成 AssistantStreamRecord[]。同一 block 的连续 text、reasoning 或 tool argument delta 会合成一个 record:使用 time0、精确时间戳间隔,以及每个原始 delta 对应的一个数组成员;其他 chunk 保留为带时间戳的 raw record。

这条压缩有三个“不”:不合并 token 边界、不丢弃 terminal、usage、block、failure 或 replay 事实、不改变顺序。所以它既能显著减小日志,又能在回放时还原精确的带时间流。

snapshot() 返回分离且不可变的 stream;expandAssistantStream() 会严格检查 record key、成员数、index、时间戳、tool-call identity 与无损 JSON,再重建精确序列。Session 日志把该 stream 嵌进作为 surface result 的 assistant/message,或嵌进没有 surface message 的 assistant/attempt。

进程本地的 agent/assistant-stream frame 只承载实时呈现,不进入持久 feed。记录级读取器(如 assistantStreamFirstTokenTime、assistantStreamHasVisibleText、lastAssistantStreamChunk)在一次扫描内提前退出,因此大历史每次结算的代价是 O(records) 而不是 O(members)。

LlmFailure 是事实,不是重试决定

它只描述失败,是否重试不写在里面。(来源)

ts
interface LlmFailure {
  readonly message: string
  readonly code: string
  readonly status?: number
  readonly providerRetryAfterMs?: number
  readonly requestId?: ProviderRequestId
  readonly offloadImages?: number
}

code 是稳定的提供方中立机器路由码,消费方按 code 路由,绝不依赖提供方文本。status 是可用时的 HTTP 状态。providerRetryAfterMs 是经校验、由提供方请求的正数延迟,官方特别说明它不是重试决策——策略可以采纳,也可以忽略。requestId 是不透明品牌字符串,只用于诊断。

offloadImages 只与 IMAGE_OFFLOAD_REQUIRED 配套:它告诉路由还需要卸载多少个最老的保留图片,才能让同一请求装进精确字节计量;dsh-compaction-image-offload 会记录选中的出现位置并重试该步骤。

两条错误路径,一个失败类型

抛出的失败与带内失败最终都收敛成同一个 payload。(来源)

两条受支持的错误路径共用 LlmFailure:一是从 stream() 抛出,属于传输或协议错误;二是以 finish { kind: 'error' | 'aborted', failure } 结束流,供无法在流中途抛异常的适配器表示提供方带内错误。LlmError.failure 携带同一个类型。

调用选定适配器后,流会保留被抛出的确切 Error 对象,并把不可变事实与实际服务注册对应的不可变重试策略关联到该调用。agent 循环的处理顺序是固定的:

  1. 先把 attempt stream 提交为 assistant/attempt;
  2. 再关闭失败步骤;
  3. 把错误、事实、不可变的先前已重试失败事实、实际服务策略与轮次信号交给 agent/request-error;
  4. listener 在 await 的修复完成后返回 { kind: 'retry' } 才算接管恢复。

若未恢复,结构化失败会成为轮次错误,并且该次 attempt 不会提交 surface Assistant message 或工具副作用。这条“先提交 attempt 再关闭”的顺序,正是避免半截内容被当成成功消息的关键。

适配器约定里与重试直接相关的四条

这四条决定了“重试会不会重复输出”。(来源)

  1. 一次适配器调用就是一次提供方尝试 — 适配器必须禁用库级重试。agent 层恢复会打开另一个持久、带编号的轮次;直接调用 ctx.llm.stream() 的调用方仍然只尝试一次。
  2. 停顿由传输层限时 — 两个已交付的远程适配器都暴露正数且有限的 streamIdleTimeoutMs,默认五分钟。watchdog 只在 iterator next() 尚未完成时启动,整个请求使用同一个稳定 signal,把自身到期映射为 TIMEOUT,而更早发生的调用方中止保留为 ABORTED。
  3. 上下文溢出只有一个规范 code — 两个 DeepSeek 适配器都通过 isContextWindowExceededError() 分类并暴露 CONTEXT_WINDOW_EXCEEDED,无论失败以抛出的 HTTP LlmError 还是带内 finish error 到达。
  4. 空 completion 是可重试错误 — 没有携带任何内容块的终止性 stop 映射为带 EMPTY_RESPONSE 的 finish { kind: 'error' },dsh-llm-retry 默认会重试它。

ResolvedRetryPolicy:注册后不再改变

策略在路由注册前解析成不可变联合,进行中的失败不再受后续替换影响。(来源)

两种模式:

  • normal — 携带有限的 maxRetries、retryableCodes,以及必填的 initialDelayMs、maxDelayMs 与 jitterRatio;
  • always — 携带 mode: 'always' 与相同的必填退避字段,但没有有限上限。

省略提供方策略时,使用重试五次的 normal 默认值。分层 settings 从 normal 切到 always 后,可能仍保留只属于 normal 的 maxRetries 或 retryableCodes;解析器会忽略这些未启用字段,并捕获一个纯 always 策略。

读取入口有两个:LlmRuntime.providerRetryPolicy(provider) 返回注册值;调用选定实际提供服务的注册后,llmRetryPolicyOf(stream) 返回从中捕获的值。后者是排查“为什么这次没重试”的依据——之后释放或替换路由,都无法改变进行中失败所用的恢复策略。

验证:注入中途断开与不重复输出

验证重试要看两件事:失败是否被正确分类,以及输出有没有被重复提交。(来源) 六步:

  1. 注入一个在 text-delta 之后抛错的适配器,断言错误被规范化为终止性 finish,而不是裸露异常。
  2. 断言该尝试先提交为 assistant/attempt,且没有产生 surface Assistant message。
  3. 在 agent/request-error 里返回 { kind: 'retry' },断言恢复轮次是新的持久编号,而非复用旧尝试。
  4. 让重试成功,断言历史里只有一条 assistant 消息,不包含第一次的半截文本。
  5. 构造只有 stop、没有内容块的响应,断言失败 code 是 EMPTY_RESPONSE 且默认策略会重试。
  6. 构造上下文溢出,断言 code 是 CONTEXT_WINDOW_EXCEEDED,而不是靠匹配提供方文本。

如果第 4 步出现两条消息,问题通常在适配器自己做了库级重试——违反“一次调用一次尝试”的约定。

流式卡顿与 gzip 缓冲的具体排查,可以对照gzip 流式缓冲修复;适配器怎么接入路由,见LLM 适配器。

一句话收束: chunk 是交错块协议,紧凑 stream 只压信封不压事实,失败只记事实、重试只看策略,一次适配器调用只算一次尝试。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 StreamChunk 需要消费方自己拼 block 吗?

不需要,DSH plugin 的 block-end 携带完整组装好的 ContentBlock。DSH plugin 用 index 关联交错 delta,消费方只要处理 block-end 的结果,不必重新组装。

DSH plugin 的 providerRetryAfterMs 是重试决定吗?

不是,DSH plugin 只把它当作提供方请求的延迟。DSH plugin 的 LlmFailure 提供可序列化的事实,是否重试由不可变的重试策略决定。

DSH plugin 的适配器能不能自己在库里做重试,为什么不行?

不可以,DSH plugin 规定一次适配器调用就是一次提供方尝试。DSH plugin 要求适配器禁用库重试,恢复由 agent 层打开另一个持久编号的轮次完成。

DSH plugin 的空 completion 算成功吗?

不算,DSH plugin 把它映射成可重试错误。DSH plugin 的适配器会把没有内容块的终止性 stop 映射为带 EMPTY_RESPONSE 的 error finish,默认重试策略会重试它。

相关术语

StreamChunk
StreamChunk 是适配器发出的原始流式协议,是封闭的可辨识联合类型,block-end 携带已组装的 ContentBlock。— packages/llm/llm/src/types.ts
AssistantStreamRecord
AssistantStreamRecord 是紧凑 assistant stream 的记录,把 chunk 与原始安全整数时间戳配对,保留 delta 边界。— DeepSeek Harness 官方参考 - LLM 流式输出
LlmFailure
LlmFailure 是可序列化、提供方无关的失败事实,含 message、code、可选 status、providerRetryAfterMs 与 requestId。— packages/llm/llm/src/types.ts
ResolvedRetryPolicy
ResolvedRetryPolicy 是路由注册前解析出的不可变重试策略,分 normal 与 always 两种模式。— DeepSeek Harness 官方参考 - LLM 流式输出

来源