导入技能包¶
导入技能 ZIP 包及其中的静态文件，并创建版本 1 的活动技能。可以用表单字段覆盖包内清单的名称、描述、分类和标签。
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/skills/import
调用前准备¶
先检查技能包确认包格式通过校验。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和本地技能包文件。
该接口的请求类型为 multipart/form-data；示例使用 curl -F 提交文件，不要添加 Content-Type: application/json。
路径参数¶
参数 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
是 |
当前工作区 ID。 |
表单字段¶
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/skills/import" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-F "file=@./skill-package.zip" \
-F 'tags=["摘要","文本处理"]'
参数 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
file |
是 |
|
|
string |
否 |
覆盖 |
|
string |
否 |
覆盖 |
|
string |
否 |
覆盖 |
|
string |
否 |
JSON 字符串数组，例如 |
成功响应¶
{
"code": 0,
"data": {
"skill": {
"id": "skill_01",
"workspace_id": "ws_01",
"name": "摘要技能",
"description": "总结输入内容。",
"status": "active",
"source_type": "custom",
"source_ref": "skill_package:sha256:abc123",
"version": 1
},
"files": [
{
"file_path": "SKILL.md",
"file_kind": "manifest",
"media_type": "text/markdown",
"sha256": "abc123",
"size_bytes": 512
}
],
"warnings": []
}
}
成功时返回 201。静态文件随导入结果保存；后续技能版本更新不会使这些文件自动回到历史版本。
响应字段如下。
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
成功时为 |
字段 |
类型 |
说明 |
|---|---|---|
|
object |
新建的技能； |
|
array |
已保存的静态文件元数据。 |
|
array of string |
非阻塞导入警告。 |
下面表格展开响应示例中的 skill 数据；每一行是该对象或数组项的一个字段。
字段 |
类型 |
说明 |
|---|---|---|
|
string |
指向导入压缩包摘要的技能包来源引用。 |
错误响应¶
{
"code": 2,
"message": "<错误信息>",
"details": {
"reason": "SKILL_PACKAGE_INVALID_ZIP"
}
}
常见 HTTP 错误
字段 |
类型 |
说明 |
|---|---|---|
|
|
**常见原因：**包格式、清单、表单 |
|
|
**常见原因：**压缩包或解压后的内容超出大小限制。**建议操作：**缩小包体或移除不需要的文件。 |
|
|
**常见原因：**缺少有效身份凭据。**建议操作：**检查 API Key。 |
|
|
**常见原因：**当前身份没有导入技能包的权限。**建议操作：**检查工作区授权。 |
|
|
**常见原因：**技能包存储或授权依赖暂不可用。**建议操作：**稍后重试。 |