手把手教你做一款自己的Dify插件

Dify 是一个的开源 LLMOps 平台，支持私有化部署，平台提供了非常丰富的插件功能，用户只需要通过拖拉拽的方式，无论是对接第三方 API、实现自定义业务逻辑，还是适配专属场景需求，都能通过开发插件快速集成并定制各种功能。。本文将以「文本清洗插件」（去除DeepSeek 模型输出的冗余think 标签）为例，从环境准备到打包部署，手把手带你完成Dify 插件开发，全程基于Python 语言，新手也能轻松上手，所有操作均经过实测可落地。

本次开发的插件核心功能：接收 Dify 中 AI 模型的输出文本，自动过滤冗余的 think 标签，返回干净的文本结果，适配 Dify 的 Agent 与 Workflow 应用，无需复杂依赖，部署后可直接在 Dify 平台调用。

一、前置知识与开发准备

（一）核心前置认知

1.插件类型：Dify 支持多种插件类型，其中最常用的是「工具插件」（Tool Plugin），用于集成第三方服务或实现自定义功能，本文聚焦工具插件开发，也是新手入门的最佳选择。

2.开发语言：Dify 插件支持 Python、JavaScript 等语言，本文选用 Python（≥3.12 版本），生态完善、代码简洁，适配绝大多数开发场景。

3.核心依赖：主要依赖 Dify 插件脚手架工具（dify-plugin-daemon），用于初始化项目、打包部署，无需手动搭建复杂项目结构。

（二）环境搭建步骤

1.安装 Python 环境

需安装 Python 3.12 及以上版本（低于该版本可能出现依赖兼容问题），下载地址：https://www.python.org/downloads/。

安装完成后，打开终端（Windows 用 PowerShell，Mac/Linux 用自带终端），输入以下命令验证是否安装成功：

同时配置 pip 镜像（加速依赖下载），执行以下命令：

2.安装 Dify 插件脚手架

脚手架是 Dify 插件开发的核心工具，支持项目初始化、调试、打包等全流程操作，不同系统安装命令不同，按需执行：

https://github.com/langgenius/dify-plugin-daemon/releases

•Mac系统：# 方式1：Homebrew 全局安装（推荐，适用于所有 Mac 机型）brew tap langgenius/difybrew install dify# 验证安装dify version

•Windows系统（需安装WSL2 或直接使用PowerShell）：# 下载脚手架工具（amd64 机型）Invoke-WebRequest -Uri https://github.com/langgenius/dify-plugin-cli/releases/latest/download/dify-plugin-windows-amd64.exe -OutFile dify.exe# 将 dify.exe 移动到系统环境变量目录（如C:\Windows），或配置环境变量# 验证安装dify version

•Linux系统：curl -O https://github.com/langgenius/dify-plugin-cli/releases/latest/download/dify-plugin-linux-amd64chmod +x dify-plugin-linux-amd64sudo mv dify-plugin-linux-amd64 /usr/local/bin/dify# 验证安装dify version

若执行dify version能输出版本信息，说明脚手架安装成功。

3.准备 Dify 平台环境

需拥有 Dify 平台账号（本地部署或云端版本均可），用于后续插件调试与部署：

•云端版本：直接访问https://dify.ai/注册登录即可。

•本地部署：参考 Dify 官方文档，完成本地部署（适合需要隐私保护的场景）。

登录后，进入「插件」页面，获取调试所需的远程服务器地址、端口和调试 Key，后续配置.env文件时会用到。

二、初始化插件项目（核心步骤）

使用脚手架命令快速初始化项目，无需手动创建文件夹和配置文件，全程按提示操作即可，步骤如下：

1.创建项目目录

先创建一个空目录，用于存放插件项目文件，终端执行命令：

2.初始化插件

执行以下命令启动初始化向导，按提示逐步配置项目信息：

初始化过程中需填写/选择以下内容，按实际情况配置：

•Plugin name（插件名称）：输入text-clean-plugin（自定义，需唯一，避免与现有插件重复）。

•Author（作者信息）：输入自己的名称或邮箱（如xxx@163.com）。

•Description（插件描述）：输入插件功能（如Clean redundant think tags from model output, optimize text content）。

•Select language（开发语言）：选择Python。

•Select template（选择模板）：选择Tool Plugin（工具插件，本文核心）。

•Select permissions（选择权限）：用方向键移动、Tab 键选中，需勾选以下权限（开发工具插件必备）：可选勾选 storage（存储权限），用于保存临时文本数据，勾选完成后按 Enter 确认。

1. Tools:

• Enabled: [✔] 表示如果启用了，可以调用 Dify 内部的工具。

2. Models:

• Enabled: [✘] 表示如果启用了，可以调用 Dify 内部的模型。

• LLM: [✘] 表示如果启用了，可以调用 Dify 内部的大型语言模型（LLM）。

• Text Embedding: [✘] 表示如果启用了，可以调用 Dify 内部的文本嵌入模型。

• Rerank: [✘] 表示如果启用了，可以调用 Dify 内部的重排序模型。

