05_UI 组件库集成指南：Shadcn/ui + Tailwind CSS v4

第一阶段：进入前端目录并初始化

由于我们是在 Monorepo 结构下工作，请确保你的终端路径在 apps/web。

1.1 运行初始化指令

在 PowerShell 中执行以下命令：

powershell 复制代码

cd apps/web
pnpm dlx shadcn@latest init

1.2 推荐的配置选项

在 2026 年，为了追求极致的专业感，建议选择以下配置：

Style: New York (更现代、紧凑)
Base color: Zinc (高级灰，适合 AI 知识库)
CSS variables: Yes (方便后续一键切换深色模式)

第二阶段：安装"AI 风格"的核心组件

知识库系统最常用的就是卡片、按钮和输入框。我们先一键安装这些"基础包"：

powershell 复制代码

pnpm dlx shadcn@latest add button card input badge scroll-area

安装完成后，你会发现 apps/web/src/components/ui 目录下多出了这些组件的代码。

第三阶段：搭建 KnoSphere 的首页雏形

我们要利用 Next.js 16 的 Server Components 优势，快速搭建一个有 AI 科技感的布局。

修改 apps/web/src/app/page.tsx：

tsx 复制代码

import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Input } from "@/components/ui/input"
import { Badge } from "@/components/ui/badge"

export default function Home() {
  return (
    <main className="min-h-screen bg-zinc-950 text-zinc-50 p-8">
      {/* 顶部装饰 */}
      <div className="max-w-5xl mx-auto space-y-12">
        <section className="text-center space-y-4">
          <h1 className="text-6xl font-extrabold tracking-tight bg-gradient-to-r from-blue-400 to-emerald-400 bg-clip-text text-transparent">
            KnoSphere
          </h1>
          <p className="text-zinc-400 text-lg">2026 企业级智能知识库中枢</p>
          <div className="flex justify-center gap-2">
            <Badge variant="secondary" className="bg-blue-500/10 text-blue-300">React 19</Badge>
            <Badge variant="secondary" className="bg-emerald-500/10 text-emerald-300">FastAPI</Badge>
            <Badge variant="secondary" className="bg-purple-500/10 text-purple-300">pgvector</Badge>
          </div>
        </section>

        {/* 搜索与快捷操作 */}
        <div className="flex gap-4 max-w-2xl mx-auto">
          <Input placeholder="检索您的企业知识..." className="bg-zinc-900 border-zinc-800" />
          <Button className="bg-blue-600 hover:bg-blue-500">搜索</Button>
        </div>

        {/* 状态卡片 */}
        <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
          <Card className="bg-zinc-900 border-zinc-800 text-zinc-100">
            <CardHeader>
              <CardTitle className="text-sm font-medium">知识总量</CardTitle>
            </CardHeader>
            <CardContent>
              <div className="text-2xl font-bold">1,284 篇</div>
              <p className="text-zinc-400 text-sm mt-1">持续增长中</p>
            </CardContent>
          </Card>
          
          <Card className="bg-zinc-900 border-zinc-800 text-zinc-100">
            <CardHeader>
              <CardTitle className="text-sm font-medium">向量存储</CardTitle>
            </CardHeader>
            <CardContent>
              <div className="text-2xl font-bold">1536 维</div>
              <p className="text-zinc-400 text-sm mt-1">OpenAI text-embedding-3-small</p>
            </CardContent>
          </Card>
          
          <Card className="bg-zinc-900 border-zinc-800 text-zinc-100">
            <CardHeader>
              <CardTitle className="text-sm font-medium">响应时间</CardTitle>
            </CardHeader>
            <CardContent>
              <div className="text-2xl font-bold">~50ms</div>
              <p className="text-zinc-400 text-sm mt-1">HNSW 索引加速</p>
            </CardContent>
          </Card>
        </div>

        {/* 上传区域 */}
        <Card className="bg-zinc-900 border-zinc-800 max-w-3xl mx-auto">
          <CardHeader>
            <CardTitle className="text-xl">上传新文档</CardTitle>
            <p className="text-zinc-400 text-sm">支持 PDF、DOCX、TXT、Markdown 格式</p>
          </CardHeader>
          <CardContent>
            <div className="border-2 border-dashed border-zinc-800 rounded-lg p-12 text-center hover:border-blue-500 transition-colors cursor-pointer">
              <div className="space-y-4">
                <div className="text-zinc-400">
                  <svg className="w-12 h-12 mx-auto" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
                    <path strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.5" d="M9 13h6m-3-3v6m5 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"></path>
                  </svg>
                </div>
                <p className="text-zinc-300">拖拽文件到此处或点击上传</p>
                <p className="text-zinc-500 text-sm">文件将自动转换为向量并加入知识库</p>
              </div>
            </div>
          </CardContent>
        </Card>
      </div>
    </main>
  );
}

第四阶段：注入动效 (Framer Motion)

为了让 Agent 的思考过程看起来更智能，2026 年的标配是 Framer Motion。

powershell 复制代码

pnpm add framer-motion

你可以在组件切换或数据加载时，加上简单的淡入淡出动效，这会让用户感觉系统是在"思考"而不是单纯的死机。

例如，为状态卡片添加简单的动画：

tsx 复制代码

// 在 page.tsx 顶部添加
"use client";

import { motion } from "framer-motion";

// 然后在卡片区域使用
<motion.div 
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.3 }}
  className="grid grid-cols-1 md:grid-cols-3 gap-6"
>
  {/* 卡片内容 */}
</motion.div>

为什么这一步很重要？

Tailwind CSS v4: 提供了更强的设计一致性，你的 CSS 几乎不需要维护。
零成本性能优化 : 借助 React 19 编译器，这些 UI 组件的重绘和更新都是全自动优化的，无需手动写 useMemo。
专业交互感: Shadcn/ui 的组件自带无障碍支持（Accessibility），这在企业级采购中是硬性指标。

检查点：KnoSphere 变帅了

UI 组件库：已就绪，所有组件代码都在你本地。
科技感色调：深色系 + 渐变文字，符合 2026 AI 审美。
响应式设计：代码已经考虑了手机和电脑的适配。