Skip to Content
概念任務受眾 — 分享與啟用

任務受眾 — 分享、啟用、選單

這一頁是 PR #975 之後目錄任務的單一契約。其他頁只連到這裡，不要各自重寫規則。若別頁與本頁衝突，以本頁為準（並當作手冊缺陷回報）。

目錄任務是 POST /tasks 建出的 SandboxTask。它不是聊天室擁有的物件。

建立：只有 department 或 company

owner_scope誰可以建owner_id
department該部門 manager，或 company manager部門 id
companycompany manager必須等於 company_id

POST /tasks 只接受 SandboxTaskCreateOwnerScope：department | company。送 chatroom 是 422（enum）。隱藏的 Quick Run 父任務仍由 POST .../quick-run 以聊天室擁有的內部物件鑄出——不要自己建那種。

歷史上的 owner_scope=chatroom 列仍可讀。不要把它當成建立路徑。

呼叫者不能擁有的 scope（錯部門、不是 company manager、owner_id ≠ company）是 403 owner_scope_forbidden。這仍是「用 404 藏存在性」的文件化例外。

任務父層的 agent_enabled 是舊旗標。Agent 能否看到任務，看的是房間的啟用開關，不是這個欄位。

分享 ≠ Agent 啟用

POST /tasks/{id}/shares 授的是使用權。它不會把任務放進 GET .../menu，也不會交給 Agent。

部門擁有的任務，可由擁有部門 manager（或 company manager）分享到：

  1. company + 公司 id — 整間公司，包含之後才建立的部門。
  2. department + 部門 id — 該部門（包含之後才在該部門建立的房間）。
  3. chatroom + 房間 id — 同公司任一存活房間，不必先分享整個部門。

擁有部門的管理員（或公司管理員）可直接分享到同公司任一存活聊天室，不必先建立公司／部門 grant。分享只提供可用性，接收方的房間管理員仍自行決定是否啟用；跨公司或已失效對象仍不可用。

公司擁有的任務可由 company manager 分享到同樣三種對象（都在公司內）。它們在每個房間對 writeback 都仍是 borrowed。

一筆分享也可以帶逐 slot 的secret 憑證來源政策（secret_slot_policies，只能在建立時設定——見 Secret 與授權）：借用方的房間是要自己綁 secret，還是借用 owner 的 binding。

撤銷會收回該 grant；若仍有等價的 live 授權，binding 可繼續用於後續提交。何時需要明確重新接受，請見下一節。

重疊分享與憑證同意（v5.10.0）

適用分享依 chatroom → department → company 順序解析。房間保留精確的任務版本 pin，以及管理員已接受的逐 slot 憑證來源政策。撤銷其中一個 grant 後，政策等價的其他 live grant 可以涵蓋後續提交；不同的 secret 來源政策不會被悄悄採用，需要改變同意內容時必須明確 Enable／Update。已提交的 run 仍固定在當時的 grant 與 generation；撤銷該 grant 仍會取消受影響的工作。

Enable、明確建立 binding 與 accept-version，會在每個必要 slot 都能解析時，替操作者實際管理的 consumer scope 記錄精確版本的借用 secret 同意，不會讀取 secret 值。缺少 slot，或 consumer scope 由他人管理時，仍須設定或由該 scope 管理員明確核准。GET、發布、分享、一般 run 都不會建立同意；補齊 secret 後可再呼叫冪等 Enable 完成同意。接受新版本會保留原先已接受的憑證來源政策。

啟用是房間開關

房間建立者／管理者（聊天室管理者階梯）：

Method + path效果
GET /chatrooms/{id}/granted-jobs到達此房間的每個 live grant，加上 enabled。受限 Sandbox 金鑰在 scope 過濾層回 405，detail 是 Access to GET /private/module/sandbox/chatrooms/{id}/granted-jobs is not allowed for your role（帶實際房間 id）——不是 403，也不是 invalid scope。
POST /chatrooms/{id}/granted-jobs/{task_id}/enablelive binding 已釘在你要的版本（或沒送 task_version_id）時冪等。送不同的 task_version_id 會重新釘版（後端 ≥ #1140：既有 binding 像 disable 一樣撤銷，再建新的）；POST /bindings/{binding_id}/accept-version 仍是原地升版。任務沒有分享給這個聊天室（或其部門／公司）時回 409 task_not_shared_to_room，訊息寫出該呼叫哪條分享 API。任務進入選單／Agent。
POST /chatrooms/{id}/granted-jobs/{task_id}/disable撤銷 live binding。share 還在。任務從選單消失，直到再次啟用。

