建立管線範本

管線範本是在工作區設定中編寫的。工作區側邊欄中的 管線 入口是_執行佇列_， 而不是範本清單——它沒有「新增範本」操作。

關於每種步驟種類、主體鍵與設定欄位的含義，請參閱 管線步驟參考。

建立範本

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	把彙整後的發現以 GitHub 審查留言的形式發佈到該 PR
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	移除過期的隔離 worktree；確定性操作，不派發代理

節點庫把它們歸入 流程與邏輯、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 步驟都共用 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. 若要讓它自動啟動，請從節點庫中把一個觸發器拖到畫布上——參見 設定管線觸發器。

相關指南

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

相關概念

• 管線