ai-elements-chatbot

AI Elements 聊天机器人组件

状态：已可用于生产环境 ✅ | 上次验证时间：2025-11-18

---

什么是 AI Elements？

适用于 AI 应用、已可用于生产环境的聊天 UI 组件：

• 基于 shadcn/ui 构建
• 30+ 个组件（Message、Conversation、Response 等）
• 兼容 Vercel AI SDK v5
• 支持流式传输
• 工具／函数调用显示
• 推理可视化

---

快速开始（15 分钟）

前置条件

• Next.js 15+（App Router）
• 已初始化 shadcn/ui
• Tailwind v4
• AI SDK v5+

1. 初始化

pnpm dlx ai-elements@latest init

2. 添加组件

pnpm dlx ai-elements@latest add message conversation response prompt-input

3. 创建聊天界面

'use client';

import { useChat } from 'ai/react';
import { Conversation } from '@/components/ui/ai/conversation';
import { Message } from '@/components/ui/ai/message';
import { Response } from '@/components/ui/ai/response';
import { PromptInput } from '@/components/ui/ai/prompt-input';

export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: '/api/chat'
  });

  return (
    <div className="flex h-screen flex-col">
      <Conversation>
        {messages.map((msg) => (
          <Message key={msg.id} role={msg.role}>
            <Response markdown={msg.content} />
          </Message>
        ))}
      </Conversation>

      <PromptInput
        value={input}
        onChange={handleInputChange}
        onSubmit={handleSubmit}
      />
    </div>
  );
}

加载 references/setup-guide.md 查看完整设置指南。

---

核心组件

Message 和 Conversation

import { Conversation } from '@/components/ui/ai/conversation';
import { Message } from '@/components/ui/ai/message';

<Conversation>
  {messages.map((msg) => (
    <Message key={msg.id} role={msg.role}>
      {msg.content}
    </Message>
  ))}
</Conversation>

Response（Markdown）

import { Response } from '@/components/ui/ai/response';

<Response markdown={content} />

PromptInput

import { PromptInput } from '@/components/ui/ai/prompt-input';

<PromptInput
  value={input}
  onChange={handleInputChange}
  onSubmit={handleSubmit}
/>

CodeBlock

import { CodeBlock } from '@/components/ui/ai/code-block';

<CodeBlock code={code} language="typescript" />

Reasoning（思考过程）

import { Reasoning } from '@/components/ui/ai/reasoning';

<Reasoning content={thinking} />

Tool（函数调用）

import { Tool } from '@/components/ui/ai/tool';

<Tool name="search" args={{ query: "..." }} result={result} />

---

关键规则

务必做到 ✅

1. 先安装 shadcn/ui（AI Elements 需要它）
2. 使用 Next.js App Router（不支持 Pages Router）
3. 使用 AI SDK v5（相较于 v4 有破坏性变更）
4. 通过 CLI 安装（pnpm dlx ai-elements@latest）
5. 在 components.json 中更新注册表
6. 使用客户端组件（'use client' 指令）
7. 流式传输响应，以提升用户体验
8. 处理加载状态
9. 添加错误边界
10. 在移动设备上测试

切勿这样做 ❌

1. 切勿将其作为 npm 包安装（组件会被复制）
2. 切勿使用 Pages Router（仅支持 App Router）
3. 切勿使用 AI SDK v4（存在破坏性变更）
4. 切勿跳过前置条件（shadcn/ui、Tailwind）
5. 切勿修改核心类型（扩展自 shadcn 类型）
6. 切勿在不使用流式传输的情况下使用（这会失去其用途）
7. 切勿忽略无障碍功能（ARIA 标签）
8. 切勿硬编码样式（使用 Tailwind）
9. 切勿跳过错误处理（API 可能失败）
10. 切勿忽略移动设备（必须支持响应式布局）

---

可用组件（30+）

核心组件：

• Message
• Conversation
• Response
• PromptInput

内容：

• CodeBlock
• Markdown
• Tool
• Reasoning
• Sources

操作：

• Actions
• CopyButton
• ShareButton
• RegenerateButton

高级组件：

• BranchNavigation
• ThinkingDisplay
• WebPreview

---

常见用例

用例 1：基础聊天

const { messages, input, handleInputChange, handleSubmit } = useChat();

return (
  <>
    <Conversation>
      {messages.map(m => (
        <Message key={m.id} role={m.role}>
          <Response markdown={m.content} />
        </Message>
      ))}
    </Conversation>
    <PromptInput value={input} onChange={handleInputChange} onSubmit={handleSubmit} />
  </>
);

用例 2：使用工具调用

{messages.map(m => (
  <Message key={m.id} role={m.role}>
    {m.toolInvocations?.map(tool => (
      <Tool key={tool.toolCallId} name={tool.toolName} args={tool.args} result={tool.result} />
    ))}
    <Response markdown={m.content} />
  </Message>
))}

用例 3：显示推理过程

<Message role="assistant">
  {reasoning && <Reasoning content={reasoning} />}
  <Response markdown={content} />
</Message>

用例 4：显示代码块

<Response markdown={content}>
  {(node) => node.type === 'code' ? (
    <CodeBlock code={node.value} language={node.lang} />
  ) : null}
</Response>

用例 5：显示来源

<Message role="assistant">
  <Response markdown={content} />
  <Sources sources={sources} />
</Message>

---

API 路由

基础流式传输

// app/api/chat/route.ts
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai('gpt-4'),
    messages
  });

  return result.toDataStreamResponse();
}

使用工具

const result = streamText({
  model: openai('gpt-4'),
  messages,
  tools: {
    search: {
      description: 'Search the web',
      parameters: z.object({ query: z.string() }),
      execute: async ({ query }) => {
        return await search(query);
      }
    }
  }
});

---

何时使用 AI Elements

适用于：

• 构建 ChatGPT 风格的界面
• 需要可用于生产环境的组件
• 使用 Vercel AI SDK
• 希望流式传输响应
• 需要显示工具／函数调用
• 希望可视化推理过程

不适用于：

• 不使用 Next.js App Router
• 没有 shadcn/ui
• 需要 Pages Router
• 构建自定义设计系统

---

资源

参考资料（references/）：

• component-catalog.md - 全部 8 个 AI Elements 组件及示例
• example-reference.md - 完整的集成示例和模式
• setup-guide.md - 使用 Next.js 15 和 shadcn/ui 的分步设置指南

模板（templates/）：

• 参考文件中提供了组件示例

---

官方文档

• AI Elements：https://ai-elements.vercel.app
• 组件：https://ai-elements.vercel.app/docs/components
• 示例：https://github.com/ai-elements/ai-elements/tree/main/examples

---

有疑问？遇到问题？

1. 查看 references/setup-guide.md 获取完整设置指南
2. 确认前置条件（Next.js 15+、shadcn/ui、AI SDK v5）
3. 查看官方示例