Skip to Content
操作流程一般使用者執行任務

一般使用者執行任務

這頁只給一般租戶使用者（聊天室成員，role < 2）：從 menu 找到可跑的任務、提交、等結果。不要建環境、不要建任務、不要建綁定——那些是管理員的事，見 角色與權限。

公司沒有自訂環境也沒關係。live 目錄是名為 SCFG Standard 的 system_curated 環境（每個公開區域都是 state=ready）。管理員把那個版本釘到部門或公司任務上（租戶不上傳）、分享、房間啟用，你還是從下面的選單開始。見 任務受眾。

受限 API key 只允許 menu、提交與自己的 run。Retry 被 route allowlist 排除（允許房間回 405），Quick Run 與任務管理則更早在 auth 回 403；請見認證。

1. 從 menu 發現可執行任務

沒有 GET /bindings 列表。 一般使用者靠聊天室 menu 發現能跑什麼：

GET /chatrooms/{chatroom_id}/menu   # query page_size (ge1 le100, 預設 50)

回 items[]（SandboxMenuItemResponse）：task_id、task_name、task_version_id、task_version_digest、requires_confirmation、secret_slot_names、secret_slots[]、timeout_seconds、update_available、input_instructions / input_example、input_schema?、runtime_contract?、secret_use_risk_warning?。如果有 input_schema，client 端就先照它驗證 input——伺服器也會強制檢查（派工前 422 input_schema_violation）。這個選單回應上的 runtime_contract.driver 永遠是預設 fallback，不管誰來問都不會是真正的 work_command——見 Schemas。

選單列出已授予此房間且已在此啟用的任務。清單不因你是誰而變。已授予但未啟用的任務不會出現。受限金鑰可對允許清單內的房間呼叫。未授權的房間 → 404。

公司內任何非受限 JWT 也可以 GET /tasks 看公司任務目錄（隱藏的 quick-run parent 會過濾），但可執行清單仍以 menu 為準。

2. 提交執行（必帶 Idempotency-Key）

POST /chatrooms/{chatroom_id}/runs
Idempotency-Key: <UUID>          # 必帶，否則 422 idempotency_key_required
{ "task_version_id": "...", "input": {...}, "timeout_seconds": 1800 }
  • input：canonical JSON（≤1 MiB、深度 ≤64、節點 ≤100k、無 NUL、無重複 key）。
  • body 過大先回 413 request_too_large（依 Content-Length）。
  • 版本非「published + content active」→ 409。
  • 回 SandboxRunDetailResponse，status: "queued"。

同一把 Idempotency-Key 配完全相同的請求（同房間、task_version_id、input、實際生效的 timeout_seconds）重送，會重放同一結果。同一把 key 換了內容則回 409 idempotency_conflict，不是重放；請求雜湊也包含 retry_of_run_id，所以同一把 key 混用 retry 與新提交同樣是 409——新的意圖一律用新的 UUID。

3. 輪詢狀態

GET /chatrooms/{chatroom_id}/runs/{run_id}

status 走 queued → starting → running → completed（或 customer_failed / platform_failed；取消 cancel_requested → cancelled）。終態看 terminal_at。失敗看 error_code。沒有 streaming。

列表：

GET /chatrooms/{chatroom_id}/runs?status=queued&status=running   # status 可重複

一般使用者只會看到自己的 run。別人的 run、別的室的 run、借用方跑你沒提交的任務——對你都是 404。狀態細節見 執行與取回結果。

4. 看有哪些產出

GET /chatrooms/{chatroom_id}/runs/{run_id}/content
# → { state, has_input, has_output, has_log, has_artifact_bundle, input_digest }

只有布林旗標，沒有內容本體。 state 可能是 "missing"（尚無內容列）。

5. 列出並下載產出物

GET /chatrooms/{chatroom_id}/runs/{run_id}/artifacts        # 預設 lifecycle=active
# → items[] { id, relative_path, byte_size, digest, deletion_state, declared_content_type }
 
