一、初始化开发环境

1.1、Dify 插件 CLI 工具

Dify 插件 CLI 工具又称为 dify-plugin-daemon，可以被视作插件开发 SDK。

1.1.1、 安装 Dify 插件 CLI 工具

        Dify 插件 CLI 工具可以通过 Homebrew（在 Linux 和 macOS 上）或独立的二进制可执行文件（在 Windows、Linux 和 macOS 上）进行安装。

        通过 Homebrew 安装对于 macOS 和 Linux 用户，建议使用 Homebrew 安装 Dify 插件 CLI 工具。首先添加 Dify 插件 CLI 工具的 Homebrew 配方，然后使用 brew install 命令进行安装。

brew tap langgenius/dify
brew install dify

要检查安装是否成功，请运行 dify version，应该会显示版本代码。

dify version

要升级 Dify 插件 CLI 工具，请运行以下命令：

brew upgrade dify

        通过二进制可执行文件安装下载二进制可执行文件：访问 Dify Plugin CLI 项目地址，在发布页面的资产列表中，选择并下载适合操作系统（Linux / macOS / Windows）和芯片架构（amd64 为 x86 芯片 / arm64 为 ARM 或 Apple 的 M 芯片）的二进制可执行文件。本文以装载 M 系列芯片的 macOS 为例（windows版本的下载dify-plugin-windows-amd64.exe即可）。下载 dify-plugin-darwin-arm64 文件后，赋予其执行权限。

chmod +x ./dify-plugin-darwin-arm64
mv ./dify-plugin-darwin-arm64 ./dify

要检查安装是否成功，请运行 ./dify version，应该会显示版本代码。

./dify version

若提示 “Apple 无法验证” 错误，请前往  “设置 → 隐私与安全性 → 安全性”，轻点 “仍要打开” 按钮。

运行命令后，终端若返回类似 v0.0.1-beta.15 的版本号信息，则说明安装成功。

1.2、Python 环境，版本号 ≥ 3.12

详细说明请参考 Python 安装教程，或询问 LLM 安装版本号 ≥ 3.12 的 Python 环境。

二、工具插件开发

2.1、环境准备

在开始开发 Dify 插件之前，请确保您的环境中已准备好以下工具：

• Dify 插件开发脚手架 (CLI): 这是开发、调试和打包插件的核心工具，也称为 dify-plugin-daemon 或“插件开发 SDK”。
• Python 环境: 需要 Python 3.12 或更高版本。

2.2、插件开发流程

以windows11 64位系统为例

2.2.1、初始化插件项目

现在，让我们使用脚手架工具创建一个新的插件项目。

1、打开终端，进入插件安装路径，执行初始化命令：

dify-plugin-windows-amd64.exe plugin init

2、根据提示依次输入插件的基本信息：

•         Plugin name: 插件的唯一标识符。例如：hello_world
•                 约束: 长度 1-128 字符，只能包含小写字母、数字、连字符(-)和下划线(_)。
•         Author: 插件作者的标识符。例如：hz
•                 约束: 长度 1-64 字符，只能包含小写字母、数字、连字符(-)和下划线(_)。
•         Description: 对插件功能的简短描述。例如：测试Tool

3、选择开发语言: 当提示 Select language 时，请选择 python。

4、选择插件类型: 当提示 Select plugin type 时，对于本教程，请选择 tool。

5、选择附加功能: 接下来会提示是否需要包含 Provider 验证、持久存储等附加功能。对于这个简单的 Hello World 插件，我们暂时不需要这些，可以直接按 回车键 跳过所有选项，直到看到成功信息。

6、Dify版本要求，默认为空即可，可以直接按回车键。

7、确认创建成功: 当终端输出类似以下信息时，表示插件项目已成功创建：

[INFO]plugin hello_world created successfully, you can refer to `hello_world/GUIDE.md` for more information about how to develop it

现在，您的当前目录下应该出现了一个名为 hello_world(或您指定的插件名) 的新文件夹，这就是您的插件项目。

2.2.2、配置python虚拟环境与依赖

为了隔离项目依赖，避免不同项目之间的依赖包互相干扰。推荐使用 Python 虚拟环境。

1、 创建并激活虚拟环境 (命令行方式)

这是推荐且通用的方法，不依赖特定 IDE：

1. 进入项目目录:

   cd hello_world
   

2. 创建虚拟环境: (建议命名为 venv)，创建成功后会在当前目录生成一个venv目录

   python -m venv venv
   

3. 激活虚拟环境:
   • macOS / Linux:

     source venv/bin/activate
     

   • Windows (cmd.exe):

     venv\Scripts\activate.bat
     

   • Windows (PowerShell):

     venv\Scripts\Activate.ps1
     

   • 激活成功后，您的终端提示符前通常会显示 (venv) 字样。

