# Dify 工作流节点系统参考

> 本文件基于 `D:/projects/agent-management/dify` 1.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<varName, {type: VarType, children: null}>） | 否 | `{}` | 输出变量声明 |

### 3.9 Template Transform（模板转换）`template-transform`

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `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<name, {type: variable/constant/mixed, value}>） | 视 schema required | `{}` | 工具参数（动态） |
| `tool_configurations` | `Record<string, any>` | 视 settingSchema required | `{}` | 工具配置 |
| `tool_node_version` | string | 否 | `'2'` | 工具节点版本 |
| `plugin_id` / `plugin_unique_identifier` | string | 否 | - | 插件标识 |

**输出**：默认 `text`(string)、`files`(array[file])、`json`(array[object])；若工具有 `output_schema`，额外暴露其 properties。

### 3.12 Parameter Extractor（参数提取器）`parameter-extractor`

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `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<string, any> | - | - | 输出 schema |
| `memory` | Memory | 否 | - | 记忆 |
| `version` / `tool_node_version` | string | 否 | `'2'` | 版本 |

**固定输出**：`text`(string)、`files`(array[file])、`json`(object)（`AGENT_OUTPUT_STRUCT`）。

### 3.22 Agent V2 `agent-v2`

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `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<string, any> | 否 | `{}` | 数据源配置 |
| `fileExtensions` | string[] | 否 | - | 文件扩展名（local_file 时） |

**输出**：通用输出 + LOCAL_FILE_OUTPUT（local_file 时）+ ragVars + 动态 output_schema。

### 3.25 Trigger Schedule `trigger-schedule`

| 字段 | 类型 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `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<string, any> | 否 | - | 事件配置 |
| `output_schema` | Record<string, any> | - | - | 输出 schema |
| `subscription_id` | string | 是 | - | 订阅实例 ID |
| `config` | Record<string, any> | 否 | `{}` | 兼容字段 |

**输出**：从 `output_schema` 的 properties 动态构建（支持嵌套 object，递归 `convertJsonSchemaToField`）。

### 3.28 Empty Data Source / Start Placeholder

- `datasource-empty`：无字段，checkValid 永远通过。
- `start-placeholder`：仅含通用 `title`、`desc`，checkValid 永远返回 invalid 并提示"需要选择具体起始节点"。

---

## 4. 节点通用机制

### 4.1 所有节点隐式继承的通用字段（`CommonNodeType<T>`）

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `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 输出变量声明机制（三种）

1. **静态固定输出**（`constants.ts` 中的 `*_OUTPUT_STRUCT` 常量）：
   - `LLM_OUTPUT_STRUCT`：text / reasoning_content / usage
   - `KNOWLEDGE_RETRIEVAL_OUTPUT_STRUCT`：result
   - `TEMPLATE_TRANSFORM_OUTPUT_STRUCT`：output
   - `QUESTION_CLASSIFIER_OUTPUT_STRUCT`：class_name / class_label / usage
   - `HTTP_REQUEST_OUTPUT_STRUCT`：body / status_code / headers / files
   - `TOOL_OUTPUT_STRUCT`：text / files / json
   - `HUMAN_INPUT_OUTPUT_STRUCT`：__action_id / __action_value / __rendered_content
   - `PARAMETER_EXTRACTOR_COMMON_STRUCT`：__is_success / __reason / __usage
   - `AGENT_OUTPUT_STRUCT`：text / files / json
   - `FILE_STRUCT`：name/size/type/extension/mime_type/transfer_method/url/related_id
   - `SUPPORT_OUTPUT_VARS_NODE`（`constants.ts:103-125`）声明哪些节点能被其他节点引用输出

2. **用户在节点面板中声明**：
   - 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`

3. **动态从插件 / 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`）

`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 时）

1. **节点 schema 统一用 TS 类型 + zod 校验**：参考 Dify 的 `types.ts` + `default.ts` 中 `checkValid` 模式，每个节点单独目录维护。
2. **字段组件库优先抽象**：var-reference / var-list / prompt-editor / code-editor / model-selector / error-handle / retry 等通用组件应抽到 `_base/components/`，避免每个节点重复实现。
3. **输出变量声明支持三种模式**：固定 / 用户声明 / schema 推断——对工具型节点（如 HTTP / Tool）尤其重要。
4. **错误处理 + 重试在节点级别通用化**：避免每个节点单独定义。
5. **触发器 / 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` 等）。