@blueking/chat-x

蓝鲸智云 AI Chat 组件库 —— 基于 Vue 3 + TypeScript，遵循 AG-UI（Agent-User Interaction Protocol） 协议规范，为 AI Agent 和人类开发者共同设计的对话 UI 组件库。

提供符合 AG-UI 协议的标准化消息模型、流式消息渲染、Markdown 内容展示、代码高亮、LaTeX 公式、Mermaid 图表、快捷指令、划词选择等一站式 AI 对话能力，并内置 MCP Server 让 AI IDE 直接查询组件文档。

特性

• AG-UI 协议支持 — 基于 AG-UI 开放协议规范构建消息类型系统，标准化 AI Agent 与用户界面之间的交互，支持流式事件、工具调用、多角色消息等协议能力
• AI 优先设计 — 每个组件携带结构化元数据和 AI 专用摘要（aiSummary），内置 MCP Server 让 Cursor 等 AI IDE 通过标准协议直接查询文档
• 流式渲染 — 原生支持 AI 响应的实时流式输出，逐字渲染并自动补全未闭合的 Markdown 语法
• 20+ 消息角色 — 覆盖 User、Assistant、Tool、Reasoning、Activity、Info、Loading 等全部 AI 对话场景，支持 declare global 零侵入扩展自定义角色
• 多级内容管线 — ContentRender → MarkdownContent → CodeContent / LatexContent / MermaidContent，按 token 类型自动分发，支持 180+ 语言代码高亮
• 渐进式组合 — 最小组合 ChatInput + MessageContainer，完整方案 ChatContainer 一行搞定，原子 / 分子分层设计，按需引入
• 快捷指令与斜杠命令 — 内置 / 和 @ 触发的命令系统，支持文本、数字、下拉、复选等表单组件
• 划词选择 — AiSelection 监听页面文本选中，弹出快捷操作浮窗
• 图片与文件 — 文件上传、图片展示、全屏预览、多图管理，内置下载与错误重试
• 类型安全 — 完整的 TypeScript 类型定义，泛型 + 全局类型扩展

安装

# pnpm（推荐）
pnpm add @blueking/chat-x

# npm
npm install @blueking/chat-x

# yarn
yarn add @blueking/chat-x

前置依赖

快速开始

方式一：ChatContainer 一站式方案（推荐）

ChatContainer 封装了 MessageContainer、ChatInput、ShortcutBtns、ShortcutRender 等子组件，内部自动完成消息分组、快捷指令渲染与侧栏 Tab 编排。

<template>
  <div class="chat-page">
    <ChatContainer
      :messages="messages"
      :on-agent-action="handleAgentAction"
      :menu-sources="menuSources"
      :on-send-message="handleSendMessage"
      :on-stop-sending="handleStopSending"
      :shortcuts="shortcuts"
      @update:model-value="val => (userInput = val)"
    />
  </div>
</template>

<script setup lang="ts">
  import { ref as deepRef, shallowRef } from 'vue';
  import {
    ChatContainer,
    MessageRole,
    MessageStatus,
    type IInputMenuItem,
    type IToolBtn,
    type Message,
    type Shortcut,
    type TagSchema,
    type UserMessage,
  } from '@blueking/chat-x';

  const messages = deepRef<Message[]>([]);
  const userInput = shallowRef<string | TagSchema>('');
  // 输入框菜单统一数据源：按 type 分发到 "/"、"@"、"\" 与左下角 + 号
  const menuSources = shallowRef<IInputMenuItem[]>([
    { id: 'prompt-code', name: '写代码', type: 'prompt', content: '帮我写一段代码' },
    { id: 'kb-ops', name: '运维知识库', type: 'knowledgebase' },
  ]);
  const shortcuts = shallowRef<Shortcut[]>([
    { id: 'ask', name: '问问小鲸', description: '向 AI 助手提问' },
    { id: 'code-review', name: '代码审查', description: '让 AI 审查你的代码' },
  ]);

  const handleSendMessage = async (content: UserMessage['content'], docSchema: TagSchema) => {
    messages.value.push({
      id: `user_${Date.now()}`,
      messageId: `user_${Date.now()}`,
      role: MessageRole.User,
      content,
      status: MessageStatus.Complete,
    });
    userInput.value = '';

    const aiMessage: Message = {
      id: `ai_${Date.now()}`,
      messageId: `ai_${Date.now()}`,
      role: MessageRole.Assistant,
      content: '',
      status: MessageStatus.Streaming,
    };
    messages.value.push(aiMessage);

    // 替换为实际 SSE / WebSocket 调用
    const reply = '这是一个 **Markdown** 回复。\n\n```javascript\nconsole.log("Hello!");\n```';
    for (const char of reply) {
      await new Promise(r => setTimeout(r, 20));
      aiMessage.content += char;
    }
    aiMessage.status = MessageStatus.Complete;
  };

  const handleStopSending = async () => {
    const last = messages.value.at(-1);
    if (last) last.status = MessageStatus.Stop;
  };

  const handleAgentAction = async (tool: IToolBtn) => {
    if (tool.id === 'like') return ['回答准确', '信息全面', '表达清晰'];
    if (tool.id === 'unlike') return ['信息错误', '回答不相关', '解释不清楚'];
  };
