assistant-ui Primitives 是一组组件指南与参考，介绍 assistant-ui 中可组合、无样式的 UI 原语，遵循 Radix UI 的设计模式，用于自定义聊天 UI 组件。使用时应查阅 assistant-ui.com/llms.txt 获取最新 API。
用途 主要用于自定义聊天界面中的各类 UI 组件，包括线程、输入框、消息、操作栏、分支选择器和附件等。
导入方式 从 @assistant-ui/react 导入：AuiIf、ThreadPrimitive、ComposerPrimitive、MessagePrimitive、ActionBarPrimitive、BranchPickerPrimitive、AttachmentPrimitive、ThreadListPrimitive、ThreadListItemPrimitive。
主要原语及关键部件
- ThreadPrimitive：.Root、.Viewport、.Messages、.Empty、.ScrollToBottom
- ComposerPrimitive：.Root、.Input、.Send、.Cancel、.Attachments
- MessagePrimitive：.Root、.Parts/.Content、.If、.Error
- ActionBarPrimitive：.Copy、.Edit、.Reload、.Speak、.FeedbackPositive、.FeedbackNegative、.ExportMarkdown
- BranchPickerPrimitive：.Previous、.Next、.Number、.Count
使用方式 参考资料提供了自定义 Thread 的完整示例：使用 ThreadPrimitive.Root 包裹整体，配合 ThreadPrimitive.Empty 显示初始提示，ThreadPrimitive.Viewport 承载消息区并通过 ThreadPrimitive.Messages 传入自定义的 UserMessage 与 AssistantMessage 组件，最后在 ComposerPrimitive.Root 内组合 Input 与 Send 实现输入发送。
条件渲染 新代码推荐使用 AuiIf 组件，可为不同条件渲染内容，例如按消息角色、线程运行状态、分支数量或线程是否为空等。各原语的 .If 组件仍然存在，但已废弃。
内容部件 MessagePrimitive.Content 支持通过 components 属性自定义 Text、Image、ToolCall、Reasoning 等部件。
分支选择器 通过 MessagePrimitive.If hasBranches 与 BranchPickerPrimitive 组合，可实现 Previous、Number/Count、Next 等分支切换 UI。
适用场景 需要在 React 中构建完全自定义外观与交互的 AI 聊天界面时使用。
限制与注意事项 原语默认无样式，需自行添加 className 并使用应用的 Tailwind/CSS 系统进行样式定制；原语不渲染通常是因为缺少 AssistantRuntimeProvider 包裹或父级原语未提供上下文；自定义样式不生效多因未主动添加样式类。
参考资料 资料还包含以下深入参考文档：./references/thread.md（ThreadPrimitive 深入）、./references/composer.md（ComposerPrimitive 深入）、./references/message.md（MessagePrimitive 深入）、./references/action-bar.md（ActionBarPrimitive 深入）。