架構：控制面與資料面
前端的世界：/private/module/sandbox
所有前端會呼叫的 sandbox API 都掛在 /private/module/sandbox 底下（注意是單數 module，這在後端是「安全相關」的路徑，用於請求內容遮蔽）。子路由前綴：
| 資源 | 前綴 |
|---|---|
| 公司設定 | /settings |
| 環境 / 版本 / 建置 | /environments |
| 任務 / 任務版本 / 分享 | /tasks |
| 綁定 | /bindings |
| Secret / 授權 | /secrets、/secret-approvals |
| 執行 | /chatrooms/{chatroom_id}/...（含 /menu、/runs、/quick-run） |
前端「看不到」的世界：控制面
以下都是系統對系統，前端沒有呼叫路徑，也不該出現在前端文件裡（僅為理解流程列出）：
| 路由群 | 用途 | 認證 |
|---|---|---|
/sandbox-control/* | Cloud Build / Run / Scheduler 等隔離工作負載回呼、結果物件上傳、建置內容串流 | Google 服務帳號 OIDC + capability session；include_in_schema=False |
/root/sandbox/* | 營運/root 操作 | Root/operator |
位元組怎麼搬：實際的建置內容上傳（init → capability → put/parts → complete）、結果物件寫入、建置內容串流，全在控制面。前端不會拿到上傳 capability，也不需要處理 20 槽位配額那類事情——那些是控制面內部機制。前端對「內容」的接觸只有兩點：
- 建立版本時提供一個
source_digest（sha256:...），宣告建置內容的內容雜湊。 - 取產出物時，向
/download換一張短效 capability token，再用它拿位元組。
詳見 內容、Digest 與下載。
沒有 streaming
sandbox 面向前端的部分沒有任何 WebSocket / SSE / StreamingResponse。建置與執行的進度一律用輪詢（GET 狀態）。細節見 狀態機與輪詢。
Last updated on