跳到主要内容

创建自定义工具

本文档将指导您如何在 GeniSpace 平台上创建和管理自定义工具，包括手动创建和从 OpenAPI 文档导入两种方式。

自定义工具 vs 系统工具​

在开始创建自定义工具之前，让我们先了解自定义工具与系统工具的区别：

特性自定义工具系统工具
创建者用户自主创建平台管理员创建
配置权限完全可配置和定制只能配置用户部分，系统配置不可见
维护责任用户自行维护平台统一维护和更新
使用门槛高，需要技术配置低，启用即可使用
定制程度完全定制有限定制
共享范围个人或团队内全平台用户可用

建议使用场景：

  • 选择系统工具：如果平台已有符合需求的工具，优先使用系统工具
  • 选择自定义工具：需要特殊定制功能、集成私有服务或现有系统工具无法满足需求时

创建方式概览​

GeniSpace 提供多种创建自定义工具的方式：

  1. 手动创建 - 从零开始构建工具
  2. OpenAPI 导入 - 从 OpenAPI 文档快速生成工具
  3. Docker 容器 - 基于容器化应用创建工具

手动创建工具​

步骤 1：基本信息配置​

首先需要配置工具的基本信息：

{
  "name": "用户管理工具",
  "identifier": "user-management",
  "description": "提供用户信息的增删改查功能",
  "category": "api",
  "executionType": "api",
  "version": "1.0.0",
  "tags": ["用户", "管理", "API"]
}

字段说明：

  • name: 工具显示名称
  • identifier: 唯一标识符，只能包含小写字母、数字和连字符
  • description: 工具功能描述
  • category: 工具分类（api、data-source、transform 等）
  • executionType: 执行类型（api、worker、mcp、container）
  • version: 版本号
  • tags: 标签列表，便于搜索和分类

步骤 2：运行配置（用户配置）​

自定义工具使用单层配置结构，所有配置都由用户完全控制。配置工具的全局运行参数：

{
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "服务器地址",
          "required": true,
          "description": "API 服务器的基础地址"
        },
        "apiKey": {
          "type": "string",
          "title": "API 密钥",
          "sensitive": true,
          "description": "访问 API 的密钥"
        },
        "timeout": {
          "type": "number",
          "title": "全局超时时间",
          "default": 30000,
          "description": "请求超时时间（毫秒）"
        },
        "headers": {
          "type": "array",
          "title": "全局请求头",
          "items": {
            "type": "object",
            "properties": {
              "key": {"type": "string"},
              "value": {"type": "string"}
            }
          }
        }
      }
    },
    "values": {
      "serverUrl": "https://api.example.com",
      "apiKey": "your-api-key-here",
      "timeout": 30000,
      "headers": [
        {"key": "Content-Type", "value": "application/json"}
      ]
    }
  }
}

注意：与系统工具不同，自定义工具的所有配置（包括敏感信息）都需要用户自行配置和管理。建议使用 sensitive: true 标记敏感字段。

步骤 3：添加方法​

每个工具可以包含多个方法，每个方法代表一个具体的功能：

方法基本信息​

{
  "name": "获取用户信息",
  "identifier": "get-user",
  "description": "根据用户ID获取用户详细信息",
  "isDefault": true,
  "order": 1,
  "status": "ACTIVE"
}

输入 Schema​

定义方法接受的输入参数：

{
  "inputSchema": {
    "type": "object",
    "required": ["userId"],
    "properties": {
      "userId": {
        "type": "string",
        "title": "用户ID",
        "description": "要查询的用户ID",
        "isPort": true
      },
      "includeProfile": {
        "type": "boolean",
        "title": "包含详细信息",
        "description": "是否包含用户详细资料",
        "default": false
      }
    }
  }
}

输出 Schema​

定义方法产生的输出结果：

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "user": {
        "type": "object",
        "title": "用户信息",
        "properties": {
          "id": {"type": "string", "title": "用户ID"},
          "name": {"type": "string", "title": "用户名"},
          "email": {"type": "string", "title": "邮箱"},
          "profile": {
            "type": "object",
            "title": "详细资料",
            "properties": {
              "avatar": {"type": "string", "title": "头像"},
              "bio": {"type": "string", "title": "简介"}
            }
          }
        }
      },
      "metadata": {
        "type": "object",
        "title": "元数据",
        "properties": {
          "timestamp": {"type": "string", "title": "查询时间"},
          "source": {"type": "string", "title": "数据源"}
        }
      }
    }
  }
}

