跳到主要内容

工具配置规范

本文档详细介绍 GeniSpace 工具的配置结构和规范，包括输入输出 Schema 定义、配置参数管理等核心概念。

配置结构概览​

每个工具包含以下主要配置部分：

{
  "name": "工具名称",
  "identifier": "operator-id",
  "description": "工具描述",
  "type": "operator",  // 或 "agent"
  "inputPorts": [ /* 输入端口定义 */ ],
  "outputPorts": [ /* 输出端口定义 */ ],
  "inputSchema": { /* 输入数据结构定义 */ },
  "outputSchema": { /* 输出数据结构定义 */ },
  "configuration": {
    "schema": { /* 用户配置项定义 */ },
    "values": { /* 默认配置值 */ }
  },
  "systemConfiguration": {
    "schema": { /* 系统配置项定义 */ },
    "values": { /* 系统配置值 */ }
  },
  "metadata": {
    "origin": "built-in" | "custom",
    "runtime": {
      "type": "worker" | "rest-api" | "container" | "mcp",
      "config": {}
    }
  }
}

工具类型配置​

智能体（Agent）工具配置​

智能体工具具有特殊的配置结构，包含 AI 模型相关的配置：

{
  "type": "agent",
  "name": "医美营销Pro",
  "description": "专注医美行业的智能营销专家",
  "promptTemplate": "请为【{{product}}】撰写小红书种草文案，核心卖点：{{features}}，目标人群：{{target}}，使用场景：{{scenario}}。要求突出{{key_benefit}}并解决{{pain_point}}问题",
  "systemPrompt": "你是一位精通医美行业的小红书运营专家，需遵循以下准则：\n1. 文案符合小红书社区规范，采用年轻女性偏好的语言风格\n2. 使用场景化描述搭配emoji表情符号\n3. 植入相关话题标签（#医美新趋势 #护肤黑科技）\n4. 突出产品成分/技术优势与用户痛点关联\n5. 规避广告法禁用词汇，采用体验分享形式\n6. 结合用户分层（年龄/肤质/消费能力）提供定制化方案",
  "inputPorts": [
    {
      "name": "memory",
      "type": "boolean",
      "label": "启用历史对话记忆",
      "required": false
    },
    {
      "name": "product",
      "type": "string",
      "label": "产品名称",
      "required": false
    },
    {
      "name": "features",
      "type": "string",
      "label": "产品特性",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "answer",
      "type": "string",
      "label": "生成内容"
    }
  ],
  "model": {
    "id": "3638ac90-902e-424c-84fd-a100d9e97b43",
    "identifier": "deepseek-v3",
    "name": "DeepSeek-V3",
    "apiType": "openai",
    "modelType": "text",
    "systemConfiguration": {
      "model": "deepseek-v3",
      "apiKey": "sk-xxx",
      "apiUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "provider": "alibaba"
    }
  }
}

Worker 工具配置​

Worker 工具的配置结构：

