AI 组件库-MateChat 快速起步与核心概念

MateChat 快速起步与核心概念

一、MateChat 是什么？

MateChat 是一套 面向 AI- 聊天/智能助手场景的 Vue 3 组件库，已在华为 CodeArts、InsCode 等内部产品中落地。它强调开箱即用、多场景匹配与多主题适配，让你像拼积木一样把大模型能力嵌进任何前端页面。

二、环境准备

依赖	版本建议	说明
Node.js	≥ 18	Vite 官方脚手架默认支持
包管理器	npm / pnpm	任意
前端框架	Vue 3 + TS	组件内部使用 `<script setup`>

三、三步跑通 Hello-MateChat

以下内容全部来自官方"快速开始"示例，删掉了日志、样式等与核心逻辑无关的部分。你可以直接 copy 到一个全新的 Vite 项目中。

1. 安装依赖

bash 复制代码

pnpm create vite@latest      # 新建 vue-ts 项目
cd my-mate-chat-demo
pnpm i vue-devui @matechat/core @devui-design/icons
pnpm run dev

2. 全局注册组件库（main.ts）

vue 复制代码

import { createApp } from 'vue'
import './style.css'
import App from './App.vue'

import MateChat from '@matechat/core';
import '@devui-design/icons/icomoon/devui-icon.css'; // 图标库

createApp(App).use(MateChat).mount('#app')

3. 最小示例（App.vue）

vue 复制代码

<script setup lang="ts">
</script>

<template>
  <div>
    <McBubble :content="'Hello, MateChat'" :avatarConfig="{ name: 'matechat' }"/>
  </div>
</template>

<style scoped>

</style>

已能渲染出单条聊天气泡。

四、完整对话 Demo

下面这段官方示例把 MateChat 的 布局、输入、消息、提示 四大类组件都串了起来。复制进 App.vue 即可得到多轮对话、快捷提问、消息分流等常见功能：

typescript 复制代码

<template>
  <McLayout class="container">
    <!-- 顶栏 -->
    <McHeader :title="'MateChat'" :logoImg="logo" />

    <!-- 欢迎页 / 对话区二选一 -->
    <McLayoutContent v-if="startPage" class="center">
      <McIntroduction :logoImg="logo2" title="MateChat" subTitle="Hi，欢迎使用 MateChat" />
      <McPrompt :list="introPrompt" direction="horizontal" @itemClick="onSubmit" />
    </McLayoutContent>

    <McLayoutContent v-else class="content">
      <template v-for="(msg, i) in messages" :key="i">
        <McBubble :content="msg.content" :align="msg.from === 'user' ? 'right' : 'left'"
          :avatarConfig="msg.from === 'user' ? userAvatar : modelAvatar" />
      </template>
    </McLayoutContent>

    <!-- 输入区 -->
    <McLayoutSender>
      <McInput :value="input" :maxLength="2000" @change="v => input = v" @submit="onSubmit" />
    </McLayoutSender>
  </McLayout>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const logo = 'https://matechat.gitcode.com/logo.svg'
const logo2 = 'https://matechat.gitcode.com/logo2x.svg'
const userAvatar = { imgSrc: 'https://matechat.gitcode.com/png/demo/userAvatar.svg' }
const modelAvatar = { imgSrc: logo }
const startPage = ref(true)
const input = ref('')
const messages = ref<{ from: 'user' | 'model'; content: string }[]>([])
const introPrompt = [{ label: '帮我写一个快速排序' }, { label: '你可以帮我做些什么？' }]

function onSubmit(text: string) {
  if (!text) return
  startPage.value = false
  messages.value.push({ from: 'user', content: text })
  // 临时代码：回显
  setTimeout(() => messages.value.push({ from: 'model', content: text }), 200)
  input.value = ''
}
</script>

<style scoped>
.container {
  width: 800px;
  margin: 24px auto;
  height: calc(100vh-48px);
  display: flex;
  flex-direction: column;
}

.center {
  display: flex;
  flex: 1;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 12px;
}

.content {
  flex: 1;
  display: flex;
  flex-direction: column;
  gap: 8px;
  overflow: auto;
}
</style>