方法配置​

定义方法特定的配置参数：

{
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "method": {
          "type": "string",
          "title": "请求方法",
          "enum": ["GET", "POST"],
          "default": "GET",
          "required": true
        },
        "endpoint": {
          "type": "string",
          "title": "接口路径",
          "description": "相对于服务器地址的接口路径",
          "required": true
        },
        "caching": {
          "type": "object",
          "title": "缓存配置",
          "properties": {
            "enabled": {
              "type": "boolean",
              "title": "启用缓存",
              "default": false
            },
            "ttlSeconds": {
              "type": "number",
              "title": "缓存时间",
              "default": 3600
            }
          }
        }
      }
    },
    "values": {
      "method": "GET",
      "endpoint": "/api/users/{userId}",
      "caching": {
        "enabled": true,
        "ttlSeconds": 1800
      }
    }
  }
}

从 OpenAPI 导入​

支持的格式​

GeniSpace 支持从以下格式的 OpenAPI 文档导入工具：

  • OpenAPI 3.0 (JSON/YAML)
  • Swagger 2.0 (JSON/YAML)

导入方式​

1. URL 导入​

直接从 URL 导入 OpenAPI 文档：

https://api.example.com/openapi.json
https://api.example.com/swagger.yaml

2. 文件上传​

支持上传本地的 OpenAPI 文档文件：

  • .json 文件
  • .yaml 或 .yml 文件

自动生成内容​

从 OpenAPI 文档导入时，系统会自动生成：

工具基本信息​

{
  "name": "User API",  // 来自 info.title
  "description": "User management API",  // 来自 info.description
  "identifier": "user-api",  // 自动生成
  "version": "1.0.0"  // 来自 info.version
}

服务器配置​

{
  "configuration": {
    "values": {
      "serverUrl": "https://api.example.com"  // 来自 servers[0].url
    }
  }
}

方法生成​

每个 API 端点会生成对应的方法：

# OpenAPI 定义
paths:
  /users/{id}:
    get:
      summary: "获取用户信息"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "用户信息"
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string

生成的方法：

{
  "name": "获取用户信息",
  "identifier": "get-users-id",
  "inputSchema": {
    "type": "object",
    "required": ["id"],
    "properties": {
      "id": {
        "type": "string",
        "title": "用户ID",
        "isPort": true
      }
    }
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "result": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"}
        }
      }
    }
  },
  "configuration": {
    "values": {
      "method": "GET",
      "endpoint": "/users/{id}"
    }
  }
}

导入后的调整​

导入完成后，您可以进一步调整：

  1. 修改工具信息：调整名称、描述、分类等
  2. 优化 Schema：完善输入输出的数据结构定义
  3. 添加验证规则：为参数添加验证约束
  4. 配置缓存策略：设置合适的缓存规则
  5. 设置默认值：为可选参数提供默认值

配置安全性​

敏感信息处理​

自定义工具需要用户自行管理所有配置，包括敏感信息。建议遵循以下安全实践：

1. 标记敏感字段​

{
  "apiKey": {
    "type": "string",
    "title": "API 密钥",
    "sensitive": true,
    "description": "用于身份验证的密钥"
  },
  "password": {
    "type": "string",
    "title": "密码",
    "sensitive": true,
    "format": "password"
  }
}

2. 使用环境变量​

{
  "configuration": {
    "values": {
      "apiKey": "${API_KEY}",
      "serverUrl": "${SERVER_URL:-https://api.example.com}"
    }
  }
}

3. 配置验证​

{
  "apiKey": {
    "type": "string",
    "pattern": "^[A-Za-z0-9]{32}$",
    "description": "32位字母数字组合"
  },
  "serverUrl": {
    "type": "string",
    "format": "uri",
    "pattern": "^https://.*"
  }
}

访问控制​

  • 团队共享：可以将自定义工具分享给团队成员
  • 权限管理：设置不同成员的编辑权限
  • 使用限制：可以限制工具的使用范围和频率

Docker 容器工具​

基本配置​

