一、背景：云原生前端从“能用”走向“聪明好用”

在云原生早期，前端更多是把各类 API 的“配置项”和“状态”表现出来：
控制台、运维平台、CI/CD 面板，能查、能配、能点，就算完成任务。

但现在情况已经明显不同：

• 业务复杂度

  • 多集群、多 Region、多租户
  • 资源对象越来越多：集群、节点、工作负载、服务网格、安全策略……

• 智能化诉求

  • 日志希望有人帮“粗看一遍”，只把可疑点挑给我
  • 告警希望有人帮“分组归因”，给出优先处理顺序
  • 配置希望通过“自然语言描述”就能自动生成一份表单 / YAML 草稿

这两股力量叠加，逼着前端从单纯的“界面层”升级为一个 “体验+智能协作”的综合层”。

在这条升级路径上：

• DevUI 负责给我们一套稳定、统一、可扩展的 企业级中后台 UI 方案——包括设计体系、组件库和实践范式。
• MateChat 则带来一个面向 GenAI 场景的前端智能化 UI 库，专门解决“在各种工具里如何放一个好用、不违和的 AI 助手”的问题。

接下来，我们先把“地基”打牢——从 DevUI 讲起。🏗️

官方链接汇总如下，一键直达：

• MateChat：https://gitcode.com/DevCloudFE/MateChat
• MateChat官网：https://matechat.gitcode.com
• DevUI官网：https://devui.design/home

二、DevUI：企业级界面层的“地基工程”

2.1 DevUI 是什么：一套面向中后台的前端解决方案

从官方站点和仓库来看，可以把 DevUI 概括为三句话：

1. 定位：面向企业中后台产品（云控制台、管理系统、研发工具等）的 开源前端解决方案。

2. 形态：同时提供

   • 一套统一的设计体系 DevUI Design（规则、设计语言、最佳实践）

   • 两条主技术栈版本：

     • Angular 版本：ng-devui
     • Vue3 版本：Vue DevUI / vue-devui

3. 目标：让“设计师专注体验、前端专注逻辑”，统一企业内部中后台界面风格、交互范式和组件实现。

✅ 对征文要求的呼应：

• DevUI 主要版本为 Angular 与 Vue 版本 —— 这也是下文示例重点覆盖的技术线。
• 文章内容围绕官方能力展开，不引入臆造的 API 或组件。

DevUI 更像是一套“企业 UI 操作系统”，而不是一个零散的控件集合。

2.2 组件进阶攻略：高频表格 / 表单 / 弹层的工程化使用

在任何一个云管平台或 DevOps 系统里，你打开页面十秒内一定能看到三个东西：

• 数据表格（资源列表）
• 表单（创建 / 编辑向导）
• 弹层（详情、确认、选择器）

DevUI 在这三类组件上的抽象已经非常成熟，但想“用得高级又不踩坑”，还是有不少工程层面的小技巧。

2.2.1 表格：从“能列出来”到“能驾驭大数据”

DevUI 在 Angular/Vue 两条线，都提供了功能丰富的表格组件，支持：
排序、过滤、固定列、树形结构、行/列拖拽、可编辑单元格、分页、虚拟滚动等。

假设有一个典型场景：集群节点列表，需求大概是：

• 支持按照状态 / 节点池 / 可用区过滤
• 支持 CPU / 内存 使用率排序
• 点击行可展开查看 Pod / 容器信息
• 一次可能展示上万行数据

在这种场景下，几条“生存经验”很关键：

1. 前后端协同分页 + 条件查询是底线

   • DevUI 表格负责展示与交互，数据量控制交给后端。
   • 分页、排序、过滤参数都作为 Query 一部分传给后端。

2. 大表格必须开启虚拟滚动或分段加载

   • 否则 DOM 一多，浏览器就开始“风扇起飞”。
   • Angular 场景可配合 cdk-virtual-scroll 等技术；Vue 场景通过列表虚拟化方案减轻压力。

3. 不要在模板里写重逻辑函数

   <!-- 反例：模板中反复执行复杂计算 -->
   <td>{{ computeHealthStatus(row) }}</td>
   

   • 这种写法会在变更检测中被频繁触发，极易成为性能瓶颈。
   • 建议预先在数据加工阶段算好字段，用纯字段绑定。

4. 树形表格适用于“层级资源视图”

   • 例如“集群 → 节点 → Pod → 容器”的分层展示，可使用 DevUI 提供的树表格 / 嵌套行能力来承载。
   • 折叠状态不要全部展开，以免首屏太重。

2.2.2 表单：从“填空题”到“配置编排器”

在 DevOps/云管场景里，一个创建表单往往意味着一个复杂的资源配置过程，例如：

