【免费下载链接】open-slideA slide framework built for agents.项目地址https://gitcode.com/gh_mirrors/op/open-slide点击查看免费下载本篇指南完整讲解 open-slide 仓库内嵌 Agent 技能.agents/skills/shadcn/registry.md所定义的 shadcn Registry 编写规范包括 source/built 两种形态、根级registry.json、include拆分、Item 定义、registryDependencies依赖寻址、五类地址方案、GitHub Registry 的消费与构建验证流程。读完你可以独立创建一个可被npx shadcnlatest直接安装、搜索与验证的组件/区块/工具库注册表并理解 CLI 消费注册表的底层规则。核心心智模型source registry 与 built registry一个 shadcn registry 有两种形态这是理解后续一切规则的前提Source registry源码注册表项目或仓库中以真实文件形式编写的registry.json允许使用include和指向源文件的路径是人类直接编写与维护的形态。Built registry构建注册表由 CLI 生成、专门面向 CLI 消费方的 JSON 文件集合通常输出到public/r目录通过npx shadcnlatest build从源码注册表生成。CLI 安装器add等命令消费的是registry item payload条目载荷而 source registry 的意义在于让你从真实文件出发、以可读可维护的方式编写这些载荷而不是手写散落的 JSON。一个重要认知registry 条目并不局限于 React 组件。它可以分发组件、hooks、工具函数、设计令牌design tokens、页面、配置文件、文档、规则、工作流、模板、MCP 文件以及其他项目文件。这意味着 registry 是一种通用的包分发机制而 shadcn 只是最典型的消费场景。根级registry.json元数据与 items/include 二选一根注册表文件必须定义注册表元数据并在items与include中二选一也可同时存在但至少要有一个{ $schema: https://ui.shadcn.com/schema/registry.json, name: acme, homepage: https://acme.com, items: [ { name: absolute-url, type: registry:lib, title: Absolute URL, description: A utility to turn any path into an absolute URL., files: [ { path: lib/absolute-url.ts, type: registry:lib } ] } ] }根级规则根registry.json必须包含name与homepageitems是 registry item 定义的数组include可用于把 source registry 拆分成多个文件被 include 的注册表文件可以省略name和homepage它们只出现在根文件。注意files中每个文件条目都带有自己的type与 item 的type可以不同这允许一个 item 混合分发 UI 组件与 lib 工具。用include拆分大型注册表当注册表条目较多时include是保持模块化的标准手段。根文件只声明元数据和拆分入口{ $schema: https://ui.shadcn.com/schema/registry.json, name: acme, homepage: https://acme.com, include: [registry/ui/registry.json, registry/blocks/registry.json] }include 规则include 路径相对声明它的registry.json解析include 路径必须显式指向一个registry.json文件禁止远程 URL、绝对路径和父目录回溯..item 文件路径相对声明该 item 的 registry 文件解析整个解析后的注册表中item 名重复会导致失败全局唯一约束。被 include 的文件示例放在registry/ui/registry.json{ items: [ { name: button, type: registry:ui, files: [ { path: button.tsx, type: registry:ui } ] } ] }路径解析规则的关键在于相对声明处解析如果该文件位于registry/ui/registry.json则button.tsx从registry/ui/button.tsx读取而构建产物中的 item 路径以根注册表为基准重新计算后输出。这种设计让子目录可以自由组织源码同时保证对外地址始终一致。Item 定义字段速查与文件规则一个典型 item区块级的定义{ name: login-form, type: registry:block, title: Login Form, description: A login form with email and password fields., dependencies: [zod], registryDependencies: [button, input, label], files: [ { path: blocks/login-form.tsx, type: registry:block } ], cssVars: { light: { brand: oklch(0.62 0.18 250) }, dark: { brand: oklch(0.72 0.16 250) } } }重要字段说明name可安装的条目名不一定是文件路径typeregistry item 类型之一包括registry:ui、registry:block、registry:lib、registry:hook、registry:file、registry:page、registry:theme、registry:style、registry:font、registry:itemfiles条目复制或生成的源文件列表dependenciesnpm 运行时依赖devDependenciesnpm 开发依赖registryDependencies本条目依赖的其他 registry 条目cssVars、css、tailwind、envVars、docs可选的安装时附加内容。文件规则文件路径相对声明它的registry.json解析registry:file与registry:page类型的文件必须指定target写入目标位置source registry 的文件路径中禁止使用远程文件 URL保持源文件可复制粘贴不要包含隐藏的仅应用内可用的 import——因为安装者会把文件原样拷入自己的项目任何依赖私有路径的 import 都会破坏可安装性。cssVars使用 OKLCH 颜色表示oklch(0.62 0.18 250)中的三个值是亮度 0–1、彩度、色相这与 shadcn 主题体系一致组件引用语义化 CSS 变量令牌改变变量即改变所有组件。open-slide 仓库内的 customization.md 对--primary、--brand等变量的 light/dark 定义方式有完整展开。registryDependencies依赖是条目地址不是文件路径registryDependencies中的每一项都是条目地址item address而不是文件路径{ name: login-form, type: registry:block, registryDependencies: [button, acme/input, acme/ui/card#v1.2.0], files: [ { path: blocks/login-form.tsx, type: registry:block } ] }依赖规则裸名称如button表示shadcn 官方条目裸名称绝不表示同注册表或同仓库内的条目——想依赖自己的条目必须用带命名空间或 GitHub 形式的完整地址命名空间依赖使用namespace/item-nameGitHub 依赖使用owner/repo/item-name需要固定版本时用owner/repo/item-name#ref钉住ref 不会继承如果owner/repo/foo#v2依赖同一仓库v2下的bar必须显式写owner/repo/bar#v2而不是裸bar禁止相对依赖如./bar。这条ref 不继承规则是依赖解析中最容易踩坑的点任何依赖声明都必须自带完整地址语义解析器不做上下文推断。地址方案先分类再解析面对任意 registry item 字符串第一步永远是判断它属于哪种地址方案。官方给出了完整的分类表地址方案含义buttonshadcn名为button的 shadcn 官方条目acme/buttonnamespace配置的注册表acme中的条目buttonacme/ui/buttonnamespace配置的注册表acme中的条目ui/buttonhttps://example.com/r/button.jsonurl该 URL 上的 built registry item JSON./button.jsonfile磁盘上的 built registry item JSONacme/ui/buttongithubGitHub 仓库acme/ui中的条目buttonacme/ui/forms/login#maingithubGitHub 仓库acme/ui中、refmain下的条目forms/login两个关键解析规则namespace 与 GitHub 地址允许带斜杠的条目名且它们就是条目名不是文件路径以.json结尾的地址保留文件地址优先权因此acme/ui/data/schema.json会被当作文件路径而不是 GitHub 条目地址。这一点决定了地址解析器必须区分条目名含斜杠与文件路径两种形态.json后缀是天然的消歧信号。GitHub Registries公共仓库即注册表一个公共 GitHub 仓库只要拥有根级registry.json就可以直接作为 source registry 使用地址形式为owner/repo/item-name[#ref]规则前两段路径段是 GitHub owner 与 repo其余路径段全部是 registry item 名源码入口永远是根registry.jsonGitHub registry 是 source registry由 CLI 直接消费不需要shadcn build或生成的 item JSON 文件include遵循与本地注册表相同的 source-registry 规则目前仅支持github.com上的公共仓库私有仓库和 GitHub Enterprise 需要明确的产品决策即当前 CLI 不支持。实现层面的关键约束文档明确给出在读取源文件前必须先把 ref 解析为 commit SHA。不能直接从raw.githubusercontent.com读取移动中的 ref分支因为类似分支的 ref 可能被缓存数分钟导致同一命令在不同快照间不一致。推荐流程owner/repo[#ref] - resolve ref with git ls-remote - commit SHA - read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json - read includes and item files from the same SHA这样一条命令始终工作在同一个仓库快照上完整的 40 位 commit SHA 本身已稳定可直接使用分支、标签和短 ref 必须经过 Gitgit ls-remote先解析成 commit SHA。构建与验证CLI 命令全集用 CLI 把 source registry 构建为 built registrynpx shadcnlatest build npx shadcnlatest build registry.json --output public/r第一条使用默认输入./registry.json、默认输出./public/r第二条显式指定输入文件与输出目录。在 CLI 参考.agents/skills/shadcn/cli.md中build还支持--output path与--cwd cwd两个参数默认输出目录即./public/r。用 CLI 命令检查构建结果namespace 形式npx shadcnlatest list acme npx shadcnlatest search acme -q login npx shadcnlatest view acme/login-form npx shadcnlatest add acme/login-form --dry-run npx shadcnlatest registry validate ./registry.json公共 GitHub registry 可直接用 GitHub 地址消费npx shadcnlatest list owner/repo npx shadcnlatest search owner/repo -q login npx shadcnlatest view owner/repo/item npx shadcnlatest add owner/repo/item --dry-run npx shadcnlatest registry validate owner/reposearch也同时是list的别名支持-q查询、-t按类型过滤、--json结构化输出详见 cli.md 的search命令表。安装前的--dry-run用于预览全部受影响文件--diff/--view用于逐文件审阅这与 SKILL.md 中绝不手动从 GitHub 拉取原始文件、一律走 CLI的更新工作流一致。在 shadcn/ui 代码库中实现 registry 时的工程建议文档对实现侧给出了明确约束这些约束同样适用于任何想深度定制 CLI 的团队保持地址解析纯函数化、可测试——解析不应依赖网络、文件系统等副作用不要给 validator 增加副作用——校验器应当只读、纯判断对官方 shadcn、namespace、URL、file 四种既有方案保留既有行为不得破坏兼容为地址解析、源码加载、依赖解析、list、search、view、add各路径补测试在出现多个真实 provider 之前优先使用小的 source-reader 抽象而不是插件系统——避免过早抽象。这条建议背后的设计哲学很清晰registry 的价值在于一个 CLI、多种地址方案、统一消费因此解析与加载边界要小且稳定扩展点推迟到确有多个 provider 时再引入。仓库证据open-slide 中的 shadcn 集成现状本仓库并未内置自己的registry.json仓库内未检索到任何registry.json文件但它本身就是一个典型的 shadcn 消费方可以作为理解本文规则的实物参照packages/core/components.json 采用new-york风格、baseColor: neutral、cssVariables: trueCSS 指向src/app/styles.cssaliases.ui为/components/ui——这正是 CLIadd安装组件时写入文件的目标位置packages/core/src/app/components/ui/button.tsx 使用class-variance-authority的cva定义variant/size变体并大量使用bg-foreground、bg-brand、bg-card等语义化令牌——与本文cssVars定义语义令牌、组件引用令牌的设计完全对应packages/core/package.json 声明了shadcn: ^4.12.0依赖说明仓库运行的是现代 shadcn CLI本文所述命令与字段均以该版本行为为准.agents/skills/shadcn/SKILL.md 中要求Registry 必须显式指定绝不替用户默认某个注册表与本文registryDependencies必须书写完整地址、裸名不代表同仓库条目的规则互为印证。小结从心智模型出发本文完整覆盖了 shadcn registry 编写与寻址的全链路source registry 用真实文件编写条目built registry 用npx shadcnlatest build生成根registry.json承载name/homepage元数据与items/includeinclude按相对路径模块化拆分item 文件路径一律相对声明处解析item 通过files、dependencies、registryDependencies、cssVars等字段定义完整安装语义依赖地址区分 shadcn / namespace / url / file / github 五类方案GitHub 仓库可作为免构建的 source registry 由 CLI 直接消费最后用list/search/view/add --dry-run/registry validate完成验证闭环。若你需要继续深入仓库内还有两份直接相关的姊妹文档CLI 命令与参数全集见 .agents/skills/shadcn/cli.md主题令牌与 CSS 变量体系见 .agents/skills/shadcn/customization.mdAgent 工作流见 .agents/skills/shadcn/SKILL.md。赞分享【免费下载链接】open-slideA slide framework built for agents.项目地址https://gitcode.com/gh_mirrors/op/open-slide点击查看免费下载相关推荐shadcn Registry 编写与地址解析实战指南从 source registry 到 GitHub 分发的完整链路shadcn Registry 编写与地址解析实战指南从 source registry 到 GitHub 分发的完整链路 导读本文以 react star后端前端Coolify 中的 shadcn Registry 实战源码级注册表的编写、依赖寻址与 GitHub 分发Coolify 中的 shadcn Registry 实战源码级注册表的编写、依赖寻址与 GitHub 分发 本文以 Coolify 仓库中为 AI Agen后端云原生容器编排运维DevOpsComp AI CRM 中的 shadcn Registry 编写与地址解析从源注册表到 CLI 分发Comp AI CRM 中的 shadcn Registry 编写与地址解析从源注册表到 CLI 分发 Comp AI CRMcrm48/crm 镜像仓库后端前端CRM人工智能AI Agent上一篇Kubernetes 子项目网站托管与域名申请全指南基于 Netlify 的 sigs.k8s.io 子域建站流程下一篇NoSleepWindows系统休眠防护的轻量级解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
