Workflow Spec
表达 Workflow 工作流的定义语义。运行时通过 name 定位工作流，schema 描述由节点（nodes）与连线（edges）组成的执行图，并附带导出定义（exports）。
资源类型与自然键
| 资源类型 | 自然键 | 说明 |
|---|---|---|
WORKFLOW | ${name} | 工作流名称，作为自然键在定义资源内唯一 |
WorkflowSpecDTO
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 名称，作为工作流自然键 |
displayName | string | 显示名称，对应 canonical metadata.displayName |
category | string | 分类，对应 canonical metadata.category |
description | string | 描述 |
schema | WorkflowSchemaDTO | 工作流 schema：节点、连线与导出定义 |
WorkflowSchemaDTO
| 字段 | 类型 | 说明 |
|---|---|---|
nodes | List<WorkflowNodeDTO> | 节点列表 |
edges | List<WorkflowEdgeDTO> | 连线列表 |
exports | List<WorkflowExportDTO> | 导出定义列表；运行时可在实例完成后消费导出定义 |
协议约束：
WorkflowSchemaDTO当前 canonical 主结构固定为nodes / edges / exports- 当前不定义
variables / bindings / outputs / runtime / profile等额外 workflow 顶层字段 - workflow 级输入由
START节点承担，workflow 级输出由END节点承担
WorkflowNodeDTO
所有节点的公共字段。type 决定 Jackson 多态反序列化的具体子类型与节点配置类型。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 节点ID，必填 |
name | string | 节点名称，必填 |
type | string | 节点类型，必填；见下表 |
inputSchema | WorkflowVariableSchemaDTO | 输入 schema |
outputSchema | WorkflowVariableSchemaDTO | 输出 schema |
使用约定：
- 节点
inputSchema/outputSchema用于声明节点自己的输入输出契约 START节点的outputSchema用于声明 workflow 可供后续节点消费的入口变量END节点的outputSchema用于声明 workflow 对外暴露的规范化输出- 节点间数据映射优先通过
edges+ 节点配置中的模板引用表达，而不是新增 workflow 顶层绑定语义
节点类型映射
type | 对应 DTO | 配置 DTO | 说明 |
|---|---|---|---|
START | StartWorkflowNodeDTO | StartNodeConfigDTO | 开始节点 |
END | EndWorkflowNodeDTO | EndNodeConfigDTO | 结束节点 |
AGENT_TASK | AgentWorkflowNodeDTO | AgentNodeConfigDTO | Agent 任务节点 |
ACTION_TASK | LlmWorkflowNodeDTO | LlmNodeConfigDTO | LLM 动作节点 |
CODE_EXECUTION | FunctionWorkflowNodeDTO | FunctionNodeConfigDTO | 函数执行节点 |
FUNCTION | FunctionWorkflowNodeDTO | FunctionNodeConfigDTO | CODE_EXECUTION 的历史别名，反序列化时映射到同一 DTO |
WEBHOOK | WebhookWorkflowNodeDTO | WebhookNodeConfigDTO | Webhook 调用节点 |
EXCLUSIVE_GATEWAY | ConditionWorkflowNodeDTO | ConditionNodeConfigDTO | 条件分支网关 |
LOOP | LoopWorkflowNodeDTO | LoopNodeConfigDTO | 循环节点 |
USER_TASK | HumanApprovalWorkflowNodeDTO | HumanApprovalNodeConfigDTO | 人工审批节点 |
SUB_WORKFLOW | SubWorkflowWorkflowNodeDTO | SubWorkflowNodeConfigDTO | 子工作流节点 |
ONTOLOGY_MUTATION | VariableSetWorkflowNodeDTO | VariableSetNodeConfigDTO | 变量设置节点 |
WAIT_EVENT | DelayWorkflowNodeDTO | DelayNodeConfigDTO | 延迟等待节点 |
PARALLEL_GATEWAY | ParallelWorkflowNodeDTO | ParallelNodeConfigDTO | 并行网关节点 |
未知类型会回退到 GenericWorkflowNodeDTO / GenericNodeConfigDTO。
_nodeConfigType必须与节点type匹配；缺失或拼写错误会触发多态降级，导致code/inputMapping等具体配置字段被静默丢弃。历史上FUNCTION已并入CODE_EXECUTION，但为兼容旧 spec 仍注册为别名。
扩展节点配置类型
以下 _nodeConfigType 没有对应的 WorkflowNodeDTO 子类，节点本体回退为 GenericWorkflowNodeDTO，但 config 仍按类型反序列化为专用配置 DTO：
_nodeConfigType | 配置 DTO | 说明 |
|---|---|---|
ONTOLOGY_QUERY | OntologyQueryNodeConfigDTO | 本体查询 |
CONDITION | ConditionEvalNodeConfigDTO | 条件求值 |
ONTOLOGY_TRAVERSE | OntologyTraverseNodeConfigDTO | 本体遍历 |
ANALYSIS_OPERATOR | AnalysisOperatorNodeConfigDTO | 分析算子 |
DATASET_WRITE | DatasetWriteNodeConfigDTO | 数据集写入 |
DATASET_QUERY | DatasetQueryNodeConfigDTO | 数据集查询 |
RAW_SINK | RawSinkNodeConfigDTO | 原始结果输出 |
节点配置
公共配置 WorkflowNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
_nodeConfigType | string | 节点配置类型标识，用于 Jackson 多态反序列化；运行态不消费 |
label | string | 未使用。节点标签，仅作为前端展示占位。 |
description | string | 未使用。节点描述，仅作为前端展示占位。 |
StartNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
inputParams | List<StartInputParamDTO> | 开始节点的输入参数列表 |
约定：
START.config.inputParams用于定义 workflow 运行入口表单与参数说明- 如需声明入口变量契约，需与
START.outputSchema保持一致
EndNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
outputMappings | List<EndOutputMappingDTO> | 输出映射列表 |
约定：
END.config.outputMappings用于将执行图中的中间结果收口为 workflow 最终输出- 如需对外暴露稳定结果契约，需与
END.outputSchema保持一致 - 运行时会执行
outputMappings，并将结果作为 workflow 的规范化输出
AgentNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
agentId | string | Agent ID |
systemPrompt | string | 系统提示词 |
tools | List<string> | 工具列表 |
model | string | 模型 |
temperature | Double | 温度 |
maxTokens | Integer | 最大 Token 数 |
memory | Boolean | 是否开启记忆 |
outputSchema | Map<String, Object> | 输出 schema |
LlmNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 模型 |
prompt | string | 提示词 |
systemPrompt | string | 系统提示词 |
temperature | Double | 温度 |
maxTokens | Integer | 最大 Token 数 |
responseFormat | string | 响应格式 |
jsonSchema | Map<String, Object> | JSON schema |
stream | Boolean | 是否流式输出 |
FunctionNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
runtime | string | 运行时 |
code | string | 代码 |
entryPoint | string | 入口函数 |
mode | string | 函数执行模式：INLINE（默认）或 REFERENCE |
executionMode | string | 已废弃。历史执行模式字段，工作流不再调度推理算法 |
algorithmRef | string | 已废弃。历史算法引用字段 |
params | Map<String, Object> | 参数映射 |
inputMapping | Map<String, Object> | 输入映射：目标变量 → 表达式（支持 {{nodeId.field}} 插值） |
dependencies | List<string> | 依赖列表 |
timeout | Integer | 超时时间（毫秒） |
memory | Integer | 内存限制（MB） |
约定：
CODE_EXECUTION仍是函数节点的统一承载类型- 新配置优先使用
mode=INLINE+code，或mode=REFERENCE+entryPoint/runtime executionMode/algorithmRef仅为历史兼容，不应在新 spec 中使用
WebhookNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
url | string | 请求地址 |
method | string | 请求方法 |
queryParams | Map<String, String> | 查询参数 |
headers | Map<String, String> | 请求头 |
body | Object | 请求体 |
timeout | Object | 超时时间 |
retry | RetryPolicyDTO | 重试策略 |
outputMapping | Map<String, String> | 输出映射 |
authType | string | 认证类型 |
authUsername | string | 认证用户名 |
authPassword | string | 认证密码 |
authToken | string | 认证 Token |
authApiKey | string | API Key |
authApiKeyHeader | string | API Key 请求头名 |
outputSchema | string | 输出 schema 范围 |
responseMapping | Map<String, String> | 响应提取映射（key → JSON path，如 $.data.total_count） |
timeoutSeconds | Integer | 请求超时秒数 |
allowPrivate | Boolean | 是否允许访问内网/本地地址（默认拒绝） |
ConditionNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
branches | List<ConditionBranchDTO> | 条件分支列表 |
defaultBranchId | string | 默认分支ID |
ConditionBranchDTO
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 分支ID |
label | string | 分支标签 |
mode | string | 条件模式 |
field | string | 字段 |
operator | string | 操作符 |
valueSource | string | 值来源 |
valueType | string | 值类型 |
value | Object | 常量值 |
valueExpr | string | 值表达式 |
expression | string | 完整表达式 |
condition | string | 条件文本 |
LoopNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
mode | string | 循环模式 |
iterateOver | string | 迭代变量表达式 |
condition | string | 循环条件表达式 |
count | Object | 循环次数 |
maxIterations | Integer | 最大迭代次数 |
parallel | Boolean | 是否并行迭代 |
concurrency | Integer | 子流程并发度（1-8，默认 4） |
continueOnError | Boolean | 单迭代失败是否继续（默认 true） |
perItemTimeoutSeconds | Integer | 单子实例超时（秒，默认 120） |
subWorkflow | Map<String, Object> | 每迭代执行的子工作流（definitionKey / inputMapping） |
inline | Map<String, Object> | 每迭代执行的内嵌子图（nodes / edges），与 subWorkflow 二选一 |
HumanApprovalNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
assignee | string | 审批人 |
approvalType | string | 审批类型 |
timeout | Integer | 超时时间（毫秒） |
timeoutAction | string | 超时动作 |
formSchema | Map<String, Object> | 表单 schema |
message | string | 审批消息 |
SubWorkflowNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
workflowId | string | 子工作流ID |
version | string | 版本 |
inputs | Map<String, String> | 输入映射（兼容字段） |
outputs | Map<String, String> | 输出映射（兼容字段） |
async | Boolean | 是否异步执行（兼容字段） |
definitionKey | string | 子工作流 definition key |
inputMapping | Map<String, String> | 输入映射（变量求值） |
outputMapping | Map<String, String> | 输出映射（子实例上下文求值） |
syncMode | string | 执行模式：SYNC / ASYNC |
VariableSetNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
variableName | string | 变量名 |
value | string | 变量值表达式 |
DelayNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
duration | Object | 延迟时长 |
unit | string | 时间单位 |
ParallelNodeConfigDTO
| 字段 | 类型 | 说明 |
|---|---|---|
parallelTasks | List<string> | 并行任务节点ID列表 |
failFast | Boolean | 是否快速失败 |
concurrency | Integer | 并发数 |
GenericNodeConfigDTO
未知/未识别节点类型的回退配置。
| 字段 | 类型 | 说明 |
|---|---|---|
extra | Map<String, Object> | 未使用。扩展属性占位字段。 |
WorkflowEdgeDTO
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 连线ID，必填 |
sourceNodeId | string | 源节点ID，必填 |
targetNodeId | string | 目标节点ID，必填 |
conditionExpression | string | 条件表达式；条件网关出线必填 |
priority | Integer | 优先级，默认 0 |
变量结构
WorkflowVariableSchemaDTO
用于节点的 inputSchema / outputSchema。
| 字段 | 类型 | 说明 |
|---|---|---|
required | List<string> | 必填字段名列表 |
properties | Map<String, WorkflowVariablePropertyDTO> | 变量属性定义 |
WorkflowVariablePropertyDTO
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 变量类型 |
description | string | 变量描述 |
开始节点输入参数
StartInputParamDTO
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 参数名 |
displayName | string | 显示名称 |
type | string | 参数类型 |
required | Boolean | 是否必填 |
defaultValue | Object | 默认值 |
description | string | 描述 |
itemType | string | 数组元素类型 |
objectFields | List<ObjectFieldDTO> | 对象字段 |
enumValues | List<string> | 枚举值 |
min | Number | 最小值 |
max | Number | 最大值 |
ObjectFieldDTO
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 字段名 |
displayName | string | 显示名称 |
type | string | 字段类型 |
required | Boolean | 是否必填 |
description | string | 描述 |
itemType | string | 数组元素类型 |
objectFields | List<ObjectFieldDTO> | 嵌套对象字段 |
结束节点输出映射
EndOutputMappingDTO
| 字段 | 类型 | 说明 |
|---|---|---|
key | string | 输出键 |
source | Object | 变量来源表达式或结构化来源对象 |
type | string | 输出映射类型，例如 AGENT_VIEW |
params | Map<String, Object> | 结构化映射参数，用于复杂输出装配 |
重试策略
RetryPolicyDTO
| 字段 | 类型 | 说明 |
|---|---|---|
maxRetries | Integer | 最大重试次数 |
backoff | string | 退避策略 |
delay | Integer | 退避延迟（毫秒） |
导出定义
WorkflowExportDTO
| 字段 | 类型 | 说明 |
|---|---|---|
type | string | 导出类型 |
exportName | string | 导出名称 |
displayName | string | 显示名称 |
inputSchema | Map<String, Object> | 输入 schema |
outputSchema | Map<String, Object> | 输出 schema |
executionMode | string | 执行模式 |
constraints | Map<String, Object> | 约束条件 |
使用约定：
exports负责将 workflow 最终结果导出给外部消费者- 分析型 workflow 可使用
type=AGENT_VIEW_RESULT，由运行时将END节点输出投影为统一AgentViewResultVO constraints可用于补充导出来源、投影方式等运行时约束
触发器
当前 WorkflowSpecDTO 与 WorkflowSchemaDTO 未定义独立的触发器（trigger）字段。工作流的入口由类型为 START 的开始节点唯一标识，运行时通过 name 发起工作流实例。
示例
apiVersion: foundry.loambase.ai/v1alpha1
kind: Workflow
metadata:
name: reviewOrder
spec:
name: reviewOrder
description: 订单审批工作流
schema:
nodes:
- id: start
name: 开始
type: START
outputSchema:
required: [orderId]
properties:
orderId:
type: string
description: 订单主键
config:
_nodeConfigType: START
inputParams:
- name: orderId
displayName: 订单ID
type: STRING
required: true
- id: llm_summary
name: LLM 摘要
type: ACTION_TASK
config:
_nodeConfigType: ACTION_TASK
model: gpt-4o
prompt: "请总结订单 {{orderId}} 的内容"
temperature: 0.7
- id: approve
name: 人工审批
type: USER_TASK
config:
_nodeConfigType: USER_TASK
assignee: manager
approvalType: SINGLE
message: 请审批订单摘要
- id: end
name: 结束
type: END
outputSchema:
properties:
result:
type: boolean
description: 审批结果
config:
_nodeConfigType: END
outputMappings:
- key: result
source: "{{approve.approved}}"
edges:
- id: e1
sourceNodeId: start
targetNodeId: llm_summary
- id: e2
sourceNodeId: llm_summary
targetNodeId: approve
- id: e3
sourceNodeId: approve
targetNodeId: end
exports:
- type: AGENT_VIEW_RESULT
exportName: defaultView
displayName: 默认视图
executionMode: SYNC
constraints:
sourceNodeId: end消费位置
foundry-workflow-biz/WorkflowDomainProjectionAdapter：保留为DomainProjectionHandler注册空实现，不执行写库投影。foundry-workflow-biz/WorkflowDefinitionService：运行时从fd_definition_resource_version读取WorkflowSpecDTO。name、description投影到WorkflowDefinitionEntity。schema经WorkflowSpecMapper转换为WorkflowDefinitionSchemaDTO后供运行态引擎使用。
foundry-workflow-biz/WorkflowSpecMapper：将nodes、edges、exports及节点inputSchema/outputSchema全量映射到运行态；不引入额外 workflow 顶层字段。
相关文档
- 核心概念 — CanonicalSpec、ResourceRef 与投影框架
- Bundle API — 定义资源 Bundle 的导入/导出契约