從模板實例化一條工作流程

在 Braidrun 裡，"從模板實例化" 是最主流的工作流生成方式：90% 以上的用戶第一條工作流都不是從白板寫的，而是從模板克隆一條，再按自己的業務做調整。這一篇把這個流程拆到每一個按鈕。

完整流程概覽

1. 瀏覽模板庫，按分類 / 標籤 / 搜索挑一個
2. 讀模板詳情卡片，確認前提條件與預估成本
3. 點"使用此模板"，克隆到你的工作區
4. 在編輯器裡按變量說明改業務參數
5. 補齊憑據中心裡的 key
6. 先 dry-run 校驗結構、再真跑一次
7. 按需綁定調度 / Webhook 觸發器

第 1 步 · 瀏覽模板庫

1.1 打開入口

左側主導航「模板庫」。頁面結構：

• 頂部篩選欄 —— 10 個行業大類 + 標籤 + 關鍵詞搜索
• 模板卡片網格 —— 顯示名稱、描述、標籤、預估時長、複雜度
• 右上角"我的收藏" —— 長期用的模板可以收藏，下次直接進入

1.2 常見的選擇策略

• 需求很具體 — 直接搜索關鍵詞。比如你要做"TestFlight 證書到期提醒"，搜 certificate expiry 就能立刻鎖定。
• 需求偏寬泛 — 按行業先收斂。挑一個你最熟悉的行業大類，翻兩三頁大致瞭解我們有哪些類型的流程。
• 想"看看行業裡別人怎麼做" — 按"複雜度"倒排，挑最複雜的幾個看 —— 它們通常代表了端到端的成熟實踐。

第 2 步 · 閱讀模板詳情

點某個模板卡片進入詳情頁，重點看四塊：

2.1 「描述」段

兩三段文字，告訴你：它解決什麼問題、最適合什麼場景、不適合什麼場景、使用前需要哪些準備。

2.2 「所需憑據」列表

一清二楚列出跑這條工作流需要哪些憑據，例如：

• openai_api_key — OpenAI API Key（必需）
• slack_webhook_url — Slack Incoming Webhook URL（用於投遞，可選）
• apple_appstoreconnect — App Store Connect JWT（僅 Apple 相關模板需要）

"必需"的憑據缺一個，工作流跑到對應 step 時會失敗。"可選"的缺失時，相關 step 會被 condition 跳過。

2.3 「預估耗時與成本」

一次完整執行：

• 耗時 —— 2 分鐘 / 15 分鐘 / 1 小時，取決於工作流複雜度與外部依賴響應速度
• Token 用量 —— 平均 xxx input / xxx output
• $ 預估 —— 按平臺默認 preset 與 OpenAI 單價算的大概值

2.4 「示例輸入與示例輸出」

一份具體的輸入樣例（你可以直接照抄跑一次）+ 對應產生的輸出樣例（讓你心裡有底 "大概能得到什麼"）。

第 3 步 · 克隆到工作區

1. 右上角點 「使用此模板」。
2. 彈窗裡給你的副本起個名字（默認是模板名 + 時間戳，你可以改成更有業務意義的）。
3. 選擇目標團隊（如果你在多個團隊裡）。這決定了這條工作流能被誰看到 / 編輯。
4. 點確認。平臺為你生成一份 獨立副本，你的修改不會回傳範本，範本後續更新也不會自動改動你的副本。

第 4 步 · 定製業務參數

4.1 variables 段是你唯一需要認真看的地方

編輯器打開後先翻 YAML 到頂部的 variables 段。所有"這條工作流要按你業務情況調的東西"都在這裡，已經註釋好了：

variables:
  target_date:
    type: string
    default: yesterday    # ← 改成你要跑哪一天的数据
    description: |
      支持 yesterday / last_7_days / last_30_days /
      或具体日期 2026-04-17

  top_n:
    type: number
    default: 10           # ← 要拉多少条新闻
    description: 抓取的新闻数量上限

  target_channel:
    type: string
    default: "#my_daily_digest"  # ← 改成你的 Slack 频道名或保留默认 webhook 目标
    description: Slack 目标频道或 Incoming Webhook 默认目标