• 创建 Deployment：描述副本数、镜像、环境变量、资源限制、挂载卷、探针等
• 创建流水线：配置触发规则、阶段、任务、通知策略等

DevUI 提供了各类输入组件：输入框、选择器、日期时间、开关、滑块、多选等。

但真正落地时，建议按以下思路升级：

1. Schema 驱动，而不是纯手搓表单布局

   • 针对复杂资源类型，用一份 JSON Schema 或自定义 DSL 描述字段：

     • 字段类型、默认值、校验规则、是否必填、依赖条件、字段分组等

   • 由统一的“表单渲染器组件”去解释 Schema，并渲染 DevUI 的具体控件。

   • 好处是后续扩展字段时，不用频繁改前端模板。

2. 校验逻辑一分为二：即时反馈 + 最终兜底

   • DevUI 表单做“即时体验”：必填、格式、范围等校验，让用户边填边得到反馈。
   • 重要约束（例如配额、资源上线等）仍交给后端再次校验，确保不会被绕过。

3. 可视化配置与 YAML 模式双向同步

   • 许多高阶用户习惯直接编辑 YAML / JSON，而初学者更偏向可视化表单。

   • 可以利用 DevUI 的代码编辑器组件 + 表单组件，提供“表单 ⇄ YAML”的互相转换：

     • 表单改动自动生成 YAML。
     • 粘贴 YAML 自动解析成表单字段（解析失败要给友好提示）。

涉及官方展示如下：

2.2.3 弹层：不止是“确认”，而是一种任务容器

DevUI 的弹层（Dialog/Modal/Drawer）在 B 端里几乎无处不在：

• 新建资源向导
• 批量编辑
• 快速查看详情
• 复杂筛选面板

“好用的弹层”通常有几个特点：

1. 弹层内部逻辑单一，易于复用

   • 建议抽象为独立组件（例如 ClusterCreateDialog），只专注一件事。
   • 父组件只负责“开/关弹层 + 接收结果”。

2. 扩展能力交给插槽 / TemplateRef

   • 子组件定义好基本结构，预留插槽或内容 Projection（Angular 中用 ng-template）来让业务注入额外字段。
   • 这样在多个产品线复用时，只需在不同场景填入不同内容即可。

3. 与表格深度组合：弹层表单、弹层选择器

   • 例如“选择关联资源”、“挑选用户/角色”等，使用 DevUI 的表格 + 分页 + 搜索嵌入弹层中。
   • 统一暴露“已选数据”给父组件，从而形成一套标准的“选择器模式”。

涉及官方展示如下：

2.3 自定义组件与插件：把 DevUI 变成“业务语言”

DevUI 给的是基础构件；真正要服务业务，还得在它之上堆一层“领域组件”。

可以把这层称为：Biz 组件层。

2.3.1 业务组件命名与边界

推荐在团队内部统一一套命名规范，例如：

• BizClusterSelector：集群选择器
• BizNamespaceCascader：命名空间级联选择器
• BizAlarmPolicyEditor：告警策略编辑器
• BizPipelineDesigner：流水线编排器

这些组件内部 全部使用 DevUI 的基础组件，但对外只暴露少量业务语义化的属性/事件：

// 示例：集群选择器可能只暴露如下接口：
props: {
  value: string[];            // 选中集群 ID 列表
  mode: 'single' | 'multi';   // 单选/多选
}
events:
  - update:value
  - change(clusterList)

这样，对上层页面来说：

• 不再关心“用的是哪个下拉组件、是否多选、样式怎么配”，
• 只关心“我要选一批集群”。

这就是让 DevUI 说“业务语言”的过程。

2.3.2 按领域拆分组件包

在大型组织中，建议将 Biz 组件进一步按业务拆包：

• @company/devui-biz-observability —— 监控、告警、日志相关组件
• @company/devui-biz-devops —— 流水线、制品、环境管理组件
• @company/devui-biz-security —— 策略、访问控制组件

每个包内部：

• 引入 DevUI（Angular 或 Vue 版本）
• 实现该领域通用的“业务组件和页面骨架”
• 对外以 npm 包形式统一发布

这样，将 DevUI 真正变成了企业级的 “UI 基础设施 + 领域资产”。

这样，一次主题切换就能覆盖整个系统，包括 DevUI 官方组件和你们自定义组件。

2.4 主题、暗黑与响应式：多产品、多场景的一致体验

界面风格一旦跨产品线不统一，用户会非常敏感：“这个明明是同一家的云，怎么感觉 UI 完全不像同一个团队做的？”🤔

DevUI 在这件事上给了我们完整的“工具箱”。

2.4.1 DevUI 主题体系：从设计稿到可切换主题

DevUI 官方站点和 Vue DevUI 文档都强调了 主题和设计体系的整合：

