跳轉到主要內容
文件建構工作流程視覺化編輯器

視覺化編輯器

畫布 + YAML 雙列、工具列、匯入匯出、版本快照、協作編輯鎖定 —— 每個按鈕都介紹一遍。

工作流編輯器是你每天停留時間最長的頁面。這一篇把它的每一個區域、每一個按鈕都講一遍，讓你知道"想幹 X，該點哪裡"。

整體佈局

編輯器是典型的三欄佈局：

  • 頂部工具欄 — 保存 / 驗證 / 執行 / 導入導出 / 版本歷史等核心操作
  • 左欄畫布 — DAG 可視化，可拖拽節點、連線、縮放、迷你地圖
  • 右欄 YAML — Monaco Editor 直接編輯 YAML 源，帶語法高亮 / 自動補全 / 錯誤提示
  • 底部狀態欄 — 保存狀態、編輯鎖持有者、協作者光標位置、最近一次驗證時間
  • 右側抽屜 — AI 助手、斷點面板、變量快照（按需打開）

畫布 vs YAML：雙向字節級同步

這是 Braidrun 和別家最明顯的差異。一張 DAG 圖和一份 YAML 是字節級等價的：

  • 你在 YAML 裡改一行，畫布對應節點瞬間更新；
  • 你在畫布上拖一條連線，YAML 裡對應的 depends_on 字段同步出現；
  • 註釋 / 空行 / 字段順序都不會丟 —— 導出的 YAML 和你在編輯器裡看到的完全一樣。
什麼時候用哪邊
  • 畫布：看整體結構、畫新步驟的拓撲、做 code review。
  • YAML：改細節字段、複製粘貼塊、精細控制。
  • 兩者都開著 —— 你改其中一邊另一邊跟著變，隨時切換。

頂部工具欄

儲存

默認會在你停止鍵入 5 秒後自動保存一次；也可以按 Ctrl / Cmd + S 手動觸發。每次保存都會創建一個 版本快照（不是簡單的覆蓋）。

復原 / 重做

工具列上有復原 / 重做兩個按鈕，快捷鍵 Ctrl / Cmd + Z 與 Ctrl / Cmd + Shift + Z。這是編輯器級的歷史堆疊：畫布拖曳、YAML 修改、AI 助理逐步搭建的每一步都進同一份歷史 —— 「AI 搞砸了一步」同樣可以一鍵回退。連續鍵入會合併成一筆記錄，自動儲存回寫的時間戳記不會產生多餘歷史；最多保留最近 50 個快照，切換到另一條工作流後歷史重置。

驗證

呼叫平台解析器做一次 round-trip：

  1. YAML → WorkflowDefinition 對象（語法層）
  2. WorkflowDefinition → 語義校驗（變量引用能不能解析、preset 能不能找到、依賴有沒有環）
  3. WorkflowDefinition → YAML round-trip（如果有任何偏差也會報錯）

錯誤會用紅色波浪線標在 YAML 列級，點一下會跳到具體列。深度校驗的結果也會合併進下方介紹的診斷問題面板。修乾淨了再儲存上線。

執行

點這個按鈕會彈一個對話框，讓你：

  • 填 workflow 的 variables（有默認值會預填）
  • 勾選 / 取消 dry-run （默認勾選 —— 強烈推薦第一次跑）
  • 選觸發來源（manual / schedule-simulation）

點「開始執行」後編輯器會自動開一個右側抽屜展示實時事件流，同時在當前標籤打開執行詳情。

導入 / 導出

  • 導入 YAML —— 從文件 / 粘貼板 / 一個 URL 加載 YAML 覆蓋當前內容。
  • 導出 YAML —— 下載當前 YAML 到本地文件。適合做 git 版本控制。
  • 導入 Dify / Langflow 等外部格式 —— 需要 Pro 以上套餐，平臺自動轉換為 Braidrun YAML。

版本歷史

每次保存創建一個快照，默認保留 100 個版本（Enterprise 不限）。你可以：

  • 列出所有快照（含時間、保存者、變更行數）
  • 與當前版本 diff 對比
  • 回滾到任意歷史版本（回滾會創建一條新快照，不會真的覆蓋歷史）

Promote to module / Demote from module

選中畫布上若干連續 step，點「Promote to module」會把這幾步抽成一條獨立的 sub_workflow 模塊，原位置變成一個 module 調用。Demote 反向操作。詳見 模組化與復用。

