Dify插件开发全解析：从环境搭建到代码实现-优快云博客

本文链接：https://blog.youkuaiyun.com/zero_forever_lzm/article/details/149499659

Dify插件开发全解析：从环境搭建到代码实现

Dify作为一款开源的LLM应用开发平台，通过插件系统实现了功能的灵活扩展。插件开发已成为Dify生态的重要组成部分，为开发者提供了构建自定义工具、模型和API服务的能力 。本文将系统阐述Dify插件开发的完整流程，包括环境准备、项目初始化、功能开发、测试验证和打包发布，并结合实际案例代码进行详细分析，帮助开发者快速掌握Dify插件开发技能。

一、Dify插件开发环境准备

开发Dify插件首先需要配置合适的开发环境，包括安装Dify插件脚手架工具和Python环境。Dify插件脚手架工具是官方提供的命令行工具，用于辅助插件开发、测试和打包。根据操作系统不同，需要下载对应版本的脚手架工具：

Windows系统：下载dify-plugin-windows-amd64.exe
Linux系统：下载dify-plugin-linux-amd64
macOS系统：下载dify-plugin-darwin-arm64

下载完成后，需赋予脚手架工具执行权限。对于Linux/macOS系统，可通过chmod +x命令实现；Windows系统则需确保文件可执行。验证工具安装是否成功，可通过执行./dify-plugin version命令查看版本信息。

Python环境要求版本≥3.12，这是Dify插件开发的最低要求。建议使用虚拟环境管理依赖，可通过以下命令创建：

python -m venv .venv  # 创建虚拟环境
source .venv/bin/activate  # 激活环境（Linux/macOS）
.\.venv\Scripts\activate  # 激活环境（Windows）

激活虚拟环境后，安装必要的依赖：

pip install dify_plugin  # 安装Dify插件开发核心包

对于Docker部署的Dify平台，还需配置镜像加速器以提高下载速度。国内常用加速器包括阿里云（https://xxx.mirror.aliyuncs.com）、腾讯云（https://mirror.ccs.tencentyun.com）和网易云（http://hub-mirror.c.163.com）等。配置方法为修改Docker配置文件，添加registry-mirrors参数。

二、Dify插件项目初始化

完成环境准备后，接下来是插件项目的初始化。Dify插件系统支持多种插件类型，包括工具(Tool)、模型LLM、Agent策略、扩展(Extension)和插件集(Bundle) 。其中工具插件是最常见的类型，用于扩展外部API调用能力。

使用脚手架工具初始化项目：

./dify-plugin plugin init

执行命令后，系统会提示输入插件名称、作者和描述信息。接着需要选择开发语言（目前仅支持Python）和插件类型。对于工具插件，需要选择"tool"类型。

初始化过程中，还需配置插件权限。工具插件必须勾选Tools、Apps和Endpoints权限，存储（Storage）和LLM模型权限则根据插件需求选择。权限配置界面可通过方向键和Tab键进行选择和确认。

项目初始化完成后，会生成标准的插件目录结构：

my-plugin/
├── .difyignore  # 插件打包时忽略的文件和文件夹
├── .env           # 插件环境配置文件
├── .env.example    # 环境配置示例文件
├── .gitignore      # Git忽略的文件和文件夹
├── GUIDE.md        # 插件使用指南
├── main.py         # 插件入口文件
├── manifest.yaml    # 插件元数据配置文件
├── PRIVACY.md      # 隐私政策声明
├── README.md        # 插件说明文档
├── requirements.txt # 插件依赖的Python包列表
├── provider/        # 插件凭证验证相关代码
└── tools/          # 插件功能实现代码

三、Dify插件功能开发

插件功能开发是核心环节，主要涉及工具类代码编写、参数配置和消息类型处理。每个Dify插件工具类都需继承自Tool基类，并实现-invoke方法处理输入参数并返回结果 。

以DeepSeek输出清洗插件为例，其核心代码如下：

from typing import Any
from difyplugin import Tool, ToolInvokeError

class DeepSeekOutputCleanerTool(Tool):
    def _invoke(self, tool_parameters: dict[str, Any]) -> Any:
        try:
            context = tool_parameters['deepseek_output']
            if '<think>' in context:
                result = context.split('<think>')[0].strip()
            else:
                result = context
            return self.create_text_message(result)
        except Exception as e:
            raise ToolInvokeError(f"Error cleaning DeepSeek output: {str(e)}")

这段代码定义了一个工具类DeepSeekOutputCleanerTool，继承自Tool基类。_invoke方法接收tool_parameters参数字典，从中获取’deepseek_output’参数，进行清洗处理，并返回清洗后的文本消息。

插件参数配置在tools目录下的yaml文件中完成，例如：

identity:
  name: deepseek_output_cleaner
  author: song
  label:
    en_US: DeepSeek Output Cleaner
    zh_Hans: DeepSeek输出清洗器
    pt BR: DeepSeek Output Cleaner
  description:
    human:
      en_US: cleans DeepSeek model output by removing think tags
      zh_Hans: 清洗DeepSeek模型输出，移除think标签
      pt BR: cleans DeepSeek model output by removing think tags
    llm: cleans DeepSeek model output by removing think tags
