跳轉到主要內容
文件入門核心概念

核心概念

工作流程、步驟、Agent、模組、執行、憑證 —— 這些字在 Braidrun 裡到底指什麼。

Braidrun 裡所有的功能 —— 畫布、YAML、調度、審批、監控 —— 都圍繞一組非常剋制的核心概念。這一頁把這些概念放在一張圖裡，讓你"無論後面讀哪一篇都知道座標"。

心智模型一句話

一個 工作流程 是一張 DAG，由若干 步驟 組成；Step 可以是一次 LLM 調用（用 Agent）、一段程式碼或一個子工作流（引用一個 模塊），任意步驟上還能加審批門控。Workflow 被觸發後產生一次 執行過程，運行期間會引用 憑證 訪問外部系統。

Workflow · 工作流

工作流是本平臺最上層的對象。你可以把它理解為"一張可版本化的業務流程圖"，由：

  • 一份 YAML 文檔（定義了結構）
  • 一組元數據（觸發器、參數預設、權限、標籤）
  • 若干次過去的 Execution 記錄（審計與調試用）

組成。同一個 workflow 在 Web UI 裡以 DAG 畫布呈現，畫布與 YAML 是同一份定義的兩種檢視。Git 裡的 diff 是正常的 YAML diff，不是混亂的 JSON dump。

工作流可以被五種方式觸發：

  1. 手動 — 編輯器裡點"執行"，或從列表批量發起。
  2. 定時 — cron 運算式、固定間隔、一次性定時，或「上游工作流完成後延遲 N 秒」的鏈式觸發。
  3. 網路鉤子 — 外部系統 POST 觸發，API Key 認證（相容 HMAC 簽章）。
  4. API — 用 v1 API 的觸發端點從你自己的系統發起執行。
  5. 被父工作流嵌入 — 通過 sub_workflow step 被另一條工作流當作黑盒調用。

Step · 步驟

Step 是工作流裡的最小執行單元。每個 step 必須且只能選一種"主模式"：

  • single — 單個 Agent 執行一條任務描述。最輕量的 LLM 調用原語。
  • group_chat — 多個 Agent 按輪次討論，互相參考上下文。適合頭腦風暴、批判性評審。
  • agent_based — 一個 orchestrator Agent 讀完任務，動態把子任務派給 worker Agent。
  • code — 代码脚本（Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI 共 7 种），在隔离沙箱中执行。确定性 > LLM 的场景首选。
  • classifier — LLM 對輸入打一個類別標籤，結果寫入 output_variable 指定的變數，供後續 step 用 condition 分支。
  • state_machine — 多狀態 + 狀態轉移條件。適合多輪反覆或工作流內含小流程。
  • sub_workflow — 把另一個工作流當黑盒調用，帶契約校驗、環路檢測、變量隔離。
  • workflow_output_read — 讀取另一個工作流執行發布的輸出（publish_outputs），存入本地變數。

在主模式之上，幾乎所有 step 可以疊加下面的通用增強字段：

  • depends_on / condition — 前驅相依 + 跳過條件（condition 支援頂層 && 與 ||）
  • manual_approval — 人工審批門控：暫停執行，批准後續跑
  • parallel / timeout_seconds — 並行執行設定 / 步驟逾時
  • retry — 瞬時錯誤的退避重試策略
  • repeat_until / iterate_over — 迴圈到條件滿足 / 對集合逐項執行
  • extract / aggregate — 從輸出裡挑字段 / 多輸入合併
  • publish_outputs — 把步驟產物發布為命名輸出，供 workflow_output_read 取用
  • idempotent — 宣告「同輸入 → 同輸出、無副作用」，服務重啟後自動續跑時以它判斷能否從中斷步驟重來
  • on_success / on_failure — 成功 / 失敗後的補充動作（發通知、寫審計等）

Agent · 代理

Agent 是「一次 LLM 會話 + 它可用的工具 + 它的執行策略」的封裝。在 Braidrun 裡你幾乎不直接手寫 system prompt —— 從 19 個內建 preset 裡選一個（universal / coder / researcher / data_analyst / web_scraper / writer ……），按需 overrides 幾個欄位就夠。

yaml
agents:
  planner:
    preset: universal              # 选一个基线模板
  analyst:
    preset: data_analyst
    overrides:                     # 按需覆盖
      llm_config:
        temperature: 0.2
      tool_set: [file_system, csv, database]

