大多数前端组件库的设计起点是页面需要什么——按钮、表单、表格、导航。但 AI 对话产品的前端需求不是页面驱动的而是交互驱动的。Agent 会思考、会调用工具、会执行多步任务、会引用来源、会生成代码并预览。这些交互形态在传统组件库里找不到对应物。TokUI 内置 150 组件其中 30 多个是专门为 AI 对话场景设计的。这篇文章不讲组件怎么用而是拆解这些组件背后的 UI 语义设计——为什么 AI 对话需要一套全新的组件分类法。一、传统组件库覆盖不了的那 30 种交互如果你拿一个主流前端组件库——无论是 Ant Design 还是 Element Plus——去搭一个 AI 对话产品你会发现核心对话区域几乎全是手写的。组件库里没有AI 消息气泡、没有思考过程折叠面板、没有工具调用状态卡片、没有推理链步骤条。这些交互形态在传统 Web 应用里不存在但在 AI 对话产品里是最高频的 UI 元素。一个典型 AI 对话产品的前端代码中对话区域的组件占比超过 60%——而其中大部分都是开发者从零手写的。根因分析传统组件库的设计视角是页面元素——把一个网页拆成导航、表单、列表、表格等原子单元。但 AI 对话的 UI 单元不是页面元素而是交互事件——Agent 推理了一段内容、调用了一个工具、引用了一个来源、生成了一段代码。每个事件都需要一个专属的 UI 容器来承载。TokUI 的组件分类法把 AI 对话拆成了七类基础展示、表单控件、布局容器、数据展示、图表、AI 对话专属、综合案例。前五类和传统组件库有交集但第六类AI 对话专属是完全独占的。翻看源码中 parser.js 的 CONTAINERS 集合可以清楚看到这套分类的全貌——think、think-chain、think-step、bubble、tool-call、plan、diff、terminal、sandbox、artifact、artifact-code、artifact-preview 等容器类型都是专为 AI 对话场景定义的在传统前端框架中没有对应物。这些容器类型的注册逻辑统一收敛在 components/index.js 的 registerAllComponents 函数中通过 renderer.register 方法以插件化方式挂载。二、Agent 透明度组件让推理过程从黑盒变白盒Agent 产品最大的信任障碍是黑盒问题——用户不知道 Agent 内部做了什么只能看到最终结果。如果结果出错了用户不知道是哪一步出了问题。TokUI 设计了一组专门解决 Agent 透明度的组件它们的核心逻辑是把 Agent 执行过程中的每个关键节点映射为一个可视化组件。思考块组件。可折叠的容器展示 AI 的推理过程文本。默认展开或折叠可控支持流式逐字渲染——AI 在思考时用户能实时看到思考内容的逐步铺展。这个组件的设计直觉是推理过程不应该是最终结果的一部分而应该是独立的、可折叠的上下文。推理链组件。比思考块更结构化把 Agent 的推理拆成多个有序步骤每步有状态标记——pending、running、done、error——以及耗时标注。这个组件解决的问题是用户不仅需要看到 AI 在想什么还需要看到它分了几步想、每一步花了多长时间、哪一步失败了。工具调用卡片。当 Agent 调用一个外部工具时——比如搜索、代码执行、文件读取——工具调用卡片展示工具名称、调用状态、耗时和返回摘要。状态用颜色区分完成是绿色、运行中是动画、错误是红色、被拒绝是灰色。Agent 状态卡片。多 Agent 协作场景下每个 Agent 有自己的状态卡片显示名称、当前动作、状态和耗时。支持流式更新——状态从 running 切换到 done 时卡片颜色实时变化。执行计划组件。把 Agent 的多步任务拆成一个计划清单每步有 pending、running、done、error、skipped 五种状态。用户能看到完整任务规划而不仅仅是最终结果。这五个组件的设计思路有一个共同点它们不展示内容而是展示过程。传统组件库没有这个维度因为传统 Web 应用不存在流式展示过程的需求。三、代码与 Artifact 组件对话即工作台AI 对话产品越来越像一个工作台——用户不仅在对话中获取信息还在对话中生成代码、预览效果、审查变更。TokUI 为这个趋势设计了一组代码与 Artifact 组件。代码差异组件。以红绿着色展示代码变更——新增行绿色、删除行红色、上下文行灰色。内部用原始内容模式方括号等符号不会破坏解析。这个组件的工程难点在于流式渲染AI 输出 diff 内容时[/diff]闭标签的前缀可能先到达解析器需要回持这部分等下一块到齐再决定。终端组件。模拟终端窗口展示命令行输入和输出。带执行状态标记——success 或 error。同样使用原始内容模式内部的反斜杠转义和特殊字符不会干扰解析。代码沙盒组件。可执行 HTML、CSS、JavaScript 的代码容器带实时预览区域。用户在对话中看到 AI 生成的代码同时看到渲染效果。Artifact 组件。侧边预览面板内部用代码槽和预览槽分离展示。AI 可以一边生成代码一边在预览区渲染效果。这个组件对标的是 Claude 的 Artifact 功能但区别在于——它不是产品功能层面的实现而是组件层面的语义化封装任何 AI 对话产品都可以直接使用。文件树组件。展示项目文件结构支持文件夹嵌套和文件状态角标——M 修改、A 新增、D 删除。适合 AI 帮助用户修改项目代码时展示变更范围。插槽委托机制流式渲染中一个隐蔽但关键的工程细节是插槽委托。源码中 renderer 的 _streamOpen 方法对不同容器类型有不同的挂载逻辑——比如 ft 页脚在 card 内部时直接追加到 card 元素而非 body 插槽tab 标签页在 tabs 容器内时渲染器会在 tabs 元素上动态创建 input radio 和 label 标签面板内容追加到 tabs 本身而非默认插槽图表容器内的子节点不渲染为 DOM而是喂给图表组件的 _tokuiChartUpdate 方法做增量重绘。这些委托逻辑通过每个组件 DOM 上的 _variantTarget 属性和 _streamCloseHook 回调实现。像 picker、transfer 这类需要在所有子元素就绪后才能绑定交互的组件通过 _streamCloseHook 把初始化推迟到容器流式关闭时执行——既保证 DOM 完整又不破坏流式的即时性。四、对话上下文组件消息不止于文字AI 对话产品的消息区不只是文字聊天。一条 AI 回复可能包含引用来源、附件、延迟指标、操作按钮等多种上下文信息。TokUI 设计了一组组件来承载这些信息。对话气泡。区分用户和 AI 角色AI 侧可显示模型名和响应时间。气泡内部嵌套的子组件通过渲染器的 slotStack 插槽栈机制自动挂载——渲染器在 mountStreaming 方法中为每个到达的容器节点创建 DOM 并压入栈顶同时在该 DOM 上标记 _slot 内容插入点和 _tokuiType 组件类型后续子节点始终挂到栈顶容器的 _slot。这意味着卡片、表格、图表、思考链可以自然地嵌套在气泡内部不需要开发者手动管理 DOM 层级。引用来源组件。联网搜索场景下AI 回复底部列出参考来源——编号、标题、摘要片段、链接。这个组件的设计解决了 RAG 产品的一个常见问题用户不知道 AI 的回答依据是什么。延迟标记组件。显示首字节时间和吞吐量等性能指标。在追求极致体验的 AI 产品中延迟透明度直接影响用户感知。消息操作栏。气泡底部的操作区支持复制、重新生成、点赞、点踩。支持悬停显示或常驻可见两种模式。快捷回复组件。一行式的建议回复列表用户点击即可发送预设内容。适合在 AI 回复结束后引导下一步对话。欢迎页组件。新会话的欢迎页面包含标题、副标题和功能特性卡片网格。每个特性卡片是自闭合的流式到达时即渲染——不需要等整个欢迎页到齐。五、动态更新机制对话不是静态快照传统组件渲染是一次性的——数据到位后渲染成 DOM之后就不再变化。但 AI 对话是动态的——Agent 在执行过程中会更新状态、追加数据、修改已有内容。TokUI 设计了动态更新组件来解决这个问题。通过更新指令可以修改已渲染元素的值、状态、标题、文本。比如进度条从 0 更新到 50 再到 100、工具调用状态从 running 切换到 done、Agent 状态从执行中切换到完成。工程细节源码中动态更新指令走的是 renderer 的 setAttribute 路径只改目标元素的属性值不触发整棵 DOM 树重渲染。而且更新指令通过 id 属性定位元素本质是一次 DOM 查询加属性赋值——时间复杂度是 O(1)和页面中已有组件数量无关。渲染器的 VARIANTS 白名单还保证了状态更新时的样式一致性比如 plan-step 的 status 从 running 变为 done 时渲染器只在白名单允许的变体范围内切换 CSS 类名不会出现样式冲突。从 JBoltAI 的实践来看这个动态更新机制在实时监控看板场景下尤其有价值。CPU 使用率每秒更新一次流量图逐点增长指标超阈值自动变色——这些效果用更新指令几行 DSL 就能实现不需要引入 WebSocket 或长轮询等复杂机制。六、一个组件设计哲学的判断TokUI 的 30 多个 AI 对话组件背后有一个统一的设计哲学组件的粒度应该对齐 AI 的输出语义而不是对齐页面布局。传统组件库按视觉形态分类——按钮是一类、表单是一类、表格是一类。但 AI 对话的组件应该按交互事件分类——思考是一类、工具调用是一类、代码生成是一类。每种事件对应一个语义化组件组件内部封装了该事件的标准展示形态。这个设计的好处是后端只需要告诉前端发生了什么事件前端自动知道用哪个组件、怎么渲染。开发者不需要为每种事件手写渲染逻辑——组件本身就是渲染逻辑。一个成本洞察传统模式下每新增一个 AI 功能——比如新增加一个 Agent 类型——前端团队需要开发一套对应的展示组件工作量大约 2-3 天。语义化组件模式下后端只需要输出已有的组件 DSL前端零开发工作量。当产品快速迭代、Agent 类型从 3 个增长到 20 个时这个差异会变成数周的工期差距。TokUI 的组件体系不是多了一些组件那么简单。它提出了一种新的组件分类法——以 AI 交互事件为核心维度而非以页面视觉形态为核心维度。这套分类法决定了 AI 对话产品的前端开发模式从手写每个组件走向描述每个事件。