[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 对比: Vercel AI SDK UI
• 架构学习: assistant-ui 架构概览
• 设计选型: AI 聊天 UI 设计与组件选型

assistant-ui

一句话定义

assistant-ui 是一个 React AI 聊天界面组件库，采用 Radix 风格的可组合原语架构。它不是预设好的聊天框，而是一组可自由组合的构建块（Thread、Message、Composer），让你完全控制样式和行为。

知识库职责

本页是 assistant-ui 的 canonical resource 节点：保存项目身份、入口和稳定能力概览。内部 Primitive/Runtime/Adapter 的架构学习统一放到 assistant-ui 架构概览；跨框架的设计与选型统一放到 AI 聊天 UI 设计与组件选型。

因此其他笔记需要链接 assistant-ui 项目本身时，应链接本页，而不是把 assistant-ui 作为别名复制到概览或选型笔记。

核心特性

1. 可组合原语

Thread (会话容器)
├── ThreadList (会话列表)
├── Message (消息)
│   ├── TextContent (文本)
│   ├── ToolCallCard (工具调用)
│   └── ActionBar (操作栏: 重试、复制)
├── Composer (输入区)
│   ├── TextInput
│   └── SendButton
└── ScrollAnchor (自动滚动)

2. 多后端运行时

// 连接 Vercel AI SDK
const runtime = useChatRuntime({ api: '/api/chat' });

// 连接 LangGraph
const runtime = useLangGraphRuntime({ apiUrl: '/api/langgraph' });

// 连接自定义后端
const runtime = useDataStreamRuntime({ api: '/api/stream' });

运行时与 UI 解耦，切换后端不需要改 UI 代码。

3. Generative UI

工具调用直接渲染为 React 组件：

const tools = {
  show_chart: {
    description: '展示图表',
    parameters: z.object({ data: z.array(z.number()) }),
    render: ({ data }) => <Chart data={data} />,
  },
  ask_confirmation: {
    description: '请求用户确认',
    parameters: z.object({ message: z.string() }),
    render: ({ message }) => <ConfirmationDialog message={message} />,
  },
};

4. 内置功能

• 流式响应
• 自动滚动
• 重试机制
• 文件附件
• Markdown 渲染 + 代码高亮
• 语音输入
• 键盘快捷键
• 无障碍支持

使用方式

# 新建项目
npx assistant-ui@latest create

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

参考资料

• assistant-ui GitHub
• assistant-ui Docs
• AI Chat UI Design