> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 通用规范

> 各类插件共享的通用数据结构，包括 I18nObject、ProviderConfig、ModelConfig、NodeResponse 和 ToolSelector

> 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/develop-plugin/features-and-specs/plugin-types/general-specifications)。

本页介绍所有插件类型共享的结构。建议结合 [插件开发基本概念](/zh/develop-plugin/getting-started/getting-started-dify-plugin) 和 [开发者速查表](/zh/develop-plugin/getting-started/cli) 一起阅读，以了解整体架构。

## 路径规范

在 Manifest 或任何 YAML 文件中填写文件路径时，根据文件类型遵循以下两条规则：

* 图片、视频等多媒体文件（例如插件的 `icon`），放在插件根目录下的 `_assets` 文件夹中。
* 普通文本文件，如 `.py` 或 `.yaml` 代码文件，使用其在插件项目中的绝对路径引用。

## 通用结构

部分数据结构在工具、模型和 Endpoint 之间共享，在此统一定义。

### I18nObject

`I18nObject` 是符合 [IETF BCP 47](https://tools.ietf.org/html/bcp47) 标准的国际化结构，支持四种语言：

<ParamField path="en_US" type="string">
  英语（美国）。
</ParamField>

<ParamField path="zh_Hans" type="string">
  简体中文。
</ParamField>

<ParamField path="ja_JP" type="string">
  日语。
</ParamField>

<ParamField path="pt_BR" type="string">
  葡萄牙语（巴西）。
</ParamField>

### ProviderConfig

`ProviderConfig` 是供应商通用表单结构，`Tool` 和 `Endpoint` 都会使用。

<ParamField path="name" type="string">
  表单项名称。
</ParamField>

<ParamField path="label" type="I18nObject" required>
  显示标签，遵循 [IETF BCP 47](https://tools.ietf.org/html/bcp47) 标准。
</ParamField>

<ParamField path="type" type="provider_config_type" required>
  表单字段类型，决定该字段在 UI 中的渲染方式。
</ParamField>

<ParamField path="scope" type="provider_config_scope">
  可选的范围限定，随 `type` 的取值而变化。
</ParamField>

<ParamField path="required" type="boolean">
  该字段是否不能为空。
</ParamField>

<ParamField path="default" type="any">
  默认值。仅支持基本类型：`float`、`int`、`string`。
</ParamField>

<ParamField path="options" type="array[provider_config_option]">
  可用选项。仅在 `type` 为 `select` 时使用。
</ParamField>

<ParamField path="helper" type="object">
  帮助文档链接标签，遵循 [IETF BCP 47](https://tools.ietf.org/html/bcp47)。
</ParamField>

<ParamField path="url" type="string">
  帮助文档链接。
</ParamField>

<ParamField path="placeholder" type="object">
  多语言占位符文本，遵循 [IETF BCP 47](https://tools.ietf.org/html/bcp47)。
</ParamField>

### ProviderConfigOption (object)

<ParamField path="value" type="string" required>
  选项的值。
</ParamField>

<ParamField path="label" type="object" required>
  选项的显示标签，遵循 [IETF BCP 47](https://tools.ietf.org/html/bcp47)。
</ParamField>

### ProviderConfigType (string)

<ParamField path="secret-input" type="string">
  将被加密的配置信息。
</ParamField>

<ParamField path="text-input" type="string">
  纯文本输入字段。
</ParamField>

<ParamField path="select" type="string">
  下拉选择字段。
</ParamField>

<ParamField path="boolean" type="boolean">
  开关/切换控件。
</ParamField>

<ParamField path="model-selector" type="object">
  模型配置选择器，包含供应商名称、模型名称和模型参数。
</ParamField>

<ParamField path="app-selector" type="object">
  应用 ID 选择器。
</ParamField>

<ParamField path="tool-selector" type="object">
  工具配置选择器，包含工具供应商、名称和参数。
</ParamField>

<ParamField path="dataset-selector" type="string">
  数据集选择器（待定）。
</ParamField>

### ProviderConfigScope (string)

当 `type` 为 `model-selector` 时：

<ParamField path="all" type="string">
  所有模型类型。
</ParamField>

<ParamField path="llm" type="string">
  仅大语言模型。
</ParamField>

<ParamField path="text-embedding" type="string">
  仅文本嵌入模型。
</ParamField>

<ParamField path="rerank" type="string">
  仅重排序模型。
</ParamField>

<ParamField path="tts" type="string">
  仅文字转语音模型。
</ParamField>

<ParamField path="speech2text" type="string">
  仅语音转文字模型。
</ParamField>

<ParamField path="moderation" type="string">
  仅内容审核模型。
</ParamField>

<ParamField path="vision" type="string">
  仅视觉模型。
</ParamField>

当 `type` 为 `app-selector` 时：

<ParamField path="all" type="string">
  所有应用类型。
</ParamField>

<ParamField path="chat" type="string">
  仅聊天应用。
</ParamField>

<ParamField path="workflow" type="string">
  仅工作流应用。
</ParamField>

<ParamField path="completion" type="string">
  仅补全应用。
</ParamField>

当 `type` 为 `tool-selector` 时：

<ParamField path="all" type="string">
  所有工具类型。
</ParamField>

<ParamField path="plugin" type="string">
  仅插件工具。
</ParamField>

<ParamField path="api" type="string">
  仅 API 工具。
</ParamField>

<ParamField path="workflow" type="string">
  仅工作流工具。
</ParamField>

### ModelConfig

<ParamField path="provider" type="string">
  包含 `plugin_id` 的模型供应商名称，格式为 `langgenius/openai/openai`。
</ParamField>

<ParamField path="model" type="string">
  具体的模型名称。
</ParamField>

<ParamField path="model_type" type="enum">
  模型类型枚举，参见 [模型设计规则](/zh/develop-plugin/features-and-specs/plugin-types/model-designing-rules#modeltype)。
</ParamField>

### NodeResponse

<ParamField path="inputs" type="dict">
  最终传入节点的变量。
</ParamField>

<ParamField path="outputs" type="dict">
  节点的输出结果。
</ParamField>

<ParamField path="process_data" type="dict">
  节点执行期间生成的数据。
</ParamField>

### ToolSelector

<ParamField path="provider_id" type="string">
  工具供应商名称。
</ParamField>

<ParamField path="tool_name" type="string">
  工具名称。
</ParamField>

<ParamField path="tool_description" type="string">
  工具描述。
</ParamField>

<ParamField path="tool_configuration" type="dict[string, any]">
  工具配置信息。
</ParamField>

<ParamField path="tool_parameters" type="dict[string, dict]">
  需要 LLM 推理的参数。

  <ParamField path="name" type="string">
    参数名称。
  </ParamField>

  <ParamField path="type" type="string">
    参数类型。
  </ParamField>

  <ParamField path="required" type="boolean">
    该参数是否必填。
  </ParamField>

  <ParamField path="description" type="string">
    参数描述。
  </ParamField>

  <ParamField path="default" type="any">
    默认值。
  </ParamField>

  <ParamField path="options" type="array[string]">
    该参数的可用选项。
  </ParamField>
</ParamField>

## 相关资源

* [插件开发基本概念](/zh/develop-plugin/getting-started/getting-started-dify-plugin)：Dify 插件开发总览
* [开发者速查表](/zh/develop-plugin/dev-guides-and-walkthroughs/cheatsheet)：常用命令和概念的快速参考
* [工具插件开发详解](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)：定义插件信息及工具插件开发流程
* [模型设计规则](/zh/develop-plugin/features-and-specs/plugin-types/model-designing-rules)：模型配置的相关标准