Variáveis e expressões

Todos os valores dinâmicos no Braidrun usam "referências variáveis".

{{var:name}}                     # workflow 级变量
{{steps.fetch.data.user.name}}   # 上游步骤的 JSON 输出
{{classifier.category}}          # 分类器路由结果
{{credentials.openai_api_key}}   # 凭据库里的密钥

Quatro fontes de variáveis

1. var: — Parâmetros de workflow

A seção de variáveis/parâmetros na parte superior do workflow ou a entrada da predefinição de agendamento/webhook.

variables:
  target_date:
    type: string
    default: "yesterday"
  top_n:
    type: number
    default: 10

steps:
  - id: fetch
    type: code
    code: |
      return { date: "{{var:target_date}}", top: {{var:top_n}} };

2. steps.id.* — Saída da etapa upstream

Há uma saída estruturada após a execução de cada etapa.

• steps.id.output — Texto simples ou valor de retorno bruto.
• steps.id.data — JSON estruturado após extração.
• steps.id.artifacts[0].url — Link do arquivo do produto.
• steps.id.tokens / cost / duration_ms — Estatísticas de execução.

steps:
  - id: fetch
    type: code
    extract:
      articles: $.items
      total: $.meta.total

  - id: summarize
    type: single
    agent: writer
    task: |
      我有 {{steps.fetch.data.total}} 条新闻，这是第一条：
      {{steps.fetch.data.articles[0].title}}

3. classifier.* — Resultados de roteamento do classificador

O resultado da etapa anterior do classificador é usado como referência de primeiro nível para condição/ramificação.

steps:
  - id: triage
    type: classifier
    agent: planner
    task: "{{var:user_message}}"
    categories: [billing, technical, other]

  - id: respond
    type: single
    condition: "{{classifier.category}} == 'billing'"
    agent: writer
    task: "客户关于账单的问题是：{{var:user_message}}"

Equivalente a steps.<classifier_step_id>.category - apenas mais curto e mais semântico.

4. credentials.* — Referência de credencial

Link de resolução: Namespace do usuário → Namespace da equipe → Namespace do sistema; Credenciais.

Expressão jsonpath

A sintaxe de caminho simples pode ser escrita entre chaves - basicamente compatível com um subconjunto de JSONPath:

• {{steps.fetch.data.articles[0].title}} — índice de matriz
• {{steps.fetch.data.articles[*].title}} — Todos os elementos do array (matriz de retorno)
• {{steps.fetch.data.articles[?(@.score>5)]}} — Filtragem condicional
• {{steps.fetch.data | length}} — filtro: comprimento / superior / inferior / padrão / corte

Extrair: estrutura a saída da etapa

Os dados retornados pelo LLM ou pelo código geralmente precisam "selecionar alguns campos" para uso posterior.

- id: fetch_user
  type: code
  code: |
    const res = await fetch('https://api.example.com/me');
    return await res.json();
  extract:
    name: $.profile.fullName
    company: $.profile.org.name
    is_admin: $.permissions[?(@=='admin')] | length > 0

Depois disso, steps.fetch_user.data.name / .company estará disponível diretamente.

Condição: execução condicional

Qualquer etapa pode ter uma condição - quando a expressão é falsa, esta etapa é ignorada (o status de execução é marcado como SKIPPED).

- id: summarize
  type: single
  agent: writer
  condition: "{{classifier.category}} == 'ai' && length({{steps.fetch.data.articles}}) > 0"
  task: "..."

Operadores suportados:

• Comparar:== != < > <= >=
• Lógica:&& || !
• Corda:contains(x, y) startsWith(x, y) endsWith(x, y) matches(x, /re/)
• Variedade:length(x) any(list, cond) all(list, cond)
• Julgamento curto:isEmpty(x) isNotEmpty(x)

Tentar novamente: estratégia de tentar novamente

- id: fetch
  type: code
  code: "..."
  retry:
    max_attempts: 3
    backoff: exponential     # fixed | linear | exponential
    initial_delay_ms: 1000
    max_delay_ms: 30000
    retry_on: [network, rate_limit, http_5xx]

Tente novamente somente em erros transitórios (rede/limite de velocidade/5xx).

Agregar: mesclar várias entradas

Use agregado quando uma etapa coletar dados de diversas fontes upstream.

- id: combine
  type: code
  aggregate:
    comments: concat_lines({{steps.group_chat_1.messages}})
    total_tokens: sum({{steps.*.tokens}})
  code: "return { comments, total_tokens };"

Funções agregadas disponíveis: concat/concat_lines/json_array/join(sep)/first/last/max/min/avg.

Mapeamento de nomenclatura DTO

Use Snake_case (group_chat, agent_based) para YAML e camelCase (groupChat, agentBased) para JSON API/DTO.

Armadilhas comuns

• Referência a uma etapa que não foi executada — Se a condição pular a etapa upstream, as referências downstream a ela serão nulas/indefinidas.
• Campos grandes são diretamente conectados às tarefas — task: "{{steps.x.output}}" Se a saída upstream for 100 KB, o LLM irá estourar o token.
• YAML aspas dentro — Expressões contendo dois pontos ou caracteres especiais devem ser colocadas entre aspas duplas: condition: "{{x}} == 1"