• 颜色、字号、间距等统一抽象为主题变量
• 支持通过 CSS 变量 / 主题包进行重定义
• Vue DevUI 提供 devui-theme 相关能力，方便切换与配置

通常可以走这三步：

1. 梳理品牌色板

   • Primary / Success / Warning / Danger / Info
   • 以及背景、边框、文字的基础色级别

2. 建立主题映射表

   • 将品牌色与 DevUI 主题变量一一映射，并沉淀成主题配置文件。
   • 例如“标准控制台主题”、“深色 IDE 主题”、“营销后台主题”等。

3. 实现运行时主题切换

   • 使用 CSS 变量 + data-theme 实现无刷新切换。
   • DevUI 组件跟随变量变化自动更新样式。

2.4.2 暗黑模式与 IDE 风格

MateChat 官方说明其主题能力是 基于 vue-devui 主题化能力实现的，支持如 IDE 风主题。

这意味着：

• DevUI 的暗黑主题和 MateChat 的 ide-dark 样式是可以对齐的
• 对于在线 IDE / 代码平台，可以让编辑器、控制台、AI 助手统一使用类似 VS Code 风格的深色主题
• 用户切换“浅色 / 深色”，两者同时响应

前端可以通过：

• 根元素挂 data-theme="dark"
• 统一设置 DevUI + MateChat 使用同一套主题变量
• 个别组件再进行少量补充样式，保证整体观感统一

2.4.3 响应式布局：从大屏控制台到嵌入式窗口

云原生前端不一定永远跑在全屏浏览器里，还会出现：

• 嵌在其它平台中的 iFrame 小窗
• 日志分析工具的嵌入面板
• 平板 / 小屏笔记本访问

DevUI 的栅格系统和 Flex 布局可以应对大部分适配需求：

• 栅格用于“主内容 / 侧栏 / 工具栏”的布局
• Flex 用于卡片内部结构调整（列表 + 侧边详情等）
• 对于 MateChat 这样的侧边对话区域，可以在窄屏下自动收缩为“悬浮按钮 + 抽屉式对话框”

2.5 云原生场景落地：控制台 / DevOps / B 端系统实战拆解

我们用一个虚构的云原生平台 “NebulaCloud” 来串一下 DevUI 在几个典型场景的落地形态（方便你后面改成自己公司的名字 😄）。

2.5.1 云控制台：集群视图与资源治理

页面骨架：

• 顶部：全局导航 + 搜索框 + 用户菜单

• 左侧：资源导航（集群、节点、工作负载、服务、网络、安全策略、监控、告警……）

• 主内容区：

  • 上半部分：资源筛选条件 + 关键指标概览（用 DevUI 卡片 + 图表）
  • 下半部分：DevUI 表格展示资源列表
  • 详情 / 编辑通过 Drawer 或 Dialog 呈现

DevUI 承担的角色：

• Layout / Menu / Breadcrumb / Tabs：构建主骨架
• Table / Pagination / Tree / Tag / Tooltip：承载资源列表
• Form / Select / DatePicker：承载筛选条件和表单配置
• ECharts 组件（Vue DevUI 提供）承载监控曲线和统计图表

2.5.2 DevOps 平台：流水线与制品管理

在 DevOps 场景中，DevUI 的优势体现在：

• “长流程 + 多阶段 + 状态丰富”的 UI 表达能力
• 通过步骤条、时间轴、状态 Badge、进度条等组合出清晰的流水线视图

典型页面：

• 流水线列表：表格 + 筛选 + 状态组件

• 流水线详情：

  • 上部：当前运行状态、最近一次执行结果
  • 中部：阶段视图（DevUI Steps / Timeline）
  • 下部：执行日志（可结合代码编辑器组件做高亮展示）

2.5.3 一般 B 端系统：运营后台 / 权限管理 / 内部工具

DevUI 的定位本身就包括企业中后台，因此非常适合作为统一的“运营后台套件”：

• 快速搭建 CRUD 页面
• 使用统一的表单风格与校验体系
• 封装一套权限管理界面（角色、菜单、权限点）
• 与后端 RBAC/ABAC 体系协同

2.6 从 0 到 1 的 DevUI 实战路径（Angular & Vue 双线）

这一节我们不写“教科书式 Quick Start”，而是从工程视角给一条更贴近真实项目的路径。

2.6.1 Angular 线：基于 ng-devui 的中后台项目雏形

官方推荐使用 @angular/cli + ng-devui 来构建 Angular 版 DevUI 应用。

Step 1：脚手架初始化

npm install -g @angular/cli
ng new nebula-console
cd nebula-console
npm install ng-devui @devui-design/icons

Step 2：在根模块中引入 DevUI

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { DevUIModule } from 'ng-devui';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    DevUIModule
  ],
  bootstrap: [AppComponent]
})
export class AppModule {}

