新手指南

欢迎使用 Unnamed UI。本指南旨在帮助您快速搭建开发环境，并通过“搭建题目 (Proposal)”这一典型研发场景，熟悉核心组件的使用。

1. 环境准备与安装

在开始之前，请确保您的开发环境满足基础要求：

Node.js: 18 或更高版本
pnpm（推荐）或 npm / yarn

1.1 推荐：使用 Unnamed UI 脚手架（最快）

我们提供了开箱即用的 Vite 脚手架（AI Coding 实验模板），已预配置 Tailwind、PostCSS、shadcn 及 Unnamed UI 样式，省去繁琐的手动配置。

分支说明：

脚手架提供两个分支供您选择：

分支	说明	适用场景
`feat/template`	仅配置好运行环境	想要按需安装组件，自由搭建项目
`feat/template-with-layout`	配置环境 + 所有组件 + 基础布局	快速体验完整功能，参考布局实现

推荐：初次使用建议选择 feat/template-with-layout 分支，可立即体验完整功能。

方式一：使用 degit（推荐，无 Git 历史）

# 安装 degit（首次使用需要）
npm install -g degit

# 下载 feat/template 分支（仅配置）
degit fancn21th/unnamed-ui-ai-coding-template#feat/template unnamed-demo
cd unnamed-demo
pnpm install

# 或下载 feat/template-with-layout 分支（完整功能）
degit fancn21th/unnamed-ui-ai-coding-template#feat/template-with-layout unnamed-demo
cd unnamed-demo
pnpm install

degit 会下载项目文件但不包含 Git 历史，这样您得到的是一个全新的项目，可以直接初始化自己的 Git 仓库。

方式二：下载压缩包（无需 Git）

# feat/template 分支
curl -L https://github.com/fancn21th/unnamed-ui-ai-coding-template/archive/refs/heads/feat/template.zip -o unnamed-demo.zip
unzip unnamed-demo.zip
mv unnamed-ui-ai-coding-template-feat-template unnamed-demo
cd unnamed-demo
pnpm install

# 或 feat/template-with-layout 分支
curl -L https://github.com/fancn21th/unnamed-ui-ai-coding-template/archive/refs/heads/feat/template-with-layout.zip -o unnamed-demo.zip
unzip unnamed-demo.zip
mv unnamed-ui-ai-coding-template-feat-template-with-layout unnamed-demo
cd unnamed-demo
pnpm install

方式三：Git Clone（需手动清理 Git 历史）

# 克隆 feat/template 分支
git clone -b feat/template https://github.com/fancn21th/unnamed-ui-ai-coding-template.git unnamed-demo
cd unnamed-demo

# 或克隆 feat/template-with-layout 分支
git clone -b feat/template-with-layout https://github.com/fancn21th/unnamed-ui-ai-coding-template.git unnamed-demo
cd unnamed-demo

# 删除 Git 历史，重新初始化
rm -rf .git
git init
git add .
git commit -m "Initial commit"

# 安装依赖
pnpm install

验证安装

如果您选择的是 feat/template 分支，需要手动安装 Welcome 组件进行验证：

pnpm dlx shadcn@latest add -y -o "https://unnamed-ui.vercel.app/r/wuhan/welcome.json"

使用组件

在 src/App.tsx 中引入 Welcome 组件：

import { WelcomeMessage } from "@/components/wuhan/composed/welcome";
import { Sparkles } from "lucide-react";

export default function App() {
  return (
    <div className="p-4">
      <WelcomeMessage
        icon={<Sparkles className="w-6 h-6" />}
        text="Hello Unnamed UI"
      />
    </div>
  );
}

运行 pnpm dev，若页面正常显示，说明环境已就绪。

提示：如果选择的是 feat/template-with-layout 分支，已包含完整的布局示例，直接运行 pnpm dev 即可查看效果，无需手动配置。

1.2 可选：从零开始手动配置

若需在现有项目或非 Vite 环境中集成，可参考以下步骤（已通过多轮验证）。

若无现有项目，可先创建 Vite 项目：npm create vite@latest 项目名 -- --template react-ts，然后 cd 项目名 && npm install。

第一步：安装依赖

pnpm add -D tailwindcss @tailwindcss/postcss postcss tw-animate-css

在项目根目录创建 postcss.config.mjs：

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

第二步：添加 Tailwind 导入

