diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..ad64a3f4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +._DS_Store +.DS_Store diff --git a/plugin_dev_zh/0221-initialize-development-tools.zh.mdx b/plugin_dev_zh/0221-initialize-development-tools.zh.mdx index ca641c3e..8363f5de 100644 --- a/plugin_dev_zh/0221-initialize-development-tools.zh.mdx +++ b/plugin_dev_zh/0221-initialize-development-tools.zh.mdx @@ -7,30 +7,58 @@ dimensions: standard_title: Initialize Development Tools language: zh title: 初始化开发工具 -description: 本文档详细介绍了Dify插件开发前的必要准备工作，包括安装Dify插件脚手架工具（dify-plugin-daemon）和配置Python环境（版本要求≥3.12）的完整步骤。文档还提供了各类型插件开发的参考链接。 +description: 本文档详细介绍了Dify插件开发前的必要准备工作，包括安装Dify插件CLI工具（dify-plugin-daemon）和配置Python环境（版本要求≥3.12）的完整步骤。文档还提供了各类型插件开发的参考链接。 --- 开发 Dify 插件需要进行以下准备。本文档是开始[插件开发](/plugin_dev_zh/0111-getting-started-dify-plugin.zh)的第一步。 -* Dify 插件脚手架工具 +* Dify 插件 CLI 工具 * Python 环境，版本号 ≥ 3.12 -> Dify 插件开发脚手架工具又称为 `dify-plugin-daemon`，可以被视作**插件开发 SDK**。 +> Dify 插件 CLI 工具又称为 `dify-plugin-daemon`，可以被视作**插件开发 SDK**。 -### **1. 安装 Dify 插件开发脚手架工具** +### **1. 安装 Dify 插件 CLI 工具** -访问 [Dify Plugin CLI](https://github.com/langgenius/dify-plugin-daemon/releases) 项目地址，下载并安装最新版本号和对应操作系统的工具。 +Dify 插件 CLI 工具可以通过 Homebrew（在 Linux 和 macOS 上）或独立的二进制可执行文件（在 Windows、Linux 和 macOS 上）进行安装。 + +#### 通过 Homebrew 安装 + +对于 macOS 和 Linux 用户，建议使用 [Homebrew](https://brew.sh/) 安装 Dify 插件 CLI 工具。 + +首先添加 [Dify 插件 CLI 工具的 Homebrew 配方](https://github.com/langgenius/homebrew-dify)，然后使用 `brew install` 命令进行安装。 + +```bash +brew tap langgenius/dify +brew install dify +``` + +要检查安装是否成功，请运行 `dify version`，应该会显示版本代码。 +```bash +dify version +``` + +要升级 Dify 插件 CLI 工具，请运行以下命令： + +```bash +brew upgrade dify +``` + +#### 通过二进制可执行文件安装 + +**下载二进制可执行文件：** + +访问 [Dify Plugin CLI](https://github.com/langgenius/dify-plugin-daemon/releases) 项目地址，在发布页面的资产列表中，选择并下载适合操作系统（Linux / macOS / Windows）和芯片架构（`amd64` 为 x86 芯片 / `arm64` 为 ARM 或 Apple 的 M 芯片）的二进制可执行文件。 本文**以装载 M 系列芯片的 macOS** 为例。下载 `dify-plugin-darwin-arm64` 文件后，赋予其执行权限。 -``` -chmod +x dify-plugin-darwin-arm64 +```bash +chmod +x ./dify-plugin-darwin-arm64 +mv ./dify-plugin-darwin-arm64 ./dify ``` -运行以下命令检查安装是否成功。 - -``` -./dify-plugin-darwin-arm64 version +要检查安装是否成功，请运行 `./dify version`，应该会显示版本代码。 +```bash +./dify version ``` > 若提示 “Apple 无法验证” 错误，请前往 **“设置 → 隐私与安全性 → 安全性”**，轻点 “仍要打开” 按钮。 @@ -39,7 +67,7 @@ chmod +x dify-plugin-darwin-arm64 > **💡 提示：** > -> 如果想要在系统全局使用 `dify` 命令运行脚手架工具，建议将该二进制文件重命名为 `dify` 并拷贝至 `/usr/local/bin` 系统路径内。 +> 如果想要在系统全局使用 `dify` 命令运行 CLI 工具，建议将该二进制文件重命名为 `dify` 并拷贝至 `/usr/local/bin` 系统路径内。 > > 配置完成后，在终端输入 `dify version` 命令后将输出版本号信息。 > diff --git a/plugin_dev_zh/0222-tool-plugin.zh.mdx b/plugin_dev_zh/0222-tool-plugin.zh.mdx index 72043ea8..935b09f4 100644 --- a/plugin_dev_zh/0222-tool-plugin.zh.mdx +++ b/plugin_dev_zh/0222-tool-plugin.zh.mdx @@ -218,7 +218,7 @@ extra: - `identity` 包含了工具的基本信息，包括名称、作者、标签、描述等。 - `parameters` 参数列表 - `name` （必填）参数名称，唯一，不允许和其他参数重名。 - - `type` （必填）参数类型，目前支持`string`、`number`、`boolean`、`select`、`secret-input` 五种类型，分别对应字符串、数字、布尔值、下拉框、加密输入框，对于敏感信息，请使用`secret-input`类型。 + - `type` （必填）参数类型，目前支持`string`、`number`、`boolean`、`select`、`secret-input`、`file`、`files`、`model-selector`、`app-selector` 九种类型，分别对应字符串、数字、布尔值、下拉框、加密输入框、文件、文件集、模型选择、应用选择，对于敏感信息，请使用 `secret-input` 类型。 - `label`（必填）参数标签，用于前端展示。 - `form` （必填）表单类型，目前支持`llm`、`form`两种类型。 - 在 Agent 应用中，`llm` 表示该参数 LLM 自行推理，`form` 表示要使用该工具可提前设定的参数。 @@ -287,7 +287,7 @@ class GoogleSearchTool(Tool): 该例子的含义为请求 `serpapi`，并使用 `self.create_json_message` 返回一串 `json` 的格式化数据，如果想了解更多的返回数据类型，可以参考[远程调试插件](/plugin_dev_zh/0411-remote-debug-a-plugin.zh)和[持久化存储 KV](/plugin_dev_zh/0411-persistent-storage-kv.zh)文档。 -#### 4. 完成工具供应商代码 +#### 5. 完成工具供应商代码 最后需要创建一个供应商的实现代码，用于实现凭据验证逻辑。如果凭据验证失败，将会抛出`ToolProviderCredentialValidationError`异常。验证成功后，将正确请求 `google_search` 工具服务。 diff --git a/plugin_dev_zh/0312-privacy-protection-guidelines.zh.mdx b/plugin_dev_zh/0312-privacy-protection-guidelines.zh.mdx index 13176d4f..24dd1598 100644 --- a/plugin_dev_zh/0312-privacy-protection-guidelines.zh.mdx +++ b/plugin_dev_zh/0312-privacy-protection-guidelines.zh.mdx @@ -76,7 +76,7 @@ description: 本文档描述了开发者向Dify Marketplace提交插件时如何 * 使用登录功能（含第三方认证）； * 收集可能包含个人信息的输入或资源； * 分析用户行为、互动和使用情况； -* 存储通讯内容，如消息、聊天记录、邮箱； +* 存储通讯内容，如消息、聊天记录、邮件； * 访问关联社交媒体的用户资料； * 收集健康数据，如运动、心率、医疗信息； * 保存搜索记录或浏览行为； diff --git a/plugin_dev_zh/0321-release-overview.zh.mdx b/plugin_dev_zh/0321-release-overview.zh.mdx index 5e6d1055..aab18ba6 100644 --- a/plugin_dev_zh/0321-release-overview.zh.mdx +++ b/plugin_dev_zh/0321-release-overview.zh.mdx @@ -76,6 +76,12 @@ description: 本文档介绍了Dify插件的三种发布方式：官方Marketpla * **开源共享项目** → **推荐使用 GitHub**，方便版本管理与社区协作。 * **快速分发或内部测试** → **推荐使用插件文件**，简单高效地安装和分享。 +{/* +### 第三方验证 + +安装非 Dify 市场内的插件时，有可能遇到第三方签名验证问题。解决办法请参考[第三方签名验证](./signing-plugins-for-third-party-signature-verification.mdx)。 +*/} + ## 相关资源 - [插件开发基本概念](/plugin_dev_zh/0111-getting-started-dify-plugin.zh) - 全面了解Dify插件开发 diff --git a/plugin_dev_zh/0322-release-by-file.zh.mdx b/plugin_dev_zh/0322-release-by-file.zh.mdx index 43f607d3..78eba256 100644 --- a/plugin_dev_zh/0322-release-by-file.zh.mdx +++ b/plugin_dev_zh/0322-release-by-file.zh.mdx @@ -10,7 +10,7 @@ title: 打包为本地文件与分享 description: 本文档介绍了如何将Dify插件项目打包为本地文件并分享给他人的详细步骤。内容包括插件打包前的准备工作、使用Dify插件开发工具执行打包命令、生成的.difypkg文件的安装方式以及如何分享插件文件给其他用户。 --- -完成插件开发后，你可以将插件项目打包为一个本地文件并分享给他人，通过插件文件后即可安装至 Dify Workspace 内。如果您还没有开发插件，可以参考[插件开发入门指南](/plugin_dev_zh/0211-getting-started-dify-tool.zh)。 +完成插件开发后，你可以将插件项目打包为一个本地文件并分享给他人，通过插件文件即可安装至 Dify Workspace 内。如果您还没有开发插件，可以参考[插件开发入门指南](/plugin_dev_zh/0211-getting-started-dify-tool.zh)。 * **特点**： * 不依赖在线平台，**快速灵活**地分享插件。 diff --git a/plugin_dev_zh/0331-faq.zh.mdx b/plugin_dev_zh/0331-faq.zh.mdx index 44fa1261..bc5e57e4 100644 --- a/plugin_dev_zh/0331-faq.zh.mdx +++ b/plugin_dev_zh/0331-faq.zh.mdx @@ -19,7 +19,7 @@ description: Author Allen 本文档回答了Dify插件开发和安装过程中 重新运行插件打包命令并安装新的插件包。 -## 装插件时遇到异常应如何处理安？ +## 安装插件时遇到异常应如何处理？ **问题描述**：安装插件时遇到异常信息：`plugin verification has been enabled, and the plugin you want to install has a bad signature`，应该如何处理？ diff --git a/plugin_dev_zh/0411-general-specifications.zh.mdx b/plugin_dev_zh/0411-general-specifications.zh.mdx index 26163c97..65990852 100644 --- a/plugin_dev_zh/0411-general-specifications.zh.mdx +++ b/plugin_dev_zh/0411-general-specifications.zh.mdx @@ -37,8 +37,8 @@ description: 本文档详细介绍了Dify插件开发中的通用结构和规范 `ProviderConfig` 为一个通用的供应商表单结构，适用于 `Tool`与`Endpoint` * `name`(string)：表单项名称 -* `label`([I18nObject](#i18nobject), requierd)：遵循 [IETF BCP 47](https://tools.ietf.org/html/bcp47) -* `type`([provider\_config\_type](#providerconfigtype-string), requierd)：表单类型 +* `label`([I18nObject](#i18nobject), required)：遵循 [IETF BCP 47](https://tools.ietf.org/html/bcp47) +* `type`([provider\_config\_type](#providerconfigtype-string), required)：表单类型 * `scope`([provider\_config\_scope](#providerconfigscope-string))：可选项范围，根据`type`变动 * `required`(bool)：不能为空 * `default`(any)：默认值，仅支持基础类型 `float` `int` `string` diff --git a/plugin_dev_zh/0411-model-designing-rules.zh.mdx b/plugin_dev_zh/0411-model-designing-rules.zh.mdx index 4e7ab2b1..1fc9f8bd 100644 --- a/plugin_dev_zh/0411-model-designing-rules.zh.mdx +++ b/plugin_dev_zh/0411-model-designing-rules.zh.mdx @@ -130,16 +130,16 @@ description: 本文档详细定义了Dify模型插件开发的核心概念和结 可在 use\_template 中直接设置模板变量名，将会使用 entities.defaults.PARAMETER\_RULE\_TEMPLATE 中的默认配置不用设置除 `name` 和 `use_template` 之外的所有参数，若设置了额外的配置参数，将覆盖默认配置。可参考 `openai/llm/gpt-3.5-turbo.yaml`。 * `label` (object) \[optional] 标签，i18n -* `zh_Hans`(string) \[optional] 中文标签名 -* `en_US` (string) 英文标签名 + * `zh_Hans`(string) \[optional] 中文标签名 + * `en_US` (string) 英文标签名 * `type`(string) \[optional] 参数类型 * `int` 整数 * `float` 浮点数 * `string` 字符串 * `boolean` 布尔型 -* `help` (string) \[optional] 帮助信息 -* `zh_Hans` (string) \[optional] 中文帮助信息 -* `en_US` (string) 英文帮助信息 +* `help` (object) \[optional] 帮助信息 + * `zh_Hans` (string) \[optional] 中文帮助信息 + * `en_US` (string) 英文帮助信息 * `required` (bool) 是否必填，默认 False。 * `default`(int/float/string/bool) \[optional] 默认值 * `min`(int/float) \[optional] 最小值，仅数字类型适用 diff --git a/plugin_dev_zh/0411-model-plugin-introduction.zh.mdx b/plugin_dev_zh/0411-model-plugin-introduction.zh.mdx index 84c2cfd6..0e4d5bcb 100644 --- a/plugin_dev_zh/0411-model-plugin-introduction.zh.mdx +++ b/plugin_dev_zh/0411-model-plugin-introduction.zh.mdx @@ -8,6 +8,7 @@ standard_title: Model Plugin Introduction language: zh title: Model 插件 description: 介绍模型插件的基本概念和结构。模型插件让Dify能够调用不同供应商（如OpenAI、Anthropic、Google等）的各类模型，包括大语言模型（LLM）、文本嵌入、语音转文字等不同类型。 +todo: 考虑恢复被注释的'开始开发模型插件'章节，提供初学者友好的3步骤快速指引 --- Model 模型插件使 Dify 平台能够调用该模型供应商下的所有 LLM。例如，安装 OpenAI 模型插件后，Dify 平台即可调用 OpenAI 提供的 `GPT-4`、`GPT-4o-2024-05-13` 等模型。 @@ -73,6 +74,16 @@ Model 模型插件使 Dify 平台能够调用该模型供应商下的所有 LLM 模型插件通过配置文件定义模型的行为和属性。详细的模型设计规则和配置格式请参考[模型设计规则](/plugin_dev_zh/0411-model-designing-rules.zh)文档和[模型架构](/plugin_dev_zh/0412-model-schema.zh)规范。 +{/* +### 开始开发模型插件 + +请参考以下顺序阅读文档，了解如何开发一个模型插件。 + +1. [创建模型供应商](/zh-hans/plugins/quick-start/develop-plugins/model-plugin/create-model-providers) +2. 接入[预定义](/zh-hans/guides/model-configuration/predefined-model) / [自定义](/zh-hans/plugins/quick-start/develop-plugins/model-plugin/customizable-model)模型 +3. [调试插件](/zh-hans/plugins/quick-start/debug-plugin) +*/} + ## 进一步阅读 - [快速接入一个新模型](/plugin_dev_zh/0211-getting-started-new-model.zh) - 学习如何为已支持的供应商添加新模型 diff --git a/plugin_dev_zh/0411-persistent-storage-kv.zh.mdx b/plugin_dev_zh/0411-persistent-storage-kv.zh.mdx index c3cb454d..15d7f9a7 100644 --- a/plugin_dev_zh/0411-persistent-storage-kv.zh.mdx +++ b/plugin_dev_zh/0411-persistent-storage-kv.zh.mdx @@ -12,7 +12,7 @@ description: 本文档介绍了Dify插件中的持久化存储功能，详细说 如果单独审视插件中的 Tool 及 Endpoint，不难发现大多数情况下其只能完成单轮交互，请求后返回数据，任务结束。 -如果有需要长期储存的数据，如实现持久化的记忆，需要插件具备持久化存储能力。**持久化储机制能够让插件具备在相同 Workspace 持久存储数据的能力**，目前通过提供 KV 数据库满足存储需求，未来可能会根据实际的使用情况推出更灵活更强大的储存接口。 +如果有需要长期储存的数据，如实现持久化的记忆，需要插件具备持久化存储能力。**持久化存储机制能够让插件具备在相同 Workspace 持久存储数据的能力**，目前通过提供 KV 数据库满足存储需求，未来可能会根据实际的使用情况推出更灵活更强大的储存接口。 ### 储存 Key diff --git a/plugin_dev_zh/0411-plugin-info-by-manifest.zh.mdx b/plugin_dev_zh/0411-plugin-info-by-manifest.zh.mdx index df55bd97..c88c3dbe 100644 --- a/plugin_dev_zh/0411-plugin-info-by-manifest.zh.mdx +++ b/plugin_dev_zh/0411-plugin-info-by-manifest.zh.mdx @@ -14,6 +14,10 @@ Manifest 是一个符合 yaml 规范的文件，它定义了**插件**最基础 若该文件的格式错误，插件的解析和打包过程都将会失败。 +### 版本管理 + +插件的版本由 `manifest` 文件中的 `version` 字段管理。版本号必须符合 `大版本.小版本.补丁版本` 格式，否则自动更新可能无法正常工作。 + ### 代码示例 下面是一个 Manifest 文件的简单示例，将在下文解释各个数据的含义和作用。 @@ -54,7 +58,7 @@ meta: - "arm64" runner: language: "python" - version: "3.10" + version: "3.11" entrypoint: "main" privacy: "./privacy.md" ``` diff --git a/plugin_dev_zh/0411-remote-debug-a-plugin.zh.mdx b/plugin_dev_zh/0411-remote-debug-a-plugin.zh.mdx index 4027c8b6..abbfe8ca 100644 --- a/plugin_dev_zh/0411-remote-debug-a-plugin.zh.mdx +++ b/plugin_dev_zh/0411-remote-debug-a-plugin.zh.mdx @@ -10,11 +10,11 @@ title: 插件调试 description: 本文档介绍了如何使用Dify的远程调试功能来测试插件。详细说明了获取调试信息、配置环境变量文件、启动插件远程调试以及验证插件安装状态的完整流程。通过这种方式，开发者可以在本地开发的同时在Dify环境中实时测试插件。 --- -插件开发完成后，接下来需要测试插件是否可以正常运行。Dify 提供便捷地远程调试方式，帮助你快速在测试环境中验证插件功能。 +插件开发完成后，接下来需要测试插件是否可以正常运行。Dify 提供便捷的远程调试方式，帮助你快速在测试环境中验证插件功能。 前往[“插件管理”](https://cloud.dify.ai/plugins)页获取远程服务器地址和调试 Key。 -![远程调试插件](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png) +![远程调试插件](https://assets-docs.dify.ai/2025/04/2779338a43687f3e00155baccdd6d06c.png) 回到插件项目，拷贝 `.env.example` 文件并重命名为 `.env`，将获取的远程服务器地址和调试 Key 等信息填入其中。 diff --git a/plugin_dev_zh/0412-model-schema.zh.mdx b/plugin_dev_zh/0412-model-schema.zh.mdx index b2692684..d7ce6f71 100644 --- a/plugin_dev_zh/0412-model-schema.zh.mdx +++ b/plugin_dev_zh/0412-model-schema.zh.mdx @@ -116,7 +116,7 @@ def _invoke(self, model: str, credentials: dict, :param prompt_messages: prompt messages :param model_parameters: model parameters :param tools: tools for tool calling - :param stop: stop words + :param stop: stop sequences :param stream: is stream response :param user: unique user id :return: full response or stream response chunk generator result diff --git a/plugin_dev_zh/0432-develop-a-slack-bot-plugin.zh.mdx b/plugin_dev_zh/0432-develop-a-slack-bot-plugin.zh.mdx index 1d81b822..4e6520f1 100644 --- a/plugin_dev_zh/0432-develop-a-slack-bot-plugin.zh.mdx +++ b/plugin_dev_zh/0432-develop-a-slack-bot-plugin.zh.mdx @@ -258,7 +258,7 @@ class SlackEndpoint(Endpoint): ```bash INSTALL_METHOD=remote -REMOTE_INSTALL_HOST=remote +REMOTE_INSTALL_HOST=remote-url REMOTE_INSTALL_PORT=5003 REMOTE_INSTALL_KEY=****-****-****-****-**** ``` @@ -273,7 +273,7 @@ python -m main 在 Dify 的插件管理页中找到自动安装的测试插件，新建一个 Endpoint，填写名称、Bot token、选择需要连接的 app。 -![生成 POST 请求地址](https://assets-docs.dify.ai/2025/01/e6952a5798a7ae793b3fe7df6f76ea73.png) +![测试插件](https://assets-docs.dify.ai/2025/01/07f87e8a2786d6f5f05195961c5630c3.png) 保存后将生成一个 POST 请求地址。 @@ -297,7 +297,7 @@ python -m main 代码使用了 `self.session.app.chat.invoke` 调用 Dify 平台内的 App，并传递了 `app_id` 和 `query` 等信息，最后将 response 的内容返回至 Slack Bot。运行 `python -m main` 命令重启插件进行调试，确认 Slack Bot 是否能够正确输出 Dify App 的答复消息。 -![生成 POST 请求地址](https://assets-docs.dify.ai/2025/01/e6952a5798a7ae793b3fe7df6f76ea73.png) +![验证插件效果](https://assets-docs.dify.ai/2025/01/6fc872d1343ce8503d63c5222f7f26f9.png) ### 4. 打包插件（可选） diff --git a/plugin_dev_zh/9231-extension-plugin.zh.mdx b/plugin_dev_zh/9231-extension-plugin.zh.mdx index e47d4ed0..bd055120 100644 --- a/plugin_dev_zh/9231-extension-plugin.zh.mdx +++ b/plugin_dev_zh/9231-extension-plugin.zh.mdx @@ -233,7 +233,7 @@ pip install dify-plugin ```bash INSTALL_METHOD=remote -REMOTE_INSTALL_HOST=remote +REMOTE_INSTALL_HOST=remote-url REMOTE_INSTALL_PORT=5003 REMOTE_INSTALL_KEY=****-****-****-****-**** ``` @@ -251,8 +251,6 @@ REMOTE_INSTALL_KEY=****-****-****-****-**** 确认插件能够正常运行后，可以通过以下命令行工具打包并命名插件。运行以后你可以在当前文件夹发现 `neko.difypkg` 文件，该文件为最终的插件包。 ```bash -# 将 ./neko 替换为插件项目的实际路径 - dify plugin package ./neko ``` diff --git a/plugin_dev_zh/9232-agent.zh.mdx b/plugin_dev_zh/9232-agent.zh.mdx index 82566f68..35b44ccc 100644 --- a/plugin_dev_zh/9232-agent.zh.mdx +++ b/plugin_dev_zh/9232-agent.zh.mdx @@ -107,7 +107,7 @@ extra: source: strategies/function_calling.py ``` -代码格式类似 [`Tool` 标准格式](tool.md)，定义了 `model` `tools` `query` `max_iterations` 等一共四个参数，以便于实现最基础的 Agent 策略。该代码的含义是可以允许用户选择模型和需要使用的工具，配置最大迭代次数并最终传入一个 query 后开始执行 Agent。 +代码格式类似 [`Tool` 标准格式](/plugin_dev_zh/0411-tool.zh)，定义了 `model` `tools` `query` `max_iterations` 等一共四个参数，以便于实现最基础的 Agent 策略。该代码的含义是可以允许用户选择模型和需要使用的工具，配置最大迭代次数并最终传入一个 query 后开始执行 Agent。 #### 编写功能实现代码 diff --git a/plugin_dev_zh/9241-bundle.zh.mdx b/plugin_dev_zh/9241-bundle.zh.mdx index db6d6ca0..0a3d3326 100644 --- a/plugin_dev_zh/9241-bundle.zh.mdx +++ b/plugin_dev_zh/9241-bundle.zh.mdx @@ -23,7 +23,7 @@ Bundle 插件包是多个插件的集合。它可以将多个插件打包在一 * Dify 插件脚手架工具 * Python 环境，版本号 ≥ 3.10 -关于如何准备插件开发的脚手架工具，详细说明请参考[初始化开发工具](initialize-development-tools.md)。 +关于如何准备插件开发的脚手架工具，详细说明请参考[初始化开发工具](initialize-development-tools.zh.mdx)。 ### 创建 Bundle 项目 diff --git a/plugin_dev_zh/9242-reverse-invocation-app.zh.mdx b/plugin_dev_zh/9242-reverse-invocation-app.zh.mdx index a06e9f0a..62355946 100644 --- a/plugin_dev_zh/9242-reverse-invocation-app.zh.mdx +++ b/plugin_dev_zh/9242-reverse-invocation-app.zh.mdx @@ -62,8 +62,12 @@ class Duck(Endpoint): app_id = values["app_id"] def generator(): - response = self.session.app.workflow.invoke( - app_id=app_id, inputs={}, response_mode="streaming", files=[] + response = self.session.app.chat.invoke( + app_id=app_id, + inputs={}, + response_mode="streaming", + conversation_id="", # 可选，留空则创建新对话 + files=[] ) for data in response: diff --git a/plugin_dev_zh/9242-reverse-invocation-tool.zh.mdx b/plugin_dev_zh/9242-reverse-invocation-tool.zh.mdx index cae86661..a5981e84 100644 --- a/plugin_dev_zh/9242-reverse-invocation-tool.zh.mdx +++ b/plugin_dev_zh/9242-reverse-invocation-tool.zh.mdx @@ -90,7 +90,7 @@ description: 本文档详细介绍了插件如何反向调用Dify平台中的工 - [反向调用 App](/plugin_dev_zh/9242-reverse-invocation-app.zh) - 了解如何调用平台内的 App - [反向调用 Model](/plugin_dev_zh/9242-reverse-invocation-model.zh) - 了解如何调用平台内的模型能力 - [工具插件开发指南](/plugin_dev_zh/0211-getting-started-dify-tool.zh) - 学习如何开发工具插件 -- [高级工具插件](/plugin_dev_zh/9223-tool.zh) - 了解 Workflow as Tool 等高级功能\ +- [高级工具插件](/plugin_dev_zh/9223-tool.zh) - 了解 Workflow as Tool 等高级功能 {/* Contributing Section diff --git a/plugin_dev_zh/9243-customizable-model.zh.mdx b/plugin_dev_zh/9243-customizable-model.zh.mdx index b09c2bd8..c3e2c7f7 100644 --- a/plugin_dev_zh/9243-customizable-model.zh.mdx +++ b/plugin_dev_zh/9243-customizable-model.zh.mdx @@ -43,7 +43,7 @@ description: 本文档详细介绍了如何在Dify中接入自定义模型，以 示例代码： -```yaml +```yaml {14-17} provider: xinference # 确定供应商标识 label: # 供应商展示名称，可设置 en_US 英文、zh_Hans 中文两种语言，zh_Hans 不设置将默认使用 en_US。 en_US: Xorbits Inference @@ -69,7 +69,7 @@ provider_credential_schema: 接着需要定义 `provider_credential_schema` 字段。`Xinference 支持` text-generation，embeddings 和 reranking 模型，示例代码如下： -```yaml +```yaml {10,14,17} provider_credential_schema: credential_form_schemas: - variable: model_type @@ -107,7 +107,7 @@ Xinference 中的每个模型都需要定义名称 `model_name`。 Xinference 模型需要使用者输入模型的本地部署地址，插件内需要提供允许填写 Xinference 模型的本地部署地址（server\_url）和模型 UID 的位置，示例代码如下： -```yaml +```yaml {1,10} - variable: server_url label: zh_Hans: 服务器 URL diff --git a/plugin_dev_zh/9243-reverse-invocation-node.zh.mdx b/plugin_dev_zh/9243-reverse-invocation-node.zh.mdx index 8a9b7973..fe201c5f 100644 --- a/plugin_dev_zh/9243-reverse-invocation-node.zh.mdx +++ b/plugin_dev_zh/9243-reverse-invocation-node.zh.mdx @@ -35,7 +35,7 @@ description: 本文档介绍了插件如何反向调用Dify平台中的Chatflow/ pass ``` -其中 `parameters` 是需要提取出的参数的列表，`model` 符合 `LLMModelConfig` 规范，`query` 为提取参数的源文本，`instruction` 为一些可能额外需要给到 LLM 的指令，`NodeResponse` 的结构请参考该[文档](../general-specifications.md#noderesponse)。 +其中 `parameters` 是需要提取出的参数的列表，`model` 符合 `LLMModelConfig` 规范，`query` 为提取参数的源文本，`instruction` 为一些可能额外需要给到 LLM 的指令，`NodeResponse` 的结构请参考该[文档](../general-specifications#noderesponse)。 #### **用例** @@ -93,7 +93,7 @@ class ParameterExtractorTool(Tool): pass ``` -该接口参数与 `ParameterExtractor` 一致，最终的返回结果储存在 `NodeResponse.outputs['class_name']` 中。\ +该接口参数与 `ParameterExtractor` 一致，最终的返回结果储存在 `NodeResponse.outputs['class_name']` 中。 {/* Contributing Section diff --git a/plugin_dev_zh/9433-agent-strategy-plugin.zh.mdx b/plugin_dev_zh/9433-agent-strategy-plugin.zh.mdx index c6d15d19..1107c263 100644 --- a/plugin_dev_zh/9433-agent-strategy-plugin.zh.mdx +++ b/plugin_dev_zh/9433-agent-strategy-plugin.zh.mdx @@ -21,13 +21,13 @@ Agent 策略插件能够帮助 LLM 执行推理或决策逻辑，包括工具选 关于如何准备插件开发的脚手架工具，详细说明请参考[初始化开发工具](/plugin_dev_zh/0221-initialize-development-tools.zh)。 -**Tips**：在终端运行 `dify version` 命令，检查是否出现版本号以确认成功安装脚手架工具。 +**Tips**：在终端运行 `dify version` 命令，检查是否出现版本号以确认成功安装脚手架工具。 ### 1. 初始化插件模板 运行以下命令，初始化 Agent 插件开发模板。 -``` +```bash dify plugin init ``` @@ -72,7 +72,7 @@ Models: 初始化插件模板后将生成一个代码文件夹，包含插件开发过程中所需的完整资源。熟悉 Agent 策略插件的整体代码结构有助于插件的开发过程。 -``` +```text ├── GUIDE.md # User guide and documentation ├── PRIVACY.md # Privacy policy and data handling guidelines ├── README.md # Project overview and setup instructions @@ -103,13 +103,13 @@ Agent 策略插件的开发主要围绕以下两个文件展开： 建议优先配置以下四个基础参数： -1\. **model**：指定要调用的大语言模型（LLM），如 GPT-4、GPT-4o-mini 等。 +1. **model**：指定要调用的大语言模型（LLM），如 GPT-4、GPT-4o-mini 等。 -2\. **tools**：定义插件可以使用的工具列表，增强插件功能。 +2. **tools**：定义插件可以使用的工具列表，增强插件功能。 -3\. **query**：设置与模型交互的提示词或输入内容。 +3. **query**：设置与模型交互的提示词或输入内容。 -4\. **maximum\_iterations**：限制插件执行的最大迭代次数，避免过度计算。 +4. **maximum_iterations**：限制插件执行的最大迭代次数，避免过度计算。 示例代码： @@ -191,7 +191,7 @@ class BasicAgentAgentStrategy(AgentStrategy): params = BasicParams(**parameters) ``` -#### 3. 调用模型 +#### 2.3 调用模型 在 Agent 策略插件中，**调用模型**是核心执行逻辑之一。可以通过 SDK 提供的 `session.model.llm.invoke()` 方法高效地调用 LLM 模型，实现文本生成、对话处理等功能。 @@ -224,7 +224,91 @@ def invoke( ![生成工具的请求参数](https://assets-docs.dify.ai/2025/01/01e32c2d77150213c7c929b3cceb4dae.png) -#### 4. 调用工具 +#### 2.4 为模型添加记忆 + +当使用 Agent 插件调用模型时，为模型添加记忆功能能够极大提升对话体验。通过记忆功能，模型可以理解完整的对话上下文，实现连贯的交互体验和精准的工具调用。 + +具体实现步骤： + +1. 配置记忆功能 + +在 Agent 插件的 YAML 配置文件 `strategies/agent.yaml` 中添加 `history-messages` 特性： + +```yaml +identity: + name: basic_agent # Agent策略名称 + author: novice # 作者 + label: + en_US: BasicAgent # 英文标签 +description: + en_US: BasicAgent # 英文描述 +features: + - history-messages # 启用历史消息功能 +... +``` + +2. 启用记忆设置 + +修改插件配置文件并重启后，你将在节点配置界面中看到 **记忆** 开关。点击右侧的开关按钮，启用记忆功能。 + +启用后，您可以通过 **窗口大小** 滑块调整记忆窗口，它决定了模型能够“记住”多少之前的对话内容。 + +3. 调试历史消息 + +添加以下代码，查看历史消息内容： + +```python +class BasicAgentAgentStrategy(AgentStrategy): + def _invoke(self, parameters: dict[str, Any]) -> Generator[AgentInvokeMessage]: + params = BasicParams(**parameters) + print(f"history_messages: {params.model.history_prompt_messages}") + ... +``` + +![History messages](https://assets-docs.dify.ai/2025/04/cb11fae7981dae431966f83fa99f1dfb.png) + +控制台将显示类似如下输出： + +``` +history_messages: [] +history_messages: [UserPromptMessage(role=, content='hello, my name is novice', name=None), AssistantPromptMessage(role=, content='Hello, Novice! How can I assist you today?', name=None, tool_calls=[])] +``` + +4. 将历史消息集成到模型调用 + +最后，修改模型调用代码，将历史消息拼接到当前查询： + +```python +class BasicAgentAgentStrategy(AgentStrategy): + def _invoke(self, parameters: dict[str, Any]) -> Generator[AgentInvokeMessage]: + params = BasicParams(**parameters) + + chunks: Generator[LLMResultChunk, None, None] | LLMResult = ( + self.session.model.llm.invoke( + model_config=LLMModelConfig(**params.model.model_dump(mode="json")), + # 添加历史消息 + prompt_messages=params.model.history_prompt_messages + + [UserPromptMessage(content=params.query)], + tools=[ + self._convert_tool_to_prompt_message_tool(tool) + for tool in params.tools + ], + stop=params.model.completion_params.get("stop", []) + if params.model.completion_params + else [], + stream=True, + ) + ) + ... +``` + +5. 效果验证 + +添加加记忆功能后，模型能够基于历史对话进行回复。在下图示例中，模型成功地记住了之前对话中提及的用户名称，实现了对话的连贯性。 + +![Outcome](https://assets-docs.dify.ai/2025/04/6bdd3d2c6a455ae8e463bd6abab5c3a4.png) + +#### 2.5 调用工具 填写工具参数后，需赋予 Agent 策略插件实际调用工具的能力。可以通过 SDK 中的`session.tool.invoke()` 函数进行工具调用。 @@ -268,7 +352,7 @@ for tool_call_id, tool_call_name, tool_call_args in tool_calls: ![工具调用](https://assets-docs.dify.ai/2025/01/80e5de8acc2b0ed00524e490fd611ff5.png) -#### 5. 日志创建 +#### 2.6 日志创建 在 **Agent 策略插件**中，通常需要执行多轮操作才能完成复杂任务。记录每轮操作的执行结果对于开发者来说非常重要，有助于追踪 Agent 的执行过程、分析每一步的决策依据，从而更好地评估和优化策略效果。 @@ -331,9 +415,10 @@ model_log = self.create_log_message( yield model_log ``` -#### 插件功能示例代码 - +### 插件功能示例代码 + + #### 调用模型 以下代码将演示如何赋予 Agent 策略插件调用模型的能力： @@ -558,8 +643,9 @@ class BasicAgentAgentStrategy(AgentStrategy): return tool_calls ``` + - + #### 调用工具 以下代码展示了如何为 Agent 策略插件实现模型调用并向工具发送规范化请求。 @@ -784,8 +870,9 @@ class BasicAgentAgentStrategy(AgentStrategy): return tool_calls ``` + - + #### 完整功能代码示例 包含**调用模型、调用工具**以及**输出多轮日志功能**的完整插件代码示例： @@ -1041,14 +1128,14 @@ class BasicAgentAgentStrategy(AgentStrategy): return tool_calls ``` - - + + ### 3. 调试插件 -配置插件的声明文件与功能代码后，在插件的目录内运行 `python -m main` 命令重启插件。接下来需测试插件是否可以正常运行。Dify 提供远程调试方式，前往[“插件管理”](https://console-plugin.dify.dev/plugins)获取调试 Key 和远程服务器地址。 +配置插件的声明文件与功能代码后，在插件的目录内运行 `python -m main` 命令重启插件。接下来需测试插件是否可以正常运行。Dify 提供远程调试方式，前往[“插件管理”](https://cloud.dify.ai/plugins)获取调试 Key 和远程服务器地址。 -![远程调试插件](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png) +![Image](https://assets-docs.dify.ai/2024/12/053415ef127f1f4d6dd85dd3ae79626a.png) 回到插件项目，拷贝 `.env.example` 文件并重命名为 `.env`，将获取的远程服务器地址和调试 Key 等信息填入至 `REMOTE_INSTALL_HOST` 与 `REMOTE_INSTALL_KEY` 参数内。