跳到主要内容

系统工具

系统工具是 GeniSpace 平台内置的预配置工具，由平台管理员统一管理，为用户提供开箱即用的功能。本文档将详细介绍系统工具的概念、使用方法和配置管理。

概念介绍​

什么是系统工具​

系统工具是由平台管理员在后台预先配置的工具，具有以下特点：

  • 预配置：包含完整的功能定义和默认配置
  • 统一管理：由平台管理员维护和更新
  • 开箱即用：用户启用后即可直接使用
  • 配置分离：系统配置（不可见）与用户配置（可见）分离

系统工具 vs 自定义工具​

特性系统工具自定义工具
创建方式平台管理员创建用户自主创建
配置管理系统配置不可见，用户配置可编辑完全可配置
维护更新统一维护和更新用户自行维护
使用门槛低，直接启用高，需要配置
定制程度有限定制完全定制

配置结构​

双层配置设计​

系统工具采用双层配置设计：

{
  "systemConfiguration": {
    "schema": {
      "type": "object",
      "properties": {
        "apiKey": {
          "type": "string",
          "title": "API 密钥",
          "sensitive": true
        },
        "serverUrl": {
          "type": "string",
          "title": "服务器地址",
          "default": "https://api.example.com"
        }
      }
    },
    "values": {
      "apiKey": "admin-configured-key",
      "serverUrl": "https://api.example.com"
    }
  },
  "configuration": {
    "schema": {
      "type": "object",
      "properties": {
        "timeout": {
          "type": "number",
          "title": "超时时间",
          "default": 30000,
          "minimum": 1000,
          "maximum": 60000
        },
        "enableCache": {
          "type": "boolean",
          "title": "启用缓存",
          "default": true
        }
      }
    }
  }
}

配置类型说明​

systemConfiguration（系统配置）​

  • 不对用户可见
  • 包含敏感信息（API 密钥、内部配置等）
  • 由平台管理员配置和维护
  • 包含 schema 和 values 两部分

configuration（用户配置）​

  • 对用户可见可编辑
  • 包含用户可自定义的参数
  • 用户启用工具时填写具体值
  • 只包含 schema，values 由用户填写

工具类型​

API 类型工具​

适用于调用外部 REST API 服务：

{
  "executionType": "api",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "baseUrl": {
          "type": "string",
          "title": "基础URL"
        },
        "authentication": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": ["bearer", "apikey", "basic"]
            },
            "credentials": {
              "type": "string",
              "sensitive": true
            }
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "timeout": {"type": "number", "default": 30000},
        "retries": {"type": "number", "default": 3}
      }
    }
  }
}

示例系统工具：

  • 微信 API 工具
  • 钉钉 API 工具
  • SendGrid 邮件工具
  • 阿里云 OSS 工具

Worker 类型工具​

适用于后台任务处理：

{
  "executionType": "worker",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "queueConfig": {
          "type": "object",
          "properties": {
            "maxConcurrency": {"type": "number"},
            "priority": {"type": "string"}
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "batchSize": {"type": "number", "default": 100},
        "processingMode": {
          "type": "string", 
          "enum": ["parallel", "sequential"],
          "default": "parallel"
        }
      }
    }
  }
}

示例系统工具：

  • 数据清洗工具
  • 文件转换工具
  • 批量处理工具

MCP 类型工具​

适用于 Model Context Protocol 集成：

{
  "executionType": "mcp",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "serverConfig": {
          "type": "object",
          "properties": {
            "command": {"type": "string"},
            "args": {"type": "array"},
            "env": {"type": "object"}
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "model": {
          "type": "string",
          "enum": ["gpt-4", "claude-3", "gemini-pro"],
          "default": "gpt-4"
        },
        "temperature": {
          "type": "number",
          "minimum": 0,
          "maximum": 2,
          "default": 0.7
        }
      }
    }
  }
}

示例系统工具：

  • GPT 对话工具
  • Claude 分析工具
  • 代码生成工具

Container 类型工具​

适用于容器化任务：

{
  "executionType": "container",
  "systemConfiguration": {
    "schema": {
      "properties": {
        "image": {"type": "string"},
        "registry": {
          "type": "object",
          "properties": {
            "url": {"type": "string"},
            "username": {"type": "string"},
            "password": {"type": "string", "sensitive": true}
          }
        },
        "resources": {
          "type": "object",
          "properties": {
            "memory": {"type": "string", "default": "512Mi"},
            "cpu": {"type": "string", "default": "0.5"}
          }
        }
      }
    }
  },
  "configuration": {
    "schema": {
      "properties": {
        "environment": {
          "type": "object",
          "title": "环境变量"
        },
        "command": {
          "type": "string",
          "title": "执行命令"
        }
      }
    }
  }
}

示例系统工具：

  • Python 脚本执行工具
  • 数据库备份工具
  • 图像处理工具

方法配置​

方法级系统配置​

每个方法也可以有自己的系统配置：

