npm package: @hd-front-end/ai-assistant-sdk-vue3
Description: AI助手SDK - Vue3 + TypeScript组件库
Latest version: 0.0.18

# @ai-assistant-sdk/vue3

基于 Vue 3.4+ 的 AI 助手 SDK，提供开箱即用的聊天、数据可视化、多模态交互能力。

## 📦 特性

- 🎯 **完整功能**：复刻 haichat-web-ui 的全部能力
- 🧩 **组件化设计**：40+ 精心设计的组件，灵活组合
- 📐 **架构清晰**：UI 层与 Core 层职责明确，易于维护
- 🔒 **类型安全**：完整的 TypeScript 类型定义
- 🎨 **主题定制**：支持浅色/深色主题
- 📱 **响应式**：适配桌面和移动端
- ⚡ **性能优良**：基于 Vue 3 Composition API
- 🔧 **高度可配置**：丰富的配置选项

## 🚀 快速开始

### 安装

```bash
pnpm add @ai-assistant-sdk/vue3
```

### 基础用法

```vue
<template>
  <AIAssistant :config="config" />
</template>

<script setup lang="ts">
import { AIAssistant } from '@ai-assistant-sdk/vue3';
import type { AIAssistantConfig } from '@ai-assistant-sdk/vue3';

const config: AIAssistantConfig = {
  // 基础配置
  apiUrl: 'https://api.example.com',
  accessToken: 'your-token',
  botId: 'bot-123',
  channelId: 'channel-456',

  // 功能开关
  features: {
    enableFileUpload: true,
    enableVoiceRecord: true,
    enableDataChart: true,
    enableFeedback: true,
  },

  // UI 配置
  ui: {
    theme: 'light',
    avatarUrl: 'https://example.com/bot.png',
    welcomeMessage: '你好！我是AI助手',
    suggestedQuestions: [
      '帮我分析销售数据',
      '生成月度报告',
    ],
  },
};
</script>
```

## 📚 文档

### 设计文档

- [组件架构设计](./ARCHITECTURE.md) - 完整的组件架构和设计原则
- [Core 依赖清单](./CORE_DEPENDENCIES.md) - Core 层需要实现的能力清单
- [实现状态](./IMPLEMENTATION_STATUS.md) - 当前实现进度

### 核心能力

#### 1. 对话能力

- ✅ SSE 流式对话
- ✅ 思考过程展示
- ✅ 重新生成回复
- ✅ 历史对话查询
- ✅ 会话管理
- ✅ 错误处理

#### 2. 多模态能力

- ✅ 文件上传（图片、文档）
- ✅ 图片预览
- ✅ 文件状态管理
- ✅ 语音录制
- ✅ 语音转文字

#### 3. 数据可视化

- ✅ 柱状图
- ✅ 折线图
- ✅ 饼图
- ✅ 表格
- ✅ 指标卡片
- ✅ 图表类型切换
- ✅ 数据解读

#### 4. 交互能力

- ✅ 复制回复
- ✅ 点赞/点踩
- ✅ 收藏对话
- ✅ 重新生成
- ✅ 取消生成
- ✅ 引用材料展示

#### 5. 欢迎页

- ✅ 机器人信息展示
- ✅ 欢迎语
- ✅ 推荐问题

## 🏗️ 架构设计

### 组件层级

```
AIAssistant (主容器)
├── ChatWelcome (欢迎页)
│   ├── BotAvatar
│   ├── WelcomeMessage
│   └── SuggestedQuestions
├── ChatMessages (消息列表)
│   └── MessageItem
│       ├── UserMessage
│       │   ├── MessageFiles
│       │   └── MessageText
│       └── AssistantMessage
│           ├── MessageThinking
│           ├── MessageText
│           ├── DataCharts
│           ├── DataInterpretation
│           ├── RetrieverResources
│           └── MessageActions
└── ChatInput (输入区)
    ├── FileUploadArea
    ├── InputTextarea
    └── ActionBar
```

### Composables

- `useAIChat` - 聊天功能
- `useFileUpload` - 文件上传
- `useVoiceRecord` - 语音录制
- `useConversation` - 会话管理
- `useFeedback` - 反馈操作
- `useDataChart` - 图表处理
- `useScrollToBottom` - 滚动控制

### Core 层依赖

SDK 的 UI 层需要依赖 Core 层提供以下引擎：

1. **MessageEngine** - 消息处理引擎
   - 流式对话
   - 重新生成
   - 子对话（数据解读）
   - 会话管理

2. **FileEngine** - 文件处理引擎
   - 文件上传
   - 文件验证
   - 状态管理

3. **VoiceEngine** - 语音处理引擎
   - 录音控制
   - 权限管理
   - 语音转文字

4. **DataEngine** - 数据处理引擎
   - 图表数据解析
   - ECharts 配置生成
   - 图表类型切换

5. **ConversationEngine** - 会话引擎
   - 历史查询
   - 会话管理

