Sandbox 前端整合手冊

這份手冊怎麼讀

先讀 快速開始，跑一次完整的 happy path：建環境 → 建版本（給 digest）→ 建置 → 建任務並發布 → 綁定聊天室 → 提交執行 → 取回結果。跑過一次，後面的內容就都是查閱資料。

概念 是設計串接前值得先讀的部分。前端只跟一個面向對話：/private/module/sandbox。三個最常踩雷的觀念是——未授權一律回 404（不洩漏存在性）、沒有 streaming（用輪詢）、下載產出物拿的是短效 capability token 而不是 URL。位元組的實際搬運與持久化上傳都在後端控制面，前端碰不到。

操作流程 是任務導向的：一頁一個你被交辦要做的功能。API 參考 逐一列出端點、參數、回應與錯誤。

內容來源

每一頁都對照後端 master 原始碼撰寫。前端端點取自 src/routers/private/modules/sandbox/（base /private/module/sandbox）；狀態列舉與限制取自 src/schemas/enums.py、src/components/sandbox/constants.py、src/components/sandbox/storage.py。控制面（/sandbox-control/*）與 root（/root/sandbox/*）不對前端開放。若後端與本手冊不一致，以後端原始碼為準，並回報給我們修正。