跳转至

shadcn Registry 兼容性系统规范

意图

让构建者能通过标准的 shadcn Registry 协议安装 Astryx 组件、组件展示、示例块和页面模板,同时不必将 Astryx 变成基于 shadcn 的库,也不必把 Astryx 组件实现复制到消费者仓库中。

该兼容层在现有 shadcn 工作流中与构建者对接。Astryx CLI 仍然是用于发现、组合、集成、主题、验证和升级的主要且更丰富的接口。

本记录规定了已获批准的兼容性基础。实现可能会在 canary 文档站之后合并,而复制型组合升级仍是生产端点和对外公告的发布门槛。

非目标

  • 用 shadcn CLI 取代 Astryx CLI。
  • 定义第二种仅限 Astryx 的 Registry 格式。
  • 在常规安装期间复制 Core 或 Lab 组件的实现源码。
  • 将生成的示例、块或页面视为字节级稳定的公开 API。
  • 发布不受支持的服务级别协议,或将复制型组合变成由包控制的实现源码。
  • 更改用于深度自定义的显式 astryx swizzle 逃生舱。

要求

  • FR1 — 标准协议。 每一项 registry 条目都 MUST 通过标准 shadcn Registry schema 验证,并使用标准的 registry 条目类型。标准 shadcn 客户端 MUST NOT 需要任何 Astryx 专属代码来读取或安装该条目。
  • FR2 — 保持包边界。 组件安装 MUST 添加已发布的 Astryx 包依赖,并且只创建面向消费者的 import 或 re-export 源码。它 MUST NOT 复制组件实现、私有辅助函数或未编译的 StyleX 源码。
  • FR3 — 完整的所需目录。 该实验 MUST 覆盖每一个公开组件或 hook、每一个组件展示和示例块、每一个其他块,以及 CLI 和 docsite 使用的同一目录中的每一个现成页面模板。
  • FR4 — 可编辑的组合。 展示、示例、块和页面条目 MAY 复制应用层级的组合源码。该源码 MUST 通过已发布的包路径导入 Astryx,声明所有非 React 包依赖,并且不得包含任何逃逸出所复制条目的相对导入。
  • FR5 — 确定、稳定的标识。 条目名称、组织化 URL 路径、目标路径、依赖列表和 JSON 输出 MUST 是确定性的且无冲突。标识 MUST 源自稳定的文档/目录字段,而不是显示标签或源文件名。显示名称变更 MUST NOT 改变安装 URL。已发布的改名 MUST 将先前的路由保留为别名。
  • FR6 — 一个目录,两个客户端。 shadcn 客户端消费标准字段。Astryx CLI MAY 从原始 JSON 中读取可选的 astryx 元数据,用于集成、来源追踪和升级指导。标准客户端可以丢弃该元数据而不改变安装。
  • FR7 — 可发现的兼容性。 公开的 docsite MUST 描述兼容性边界,并在每个适用的组件、示例、块和页面展示面的末尾显示一个次要的可复制安装命令。常规的 Astryx 文档仍然是人浏览的体验;原始 /shadcn/ 路径仍然是机器端点。
  • FR8 — 分阶段发布。 预览构建 MUST 从各自自己的 /shadcn 源提供完整 registry,并使用 @canary 包依赖。生产环境 MUST 使用精确的已发布包版本,并在复制型组合升级就绪之前保持禁用。
  • FR9 — 可升级安全的复制型组合。 每一个被复制的展示、示例、块和页面 MUST 安装一个相邻的机器可读收据,其中包含稳定条目路由、复制目标、精确的已安装字节及其哈希。astryx upgrade MUST 仅应用与已安装 Astryx 版本匹配的规范条目,自动更新未更改的文件,对编辑进行三方合并,在编辑冲突时保持原始内容不动,并且绝不重新创建已删除或移动的文件。
  • FR10 — 必需的全目录 CI。 必需的 pull-request CI MUST 生成完整的预览目录,在启动前拒绝生产输出,通过固定的 shadcn 客户端安装每一个规范条目,验证每一条路由和精确写入的文件,并根据当前 Astryx 包导出编译每一个已安装的源码。
  • IR1 — 从当前源码生成。 Registry 输出 MUST 来自现有的 docsite 和 CLI 目录,绝不是一个并行的手写条目列表。
  • IR2 — 构建时静态输出。 docsite 构建 MUST 在一个 registry 根目录下生成静态 JSON。当干净的构建可以重现该 JSON 时,生成的 JSON MUST NOT 被提交。
  • IR3 — 失败必须响亮。 缺失源码、重复名称、无效 schema、无法解析的包版本、逃逸的相对导入和陈旧的生成输出 MUST 使生成或验证失败。
  • IR4 — 端到端证据。 必需的验证 MUST 通过固定的标准客户端将每一个规范组件、hook、展示、示例、块和页面安装到一个干净的 shadcn 风格应用中,验证精确写入的字节和声明的依赖,并编译每一个写入的源文件。别名路由 MUST 解析到相同的规范条目字节。
  • IR5 — 稳定的路由契约。 生成的条目名称和规范路径 MUST 与已审阅的路由锁定保持一致。显示名称的编辑 MUST NOT 改变它们。有意的改名 MUST 通过 registry.aliases 保留旧路径,除非另行审阅的破坏性变更批准将其移除。

