@yuworm/agui-antdvn-chat

Vue 3 AI 对话组件库，提供开箱即用的 Chat UI。支持两种使用姿势：纯渲染模式（ChatBox）和一体化模式（ChatClient）。

特性

• 两层架构 — ChatBox 纯渲染层零业务耦合；ChatClient 一体化层配置即用
• 完整对话能力 — 消息列表、流式输出、Markdown 渲染、思维链展示、工具调用卡片、Human-in-the-Loop 确认
• 内置 AG-UI 协议 — useChat composable 内置 AG-UI 流式通信、文件上传、工具执行
• 请求配置 — 支持自定义接口地址、请求头注入、请求拦截器、错误回调
• 丰富插槽 — 11 个插槽覆盖欢迎页、消息渲染、头像、工具确认、操作栏等
• 文件上传 — 支持点击上传、拖拽上传、剪贴板粘贴图片，含文件大小/数量校验
• 主题系统 — 基于 CSS 变量，内置 light/dark 双主题，支持完全自定义
• 零 UI 框架依赖 — 不依赖 Ant Design、Element Plus 等，纯原生 HTML + CSS
• TypeScript — 完整类型定义，开发体验友好

安装

npm install @yuworm/agui-antdvn-chat

Peer Dependencies:

依赖	版本	必需	说明
vue	^3.3.0	是	Vue 3 核心
markstream-vue	^0.0.10-beta.1	是	Markdown 流式渲染
@ag-ui/client	^0.0.47	否	仅 useChat / ChatClient 需要
@ag-ui/core	^0.0.47	否	仅 useChat / ChatClient 需要

快速上手

方式一：ChatClient（推荐，开箱即用）

配置接口地址和请求头即可使用，无需自行管理状态和 API 调用。

<script setup lang="ts">
import { ChatClient } from "@yuworm/agui-antdvn-chat";
import "@yuworm/agui-antdvn-chat/dist/index.css";
import "@yuworm/agui-antdvn-chat/dist/theme/variables.css";

const token = localStorage.getItem("access_token") || "";
</script>

<template>
  <div style="height: 100vh">
    <ChatClient
      agent-url="/api/agui"
      upload-url="/api/upload"
      tool-execute-url="/api/tools/execute"
      :get-headers="() => ({ Authorization: `Bearer ${token}` })"
      :on-error="(e) => console.error(e)"
      thread-id="session-123"
    />
  </div>
</template>

方式二：ChatBox（纯渲染，完全控制）

自行管理消息状态和 API 调用逻辑，组件只负责渲染。

<script setup lang="ts">
import { ref } from "vue";
import { ChatBox } from "@yuworm/agui-antdvn-chat";
import "@yuworm/agui-antdvn-chat/dist/index.css";

const messages = ref([]);
</script>

<template>
  <div style="height: 100vh">
    <ChatBox
      :messages="messages"
      :upload-handler="handleUpload"
      :on-error="handleError"
      @send="handleSend"
      @stop="handleStop"
    />
  </div>
</template>

文档

文档	说明
快速开始	安装、引入样式、ChatClient 和 ChatBox 两种使用方式
API 参考	ChatClient / ChatBox / useChat 及全部子组件的完整 API
类型定义	所有导出类型的详细说明
主题定制	CSS 变量体系、light/dark 主题、完整变量清单
使用示例	ChatClient 集成、自定义插槽、自定义布局等场景

导出一览

组件

组件	说明
ChatClient	一体化组件，内置状态管理 + AG-UI 通信，配置即用
ChatBox	纯渲染入口，包含 MessageList + ChatInput，纯 props/events 驱动
ChatInput	消息输入框（文件上传 / 粘贴图片 / 拖拽）
MessageList	消息列表（自动滚动，支持消息级插槽）
AssistantMessage	助手消息（Markdown / 思维链 / 工具调用）
UserMessage	用户消息气泡
MarkdownViewer	Markdown 流式渲染
ThinkingBlock	可折叠思维链展示
ToolCallCard	工具调用状态卡片
HilConfirm	Human-in-the-Loop 确认
AttachmentPreview	文件 / 图片附件预览

Composable

Composable	说明
useChat(options)	聊天状态管理 + AG-UI 流式通信 + 文件上传 + 工具执行

类型

Message / Attachment / ToolCallRecord / StreamingStatus / PendingFile / ChatBoxProps / ChatBoxEmits / ChatError / UseChatOptions / ChatClientProps / RequestConfig / SendPayload / UseChatReturn

开发

npm install     # 安装依赖
npm run dev     # watch 构建
npm run build   # 生产构建

License

MIT