建立管線範本

管線範本是在工作區設定中撰寫的。工作區側邊欄中的 管線 項目是_執行佇列_， 而不是範本清單 — 它沒有「建立範本」這個操作。

關於每種步驟種類、主體鍵與設定欄位代表什麼，請參閱 管線步驟參考。

建立範本

1. 前往 設定 → 工作區 → 管線範本 （/workspaces/<workspace-id>/settings/pipelines）。
2. 按下 新增範本。

不會出現 id 對話框。編輯器會立刻以一個名為 新增管線 的預先植入骨架開啟， 並自動分配 id（先是 pipeline_1，接著是 pipeline_2，…）。點擊頁首的標題 即可重新命名。

畫布並非空白：裡面有一個 Trigger 入口節點、一個標示為 Step 的提示代理 節點，以及一個結束執行的終端哨兵。哨兵不會被繪製出來。編輯器會把這個隱藏的 終端重新接到每個可到達的匯點，因此你在 Step 之後接上的工作仍會執行。

新增節點

節點庫 側邊欄常駐在編輯器左側。用 搜尋節點 方塊篩選它，並把項目拖曳到 畫布上 — 節點會落在你放開的位置，且沒有傳入連線。

節點庫項目	步驟種類	作用
Bash script	listen	執行帶 {{state}} 替代的 shell 指令碼；不派送代理
Open conversation	listen	開啟這次執行唯一可見的空間及其檢出；代理節點會加入這個房間
Clone PR branch	listen	透過 gh pr view 找出 PR 的 head 分支，並將它複製到執行目錄
Post PR comment	listen	把彙整後的發現張貼到該 PR，成為一則 GitHub 審查留言
Reviewer (prompt)	listen	派送專門的審查代理；暫停直到該代理提交結果
Consolidate (join)	join	等待多個上游分支，然後請代理彙整它們的輸出
Custom prompt	listen	經由 promptAgent 主體路由的通用提示驅動節點
Post to space	listen	傳送一則訊息到訊息空間
Condition / switch (router)	router	依狀態值讓流程分支
If file exists (router)	router	當複本下存在某個路徑時路由到 "true"，否則路由到 "false"
Any file exists (OR router)	router	當列出的任一路徑存在時路由到 "true"
All conditions (AND router)	router	僅當列出的所有路徑都存在時路由到 "true"
Team dispatch	listen	派送整個團隊並暫停，直到它完成
Approval gate	listen	暫停以等待核准決定
For each (map)	forEach	為每個項目渲染一次提示，然後把這些提示串接後對代理派送一次
Call sub-pipeline	listen	以巢狀步驟執行另一個範本
Clean up worktrees	listen	移除過期隔離的工作樹；為確定性操作，不派送代理

節點庫把這些分組在 流程與邏輯、PR 審查、代理、訊息 與 程式碼 之下。沒有 Demo 群組。

連接節點

每個工作節點的右緣都有一個圓形的 輸出埠。從該埠拖曳到另一個節點即可連接 它們。起始觸發器也一樣：每一個都有自己的埠，因此從 排程 拉出的線不會同時從 手動執行 離開。在節點之後按下 新增步驟（+），即可在其後插入一個類型。 將游標停在既有邊的中點並按下 × 即可中斷連線。

連線也可以從_接收_它們的節點編輯：

1. 選取下游節點。它的設定面板會從右側開啟。
2. 捲動到 Triggers from，並為這個節點應監聽的每個上游節點點選其標籤。 點選已選取的標籤會移除該連線。
3. 如果某個上游節點是路由器，標籤下方會出現一個 路由鍵 區塊，每條路由器邊 各有一個 來自 <node> 的路由鍵 欄位。輸入該邊觸發時所用的鍵 — 檔案存在類路由器為 true 或 false，切換則為案例名稱。

每個觸發節點都是一個進入點。一個節點可以監聽多個上游（扇入），並饋送多個下游 （扇出），而圖必須保持無環 — 編輯器中沒有任何機制會阻止你接出一個環，所以要 自行檢查。

終端哨兵會從畫布中被濾除，因此無法選取。每當圖變更時，編輯器都會將它重新接到 每個可到達的匯點，因此你在預先植入的 Step 之後接上的工作仍會執行。空圖 （觸發器沒有任何後續工作節點）會列出觸發器本身，讓執行立即完成。

設定節點

選取節點即可開啟其設定面板。會出現哪些欄位取決於該節點的主體。

每個節點都有 標籤、輸入鍵（執行時讀取、以逗號分隔的狀態鍵），並在 進階 之下有 縮減器、逾時（毫秒）、重試次數、 此步驟失敗時仍繼續 與 輸出結構描述。listen 與 join 節點也可以在兩者 之間切換它們的 種類。

開啟對話

新增一個 要複製的儲存庫 選擇器（要檢出哪些工作區儲存庫；留空表示都不 檢出）、一個 空間名稱，以及一個 在其中開啟對話 核取方塊。當該核取方塊 開啟時，對話名稱 欄位會為房間開啟時所在的資料流命名。代理節點會加入這個 房間 — 它們不會自己開啟一個。

提示代理

新增 代理（要派送哪個代理）、提示範本（用 {{key}} 參照輸入或上游 輸出）與 輸出鍵。

逾時（毫秒） 的單位是_毫秒_，不是秒 — 900000 是 15 分鐘。輸入 900 會讓該步驟只有 0.9 秒。