在 src/index.css（Vite）或 app/globals.css（Next.js）最顶部添加：

@import "tailwindcss";
@import "tw-animate-css";

Tailwind v4 采用 CSS-first 配置，无需 tailwind.config.js；若项目已有该文件可保留，shadcn 会读取。

第三步：配置 @/* 路径别名

shadcn 会将组件安装到 src/components/，路径别名需与之对应。

在根目录 tsconfig.json 的 compilerOptions 中添加（Vite 默认使用 project references，根 tsconfig.json 可能仅有 references，此时需新增 compilerOptions 块，否则 shadcn init 会报错）：

"baseUrl": ".",
"paths": {
  "@/*": ["./src/*"],
  "@/components/*": ["./src/components/*"]
}

若使用 project references，在 tsconfig.app.json 的 compilerOptions 中同样添加上述 baseUrl 和 paths。

若使用 Vite，还需在 vite.config.ts 中配置 resolve.alias：

import path from "path";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
      "@/components": path.resolve(__dirname, "./src/components"),
    },
  },
});

第四步：初始化 shadcn 并安装样式

先创建 components.json（脚本/CI 场景必需；交互式场景下，首次 add 时选择 yes 创建亦可）：

pnpm dlx shadcn@latest init --yes --src-dir --base-color neutral --no-base-style

再安装 Unnamed UI 样式：

pnpm dlx shadcn@latest add https://unnamed-ui.vercel.app/r/wuhan/style.json -y -o

样式安装后，在 src/index.css（或 app/globals.css）顶部追加引入：

@import "./components/globals.css";

globals.css 会安装到 src/components/，故从 src/index.css 用 @import "./components/globals.css" 引用。若 style 安装时生成了 src/postcss.config.mjs，可删除，PostCSS 使用根目录配置即可。

第五步：安装 Welcome 组件（用于验证）

pnpm dlx shadcn@latest add https://unnamed-ui.vercel.app/r/wuhan/welcome.json -y -o

注意事项与常见问题

init 报错 "No import alias found"：在根 tsconfig.json 中补充 compilerOptions.baseUrl 和 paths。
add 卡在 components.json 提示：先执行 shadcn init，脚本/CI 场景下 add -y 无法跳过该提示。
布局未占满视口：在 index.css 中添加 html, body, #root { height: 100%; }。
构建时 @keyframes 警告：来自 globals.css，可忽略，不影响构建。
使用 pnpm 时，将 npm install 替换为 pnpm add。

1.3 批量安装所有组件（可选）

如果您想一次性安装所有 54 个组件，而不是在后续章节中按需逐个安装，可以使用批量安装脚本。

适用场景：

快速体验所有组件功能
在开发环境中预先安装全部组件
减少后续开发中的安装操作

方式一：下载并执行（推荐）

# 下载安装脚本
curl -O https://raw.githubusercontent.com/fancn21th/unnamed-ui/main/apps/www/scripts/install/install-components.cjs

# 执行批量安装
node install-components.cjs https://unnamed-ui.vercel.app

方式二：一行命令直接安装

curl -fsSL https://raw.githubusercontent.com/fancn21th/unnamed-ui/main/apps/www/scripts/install/install-components.cjs | node - https://unnamed-ui.vercel.app

安装说明：

📦 包含所有 54 个组件（基础、按钮、卡片、输入、布局、列表、步骤等）
⏱️ 完整安装约需 3-5 分钟
✅ 自动覆盖已存在的文件，无需手动确认
🔄 可重复执行以更新组件

安装完成后，您可以直接跳到第 2 章节开始使用，无需再逐个安装组件。

提示：如果您只想根据需要安装特定组件，可以跳过此步骤，在后续章节中按照示例代码逐个安装。

1.4 重要：组件引用路径说明

在使用 Unnamed UI 组件时，请特别注意组件的引用路径。文档示例中展示的路径与您项目中的实际路径不完全相同。

路径差异对比：

场景	引用路径示例	说明
文档示例代码	`@/registry/wuhan/composed/welcome`	仅用于展示，不能直接复制使用
您项目中的实际路径	`@/components/wuhan/composed/welcome`	安装后的真实路径，请使用此路径

为什么会有差异？

文档示例代码来自 Unnamed UI 源码仓库，组件位于 registry/ 目录
shadcn CLI 安装组件时，会将文件复制到您项目的 src/components/ 目录
因此需要将示例中的 @/registry/ 替换为 @/components/

正确使用方式：

查看文档示例时，注意调整引用路径：

// ❌ 文档示例中的路径（不能直接使用）
import { WelcomeMessage } from "@/registry/wuhan/composed/welcome/welcome";

// ✅ 您项目中应使用的路径
import { WelcomeMessage } from "@/components/wuhan/composed/welcome";

简单规则：将文档示例中的 @/registry/wuhan/ 替换为 @/components/wuhan/，并移除末尾重复的文件名部分（如 /welcome、/page-header 等）。

提示：在后续章节的代码示例中，我们已经为您调整为正确的 @/components/ 路径，可以直接使用。但查看在线文档或 Storybook 时，请记得进行路径转换。

1.5 Token 定制说明

如需自定义主题色，请新建 theme.css，在入口 CSS 中 globals 引入之后追加引入：

@import "./components/globals.css";
@import "./theme.css";   /* 您的主题覆盖 */

