跳转到主要内容
文档构建工作流可视化编辑器

可视化编辑器

画布 + 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 — 开关断点面板

下一步