从0到1开发Dify插件：手把手教你打造第一个“文本增强器”

一、环境搭建

Dify插件开发对Python版本有硬性要求，这一点千万别忽视。

1. 使用Conda管理Python环境

首先，确保你的电脑里安装了 Python 3.12 或更高版本。低版本可能会导致兼容性问题。
强烈建议使用 Conda 来管理环境，这样可以避免依赖冲突，也能随时切换Python版本：

# 创建名为 dify-env 的虚拟环境，指定 Python 3.12
conda create -n dify-env python=3.12
#会出现Do you accept the Terms of Service (ToS) for https://repo.anaconda.com/pkgs/main? [(a)ccept/(r)eject/(v)iew]:
输入a
# 激活环境
conda activate dify-env
# 验证版本
python --version  # 应输出 Python 3.12.x

2. 安装Dify插件守护进程

这是官方提供的核心开发工具，用于本地调试和插件打包。
你需要去Dify的GitHub Releases页面下载对应系统的二进制文件。

• macOS用户：下载 dify-plugin-darwin-amd64 (或arm64) 
• Windows用户：下载 dify-plugin-windows-amd64.exe

下载完成后，需要进行两步关键操作：

macOS用户

1.  添加执行权限：在终端中运行以下命令赋予工具执行权限。

   chmod +x dify-plugin-darwin-amd64

2. 配置环境变量：为了方便在任何目录下都能使用该命令，建议将其重命名并移动到系统路径中。

   # 重命名为 dify 并移动到 /usr/local/bin
   mv dify-plugin-darwin-amd64 /usr/local/bin/dify

Windows用户

1. 创建专用文件夹（推荐）：
   在磁盘根目录创建一个专门存放工具的文件夹，例如：D:\dify-tools。
2. 移动并重命名文件：
   将你下载的 dify-plugin-windows-amd64.exe 移动到上述文件夹中，并将其重命名为 dify.exe。
3. 配置环境变量
   • 在桌面“此电脑”图标上点击右键，选择“属性”。
   • 在弹出的窗口右侧（或左侧菜单）点击“高级系统设置”。
   • 在“系统属性”窗口中，点击右下角的“环境变量”按钮。
   • 在下方的“系统变量”（或者上方的“用户变量”）区域中，找到名为 Path 的变量，选中它并点击“编辑”。
   • 新建输入刚才创建的文件夹路径，例如：D:\dify-tools

验证安装成功：

dify version

如果能看到版本信息，说明工具就位了。

3. 安装核心依赖

在编写代码之前，必须先安装 Dify 的 Python SDK，建议手动指定版本以确保兼容性（例如使用 0.7.0 版本）：

pip install dify_plugin==0.7.0

#如果你没有配置源，安装会很慢，推荐（使用清华源）
pip install dify_plugin==0.7.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

二、项目初始化

在你想存放项目的文件夹下，运行初始化命令：

dify plugin init

这时候终端会进入交互模式，按提示填写即可：

• Plugin Name：填 text-enhancer（插件唯一标识）。
• Author：填你的名字。
• Description：简单描述，比如“文本增强工具”。
• Repository URL(Optional)：回车跳过。
• Language：选 Python。
• Select Plugin Type：使用 ↑ ↓ 方向键，按 空格键 选中 Tool。
• Permissions：根据需求勾选，比如“调用外部API”等。
• 下一步配置插件的权限。因为我们要做的“文本增强工具”需要被 Dify 调用，所以必须开启 Tools 权限，如下图

• Minimal Dify version：1.0.0（设置你的插件最低需要哪个版本的 Dify 才能运行）

执行完后，当前目录下会多出一个名为 text-enhancer 的文件夹。

三、核心开发

项目生成后，我们不需要动太多文件，核心工作集中在几个关键位置。一个典型的插件项目结构如下：

text-enhancer/
├── main.py           # 核心逻辑入口
├── manifest.yaml     # 插件元信息配置
├── provider/         # 具体功能实现目录
├── tools/            # 具体功能实现目录
│   ├── text_enhancer.yaml  # 工具定义文件
│   └── text_enhancer.py    # 工具逻辑文件
├── _assets/          # 存放图标等静态资源
├── requirements.txt  # Python 依赖包列表
└── .env.example      # 环境变量配置模板

1. 编写逻辑代码

文件路径：text-enhancer/tools/text-enhancer.py

from collections.abc import Generator
from typing import Any

from dify_plugin import Tool
from dify_plugin.entities.tool import ToolInvokeMessage

