云侧 API 插件：导入与代码注册

已有标准接口描述时，优先导入而不是逐个手工创建工具。当前界面提供“导入插件”和“使用代码注册插件”两个入口；两种方式最终创建的都是云侧 API 插件，不是新的插件类型。

图 1：新建插件右上角提供代码注册和导入入口。界面字段或按钮状态与旧图不一致时，以当前页面为准。

导入插件

新建插件弹窗右上角和资源库顶部都提供导入入口。当前导入面板包含两种方式：

• 本地文件：支持 .json、.yaml、.yml，用于 OpenAPI、Swagger 或 Postman Collection。
• URL 和原始数据：可输入 cURL、Swagger/OpenAPI 原始内容，或指向这些内容的 URL。

如果“下一步”按钮处于禁用状态，表示当前页面状态、文件解析或所在版本尚未满足导入条件；不要把关闭弹窗当作导入成功。只有资源列表出现新插件，或页面明确提示创建成功，才算完成。

导入前检查

1. 接口定义来自可信来源，版本与真实服务一致。
2. servers 或基础 URL 指向预期环境，没有携带内网测试地址。
3. 路径、方法、Content-Type、认证方式和响应 Schema 完整。
4. 示例中不包含 Token、Cookie、手机号、邮箱或真实业务数据。
5. 不导入管理后台、删除全量数据等不应交给模型的高风险接口。

导入后检查

• 插件名称、说明和头像符合当前工作空间规范。
• 每个 operation 已生成正确的工具名称和描述。
• Path、Query、Header、Body 参数位置与真实接口一致。
• 必填项、枚举、数组、对象和嵌套字段没有被错误转换。
• 输出字段能够覆盖真实成功响应和错误响应。
• 配置服务鉴权后逐个执行真实试运行。

使用代码注册插件

“使用代码注册插件”入口提供两个编辑区：

• ai_plugin：填写插件元数据 JSON。
• openapi：填写 OpenAPI YAML。

这适合需要精确维护注册清单、且已经理解插件元数据与 OpenAPI 契约的开发者。提交前先在本地校验 JSON/YAML 语法和 OpenAPI 结构。

当前实现中，代码注册入口是否真正完成持久化，要以确认后的成功反馈和资源列表新增结果为准。没有成功提示或列表新增时，不要继续编排调用方。

何时改用其他方式

• 只有少量 API 且没有规范文件：使用基于已有 API 创建。
• 需要写适配、聚合或转换逻辑：使用Cloud IDE。
• 工具来自 MCP Server：创建MCP 插件，不要把 MCP 清单转换成普通 HTTP 工具维护。