系统工具

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

概念介绍

什么是系统工具

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

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

系统工具 vs 自定义工具

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

已发布的内置工具

当前版本共发布 14 个内置（系统）工具，全部运行于 worker 运行时。下表列出每个工具的标识符、显示名称、类别与默认方法（来源于平台目录）。

标识符	名称	类别	默认方法
`email`	邮件发送器	utilities	`default`
`document-reader`	文档阅读器	text	`default`
`multimodal-embedding`	多模态向量化	embedding	`default`
`js-executor`	JavaScript 执行器	code	`default`
`sql-template`	SQL 模板操作符	database	`default`
`generic-api`	通用 API 调用	utilities	`default`
`rest`	REST 客户端	utilities	`default`
`wechat`	微信公众号图文发布	utilities	`default`
`transform`	数据转换	utilities	`default`
`default-data-source`	默认数据源	utilities	`default`
`postgresql-schema`	PostgreSQL 表结构读取	database	`default`
`mysql-schema`	MySQL 表结构读取	database	`default`
`global-variable`	全局变量操作器	variable	`get`
`storage`	存储操作器	storage	`list`

备注

global-variable（方法：get / set / append / delete / clear / list）与 storage（方法：list / upload / getInfo）为多方法工具；其余工具均只提供单一的 default 方法。

配置结构

双层配置设计

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

{
  "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 类型工具（规划中 — 未发布）

当前版本未提供

当前版本未发布任何 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 类型工具（规划中 / 企业版 — 未发布）

当前版本未提供

当前版本未发布任何 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/{operatorId}/enable
Content-Type: application/json

{
  "configuration": { /* 用户配置值 */ }
}

启用后会创建用户工具实例（绑定到当前空间的已启用记录）：

{
  "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"
        }
      }
    }
  ]
}

管理和维护

系统配置管理

平台管理员负责管理内置工具的系统级配置（包括隐藏的 systemConfiguration 及其敏感值）。这些管理操作属于平台内部能力，不属于面向空间的公开 API。

用户配置管理

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

更新用户配置

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

{
  "configuration": { /* 用户配置值 */ }
}

方法配置

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

{
  "configuration": { /* 方法配置值 */ }
}

监控和诊断

使用统计

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

{
  "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"
    }
  ]
}

最佳实践

系统工具设计原则

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

用户使用建议

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

管理员维护指南

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

常见问题

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

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

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

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

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

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

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

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

概念介绍​

什么是系统工具​

系统工具 vs 自定义工具​

已发布的内置工具​

配置结构​

双层配置设计​

配置类型说明​

systemConfiguration（系统配置）​

configuration（用户配置）​

工具类型​

API 类型工具​

Worker 类型工具​

MCP 类型工具（规划中 — 未发布）​

Container 类型工具（规划中 / 企业版 — 未发布）​

方法配置​

方法级系统配置​

用户使用流程​

1. 浏览系统工具​

2. 启用系统工具​

3. 配置用户参数​

4. 在工作流中使用​

管理和维护​

系统配置管理​

用户配置管理​

更新用户配置​

方法配置​

监控和诊断​

使用统计​

性能监控​

错误诊断​

最佳实践​

系统工具设计原则​

用户使用建议​

管理员维护指南​

常见问题​

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

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

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

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

相关文档​

概念介绍

什么是系统工具

系统工具 vs 自定义工具

已发布的内置工具

配置结构

双层配置设计

配置类型说明

systemConfiguration（系统配置）

configuration（用户配置）

工具类型

API 类型工具

Worker 类型工具

MCP 类型工具（规划中 — 未发布）

Container 类型工具（规划中 / 企业版 — 未发布）

方法配置

方法级系统配置

用户使用流程

1. 浏览系统工具

2. 启用系统工具

3. 配置用户参数

4. 在工作流中使用

管理和维护

系统配置管理

用户配置管理

更新用户配置

方法配置

监控和诊断

使用统计

性能监控

错误诊断

最佳实践

系统工具设计原则

用户使用建议

管理员维护指南

常见问题

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

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

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

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

相关文档