{
  "type": "operator",
  "name": "邮件发送器",
  "identifier": "email",
  "method": "default",
  "inputPorts": [
    {
      "name": "to",
      "type": "string",
      "label": "收件人",
      "required": true
    },
    {
      "name": "content",
      "type": "string",
      "label": "邮件内容",
      "required": true
    },
    {
      "name": "subject",
      "type": "string",
      "label": "邮件主题",
      "required": true
    },
    {
      "name": "attachments",
      "type": "array",
      "label": "附件",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "success",
      "type": "boolean",
      "label": "发送状态"
    },
    {
      "name": "messageId",
      "type": "string",
      "label": "消息ID"
    }
  ],
  "metadata": {
    "origin": "built-in",
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}

API 工具配置​

API 工具的配置结构：

{
  "type": "operator",
  "name": "发送邮件plus",
  "identifier": "email-operator",
  "method": "default",
  "inputPorts": [
    {
      "name": "to",
      "type": "string",
      "label": "收件人",
      "required": true
    },
    {
      "name": "cc",
      "type": "array",
      "label": "抄送",
      "required": false
    },
    {
      "name": "bcc",
      "type": "array",
      "label": "密送",
      "required": false
    },
    {
      "name": "subject",
      "type": "string",
      "label": "主题",
      "required": true
    },
    {
      "name": "text",
      "type": "string",
      "label": "文本内容",
      "required": false
    },
    {
      "name": "html",
      "type": "string",
      "label": "HTML内容",
      "required": false
    },
    {
      "name": "attachment_files",
      "type": "array",
      "label": "附件文件",
      "required": false
    }
  ],
  "outputPorts": [
    {
      "name": "success",
      "type": "boolean",
      "label": "发送状态"
    },
    {
      "name": "data",
      "type": "object",
      "label": "返回数据"
    }
  ],
  "metadata": {
    "origin": "custom",
    "runtime": {
      "type": "rest-api",
      "config": {
        "serverUrl": "https://api.genitask.cn",
        "method": "POST",
        "endpoint": "https://api.genitask.cn/njs-operators/message/email_operator",
        "timeout": 30000,
        "retryPolicy": {
          "maxAttempts": 3,
          "intervalMs": 1000
        },
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "headers": []
      }
    }
  }
}

Input Schema（输入模式）​

Input Schema 定义了工具接受的输入数据结构，基于 JSON Schema 标准。

智能体输入 Schema​

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "memory": {
        "type": "boolean",
        "default": false,
        "description": "启用历史对话记忆"
      },
      "target": {
        "type": "string",
        "description": "目标人群"
      },
      "context": {
        "type": "boolean",
        "default": false,
        "description": "启用知识库内容"
      },
      "product": {
        "type": "string",
        "description": "产品名称"
      },
      "features": {
        "type": "string",
        "description": "产品特性"
      },
      "internet": {
        "type": "boolean",
        "default": false,
        "description": "启用互联网搜索"
      },
      "scenario": {
        "type": "string",
        "description": "使用场景"
      },
      "pain_point": {
        "type": "string",
        "description": "用户痛点"
      },
      "key_benefit": {
        "type": "string",
        "description": "核心利益点"
      }
    }
  }
}

基本结构​

{
  "type": "object",
  "required": ["param1"],
  "properties": {
    "param1": {
      "type": "string",
      "title": "参数1",
      "description": "参数1的描述",
      "isPort": true
    },
    "param2": {
      "type": "number",
      "title": "参数2",
      "description": "参数2的描述",
      "default": 100,
      "minimum": 0,
      "maximum": 1000
    }
  }
}

支持的数据类型​

1. 字符串类型（string）​

{
  "type": "string",
  "title": "文本输入",
  "description": "请输入文本内容",
  "minLength": 1,
  "maxLength": 1000,
  "pattern": "^[a-zA-Z0-9]+$",
  "default": "默认值"
}

2. 数字类型（number/integer）​

{
  "type": "number",
  "title": "数值输入",
  "description": "请输入数值",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.1,
  "default": 50
}

3. 布尔类型（boolean）​

{
  "type": "boolean",
  "title": "开关选项",
  "description": "是否启用该功能",
  "default": false
}

4. 数组类型（array）​

{
  "type": "array",
  "title": "列表数据",
  "description": "数据列表",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

5. 对象类型（object）​

{
  "type": "object",
  "title": "配置对象",
  "description": "复杂配置对象",
  "properties": {
    "name": {
      "type": "string",
      "title": "名称"
    },
    "value": {
      "type": "number",
      "title": "数值"
    }
  },
  "required": ["name"]
}

端口标识​

使用 isPort 属性标识该字段是否为工作流连接端口：

{
  "param1": {
    "type": "string",
    "title": "输入数据",
    "isPort": true,  // 标识为端口，可在工作流中连接
    "description": "来自上游节点的数据"
  },
  "config1": {
    "type": "string",
    "title": "配置参数",
    "isPort": false, // 非端口，仅作为配置参数
    "description": "工具配置参数"
  }
}

默认值设置​

可以为输入参数设置默认值：

{
  "properties": {
    "timeout": {
      "type": "number",
      "title": "超时时间",
      "description": "请求超时时间（秒）",
      "default": 30,
      "minimum": 1,
      "maximum": 300
    },
    "retryCount": {
      "type": "integer",
      "title": "重试次数",
      "description": "失败时的重试次数",
      "default": 3,
      "minimum": 0,
      "maximum": 10
    }
  }
}

Output Schema（输出模式）​

Output Schema 定义了工具产生的输出数据结构。

智能体输出 Schema​

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "string",
        "label": "生成内容",
        "description": "AI 生成的回答内容"
      }
    }
  }
}

基本结构​

