mcpField
S
shadcn-detection

shadcn-detection

github.com/fusengine开发3441 次安装2 周前更新
代码仓库

关于 shadcn-detection

shadcn-detection 是面向 shadcn/ui 开发者的项目分析技能。它结合 CLI 输出与代码库信号，在组件开发前识别 Base UI、Radix、React Aria、混合状态或尚未配置。

主要功能

  1. 01通过 CLI 识别组件基础
  2. 02加权检查五类信号
  3. 03检查依赖与配置
  4. 04分析导入与数据属性
  5. 05检测混合基础迁移
  6. 06识别包管理器

适用场景

  1. 01确认项目的 shadcn/ui 基础
  2. 02选择兼容的组件模式
  3. 03发现混合基础迁移需求

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/fusengine/agents --skill shadcn-detection

安装后在 Claude Code 中输入/shadcn-detection确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
baseui-patterns.md
detection-algorithm.md
radix-patterns.md
references/templates/
detection-script.md

详细介绍

检测项目使用的三种 shadcn/ui 组件基底之一：Base UI（`base`，自 2026 年 7 月起新项目的默认选项）、Radix（`radix`，完全支持）或 React Aria（`aria`，于 2026 年 7 月新增）。优先采用权威信号（`shadcn info --json` -> `config.base`），再进行 5 项信号加权扫描：`package.json` 依赖、`components.json` 的样式前缀、源代码导入模式、数据属性约定（`data-state` 与 `data-open` 与 `data-entering`），以及通过锁文件检测包管理器。

结果为 Base UI / Radix / React Aria / Mixed（需要迁移）/ None（全新设置），并据此决定是否执行所有后续 shadcn 组件或迁移任务。

shadcn 检测

Agent 工作流（强制）

检测之前，并行启动 Agent，每个调用一次 Agent，并提供 name：

  1. fuse-ai-pilot:explore-codebase - 扫描项目结构
  2. fuse-ai-pilot:research-expert - 验证最新的原语模式

之后：使用结果配置组件工作流。

概览

功能描述
CLI 探测（权威）{runner} shadcn@latest info --json -> .config.base = base | radix | aria（以及 .config.style、.components、.links）
包扫描检测 @base-ui/react、radix-ui / @radix-ui/*、react-aria-components
配置检查分析 components.json 样式前缀（base-*、radix-*/new-york、aria-*）
导入分析扫描源代码中的导入模式
属性扫描data-state=（Radix）与 data-open（Base UI）与 data-entering/data-placement（React Aria）
包管理器通过锁文件检测 bun/npm/pnpm/yarn
基底包样式前缀组合方式文档
Base UI（默认）@base-ui/reactbase-*render 属性/docs/components/base/<name>
Radixradix-ui（旧版 @radix-ui/react-*）radix-*，旧版 new-yorkasChild/docs/components/radix/<name>
React Ariareact-aria-componentsaria-*Trigger 包装器（DialogTrigger > Button + Dialog）、slot、onPress/docs/components/aria/<name>

已知的跨基底依赖（不代表混合项目）：radix-* Combobox 会导入 @base-ui/react（Radix 没有 Combobox）；Questionnaire 和 MessageScroller 在所有基底中都会导入 @shadcn/react；当前每个组件都会从 cn 包导入 cn。

关键规则

  1. 始终先运行检测，再进行任何组件工作
  2. 检查全部 5 项信号，以确保准确性
  3. 将混合状态视为迁移案例处理，绝不可忽略
  4. 在会话期间缓存结果，无需重新检测
  5. 按锁文件优先级顺序检测包管理器

架构

project/
├── package.json            # Step 1: deps scan
├── components.json         # Step 2: style field
├── bun.lock|bun.lockb|pnpm-lock.yaml|yarn.lock|package-lock.json  # Step 5: PM
└── src/|components/|app/   # Step 3-4: imports + attrs

→ 完整示例请参见 detection-script.md

5 步检测算法

第 0 步：如果存在 components.json，{runner} shadcn@latest info --json 会直接给出基底；以下加权扫描用于确认结果并发现混合项目。

步骤信号权重
1package.json 依赖（@base-ui/react、radix-ui / @radix-ui/*、react-aria-components）40%
2components.json 样式前缀（base-*、radix-*/new-york、aria-*）20%
3源文件中的导入模式25%
4数据属性（data-state= / data-open / data-entering）15%
5包管理器（锁文件 → bunx/npx/pnpm dlx/yarn dlx）-

决策表

每个基础 UI 库各自获得一个分数（0-100）。

分数结果操作
只有 Base UI >50Base UI使用 Base UI 模式（render）
只有 Radix >50Radix使用 Radix 模式（asChild）
只有 React Aria >50React Aria使用 React Aria 模式（触发器包装器、onPress）
两个或更多 >0（扣除上述已知的跨基础 UI 库依赖后）混合需要迁移
全部为 0无全新设置：init 默认使用 Base UI；传入 -b radix 或 -b aria 进行选择

最佳实践

应该做
  • 在进行任何组件工作之前运行检测
  • 检查全部 5 个信号以确保准确
  • 将“混合”状态视为迁移情况
不应该做
  • 未经检查就假设使用 Radix（或新的默认项 Base UI）
  • 跳过对 components.json 的分析
  • 忽略 data 属性信号
  • 将 Radix 风格 Combobox 中的 @base-ui/react 计为混合项目

参考指南

概念
主题参考资料何时查阅
Radix 模式radix-patterns.md识别 Radix UI 信号
Base UI 模式baseui-patterns.md识别 Base UI 信号
算法detection-algorithm.md了解评分逻辑和 React Aria 信号
模板
模板使用时机
detection-script.md在项目中运行检测

评论

支持 Markdown