Skip to Content
操作流程自訂表格 trigger

從自訂表格 trigger 提交執行

自訂表格的列 trigger 可以在列被建立或更新時排入一次 Sandbox run。這不是 /private/module/sandbox 端點。Action 活在 custom-tables 的 trigger 設定裡（src/crud/custom_table_triggers.py，型別 submit_sandbox_job）。產生的 run 是普通租戶 run（submission_source="custom_table_trigger"），前端用既有方式輪詢即可。

Trigger 的其餘機制（when 條件、receipt、重試）留在 custom-tables 手冊。本頁只寫 Sandbox 契約。

Action 形狀

{
  "type": "submit_sandbox_job",
  "chatroom_id": "<room uuid>",
  "task_version_id": "<published version id>",
  "timeout_seconds": 1800,
  "input": {
    "order_id": "$row.col_…",
    "note": "static"
  }
}
欄位必填說明
type是字面 submit_sandbox_job。
task_version_id是同公司、state=published、content_state=active。
chatroom_id見說明預設用表格的 chatroom。部門／公司範圍表格沒有隱含房間，所以必填。
timeout_seconds否整數 1..604680。預設 = 版本的 timeout_seconds。
input是JSON 物件。可用 $row.col_<hex>（改名穩定的內部鍵）插值。模板本身另有更嚴上限：根物件以下巢狀最多 8 層、每個字串葉節點最多 2000 字元，超過在存檔時就被拒。通過後才以 canonical JSON 規則（≤1 MiB、深度 ≤64）驗證，觸發時再重驗一次。

只有 created、updated 事件能帶這個 action。

存檔時檢查（設定者）

編輯者必須是活著的使用者，且對所選任務在所選房間 can_execute_manually。列真正觸發時，會再用造成寫入的行為主體重跑同一套檢查。Action 裡的 id 只是設定，不是授權。

存檔會拒絕：

  • 任務版本找不到／不是 published+active／公司不對。
  • requires_confirmation=true — 背景 trigger 沒有第二則 HumanMessage 可以 commit。
  • 版本宣告了表格 writeback 的 output_policy（custom_table_writeback）— trigger 路徑永不鑄表格憑證。改用擁有部門房間裡、部門擁有任務的手動 JWT 提交（任務受眾）。Command 輸出的版本（custom_table_command）則可接受，但要符合下面Command 輸出版本的額外規則。
  • 設定者不能在該房執行該任務。
  • 部門／公司表格缺 chatroom_id。
  • input 不是物件，或 canonical JSON／$row 正規化失敗。

觸發時授權

Worker 會解析恰好一個造成寫入的 principal（寫入該列的 user 或 client）。然後：

  • 目的地 chatroom_id 必須仍在該公司且活著。
  • 造成者必須仍活著，且仍是來源行動房間的成員。
  • 造成者必須能在目的地房間 can_execute_manually 該任務（Command 輸出的版本改為檢查 trigger 的撰寫者——見下）。
  • 來源權限語境（當初讓這列可見的 ACL）仍須允許付費工作；principal 變了或來源房死了就拒絕。
  • 造成者若是 client（社群媒體與 Agent 通道皆然），目的地 chatroom_id 必須就是該 client 自己的聊天室 — worker 以 SocialMediaClient.chatroom_id == 目的地房間 查詢，查不到就整個觸發被拒。所以部門／公司範圍表格若把目的地指到別的房間，由 client 造成的寫入永遠不會產生 Sandbox run。
  • Agent 通道的 client 不會被重對應成社群 Sandbox principal（那會記錯預算）。需要活著的 Agent delegate user（前一條的目的地房間限制通過後才做這個重對應）。

被拒的觸發記在 trigger run receipt 上；不會建立 Sandbox run。

Command 輸出版本

output_policy.kind 為 custom_table_command 的版本（任務輸出交給自訂表格 Command）是 trigger 唯一可以對準的 output_policy 種類。這種版本的規則是：

  • **存檔時。**Action 的目的地 chatroom_id 必須等於政策的 chatroom_id（否則是 actions 上的設定錯誤），而且設定者與版本的撰寫者都要通過 Command 檢查（失敗時保留各自的 code，例如 403 output_policy_author_denied）。
  • **觸發時。**run 由 trigger 的撰寫者提交，不是造成寫入的 principal。Worker 會重新對 Command 檢查政策的房間、撰寫者與版本的撰寫者，而且撰寫者必須能在目的地房間 can_execute_manually 該任務；失敗就是被拒的觸發（不會有 Sandbox run）。造成者不再需要能執行該任務，但仍必須讀得到來源列與被引用的欄位，同上。
  • **輸入。**任務的輸入檔就是渲染後的 action.input 物件——不會包在下面那個 source／trigger／record／row 信封裡——而 receipt 的 input_digest 就是這個物件的 digest。

前端該呈現什麼

  1. Trigger 編輯器：從編輯者能執行的房間裡挑已發布任務版本。隱藏／拒絕 requires_confirmation 版本。
  2. 部門／公司表格必須明確填目的地 chatroom_id。
  3. 列寫入後，看 custom-tables 的 trigger-run receipt。成功長這樣：
{
  "type": "submit_sandbox_job",
  "ok": true,
  "run_id": "...",
  "trigger_run_id": "...",
  "task_version_id": "...",
  "input_digest": "sha256:…",
  "run_status": "queued",
  "submission_source": "custom_table_trigger"
}

Worker 用的冪等鍵：ct-trigger:{trigger_run_id}:{action_id}。保留回顯的 action id，重試才能接同一張 receipt。

sandbox 看到的耐久 run input 不是整列原文。除了 Command 輸出的版本（見上），它是這個信封（只有你在 action.input 下列出的葉子；沒有整列、沒有 diff）：

{
  "source": "custom_table_trigger",
  "trigger": { "run_id": "...", "trigger_id": "...", "action_id": "...", "event": "created|updated", "fired_at": "..." },
  "record": { "table_id": "...", "record_id": "...", "record_version": 1 },
  "row": { "order_id": "…" }
}

設定走 custom-tables 的 trigger 路由（GET/PUT /private/module/custom_tables/{chatroom|department|company}/.../triggers），再 GET .../trigger-runs 與 POST .../trigger-runs/{id}/retry。那些路徑不在 /private/module/sandbox 底下。

  1. 在目的地聊天室用一般 執行 API 觀察：
GET /chatrooms/{destination_chatroom_id}/runs/{run_id}

SandboxRunDetailResponse.submission_source 是 custom_table_trigger。可見性仍是 A-010：你看得到它，是因為你是造成者，或你管理目的地房間。Command 輸出的版本，run 的 principal 是 trigger 的撰寫者，所以不是該撰寫者的造成者，只有以 manager 身分（目的地房間、其部門或公司的 manager）才看得到。

  1. 輪詢 terminal_at。通知（run_terminal）仍不能取代 GET。

這不是什麼

  • 不是 agent 確認。不要等 proposal_receipt。
  • 不是繞過分享的後門。can_execute_manually 仍要 live 適用 share（或歷史上的擁有方聊天室任務）。這道閘不要求啟用／binding — 那個開關是給 Agent 選單的。目的地房間不必已啟用該任務。
  • 不是 REST 提交。不要替 trigger 去 POST /runs；worker 會提交。

相關

Last updated on
Agent 確認流程任務輸出交給 Command