• TTS: [✘] 表示如果启用了，可以调用 Dify 内部的文本转语音（TTS）模型。

• Speech2Text: [✘] 表示如果启用了，可以调用 Dify 内部的语音转文本模型。

• Moderation: [✘] 表示如果启用了，可以调用 Dify 内部的内容审核模型。

3. Apps:

• Enabled: [✘] 表示如果启用了，可以调用 Dify 内部的应用，包括 BasicChat、ChatFlow、Agent、Workflow 等。

4. Resources:

• Enabled: [✘] 表示如果启用了，可以持久化存储插件数据。

• Size: N/A 表示存储的最大尺寸没有限制。

• Storage:

5. Endpoints:

• Enabled: [✔] 表示如果启用了，可以注册端点。

脚手架会自动生成完整的项目结构，初始化完成后，目录如下（核心文件已标注）：

三、编写插件核心代码（重点环节）

插件的核心逻辑集中在tools目录下，需完成参数定义（yaml 文件）和功能实现（py 文件），同时配置插件基础信息，步骤如下：

1.配置插件基础信息（manifest.yaml）

该文件是插件的“身份证”，决定插件在 Dify 市场的展示信息，按以下内容修改（自定义部分可调整）：

name: text-clean-pluginversion: 1.0.0author: xxx@163.comdescription:  human:    zh_Hans: 去除模型输出中的冗余think标签，优化文本格式，适配Dify Agent/Workflow应用    en_US: Clean redundant think tags from model output, optimize text format for Dify Agent/Workflow  llm: A tool to clean text and remove redundant tags# 插件分类标签，参考官方枚举[1][4]tags: [utilities, productivity]# 插件图标（放在 _assets 目录，可自定义）icon: icon.png# 支持的语言supported_languages: [zh_Hans, en_US]# 插件类型type: tool# 依赖的Dify版本dify_version: ">=0.6.0"

2.配置工具参数（tools/text_clean.yaml）

该文件定义插件的输入输出参数、前端展示文本，告诉 Dify 插件如何接收参数、展示功能，完整配置如下：

identity:  name: text_clean  author: xxx@163.com  label:    zh_Hans: 文本清洗工具    en_US: Text Clean Tooldescription:  human:    zh_Hans: 去除模型输出中的think标签及冗余内容，返回干净文本    en_US: Remove think tags and redundant content from model output, return clean text  llm: A tool to clean text by removing redundant think tags# 输入参数定义（核心）parameters:  - name: model_output    type: string    required: true  # 必传参数    label:      zh_Hans: 模型输出文本      en_US: Model Output Text    human_description:      zh_Hans: 需清洗的AI模型输出文本，支持包含think标签的内容      en_US: AI model output text to be cleaned, supporting content with think tags    llm_description: The AI model's output text that needs to be cleaned, which may contain think tags    form: llm  # Agent模式下由LLM自动推理参数，Workflow模式下作为输入变量# 关联核心逻辑文件extra:  python:    source: tools/text_clean.py  # 指向功能实现的py文件

关键说明：参数类型string表示接收文本输入，required: true表示该参数必须传入，避免插件运行报错。

3.编写文本清洗逻辑（tools/text_clean.py）

该文件是插件的核心，实现文本清洗功能——接收model_output参数，过滤冗余 think 标签，返回清洗后的文本，完整代码如下（含注释，可直接复制）：

from collections.abc import Generatorfrom typing import Anyfrom dify_plugin import Toolfrom dify_plugin.entities.tool import ToolInvokeMessageclass TextCleanPluginTool(Tool):    def _invoke(self, tool_parameters: dict[str, Any]) -> Generator[ToolInvokeMessage]:        model_output =  tool_parameters.get("model_output", "")        if "<think>" in  model_output and "</think>" in model_output:            clean_text =   model_output.split("</think>")[-1].strip()        else:            clean_text =   model_output.strip()        yield self.create_json_message({            "cleaned_text": clean_text,            "original_length": len(model_output),            "cleaned_length":   len(clean_text),            "status":   "success"        })#实例化工具，供入口文件调用tool = TextCleanTool()

代码说明：可根据需求修改_invoke方法中的清洗逻辑，比如添加空格去除、换行优化等功能，适配不同的文本清洗场景。

4.配置供应商信息（provider/text_clean.yaml）

该文件用于配置插件的供应商信息和凭证（若无需对接第三方 API，无需修改核心内容），简化配置如下：

name: text_cleanauthor: xxx@163.comlabel:  zh_Hans: 文本清洗供应商  en_US: Text Clean Providerdescription:  human:    zh_Hans: 提供文本清洗服务，去除冗余标签    en_US: Provide text cleaning services to remove redundant tags# 若无需第三方凭证，credentials_for_provider 可省略credentials_for_provider: []# 关联工具（与tools目录下的工具名称一致）tools:  - text_clean

5.配置调试环境（.env 文件）

复制.env.example文件，重命名为.env，填入 Dify 平台的调试信息：

