[!info] related notes

• 框架资源: assistant-ui
• AI 聊天 UI 设计与选型: AI 聊天 UI 设计与组件选型
• Thread 原语: Thread & Message 原语
• Composer 原语: Composer 原语
• ActionBar 原语: ActionBar & BranchPicker 原语
• Runtime 架构: Runtime 架构与后端集成

assistant-ui 架构概览

本页学习 assistant-ui 内部怎么分层；框架的 canonical 资源身份、URL 与仓库入口统一放在 assistant-ui。

与资源节点的边界

assistant-ui.md 回答“这个项目是什么、去哪里使用”；本页回答“为什么它能把同一套 Chat UI 接到不同后端”。因此这里优先保留稳定的架构心智模型，而不是重复维护版本、官网或营销特性列表。

核心特点

特性	说明
组合式原语	Thread、Message、Composer、ActionBar 等独立原语，自由组合
流式打字机	原生支持 SSE 流式响应，逐 token 渲染
工具调用渲染	function calling 结果渲染为 React 组件，支持人工审批
多后端运行时	通过运行时抽象层切换 Vercel AI SDK / LangGraph / 自定义后端
TypeScript 强类型	运行时 API、工具 schema、消息 part 全部类型化
shadcn/ui 集成	CLI 一键添加预样式组件到项目

安装

# 新项目
npx assistant-ui@latest create

# 已有项目
npx assistant-ui@latest init

# 手动安装
npm install @assistant-ui/react @assistant-ui/react-ai-sdk

架构分层

┌─────────────────────────────────┐
│  预构建 UI 组件 (shadcn Thread)  │  ← 开箱即用
├─────────────────────────────────┤
│  原语 (Primitives)              │  ← ThreadPrimitive, MessagePrimitive...
├─────────────────────────────────┤
│  运行时 (Runtime)               │  ← useChatRuntime, useLangGraphRuntime...
├─────────────────────────────────┤
│  后端集成 (Adapters)            │  ← Vercel AI SDK, LangGraph, 自定义 SSE
└─────────────────────────────────┘

Radix 风格：每个原语都是独立的 headless 组件，开发者掌控布局和样式，原语负责行为和状态管理。

原语一览

原语	职责
ThreadPrimitive	可滚动消息容器、自动滚动、空状态
MessagePrimitive	单条消息渲染、内容 part 分发、hover 状态
ComposerPrimitive	输入框、提交、附件、语音输入
ActionBarPrimitive	消息级操作按钮（复制、重试、编辑、反馈）
BranchPickerPrimitive	多分支回复导航（重新生成/编辑后）
ThreadListPrimitive	多会话列表管理

后端集成

集成	包名
Vercel AI SDK	@assistant-ui/react-ai-sdk
LangGraph	@assistant-ui/react-langgraph
LangChain	@assistant-ui/react-langchain
AG-UI 协议	@assistant-ui/react-ag-ui
Google ADK	@assistant-ui/react-google-adk
自定义数据流	@assistant-ui/react-data-stream
托管云服务	assistant-cloud

基础用法

// app/page.tsx
import { Thread } from "@/components/assistant-ui/thread";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

export default function ChatPage() {
  const runtime = useChatRuntime({
    api: "/api/chat",  // 后端 API 路由
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
    </AssistantRuntimeProvider>
  );
}

优雅之处：

• 所有原语共享同一个 AssistantRuntimeProvider 上下文，状态管理自动完成
• UI 与 Runtime/Adapter 分离，使后端迁移不必重写整套消息组件
• 预构建组件可逐步替换为自定义原语，无需重写整个架构

学习检查

不看正文回答：

1. Primitive、Runtime、Adapter、预构建组件分别解决什么问题？
2. 为什么把 transport/backend 细节放进 Message 组件会破坏这套架构的可替换性？
3. “换后端只改一行”在哪些情况下只是近似说法，哪些业务语义仍然需要适配？
4. 如果需要展示 tool approval 和 artifact，应该优先扩展 Primitive、Runtime 还是业务组件？为什么？
5. 与 Vercel AI SDK UI 对比时，应按哪个架构层级比较，而不是只比较 API 名称？

---

Related

• AI 聊天 UI 设计

Related notes

• 前端工程化 MOC