LLM 適配層：單次嘗試、顯式重試、雙流持久

先玩再講。左邊是網綫上的 SSE 分片（provider 逐幀吐出來的原始數據），右邊是會話日誌（每個分片立刻落一條 assistant/chunk，流結束再派生一條 assistant/message），上方是用戶看到的 UI。三個情景：A 是一次順利的雙流落盤；B 中途斷綫，看重試怎麼以顯式事件出現在時間綫上；C 是反面教材，SDK 靜默重試模式，同一個故障，日誌裏無跡可查。

先立規矩。DSH 的適配器約定裏有一條寫得很硬：一次適配器調用就是一次提供方嘗試，適配器必須禁用庫自帶的重試（docs/subsystems/llm-streaming.zh.md 適配器約定一節）。HTTP 庫們都愛替你悄悄重試，看起來是貼心，實際是把信息藏起來了：請求為什麼慢、重試了幾次、每次因為什麼失敗，全部消失在庫的內部循環裏。DSH 把這層全部剝掉，適配器只幹一件事：發一次請求，把響應轉成統一的 StreamChunk 分片吐出來，失敗就規範化成一個可序列化的 LlmFailure（帶穩定的錯誤 code），別的不管。

防掛起也在這層解決：兩個交付的遠程適配器都帶 streamIdleTimeoutMs 看門狗，預設五分鐘，provider 停頓超時就映射成 TIMEOUT 錯誤。還有一條容易漏的：空回覆算錯誤。模型返回一個不帶任何內容塊的 stop，適配器把它映射成 EMPTY_RESPONSE 錯誤而非靜默的成功，這樣重試層才有機會救它。

然後看落盤。agent loop 消費分片流的時候幹兩件事：每個分片原樣追加一條 assistant/chunk 事件進會話日誌，同時把分片餵給 BlockAssembler（組裝器）。流成功結束，組裝結果作為一條 assistant/message 事件再落一次盤。這就是雙流：chunk 流是原始錄像，回放測試靠它逐幀重建當年的響應；message 流是派生歷史，下一次請求的對話上下文從它派生。推理塊（reasoning，模型的思考過程）和正文塊（text）在分片協議裏就是不同類型，各自獨立組裝、各自落盤。

      const assembler = new BlockAssembler()
      const chunkSeqs: number[] = []
      const stream = preparedCall?.stream(request) ?? this.loopCtx.llm.stream(request)
      signal.throwIfAborted()
      for await (const chunk of stream) {
        signal.throwIfAborted()
        chunkSeqs.push(this.session.append('assistant/chunk', { turn, step, chunk }).seq)
        assembler.push(chunk)
      }

這九行是雙流的心臟：先落盤，再組裝，一個分片都不例外。流結束後走分岔：finish 是錯誤或中止，就把失敗交給 agent/request-error 事件去決定重不重試（第 354 到 371 行）；成功才在第 381 行追加 assistant/message，並把這批 chunk 的序號寫進 sourceEventSeqs，標明這條消息是從哪些分片派生的。所以失敗的半截輸出有明確的歸宿：留在 chunk 流裏作證，絕不進派生歷史。下一次請求重建上下文時，那半截就像沒發生過。

組裝器本身也值得停一下。BlockAssembler 是全倉庫唯一的分片摺疊實現，適配器只要按 index 吐格式正確的分片，塊重組不用每家自己寫。它對畸形流有明確態度：處理 block-end 分片時，先看這個塊是不是已經關閉過，關過就直接返回，後面再來的重複關閉一律忽略。註釋裏管這叫「First close wins」，理由是只有第一次關閉説了算，流式輸出和最終組裝出的塊才能保持一致。這一行防禦恰好是性質測試抓過真 bug 的地方（複盤見 測試一個非確定性系統）。

出處：packages/llm/llm/src/assembler.ts 第 75 至 82 行的 block-end 分支，核對日期 2026-08-13。

重試住在更高一層。dsh-llm-retry 插件監聽 agent/request-error，按每條 provider 路由註冊時捕獲的策略決定救不救。預設的 normal 策略：只對 EMPTY_RESPONSE、RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT 五種 code 重試，最多兩次，退避從 500 毫秒到 10 秒，帶 10% 抖動；provider 用 Retry-After 指定的合法延遲會替換本地退避（packages/llm/llm-retry/README.zh.md）。

關鍵在於它怎麼記帳。等待退避之前，插件先往會話日誌追加一條 llm/retry 事件，裏面裝着重試 id、提供方、策略 mode、完整的失敗信息和計劃延遲；退避結束真要動手了，再追加一條 llm/retry-started。這兩條事件不進模型可見的表層，模型對重試一無所知，但 UI 和事後分析全靠它們：UI 據此撤回失敗的半截輸出、顯示「第 1/2 次重試，3 秒後」；排查問題時，日誌裏每一次嘗試、每一段等待都有時間戳。重試本身則開一個新的編號輪次，從持久歷史重建同樣的請求重發，舊輪次的記錄一個字不改。

還有一個跨適配器的細節：replayState。成功的 finish 分片可以攜帶適配器私有的回放狀態（比如 DeepSeek 推理內容的原生表示），跟着 assistant/message 一起存。下次請求把歷史發給適配器前，LlmRuntime.forAdapter() 檢查每條歷史消息：歷史 provider 和目標 provider 歸同一個適配器實例，狀態才透傳；換了適配器，狀態被剝離，對方只拿到提供方無關的內容（packages/llm/llm/src/index.ts 第 822 至 836 行）。一家的私貨絕不餵給另一家。