文档构建工作流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：

Web 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