跳到主要内容

配置算子

算子契约包含四个用户可见部分：标识、执行、方法和授权。只配置当前算子目录实际支持的 Runtime 类型。

标识​

使用稳定、唯一的 Identifier 和动作明确的名称。

字段建议
名称只描述一个操作，例如“读取客户档案”
Identifier稳定机器名；被引用后不要随意修改
描述说明何时使用，以及重要的不适用场景
分类/标签便于在目录中可靠发现
状态只有启用的算子可供调用方使用

执行方式​

内置 Worker 算子​

内置算子在 GeniSpace Worker 中执行。用户从目录选择并配置，Runtime 实现由平台管理。不要为了修改代码而复制内置定义；应配置它开放的方法输入、连接和权限。

REST API 算子​

REST API 算子用于调用外部 HTTPS 服务，需要配置：

  • Base/Server URL 与方法路径；
  • HTTP 方法和 Content Type；
  • Header、Path、Query 和 Body 映射；
  • 用于认证的连接或 Secret 引用；
  • 超时和安全重试策略；
  • 预期成功状态与输出映射。

部署相关值使用环境变量或 ConfigMap 引用。不要把 Access Token 写入描述、样例值或导出的工作流 JSON。

数据源操作​

数据源操作通过已配置连接执行。凭据归连接管理，操作负责类型化参数和预期输出。请使用实际运行工作流的空间与角色测试访问权限。

方法​

一个算子可以开放一个或多个方法。每个方法应对应一项完整操作，并定义：

{
  "name": "getCustomer",
  "description": "按平台客户 ID 读取一位客户",
  "inputSchema": {
    "type": "object",
    "required": ["customerId"],
    "properties": {
      "customerId": {
        "type": "string",
        "description": "稳定客户 ID"
      }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["found"],
    "properties": {
      "found": { "type": "boolean" },
      "customer": { "type": ["object", "null"] }
    }
  }
}

优先使用编辑器生成的表单。支持 JSON Schema 编辑时，也应保持与界面校验能力一致。

输入 Schema 规则​

  • 方法输入根节点使用 object。
  • 字段放在 properties 下，真正必填的字段写入 required。
  • 一致使用 string、number、integer、boolean、array 或 object。
  • 封闭取值集合使用 enum。
  • 数组定义 items，嵌套对象定义 properties。
  • 有意区分未传、null、空字符串和空数组。
  • 不允许未知输入时设置 additionalProperties: false。
  • 每个业务字段都应有对工作流作者和智能体有意义的说明。

除非远端 API 的确是动态契约，否则不要只定义一个无类型的 payload 对象。

输出 Schema 规则​

返回下游节点或智能体可使用的事实。稳健结果通常能区分：

  • 成功并有数据；
  • 成功但无匹配；
  • 参数校验失败；
  • 授权失败；
  • 远端或 Runtime 失败。

不要只返回“操作完成”。适用时应提供稳定 ID、影响记录数、状态和安全错误信息，并排除 Secret 及调用方无权查看的字段。

映射​

在 WorkflowStudio 中，把上游输出路径映射到每项输入。编辑器会校验类型兼容性，但无法判断业务含义。需要测试 null、空数组、嵌套对象、日期和数值转换。

REST API 算子应把传输细节与业务输出分开，例如把远端响应映射成稳定输出对象，不要让每个工作流理解供应商专属信封。

超时与重试​

  • 算子超时应小于父任务超时。
  • 只有操作安全时，才重试临时网络和 5xx 错误。
  • 没有幂等键时，不要自动重试非幂等写操作。
  • 参数和授权错误应直接结束。
  • 提供足够诊断元数据，但不暴露凭据或机密负载。

授权​

启用算子不会绕过访问控制。调用方必须具备算子、连接、数据集/数据源和目标空间资源的权限。智能体工具目录还会按智能体形态、Chat 模式、应用本地 Provider 和权限进一步筛选。

验证清单​

  1. Identifier 唯一且稳定。
  2. 输入输出 Schema 明确。
  3. 认证使用托管连接或 Secret 引用。
  4. 已测试成功、空结果、参数错误、无权限、超时和远端失败。
  5. 写操作重试具有幂等性。
  6. 日志和结果不暴露敏感值。
  7. 破坏性契约变更前已经检查现有工作流和智能体。

相关指南​