{
  "methods": [
    {
      "name": "发送邮件",
      "identifier": "send-email",
      "systemConfiguration": {
        "schema": {
          "properties": {
            "smtpConfig": {
              "type": "object",
              "properties": {
                "host": {"type": "string"},
                "port": {"type": "number"},
                "secure": {"type": "boolean"}
              }
            }
          }
        },
        "values": {
          "smtpConfig": {
            "host": "smtp.gmail.com",
            "port": 587,
            "secure": true
          }
        }
      },
      "configuration": {
        "schema": {
          "properties": {
            "template": {
              "type": "string",
              "enum": ["plain", "html"],
              "default": "html"
            },
            "priority": {
              "type": "string",
              "enum": ["low", "normal", "high"],
              "default": "normal"
            }
          }
        }
      }
    }
  ]
}

用户使用流程​

1. 浏览系统工具​

在工具市场中浏览可用的系统工具：

{
  "systemOperators": [
    {
      "id": "wechat-api",
      "name": "微信 API",
      "description": "提供微信公众号和小程序 API 接口",
      "category": "communication",
      "tags": ["微信", "API", "通信"],
      "version": "1.2.0",
      "status": "ACTIVE"
    }
  ]
}

2. 启用系统工具​

选择需要的系统工具并启用：

POST /api/operators/system/{operatorId}/enable

启用后会创建用户工具实例：

{
  "userOperator": {
    "id": "user-wechat-001",
    "systemOperatorId": "wechat-api",
    "userId": "user123",
    "status": "ENABLED",
    "configuration": {
      "values": {
        "timeout": 30000,
        "enableCache": true
      }
    }
  }
}

3. 配置用户参数​

填写用户可配置的参数：

{
  "configuration": {
    "values": {
      "timeout": 45000,
      "enableCache": false,
      "retryCount": 5
    }
  }
}

4. 在工作流中使用​

将启用的工具添加到工作流中：

{
  "nodes": [
    {
      "id": "node1",
      "type": "operator",
      "operatorId": "user-wechat-001",
      "methodId": "send-message",
      "config": {
        "inputs": {
          "message": "Hello World",
          "to": "user456"
        }
      }
    }
  ]
}

管理和维护​

系统配置管理​

管理员可以通过后台管理系统工具的系统配置：

编辑系统配置​

PUT /admin/operators/system/{operatorId}/system-configuration
Content-Type: application/json

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "newField": {
          "type": "string",
          "title": "新字段"
        }
      }
    },
    "values": {
      "newField": "default-value"
    }
  }
}

更新工具版本​

POST /admin/operators/system/{operatorId}/versions
Content-Type: application/json

{
  "version": "1.3.0",
  "changelog": "新增批量处理功能",
  "migration": {
    "required": false,
    "instructions": "自动升级，无需手动操作"
  }
}

用户配置管理​

用户可以管理自己启用的工具配置：

更新用户配置​

PUT /api/operators/custom/{userOperatorId}/configuration
Content-Type: application/json

{
  "configuration": {
    "values": {
      "timeout": 60000,
      "enableCache": true
    }
  }
}

方法配置​

PUT /api/operators/custom/{userOperatorId}/methods/{methodId}/configuration
Content-Type: application/json

{
  "configuration": {
    "values": {
      "template": "html",
      "priority": "high"
    }
  }
}

监控和诊断​

使用统计​

查看系统工具的使用情况：

{
  "statistics": {
    "totalUsers": 1250,
    "activeUsers": 890,
    "totalExecutions": 156780,
    "successRate": 98.5,
    "avgResponseTime": 450
  }
}

性能监控​

{
  "performance": {
    "qps": 125.5,
    "errorRate": 0.02,
    "p95ResponseTime": 800,
    "p99ResponseTime": 1200
  }
}

错误诊断​

{
  "errors": [
    {
      "type": "configuration_error",
      "message": "Invalid API key format",
      "count": 15,
      "lastOccurred": "2024-01-15T10:30:00Z"
    }
  ]
}

最佳实践​

系统工具设计原则​

  1. 配置分离：系统配置和用户配置清晰分离
  2. 安全优先：敏感信息仅在系统配置中
  3. 向后兼容：升级时保持接口兼容性
  4. 文档完整：提供详细的使用文档

用户使用建议​

  1. 合理配置：根据实际需求调整参数
  2. 定期更新：及时升级到新版本
  3. 监控使用：关注工具执行情况
  4. 备份配置：重要配置及时备份

管理员维护指南​

  1. 版本管理：遵循语义化版本号规范
  2. 变更通知：重大变更提前通知用户
  3. 性能优化：定期优化工具性能
  4. 安全审计：定期检查安全配置

常见问题​

Q: 系统工具和自定义工具有什么区别？​

A: 系统工具是平台预配置的，用户只能配置部分参数；自定义工具是用户完全自主创建和管理的。

Q: 可以修改系统工具的系统配置吗？​

A: 不可以，系统配置只有平台管理员可以修改，用户只能修改用户配置部分。

Q: 系统工具升级会影响现有工作流吗？​

A: 通常不会，系统工具升级会保持向后兼容性。如有破坏性变更，会提前通知并提供迁移指南。

Q: 如何知道系统工具有新版本？​

A: 系统会在工具列表中显示更新提示，您也可以在设置中开启版本更新通知。

相关文档​