6. **FeedbackEngine** - 反馈引擎
   - 点赞/点踩
   - 收藏对话

详见 [Core 依赖清单](./CORE_DEPENDENCIES.md)

## 🎨 配置选项

### AIAssistantConfig

```typescript
interface AIAssistantConfig {
  /** 基础配置 */
  apiUrl?: string;
  accessToken: string;
  botId: string;
  channelId?: string;
  chatUser?: string;
  chatUserName?: string;
  tenantId?: string;

  /** 功能开关 */
  features?: {
    enableFileUpload?: boolean;
    enableVoiceRecord?: boolean;
    enableDataChart?: boolean;
    enableFeedback?: boolean;
    enableCollection?: boolean;
    enableRegenerate?: boolean;
    enableThinking?: boolean;
    enableInterpretation?: boolean;
    enableRetrieverResources?: boolean;
  };

  /** 文件上传配置 */
  fileUpload?: {
    maxFiles?: number;
    maxFileSize?: number;
    maxImageSize?: number;
    allowedTypes?: string[];
  };

  /** UI 配置 */
  ui?: {
    theme?: 'light' | 'dark';
    avatarUrl?: string;
    welcomeMessage?: string;
    suggestedQuestions?: string[];
    placeholder?: string;
    showWelcome?: boolean;
  };
}
```

## 🔧 高级用法

### 使用 Composables

```vue
<script setup lang="ts">
import { useAIChat, useFileUpload } from '@ai-assistant-sdk/vue3';

const context = {
  accessToken: 'your-token',
  botId: 'bot-123',
};

// 聊天功能
const {
  messages,
  isLoading,
  sendMessage,
  cancelStream,
} = useAIChat({ 
  context,
  apiUrl: 'https://api.example.com',
});

// 文件上传
const {
  files,
  uploadFile,
  removeFile,
} = useFileUpload({ 
  context,
  maxFiles: 5,
});

async function handleSend() {
  await sendMessage('你好', {
    fileIds: files.value.map(f => f.id),
  });
}
</script>
```

### 自定义组件

```vue
<template>
  <div class="custom-chat">
    <!-- 使用独立的消息组件 -->
    <ChatMessages
      :messages="messages"
      :is-loading="isLoading"
      @regenerate="handleRegenerate"
    />

    <!-- 使用独立的输入组件 -->
    <ChatInput
      v-model="inputValue"
      :loading="isLoading"
      :enable-file-upload="true"
      @submit="handleSubmit"
      @cancel="handleCancel"
    />
  </div>
</template>

<script setup lang="ts">
import { ChatMessages, ChatInput } from '@ai-assistant-sdk/vue3';
</script>
```

## 📊 实现状态

当前已完成核心架构设计和基础组件实现：

### ✅ 已完成 (17%)

- 完整的架构设计文档
- 完整的 Core 依赖清单
- 完整的类型定义
- 基础通用组件（头像、文件卡片）
- 基础消息组件（文本、思考、用户消息、文件）

### 🚧 进行中 (83%)

- 剩余消息组件
- 图表组件
- 输入组件
- 主容器组件
- Composables
- 导出文件

详见 [实现状态](./IMPLEMENTATION_STATUS.md)

## 🎯 设计原则

1. **单一职责**：每个组件只负责一个功能模块
2. **组件复用**：通用组件可在多处复用
3. **Props Down, Events Up**：数据向下传递，事件向上发送
4. **配置驱动**：通过配置控制组件行为
5. **TypeScript 优先**：完整的类型安全保障

## 📝 开发指南

### 组件开发规范

1. 使用 Vue 3 Composition API
2. 使用 `<script setup lang="ts">`
3. 添加完整的中文注释
4. 定义清晰的 Props 和 Emits
5. 使用 scoped 样式
6. 遵循 BEM 命名规范

### 样式规范

```scss
// 颜色
$color-primary: #1C64FD;
$color-text-primary: #242633;
$color-text-secondary: #4E5369;
$color-border: #D7DFEB;
$color-bg-light: #F7F9FC;

// 间距
$spacing-sm: 8px;
$spacing-md: 12px;
$spacing-lg: 16px;

// 圆角
$border-radius-sm: 4px;
$border-radius-md: 8px;
$border-radius-lg: 12px;
```

## 🤝 贡献指南

欢迎贡献代码、提出建议或报告问题！

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

[MIT](./LICENSE)

## 🔗 相关链接

- [Core 包](../core)
- [Vanilla 包](../vanilla)
- [Vue2 包](../vue2)
- [示例项目](../../examples)

## 📞 联系我们

- 项目主页：https://github.com/your-org/ai-assistant-sdk
- 问题反馈：https://github.com/your-org/ai-assistant-sdk/issues
- 邮箱：contact@example.com

---

**注意**：本 SDK 目前处于开发阶段，API 可能会有变化。建议在生产环境使用前等待稳定版本发布。