Biến

Mọi giá trị động trong Braidrun đều đi qua "tham chiếu biến". Cú pháp chỉ có một dạng: ngoặc nhọn kép.

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

Bốn nguồn biến

1. var: — Tham số quy trình làm việc

Phần biến/thông số ở đầu quy trình làm việc hoặc đầu vào của lịch trình/webhook đặt trước.

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.* — Đầu ra từ bước ngược dòng

Có một đầu ra có cấu trúc sau mỗi bước được chạy. Các trường con được sử dụng phổ biến nhất:

• steps.id.output — Văn bản thuần túy hoặc giá trị trả về thô.
• steps.id.data — JSON có cấu trúc sau khi trích xuất.
• steps.id.artifacts[0].url — Liên kết tập tin sản phẩm.
• steps.id.tokens / cost / duration_ms — Thống kê thực hiện.

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.* — Kết quả định tuyến của bộ phân loại

Kết quả của bước phân loại trước đó được sử dụng làm tham chiếu cấp một cho điều kiện/phân nhánh.

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}}"

Tương đương với các bước.<classifier_step_id>.category - chỉ ngắn hơn và có nhiều ngữ nghĩa hơn.

4. credentials.* — Tham chiếu thông tin xác thực

Liên kết giải quyết: Không gian tên người dùng → Không gian tên nhóm → Không gian tên hệ thống; xem chi tiết Nhận diện.

Biểu thức jsonpath

Cú pháp đường dẫn đơn giản có thể được viết trong dấu ngoặc nhọn - về cơ bản tương thích với một tập hợp con của JSONPath:

• {{steps.fetch.data.articles[0].title}} — chỉ số mảng
• {{steps.fetch.data.articles[*].title}} — Tất cả các phần tử của mảng (mảng trả về)
• {{steps.fetch.data.articles[?(@.score>5)]}} — Lọc có điều kiện
• {{steps.fetch.data | length}} — bộ lọc: chiều dài / trên / dưới / mặc định / cắt

Trích xuất: cấu trúc đầu ra của bước

Dữ liệu LLM hoặc code trả về thường cần "nhặt ra vài trường" cho downstream dùng. Dùng extract:

- 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

Sau đó, step.fetch_user.data.name / .company sẽ có sẵn trực tiếp.

Điều kiện: thực hiện có điều kiện

Bất kỳ bước nào cũng có thể có điều kiện - khi biểu thức sai, bước này sẽ bị bỏ qua (trạng thái thực thi được đánh dấu BỎ QUA).

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

Các toán tử được hỗ trợ:

• So sánh:== != < > <= >=
• Logic:&& || !
• Sợi dây:contains(x, y) startsWith(x, y) endsWith(x, y) matches(x, /re/)
• Mảng:length(x) any(list, cond) all(list, cond)
• Phán quyết ngắn gọn:isEmpty(x) isNotEmpty(x)

Thử lại: chiến lược thử lại

- 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]

Chỉ thử lại các lỗi nhất thời (mạng/giới hạn tốc độ/5xx). Các ngoại lệ kinh doanh (lỗi điều kiện, từ chối LLM) sẽ không được thử lại.

Tổng hợp: hợp nhất nhiều đầu vào

Sử dụng tổng hợp khi một bước thu thập dữ liệu từ nhiều nguồn ngược dòng. Ví dụ: tóm tắt các nhận xét sau group_chat:

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

Các hàm tổng hợp có sẵn: concat/concat_lines/json_array/join(sep)/first/last/max/min/avg.

Ánh xạ đặt tên DTO

Sử dụng snake_case (group_chat, Agent_based) cho YAML và CamelCase (groupChat, AgentBased) cho JSON API/DTO. Nền tảng tự động chuyển đổi theo cả hai hướng, bạn không cần lo lắng.

Những cạm bẫy thường gặp

• Tham chiếu đến một bước chưa được chạy — Nếu điều kiện bỏ qua bước ngược dòng, các tham chiếu xuôi dòng tới nó sẽ có giá trị rỗng/không xác định. Sử dụng | default(...) để tìm hiểu.
• Các trường lớn được cắm trực tiếp vào nhiệm vụ — task: "{{steps.x.output}}" Nếu đầu ra ngược dòng là 100KB, LLM sẽ phân tách mã thông báo. Giải nén và nén đầu tiên trước khi truyền.
• YAML dấu ngoặc kép bên trong — Các biểu thức chứa dấu hai chấm hoặc ký tự đặc biệt phải được đặt trong dấu ngoặc kép: condition: "{{x}} == 1"