Step 3：搭一个最小“控制台壳子”

<!-- app.component.html -->
<d-layout>
  <d-aside width="240px">
    <d-menu mode="vertical">
      <d-menu-item>集群</d-menu-item>
      <d-menu-item>工作负载</d-menu-item>
      <d-menu-item>流水线</d-menu-item>
    </d-menu>
  </d-aside>

  <d-layout>
    <d-header>
      <div class="header-bar">
        <span class="logo">NebulaCloud</span>
        <div class="header-tools">
          <d-input style="width: 260px" placeholder="全局搜索" />
          <d-avatar dTooltip="admin">A</d-avatar>
        </div>
      </div>
    </d-header>

    <d-content>
      <d-card>
        <d-card-header>集群列表</d-card-header>
        <d-card-content>
          <d-datatable [dataSource]="clusterList">
          </d-datatable>
        </d-card-content>
      </d-card>
    </d-content>
  </d-layout>
</d-layout>

Step 4：迭代往里“塞功能”而不是推翻重来

• 第一次迭代：只做静态数据 + 简单分页
• 第二次：接入真实后端 API，支持排序、过滤
• 第三次：增加弹出层详情，接入 DevUI 表单组件
• 第四次：加上主题切换、权限控制、操作日志等

这种渐进式方式非常友好，对团队上手压力也小。

2.6.2 Vue 线：基于 Vue DevUI 的 Vite 项目

Vue DevUI 官方文档提供了基于 Vite + Vue3 + TS 的示例路径。

Step 1：初始化项目并安装依赖

npm create vite nebula-devops --template vue-ts
cd nebula-devops
npm install vue-devui @devui-design/icons devui-theme

Step 2：入口文件引入 Vue DevUI

// main.ts
import { createApp } from 'vue';
import App from './App.vue';

import DevUI from 'vue-devui';
import 'vue-devui/style.css';
import '@devui-design/icons/icomoon/devui-icon.css';

const app = createApp(App);
app.use(DevUI);
app.mount('#app');

Step 3：构建一个 DevOps 首页骨架

<template>
  <d-layout>
    <d-aside width="220px">
      <d-menu mode="vertical">
        <d-menu-item>项目</d-menu-item>
        <d-menu-item>流水线</d-menu-item>
        <d-menu-item>制品仓库</d-menu-item>
      </d-menu>
    </d-aside>

    <d-layout>
      <d-header>
        <div class="top-bar">
          <span class="logo">Nebula DevOps</span>
          <d-button type="primary" @click="createPipeline">新建流水线</d-button>
        </div>
      </d-header>

      <d-content>
        <d-card>
          <template #header>流水线列表</template>
          <d-table :data="pipelines">
            <d-column field="name" header="名称" />
            <d-column field="project" header="项目" />
            <d-column field="status" header="状态" />
          </d-table>
        </d-card>
      </d-content>
    </d-layout>
  </d-layout>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const pipelines = ref([
  { name: 'build-console', project: 'nebula-console', status: '成功' },
  { name: 'deploy-prod', project: 'nebula-core', status: '运行中' }
]);

const createPipeline = () => {
  // TODO: 打开创建流水线弹层
};
</script>

往后你可以：

• 接入路由，将菜单与路由绑定
• 添加面包屑、过滤器、批量操作、卡片视图等
• 再在这个基础上嵌入 MateChat，变成“自带 AI 助手的 DevOps 平台”（下半场就讲这个 💡）

2.7 DevUI × 可视化 × 低代码：让“配置界面”也能很聪明

DevUI 不只是“UI 组件”，还经常扮演 低代码平台的物料基础，以及可视化监控、报表的统一容器。

2.7.1 可视化看板：AI 运维指标一目了然

在 AI 相关场景里，有一些典型指标：

• 模型 QPS / 延迟分布
• Token 消耗
• 命中知识库回答 vs 大模型自由生成的比例
• 不同业务线 / 团队的使用量

可以利用 DevUI 提供的 ECharts 集成、卡片组件和布局能力：

• 上层用栅格系统做 “多卡片 + 多图表” 布局
• 卡片内部嵌入折线图、柱状图、饼图
• 通过 Tag / Badge 表示当前是否超出阈值

把这些做成统一的“AI 能力运营看板”，可为后续 MateChat 智能体验迭代提供数据依据。

2.7.2 DevUI 与低代码可视化平台结合

社区中已有将 Vue DevUI 作为 低代码组件物料 的实践。

如果你们内部也有类似低代码 / 表单引擎平台，可以考虑：

• 把 DevUI 封装为拖拽组件模块
• 让产品 / 运营通过拖拽搭建简单配置页、报表页
• 对复杂场景仍由开发基于 DevUI 手写

