Dify 工作流深度实践：从 DSL 设计到自定义节点开发的完全指南

Dify 正在重新定义 AI 应用的开发范式。它不仅仅是一个低代码平台，其背后是一套完整的基于图的编排系统（Graph-based Orchestration） ——用户通过拖拽节点构建逻辑，平台将其序列化为标准 JSON，再由自研的轻量级 DAG 执行引擎驱动运行。本文将从 DSL 设计、执行引擎、代码节点到自定义插件开发，深入拆解 Dify 工作流的技术内幕。

一、架构全景：前后端解耦，JSON 为桥

Dify 的核心设计哲学是 “前端只负责‘画’，后端只负责‘跑’” ：

• 前端：基于 React + xyflow（原 React Flow）构建可视化画布，提供节点拖拽、连线、配置面板等交互能力。
• 后端：用 Python 实现的轻量级 DAG 执行引擎，专为 LLM 场景优化——原生支持 token-by-token 流式响应、处理动态非结构化上下文、轻量低延迟。
• 通信契约：一份结构化的 工作流定义 JSON（即 DSL）。

前端将画布状态序列化为标准 JSON 提交给后端，后端解析 JSON 构建 DAG 并按拓扑序调度执行。这种解耦设计带来巨大灵活性——前端可换任何画布库，后端可用任何语言重写，只要双方遵守同一份 JSON 协议。

二、Workflow DSL：JSON 即代码

用户在画布上拖拽生成的每一个 Workflow，最终都会被序列化为一个 JSON 对象——这就是 Dify 的 DSL。

典型 DSL 结构包含以下核心要素：

{
  "graph": {
    "nodes": [
      {
        "id": "llm_1",
        "data": {
          "title": "LLM 节点",
          "type": "llm",
          "model": { "provider": "openai", "name": "gpt-4" },
          "prompt_template": "总结以下内容：{{#start.output#}}"
        },
        "position": { "x": 100, "y": 200 }
      }
    ],
    "edges": [
      { "source": "start", "target": "llm_1" }
    ]
  }
}

• Nodes（节点）：定义任务单元，包含 id（唯一标识）、data（业务配置，如提示词、模型参数）和 type（节点类型）。
• Edges（边）：定义控制流，即“谁执行完之后轮到谁”。
• View Data：如 position 等前端展示数据，后端解析执行时忽略，但存储时保留以还原画布。

变量引用语法 {{#node_id.output#}} 是 Dify 工作流中连接节点的核心机制。

三、执行引擎：从 JSON 到运行时

当请求到达后端时，原始的 JSON 字符串是一堆“死数据”，无法直接运行。WorkflowParser 承担了“编译器”的角色——将 JSON 解析为可执行的图结构。

执行流程四步走：

1️⃣ DAG 构建与环检测：将 JSON 转为图结构（邻接表），使用 DFS 或 Kahn 算法检测是否存在环，确保是合法 DAG。

2️⃣ 节点实例化（工厂模式）：Dify 利用工厂模式根据 DSL 中的 type 字段实例化不同的节点类。所有具体节点（如 LLMNode、CodeNode、KnowledgeRetrievalNode）都继承自 BaseNode，后者定义了所有节点必须遵守的“契约”：

# 基类中的通用执行逻辑（伪代码）
class BaseNode:
    def run(self):
        self._process_input_variables()   # 从变量池读取输入
        result = self._run()              # 子类实现具体逻辑
        self._process_output_variables(result)  # 写入变量池
        return result

3️⃣ 拓扑排序调度：按依赖顺序执行节点。节点之间不直接传递数据对象，而是通过一个共享的变量池（Variable Pool） 进行间接通信。

4️⃣ 事件生成与流式响应：执行过程中生成各类事件（NodeRunStartedEvent、NodeRunStreamChunkEvent、NodeRunSucceededEvent 等），用于状态更新和流程控制。

四、代码节点：工作流中的“瑞士军刀”

当预设节点无法满足特定处理需求时，代码节点（Code Node） 允许在工作流中嵌入自定义的 Python 或 JavaScript 脚本，处理复杂的数据转换、计算和逻辑。

代码节点依赖 沙箱服务（Sandbox） 执行，确保安全性。

配置示例：以下是一个从 HTTP 节点返回的 JSON 字符串中提取 data.name 字段的 Python 代码：

def main(http_response: str) -> str:
    import json
    data = json.loads(http_response)
    # 注意：输出变量必须声明为 'result'
    return { 'result': data['data']['name'] }

关键要点：

• 在“输入变量”中定义变量名，以访问工作流中其他节点的数据
• 在代码中通过变量名引用这些数据
• 函数必须返回一个字典，包含已声明的“输出变量”

代码节点适用于：Arithmetic 运算、JSON 数据转换、文本处理、自定义规则校验等场景。

五、自定义节点插件开发：深度扩展 Dify

当代码节点的能力仍不足以应对复杂业务时，可通过开发自定义节点插件（Custom Node Plugin） 将自主实现的逻辑单元嵌入工作流。

开发步骤：

1. 实现节点类：继承 BaseNode，实现 _run 方法
2. 定义配置 Schema：使用 Pydantic 校验前端传入的配置数据
3. 注册节点类型：将节点添加到 NODE_TYPE_CLASSES_MAPPING 字典中，使工作流引擎能够识别

Dify 的自定义节点机制支持异步处理能力，适用于大文件解析、外部 API 轮询、模型微调回调等长周期任务。

六、API 调用：将工作流嵌入业务系统

Dify 工作流可通过 REST API 被外部系统调用：

curl --request POST \
  --url https://{api_base_url}/workflows/{workflow_id}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "inputs": { "query": "Summarize this article" },
    "response_mode": "blocking",
    "user": "user_workflow_123"
  }'

response_mode 支持 blocking（阻塞等待完整结果）和 streaming（流式返回）两种模式。

官方社区维护了 Python SDK（dify-client-python），提供类型安全的 API 调用接口，覆盖 workflow run、stream、stop 等全部端点：

from dify_client import Client

client = Client(api_key="your-api-key", api_base="https://api.dify.ai/v1")
response = client.workflow_run(
    workflow_id="your-workflow-id",
    inputs={"query": "Hello, world!"},
    response_mode="blocking"
)

七、总结

Dify 工作流的技术架构可概括为 “可视化是入口，执行引擎才是灵魂” 。其核心设计围绕三个层面展开：

• DSL 层：用 JSON 描述图结构，实现“配置即代码”
• 引擎层：基于 DAG + 变量池 + 事件驱动的轻量级执行器，专为 LLM 场景优化
• 扩展层：代码节点提供脚本级定制，自定义插件实现深度扩展

未来，随着 Agent 能力增强（如自主规划、多轮反思），工作流引擎将从“线性 DAG”走向“动态状态机”。但核心思想不变——让开发者用最自然的方式编排 AI 能力，让执行引擎在后台高效可靠地运行。掌握这套技术体系，便能在 AI 应用开发的浪潮中游刃有余。