nextjs-chatbot

生产环境中的 Next.js 聊天机器人

将此技能用于 Web 聊天集成：持久化对话、工具审批、工具结果 UI 和嵌入式小组件。使用 ai-app 进行脚手架搭建，使用 ai-sdk 确认 SDK 版本，使用 ai-elements 了解组件契约。对于多平台消息传递，请参阅 Chat SDK。

沿用项目现有技术栈。根据产品对质量、延迟和隐私的要求，选择模型、推理设置、存储和客户端状态。聊天机器人并非天生就需要 PostgreSQL、Zustand、MCP 服务或每种消息操作。对于尚未做出选择的新项目，默认采用 Bun、基于 shadcn/ui 的 ai-elements、用于服务端历史记录的 Drizzle + PostgreSQL，以及推理力度较低或不进行推理的快速模型，因为聊天延迟就是产品体验的一部分。

阅读已安装的 node_modules/ai/docs/04-ai-sdk-ui/，了解持久化、工具用法、错误和恢复流；若包中包含类型定义和 src/，请使用它们确认准确的契约。 链接中的 ai-sdk.dev 页面是在线备用资料，介绍最新主版本。

集成契约

• 编写 API 调用前，确认 ai、@ai-sdk/react 和提供商的版本匹配。v7 使用 ai-sdk-7，现有的 v6 项目使用 ai-sdk-6；核心回调的重命名并不意味着也要重命名单独的 useChat.onFinish。
• 在服务端验证对话访问权限、校验请求数据并授权工具。客户端历史记录、上下文、模型 ID 和同意标记均不可信；提示词无法强制实现租户隔离或权限控制。
• 如果必须恢复完整的对话 UI，请使用稳定 ID 存储经过校验的 UI 消息。通过已安装 SDK 的辅助函数转换模型历史记录；保留必需的工具调用/结果关系及提供商推理关系。
• 确定取消、断开连接、重新加载和重试时的处理方式。断开连接后继续消费流仍取决于托管环境的生命周期；持久化执行需要受支持的持久化运行时。
• 使用关联 ID 记录脱敏诊断信息。对于失败的 HTTP 请求和流内失败，返回安全的公开错误；响应头发送后，无法再更改 HTTP 状态。默认情况下，UI 流会隐藏普通错误；由提供商执行的工具错误可能绕过 onError，因此也要检查工具错误渲染器。自定义 onError 的返回值会原样传给浏览器；非 2xx 响应会传递给 useChat 的 onError，并以原始响应正文作为错误消息。
• 核实实际代理的流式传输和缓冲配置。SDK 的 UI 消息响应已发送 X-Accel-Buffering: no；自行构建的流（NDJSON/SSE 进度流）则需要此标头和 Cache-Control: no-store, no-transform。该标头对受支持的 nginx 配置有帮助，但无法保证所有主机都能在不缓冲的情况下传输流。

聊天界面

让回答、相关工具结果和有用来源清晰易读。默认布局：用户消息显示在右侧对齐的 bg-muted 气泡中，助手消息占满宽度且不带背景，并让品牌风格延伸到滚动条。根据产品需要添加反馈、重新生成、删除或建议；默认情况下，避免重复显示“回答”标题，也避免每条消息都带有操作工具栏。使用 icons 技能选择图标，并使用 nextjs-shadcn 构建周边界面。

当读者位于底部时，跟随流式输出；当他们滚动离开底部或加载更早的历史记录时，保留其所在位置。适合时使用现有的兼容滚动原语；shadcn 的 消息滚动器 是一种选择； 以用户消息为锚点，让回复在其下方流式输出。 通过应用程序的渲染器渲染 Markdown（默认技术栈中的 ai-elements MessageResponse）， 并默认使用 shadcn Typeset 设置样式（仅 CSS，参见 nextjs-shadcn）； 验证嵌套列表、长链接和代码块的显示效果。

根据 useChat 状态（submitted/streaming）判断轮次是否完成，而不是依据工具之间短暂的间隙。切换对话前应停止或隔离生成。浏览器存储不得导致客户端首次渲染与服务端渲染的同意状态或历史记录不一致。

阅读与此功能相关的内容

• 工具审批：策略、重放安全性和 UI 状态转换。
• 持久化：ID、历史记录重放、反馈和恢复。
• 工具渲染：类型化状态和安全输出。
• 弹窗/嵌入：焦点、滚动和宿主边界。
• 检索：结构化筛选器和经过评估的搜索选项。
• 建议：可选且有依据的后续操作。
• 网页搜索：来源范围、新鲜度和提供方能力。
• 验证：UI 状态转换以及模型/检索评估。

在恢复历史记录后进行第二轮对话，并测试审批与拒绝、工具失败、取消、快速切换对话以及已部署的流式传输路径。报告实际检查过的行为。