注册表规范 — eyai Registry v1.0

版本： 1.0.0-rc5  |  状态： 🔴 候选发布

本规范定义 eyai 规范注册表的发现、解析、身份验证协议。

核心概念

概念	说明
注册表索引	规范元数据的 JSON 目录
规范包	包含 extension.eyai-ext.yaml 的 .eyaipkg 归档文件
解析器	验证器内建的规范查找机制
发布者	将规范发布到注册表的作者

解析优先级

验证器解析规范引用时，按以下顺序查找：

1. 内置缓存 → 已解析过的规范
2. 本地目录 → ~/.eyai/specs/
3. 远程注册表 → 通过 URL 配置

注册表索引

{
  "registry": {
    "name": "eyai Official Registry",
    "url": "https://registry.eyai.top",
    "version": "1.0.0"
  },
  "specs": {
    "com.example.power": {
      "versions": {
        "1.0.0": {
          "location": "https://registry.eyai.top/packages/com.example.power-v1.0.0.eyaipkg",
          "checksum": "sha256:abc123...",
          "parent": "eyai/core@>=1.0.0",
          "published": "2026-06-04T10:00:00Z"
        }
      }
    }
  }
}

RESTful API

索引端点

方法	路径	用途
GET	/v1/index.json	获取完整索引
GET	/v1/index.json?since={ts}	增量更新
HEAD	/v1/index.json	检查更新（ETag）

查询端点

方法	路径	用途
GET	/v1/specs/{id}	规范版本列表
GET	/v1/specs/{id}/{ver}	版本详情
GET	/v1/search?q={q}	搜索规范

发布端点

方法	路径	用途
PUT	/v1/packages	上传规范包
DELETE	/v1/packages/{id}/{ver}	删除草稿版本

认证方式

方式	适用场景	推荐程度
API Key	CLI 工具	⭐ 推荐
Bearer Token	Web/CI/CD	⭐ 推荐
mTLS	企业级安全	可选

配置

# ~/.eyai/config.yaml
registries:
  - url: "https://registry.eyai.top"
    auth:
      type: "bearer"
      token: "eyJ..."

安全

• 校验和： 所有包必须声明 SHA-256 checksum
• 数字签名： 可选，签名密钥托管在 https://keys.eyai.top/publisher.asc
• 版本不可变： 已发布版本禁止修改或删除

全文

完整规范请查阅 GitHub 仓库。