Flow Block

引用并执行另一个文档，实现工作流的模块化复用和嵌套调用。

功能说明

Flow Block 是一个数据节点，它引用项目中的另一个文档（workflow 或 skill），在运行时加载该文档的内容并作为子流程执行。子文档的数据节点输出会被收集为 Flow Block 的输出变量，可在后续 Block 中引用；若子文档配置了 Output 声明，则只暴露声明的字段，内部块的输出不再注册（见下文「输出变量」）。

当你需要复用已有的工作流逻辑、将复杂流程拆分为多个子模块、或在不同文档间建立调用关系时，使用 Flow Block。

使用场景

工作流复用：将通用的处理逻辑（如数据清洗、格式化）封装为独立文档，在多个主工作流中通过 Flow Block 调用
模块化编排：将大型工作流拆分为多个子文档，通过 Flow Block 按序或并行调用，降低单个文档的复杂度
fire-and-forget：触发一个后台任务而不等待其完成（await=false 模式），适用于不需要返回结果的异步操作

配置参数

属性名	类型	说明	默认值
`targetDocumentId`	`string`	目标文档 ID（编辑时使用）	`''`
`targetDeploymentId`	`string`	目标部署版本 ID（发布后使用固定版本）	`''`
`inputJSON`	`string`	传入子文档的输入参数（JSON 序列化的 `Record<string, ValueSource>`）	`'{}'`
`await`	`boolean`	是否等待子文档执行完成	`true`

await 模式说明

值	行为
`true`	等待子文档执行完毕，收集输出变量后继续
`false`	fire-and-forget 模式，触发后立即继续，不等待结果

输出变量

子文档配置了 Output 声明时，Flow 只返回声明字段。例如 Flow 的公开名称为 analyze，子文档声明 answer，正文用 @{analyze.answer}。内部块名称、ID 与额外的 __default__ 不会混入声明结果；声明字段必填缺失时该 Flow 会明确失败。

没有 Output 声明的旧子文档保留以下内部块聚合行为：

变量名	类型	说明
`__default__`	`object`	包含子文档所有数据节点输出的对象，键为 blockName
`{blockName}`	`any`	子文档中每个数据节点的输出，按节点名称访问
`{blockId}`	`any`	子文档中每个数据节点的输出，按节点 ID 访问

当 await=false（fire-and-forget 模式）时，输出固定为 { __default__: null, status: 'fire-and-forget' }。

引用语法

@{analyze.answer}             -- 子文档声明的 answer 输出
@{analyze.summary.total}      -- 子文档声明的 summary 对象的 total 字段

根名称是当前 Flow 的公开 name，内部 ID 只保持稳定关联；完整深路径与数组下标保留。旧聚合文档按实际返回对象取字段，不能假定声明了 Output 的文档还会返回内部块。

使用示例

示例 1：调用子文档并使用结果

将用户输入传入子文档处理，使用返回的结构化数据：

[Input Block: user_query] — 用户输入
    |
[Flow Block: analyze] — 目标: "数据分析" 文档
    输入: query = 上游 user_query（通过 ValueSource 配置）
    |
[Generation Block] — "根据分析结果 @{analyze.answer} 生成报告"

示例 2：fire-and-forget 后台任务

触发日志记录任务，不等待结果：

[Generation Block: main_result] — 主要处理逻辑
    |
[Flow Block] — 目标: "日志记录" 文档, await: false
    输入: content = 上游 main_result（通过 ValueSource 配置）
    （后台执行，不阻塞主流程）
    |
[下一个 Block] — 立即继续执行

运行时约束

适用文档类型：workflow（Slash 菜单中排除了 skill 类型文档）
可插入上下文：顶层文档、Condition 分支、Loop 内、Promise 分支
不可嵌套场景：无特殊限制，但存在调用深度保护

安全保护机制

保护	说明
循环引用检测	通过 callStack 追踪调用链，检测到循环时报错终止
单节点调用上限	同一目标文档的调用次数超过阈值时报错（防止无限递归）
总调用上限	整个执行过程中 Flow 总调用次数超过阈值时报错（防止过深嵌套）

注意事项

函数调用语义：Flow 本质上是函数调用——目标文档的 Inputs 作为参数，Outputs 作为返回值。通过 inputJSON 传入参数，子文档中的 Input Block 接收这些参数
变量引用：inputJSON 的键必须是子文档 Input 的公开名称；值用字面量或 ValueSource 对象，例如 {"sourceType":"variable","sourceValue":["内部块ID","output"]}。字符串 "@{名称}" 会原样传入，不作为变量插值解析
循环引用防护：系统提供双层检测——发布时通过 DFS 深度优先遍历进行静态检测，运行时通过 callStack 进行动态检测。避免构建 A→B→C→D→A 这样的循环调用链
调用次数限制：系统对单节点调用次数和总调用次数都有上限保护，阈值从 site_settings 读取
文档加载优先级：优先从预加载缓存（flowDocuments）读取目标文档。缓存未命中时，若有 deploymentId 则查询已发布的 snapshot，否则查询文档的实时内容
fire-and-forget 注意事项：await=false 模式下子文档在后台执行，其错误不会影响主流程，但也无法获取其执行结果
输出变量动态解析：编辑器中 Flow Block 的输出变量列表会根据目标文档的内容自动分析生成，无需手动定义

Flow Block ​

功能说明 ​

使用场景 ​

配置参数 ​

await 模式说明 ​

输出变量 ​

引用语法 ​

使用示例 ​

示例 1：调用子文档并使用结果 ​

示例 2：fire-and-forget 后台任务 ​

运行时约束 ​

安全保护机制 ​

注意事项 ​