[Dify] 插件中的 operationId 与 tool 配置规则详解

在 Dify 的插件系统（Plugin System）中，
每个插件接口最终会在智能体（Agent）中注册为一个“工具（Tool）”。
而这个注册过程的核心依据就是——
来自 OpenAPI Schema 文件中的字段（注意，这里讨论的插件是指自己写Schema的自定义工具，不是指Marketplace上那些封装好的插件）：

✅ operationId
✅ tool（插件配置项中定义的工具标识）

理解并正确使用这两个字段，是开发稳定插件的关键。

本文将详细讲解：

• operationId 在 Dify 中的作用

• Dify 如何将 API 转换为 Tool

• tool 名称、别名、参数规则

• 冲突与命名陷阱

• 实战建议与最佳命名规范

---

一、插件机制回顾：Dify 如何识别一个接口？

当你在 Dify 中导入一个 OpenAPI Schema 文件（.yaml / .json）时，
系统会自动执行以下步骤：