7 · 工具与插件生态（Tool and Plugin Ecosystem）

工具与插件生态

工具与插件生态系统

相关源文件

本章引用的主要源码文件：

• api/controllers/console/workspace/tool_providers.py
• api/core/entities/knowledge_entities.py
• api/core/entities/provider_entities.py
• api/core/helper/marketplace.py
• api/core/mcp/client/sse_client.py
• api/core/mcp/client/streamable_client.py
• api/core/mcp/mcp_client.py
• api/core/mcp/session/base_session.py
• api/core/mcp/session/client_session.py
• api/core/plugin/endpoint/exc.py
• api/core/plugin/entities/endpoint.py
• api/core/plugin/entities/marketplace.py
• api/core/plugin/entities/plugin.py
• api/core/plugin/entities/plugin_daemon.py
• api/core/plugin/entities/request.py
• api/core/plugin/impl/base.py
• api/core/plugin/impl/datasource.py
• api/core/plugin/impl/endpoint.py
• api/core/plugin/impl/exc.py
• api/core/plugin/impl/model.py
• api/core/plugin/impl/oauth.py
• api/core/plugin/impl/plugin.py
• api/core/tools/__base/tool.py
• api/core/tools/builtin_tool/tool.py
• api/core/tools/custom_tool/provider.py
• api/core/tools/custom_tool/tool.py
• api/core/tools/entities/api_entities.py
• api/core/tools/entities/tool_bundle.py
• api/core/tools/entities/tool_entities.py
• api/core/tools/errors.py
• api/core/tools/mcp_tool/provider.py
• api/core/tools/plugin_tool/tool.py
• api/core/tools/tool_engine.py
• api/core/tools/tool_manager.py
• api/core/tools/utils/configuration.py
• api/core/tools/utils/dataset_retriever/dataset_retriever_base_tool.py
• api/core/tools/utils/dataset_retriever_tool.py
• api/core/tools/utils/model_invocation_utils.py
• api/core/tools/workflow_as_tool/tool.py
• api/migrations/versions/2025_07_22_0019-375fe79ead14_oauth_refresh_token.py
• api/schedule/check_upgradable_plugin_task.py
• api/services/plugin/oauth_service.py
• api/services/tools/api_tools_manage_service.py
• api/services/tools/builtin_tools_manage_service.py
• api/services/tools/mcp_tools_manage_service.py
• api/services/tools/tools_transform_service.py
• api/services/tools/workflow_tools_manage_service.py
• api/tasks/process_tenant_plugin_autoupgrade_check_task.py
• api/tests/test_containers_integration_tests/services/tools/__init__.py
• api/tests/test_containers_integration_tests/services/tools/test_api_tools_manage_service.py
• api/tests/unit_tests/core/plugin/test_endpoint_client.py
• api/tests/unit_tests/core/plugin/test_plugin_runtime.py
• api/tests/unit_tests/core/tools/test_base_tool.py
• api/tests/unit_tests/core/tools/workflow_as_tool/test_tool.py
• api/tests/unit_tests/services/tools/test_builtin_tools_manage_service.py
• api/tests/unit_tests/services/tools/test_mcp_tools_transform.py
• api/tests/unit_tests/tasks/test_process_tenant_plugin_autoupgrade_check_task.py
• api/tests/unit_tests/tools/test_api_tool.py
• api/tests/unit_tests/utils/http_parser/test_oauth_convert_request_to_raw_data.py
• docker/ssrf_proxy/squid.conf.template

目的与范围

本文档描述了 Dify 中的工具与插件架构，涵盖外部工具如何在应用中被集成、管理和执行。工具生态系统使 Agent 聊天应用和工作流节点能够通过五种不同的提供者类型调用外部功能：内置工具、基于 API 的工具、工作流即工具、基于插件的工具以及 MCP（模型上下文协议）服务器。

详细信息请参见：

• 工具提供者类型与架构
• 内置与 API 工具集成
• MCP 协议集成
• 插件守护进程与执行环境

工具提供者类型分类

Dify 支持五种不同的工具提供者类型，每种类型服务于不同的集成模式和使用场景。这些类型在 ToolProviderType 枚举中定义 api/core/tools/entities/tool_entities.py:65-76。

提供者类型概览