提示代理節點以哪種對話模式執行，在代理節點上並沒有對應的編輯器欄位。它是由 建立該房間的 Open conversation 節點上的 extras['mode']（chat、plan 或 review）所決定（預設為 review）。在代理步驟上設定它會被忽略。這個鍵採 完全相符：任何其他拼法都會被靜默忽略。

Bash 指令碼

新增 Bash 指令碼。沒有工作目錄或環境欄位，因為兩者都無法設定：

• 一次執行中的每個 bash 步驟都共用 cwd <cc_root>/pipelines/<runId>/。
• GITHUB_TOKEN 會從憑證儲存區注入，因此 gh 與 git clone https://x-access-token:$GITHUB_TOKEN@… 不需任何設定即可運作。
• 指令碼是以字面上的可執行檔 bash 啟動，因此伺服器主機的 PATH 中必須有 bash。這是 Windows 上的考量。

路由器

路由器會評估一個條件並傳回路由鍵；引擎只會觸發路由鍵相符的那條下游邊，並把 其他分支標示為已跳過。

選取路由器會把 輸出鍵 欄位取代為條件編輯器。從它的四種模式中挑選一種：

• 檔案存在—任一 — 當列出的任一路徑存在時路由到 "true"。
• 檔案存在—全部 — 僅當列出的每個路徑都存在時路由到 "true"。
• 比較 — 把狀態值與字面值比較。
• 切換 — 依狀態鍵的值路由，並帶有一個預設案例。

接著在輸出的邊上設定相符的路由鍵（參見 連接節點）。

布林 and / or / not 群組由主體支援，但無法從這個表單撰寫 — 它們需要在 extras.predicate 下手寫的述詞樹。完整的述詞與運算子詞彙請見 管線步驟參考。

匯合

本身沒有設定：它會等待所有上游步驟。

核准閘門

閘門會把核准者代理派送到一個帶有閘門提示的隱藏對話中，然後暫停。核准者會在該 對話中徵求你的決定，並透過 submit_output 以 { "decision": "approved" | "rejected", "reason": "..." } 提交。該決定會寫入 輸出鍵（預設 approval_decision）之下，因此下游的切換路由器可以依它分支。

把 代理 設為核准者，並把 提示範本 設為閘門問題。閘門會透過 submit_output 以 { "decision": "approved" | "rejected", "reason": "..." } 的形式得出結果。Reviewer (prompt) 節點也以相同方式提交。

團隊分派

新增 團隊 ID 與 分派模式。選擇器只提供兩種模式：

• allParallel — 每位成員一個任務，暫停直到全部完成。
• manager — 派送隊長，由隊長負責分派。

任何其他已儲存的值都會以 allParallel 的方式運作。把 縮減器 設為 append， 即可將每位成員的結果收集成輸出鍵之下的一個清單。

For each 與 Call sub-pipeline

For each 預設會對 items 狀態鍵進行映射（節點上的 extras.iterableKey / extras.itemKey）。它會為每個項目渲染一次提示（預設為 {{item}}），並把這些 提示串接後對代理派送一次。空集合會立即以空清單完成。它並不是為每個項目各做 一次並行派送。

Call sub-pipeline 會暫停，直到子執行達到終端狀態，然後把子執行的最終狀態 合併到輸出鍵（預設 subflow_result）之下。用 extras.templateId 將它指向 子範本。範本不能呼叫自己；失敗或被取消的子執行會讓父步驟失敗，接著便交由該步驟 的重試與失敗後繼續原則處理。

宣告輸入並允許手動執行

兩者都位於編輯器頁首的 手動執行 之後。

1. 按下 手動執行。
2. 開啟 允許手動執行。這個開關會立即保存 — 它會建立（或刪除）manual 觸發器資料列，讓範本出現在執行選取器中。
3. 如果想要上限，請設定 最大並行執行數（留空表示不限）。多出來的啟動會以 queued 狀態等待，直到有名額釋出。
4. 對每次手動執行應收集的每個表單欄位按下 新增輸入：

欄位	說明
鍵	值儲存所在的狀態鍵；以 {{key}} 參照它
標籤	顯示標籤（預設為該鍵）
類型	文字、多行文字、數字、開關、下拉選單、儲存庫
選項	以逗號分隔的選項，僅供下拉選單使用
預設值	預先填入的值
預留位置	空白欄位內的提示文字
說明文字	欄位下方的輔助文字
必填	執行表單是否會在值為空時阻擋提交

儲存庫 輸入會渲染一個用於挑選工作區儲存庫的選擇器，並把 repo_id、 repo_local_path、repo_full_name，以及 — 當儲存庫有 GitHub 遠端時 — repo_owner 與 repo_name 填入執行承載資料中。

5. 在對話框中按下 儲存。輸入的編輯會併入草稿；在你儲存範本時才會保存。

儲存並啟用

1. 在編輯器頁首按下 儲存。在你儲存之前，頁首會顯示「有未儲存的變更」。
2. 回到 設定 → 工作區 → 管線範本，確認範本那一列的開關已開啟。引擎會拒絕 啟動已停用的範本，而停用的範本也永遠不會出現在執行選取器中。
3. 若要讓它自動啟動，請從節點庫把觸發器拖曳到畫布上 — 參見 設定管線觸發器。

相關指南

• 手動執行管線
• 設定管線觸發器
• 監控管線執行
• 管線步驟參考

相關概念

• 管線