npm package: @simple-ai-chat-project/vue-ui
Description: Vue UI components for AI Chat (Shadcn-vue based)
Latest version: 1.0.1

# @simple-ai-chat-project/vue-ui

> Vue UI 组件包 - 基于 Shadcn-vue 的 AI 对话界面组件

## 功能特性

✅ **完整的聊天界面** - ChatGPT 风格的现代化对话 UI
✅ **流式输出** - 支持 SSE 实时流式响应
✅ **Markdown 渲染** - 使用 md-editor-v3 渲染 AI 消息
✅ **样式隔离** - 所有样式在容器内生效，不影响全局
✅ **会话管理** - 支持创建新会话、归档历史会话
✅ **文档引用** - 显示 RAG 检索的文档引用卡片
✅ **消息持久化** - 自动保存到 sessionStorage
✅ **响应式设计** - 支持桌面和移动设备

## 安装

```bash
# 使用 pnpm (推荐)
pnpm install @simple-ai-chat-project/vue-ui

# 使用 npm
npm install @simple-ai-chat-project/vue-ui
```

## 快速开始

### 1. 引入样式和组件

```vue
<template>
  <div id="app">
    <ChatWindow
      chat-height="calc(100vh - 60px)"
      :welcome-suggestions="suggestions"
      :user-avatar="userAvatar"
    />
  </div>
</template>

<script setup>
import { ChatWindow, useChatStore } from '@simple-ai-chat-project/vue-ui'
import '@simple-ai-chat-project/vue-ui/dist/ai-chat-vue.css'

const suggestions = [
  '你好，请介绍一下你自己',
  '你能帮我做什么？',
]

const userAvatar = '/path/to/user-avatar.png'
</script>
```

### 2. 初始化 Pinia

```javascript
// main.js
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const app = createApp(App)
app.use(createPinia())
app.mount('#app')
```

## 组件 API

### ChatWindow

主聊天窗口组件

**Props:**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `chatHeight` | `String` | `'calc(100vh - 140px)'` | 聊天容器高度 |
| `userAvatar` | `String` | `'/default-user-avatar.png'` | 用户头像 URL |
| `welcomeSuggestions` | `Array` | `[]` | 欢迎卡片建议列表 |

**示例:**

```vue
<ChatWindow
  chat-height="600px"
  user-avatar="/avatar.png"
  :welcome-suggestions="['问题1', '问题2']"
/>
```

### WelcomeCard

欢迎卡片组件（独立使用）

**Props:**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | `String` | `'AI 助手'` | 标题 |
| `subtitle` | `String` | `'输入消息开始对话...'` | 副标题 |
| `suggestions` | `Array` | `[]` | 建议列表 |
| `isFading` | `Boolean` | `false` | 是否正在淡出 |

**Events:**

- `suggestion-click` - 点击建议时触发
- `click` - 点击卡片外部时触发

### ReferenceCard

文档引用卡片组件（独立使用）

**Props:**

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `references` | `Array` | `[]` | 文档引用列表 |

**Events:**

- `preview` - 点击预览按钮时触发
- `download` - 点击下载按钮时触发

## Store API

### useChatStore

Pinia store，管理聊天状态

**State:**

```javascript
{
  client: null,           // Core SDK 客户端实例
  sessionId: null,        // 当前会话ID
  messages: [],           // 消息列表
  input: '',              // 输入框内容
  isLoading: false,       // 是否正在加载
  isStreaming: false,     // 是否正在流式输出
  error: null,            // 错误信息
  documentReferences: [], // 文档引用列表
}
```

**Actions:**

```javascript
// 初始化聊天
chatStore.initializeChat()

// 发送消息
await chatStore.sendMessage('你好')

// 创建新会话
await chatStore.createNewSession()

// 获取归档会话列表
const sessions = chatStore.getArchivedSessions()

// 加载归档会话
await chatStore.loadArchivedSession(sessionId)

// 删除归档会话
chatStore.deleteArchivedSession(sessionId)

// 清空所有归档会话
chatStore.clearAllArchivedSessions()

// 清理资源
chatStore.cleanup()
```

## 工具函数

### cn

合并 Tailwind CSS 类名

```javascript
import { cn } from '@simple-ai-chat-project/vue-ui'

const className = cn('text-red-500', 'font-bold', {
  'text-blue-500': isActive
})
```

## 样式定制

所有样式都在 `#ai-chat-container` 容器内生效，支持通过 CSS 变量定制：

```css
#ai-chat-container {
  /* 主色调 */
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;

  /* 背景色 */
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;

  /* 边框和输入 */
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;

  /* 圆角 */
  --radius: 0.5rem;
}
```

### 深色主题

添加 `.dark` 类到容器元素启用深色主题：

```javascript
document.getElementById('ai-chat-container').classList.add('dark')
```

## 配置 Core SDK

在 store 初始化时配置：

```javascript
import { useChatStore } from '@simple-ai-chat-project/vue-ui'

const chatStore = useChatStore()

// 自定义配置
chatStore.client = createChatClient({
  apiBaseUrl: 'https://your-api.com/v1',
  auth: {
    type: 'bearer',
    token: 'your-token'
  },
  ai: {
    provider: 'openai',
    model: 'gpt-4',
    temperature: 0.7
  }
})
```

## 浏览器支持

- Chrome >= 90
- Firefox >= 88
- Safari >= 14
- Edge >= 90

## 依赖

- Vue 3.5+
- Pinia 2.0+
- @simple-ai-chat-project/core-sdk (workspace)
- md-editor-v3
- @iconify/vue
- radix-vue
- @vueuse/core

## 开发

```bash
# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 预览
pnpm preview
```

## 许可证

MIT

## 相关链接

- [开发文档](../../docs/Vue-UI组件包详细开发说明.md)
- [Core SDK](../core-sdk/README.md)
- [演示应用](../../demo/vue-demo/README.md)