Appearance
云侧 API 插件
云侧 API 插件连接已经存在的 HTTP/HTTPS 服务。它在新建弹窗中对应“云侧插件 > 基于已有服务创建”。历史文档中的“基于 API 创建”“通过 JSON/YAML 导入”和“使用代码注册”最终都生成这一类插件。
适用场景
- 已有稳定、可从 AIOS 访问的 HTTP/HTTPS API。
- 希望平台负责鉴权注入、工具契约、试运行、发布和调用治理。
- 多个工具共享同一服务基础地址和一组插件级鉴权配置。
如果需要编写业务逻辑而不是调用现有接口，使用 Cloud IDE 插件；工具来自 MCP Server 时，使用 MCP 插件。
三种录入方式
| 录入方式 | 适用条件 | 结果 |
|---|---|---|
| 表单创建 | API 数量少，或没有可导入的规范文件 | 先创建插件连接，再逐个创建 HTTP 工具 |
| 导入接口定义 | 已有 OpenAPI、Swagger、Postman、cURL、URL 或原始定义 | 解析插件信息和工具，导入后逐项校验 |
| 代码注册 | 已有 ai_plugin JSON 与 OpenAPI YAML | 按清单注册插件和工具 |
导入和代码注册只是减少录入工作，不能代替鉴权配置、参数核对和真实试运行。详细步骤见导入接口定义或使用代码注册。
方式一：通过表单创建
创建插件连接
- 在新建插件中填写名称、一句话介绍、描述和头像。
- 类型选择“云侧插件”。
- 插件工具创建方式选择“基于已有服务创建”。
- 私网连接按当前页面可选项配置；当前只开放“不使用私网连接”。
- 仅当插件确实承担外部知识源同步或检索职责时，开启“配置为知识库连接器”。
- 填写插件 URL。这里是多个工具共享的服务基础地址，不包含单个工具的完整路径。
- 根据服务要求添加 Header，并选择服务鉴权。
- 确认后进入插件详情。
创建 HTTP 工具
在插件详情点击“创建工具”，然后维护：
| 配置 | 说明 |
|---|---|
| 工具名称 | 使用稳定、可识别的标识；发布后避免随意改名 |
| 工具说明 | 告诉模型何时调用、完成什么动作、返回什么结果 |
| 请求方法 | 按真实接口选择 GET、POST、PUT、PATCH、DELETE 等方法 |
| 工具路径 | 相对于插件 URL 的路径；路径变量使用 {变量名}，并配置同名 Path 参数 |
| 输入参数 | 配置名称、描述、类型、传入位置、必填和启用状态 |
| 输出参数 | 配置实际返回字段、类型、嵌套结构和是否对模型可见 |
输入参数的传入位置包括 Body、Path、Query 和 Header。不要把固定密钥作为普通可见参数；密钥应放到插件服务鉴权中。
方式二：导入接口定义
当前导入入口支持本地文件、URL 和原始数据。历史文档明确的 OpenAPI、Swagger 和 Postman Collection 仍属于云侧 API 插件定义；当前页面还提供 cURL 等输入入口。
导入完成后重点核对：
- 基础 URL 和每个工具路径是否被正确拆分。
- 请求方法、Content-Type 和参数位置是否与真实接口一致。
- 必填、枚举、数组、对象和嵌套结构是否完整。
- 安全方案是否被正确转换为插件服务鉴权。
- 高风险管理接口是否应该删除或限制调用。
方式三：使用代码注册
代码注册需要同时维护：
ai_plugin：插件元数据 JSON。openapi：工具接口 OpenAPI YAML。
提交前应分别校验 JSON、YAML 和 OpenAPI 结构。只有页面明确提示成功并且资源列表出现新插件，才表示注册完成。
参数设计原则
- 名称保持稳定且语义明确，例如
taskId，不要使用data1。 - 描述同时说明业务含义、单位、格式和边界。
- 枚举值在说明中列出允许范围，并处理未知值。
- 可选参数不要伪装成必填；服务端默认值与工具默认值保持一致。
- 输出只暴露调用方真正需要的字段，敏感字段不要传给模型。
- 分页接口明确页码、游标、是否还有下一页等字段。
当前版本边界
- 当前私网连接只显示“不使用私网连接”，历史私网插件流程不能直接作为当前可用操作。
- 历史固定 IP、专线地域限制和旧服务域名不沿用；以当前部署网络和页面实际配置为准。
- 历史流式插件协议只有在当前工具配置明确开放对应选项时才可使用，不能仅因上游返回 SSE 就视为支持。
发布前验证
完成工具试运行，至少验证最小合法输入、缺少必填参数、鉴权失败、空结果、上游超时和非 2xx 响应。只有页面显示调试通过，并在实际智能体或工作流中完成调用，才能视为接入完成。