最终在企业内形成一条链路：

设计体系（DevUI Design） → 组件库（DevUI） → 领域组件（Biz） → 低代码物料 → 具体应用

到这里，上半场 DevUI 差不多讲完，我们已经有了一套 稳定的 UI 底座 + 领域组件 + 主题体系。
接下来要让它“动”起来、“聪明”起来，就轮到 MateChat 登场了 🚀。

三、MateChat：智能交互层的“体验总控”

实际使用效果如下：

3.1 MateChat 的角色：前端智能化场景解决方案 UI 库

根据 MateChat 官网与 Git 仓库，它的定位可以拆成几层：

1. 性质：

   • 前端智能化场景解决方案 UI 库
   • 完全开源，MIT 协议，可企业级免费使用

2. 能力边界：

   • 提供的是 一组 GenAI 交互体验组件（对话气泡、输入区、头部、快捷操作、卡片模板等）
   • 不自带模型服务、不封装后端 SDK，也不会替你管理 API Key
   • 官方文档中对接模型的示例（如使用 openai 包）只是前端如何调用模型 API 的 demo，属于“项目方自己的逻辑”，并不是 MateChat 自带 SDK

3. 设计理念：

   • 体验无边界，业务无侵害 —— 尽量不打破原有业务布局，用“外挂”的方式融入
   • 针对 DevOps、IDE 等研发工具场景有专门适配
   • 聚焦 快速唤醒 / 轻松使用 / 自由表达 / 过程可监督 / 可读性强 五大要点（官网有完整表述）

4. 技术基础：

   • 主题系统基于 vue-devui 的主题化能力 实现，与 DevUI 设计体系天然对齐
   • 支持多种主题，适配例如 IDE 风格、深色模式等

这意味着：

在 DevUI 搭好的中后台界面里，我们可以“无缝”塞入一个 MateChat，对话体验在视觉上不会突兀，在情境上也能自然融入。

浅色主题效果：

现在我们已经完成了主题的自定义，来看看效果吧

3.2 搭起第一块“对话砖”：用 MateChat 组装智能助手界面

我们继续沿用上面的虚构平台：NebulaCloud。
这次要给它加一个统一的智能助手，代号叫：“Nebula Assistant” 😎。

3.2.1 项目集成：Vite + Vue3 + Vue DevUI + MateChat

官方建议基于 Vite + Vue3 + TypeScript。

Step 1：初始化项目（若已用 DevUI，可复用前文工程）

npm create vite nebula-ai --template vue-ts
cd nebula-ai

Step 2：安装 Vue DevUI 与 MateChat

npm install vue-devui @devui-design/icons devui-theme
npm install @matechat/core

这里再次强调：@matechat/core 提供的是 UI 组件；
后续你如果需要调用大模型，可以自己单独 npm install openai 或接入自家网关的 SDK，不是 MateChat 自带 SDK。

Step 3：在入口文件中引入 DevUI 与 MateChat 样式

import { createApp } from 'vue';
import App from './App.vue';

import DevUI from 'vue-devui';
import 'vue-devui/style.css';
import '@devui-design/icons/icomoon/devui-icon.css';

// MateChat 样式
import '@matechat/core/style.css';

const app = createApp(App);
app.use(DevUI);
app.mount('#app');

3.2.2 组装基础对话 UI：Header + Bubble + Input

参考官方组件说明（消息气泡、输入框、头部等），我们可以写一个非常聚焦的聊天面板。

<template>
  <div class="assistant-panel">
    <McHeader
      title="Nebula Assistant"
      :logoImg="logo"
      :logoClickable="false"
    >
      <template #operationArea>
        <d-button size="sm" @click="clear">清空对话</d-button>
      </template>
    </McHeader>

    <div class="assistant-body">
      <McBubble
        v-for="(msg, idx) in messages"
        :key="idx"
        :content="msg.content"
        :align="msg.from === 'user' ? 'right' : 'left'"
        :loading="msg.loading"
        :avatarConfig="msg.avatarConfig"
      />
    </div>

    <div class="assistant-input">
      <McInput
        v-model="input"
        placeholder="用自然语言描述你的问题，例如：帮我分析最近 5 分钟某集群的错误日志"
        @submit="handleSubmit"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
// 假定对话组件来自 @matechat/core
// import { McHeader, McBubble, McInput } from '@matechat/core';

const logo = '/nebula-logo.svg';

interface ChatMsg {
  from: 'user' | 'assistant';
  content: string;
  loading?: boolean;
  avatarConfig?: {
    name?: string;
    displayName?: string;
    imgSrc?: string;
  };
}

const messages = ref<ChatMsg[]>([]);
const input = ref('');

