1. Ant Design X Vue 项目介绍：结构、组件和启动方式

Ant Design X Vue 项目介绍：结构、组件和启动方式

最近在做 Agent 产品时，需要在前端侧选择一套 AI 组件框架。因为公司主流技术栈是 Vue，所以最终选择了 Ant Design X Vue 作为基础方案。它可以帮助我们快速搭建 AI 对话、Copilot、Agent 类产品的前端界面，避免从零开始开发聊天气泡、输入框、会话列表、附件上传、思考过程展示这些通用能力。

这篇文章主要简单介绍一下 Ant Design X Vue 是什么、项目结构怎么看，以及本地怎么启动。

Ant Design X Vue 是什么？

Ant Design X Vue 是 Ant Design X 的 Vue 实现。

Ant Design X 本身是 Ant Design 面向 AI 产品推出的一套组件和设计方案，主要服务于 AI Chat、Copilot、Agent 等场景。

而 Ant Design X Vue 则是在 Vue 技术栈下提供类似能力。

它不是一个完整的业务系统，也不是一个后端 Agent 框架，而是一个 AI 前端组件库。

它主要解决的问题是：

text 复制代码

AI 消息怎么展示？
用户输入框怎么设计？
流式输出怎么承接？
会话列表怎么管理？
附件怎么上传和展示？
提示词怎么呈现？
AI 思考过程怎么展示？
消息上的复制、重试、点赞等操作怎么处理？

如果自己从零开发这些能力，短期看可以，但长期维护成本会比较高。使用组件库的好处是，可以先基于已有能力快速搭出产品原型，再根据业务做二次封装。

适合什么场景？

Ant Design X Vue 比较适合以下场景：

text 复制代码

AI Chat 对话页面
企业内部智能助手
Copilot 类产品
Agent 任务执行界面
知识库问答
代码助手
文档助手
数据分析助手
带附件上传的 AI 对话工具

简单来说，只要产品里有"用户和 AI 对话，并且 AI 会持续返回内容或执行任务"的交互，就可以考虑使用它。

核心组件

这个项目把 AI 交互拆成了很多原子组件。

常见组件包括：

text 复制代码

Bubble：消息气泡
Bubble.List：消息列表
Sender：输入框
Conversations：会话管理
Welcome：欢迎组件
Prompts：提示词列表
Suggestion：快捷建议
Attachments：附件上传和展示
ThoughtChain：思考过程 / 执行过程
Actions：操作按钮
XProvider：全局配置

除了组件之外，它还提供了一些偏逻辑层的能力：

text 复制代码

useXAgent：模型请求调度
useXChat：聊天状态管理
XRequest：请求封装
XStream：流式数据处理

这些能力可以帮助我们把 UI 展示和 AI 请求过程串起来。

比如一个最简单的聊天页面，可能只需要：

vue 复制代码

<script setup lang="ts">
import { Bubble, Sender } from 'ant-design-x-vue';

const messages = [
  {
    content: 'Hello, Ant Design X Vue!',
    role: 'user',
  },
];
</script>

<template>
  <Bubble.List :items="messages" />
  <Sender placeholder="请输入消息" />
</template>

项目整体结构

项目目录大致如下：

text 复制代码

ant-design-x-vue
├── src/                    组件库源码
├── docs/                   文档站和示例
├── play/                   本地 playground，用于快速测试组件
├── resolver/               自动导入 resolver
├── internal/               内部构建工具
├── scripts/                项目维护脚本
├── contributors/           贡献者数据
├── package.json            项目脚本和依赖配置
├── pnpm-workspace.yaml     pnpm workspace 配置
├── vite.config.mts         组件库构建配置
├── vite.config.dist.mts    dist 产物构建配置
└── tsconfig.json           TypeScript 配置

日常开发最常看的目录是：

text 复制代码

src/
docs/
play/

src 目录

src 是组件库源码目录，也是最重要的目录。

