chat-x-kit

Vue 3 插件：在 @blueking/chat-x 之上自带角标、视频播放器、流式输出与可选预置对话的 AI 对话框组件。

特性

• ✅ 零配置安装 —— app.use(ChatXKit) 一行集成，CSS 自动注入
• ✅ 11 种角标 —— pinned / mention / new / unread / read / success / warning / error / info / thinking / video
• ✅ HTML5 视频消息 —— 标题 + 时长 + 大小 + 编码 + 封面 + 描述
• ✅ 流式输出 —— 逐字渲染，可自定义速度
• ✅ Mock 回复 —— 关键词匹配 + 兜底，无后端也能演示
• ✅ Mermaid / LaTeX —— 由底层 @blueking/chat-x 提供
• ✅ 可发布为 npm —— ESM + CJS + IIFE 三种格式

安装

# 业务方项目
npm install chat-x-kit
npm install @blueking/chat-x bkui-vue vue

⚠️ vue / @blueking/chat-x / bkui-vue 是 peerDependencies，需要业务方自行安装。

快速开始

1. 注册插件（推荐）

// src/main.ts
import { createApp } from 'vue';
import ChatXKit from 'chat-x-kit';
// 注意：不用单独 import style.css —— install() 会自动注入
import App from './App.vue';

const app = createApp(App);
app.use(ChatXKit, {
  enableMockReply: true,   // 无后端时开启 mock
  streamCharDelay: 12,     // 流式字符延迟 (ms)
  defaultPrompts: [
    '画一张流程图',
    '用 LaTeX 写下麦克斯韦方程组',
  ],
});
app.mount('#app');

2. 模板里使用

<!-- src/App.vue -->
<script setup lang="ts">
import { ref, shallowRef } from 'vue';
import { ChatXContainer, useChatXStream, useChatXMock } from 'chat-x-kit';
import { demoMessages } from 'chat-x-kit/preset';
import type { Message, Shortcut } from '@blueking/chat-x';

const messages = ref<Message[]>([...demoMessages]);
const stream = useChatXStream({ charDelay: 12 });
const mock = useChatXMock();

async function handleSend(content: any) {
  const text = typeof content === 'string' ? content
    : Array.isArray(content) ? content.map((c: any) => c.text ?? '').join('') : '';
  if (!text.trim()) return;
  await stream.runMock(text, messages.value, mock);
}
</script>

<template>
  <div class="chat-page">
    <ChatXContainer
      :messages="messages"
      :prompts="['画一张流程图', '用 LaTeX 写下麦克斯韦方程组']"
      :shortcuts="shortcuts"
      @send="handleSend"
    />
  </div>
</template>

角标 (Badge)

在消息的 property.extra.badge 字段挂上 BadgeMeta 即可：

import { MessageRole, MessageStatus, type Message } from '@blueking/chat-x';

const msg: Message = {
  id: '1',
  messageId: '1',
  role: MessageRole.User,
  content: '【置顶】请帮我看下这段代码',
  status: MessageStatus.Complete,
  // @ts-expect-error extra 是运行时扩展字段
  property: {
    extra: {
      badge: { variant: 'pinned', text: '📌 置顶' },
    },
  },
} as unknown as Message;

11 种 variant 配色：

| variant | 配色 | 典型场景 | | --- | --- | --- | | pinned | 黄 | 用户置顶提问 | | mention | 红 | @ 我的提醒 | | new | 红 | 新消息 | | unread | 蓝 | 未读计数（带脉动小圆点） | | read | 灰 | 已读 | | success | 绿 | 成功 | | warning | 黄 | 警告 | | error | 红 | 失败 | | info | 蓝 | 提示 | | thinking | 紫 | 深度思考（用在 Reasoning 上） | | video | 深色 | 视频消息角标 |

视频消息 (Video)

在 property.extra.video 挂 VideoMeta：

const videoMsg: Message = {
  id: '2',
  messageId: '2',
  role: MessageRole.Assistant,
  content: '🎬 视频消息示例',
  status: MessageStatus.Complete,
  // @ts-expect-error extra 是运行时扩展字段
  property: {
    extra: {
      badge: { variant: 'video', text: '🎬 VIDEO' },
      video: {
        url: 'https://www.w3schools.com/html/mov_bbb.mp4',
        poster: 'https://example.com/cover.jpg',
        title: 'Big Buck Bunny',
        duration: '0:10',
        size: '0.8 MB',
        description: 'W3Schools 提供的 HTML5 测试视频。',
      },
    },
  },
} as unknown as Message;

视频卡片包含：渐变图标、标题、时长/大小/编码芯片、16:9 播放器、说明文案。

预置对话 (preset)

import { demoMessages } from 'chat-x-kit/preset';
// 22+ 条预置消息，覆盖 Markdown / Mermaid / LaTeX / 角标 / 视频
const messages = ref<Message[]>([...demoMessages]);

preset 是按需引入的（子路径），不会进主包。

自定义发送

const stream = useChatXStream({ charDelay: 12 });

async function handleSend(content, docSchema) {
  // 自己调用后端接口
  const reply = await fetch('/api/chat', { ... }).then(r => r.text());
  // 推一条流式消息
  await stream.runWithPromise(messages.value, reply);
}

或者不传 onSendMessage，自动用 enableMockReply（默认 true）走关键词匹配。

CDN 用法（IIFE）

<!-- 1. 先加载依赖（顺序很重要） -->
<script src="https://unpkg.com/[email protected]/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/@blueking/[email protected]/dist/index.js"></script>
<script src="https://unpkg.com/[email protected]/dist/index.full.min.js"></script>

<!-- 2. 再加载 chat-x-kit（IIFE 产物） -->
<script src="https://unpkg.com/chat-x-kit/dist/chat-x-kit.iife.js"></script>

<script>
  const { createApp, h } = Vue;
  const app = createApp({
    render() {
      return h(ChatXKit.ChatXContainer.default, { messages: [] });
    },
  });
  app.use(ChatXKit.default, { enableMockReply: true });
  app.mount('#app');
</script>

API 速览

<ChatXContainer> Props

| Prop | 类型 | 说明 | | --- | --- | --- | | messages | Message[] | 消息列表（必填） | | prompts | string[] | 快捷问句按钮 | | shortcuts | Shortcut[] | 快捷指令 | | onSendMessage | (content, doc) => string \| Promise<string> | 自定义发送，返回字符串会被流式渲染 | | onStopSending | () => void | 自定义停止 | | onAgentAction | (tool, msgs) => string[] | 工具栏动作 | | enableMockReply | boolean | 是否启用 mock（默认遵循 install options） | | streamCharDelay | number | 字符流式延迟 ms（默认 12） |

Events

| Event | 参数 | 说明 | | --- | --- | --- | | send | (content, doc) | 用户发送 | | stop | () | 用户停止 | | agent-action | (tool, messages) | 工具栏动作 |

Composable

• useChatXStream({ charDelay }) → 流式输出工具集
• useChatXMock({ rules, fallback }) → Mock 回复匹配

类型

• ChatXKitOptions — install 选项
• BadgeMeta / BadgeVariant — 角标
• VideoMeta — 视频
• MockRule — Mock 规则

本地开发

git clone <this-repo>
cd chat-x-kit
npm install
npm run dev      # 启动 playground (http://127.0.0.1:5174)
npm run build    # 跑类型检查 + 两段 Vite 构建 + postbuild
npm run pack:dry # 预览 npm 包内容

路线图

• [ ] 单元测试（vitest）
• [ ] 暗色主题
• [ ] 自定义视频/角标组件注入（slot 覆盖）
• [ ] i18n 字符串注入

License

MIT