更新技能

部分更新当前工作区中的技能。未提供的字段保持原值；除仅更新标签外，更新会创建新的技能版本并将其设为当前版本。

PATCH https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/skills/{skill_id}

调用前准备

先查询技能详情确认要更新的技能。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和技能 ID。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递。

• $SKILL_ID：要更新的技能 ID。

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。
skill_id	string	是	要更新的技能 ID。

查询参数

参数	类型	是否必填	说明
skill_workspace_id	string	否	技能所属工作区；仅可为当前工作区或 system。系统技能为只读，更新会被拒绝。

请求体

请求体中的字段均为可选；未提供的字段保持原值。

字段	类型	是否必填	说明
name	string	否	技能基本定义。状态可为 draft、active、disabled 或 archived。
description	string	否	技能基本定义。状态可为 draft、active、disabled 或 archived。
status	string	否	技能基本定义。状态可为 draft、active、disabled 或 archived。
source_type	string	否	技能基本定义。状态可为 draft、active、disabled 或 archived。
source_ref	string	否	技能基本定义。状态可为 draft、active、disabled 或 archived。
category	string	否	分类和展示信息。提供 tags 时会替换现有标签；仅更新标签不会创建新版本。
icon_ref	string	否	分类和展示信息。提供 tags 时会替换现有标签；仅更新标签不会创建新版本。
tags	string（字符串数组）	否	分类和展示信息。提供 tags 时会替换现有标签；仅更新标签不会创建新版本。
phase	string	否	分类和展示信息。提供 tags 时会替换现有标签；仅更新标签不会创建新版本。
pipeline_ref	string	否	分类和展示信息。提供 tags 时会替换现有标签；仅更新标签不会创建新版本。
routing_summary	object	否	路由摘要、指令和依赖要求。
instruction	object	否	路由摘要、指令和依赖要求。
requirements	object	否	路由摘要、指令和依赖要求。
parameters_schema	object	否	输入 Schema 和输出约定。
output_contract	object	否	输入 Schema 和输出约定。
market_metadata	object	否	市场元数据、标签、注释和扩展元数据。
labels	object	否	市场元数据、标签、注释和扩展元数据。
annotations	object	否	市场元数据、标签、注释和扩展元数据。
metadata	object	否	市场元数据、标签、注释和扩展元数据。
change_summary	string	否	新版本的变更说明。

更新后的技能仍必须保留指令正文或路由摘要，并满足技能依赖引用的校验规则。

请求示例

curl -X PATCH "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/skills/$SKILL_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "更新后的说明",
    "change_summary": "补充输出约定"
  }'

成功响应

成功时返回 200 和更新后的技能。

{
  "code": 0,
  "data": {
    "id": "skill_01",
    "workspace_id": "ws_01",
    "name": "摘要技能",
    "description": "更新后的说明",
    "status": "active",
    "source_type": "custom",
    "instruction": {
      "body": "总结用户提供的内容。"
    },
    "version": 3,
    "updated_at": "2026-01-03T10:00:00Z"
  }
}

响应字段如下。

字段	类型	说明
code	integer	成功时为 0。
data.id	string	技能 ID 和所属工作区。
data.workspace_id	string	技能 ID 和所属工作区。
data.name	string	更新后的基本定义。
data.description	string	更新后的基本定义。
data.status	string	更新后的基本定义。
data.instruction	object	更新后的指令、路由摘要和依赖要求。
data.routing_summary	object	更新后的指令、路由摘要和依赖要求。
data.requirements	object	更新后的指令、路由摘要和依赖要求。
data.version	integer	当前版本；仅更新标签时保持不变。
data.updated_at	string	最近更新时间，使用 RFC 3339 格式。

错误响应

{
  "code": 2,
  "message": "<错误信息>"
}

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	2（INVALID_ARGUMENT）	请求字段、依赖引用或更新后的技能定义无效。	检查字段值、指令或路由摘要，以及依赖资源。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。	检查 API Key。
403	5（PERMISSION_DENIED）	当前身份没有更新技能的权限。	检查工作区授权。
403	7（FORBIDDEN）	指定系统技能为只读。	不要修改系统技能；在当前工作区创建或更新自己的技能。
404	3（NOT_FOUND）	指定工作区中不存在该技能。	检查技能 ID 和 skill_workspace_id。
503	15（UNAVAILABLE）	技能服务或授权依赖暂不可用。	稍后重试。

后续操作

用同一资源标识查询技能详情确认更新结果。

最后更新于 2026 年 8 月 22 日