概念總覽

Sandbox 讓前端把使用者定義的任務（task），綁定一個已建置好的環境版本（environment version），在聊天室（chatroom）裡執行（run），再把日誌與產出物取回。

幾乎所有呼叫都是 /private/module/sandbox。Region／profile 下拉是不必登入的 GET /public/info/sandbox/{regions,profiles}。Company manager 會經租戶 context-upload 路由上傳建置封存。Runner 串流與 R2 key 仍在控制面。

串接前先讀這幾頁：

• 架構：控制面與資料面：你呼叫哪些 API、哪些是後端系統對系統。
• 角色與權限：一般使用者、聊天室／部門／公司管理員、受限 key 誰能做什麼。
• 任務受眾：部門／公司擁有、分享 vs 啟用 vs 選單 vs writeback。
• 營運與 Root：/root/sandbox 營運面；不是產品前端。
• 資源模型：環境／context 上傳／任務／grant／啟用／執行。
• 狀態機與輪詢：所有狀態值與轉換；沒有 streaming，前端用輪詢。
• 內容、Digest 與下載：context 上傳、輸入 JSON 限制、產出物下載 token。
• Secret 與授權：secret binding、slot、borrower 授權。
• 限制與配額：分頁、輸入/腳本大小、逾時、每公司政策上限。
• 保留期：內容/映像/日誌各自的過期時鐘。
• 通知：通知中心的 sandbox_event；它們只是提示，GET 狀態仍是權威。

一頁看懂資料流

環境 Environment
   └─ context 上傳 → 版本 Version（owned_object_id → 建置 → ready）
         └─ 部門／公司任務 → 任務版本 → 發布 → 分享
               └─ 房間啟用 → 選單 / Agent
                     └─ 執行 Run（輪詢狀態；取產出物）

命名：本手冊的「Sandbox」指 TeamSync 後端的 sandbox 模組，與 Cloudflare 的「Sandbox SDK」無關。