在 theme.css 中覆盖变量，例如：

:root {
  --Light-Brand-brand-600: #00589f;
  --Container-bg-brand: #00589f;
}

.dark {
  --Dark-Brand-brand-600: #424cdc;
}

不要直接修改 globals.css，以便后续升级 Unnamed UI 样式时不受影响。变量名可参考设计变量使用指南。也可使用主题工作台（Theme Studio）调整后复制生成的 CSS 到 theme.css。

2. 实战演练：搭建 Proposal 页面

本节将按照如何搭建题目的研发步骤，逐步讲解如何使用 Unnamed UI 完成开发。

💡 开始之前必读

在构建 AI 聊天应用时，有两个核心组件您需要重点了解：

Message List：消息列表组件，负责展示 AI 与用户的对话历史，支持流式输出、多种消息类型（文本、工具调用、深度思考等）

Sender Responsive：用户输入组件，提供响应式的消息发送界面，支持文本输入、附件上传等功能

这两个组件是构建 AI 应用的基础核心，强烈建议先查看它们的详细文档和示例，理解其功能和用法后再继续后续步骤。您可以在组件文档中找到完整的 API 说明、交互示例和最佳实践。

📦 2.1 完整示例项目

为了帮助您更好地理解如何使用 Unnamed UI 构建完整的 AI 应用，我们提供了一个已搭建好的项目模板，包含完整的 Proposal 页面实现。

项目资源：

🔗 GitHub 仓库：unnamed-ui-starter-guide
🌐 在线预览：https://unnamed-ui-starter-guide.vercel.app/

使用建议：

先体验：访问在线预览，查看完整的交互效果和页面布局
再学习：浏览 GitHub 代码，了解组件的具体使用方式
后实践：跟随下面的步骤，从零开始搭建您自己的项目

通过对比示例项目和后续步骤，您可以更直观地理解每个组件的作用和最佳实践。

🛠️ 2.2 动手实践：搭建UWS基础布局

目标：查看设计稿，完成统一工作台（UWS）的基础框架搭建。

布局组件：使用 TripleSplitPane 或 SidebarComposed 进行左右分栏布局。顶部导航：使用 PageHeader 展示题目信息。

安装所需组件（在项目根目录执行）：

PageHeader

pnpm dlx shadcn@latest add -y -o "https://unnamed-ui.vercel.app/r/wuhan/page-header.json"

TripleSplitPane

pnpm dlx shadcn@latest add -y -o "https://unnamed-ui.vercel.app/r/wuhan/triple-split-pane.json"

pnpm dlx shadcn@latest add -y -o "https://unnamed-ui.vercel.app/r/wuhan/sources-sidebar.json"

示例代码（导入路径以 components.json 为准）：

import { TripleSplitPane } from "@/components/wuhan/composed/triple-split-pane";
import {
  PageHeader,
  PageHeaderUser,
} from "@/components/wuhan/composed/page-header";

