跳转到主要内容
文档入门核心概念

核心概念

工作流、步骤、Agent、模块、执行、凭据 —— 这些词在 Braidrun 里到底指什么。

Braidrun 里所有的功能 —— 画布、YAML、调度、审批、监控 —— 都围绕一组非常克制的核心概念。这一页把这些概念放在一张图里，让你"无论后面读哪一篇都知道坐标"。

心智模型一句话

一个 工作流 是一张 DAG，由若干 步骤 组成；Step 可以是一次 LLM 调用（用 Agent）、一段代码或一个子工作流（引用一个 模块），任意步骤上还能加审批门控。Workflow 被触发后产生一次 Execution，运行期间会引用 Credential 访问外部系统。

Workflow · 工作流

工作流是本平台最上层的对象。你可以把它理解为"一张可版本化的业务流程图"，由：

  • 一份 YAML 文档（定义了结构）
  • 一组元数据（触发器、参数预设、权限、标签）
  • 若干次过去的 Execution 记录（审计与调试用）

组成。同一个 workflow 在 Web UI 里以 DAG 画布呈现，画布和 YAML 是同一份定义的两种视图。Git 里的 diff 是正常的 YAML diff，不是混乱的 JSON dump。

工作流可以被五种方式触发：

  1. 手动 — 编辑器里点"执行"，或从列表批量发起。
  2. 定时 — cron 表达式、固定间隔、一次性定时，或"上游工作流完成后延迟 N 秒"的链式触发。
  3. Webhook — 外部系统 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)

你已经知道要看哪里了