上周我给一个AI Agent项目搭前端做到凌晨两点的时候没忍住骂了自己一句一个聊天页面而已怎么感觉比后端接大模型还累。后端也好、Spring AI也好无非是把模型API包一层真正让人崩溃的是界面——对话流、流式打字、markdown渲染、代码高亮、复制按钮、思考过程、工具调用状态、多会话切换全得自己从零搓。那天晚上刚好刷到 Ant Design 的 AI 组件库新版本发布的消息第二天直接把手写的聊天页面全推了重写。用下来的体感就是我标题里那四个字太好用了。这篇文章把这几天的接入过程、组件拆解、踩坑记录和扩展思路整理出来给正在做AI聊天、AI编程、Agent平台、AIGC工具前端的朋友一个参考。1. AI产品前端为什么这么难写先说说背景1.1 通用组件库和对话场景的错位在做AI应用之前我写了快十年React后台Ant Design那套表格、表单、弹窗用得滚瓜烂熟。但第一次做对话类产品时我发现一个很扎心的事实传统后台的UI是静态数据展示而AI对话是动态消息流。这两者的渲染模型完全不一样。传统列表页是数据拿到了再渲染最多加个loading态而对话页面从用户点下发送按钮那一秒开始页面就在持续变化先出现用户消息然后出现正在输入的占位接着模型输出一个token一个token地往外蹦中途还可能要展示正在调用工具正在搜索知识库正在生成代码这些过程状态。用最原始的setState去管这些东西不是不行只是你会发现自己写了大量跟业务无关的胶水代码消息数组管理、滚动定位、流式解析、错误重试、会话持久化。这些代码每个AI项目都要写一遍而且写得还不一样。更麻烦的是markdown渲染。模型输出的是markdown里面经常夹着代码块、表格、数学公式代码块还要高亮、要复制按钮。通用组件库不可能帮你内建这些因为它们面向的是后台管理系统不是对话应用。1.2 为什么不能直接把现有聊天插件拿来用也许有人会说网上开源聊天前端一抓一大把何必等Ant Design出AI组件。我试过几个流行的方案感受是能跑但绑得太死。有的聊天插件把消息格式、接口协议、状态管理全固定了接自己的后端要改源码有的是纯展示层没有输入框、没有思考链路、没有多会话管理等于是个半成品。我在这个项目里的实际诉求其实很明确前端只是一个交互壳后端可能是自建大模型网关可能是Spring AI包的Java服务也可能是团队自研的Agent框架。前端不应该关心模型是什么、用什么协议流式返回它只需要把用户输入→过程状态→模型输出这件事漂亮地、稳定地呈现出来。这正好是 Ant Design 这套AI组件库的定位它既是一套组件也是一套给AI产品用的设计规范。1.3 这套AI组件库在Ant Design体系里的位置简单说它是Ant Design 5.x基础上的一个独立组件库用起来像一套积木把AI产品界面拆成了几个标准模块消息气泡负责展示对话输入框负责收集内容思维链负责呈现模型推理和工具调用过程会话列表负责多轮对话管理欢迎页和提示词组件负责冷启动引导。拆开看每个组件都不复杂合在一起基本覆盖了主流AI产品界面的全部场景。我后来回想这套东西最值钱的不是某个组件写得有多炫而是它把AI产品的界面长什么样这件事做成了标准化答案。你不用再纠结气泡左右布局、输入框多高、思考过程怎么折叠这些细节直接站在它的肩膀上做业务。2. 核心组件逐个拆解哪些真正能救命2.1 Bubble消息气泡里的流式与富文本处理Bubble是我用得最多的组件它承担的职责是一条消息怎么显示。看起来简单实际要考虑的东西很多角色不同气泡位置不同、头像不同消息内容可能是纯文本、markdown、经过二次处理的ReactNode消息还在生成中要有打字效果消息下面要挂复制、点赞、点踩等操作按钮。Bubble把这些都做成了属性而不是让你自己搭结构。比较关键的是typing属性。做对话界面如果等后端全部返回完再渲染用户会以为页面卡死了所以要么后端做流式返回、前端逐段渲染要么前端用打字机效果模拟。typing参数控制的就是这个打字动效配合后端SSE或fetch流式读取可以让文字像大模型官方那样逐字出现体验直接上一个档次。富文本方面Bubble提供了一个messageRender的插槽。我没直接用它的默认渲染而是接入了react-markdown加rehype-highlight这样代码块能高亮表格能正常展示还顺手加了代码块的复制按钮。这种默认可用、关键处可替换的设计是我最喜欢的地方。2.2 Sender输入框不只是输入框老式聊天的输入框就是一个textarea加一个发送按钮但AI产品对输入框的要求远不止这些用户打字到一半可能想传图片传附件发送过程中要能取消按住Enter发送、ShiftEnter换行这种快捷键得支持还要有禁用态防止后端还在处理时用户重复提交。这些都是Sender现成的能力。我用的比较多的一个组合是Sender加Attachments。用户上传参考图片、PDF、代码文件附件列表会以卡片形式挂在输入框上方前端拿到文件列表后随消息一起提交给后端多模态接口整套交互不需要我自己写文件选择器和缩略图逻辑。做过多模态输入的人应该懂这个组件能省下多少工作量。顺带一提Sender支持自定义actions就是输入框右侧那排按钮。我这边把默认的语音按钮换成了清空对话和停止生成生产环境用下来很顺手。这种细节不强制你接受默认交互而是把控制权留给你接入业务速度非常快。2.3 ThoughtChain把模型的思考过程讲给用户听这是整套组件里我最想安利的一个。现在的大模型应用早就不是用户问一句、模型答一句这么简单了。做Agent的时候模型要规划步骤、调用工具、查看结果、再组织答案这个过程如果一片黑盒用户会非常不安总觉得系统是不是卡死了。ThoughtChain就是把这条思维链可视化出来的组件。每个节点叫一项可以配置标题、描述、状态状态支持pending、success、error三种正好对应用户等待、工具执行成功、工具报错三种情况。实际项目中我用它展示Agent的完整链路先搜索知识库再读取相关文件然后生成代码最后执行验证。每个节点有loading动画和耗时统计用户一眼就知道系统在干什么焦虑感瞬间下降。它还有个细节叫折叠能力。思考过程在页面上不应该喧宾夺主用户想看完整推理时会展开平时只显示当前正在执行的这一步。我刚接入时还担心这类组件会跟气泡列表在滚动上打架实测它是独立于气泡区的布局上放在气泡上方完全兼容。2.4 Conversations、Welcome、Prompts把单聊升级成完整应用如果只有一个聊天窗口很多项目其实用不上这三个组件。但只要你想做多会话AI助手或者面向用户的Agent平台它们就是刚需。Conversations负责左侧会话列表支持分组、重命名、删除切换会话时自动把历史消息加载出来我再也不用自己维护一套会话CRUD的UI。Welcome是登录后的空状态页有Logo区、标题和描述我会把产品的一句话介绍放在这里再配几个推荐问题。Prompts是提示词卡片点击之后自动填入输入框等于把常用的提问模板做成了快捷键。这三个组合起来的效果是用户打开产品后第一眼就知道这是个AI助手该怎么用而不是面对一个光秃秃的对话界面发呆。对于AI产品经理来说这种开箱即用的冷启动体验比写十页用户手册都管用。组件与场景的对应关系我整理成了一张表组件解决的核心问题典型场景Bubble消息展示、流式打字、富文本、操作按钮对话记录区Sender输入、发送、取消、快捷键、多模态附件底部输入区ThoughtChain推理过程、工具调用、执行状态可视化Agent思考链路Conversations多会话管理、历史记录、分组左侧会话列表Welcome空状态引导、首发体验登录后的首页Prompts提示词快捷入口、模板引导欢迎页、快捷指令区3. 上手实操从零搭一个能跑的AI对话页3.1 环境准备和安装我的项目是Vite加React 18加TypeScript组件库要求React不低于18这个现在基本都能满足。安装就一条命令npm install ant-design/x antd需要注意antd是它的基础依赖项目里原本没有antd的话要一起装上。装完建议在入口文件确认一下全局样式没有冲突Ant Design本身是css-in-js方案不太需要额外import样式文件但如果你的项目之前用了别的UI库要留意全局reset的顺序。3.2 最基础的一版完整返回式对接如果后端暂时不做流式只是调用完大模型一次性返回文本那么接入非常简单。用内置的useXChat来管理消息数组和请求状态import { Bubble, Sender, useXChat } from ant-design/x; export default function ChatPage() { const { messages, onRequest, status } useXChat({ request: async ({ messages }) { const res await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ messages }), }); return await res.text(); }, }); return ( div style{{ height: 100vh, display: flex, flexDirection: column }} div style{{ flex: 1, overflow: auto }} Bubble.List items{messages.map((m) ({ key: m.id, placement: m.role user ? end : start, content: m.content, }))} / /div Sender loading{status loading} onSubmit{onRequest} placeholder有什么想问的 / /div ); }这段代码跑起来一个完整的问答界面就有了用户消息靠右、模型回复靠左、发送期间输入框转圈禁用、消息列表自动滚动到底部。我第一版就是这个结构前后不超过二十分钟。Bubble.List帮我把滚动定位和列表渲染优化掉了手写的话这些至少得折腾两小时。3.3 升级版接入流式输出和思考链路完整返回式的体验还差点意思尤其是模型生成大段代码或长文时用户等得心焦。我的做法是在后端加了一个SSE接口前端用fetch流式读取把chunk不断喂给气泡。流式对接的核心代码长这样import { Bubble, Sender, ThoughtChain, useXChat } from ant-design/x; export default function ChatPage() { const { messages, onRequest, status } useXChat({ request: async ({ messages }, callbacks) { const res await fetch(/api/chat-stream, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ messages }), }); const reader res.body.getReader(); const decoder new TextDecoder(); let text ; while (true) { const { done, value } await reader.read(); if (done) break; text decoder.decode(value, { stream: true }); callbacks.onUpdate(text); } return text; }, }); return ( div style{{ height: 100vh, display: flex, flexDirection: column }} div style{{ flex: 1, overflow: auto }} ThoughtChain items{[ { key: search, title: 搜索内部知识库, status: success }, { key: generate, title: 生成回答, status: status loading ? pending : success }, ]} / Bubble.List items{/* messages 映射同上 */} / /div Sender loading{status loading} onSubmit{onRequest} / /div ); }这里的callbacks.onUpdate会在每次读到新chunk时触发气泡内容随之更新视觉效果就是文字在流式出现。我实测过只要后端SSE格式对前端这套代码完全不需要关心协议细节组件内部已经把节流和状态同步处理好了。3.4 和Spring AI等后端框架的配合建议近期接触了不少用 Spring AI 做后端的团队他们的典型架构是Java服务统一管理模型适配、提示词模板、工具调用然后通过REST接口或SSE暴露给前端。在我看来前端用这套AI组件库和后端是Spring AI还是自研网关完全不冲突因为对接点只有一个HTTP接口协议。我建议团队里把接口统一成两种一种是非流式/api/chat返回纯文本一种是流式/api/chat-stream返回text/event-stream。前端组件对这两种协议都支持得很好后端无论接OpenAI、通义、智谱还是本地部署的大模型都只是在这一层做适配。这样前后端的边界非常清晰谁来改模型都不影响界面。还有个实践很多团队在做大模型本地部署前端需要配置不同的模型地址和参数。这时可以把request函数里的fetch地址、模型名、temperature都做成配置项用全局状态管理。前端代码不变只需要切换配置就能在多个模型间切换对测试和演示都很有用。4. 实际接入踩过的坑版本、流式、样式与状态4.1 版本依赖冲突和打包体积控制我踩的第一个坑是版本冲突。项目里原本就有antd但版本偏旧安装ant-design/x之后构建直接报警提示存在多个antd实例。查下来发现是peerDependencies没对齐npm把新版antd装到了嵌套目录里。解决办法是删掉node_modules和lock文件重新安装确保全局只有一个antd版本如果你用的是pnpm建议在.npmrc里配置public-hoist-pattern[]*antd*之类的提升规则实测能避免大部分冲突。第二个坑是打包体积。组件库默认按需引入但如果你在入口一次import了很多组件bundle会明显变大。我的做法是路由级懒加载只有AI应用相关的页面才加载这些组件后台管理页面完全不受影响。再加上React 18的并发特性实际用户体感上没有明显卡顿。4.2 流式渲染的性能陷阱流式输出不是接到chunk就无脑setState那样会引发两个问题一是更新频率太高React频繁重渲染低端设备上输入框都跟着卡二是markdown解析开销大每来一个token就把整个文本重新解析一遍长回答后期会明显掉帧。我给的优化方案是节流。在request函数里对onUpdate做一层时间控制大约每30到50毫秒才更新一次UI肉眼完全看不出区别CPU占用却能降一大截。另一个技巧是markdown解析不要放在组件渲染链路上用useMemo缓存解析结果只在文本真正变化时才重新解析。实测下来一段三千字的回答不做任何优化时页面滚动和输入框交互会有可感知的迟滞做了节流和缓存之后全程稳定在流畅档位。这个优化经验在文本模型、代码模型上都有效值得提前做。4.3 主题定制和暗黑模式没有想象中麻烦Ant Design生态的好处是主题体系是统一的。AI组件库默认跟随antd的主题配置你只要在ConfigProvider里设置theme气泡、输入框、思维链的颜色会一起变。我做暗黑模式时设了algorithm: theme.darkAlgorithm整站自动切换不需要给AI组件单独写一套暗色样式。唯一需要手工调的地方是气泡背景的层级感。默认配置下用户气泡和AI气泡的颜色对比不够明显我在theme token里微调了colorPrimaryBg和colorFillQuaternary让两种气泡在暗色背景上区分度更高。另外ThoughtChain的折叠面板在暗色模式下默认的边框有点淡我用styles属性补了一条分隔线视觉上清晰很多。4.4 会话状态管理别把消息都放在组件里这个坑是我做完第一个版本之后才发现的。我最初把消息数组放在页面组件内部的state里结果一刷新就没了切到别的会话再切回来也没了。后来改成用全局状态管理我选的是zustand把会话列表、当前会话ID、每个会话的消息数组都放进去配合localStorage持久化体验才完整。这里有一个容易被忽略的点流式生成过程中如果用户切走会话再切回来流式状态应该能恢复。我的处理方式是流式更新的同时写store并且给消息打上生成中标记切换会话时如果存在生成中的消息提示用户等待完成或者手动取消。这套方案虽然不算复杂但如果不提前设计后面会改得很痛苦。踩坑和应对方案我整理成了一张简表问题表现对策依赖版本冲突构建报多个antd实例统一版本、清理lock文件、pnpm提升Bundle体积偏大首屏加载慢路由懒加载、按需引入流式更新卡顿滚动和输入掉帧30~50ms节流、缓存markdown解析暗黑模式对比度低气泡区分不明显微调theme token会话刷新丢失消息列表清空全局状态管理加localStorage5. 这套工具还能怎么扩展从聊天框到Agent工作台5.1 给AI编程工具做前端面板俗话说得好AI编程类工具是目前最卷的方向之一。这类工具的前端除了对话和代码展示还要展示正在读取哪个文件改了哪个函数跑了什么测试这类工具调用过程。ThoughtChain在这种场景下是天然的杀手锏把每一步操作都变成一个状态节点用户对Agent的信任感会强很多。我曾经给一个内部代码助手做过原型左侧Conversations列会话中间Bubble展示代码块和diff顶部ThoughtChain展示Agent的思考链路底部Sender接收指令。整个架子搭下来只花了一个下午。你甚至可以在这个基础上把AI编程里常用的提示词模板放进Prompts组件比如解释这段代码修复这个bug写单元测试用户点一下就发出指令产品化程度直接翻倍。5.2 AI绘画、视频生成类应用的提示词工作台AI绘画和AI视频生成工具的火爆程度不用多说这类产品的前端核心是用户输入提示词→生成结果图片/视频→在对话中回显。这里Sender加Attachments的组合特别合适用户可以上传参考图也可以直接在输入框里写详细的提示词生成进度用Bubble的loading态展示历史生成记录变成一个个气泡形成完整的创作时间线。甚至做AI短剧脚本、AI短视频自动生成这类工具时也可以复用同样的交互骨架。用户输入故事梗概前端展示生成的分镜脚本、画面描述、旁白文本每个脚本块用Bubble承载旁边挂上重新生成导出等操作按钮。界面统一开发成本低用户可以很快上手。5.3 面向垂直行业的Agent通用交互层最后一层是真正的通用能力把这套组件组合成一个完整的AIAgent工作台页面不管后端是什么框架、Agent在编排什么能力前端都只需要对接消息和状态。我现在的做法是把页面结构做成可配置的不同业务的Agent只需要配置Prompts的推荐问题、Welcome的品牌信息、ThoughtChain的节点文案页面整体复用。如果你团队里有AI产品经理我特别建议让TA也看看这套组件的设计理念。它能帮产品团队快速界定一个AI应用需要哪些交互模块一个需求评审时说不清的空状态、加载态、错误态在这套组件里全都有现成的对应物。PM可以基于组件画原型前端可以直接把原型变成页面沟通成本低得不是一星半点。最后再分享一个小技巧接这套组件库之前先把你的后端流式协议定好最好统一成标准的SSE格式data: {content:xxx}\n\n这种。前端组件对标准协议的支持最顺不要自造二进制协议不然上高新特性的时候还得自己写解析器。我在实际项目里就是先统一了协议后面加工具调用、加思考链路都只改前端配置后端几乎没有动过。Ant Design这套AI组件库目前还在快速迭代如果你的项目正好在起步阶段建议直接拿它当底子省下来的时间和头发都是自己的。