可通过批量导入机制将企业内部Swagger格式API文档快速转化为WorkBuddy可识别调用的API技能，支持管理后台上传、CLI离线注入及API网关动态同步三种方式。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您拥有企业内部已发布的Swagger格式API文档，但需将其快速转化为WorkBuddy可识别并调用的API技能，可通过批量导入机制实现自动化注册与能力封装。以下是完成此任务的具体操作路径：
一、准备标准化Swagger文档源
WorkBuddy要求导入的Swagger文档必须为符合OpenAPI 3.0规范的JSON或YAML文件，且需确保接口路径、参数定义、响应结构完整可解析。文档中若存在未声明的$ref引用或外部链接，将导致导入中断。
1、确认Swagger文档已通过swagger-cli validate或在线编辑器校验通过，无语法错误及schema缺失。
2、检查所有paths下的HTTP方法是否明确标注，例如get、post等，禁止使用通配符或动态占位符替代真实动词。
3、确保每个接口的requestBody和responses中均包含content.application/json.schema定义，否则WorkBuddy无法推导参数类型与结构。
4、将文档保存为单文件（如internal-api-openapi.json），避免拆分为多文件引用结构。
二、通过WorkBuddy管理后台执行批量导入
该方式适用于具备管理员权限的用户，支持一次上传多个Swagger文件，并自动映射为独立技能节点，无需编码干预。
1、登录WorkBuddy管理后台，进入「技能中心」→「API技能库」页面。
2、点击右上角「批量导入」按钮，弹出文件选择窗口。
3、拖入或选取已准备好的Swagger JSON/YAML文件，单次最多支持10个文件同时上传。
4、勾选「启用自动命名」选项，系统将基于info.title字段生成技能名称；若取消勾选，则需手动为每个文件指定唯一技能标识符。
5、点击「开始解析」，系统在后台校验接口路径冲突、参数重复及认证方式兼容性，耗时通常不超过15秒。
6、解析成功后，页面显示待确认技能列表，每项右侧显示“已映射参数：7”、“含鉴权头：Bearer”等关键摘要信息。
7、勾选全部条目，点击「确认注册」，技能即刻进入「已启用」状态，可供工作流编排调用。
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
三、使用CLI工具离线注入API技能
适用于CI/CD流水线集成场景，通过命令行直接将Swagger文档注入WorkBuddy实例，全程无界面依赖，适合DevOps自动化部署。
1、在本地安装WorkBuddy CLI工具，执行npm install -g workbuddy-cli，确保版本≥2.8.0。
2、配置环境变量WB_API_URL指向目标WorkBuddy服务地址，WB_API_TOKEN填入具有skill:write权限的令牌。
3、执行导入命令：wb skill import --file ./swaggers/erp-v2.yaml --group "企业资源计划" --tag "internal,prod"。
4、命令输出中出现“Registered 12 endpoints as skills under group ‘企业资源计划’”即表示成功。
5、若返回conflict: /api/inventory/stock [POST]，说明该路径已在技能库中存在，需先执行wb skill delete --path "/api/inventory/stock" --method POST再重试。
四、对接API网关动态同步Swagger元数据
当企业采用API网关统一托管后端服务时，可配置WorkBuddy定时拉取网关暴露的Swagger端点，实现API技能与业务系统变更实时联动。
1、在API网关控制台开启/v1/apis/swagger聚合接口，确保其返回内容为标准OpenAPI 3.0文档。
2、进入WorkBuddy管理后台「系统设置」→「外部集成」→「API网关同步」。
3、填写网关Swagger地址，例如https://gateway.internal.company.com/v1/apis/swagger?env=prod。
4、设置同步周期为每6小时自动刷新一次，并启用「删除已下线接口对应技能」开关。
5、点击「测试连接」，确认返回HTTP 200且JSON结构有效后，点击「启用同步」。
6、首次同步完成后，可在「API技能库」中看到新增技能名称末尾标记“[sync:gateway]”标识。
