labsUI

labsui

将 labsUI 组件添加到你的项目： 简洁的 React 基础组件，每种动效都采用流畅的弹簧效果。组件会复制到你的代码库中，因此你可以自行掌控并编辑它们。

需要 React 19、Tailwind CSS v4 和路径别名 （在 tsconfig.json 中设置 "paths": { "@/*": ["./src/*"] }）。CLI 可在 Node.js 22 或更高版本以及 Deno 上运行。它没有依赖项，支持离线使用。

使用方法

npx @kznlabs/labsui init                # once: styles, theme, utils, motion provider
npx @kznlabs/labsui add button tabs     # components plus everything they import
npx @kznlabs/labsui search date range   # find by name, export or intent
npx @kznlabs/labsui view dialog         # props, examples, what it installs
npx @kznlabs/labsui update              # newer components, keeping your edits
npx @kznlabs/labsui doctor              # check the setup

任何运行器都可以使用：bunx @kznlabs/labsui add button、pnpm dlx @kznlabs/labsui …、 yarn dlx @kznlabs/labsui …，也可以通过 JSR 使用 deno run -A jsr:@kznlabs/labsui add button。npm 依赖项会使用锁文件所示的包管理器安装。

组件注册表随软件包一同发布：除了安装 npm 依赖项外，无需联网；每个 labsui 版本安装的组件代码都相同。npx @kznlabs/labsui@latest add … 会获取最新组件。

全局安装

如果想在每个项目中直接输入 labsui，而不是 npx @kznlabs/labsui：

npm install -g @kznlabs/labsui    # or: bun add -g @kznlabs/labsui
deno install -gA -n labsui jsr:@kznlabs/labsui

全局安装会将组件固定在对应版本，与注册表随每个版本一同发布的方式相同。需要获取更新的组件时，请更新全局安装（npm install -g @kznlabs/labsui@latest）；npx @kznlabs/labsui@latest 则始终会获取最新组件。

命令

init

• 写入 styles/labsui.css（设计令牌、强调色预设、动画），并在样式表中的 @import "tailwindcss" 之后立即导入该文件。
• 添加 lib/utils、lib/theme 和 components/motion-provider，并安装 motion、clsx 和 tailwind-merge。
• 保存包含注册表 URL、别名及其文件夹的 labsui.json。
• 输出根布局所需的代码行（主题脚本、MotionProvider）。

可随时再次运行：现有文件会保留。

add

通过注册表解析依赖项（data-table 会引入 table、checkbox、pagination 等），将每个文件写入别名文件夹，并安装其导入的 npm 包。除非传入 --overwrite，否则会保留现有文件；如果保留的依赖项代码与此版本不同，会列出其名称，并指出可使其同步的 labsui update 命令，因为新条目可能需要更新后的依赖项。如果你的别名不是 @/，导入路径会相应重写。只需在根布局中挂载一次的组件（toast、confirm）会输出要添加到布局中的代码行。名称拼写错误时会给出建议：输入 buton 会建议使用 button。

list 和 search

list 会显示所有内容：组件、区块、钩子（use-disclosure、use-hotkey 等）和辅助工具（utils、theme 等）。钩子和辅助工具会随导入它们的组件一起添加；也可以按名称单独添加使用。

search 会优先按名称排序，其次按条目导出的内容排序，最后按描述排序，并且必须匹配每个词：

labsui search useModal         # finds dialog
labsui search toast promise    # finds toast
labsui search --kind hook      # every hook

view

在终端中即可查看使用某个条目编写代码前所需的所有信息：

• 每个导出的准确属性和类型，直接从组件源码读取。
• 用法示例行和文档中的完整示例。
• 它会引入哪些内容，以及会安装哪些 npm 包。
• 根布局需要挂载什么内容（如有）。

示例中的导入路径使用你的别名。添加 --source 可一并显示文件本身。

update 和 diff

组件由你编辑，因此更新不能悄悄撤销你的更改。labsui.json 会记录每个项目由哪个 labsui 版本写入，labsui update（或 labsui update dialog）会以该版本为基准：