{
  "executionType": "container",
  "systemConfiguration": {
    "schema": {
      "type": "container",
      "properties": {
        "image": {
          "type": "string",
          "title": "容器镜像",
          "required": true
        },
        "command": {
          "type": "string",
          "title": "执行命令"
        },
        "environment": {
          "type": "object",
          "title": "环境变量"
        },
        "resources": {
          "type": "object",
          "title": "资源限制",
          "properties": {
            "memory": {"type": "string", "default": "512Mi"},
            "cpu": {"type": "string", "default": "0.5"}
          }
        }
      }
    },
    "values": {
      "image": "my-app:latest",
      "command": "python app.py",
      "environment": {
        "API_KEY": "secret"
      },
      "resources": {
        "memory": "512Mi",
        "cpu": "0.5"
      }
    }
  }
}

容器要求​

容器化的工具需要满足以下要求：

  1. 输入输出规范：通过标准输入接收 JSON 格式的输入，通过标准输出返回 JSON 格式的结果
  2. 错误处理：使用适当的退出码表示执行状态
  3. 日志输出：将日志输出到标准错误流
  4. 资源管理：合理使用内存和 CPU 资源

示例容器代码​

#!/usr/bin/env python3
import json
import sys

def main():
    try:
        # 从标准输入读取参数
        input_data = json.load(sys.stdin)
        
        # 处理业务逻辑
        result = process_data(input_data)
        
        # 输出结果到标准输出
        json.dump(result, sys.stdout)
        sys.exit(0)
        
    except Exception as e:
        # 错误信息输出到标准错误
        print(f"Error: {str(e)}", file=sys.stderr)
        sys.exit(1)

def process_data(data):
    # 实际的业务处理逻辑
    return {
        "status": "success",
        "data": data,
        "timestamp": "2024-01-01T00:00:00Z"
    }

if __name__ == "__main__":
    main()

测试和调试​

1. 配置验证​

在保存工具之前，系统会自动验证：

  • JSON Schema 格式正确性
  • 必填字段完整性
  • 数据类型一致性
  • 标识符唯一性

2. 方法测试​

可以在工具编辑界面直接测试方法：

{
  "testInput": {
    "userId": "12345",
    "includeProfile": true
  },
  "expectedOutput": {
    "user": {
      "id": "12345",
      "name": "张三",
      "email": "zhangsan@example.com"
    }
  }
}

3. 工作流集成测试​

将工具添加到测试工作流中，验证：

  • 输入输出连接正确性
  • 数据流转正常
  • 错误处理机制
  • 性能表现

版本管理​

版本号规范​

建议使用语义化版本号：

  • 主版本号：不兼容的 API 修改
  • 次版本号：向下兼容的功能性新增
  • 修订号：向下兼容的问题修正

示例：1.2.3

更新策略​

  1. 向后兼容更新：修复 bug、优化性能
  2. 功能性更新：新增方法、扩展配置
  3. 破坏性更新：修改现有接口、删除功能

迁移指南​

当发布破坏性更新时，需要提供：

  1. 变更说明：详细说明修改内容
  2. 迁移步骤：指导用户如何升级
  3. 兼容性说明：说明影响范围
  4. 回滚方案：提供降级方案

最佳实践​

1. 设计原则​

  • 单一职责：每个工具专注于一个特定领域
  • 接口稳定：避免频繁修改公开接口
  • 错误友好：提供清晰的错误信息
  • 文档完整：编写详细的使用说明

2. 性能优化​

  • 合理缓存：为适合的操作启用缓存
  • 超时设置：设置合理的超时时间
  • 资源限制：避免资源过度消耗
  • 并发控制：处理高并发场景

3. 安全考虑​

  • 输入验证：严格验证所有输入参数
  • 权限控制：实现适当的访问控制
  • 敏感信息：妥善处理敏感数据
  • 审计日志：记录重要操作

4. 维护管理​

  • 监控告警：设置关键指标监控
  • 日志记录：记录详细的执行日志
  • 定期更新：及时修复问题和安全漏洞
  • 用户反馈：收集和处理用户反馈

5. 选择指南​

何时选择自定义工具​

  • 私有服务集成：需要连接内部或私有的 API 服务
  • 特殊业务逻辑：需要实现特定的业务处理逻辑
  • 定制化需求：现有系统工具无法满足特殊需求
  • 数据处理：需要特殊的数据转换或处理能力
  • 第三方集成：集成特定的第三方服务或工具

何时选择系统工具​

  • 通用服务：使用常见的第三方服务（微信、邮件等）
  • 标准功能：需要标准化的功能实现
  • 快速启动：希望快速开始使用，无需复杂配置
  • 维护成本：希望减少维护工作量
  • 最佳实践：希望使用经过验证的实现方案

相关文档​