{
  "type": "object",
  "properties": {
    "result": {
      "type": "object",
      "title": "处理结果",
      "description": "工具执行的结果数据",
      "properties": {
        "status": {
          "type": "string",
          "title": "状态",
          "enum": ["success", "error"]
        },
        "data": {
          "type": "object",
          "title": "数据",
          "description": "实际的结果数据"
        },
        "message": {
          "type": "string",
          "title": "消息",
          "description": "执行消息或错误信息"
        }
      }
    },
    "metadata": {
      "type": "object",
      "title": "元数据",
      "description": "执行过程的元数据信息",
      "properties": {
        "executionTime": {
          "type": "number",
          "title": "执行时间",
          "description": "工具执行耗时（毫秒）"
        },
        "timestamp": {
          "type": "string",
          "title": "时间戳",
          "format": "date-time"
        }
      }
    }
  }
}

条件输出​

对于有条件分支的工具，可以定义多个输出端口：

{
  "type": "object",
  "properties": {
    "success": {
      "type": "object",
      "title": "成功输出",
      "description": "处理成功时的输出",
      "isPort": true
    },
    "error": {
      "type": "object",
      "title": "错误输出",
      "description": "处理失败时的输出",
      "isPort": true
    }
  }
}

Configuration（配置管理）​

工具的配置分为两个层级：工具级配置和方法级配置。

工具级配置​

工具级配置是全局性的配置，影响整个工具的行为：

{
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "服务器地址",
          "description": "API 服务器的基础地址",
          "required": true,
          "format": "uri"
        },
        "timeout": {
          "type": "number",
          "title": "全局超时时间",
          "description": "请求超时时间（毫秒）",
          "default": 30000,
          "minimum": 1000,
          "maximum": 300000
        },
        "headers": {
          "type": "array",
          "title": "全局请求头",
          "description": "应用于所有请求的全局请求头",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "title": "Header名称"
              },
              "value": {
                "type": "string",
                "title": "Header值"
              }
            },
            "required": ["key", "value"]
          }
        },
        "retryPolicy": {
          "type": "object",
          "title": "全局重试策略",
          "properties": {
            "maxAttempts": {
              "type": "number",
              "title": "最大重试次数",
              "default": 3,
              "minimum": 0,
              "maximum": 10
            },
            "intervalMs": {
              "type": "number",
              "title": "重试间隔",
              "description": "重试间隔时间（毫秒）",
              "default": 1000,
              "minimum": 100
            }
          }
        }
      }
    },
    "values": {
      "serverUrl": "",
      "timeout": 30000,
      "headers": [
        {"key": "Content-Type", "value": "application/json"}
      ],
      "retryPolicy": {
        "maxAttempts": 3,
        "intervalMs": 1000
      }
    }
  }
}

方法级配置​

每个工具方法可以有自己的特定配置：

{
  "methods": [
    {
      "name": "获取用户信息",
      "identifier": "get-user",
      "configuration": {
        "schema": {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "title": "请求方法",
              "enum": ["GET", "POST", "PUT", "DELETE"],
              "default": "GET",
              "required": true
            },
            "endpoint": {
              "type": "string",
              "title": "接口路径",
              "description": "相对于服务器地址的接口路径",
              "required": true,
              "pattern": "^/"
            },
            "caching": {
              "type": "object",
              "title": "缓存配置",
              "properties": {
                "enabled": {
                  "type": "boolean",
                  "title": "启用缓存",
                  "default": false
                },
                "ttlSeconds": {
                  "type": "number",
                  "title": "缓存时间",
                  "description": "缓存有效期（秒）",
                  "default": 3600,
                  "minimum": 60
                }
              }
            },
            "headers": {
              "type": "array",
              "title": "方法特定请求头",
              "description": "仅应用于此方法的请求头",
              "items": {
                "type": "object",
                "properties": {
                  "key": {"type": "string"},
                  "value": {"type": "string"}
                }
              }
            }
          }
        },
        "values": {
          "method": "GET",
          "endpoint": "/api/users/{id}",
          "caching": {
            "enabled": true,
            "ttlSeconds": 1800
          },
          "headers": []
        }
      }
    }
  ]
}

System Configuration（系统配置）​

系统配置是对用户不可见的内部配置，用于存储敏感信息和系统级参数。

工具级系统配置​

