Cloud 環境反覆出現 "Stream idle timeout - partial response received"

[atomchung]

問題描述

在 Claude Code Cloud (Web) 環境執行較大型任務（例如 xhs_content_generator 寫入長檔案 + git commit + push）時，反覆出現以下錯誤：

API Error: Stream idle timeout - partial response received

即使重試、簡化指令、或要求「最小化輸出」，仍會在同一個 turn 中斷。

成因分析

Stream idle timeout 表示模型在生成過程中過久沒有產生新的 token，Cloud 連線判定為 idle 而被切斷。partial response received 代表已經開始回應、但中途卡住。

常見觸發條件：

1. 單一 turn 塞入過多步驟 — 例如要求一次完成「Write 落檔 + Bash commit + push」，模型需要先構思整段內容、再生成長檔案、再串接多個工具呼叫，中間任何一段思考過久沒有 streaming output 就會斷線。
2. 長檔案寫入 — 單一 Write 工具呼叫生成數千行內容，內部生成時間長，容易 idle。
3. Extended thinking 預算過高 — 思考階段沒有 visible output，容易超過 idle 閾值。
4. 網絡抖動 — Cloud 環境連線本身不穩定時更容易觸發。

解決方法

1. 分步驟執行，避免單 turn 過載

• 第一輪：只做 Write 落檔
• 第二輪（確認檔案寫入成功後）：再執行 git add / commit / push

2. 長檔案斬件寫入

• 單一 Write 內容若超過約 500 行，分 2–3 次呼叫
• 或先 Write 骨架，再用 Edit 逐段補完

3. 切換到 Fast mode

• 在 Claude Code 內輸入 /fast 切換到 Opus 4.6
• 輸出 throughput 較快，較不容易觸發 idle timeout

4. 遇到 partial response 時「繼續」而非「重做」

• partial response 表示已有部分工作完成
• 指示模型「繼續未完成的部分」，避免從零重新生成

5. 長任務改用 background agent

• 大型 research 或大量改動，spawn 一個 background subagent 處理
• 主 session 不會因 streaming timeout 受影響

6. 降低 thinking budget

• 若任務不需要深度推理，避免使用高 thinking budget
• 減少無 output 的思考時間

一句話總結

不要在同一個 turn 內又寫檔又 commit 又 push，分開做，搭配 /fast 模式基本可以解決。

參考情境

• 觸發 skill：xhs_content_generator
• 觸發指令：要求同一 turn 內完成「Write 落盤 + Bash commit + push」
• 環境：Claude Code Cloud (Web)