const clear = () => {
  messages.value = [];
};

const handleSubmit = async (val: string) => {
  const text = val.trim();
  if (!text) return;
  messages.value.push({
    from: 'user',
    content: text,
    avatarConfig: { displayName: '我' }
  });
  input.value = '';

  // 增加一条“占位”消息，用于流式输出
  messages.value.push({
    from: 'assistant',
    content: '',
    loading: true,
    avatarConfig: { displayName: 'Nebula AI' }
  });

  const idx = messages.value.length - 1;
  await fetchAnswer(text, idx);
};

// 实际调用后端模型服务
const fetchAnswer = async (question: string, index: number) => {
  // TODO: 调用你自己的 BFF / 模型网关 API，支持流式返回更佳
  const fake = `这是对「${question}」的示例回答。你可以在这里接入真实大模型服务。`;
  messages.value[index].content = fake;
  messages.value[index].loading = false;
};
</script>

这里，我们用最简单的方式把 MateChat 组件“拼”起来：

• McHeader 承担整体头部形态
• McBubble 承载每条消息，用左 / 右对齐区分人机
• McInput 提供带提交行为的智能输入区

你只要把 fetchAnswer 换成真实的大模型调用，就拥有了一个真正的 AI 助手界面 🎯。

3.2.3 按官方示例对接大模型（以 OpenAI SDK 为例）

MateChat 官网在“如何接入使用”中给出了对接模型服务的示例，使用 openai 包流式拉取结果。

大致结构如下（注意：这是你项目自己的逻辑，与 MateChat 解耦）：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: '',      // 模型 API Key（自行保密）
  baseURL: '',     // 模型服务地址，可以是内网网关
  dangerouslyAllowBrowser: true
});

const fetchAnswer = async (question: string, index: number) => {
  messages.value[index].loading = true;
  messages.value[index].content = '';

  const completion = await client.chat.completions.create({
    model: 'my-model',
    messages: [{ role: 'user', content: question }],
    stream: true
  });

  for await (const chunk of completion) {
    const content = chunk.choices[0]?.delta?.content || '';
    messages.value[index].content += content;
  }

  messages.value[index].loading = false;
};

MateChat 负责把 messages 渲染得好看、好用；
你负责构造 messages 数组并赋值，这就是两边的边界关系。

3.3 三种嵌入模式：侧边助手 / IDE 面板 / 知识库问答

MateChat 官网和介绍文章中列举了多个适用场景：协作式、沉浸式、情境式等。

结合 DevUI 的页面，我们可以总结出三种非常常见的嵌入方式。

3.3.1 模式一：中后台里的“侧边智能助手”

典型形态：

• 在 DevUI 控制台主布局右侧保留一条窄栏，用来放 MateChat 面板
• 或者使用右下角悬浮按钮 + 抽屉的方式，随时“呼出 / 收起” AI 助手
• 助手默认处于“静默”状态，需要时点一下“AI 帮我看看”按钮启动对话

用户故事示例：

运维在查看某个集群的错误日志时，一键把当前日志片段 + 集群元数据打包，丢给 MateChat，问：“最近这个集群为什么频繁出现 5xx？”
MateChat 读完日志和监控，给出可能的原因和排查步骤。

这种模式下：

• DevUI 负责把当前上下文（选中的资源、日志、指标）组合好
• MateChat 负责对话呈现
• 后端的大模型服务负责真正的“聪明事”

3.3.2 模式二：IDE / 代码平台中的“AI 辅助面板”

MateChat 官网案例里提到 InsCode AI IDE 和华为云 CodeArts 智能助手，就是典型的“IDE 插件 + AI 面板”场景。

布局通常是：

• 左边项目树
• 中间代码编辑器
• 右边 MateChat 窄栏或底部工具面板

MateChat 在这里可以做：

• 解释选中代码
• 帮忙写注释、重构、生成单测
• 根据错误信息给出修复建议

而且它的 IDE 风主题可以保证整体风格与编辑器一致，不像“嵌了一个外站聊天窗口那么违和”。

3.3.3 模式三：知识库 / 文档中心里的“智能问答助手”

在一个 DevUI 构建的文档中心里，可以这样嵌：

• 左侧目录树 + 中间文档内容使用 DevUI 组件展示
• 右侧或底部使用 MateChat，提供“问知识库”入口
• 后端通过 RAG（检索增强生成）根据文档索引返回参考片段

前端的呈现模式：

• 将检索结果通过 MateChat 的卡片组件展示为“引用文档列表”
• 在对话中附上“来自：安装指南 / 故障处理手册”等说明
• 支持一键跳转到相关文档位置

用户只需要记得“找 AI 问就行”，不必一页页翻文档，这对新同学极其友好 👍。

3.4 进阶玩法：智能体、RAG、自然语言生成 UI、工作流与多模态

MateChat 本身不提供 Agent 引擎、RAG 引擎，但它给了我们一个 非常适合承载这些能力的 UI 壳。

下面这几个玩法，可以为论文 / 演讲部分增加“前瞻性”。

3.4.1 智能体（Agent）过程可视化

后端可以使用任意智能体框架（例如自研或基于第三方框架）完成：

• 工具选择（查日志、查监控、改配置）
• 任务规划与多步执行
• 思维链（Chain-of-Thought）管理

MateChat 端可以这样呈现：

• 每一步调用以一条“系统消息 + 卡片”呈现，例如：

  • 「已分析最近 10 分钟的日志，发现 3 处高频报错」
  • 「已为你生成一条回滚流水线草案」

• 使用“时间线 / 步骤卡片”，在对话中以视觉形式展示 Agent 的执行轨迹

• 为关键步骤提供“撤销 / 重新执行 / 查看详情”入口

用户获得的是一个“透明、可控”的 AI 助手，而不是一个“黑箱给结论”的机器人。

3.4.2 RAG + 证据展示：让“AI 答案”更可信

RAG 模型的价值在于引入企业内知识库，但用户常会担心：

它到底是胡编的，还是确实查了内部文档？

MateChat 的解决方案可以是：

• 使用卡片列表展示检索到的文档片段：标题、摘要、来源链接
• 在答案中标注“引用文档”，点击可展开详细内容
• 按照相关度排序，给用户一种“像查 Google 搜索结果 + Chat 总结”的体验

UI 层完全可以用 MateChat + DevUI 的组合来实现：

• 卡片组件承载文档摘要
• Tag / Badge 标识文档类型和重要性
• 展开后使用 DevUI Markdown / 代码高亮组件展示内容细节

3.4.3 自然语言生成 UI（NL → UI）

这是一个特别适合写进“创新探索”的方向：

• 用户对 MateChat 说：

  “帮我建一个限流策略：针对 /api/v1/orders 接口，每秒最多 100 次，请给个配置草稿。”

• 后端模型根据意图生成：

  • 一份 JSON / YAML 配置
  • 或一份“DevUI 表单默认值配置”

前端流程可以是：

1. MateChat 对话中展示一个“配置预览卡片”（YAML/JSON + 概要说明）
2. 用户点击“应用到表单”按钮
3. 跳转到 DevUI 表单页面，自动带入这些默认值，允许最后再修改确认

这样，MateChat 不再只是“解释器”，而是变成 “配置向导”。

3.4.4 工作流与多模态交互

在复杂问题排查中，用户可能需要：

• 上传日志文件 / 截图 / 抓包结果
• 让 AI 帮忙从大量信息里“找重点”

在 MateChat 端：

• 输入区增加“上传文件 / 截图”按钮，交由后端多模态模型处理

• 返回结果用卡片展示，如：

  • “关键错误段落列表”
  • “异常指标时间区间”

• 对于 UI 截图错误，可直接显示“错误框定位 + 可能原因”

多模态本质还是模型能力，MateChat 只要支持在消息结构中扩展“附件信息”和合适的卡片模板即可，非常灵活。

3.5 工程实践：MateChat 无 SDK 的集成思路与边界

最后，再把一个重要点说得绝对清楚一点（也是征文特别强调的地方 ⚠️）：

1. MateChat 本身不提供 SDK 形式

   • 它不是一个“前端一引、后端全搞定”的一站式产品。
   • 它只提供了一整套 前端 UI 组件和交互体验设计。

2. 模型对接完全由业务方掌控

   • 官方文档里演示的是：

     • 你在项目中自行 npm install openai，
     • 然后在自己的代码里调用 openai.chat.completions.create 做流式请求，
     • 最终把返回内容写入 MateChat 的 messages 中。

   • 如果你用的是盘古大模型 / 自建网关 / 其他厂商模型，做法一样：

     • 在前端 / BFF 中使用对应 SDK 或 HTTP 客户端调用。
     • MateChat 完全不感知“背后是谁”。

3. 这反而给了大企业更多可控性

   • API Key 管理、费控、内容审计、调用限流都可以集中在自家网关做
   • MateChat 只负责“交互层呈现”，不会额外引入安全面或耦合风险

工程上，可以把这块抽成一个统一的“AI 网关前端 SDK”，例如：

// ai-gateway.ts
export async function chatWithAI(payload: {
  messages: { role: 'user' | 'assistant' | 'system'; content: string }[];
  stream?: boolean;
}) {
  // 调用自家 BFF / 网关
}

然后 MateChat 集成层只依赖这一个函数，不直接接触任何第三方模型 SDK，这样长期维护成本会更低。

四、DevUI × MateChat：一体化智能前端体系设计

现在我们已经分别讲完 DevUI 和 MateChat，最后把它们合在一起，搭一张“全局蓝图”。

4.1 设计层：统一设计系统 + 双层体验结构

• DevUI Design 作为统一的设计系统与视觉规范：色板、布局、控件形态、交互动效等。

• 页面层全部基于 DevUI（Angular/Vue）构建。

• 智能交互层统一走 MateChat，对话风格、气泡样式、卡片布局也遵守 DevUI 的基础规范。

• 通过主题体系保证：

  • 中后台、IDE、AI 助手看起来是“一家人”
  • 浅色 / 深色 / IDE 风在不同产品中表现一致

4.2 工程层：组件库 + 智能 UI 的模块化治理

推荐采用 monorepo（pnpm / nx 等）统一管理：

packages/
  devui-biz/            # 封装 DevUI 的领域业务组件
  matechat-shell/       # 封装 MateChat + 模型调用逻辑的前端壳
  console-app/          # 云控制台
  devops-app/           # DevOps 平台
  ide-app/              # 在线 IDE
  docs-app/             # 文档中心 / 知识库

• devui-biz 只依赖 DevUI，不关心 AI
• matechat-shell 封装 MateChat 组件与“AI 网关前端 SDK”对接逻辑
• 各个应用按需引入这两个包，用配置来开关 AI 能力

这样做的好处：

• 当 MateChat 升级、设计迭代、主题调整时，只需在 matechat-shell 里调整一次
• 当 DevUI 升级或主题体系更新时，在 devui-biz 中校正一次，各应用统一受益

4.3 架构层：BFF + 智能服务网关

在后端架构上，建议将“传统业务流量”和“智能服务流量”做出清晰分层：

• BFF for Console / DevOps / IDE / Docs：

  • 负责整合业务数据，给前端提供结构化接口

• AI Gateway：

  • 统一代理大模型、RAG、Agent 等能力
  • 集中做认证、限流、审计、敏感信息过滤

在前端：

• DevUI 页面直接调用各自对应的 BFF
• MateChat 只调用 AI Gateway 暴露出的统一接口

4.4 组织层：设计 / 前端 / 算法的三方协作模式

在 DevUI × MateChat 框架下，一种较理想的协同模式是：

• 设计团队：

  • 维护 DevUI Design & MateChat 体验规范
  • 输出组件使用指引、内容规范和对话 UX 规范

• 前端团队：

  • 基于 DevUI 实现业务页面和领域组件
  • 基于 MateChat 实现智能助手 UI 外壳与卡片组件

• 算法 / 后端团队：

  • 负责模型服务、RAG Pipeline、Agent 编排
  • 与前端约定统一的消息协议与工具调用反馈格式

最终效果是：

智能体验不是“算法部门单打独斗”，而是变成 “设计 + 前端 + 算法”三方共同打造的产品能力。

五、结语：从组件库到“智能体验基础设施”

把视角拉远一点，我们会看到这样一条演进路线：

1. 组件库时代：

   • 解决的是“页面怎么快点做出来”的问题。
   • DevUI 在这件事上已经给了完整答案。

2. 设计体系时代：

   • 解决的是“多个系统能不能统一体验”的问题。
   • DevUI Design + Vue DevUI / ng-devui 让中后台不再各自为政。

3. 智能体验时代（正在发生）：

   • 解决的是“如何把 AI 真正嵌入到业务流里，而不是一个玩具入口”的问题。
   • MateChat 以一种“前端智能化场景解决方案 UI 库”的形态，把这件事变成 “一套可复用、可迭代的工程问题”。

对前端团队来说，这既是挑战，也是机会：

• 不再只是“写组件、连接口”，

• 而是可以参与定义：

  • 一家公司 云原生控制台的统一界面标准
  • 一家公司 智能助手在所有产品中的统一形象与交互逻辑

DevUI 帮你把 “界面层的地基” 打稳；
MateChat 帮你搭起 “智能交互的上层结构”；
把这两者串联起来，你做的就不只是一套 UI，而是一套完整的 “智能体验基础设施”。

📝 写在最后

如果你觉得这篇文章对你有帮助，或者有任何想法、建议，欢迎在评论区留言交流！你的每一个点赞 👍、收藏 ⭐、关注 ❤️，都是我持续更新的最大动力！

我是一个在代码世界里不断摸索的小码农，愿我们都能在成长的路上越走越远，越学越强！

感谢你的阅读，我们下篇文章再见～👋

✍️ 作者：某个被流“治愈”过的 Java 老兵
📅 日期：2025-11-19
🧵 本文原创，转载请注明出处。

声明：相关配图及内容部分来源网络，若有侵权，请联系删除。