文件建構工作流程YAML 語法

YAML 語法參考

變數引用、條件表達式、agent preset、code_preamble —— Braidrun YAML 的完整權威參考。

Braidrun 的 Web DTO 與可執行 YAML 字節級 round-trip，但使用的字段命名風格不同： camelCase vs snake_case。本頁把你需要知道的映射、變量、條件、preset 規則集中講清楚。

權威解析器

驗證與 YAML round-trip 都走平台解析接口 /api/workflows/parse ，避免瀏覽器端另寫一套規則。

命名：camelCase ↔ snake_case

Web JSON 使用 camelCase；執行 YAML 使用 snake_case：

網路DTO	YAML
`groupChat`	`group_chat`
`agentBased`	`agent_based`
`stateMachine`	`state_machine`
`repeatUntil`	`repeat_until`
`iterateOver`	`iterate_over`
`manualApproval`	`manual_approval`
`onSuccess` / `onFailure`	`on_success` / `on_failure`

Agent preset 與 overrides

推薦用 preset 聲明 Agent，需要時用 overrides 覆蓋任意字段：

yaml

agents:
  planner:
    preset: universal
  coder:
    preset: coder
    overrides:
      max_iterations: 2000

變量引用

工作流變量： {{var:name}}
步驟輸出： {{steps.step_name.output}}

yaml

variables:
  topic: workflow

workflow:
  - step: plan
    agent: planner
    input: "Plan for {{var:topic}}"

  - step: implement
    agent: coder
    input: "Implement based on {{steps.plan.output}}"
    depends_on: [plan]

條件表達式（condition）

基本形式是「左值運算子右值」，運算子兩側必須留空格。支援的運算子：

== / != — 字串精確比較，區分大小寫
> < >= <= — 數值比較；任一側不是數字時該條件按 false 處理
contains / contains_cs — 包含判斷，區分大小寫
contains_ci — 包含判斷，不區分大小寫

多個比較可以在頂層用 &&（且）與 ||（或）組合； && 的優先度更高，先結合。範例：

yaml

condition: route == coding
condition: score >= 8
condition: status == done && score >= 8
# && binds tighter — reads as (a == 1 && b != done) || retry == true
condition: a == 1 && b != done || retry == true

不要寫：

yaml

condition: "{{var:route}} == coding"      # don't — write the variable name directly
condition: (a == 1 || b == 2) && c == 3   # don't — parentheses are not supported

不支援括號分組——需要更複雜的分組邏輯時，用 classifier 產生路由變數或拆成多步。變數名直接寫出來即可，不要在 condition 裡使用範本變數語法。無法解析的條件按 false 處理，該步驟會被跳過。

code_preamble — 共享代碼前置

當多個 code 步驟需要共享 import 或工具函式時，使用頂層的 code_preamble。按程式語言分組，執行時自動拼接到相同語言的 code 步驟指令碼開頭：

yaml

code_preamble:
  python:
    ref: ./lib/shared_utils.py

或者使用內聯形式：

yaml

code_preamble:
  python:
    inline: |
      import json, os
      def log(msg):
          print(f"[workflow] {msg}")

Transition Action（on_success / on_failure）

使用動作對象形式，而不是字符串數組：

yaml

on_success:
  - next: publish

on_failure:
  - notify: slack
    message: implementation failed
    stop: true

導出為 Web DTO 時對應：

json

{
  "onSuccess": [{"next": "publish"}],
  "onFailure": [
    {
      "notify": "slack",
      "message": "implementation failed",
      "stop": true
    }
  ]
}

verify clause 清單

變量引用使用 {{var:name}}
導出的 YAML 仍能通過 /api/workflows/parse 回讀
condition 沒有寫範本變數，&& / || 組合沒有用括號
manualApproval / onFailure / repeatUntil 等 DTO 字段導出後已轉成 snake_case