工作流编排

在外脑编辑器中，文档即工作流。文档中的 Block 按从上到下的顺序执行，通过控制流 Block 实现分支、循环和并行。

执行模型

顺序执行

文档中的 Block 按线性顺序依次执行。每个 Block 执行完成后，其输出变量可被后续 Block 引用。

[Input]          ← 接收输入参数
   ↓
[Generation]     ← 调用 AI 模型生成内容
   ↓
[Code]           ← 处理生成结果
   ↓
[输出]           ← 返回最终结果

条件分支（If-Else）

If-Else Block 根据条件表达式选择执行不同分支：

[If-Else Block]
  ├── if 条件为真 → 执行 then 分支
  └── else        → 执行 else 分支

循环（Loop）

Loop Block 支持两种循环模式：

• 计次循环：指定循环次数
• 列表遍历：遍历数组中的每个元素

循环变量 item、index、count 仅在容器内部可见。

并行执行（Promise）

Promise Block 将多个分支并行执行，支持多种完成策略：

策略	说明
all	等待所有分支完成
race	第一个分支完成即返回
first N	前 N 个分支完成即返回

并发限制：最大并发数为 10。超出的任务排队等待。

分支模式：

• single：每个分支执行一次
• expand：分支展开为多个并行任务（支持按计次或列表展开）

每个分支独立运行，拥有父级上下文的快照副本，分支间互不影响。

子工作流调用（Flow）

Flow Block 调用外部文档作为子工作流执行。支持传入参数和获取返回值。

调用限制：

模式	单节点上限	总调用上限
编辑器	10	50
API	100	500

流式输出

文档执行支持三种响应模式：

JSON 模式

等待所有 Block 执行完成后，一次性返回完整结果。

SSE 模式

通过 Server-Sent Events 实时推送执行进度。事件类型：

事件	说明
run_start	执行开始
block_start	Block 开始执行
block_chunk	Block 流式输出片段（如 AI 生成的文本）
block_complete	Block 执行完成，包含完整输出
block_end	容器 Block 结束
block_error	Block 执行出错
tool_start	工具调用开始
tool_result	工具调用完成
run_complete	执行完成，包含完整结果

NDJSON 模式

每行一个 JSON 对象（Newline Delimited JSON），与 SSE 包含相同的事件数据，但格式更适合程序处理。

运行状态

文档执行过程中会经历以下状态：

状态	说明
running	正在执行
wait_for_input	等待用户输入（Ask Block 触发）
completed	执行完成
error	执行出错或超时

状态转换

• 正常完成 → completed
• Exit Block 触发 → completed
• 执行超时 → error（标记 timedOut=true）
• 运行时错误 → error

超时与限制

执行超时

配置项	默认值
默认超时	60 秒
最大超时	300 秒

超时时间可通过 API 调用时的参数指定，会被限制在 [1, maxTimeoutS] 范围内。

超时触发后：

1. 设置停止信号，中止当前 Block 执行
2. 清理后台任务
3. 返回 error 状态，timedOut=true

Flow 调用限制

防止递归或过度调用的双重限制：

• 单节点上限：同一目标文档的最大调用次数
• 总调用上限：整个执行链路所有 Flow 调用的累计上限

Promise 并发限制

最大并发数 10，超出的任务排队执行。支持早停优化 — 当已满足完成条件时，自动取消未完成的任务。

部署执行

文档部署为 API 端点后，可通过 HTTP 请求触发执行：

# 通过部署 ID 运行
POST /api/released-app/:deploymentId/run

# 通过文档 ID 运行
POST /api/released-app/d/:documentId/run

# 通过 Release 别名运行
POST /api/released-app/r/:alias/:version/*

API 调用使用 API Key 认证（非 JWT），支持同样的三种响应模式（JSON/SSE/NDJSON）。

详细的 API 文档请参考 API 运行接口。