POST /bindings 帶明確版本 id 做同一種採用，但不冪等：房間對該任務已有 live binding 時回 409 binding_already_live，而 granted-jobs/{task_id}/enable 會直接回傳現有 binding。產品路徑請用 granted-jobs。沒有根層 GET /bindings；請使用能力與管理查詢的 task／room scoped binding 清單。

分享不會自動啟用。Grant 一開始是 enabled=false。

兩份目錄、兩道提交閘

面誰看得到列出什麼提交閘
GET /chatrooms/{id}/granted-jobs只有房間管理者已授予的任務（不論是否啟用）不適用
GET /chatrooms/{id}/menu看得到該房間的人，包含受限 Sandbox 金鑰已授予且已啟用。每個呼叫者看到同一份清單產品 UI 應提交這些 task_version_id
POST /chatrooms/{id}/runs房間成員（或階梯上的管理者）+ live 適用 share不適用can_execute_manually：成員資格 + live share。不要求啟用。 已授予任務的任何 published+active 版本都可接受。
Agent 工具（sandbox_job_menu／sandbox_submit_job）房間 job 含 "sandbox" 才載入同一份 granted+enabled 目錄can_execute_via_agent：已授予 且 此房間對該版本有 live 適用 binding

不要寫「分享 = 選單」或「只有啟用才能跑」。手動 REST 可以跑尚未啟用、但已授予的任務。Agent 與房間選單不行。

Writeback 受眾（自訂表格）

output_policy 是有型別的，不是不透明 JSON，有兩種：表格 writeback（custom_table_writeback）與 Command 輸出（custom_table_command，v5.21.0）。只有部門擁有的任務可以發布其中任何一種。公司擁有的任務發布 → 409 output_policy_owner_scope_unsupported。

一次執行會鑄出 callback 憑證，當：

  • 任務是部門擁有，且
  • 作用中的房間在擁有部門裡（即使該房間是透過明確 share 進來的），且
  • 提交者是互動式 JWT 使用者（不是 API key、不是受限 Sandbox 金鑰、不是社交客戶端），且
  • 所需的權限都在：表格 writeback 是發布者（發布時）與提交者（鑄憑證時）都持有該表的不受限寫入權；Command 輸出是提交者與版本的撰寫者（最後寫入草稿的人）在每次提交時都通過 Command 檢查，而發布者在發布時通過它。

對表格 writeback，作用中房間在外來部門，或任務是公司擁有，這次執行是 borrowed（跳過鑄憑證，run 仍會排隊 — 這不是 403）。Trigger 開火會直接拒絕 custom_table_writeback 的版本。Agent 仍走兩回合確認。403 writeback_authority_denied 只有在真的嘗試鑄憑證、且 JWT 提交者對該表沒有足夠權限時才會出現。細節見 自訂表格 trigger。

Command 輸出使用同樣的擁有部門受眾，但從不跳過：borrowed 的 run、來自政策 chatroom_id 以外房間的 run、不是以 JWT 驗證的使用者的提交者（API key、受限 Sandbox 金鑰或社群媒體 client）、沒通過身分、grant 或範圍檢查的提交者／版本撰寫者，或不再是帶 effect_identity 的 restricted definition-authority 的 Command，一律以 403 output_policy_author_denied 拒絕，且什麼都不會排隊（Command 已被刪除或輸入不再相符，則改為 422）。Trigger 路徑與 Agent 接受這種版本（requires_confirmation=false 時，Agent 不需要確認回合）。契約見任務輸出交給自訂表格 Command。

Company manager 的執行歷史

Company manager 可以列出一個目錄任務在所有房間的每一次執行：

  • GET /tasks/{task_id}/runs — offset／limit（預設 10，最大 100），order=asc|desc
  • GET /tasks/{task_id}/runs/numOfData — 同一組篩選，{ num }

受限金鑰在認證層 403（沒有聊天室路徑／tasks deny）。非 manager JWT 403 Insufficient permissions.。這不是房間執行清單（GET /chatrooms/{id}/runs）。

產品 UI 該怎麼接

  1. 公司／部門管理者建立部門（或公司）任務 → 草稿版本 → 發布 → 分享。
  2. 房間管理者打開已授予任務，啟用要出現在 Agent／房間選單上的那些。
  3. 一般成員從選單執行。
  4. Company manager 在任務上看每任務歷史，不要逐房走訪。

相關

Last updated on
角色與權限營運與 Root