4.2 按註釋改默認值

默認值只是"示例"，要換成你業務裡真實的值。改 variables 不會破壞結構，放心改。

4.3 不動 steps 是好習慣

第一次跑模板不建議動 steps 段的結構 —— 先用默認流程跑一次，看數據流，再決定是否改。

第 5 步 · 補齊憑據中心

1. 打開憑據中心。
2. 把模板詳情頁列出的每個"必需"憑據都創建一條對應的憑據，name 必須和 YAML 裡引用的完全一致。
3. "可選"憑據可以暫時不建 —— 相關 step 會被跳過。

第 6 步 · 先 dry-run，再真跑

6.1 dry-run 的意義

dry-run 零成本地走完一遍 DAG，跳過所有 LLM 與副作用。它幫你在花錢之前確認：

• variables 是不是都填對了
• 變量在 step 之間流得通
• condition / classifier 的分支選對了
• 依賴的憑據名能解析到

6.2 真跑

dry-run 通過後，取消勾選 dry-run 再次點"執行"。這次會真調 LLM、真發副作用。頁面右側實時事件流讓你看每一步的進展。

6.3 跑完後看什麼

• 「查看執行詳情」—— 甘特圖 + 每步輸入 / 輸出
• 「產物欄」—— 生成的 Markdown / Excel / 圖像可直接下載
• 「tokens / cost」—— 這一次總共花了多少

第 7 步 · 按需綁觸發器

手動跑通後，工作流就具備了"上線"條件。常見的三種觸發方式：

• 定時調度 — 每天 / 每週 / 每月一次，或按 interval 重複
• Webhook 觸發 — 外部系統 POST 過來觸發，用 API Key 認證（也相容 HMAC 簽章）
• API 觸發 —— 你的內部系統用 API Key 呼叫 REST API 啟動執行

範本升級：跟進範本的新版本

複製出來的副本不會被範本更新自動改動。當原範本發了新版本、你又想跟進時，用「從範本升級」流程：先看一份預覽，確認後一鍵升級。

入口在哪

兩個地方都能進：編輯器工具列選單裡的「從範本升級」，或 workflow 設定面板變數區上方的「檢查升級」提示。開啟的對話方塊會顯示目前版本與目標版本。

升級前先看預覽

預覽把變數差異分成三類，逐個列出：

• 保留 — 你已經改過、新範本裡仍存在的變數，升級後保留你的值
• 新增 — 新範本新增的變數，填入範本預設值，升級後按需再調整
• 刪除 — 新範本裡已不存在的變數，升級後會被捨棄 —— 確認前逐條檢查這個列表

升級時發生什麼

• 先自動儲存目前 workflow 為一個版本快照，後悔了可以在「版本」選單裡回復
• 步驟 DAG、Agent prompt、程式碼、逾時等結構性設定依新範本覆寫
• 你自己選的模型會保留：同名 Agent 的模型選擇、對應的模型憑證參照不被新範本覆寫
• workflow 名稱、標籤、並行這類屬於你的設定不動

舊 workflow 沒記錄來源範本？

早期複製的 workflow 可能沒登記來源，此時編輯器選單裡的同一項會顯示為「關聯範本…」。補登它來自哪個範本（可以順便標記目前對應哪個版本），之後就能正常走升級流程。

進階：讓 AI 助手按你的描述改

克隆之後，如果業務需求和模板不完全一致，可以讓 AI 助手幫你修：

1. 右下角 FAB 打開 AI 助手抽屜
2. 描述你的需求 —— 例如 "把 step.deliver 從 Telegram 換成飛書"
3. 助手會給出一份 diff 預覽，你 accept 或 reject
4. 滿意後點"應用"—— 10 級撤銷棧保護你隨時回滾

何時該改用 AI 助手或手寫？

下一步

• 分類詳解與典型模板 — 每個行業大類精選代表，告訴你每一類能做什麼
• 視覺化編輯器 — 克隆出來之後到底點哪些按鈕
• AI 助理 — 用自然語言改 / 生成工作流