左欄畫布操作

新增節點

  • 左下角 "+" 按鈕打開 step 類型選擇器，挑一種主模式。
  • 從右欄 "step 模板片段" 拖拽到畫布也可新增。

連線

把一個節點的輸出端點拖到另一個節點的輸入端點，自動在 YAML 里加 depends_on 關係。平臺不允許畫出成環的邊 —— 嘗試畫環時會被回彈並 toast 提示。

節點右鍵菜單

  • 編輯 —— 打開該 step 的 YAML 片段做局部編輯。
  • 複製 —— 克隆一份當前 step（id 自動加後綴）。
  • 刪除 —— 刪除時如果下游有引用會給警告。
  • 設為起點 / 終點 —— 標記 workflow 的顯式入口 / 出口（僅 state_machine 必須）。

縮放與迷你地圖

右下角有迷你地圖，複雜工作流超過畫布大小時可以快速跳轉。Ctrl / Cmd + 滾輪縮放；Space + 拖拽平移。

右欄 YAML

自動補全

基於 JSON Schema，常見字段名、preset 名、已存在的 step id 都能補全。Ctrl / Cmd + Space 強制喚起。

Fold / Unfold

點左側行號旁的箭頭把一整段 step 摺疊起來。快捷鍵 Ctrl / Cmd + Shift + [ / ]。

搜索替換

Ctrl / Cmd + F 搜索，Ctrl / Cmd + H 替換。支持正則。只會作用於當前 workflow —— 不影響其它 workflow。

診斷與問題面板

編輯器有兩層 lint，共用同一套規則碼：

  • 用戶端即時診斷 — 每次編輯後立即在本地重算（相依環、懸空引用、拼寫相近的 step id 建議等結構規則），零延遲驅動問題面板、節點角標與工具列徽章。
  • 伺服器端深度校驗 — 點工具列「驗證」時呼叫 POST /api/workflows/lint，一次拿到全部問題（儲存校驗遇到第一條錯誤就停，lint 不會），並補上 agent 預設、模組契約這類需要伺服器端資料的規則。

工具列上的徽章即時顯示錯誤 / 警告數量（有錯誤時紅色，只有警告時黃色），點擊會觸發一次深度校驗並開啟問題面板。面板裡每條問題帶步驟定位標籤（點擊跳到對應節點）與修復建議；也可以單條或全部「交給 AI 修復」—— 編輯器會把問題組裝成結構化 prompt 發給 AI 助理。

右側抽屜

AI 助手

點右側欄中部的"AI 助手"圖標展開。支持：

  • 用自然語言描述一段要改的邏輯，助手給出 diff 預覽；
  • Slash 命令：/execute、/validate、/export、/new、/undo、/help；
  • /undo 回退助理的修改（最多 10 步）；編輯器自身的 Ctrl / Cmd + Z 也能一步步復原 AI 的改動。

完整能力見 使用 AI 助理編排。

斷點面板

execution 正在 debug 模式下執行時，這個面板會亮起來。可以添加 / 刪除斷點、看命中歷史、編輯暫停時的變量。詳見 斷點調試。

變量快照

點中某個 step 時顯示該 step 執行前可用的所有變量 —— 包括 var:* / steps.*.data / classifier.* / credentials.*（憑據值會被脫敏顯示）。

協作編輯鎖

同一條工作流同一時間只有一個人可以編輯 —— 誰先進入誰拿鎖。其它人訪問時是隻讀模式，狀態欄會顯示"xxx 正在編輯"。鎖在 5 分鐘無操作後自動釋放，或被 Admin 強制解鎖。

多人協同流程

推薦流程：A 改完保存 → 釋放鎖 → B 拿鎖 → 繼續改。想並行改就拆成多個子工作流，分別編輯。

常用快捷鍵

編輯器裡最常用的幾個 —— 完整列表見 鍵盤快捷鍵。

  • Ctrl / Cmd + S — 儲存
  • Ctrl / Cmd + E — 執行（打開對話框）
  • Ctrl / Cmd + Shift + V — 驗證
  • Ctrl / Cmd + Z — 撤銷（YAML 編輯 + AI 助手都適用）
  • Ctrl / Cmd + Shift + Z — 重做
  • Alt + A — 開關 AI 助手抽屜
  • Alt + B — 開關斷點面板

下一步