dify-workflow-nodes-reference.md 39 KB
Dify 工作流节点系统参考
本文件基于
D:/projects/agent-management/dify1.16.0 前端代码（web/app/components/workflow/）梳理，聚焦"工作流编排器中的节点类型"与"每个节点详情面板要填的表单项"，作为本仓库后续实现节点 schema / 节点详情面板 / 工作流引擎时的字段对照。已有
dify-reference.md偏项目整体架构（应用形态、引擎、Plugin Daemon、Agent Runtime 等），本文档聚焦"节点 → 字段"这一层，两份文档互为补充。
0. 关键源码定位
| 内容 | 文件相对路径 |
|---|---|
节点类型枚举 BlockEnum（共 31 个） |
web/app/components/workflow/types.ts:27-60 |
节点分类枚举 BlockClassification |
web/app/components/workflow/block-selector/types.ts:40-48 |
| 节点选择面板分组（BLOCKS 数组） | web/app/components/workflow/block-selector/constants.tsx |
节点元数据生成器 genNodeMetaData |
web/app/components/workflow/utils/gen-node-meta-data.ts |
通用节点类型 CommonNodeType<T> |
web/app/components/workflow/types.ts:77-119 |
各节点固定输出结构常量 *_OUTPUT_STRUCT |
web/app/components/workflow/constants.ts |
| 中/英文节点标题与描述 i18n | web/i18n/zh-Hans/workflow.json 的 blocks.* 与 tabs.* |
| 节点目录约定 | web/app/components/workflow/nodes/<type>/{default.ts, types.ts, panel.tsx, node.tsx} |
| 通用错误处理类型 | web/app/components/workflow/nodes/_base/components/error-handle/types.ts |
| 通用重试类型 | web/app/components/workflow/nodes/_base/components/retry/types.ts |
| 字段组件库 | web/app/components/workflow/nodes/_base/components/field.tsx 等 |
1. 节点分类（5 类）
来自 BlockClassification，中文标签来自 i18n tabs.*：
| 分类 key | 中文 | 英文 |
|---|---|---|
-（默认） |
默认（最常用） | Most Common |
question-understand |
问题理解 | Question Understand |
logic |
逻辑 | Logic |
transform |
转换 | Transform |
utilities |
工具 | Utilities |
2. 节点完整清单（31 个，按分类组织）
顺序按
genNodeMetaData中传入的classification字段归位；sort为同类内排序权重。
2.1 默认 / 最常用（Default）
| type | 中文名 | 英文名 | 用途 | sort | 源码路径 |
|---|---|---|---|---|---|
start |
用户输入 | User Input | 工作流起始节点；定义工作流输入变量；自动暴露 userinput.query / userinput.files |
0.1 | nodes/start/ |
start-placeholder |
工作流开始 | Workflow Start | 占位起始节点；提示用户选择具体起始类型 | 0.05 | nodes/start-placeholder/ |
llm |
LLM | LLM | 大模型调用节点 | 1 | nodes/llm/ |
knowledge-retrieval |
知识检索 | Knowledge Retrieval | 从知识库检索文档片段 | 2 | nodes/knowledge-retrieval/ |
end |
输出 | Output / End | 工作流输出节点；声明最终输出变量 | 2.1 | nodes/end/ |
answer |
直接回复 | Answer / Direct Answer | Chat 模式下直接给出回复（isRequired） |
2.1 | nodes/answer/ |
agent |
Agent | Agent | 旧版 Agent 节点（基于策略插件） | 3 | nodes/agent/ |
agent-v2 |
Agent | Agent | 新版 Agent 节点（绑定 roster/inline agent） | 3 | nodes/agent-v2/ |
tool |
工具 | Tool | 调用任意工具/插件/MCP/工作流作为工具 | -1 | nodes/tool/ |
datasource |
数据源 | Data Source | 数据源驱动 flow 的入口（isStart, isRequired） |
-1 | nodes/data-source/ |
datasource-empty |
空数据源 | Empty Data Source | 数据源 flow 的空占位节点 | -1 | nodes/data-source-empty/ |
knowledge-index |
知识库 | Knowledge Base | 在数据源 flow 中索引知识块（isRequired、isUndeletable、isSingleton、isTypeFixed） |
3.1 | nodes/knowledge-base/ |
trigger-schedule |
定时触发器 | Schedule Trigger | 基于 cron / 可视化时间触发 | 2 | nodes/trigger-schedule/ |
trigger-webhook |
Webhook 触发器 | Webhook Trigger | 通过 HTTP 回调触发 | 3 | nodes/trigger-webhook/ |
trigger-plugin |
集成触发器 | Integration Trigger | 通过插件事件订阅触发 | 1 | nodes/trigger-plugin/ |
2.2 问题理解（Question Understand）
| type | 中文名 | 用途 | sort | 源码路径 |
|---|---|---|---|---|
question-classifier |
问题分类器 | 用大模型把用户问题分类到不同分支 | 1 | nodes/question-classifier/ |
2.3 逻辑（Logic）
| type | 中文名 | 用途 | sort | 源码路径 |
|---|---|---|---|---|
if-else |
条件分支 | IF/ELIF/ELSE 多分支 | 1 | nodes/if-else/ |
iteration |
迭代 | 对数组迭代（含子工作流；isTypeFixed） |
2 | nodes/iteration/ |
iteration-start |
迭代开始 | 迭代节点内部自动生成的起始节点 | -1 | nodes/iteration-start/ |
loop |
循环 | 通用循环（条件终止；isTypeFixed） |
3 | nodes/loop/ |
loop-start |
循环开始 | 循环节点内部自动生成的起始节点 | -1 | nodes/loop-start/ |
loop-end |
退出循环 | 循环终止节点（isSingleton） |
2 | nodes/loop-end/ |
human-input |
人工介入 | 暂停工作流，等待人工表单输入 | 1 | nodes/human-input/ |
2.4 转换（Transform）
| type | 中文名 | 用途 | sort | 源码路径 |
|---|---|---|---|---|
code |
代码执行 | 执行 Python3 / JavaScript 代码 | 1 | nodes/code/ |
template-transform |
模板转换 | 用 Jinja2 模板渲染字符串 | 2 | nodes/template-transform/ |
variable-aggregator |
变量聚合器 | 把多路变量聚合为一个输出（目录 variable-assigner/） |
3 | nodes/variable-assigner/ |
document-extractor |
文档提取器 | 从文件变量提取文本 | 4 | nodes/document-extractor/ |
assigner |
变量赋值 | 给会话变量赋值（v2 写入模式） | 5 | nodes/assigner/ |
parameter-extractor |
参数提取器 | 用大模型从文本提取结构化参数 | 6 | nodes/parameter-extractor/ |
2.5 工具（Utilities）
| type | 中文名 | 用途 | sort | 源码路径 |
|---|---|---|---|---|
http-request |
HTTP 请求 | 发起 HTTP/HTTPS 请求 | 1 | nodes/http/ |
list-operator |
列表操作 | 列表过滤 / 抽取 / 排序 / 限制 | 2 | nodes/list-operator/ |
节点选择面板的实际展示：
BLOCKS数组（block-selector/constants.tsx）只展示常用节点；start-placeholder/iteration-start/loop-start/knowledge-index/datasource/datasource-empty/trigger-plugin/tool等通过其它入口（工具面板、触发器面板、Start 标签）添加。
3. 节点配置字段表（按节点详情面板）
字段类型缩写
| 缩写 | 含义 |
|---|---|
var-reference |
变量引用选择器（ValueSelector） |
var-list |
变量列表（可添加多个，每项 variable 名 + value_selector） |
model-selector |
模型 + 完成参数（弹窗） |
prompt-editor |
提示词编辑器（basic / jinja2 两种 edition） |
code-editor |
代码编辑器（带语法高亮） |
select / input / number / textarea / switch |
基础表单 |
object |
复杂嵌套对象 |
conditional-list |
条件列表（含逻辑运算符） |
3.1 Start（用户输入）start
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
variables |
InputVar[]（var-list，支持 textInput/paragraph/select/number/url/files/json/jsonObject/contexts/iterator/singleFile/multiFiles/loop/checkbox） |
否 | [] |
用户自定义输入变量定义 |
内置变量（无需配置）：
userinput.query（chat 模式 String）、userinput.files（Array[File]）。
3.2 End（输出）end
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
outputs |
Variable[]（每项 variable、value_selector） |
是（至少 1 项且变量名/值引用都必填） | [] |
工作流最终输出变量 |
3.3 Answer（直接回复）answer
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
answer |
string（textarea + 变量插值，支持 {{#var#}}） |
是 | '' |
回答内容 |
variables |
Variable[] |
否 | [] |
回答中引用的变量列表 |
3.4 LLM llm
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
model.provider |
string（model-selector） | 是 | '' |
模型供应商 |
model.name |
string | 是 | '' |
模型名 |
model.mode |
AppModeEnum（CHAT/COMPLETION） |
- | CHAT |
模式 |
model.completion_params |
object | 否 | {temperature: 0.7} |
完成参数（temperature / top_p / max_tokens / stop 等） |
prompt_template |
PromptItem[]（chat 模型）或 PromptItem（completion 模型） |
是（除非启用 memory） | [{role:'system', text:''}] |
提示词模板；每个 PromptItem 含 role(system/user/assistant)、text、edition_type(basic/jinja2)、jinja2_text |
prompt_config.jinja2_variables |
Variable[] |
否 | - | Jinja2 模式下声明的变量 |
context.enabled |
boolean | 否 | false |
启用上下文注入 |
context.variable_selector |
ValueSelector（var-reference，过滤为 contexts） | 启用时必填 | [] |
上下文变量 |
memory |
Memory（window.enabled/size、role_prefix、query_prompt_template） |
否 | - | 记忆（仅 chat 模式可用） |
vision.enabled |
boolean | 否 | false |
启用视觉（图像）输入 |
vision.configs.variable_selector |
ValueSelector | 启用时必填 | - | 视觉变量引用 |
structured_output_enabled |
boolean | 否 | - | 启用结构化输出 |
structured_output |
{schema: SchemaRoot}（type=object + properties + required） |
否 | - | 结构化输出 schema |
reasoning_format |
'tagged' \| 'separated' |
否 | 'tagged' |
推理内容格式 |
固定输出：text(string)、reasoning_content(string)、usage(object)（来自 LLM_OUTPUT_STRUCT）。
3.5 Knowledge Retrieval（知识检索）knowledge-retrieval
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
query_variable_selector |
ValueSelector | 是 | [] |
查询变量 |
query_attachment_selector |
ValueSelector | 否 | [] |
查询附件（图片等） |
dataset_ids |
string[] | 是 | [] |
知识库（至少 1 个） |
retrieval_mode |
RETRIEVE_TYPE（multiWay/oneWay） |
否 | multiWay |
检索模式 |
multiple_retrieval_config.top_k |
number | 否 | DATASET_DEFAULT.top_k |
top_k |
multiple_retrieval_config.score_threshold |
number/null | 否 | - | 分数阈值 |
multiple_retrieval_config.reranking_enable |
boolean | 否 | false |
启用重排序 |
multiple_retrieval_config.reranking_model |
{provider, model} | multiWay+reranking 时必填 | - | 重排序模型 |
multiple_retrieval_config.reranking_mode |
RerankingModeEnum |
否 | - | 重排序模式 |
multiple_retrieval_config.weights |
object | 否 | - | 加权权重 |
single_retrieval_config.model |
ModelConfig | oneWay 时必填 | - | 单路检索模型 |
metadata_filtering_mode |
MetadataFilteringModeEnum(disabled/automatic/manual) |
否 | - | 元数据过滤模式 |
metadata_filtering_conditions |
{logical_operator, conditions: MetadataFilteringCondition[]} |
manual 时必填 | - | 元数据过滤条件 |
metadata_model_config |
ModelConfig | automatic 时必填 | - | 元数据过滤模型 |
固定输出：result(array[object])（RETRIEVAL_OUTPUT_STRUCT）。
3.6 Question Classifier（问题分类器）question-classifier
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
query_variable_selector |
ValueSelector | 是 | [] |
输入变量 |
model |
ModelConfig | 是（provider 必填） | {provider:'', name:'', mode:CHAT, completion_params:{temperature:0.7}} |
模型 |
classes |
Topic[]（id/name/label） |
是（至少 1 个；name 不能空） | [{id:'1',name:'',label:'CLASS 1'},{id:'2',...}] |
分类（每类对应一个输出分支） |
instruction |
string | 否 | - | 高级指令 |
memory |
Memory | 否 | - | 记忆 |
vision.enabled / vision.configs |
同 LLM | 否 | {enabled:false} |
视觉 |
固定输出：class_name(string)、class_label(string)、usage(object)。
3.7 IF/ELSE if-else
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
cases |
CaseItem[] |
是（至少 1 个） | [{case_id:'true', logical_operator:'and', conditions:[]}] |
条件分支（IF + ELIF*） |
cases[].logical_operator |
LogicalOperator(and/or) |
是 | and |
同一 case 内多条件的逻辑运算符 |
cases[].conditions[].variable_selector |
ValueSelector | 是 | - | 比较变量 |
cases[].conditions[].comparison_operator |
ComparisonOperator（contains/not contains/start with/end with/is/is not/empty/not empty/=/≠/>/</≥/≤/is null/is not null/in/not in/all of/exists/not exists/before/after） |
是 | - | 比较运算符 |
cases[].conditions[].value |
string / string[] / boolean | 是（除 empty/notEmpty 等空值相关运算符） | - | 比较值 |
cases[].conditions[].sub_variable_condition |
CaseItem（递归） | 否 | - | 子变量条件（嵌套） |
| ELSE | 自动暴露 false 分支 |
- | - | 不满足所有 case 时走 ELSE |
3.8 Code code
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
variables |
Variable[]（每项 variable 名 + value_selector） |
否（每项名/值必填） | [] |
输入变量 |
code_language |
CodeLanguage(python3/javascript/json) |
否 | python3 |
语言（panel 仅展示 Python3、JavaScript） |
code |
string（code-editor） | 是 | '' |
代码 |
outputs |
OutputVar（Record）
| 否 | {} |
输出变量声明 |
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
variables |
Variable[] |
否（每项名/值必填） | [] |
输入变量 |
template |
string（Jinja2 code-editor） | 是 | '' |
模板代码（Jinja2 语法） |
固定输出：output(string)。
3.10 HTTP Request http-request
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
method |
Method(get/post/head/patch/put/delete) |
否 | get |
HTTP 方法 |
url |
string | 是 | '' |
API 地址 |
variables |
Variable[]（用于 url/headers/params 插值） |
否 | [] |
输入变量 |
authorization.type |
AuthorizationType(none/apiKey) |
否 | none |
鉴权类型 |
authorization.config |
{type: basic/bearer/custom, api_key, header} | apiKey 时必填 | null |
鉴权配置 |
headers |
string（key-value 表格） | 否 | '' |
请求头 |
params |
string | 否 | '' |
查询参数 |
body.type |
BodyType(none/form-data/x-www-form-urlencoded/raw-text/json/binary) |
否 | none |
请求体类型 |
body.data |
BodyPayload[]（id/key/type[text|file]/value/file）或 string（旧） |
否 | [] |
请求体内容 |
ssl_verify |
boolean | 否 | true |
SSL 校验 |
timeout.max_connect_timeout / max_read_timeout / max_write_timeout |
number（毫秒） | 否 | 0（不限） | 超时 |
retry_config.retry_enabled |
boolean | 否 | true |
启用重试 |
retry_config.max_retries |
number | 否 | 3 |
最大重试次数 |
retry_config.retry_interval |
number（毫秒） | 否 | 100 |
重试间隔 |
固定输出：body(string)、status_code(number)、headers(object)、files(array[file])。
3.11 Tool（工具）tool
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
provider_id |
string | 是 | - | 工具供应商 ID |
provider_type |
CollectionType(builtIn/custom/workflow/mcp) |
是 | - | 工具类型 |
provider_name |
string | 是 | - | 供应商名 |
tool_name |
string | 是 | - | 工具名 |
tool_label |
string | 是 | - | 工具显示名 |
tool_parameters |
ToolVarInputs（Record）
| 视 schema required | {} |
工具参数（动态） |
tool_configurations |
Record<string, any> |
视 settingSchema required | {} |
工具配置 |
tool_node_version |
string | 否 | '2' |
工具节点版本 |
plugin_id / plugin_unique_identifier |
string | 否 | - | 插件标识 |
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
query |
ValueSelector | 是 | [] |
输入变量 |
model |
ModelConfig | 是（provider 必填） | {provider:'', name:'', mode:CHAT, completion_params:{temperature:0.7}} |
模型 |
reasoning_mode |
ReasoningModeType(prompt/function_call) |
否 | prompt |
推理模式 |
parameters |
Param[]（name/type/options/description/required） |
是（至少 1 个；name/type/description 必填） | - | 提取参数定义 |
parameters[].type |
ParamType(string/number/boolean/select/array[string]/array[number]/array[object]/array[boolean]) |
是 | - | 参数类型 |
instruction |
string | 否 | - | 高级指令 |
memory / vision |
同 LLM | 否 | - | - |
输出：每个 parameter 名 + 公共 __is_success(number)、__reason(string)、__usage(object)。
3.13 Iteration（迭代）iteration
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
start_node_id |
string | 自动 | '' |
内部 start 节点 ID |
iterator_selector |
ValueSelector | 是 | [] |
输入（要迭代的数组） |
iterator_input_type |
VarType | - | - | 输入类型缓存 |
output_selector |
ValueSelector | 是 | [] |
输出（迭代内部产出的变量） |
output_type |
VarType | - | - | 输出类型 |
is_parallel |
boolean | 否 | false |
并行模式 |
parallel_nums |
number | 否 | 10 |
并行数 |
error_handle_mode |
ErrorHandleMode(terminated/continue-on-error/remove-abnormal-output) |
否 | terminated |
错误处理模式 |
flatten_output |
boolean | 否 | true |
是否展平输出 |
特点：
isTypeFixed: true，内含独立子工作流（含iteration-start）。
3.14 Loop（循环）loop
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
start_node_id |
string | 自动 | '' |
内部 start 节点 ID |
loop_count |
number（1 ≤ n ≤ LOOP_NODE_MAX_COUNT） | 是 | 10 |
循环次数 |
loop_variables |
LoopVariable[]（id/label/var_type/value_type/value） |
否（每项 label 必填） | - | 循环变量（迭代间持久化） |
break_conditions |
Condition[]（同 if-else Condition 结构） |
是（每项变量/运算符必填） | [] |
中断条件 |
logical_operator |
LogicalOperator | 否 | and |
多个中断条件之间的逻辑运算符 |
error_handle_mode |
ErrorHandleMode | 否 | - | 错误处理模式 |
特点：
isTypeFixed: true，含loop-start自动节点。
3.15 Loop End / Loop Start / Iteration Start
均为自动辅助节点，无配置字段（默认值 {}，checkValid 永远返回 isValid: true）。loop-end 元数据 isSingleton: true。
3.16 Variable Aggregator / Variable Assigner variable-aggregator（目录 variable-assigner）
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
output_type |
VarType | 否 | any |
输出类型 |
variables |
ValueSelector[]（不启用分组时） |
是（至少 1 个且非空） | [] |
聚合的变量列表 |
advanced_settings.group_enabled |
boolean | 否 | false |
启用分组 |
advanced_settings.groups |
({group_name, groupId, output_type, variables: ValueSelector[]})[] |
group_enabled 时必填（至少 1 组） | [] |
分组（每组独立聚合） |
3.17 Variable Assigner（变量赋值 v2）assigner
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
version |
'1' \| '2' |
否 | '2' |
版本 |
items |
AssignerNodeOperation[] |
是（每项校验） | [] |
赋值操作列表 |
items[].variable_selector |
ValueSelector | 是 | - | 被赋值变量（须指向会话变量） |
items[].input_type |
AssignerNodeInputType(variable/constant) |
- | - | 输入类型 |
items[].operation |
WriteMode(over-write/clear/append/extend/set/+=/-=/*=//= /remove-first/remove-last) |
是 | - | 写入模式 |
items[].value |
any / ValueSelector | 视 operation（除 clear/removeFirst/removeLast 外必填） | - | 设置值 |
3.18 Document Extractor（文档提取器）document-extractor
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
variable_selector |
ValueSelector（file 或 array[file]） | 是 | [] |
输入变量 |
is_array_file |
boolean | 否 | false |
是否数组文件 |
3.19 List Operator / List Filter list-operator
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
variable |
ValueSelector | 是 | [] |
输入变量（数组） |
var_type / item_var_type |
VarType | - | - | 类型缓存 |
filter_by.enabled |
boolean | 否 | false |
启用过滤 |
filter_by.conditions |
Condition[]（key/comparison_operator/value） |
启用时第一项的 key/operator 必填 | [] |
过滤条件 |
extract_by.enabled |
boolean | 否 | false |
启用抽取 |
extract_by.serial |
string（'1'/first/last/...） | 否 | '1' |
抽取序号 |
order_by.enabled |
boolean | 否 | false |
启用排序 |
order_by.key |
ValueSelector | string | 否 | '' |
排序键 |
order_by.value |
OrderBy(asc/desc) |
否 | ASC |
升降序 |
limit.enabled |
boolean | 否 | false |
启用限制 |
limit.size |
number | 否 | 10 |
限制数量 |
3.20 Human Input（人工介入）human-input
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
delivery_methods |
DeliveryMethod[]（id/type[webapp/email/slack/teams/discord]/enabled/config） |
是（至少 1 个启用；邮件需 subject/body 含 {{#url#}} + recipients 完整） |
[] |
通知方式 |
form_content |
string | 否 | '' |
表单内容（说明文字） |
inputs |
FormInputItem[]（type=paragraph/select/file/file-list；每项含 output_variable_name） |
否 | [] |
表单字段定义 |
user_actions |
UserAction[]（id/title/button_style[primary/default/accent/ghost]） |
是（至少 1 个；id/title 不能空且 id 不能重复） | [] |
用户操作按钮（决定分支） |
timeout |
number | 否 | 3 |
超时数值 |
timeout_unit |
'hour' \| 'day' |
否 | 'day' |
超时单位 |
输出：每个 input 的 output_variable_name（类型按 input.type 映射）。
3.21 Agent（旧版）agent
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
agent_strategy_provider_name |
string | 是（动态） | - | 策略供应商 |
agent_strategy_name |
string | 是 | - | 策略名 |
agent_strategy_label |
string | - | - | 策略显示名 |
agent_parameters |
ToolVarInputs |
动态（按策略 parameters 中 required） | - | 策略参数（含 model selector / tool selector 等） |
output_schema |
Record | - | - | 输出 schema |
memory |
Memory | 否 | - | 记忆 |
version / tool_node_version |
string | 否 | '2' |
版本 |
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
agent_binding |
AgentBinding（binding_type: roster_agent/inline_agent + agent_id + current_snapshot_id） |
是（必须有效） | {binding_type:'inline_agent'} |
Agent 绑定 |
agent_node_kind |
'dify_agent' |
- | 'dify_agent' |
节点种类 |
version |
'2' |
- | '2' |
版本 |
agent_task |
string | 否 | - | Agent 任务描述 |
agent_declared_outputs |
DeclaredOutputConfig[] |
否 | - | 声明的输出配置 |
校验：
hasValidAgentBinding（roster_agent 须有 agent_id；inline_agent 须有 agent_id + current_snapshot_id）。
3.23 Knowledge Base（知识库）knowledge-index
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
index_chunk_variable_selector |
string[] | 是 | [] |
待索引块变量 |
keyword_number |
number | 否 | 10 |
关键词数量 |
retrieval_model.top_k |
number | 否 | 3 |
top_k |
retrieval_model.score_threshold_enabled |
boolean | 否 | false |
启用分数阈值 |
retrieval_model.score_threshold |
number | 否 | 0.5 |
分数阈值 |
chunk_structure / indexing_technique / embedding_model / embedding_model_provider / summary_index_setting |
object/string | 否 | - | 索引细节 |
元数据：
isRequired、isUndeletable、isSingleton、isTypeFixed。
3.24 Data Source datasource
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
plugin_id |
string | 是 | '' |
插件 ID |
provider_type |
DatasourceProviderType（含 local_file） |
是 | - | 供应类型 |
provider_name |
string | 是 | - | 供应商名 |
datasource_name |
string | 是 | - | 数据源名 |
datasource_label |
string | - | - | 数据源显示名 |
datasource_parameters |
ToolVarInputs |
动态（按 dataSourceInputsSchema required） | {} |
数据源参数 |
datasource_configurations |
Record | 否 | {} |
数据源配置 |
fileExtensions |
string[] | 否 | - | 文件扩展名（local_file 时） |
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
mode |
'visual' \| 'cron' |
是 | getDefaultScheduleConfig() |
调度模式 |
frequency |
'hourly' \| 'daily' \| 'weekly' \| 'monthly' |
visual 时必填 | - | 频率 |
cron_expression |
string（合法 cron） | cron 模式必填 | '' |
cron 表达式 |
visual_config.time |
string（h:mm AM/PM） |
daily/weekly/monthly 必填 | - | 时间 |
visual_config.on_minute |
number（0-59） | hourly 必填 | - | 分钟 |
visual_config.weekdays |
string[]（sun/mon/.../sat） | weekly 必填 | - | 星期 |
visual_config.monthly_days |
(number \| 'last')[]（1-31 或 'last'） |
monthly 必填 | - | 日期 |
timezone |
string（合法 IANA 时区） | 否（自动填充） | - | 时区 |
3.26 Trigger Webhook trigger-webhook
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
webhook_url |
string | 是 | '' |
Webhook URL（系统生成） |
webhook_debug_url |
string | 否 | - | 调试 URL |
method |
HttpMethod(GET/POST/PUT/DELETE/PATCH/HEAD) |
否 | POST |
接收的 HTTP 方法 |
content_type |
string | 否 | application/json |
Content-Type |
headers |
WebhookHeader[]（name/required） |
否 | [] |
期望的请求头 |
params |
WebhookParameter[]（name/type/required） |
否 | [] |
查询参数声明 |
body |
WebhookParameter[] |
否 | [] |
请求体参数声明 |
async_mode |
boolean | 否 | true |
异步模式 |
status_code |
number | 否 | 200 |
响应状态码 |
response_body |
string | 否 | '' |
响应体模板 |
variables |
Variable[]（含一个 raw variable 默认项） |
否 | [createWebhookRawVariable()] |
输出变量声明 |
3.27 Trigger Plugin trigger-plugin
| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
provider_id / provider_type / provider_name |
string/enum | 是 | - | 插件供应信息 |
plugin_id |
string | 是 | '' |
插件 ID |
event_name / event_label |
string | 是 | '' |
事件名 |
event_parameters |
PluginTriggerVarInputs |
动态（按 triggerInputsSchema required） | {} |
事件参数 |
event_configurations |
Record | 否 | - | 事件配置 |
output_schema |
Record | - | - | 输出 schema |
subscription_id |
string | 是 | - | 订阅实例 ID |
config |
Record | 否 | {} |
兼容字段 |
| 字段 | 类型 | 含义 |
|---|---|---|
title / desc |
string | 节点标题与描述（用户可编辑） |
type |
BlockEnum | 节点类型 |
selected |
boolean | 是否选中 |
width / height / position |
number / XYPosition | 画布位置尺寸 |
isInIteration / iteration_id |
boolean / string | 是否在迭代节点内 |
isInLoop / loop_id |
boolean / string | 是否在循环节点内 |
error_strategy |
ErrorHandleTypeEnum(none/fail-branch/default-value) |
错误处理策略 |
retry_config |
WorkflowRetryConfig{retry_enabled, max_retries, retry_interval} |
重试配置 |
default_value |
DefaultValueForm[]{key, type, value} |
错误处理为 default-value 时的默认值 |
credential_id / subscription_id / provider_id |
string | 凭证/订阅/供应商 |
_isSingleRun / _runningStatus 等 |
various | 运行时内部状态 |
4.2 异常处理 / 重试 / 超时
| 项 | 取值 | 出处 |
|---|---|---|
错误处理策略 ErrorHandleTypeEnum |
none / fail-branch / default-value |
_base/components/error-handle/types.ts |
错误处理模式 ErrorHandleMode（迭代/循环节点） |
terminated / continue-on-error / remove-abnormal-output |
nodes/_base/types.ts |
重试配置 WorkflowRetryConfig |
{retry_enabled, max_retries, retry_interval} |
_base/components/retry/types.ts |
| 全局默认重试 | DEFAULT_RETRY_MAX = 3，DEFAULT_RETRY_INTERVAL = 100（ms） |
web/app/components/workflow/constants.ts:296-297 |
| HTTP 节点私有重试 | retry_enabled: true, max_retries: 3, retry_interval: 100 |
nodes/http/default.ts |
| HTTP 节点私有超时 | timeout.{max_connect_timeout, max_read_timeout, max_write_timeout}（ms，默认 0 = 不限） |
nodes/http/default.ts |
UI 入口：_base/components/error-handle/error-handle-on-panel.tsx 与 _base/components/retry/retry-on-panel.tsx，各节点 panel 直接引入。
4.3 输出变量声明机制（三种）
静态固定输出（
constants.ts中的*_OUTPUT_STRUCT常量）：LLM_OUTPUT_STRUCT：text / reasoning_content / usageKNOWLEDGE_RETRIEVAL_OUTPUT_STRUCT：resultTEMPLATE_TRANSFORM_OUTPUT_STRUCT：outputQUESTION_CLASSIFIER_OUTPUT_STRUCT：class_name / class_label / usageHTTP_REQUEST_OUTPUT_STRUCT：body / status_code / headers / filesTOOL_OUTPUT_STRUCT：text / files / jsonHUMAN_INPUT_OUTPUT_STRUCT：__action_id / __action_value / __rendered_contentPARAMETER_EXTRACTOR_COMMON_STRUCT：__is_success / __reason / __usageAGENT_OUTPUT_STRUCT：text / files / jsonFILE_STRUCT：name/size/type/extension/mime_type/transfer_method/url/related_idSUPPORT_OUTPUT_VARS_NODE（constants.ts:103-125）声明哪些节点能被其他节点引用输出
用户在节点面板中声明：
- Code 节点
outputs: Record<varName, {type}> - End 节点
outputs: Variable[] - Parameter Extractor
parameters: Param[]（每个 param.name 成为一个输出） - Question Classifier
classes（每个 class 一个分支，输出仍为 class_name） - Human Input
inputs（每个 input 的output_variable_name） - Trigger Webhook
variables
- Code 节点
动态从插件 / tool 的
output_schema推断：- Tool 节点：从
output_schema.properties解析（tool/default.ts的getOutputVars），叠加默认 TOOL_OUTPUT_STRUCT - Data Source 节点：从
output_schema解析（data-source/default.ts），叠加 COMMON_OUTPUT / LOCAL_FILE_OUTPUT / ragVars - Trigger Plugin 节点：从
output_schema解析（trigger-plugin/default.ts），支持嵌套（递归convertJsonSchemaToField）
- Tool 节点：从
NodeDefault.getOutputVars(payload, allPluginInfoList, ragVariables, utils) 是统一的输出变量计算入口。
4.4 节点元数据特性（genNodeMetaData）
| 字段 | 含义 |
|---|---|
classification |
分类（默认 -） |
sort |
同分类内的排序值 |
type |
BlockEnum |
title |
默认标题（多数为空，靠 i18n 渲染） |
author |
默认 'Dify'（Loop 节点为 'AICT-Team'） |
helpLinkUri |
文档锚点 |
isRequired |
是否必需（answer/knowledge-base/datasource 为 true） |
isUndeletable |
不可删除（knowledge-base、datasource-empty） |
isStart |
是否可作为起始（start、start-placeholder、3 个 trigger、datasource） |
isSingleton |
画布上唯一（start、start-placeholder、loop-end、knowledge-base、datasource-empty） |
isTypeFixed |
类型不可切换（start-placeholder、iteration、loop、knowledge-base、datasource-empty） |
4.5 节点目录约定
nodes/<type>/
├── default.ts # 元数据 + 默认值 + checkValid + getOutputVars
├── types.ts # TypeScript 类型定义
├── panel.tsx # 详情面板组件（右侧抽屉）
├── node.tsx # 画布上的节点卡片渲染
├── index.tsx # 导出入口（部分节点）
└── components/ # 面板内子组件（部分节点）
4.6 校验机制
每个节点的 default.ts 导出 checkValid(payload, t, moreDataForCheckValid?)，返回 {isValid, errorMessage}。共同模式：
- 必填字段：
t('errorMsg.fieldRequired', {field: ...}) - i18n 前缀：部分节点用
'errorMsg'，部分用空字符串拼接'errorMsg.xxx'
4.7 字段组件库（_base/components/）
| 组件 | 用途 |
|---|---|
field.tsx |
字段容器（title/required/tooltip/operations） |
selector.tsx |
下拉选择 |
input-number-with-slider.tsx |
数字 + 滑块 |
input-support-select-var.tsx |
文本输入 + 变量引用切换 |
readonly-input-with-select-var.tsx |
只读输入 + 变量引用 |
variable/var-list.tsx |
变量列表 |
variable/var-reference-picker.tsx |
变量引用选择器 |
variable/output-var-list.tsx |
输出变量声明列表 |
editor/code-editor.tsx |
代码编辑器（Python/JS/Jinja2） |
config-vision.tsx |
视觉配置 |
memory-config.tsx |
记忆配置 |
file-upload-setting.tsx |
文件上传设置 |
prompt/ |
提示词编辑器 |
error-handle/error-handle-on-panel.tsx |
错误处理 |
retry/retry-on-panel.tsx |
重试配置 |
4.8 内置变量与系统变量
- Start 节点自动暴露：
userinput.query（chat 模式 String）、userinput.files（Array[File]） - 系统全局变量（
constants.ts:35-76的getGlobalVars）：sys.dialogue_count、sys.conversation_id、sys.user_id、sys.app_id、sys.workflow_id、sys.workflow_run_id、sys.timestamp
- VAR_SHOW_NAME_MAP：
sys.query→ query、sys.files→ files
4.9 节点版本兼容
| 节点 | 版本字段 |
|---|---|
tool |
tool_node_version: '2'（默认） |
assigner |
version: '2' |
agent-v2 |
version: '2'、agent_node_kind: 'dify_agent' |
| LLM prompt | 旧版 edition_type: 'basic' vs 新版 'jinja2' |
5. 与本仓库（agent-management）的对照
平台（极智）和 Dify 在工作流节点体系上高度相似——本仓库在做工作流引擎 / 节点 schema 设计时可作如下对照。
| 维度 | 极智平台（参考 jizhi-platform-reference.md） |
Dify（本文档） |
|---|---|---|
| 节点类型数 | 26 | 31（含辅助 / 占位节点） |
| 分类 | 基础 / 问题处理 / 逻辑 / 工具 / 文件 / 转换（6 类） | 默认 / 问题理解 / 逻辑 / 转换 / 工具（5 类） |
| 大模型节点 | 模型 / 短期记忆 / 流式 / JSON / 温度 / 思考模式 / 思考级别 / 系统提示 / 用户输入 / 异常处理 | 模型 / prompt_template（basic+jinja2） / context / memory / vision / structured_output / reasoning_format + 异常处理 |
| 异常处理 | 处理方式（无 / 默认值 / 异常分支） + 最大重试次数 | error_strategy（none / fail-branch / default-value） + retry_config（retry_enabled / max_retries / retry_interval） |
| 知识库检索 | 知识库选择 + 推测字段 | query / dataset_ids / retrieval_mode / 重排序 / 元数据过滤（完整字段化） |
| 条件分支 | 条件表达式（多分支） | cases（IF + ELIF*）+ 隐式 ELSE + 子变量嵌套条件 |
| 迭代 | 输入列表 + 模式 + 并发 + 子图 | iterator_selector + output_selector + is_parallel + parallel_nums + error_handle_mode + flatten_output |
| 工具调用 | 工具选择 + Schema 参数 | provider_id/type/name + tool_parameters（动态） + tool_configurations |
| HTTP 请求 | URL / Method / 重试 / 超时 | method/url/auth/headers/params/body/ssl_verify/timeout（3 项）/retry_config |
| 人工确认 | 提示文案 + 交互方式 + 超时 + 默认值 | delivery_methods + form_content + inputs + user_actions + timeout |
| 数据查询 | 自动 SQL / 手动 SQL | （Dify 通过 Tool / Data Source 节点承载，无独立"数据查询"节点） |
| 触发器 | （自动化模块独立承载，无独立触发节点） | trigger-schedule / trigger-webhook / trigger-plugin（节点级别） |
| 输出变量声明 | 每节点固定输出 + 用户在节点内声明 | 三种机制：固定常量 / 用户面板声明 / output_schema 动态推断 |
设计建议（落地到 agent-management 时）
- 节点 schema 统一用 TS 类型 + zod 校验：参考 Dify 的
types.ts+default.ts中checkValid模式，每个节点单独目录维护。 - 字段组件库优先抽象：var-reference / var-list / prompt-editor / code-editor / model-selector / error-handle / retry 等通用组件应抽到
_base/components/，避免每个节点重复实现。 - 输出变量声明支持三种模式：固定 / 用户声明 / schema 推断——对工具型节点（如 HTTP / Tool）尤其重要。
- 错误处理 + 重试在节点级别通用化：避免每个节点单独定义。
- 触发器 / Start 节点的
isStart、isRequired、isSingleton、isTypeFixed元数据：用于编排器自动约束（如 Start 只能有一个、Knowledge-Index 类型不可切换）。
6. 覆盖完整性核对
BlockEnum 共 31 个枚举值（types.ts:27-60），本报告全部覆盖：
- ✅ Start, StartPlaceholder, End, Answer, LLM, KnowledgeRetrieval, QuestionClassifier, IfElse, Code, TemplateTransform, HttpRequest
- ✅ VariableAssigner, VariableAggregator（共用
variable-assigner目录）, Tool, ParameterExtractor - ✅ Iteration, DocExtractor, ListFilter, IterationStart, Assigner
- ✅ Agent, AgentV2, Loop, LoopStart, LoopEnd
- ✅ HumanInput, DataSource, DataSourceEmpty, KnowledgeBase
- ✅ TriggerSchedule, TriggerWebhook, TriggerPlugin
每个节点都列出了：源码相对路径、字段表（变量名 / 类型 / 必填 / 默认 / 说明）、所属分类、元数据特性（isRequired / isSingleton / isTypeFixed 等）。