最佳實踐

這一篇是"踩過的坑"彙總。寫過 10 條以上工作流就能感同身受；沒寫過就先存著，碰到了翻回來看。

一、如何寫一條"能上生產"的工作流

從範本起步

哪怕你的場景看起來很獨特，240+ 個範本裡總有一條「拆一半、改一半」能用的。從範本起步省掉大量從零搭骨架的時間。

從模板實例化 是大多數使用者的第一步。

先做"最蠢版本"，再做"聰明版本"

新工作流第一版：

• 變量寫死默認值
• condition 都不加，全部都跑
• 用平臺統一的 LLM Key，不折騰 BYOK
• 不掛 cron，手動跑

跑通後再逐個"精細化"：變量化、分支、BYOK、cron、審批。這樣每一步出問題都好定位。

每次改都先 dry-run

改了東西 → dry-run 看 DAG 結構和變量流 → 再真跑。dry-run 零成本，不要跳。

二、步驟類型的選擇

優先級從上到下，遇到選擇困難挑排得靠上的那個：

1. code — 能用確定性邏輯就別用 LLM。快、便宜、可測試。
2. classifier — 需要 LLM 但輸出是一個類別時用；不要用 single 讓 Agent 自由發揮。
3. single — 大部分"摘要 / 抽取 / 改寫"任務。
4. sub_workflow — 同一段逻辑在多个 workflow 里复用，或单 workflow > 15 个 step。
5. group_chat — 任務需要多個視角互相討論時用；一個 Agent 能獨立完成的用 single。
6. agent_based — 任務有很強分支特徵，每個分支都需要 LLM 判斷派到哪裡。
7. state_machine — 有明確的狀態轉移，譬如多輪交互 / 工單生命週期。
8. manual_approval — 影響線上 / 花錢 / 對外的步驟前都要加。

三、變量與數據流

大字段先 extract 再傳

上游 step 返回 100KB JSON 時，不要直接塞給下游 task。用 extract 把真正需要的字段挑出來：

- id: fetch_data
  type: code
  code: |
    // 返回一个很大的 JSON
    return await heavyFetch();
  extract:
    user_count: $.data.stats.total_users
    top_3: $.data.items[:3].name

用 | default(...) 兜底

引用可能為空的變量（被 condition 跳過的 step 的輸出）時，加 default：

- id: summarize
  type: single
  agent: writer
  condition: "length({{steps.classify.categories}} | default([])) > 0"
  task: "{{steps.classify.output | default('无内容可摘要')}}"

condition 分支 vs on_failure

不要混用：

• condition 控制"正常情況下走不走這一步"—— 跳過 = SKIPPED（不算失敗）
• on_failure 是"出錯後的補償動作"—— 發通知 / 降級到備用數據源

把 on_failure 當 try-catch 用，但不要把它當正常分支。業務正常邏輯用 condition。

四、Agent 與模型

tool_set 越小越好

默認 preset 給的工具多數 step 用不上。裁到 2–3 個 —— 成功率上升、token 消耗下降。

模型按任務挑

• 推理 / 代碼審閱 → Claude Opus 4 / GPT-5 / DeepSeek-Reasoning
• 短摘要 / 分類 → Haiku / GPT-4.1-mini / DeepSeek-V3.5
• 中文寫作 → Claude Sonnet / Kimi K2
• 長上下文（32K+）→ Kimi K2 / Claude 200K

temperature 按任務挑

• 0.0 – 0.3 —— 推理 / 分類 / 抽取（要穩定）
• 0.4 – 0.7 —— 摘要 / 改寫（平衡）
• 0.7 – 0.9 —— 創意寫作 / 頭腦風暴（要發散）

五、idempotent 與自動續跑

純數據管道的 step 都加 idempotent: true —— 服務重啟後可續跑。含副作用（發消息 / 下單）的 step 不要加。

詳見 自動續跑。

六、拆分與模塊化

1. 一個 workflow 超過 15 個 step —— 該拆。
2. 同一段 3–5 步邏輯在另一個 workflow 裡也要用 —— 該做成模塊（sub_workflow）。
3. 模塊發佈後，刪 input / 改類型都是破壞兼容，要升 MAJOR 版本。

七、成本控制

• 先 dry-run — 前面說過，白跑一次真執行浪費的錢最多，這條最省。
• 分類用便宜模型 — classifier 十有八九不需要 Opus / GPT-5。
• 併發有上限 — 批處理用 sub_workflow + max_parallel 控制併發，別讓 TPM 打爆。
• 緩存 RAG index — 同一語料每次都 re-embedding 很貴，把結果持久化到產物。
• 綁預算告警 — 在通知设置里加"单 execution cost > $1"或"当日累计 > $50"告警。

八、安全與合規

• 永遠不把 key 寫進 YAML —— 用憑據中心。
• code step 的 credentials: 列表要顯式 —— 不給 step 它用不上的憑據。
• 付款 / 對外通訊 / 寫客戶數據庫前都加 manual_approval。
• 涉及用戶數據的 workflow 考慮開啟 審批人列表，讓合規團隊進 approvers。
• Webhook 用的 API Key（以及相容模式的 signing secret）定期輪換。

九、測試與上線流程

1. 新 workflow 先在測試工作流頁 dry-run。
2. code step 的腳本單獨在本地 node / python 裡跑一次看輸出。
3. Agent 行為用斷點調試器 + 小樣本跑 10 次看穩定性。
4. 調度上線前用"立即觸發一次"驗證時區 / 參數預設。

十、協作與版本

• 重要改動前先"導出 YAML"本地備份 —— 哪怕版本歷史兜底，一份本地副本更踏實。
• 多人編輯：一個人拿鎖、改完保存、釋放鎖，再下一個人拿。並行改請拆成子工作流。
• 大版本變更前和團隊同步 —— 別人可能正在依賴你的模塊。

十一、監控與告警

• 關鍵 workflow 的 execution.failed 綁 Slack / 飛書通知 —— 失敗了第一時間知道。
• 定期查看數據看板 —— 哪條 workflow 最貴 / 最慢 / 最常失敗？優化從它開始。
• 每月看一次審計日誌 —— 權限有沒有異常 / 憑據被誰用過。

十二、我做完一條工作流的 checklist

1. dry-run 通過
2. 真跑一次成功
3. 每個 step 的 idempotent / retry 策略已確認
4. 對外副作用前有 manual_approval 或 condition 明確控制
5. 所有憑據都從憑據中心解析，YAML 裡沒有 plaintext key
6. cron / webhook 綁好並確認"下次觸發時間"
7. 失敗通知配好（至少把 execution.failed 推到 Slack）
8. YAML 導出一份到 git 做異地備份

推薦延伸閱讀

• YAML 語法參考 — 模糊字段拿捏不準時查
• 斷點調試 — 複雜流程出問題的定位神器
• 問題排查 — 具體症狀對照