项目分析:ui-common
1. 项目概览
ui-common 是一个 Monorepo 仓库,包含了一系列为 Infinilabs 生态系统设计的 React 包、组件和应用程序。它专注于为 AI 驱动的交互(聊天、搜索、发现)和数据可视化提供统一的 UI/UX。
2. 架构与技术栈
核心技术
- 包管理器:
pnpm(使用 workspaces) - 构建工具:
Vite(快速开发,支持库模式构建) - 框架:
React(v18+) - 语言:
TypeScript - 样式:
- CSS 引擎:
UnoCSS/Tailwind CSS(原子化 CSS) - 组件库:
Ant Design(通用 UI),Elastic EUI(数据密集型组件)
- CSS 引擎:
- 状态管理:
Zustand(轻量级全局状态),React Context - 国际化:
i18next/react-i18next
包结构
项目在 packages/ 目录下分为几个包:
| 包名 | 描述 | 关键特性 |
|---|---|---|
AIChat | 主要的 AI 聊天应用/挂件。 | 编排聊天流程,处理流式响应,管理聊天历史,并与后端 API 集成。使用 ChatMessage 进行渲染。 |
ChatMessage | 核心消息渲染库。 | 处理复杂消息类型:Markdown、代码块、DeepResearch (可视化规划/研究步骤)、DeepRead 和 QueryIntent。 |
AIAnswer | 简化的 AI 回答组件。 | 可能用于在其他上下文中嵌入单轮问答。 |
Attachments | 文件附件管理。 | 用于上传和显示文件附件的组件。 |
CommandCenter | 全局命令面板 / 启动器。 | 提供类似 "Spotlight" 的界面,用于快速操作和导航。 |
Discover | 数据发现与可视化模块。 | 集成 Elastic EUI 和 Monaco Editor。似乎是复杂数据探索工具(类似 Kibana)的迁移或封装。 |
Filter | 筛选组件库。 | 专门用于筛选数据的输入控件(选择、滑块、日期范围等)。 |
DatePicker | 高级日期/时间选择器。 | 支持绝对、相对和快速选择时间范围(类似于 Kibana/Grafana)。 |
CustomIcons | 图标管理系统。 | 图标选择器和上传功能。 |
3. 核心亮点与创新
🌟 深度研究可视化 (ChatMessage)
该项目具有复杂的“Agentic”工作流可视化功能。DeepResearch 组件 (packages/ChatMessage/src/components/DeepResearch) 不仅仅展示文本,它还可视化了 AI 的内部思维过程:
- 状态机: 解析特定块类型的流 (
research_planner_start,research_researcher_start等) 以重构 AI 的状态。 - 分步 UI: 显示当前阶段(规划 -> 研究 -> 报告)以及进度指示器。
- 交互式: 允许用户查看 AI 正在搜索的内容及其找到的来源。
🚀 乐观更新与流式聊天 (AIChat)
- 实时流式传输: 高效处理分块响应,随着数据到达更新 UI。
- 复杂消息类型: 不仅支持文本,还支持“思考”块 (
<Think>)、“阅读”状态 (<DeepRead>) 和结构化产物。
🎨 混合 UI 系统
- Ant Design + EUI: 该项目成功集成了 Ant Design(在企业应用中流行)和 Elastic EUI(专门用于数据工具)。这使其能够利用两者的优势——Antd 精致的组件和 EUI 强大的数据可视化工具——尽管这可能需要仔细的 CSS 管理。
⚡ 现代构建流程
- 基于 Vite: 从 Webpack(主要)迁移到 Vite,以获得更快的 HMR 和构建速度。
- 库模式: 包作为库构建 (
es,cjs),并自动生成dts(vite-plugin-dts),使其可供其他应用程序使用。
4. 挑战与困难
🔧 ESM 与 CommonJS 兼容性
挑战: Discover 包包含依赖 CommonJS 特性(如 require('react'))的依赖项,这在纯 ESM 环境(Vite)中使用时会中断。 解决方案: 我们通过在 vite.config.ts 中配置 commonjsOptions 来转换混合模块,并确保构建输出正确处理互操作性来解决此问题。
📦 Monorepo 发布与依赖
挑战: 管理内部包之间的依赖关系(例如 AIChat 依赖 ChatMessage)并将它们发布到注册表。 解决方案:
- Workspace 协议: 使用
pnpmworkspaces 进行本地开发。 - 构建顺序: 需要仔细的构建顺序(在
AIChat之前构建ChatMessage)。 - 发布配置: 为现代消费者正确配置
package.json导出 (types,import,require)。
🧠 复杂状态派生
挑战: “深度研究”功能接收线性块流,但需要呈现结构化的嵌套状态(计划 -> 步骤 -> 搜索结果)。 解决方案: deriveDeepResearchState 函数充当 reducer,实时从扁平事件流中重构复杂的树状状态。
🌍 遗留代码集成
挑战: Discover 包包含一个带有遗留 Webpack 配置的 common 文件夹,表明正在从类似 CRA 的设置迁移到现代 Vite monorepo。 解决方案: 将遗留代码包装在 Vite 构建过程中,使其与现代技术栈的其余部分兼容。
5. 总结
ui-common 是一个成熟、现代的 React 代码库,解决了 AI 领域的复杂 UI 挑战。它超越了简单的“聊天机器人”,提供了 AI 推理和研究过程的丰富、交互式可视化,同时保持了可重用的组件架构。
