算子
算子是一项可复用、由 Schema 定义的操作。它接收类型明确的输入，完成一个操作，并返回结构化结果。算子可作为工作流节点使用；经过显式开放和授权后，也可以成为智能体工具。
算子、工具与智能体节点
| 概念 | 主要用途 | 执行控制方 |
|---|---|---|
| 算子 | 确定性、可复用的业务或数据操作 | 工作流运行时，或已授权的智能体工具 |
| 智能体工具 | 以名称、描述和输入 Schema 提供给模型的能力 | 智能体运行时及其授权策略 |
| 智能体节点 | 使用任务型智能体进行语言理解或结构化生成 | 工作流运行时 |
| MCP 工具 | 由 MCP Server 提供的外部能力 | 智能体运行时、MCP 连接与空间授权 |
算子可以成为智能体工具，但两个术语并不等价。智能体只能获得与其类型、当前模式、空间和应用相匹配的工具。
当前执行类型
内置算子
内置算子在 GeniSpace Worker 中执行，覆盖常用平台能力，包括：
- 数据集查询、计数、向量搜索和全文搜索；
- 数据转换与通用工具；
- 文档和媒体处理；
- 数据库 Schema 与 SQL 相关工具；
- HTTP、消息和平台支持的集成。
当前环境实际启用的能力以算子目录为准。
REST API 算子
自定义 REST API 算子用于调用外部 HTTPS 接口。可以定义方法、URL、请求头、输入 Schema、输出 Schema、超时和重试策略。密钥应放在已授权的连接或环境配置中，不要粘贴到工作流或提示词里。
OpenAPI 导入可以从已有服务契约创建算子定义。激活前必须检查生成的 Schema、鉴权方式和 Server URL。
数据源操作
数据源操作使用已经配置的连接查询或更新外部业务系统。连接权限和当前空间共同决定可用范围。
算子生命周期
- 查找或创建——选择内置算子、创建 REST API 算子，或导入 OpenAPI。
- 定义契约——明确字段名、说明、必填项、类型和输出结构。
- 配置授权——连接凭据，只授予所需空间权限。
- 测试——覆盖成功、空结果、参数错误、远端错误和超时。
- 激活——只有启用的算子才会进入相关工作流或智能体目录。
- 使用与监控——查看结构化输出、执行时长、重试和错误详情。
- 谨慎更新——字段类型或必填输入的变更会影响所有引用它的工作流和智能体。
在工作流中使用算子
- 在 WorkflowStudio 中打开任务。
- 从工具、数据集或数据源添加节点。
- 将上游输出映射到算子的类型化输入。
- 配置默认值、环境变量、超时和错误处理。
- 把结构化输出连接到下游节点。
- 保存后使用立即运行和代表性输入测试，再启用触发器。
执行面板会显示节点输入、结果、时长、重试和错误。测试数据和日志中不要包含不必要的敏感值。
向智能体开放算子
智能体能够使用算子，不仅取决于算子记录。运行时会根据智能体形态、Chat 模式、应用本地 Provider、空间授权和配置构建工具目录。为了让模型可靠选择工具：
- 使用唯一、动作明确的名称；
- 说明适用和不适用场景；
- 保持必填输入精简且类型明确；
- 返回结构化事实，不要只返回展示文案；
- 区分精确查询/计数、全文搜索和向量搜索；
- 明确表达空结果与错误；
- 破坏性或有重要后果的操作应要求确认。
Chat 会在执行过程中展示支持的结果。部分应用本地工具还会渲染专属插件卡片，例如 Workbench 草稿修改或 Assistant 创建资源。
数据集算子选择
| 用户需求 | 首选操作 |
|---|---|
| 精确字段条件、排序、分页或 ID | 结构化查询 |
| 匹配记录总数 | 计数 |
| 姓名、编号或字面短语 | 全文搜索 |
| 概念、能力、相似性或跨语言匹配 | 向量搜索 |
向量 Top-K 结果只是待评估候选，不代表每条都满足条件。输出字段和筛选条件必须使用数据集 Schema 中存在的字段名与类型。
设计检查清单
- 名称是否只表达一个操作？
- 输入和输出类型是否明确？
- 能否区分空结果与执行失败？
- 重试是否安全，特别是写操作？
- 凭据是否放在算子负载之外？
- 操作是否校验空间授权？
- 用户能否在不泄露敏感字段的情况下检查结果？
- 修改契约前是否检查了现有工作流和智能体？