一個 Agent 可被多個 step 引用；每次 step 執行都會開一個新的會話實例（不會串記憶）。詳見 Agent 配置詳解。

Module · 模塊

模塊是"聲明瞭 WorkflowModuleContract 的 workflow"—— 也就是一個對外公開了 inputs / outputs 契約的可複用工作流，能被其他工作流通過 sub_workflow 調用。

模塊帶來的價值：

  • 類型化 + 字段級別的契約校驗，不會"字段改了下游全掛"
  • 黑盒執行 —— 調用方看不到內部 step，內部邏輯可以獨立演化
  • 運行時 + 發佈時雙重環路檢測，避免"A 引用 B，B 又引用了 A"
  • 模塊庫裡一鍵 Promote（把一段 step 抽成模塊）/ Demote（把模塊還原為內聯 step）

模組庫自帶 120+ 個內建模組（平台登入、時間窗計算、ASA 報表拉取、Excel 報表、Slack 投遞等），詳見 內建模組庫；創建你自己的模塊見 模組化與復用。

Execution · 執行

Execution 是一次工作流的具體運行實例。它的生命週期是一個狀態機：

PENDING → RUNNING → COMPLETED / FAILED / CANCELLED / INTERRUPTED

遇到審批門控時，執行會停在等待審批的狀態，批復後繼續走狀態機。

每次 execution 都有：

  • 觸發來源（manual / schedule / webhook / api / sub_workflow）
  • 開始時間、結束時間、總耗時、每步耗時
  • 所有 step 的輸入 / 輸出 / 中間事件（SSE 事件流）
  • 累計 token / cost
  • 產生的 artifacts 列表

服務異常重啟時進行中的 execution 會被標成 INTERRUPTED。開啟 recovery.autoResumeOnRestart 之後，可以從中斷步驟自動續跑，詳見 服務重啟自動續跑。

Credential · 憑據

憑據是"API Key、Webhook Secret、OAuth Token"等敏感信息的統一存儲。所有值在服務端 AES-256-GCM 加密落庫，一旦寫入就不能讀回（只能覆蓋或刪除）。

解析鏈路按順序查找，先命中生效：

  1. 當前用戶個人命名空間
  2. 用戶所在團隊的命名空間
  3. 系統命名空間（管理員配置的公共 Key）

Agent / code 步驟在運行時按需解析，永遠不寫入日誌、不出現在 YAML 導出、不對調用方的其它步驟可見。

Skill / Tool · 技能與工具

Agent 的"雙手" —— LLM 推理過程中可調用的函數。分三類：

  • 內置工具集 — file_system / shell / web / browser / code_execution 等，隨 preset 默認就綁好。
  • MCP 擴展工具 — 任何 MCP server 暴露的工具都能註冊進來。
  • 技能市場 — 在「技能市場」挑選已發佈的技能一鍵啟用。

變數與表達式

所有動態值都通過雙花括號 {{ ... }} 引用。三種寫法：

  • {{var:name}} — workflow 頂層變數
  • {{steps.plan.output}} — 上游步驟的輸出（建議的完全限定形式）
  • {{plan}} — 裸形式：先按步驟名查輸出，再按變數名查值

classifier 的分類結果會寫入它 output_variable 指定的變數，下游步驟用 condition 判斷走哪個分支。憑證不走範本變數：執行時按 provider 從憑證中心解析注入；code 步驟拿到的變數則以 WF_VAR_* 環境變數注入。

完整語法（JSONPath、filter、condition 表達式）見 變數與表達式。

一張圖把它們放一起

text
       ┌──────────── Workflow ────────────┐
       │                                  │
Trigger→─────►  Step 1 (single, agent=A) ◄─── Credential (解析给 A)
       │         │                        │
       │         ▼                        │
       │      Step 2 (classifier)         │
       │         │                        │
       │   ┌─────┴─────┐                  │
       │   ▼           ▼                  │
       │ Step 3       Step 4 (sub_workflow ──► Module)
       │ (code)       │                   │
       │              ▼                   │
       │      manual_approval 门控        │
       │              │                   │
       └──────────────┴──► Execution (记录状态 / 产物 / token / cost)

你已經知道要看哪裡了