Sandbox 前端整合手冊
把使用者的程式碼打包成環境、送到該部署建置、執行，再把日誌與產出物取回前端。這份手冊說明前端要怎麼串。
這份手冊怎麼讀
先讀 快速開始，跑一次完整的 happy path：釘策展環境 SCFG Standard（或上傳＋建置自訂映像）→ 建部門任務 → 發布 → 分享 → 房間啟用 → 提交執行 → 取回結果。跑過一次，後面的內容就都是查閱資料。
概念 是設計串接前值得先讀的部分。幾乎所有呼叫都是 /private/module/sandbox；region／profile 下拉是 GET /public/info/sandbox/{regions,profiles}。最常踩雷的是——目錄任務是部門／公司擁有，不是聊天室（任務受眾）、未授權通常回 404（錯的 owner-scope 是 403；chatroom 建立是 422）、分享不是 Agent 選單、沒有 streaming（用輪詢）、兩種不同的 capability token（上傳 15 分鐘 vs 下載 5 分鐘 — 都不是 URL）。權限是階梯，不是一律 company manager，見 角色與權限。
操作流程 是任務導向的：一頁一個你被交辦要做的功能。API 參考 列出端點、完整請求／回應欄位、五個 agent 工具、列舉與錯誤。變更紀錄 釘住手冊稽核時的後端 SHA。
快速開始 →
從認證到第一個執行結果的完整最短路徑。
概念 →
控制面 vs 資料面、資源模型、狀態機與輪詢、內容與下載。
操作流程 →
建置環境、任務與綁定、執行與取結果、Agent 確認。
API 參考 →
端點目錄、完整欄位表、agent 工具、列舉、錯誤。
給 LLM / Agent 讀
這份手冊有機器可讀的純文字版本（與 custom-tables-docs 同一套慣例）：
/llms.txt— 索引：閱讀順序、租戶 API 契約摘要、每頁.md連結。/llms-full.txt— 雙語全文（先 zh-TW 再 en）。- 每一頁還有對應的 Markdown twin，例如
/zh-TW/concepts/personas.md。
內容來源
每一頁都對照後端 origin/master 原始碼撰寫。目前釘選見 變更紀錄（172a7f80bdf4dbdffdc018eb08bfa42c62bb485c，release v5.21.0，2026-10-08）。前端端點取自 src/routers/private/modules/sandbox/（base /private/module/sandbox）加上 GET /public/info/sandbox/*；欄位表取自那些 router 加上 src/schemas/sandbox.py；狀態列舉與限制取自 src/schemas/enums.py、src/components/sandbox/constants.py、src/components/sandbox/storage.py。Agent 工具在 src/components/tools/custom/sandbox/。控制面（/sandbox-control/*）與 root（/root/sandbox/*）不對前端開放。若後端與本手冊不一致，以後端原始碼為準，並回報給我們修正。
v5.21.0 串接變更（任務的 output_policy 現在可以執行自訂表格 Command、runner 憑證的有效期限現在涵蓋整個 timeout_seconds、runner 會重試完成回報）請先看更新紀錄，再看任務輸出交給自訂表格 Command。v5.10.11 的變更（佇列位置／預估時間、佇列 429 body、Quick Run input、依 provider 過濾的區域與地端部署）同樣在更新紀錄，以及能力、管理查詢與執行規劃。