{
  "systemConfiguration": {
    "schema": {
      "type": "api",
      "properties": {
        "internalServerUrl": {
          "type": "string",
          "title": "内部服务器地址",
          "description": "内部API服务器地址",
          "required": true
        },
        "apiKey": {
          "type": "string",
          "title": "API密钥",
          "description": "系统级API密钥",
          "format": "password",
          "required": true
        },
        "rateLimiting": {
          "type": "object",
          "title": "限流配置",
          "properties": {
            "requestsPerSecond": {
              "type": "number",
              "title": "每秒请求数",
              "default": 10
            },
            "burstSize": {
              "type": "number",
              "title": "突发大小",
              "default": 20
            }
          }
        }
      }
    },
    "values": {
      "internalServerUrl": "https://internal-api.example.com",
      "apiKey": "system-secret-key",
      "rateLimiting": {
        "requestsPerSecond": 10,
        "burstSize": 20
      }
    }
  }
}

方法级系统配置​

{
  "methods": [
    {
      "systemConfiguration": {
        "schema": {
          "type": "api",
          "properties": {
            "internalEndpoint": {
              "type": "string",
              "title": "内部接口路径",
              "required": true
            },
            "authToken": {
              "type": "string",
              "title": "认证令牌",
              "format": "password"
            }
          }
        },
        "values": {
          "internalEndpoint": "/internal/users",
          "authToken": "method-specific-token"
        }
      }
    }
  ]
}

配置类型说明​

根据执行类型的配置差异​

API 类型工具​

{
  "metadata": {
    "runtime": {
      "type": "rest-api",
      "config": {
        "serverUrl": "https://api.genitask.cn",
        "method": "POST",
        "endpoint": "/njs-operators/message/email_operator",
        "timeout": 30000,
        "retryPolicy": {
          "maxAttempts": 3,
          "intervalMs": 1000
        },
        "caching": {
          "enabled": false,
          "ttlSeconds": 3600
        },
        "headers": []
      }
    }
  }
}

Worker 类型工具​

{
  "metadata": {
    "runtime": {
      "type": "worker",
      "config": {}
    }
  }
}

MCP 类型工具​

{
  "systemConfiguration": {
    "schema": {
      "type": "mcp",
      "properties": {
        "serverUrl": {"type": "string", "required": true},
        "model": {"type": "string", "required": true},
        "apiKey": {"type": "string", "format": "password"},
        "timeout": {"type": "number", "default": 60000}
      }
    }
  }
}

Container 类型工具​

{
  "systemConfiguration": {
    "schema": {
      "type": "container",
      "properties": {
        "image": {"type": "string", "required": true},
        "registry": {
          "type": "object",
          "properties": {
            "url": {"type": "string"},
            "username": {"type": "string"},
            "password": {"type": "string", "format": "password"}
          }
        },
        "resources": {
          "type": "object",
          "properties": {
            "memory": {"type": "string", "default": "512Mi"},
            "cpu": {"type": "string", "default": "0.5"}
          }
        }
      }
    }
  }
}

配置验证​

Schema 验证规则​

  1. 必填字段验证：使用 required 数组指定必填字段
  2. 数据类型验证：严格验证字段的数据类型
  3. 格式验证：使用 format 属性验证特定格式（如 email、uri、date-time）
  4. 范围验证：使用 minimum、maximum、minLength、maxLength 等
  5. 枚举验证：使用 enum 限制可选值
  6. 正则验证：使用 pattern 进行正则表达式验证

示例验证配置​

{
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "title": "邮箱地址"
    },
    "url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https?://",
      "title": "网址"
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "title": "端口号"
    },
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "pending"],
      "title": "状态"
    }
  },
  "required": ["email", "url"]
}

最佳实践​

1. Schema 设计原则​

  • 清晰的命名：使用有意义的字段名和标题
  • 详细的描述：为每个字段提供清晰的描述
  • 合理的默认值：为可选字段提供合理的默认值
  • 适当的验证：添加必要的验证规则，但不要过度限制

2. 配置分层​

  • 工具级配置：全局性、通用性的配置
  • 方法级配置：特定于某个方法的配置
  • 用户配置：用户可见可配置的参数
  • 系统配置：系统内部使用的敏感配置

3. 向后兼容​

  • 新增字段：总是添加默认值
  • 修改字段：保持向后兼容，考虑使用新字段名
  • 删除字段：标记为废弃，而不是直接删除

4. 安全考虑​

  • 敏感信息：使用 format: "password" 标记敏感字段
  • 输入验证：严格验证所有输入数据
  • 权限控制：区分用户配置和系统配置的访问权限

相关文档​