Skip to main content

创建版本

为自定义 Skill 上传新版本 ZIP 包,版本号由服务端递增。

接口

POST /api/v1/skills/{skill_id}/versions 使用 multipart/form-data 为自定义 Skill 上传新版本。版本号由服务端在 latest_version 基础上递增,例如 1.0 递增为 1.1,不能指定。

请求参数

参数位置类型必填说明
skill_idPathstring是主账号和工作空间下的自定义 Skill ID
fileFormfile是新版本 ZIP 包,要求同创建 Skill
display_nameFormstring否更新 Skill 展示名称;不传或为空白时取新包 SKILL.md 的 name
display_descriptionFormstring否更新 Skill 展示描述;不传或为空白时取新包 SKILL.md 的 description

业务规则

  • 仅自定义 Skill 可以创建版本。
  • Skill 正在安全扫描(checking)时不能创建新版本,需等待扫描结束;rejected 状态可以重新上传。
  • 新包 SKILL.md 的 name 不能与官方 Skill 或当前空间的其他自定义 Skill 重名。
  • 创建成功后,Skill 的 latest_version 指向新版本,旧版本保留。
  • 请求中的 display_name 和 display_description 用于更新 Skill 展示信息。

响应

返回新版本的 SkillVersionDTO。
字段类型说明
idstring版本记录唯一标识
typestring固定为 skill_version
skill_idstring所属 Skill ID
display_namestring该版本的展示名称
display_descriptionstring该版本的展示描述
versionstring版本号
statusstring版本状态
created_atstring创建时间
updated_atstring更新时间
additional_propertiesobject / null扩展属性

示例

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/skills/skill_abc123/versions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -F "file=@./pdf-skill-v2.zip"
{
  "success": true,
  "error_code": null,
  "error_msg": null,
  "data": {
    "id": "skillver_xxxxxxxxxxxxxxxxxxxxxx",
    "type": "skill_version",
    "skill_id": "skill_abc123",
    "display_name": "My Custom Skill",
    "display_description": "从 SKILL.md 解析的描述",
    "version": "1.1",
    "status": "checking",
    "created_at": "2026-06-15T08:23:11Z",
    "updated_at": "2026-06-15T08:23:11Z",
    "additional_properties": null
  },
  "request_id": "15a89d4c-f142-4e00-a9f7-b088442417c9"
}

错误

HTTP 状态码error_code说明
401WORKSPACE_ID_ILLEGAL身份信息缺失或无效
400SKILL_ID_IS_NULLskill_id 为空白
400SKILL_FILE_IS_NULL未上传 file 或文件为空
400SKILL_FILE_FORMATER_ERROR文件扩展名不是 .zip,或文件头不是 ZIP 格式
400SKILL_PACKAGE_TOO_LARGEZIP 包超过 50MB
400INVALID_PARAMETERmultipart 请求格式错误
500SKILL_NOT_EXISTSkill 不存在、已删除或无权访问
500SKILL_VERSION_NOT_EXIST保存成功但读取新版本记录失败
500SKILL_UPDATE_SECURITY_ERRORSkill 正在安全扫描中
500SKILL_NAME_OFFICIAL_DUPLICATE新包 name 与官方 Skill 重名
500SKILL_NAME_CUSTOMER_DUPLICATE新包 name 与当前空间的其他自定义 Skill 重名
500SKILL_UPDATE_LOCK_ERROR同一 Skill 的并发创建版本冲突
完整错误码见Skill API 错误码。