This document provides a detailed tutorial for Dify plugin development from scratch, using the Telegraph publishing plugin as an example, covering environment preparation, project initialization, virtual environment configuration, plugin core logic development, local debugging, plugin metadata enhancement, and packaging for release.
Note for LLMs: You can also use our built prompt to assist you in developing plugins: Dify Plugin Development: PromptBefore you begin, you can always refer to our Developer Cheatsheet for common commands and information, or consult the complete developer documentation when facing more complex issues.
dify-plugin-daemon
or “Plugin Development SDK.”For a more detailed guide on preparing the development environment, please refer to Initializing Development Tools.
dify-plugin-darwin-arm64
. In the terminal, navigate to the directory containing the file and execute the following command to grant execution permissions:
chmod +x <downloaded_filename>
.
.exe
file, you can typically run it directly.
./dify-plugin-darwin-arm64
with the actual filename or path you downloaded):
v0.0.1-beta.15
), then the installation is successful.
Tips:For convenience, this article will use
- macOS Security Prompt: If macOS initially prompts “Apple cannot verify” or “Cannot open,” go to “System Settings” → “Privacy & Security” → “Security” section, find the related prompt and click “Open Anyway” or “Allow.”
- Simplify Command: You can rename the downloaded binary file to a shorter name (e.g.,
dify
ordify-plugin
) for easier use. Example:mv dify-plugin-darwin-arm64 dify
, then you can use./dify version
.- Global Installation (Optional): If you want to run the command from any path in your system (e.g., directly typing
dify
instead of./dify
), you can move the renamed file to a directory included in your system’sPATH
environment variable, such as/usr/local/bin
(macOS/Linux) or add it to Windows environment variables.
- For example (macOS/Linux):
sudo mv dify /usr/local/bin/
- After configuration, typing
dify version
directly in the terminal should successfully output the version number.
./dify
as an example command for the Dify plugin development scaffold. Please replace it with your corresponding command based on your actual situation.
telegraph
your-name
A Telegraph plugin that allows you to publish your content easily
Select language
, choose python
.
Select plugin type
, for this tutorial, choose tool
.
telegraph
(or the plugin name you specified) should appear in your current directory, which is your plugin project.
venv
)
(venv)
at the beginning.
requirements.txt
file generated during project initialization already includes the basic library dify_plugin
needed for plugin development. After activating the virtual environment, execute the following command to install:
telegraph
folder you just created.Cmd+Shift+P
, Windows/Linux: Ctrl+Shift+P
).Python: Select Interpreter
..venv/bin/python
or venv\Scripts\python.exe
). If the list doesn’t automatically display it, you can select Enter interpreter path...
to manually find it.requirements.txt
file and prompt you to install its dependencies. If prompted, confirm the installation.
pip install
commands and running python -m main
operations are performed in the activated virtual environment.
your-telegraph
your-telegraph
to interact with the Telegraph API. (This is a hypothetical library name, please ensure that the library you actually use is valid).
your-telegraph
is a Python wrapper that simplifies Telegraph API operations, allowing you to easily publish content with just a few lines of code.
Its basic usage might be as follows:
requirements.txt
: Open the requirements.txt
file in the telegraph
project root directory, and add a line below dify_plugin
with the name of the library you just installed:
telegraph_access_token
. We need to define this credential in the Provider configuration so that users can input it when using the plugin. For more information about Provider configuration, please refer to General Specification Definitions.
telegraph/provider/telegraph.yaml
file.
credentials_for_provider
: Add the following content at the end of the file (or at an appropriate location):
telegraph_access_token
: Unique identifier for the credential, accessed in code via self.runtime.credentials["telegraph_access_token"]
.type: secret-input
: Indicates that it will be displayed as a password input field in the Dify interface.required: true
: Indicates that users must fill in this credential to use tools provided by this plugin.label
, placeholder
, help
: Provide multilingual interface text.url
: (Optional) Provides a help link for obtaining the credential.telegraph/tools/telegraph.py
.
_invoke
Method: Replace the file contents with the following code:
self.runtime.credentials
.tool_parameters
(parameter names will be defined in YAML in the next step). Using .get()
is a more robust approach.ytelegraph
library to perform the actual operation.try...except
to catch possible errors and throw exceptions.yield self.create_link_message(url)
to return a result containing a URL to Dify.telegraph/tools/telegraph.yaml
.
identity
: Basic information about the tool, name
is a unique identifier.description
: Divided into human
(for users) and llm
(for Agent). The llm
description is crucial for the Agent to correctly understand and use the tool.parameters
: Defines each input parameter.
name
: Internal name, must match the key in the Python code’s tool_parameters.get("...")
.type
: Data type (such as string
, number
, boolean
, etc.).required
: Whether it must be provided.label
, human_description
, llm_description
: Similar to descriptions in identity
, but for specific parameters. llm_description
should clearly guide the LLM on how to generate or obtain the parameter value, including format requirements (such as Markdown here).form
: Defines how the parameter is presented and filled in Dify. llm
indicates that the parameter value can be input by the user, passed through variables, or determined by the LLM in Agent mode; form
typically indicates a configuration item that needs to be fixed by the user in the interface. For tool inputs, llm
is more common.extra.python.source
: Specifies the path to the Python file implementing this tool’s logic (relative to the project root directory).telegraph/provider/telegraph.py
.
_validate_credentials
Method: Replace the file contents with:
credentials
dictionary.ToolProviderCredentialValidationError
, including the original error message..env
File:
telegraph
project directory.
.env
File: Open the .env
file you just created and fill in your Dify environment information:
telegraph
directory, run the main program:
https://your-dify-host.com/plugins
).label
you defined in the Provider YAML) in the list, possibly with a “Debugging” mark.provider/telegraph.yaml
. Enter a valid token and save. If your validation logic (_validate_credentials
) is implemented correctly, validation will be performed here. (Please refer to your local corresponding screenshot, which shows the plugin appearing in the list and requesting authorization)python -m main
process for processing. You can see related log output in your local terminal for debugging.Ctrl + C
in the terminal to stop the local plugin service.
telegraph/_assets
directory (e.g., icon.png
, icon.svg
). Square, clear images are recommended.provider/telegraph.yaml
):
label
(display name), description
(function description), and icon
(icon filename, such as icon.png
) in the identity
section are filled in and support multiple languages. This information is primarily displayed to users who use the plugin in the Dify application orchestration interface.manifest.yaml
):
manifest.yaml
file in the project root directory. This is the “ID card” for the entire plugin, and its information will be displayed on the plugin management page and Plugin Marketplace in Dify.label
: The main display name of the plugin (supports multiple languages).description
: An overall introduction to the plugin’s functionality (supports multiple languages), which should clearly summarize its core value. Note that the marketplace display may have length limitations.icon
: The main icon of the plugin (directly enter the icon filename in the _assets
directory, such as icon.png
).tags
: Add category tags to the plugin, which helps users filter in the marketplace. For optional values, please refer to Dify’s enumerations or documentation (such as media
, tools
, data-processing
, etc.). You can refer to the ToolLabelEnum definition.README.md
: Edit the README.md
file in the project root directory. It will serve as the detailed introduction page for the plugin on the Marketplace, and should include richer information such as detailed functionality, usage examples, configuration guide, frequently asked questions, etc. You can refer to the style of the AWS plugin marketplace page.PRIVACY.md
: If you plan to publish the plugin to the official Marketplace, you need to provide a privacy policy document PRIVACY.md
, describing how the plugin handles data..difypkg
file for distribution or installation. For detailed information about plugin packaging and publishing, please refer to Publishing Overview.
telegraph
folder.
./telegraph
with the actual path to your plugin project)
telegraph.difypkg
(or your_plugin_name.difypkg
) will be generated in the current directory.
.difypkg
file is a complete plugin package. You can: