new-api 前端 shadcn/ui 技能Skill实战components.json、CLI、主题与 MCP 全景【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api本篇技术指南围绕仓库中.agents/skills/shadcn-ui/目录下的shadcn-ui技能展开讲解它是如何让 AI 助手在 new-api 的前端web应用基于 Bun Tailwind v4 shadcn/ui中读懂项目、一次写对代码的。你将学会如何用它的项目上下文探测shadcn info --json、如何查阅 CLI 命令、如何按 CSS 变量体系定制主题、如何接入 shadcn MCP 服务器以及如何组织 vendored 上游规则来做具体 markup 校验。读完后你能够独立在该前端项目中查找、安装、组合和定制 shadcn 组件并复现本文给出的可运行命令与真实配置。技能Skill的定位给 AI 助手注入项目感知的 shadcn 上下文所谓 shadcn Skill本质是一份写给 AI 助手的项目感知上下文。它解决的问题是当你在 new-api 前端里让助手加一个带邮箱和密码字段的登录表单做一个带侧边栏、统计卡片和数据表格的仪表盘把样式切换到某个 preset时助手必须先知道当前项目用了哪个框架、哪个别名校、装了哪些组件、图标库是什么、基础库是 radix 还是 base才能第一次就生成正确的导入路径和 API 调用。技能的工作方式可以概括为四个环节摘自 SKILL.md 的 How it works项目检测Project detection——仅当components.json存在时生效在 new-api 中对应 web/components.json。上下文注入Context injection——以shadcn info --json的输出作为唯一事实来源ground truth用于确定导入与 API。模式约束Pattern enforcement——用vendor/shadcn/rules/下的规则文件做具体的 markup 校验更完整的官方 CLI / registry / preset 工作流见 workflow 参考文档。组件发现Component discovery——通过shadcn docs、shadcn search、MCP 或 registry 查找组件。技能还给出了几类典型的自然语言触发示例帮助理解它的适用范围Add a login form with email and password fields.加一个登录表单Create a settings page with a form for updating profile information.做一个资料设置页Build a dashboard with a sidebar, stats cards, and a data table.做一个仪表盘Switch to --preset [CODE]切换 presetCan you add a hero from tailark?从某个 registry 添加组件技能会读取项目的components.json据此提供框架、别名、已安装组件、图标库和基础库从而第一次就写对代码。安装与运行生态安装 vs 本仓库约定SKILL.md 区分了两种安装方式这一点在 new-api 里尤其重要官方生态安装npx skills add shadcn/ui它会安装到skillsCLI 可用的地方。本仓库约定同一个意图被收进.agents/skills/shadcn-ui/本概览文档 vendored 上游文档并从前端应用根目录运行 shadcn CLIcd web bunx shadcnlatest info --json注意两点仓库事实其一new-api 前端使用Bun作为包运行器所以命令前缀是bunx而非npx其二shadcn 的所有命令都必须在web/目录下执行因为components.json位于前端根目录。这一点由 SKILL.md 结尾的 Workflow 提示明确强调Prefer this root SKILL.md for repo paths (web, Bun)”。vendored 上游文档快照的来源记录在 UPSTREAM.txt其中注明了抓取的上游提交与抓取日期2026-04-29并特别说明上游的SKILL.md被重存为official-shadcn-ui-workflow.md且去掉了原来的 frontmatter以避免 vendored 副本被当作第二个本地技能发现。项目上下文用真实components.json读懂 new-api 前端shadcn info --json会把components.json解析成结构化上下文。下面结合 new-api 前端的真实配置文件 web/components.json 逐项说明这些字段在这个项目里具体是什么值{ style: base-nova, rsc: false, tsx: true, tailwind: { config: , css: src/styles/index.css, baseColor: neutral, cssVariables: true, prefix: }, iconLibrary: hugeicons, aliases: { components: /components, utils: /lib/utils, ui: /components/ui, lib: /lib, hooks: /hooks }, menuColor: inverted, menuAccent: subtle, registries: { ai-elements: https://registry.ai-sdk.dev/{name}.json } }从这份真实配置可以读出 new-api 前端的 shadcn 项目画像style: base-nova视觉风格为base-nova注意 CLI 文档中style字段的取值示例为nova、vega而这里带base-前缀反映的是基于 base 库的 nova 风格。rsc: false/tsx: true未启用 React Server Components但使用 TypeScript。tailwind.config: 且cssVariables: true这是 Tailwind v4 的CSS 优先配置形态——不再依赖独立的tailwind.config.js而是把主题变量写在全局 CSS 里。全局 CSS 文件为 src/styles/index.css相对web/根。iconLibrary: hugeicons图标库为 HugeIcons助手生成图标导入时须用它而不是默认假设的lucide-react。aliases确定了导入路径约定——组件在/components、UI 组件在/components/ui、工具函数在/lib/utils、hooks 在/hooks。助手第一次写对的关键就在于按这套别名生成 import。menuColor: inverted/menuAccent: subtle额外的菜单配色定制项。registries[ai-elements]注册了自定义 registry指向https://registry.ai-sdk.dev/{name}.json。这说明 new-api 前端除了内置shadcnregistry 外还能从 AI SDK 的 registry 拉取组件下文 MCP 章节会讲 registry 的配置规则。CLI 文档把shadcn info的输出字段整理成三类见 cli.mdProject Info 字段framework、frameworkVersion、isSrcDir、isRSC、isTsx、tailwindVersionv3/v4、tailwindConfigFile、tailwindCssFile、aliasPrefix、packageManager。Components.json 字段baseradix或base决定组件 API 与可用 props、style、rsc、tsx、tailwind.config、tailwind.css自定义 CSS 变量所在文件、iconLibrary、各aliases.*、resolvedPaths每个别名的绝对路径、registries。Links 字段组件文档 / 源码 / 示例的模板化 URL需要解析后的真实 URL 时应改用shadcn docs component。实践建议在动手改任何组件前先在web/里跑一次bunx shadcnlatest info把它当作项目的 ground truth避免助手凭默认假设写错导入路径或图标包。CLI 命令参考init / apply / add / search / view / docs / info / buildnew-api 仓库 vendored 了一份完整的 CLI 参考cli.md。下面提炼最关键的几条命令与约束命令前缀在本仓库应替换为bunx shadcnlatest并在web/下运行。运行器约定CLI 文档的两条 IMPORTANT始终用项目自己的包运行器npx shadcnlatest、pnpm dlx shadcnlatest、bunx --bun shadcnlatest。new-api 用 Bun故用bunx。只使用文档中列出的 flag不要臆造 flagCLI 会从 lockfile 自动检测包管理器没有--package-manager这个 flag。核心命令速览命令作用init [components...]初始化或在已有项目安装组件或带--name新建项目apply [preset]给已有项目套用 preset覆盖 preset 驱动的 config、字体、CSS 变量与被检测到的 UI 组件add [components...]添加组件支持组件名、registry 前缀名magicui/...、URL、本地路径search registries...跨 registry 模糊搜索别名listview items...查看条目详情含文件内容docs components...输出组件文档 / 示例 / API 的解析后 URLinfo输出项目信息与components.json配置建议第一个跑build [registry]把registry.json构建成分散的 JSON 用于分发默认输入./registry.json、输出./public/rinit的关键 flag摘自 CLI 文档表格Flag短说明默认--template t-t模板next, start, vite, next-monorepo, react-router—--preset [name]-ppreset 配置命名 / code / URL—--yes-y跳过确认true--defaults-d用默认值--templatenext --presetbase-novafalse--force-f强制覆盖已有配置false--name name-n新项目名—--reinstall重装已有 UI 组件falsenpx shadcnlatest create是init的别名。add的 dry-run 与 smart merge重点CLI 文档反复强调要对比本地组件与上游、或预览改动时必须用add --dry-run、--diff、--view绝不手动去 GitHub 或其他源抓原始文件——CLI 会自动处理 registry 解析、文件路径与 CSS diff。# 预览所有改动不写文件 bunx shadcnlatest add button --dry-run # 显示所有文件的 diff默认前 5 个 bunx shadcnlatest add button --diff # 只显示某个文件的 diff bunx shadcnlatest add button --diff button.tsx # 查看某个文件的完整内容 bunx shadcnlatest add button --view button.tsx # 查看 CSS 会怎么变 bunx shadcnlatest add button --diff globals.css文档还特别区分了add --dry-run与view当用户想预览对我项目会有何影响时优先用add --dry-run/--diff/--view它会给出解析后的文件路径、相对现有文件的 diff、CSS 更新只有当用户想在无项目上下文下浏览 registry 信息时才用view。模板与 preset模板支持表摘自 CLI 文档next、vite、startTanStack Start、react-router、astro、laravel除 Laravel 外均支持 monorepo 脚手架通过--monorepo。preset 有三种指定方式命名--preset nova或--preset lyracode--preset a2r6bw带版本前缀的 base62 字符串如a2r6bw或b0URL--preset https://ui.shadcn.com/init?baseradixstylenova...两条强约束preset code 是不透明的绝不要试图手动解码 / 抓取 / 解析它直接传给 CLI 让它解析即可切换已有项目 preset 用apply --preset code。切换 preset 的三选一先问用户Overwrite / Re-install→apply --preset code用新 preset 样式覆盖所有被检测到的组件文件。适用于用户没自定义组件时。Merge→init --preset code --force --no-reinstall再info拿到已装组件列表逐一走 smart merge 更新并保留本地改动。适用于用户已自定义组件。Skip→init --preset code --force --no-reinstall只更新 config 与 CSS 变量保留现有组件不动。preset 命令必须在用户项目目录内运行apply只对有components.json的已有项目生效CLI 会自动从components.json保留当前 basebasevsradix。若必须在临时目录如做 dry-run 对比使用需显式传--base current-base因为 preset code 并不编码 base。主题与定制CSS 变量 → Tailwind 工具类 → 组件new-api 前端用 Tailwind v4由 web/components.json 的空tailwind.configcssVariables: true印证其主题定制遵循 vendored 的 customization.md 描述的三层链路CSS 变量定义在:root亮色与.dark暗色里Tailwind 把它们映射成工具类bg-primary、text-muted-foreground等组件使用这些工具类——改一个变量所有引用它的组件随之改变。颜色变量命名约定每个颜色遵循name/name-foreground约定基础变量用于背景-foreground用于其上的文字 / 图标。常用变量包括--background/--foreground页面背景与默认文字、--card、--primary主按钮与主操作、--secondary、--muted弱化 / 禁用态、--accent悬停与强调态、--destructive错误与破坏性操作、--border、--input表单输入边框、--ring聚焦环、--chart-1~--chart-5图表、--sidebar-*、--surface。颜色格式为 OKLCH例如--primary: oklch(0.205 0 0)三元组依次是亮度0–1、色度0灰、色相0–360。暗色模式通过在根元素上切换.dark类实现 class 策略。在 Next.js 中通常用next-themes的ThemeProviderattributeclassdefaultThemesystemenableSystem。new-api 前端非 Next.jsrsc: false、Vite/Rsbuild 体系因此暗色切换的落点在其全局 CSS 与运行时主题逻辑上但.darkclass 机制与语义变量体系完全一致。改主题的两种方式# 用 preset code 应用覆盖式 bunx shadcnlatest apply --preset a2r6bw # 位置参数简写同样可用 bunx shadcnlatest apply a2r6bw # 切换命名 preset 并覆盖现有组件 bunx shadcnlatest apply --preset nova # 保留现有组件不覆盖 bunx shadcnlatest init --preset nova --force --no-reinstall或者直接编辑全局 CSS 变量——在 new-api 中即 src/styles/index.css。添加自定义颜色三步文档强调自定义颜色要加到shadcn info中tailwindCssFile指向的文件new-api 即src/styles/index.css不要为此新建 CSS 文件。/* 1. 在全局 CSS 文件里定义 */ :root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.28 0.07 46); } .dark { --warning: oklch(0.41 0.11 46); --warning-foreground: oklch(0.99 0.02 95); }/* 2a. Tailwind v4用 theme inline 注册 */ theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }若tailwindVersion是v3先用shadcn info确认则改为在tailwind.config.js的theme.extend.colors里注册module.exports { theme: { extend: { colors: { warning: oklch(var(--warning) / alpha-value), warning-foreground: oklch(var(--warning-foreground) / alpha-value), }, }, }, }// 3. 在组件里使用 div classNamebg-warning text-warning-foregroundWarning/div由于 new-api 前端是 Tailwind v4走的是2a 的theme inline路径。圆角--radius全局控制圆角组件从它派生rounded-lgvar(--radius)rounded-mdcalc(var(--radius) - 2px)。定制组件的优先顺序文档给出 4 级策略内置 variantsButton variantoutline sizesmTailwind 类经classNameCard classNamemx-auto max-w-md新增一个 variant编辑组件源码用cva加一个 variant如warning: bg-warning text-warning-foreground hover:bg-warning/90封装 wrapper 组件把 shadcn 原语组合成更高层组件例如用AlertDialog系列封装出ConfirmDialog。shadcn MCP 服务器让助手跨 registry 检索与安装new-api 仓库 vendored 的 mcp.md 描述了 CLI 内置的 MCP 服务器——它让 AI 助手能搜索、浏览、查看并安装来自各 registry 的组件。启动与编辑器接入shadcn mcp # 启动 MCP 服务器stdio shadcn mcp init # 为你的编辑器写配置编辑器配置文件Claude Code.mcp.jsonCursor.cursor/mcp.jsonVS Code.vscode/mcp.jsonOpenCodeopencode.jsonCodex~/.codex/config.toml手动关键区分MCP 工具负责registry 操作search / view / install而项目配置别名、框架、Tailwind 版本请用shadcn info——MCP 没有对应工具。MCP 工具清单工具作用输入shadcn:get_project_registries从components.json返回 registry 名无shadcn:list_items_in_registries列出 registry 中所有条目registries,limit?,offset?shadcn:search_items_in_registries跨 registry 模糊搜索registries,query,limit?,offset?shadcn:view_items_in_registries查看条目详情含完整文件内容itemsshadcn:get_item_examples_from_registries找带源码的用法示例 / demoregistries,queryshadcn:get_add_command_for_items返回 CLI 安装命令itemsshadcn:get_audit_checklist返回组件校验清单imports / deps / lint / TS无registry 配置registry 在components.json里设置内置shadcn始终存在。配置格式{ registries: { acme: https://acme.com/r/{name}.json, private: { url: https://private.com/r/{name}.json, headers: { Authorization: Bearer ${MY_TOKEN} } } } }规则名字必须以开头URL 必须包含{name}${VAR}会从环境变量解析。new-api 前端的 web/components.json 正是一个真实实例——它注册了ai-elements指向https://registry.ai-sdk.dev/{name}.json说明这套 registry 机制在该项目里是实际启用的能力。vendored 上游规则包具体 markup 校验的检查清单SKILL.md 把 vendored 上游文档组织成一棵结构清晰的树路径相对本仓库根文档路径官方 shadcn/ui 工作流参考official-shadcn-ui-workflow.mdCLI 参考cli.md主题 / 定制customization.mdMCPmcp.mdForms 规则rules/forms.mdComposition 规则rules/composition.mdIcons 规则rules/icons.mdStyling 规则rules/styling.mdBase vs Radix 规则rules/base-vs-radix.md上游快照来源与提交信息见 UPSTREAM.txt。使用这些文档的分工摘自 SKILL.md 结尾 Workflow优先读根SKILL.md来获取仓库路径web、Bun只有当你需要完整的官方组件 / registry / preset 工作流时才读vendor/shadcn/official-shadcn-ui-workflow.md当你要校验具体 markup表单写法、组件组合、图标用法、样式、base 与 radix 的差异时用vendor/shadcn/rules/*.md。rules/下的每篇规则都给出错误写法 / 正确写法的对照是助手落地生成代码前的最后一道约束。例如 Styling 规则与 customization 文档互相引用帮助判断改主题该动 CSS 变量还是该加 variant。小结在 new-api 前端使用 shadcn 技能的标准动作把上面的证据串起来在 new-api 前端web/Bun Tailwind v4 shadcnbase-nova风格图标库 hugeicons使用这套技能时推荐的操作序列是进入web/运行bunx shadcnlatest info拿到项目 ground truth框架、别名、Tailwind 版本、已装组件。依据 web/components.json 的aliases生成正确的导入路径/components/ui、/lib/utils等图标导入走 hugeicons。添加 / 更新组件时一律用add --dry-run/--diff/--view预览不手动抓上游文件。改主题时改src/styles/index.css里的 OKLCH 语义变量Tailwind v4 用theme inline注册自定义色而不是新建 CSS 文件。需要跨 registry含本项目注册的ai-elements检索 / 安装时用 MCP 工具或search/view/docs。校验具体 markup 前对照vendor/shadcn/rules/下对应规则涉及完整 preset / registry 工作流再翻official-shadcn-ui-workflow.md。这套技能的价值不在于再造一遍 shadcn 文档而在于把项目感知固化下来——让 AI 助手在 new-api 前端里第一次就生成符合项目别名、图标库、Tailwind 版本与 preset 约定的正确代码同时为 vendored 上游规则保留了做具体校验的权威依据。【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考