2、安装基础依赖

项目初始化时生成的 requirements.txt 文件已包含插件开发所需的基础库 dify_plugin。激活虚拟环境后，执行以下命令安装：

pip install -r requirements.txt

3、(可选) VSCode 集成环境配置

如果您使用 VSCode 作为代码编辑器，可以利用其集成功能来管理 Python 环境：

1. 打开项目文件夹: 使用 VSCode 打开刚刚创建的 hello_world文件夹。
2. 选择 Python 解释器:
   • 打开命令面板 (macOS: Cmd+Shift+P, Windows/Linux: Ctrl+Shift+P)。
   • 输入并选择 Python: Select Interpreter。
   • 在弹出的列表中，选择您刚刚创建的虚拟环境中的 Python 解释器（通常路径包含 .venv/bin/python 或 venv\Scripts\python.exe）。如果列表没有自动显示，您可以选择 Enter interpreter path... 手动查找。
3. 安装依赖 (若 VSCode 提示): VSCode 可能会检测到 requirements.txt 文件并提示您安装其中的依赖项。如果出现提示，请确认安装。

2.2.3、编写工具

1、编辑python文件：打开hello_world/tools/hello_world.py

2、实现_invoke方法，将实现逻辑放入该方法中

3、工具参数配置

identity:
  name: "hello_world"
  author: "hz"
  label:
    en_US: "hello_world"
    zh_Hans: "这里是一个测试Tool"
    pt_BR: "hello_world"
description:
  human:
    en_US: "测试Tool"
    zh_Hans: "测试Tool"
    pt_BR: "测试Tool"
  llm: "测试Tool"
parameters:
  - name: query
    type: string
    required: true
    label:
      en_US: Query string
      zh_Hans: 查询语句
      pt_BR: Query string
    human_description:
      en_US: "测试Tool"
      zh_Hans: "测试Tool"
      pt_BR: "测试Tool"
    llm_description: "测试Tool"
    form: llm
extra:
  python:
    source: tools/hello_world.py

• 字段解释:
  • identity: 工具的基本信息，name 是唯一标识。
  • description: 分为 human (给用户看) 和 llm (给 Agent 看)。llm 描述对于 Agent 能否正确理解和使用工具至关重要。
  • parameters: 定义每个输入参数。
    • name: 内部名称，需与 Python 代码中 tool_parameters.get("...") 的键一致。
    • type: 数据类型 (如 string, number, boolean 等)。
    • required: 是否必须提供。
    • label, human_description, llm_description: 类似 identity 中的描述，但针对具体参数。llm_description 应清晰指导 LLM 如何生成或获取该参数的值，包括格式要求（如此处的 Markdown）。
    • form: 定义参数如何在 Dify 中呈现和填充。llm 表示该参数值可以由用户输入、通过变量传入，或者在 Agent 模式下由 LLM 自主决定；form 通常表示需要用户在界面上固定填写的配置项。对于工具输入，llm 更常见。
  • extra.python.source: 指明实现此工具逻辑的 Python 文件路径（相对于项目根目录）。

2.2.4、本地运行与调试

现在可以在本地运行插件，并在 Dify 中进行调试了。

1. 准备 .env 文件:
   • 确保您仍在 telegraph 项目目录下。
   • 复制环境变量模板文件：

     cp .env.example .env
     

   • 编辑 .env 文件: 打开刚刚创建的 .env 文件，填入您的 Dify 环境信息：

     DIFY_API_HOST=https://your-dify-host.com # 替换为您的 Dify 实例地址 (例如 https://cloud.dify.ai)
     DIFY_API_KEY=your-api-key             # 替换为您的 Dify API 密钥
     

     • 获取 Host 和 Key: 登录您的 Dify 环境，点击右上角的“插件”图标，然后点击调试图标（或类似虫子形状）。在弹出的窗口中，复制“API 密钥 (Key)”和“主机地址 (Host)”。 (请参考您本地对应的截图 ，它展示了获取密钥和主机地址的界面)
2. 启动本地插件服务:
   • 确保您的 Python 虚拟环境已激活。
   • 在 hello_world目录下，运行主程序：

     python -m main
     

   • 观察终端输出: 如果一切正常，您应该会看到类似以下的日志信息，表示插件工具已成功加载并连接到 Dify：

三、插件安装

3.1、插件打包

切换到插件安装目录，执行以下命令进行打包

dify-plugin-windows-amd64.exe plugin package hello_world

3.2、登录dify环境插件页面

https://dify.xxx.xxx.com.cn/plugins

3.3、上传插件