class TextEnhancerTool(Tool):
    def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
        # 1. 获取参数
        # 这里的 'query' 必须和 manifest.yaml 里定义的参数名一致
        input_text = tool_parameters.get('query', '')
        
        # 2. 处理逻辑
        # 这里我们做一个简单的增强：在前面加上 "[增强后]: "
        enhanced_result = f"[增强后]: {input_text}"
        
        # 3. 返回结果
        # 我们返回一个文本消息
        yield self.create_text_message(enhanced_result)

2 .配置工具清单

文件路径：text-enhancer/tools/text-enhancer.yaml

确保 parameters 中的 query 配置正确，并修改版本号以便管理。

identity:
  version: 0.0.1             # 版本号，每次修改代码建议升级这里
  name: "text-enhancer"
  author: "gaowei"
  label:
    en_US: "text-enhancer"
    zh_Hans: "文本增强器".     #建议修改为中文

四、调试与部署

完成编码后，就可以进行本地调试和打包部署了。

1. 本地逻辑验证

在启动Dify服务进行联调之前，先写一个独立的Python脚本来验证核心逻辑。

在tools目录下创建了一个 test_logic.py 文件：

# -*- coding: utf-8 -*-
# 这是一个独立测试脚本，用来验证你的核心逻辑是否正确
# 不需要安装 dify_plugin 库即可运行

def mock_invoke_logic(tool_parameters):
    """
    这里复制了你插件中的核心逻辑
    """
    # 1. 获取参数
    input_text = tool_parameters.get('query', '')
    
    # 2. 处理逻辑 (模拟增强)
    enhanced_result = f"[增强后]: {input_text}"
    
    return enhanced_result

if __name__ == "__main__":
    print("--- 开始测试插件逻辑 ---")
    
    # 模拟 Dify 传过来的参数
    mock_params = {"query": "你好，这是测试文本"}
    
    # 调用逻辑
    result = mock_invoke_logic(mock_params)
    
    # 打印结果
    print(f"输入: {mock_params['query']}")
    print(f"输出: {result}")
    
    # 简单断言测试
    assert "[增强后]:" in result, "逻辑错误：结果中缺少前缀"
    
    print("--- 测试通过！逻辑没问题 ---")

运行脚本验证：

python test_logic.py

如果看到“测试通过”，说明处理逻辑是稳健的。

2. 打包部署

当本地调试成功后，就可以打包插件了。在项目目录上一层，运行打包命令：

dify plugin package ./text-enhancer

命令执行成功后，会生成一个 .difypkg 后缀的插件包文件。

3. 上传与验证

这是最后也是最关键的一步，我们要把打包好的文件真正用起来。

1. 上传：登录 Dify Web 界面 -> 插件 -> 安装插件 -> 选择“本地插件” -> 上传 .difypkg 文件。
2. 安装插件：上传成功后，点击“安装”，等待片刻。
3. 工作流验证：
   • 新建一个空白工作流。
   • 右击画布->添加节点->工具->下拉选择新建的工具“text-enhancer”。
   • 在节点的配置面板中，为 query 参数填入一个测试值，比如“Hello Dify”。
   • 点击“运行”按钮。
4. 结果确认：如果一切顺利，你会看到节点运行成功，并在输出结果中看到我们预期的 [增强后]: Hello Dify。这标志着你的第一个插件已经成功开发并投入使用！

五、源码探索

1.官方示例代码

如果你想参考官方写好的插件（比如 GitHub 搜索、维基百科插件）来模仿开发，可以去官方仓库拉取代码。

• SDK 源码与示例：https://github.com/langgenius/dify-plugin-sdks 
• Git 拉取命令：

  git clone https://github.com/langgenius/dify-plugin-sdks.git

用途：这个仓库里通常包含 examples 目录，你可以直接阅读里面的 tool 类插件源码。

2. 核心概念辨析

新手容易混淆 dify_plugin (Python 包) 和 dify-plugin-sdks (GitHub 仓库)，请参考下表：

特性	dify_plugin (Python 库)	dify-plugin-sdks (GitHub 仓库)
类比	汽车的引擎和底盘	驾校的教练车或汽车设计图纸
本质	Python 依赖包 (代码库)	GitHub 代码仓库 (文档与示例)
获取方式	通过 pip install dify_plugin 安装	通过 git clone 下载
作用	提供开发插件所需的基础能力（如装饰器、基类、通信协议）。你的代码必须 import 它才能运行。	提供参考代码。教你如何写 manifest.yaml，如何组织文件结构，如何处理复杂的逻辑。
你需要做什么	安装它，然后在你的代码里引用它。	阅读它，复制它的代码片段，模仿它的写法。

六、总结

至此，你的第一个 Dify 插件已经成功上线！