</script>

<style scoped>
  .chat-page {
    display: flex;
    height: 100vh;
    background: #fff;
  }
</style>

方式二：自定义组合（进阶）

如需完全控制布局，可单独使用 MessageContainer + ChatInput + useMessageGroup。

<template>
  <div class="chat-page">
    <MessageContainer
      :messages="messages"
      :message-groups="messageGroups"
      :on-agent-action="handleAgentAction"
    />
    <ChatInput
      :model-value="userInput"
      :on-send-message="handleSendMessage"
      :on-stop-sending="handleStopSending"
      @update:model-value="val => (userInput = val)"
    />
  </div>
</template>

<script setup lang="ts">
  import { computed, ref as deepRef, shallowRef } from 'vue';
  import {
    ChatInput,
    MessageContainer,
    MessageRole,
    MessageStatus,
    useMessageGroup,
    type Message,
    type TagSchema,
    type UserMessage,
  } from '@blueking/chat-x';

  const messages = deepRef<Message[]>([]);
  const userInput = shallowRef<string | TagSchema>('');

  const { messageGroups } = useMessageGroup({
    messages: computed(() => messages.value),
    selectedUserMessages: deepRef(undefined),
  });

  const handleSendMessage = async (content: UserMessage['content']) => {
    messages.value.push({
      id: `user_${Date.now()}`,
      messageId: `user_${Date.now()}`,
      role: MessageRole.User,
      content,
      status: MessageStatus.Complete,
    });
    userInput.value = '';
    // ...发送 AI 请求并流式追加响应
  };

  const handleStopSending = async () => {
    const last = messages.value.at(-1);
    if (last) last.status = MessageStatus.Stop;
  };

  const handleAgentAction = async () => {};
</script>

AG-UI 协议

@blueking/chat-x 的消息类型系统基于 AG-UI（Agent@blueking/[email protected] Interaction Protocol） 协议规范构建。AG-UI 是一个开放的、轻量级的、基于事件的协议，标准化了 AI Agent 后端与用户前端之间的实时双向通信。

协议栈定位

AG-UI 与 MCP、A2A 构成互补的三层 Agent 协议栈：

┌─────────────────────────────────────────┐
│            用户界面 (Frontend)            │
└──────────────────┬──────────────────────┘
                   │ AG-UI — Agent ↔ 用户交互
┌──────────────────┴──────────────────────┐
│            AI Agent (Backend)            │
├──────────────────┬──────────────────────┤
│ MCP — Agent ↔ 工具/数据  │ A2A — Agent ↔ Agent │
└──────────────────┴──────────────────────┘

• AG-UI：连接 Agent 与用户界面，处理消息流、状态同步、工具调用展示
• MCP：连接 Agent 与工具/数据源
• A2A：协调分布式 Agent 间的通信

chat-x 中的 AG-UI 实现

组件库在 src/ag-ui/types/ 中实现了 AG-UI 协议的核心类型定义：

所有组件（MessageRender、ContentRender、ChatInput 等）均基于这套 AG-UI 类型系统进行消息分发和渲染，确保前端 UI 与 Agent 后端的交互遵循统一的协议规范。