• 从未编辑过的文件会被替换。
• 编辑过的文件会进行三方合并：你的更改和此版本的更改都会保留。
• 如果双方更改了相同的行，文件中会出现 <<<<<<< yours / >>>>>>> labsui 标记，并且 update 会列出该文件。在解决冲突之前，labsui doctor 会报错。
• 更新项目所需的新依赖会被添加。

基准文件来自 JSR，它会保留每个版本的文件。离线、使用托管注册表，或对于安装时尚未记录版本的项目，编辑过的文件会保持原样。labsui diff 会列出与此版本不同的已安装项目，并基于同一基准指出每个文件的更改来源：仅由 labsUI 更改（更新会替换它）、仅由你更改（更新会保留它），或双方都更改（更新会合并）。它还会标记仅空行或缩进不同的文件。labsui diff dialog 会打印从此版本文件到你的文件的补丁，或说明未安装 dialog。

doctor

检查设置，并为每个问题打印修复方法：React 19 和 Tailwind v4、路径别名和 labsui.json、样式表导入、MotionProvider 和主题脚本、已安装时挂载的 <Toaster /> 和 <Confirmer />、缺少的 npm 包，以及已安装组件导入但项目中缺少的文件。它还会列出与此版本、你的编辑内容或较早安装版本不同的已安装项目。如果存在问题，会以 1 退出，因此可在 CI 中运行。

它读取你的代码，而非某个框架的约定：在任何 React 应用中都能以相同方式工作。

编码 Agent

MCP 服务

labsui mcp 会通过标准输入/输出，向任何支持 Model Context Protocol 的 Agent 提供相同的命令。将其注册到你的 Agent：

{
	"mcpServers": {
		"labsui": { "command": "npx", "args": ["-y", "@kznlabs/labsui", "mcp"] }
	}
}

它会在 Agent 共享为工作区的文件夹（MCP roots）中运行，或在启动服务时所在的文件夹中运行。如果 Agent 在其他位置启动服务，且没有共享工作区，请在 "mcp" 后添加 "--cwd", "/path/to/app"；--cwd 始终优先。Claude Desktop 就是这种情况：它不共享工作区，因此请为其指定 --cwd。在 Windows 上，Desktop 会通过 cmd 启动 npx：

{
	"mcpServers": {
		"labsui": {
			"command": "cmd",
			"args": ["/c", "npx", "-y", "@kznlabs/labsui", "mcp", "--cwd", "C:\\path\\to\\app"]
		}
	}
}

工具	功能
search	按名称、导出项或意图查找项目
view	查看准确的 props、示例、依赖项和可选源码
add	将项目安装到项目中（绝不覆盖文件）
init	一次性设置；返回根布局代码
diff	查看此版本与编辑后文件之间的补丁
update	更新项目，以三方合并方式保留你的编辑
doctor	检查设置，并为每个问题提供修复方法

连接时，服务还会发送 labsUI 编码规则（导入、令牌、动效、挂载），让 Agent 按照库的预期编写代码。它会在 Agent 启动时所在的文件夹中运行，并且只会在该项目内写入文件。

不使用 MCP

• labsui rules 会以 Markdown 格式打印相同的编码规则。将其追加到 Agent 读取的文件中：labsui rules >> AGENTS.md。
• 在任何命令中使用 --json，都会将一个 JSON 文档打印到标准输出；npm 输出会写入标准错误。错误的格式为 { "error": "…" }，退出代码为 1。

选项

标志	含义
--json	将机器可读的输出写入标准输出
--kind <kind>	仅用于 search：component、block、hook、helper 或 setup
--source	仅用于 view：包含源文件
--overwrite	替换已存在的文件
--dry-run	显示将要进行的更改，不写入任何内容
--no-install	打印安装命令，而不运行该命令
--registry <url>	使用其他注册表（也可通过 LABSUI_REGISTRY 或配置中的 registry 指定）
--cwd <dir>	在其他项目文件夹中运行

许可证

MIT。每个组件都是原创的 labsUI 手工编写代码。