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 upgradeMUST 仅应用与已安装 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