@ai-assistant-sdk/vue3

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

📦 特性

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

🚀 快速开始

安装

pnpm add @ai-assistant-sdk/vue3

基础用法

<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>

📚 文档

设计文档

• 组件架构设计 - 完整的组件架构和设计原则
• Core 依赖清单 - Core 层需要实现的能力清单
• 实现状态 - 当前实现进度

核心能力

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 依赖清单

🎨 配置选项

AIAssistantConfig

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

<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>

自定义组件

<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
• 导出文件

详见 实现状态

🎯 设计原则

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 命名规范

样式规范

// 颜色
$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

🔗 相关链接

• Core 包
• Vanilla 包
• Vue2 包
• 示例项目

📞 联系我们

• 项目主页：https://github.com/your-org/ai-assistant-sdk
• 问题反馈：https://github.com/your-org/ai-assistant-sdk/issues
• 邮箱：[email protected]

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