← 返回文章列表
Dify 节点设计手册发布于 2026-09-01
Dify 节点全景图：20 个节点、7 个功能族、3 个通用设计问题
📖 摘要：Dify 工作流有 20 个节点，分布在 7 个功能族。本文是《Dify
节点设计手册》系列的开篇——先给你一张节点地图（每个节点两句话：干什么 +
最容易犯的错），再给三个设计任何节点都要先回答的问题（输入契约 /
输出契约 / 失败兜底），最后给一套节点级验证的总方法（三层排查 +
取证命令）。后续 8 篇按功能族逐族展开，每篇都有实测数据和踩坑记录。
📌 本文要解决的核心痛点
- 刚接触 Dify，20 个节点不知道从哪下手、各自干什么？
- 设计一个节点时，该先想什么？为什么总在运行时才发现「类型不对 /
字段没映射 / 失败没兜底」？
- 节点跑挂了，怎么快速定位是格式问题、运行问题还是逻辑问题？
- 本文给一张 7 族 20 节点的地图 + 三个通用设计问题 +
三层验证方法——先把骨架立起来，后面 8 篇按族深入。
一、节点全景图是干什么的
这是《Dify 节点设计手册》系列的开篇。整个系列解决一个问题：用
Dify 做交付时，每个节点怎么设计才稳、怎么验证才信得过。
本系列不是功能说明书（节点有哪些字段看官方文档就行），而是设计方法——每个节点给出：干什么用、设计模式（输入/输出/兜底）、实测踩过的坑、怎么验证。所有内容来自真实实验：8
组节点级实验（E1-E8）+ 200 余次工作流构建与验收记录，全部基于 Dify
1.16.1。
本文只做三件事：
| 你要带走什么 |
在哪 |
| 一张节点地图（20 个节点，两句话一个） |
第二节 |
| 三个设计任何节点都要先回答的问题 |
第三节 |
| 一套节点级验证的总方法 |
第四节 |
三件事做完，你就有了系列的地图——后面每一篇都是这张地图上某个功能族的放大。
二、20 个节点分类地图（7
个功能族）
Dify 1.16.1 的节点按功能分 7
族。每个节点给两句话：干什么 +
最容易犯的错（深度在后续对应篇展开）。
内容生成（1 个）
| 节点 |
干什么 |
最容易犯的错 |
| LLM |
理解与生成的引擎——把输入文本变成输出文本 |
占位符引用格式不对（必须
{{#节点.字段#}}）；模板化生成任务不关思考，推理模型吃光
token 输出空 |
知识接入（1 个）
| 节点 |
干什么 |
最容易犯的错 |
| 知识检索 |
把外部知识库的内容带进对话——RAG 的核心入口 |
query
变量忘配；检索配置时序不对（建库后不立即配，跑默认配置）；中文检索口语化
query 召回为零（BM25 无分词） |
决策路由（2 个）
| 节点 |
干什么 |
最容易犯的错 |
| 问题分类 |
按意图把请求分到不同处理链——工作流的「交警」 |
instruction 不强制 JSON 输出，分类概率性失败（实测曾 33%
失败率）；下游共享普通节点导致多分支同时执行 |
| 条件分支 |
按条件真假分流（if-else） |
比较运算符用 ASCII 符号（>= 而非
≥）；分支条件漏写导致逻辑分支成死代码 |
数据操作（5 个）
| 节点 |
干什么 |
最容易犯的错 |
| 代码执行 |
确定性计算——Python 沙箱，清洗/解析/校验/组装 |
变量名与函数参数名不一致（按名传参）；正则双重转义（\d
写成了 \\d 匹配不到数字，PII 脱敏静默失效） |
| 模板转换 |
文本模板格式化（Jinja 语法） |
上游字段为空时除零/引用报错；输出字段格式不对 |
| 变量聚合 |
把多个分支/来源的变量合并成一个 |
共享参数节点放在分流之后，两个分支都执行；variables
嵌套数组格式写错 |
| 变量赋值 |
更新会话变量/循环状态——记忆与累积的机制 |
忘写 version: "2"（按 v1 解析直接报错）；不知道有 10
种操作（append/extend/over-write 等） |
| 列表操作 |
数组过滤/排序/截断/取第一个 |
1.16.1 对 object 数组输入不识别为数组（实测报错）；排序枚举必须小写
asc/desc |
外部交互（4 个）
| 节点 |
干什么 |
最容易犯的错 |
| HTTP 请求 |
调用外部 API——取数/回调/通知 |
漏配 fail 分支（外部失败直接阻断主流程）；SSRF/网络白名单没考虑 |
| 工具 |
调用插件工具或子工作流发布成的工具 |
子工作流改了配置不重建工具，旧工具跑旧配置；重建后 provider_id
变了，调用方没同步 |
| Agent 节点 |
自主选择工具完成多步任务 |
当 LLM 用（实测同任务 prompt token 开销是 LLM 的 18 倍）；model
参数必须是 model-selector 结构（写错报「Model required」） |
| 外部数据源 |
把外部数据（Notion/爬虫/API）作为变量引入 |
没装数据源插件时静默不赋值——引用它的模板原样输出，不报错 |
流程编排（5 个）
| 节点 |
干什么 |
最容易犯的错 |
| 迭代 |
遍历数组逐条处理（for-each） |
循环体链尾多加一条「回容器」边，容器静默不执行（无报错） |
| 循环 |
条件循环（while）——重试/收敛/累加 |
break 条件运算符必须 Unicode（≥ 非
>=）；loop_variables
初始值用字符串报错（要用数字字面量） |
| 定时触发 |
到点自动跑工作流（日报/巡检/看板） |
时间不支持 24 小时制（"14:30" 报错）；时区默认 UTC
不是北京时间 |
| 子工作流 |
把一段流程发布成工具复用——拼装式交付 |
发布为工具后，改子工作流配置必须删旧重建（缓存旧配置）；调用方
provider_id 连锁更新 |
| 人工输入 |
工作流暂停，人工填表审批后继续（HITL） |
delivery_methods 不配（没有收件人，无法提交）；Service API
触发后恢复执行有竞态（实测 3 次 2 成 1 败） |
输入处理（2 个）
| 节点 |
干什么 |
最容易犯的错 |
| 参数提取 |
从非结构化文本里提取结构化字段（姓名/电话/订单号） |
instruction
不写防幻觉约束（没提到也编造填值）；「空」的形态不统一（防幻觉输出
"null"，宽松输出 ""，下游判空要兼容两种） |
| 文档提取器 |
提取上传文件（txt/pdf/docx）的文本内容 |
文件链路用 chatflow 的 sys.files 实测静默失败（200
但文件不进）；可靠路径是 workflow 模式 + start 文件变量 |
说明：IO 节点（开始/结束/答案）
开始、结束、答案三个节点是 IO
基础件，本系列不单独展开——只提几条铁律：start 变量没有 boolean
类型（复选框是 checkbox）；多个 end
节点的输出变量名必须唯一；答案节点不支持 Jinja
过滤器（格式化交给代码节点）。
三、通用设计三问（设计任何节点前先过）
设计一个节点（或审查一个工作流里的节点）时，永远先回答三个问题。三个问题答完，80%
的运行时缺陷在设计阶段就被排掉了。
第一问：输入契约是什么——这个节点吃什么？
| 检查项 |
说明 |
| 变量类型 |
引用上游时类型要匹配（start 没有 boolean/array；数组数据源必须 code
节点产出） |
| 引用格式 |
模板里 {{#节点id.字段#}}
全限定；code/模板节点的变量映射要声明 |
| 判空 |
上游可能为空/未执行（多分支场景，未执行分支的变量引用要防呆） |
第二问：输出契约是什么——这个节点吐什么？
| 检查项 |
说明 |
| 字段结构 |
输出字段名/类型与下游消费一致（code 输出 object
字段只给代码/模板消费，LLM 模板引用要展平） |
| 唯一性 |
多个 end 节点的输出变量名必须唯一（否则校验不过） |
| 可观测性 |
每个出口有明确输出变量名且语义唯一（验收报告最先写的缺陷就是可观测性不足） |
第三问：失败兜底——挂了怎么办？
| 检查项 |
说明 |
| 显式出口 |
错误/降级路径有显式出口（HTTP fail 分支可达
end，异常分支不悬空） |
| 静默失败最危险 |
三个典型：LLM 变量不映射（占位符原样输出）、mock
类型不一致、校验透传——「系统照常运行但结果错」 |
| 确定性优先 |
判定性输出用确定性节点（代码/规则）承载，别交给 LLM——LLM
是理解与生成的引擎，不是流程控制者 |
四、节点级验证总方法（三层排查）
节点跑挂了，先分清楚是哪一层的问题——三层根因完全不同，排查路径完全不同：
| 层 |
特征 |
排查方式 |
| 导入层 |
导入/渲染报错（格式/字段/类型） |
python check_dsls.py <file> 静态检查（DSL
格式校验脚本） |
| 运行层 |
运行中节点失败（变量引用无效/代码异常/LLM 思考污染） |
节点执行日志（node-executions）+ 代码本地自测 |
| 逻辑层 |
跑通但结果错（分支条件错误/Agent 幻觉/检索不命中） |
对照设计链路逐节点核对 + 确定性节点输出字节级比对 |
取证命令（两条核心）：
| 取证方式 |
用法 |
| console node-executions |
GET /apps/{app_id}/workflow-runs/{run_id}/node-executions——每个节点的状态/耗时/输出/错误 |
| DB 直查 |
workflow_runs（输入/输出）→
workflow_node_executions（节点级输出，确定性节点字节级比对）——列表接口排序不可信时
DB 直查最可靠 |
三条验证纪律（实测教训）：
| 纪律 |
为什么 |
| 概率性问题多次采样 |
LLM 类节点单次通过不可信（同输入 5 次全过才算修好）——PE 防幻觉、QC
分类都吃过单次通过的亏 |
| 看节点输出，别看最终答案 |
只看最终回答会误判（回答是 LLM
生成的，可能抄系统提示词里的兜底文案）——要查确定性节点的真实输出 |
| 配置类功能双路径验证 |
Service API 冒烟 + UI 导出回读比对（API 全过 ≠ UI
可用——文件类型白名单就是 API 放行、UI 拦截的典型） |
五、系列地图（后面 8 篇去哪看）
| 篇 |
功能族 |
你做什么功能时看它 |
| 二 |
内容生成：LLM 节点 |
任何要让模型生成内容的工作流（报告/改写/问答） |
| 三 |
知识接入：知识检索 |
做知识库问答、RAG 检索调优 |
| 四 |
决策路由：问题分类 + 条件分支 |
工作流要按意图/条件分流 |
| 五 |
数据操作：代码/模板/聚合/赋值/列表 |
数据处理、清洗、格式变换、状态累积 |
| 六 |
外部交互：HTTP/工具/Agent/数据源 |
接外部系统、调 API、自主工具选择 |
| 七 |
流程编排：迭代/循环/定时/子工作流/人工输入 |
批量处理、定时任务、拼装复用、人工审批 |
| 八 |
输入处理：参数提取 + 文档提取器 |
从文本/文件里提取结构化数据 |
| 九 |
节点级验证方法论 |
验收一个应用时（验证清单总表 + 三层排查全流程） |
下一篇预告：《内容生成族：LLM
节点》——全系列核心篇。LLM
节点怎么设计才稳定：输入防护、输出约束、模型参数、错误处置、上下文管理、工具描述——六类
17 条自查清单 + 4 条进阶经验，每条都有实测证据。
