Registry 协议文档

SkillForge Registry HTTP v1 是 CLI 与远端服务之间的标准协议：多源聚合、签名发布、Scope RBAC、撤回审计，客户端和服务端都可以独立升级而不破坏链路。

HTTP v1 协议

Bearer Token 鉴权

所有写操作（publish / yank / scope 更新 / token 颁发）都需要 Authorization: Bearer <token> 头。服务端启动时会生成 bootstrap token，写入 data/bootstrap-tokens.json 便于本地联调。

# 本地一键启动服务 & 读取默认 token
$ pnpm registry-service:dev
$ cat data/bootstrap-tokens.json

# CLI 登录
$ skillforge registry login official --token-stdin < <(jq -r '.tokens[] | select(.name=="bootstrap-admin") | .token' data/bootstrap-tokens.json)

# 使用管理员颁发新的 ci 只读 token
$ curl -X POST http://localhost:18081/v1/internal/tokens \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"owner":"ci-bot","scopes":["read"]}'

包签名

采用类似 Minisign 的 Ed25519 结构：untrusted comment 放 keyId，trusted comment 放时间戳。安装端以 trusted publishers 公钥集做白名单校验，确保即使被镜像投毒也无法通过。

# 生成密钥对 & 导出公钥
$ skillforge signer keygen --alias team-a
$ skillforge signer export-pub team-a > ./team-a.pub

# 发布时自动签名
$ skillforge publish @corp/security-review --sign

# 安装时强制校验
$ skillforge install @corp/security-review --remote \
    --require-signature \
    --trust ./team-a.pub

Scope 白名单

每个 scope 有 publishers（可发布）和 admins（可撤回/管理成员），未配置 admins 时 publishers 可自撤回。未带 scope 的全局技能不对发布者做白名单限制。

# 服务端通过 admin token 配置 scope 白名单
$ curl -X PUT http://localhost:18081/v1/scopes/corp \
    -H "Authorization: Bearer $ADMIN_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"publishers":["alice","bob"],"admins":["alice"]}'

# CLI 侧把 scope 绑定到私有源，路由 @corp/*
$ skillforge registry add internal https://corp.internal/registry \
    --scopes corp --priority 300

审计日志

所有会影响 registry 状态的动作都会写入 audit_log：发布、撤回、scope 更新、token 颁发。通过 /v1/audit?limit=&action=&actor= 过滤，Web UI 的「审计日志」页也可直接浏览。