parameters:
  - name: deepseek_output
    type: string
    required: true
    label:
      en_US: DeepSeek Output
      zh_Hans: DeepSeek输出内容
      pt BR: DeepSeek Output
    human_description:
      en_US: The output from DeepSeek model that needs cleaning
      zh_Hans: 需要清洗的DeepSeek模型输出
      pt BR: The output from DeepSeek model that needs cleaning
    llm_description: The output from DeepSeek model that needs cleaning
form:
  llm: |
    请提供需要清洗的DeepSeek模型输出，我将帮您移除<think>标签。
    示例输入格式：包含<think>标签的DeepSeek模型输出内容。
    示例输出格式：清洗后的纯文本内容。
extra:
  python:
    source: tools/deepseek_output_cleaner.py
    dependencies:  # 可选，指定额外依赖
      - "requests==2.26.0"

这个yaml文件定义了插件的名称、作者、多语言标签和描述，以及所需的参数（此处为’deepseek_output’字符串参数）。还配置了插件在Dify界面中的表单提示和LLM调用时的描述，以及Python实现文件的路径和依赖。

Dify支持多种消息类型返回，包括文本、链接、图片、文件BLOB和JSON等。返回JSON格式数据时，可使用create_json_message接口，这对于节点间数据传递非常有用。对于流式输出，插件需使用生成器和yield语法，示例如下：

def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:
    context = tool_parameters['text']
    for char in context:
        yield self.create_text_message(char)

四、Dify插件测试与验证

完成插件代码开发后，需要进行测试和验证。测试环境配置是确保插件正常工作的关键步骤，需要从Dify插件页面获取远程服务器地址和调试Key ，复制到插件项目的.env文件中（由.env.example重命名而来）。

配置.env文件示例：

HOST = http://localhost:5003
KEY = your Plugin Debugging Key

启动插件进行测试：

python -m main

插件成功启动后，会在Dify平台显示为"DEBUG模式"的插件。接下来可以创建工作流，添加插件节点并配置输入参数，执行工作流并验证输出是否符合预期。

测试过程中，可通过以下方式查看日志：

docker logs -f dify-plugin-daemon  # 查看Dify插件守护进程日志
docker exec -it dify-plugin-daemon tail -n 100 -f /app/logs/server.log  # 查看Dify服务器日志

若遇到插件未生效的情况，可能是由于Dify重启后Key变化导致的。此时需要重新获取Key并更新.env文件。若出现模块缺失错误（如ModuleNotFoundError），需确保在虚拟环境中安装了所有依赖（pip install -r requirements.txt）。

对于流式输出测试，需要在工作流节点中设置response_mode: streaming参数，才能触发"打字机"效果输出。对于JSON结构化输出，Dify v1.6.0版本已修复JSON输出一致性问题，确保数据传递正确。

五、Dify插件打包与发布

完成测试验证后，下一步是插件打包和发布。Dify插件打包使用脚手架工具执行：

./dify-plugin plugin package ./my-plugin

打包完成后，会在当前目录生成my-plugin.difypkg文件，这是最终的插件包。

Dify v1.6.0版本引入了插件签名验证机制，以确保插件来源可信和安全性 。若不签名直接安装，会遇到"plugin verification has been enabled, and the plugin you want to install has a bad signature"错误。解决方法有两种：

禁用签名验证（仅限测试环境）：
在Dify的.env配置文件末尾添加FORCE VerifyINGSignature=false字段，重启Dify服务。

为插件签名（推荐）：

# 生成密钥对
dify-plugin.exe signature generate -f your_key_pair

# 为插件添加签名
dify-plugin.exe signature sign my-plugin.difypkg -p your_key_pair/private.pem

# 验证签名
dify-plugin.exe signature verify my-plugin.signed.difypkg -p your_key_pair/public.pem

签名后，需要配置Dify以启用第三方签名验证：

# docker-compose.yaml配置
services:
  plugin_daemon:
    environment:
      Third_PARTYSignatureVerificationEnabled: true
      Third_PARTYSignatureVerificationPublicKeys: /app/storage/public_keys/your_key_pair.public.pem

配置完成后，重启Dify服务：

cd docker
docker compose down
docker compose up -d

插件部署到Dify平台的方式有三种：从Marketplace安装、从GitHub安装和本地插件安装。对于自定义开发的插件，通常使用本地安装方式：

在Dify平台的插件市场页面，点击"安装插件"，选择"本地插件"选项，上传生成的.difypkg或.signed.difypkg文件，完成安装。

若需将插件发布到Dify Marketplace，需遵循官方审核流程，提交插件代码、文档、许可证等材料，并通过安全检测。发布后，其他用户可通过Marketplace搜索并安装该插件。

六、Dify插件类型与实际应用案例

Dify插件系统支持多种插件类型，每种类型适用于不同的应用场景。以下是几种常见插件类型及其实际应用案例：

1. 工具插件(Tool)

工具插件是Dify中最常用的插件类型，用于扩展外部API调用能力。例如，清洗DeepSeek模型输出内容的插件，通过split操作移除标签。另一个案例是创建本地文件的插件，允许用户在工作流中生成和保存文件。

工具插件的代码结构通常包括：

class MyTool(Tool):
    def _invoke(self, tool_parameters: dict[str, Any]) -> Any:
        # 处理输入参数
        param = tool_parameters['param']

        # 执行业务逻辑
        result = process(param)

        # 返回结果
        return self.create_text_message(result)