为自定义 Skill 上传新版本 ZIP 包,版本号由服务端递增。
接口
POST /api/v1/skills/{skill_id}/versions
使用 multipart/form-data 为自定义 Skill 上传新版本。版本号由服务端在 latest_version 基础上递增,例如 1.0 递增为 1.1,不能指定。
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| skill_id | Path | string | 是 | 主账号和工作空间下的自定义 Skill ID |
| file | Form | file | 是 | 新版本 ZIP 包,要求同创建 Skill |
| display_name | Form | string | 否 | 更新 Skill 展示名称;不传或为空白时取新包 SKILL.md 的 name |
| display_description | Form | string | 否 | 更新 Skill 展示描述;不传或为空白时取新包 SKILL.md 的 description |
业务规则
- 仅自定义 Skill 可以创建版本。
- Skill 正在安全扫描(
checking)时不能创建新版本,需等待扫描结束;rejected状态可以重新上传。 - 新包 SKILL.md 的
name不能与官方 Skill 或当前空间的其他自定义 Skill 重名。 - 创建成功后,Skill 的
latest_version指向新版本,旧版本保留。 - 请求中的
display_name和display_description用于更新 Skill 展示信息。
响应
返回新版本的 SkillVersionDTO。
| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 版本记录唯一标识 |
| type | string | 固定为 skill_version |
| skill_id | string | 所属 Skill ID |
| display_name | string | 该版本的展示名称 |
| display_description | string | 该版本的展示描述 |
| version | string | 版本号 |
| status | string | 版本状态 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |
| additional_properties | object / null | 扩展属性 |
示例
错误
| HTTP 状态码 | error_code | 说明 |
|---|---|---|
| 401 | WORKSPACE_ID_ILLEGAL | 身份信息缺失或无效 |
| 400 | SKILL_ID_IS_NULL | skill_id 为空白 |
| 400 | SKILL_FILE_IS_NULL | 未上传 file 或文件为空 |
| 400 | SKILL_FILE_FORMATER_ERROR | 文件扩展名不是 .zip,或文件头不是 ZIP 格式 |
| 400 | SKILL_PACKAGE_TOO_LARGE | ZIP 包超过 50MB |
| 400 | INVALID_PARAMETER | multipart 请求格式错误 |
| 500 | SKILL_NOT_EXIST | Skill 不存在、已删除或无权访问 |
| 500 | SKILL_VERSION_NOT_EXIST | 保存成功但读取新版本记录失败 |
| 500 | SKILL_UPDATE_SECURITY_ERROR | Skill 正在安全扫描中 |
| 500 | SKILL_NAME_OFFICIAL_DUPLICATE | 新包 name 与官方 Skill 重名 |
| 500 | SKILL_NAME_CUSTOMER_DUPLICATE | 新包 name 与当前空间的其他自定义 Skill 重名 |
| 500 | SKILL_UPDATE_LOCK_ERROR | 同一 Skill 的并发创建版本冲突 |