Overview

aui-components 是一个基于 assistant-ui 封装的 React 聊天 UI 组件库。提供了开箱即用的 Thread、MarkdownText、Reasoning、ToolGroup 等组件，支持工具调用、思维链、附件、图片预览、引用等完整的聊天交互能力。

特性

开箱即用 — 一行 <Thread /> 即可渲染完整聊天界面
assistant-ui 生态 — 基于 assistant-ui primitives，支持 AI SDK、LangGraph 等后端
CVA 变体 — 组件通过 class-variance-authority 提供多种视觉变体
Tailwind CSS v4 — 使用 Tailwind CSS v4 构建，支持深色模式
base-ui 原语 — UI 基础组件基于 @base-ui/react，无样式冲突
TypeScript — 完整的类型定义，组件支持 Props 推导

定位

assistant-ui 提供了强大的聊天界面原语（Primitives），但直接使用它们需要大量的组合和样式配置。aui-components 在这一层之上提供了预配置、可组合的组件，帮助你快速搭建美观的聊天界面。

核心依赖

包名	用途
`@assistant-ui/react`	聊天界面原语和 Runtime 系统
`@assistant-ui/react-markdown`	Markdown 渲染引擎
`@base-ui/react`	无样式 UI 原语（Collapsible、Dialog、Tooltip 等）
`class-variance-authority`	组件变体管理
`tailwind-merge` + `clsx`	类名合并工具
`lucide-react`	图标库
`zustand`	状态管理（assistant-ui 依赖）

设计理念

复合组件模式

所有复杂组件都采用复合组件（Compound Components）模式，子组件作为静态属性挂载在父组件上：

import { Reasoning } from "aui-components";

// 预设组合
<Reasoning />

// 或自由组合
<Reasoning.Root streaming>
  <Reasoning.Trigger active />
  <Reasoning.Content>
    <Reasoning.Text>思考过程...</Reasoning.Text>
  </Reasoning.Content>
</Reasoning.Root>

CVA 变体

通过 class-variance-authority 提供一致的视觉变体系统：

variant: "outline" | "ghost" | "muted" — 适用于 Reasoning、ToolGroup、Image 等
size: "sm" | "default" | "lg" | "full" — 适用于 Image

组件	说明
Thread	主聊天线程组件
MarkdownText	Markdown 渲染（支持 GFM + KaTeX）
Reasoning	思维链展示组件
ToolGroup	工具调用分组容器
ToolFallback	工具调用通用回退 UI
Quote	引用块 / 选中工具栏 / 输入预览
Image	图片消息渲染
Attachment	附件展示与上传
FollowupSuggestions	对话追问建议

Utility

组件	说明
TooltipIconButton	带 Tooltip 的图标按钮

UI Primitives

组件	说明
Button	按钮（5 种变体 + 6 种尺寸）
Collapsible	折叠面板
Dialog	对话框
Tooltip	工具提示
Avatar	头像

Tools

函数	说明
cn	clsx + tailwind-merge 类名合并

快速开始

"use client";

import { AssistantRuntimeProvider, useChatRuntime } from "@assistant-ui/react";
import { Thread } from "aui-components";

export default function ChatPage() {
  const runtime = useChatRuntime({
    api: "/api/chat",
  });

  return (
    <AssistantRuntimeProvider aui={runtime.aui} runtime={runtime}>
      <div className="h-screen">
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}

更多细节请查看 Quick Start 和 Installation。

与 langgraph-aui-app 的关系

langgraph-aui-app 是本仓库中的客户端应用，它直接使用了 aui-components 的全部组件。你可以将其作为参考实现。