Skill Market

Skills API

Skill 查询、下载、创建与版本上传接口（当前仅草稿流）。

Base URL: /v1，外部调用认证头：Authorization: Bearer sk_xxx；Web Console 使用登录 Session。

当前阶段：Skill 通过 API 创建后保持 draft；公开下载仅允许 published，管理员可通过 /v1/admin/skills/:skillId/status 发布或下线 Skill。

方法 路径 说明 认证
GET /v1/skills 列表查询（q 主参数；兼容 keyword/query/search；支持标签、分类、精选、排序） 公开
GET /v1/skills/:skillId 获取 Skill 详情 公开
GET /v1/skills/:skillId/versions 获取版本列表 公开
GET /v1/skills/:skillId/versions/:version/download 下载指定版本（公开仅限 published；管理员 Session 可下载 draft/deprecated） 公开 / Admin Session
GET /v1/skills/:skillId/stats 获取下载统计 公开
GET /v1/skills/:skillId/versions/:version/files 查看版本文件列表（公开仅限 published） 公开 / owner / admin
POST /v1/skills 创建 Skill 草稿 Session / skill:upload
POST /v1/skills/with-package 创建草稿并上传初始版本（multipart） Session / skill:upload
PATCH /v1/skills/:skillId 更新 Skill 元信息 Session / skill:upload
DELETE /v1/skills/:skillId 删除 draft Skill Session / skill:upload
POST /v1/skills/:skillId/versions 上传新版本（multipart） Session / skill:upload
POST /v1/skills/:skillId/publish 发布 Skill（暂不可用） ⛔ 禁用
POST /v1/skills/:skillId/deprecate 下线 Skill（暂不可用） ⛔ 禁用

请求示例

curl -X POST /v1/skills \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Skill","slug":"my-skill","source_type":"github","source_url":"https://github.com/example/my-skill"}'

列表查询参数

GET /v1/skills 默认只返回 published Skill；管理员 Session 请求可以按状态过滤或查看全部状态。

参数 类型 说明
q string 关键词搜索主参数，匹配 Skill 名称和描述。
keyword / query / search string q 的兼容别名；同时提供多个搜索参数时按 q → keyword → query → search 取第一个非空白值。
category string 按分类精确过滤。
tags string 逗号分隔的标签列表，返回同时包含这些标签的 Skill。
status draft / published / deprecated 仅管理员 Session 有效；普通公开请求忽略该参数并只返回 published。
featured boolean true 时只返回已发布且精选的 Skill。
sort latest / downloads / featured 排序方式，默认 latest。
page / page_size integer 分页参数；page 默认 1，page_size 默认 20，最大 100。 
curl "/v1/skills?q=data-cleaner&sort=downloads&page=1&page_size=20"

来源字段

创建和更新 Skill 时可声明主要来源；列表、详情、我的 Skill 和管理员状态接口都会返回 source_type 与 source_url。未声明时两个字段为 null。

字段 类型 说明
source_type original / github / external / null null 表示未声明；original 表示上传者声明自创。
source_url string / null github 必须是 https://github.com/owner/repo 或子路径；external 必须是 http(s) URL；其他类型必须为空。 
curl -X PATCH /v1/skills/<skill_id> \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"source_type":null,"source_url":null}'

上传版本压缩包

POST /v1/skills/:skillId/versions 使用 multipart/form-data。 不要手动设置 Content-Type，让客户端自动生成 boundary。

字段 必填 说明
file 是 Skill 压缩包，建议 zip 格式。
version 是 版本号，例如 0.1.0。
changelog 否 版本变更说明。
metadata 否 JSON 字符串对象。 
curl -X POST https://skill.aiphys.cn/v1/skills/<skill_id>/versions \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "version=0.1.0" \
  -F "changelog=Initial release" \
  -F 'metadata={"entry":"SKILL.md"}' \
  -F "file=@./skill.zip;type=application/zip"

创建并上传初始版本

如果还没有 Skill 草稿，可以用 POST /v1/skills/with-package 一次提交元信息和压缩包。 

curl -X POST https://skill.aiphys.cn/v1/skills/with-package \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "name=My Skill" \
  -F "slug=my-skill" \
  -F "version=0.1.0" \
  -F "source_type=github" \
  -F "source_url=https://github.com/example/my-skill" \
  -F 'tags=["research","analysis"]' \
  -F "file=@./skill.zip;type=application/zip"