本页目录

HTTP registry 端点

一个 Skill Wiki registry 至少要实现的 HTTP 契约。参考实现：packages/registry/src/index.ts。

认证

POST 端点要求 Authorization: Bearer <token>。读端点默认公开，registry 可自行加限制。token 走带外签发，格式和有效期由 registry 自己定。

端点

`POST /publish`

上传 Prime tarball 加 manifest。

Headers:
  Authorization: Bearer <token>
  Content-Type:  multipart/form-data

Form parts:
  manifest:  pack.yaml content (string)
  tarball:   .tar.gz binary

Response (201):
{
  "name":     "@my/pack",
  "version":  "1.0.0",
  "sha256":   "...",
  "url":      "/pack/@my/pack/1.0.0/tarball"
}

Errors:
  400  bad manifest schema
  401  bad token
  409  version already published

`GET /pack/:scope`

列出某个 Prime 的所有版本。

Path: /pack/%40my%2Fcooking          // url-encoded "@my/cooking"

Response (200):
{
  "name": "@my/cooking",
  "versions": [
    { "version": "1.0.0", "published_at": "2026-05-01T12:00:00Z" },
    { "version": "1.1.0", "published_at": "2026-05-08T09:30:00Z" }
  ],
  "latest": "1.1.0"
}

`GET /pack/:scope/:version`

取某个具体版本的 manifest。

Response (200):
{
  "name":          "@my/cooking",
  "version":       "1.1.0",
  "description":   "Cooking knowledge ...",
  "license":       "Apache-2.0",
  "atoms":         123,
  "namespaces":    ["@my"],
  "prime-version": "1.0",
  "sha256":        "...",
  "tarball_url":   "/pack/@my/cooking/1.1.0/tarball"
}

`GET /pack/:scope/:version/tarball`

下载 Prime tarball。

Response (200):
  Content-Type: application/gzip
  Body: tarball bytes

可选端点

`GET /search?q=...`

Response (200):
{
  "results": [
    {
      "name":        "@my/cooking",
      "version":     "1.1.0",
      "description": "...",
      "score":       0.84
    }
  ]
}

`DELETE /pack/:scope/:version`

撤回某个版本，需要鉴权。多数 registry 应当对非预发布版本拒绝这个操作。

状态码

码	含义
200	OK。
201	已创建（publish）。
304	未修改（tarball 走 ETag）。
400	manifest 或 query 的 schema 不对。
401	缺鉴权或鉴权错误。
404	Prime 或版本找不到。
409	publish 时版本撞车。
500	服务端错误。

镜像与回退

CLI 接受多个 --remote，碰到 404 时解析器自动落到下一个。所以做镜像（比如在公共 registry 前架一层企业代理）很轻松。

参考实现

packages/registry/src/index.ts —— 单文件 Bun server， manifest 走 SQLite，tarball 落本地文件系统，约 600 行。