export default function ProposalPage() {
  return (
    <div className="h-full p-3 flex flex-col gap-3 overflow-hidden bg-[var(--Container-bg-neutral-light)]">
      <PageHeader
        logo={
          <div className="flex items-center justify-center w-6 h-6 bg-gradient-to-br from-blue-500 to-purple-600 rounded-lg">
            <span className="text-white font-bold text-xs">AI</span>
          </div>
        }
        title="Proposal: 新手引导设计"
        actions={
          <>
            <PageHeaderUser
              name="User"
              avatarSrc="https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=100&h=100&fit=crop"
            />
          </>
        }
      />
      <TripleSplitPane
        className="w-full flex-1 overflow-hidden"
        left={{
          title: "数据来源",
          width: "240px",
          collapsedWidth: "0px",
          minWidth: "240px",
          children: <div>数据来源</div>,
          classNames: { body: "px-2 py-4" },
        }}
        leftPopover={{
          enabled: true,
          width: "240px",
          height: "520px",
          className: "px-2! py-4!",
          content: <div>数据来源</div>,
        }}
        center={{
          title: "对话",
          minWidth: "280px",
          children: <div>对话</div>,
        }}
        right={{
          title: "UWS",
          width: "360px",
          collapsedWidth: "48px",
          minWidth: "360px",
          children: <div>工作空间</div>,
          classNames: { body: "p-4" },
        }}
      />
    </div>
  );
}

右侧 UWS 区域可替换为 SourcesSidebar 等组件，详见 Sources Sidebar 文档。

3. 核心功能：对话与流式输出

目标：实现消息问答交互，支持 AI 消息的流式输出。

在对话区域中，我们将集成多种类型的 AI 响应能力。以下组件需先通过 npx shadcn@latest add -y -o "https://unnamed-ui.vercel.app/r/wuhan/<组件名>.json" 安装，详见各组件文档。

3.1 基础布局与输入

使用 Sender 或 Sender Responsive 作为用户输入组件，AIMessage / UserMessage 作为消息气泡容器。

3.2 消息问答类型实现

所有 AI 消息组件需支持 streaming 状态。以下是各类型问答的推荐组件方案：

A. 基本文本消息 (Basic Text)

使用 AIMessage 组件渲染 Markdown 内容，status 为 generating 时表示流式输出中。

import { AIMessage } from "@/components/wuhan/composed/message";

<AIMessage status={isStreaming ? "generating" : "idle"}>
  {streamingContent}
</AIMessage>

B. 工具调用问答 (Tool Calling)

当 AI 需要调用外部工具时，使用 Agent Card 或 Execution Result 展示调用过程和结果。

组件推荐: Agent Card, Execution Result
场景: 展示 "Searching database..." 或 "Calculator used"。

C. 深度思考问答 (Deep Thinking)

针对推理模型（如 o1/r1），使用 DeepThinking 组件包裹思考内容，支持折叠与展开。注意组件名为 DeepThinking（无空格），prop 为 status（非 state）。

import { DeepThinking } from "@/components/wuhan/composed/deep-thinking";
import { AIMessage } from "@/components/wuhan/composed/message";

<DeepThinking status={isThinking ? "thinking" : "completed"} content={thoughtProcessContent} />
<AIMessage>{finalAnswer}</AIMessage>

D. 思维链问答 (Chain of Thought)

如果需要展示详细的步骤拆解，使用 Thinking Process 和 Thinking Step Item。

组件推荐: Thinking Process, Thinking Step Item
功能: 将复杂的流式输出拆解为 Checkpoints（检查点），让用户感知 AI 的每一步逻辑。

E. HITL 问答 (Human in the Loop)

当 AI 需要用户确认才能继续时，插入交互卡片。

组件推荐: Confirm Panel, Quick Action, Select Card
场景: "检测到多个冲突文件，请选择保留哪一个？"

4. UWS 组件 (UWS Components)

在右侧或辅助区域，利用业务组件增强 Proposal 的信息密度。以下组件需先通过 npx shadcn@latest add -y -o "https://unnamed-ui.vercel.app/r/wuhan/<组件名>.json" 安装：

折叠内容: 使用 Accordion（block-accordion.json）收纳长文档。
任务管理: 使用 Task Card（task-card.json）或 Task List（task-list.json）展示关联任务。
引用来源: 使用 Custom Sources（custom-sources.json）或 File Card（file-card.json）展示 AI 回答的参考资料。
反馈机制: 在消息底部添加 Feedback（feedback.json）组件收集用户评价。

研发小贴士

边搭建边更新: 建议在开发 Proposal 页面时，随时将复用的模式（Pattern）更新回本文档或 Storybook。
流式兼容: 确保本 registry 中的 Chat 类组件都能优雅处理 undefined 或部分数据块（Chunk），以防止流式传输时的页面抖动。

新手指南

On this page