平台支持

  • 支持的功能/引擎下限:当前的 Astryx Node 下限以及实验所使用的固定 shadcn 版本。
  • 不支持的行为:在没有显式 astryx swizzle 操作的情况下复制 Astryx 实现源码;安装隐藏的、不完整的或无法解析的目录条目。
  • 浏览器证据:在提议发布之前,一个代表性的已安装页面 MUST 在真实 Chrome 中以浅色和深色模式渲染。

当前状态影响

CLI 已经随附组件、数百个示例和展示,以及页面模板。docsite 生成器已经能够发现组件、单个展示和示例、块、页面、包版本和源码。兼容层在现有目录之上添加了一个序列化器,而不是另建一套发现系统。

当前目录生成 970 个条目。其中 700 个复制的组合每个都附带一份相邻回执,其基准内容与标准 shadcn 写入的确切字节一致。必需的 CI 通过 shadcn 4.19.0 将所有 970 个条目安装到一个干净的消费者项目中,验证全部 1,670 个已写入的源码和回执文件,并编译全部 970 个源码入口点。有 14 个使用本地 StyleX 编写的组合在生成期间被预编译为无需编译器的 JSX;所有其他组合源码保持为带类型的 TSX。复制组件实现之所以失败,是因为私有导入和未编译的 StyleX 越过了包边界;FR2 通过安装该包并仅创建公共再导出,避开了这条路径。

验证

契约 验证 代表性状态 变更或失败预期
FR1, FR5 shadcn 模式校验与确定性快照 组件、展示、示例、块、页面 未知类型、重复名称或不稳定输出将失败
FR2 干净消费者安装加源码检查 核心组件、hook、非核心包 实现源码或私有导入将失败
FR3, IR1 将注册表计数和名称与生成的 docsite 目录进行核对 可见与隐藏条目、分组系列 缺失或多余的目录条目将失败
FR4, IR3 依赖提取与相对导入审计 heroicons、recharts、StyleX 导入、页面源码 越界导入或未声明的包将失败
FR6 原始 JSON 与 shadcn 解析测试 存在可选的 astryx 元数据 shadcn 安装发生变化或 Astryx 元数据变为必需时失败
FR7 docsite 测试与复制按钮交互 组件、块、页面、兼容性指南 命令缺失、过时或错误描述复制行为时失败
FR8 canary 预览加生产目标断言 预览与已发布包依赖 升级门禁通过之前生产环境即启用则失败
FR9 回执变更测试加标准 ShadCN 安装 原始、已编辑、冲突、缺失、别名 用户源码被覆盖或旧路由无法解析时失败
FR10, IR4 必需的全目录干净消费者安装与构建 每个规范条目、路由、依赖、目标 任一条目无法安装、与回执不匹配或无法编译时失败

决策日志

DEC-1 — 使用 shadcn 作为兼容协议,而非 Astryx 基础

参考: spec:AST-026/DEC-1 决策者: josephfarina,2026-09-02

生成标准注册表 JSON,使现有 shadcn 用户无需更换工具即可安装 Astryx。将 Astryx CLI 保留为主要产品,以及更丰富知识和维护行为的来源。