核心概念

消息角色（MessageRole）

通过 declare global { interface AIBluekingMessageMap } 注册自定义消息角色，类型自动合并到 Message 联合中。

消息状态（MessageStatus）

Pending → Streaming → Complete / Error / Stop

消息结构（Message）

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

const message: Message = {
  id: 'msg-1',
  messageId: 1001,
  role: MessageRole.User,
  content: '你好，请介绍一下蓝鲸智云',
  status: MessageStatus.Complete,
};

组件一览

消息展示

输入交互

内容渲染

文件与图片

工具与反馈

辅助组件

Composables 组合式函数

类型导入

import type {
  Message,
  UserMessage,
  AssistantMessage,
  ReasoningMessage,
  ToolMessage,
  InfoMessage,
  LoadingMessage,
  ActivityMessage,
  GuideMessage,
  SystemMessage,
  Shortcut,
  ShortcutComponent,
  IToolBtn,
  TagSchema,
  InputContent,
  UploadFile,
  ImageItem,
  IInputMenuItem,
  MenuItemType,
  MenuTrigger,
} from '@blueking/chat-x';

常量导入

import {
  MessageRole,
  MessageStatus,
  MessageContentType,
  CONST_MESSAGE_TOOLS, // AI 消息默认工具：复制、重新生成、分享
  CONST_USER_MESSAGE_TOOLS, // 用户消息默认工具：复制、编辑、删除
  CONST_UPDATE_TOOLS, // 更新工具：点赞、不满意、删除
} from '@blueking/chat-x';

架构概览

ChatContainer                          ← 一站式对话布局
├── MessageContainer                   ← 消息列表容器
│   ├── MessageRender × N             ← 按 role 分发渲染
│   │   ├── UserMessage               ← 用户消息
│   │   ├── AssistantMessage           ← AI 回复
│   │   │   ├── ContentRender          ← 内容分发
│   │   │   │   └── MarkdownContent    ← Markdown 解析
│   │   │   │       ├── CodeContent    ← 代码高亮
│   │   │   │       ├── LatexContent   ← LaTeX 公式
│   │   │   │       └── MermaidContent ← 图表
│   │   │   └── ToolcallRender × N    ← 工具调用卡片
│   │   ├── ReasoningMessage           ← 推理过程
│   │   ├── ActivityMessage            ← 活动消息
│   │   └── LoadingMessage             ← 加载动画
│   ├── MessageTools                   ← 消息工具栏
│   └── ScrollBtn                      ← 返回底部
├── ShortcutBtns                       ← 快捷指令引导
├── ShortcutRender                     ← 快捷指令表单
├── ChatInput                          ← 输入区
│   ├── InputMenuPanel                 ← 统一菜单（/ @ \ 与 + 号共用）
│   ├── AiSlashInput                   ← 富文本编辑区（触发符识别 + 资源标签）
│   └── InputAttachment                ← 底部工具栏（+ 号 / 快捷指令 / 模型 / 发送）
└── SelectionFooter                    ← 多选操作栏

数据流：ChatInput → onSendMessage → 业务层 API → AG-UI Message[] 写入 → useMessageGroup 分组 → MessageContainer 按 role 分发渲染

扩展

自定义消息类型

通过 TypeScript 声明合并扩展消息角色，在 MessageRender 的默认 slot 中渲染自定义组件：

declare global {
  interface AIBluekingMessageMap {
    chart: BaseMessage<'chart', { type: string; data: unknown[] }>;
  }
}

工具栏定制

通过 onAgentAction / onUserAction 回调处理工具按钮点击，messageToolsStatus 控制按钮的禁用/隐藏，like/unlike 返回反馈原因数组。

主题定制

CSS 变量 + useGlobalConfig 统一调整全局展示配置。

MCP Server

@blueking/chat-x 内置 MCP Server，供 AI IDE（如 Cursor）通过标准协议查询组件文档。

配置

在 Cursor 的 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "chat-x": {
      "command": "npx",
      "args": ["@blueking/chat-x"]
    }
  }
}

可用工具

依赖说明