# 安装方式（远程调试选remote，本地部署选local）INSTALL_METHOD=remote# Dify 远程服务器地址（从Dify插件页面获取）REMOTE_INSTALL_HOST=你的Dify地址（如 https://xxx.dify.ai）# 调试端口（默认5003，从Dify插件页面获取）REMOTE_INSTALL_PORT=5003# 调试Key（从Dify插件页面获取）REMOTE_INSTALL_KEY=你的调试Key

6.安装依赖包

终端执行以下命令，安装插件所需的依赖包：

若安装失败，可尝试升级 pip 后重新安装。

四、插件调试（避免踩坑关键）

调试的核心是验证插件是否能正常运行、功能是否符合预期，分为本地调试和 Dify 平台调试两步：

（一）本地调试

终端进入插件根目录，执行以下命令启动本地调试服务：

若终端输出Plugin started successfully，说明本地服务启动成功，无语法错误；若报错，需根据提示修改代码（常见错误：参数名不匹配、依赖缺失、环境变量配置错误）。

（二）Dify 平台调试

1.登录 Dify 平台，进入「插件」页面，点击「安装插件」→「本地插件」，输入本地调试地址（如http://localhost:5003），点击「连接」。

2.连接成功后，插件会显示在「已安装插件」列表中，点击「测试」，进入测试页面。

3.输入测试文本（含冗余 think 标签，如“<think>正在整理文本…</think> 这是需要保留的内容“），点击「运行」，查看输出结果。

4.若输出结果中包含清洗后的文本、长度统计等信息，说明插件功能正常；若失败，可查看终端调试日志，排查问题后重新测试。

常见调试问题解决

•问题1：无法连接 Dify 平台 → 检查.env文件中的地址、端口、调试 Key 是否正确，确保网络通畅。

•问题2：参数缺失报错 → 检查text_clean.yaml中required: true的参数是否传入，参数名是否一致。

•问题3：清洗逻辑无效 → 打印model_output参数，确认输入文本是否正确传递，调整_invoke方法中的逻辑。

五、插件打包与部署

调试通过后，即可打包插件，部署到 Dify 平台供正式使用，步骤如下：

1.打包插件

终端进入插件根目录，执行以下命令打包（生成 zip 压缩包）：

打包完成后，根目录会生成text-clean-plugin-1.0.0.zip文件（名称由插件名+版本号组成），该文件即为可部署的插件包。

2.部署到 Dify 平台

1.登录 Dify 平台，进入「插件」页面，点击「安装插件」→「上传插件」。

2.选择打包生成的 zip 压缩包，上传完成后，系统会自动校验插件格式。

3.校验通过后，插件会显示在「已安装插件」列表中，点击「启用」，即可在Dify 应用（Agent/Workflow）中调用该插件。

3.应用调用示例

以 Dify Workflow 应用为例，调用插件步骤：

•创建 Workflow 应用，添加「AI 模型」节点（选择 DeepSeek 等模型），配置模型输出。

•添加「工具」节点，选择已部署的「文本清洗工具」，将 AI 模型的输出作为文本清洗工具的输入（关联model_output参数）。

•运行 Workflow，即可获取清洗后的文本结果，完成插件调用。

六、进阶优化与提交市场（可选）

（一）插件进阶优化

•1.丰富功能：添加更多文本清洗规则，如去除特殊符号、格式化换行、过滤敏感词等。

•2.适配多语言：在 yaml 文件中补充多语言描述（如 pt_BR 葡萄牙语），适配更多地区用户。

•3.增加错误处理：在text_clean.py中添加异常捕获，避免插件因输入异常崩溃。

•4.优化性能：针对大量文本清洗场景，优化代码逻辑，提升处理速度。

（二）提交到 Dify 插件市场

若想分享插件给其他用户，可提交到 Dify 官方插件市场，需满足以下要求[5]：

•1.功能唯一：插件功能需独特，不与现有市场插件重复。

•2.文档完整：完善README.md文件，包含功能介绍、使用方法、示例截图、FAQ 等。

•3.安全合规：无恶意代码，不收集敏感信息，若涉及第三方服务，需提供隐私政策。

•4.提交方式：Fork Dify 官方插件仓库，提交 PR，附上插件功能说明，等待官方审核[5]。

七、总结

本文通过「文本清洗插件」实战，完成了 Dify 插件从环境准备到部署调用的全流程，核心要点可总结为：

1.新手优先选择工具插件，基于脚手架初始化项目，无需手动搭建结构，降低入门门槛。

2.核心文件聚焦tools目录，yaml 负责参数定义，py 负责逻辑实现，两者参数名需严格一致。

3.调试是关键步骤，先本地验证语法，再平台测试功能，避免打包后出现无法解决的问题。

按照本文步骤，你可以轻松修改核心逻辑，开发出适配自身需求的 Dify 插件（如 API 对接插件、数据处理插件等）。如果遇到问题，可参考Dify 官方插件开发文档，或查看官方开源插件的代码，快速排查问题。