POST /chatrooms/{chatroom_id}/runs/{run_id}/artifacts/{artifact_id}/download
# → { capability_token, expires_at, content_type, content_disposition, x_content_type_options: "nosniff" }
  • POST .../download 只做擁有權授權，回傳 5 分鐘效期的 capability_token——這個 token 不會被儲存，目前沒有任何端點能兌換它，拿不到位元組。
  • 要實際下載 run 的位元組，改為對 run 的 log 或 output 鑄造永久公開連結：POST /chatrooms/{chatroom_id}/runs/{run_id}/{log|output}/public-link → { url, token }，再 GET /public/sandbox/artifacts/{token}；用同一路由的 DELETE 撤銷。run 還沒有 log／output 物件時鑄造會 404；受限 API key 一律被拒絕鑄造（因此完全沒有位元組下載路徑）。
  • 個別檔案現在可用 per-file public link 供瀏覽器下載；短效 artifact-capability 端點只授權，不回位元組或 raw URL。請使用回傳的 public-link URL，不需分享時將其撤銷，詳見下載契約。
  • deletion_state != active 的產出物，download 一律 404。

6. 取消自己進行中的 run

POST /chatrooms/{chatroom_id}/runs/{run_id}/cancel

一般使用者只能取消自己的進行中 run（kill switch 下這條仍可用）。別人的 run 對你是 404。管理員能取消他們看得到的 run——那不是本頁。

Retry 保留精確的任務版本 pin，建立新的 run 身分。省略 body、送 {} 或 {"input": null} 會逐位元重放保留的來源 input；非 null 的 input 則覆寫參數，依一般輸入限制重新驗證與暫存。來源 input 不存在、已退役、無法讀取或 digest 不符時，重放回 409 retry_input_unavailable，請改傳明確的 input。必帶 Idempotency-Key；來源未終態回 409 retry_not_eligible。受限 Sandbox key 不可 retry：允許房間的請求會被 route allowlist 拒絕（405）；不在 key scope 的房間可能更早回 403。

借用者目錄：沒有腳本

menu 與借用者視圖不含腳本原文。別人分享給你的任務，版本回應中 startup_script / work_script / ordinary_env / work_command / secret_slot_declarations / output_policy 全都回 null（欄位存在但為 null，不是缺席），content_hash 回空字串。task version 沒有 source_digest 這個欄位（那是環境版本的欄位）；版本摘要 canonical_digest（menu 上叫 task_version_digest）借用者看得到，secret 核准就是用它。你只看得到執行所需（secret_slot_names、說明、逾時）。只有管理該任務 owner scope 的人才看得到擁有者視圖。

一般使用者做不到的事

不要呼叫這些；未授權識別碼通常是 404（隱藏存在性）：

  • 建立 / 更新 / 歸檔環境
  • GET / PUT /settings——例外：這兩條走共用的 COMPANY_MANAGER（role ≥ 3）依賴，role 不足回 403 Insufficient permissions.，不是 404；前端不要假設所有管理員專用端點都長成 404
  • 建立任務（任何 owner scope）、發布 / 歸檔 / 分享
  • 建立 / 接受 / 撤銷綁定
  • secret 寫入 / 輪替 / 撤銷與核准
  • POST /chatrooms/{id}/quick-run

一般使用者不該建任務。POST /tasks 送 owner_scope=chatroom 是 422。不能擁有的 department／company scope 是 403 owner_scope_forbidden。

404 對你代表什麼

對一般使用者，404 幾乎都是「這個 id 你不能碰」——可能不存在，也可能存在但你沒權限。前端不要用 404 判斷資源被刪了。跨公司、非成員聊天室、別人的 run、管理員專用端點，都長一樣。

完整階梯與矩陣見 角色與權限。

Last updated on
總覽建立環境並建置