已否决:自定义 Astryx 注册表格式。它无法为第三方客户端提供互操作性,并要求先采用 Astryx 才能发现 Astryx。

DEC-2 — 复制组合,而非组件实现

参考: spec:AST-026/DEC-2 决策者: josephfarina,2026-09-02

常规安装会将 @astryxdesign/core 或所属 Astryx 包保留为真实依赖。组件条目创建公共再导出;展示、块和页面复制可编辑的组合代码,这些代码会导入该包。

已否决:复制 Core 实现源码。这会破坏由包控制的升级,并跨越私有导入和未编译 StyleX 的边界。

DEC-3 — 将发布阶段置于 canary docsite 之后

参考: spec:AST-026/DEC-3 决策者: josephfarina,2026-09-09

在端到端验证之后合并兼容基础,但在复制的组合升级就绪之前,保持生产注册表和广泛公告处于禁用状态。

DEC-4 — 从文档中派生稳定 ID,并按条目种类组织 URL

参考: spec:AST-026/DEC-4 决策者: josephfarina,2026-09-03

在发布前将注册表名称和路径视为公共 API。它们来源于稳定的组件/hook 名称、块的 name 加上 exampleFor,以及现有模板 slug。displayName 保留为编辑性内容。使用以下路径族:components、hooks、showcases/<component>、examples/<component>、blocks 和 templates。没有 exampleFor 的块在 blocks 下独立存在;有组件归属的块则作为示例或展示。

允许文档通过 registry.slug 覆盖其叶节点,并通过 registry.aliases 保留旧的相对路径。将所有名称和路径与经评审的锁定文件核对,以防重命名静默破坏现有安装命令。

每个条目还会在注册表根目录以 <name>.json 提供其规范字节。标准客户端在搜索结果和 @namespace/<name> 安装中,会从索引名称构建该地址。每个别名路径也会保留其原先代表的名称,因此重命名后的条目仍可通过旧名称安装。

DEC-5 — 使用 /shadcn、精确版本与 canary 预览

参考: spec:AST-026/DEC-5 决策者: josephfarina,2026-09-09

使用 https://astryx.atmeta.com/shadcn 作为规范生产根路径,并为未来的 Astryx 原生协议保留 /r。生产条目固定确切的已发布 Astryx 包版本;预览条目使用匹配的预览源和 @canary 依赖。

DEC-6 — 安装相邻收据并从规范注册表进行协调

参考: spec:AST-026/DEC-6 决策者: josephfarina,2026-09-10

每个复制的组合都会在其源文件旁边携带一个唯一的 JSON 收据。该收据存储已安装的基础字节和哈希;稳定的条目路由会解析该发布版本的编译源码。astryx upgrade --registry 会拒绝与已安装的 Astryx 版本不匹配的注册表项,然后更新原始文件或执行真正的三方合并,而不会将可编辑的应用程序代码视为包所有的实现。冲突会写入单独的产物,绝不会替换用户的文件。已删除或已移动的文件保持删除或移动状态。

已拒绝:仅含哈希的收据。它们在用户编辑文件后无法重建合并基准。同样已拒绝:在升级时从原始 CLI 模板资源重新构建最新组合。StyleX 预编译的注册表项需要注册表的编译字节。

DEC-7 — 通过一个干净的消费者把关每个注册表项

参考: spec:AST-026/DEC-7 决策者: josephfarina,2026-09-10

必需的 pull-request CI 会证明发布渠道选择器移除了面向生产环境的兼容性输出,然后在同一个干净的消费者中,将每个规范预览项传递给固定版本的 shadcn 客户端。该消费者会用当前的本地包构建替换 Astryx 包的固定版本,以便新组件在该版本尚不存在于 npm 上时就能证明其导出;所有第三方依赖都保留生成目录所声明的版本。CI 会将每个写入的文件与其注册表字节进行比较,并在解析 Astryx 包导出的同时编译每个源文件。

已拒绝:每个条目一个客户端进程。它会重复数百次依赖安装,却没有增加协议覆盖。同样已拒绝:仅验证代表性条目。源码或目标的缺陷可能只出现在生成的组合中的某一个上。

开放问题

  • OQ1 — 目录可见性。(human-design)隐藏或未就绪的目录条目应保持可通过 URL 访问,还是应完全省略?

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx