統一執行時串流重構計畫

目標

建立一條 main、subagent 和 acp 共用的串流管線，讓所有執行時取得一致的合併、分塊、投遞排序與崩潰復原行為。

為何需要

• 目前的行為分散在多個執行時專屬的整形路徑中。
• 格式化/合併的 bug 可能在某個路徑修復但在其他路徑仍然存在。
• 投遞一致性、重複抑制和復原語義更難推理。

目標架構

單一管線，搭配執行時專屬的轉接器：

1. 執行時轉接器僅發出正規化事件。
2. 共用串流組裝器合併並最終化文字/工具/狀態事件。
3. 共用頻道投影器套用頻道專屬的分塊/格式化一次。
4. 共用投遞帳本強制冪等的傳送/重播語義。
5. 出站頻道轉接器執行傳送並記錄投遞檢查點。

正規化事件合約：

• turn_started
• text_delta
• block_final
• tool_started
• tool_finished
• status
• turn_completed
• turn_failed
• turn_cancelled

工作流

1) 正規化串流合約

• 在核心中定義嚴格的事件 schema + 驗證。
• 新增轉接器合約測試，保證每個執行時發出相容的事件。
• 及早拒絕格式錯誤的執行時事件，並呈現結構化的診斷。

2) 共用串流處理器

• 以單一處理器取代執行時專屬的合併器/投影器邏輯。
• 處理器負責文字 delta 緩衝、閒置刷新、最大區塊分割和完成刷新。
• 將 ACP/main/subagent 的設定解析移至同一輔助函式以防止偏差。

3) 共用頻道投影

• 保持頻道轉接器的簡潔：接受最終化的區塊並傳送。
• 將 Discord 專屬的分塊怪癖僅移至頻道投影器。
• 在投影前保持管線與頻道無關。

4) 投遞帳本 + 重播

• 為每回合/每區塊新增投遞 ID。
• 在實際傳送前後記錄檢查點。
• 重啟時冪等地重播待處理的區塊，避免重複。

5) 遷移與轉換

• 第 1 階段：影子模式（新管線計算輸出但舊路徑傳送；進行比對）。
• 第 2 階段：逐執行時轉換（acp，然後 subagent，然後 main，或依風險反向進行）。
• 第 3 階段：刪除舊有的執行時專屬串流程式碼。

非目標

• 本次重構不改變 ACP 策略/權限模型。
• 除投影相容性修復外，不進行頻道專屬功能擴展。
• 不進行傳輸/後端重新設計（acpx 外掛合約維持不變，除非需要事件對齊）。

風險與緩解

• 風險：既有 main/subagent 路徑的行為回歸。 緩解：影子模式比對 + 轉接器合約測試 + 頻道端對端測試。
• 風險：崩潰復原期間的重複傳送。 緩解：持久的投遞 ID + 投遞轉接器中的冪等重播。
• 風險：執行時轉接器再次偏差。 緩解：所有轉接器必須通過共用合約測試套件。

驗收標準

• 所有執行時通過共用串流合約測試。
• Discord 的 ACP/main/subagent 對微小 delta 產生等同的間距/分塊行為。
• 崩潰/重啟重播對同一投遞 ID 不傳送重複區塊。
• 舊有的 ACP 投影器/合併器路徑已移除。
• 串流設定解析為共用且與執行時無關。