跳到內容

工單與委派

工單是 Control Center 追蹤工作的單位。它刻意是個_笨拙_的產物:標題、內容、狀態、負責人,以及在樹狀結構中的位置。它並不是代理執行時所依據的東西——代理的工作存在於對話中,而一次執行的結構化輸出則保存在執行紀錄上。

指派只記錄擁有權,不會派送任何工作

標題為「指派只記錄擁有權,不會派送任何工作」的章節

這是關於工單最重要、務必弄對的一件事。

設定 assignedAgentId 會寫入一個欄位,並發布一個 TicketAssigned 領域事件。該事件是稽核與通知訊號,也是管線觸發器。將工單指派給代理不會啟動任何執行。 沒有任何工單派送器會監看 assignedAgentId 並喚醒該代理。

例外是團隊:當設定 assignedTeamId 時,TeamRoutingService 會以作業協定與名冊派送團隊領導者。

若你想讓特定代理處理某張工單,你得在對話中要求它、由管線步驟派送它,或由另一個代理對它委派工作。把工單指派給代理後枯等,是唯一永遠不會產生任何工作成果的做法。

工單可以純粹是本地資料,也可以由外部追蹤器支援,而它會在單一資料列上同時承載兩者。

鏡像——供應商、外部識別碼、URL、標題、描述、優先順序、標籤、原始與正規化狀態、時間戳記——在工單屬於遠端時是快取。此時遠端才是真實來源,而重新整理會整批改寫鏡像。

覆蓋層——指派、委派、空間連結、父項、專案、連結的 PR——只存在於 Control Center。追蹤器對它一無所知,重新整理也永遠不會觸及它。

正是這種切分讓同步得以安全進行:供應商拉取可以盡情破壞鏡像,卻永遠不會遺失疊加在上面的編排中繼資料。

狀態依序為 backlog → open → inProgress → inReview → done,其中 blocked 是側邊迴圈,failed / cancelled 則是另外兩個終止狀態。

轉換圖只在代理與自動化路徑上強制執行——也就是 MCP 工具與對帳器。在該路徑上,不合法的轉換會被記錄並忽略,因此狀況混亂的代理無法把工單倒退著帶出終止狀態。

UI 中每一項由使用者發起的變更都會傳入 force: true,完全繞過這張圖。人可以將工單移到選單所列出的任何狀態——包括重新開啟已進入終止狀態的工單。選單不提供 failed;代理會透過 fail_ticket 設定該狀態。這張圖是給自動化用的護欄,而不是規定工作該如何進行的規則。

TicketWorkflowService 透過單一關卡掌控每一項變更:它會載入該資料列、確認它屬於呼叫端的工作區,並以預期的 version 寫入,讓兩筆並行編輯無法悄悄互相覆寫。

完整的狀態表、轉換、欄位清單與關係種類,請參閱 工單生命週期。

每張工單都有一個 originKind。這個列舉有五個值——manual、pipelineStep、agentDelegation、externalSync、recovery——但目前只會寫入其中兩個:manual(createTicket 的預設值,包含委派建立的子工單)與 externalSync(同步引擎在供應商拉取時使用)。TicketWorkflowService.createTicket 不接受來源參數,因此 pipelineStep、agentDelegation 與 recovery 永遠不會寫入資料列。

委派是代理為另一個代理建立工作的地方,也是權限可能外洩之處,因此防護機制位於伺服器端的關卡,而不是放在提示指令中。

delegate_task 會經由 TicketWorkflowService.delegateGuarded 處理,它會從父項鏈結計算子工單的深度與根,接著執行全部四項 DelegationGuards 檢查:會超過深度上限 3 的一次跳躍、跳回鏈結中已存在的代理(循環偵測)、自主程度上限(被委派者在該空間中的有效層級不得超過委派者),以及預算額度(委派會計入委派者剩餘的硬性停止預算,且無法再增發)。正式環境的相依組態會提供這兩個解析器埠。省略 from_agent_id 時會略過自主程度與預算(無限制/無原則的預算也會通過)。拒絕會擲出 DelegationRefusedException,其訊息會原封不動地送達發起委派的代理——是明確大聲的拒絕,絕不是靜默無聲的略過。

delegate_ticket 是較舊的未受防護同類工具:它直接呼叫 createTicket,略過所有防護。請優先使用 delegate_task。

請勿將委派深度上限(在 delegate_task 鏈結上為 3)與內建執行框架的子代理巢狀上限(2)混為一談。它們是不同機制上的不同限制。

父項與子議題關係儲存在 tickets.parent_ticket_id,由 setParent / clearParent 管理。它們不是 ticket_links 資料列,因此任何讀取工單關係的程式都必須合併這兩個來源。

ticket_links 儲存彼此原本無關的工單之間的有向邊:

連結類型 含義
blocks 來源封鎖目標
relatesTo 兩張工單彼此相關(對稱)
duplicateOf 來源是目標的重複項

專案是工作區範圍內、為共同目標而將工單分組的方式。專案只存在於 Control Center,永遠不會同步到外部供應商。

TicketCollaborator 資料列是多個主體附加到同一張工單的方式,角色可為 assignee、collaborator 或 reviewer。人類與代理是對等的資料列——一個 principalId 加上一個 collaboratorType——沒有代表「使用者」的哨兵值,也沒有指向這兩張表中任一者的外鍵。

Control Center 的工單是主要來源。刪除工單只在本機生效,因此你刪除的供應商支援工單不會在追蹤器上被刪除,並可能在下次同步時再次出現。協作者與子工單會串聯刪除。

配接器憑證會從伺服器的憑證存放區解析(在設定中貼上的 Linear 金鑰或 GitHub token 會在下一次請求時被讀取;環境只會為這些存放區提供初始內容)。

沒有任何管線節點會建立、完成或取消工單——步驟面板中沒有這類步驟,引擎也不會呼叫 TicketWorkflowService。管線觸發器仍可在 TicketAssigned、TicketCompleted、TicketFailed 或 TicketCancelled 時觸發(這四個正是 EventPayloadMapper 實際對應的工單事件)。工單上沒有 pipelineRunId 欄位;與管線的耦合關係保存在代理執行紀錄中。