Quartz 4

dify-custom-tool

9 min read

📋 什么是 Dify 自定义工具？

Dify 自定义工具是通过 OpenAPI 3.0 规范定义的 API 接口，可以在 Dify 的工作流或 Agent 中调用。

📄 文件格式

格式类型：OpenAPI 3.0 规范（YAML 或 JSON）

当前文件 api.md 使用的是 YAML 格式的 OpenAPI 3.0 规范。

文件扩展名

  • ✅ .yaml 或 .yml（推荐）

  • ✅ .json

  • ✅ .md（如果内容是 OpenAPI YAML，也可以）

🔍 文件结构说明

1. 基本信息（info）

 
openapi: 3.0.0
 
info:
 
  title: NovelFlow API              # 工具名称
 
  description: NovelFlow 外部应用接口集合  # 工具描述
 
  version: 1.0.0                     # 版本号
 
  contact:
 
    name: NovelFlow API Support      # 联系方式

2. 服务器配置（servers）

 
servers:
 
  - url: https://test-book.novelflow.app
 
    description: 生产环境（默认服务器，用于章节总结等已发布接口）

说明：

  • url：API 的基础地址

  • 可以有多个服务器（生产、测试等）

  • 路径级别的接口可以覆盖全局服务器配置

3. 接口路径（paths）

 
paths:
 
  /api/v1/externalbookapp/text-to-image:  # 接口路径
 
    post:                                 # HTTP 方法
 
      summary: 文生图接口                  # 接口摘要
 
      description: 根据文本提示词生成图片  # 接口描述
 
      operationId: generateImage          # 操作ID（工具调用名称）
 
      requestBody:                        # 请求体（POST/PUT）
 
        required: true
 
        content:
 
          application/json:
 
            schema:
 
              $ref: '#/components/schemas/TextToImageRequest'
 
      responses:                          # 响应定义
 
        '200':
 
          description: 成功生成图片
 
          content:
 
            application/json:
 
              schema:
 
                type: object
 
                properties:
 
                  code:
 
                    type: integer
 
                  data:
 
                    $ref: '#/components/schemas/TextToImageData'
 
      security:
 
        - AppNameAuth: []                # 安全认证配置

4. 组件定义（components）

 
components:
 
  schemas:                              # 数据模型定义
 
    TextToImageRequest:                 # 请求模型
 
      type: object
 
      required:
 
        - prompt
 
        - modelName
 
      properties:
 
        prompt:
 
          type: string
 
          description: 文本提示词（必填，最大1000字符）
 
          maxLength: 1000
 
        modelName:
 
          type: string
 
          description: 模型名称（必填）
 
    TextToImageData:                    # 响应模型
 
      type: object
 
      properties:
 
        imageUrl:
 
          type: string
 
          description: 生成的图片OSS URL
 
  securitySchemes:                      # 安全认证方案
 
    AppNameAuth:
 
      type: apiKey
 
      in: header
 
      name: X-AppName
 
      description: 应用名称认证头，值为 NovelFlow

✅ Dify 导入要求

必需字段

  1. openapi：版本号（必须是 3.0.0）

  2. info：基本信息

   - title：工具名称

   - version：版本号

  1. paths：至少定义一个接口路径

  2. operationId：每个接口必须有一个唯一的 operationId（这是工具调用名称）

推荐字段

  1. servers：服务器地址配置

  2. components/schemas：数据模型定义（便于复用）

  3. components/securitySchemes：安全认证配置

  4. description：接口和参数的详细描述

🎯 关键配置说明

operationId（工具调用名称）

 
operationId: generateImage

作用：

  • 这是 Dify 中调用工具时使用的标识符

  • 必须唯一

  • 建议使用驼峰命名（camelCase）

  • 应该与接口功能相关

示例：

  • ✅ generateImage（生成图片）

  • ✅ getChapterSummary（获取章节总结）

  • ❌ api1（不推荐，不够描述性）

工具显示名称

Dify 会根据以下字段显示工具名称（优先级从高到低）：

  1. summary：接口摘要

  2. operationId：操作ID

  3. description：接口描述

建议：

  • summary：简短的中文名称（如”文生图接口”）

  • operationId：英文调用名称（如 generateImage）

  • description：详细的功能描述

📝 在 Dify 中使用

导入步骤

  1. 进入 Dify

   - 登录 Dify 平台

   - 进入 工具 → API工具

  1. 导入 OpenAPI 规范

   - 点击 添加工具 或 导入

   - 选择 “从 OpenAPI 规范导入”

   - 上传 api.md 文件或直接粘贴内容

  1. 配置认证（如果定义了 securitySchemes）

   - 在工具编辑页面配置认证信息

   - 例如：Header 认证 X-AppName: NovelFlow

  1. 测试工具

   - 点击 测试 按钮

   - 确认接口可以正常调用

🔧 当前文件检查

✅ 当前 api.md 文件符合要求

检查项：

  • ✅ OpenAPI 版本：3.0.0

  • ✅ 基本信息完整：title, description, version

  • ✅ 服务器配置：已定义

  • ✅ 接口路径：已定义两个接口

  • ✅ operationId：已定义（getChapterSummary, generateImage）

  • ✅ 请求/响应定义：完整

  • ✅ 安全认证：已定义 AppNameAuth

  • ✅ 数据模型：已定义 schemas

⚠️ 需要注意的点

  1. 服务器地址

   - 全局服务器：https://test-book.novelflow.app（测试环境）

   - 文生图接口：路径级别覆盖为测试环境

   - 章节总结接口：使用全局服务器

  1. 认证配置

   - 定义了 AppNameAuth 安全方案

   - 需要在 Dify 中手动配置 X-AppName: NovelFlow header

📚 参考资源

OpenAPI 3.0 规范

Dify 文档

💡 最佳实践

  1. 命名规范

   - operationId：使用驼峰命名，动词开头（如 generateImage）

   - summary：简短描述性名称（中文或英文）

   - description：详细的功能说明

  1. 版本管理

   - 在 info.version 中维护版本号

   - 重大变更时更新版本号

  1. 文档完整性

   - 为所有参数添加 description

   - 提供 example 示例值

   - 明确标注 required 必填字段

  1. 错误处理

   - 定义完整的响应状态码（200, 400, 404, 500等）

   - 提供错误响应的 schema 定义

  1. 安全配置

   - 使用 securitySchemes 定义认证方式

   - 在接口级别应用安全配置

🎯 总结

Dify 自定义工具格式：

  • 格式：OpenAPI 3.0 规范（YAML 或 JSON）

  • 文件扩展名：.yaml, .yml, .json 或 .md

  • 必需字段：openapi, info, paths, operationId

  • 推荐字段：servers, components, securitySchemes

当前 api.md 文件格式正确，可以直接导入到 Dify 中使用！

Graph View