当前位置：首页 > news >正文

Dify插件开发入门指南：在现有插件上改造出一个自己的插件

news 2025/10/27 12:21:13

Dify插件开发的官方文档非常详细，但对于初学者来说，可能会觉得有些复杂，不知道从何入手。本文将通过一个实战案例，带你一步步了解如何在现有插件仓库的基础上进行修改，开发出属于自己的插件。

一、开发包准备

首先参考官方文档中《获取 Dify Plugin 开发包》部分，安装好开发包即可。
暂时不需要运行，安装到环境里就行。

二、复制代码

建议从 Dify 的官方插件库中挑一个和自己想做的功能类型类似的插件，复制它的代码到本地。这样可以少踩坑，直接在现有的结构上改就行。

我自己在开发「谷歌学术搜索」插件时，就是参考了官方的谷歌搜索插件。它的代码在这里：
https://github.com/langgenius/dify-official-plugins/tree/main/tools/google

把这个项目复制到本地，然后在此基础上改即可。

项目结构大概如下：

三、安装依赖

进入项目目录后，执行：

pip install -r requirements.txt

安装完依赖，基本的准备工作就完成了。

四、项目结构概览

接下来我们看一下这个项目的整体结构，以及每个文件夹的作用。

1. manifest.yaml

这是整个插件的“身份证”。它决定了插件在 Dify 插件管理页面和市场（Marketplace）中展示的基本信息。

需要重点关注以下字段：

label：插件显示名称（支持多语言）
description：功能简介（支持多语言）
icon：插件图标文件名（放在 _assets 目录下）
tags：插件分类标签，帮助用户在市场中筛选

可选标签包括：

class ToolLabelEnum(Enum):SEARCH = "search"IMAGE = "image"VIDEOS = "videos"WEATHER = "weather"FINANCE = "finance"DESIGN = "design"TRAVEL = "travel"SOCIAL = "social"NEWS = "news"MEDICAL = "medical"PRODUCTIVITY = "productivity"EDUCATION = "education"BUSINESS = "business"ENTERTAINMENT = "entertainment"UTILITIES = "utilities"OTHER = "other"

2. README.md

插件在 Marketplace 上的详细介绍页。建议写清楚以下内容：

插件的主要功能
使用方法与配置说明
示例截图或代码
常见问题（FAQ）

Dify 支持多语言 README，规范可参考多语言 README 指南。

3. main.py

程序入口文件。一般逻辑不多，主要是调用其他模块的代码。

4. _assets 目录

这里存放图标和静态资源，例如插件的 icon、README 里引用的图片等。

5. provider 目录

这里通常会有两个文件：google.yaml 和 google.py。

google.yaml

这个文件定义了插件的配置项，包括凭据和功能列表。

credentials_for_provider：插件使用的凭证，比如谷歌搜索插件用到 SerpApi 的 API key。

截屏2025-10-27 10.23

截屏2025-10-27 10.33

tools：定义插件提供的功能，比如谷歌搜索插件有两个功能——网页搜索和图片搜索。

截屏2025-10-27 10.27

截屏2025-10-27 10.32

google.py

用于验证凭证是否有效。如果插件不需要凭证，这个文件可以省略。

6. tools 目录

这里存放的是每个功能的具体实现。
每个功能一般对应一个 .yaml 文件（定义输入输出）和一个 .py 文件（实现逻辑）。

我们以 google_search 功能为例。

google_search.yaml

描述当前功能的参数定义，重点是 parameters 部分。
它规定了插件可接收的输入参数。其中type字段应该是和开始结点支持的输入类型对应的：

截屏2025-10-27 10.36

此外，extra-python-source 字段指定了对应的实现文件路径，如果改了文件名，这里也要同步修改。

截屏2025-10-27 10.38

google_search.py

这个文件就是插件的核心逻辑。当工作流运行到该节点时，会调用它的 main() 函数。

主要逻辑写在 _invoke() 方法中。输入参数通过 tool_parameters 传入，输出结果这里用了：

yield self.create_json_message(valuable_res)

这个函数会返回一个 JSON 格式的结果，供后续节点使用。
当然，你也可以返回文本、图片、文件等其他类型的消息，具体格式参考官方文档：
https://docs.dify.ai/zh-hans/plugins/schema-definition/tool

google-countries.json / google-languages.json

分别定义了国家代码和语言代码。

五、修改为自己的插件

我自己的插件是“谷歌学术搜索”，同样使用 SerpApi 的接口，所以凭据部分不需要改，只需修改 tools 目录。

删除 google_image_search.yaml 和 google_image_search.py，然后在 google_search.yaml 和 google_search.py 的基础上修改即可。

修改 google_search.yaml

在 SerpApi 文档中找到 Google Scholar API 的支持参数，然后在 YAML 文件中定义。
比如我增加了两个年份过滤参数 as_ylo（起始年）和 as_yhi（结束年），删掉了 location 参数。

parameters:- name: querytype: stringrequired: truelabel:zh_Hans: 查询语句llm_description: key words for searchingform: llm- name: as_ylotype: numberrequired: falselabel:zh_Hans: 起始年份form: llm- name: as_yhitype: numberrequired: falselabel:zh_Hans: 结束年份form: llm- name: hltype: stringrequired: falselabel:zh_Hans: 语言form: llm- name: gltype: stringrequired: falselabel:zh_Hans: 国家form: llm

修改 google_search.py

由于参数变了，这里也要同步调整。
同时，建议对 SerpApi 返回的原始数据进行简单包装，只保留必要字段，否则结果会太冗余。

修改 provider/google.yaml

删除掉原本指向图片搜索的那一行：

- tools/google_image_search.yaml

六、其他修改

把项目中所有带 google 的命名（文件名、变量名等）改成 google_scholar。
更新 README 里的说明。
添加 PRIVACY.md 文件。
官方要求每个插件必须提供隐私政策文件，否则无法发布。
如果参考的插件没有这个文件，可以从其他插件复制一个，然后根据实际情况修改。

七、调试插件

开发完成后，可以先在本地调试。

打开自己的 Dify 环境，点击右上角的「插件」按钮；
再点击右上角的小虫图标，查看调试地址和 Key；

截屏2025-10-27 11.08

把调试地址写入项目根目录 .env 文件中的 REMOTE_INSTALL_HOST；
把 Key 填入 REMOTE_INSTALL_KEY；
运行命令：
```
python -m main.py
```

如果没有报错，就说明插件安装成功。
此时在 Dify 环境里应该能看到并使用你的插件。

八、发布插件

测试通过后，可以发布到 Dify 官方插件市场。

在插件项目的上一层目录执行：
```
dify plugin package ./your_plugin_project
```
生成 .difypkg 文件。
Fork Dify Plugins 仓库；
新建个人或组织文件夹，把 .difypkg 文件上传；
按照 PR 模板提交 Pull Request；
等待官方审核，审核通过后你的插件就会上架市场。