五、核心组件概括

组件	组件 / 对象	描述
Layout	McLayoutMcHeaderMcLayoutContentMcLayoutSender	提供「顶栏-内容-输入栏」三段式布局
Bubble	McBubble	渲染单条消息气泡
Prompt	McPrompt	常用提问/指令快捷按钮
Input	McInput	用户编辑并提交文本
Introduction	McIntroduction	欢迎页/空态页信息面板
Message 对象	{ id, from, content, loading }	描述一次用户/模型发言；可扩展流式加载

六、接入 DeepSeek 大模型

MateChat 不关心模型实现，只要你在 onSubmit 里按需 发送请求 ➜ 拆分响应 ➜ 填充 messages 即可。

1. 安装 openai

bash 复制代码

npm install openai

2. Vue Demo

typescript 复制代码

<template>
  <McLayout class="container">
    <!-- 顶栏 -->
    <McHeader :title="'MateChat'" :logoImg="logo" />

    <!-- 欢迎页 / 对话区二选一 -->
    <McLayoutContent v-if="startPage" class="center">
      <McIntroduction :logoImg="logo2" title="MateChat" subTitle="Hi，欢迎使用 MateChat" />
      <McPrompt :list="introPrompt" direction="horizontal" @itemClick="onSubmit" />
    </McLayoutContent>

    <McLayoutContent v-else class="content">
      <template v-for="(msg, i) in messages" :key="i">
        <McBubble :content="msg.content" :align="msg.from === 'user' ? 'right' : 'left'"
          :avatarConfig="msg.from === 'user' ? userAvatar : modelAvatar" />
      </template>
    </McLayoutContent>

    <!-- 输入区 -->
    <McLayoutSender>
      <McInput :value="input" :maxLength="2000" @change="v => input = v" @submit="onSubmit" />
    </McLayoutSender>
  </McLayout>
</template>

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

const logo = 'https://matechat.gitcode.com/logo.svg'
const logo2 = 'https://matechat.gitcode.com/logo2x.svg'
const userAvatar = { imgSrc: 'https://matechat.gitcode.com/png/demo/userAvatar.svg' }
const modelAvatar = { imgSrc: logo }
const startPage = ref(true)
const input = ref('')
const messages = ref<{ from: 'user' | 'model'; content: string }[]>([])
const introPrompt = [{ label: '帮我写一个快速排序' }, { label: '你可以帮我做些什么？' }]
// 修改 apikey
const client = new OpenAI({ apiKey:'sk-xxx', baseURL:'https://api.deepseek.com/v1', dangerouslyAllowBrowser:true })

async function fetchData(question:string){
  messages.value.push({ from:'model',content:'',loading:true })
  const idx = messages.value.length - 1

  // 流式读取
  const stream = await client.chat.completions.create({
    model:'deepseek-reasoner',
    messages:[{ role:'user', content:question }],
    stream:true
  })
  messages.value[idx].loading = false
  for await (const chunk of stream){
    messages.value[idx].content += chunk.choices[0]?.delta?.content || ''
  }
}

async function onSubmit(text: string) {
  if (!text) return
  startPage.value = false
  messages.value.push({ from: 'user', content: text })
  await fetchData(text)
  input.value = ''
}
</script>

<style scoped>
.container {
  width: 800px;
  margin: 24px auto;
  height: calc(100vh-48px);
  display: flex;
  flex-direction: column;
}

.center {
  display: flex;
  flex: 1;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  gap: 12px;
}

.content {
  flex: 1;
  display: flex;
  flex-direction: column;
  gap: 8px;
  overflow: auto;
}
</style>

七、常见问题

问题	可能原因 / 解决办法
组件样式错乱	忘记引入 @devui-design/icons/icomoon/devui-icon.css 或者项目里存在全局 CSS Reset 覆盖
流式读取卡顿	浏览器需在 HTTPS 环境下才能稳定保持 EventStream；本地调试可先关闭流式 (stream:false)
Prompt 没反应	记得监听 @itemClick 并手动调用 onSubmit；组件本身不会帮你发请求

引用

MateChat