@kernelift/ai-chat 1.0.1-beta.0

package/README.md

@@ -0,0 +1,711 @@
+# Vue3 AI 聊天框组件使用手册
+
+配合的请求SSE库：[Sse-Client](./SSE-Client.md)
+
+## 目录
+
+- [概述](#概述)
+- [安装与导入](#安装与导入)
+- [组件构成](#组件构成)
+- [主容器组件](#主容器组件)
+- [子组件详解](#子组件详解)
+- [事件处理](#事件处理)
+- [样式定制](#样式定制)
+- [使用示例](#使用示例)
+- [API 参考](#api-参考)
+
+## 概述
+
+Vue3 AI 聊天框组件是一个功能完整的聊天界面解决方案，支持流式对话、消息气泡、侧边栏历史记录、主题切换等特性。
+
+### 主要特性
+
+- 💬 **实时对话** - 支持流式消息显示
+- 📱 **响应式设计** - 适配桌面端和移动端
+- 🎨 **主题系统** - 支持亮色/暗色主题切换
+- 📚 **历史记录** - 侧边栏对话历史管理
+- 🛠️ **工具集成** - 支持深度思考、联网搜索等功能
+- 🎯 **可定制** - 丰富的插槽和配置选项
+
+## 安装与导入
+
+### 安装依赖
+
+```bash
+# 安装核心依赖
+npm install @kernelift/icons @kernelift/utils @kernelift/markdown element-plus
+```
+
+### 组件导入
+
+```typescript
+// 全局注册
+import { createApp } from 'vue';
+import ChatContainer from '@kernelift/ai-chat';
+import '@kernelift/ai-chat/style.css';
+
+const app = createApp(App);
+app.component('AIChatBox', ChatContainer);
+```
+
+```vue
+<!-- 局部导入 -->
+<script setup>
+import {
+  ChatContainer,
+  ChatBubble,
+  ChatSender,
+  ChatSidebar,
+  ChatHeader,
+  ThinkingProcess
+} from '@kernelift/ai-chat';
+import type { ChatMessage, ChatRecord, BubbleEvent } from '@kernelift/ai-chat';
+</script>
+```
+
+## 组件构成
+
+### 组件结构
+
+```
+ChatContainer (主容器)
+├── ChatSidebar (侧边栏)
+├── ChatHeader (头部)
+├── ChatBubble (消息气泡)
+├── ThinkingProcess (思考过程)
+├── ChatSender (发送器)
+└── 工作区 (可选)
+```
+
+## 主容器组件
+
+### 基本用法
+
+```vue
+<template>
+  <ChatContainer
+    v-model:messages="messages"
+    v-model:inputText="inputText"
+    v-model:loading="loading"
+    :records="chatRecords"
+    @send="handleSend"
+    @bubble-event="handleBubbleEvent"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import type { ChatMessage, ChatRecord, BubbleEvent } from '@kernelift/ai-chat';
+
+const messages = ref<ChatMessage[]>([]);
+const inputText = ref('');
+const loading = ref(false);
+const chatRecords = ref<ChatRecord[]>([]);
+
+const handleSend = (text: string) => {
+  // 处理发送消息
+  console.log('发送消息:', text);
+};
+
+const handleBubbleEvent = (eventName: BubbleEvent, data: ChatMessage) => {
+  // 处理气泡事件
+  console.log('气泡事件:', eventName, data);
+};
+</script>
+```
+
+### 完整配置示例
+
+```vue
+<template>
+  <ChatContainer
+    v-model:messages="messages"
+    v-model:inputText="inputText"
+    v-model:loading="loading"
+    :records="chatRecords"
+    :has-header="true"
+    :has-theme-mode="true"
+    :has-sender-tools="true"
+    :show-workspace="true"
+    :theme-mode="currentTheme"
+    :primary-color="primaryColor"
+    :default-record-id="defaultRecordId"
+    @send="handleSend"
+    @bubble-event="handleBubbleEvent"
+    @change-record="handleRecordChange"
+    @change-theme="handleThemeChange"
+    @change-collapse="handleCollapseChange"
+    @click-logo="handleLogoClick"
+  >
+    <!-- 自定义侧边栏 Logo -->
+    <template #logo>
+      <div class="custom-logo">
+        <img src="/logo.png" alt="Logo" />
+        <span>我的AI助手</span>
+      </div>
+    </template>
+
+    <!-- 自定义消息头部 -->
+    <template #bubble-header="{ data }">
+      <div class="custom-header">
+        <span>{{ formatTime(data.timestamp) }}</span>
+      </div>
+    </template>
+
+    <!-- 自定义发送工具 -->
+    <template #sender-tools>
+      <el-button @click="handleAttachment">
+        <IconRender icon="material-symbols:attach-file" />
+        附件
+      </el-button>
+    </template>
+
+    <!-- 自定义工作区 -->
+    <template #workspace="{ record }">
+      <div class="workspace-content">
+        <h3>当前对话: {{ record?.name }}</h3>
+        <!-- 工作区内容 -->
+      </div>
+    </template>
+  </ChatContainer>
+</template>
+```
+
+## 子组件详解
+
+### ChatBubble - 消息气泡
+
+消息气泡组件支持多种消息类型和交互操作。
+
+```vue
+<template>
+  <ChatBubble
+    v-model="message"
+    :is-last="isLastMessage"
+    :markdown-class="customMarkdownClass"
+    @bubble-event="handleBubbleEvent"
+  >
+    <!-- 自定义消息头部 -->
+    <template #header>
+      <div class="message-time">
+        {{ formatTime(message.timestamp) }}
+      </div>
+    </template>
+
+    <!-- 自定义思考过程头部 -->
+    <template #thinking-header>
+      <div class="thinking-label">推理过程</div>
+    </template>
+
+    <!-- 自定义操作按钮 -->
+    <template #bubble-event>
+      <el-button @click="handleCustomAction(message)"> 自定义操作 </el-button>
+    </template>
+  </ChatBubble>
+</template>
+```
+
+### ChatSender - 消息发送器
+
+发送器组件提供消息输入和工具按钮。
+
+```vue
+<template>
+  <ChatSender
+    v-model="inputText"
+    :loading="isSending"
+    :has-thinking="true"
+    :has-net-search="true"
+    @send="handleSend"
+  >
+    <!-- 自定义工具 -->
+    <template #tools="{ value, loading }">
+      <el-tooltip content="清空输入">
+        <el-button :disabled="!value" @click="inputText = ''">
+          <IconRender icon="material-symbols:clear" />
+        </el-button>
+      </el-tooltip>
+    </template>
+  </ChatSender>
+</template>
+```
+
+### ChatSidebar - 侧边栏
+
+侧边栏组件管理对话历史记录。
+
+```vue
+<template>
+  <ChatSidebar
+    v-model="activeRecord"
+    :data="records"
+    :collapse="isCollapsed"
+    :theme-mode="theme"
+    @change="handleRecordChange"
+    @change-collapse="handleCollapse"
+    @change-theme="handleThemeChange"
+    @click-logo="handleLogoClick"
+  >
+    <!-- 自定义 Logo -->
+    <template #logo>
+      <div class="brand-logo">
+        <img src="/brand-logo.png" alt="Brand" />
+        <span>AI对话平台</span>
+      </div>
+    </template>
+  </ChatSidebar>
+</template>
+```
+
+### ThinkingProcess - 思考过程
+
+展示AI的思考推理过程。
+
+```vue
+<template>
+  <ThinkingProcess
+    v-model:collapse="isThoughtCollapsed"
+    :data="thoughtContent"
+    :loading="isThinking"
+    :markdown-class="thoughtStyle"
+  >
+    <!-- 自定义头部 -->
+    <template #header>
+      <div class="thought-title">
+        <IconRender icon="material-symbols:psychology" />
+        AI思考过程
+      </div>
+    </template>
+  </ThinkingProcess>
+</template>
+```
+
+## 事件处理
+
+### 消息事件
+
+```typescript
+// 消息发送
+const handleSend = (text: string) => {
+  // 添加用户消息
+  messages.value.push({
+    id: generateId(),
+    role: 'user',
+    content: text,
+    timestamp: Date.now()
+  });
+
+  // 调用AI接口
+  callAI(text).then((response) => {
+    // 处理AI响应
+  });
+};
+
+// 气泡交互事件
+const handleBubbleEvent = (eventName: BubbleEvent, message: ChatMessage) => {
+  switch (eventName) {
+    case 'like':
+      // 点赞处理
+      message.isLiked = true;
+      message.isDisliked = false;
+      break;
+    case 'dislike':
+      // 点踩处理
+      message.isLiked = false;
+      message.isDisliked = true;
+      break;
+    case 'copy':
+      // 复制消息
+      navigator.clipboard.writeText(message.content);
+      ElMessage.success('已复制到剪贴板');
+      break;
+    case 'reload':
+      // 重新生成
+      handleRegenerate(message);
+      break;
+    case 'terminate':
+      // 终止生成
+      handleTerminate(message);
+      break;
+    case 'bookmark':
+      // 收藏消息
+      message.isBookmarked = !message.isBookmarked;
+      break;
+  }
+};
+```
+
+### 流式消息处理
+
+```typescript
+import { SSEClient } from './sse-client';
+
+const handleStreamResponse = async (question: string) => {
+  const client = new SSEClient('your-token', 'https://api.example.com');
+
+  let currentMessage: ChatMessage = {
+    id: generateId(),
+    role: 'assistant',
+    content: '',
+    timestamp: Date.now(),
+    loading: true
+  };
+
+  messages.value.push(currentMessage);
+
+  const handlers = {
+    onContent: (content: string) => {
+      currentMessage.content += content;
+    },
+
+    onToolCallDelta: (data: any) => {
+      // 处理工具调用
+      if (!currentMessage.toolCalls) {
+        currentMessage.toolCalls = [];
+      }
+      currentMessage.toolCalls.push(data);
+    },
+
+    onComplete: (finalData: { content: string; toolCalls: any[] }) => {
+      currentMessage.content = finalData.content;
+      currentMessage.toolCalls = finalData.toolCalls;
+      currentMessage.loading = false;
+    },
+
+    onError: (error: Error) => {
+      console.error('流式响应错误:', error);
+      currentMessage.loading = false;
+      currentMessage.isError = true;
+      currentMessage.error = error.message;
+    }
+  };
+
+  await client.connect('/api/chat/stream', handlers, {
+    body: { question }
+  });
+};
+```
+
+## 样式定制
+
+### CSS 变量定制
+
+```css
+/* 在全局样式或组件样式中覆盖 */
+:root {
+  --kl-chat-primary-color: #615ced;
+  --kl-chat-primary-rgb: 97, 92, 237;
+
+  /* Element Plus 主题色 */
+  --el-color-primary: var(--kl-chat-primary-color);
+  --el-color-primary-light-3: #8a86f1;
+  --el-color-primary-light-5: #b3b0f5;
+}
+
+/* 暗色主题 */
+.dark {
+  --kl-chat-primary-color: #8a86f1;
+  --dark-background-color: #1a1a1a;
+}
+```
+
+### SCSS 样式定制
+
+```scss
+// 自定义主题
+.kernelift-chat-container {
+  // 修改主容器样式
+  border-radius: 16px;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.1);
+
+  &__aside {
+    // 修改侧边栏样式
+    background: linear-gradient(180deg, #ffffff 0%, #f8f9fa 100%);
+  }
+
+  &__messages-section {
+    // 修改消息区域样式
+    background-color: #fafbfc;
+  }
+}
+
+// 自定义消息气泡
+.custom-chat-bubble {
+  .kernelift-chat-bubble__assistant {
+    background: linear-gradient(135deg, #ffffff 0%, #f0f4ff 100%);
+    border: 1px solid #e1e8ff;
+  }
+
+  .kernelift-chat-bubble__user {
+    &-content {
+      background: linear-gradient(135deg, var(--kl-chat-primary-color) 0%, #8a86f1 100%);
+      color: white;
+    }
+  }
+}
+```
+
+## 使用示例
+
+### 完整聊天应用
+
+```vue
+<template>
+  <div class="chat-app">
+    <ChatContainer
+      v-model:messages="messages"
+      v-model:inputText="inputText"
+      v-model:loading="loading"
+      :records="records"
+      :has-theme-mode="true"
+      :has-sender-tools="true"
+      :primary-color="brandColor"
+      @send="handleSend"
+      @bubble-event="handleBubbleEvent"
+      @change-theme="handleThemeChange"
+    >
+      <!-- 自定义头部 -->
+      <template #header="{ record }">
+        <div class="custom-header">
+          <h2>{{ record?.name || '新对话' }}</h2>
+          <div class="header-actions">
+            <el-button @click="exportChat">导出</el-button>
+            <el-button @click="clearChat">清空</el-button>
+          </div>
+        </div>
+      </template>
+
+      <!-- 自定义发送工具 -->
+      <template #sender-tools>
+        <div class="sender-tools">
+          <el-tooltip content="上传文件">
+            <el-button circle @click="handleFileUpload">
+              <IconRender icon="material-symbols:attach-file" />
+            </el-button>
+          </el-tooltip>
+          <el-tooltip content="语音输入">
+            <el-button circle @click="handleVoiceInput">
+              <IconRender icon="material-symbols:mic" />
+            </el-button>
+          </el-tooltip>
+        </div>
+      </template>
+
+      <!-- 自定义工作区 -->
+      <template #workspace="{ record }">
+        <ChatWorkspace :record="record" @analysis="handleAnalysis" />
+      </template>
+    </ChatContainer>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue';
+import type { ChatMessage, ChatRecord, BubbleEvent } from '@kernelift/ai-chat';
+import { ElMessage } from 'element-plus';
+
+// 响应式数据
+const messages = ref<ChatMessage[]>([]);
+const inputText = ref('');
+const loading = ref(false);
+const records = ref<ChatRecord[]>([]);
+const brandColor = ref('#615ced');
+
+// 初始化加载历史记录
+onMounted(async () => {
+  try {
+    const history = await loadChatHistory();
+    records.value = history;
+  } catch (error) {
+    console.error('加载历史记录失败:', error);
+  }
+});
+
+// 发送消息处理
+const handleSend = async (text: string) => {
+  if (!text.trim()) return;
+
+  // 添加用户消息
+  const userMessage: ChatMessage = {
+    id: generateId(),
+    role: 'user',
+    content: text,
+    timestamp: Date.now()
+  };
+
+  messages.value.push(userMessage);
+  inputText.value = '';
+  loading.value = true;
+
+  try {
+    // 调用AI接口
+    await callAIChatAPI(text, messages.value);
+  } catch (error) {
+    ElMessage.error('发送失败，请重试');
+    console.error('发送消息错误:', error);
+  } finally {
+    loading.value = false;
+  }
+};
+
+// 气泡事件处理
+const handleBubbleEvent = (eventName: BubbleEvent, message: ChatMessage) => {
+  switch (eventName) {
+    case 'like':
+      handleFeedback(message, 'positive');
+      break;
+    case 'dislike':
+      handleFeedback(message, 'negative');
+      break;
+    case 'copy':
+      copyToClipboard(message.content);
+      ElMessage.success('已复制到剪贴板');
+      break;
+    case 'reload':
+      handleRegenerate(message);
+      break;
+    default:
+      console.log('未处理的事件:', eventName);
+  }
+};
+
+// 工具函数
+const generateId = () => {
+  return Date.now().toString(36) + Math.random().toString(36).substr(2);
+};
+
+const copyToClipboard = async (text: string) => {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch (err) {
+    // 降级方案
+    const textArea = document.createElement('textarea');
+    textArea.value = text;
+    document.body.appendChild(textArea);
+    textArea.select();
+    document.execCommand('copy');
+    document.body.removeChild(textArea);
+  }
+};
+</script>
+
+<style scoped>
+.chat-app {
+  height: 100vh;
+  width: 100vw;
+}
+
+.custom-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0 20px;
+}
+
+.sender-tools {
+  display: flex;
+  gap: 8px;
+  padding: 0 12px;
+}
+</style>
+```
+
+### 移动端适配示例
+
+```vue
+<template>
+  <ChatContainer
+    v-model:messages="messages"
+    v-model:inputText="inputText"
+    :records="records"
+    :has-header="true"
+    :has-sender-tools="false"
+    :show-workspace="false"
+    @send="handleSend"
+  >
+    <!-- 移动端优化的发送器 -->
+    <template #sender-footer-tools="{ value, loading }">
+      <div class="mobile-tools">
+        <el-button :disabled="!value || loading" size="small" @click="handleQuickAction">
+          快捷操作
+        </el-button>
+      </div>
+    </template>
+  </ChatContainer>
+</template>
+
+<style scoped>
+/* 移动端样式优化 */
+@media (max-width: 768px) {
+  :deep(.kernelift-chat-container) {
+    padding: 4px;
+  }
+
+  :deep(.kernelift-chat-sender) {
+    height: 160px;
+  }
+
+  :deep(.kernelift-chat-bubble__actions) {
+    opacity: 1; /* 移动端始终显示操作按钮 */
+  }
+}
+</style>
+```
+
+## API 参考
+
+### 主容器 Props
+
+| 参数                | 类型                | 默认值      | 说明                    |
+| ------------------- | ------------------- | ----------- | ----------------------- |
+| `messages`          | `ChatMessage[]`     | `[]`        | **必需**，消息列表      |
+| `inputText`         | `string`            | `''`        | 输入框文本              |
+| `loading`           | `boolean`           | `false`     | 加载状态                |
+| `records`           | `ChatRecord[]`      | `[]`        | 聊天记录列表            |
+| `hasHeader`         | `boolean`           | `true`      | 是否显示头部            |
+| `hasThemeMode`      | `boolean`           | `false`     | 是否支持主题切换        |
+| `hasSenderTools`    | `boolean`           | `false`     | 是否显示发送工具        |
+| `showWorkspace`     | `boolean`           | `true`      | 是否显示工作区          |
+| `themeMode`         | `'light' \| 'dark'` | `'light'`   | 主题模式                |
+| `primaryColor`      | `string`            | `'#615ced'` | 主题色                  |
+| `defaultRecordId`   | `string`            | -           | 默认选中的记录ID        |
+| `defaultCollapse`   | `boolean`           | `false`     | 默认侧边栏折叠状态      |
+| `defaultAsideWidth` | `number`            | `250`       | 侧边栏默认宽度          |
+| `markdownClassName` | `string`            | -           | Markdown 内容自定义类名 |
+
+### 事件列表
+
+| 事件名               | 参数                       | 说明                     |
+| -------------------- | -------------------------- | ------------------------ |
+| `send`               | `string`                   | 发送消息时触发           |
+| `change-record`      | `ChatRecord \| undefined`  | 切换聊天记录时触发       |
+| `change-collapse`    | `boolean`                  | 侧边栏折叠状态改变时触发 |
+| `change-theme`       | `'light' \| 'dark'`        | 主题切换时触发           |
+| `change-aside-width` | `number`                   | 侧边栏宽度改变时触发     |
+| `click-logo`         | -                          | 点击Logo时触发           |
+| `bubble-event`       | `BubbleEvent, ChatMessage` | 消息气泡交互事件         |
+| `close-workspace`    | -                          | 关闭工作区时触发         |
+
+### 插槽列表
+
+| 插槽名                   | 作用域                                | 说明             |
+| ------------------------ | ------------------------------------- | ---------------- |
+| `aside`                  | `{ record: ChatRecord }`              | 自定义侧边栏内容 |
+| `header`                 | `{ record: ChatRecord }`              | 自定义头部内容   |
+| `logo`                   | -                                     | 自定义Logo       |
+| `header-logo`            | -                                     | 折叠状态下的Logo |
+| `bubble-header`          | `{ data: ChatMessage }`               | 消息气泡头部     |
+| `bubble-footer`          | `{ data: ChatMessage }`               | 消息气泡底部     |
+| `bubble-event`           | `{ data: ChatMessage }`               | 消息气泡操作区域 |
+| `bubble-content-footer`  | `{ data: ChatMessage }`               | 消息内容底部     |
+| `bubble-thinking-header` | `{ data: ChatMessage }`               | 思考过程头部     |
+| `sender-tools`           | -                                     | 发送器工具区域   |
+| `sender-footer-tools`    | `{ value: string, loading: boolean }` | 发送器底部工具   |
+| `footer`                 | -                                     | 页面底部内容     |
+| `workspace`              | `{ record: ChatRecord }`              | 工作区内容       |
+
+---
+
+**版本**: 1.0.0  
+**兼容性**: Vue 3.3+  
+**License**: 禁止商业使用