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 dev2. 全局注册组件库（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 openai2. 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；组件本身不会帮你发请求 |