五分鐘跑一次

以下省略 base 前綴 {BASE}/private/module/sandbox，並假設帶好認證。變更操作需要 company manager。

1. 建立環境


POST /environments
{ "name": "my-runner", "description": "demo" }
# → SandboxEnvironmentResponse { id, state: "active", ... }

2. 建立版本（提供 source_digest）

在本地打包建置內容、算出 sha256，把 digest 傳進來：


POST /environments/{environment_id}/versions
{ "source_digest": "sha256:<64位hex>", "resource_profile": "standard" }
# → SandboxEnvironmentVersionResponse { id, state: "draft", ... }

resource_profile ∈ standard / performance / large / xlarge。

3. 觸發建置並輪詢到 ready


POST /environments/{environment_id}/versions/{version_id}/builds
{ "build_region": "asia-east1", "build_profile": "standard" }
# → SandboxBuildAttemptResponse { id: attempt_id, status: "validation_queued", ... }

輪詢（沒有 streaming）：


GET /environments/{environment_id}/versions/{version_id}/builds/{attempt_id}
# 直到 terminal_class 有值：completed / customer_failed / platform_failed / cancelled
 
GET /environments/{environment_id}/versions/{version_id}
# 直到 version state == "ready"

4. 建立任務並發布版本


POST /tasks
{ "name": "hello", "owner_scope": "chatroom", "owner_id": "{chatroom_id}", "agent_enabled": false }
# → SandboxTaskResponse { id: task_id, ... }
 
POST /tasks/{task_id}/versions
{ "environment_version_id": "{version_id}", "work_script": "echo hi",
  "timeout_seconds": 1800, "requires_confirmation": false }
# → SandboxTaskVersionResponse { id: task_version_id, state: "draft", ... }
 
POST /tasks/{task_id}/versions/{task_version_id}/publish
# → state: "published"

5. 綁定到聊天室


POST /bindings
{ "chatroom_id": "{chatroom_id}", "task_id": "{task_id}", "task_version_id": "{task_version_id}" }
# → SandboxBindingResponse { id, state, ... }

之後在該聊天室即可看到可執行清單：


GET /chatrooms/{chatroom_id}/menu
# → items[] 帶 task_version_id / requires_confirmation / secret_slot_names / timeout_seconds

6. 提交執行（要帶 Idempotency-Key）


POST /chatrooms/{chatroom_id}/runs
Idempotency-Key: <每次新的 UUID>
{ "task_version_id": "{task_version_id}", "input": { "any": "json" } }
# → SandboxRunDetailResponse { id: run_id, status: "queued", ... }

7. 輪詢狀態並取產出物


GET /chatrooms/{chatroom_id}/runs/{run_id}
# 直到 terminal_at 有值（status: completed / customer_failed / platform_failed / cancelled）
 
GET /chatrooms/{chatroom_id}/runs/{run_id}/content
# → { has_output, has_log, has_artifact_bundle, input_digest, ... }
 
GET /chatrooms/{chatroom_id}/runs/{run_id}/artifacts
# → items[] { id, relative_path, byte_size, digest, deletion_state }
 
POST /chatrooms/{chatroom_id}/runs/{run_id}/artifacts/{artifact_id}/download
# → { capability_token, expires_at, content_type, content_disposition }
# 用 capability_token 去取實際位元組（短效；過期重換）

想更快？Quick Run（manager-only）

一次原子地建立隱藏任務+版本+執行，適合「跑一次性腳本」：


POST /chatrooms/{chatroom_id}/quick-run
Idempotency-Key: <UUID>
{ "name": "adhoc", "environment_version_id": "{ready_version_id}",
  "startup_script": "", "work_script": "echo hi", "ordinary_env": {},
  "input": {}, "timeout_seconds": 600 }
# → { task, version, run: SandboxRunDetailResponse }

完整端點、欄位與錯誤見 API 端點目錄。逐步流程見操作流程。