查询技能列表

列出当前工作区技能和可读取的系统默认技能。系统技能的 workspace_id 为 system，应视为只读资源。

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

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求参数

调用示例

curl "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/skills?status=active&limit=20&offset=0" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

参数说明

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	当前工作区 ID。

查询参数

参数	类型	是否必填	说明
status	string	否	按状态、来源类型、分类或阶段筛选。
source_type	string	否	按状态、来源类型、分类或阶段筛选。
category	string	否	按状态、来源类型、分类或阶段筛选。
phase	string	否	按状态、来源类型、分类或阶段筛选。
query	string	否	按技能文本搜索。
tags	string	否	标签筛选值。可重复传入，例如 tags=文本&tags=摘要。
limit	integer	否	每页数量。默认 50，最大 200。
offset	integer	否	起始偏移量；负数按 0 处理。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "skill_01",
        "workspace_id": "ws_01",
        "name": "摘要技能",
        "description": "总结输入内容。",
        "status": "active",
        "source_type": "custom",
        "version": 2
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

字段说明

成功时返回 200。

响应字段如下。

本文中，字段路径中的 [] 表示数组中的每一项。例如，items[].name 表示 items 数组中每一项的 name 字段。

通用字段

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

基本信息

字段	类型	说明
items	array	当前页的技能定义。
total	integer	匹配技能总数。
limit	integer	本页请求的最大技能数。
offset	integer	本页第一条技能的零基偏移量。

列表项

下面表格展开响应示例中的 items 数据；每一行是该对象或数组项的一个字段。

字段	类型	说明
id	string	技能 ID。
workspace_id	string	技能所属工作区；系统技能为 system。
name	string	名称、状态和来源类型。
display_name	string	面向界面展示的名称；有值时返回。
display_description	string	面向界面展示的说明；有值时返回。
display_tags	array of string	面向界面展示的标签；有值时返回。
status	string	名称、状态和来源类型。
source_type	string	名称、状态和来源类型。
description	string	技能说明；未设置时不返回。
source_ref	string	来源引用；未设置时不返回。
category	string	技能分类；未设置时不返回。
tags	array of string	技能标签；未设置时不返回。
phase	string	技能阶段；未设置时不返回。
routing_summary	object	路由摘要；未设置时不返回。
instruction	object	技能指令。
requirements	object	技能依赖要求；未设置时不返回。
version	integer	当前版本。
metadata	object	扩展元数据；未设置时不返回。
created_by	string	创建者标识；未设置时不返回。
updated_by	string	最近更新者标识；未设置时不返回。
created_at	string	创建时间，采用 RFC 3339 格式。
updated_at	string	最近更新时间，采用 RFC 3339 格式。

错误响应

响应示例

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

字段说明

常见 HTTP 错误

通用字段

字段	类型	说明
400	2（INVALID_ARGUMENT）	**常见原因：**工作区或筛选参数无效。**建议操作：**检查路径和查询参数。
401	6（UNAUTHENTICATED）	**常见原因：**缺少有效身份凭据。**建议操作：**检查 API Key。
403	5（PERMISSION_DENIED）	**常见原因：**当前身份没有读取工作区技能的权限。**建议操作：**检查工作区授权。
503	15（UNAVAILABLE）	**常见原因：**技能服务或授权依赖暂不可用。**建议操作：**稍后重试。

后续操作

保存目标技能的标识，再查询技能详情。

最后更新于 2026 年 9 月 28 日