更新技能

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

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

调用前准备

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

路径参数

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

查询参数

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

请求体

调用示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/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": "补充输出约定"
  }'

参数说明

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

参数	类型	是否必填	说明
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	array of 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	否	新版本的变更说明。

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

成功响应

响应示例

{
  "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"
  }
}

字段说明

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

响应字段如下。

通用字段

字段	类型	说明
code	integer	成功时为 0。

基本信息

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

错误响应

响应示例

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

字段说明

常见 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 年 9 月 11 日