技能 API 参考

本页汇总工作区技能的查询、创建、导入、版本和运行接口。认证与工作区规则见 Product API 开始使用。

接口

方法	相对路径	用途
GET	/workspaces/{workspace_id}/skills	列出技能。
GET	/workspaces/{workspace_id}/skills/tags	列出技能标签及数量。
POST	/workspaces/{workspace_id}/skills	创建技能。
GET	/workspaces/{workspace_id}/skills/{skill_id}	读取技能详情。
PATCH	/workspaces/{workspace_id}/skills/{skill_id}	部分更新技能；将状态设为 archived 可归档。
POST	/workspaces/{workspace_id}/skills/import/inspect	检查技能包。
POST	/workspaces/{workspace_id}/skills/import	导入技能包。
GET	/workspaces/{workspace_id}/skills/{skill_id}/files	列出技能文件。
GET	/workspaces/{workspace_id}/skills/{skill_id}/files/content?path={path}	下载技能文件。
GET	/workspaces/{workspace_id}/skills/{skill_id}/versions	列出技能版本。
POST	/workspaces/{workspace_id}/skills/{skill_id}/versions/{version}/current	将指定版本设为当前版本。
POST	/workspaces/{workspace_id}/skills/{skill_id}/execute	运行技能。
POST	/workspaces/{workspace_id}/skills/polish/stream	流式润色技能草稿。

创建和更新字段

字段	类型	必需	默认值	说明
name	string	创建时是	—	技能名称。
description	string	否	—	任务目标和结果。
status	string	否	—	技能状态。归档使用 archived。
source_type、source_ref	string	否	—	技能来源。
category、tags、phase	string、array、string	否	—	分类和检索信息。
routing_summary	object	否	—	选择技能所需的摘要和示例。
instruction	object	否	—	body 及可选变量 Schema。
requirements	object	否	—	技能、工具、知识库、文件和模型能力依赖。
parameters_schema	object	否	—	执行输入的 JSON Schema。
output_contract	object	否	—	输出约定。
change_summary	string	否	—	本次变更摘要。

更新接口接受上述字段的子集。系统技能或来自其他工作区的技能可能需要通过 skill_workspace_id 指定资源所属工作区；不要用当前工作区 ID 猜测资源归属。

列表和版本

技能列表支持 query、category、status、source_type、phase、重复的 tags、limit 和 offset。版本列表额外返回 version、spec_snapshot、change_summary 和创建时间。

设置当前版本时，请求体包含：

{
  "expected_current_version": 3
}

该字段用于检测并发修改。若当前版本已变化，应重新读取版本列表，而不是直接重试旧请求。

运行请求和响应

运行请求可包含 agent_id、context_id、message、parts、variables、parameters、resource_refs、idempotency_key 和 metadata。响应主要字段如下：

字段	类型	返回条件	说明
id	string	始终返回	技能运行记录 ID。
skill_id	string	始终返回	本次运行的技能。
skill_version	integer	始终返回	本次运行使用的版本。
runtime_task_id	string	已创建运行任务时返回	底层运行任务 ID。
runtime_task_url	string	可提供查询入口时返回	后续查询入口。
status	string	始终返回	执行当前状态。
accepted_at	string	始终返回	请求受理时间。

流式润色事件

流式响应使用 SSE。客户端必须按 request_id 关联同一次请求，并处理：started、delta、ping、result、error 和 done。只有收到 result 后才能取得完整候选技能；收到 done 只表示流结束，不会自动保存候选内容。

任务指南

• 创建和管理技能

• 导入和运行技能

最后更新于 2026 年 8 月 14 日