它里面基本是一个组件一个目录：

text 复制代码

src
├── actions/          
├── attachments/
├── bubble/
├── conversations/
├── prompts/
├── sender/
├── suggestion/
├── thought-chain/
├── welcome/
├── x-provider/
├── use-x-agent/
├── use-x-chat/
├── x-request/
├── x-stream/
├── theme/
├── _util/
└── index.ts

其中：

text 复制代码

actions              操作按钮组件
attachments          附件上传和文件列表
bubble               消息气泡和消息列表
conversations        会话列表
prompts              提示词组件
sender               输入框组件
suggestion           快捷建议组件
thought-chain        思考过程组件
welcome              欢迎组件
x-provider           全局配置组件
use-x-agent          模型调度 hook
use-x-chat           聊天状态管理 hook
x-request            请求封装
x-stream             流式数据处理
theme                主题和 token
_util                内部工具方法

入口文件是：

text 复制代码

src/index.ts

它负责统一导出组件、hooks、主题能力，并提供 Vue 插件安装能力。

单个组件目录怎么看？

以 Bubble 组件为例，目录结构大致是：

text 复制代码

src/bubble
├── Bubble.vue
├── BubbleList.vue
├── context.ts
├── interface.ts
├── index.ts
├── loading.vue
├── hooks/
└── style/

一般可以这样理解：

text 复制代码

Bubble.vue          组件主体
BubbleList.vue      气泡列表组件
interface.ts        props 和类型定义
index.ts            组件导出和 install 注册
context.ts          组件内部上下文
hooks/              组件内部逻辑
style/              组件样式

所以如果要改某个组件，通常可以按这个顺序看：

text 复制代码

1. index.ts
2. interface.ts
3. 主组件 .vue 文件
4. style/ 样式文件
5. docs/examples 中对应示例

docs 目录

docs 是文档站目录，使用的是 VitePress。

大致结构如下：

text 复制代码

docs
├── component/          组件文档
├── development/        开发介绍文档
├── examples/           文档示例
├── examples-setup/     setup 风格示例
├── playground/         playground 文档
├── public/             静态资源
├── semantics/          语义化结构示例
└── index.md            文档首页

如果你想看某个组件怎么使用，可以重点看：

text 复制代码

docs/component/
docs/examples/

比如 Bubble 的文档和示例：

text 复制代码

docs/component/bubble.md
docs/examples/bubble/basic.vue

文档里一般会通过 demo 标记引用示例：

md 复制代码

:::demo 基础用法。

bubble/basic

:::

这里的 bubble/basic 对应的就是：

text 复制代码

docs/examples/bubble/basic.vue

play 目录

play 是本地 playground，用来快速测试组件。

它是一个很轻量的 Vite + Vue 项目，适合在开发过程中临时写 demo。

目录大致如下：

text 复制代码

play
├── src/
│   ├── App.vue
│   ├── main.ts
│   └── style.css
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

平时如果只是想测试某个组件，直接改：

text 复制代码

play/src/App.vue

例如测试 Bubble：

vue 复制代码

<script setup lang="ts">
import { Bubble } from 'ant-design-x-vue';
</script>

<template>
  <div style="padding: 24px">
    <Bubble content="hello world" />
  </div>
</template>

例如测试 Sender：

vue 复制代码

<script setup lang="ts">
import { Sender } from 'ant-design-x-vue';
</script>

<template>
  <div style="padding: 24px">
    <Sender placeholder="请输入消息" />
  </div>
</template>

resolver 目录

resolver 是自动导入相关能力。

它主要用于配合 unplugin-vue-components，让业务项目里可以直接使用类似下面的组件名：

vue 复制代码

<AXBubble />
<AXSender />

然后自动解析成：

ts 复制代码

import { Bubble } from 'ant-design-x-vue';
import { Sender } from 'ant-design-x-vue';