来源： api/core/tools/entities/tool_entities.py:65-76，api/models/tools.py:64-64，api/core/tools/tool_manager.py:22-29

来源： api/core/tools/entities/tool_entities.py:65-76，api/core/tools/tool_manager.py:42-47

ToolManager：中央协调单例

ToolManager 类 api/core/tools/tool_manager.py:98 作为所有工具操作的协调单例，负责管理提供者发现、凭证解析和工具运行时实例化。

ToolManager 架构

来源： api/core/tools/tool_manager.py:98-192

工具运行时检索流程

get_tool_runtime() 方法 api/core/tools/tool_manager.py:182 协调凭证查找、解密和工具实例化。它会返回专门的工具实例，例如 BuiltinTool、PluginTool、ApiTool、WorkflowTool 或 MCPTool api/core/tools/tool_manager.py:192。

关于架构和单例模式的详细信息，请参见 工具提供者类型与架构。

内置与 API 工具集成

内置工具是通过 BuiltinToolManageService api/services/tools/builtin_tools_manage_service.py:40 存储和管理的预打包实现。API 工具允许用户通过提供 OpenAPI/Swagger 规范来定义自定义工具，由 ApiToolManageService api/services/tools/api_tools_manage_service.py:39 管理。

ToolTransformService api/services/tools/tools_transform_service.py:37 负责管理数据库模型与前端使用的 API 实体之间的转换。这些工具的凭证以加密格式存储，ToolManager 在运行时创建期间处理解密 api/core/tools/tool_manager.py:220-230。API 工具使用 ApiBasedToolSchemaParser 将原始规范转换为 ApiToolBundle 实体 api/services/tools/api_tools_manage_service.py:48-50。

关于凭证管理和模式解析的详细信息，请参见 内置与 API 工具集成。

MCP 协议集成

Dify 集成了 模型上下文协议（MCP），使其能够连接到远程 MCP 服务器。MCPToolManageService api/services/tools/mcp_tools_manage_service.py:78 管理这些连接的生命周期和提供者持久化。

MCP 连接架构

MCPClient api/controllers/console/workspace/tool_providers.py:26 处理底层传输，支持 SSE（服务器发送事件）和可流式 HTTP 连接。

来源： api/services/tools/mcp_tools_manage_service.py:19-22，api/controllers/console/workspace/tool_providers.py:23-26

关于传输层和服务器通信的详细信息，请参见 MCP 协议集成。

插件守护进程与执行环境

Dify 中的插件在由 插件守护进程 管理的安全环境中执行。PluginToolManager api/core/plugin/impl/tool.py:21 和 PluginToolProviderController api/core/tools/plugin_tool/provider.py:26 通过 BasePluginClient api/core/plugin/impl/base.py:62 与此守护进程交互，以获取工具声明并执行逻辑。

插件发现

当调用 ToolManager.get_plugin_provider() 时，它会利用 PluginToolManager 从插件守护进程获取工具提供者声明 api/core/tools/tool_manager.py:166-170。这确保了插件工具会根据租户已安装的插件动态加载。通信使用专用的 API 密钥，并通过 W3C traceparent 请求头处理分布式追踪 api/core/plugin/impl/base.py:108-112。

关于安全隔离和市场集成的详细信息，请参见 插件守护进程与执行环境。

工具执行引擎

ToolEngine api/core/tools/tool_engine.py:42 负责工具的实际调用。它为不同的上下文提供了专门的方法：

• agent_invoke()：由 Agent 应用使用，用于在聊天上下文中处理工具调用，并与 DifyAgentCallbackHandler 集成 api/core/tools/tool_engine.py:48-55。
• generic_invoke()：一种更通用的调用方法，由工作流节点使用，通过 workflow_call_depth 支持嵌套工作流调用 api/core/tools/tool_engine.py:158-163。

该引擎处理参数校验、命中回调（例如 on_tool_start、on_tool_end），并通过 _create_message_files() api/core/tools/tool_engine.py:109 管理二进制文件输出。工作流特定的工具由 WorkflowTool 处理，它使用 WorkflowAppGenerator 执行底层图 api/core/tools/workflow_as_tool/tool.py:89-91。

来源： api/core/tools/tool_engine.py:42-167，api/core/tools/workflow_as_tool/tool.py:35-119