diff --git a/docs.json b/docs.json
index b8f64ac2d..331c12ffb 100644
--- a/docs.json
+++ b/docs.json
@@ -353,6 +353,7 @@
"group": "Getting Started",
"pages": [
"en/develop-plugin/getting-started/getting-started-dify-plugin",
+ "en/develop-plugin/getting-started/choose-plugin-type",
"en/develop-plugin/getting-started/cli"
],
"icon": "rocket"
@@ -398,41 +399,61 @@
"group": "Development Guides & Walkthroughs",
"pages": [
"en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet",
- "en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin",
- "en/develop-plugin/dev-guides-and-walkthroughs/tool-oauth",
- "en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider",
- "en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin",
- "en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin",
- "en/develop-plugin/dev-guides-and-walkthroughs/endpoint",
- "en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin",
- "en/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin",
- "en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin",
- "en/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter",
- "en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool"
+ {
+ "group": "By Plugin Type",
+ "pages": [
+ "en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin",
+ "en/develop-plugin/dev-guides-and-walkthroughs/tool-oauth",
+ "en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider",
+ "en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin",
+ "en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin",
+ "en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin",
+ "en/develop-plugin/dev-guides-and-walkthroughs/endpoint"
+ ]
+ },
+ {
+ "group": "Full Walkthroughs",
+ "pages": [
+ "en/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin",
+ "en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin",
+ "en/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter",
+ "en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool"
+ ]
+ }
],
"icon": "code"
},
{
"group": "Publishing",
"pages": [
+ "en/develop-plugin/publishing/marketplace-listing/release-overview",
{
"group": "Standards",
"pages": [
"en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct",
- "en/develop-plugin/publishing/standards/privacy-protection-guidelines",
- "en/develop-plugin/publishing/standards/third-party-signature-verification"
+ "en/develop-plugin/publishing/standards/privacy-protection-guidelines"
]
},
{
- "group": "Marketplace Listing",
+ "group": "Marketplace",
"pages": [
- "en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr",
- "en/develop-plugin/publishing/marketplace-listing/release-overview",
- "en/develop-plugin/publishing/marketplace-listing/release-by-file",
"en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace",
+ "en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr"
+ ]
+ },
+ {
+ "group": "GitHub Repository",
+ "pages": [
"en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo"
]
},
+ {
+ "group": "Local File",
+ "pages": [
+ "en/develop-plugin/publishing/marketplace-listing/release-by-file",
+ "en/develop-plugin/publishing/standards/third-party-signature-verification"
+ ]
+ },
{
"group": "FAQ",
"pages": [
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx
index e6e0e5ac4..679a0f0ef 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin.mdx
@@ -1,12 +1,13 @@
---
title: Agent Strategy Plugin
+description: Build a Function Calling agent strategy from scratch, with a worked example showing how to give an LLM tools and let it autonomously fetch the current time
---
An **Agent Strategy Plugin** helps an LLM carry out tasks like reasoning or decision-making, including choosing and calling tools, as well as handling results. This allows the system to address problems more autonomously.
Below, you’ll see how to develop a plugin that supports **Function Calling** to automatically fetch the current time.
-### Prerequisites
+## Prerequisites
- Dify plugin scaffolding tool
- Python environment (version 3.12)
@@ -19,7 +20,7 @@ For details on preparing the plugin development tool, see [Initializing the Deve
---
-### 1. Initialize the Plugin Template
+## 1. Initialize the Plugin Template
Run the following command to create a development template for your Agent plugin:
@@ -88,14 +89,14 @@ All key functionality for this plugin is in the `strategies/` directory.
---
-### 2. Develop the Plugin
+## 2. Develop the Plugin
Agent Strategy Plugin development revolves around two files:
- **Plugin Declaration**: `strategies/basic_agent.yaml`
- **Plugin Implementation**: `strategies/basic_agent.py`
-#### 2.1 Defining Parameters
+### 2.1 Defining Parameters
To build an Agent plugin, start by specifying the necessary parameters in `strategies/basic_agent.yaml`. These parameters define the plugin’s core features, such as calling an LLM or using tools.
@@ -160,7 +161,7 @@ Once you’ve configured these parameters, the plugin will automatically generat
-#### 2.2 Retrieving Parameters and Execution
+### 2.2 Retrieving Parameters and Execution
After users fill out these basic fields, your plugin needs to process the submitted parameters. In `strategies/basic_agent.py`, define a parameter class for the Agent, then retrieve and apply these parameters in your logic.
@@ -186,7 +187,7 @@ class BasicAgentAgentStrategy(AgentStrategy):
params = BasicParams(**parameters)
```
-### 3. Invoke the Model
+## 3. Invoke the Model
In an Agent Strategy Plugin, **invoking the model** is central to the workflow. You can invoke an LLM efficiently using `session.model.llm.invoke()` from the SDK, handling text generation, dialogue, and so forth.
@@ -221,7 +222,7 @@ This code achieves the following functionality: after a user inputs a command, t
-### 4. Handle a Tool
+## 4. Handle a Tool
After specifying the tool parameters, the Agent Strategy Plugin must actually call these tools. Use `session.tool.invoke()` to make those requests.
@@ -259,13 +260,13 @@ for tool_call_id, tool_call_name, tool_call_args in tool_calls:
)
```
-With this in place, your Agent Strategy Plugin can automatically perform **Function Calling**—for instance, retrieving the current time.
+With this in place, your Agent Strategy Plugin can automatically perform **Function Calling**, for instance retrieving the current time.
-### 5. Create Logs
+## 5. Create Logs
Often, multiple steps are necessary to complete a complex task in an **Agent Strategy Plugin**. It’s crucial for developers to track each step’s results, analyze the decision process, and optimize strategy. Using `create_log_message` and `finish_log_message` from the SDK, you can log real-time states before and after calls, aiding in quick problem diagnosis.
@@ -328,7 +329,7 @@ model_log = self.create_log_message(
yield model_log
```
-#### Sample code for agent-plugin functions
+### Sample code for agent-plugin functions
@@ -1042,9 +1043,9 @@ class BasicAgentAgentStrategy(AgentStrategy):
-### 6. Debug the Plugin
+## 6. Debug the Plugin
-After finalizing the plugin’s declaration file and implementation code, run `python -m main` in the plugin directory to restart it. Next, confirm the plugin runs correctly. Dify offers remote debugging—go to **Plugin Management** to obtain your debug key and remote server address.
+After finalizing the plugin’s declaration file and implementation code, run `python -m main` in the plugin directory to restart it. Next, confirm the plugin runs correctly. Dify offers remote debugging. Go to **Plugin Management** to obtain your debug key and remote server address.
@@ -1070,7 +1071,7 @@ You’ll see the plugin installed in your Workspace, and team members can also a
-### Package the Plugin (Optional)
+## Package the Plugin (Optional)
Once everything works, you can package your plugin by running:
@@ -1080,17 +1081,17 @@ Once everything works, you can package your plugin by running:
dify plugin package ./basic_agent/
```
-A file named `google.difypkg` (for example) appears in your current folder—this is your final plugin package.
+A file named `basic_agent.difypkg` (matching your plugin name) appears in your current folder. This is your final plugin package.
**Congratulations!** You’ve fully developed, tested, and packaged your Agent Strategy Plugin.
-### Publish the Plugin (Optional)
+## Publish the Plugin (Optional)
You can now upload it to the [Dify Plugins repository](https://github.com/langgenius/dify-plugins). Before doing so, ensure it meets the [Plugin Publishing Guidelines](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace). Once approved, your code merges into the main branch, and the plugin automatically goes live on the [Dify Marketplace](https://marketplace.dify.ai/).
---
-### Further Exploration
+## Further Exploration
Complex tasks often need multiple rounds of thinking and tool calls, typically repeating **model invoke → tool use** until the task ends or a maximum iteration limit is reached. Managing prompts effectively is crucial in this process. Check out the [complete Function Calling implementation](https://github.com/langgenius/dify-official-plugins/blob/main/agent-strategies/cot_agent/strategies/function_calling.py) for a standardized approach to letting models call external tools and handle their outputs.
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx
index ed7f2c280..6611f283a 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet.mdx
@@ -6,25 +6,25 @@ dimensions:
level: beginner
standard_title: Cheatsheet
language: en
-title: Dify Plugin Development Cheatsheet
+title: Cheatsheet
description: A comprehensive reference guide for Dify plugin development, including
environment requirements, installation methods, development process, plugin categories
and types, common code snippets, and solutions to common issues. Suitable for developers
to quickly consult and reference.
---
-### Environment Requirements
+## Environment Requirements
- Python version 3.12
- Dify plugin scaffold tool (dify-plugin-daemon)
> Learn more: [Initializing Development Tools](/en/develop-plugin/getting-started/cli)
-### Obtain the Dify Plugin Development Package
+## Obtain the Dify Plugin Development Package
[Dify Plugin CLI](https://github.com/langgenius/dify-plugin-daemon/releases)
-#### Installation Methods for Different Platforms
+### Installation Methods for Different Platforms
**macOS [Brew](https://github.com/langgenius/homebrew-dify) (Global Installation)**:
@@ -69,13 +69,13 @@ sudo mv dify /usr/local/bin/
dify version
```
-### Run the Development Package
+## Run the Development Package
Here we use `dify` as an example. If you are using a local installation method, please replace the command accordingly, for example `./dify-plugin-darwin-arm64 plugin init`.
-### Plugin Development Process
+## Plugin Development Process
-#### 1. Create a New Plugin
+### 1. Create a New Plugin
```bash
./dify plugin init
@@ -85,7 +85,7 @@ Follow the prompts to complete the basic plugin information configuration
> Learn more: [Dify Plugin Development: Hello World Guide](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)
-#### 2. Run in Development Mode
+### 2. Run in Development Mode
Configure the `.env` file, then run the following command in the plugin directory:
@@ -95,7 +95,7 @@ python -m main
> Learn more: [Remote Debugging Plugins](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin)
-#### 3. Packaging and Deployment
+### 3. Packaging and Deployment
Package the plugin:
@@ -106,9 +106,9 @@ dify plugin package ./yourapp
> Learn more: [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview)
-### Plugin Categories
+## Plugin Categories
-#### Tool Labels
+### Tool Labels
Category `tag` [class ToolLabelEnum(Enum)](https://github.com/langgenius/dify-plugin-sdks/blob/main/python/dify_plugin/entities/tool.py)
@@ -132,7 +132,7 @@ class ToolLabelEnum(Enum):
OTHER = "other"
```
-### Plugin Type Reference
+## Plugin Type Reference
Dify supports the development of various types of plugins:
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx
index 07a3f985f..cb63c94dd 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider.mdx
@@ -12,7 +12,7 @@ description: This comprehensive guide provides detailed instructions on creating
writing provider code, and implementing model integration with detailed examples of core API implementations.
---
-### Prerequisites
+## Prerequisites
* [Dify CLI](/en/develop-plugin/getting-started/cli)
* Basic Python programming skills and understanding of object-oriented programming
@@ -423,8 +423,7 @@ Dify provides a remote debugging capability that allows you to test your plugin
```dotenv
INSTALL_METHOD=remote
-REMOTE_INSTALL_HOST=
-REMOTE_INSTALL_PORT=5003
+REMOTE_INSTALL_URL=:5003
REMOTE_INSTALL_KEY=****-****-****-****-****
```
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx
index 1eb4400d7..fba9578a3 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin.mdx
@@ -1,5 +1,6 @@
---
title: Data Source Plugin
+description: Build a Dify 1.9.0+ datasource plugin that feeds documents into the knowledge pipeline, with architecture, code samples, and debugging steps
---
Data source plugins are a new type of plugin introduced in Dify 1.9.0. In a knowledge pipeline, they serve as the document data source and the starting point for the entire pipeline.
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx
index 01cd0dd50..fbc3c5d66 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin.mdx
@@ -4,9 +4,9 @@ dimensions:
primary: reference
detail: examples
level: intermediate
-standard_title: Develop A Slack Bot Plugin
+standard_title: Slack Bot
language: en
-title: Develop A Slack Bot Plugin
+title: Slack Bot
description: This guide provides a complete walkthrough for developing a Slack Bot
plugin, covering project initialization, configuration form editing, feature implementation,
debugging, endpoint setup, verification, and packaging. You'll need the Dify plugin
@@ -15,9 +15,9 @@ description: This guide provides a complete walkthrough for developing a Slack B
**What You’ll Learn**:
-Gain a solid understanding of how to build a Slack Bot that’s powered by AI—one that can respond to user questions right inside Slack. If you haven't developed a plugin before, we recommend reading the [Plugin Development Quick Start Guide](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) first.
+Gain a solid understanding of how to build a Slack Bot that’s powered by AI, one that can respond to user questions right inside Slack. If you haven't developed a plugin before, we recommend reading the [Plugin Development Quick Start Guide](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) first.
-### Project Background
+## Project Background
The Dify plugin ecosystem focuses on making integrations simpler and more accessible. In this guide, we’ll use Slack as an example, walking you through the process of developing a Slack Bot plugin. This allows your team to chat directly with an LLM within Slack, significantly improving how efficiently they can use AI.
@@ -40,13 +40,13 @@ Slack is an open, real-time communication platform with a robust API. Among its
2. **Forward the Message to the Slack Bot Plugin**
- The Dify platform triggers the Slack Bot plugin, which relays the details to the Dify application—similar to entering a recipient’s address in an email system. By setting up a Slack webhook address through Slack’s API and entering it in the Slack Bot plugin, you establish this connection. The plugin then processes the Slack request and sends it on to the Dify application, where the LLM analyzes the user’s input and generates a response.
+ The Dify platform triggers the Slack Bot plugin, which relays the details to the Dify application, similar to entering a recipient’s address in an email system. By setting up a Slack webhook address through Slack’s API and entering it in the Slack Bot plugin, you establish this connection. The plugin then processes the Slack request and sends it on to the Dify application, where the LLM analyzes the user’s input and generates a response.
3. **Return the Response to Slack**
Once the Slack Bot plugin receives the reply from the Dify application, it sends the LLM’s answer back through the same route to the Slack Bot. Users in Slack then see a more intelligent, interactive experience right where they’re chatting.
-### Prerequisites
+## Prerequisites
- **Dify plugin developing tool**: For more information, see [Initializing the Development Tool](/en/develop-plugin/getting-started/cli).
- **Python environment (version 3.12)**: Refer to the [Python official downloads page](https://www.python.org/downloads/) or ask an LLM for a complete setup guide.
@@ -76,11 +76,11 @@ Go to the [Slack API platform](https://api.slack.com/apps), create a Slack app f
-### 1. Develop the Plugin
+## 1. Develop the Plugin
Now we’ll dive into the actual coding. Before starting, make sure you’ve read [Quick Start: Developing an Extension Plugin](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint) or have already built a Dify plugin before.
-#### 1.1 Initialize the Project
+### 1.1 Initialize the Project
Run the following command to set up your plugin development environment:
@@ -96,11 +96,11 @@ For additional details on reverse-invoking Dify services within a plugin, see [R
-#### 1.2 Edit the Configuration Form
+### 1.2 Edit the Configuration Form
This plugin needs to know which Dify app should handle the replies, as well as the Slack App token to authenticate the bot’s responses. Therefore, you’ll add these two fields to the plugin’s form.
-Modify the YAML file in the group directory—for example, `group/slack.yaml`. The form’s filename is determined by the info you provided when creating the plugin, so adjust it accordingly.
+Modify the YAML file in the group directory (for example, `group/slack.yaml`). The form’s filename is determined by the info you provided when creating the plugin, so adjust it accordingly.
**Sample Code**:
@@ -173,7 +173,7 @@ extra:
source: "endpoints/slack.py"
```
-### 2. Edit the function code
+## 2. Edit the function code
Modify the `endpoints/slack.py` file and add the following code:
@@ -252,7 +252,7 @@ class SlackEndpoint(Endpoint):
return Response(status=200, response="ok")
```
-### 3. Debug the Plugin
+## 3. Debug the Plugin
Go to the Dify platform and obtain the remote debugging address and key for your plugin.
@@ -274,7 +274,7 @@ Run `python -m main` to start the plugin. You should now see your plugin install
python -m main
```
-#### Configure the Plugin Endpoint
+### Configure the Plugin Endpoint
From the plugin management page in Dify, locate the newly installed test plugin and create a new endpoint. Provide a name, a Bot token, and select the app you want to connect.
@@ -310,7 +310,7 @@ Next, complete the Slack App setup:
---
-### 4. Verify the Plugin
+## 4. Verify the Plugin
In your code, `self.session.app.chat.invoke` is used to call the Dify application, passing in parameters such as `app_id` and `query`. The response is then returned to the Slack Bot. Run `python -m main` again to restart your plugin for debugging, and check whether Slack correctly displays the Dify App’s reply:
@@ -320,9 +320,9 @@ In your code, `self.session.app.chat.invoke` is used to call the Dify applicatio
---
-### 5. Package the Plugin (Optional)
+## 5. Package the Plugin (Optional)
-Once you confirm that the plugin works correctly, you can package and name it via the following command. After it runs, you’ll find a `slack_bot.difypkg` file in the current directory—your final plugin package. For detailed packaging steps, refer to [Package as a Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file).
+Once you confirm that the plugin works correctly, you can package and name it via the following command. After it runs, you’ll find a `slack_bot.difypkg` file in the current directory: your final plugin package. For detailed packaging steps, refer to [Package as a Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file).
```bash
# Replace ./slack_bot with your actual plugin project path.
@@ -334,7 +334,7 @@ Congratulations! You’ve successfully developed, tested, and packaged a plugin!
---
-### 6. Publish the Plugin (Optional)
+## 6. Publish the Plugin (Optional)
You can now upload it to the [Dify Marketplace repository](https://github.com/langgenius/dify-plugins) for public release. Before publishing, ensure your plugin meets the [Publishing to Dify Marketplace Guidelines](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace). Once approved, your code is merged into the main branch, and the plugin goes live on the [Dify Marketplace](https://marketplace.dify.ai/).
@@ -351,7 +351,7 @@ You can now upload it to the [Dify Marketplace repository](https://github.com/la
- [Publishing to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace) - Marketplace publishing guide
- [Endpoint Detailed Definition](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint) - Detailed Endpoint definition
-### Further Reading
+## Further Reading
For a complete Dify plugin project example, visit the [GitHub repository](https://github.com/langgenius/dify-plugins). You’ll also find additional plugins with full source code and implementation details.
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx
index 76abd9270..7e35ca043 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/develop-flomo-plugin.mdx
@@ -1,8 +1,8 @@
---
-title: 10-Minute Guide to Building Dify Plugins
-description: Learn how to build a functional Dify plugin that connects with Flomo note-taking service in just 10 minutes
+title: Flomo Tool (10-min)
+description: Build a functional Dify tool plugin that connects to the Flomo note-taking service end-to-end in about ten minutes
language: en
-standard_title: 10-Minute Guide to Building Dify Plugins
+standard_title: Flomo Tool (10-min)
---
## What you'll build
@@ -35,13 +35,11 @@ By the end of this guide, you'll have created a Dify plugin that:
```
- Get the latest Dify CLI from the [Dify GitHub releases page](https://github.com/langgenius/dify-plugin-daemon/releases)
-
+ Download the latest binary from the [Dify Plugin Daemon releases page](https://github.com/langgenius/dify-plugin-daemon/releases). Pick `dify-plugin-linux-amd64` for x86_64 or `dify-plugin-linux-arm64` for ARM.
+
```bash
- # Download appropriate version
chmod +x dify-plugin-linux-amd64
- mv dify-plugin-linux-amd64 dify
- sudo mv dify /usr/local/bin/
+ sudo mv dify-plugin-linux-amd64 /usr/local/bin/dify
```
@@ -100,8 +98,8 @@ resource:
plugins:
tools:
- - flomo.yaml
-
+ - provider/flomo.yaml
+
meta:
version: 0.0.1
arch:
@@ -115,7 +113,9 @@ meta:
## Step 3: Create the tool definition
-Create a `flomo.yaml` file to define your tool interface:
+A tool plugin uses two YAML files: a **provider** file that declares credentials and lists the tools, and one **tool** file per callable tool. See [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) for the full schema.
+
+Create `provider/flomo.yaml`:
```yaml
identity:
@@ -124,32 +124,61 @@ identity:
label:
en_US: Flomo Note
zh_Hans: Flomo 浮墨笔记
-description:
- human:
+ description:
en_US: Add notes to your Flomo account directly from Dify.
- zh_Hans: 直接从Dify添加笔记到您的Flomo账户。
- llm: >
- A tool that allows users to save notes to Flomo. Use this tool when users want to save important information from the conversation. The tool accepts a 'content' parameter that contains the text to be saved as a note.
-credential_schema:
+ zh_Hans: 直接从 Dify 添加笔记到您的 Flomo 账户。
+ icon: icon.png
+credentials_for_provider:
api_url:
- type: string
+ type: secret-input
required: true
label:
en_US: API URL
zh_Hans: API URL
- human_description:
+ placeholder:
+ en_US: https://flomoapp.com/iwh/{token}/{secret}/
+ help:
en_US: Flomo API URL from your Flomo account settings.
- zh_Hans: 从您的Flomo账户设置中获取的API URL。
-tool_schema:
- content:
+ zh_Hans: 从您的 Flomo 账户设置中获取的 API URL。
+tools:
+ - tools/flomo.yaml
+extra:
+ python:
+ source: provider/flomo.py
+```
+
+Create `tools/flomo.yaml`:
+
+```yaml
+identity:
+ name: flomo
+ author: yourname
+ label:
+ en_US: Save to Flomo
+ zh_Hans: 保存到 Flomo
+description:
+ human:
+ en_US: Save the conversation content as a Flomo note.
+ zh_Hans: 将对话内容保存为 Flomo 笔记。
+ llm: >
+ Saves content to the user's Flomo account. Use this tool when the user
+ asks to save, capture, or remember the current message. Takes a single
+ `content` parameter containing the text to save.
+parameters:
+ - name: content
type: string
required: true
label:
- en_US: Note Content
+ en_US: Note content
zh_Hans: 笔记内容
human_description:
en_US: Content to save as a note in Flomo.
- zh_Hans: 要保存为Flomo笔记的内容。
+ zh_Hans: 要保存为 Flomo 笔记的内容。
+ llm_description: The text to save as a Flomo note.
+ form: llm
+extra:
+ python:
+ source: tools/flomo.py
```
## Step 4: Implement core utility functions
@@ -262,12 +291,11 @@ Always handle exceptions gracefully and return user-friendly error messages. Rem
Edit the `.env` file with your Dify environment details:
```
INSTALL_METHOD=remote
- REMOTE_INSTALL_HOST=debug-plugin.dify.dev
- REMOTE_INSTALL_PORT=5003
+ REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=your_debug_key
```
-
- You can find your debug key and host in the Dify dashboard: click the "Plugins" icon in the top right corner, then click the debug icon. In the pop-up window, copy the "API Key" and "Host Address".
+
+ You can find your debug URL and key in the Dify dashboard: click the **Plugins** icon in the top-right corner, then click the debug icon. Copy the **API Key** and **Host Address** (the host already includes the port).
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx
index 7916e6bd5..88192eacf 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/develop-md-exporter.mdx
@@ -1,5 +1,5 @@
---
-title: Build a Markdown Exporter Plugin
+title: Markdown Exporter
description: Learn how to create a plugin that exports conversations to different document formats
language: en
standard_title: Building a Markdown Exporter Plugin
@@ -454,8 +454,7 @@ plugin = PluginRunner(
Configure it with your Dify environment details:
```
INSTALL_METHOD=remote
- REMOTE_INSTALL_HOST=debug-plugin.dify.dev
- REMOTE_INSTALL_PORT=5003
+ REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=your_debug_key
```
@@ -507,7 +506,7 @@ Here are some interesting ways to extend this plugin:
The core challenge in document conversion is maintaining formatting and structure. The approach used in this plugin first converts markdown to HTML (an intermediate format), then processes that HTML into the target format.
-This two-step process provides flexibility—you could extend it to support additional formats by simply adding new output modules that work with the HTML representation.
+This two-step process provides flexibility: you could extend it to support additional formats by simply adding new output modules that work with the HTML representation.
For PDF generation, WeasyPrint was chosen because it offers high-quality PDF rendering with CSS support. For Word documents, python-docx provides granular control over document structure.
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx
index 02d98f483..3f7f0a335 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/develop-multimodal-data-processing-tool.mdx
@@ -1,5 +1,6 @@
---
-title: Build Tool Plugins for Multimodal Data Processing in Knowledge Pipelines
+title: Multimodal Tool
+description: Configure a tool plugin to emit images, audio, or video so the Knowledge Base node can embed multimodal outputs alongside text
---
In knowledge pipelines, the Knowledge Base node supports input in two multimodal data formats: `multimodal-Parent-Child` and `multimodal-General`.
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx
index e217f6d47..433fbfb8c 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx
@@ -6,7 +6,7 @@ dimensions:
level: intermediate
standard_title: Endpoint
language: en
-title: Neko Cat Endpoint
+title: Endpoint Plugin
description: Authors Yeuoly, Allen. This document details the structure and implementation
of Endpoints in Dify plugins, using the Neko Cat project as an example. It covers
defining Endpoint groups, configuring interfaces, implementing the _invoke method,
@@ -14,11 +14,9 @@ description: Authors Yeuoly, Allen. This document details the structure and impl
of various YAML configuration fields.
---
-# Endpoint
+This document uses the [Neko Cat](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko) project as an example to explain the structure of Endpoints within a plugin. Endpoints are HTTP interfaces exposed by the plugin, which can be used for integration with external systems. For the complete plugin code, see the [GitHub repository](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko).
-This document uses the [Neko Cat](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint) project as an example to explain the structure of Endpoints within a plugin. Endpoints are HTTP interfaces exposed by the plugin, which can be used for integration with external systems. For the complete plugin code, please refer to the [GitHub repository](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko).
-
-### Group Definition
+## Group Definition
An `Endpoint` group is a collection of multiple `Endpoints`. When creating a new `Endpoint` within a Dify plugin, you might need to fill in the following configuration.
@@ -32,7 +30,7 @@ Besides the `Endpoint Name`, you can add new form items by writing the group's c
-#### **Structure**
+### **Structure**
* `settings` (map[string] [ProviderConfig](/en/develop-plugin/features-and-specs/plugin-types/general-specifications#providerconfig)): Endpoint configuration definition.
* `endpoints` (list[string], required): Points to the specific `endpoint` interface definitions.
@@ -57,7 +55,7 @@ endpoints:
- endpoints/neko.yaml
```
-### Interface Definition
+## Interface Definition
* `path` (string): Follows the Werkzeug interface standard.
* `method` (string): Interface method, only supports `HEAD`, `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`.
@@ -73,7 +71,7 @@ extra:
source: "endpoints/duck.py"
```
-### Interface Implementation
+## Interface Implementation
You need to implement a subclass that inherits from `dify_plugin.Endpoint` and implement the `_invoke` method.
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx
index 98b82b85d..e79c602d0 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/tool-oauth.mdx
@@ -1,5 +1,6 @@
---
-title: Add OAuth Support to Your Tool Plugin
+title: Tool OAuth
+description: Replace manual API-key entry with an OAuth authorization flow so users grant access to third-party services with one click
---
@@ -14,6 +15,33 @@ OAuth is a better way to authorize tool plugins that need to access user data fr
OAuth in Dify involves **two separate flows** that developers should understand and design for.
+```mermaid
+sequenceDiagram
+ autonumber
+ participant Admin as Admin / Developer
+ participant Service as Third-party Service
+ participant Dify
+ participant User
+
+ rect rgb(235, 245, 255)
+ Note over Admin,Dify: Flow 1: One-time OAuth client setup
+ Admin->>Service: Register OAuth app
+ Service-->>Admin: client_id + client_secret
+ Admin->>Dify: Configure plugin OAuth client
+ end
+
+ rect rgb(245, 255, 235)
+ Note over User,Service: Flow 2: Per-user authorization
+ User->>Dify: Click "Authorize"
+ Dify->>Service: Redirect to consent screen
+ User->>Service: Approve
+ Service-->>Dify: Authorization code
+ Dify->>Service: Exchange for access token
+ Service-->>Dify: Access + refresh tokens
+ Dify-->>User: Tool ready to use
+ end
+```
+
### Flow 1: OAuth Client Setup (Admin / Developer Flow)
@@ -171,7 +199,6 @@ def _oauth_get_authorization_url(self, redirect_uri: str, system_credentials: Ma
return f"{self._AUTH_URL}?{urllib.parse.urlencode(params)}"
```
-
```python _oauth_get_credentials expandable
def _oauth_get_credentials(
self, redirect_uri: str, system_credentials: Mapping[str, Any], request: Request
@@ -247,7 +274,6 @@ def _oauth_get_credentials(
raise ToolProviderOAuthError(f"Failed to exchange authorization code: {str(e)}")
```
-
```python _oauth_refresh_credentials
def _oauth_refresh_credentials(
self, redirect_uri: str, system_credentials: Mapping[str, Any], credentials: Mapping[str, Any]
@@ -339,10 +365,10 @@ For plugins that support both OAuth and API_KEY authentication, you can use `sel
### 4. Specify the Correct Versions
-Previous versions of the plugin SDK and Dify do not support OAuth authentication. Therefore, you need to set the plugin SDK version to:
+OAuth requires a recent SDK and Dify version. Pin the plugin SDK in `requirements.txt`:
```
-dify_plugin>=0.4.2,<0.5.0.
+dify_plugin>=0.5.0
```
In `manifest.yaml`, add the minimum Dify version:
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin.mdx
index 198b939ff..01eb404ab 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin.mdx
@@ -34,14 +34,14 @@ In this article, **"Tool Plugin"** refers to a complete project that includes to
This article will use `Google Search` as an example to demonstrate how to quickly develop a tool plugin.
-### Prerequisites
+## Prerequisites
- Dify plugin scaffolding tool
- Python environment (version 3.12)
-For detailed instructions on how to prepare the plugin development scaffolding tool, please refer to [Initializing Development Tools](/en/develop-plugin/getting-started/cli). If you are developing a plugin for the first time, it is recommended to read [Dify Plugin Development: Hello World Guide](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) first.
+For detailed instructions on how to prepare the plugin development scaffolding tool, please refer to [Initializing Development Tools](/en/develop-plugin/getting-started/cli).
-### Create a New Project
+## Create a New Project
Run the scaffolding command line tool to create a new Dify plugin project.
@@ -57,7 +57,7 @@ dify plugin init
> In the following text, `dify` will be used as a command line example. If you encounter any issues, please replace the `dify` command with the path to the command line tool.
-### Choose Plugin Type and Template
+## Choose Plugin Type and Template
All templates in the scaffolding tool provide complete code projects. In this example, select the `Tool` plugin.
@@ -67,7 +67,7 @@ All templates in the scaffolding tool provide complete code projects. In this ex
-#### Configure Plugin Permissions
+### Configure Plugin Permissions
The plugin also needs permissions to read from the Dify platform. Grant the following permissions to this example plugin:
@@ -84,9 +84,9 @@ After checking all permission items, press Enter to complete the plugin creation
-### Develop the Tool Plugin
+## Develop the Tool Plugin
-#### 1. Create the Tool Provider File
+### 1. Create the Tool Provider File
The tool provider file is a yaml format file, which can be understood as the basic configuration entry for the tool plugin, used to provide necessary authorization information to the tool.
@@ -142,7 +142,7 @@ class ToolLabelEnum(Enum):
OTHER = 'other'
```
-#### **2. Complete Third-Party Service Credentials**
+### **2. Complete Third-Party Service Credentials**
For development convenience, we choose to use the Google Search API provided by the third-party service `SerpApi`. `SerpApi` requires an API Key for use, so we need to add the `credentials_for_provider` field in the `yaml` file.
@@ -188,7 +188,7 @@ extra:
- You need to specify which tools the provider includes. This example only includes one `tools/google_search.yaml` file.
- As a provider, in addition to defining its basic information, you also need to implement some of its code logic, so you need to specify its implementation logic. In this example, we put the code file for the functionality in `google.py`, but we won't implement it yet, but instead write the code for `google_search` first.
-#### 3. Fill in the Tool YAML File
+### 3. Fill in the Tool YAML File
A tool plugin can have multiple tool functions, and each tool function needs a `yaml` file for description, including basic information about the tool function, parameters, output, etc.
@@ -248,7 +248,7 @@ extra:
- `placeholder` prompt text for the input field, can be set when the form type is `form` and the parameter type is `string`, `number`, `secret-input`, supports multiple languages.
- `llm_description` introduction passed to the LLM. To make the LLM better understand this parameter, please write as detailed information as possible about this parameter here, so that the LLM can understand the parameter.
-#### 4. Prepare Tool Code
+### 4. Prepare Tool Code
After filling in the configuration information for the tool, you can start writing the code for the tool's functionality, implementing the logical purpose of the tool. Create `google_search.py` in the `/tools` directory with the following content:
@@ -299,7 +299,7 @@ class GoogleSearchTool(Tool):
This example means requesting `serpapi` and using `self.create_json_message` to return a formatted `json` data string. If you want to learn more about return data types, you can refer to the [Remote Debugging Plugins](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) and [Persistent Storage KV](/en/develop-plugin/features-and-specs/plugin-types/persistent-storage-kv) documents.
-#### 5. Complete the Tool Provider Code
+### 5. Complete the Tool Provider Code
Finally, you need to create an implementation code for the provider to implement the credential validation logic. If credential validation fails, a `ToolProviderCredentialValidationError` exception will be thrown. After validation succeeds, the `google_search` tool service will be correctly requested.
@@ -323,7 +323,7 @@ class GoogleProvider(ToolProvider):
raise ToolProviderCredentialValidationError(str(e))
```
-### Debug the Plugin
+## Debug the Plugin
After completing plugin development, you need to test whether the plugin can function properly. Dify provides a convenient remote debugging method to help you quickly verify the plugin's functionality in a test environment.
@@ -349,7 +349,7 @@ Run the `python -m main` command to start the plugin. On the plugins page, you c
-### Package the Plugin (Optional)
+## Package the Plugin (Optional)
After confirming that the plugin can run normally, you can package and name the plugin using the following command line tool. After running, you will discover a `google.difypkg` file in the current folder, which is the final plugin package.
@@ -361,21 +361,21 @@ dify plugin package ./google
Congratulations, you have completed the entire process of developing, debugging, and packaging a tool-type plugin!
-### Publish the Plugin (Optional)
+## Publish the Plugin (Optional)
If you want to publish the plugin to the Dify Marketplace, please ensure that your plugin follows the specifications in [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace). After passing the review, the code will be merged into the main branch and automatically launched to the [Dify Marketplace](https://marketplace.dify.ai/).
[Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview)
-### Explore More
+## Explore More
-#### **Quick Start**:
+### **Quick Start**:
- [Developing Extension Plugins](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint)
- [Developing Model Plugins](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider)
- [Bundle Plugins: Packaging Multiple Plugins](/en/develop-plugin/features-and-specs/advanced-development/bundle)
-#### **Plugin Interface Documentation**:
+### **Plugin Interface Documentation**:
- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) - Manifest Structure and Tool Specifications
- [Endpoint](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint) - Detailed Endpoint Definition
diff --git a/en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin.mdx b/en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin.mdx
index ccfb1aac3..cb7b26dc9 100644
--- a/en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin.mdx
+++ b/en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin.mdx
@@ -1,5 +1,6 @@
---
title: Trigger Plugin
+description: Build a Dify 1.10.0+ trigger plugin that turns third-party webhook events into workflow start signals
---
## What Is a Trigger Plugin?
@@ -28,7 +29,7 @@ To handle webhook events from different platforms in a unified way, Dify defines
- **Subscription**: Webhook-based event dispatch requires **registering Dify's network address on a third-party platform's developer console as the target server. In Dify, this configuration process is called a *Subscription*.**
-- **Event**: A platform may send multiple types of events—such as *email received*, *email deleted*, or *email marked as read*—all of which are pushed to the registered address. A trigger plugin can handle multiple event types, with each event corresponding to a plugin trigger node in a Dify workflow.
+- **Event**: A platform may send multiple types of events (such as *email received*, *email deleted*, or *email marked as read*), all of which are pushed to the registered address. A trigger plugin can handle multiple event types, with each event corresponding to a plugin trigger node in a Dify workflow.
## Plugin Development
@@ -207,7 +208,7 @@ Taking the Issue event as an example, you can define the event and its implement
### Event Filtering
-To filter out certain events—for example, to focus only on Issue events with a specific label—you can add `parameters` to the event definition in `issues.yaml`. Then, in the `_on_event` method, you can throw an `EventIgnoreError` exception to filter out events that do not meet the configured criteria.
+To filter out certain events (for example, to focus only on Issue events with a specific label), you can add `parameters` to the event definition in `issues.yaml`. Then, in the `_on_event` method, you can throw an `EventIgnoreError` exception to filter out events that do not meet the configured criteria.
diff --git a/en/develop-plugin/features-and-specs/advanced-development/bundle.mdx b/en/develop-plugin/features-and-specs/advanced-development/bundle.mdx
index 67210c57e..b2b7cc3aa 100644
--- a/en/develop-plugin/features-and-specs/advanced-development/bundle.mdx
+++ b/en/develop-plugin/features-and-specs/advanced-development/bundle.mdx
@@ -22,14 +22,14 @@ You can use the Dify CLI tool to package multiple plugins into a Bundle. Bundle
* `GitHub` type. Stores the GitHub repository address, release version number, and asset filename. During import, Dify will access the corresponding GitHub repository to download the plugin package.
* `Package` type. The plugin package is stored directly within the Bundle. It does not store reference sources, but this might lead to a larger Bundle package size.
-### Prerequisites
+## Prerequisites
* Dify plugin scaffolding tool
* Python environment (version 3.12)
For detailed instructions on how to prepare the plugin development scaffolding tool, please refer to [Initialize Development Tools](/en/develop-plugin/getting-started/cli).
-### Create a Bundle Project
+## Create a Bundle Project
In the current directory, run the scaffolding command-line tool to create a new plugin package project.
@@ -43,7 +43,7 @@ If you have renamed the binary file to `dify` and copied it to the `/usr/local/b
dify bundle init
```
-#### 1. Fill in Plugin Information
+### 1. Fill in Plugin Information
Follow the prompts to configure the plugin name, author information, and plugin description. If you are collaborating as a team, you can also enter the organization name as the author.
@@ -59,7 +59,7 @@ After filling in the information and pressing Enter, the Bundle plugin project d
-#### 2. Add Dependencies
+### 2. Add Dependencies
* **Marketplace**
@@ -91,7 +91,7 @@ dify-plugin bundle append package . --package_path=./openai.difypkg
Where `package_path` is the directory of the plugin package.
-### Package the Bundle Project
+## Package the Bundle Project
Run the following command to package the Bundle plugin:
diff --git a/en/develop-plugin/features-and-specs/advanced-development/customizable-model.mdx b/en/develop-plugin/features-and-specs/advanced-development/customizable-model.mdx
index d135a1aba..56e472100 100644
--- a/en/develop-plugin/features-and-specs/advanced-development/customizable-model.mdx
+++ b/en/develop-plugin/features-and-specs/advanced-development/customizable-model.mdx
@@ -17,7 +17,7 @@ description: This document details how to integrate custom models into Dify, usi
A **custom model** refers to an LLM that you deploy or configure on your own. This document uses the [Xinference model](https://inference.readthedocs.io/en/latest/) as an example to demonstrate how to integrate a custom model into your **model plugin**.
-By default, a custom model automatically includes two parameters—its **model type** and **model name**—and does not require additional definitions in the provider YAML file.
+By default, a custom model automatically includes two parameters (its **model type** and **model name**) and does not require additional definitions in the provider YAML file.
You do not need to implement `validate_provider_credential` in your provider configuration file. During runtime, based on the user’s choice of model type or model name, Dify automatically calls the corresponding model layer’s `validate_credentials` method to verify credentials.
@@ -137,7 +137,7 @@ Once you’ve defined these parameters, the YAML configuration for your custom m
Since Xinference supports llm, rerank, speech2text, and tts, you should create corresponding directories under /models, each containing its respective feature code.
-Below is an example for an llm-type model. You’d create a file named llm.py, then define a class—such as XinferenceAILargeLanguageModel—that extends \_\_base.large\_language\_model.LargeLanguageModel. This class should include:
+Below is an example for an llm-type model. You’d create a file named llm.py, then define a class (such as XinferenceAILargeLanguageModel) that extends \_\_base.large\_language\_model.LargeLanguageModel. This class should include:
* **LLM Invocation**
@@ -268,9 +268,7 @@ def get_customizable_model_schema(self, model: str, credentials: dict) -> AIMode
)
)
- """
- some NOT IMPORTANT code here
- """
+ # ... additional ParameterRule entries omitted for brevity ...
entity = AIModelEntity(
model=model,
diff --git a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app.mdx b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app.mdx
index 849947858..2525c615d 100644
--- a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app.mdx
+++ b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app.mdx
@@ -23,15 +23,15 @@ Reverse invoking an App means that a plugin can access data from an App within D
Please note that plugins are only allowed to access Apps within the Workspace where the plugin resides.
-### Call the Chat Interface
+## Call the Chat Interface
-#### **Entry Point**
+### **Entry Point**
```python
self.session.app.chat
```
-#### **Interface Specification**
+### **Interface Specification**
```python
def invoke(
@@ -47,7 +47,7 @@ Please note that plugins are only allowed to access Apps within the Workspace wh
When `response_mode` is `streaming`, this interface will directly return `Generator[dict]`. Otherwise, it returns `dict`. For specific interface fields, please refer to the return results of `ServiceApi`.
-#### **Use Case**
+### **Use Case**
We can call a Chat type App within an `Endpoint` and return the result directly.
@@ -65,15 +65,12 @@ class Duck(Endpoint):
app_id = values["app_id"]
def generator():
- # Note: The original example incorrectly called self.session.app.workflow.invoke
- # It should call self.session.app.chat.invoke for a chat app.
- # Assuming a chat app is intended here based on the section title.
response = self.session.app.chat.invoke(
- app_id=app_id,
- inputs={}, # Provide actual inputs as needed
- response_mode="streaming",
- conversation_id="some-conversation-id", # Provide a conversation ID if needed
- files=[]
+ app_id=app_id,
+ inputs={},
+ response_mode="streaming",
+ conversation_id="some-conversation-id",
+ files=[],
)
for data in response:
@@ -82,15 +79,15 @@ class Duck(Endpoint):
return Response(generator(), status=200, content_type="text/html")
```
-### Call the Workflow Interface
+## Call the Workflow Interface
-#### **Entry Point**
+### **Entry Point**
```python
self.session.app.workflow
```
-#### **Interface Specification**
+### **Interface Specification**
```python
def invoke(
@@ -103,9 +100,9 @@ class Duck(Endpoint):
pass
```
-### Call the Completion Interface
+## Call the Completion Interface
-#### **Entry Point**
+### **Entry Point**
```python
self.session.app.completion
diff --git a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-model.mdx b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-model.mdx
index ece1d56e6..2c42e92f2 100644
--- a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-model.mdx
+++ b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-model.mdx
@@ -20,15 +20,15 @@ However, please note that invoking a model requires passing a `ModelConfig` type
For example, for `LLM` type models, it also needs to include `completion_params` and `mode` parameters. You can manually construct this structure or use `model-selector` type parameters or configurations.
-### Invoke LLM
+## Invoke LLM
-#### **Entry Point**
+**Entry Point**
```python
self.session.model.llm
```
-#### **Endpoint**
+**Endpoint**
```python
def invoke(
@@ -44,7 +44,7 @@ For example, for `LLM` type models, it also needs to include `completion_params`
Please note that if the model you are invoking does not have `tool_call` capability, the `tools` passed here will not take effect.
-#### **Use Case**
+**Use Case**
If you want to invoke OpenAI's `gpt-4o-mini` model within a `Tool`, please refer to the following example code:
@@ -85,7 +85,7 @@ class LLMTool(Tool):
Note that the `query` parameter from `tool_parameters` is passed in the code.
-### **Best Practice**
+## **Best Practice**
It is not recommended to manually construct `LLMModelConfig`. Instead, allow users to select the model they want to use on the UI. In this case, you can modify the tool's parameter list by adding a `model` parameter as follows:
@@ -156,7 +156,7 @@ class LLMTool(Tool):
content='you are a helpful assistant'
),
UserPromptMessage(
- content=tool_parameters.get('query') # Assuming 'query' is still needed, otherwise use 'prompt' from parameters
+ content=tool_parameters.get('prompt')
)
],
stream=True
@@ -168,7 +168,7 @@ class LLMTool(Tool):
yield self.create_text_message(text=chunk.delta.message.content)
```
-### Invoke Summary
+## Invoke Summary
You can request this endpoint to summarize a piece of text. It will use the system model within your current workspace to summarize the text.
@@ -189,7 +189,7 @@ You can request this endpoint to summarize a piece of text. It will use the syst
) -> str:
```
-### Invoke TextEmbedding
+## Invoke TextEmbedding
**Entry Point**
@@ -201,12 +201,15 @@ You can request this endpoint to summarize a piece of text. It will use the syst
```python
def invoke(
- self, model_config: TextEmbeddingResult, texts: list[str]
+ self,
+ model_config: TextEmbeddingModelConfig,
+ texts: list[str],
+ input_type: EmbeddingInputType = EmbeddingInputType.QUERY,
) -> TextEmbeddingResult:
pass
```
-### Invoke Rerank
+## Invoke Rerank
**Entry Point**
@@ -223,7 +226,7 @@ You can request this endpoint to summarize a piece of text. It will use the syst
pass
```
-### Invoke TTS
+## Invoke TTS
**Entry Point**
@@ -242,7 +245,7 @@ You can request this endpoint to summarize a piece of text. It will use the syst
Please note that the `bytes` stream returned by the `tts` endpoint is an `mp3` audio byte stream. Each iteration returns a complete audio segment. If you want to perform more in-depth processing tasks, please choose an appropriate library.
-### Invoke Speech2Text
+## Invoke Speech2Text
**Entry Point**
@@ -261,7 +264,7 @@ Please note that the `bytes` stream returned by the `tts` endpoint is an `mp3` a
Where `file` is an audio file encoded in `mp3` format.
-### Invoke Moderation
+## Invoke Moderation
**Entry Point**
diff --git a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-node.mdx b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-node.mdx
index 64c0a9dcb..003b91b58 100644
--- a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-node.mdx
+++ b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-node.mdx
@@ -18,15 +18,15 @@ Reverse invoking a Node means that a plugin can access the capabilities of certa
The `ParameterExtractor` and `QuestionClassifier` nodes in `Workflow` encapsulate complex Prompt and code logic, enabling tasks that are difficult to solve with hardcoding through LLMs. Plugins can call these two nodes.
-### Call the Parameter Extractor Node
+## Call the Parameter Extractor Node
-#### **Entry Point**
+### **Entry Point**
```python
self.session.workflow_node.parameter_extractor
```
-#### **Interface**
+### **Interface**
```python
def invoke(
@@ -39,17 +39,18 @@ The `ParameterExtractor` and `QuestionClassifier` nodes in `Workflow` encapsulat
pass
```
-Here, `parameters` is a list of parameters to be extracted, `model` conforms to the `LLMModelConfig` specification, `query` is the source text for parameter extraction, and `instruction` provides any additional instructions that might be needed for the LLM. For the structure of `NodeResponse`, please refer to this [document](/en/develop-plugin/features-and-specs/plugin-types/general-specifications.mdx#noderesponse).
+Here, `parameters` is a list of parameters to be extracted, `model` conforms to the `LLMModelConfig` specification, `query` is the source text for parameter extraction, and `instruction` provides any additional instructions that might be needed for the LLM. For the structure of `NodeResponse`, please refer to this [document](/en/develop-plugin/features-and-specs/plugin-types/general-specifications#noderesponse).
-#### **Use Case**
+### **Use Case**
To extract a person's name from a conversation, you can refer to the following code:
```python
from collections.abc import Generator
-from dify_plugin.entities.tool import ToolInvokeMessage
from dify_plugin import Tool
-from dify_plugin.entities.workflow_node import ModelConfig, ParameterConfig, NodeResponse # Assuming NodeResponse is importable
+from dify_plugin.entities.tool import ToolInvokeMessage
+from dify_plugin.entities.workflow_node import ModelConfig, NodeResponse, ParameterConfig
+
class ParameterExtractorTool(Tool):
def _invoke(
@@ -73,25 +74,26 @@ class ParameterExtractorTool(Tool):
instruction="Extract the name of the person",
)
- # Assuming NodeResponse has an 'outputs' attribute which is a dictionary
- extracted_name = response.outputs.get("name", "Name not found")
+ extracted_name = response.outputs.get("name", "Name not found")
yield self.create_text_message(extracted_name)
```
-### Call the Question Classifier Node
+`NodeResponse` is a Pydantic model defined in `dify_plugin.entities.workflow_node` with three dictionary fields: `process_data`, `inputs`, and `outputs`. Extracted values live under `response.outputs`.
+
+## Call the Question Classifier Node
-#### **Entry Point**
+### **Entry Point**
```python
self.session.workflow_node.question_classifier
```
-#### **Interface**
+### **Interface**
```python
def invoke(
self,
- classes: list[ClassConfig], # Assuming ClassConfig is defined/imported
+ classes: list[ClassConfig],
model: ModelConfig,
query: str,
instruction: str = "",
@@ -99,7 +101,7 @@ class ParameterExtractorTool(Tool):
pass
```
-The interface parameters are consistent with `ParameterExtractor`. The final result is stored in `NodeResponse.outputs['class_name']`.
+`ClassConfig` is also exported from `dify_plugin.entities.workflow_node`. The interface parameters are consistent with `ParameterExtractor`. The final result is stored in `response.outputs["class_name"]`.
{/*
Contributing Section
diff --git a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-tool.mdx b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-tool.mdx
index 0e3dc45b6..d0f292e0e 100644
--- a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-tool.mdx
+++ b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-tool.mdx
@@ -25,7 +25,7 @@ In these cases, you need to call other existing tools within your plugin. These
These requirements can be met by calling the `self.session.tool` field of the plugin.
-### Call Installed Tools
+## Call Installed Tools
Allows the plugin to call various tools installed in the current Workspace, including other tool-type plugins.
@@ -46,7 +46,7 @@ Allows the plugin to call various tools installed in the current Workspace, incl
Here, `provider` is the plugin ID plus the tool provider name, formatted like `langgenius/google/google`. `tool_name` is the specific tool name, and `parameters` are the arguments passed to the tool.
-### Call Workflow as Tool
+## Call Workflow as Tool
For more information on Workflow as Tool, please refer to the [Tool Plugin documentation](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin).
@@ -67,7 +67,7 @@ For more information on Workflow as Tool, please refer to the [Tool Plugin docum
In this case, `provider` is the ID of this tool, and `tool_name` is specified during the creation of the tool.
-### Call Custom Tool
+## Call Custom Tool
**Entry Point**
diff --git a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation.mdx b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation.mdx
index 19889a9ec..1bed8b3db 100644
--- a/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation.mdx
+++ b/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation.mdx
@@ -16,7 +16,7 @@ description: This document briefly introduces the reverse invocation capability
Plugins can freely call some services within the main Dify platform to enhance their capabilities.
-### Callable Dify Modules
+## Callable Dify Modules
* [App](/en/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app)
diff --git a/en/develop-plugin/features-and-specs/plugin-types/general-specifications.mdx b/en/develop-plugin/features-and-specs/plugin-types/general-specifications.mdx
index c31fe5d69..5d2c2aab3 100644
--- a/en/develop-plugin/features-and-specs/plugin-types/general-specifications.mdx
+++ b/en/develop-plugin/features-and-specs/plugin-types/general-specifications.mdx
@@ -10,18 +10,18 @@ title: General Specs
description: This article will briefly introduce common structures in plugin development. During development, it is strongly recommended to read this alongside [Basic Concepts of Plugin Development](/en/develop-plugin/getting-started/getting-started-dify-plugin) and the [Developer Cheatsheet](/en/develop-plugin/getting-started/cli) for a better understanding of the overall architecture.
---
-### Path Specifications
+## Path Specifications
When filling in file paths in Manifest or any yaml files, follow these two specifications depending on the type of file:
* If the target file is a multimedia file such as an image or video, for example when filling in the plugin's `icon`, you should place these files in the `_assets` folder under the plugin's root directory.
* If the target file is a regular text file, such as `.py` or `.yaml` code files, you should fill in the absolute path of the file within the plugin project.
-### Common Structures
+## Common Structures
When defining plugins, there are some data structures that can be shared between tools, models, and Endpoints. These shared structures are defined here.
-#### I18nObject
+### I18nObject
`I18nObject` is an internationalization structure that conforms to the [IETF BCP 47](https://tools.ietf.org/html/bcp47) standard. Currently, four languages are supported:
@@ -41,7 +41,7 @@ When defining plugins, there are some data structures that can be shared between
Portuguese (Brazil)
-#### ProviderConfig
+### ProviderConfig
`ProviderConfig` is a common provider form structure, applicable to both `Tool` and `Endpoint`
@@ -85,7 +85,7 @@ When defining plugins, there are some data structures that can be shared between
Placeholder text in multiple languages, following [IETF BCP 47](https://tools.ietf.org/html/bcp47)
-#### ProviderConfigOption(object)
+### ProviderConfigOption(object)
The value of the option
@@ -95,7 +95,7 @@ When defining plugins, there are some data structures that can be shared between
Display label for the option, following [IETF BCP 47](https://tools.ietf.org/html/bcp47)
-#### ProviderConfigType(string)
+### ProviderConfigType(string)
Configuration information that will be encrypted
@@ -129,7 +129,7 @@ When defining plugins, there are some data structures that can be shared between
Dataset selector (TBD)
-#### ProviderConfigScope(string)
+### ProviderConfigScope(string)
When `type` is `model-selector`:
@@ -185,7 +185,7 @@ When `type` is `tool-selector`:
Workflow tools only
-#### ModelConfig
+### ModelConfig
Model provider name containing plugin_id, in the form of `langgenius/openai/openai`
@@ -199,7 +199,7 @@ When `type` is `tool-selector`:
Enumeration of model types, refer to the [Model Design Rules](/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules#modeltype) document
-#### NodeResponse
+### NodeResponse
Variables that are finally input to the node
@@ -213,7 +213,7 @@ When `type` is `tool-selector`:
Data generated during node execution
-#### ToolSelector
+### ToolSelector
Tool provider name
diff --git a/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules.mdx b/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules.mdx
index 0160f127a..43a4e56e0 100644
--- a/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules.mdx
+++ b/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules.mdx
@@ -15,12 +15,28 @@ description: This document defines in detail the core concepts and structures fo
modes.
---
-* Model provider rules are based on the [Provider](#provider) entity.
-* Model rules are based on the [AIModelEntity](#aimodelentity) entity.
+A model plugin describes itself with two entities: a **Provider** (this page's [Provider](#provider) section) that handles authentication and lists supported models, and one **AIModelEntity** ([AIModelEntity](#aimodelentity)) per model declaring its type, features, and parameters.
-> All entities below are based on `Pydantic BaseModel`, and can be found in the `entities` module.
+> All entities below are `Pydantic BaseModel` subclasses from the `dify_plugin.entities.model` module.
-### Provider
+## Quick Decision
+
+
+
+ User pastes an API key, gets your full model list. Set `configurate_methods: [predefined-model]` and define each model's AIModelEntity in YAML.
+
+
+ User configures their own model name and base URL (OpenAI-compatible endpoints, custom deployments). Use `configurate_methods: [customizable-model]` and see [Customizable Model](/en/develop-plugin/features-and-specs/advanced-development/customizable-model).
+
+
+ Built-in catalog plus user-added custom models. Combine both `configurate_methods` values.
+
+
+ For an end-to-end example, see [Creating a New Model Provider](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider).
+
+
+
+## Provider
Provider identifier, e.g.: `openai`
@@ -122,7 +138,7 @@ description: This document defines in detail the core concepts and structures fo
Model credential specifications
-### AIModelEntity
+## AIModelEntity
Model identifier, e.g.: `gpt-3.5-turbo`
@@ -220,7 +236,7 @@ description: This document defines in detail the core concepts and structures fo
Whether deprecated. If deprecated, the model list will no longer display it, but those already configured can continue to be used. Default is False.
-### ModelType
+## ModelType
Text generation model
@@ -246,7 +262,7 @@ description: This document defines in detail the core concepts and structures fo
Content moderation
-### ConfigurateMethod
+## ConfigurateMethod
Predefined model - Indicates that the user only needs to configure unified provider credentials to use predefined models under the provider.
@@ -260,7 +276,7 @@ description: This document defines in detail the core concepts and structures fo
Fetch from remote - Similar to the `predefined-model` configuration method, only unified provider credentials are needed, but the models are fetched from the provider using the credential information.
-### ModelFeature
+## ModelFeature
Agent reasoning, generally models over 70B have chain-of-thought capabilities.
@@ -282,7 +298,7 @@ description: This document defines in detail the core concepts and structures fo
Streaming tool calling
-### FetchFrom
+## FetchFrom
Predefined model
@@ -292,7 +308,7 @@ description: This document defines in detail the core concepts and structures fo
Remote model
-### LLMMode
+## LLMMode
Text completion
@@ -302,7 +318,7 @@ description: This document defines in detail the core concepts and structures fo
Chat
-### ParameterRule
+## ParameterRule
Actual parameter name for model call
@@ -392,7 +408,7 @@ You can directly set the template variable name in `use_template`, which will us
Dropdown option values, only applicable when `type` is `string`, if not set or is null, then option values are not restricted
-### PriceConfig
+## PriceConfig
Input unit price, i.e., Prompt unit price
@@ -410,13 +426,13 @@ You can directly set the template variable name in `use_template`, which will us
Currency unit
-### ProviderCredentialSchema
+## ProviderCredentialSchema
Credential form specifications
-### ModelCredentialSchema
+## ModelCredentialSchema
Model identifier, default variable name is `model`
@@ -450,7 +466,7 @@ You can directly set the template variable name in `use_template`, which will us
Credential form specifications
-### CredentialFormSchema
+## CredentialFormSchema
Form item variable name
@@ -504,7 +520,7 @@ You can directly set the template variable name in `use_template`, which will us
Display when other form item values meet conditions, empty means always display
-#### FormType
+### FormType
Text input component
@@ -526,7 +542,7 @@ You can directly set the template variable name in `use_template`, which will us
Switch component, only supports `true` and `false`
-#### FormOption
+### FormOption
Label
@@ -548,7 +564,7 @@ You can directly set the template variable name in `use_template`, which will us
Display when other form item values meet conditions, empty means always display
-#### FormShowOnObject
+### FormShowOnObject
Other form item variable name
diff --git a/en/develop-plugin/features-and-specs/plugin-types/model-schema.mdx b/en/develop-plugin/features-and-specs/plugin-types/model-schema.mdx
index fb54f7b0c..c3dc1ea28 100644
--- a/en/develop-plugin/features-and-specs/plugin-types/model-schema.mdx
+++ b/en/develop-plugin/features-and-specs/plugin-types/model-schema.mdx
@@ -15,9 +15,22 @@ description: Comprehensive guide to the Dify model plugin API including implemen
This document details the interfaces and data structures required to implement Dify model plugins. It serves as a technical reference for developers integrating AI models with the Dify platform.
-Before diving into this API reference, we recommend first reading the [Model Design Rules](/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules) and [Model Plugin Introduction](/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules) for conceptual understanding.
+Before diving into this API reference, we recommend reading [Model Design Rules](/en/develop-plugin/features-and-specs/plugin-types/model-designing-rules) for the conceptual model and [Creating a New Model Provider](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) for a step-by-step walkthrough.
+### Quick Decision: Which Method Do I Implement?
+
+| If your model is a... | Implement |
+| :--- | :--- |
+| Chat/completion LLM | `LargeLanguageModel._invoke`, `_get_num_tokens` |
+| Embedding model | `TextEmbeddingModel._invoke`, `_get_num_tokens` |
+| Rerank model | `RerankModel._invoke` |
+| Speech-to-text | `Speech2TextModel._invoke` |
+| Text-to-speech | `Text2SpeechModel._invoke` |
+| Moderation | `ModerationModel._invoke` |
+
+Every provider also implements `validate_provider_credentials` (provider-level auth) and, if the model is user-configurable, `validate_credentials` per model type.
+
Learn how to implement model provider classes for different AI service providers
@@ -820,7 +833,6 @@ Most text-to-speech APIs require you to specify a voice along with the model. Co
Long text inputs may need to be chunked for better speech synthesis quality. Consider implementing text preprocessing to handle punctuation, numbers, and special characters properly.
-
### Moderation Implementation
diff --git a/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme.mdx b/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme.mdx
index 825a5352b..b889db7b6 100644
--- a/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme.mdx
+++ b/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme.mdx
@@ -7,40 +7,79 @@ dimensions:
standard_title: Multilingual README
language: en
title: Multilingual README
-description: This article introduces the file specifications for Dify plugins' multilingual READMEs and their display rule in Dify Marketplace.
+description: Add per-language README files so Dify Marketplace shows your plugin's documentation in each user's preferred language
---
-You can create multilingual READMEs for your plugin, which will be displayed in [Dify Marketplace](https://marketplace.dify.ai) and other locations based on the user's preferred language.
+A plugin's README is the first thing users read on the [Dify Marketplace](https://marketplace.dify.ai) detail page. Adding translations lets non-English users read your docs in their own language without losing the original.
-### README **File Specifications**
+## File Specifications
-| **Language** | Required | Filename | Path | **Description** |
-| :------------------ | :------- | :-------------------------- | :----------------------------------------------------- | :--------------------------------------------------------------- |
-| **English** | Yes | `README.md` | Plugin root directory | / |
-| **Other Languages** | No | `README_.md` | In the `readme` folder under the plugin root directory | Currently supports Japanese, Portuguese, and Simplified Chinese. |
+| Language | Required | Filename | Path |
+| :--- | :--- | :--- | :--- |
+| English | Yes | `README.md` | Plugin root |
+| Simplified Chinese | No | `README_zh_Hans.md` | `readme/` |
+| Japanese | No | `README_ja_JP.md` | `readme/` |
+| Portuguese (Brazil) | No | `README_pt_BR.md` | `readme/` |
-Here's an example of the directory structure:
+All files must be UTF-8 encoded. The English `README.md` always stays in the plugin root; every other language goes inside a `readme/` subdirectory.
```bash
-...
-├── main.py
-├── manifest.yaml
-├── readme
-│ ├── README_ja_JP.md
-│ ├── README_pt_BR.md
-│ └── README_zh_Hans.md
+your_plugin/
├── README.md
-...
+├── readme/
+│ ├── README_zh_Hans.md
+│ ├── README_ja_JP.md
+│ └── README_pt_BR.md
+├── manifest.yaml
+├── main.py
+└── ...
+```
+
+## Recommended Structure
+
+Keep READMEs concise, under ~500 words. The Marketplace detail page surfaces the README directly, so optimize it for someone evaluating whether to install:
+
+```markdown
+# Plugin Name
+
+One-sentence summary of what the plugin does.
+
+## Features
+
+- Key capability 1
+- Key capability 2
+- Key capability 3
+
+## Setup
+
+1. Where to get the credentials (link to the upstream service).
+2. Where to paste them in Dify.
+
+## Usage
+
+A minimal example — for a tool, show the inputs and outputs. For a model
+provider, show the model selector. Screenshots help.
+
+## Privacy
+
+Briefly describe what data the plugin sends to third parties. Link to your
+PRIVACY.md.
```
-### How Multilingual READMEs are Displayed **in Marketplace**
+Avoid putting full API reference or development notes in the README; those belong in source comments or a separate docs site. The Marketplace audience is end users picking a plugin, not contributors reading your codebase.
+
+## How the Marketplace Picks a Language
-When your plugin has a README in the user's preferred language, the plugin's detail page in Dify Marketplace will display that language version of the README.
+When a visitor opens your plugin's detail page, the Marketplace looks for a README matching their UI language. If a match exists in the `readme/` directory, it renders that file. Otherwise it falls back to the English `README.md`.
+
+ Language codes are matched exactly: `README_zh_Hans.md` serves Simplified Chinese only; Traditional Chinese users see the English fallback.
+
+
{/*
Contributing Section
DO NOT edit this section!
@@ -50,4 +89,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest.mdx b/en/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest.mdx
index a93dabac8..3e6131322 100644
--- a/en/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest.mdx
+++ b/en/develop-plugin/features-and-specs/plugin-types/plugin-info-by-manifest.mdx
@@ -7,13 +7,14 @@ dimensions:
standard_title: Plugin info by Manifest
language: en
title: Manifest
+description: YAML schema for the plugin manifest that declares name, author, runtime, resources, permissions, and which tools/models/endpoints the plugin ships
---
The Manifest is a YAML-compliant file that defines the most basic information of a **plugin**, including but not limited to the plugin name, author, included tools, models, etc. For the overall architecture of the plugin, please refer to [Basic Concepts of Plugin Development](/en/develop-plugin/getting-started/getting-started-dify-plugin) and [Developer Cheatsheet](/en/develop-plugin/dev-guides-and-walkthroughs/cheatsheet).
If the format of this file is incorrect, the parsing and packaging process of the plugin will fail.
-### Code Example
+## Code Example
Below is a simple example of a Manifest file. The meaning and function of each data item will be explained later.
@@ -58,7 +59,7 @@ meta:
privacy: "./privacy.md"
```
-### Structure
+## Structure
The version of the plugin.
diff --git a/en/develop-plugin/features-and-specs/plugin-types/plugin-logging.mdx b/en/develop-plugin/features-and-specs/plugin-types/plugin-logging.mdx
index cf94cec8e..3d40b577a 100644
--- a/en/develop-plugin/features-and-specs/plugin-types/plugin-logging.mdx
+++ b/en/develop-plugin/features-and-specs/plugin-types/plugin-logging.mdx
@@ -1,5 +1,6 @@
---
title: Plugin Logging
+description: Emit log lines from inside a plugin using the SDK plugin_logger_handler, visible during remote debugging and persisted to daemon container logs
---
As a plugin developer, you may want to print arbitrary strings to logs during plugin processing for development or debugging purposes.
diff --git a/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin.mdx b/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin.mdx
index b24089078..e55752e53 100644
--- a/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin.mdx
+++ b/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin.mdx
@@ -7,37 +7,96 @@ dimensions:
standard_title: Remote Debug a Plugin
language: en
title: Plugin Debugging
-description: This document introduces how to use Dify's remote debugging feature to
- test plugins. It provides detailed instructions on obtaining debugging information,
- configuring environment variable files, starting plugin remote debugging, and verifying
- plugin installation status. Through this method, developers can test plugins in
- the Dify environment in real-time while developing locally.
+description: Run your in-development plugin locally and attach it to a live Dify workspace for end-to-end testing, no packaging required
---
-After completing plugin development, the next step is to test whether the plugin can function properly. Dify provides a convenient remote debugging method to help you quickly verify plugin functionality in a test environment.
+Remote debugging is the fastest way to iterate on a plugin. You run the plugin process on your laptop, and Dify treats it as if it were installed in the workspace. Saves, edits, and restarts take effect immediately.
-Go to the ["Plugin Management"](https://cloud.dify.ai/plugins) page to obtain the remote server address and debugging Key.
+## Prerequisites
+
+- A Dify workspace where you can access **Plugins** in the top-right corner.
+- A scaffolded plugin project (see [CLI](/en/develop-plugin/getting-started/cli) if you haven't created one yet).
+- Python 3.12 and the plugin's dependencies installed (`pip install -r requirements.txt`).
+
+## Step 1: Get the Debug URL and Key
+
+Open the **Plugins** page in Dify and click the debug icon (the small bug icon next to **Install Plugin**). A dialog shows the **remote install host:port** and an **API key**.
-Return to the plugin project, copy the `.env.example` file and rename it to `.env`, then fill in the remote server address and debugging Key information you obtained.
+
+
+ The host is something like `debug-plugin.dify.dev:5003`. The key is unique to your workspace; anyone with the key can attach a plugin, so do not share it.
+
+
+ The host defaults to `127.0.0.1:5003` and is configured by `PLUGIN_REMOTE_INSTALLING_HOST` / `PLUGIN_REMOTE_INSTALLING_PORT` in the plugin daemon's environment. Make sure port `5003` is reachable from your dev machine. If Dify runs in Docker on the same host, use the daemon container's bridge IP (or expose the port).
+
+
-`.env` file:
+## Step 2: Configure the Plugin's `.env`
+
+In your plugin project, copy `.env.example` to `.env` and fill in the values:
```bash
INSTALL_METHOD=remote
-REMOTE_INSTALL_URL=debug.dify.ai:5003
+REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=********-****-****-****-************
```
-Run the `python -m main` command to start the plugin. On the plugins page, you can see that the plugin has been installed in the Workspace, and other members of the team can also access the plugin.
+
+ `REMOTE_INSTALL_URL` is the combined `host:port` from Step 1, not two separate variables.
+
+
+## Step 3: Run the Plugin
+
+From the plugin project directory:
+
+```bash
+pip install -r requirements.txt
+python -m main
+```
+
+The process stays in the foreground and logs incoming invocations. Edit your code and restart the process to apply changes.
+
+## Step 4: Verify the Install
+
+Go back to the Dify **Plugins** page. The plugin appears in the list, labelled with a debug marker. Other members of the workspace can also see and use it.
+
+The plugin tile shows a debug indicator and your local terminal logs the first registration handshake. You're attached.
+
+
+Trigger the plugin as you would any other: call it from a workflow node, run it as a tool inside an Agent, or hit an endpoint URL. Invocations land on your local process and you can attach a debugger.
+
+## Troubleshooting
+
+
+
+ The daemon is not listening on the address you put in `REMOTE_INSTALL_URL`. On self-hosted setups, confirm the daemon container has `PLUGIN_REMOTE_INSTALLING_ENABLED=true` and that port `5003` is exposed. On cloud, double-check you copied the host:port exactly as shown in the debug dialog.
+
+
+ The most common cause is a stale or wrong `REMOTE_INSTALL_KEY`. Regenerate the key from the debug dialog and rerun `python -m main`. Also confirm the daemon log shows the incoming registration.
+
+
+ The `author` field in `manifest.yaml` or in `provider/*.yaml` doesn't match a value the daemon accepts. Set it to your GitHub handle, then restart.
+
+
+ The plugin process needs to restart after every edit; there's no hot reload. Stop with `Ctrl+C` and rerun `python -m main`.
+
+
+
+## Related Resources
+
+- [CLI](/en/develop-plugin/getting-started/cli) - Scaffold a plugin and set up `.env`
+- [Plugin Logging](/en/develop-plugin/features-and-specs/plugin-types/plugin-logging) - Emit structured logs from inside your plugin
+- [Package as Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file) - Ship the plugin once debugging is done
+
{/*
Contributing Section
DO NOT edit this section!
@@ -47,4 +106,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/getting-started/choose-plugin-type.mdx b/en/develop-plugin/getting-started/choose-plugin-type.mdx
new file mode 100644
index 000000000..a2e1dd7df
--- /dev/null
+++ b/en/develop-plugin/getting-started/choose-plugin-type.mdx
@@ -0,0 +1,64 @@
+---
+dimensions:
+ type:
+ primary: conceptual
+ detail: introduction
+ level: beginner
+standard_title: Choose a Plugin Type
+language: en
+title: Choose a Plugin Type
+description: A short decision guide for picking between Tool, Model, Agent Strategy, Extension, Datasource, and Trigger plugins
+---
+
+Dify supports several plugin types, each targeting a different extension point inside the platform. Pick the one that matches how your code will be invoked.
+
+## Quick decision
+
+| You want to... | Build a... |
+| :--- | :--- |
+| Add a callable action to Agents and Workflows (search, send email, transform data, etc.) | [Tool](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) |
+| Make a new LLM, embedding, rerank, TTS, STT, or moderation model selectable inside Dify | [Model](/en/develop-plugin/dev-guides-and-walkthroughs/creating-new-model-provider) |
+| Implement a custom reasoning loop for Agents (ReAct, Function Calling variant, etc.) | [Agent Strategy](/en/develop-plugin/dev-guides-and-walkthroughs/agent-strategy-plugin) |
+| Expose an HTTP endpoint that external services can call to drive a Dify workflow | [Extension (Endpoint)](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint) |
+| Ingest documents from an external system into a Knowledge Base | [Datasource](/en/develop-plugin/dev-guides-and-walkthroughs/datasource-plugin) |
+| Start a workflow when something happens upstream (a webhook fires, a file lands) | [Trigger](/en/develop-plugin/dev-guides-and-walkthroughs/trigger-plugin) |
+
+## Common questions
+
+
+
+ Yes. A Tool plugin can also expose endpoints. For example, a Discord bot plugin sends messages (tool) and receives webhooks (endpoint) in one package. Model plugins are stricter: they cannot bundle tools or endpoints.
+
+
+ A Tool is an individual capability the Agent decides to call (like "search the web"). An Agent Strategy is the *reasoning loop itself*: the policy that decides which tools to call, in what order, and when to stop. Build a tool unless you're replacing how Agents think.
+
+
+ Datasource brings documents into a Knowledge Base for retrieval. Trigger fires a workflow in real time on an upstream event. Same systems can power both, but the consumption pattern is different: indexing vs. event-driven execution.
+
+
+ Extensions are for the other direction: an outside service calls *into* Dify. Tools are for Agents/Workflows calling *out* to a service. Build an Extension when your plugin is the entry point, not the action.
+
+
+
+## Next steps
+
+Once you've picked a type, set up the CLI and scaffold a project:
+
+
+
+ Get `dify` on your machine and run `dify plugin init`.
+
+
+ Understand the YAML structure every plugin shares.
+
+
+
+{/*
+Contributing Section
+DO NOT edit this section!
+It will be automatically generated by the script.
+*/}
+
+---
+
+[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/getting-started/choose-plugin-type.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
diff --git a/en/develop-plugin/getting-started/cli.mdx b/en/develop-plugin/getting-started/cli.mdx
index 3b235599b..5f83d5cbb 100644
--- a/en/develop-plugin/getting-started/cli.mdx
+++ b/en/develop-plugin/getting-started/cli.mdx
@@ -7,7 +7,7 @@ dimensions:
standard_title: CLI
language: en
title: CLI
-description: Command Line Interface for Dify Plugin Development
+description: Install the Dify CLI, scaffold a new plugin project, and run it against a Dify instance for local development
---
Set up and package your Dify plugins using the Command Line Interface (CLI). The CLI provides a streamlined way to manage your plugin development workflow, from initialization to packaging.
@@ -30,15 +30,16 @@ Before you begin, ensure you have the following installed:
```
- Get the latest Dify CLI from the [Dify GitHub releases page](https://github.com/langgenius/dify-plugin-daemon/releases)
-
+ Download the latest binary from the [Dify Plugin Daemon releases page](https://github.com/langgenius/dify-plugin-daemon/releases). Pick `dify-plugin-linux-amd64` for x86_64 hosts or `dify-plugin-linux-arm64` for ARM hosts.
+
```bash
- # Download dify-plugin-darwin-arm64
- chmod +x dify-plugin-darwin-arm64
- mv dify-plugin-darwin-arm64 dify
- sudo mv dify /usr/local/bin/
+ chmod +x dify-plugin-linux-amd64
+ sudo mv dify-plugin-linux-amd64 /usr/local/bin/dify
```
+
+ Download `dify-plugin-windows-amd64.exe` (or `dify-plugin-windows-arm64.exe`) from the [Dify Plugin Daemon releases page](https://github.com/langgenius/dify-plugin-daemon/releases), rename it to `dify.exe`, and add its folder to your `PATH`.
+
Now you have successfully installed the Dify CLI. You can verify the installation by running:
@@ -81,15 +82,18 @@ Before starting, here's some basic knowledge about Plugin types in Dify:
- Tool: Tool Providers like Google Search, Stable Diffusion, etc. Used to perform specific tasks.
- Model: Model Providers like OpenAI, Anthropic, etc. Use their models to enhance AI capabilities.
-- Endpoint: Similar to Service API in Dify and Ingress in Kubernetes. Extend HTTP services as endpoints with custom logi
+- Endpoint: Similar to Service API in Dify and Ingress in Kubernetes. Extend HTTP services as endpoints with custom logic.
+- Trigger: Webhook-based providers that turn third-party platform events into workflow start signals.
- Agent Strategy: Implement your own agent strategies like Function Calling, ReAct, ToT, CoT, etc.
-Based on the ability you want to extend, Plugins are divided into four types: Tool, Model, Extension, and Agent Strategy
+Based on the ability you want to extend, Plugins are divided into six types: Tool, Model, Extension, Agent Strategy, Datasource, and Trigger.
-- Tool: A tool provider that can also implement endpoints. For example, building a Discord Bot requires both Sending and
+- Tool: A tool provider that can also implement endpoints. For example, building a Discord Bot requires both sending and receiving messages.
- Model: Strictly for model providers, no other extensions allowed.
- Extension: For simple HTTP services that extend functionality.
- Agent Strategy: Implement custom agent logic with a focused approach.
+- Datasource: Provide datasource for Dify Knowledge Pipeline.
+- Trigger: Build webhook integrations that emit events to kick off workflows.
We've provided templates to help you get started. Choose one of the options below:
-> tool
@@ -101,6 +105,8 @@ We've provided templates to help you get started. Choose one of the options belo
speech2text
moderation
extension
+ datasource
+ trigger
```
Enter the default dify version, leave it blank to use the latest version:
@@ -126,14 +132,16 @@ cp .env.example .env
Edit the `.env` file to set your plugin's environment variables, such as API keys or other configurations. You can find these variables in the Dify dashboard. Log in to your Dify environment, click the “Plugins” icon in the top right corner, then click the debug icon (or something that looks like a bug). In the pop-up window, copy the “API Key” and “Host Address”. (Please refer to your local corresponding screenshot, which shows the interface for obtaining the key and host address)
-
```bash
INSTALL_METHOD=remote
-REMOTE_INSTALL_HOST=debug-plugin.dify.dev
-REMOTE_INSTALL_PORT=5003
+REMOTE_INSTALL_URL=debug-plugin.dify.dev:5003
REMOTE_INSTALL_KEY=********-****-****-****-************
```
+
+ `REMOTE_INSTALL_URL` combines host and port in `host:port` form. The host and port are shown together in the **API Key** card on the Plugins page.
+
+
Now you can run your plugin locally using the following command:
```bash
diff --git a/en/develop-plugin/getting-started/getting-started-dify-plugin.mdx b/en/develop-plugin/getting-started/getting-started-dify-plugin.mdx
index 437236eea..71c145e52 100644
--- a/en/develop-plugin/getting-started/getting-started-dify-plugin.mdx
+++ b/en/develop-plugin/getting-started/getting-started-dify-plugin.mdx
@@ -6,7 +6,8 @@ dimensions:
level: beginner
standard_title: Getting Started with Dify Plugin Development
language: en
-title: Dify Plugin
+title: Dify Plugin
+description: Modular components that extend Dify AI applications with external services, custom logic, and specialized tools
---
Dify plugins are modular components that enhance AI applications with additional capabilities. They allow you to integrate external services, custom functions, and specialized tools into your Dify-built AI applications.
@@ -21,6 +22,17 @@ Through plugins, your AI applications can:
- Perform specialized calculations
- Execute real-world actions
+## Start here
+
+
+
+ A short decision guide for picking between Tool, Model, Agent Strategy, Extension, Datasource, and Trigger plugins.
+
+
+ Set up `dify` on your machine and scaffold a new plugin project in minutes.
+
+
+
## Types of Plugins
@@ -60,6 +72,24 @@ Through plugins, your AI applications can:
Learn more
+
+ Feed external content into Dify's Knowledge Pipeline
+
+ Learn more
+
+
+ Kick off workflows from third-party platform events received via webhooks
+
+ Learn more
+
## Additional Resources
diff --git a/en/develop-plugin/publishing/faq/faq.mdx b/en/develop-plugin/publishing/faq/faq.mdx
index fa2bef663..579aa13ac 100644
--- a/en/develop-plugin/publishing/faq/faq.mdx
+++ b/en/develop-plugin/publishing/faq/faq.mdx
@@ -4,40 +4,97 @@ dimensions:
primary: operational
detail: maintenance
level: beginner
-todo: Developers (Contributors) should thoroughly test before releasing; debugging
- should not be the user's (Dify User / Consumer) responsibility.
standard_title: Faq
language: en
title: Frequently Asked Questions
-description: This document answers common questions about Dify plugin development
- and installation, including how to resolve plugin upload failures (by modifying
- the author field) and how to handle verification exceptions during plugin installation
- (by setting the FORCE_VERIFYING_SIGNATURE environment variable).
+description: Common issues and fixes for building, packaging, debugging, and installing Dify plugins
---
-## What should I do if the plugin upload fails during installation?
+## Package and install
-**Error Details**: An error message `PluginDaemonBadRequestError: plugin_unique_identifier is not valid` appears.
+### Why does `dify plugin package` fail with `plugin_unique_identifier is not valid`?
-**Solution**: Modify the `author` field in the `manifest.yaml` file under the plugin project and the `.yaml` file under the `/provider` path to your GitHub ID.
+The `author` field in `manifest.yaml` and any `provider/*.yaml` file must match your GitHub handle. Update it in every file, repackage with `dify plugin package`, and reinstall.
-Rerun the plugin packaging command and install the new plugin package.
+### Why am I seeing `plugin verification has been enabled, and the plugin you want to install has a bad signature`?
-## How should I handle exceptions encountered during plugin installation?
+Self-hosted Dify enforces signature verification on plugin packages by default. You have two options:
-**Problem Description**: An exception message is encountered during plugin installation: `plugin verification has been enabled, and the plugin you want to install has a bad signature`. How should this be handled?
+1. **Recommended for production**: sign your package. See [Third-Party Signature Verification](/en/develop-plugin/publishing/standards/third-party-signature-verification).
+2. **For development and trusted internal use**: disable verification. Add `FORCE_VERIFYING_SIGNATURE=false` to `docker/.env`, then restart:
-**Solution**: Add the field `FORCE_VERIFYING_SIGNATURE=false` to the end of the `/docker/.env` configuration file. Then, run the following commands to restart the Dify service:
+ ```bash
+ cd docker
+ docker compose down
+ docker compose up -d
+ ```
-```bash
-cd docker
-docker compose down
-docker compose up -d
-```
+ This allows installing any unsigned plugin, including ones outside the Marketplace, so only do this in environments you control.
-After adding this field, the Dify platform will allow the installation of all plugins not listed (reviewed) on the Dify Marketplace, which may pose security risks.
+### Is there a maximum size for a `.difypkg` file?
-It is recommended to install plugins in a testing/sandbox environment first and confirm their safety before installing them in a production environment.
+Yes. The plugin daemon rejects packages over a configurable limit (default `50MB`). If you ship large model weights or static assets, host them externally and download on first use, or contact Dify support about raising the limit for marketplace plugins.
+
+### My plugin needs Python 3.13. Can I change the runtime?
+
+No. Plugins run inside a managed Python 3.12 environment. Pin your dependencies to versions compatible with 3.12. The daemon does not honor a different runtime version in `manifest.yaml`.
+
+## Remote debugging
+
+### Why does my plugin start but never appear in the workspace?
+
+Three things to check, in order: (1) the daemon log shows an incoming registration, (2) the `REMOTE_INSTALL_KEY` matches what's shown in the debug dialog, (3) `REMOTE_INSTALL_URL` uses the `host:port` format (not separate variables). See [Plugin Debugging](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) for the full troubleshooting list.
+
+### Do my code changes hot-reload?
+
+No. Stop the plugin process with `Ctrl+C` and rerun `python -m main` after every change.
+
+## OAuth and credentials
+
+### What callback URL should I configure with the upstream OAuth provider?
+
+Use `https:///console/api/oauth/plugin///tool/callback` for tool plugins, replacing `tool` with `datasource` or `trigger` for those plugin types. The exact pattern is shown in your plugin's OAuth setup card inside Dify.
+
+### Why are my OAuth tokens not refreshing?
+
+The plugin SDK refreshes tokens automatically when they expire, provided your provider implementation returns a valid `refresh_token` from the initial authorization. Confirm `OAuthCredentials.refresh_token` is populated, and that your `_oauth_refresh_credentials` method is implemented.
+
+## Marketplace publishing
+
+### Why was my Marketplace PR rejected by the automated check?
+
+The reviewer runs a 12-check pre-flight on every PR. The most common failures:
+
+- **`author` in `manifest.yaml` contains `langgenius` or `dify`**: reserved for first-party plugins; use your own GitHub handle.
+- **`dify_plugin` SDK pin is below `0.5.0`**: bump the pin in `requirements.txt`.
+- **`README.md` contains Chinese characters**: move translations to `readme/README_zh_Hans.md` (see [Multilingual README](/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme)).
+- **PR title or body contains Chinese**: only the bilingual notice line is allowlisted; everything else must be English.
+- **Missing `PRIVACY.md` or `_assets/`**: both are required, and `PRIVACY.md` must be non-empty.
+- **Version is already published**: bump `version` in `manifest.yaml` before re-submitting.
+
+The full list of checks lives in [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace#reviewer-checklist).
+
+### How long does the Marketplace review take?
+
+PRs to `langgenius/dify-plugins` are typically reviewed within a few business days. PRs that haven't seen reviewer activity in 14–30 days are marked stale; respond on the PR to reset that timer.
+
+### How do I publish an update for a plugin already on the Marketplace?
+
+Bump `version` in `manifest.yaml`, open a new PR against `langgenius/dify-plugins` with the new package. The Marketplace shows the new version once merged. See [Auto-publish PR](/en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr) for the GitHub Action that automates this.
+
+### Can I monetize my plugin?
+
+Not currently. The Marketplace only accepts free plugins. Future pricing policies will be announced separately.
+
+## Storage and limits
+
+### Where do plugin logs go?
+
+Self-hosted: container logs of the plugin daemon (`docker compose logs plugin_daemon`). Cloud: visible in the workspace's plugin debug panel during remote debugging only; persisted logs are not exposed in the UI. Use [Plugin Logging](/en/develop-plugin/features-and-specs/plugin-types/plugin-logging) for structured output.
+
+### Is plugin storage scoped per workspace?
+
+Yes. The KV storage API (`self.session.storage`) is isolated per workspace per plugin install. Two workspaces using the same plugin do not share keys. See [Persistent Storage (KV)](/en/develop-plugin/features-and-specs/plugin-types/persistent-storage-kv).
{/*
Contributing Section
@@ -48,4 +105,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/faq/faq.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr.mdx b/en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr.mdx
index 634873b43..058383c59 100644
--- a/en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr.mdx
+++ b/en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr.mdx
@@ -112,19 +112,23 @@ Once set up, the workflow automatically handles these parameters:
- Create a `.github/workflows/` directory in your repository, create a file named `plugin-publish.yml` in this directory, and copy the following content into the file:
+ Create a `.github/workflows/` directory in your repository, create a file named `plugin-publish.yml` in this directory, and paste the workflow below.
+ At a high level the workflow runs on every push to `main`, downloads the Dify CLI, packages the plugin from the manifest, checks out your `dify-plugins` fork, and opens a PR against `langgenius/dify-plugins` with the new `.difypkg`.
+
+
```yaml
- # .github/workflows/auto-pr.yml
+ # .github/workflows/plugin-publish.yml
name: Auto Create PR on Main Push
on:
push:
branches: [ main ] # Trigger on push to main
+ workflow_dispatch: # Allow manual runs from the Actions tab
jobs:
create_pr: # Renamed job for clarity
- runs-on: depot-ubuntu-24.04
+ runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
@@ -259,6 +263,7 @@ Once set up, the workflow automatically handles these parameters:
echo "Current directory contents:"
ls -R
```
+
Ensure those following fields are correctly set:
@@ -283,7 +288,7 @@ When setting up the auto-publish workflow for the first time, complete these ste
4. Create the workflow file `.github/workflows/plugin-publish.yml`
5. Ensure the `name` and `author` fields in the `manifest.yaml` file are correctly configured
-#### Subsequent Update
+#### Subsequent Updates
To publish new versions after setup:
diff --git a/en/develop-plugin/publishing/marketplace-listing/release-by-file.mdx b/en/develop-plugin/publishing/marketplace-listing/release-by-file.mdx
index 62936bf27..2982a27bd 100644
--- a/en/develop-plugin/publishing/marketplace-listing/release-by-file.mdx
+++ b/en/develop-plugin/publishing/marketplace-listing/release-by-file.mdx
@@ -7,68 +7,90 @@ dimensions:
standard_title: Release by File
language: en
title: Package as Local File and Share
-description: This document provides detailed steps on how to package a Dify plugin
- project as a local file and share it with others. It covers the preparation work
- before packaging a plugin, using the Dify plugin development tool to execute packaging
- commands, how to install the generated .difypkg file, and how to share plugin files
- with other users.
+description: Package a Dify plugin into a `.difypkg` file you can install directly or hand off to others, with no marketplace or GitHub release required
---
-After completing plugin development, you can package the plugin project as a local file and share it with others. After obtaining the plugin file, it can be installed into a Dify Workspace. If you haven't developed a plugin yet, you can refer to the [Plugin Development: Hello World Guide](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin).
+A `.difypkg` is the portable form of a Dify plugin. Once you have one, anyone can install it through the Plugins page by uploading the file. This is the right path for **private plugins**, **internal testing**, or **out-of-band distribution** to a small group.
-* **Features**:
- * Not dependent on online platforms, **quick and flexible** way to share plugins.
- * Suitable for **private plugins** or **internal testing**.
-* **Publishing Process**:
- * Package the plugin project as a local file.
- * Upload the file on the Dify plugins page to install the plugin.
+For wider distribution, see the [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview).
-This article will introduce how to package a plugin project as a local file and how to install a plugin using a local file.
+## Prerequisites
-### Prerequisites
+- The [Dify CLI](/en/develop-plugin/getting-started/cli) installed. Run `dify version` to confirm.
+- A completed plugin project. If you haven't built one yet, start with the [Tool Plugin walkthrough](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin).
+- The plugin tested with [remote debugging](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) before packaging.
-* **Dify Plugin Development Tool**, for detailed instructions, please refer to [Initializing Development Tools](/en/develop-plugin/getting-started/cli).
+
+The `author` field in `manifest.yaml` and every `provider/*.yaml` must match your GitHub handle. Mismatches cause `plugin_unique_identifier is not valid` at install time. See [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) for the full manifest spec.
+
-After configuration, enter the `dify version` command in the terminal to check if it outputs version information to confirm that the necessary development tools have been installed.
+## Package the plugin
-### Package the Plugin
+
+
+ Navigate to the directory **above** your plugin project (so the project is a subdirectory of the current working directory).
+
+
+ ```bash
+ dify plugin package ./your_plugin_project
+ ```
-> Before packaging the plugin, please ensure that the `author` field in the plugin's `manifest.yaml` file and the `.yaml` file under the `/provider` path is consistent with your GitHub ID. For detailed information about the manifest file, please refer to [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications).
-
-After completing the plugin project development, make sure you have completed the [remote debugging test](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin). Navigate to the directory above your plugin project and run the following plugin packaging command:
-
-```bash
-dify plugin package ./your_plugin_project
-```
-
-After running the command, a file with the `.difypkg` extension will be generated in the current path.
+ The CLI produces a `your_plugin_project.difypkg` file in the current directory.
+
+
- 
+ 
-### Install the Plugin
+## Install from the file
-Visit the Dify plugin management page, click **Install Plugin** in the upper right corner → **Via Local File** to install, or drag and drop the plugin file to a blank area of the page to install the plugin.
+
+
+ In Dify, click the **Plugins** icon in the top-right corner.
+
+
+ Or drag the `.difypkg` onto the empty area of the Plugins page.
+
+
+ Review the permissions the plugin requests, then click **Install**.
+
+
-### Publish the Plugin
+
+The plugin is now in the workspace and ready to use in Agents, Workflows, or Tools. No further action required.
+
+
+
+Self-hosted Dify enforces signature verification by default. Unsigned `.difypkg` files installed via Local File will be rejected unless you sign them or change the verification setting. See [Third-Party Signature Verification](/en/develop-plugin/publishing/standards/third-party-signature-verification).
+
-You can share the plugin file with others or upload it to the internet for others to download. If you want to share your plugin more widely, you can consider:
+## Share the file
-1. [Publish to Individual GitHub Repository](/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo) - Share the plugin through GitHub
-2. [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace) - Publish the plugin on the official marketplace
+Hand the `.difypkg` file to your users directly, over email, internal file share, or any channel you control. They install it with the same flow above.
-## Related Resources
+If you want broader distribution instead, consider:
-- [Publishing Plugins](/en/develop-plugin/publishing/marketplace-listing/release-overview) - Learn about various publishing methods
-- [Initializing Development Tools](/en/develop-plugin/getting-started/cli) - Configure plugin development environment
-- [Remote Debugging Plugins](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) - Learn plugin debugging methods
-- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) - Define plugin metadata
-- [Plugin Development: Hello World Guide](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - Develop a plugin from scratch
+
+
+ Attach the `.difypkg` to a GitHub release; users install via repo URL.
+
+
+ Open a PR against `langgenius/dify-plugins` for the official catalog.
+
+
+
+## Related resources
+
+- [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview)
+- [Dify CLI](/en/develop-plugin/getting-started/cli)
+- [Remote Debugging](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin)
+- [Third-Party Signature Verification](/en/develop-plugin/publishing/standards/third-party-signature-verification)
+- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications)
{/*
Contributing Section
@@ -79,4 +101,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/marketplace-listing/release-by-file.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/publishing/marketplace-listing/release-overview.mdx b/en/develop-plugin/publishing/marketplace-listing/release-overview.mdx
index 127793ce2..58b86524a 100644
--- a/en/develop-plugin/publishing/marketplace-listing/release-overview.mdx
+++ b/en/develop-plugin/publishing/marketplace-listing/release-overview.mdx
@@ -4,88 +4,66 @@ dimensions:
primary: operational
detail: deployment
level: beginner
-standard_title: Release Overview
+standard_title: Publishing Overview
language: en
title: Publish Plugins
-description: This document introduces three ways to publish Dify plugins - official
- Marketplace, open-source GitHub repository, and local plugin file package. It details
- the characteristics, publishing process, and applicable scenarios for each method,
- and provides specific publishing recommendations to meet the needs of different
- developers.
+description: Three ways to distribute a Dify plugin (Marketplace, GitHub repository, or local file) and how to pick the right one
---
-### Publishing Methods
-
-To meet the publishing needs of different developers, Dify provides the following three plugin publishing methods. Before publishing, please ensure that you have completed the development and testing of your plugin, and have read [Basic Concepts of Plugin Development](/en/develop-plugin/getting-started/getting-started-dify-plugin) and [Plugin Developer Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct).
-
-#### **1. Marketplace**
-
-**Introduction**: The official plugin marketplace provided by Dify, where users can browse, search, and install various plugins with one click.
-
-**Features**:
-
-* Plugins are reviewed before going online, ensuring they are **safe and reliable**.
-* Can be directly installed in personal or team **Workspaces**.
-
-**Publishing Process**:
-
-* Submit the plugin project to the **Dify Marketplace** [code repository](https://github.com/langgenius/dify-plugins).
-* After official review, the plugin will be publicly available in the marketplace for other users to install and use.
-
-For detailed instructions, please refer to:
-
-[Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace)
-
-#### 2. **GitHub Repository**
-
-**Introduction**: Open-source or host your plugin on **GitHub** for others to view, download, and install.
-
-**Features**:
-
-* Convenient for **version management** and **open-source sharing**.
-* Users can install directly via the plugin link, without platform review.
-
-**Publishing Process**:
-
-* Push the plugin code to a GitHub repository.
-* Share the repository link, users can integrate the plugin into their **Dify Workspace** through the link.
-
-For detailed instructions, please refer to:
-
-[Publish to Individual GitHub Repository](/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo)
-
-#### 3. Plugin File Package (Local Installation)
-
-**Introduction**: Package the plugin as a local file (such as `.difypkg` format) and share it for others to install.
-
-**Features**:
-
-* Not dependent on online platforms, **quick and flexible** way to share plugins.
-* Suitable for **private plugins** or **internal testing**.
-
-**Publishing Process**:
-
-* Package the plugin project as a local file.
-* Click **Upload Plugin** on the Dify plugins page and select the local file to install the plugin.
-
-You can package your plugin project as a local file and share it with others. After uploading the file on the plugins page, you can install the plugin into your Dify Workspace.
-
-For detailed instructions, please refer to:
-
-[Package as Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file)
-
-### **Publishing Recommendations**
-
-* **Want to promote your plugin** → **Recommended to use Marketplace**, ensuring plugin quality through official review and increasing exposure.
-* **Open-source sharing project** → **Recommended to use GitHub**, convenient for version management and community collaboration.
-* **Quick distribution or internal testing** → **Recommended to use plugin files**, simple and efficient way to install and share.
-
-## Related Resources
-
-- [Basic Concepts of Plugin Development](/en/develop-plugin/getting-started/getting-started-dify-plugin) - Comprehensive understanding of Dify plugin development
-- [Plugin Developer Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct) - Understand the standards for plugin submission
-- [Plugin Privacy Data Protection Guide](/en/develop-plugin/publishing/standards/privacy-protection-guidelines) - Understand the requirements for writing privacy policies
-- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) - Understand the configuration of plugin manifest files
+Dify supports three ways to distribute a plugin. They differ in how much vetting happens up front and how broad an audience the plugin reaches.
+
+Before publishing, finish development and testing, and read the [Plugin Development Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct).
+
+## Choose a method
+
+
+
+ Official catalog. Reviewed, trusted, one-click install for every Dify user.
+
+
+ Self-hosted on GitHub. No review; users install via repo URL.
+
+
+ A `.difypkg` file you hand off directly. Right for private or internal plugins.
+
+
+
+## Compare
+
+| | Marketplace | GitHub | Local File |
+| :--- | :--- | :--- | :--- |
+| **Audience** | Every Dify user | Anyone with the repo URL | People you give the file to |
+| **Review** | Yes: 12 automated checks + human review | None | None |
+| **Install path** | One click from Marketplace UI | Install from GitHub dialog | Upload via Plugins page |
+| **Versioning** | New PR per version, automated workflow available | GitHub releases with `.difypkg` asset | Repackage and redistribute |
+| **Best for** | Polished, broadly useful plugins | Open-source projects, internal tools shared by URL | Private plugins, internal testing, ad-hoc distribution |
+
+
+Many developers ship to **GitHub first** for fast iteration, then submit to the **Marketplace** once the plugin is stable. The same `.difypkg` works for all three methods; only the distribution channel differs.
+
+
+## Quick rules of thumb
+
+- **Want broad reach and review?** Use the **Marketplace**.
+- **Want full control over releases and versioning?** Use **GitHub**.
+- **Private or one-off use?** Use a **Local File**.
+
+## Related resources
+
+
+
+ Quality bar for Marketplace submissions.
+
+
+ `PRIVACY.md` and data-disclosure requirements.
+
+
+ Manifest fields every plugin must set.
+
+
+ New to plugins? Start here.
+
+
{/*
Contributing Section
@@ -96,4 +74,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/marketplace-listing/release-overview.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace.mdx b/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace.mdx
index cccd6dac8..b596b50c0 100644
--- a/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace.mdx
+++ b/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace.mdx
@@ -7,94 +7,183 @@ dimensions:
standard_title: Release to Dify Marketplace
language: en
title: Publish to Dify Marketplace
-description: This guide provides detailed instructions on the complete process of
- publishing plugins to the Dify Marketplace, including submitting PRs, the review
- process, post-release maintenance, and other key steps and considerations.
+description: Submit a plugin to the Dify Marketplace. Covers the pre-submission checklist, the 12 reviewer checks, the PR flow, and what happens after approval
---
-Dify Marketplace welcomes plugin submissions from partners and community developers. Your contributions will further enrich the possibilities of Dify plugins. This guide provides a clear publishing process and best practice recommendations to help your plugin get published smoothly and bring value to the community. If you haven't developed a plugin yet, you can refer to the [Plugin Development: Hello World Guide](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin).
-
-Please follow these steps to submit your plugin Pull Request (PR) to the [GitHub repository](https://github.com/langgenius/dify-plugins) for review. After approval, your plugin will be officially launched on the Dify Marketplace.
-
-### Plugin Publishing Process
-
-Publishing a plugin to the Dify Marketplace involves the following steps:
-
-1. Complete plugin development and testing according to the [Plugin Developer Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct);
-2. Write a privacy policy for the plugin according to the [Plugin Privacy Data Protection Guide](/en/develop-plugin/publishing/standards/privacy-protection-guidelines), and include the file path or URL of the privacy policy in the plugin [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications);
-3. Complete plugin packaging;
-4. Fork the [Dify Plugins](https://github.com/langgenius/dify-plugins) code repository;
-5. Create your personal or organization folder in the repository and upload the packaged `.difypkg` file to your folder;
-6. Submit a Pull Request (PR) following the PR Template format in GitHub and wait for review;
-7. After the review is approved, the plugin code will be merged into the Main branch, and the plugin will be automatically launched on the [Dify Marketplace](https://marketplace.dify.ai/).
-
-Plugin submission, review, and publication flow chart:
-
-
- 
-
-
-> **Note**: The Contributor Agreement in the above diagram refers to the [Plugin Developer Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct).
-
-### During Pull Request (PR) Review
-
-Actively respond to reviewer questions and feedback:
-
-* PR comments unresolved within **14 days** will be marked as stale (can be reopened).
-* PR comments unresolved within **30 days** will be closed (cannot be reopened, a new PR needs to be created).
-
-### **After Pull Request (PR) Approval**
-
-**1. Ongoing Maintenance**
-
-* Address user-reported issues and feature requests.
-* Migrate plugins when significant API changes occur:
- * Dify will publish change notifications and migration instructions in advance.
- * Dify engineers can provide migration support.
-
-**2. Restrictions during the Marketplace Public Beta Testing Phase**
-
-* Avoid introducing breaking changes to existing plugins.
-
-### Review Process
-
-**1. Review Order**
-
-* PRs are processed on a **first-come, first-reviewed** basis. Review will begin within 1 week. If there is a delay, reviewers will notify the PR author via comments.
-
-**2. Review Focus**
-
-* Check if the plugin name, description, and setup instructions are clear and instructive.
-* Check if the plugin's [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) meets format standards and includes valid author contact information.
-
-**3. Plugin Functionality and Relevance**
-
-* Test plugins according to the [Plugin Development Guide](/en/develop-plugin/getting-started/getting-started-dify-plugin).
-* Ensure the plugin has a reasonable purpose in the Dify ecosystem.
-
-[Dify.AI](https://dify.ai/) reserves the right to accept or reject plugin submissions.
-
-### Frequently Asked Questions
-
-1. **How to determine if a plugin is unique?**
-
-Example: A Google search plugin that only adds multilingual versions should be considered an optimization of an existing plugin. However, if the plugin implements significant functional improvements (such as optimized batch processing or error handling), it can be submitted as a new plugin.
-
-2. **What if my PR is marked as stale or closed?**
-
-PRs marked as stale can be reopened after addressing feedback. Closed PRs (over 30 days) require creating a new PR.
-
-3. **Can I update plugins during the Beta testing phase?**
-
-Yes, but breaking changes should be avoided.
-
-## Related Resources
-
-- [Publishing Plugins](/en/develop-plugin/publishing/marketplace-listing/release-overview) - Learn about various publishing methods
-- [Plugin Developer Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct) - Plugin submission standards
-- [Plugin Privacy Data Protection Guide](/en/develop-plugin/publishing/standards/privacy-protection-guidelines) - Privacy policy writing requirements
-- [Package as Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file) - Plugin packaging methods
-- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) - Define plugin metadata
+The Marketplace is the official catalog of community-built and partner-built Dify plugins. Submitting your plugin here puts it one click away from every Dify user.
+
+Plugins are published by opening a Pull Request against [`langgenius/dify-plugins`](https://github.com/langgenius/dify-plugins). A reviewer (and a set of automated checks) walks through the PR, and on approval the plugin goes live on [marketplace.dify.ai](https://marketplace.dify.ai/) automatically.
+
+If you have not built a plugin yet, start with the [Tool Plugin walkthrough](/en/develop-plugin/dev-guides-and-walkthroughs/tool-plugin).
+
+## Before you submit
+
+The Dify reviewer runs an automated 12-check pre-flight on every PR. Most rejections are mechanical, and fixing them up front saves a review cycle.
+
+
+
+ Every plugin directory must contain:
+
+ | File / Folder | Purpose |
+ | :--- | :--- |
+ | `manifest.yaml` | Plugin metadata (name, author, version, etc.) |
+ | `README.md` | English-only description, setup, usage |
+ | `PRIVACY.md` | Privacy policy (required, non-empty) |
+ | `_assets/` | Plugin icon and any other static assets |
+
+ See [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) for manifest fields and [Privacy Guidelines](/en/develop-plugin/publishing/standards/privacy-protection-guidelines) for the privacy policy.
+
+
+ - **Author** in `manifest.yaml` must not contain `langgenius` or `dify`; those are reserved for first-party plugins. Use your own GitHub handle.
+ - **Version** must be a new value. Submitting an already-published version is rejected.
+ - **Icon** must be an actual icon in `_assets/`, not a leftover template default.
+
+
+ - `pip install -r requirements.txt` must succeed cleanly.
+ - The plugin SDK pin must be at least `dify_plugin>=0.5.0`.
+ - The plugin must install and package without errors against the current daemon (the reviewer runs `test-plugin-install.py` and `upload-package.py --test`).
+
+
+ - **PR title and body** must be in English. The bilingual notice line `【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）` is the only allowlisted exception.
+ - **`README.md`** must contain no Chinese characters. Add translations as `readme/README_.md` instead. See [Multilingual README](/en/develop-plugin/features-and-specs/plugin-types/multilingual-readme).
+
+
+
+## Reviewer checklist
+
+These are the exact checks the reviewer runs, in order. Treat this as your pre-flight before opening the PR.
+
+| # | Check | Common cause of failure |
+| :--- | :--- | :--- |
+| 1 | **Single `.difypkg`** | PR includes more than one packaged file, or none |
+| 2 | **PR language** | CJK characters in title or body outside the allowlisted notice |
+| 3 | **Project structure** | Missing `manifest.yaml`, `README.md`, `PRIVACY.md`, or `_assets/` |
+| 4 | **Manifest author** | Author contains `langgenius` or `dify` |
+| 5 | **Icon** | Default template icon left in place, or icon missing |
+| 6 | **Version** | This version is already on the Marketplace |
+| 7 | **README language** | Chinese characters in `README.md` (use `readme/README_zh_Hans.md` instead) |
+| 8 | **PRIVACY.md** | Missing or empty |
+| 9 | **Dependencies install** | `pip install -r requirements.txt` errors |
+| 10 | **SDK version** | `dify_plugin` pinned below `0.5.0` |
+| 11 | **Install test** | Plugin fails to install via the daemon |
+| 12 | **Packaging test** | Plugin fails to repackage cleanly |
+
+A failing check stops the review and posts a status table with `❌ Fail` rows and required fixes; you address them and push again.
+
+## Submit the PR
+
+
+
+ Skim the [Plugin Development Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct). Reviewers use them to judge non-mechanical concerns: uniqueness, brand alignment, content quality, IP, and maintenance commitment.
+
+
+ Create `PRIVACY.md` in the plugin root (or host it and put the URL in the manifest). Follow [Privacy Guidelines](/en/develop-plugin/publishing/standards/privacy-protection-guidelines): declare what data the plugin and any third-party services it calls collect.
+
+
+ From the directory above your plugin project:
+
+ ```bash
+ dify plugin package ./your_plugin_project
+ ```
+
+ This produces `your_plugin_project.difypkg`.
+
+
+ Fork [`langgenius/dify-plugins`](https://github.com/langgenius/dify-plugins). Create a folder at `//` and drop the `.difypkg` inside.
+
+
+ Push to your fork, then open a PR against `main` using the repository's PR template. Title and body in English.
+
+
+ The automated checks post first, then a human reviewer follows up. Address feedback by pushing new commits; the checks rerun on each push.
+
+
+
+```mermaid
+flowchart LR
+ A[Build & test plugin] --> B[Package .difypkg]
+ B --> C[Fork langgenius/dify-plugins]
+ C --> D[Add file to author/plugin/]
+ D --> E[Open PR]
+ E --> F{Automated checks
12 rules}
+ F -->|❌ Fail| G[Push fixes]
+ G --> F
+ F -->|✅ Pass| H[Human review]
+ H -->|Changes requested| G
+ H -->|Approve & merge| I[Live on Marketplace]
+```
+
+
+The first review usually lands within a week. If a reviewer doesn't respond in that window, they'll leave a comment explaining the delay.
+
+
+
+Once merged to `main`, the plugin appears on [marketplace.dify.ai](https://marketplace.dify.ai/) automatically, with no separate publishing step.
+
+
+## After approval
+
+You own the plugin from the merge onward:
+
+- **Bug fixes and feature requests.** Triage issues from your users.
+- **Compatibility updates.** When Dify ships a breaking API change, the team publishes migration notes; you update the plugin. Dify engineers can help if needed.
+- **Versioning.** Bump `version` in `manifest.yaml`, repackage, open a new PR with the new `.difypkg`. The [Auto-publish PR workflow](/en/develop-plugin/publishing/marketplace-listing/plugin-auto-publish-pr) automates this from a GitHub Action.
+
+
+While the Marketplace is in public beta, avoid breaking changes to plugins already in use. Add new fields instead of renaming existing ones; deprecate before removing.
+
+
+## PR lifecycle
+
+| Status | What it means | What to do |
+| :--- | :--- | :--- |
+| **Open, awaiting review** | Within the first ~7 days, no action needed | Wait |
+| **Changes requested** | A check failed, or the reviewer left feedback | Push fixes; checks rerun automatically |
+| **Stale (14 days idle)** | No response from you in two weeks | Reply on the PR to reset the timer; it can be reopened |
+| **Closed (30 days idle)** | Closed for inactivity | Open a fresh PR; the closed one can't be reopened |
+
+## Frequently asked questions
+
+
+
+ The Marketplace deduplicates by *function*, not by *integration*. A second Google-search plugin that only adds new translations is a duplicate. A Google-search plugin that adds batched queries, better error handling, or a meaningful new capability is fine; say so in the PR description.
+
+
+ **Stale** PRs (14 days idle) can be reopened; reply on the PR or push a fix to restart the clock. **Closed** PRs (30 days idle) cannot be reopened; fix the feedback and open a fresh PR with the same package.
+
+
+ Yes. Avoid breaking changes: add fields rather than rename, deprecate before removing.
+
+
+ Not currently. The Marketplace accepts free plugins only; monetization policies will be announced separately.
+
+
+ No. Only the single allowlisted bilingual notice line is permitted in the PR title/body. Put internal multilingual notes elsewhere (commit messages, internal docs).
+
+
+
+## Related resources
+
+
+
+ Compare Marketplace, GitHub, and local-file distribution.
+
+
+ The full content and quality bar reviewers apply.
+
+
+ How to write a `PRIVACY.md` that passes review.
+
+
+ GitHub Action that packages and opens the PR for you on every push.
+
+
+ Add `readme/README_.md` files for non-English users.
+
+
+ Manifest field reference.
+
+
{/*
Contributing Section
@@ -105,4 +194,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo.mdx b/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo.mdx
index bac73b194..cf27430ab 100644
--- a/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo.mdx
+++ b/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo.mdx
@@ -7,81 +7,116 @@ dimensions:
standard_title: Release to Individual GitHub Repo
language: en
title: Publish to Individual GitHub Repository
-description: This document provides detailed instructions on how to publish Dify plugins
- to a personal GitHub repository, including preparation work, initializing a local
- plugin repository, connecting to a remote repository, uploading plugin files, packaging
- plugin code, and the complete process of installing plugins via GitHub. This method
- allows developers to fully manage their own plugin code and updates.
+description: Distribute a Dify plugin from your own GitHub repository so users can install it directly via repo URL, with no marketplace review required
---
-### Publish Methods
+Publishing through a personal GitHub repository lets you ship a plugin without going through Dify Marketplace review. Users install the plugin by entering your repo URL and selecting a release that contains a `.difypkg` asset.
-To accommodate the various publishing needs of developers, Dify provides three plugin publish methods:
-
-#### **1. Marketplace**
-
-**Introduction**: The official Dify plugin marketplace allows users to browse, search, and install a variety of plugins with just one click.
-
-**Features**:
-
-* Plugins become available after passing a review, ensuring they are **trustworthy** and **high-quality**.
-* Can be installed directly into an individual or team **Workspaces**.
-
-**Publication Process**:
-
-* Submit the plugin project to the **Dify Marketplace** [code repository](https://github.com/langgenius/dify-plugins).
-* After an official review, the plugin will be publicly released in the marketplace for other users to install and use.
-
-For detailed instructions, please refer to:
-
-
-
-
-#### 2. **GitHub Repository**
-
-**Introduction**: Open-source or host the plugin on **GitHub** makes it easy for others to view, download, and install.
-
-**Features**:
-
-* Convenient for **version management** and **open-source sharing**.
-* Users can install the plugin directly via a link, bypassing platform review.
-
-**Publication Process**:
-
-* Push the plugin code to a GitHub repository.
-* Share the repository link, users can integrate the plugin into their **Dify Workspace** through the link.
-
-For detailed instructions, please refer to:
-
-
-
-
-#### Plugin File (Local Installation)
-
-**Introduction**: Package the plugin as a local file (e.g., `.difypkg` format) and share it for others to install.
-
-**Features**:
-
-* Does not depend on an online platform, enabling **quick and flexible** sharing of plugins.
-* Suitable for **private plugins** or **internal testing**.
-
-**Publication Process**:
-
-* Package the plugin project as a local file.
-* Click **Upload Plugin** on the Dify plugin page and select the local file to install the plugin.
-
-You can package the plugin project as a local file and share it with others. After uploading the file on the plugin page, the plugin can be installed into the Dify Workspace.
-
-For detailed instructions, please refer to:
-
-
-
-
-### **Publication Recommendations**
-
-* **Looking to promote a plugin** → **Recommended to use the Marketplace**, ensuring plugin quality through official review and increasing exposure.
-* **Open-source sharing project** → **Recommended to use GitHub**, convenient for version management and community collaboration.
-* **Quick distribution or internal testing** → **Recommended to use plugin file**, allowing for straightforward and efficient installation and sharing.
+**When to use this method**
+
+- You want full control over versioning and the release cadence.
+- The plugin is open source and you want others to read, fork, or contribute to it.
+- The plugin is for internal use within a team or org, but you still want one canonical install URL.
+- Your plugin is awaiting marketplace review and you need an interim distribution channel.
+
+For a comparison with other publishing methods, see the [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview).
+
+### Prerequisites
+
+- A packaged plugin (`.difypkg` file). If you don't have one yet, see [Package as Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file).
+- A GitHub account.
+- A Dify workspace where you (or your users) have permission to install plugins.
+
+### Step 1: Create a GitHub repository
+
+
+
+ On GitHub, create a new public repository. The name typically matches your plugin name (for example, `dify-plugin-flomo`).
+
+
+ Initialize git in your plugin project and push the source code:
+
+ ```bash
+ cd your_plugin_project
+ git init
+ git add .
+ git commit -m "initial commit"
+ git branch -M main
+ git remote add origin https://github.com//.git
+ git push -u origin main
+ ```
+
+
+ The `author` field in `manifest.yaml` and in any `provider/*.yaml` must match your GitHub handle. Mismatches cause `plugin_unique_identifier is not valid` when users try to install. See the [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) for manifest details.
+
+
+
+### Step 2: Build the plugin package
+
+From the directory **above** your plugin project, run:
+
+```bash
+dify plugin package ./your_plugin_project
+```
+
+This produces `your_plugin_project.difypkg` in the current directory.
+
+### Step 3: Publish a GitHub release
+
+GitHub releases are how Dify discovers installable versions of your plugin.
+
+
+
+ On your repository page, click **Releases** > **Draft a new release**. Create a new tag using semantic versioning (for example, `v0.0.1`). The tag should match the `version` field in your `manifest.yaml`.
+
+
+ In the release form, drag the `.difypkg` file into the **Assets** area. Dify reads this asset when users install from your repo.
+
+
+ Add release notes describing what changed, then click **Publish release**.
+
+
+
+
+ Repeat Steps 2 and 3 for each new version. Bump the `version` in `manifest.yaml` first, repackage, then create a new tag and release.
+
+
+### Step 4: Install from your repository
+
+Share your repository URL with users. They install it in Dify as follows:
+
+
+
+ In Dify, go to **Plugins** in the top-right corner.
+
+
+ Click **Install Plugin** > **From GitHub**.
+
+
+ Paste the repository URL (for example, `https://github.com//`), then select the version from the dropdown. Dify pulls the matching `.difypkg` asset from that release.
+
+
+ Review the permissions the plugin requests, then click **Install**.
+
+
+
+
+The plugin appears on the user's Plugins page within seconds of clicking **Install**. Dify pulls the `.difypkg` from your GitHub release on demand.
+
+
+### Troubleshooting
+
+- **`plugin_unique_identifier is not valid`**: the `author` field in `manifest.yaml` (and `provider/*.yaml`) doesn't match the GitHub handle that owns the repo. Update it, repackage, and re-release.
+- **No versions appear in the install dialog**: the release has no `.difypkg` asset attached, or the repo has no releases yet. Open the release on GitHub and confirm the asset is listed under **Assets**.
+- **Signature verification error**: self-hosted Dify instances may have signature verification enabled. See [Third-Party Signature Verification](/en/develop-plugin/publishing/standards/third-party-signature-verification) to sign your release, or see the [FAQ](/en/develop-plugin/publishing/faq/faq) for the bypass option.
+
+## Related Resources
+
+- [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview) - Compare publishing methods
+- [Package as Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file) - Build a `.difypkg` package
+- [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace) - Submit through the official marketplace
+- [Third-Party Signature Verification](/en/develop-plugin/publishing/standards/third-party-signature-verification) - Sign packages for verified installs
+- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) - Manifest field reference
{/*
Contributing Section
@@ -92,4 +127,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct.mdx b/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct.mdx
index 4a47ea557..c66fb993a 100644
--- a/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct.mdx
+++ b/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct.mdx
@@ -4,166 +4,100 @@ dimensions:
primary: operational
detail: setup
level: intermediate
-standard_title: Contributor Covenant Code of Conduct
+standard_title: Plugin Development Guidelines
language: en
title: Plugin Development Guidelines
-description: To ensure the quality of all plugins in the Dify Marketplace and provide
- a consistent, high-quality experience for Dify Marketplace users, you must adhere
- to all requirements outlined in these Plugin Development Guidelines when submitting
- a plugin for review. By submitting a plugin, **you acknowledge that you have read,
- understood, and agree to comply with all the following terms**. Following these
- guidelines will help your plugin get reviewed faster.
+description: Requirements every Dify Marketplace plugin must meet to pass review, covering quality, language, privacy, IP, maintenance, and prohibited content
---
-## 1. Plugin Value and Uniqueness
+By submitting a plugin to the Dify Marketplace, you agree to follow the requirements on this page. Meeting them up front gets your plugin through review faster and helps keep the Marketplace useful and trustworthy.
-- **Focus on Generative AI**: Ensure the core functionality of your plugin focuses on the Generative AI domain and provides distinct and significant value to Dify users. This may include:
- - Integrating new models, tools, or services.
- - Offering unique data sources or processing capabilities to enhance AI applications.
- - Simplifying or automating AI-related workflows on the Dify platform.
- - Providing innovative supporting functions for AI application development.
+## Value and uniqueness
-- **Avoid Functional Duplication**: Submitted plugins **must not** duplicate or closely resemble existing plugins in the Marketplace. Each published plugin must be unique and independent to ensure the best experience for users.
+- **Generative AI focus.** The plugin's core capability should integrate models, tools, or services that meaningfully extend AI applications on Dify.
+- **No functional duplicates.** Don't reskin an existing Marketplace plugin. Each plugin should be unique and stand on its own.
+- **Meaningful updates.** New versions must add real capability, not just metadata bumps.
+- **Explain new submissions.** In your PR description, say briefly why the plugin is needed and what gap it fills.
-- **Meaningful Updates**: For plugin updates, **ensure new features or services** are introduced that are not already available in the current version.
+## Plugin checklist
-- **PR Submission Advice**: We **recommend** including a brief explanation in your pull request to clarify why the new plugin is needed.
+Before opening the publish PR, confirm each item:
-## 2. Plugin Functionality Checklist
+- **Unique name.** Search the Marketplace first.
+- **Brand alignment.** The plugin name reflects what it actually is.
+- **Works end-to-end.** Tested via [remote debugging](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin); production-ready.
+- **README in English** with setup steps, required credentials, and usage. No exaggerated claims, ads, self-promotion, offensive content, real user data in screenshots, or dead links.
+- **Clear error messages** for required fields and failure modes.
+- **Authentication steps documented in full**, with no skipped steps.
+- **Privacy policy ready.** See [Privacy Guidelines](/en/develop-plugin/publishing/standards/privacy-protection-guidelines).
+- **Credentials handled securely**, never hardcoded, never exposed.
+- **Performance acceptable.** Does not noticeably degrade Dify itself.
-- **Unique Name**: Ensure your plugin name is unique by searching the plugin directory beforehand.
+## Language
-- **Brand Alignment**: Plugin name must match the plugin's branding.
+English is the primary language for every user-facing string: plugin name, description, field labels, help text, error messages. Additional translations are welcome on top of English.
-- **Functionality Verification**: Test the plugin thoroughly before submission and confirm it works as intended. For details, refer to [Remote Debug a Plugin](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin). The plugin must be production-ready.
+## Prohibited and restricted plugins
-- **README Requirements**:
- - Setup instructions and usage guidance.
- - Any necessary code, APIs, credentials, or information required to connect the plugin.
- - Do **not** include irrelevant content or links.
- - Do **not** use exaggerated, promotional language, or unverifiable claims.
- - Do **not** include advertisements of any kind (including self-promotion or display ads).
- - Do **not** include misleading, offensive, or defamatory content.
- - Do **not** expose real user names or data in screenshots.
- - Do **not** link to 404 pages or pages that return errors.
- - Avoid excessive spelling or punctuation errors.
+| Category | Reason |
+|---|---|
+| **Prohibited**: misleading or malicious behavior | spam, phishing, credential theft, deceiving the review process |
+| **Prohibited**: offensive content | violence, hate speech, discrimination |
+| **Prohibited**: financial transactions | payments, asset transfers, token transfers |
+| **Restricted**: frequent defects | repeated submissions with critical bugs |
+| **Restricted**: unnecessary splitting | multiple plugins for the same API/auth; bundle them instead |
+| **Restricted**: duplicate submissions | re-submitting essentially the same plugin |
-- **User Data Use**: Use collected data only for connecting services and improving plugin functionality.
+Prohibited plugins are rejected. Restricted plugins may be delayed or asked to consolidate.
-- **Error Clarity**: Mark required fields and provide clear error messages that help users understand issues.
+## Monetization
-- **Authentication Settings**: If authentication is needed, include the full configuration steps—do not omit them.
+**The Dify Marketplace currently accepts free plugins only.** Pricing policies, if introduced, will be announced separately.
-- **Privacy Policy**: Prepare a privacy policy document or online URL in accordance with the [Privacy Guidelines](/en/develop-plugin/publishing/standards/privacy-protection-guidelines).
+## Trademarks and intellectual property
-- **Performance**: Plugins must operate efficiently and must not degrade the performance of Dify or user systems.
+- **You must have the rights** to any logo, trademark, or copyrighted material you include. We may ask for proof for recognizable third-party brands.
+- **Do not use Dify's logos** in your plugin assets.
+- **Image quality** must be sharp and well-cropped. No misleading or offensive icons.
-- **Credential Security**: API keys or other credentials must be stored and transmitted securely. Avoid hardcoding them or exposing them to unauthorized parties.
+Dify may ask for changes or remove a plugin if a rights holder complains or if unauthorized use is found.
+## Updates and versioning
-## 3. Language Requirements
+- **Announce breaking changes** in the plugin description or via GitHub Release Notes before users hit them.
+- **Update regularly** for bug fixes, Dify platform changes, security patches, and upstream-service changes.
+- **Deprecation notice.** If retiring a plugin, give users time to migrate and suggest alternatives where possible.
-- **English as Primary Language**: Since Dify Marketplace serves a global audience, **English must be the primary language** for all user-facing text (plugin names, descriptions, field names, labels, help text, error messages).
+## Maintenance and support
-- **Multilingual Support Encouraged**: Supporting multiple languages is encouraged.
+You own technical support for your plugin. Provide **at least one** support channel (GitHub repository or email) and keep it active.
+If a plugin is left unmaintained and the owner doesn't respond after a reasonable notification, Dify may tag it as `Maintenance Lacking` or `Potential Risk`, restrict new installs, and eventually unpublish it.
-## 4. Prohibited and Restricted Plugins
+## Privacy and data
-- **Prohibited: Misleading or Malicious Behavior**
- Plugins must not mislead users. Do not create plugins for spamming, phishing, or sending unsolicited messages. Attempts to deceive the review process, steal user data, or impersonate users will result in removal and possible bans from future submissions.
+You **must** declare whether your plugin collects personal data and, if so, what types. The full guidelines are in [Privacy Guidelines](/en/develop-plugin/publishing/standards/privacy-protection-guidelines).
-- **Prohibited: Offensive Content**
- Plugins must not contain violent content, hate speech, discrimination, or disrespect toward global cultures, religions, or users.
+Your privacy policy must state:
-- **Prohibited: Financial Transactions**
- Plugins must not facilitate any financial transactions, asset transfers, or payment processing. This includes token or asset ownership transfers in blockchain/crypto applications.
+- What data is collected
+- How it is used
+- What is shared with third parties (with links to their privacy policies)
-- **Restricted: Plugins with Frequent Defects**
- Thoroughly test your plugin to avoid critical bugs. Repeated submissions with defects may lead to delays or penalties.
+Plugins that handle sensitive data (health, finance, children's information) get extra scrutiny. Collecting or transmitting user data without consent is grounds for removal.
-- **Restricted: Unnecessary Plugin Splitting**
- Do not create multiple plugins for features that share the same API and authentication unless each is clearly a standalone product or service. Prefer integrating features into one high-level plugin.
+## Review and discretion
-- **Restricted: Duplicate Submissions**
- Avoid repeatedly submitting essentially identical plugins. Doing so may delay reviews or result in rejection.
+- Dify may reject or remove plugins that don't meet these requirements or that abuse the review process.
+- Reviews aim to land within a reasonable window; turnaround depends on submission volume and complexity.
+- Reviewers communicate via the support channel you provide; keep it monitored.
-## 5. Plugin Monetization
+## Related resources
-- **Dify Marketplace currently only supports **free** plugins.
-
-- **Future Policy**: Policies for monetization and pricing models will be announced in the future.
-
-## 6. Trademarks and Intellectual Property
-
-- **Authorization Required**: Ensure you have rights to use any logos or trademarks submitted.
-
-- **Verification Rights**: We may ask you to prove you have permission if third-party logos are used—especially if they clearly belong to known brands.
-
-- **Violation Consequences**: Dify reserves the right to ask for changes or remove the plugin if unauthorized use is found. Complaints from rights holders may also result in removal.
-
-- **Dify Logos Forbidden**: You may not use Dify's own logos.
-
-- **Image Standards**: Do not submit low-quality, distorted, or poorly cropped images. The review team may request replacements.
-
-- **Icon Restrictions**: Icons must not contain misleading, offensive, or malicious visuals.
-
-
-
-## 7. Plugin Updates and Version Management
-
-- **Responsible Updates**: Clearly communicate breaking changes in descriptions or via external channels (e.g., GitHub Release Notes).
-
-- **Encouraged Maintenance**: Update regularly to fix bugs, match Dify platform changes, or respond to updates from third-party services—especially for security.
-
-- **Deprecation Notice**: If discontinuing a plugin, notify users in advance (e.g., timeline and plan in the plugin description) and suggest alternatives if available.
-
-
-## 8. Plugin Maintenance and Support
-
-- **Owner Responsibility**: Plugin owners are responsible for technical support and maintenance.
-
-- **Support Channel Required**: Owners must provide **at least one** support channel (GitHub repo or email) for feedback during review and publication.
-
-- **Handling Unmaintained Plugins**: If a plugin lacks maintenance and the owner does not respond after reasonable notification, Dify may:
- - Add "Maintenance Lacking" or "Potential Risk" tags.
- - Restrict new installs.
- - Eventually unpublish the plugin.
-
-
-## 9. Privacy and Data Compliance
-
-- **Disclosure Required**: You **must declare** whether your plugin collects any user personal data. See the [Privacy Guidelines](/en/develop-plugin/publishing/standards/privacy-protection-guidelines).
-
-- **Simple Data Listing**: If collecting data, briefly list types (e.g., username, email, device ID, location). No need for exhaustive detail.
-
-- **Privacy Policy**: You **must provide** a privacy policy link stating:
- - What information is collected.
- - How it is used.
- - What is shared with third parties (with their privacy links if applicable).
-
-- **Review Focus**:
- - **Formal Check**: Make sure you declare what data you collect.
- - **Sensitive Data Scan**: Plugins collecting sensitive data (e.g., health, finance, children's info) require additional scrutiny.
- - **Malicious Behavior Scan**: Plugins must not collect or upload user data without consent.
-
----
-
-## 10. Review and Discretion
-
-- **Right to Reject/Remove**: If requirements, privacy standards, or related policies are unmet, Dify may reject or remove your plugin. This includes abuse of the review process or data misuse.
-
-- **Timely Review**: The Dify review team will aim to review plugins within a reasonable time, depending on volume and complexity.
-
-- **Communication**: We may reach out through the support channel you provide—please ensure it is active.
-
-## Related Resources
-
-- [Basic Concepts of Plugin Development](/en/develop-plugin/getting-started/getting-started-dify-plugin) - Learn the basics of plugin development
-- [Publishing Plugins](/en/develop-plugin/publishing/marketplace-listing/release-overview) - Overview of the plugin publishing process
-- [Plugin Privacy Data Protection Guide](/en/develop-plugin/publishing/standards/privacy-protection-guidelines) - Guide for writing privacy policies
-- [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace) - Publish plugins on the official marketplace
-- [Remote Debugging Plugins](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin) - Plugin debugging guide
+- [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview)
+- [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace)
+- [Privacy Guidelines](/en/develop-plugin/publishing/standards/privacy-protection-guidelines)
+- [Remote Debugging](/en/develop-plugin/features-and-specs/plugin-types/remote-debug-a-plugin)
{/*
Contributing Section
@@ -174,4 +108,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/publishing/standards/privacy-protection-guidelines.mdx b/en/develop-plugin/publishing/standards/privacy-protection-guidelines.mdx
index 47a102eac..e6382d6fc 100644
--- a/en/develop-plugin/publishing/standards/privacy-protection-guidelines.mdx
+++ b/en/develop-plugin/publishing/standards/privacy-protection-guidelines.mdx
@@ -4,95 +4,105 @@ dimensions:
primary: operational
detail: setup
level: intermediate
-standard_title: Privacy Protection Guidelines
+standard_title: Privacy Guidelines
language: en
-title: Plugin Privacy Policy Guidelines
-description: This document describes guidelines for developers on how to write a privacy
- policy when submitting plugins to the Dify Marketplace. It includes how to identify
- and list the types of personal data collected (direct identification information,
- indirect identification information, combined information), how to fill out the
- plugin privacy policy, how to include the privacy policy statement in the Manifest
- file, and answers to related common questions.
+title: Privacy Guidelines
+description: How to declare data collection and write the privacy policy required for every plugin submitted to the Dify Marketplace
---
-When you are submitting your Plugin to Dify Marketplace, you are required to be transparent in how you handle user data. The following guidelines focus on how to address privacy-related questions and user data processing for your plugin.
+Every plugin submitted to the Dify Marketplace must be transparent about how it handles user data. This page tells you what to declare and how to write the policy reviewers expect.
-Center your privacy policy around the following points:
+The whole submission boils down to one question:
-**Does your plugin collect and use any user personal data?** If it does, please list the types of data collected.
+> Does your plugin collect or transmit any user personal data, either directly or through a third-party service it calls?
-> “Personal data” refers to any information that can identify a specific individual—either on its own or when combined with other data—such as information used to locate, contact, or otherwise target a unique person.
+If yes, list the data types and link a privacy policy. If no, say so explicitly.
-#### 1. List the types of data collected
+
+"Personal data" means any information that identifies a specific individual on its own or when combined with other data: anything that could locate, contact, or target a unique person.
+
-**Type A**: **Direct Identifiers**
+## Identify the data your plugin handles
-* Name (e.g., full name, first name, last name)
-* Email address
-* Phone number
-* Home address or other physical address
-* Government-issued identification numbers (e.g., Social Security number, passport number, driver's license number)
+Walk through the three categories below. Anything you collect, store, log, or send to a third party must be declared.
-**Type B**: **Indirect Identifiers**
+### Direct identifiers
-* Device identifiers (e.g., IMEI, MAC address, device ID)
-* IP address
-* Location data (e.g., GPS coordinates, city, region)
-* Online identifiers (e.g., cookies, advertising IDs)
-* Usernames
-* Profile pictures
-* Biometric data (e.g., fingerprints, facial recognition data)
-* Web browsing history
-* Purchase history
-* Health information
-* Financial information
+- Full name, first name, last name
+- Email address
+- Phone number
+- Home address or other physical address
+- Government IDs (passport, driver's license, Social Security number, etc.)
-**Type C: Data that can be combined with other data to identify an individual**:
+### Indirect identifiers
-* Age
-* Gender
-* Occupation
-* Interests
+- Device identifiers (IMEI, MAC address, device ID)
+- IP address
+- Location data (GPS coordinates, city, region)
+- Online identifiers (cookies, advertising IDs)
+- Usernames, profile pictures
+- Biometric data (fingerprints, facial recognition)
+- Browsing history, purchase history
+- Health or financial information
-While your plugin may not collect any personal information, you also need to make sure the use of third-party services within your plugin may involve data collection or processing. As the plugin developer, you are responsible for disclosing all data collection activities associated within your plugin, including those performed by third-party services. Thus, make sure to read through the privacy policy of the third-party service and verify any data collected by your plugin is claimed in your submission.
+### Combinable data
-For example, if the plugin you are developing involves Slack services, make sure to reference [Slack’s privacy policy](https://slack.com/trust/privacy/privacy-policy) in your plugin’s privacy policy statement and clearly disclose the data collection practices.
+Data that becomes identifying when joined with other data:
-#### **2. Submit the most up to date Privacy Policy of your Plugin**
+- Age, gender
+- Occupation
+- Interests
-**The Privacy Policy** should contain:
+### Third-party services count too
-* What types of data are collected.
-* How the collected data is used.
-* Whether any data is shared with third parties, and if so, identify those third parties and provide links to their privacy policies.
-* If you have no clue of how to write a privacy policy, you can also check the privacy policy of Plugins issued by Dify Team.
+Your plugin is responsible for what the services it calls collect. If your plugin uses Slack, you must reference [Slack's privacy policy](https://slack.com/trust/privacy/privacy-policy) and disclose what Slack receives.
-#### 3. Introduce a privacy policy statement within the plugin Manifest file
+Before submitting, read the privacy policy of every third-party API the plugin touches and make sure your declaration covers it.
-For detailed instructions on filling out specific fields, please refer to the [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) documentation.
+## Write the privacy policy
-**FAQ**
+Your policy, either a `PRIVACY.md` in the plugin repository or a hosted URL, must cover:
-1. **What does "collect and use" mean regarding user personal data? Are there any common examples of how personal data is collected and used in any Plugin?**
+- **What** is collected (from the categories above).
+- **How** it is used.
+- **Where** it goes, including any third parties and links to their policies.
-"Collect and use" user data generally refers to the collection, transmission, use, or sharing of user data. Common examples of how products may handle personal or sensitive user data include:
+If you're unsure where to start, look at the privacy policy of any plugin published by the Dify team for a working template.
-* Using forms that gather any kind of personally identifiable information.
-* Implementing login features, even when using third-party authentication services.
-* Collecting information about input or resources that may contain personally identifiable information.
-* Implementing analytics to track user behavior, interactions, and usage patterns.
-* Storing communication data like messages, chat logs, or email addresses.
-* Accessing user profiles or data from connected social media accounts.
-* Collecting health and fitness data such as activity levels, heart rate, or medical information.
-* Storing search queries or tracking browsing behavior.
-* Processing financial information including bank details, credit scores, or transaction history.
+## Declare it in the manifest
-## Related Resources
+The privacy URL goes in the plugin manifest. See [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) for the exact field.
-- [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview) - Understand the plugin publishing process
-- [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace) - Learn how to submit plugins to the official marketplace
-- [Plugin Developer Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct) - Understand plugin submission guidelines
-- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications) - Plugin metadata configuration
+## Common questions
+
+
+
+ Any of: collecting, transmitting, storing, logging, sharing, or analyzing user data. Concrete examples:
+
+ - Forms that gather personally identifiable information
+ - Login or third-party-auth flows
+ - Capturing user input that may contain PII
+ - Analytics that track user behavior or usage patterns
+ - Storing messages, chat logs, or email addresses
+ - Accessing connected social-media profiles
+ - Collecting health or fitness data
+ - Storing search queries or browsing behavior
+ - Processing financial information (bank details, credit scores, transactions)
+
+
+ Say so explicitly in the privacy policy. Reviewers still expect a `PRIVACY.md` file or hosted URL; it just needs to state that no user data is collected, stored, or transmitted, including by any third-party services the plugin calls.
+
+
+ Plugins that touch health, finance, biometrics, or children's data get extra review. Be explicit about each data type, the legal basis for collecting it, retention period, and how users can request deletion.
+
+
+
+## Related resources
+
+- [Publishing Overview](/en/develop-plugin/publishing/marketplace-listing/release-overview)
+- [Plugin Development Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct)
+- [Publish to Dify Marketplace](/en/develop-plugin/publishing/marketplace-listing/release-to-dify-marketplace)
+- [General Specifications](/en/develop-plugin/features-and-specs/plugin-types/general-specifications)
{/*
Contributing Section
@@ -103,4 +113,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/standards/privacy-protection-guidelines.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-
diff --git a/en/develop-plugin/publishing/standards/third-party-signature-verification.mdx b/en/develop-plugin/publishing/standards/third-party-signature-verification.mdx
index 41fd14195..fe60f4c0a 100644
--- a/en/develop-plugin/publishing/standards/third-party-signature-verification.mdx
+++ b/en/develop-plugin/publishing/standards/third-party-signature-verification.mdx
@@ -7,101 +7,122 @@ dimensions:
standard_title: Third-Party Signature Verification
language: en
title: Sign Plugins for Third-Party Signature Verification
-description: This document describes how to enable and use the third-party signature verification feature in the Dify Community Edition, including key pair generation, plugin signing and verification, and environment configuration steps, enabling administrators to securely install plugins not available on the Dify Marketplace.
+description: Enable signed `.difypkg` installation in Dify Community Edition without disabling signature verification entirely (generate keys, sign packages, distribute the public key)
---
-This feature is available only in the Dify Community Edition. Third-party signature verification is not currently supported on Dify Cloud Edition.
+
+Third-party signature verification is a **Dify Community Edition** feature. Dify Cloud manages signatures centrally and does not expose these controls.
+
-Third-party signature verification allows Dify administrators to safely approve the installation of plugins not listed on the Dify Marketplace without completely disabling signature verification. This supports the following scenarios for example:
+Self-hosted Dify enforces signature verification by default. Third-party signature verification lets administrators safely install plugins that are not on the Marketplace without disabling verification entirely.
-* Dify administrators can add a signature to a plugin sent by the developer once it has been approved.
-* Plugin developers can add a signature to their plugin and publish it along with the public key for Dify administrators who cannot disable signature verification.
+Two scenarios:
-Both Dify administrators and plugin developers can add a signature to a plugin using a pre-generated key pair. Additionally, administrators can configure Dify to enforce signature verification using specific public keys during plugin installation.
+
+
+ The admin reviews a `.difypkg` from a trusted developer and signs it with their own key before installing.
+
+
+ The developer signs the `.difypkg` and publishes the matching public key. Admins who trust the developer add that public key to the verification list.
+
+
-## Generate a Key Pair for Signing and Verification
+The mechanics are the same in both cases: generate a key pair, sign with the private key, verify with the public key.
-Generate a new key pair for adding and verifying the plugin's signature with the following command:
+## Generate a key pair
```bash
dify signature generate -f your_key_pair
```
-After running this command, two files will be generated in the current directory:
-
-* **Private Key**: `your_key_pair.private.pem`
-* **Public Key**: `your_key_pair.public.pem`
-
-The private key is used to sign the plugin, and the public key is used to verify the plugin's signature.
-
-Keep the private key secure. If it is compromised, an attacker could add a valid signature to any plugin, which would compromise Dify's security.
-
-## Add a Signature to the Plugin and Verify It
-
-Add a signature to your plugin by running the following command. Note that you must specify the **plugin file to sign** and the **private key**:
-
-```bash
-dify signature sign your_plugin_project.difypkg -p your_key_pair.private.pem
-```
-
-After executing the command, a new plugin file will be generated in the same directory with `signed` added to its original filename: `your_plugin_project.signed.difypkg`
-
-You can verify that the plugin has been correctly signed using this command. Here, you need to specify the **signed plugin file** and the **public key**:
-
-```bash
-dify signature verify your_plugin_project.signed.difypkg -p your_key_pair.public.pem
-```
-
-If you omit the public key argument, verification will use the Dify Marketplace public key. In that case, signature verification will fail for any plugin file not downloaded from the Dify Marketplace.
-
-## Enable Third-Party Signature Verification
-
-Dify administrators can enforce signature verification using pre-approved public keys before installing a plugin.
-
-### Place the Public Key
-
-Place the **public key** corresponding to the private key used for signing in a location that the plugin daemon can access.
-
-For example, create a `public_keys` directory under `docker/volumes/plugin_daemon` and copy the public key file there:
-
-```bash
-mkdir docker/volumes/plugin_daemon/public_keys
-cp your_key_pair.public.pem docker/volumes/plugin_daemon/public_keys
-```
-
-### Environment Variable Configuration
-
-In the `plugin_daemon` container, configure the following environment variables:
-
-* `THIRD_PARTY_SIGNATURE_VERIFICATION_ENABLED`
- * Enables third-party signature verification.
- * Set this to `true` to enable the feature.
-* `THIRD_PARTY_SIGNATURE_VERIFICATION_PUBLIC_KEYS`
- * Specifies the path(s) to the public key file(s) used for signature verification.
- * You can list multiple public key files separated by commas.
-
-Below is an example of a Docker Compose override file (`docker-compose.override.yaml`) configuring these variables:
-
-```yaml
-services:
- plugin_daemon:
- environment:
- FORCE_VERIFYING_SIGNATURE: true
- THIRD_PARTY_SIGNATURE_VERIFICATION_ENABLED: true
- THIRD_PARTY_SIGNATURE_VERIFICATION_PUBLIC_KEYS: /app/storage/public_keys/your_key_pair.public.pem
-```
-
-Note that `docker/volumes/plugin_daemon` is mounted to `/app/storage` in the `plugin_daemon` container. Ensure that the path specified in `THIRD_PARTY_SIGNATURE_VERIFICATION_PUBLIC_KEYS` corresponds to the path inside the container.
-
-To apply these changes, restart the Dify service:
-
-```bash
-cd docker
-docker compose down
-docker compose up -d
-```
-
-After restarting the service, the third-party signature verification feature will be enabled in the current Community Edition environment.
+Two files appear in the current directory:
+
+| File | Use |
+| :--- | :--- |
+| `your_key_pair.private.pem` | Sign plugins (keep secret) |
+| `your_key_pair.public.pem` | Verify signatures (share publicly) |
+
+
+Guard the private key. Anyone who has it can sign plugins that pass verification on installations trusting your public key.
+
+
+## Sign and verify a plugin
+
+
+
+ ```bash
+ dify signature sign your_plugin_project.difypkg -p your_key_pair.private.pem
+ ```
+
+ Produces `your_plugin_project.signed.difypkg` in the same directory.
+
+
+ ```bash
+ dify signature verify your_plugin_project.signed.difypkg -p your_key_pair.public.pem
+ ```
+
+ Confirms the signature matches before you distribute or install.
+
+
+
+
+If you omit `-p`, `dify signature verify` checks against the Dify Marketplace public key. Any plugin not signed by Dify will fail verification in that mode.
+
+
+## Enable verification on the daemon
+
+Admins install signed plugins by giving the plugin daemon a list of trusted public keys.
+
+
+
+ Put the `.public.pem` file somewhere the daemon container can reach it. For Docker Compose installs:
+
+ ```bash
+ mkdir -p docker/volumes/plugin_daemon/public_keys
+ cp your_key_pair.public.pem docker/volumes/plugin_daemon/public_keys/
+ ```
+
+
+ Set these variables on the `plugin_daemon` service:
+
+ | Variable | Value |
+ | :--- | :--- |
+ | `FORCE_VERIFYING_SIGNATURE` | `true` |
+ | `THIRD_PARTY_SIGNATURE_VERIFICATION_ENABLED` | `true` |
+ | `THIRD_PARTY_SIGNATURE_VERIFICATION_PUBLIC_KEYS` | Comma-separated paths to public keys inside the container |
+
+ A `docker-compose.override.yaml` snippet:
+
+ ```yaml
+ services:
+ plugin_daemon:
+ environment:
+ FORCE_VERIFYING_SIGNATURE: true
+ THIRD_PARTY_SIGNATURE_VERIFICATION_ENABLED: true
+ THIRD_PARTY_SIGNATURE_VERIFICATION_PUBLIC_KEYS: /app/storage/public_keys/your_key_pair.public.pem
+ ```
+
+
+ `docker/volumes/plugin_daemon` mounts to `/app/storage` inside the container, so the path in `THIRD_PARTY_SIGNATURE_VERIFICATION_PUBLIC_KEYS` must use the in-container path.
+
+
+
+ ```bash
+ cd docker
+ docker compose down
+ docker compose up -d
+ ```
+
+ Verified installs are now enforced: signed `.difypkg` files matching the configured public keys install cleanly; unsigned or mismatched ones are rejected.
+
+
+
+## Related resources
+
+- [Package as Local File and Share](/en/develop-plugin/publishing/marketplace-listing/release-by-file)
+- [Publish to Individual GitHub Repository](/en/develop-plugin/publishing/marketplace-listing/release-to-individual-github-repo)
+- [Plugin Development Guidelines](/en/develop-plugin/publishing/standards/contributor-covenant-code-of-conduct)
+- [Publishing FAQ](/en/develop-plugin/publishing/faq/faq)
{/*
Contributing Section
@@ -112,4 +133,3 @@ It will be automatically generated by the script.
---
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/publishing/standards/third-party-signature-verification.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
-