默认前缀是：

text 复制代码

AX

这对业务项目来说比较方便，可以减少手动 import。

安装依赖

在项目根目录执行：

bash 复制代码

pnpm install

启动 playground

如果只是想测试组件，推荐启动 playground：

bash 复制代码

pnpm play

启动后访问终端里输出的地址，一般是：

text 复制代码

http://127.0.0.1:5173/

之后可以修改：

text 复制代码

play/src/App.vue

来测试不同组件。

这也是最适合日常开发调试的方式。

启动文档站

如果想看完整文档和组件 demo，可以启动文档站：

bash 复制代码

pnpm docs:dev

它会启动 VitePress 文档站。

文档站更适合查看组件 API、示例、不同用法。

构建项目

构建组件库：

bash 复制代码

pnpm build

这个命令会执行：

text 复制代码

build:es
build:dist
build:resolver

对应产物大致是：

text 复制代码

es/               ES Module 产物
lib/              CommonJS 产物
dist/             浏览器分发产物
typings/          类型声明
resolver-dist/    resolver 构建产物

构建文档站：

bash 复制代码

pnpm docs:build

预览文档站构建结果：

bash 复制代码

pnpm docs:preview

常用命令汇总

bash 复制代码

# 安装依赖
pnpm install

# 启动 playground
pnpm play

# 启动文档站
pnpm docs:dev

# 构建组件库
pnpm build

# 构建文档
pnpm docs:build

# 预览文档
pnpm docs:preview

# 类型检查
pnpm typecheck

# 运行测试
pnpm test

# 运行 lint
pnpm lint

开发一个组件时怎么看？

如果要开发或修改一个组件，可以按下面的顺序来：

text 复制代码

1. 先看 src/components.ts，确认组件是否已经对外导出
2. 找到 src/组件名 目录
3. 看 interface.ts，理解 props 和类型
4. 看主组件 .vue 文件，理解核心逻辑
5. 看 style/，理解样式和 token
6. 看 docs/component/组件名.md，理解文档说明
7. 看 docs/examples/组件名，理解用户怎么使用
8. 在 play/src/App.vue 中写 demo 做本地测试

比如要看 Bubble：

text 复制代码

src/bubble/index.ts
src/bubble/interface.ts
src/bubble/Bubble.vue
src/bubble/BubbleList.vue
src/bubble/style/
docs/component/bubble.md
docs/examples/bubble/

为什么适合我们当前项目？

我们做的是 Agent 产品，前端需要的不只是一个聊天框，而是一整套 AI 交互组件。

Ant Design X Vue 的优势主要有：

text 复制代码

基于 Vue，符合公司主流技术栈
组件覆盖 AI 对话常见场景
设计风格适合企业级产品
可以快速搭建第一版 Agent 界面
后续方便做内部二次封装

它适合作为第一阶段的基础方案。

后面我们可以在它之上封装自己的业务组件，比如：

text 复制代码

AgentChat
AgentSender
AgentMessageList
AgentConversation
AgentThoughtChain

这样既能复用开源组件能力，又能保持业务层的统一封装。

总结

Ant Design X Vue 可以理解为一套面向 AI 产品的 Vue 组件库。

它主要帮助我们解决 Agent / Copilot / AI Chat 产品中的通用前端问题，比如消息展示、输入、会话、附件、提示词、思考过程和流式处理。

项目结构整体比较清晰：

text 复制代码

src       组件源码
docs      文档和示例
play      本地调试 playground
resolver  自动导入能力
scripts   项目维护脚本

日常开发时，最常用的是：

bash 复制代码

pnpm install
pnpm play
pnpm docs:dev

如果只是测试组件，优先用 play/src/App.vue。

如果要查看完整用法，优先看 docs/component 和 docs/examples。

对于 Vue 技术栈团队来说，Ant Design X Vue 是一个比较适合快速启动 AI 前端界面的基础方案。