@kernelift/ai-chat 2.0.0 → 2.1.0

package/README.md

@@ -1,94 +1,128 @@
-# Kernelift AI 聊天框组件使用手册
+# @kernelift/ai-chat
 
-`kernelift/核心跃升` 基于 `vue3` 编写的 AI 聊天框组件，依赖 `pnpm` 管理依赖。
+[![npm version](https://badge.fury.io/js/%40kernelift%2Fai-chat.svg)](https://badge.fury.io/js/%40kernelift%2Fai-chat)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)
 
-配合的请求SSE库：[Sse-Client](./SSE-Client.md)
+基于 Vue 3 + TypeScript 的现代化 AI 聊天框组件，提供企业级的对话界面解决方案。
 
-## 目录
+## ✨ 特性
 
-- [概述](#概述)
-- [安装与导入](#安装与导入)
-- [组件构成](#组件构成)
-- [主容器组件](#主容器组件)
-- [子组件详解](#子组件详解)
-- [事件处理](#事件处理)
-- [样式定制](#样式定制)
-- [使用示例](#使用示例)
-- [API 参考](#api-参考)
+- 🚀 **现代化架构** - 基于 Vue 3 Composition API + TypeScript
+- 💬 **流式对话** - 支持 SSE 实时通信和流式消息显示
+- 🎨 **主题系统** - 内置亮色/暗色主题，支持自定义主题色
+- 📱 **响应式设计** - 完美适配桌面端和移动端
+- 📚 **历史管理** - 智能的对话历史记录管理
+- 🛠️ **高度可定制** - 丰富的插槽和配置选项
+- 🌐 **国际化** - 内置中英文支持
+- 🧠 **AI 能力** - 支持深度思考、联网搜索等 AI 功能
 
-## 概述
+## 📦 安装
 
-Vue3 AI 聊天框组件是一个功能完整的聊天界面解决方案，支持流式对话、消息气泡、侧边栏历史记录、主题切换等特性。
+```bash
+# 使用 pnpm
+pnpm add @kernelift/ai-chat
 
-### 主要特性
+# 使用 npm
+npm install @kernelift/ai-chat
 
-- 💬 **实时对话** - 支持流式消息显示
-- 📱 **响应式设计** - 适配桌面端和移动端
-- 🎨 **主题系统** - 支持亮色/暗色主题切换
-- 📚 **历史记录** - 侧边栏对话历史管理
-- 🛠️ **工具集成** - 支持深度思考、联网搜索等功能
-- 🎯 **可定制** - 丰富的插槽和配置选项
+# 使用 yarn
+yarn add @kernelift/ai-chat
+```
 
-## 安装与导入
+### 依赖要求
 
-### 安装依赖
+- Vue 3.3+
+- TypeScript 5.0+
+- @kernelift/markdown (workspace:\*)
 
-```bash
-# 安装核心依赖
-pnpm install @kernelift/markdown @kernelift/ai-chat
-```
+## 🚀 快速开始
 
-#### 其他推荐依赖 (选用)
+### 基础用法
 
-```bash
-pnpm install @vueuse/core @kernelift/utils
-```
+```vue
+<template>
+  <ChatContainer
+    v-model:messages="messages"
+    v-model:inputText="inputText"
+    v-model:loading="loading"
+    :records="records"
+    @send="handleSend"
+    @bubble-event="handleBubbleEvent"
+  />
+</template>
 
-### 组件导入
+<script setup>
+import { ref } from 'vue'
+import { ChatContainer } from '@kernelift/ai-chat'
+import '@kernelift/ai-chat/style.css'
+import type { ChatMessage, ChatRecord, BubbleEvent } from '@kernelift/ai-chat'
 
-```typescript
-// 全局注册
-import { createApp } from 'vue';
-import { ChatContainer } from '@kernelift/ai-chat';
-import '@kernelift/ai-chat/style.css';
+const messages = ref<ChatMessage[]>([])
+const inputText = ref('')
+const loading = ref(false)
+const records = ref<ChatRecord[]>([])
 
-const app = createApp(App);
-app.component('ChatContainer', ChatContainer);
-```
+const handleSend = (text: string) => {
+  console.log('发送消息:', text)
+}
 
-```vue
-<!-- 局部导入 -->
-<script setup>
-import {
-  ChatContainer,
-  ChatBubble,
-  ChatSender,
-  ChatSidebar,
-  ChatHeader,
-  ThinkingProcess
-} from '@kernelift/ai-chat';
-import '@kernelift/ai-chat/style.css';
-import type { ChatMessage, ChatRecord, BubbleEvent } from '@kernelift/ai-chat';
+const handleBubbleEvent = (eventName: BubbleEvent, data: ChatMessage) => {
+  console.log('气泡事件:', eventName, data)
+}
 </script>
 ```
 
-## 组件构成
+## 📚 目录
+
+- [组件架构](#组件架构)
+- [组件详解](#组件详解)
+- [事件处理](#事件处理)
+- [样式定制](#样式定制)
+- [完整示例](#完整示例)
+- [API 文档](#api-文档)
+- [常见问题](#常见问题)
+
+## 🏗️ 组件架构
 
-### 组件结构
+### 组件层次结构
 
 ```
 ChatContainer (主容器)
 ├── ChatSidebar (侧边栏)
+│   ├── Logo 区域
+│   ├── 新建聊天按钮
+│   ├── 聊天记录列表
+│   └── 记录操作菜单
 ├── ChatHeader (头部)
-├── ChatBubble (消息气泡)
-├── ThinkingProcess (思考过程)
-├── ChatSender (发送器)
-└── 工作区 (可选)
+│   ├── Logo 显示
+│   └── 主题切换按钮
+├── 消息区域
+│   ├── ChatBubble (消息气泡)
+│   │   ├── 用户消息
+│   │   └── AI 助手消息
+│   │       ├── 思考过程 (ThinkingProcess)
+│   │       ├── 消息内容
+│   │       └── 操作按钮
+│   └── 空状态提示
+└── ChatSender (发送器)
+    ├── 工具按钮区域
+    ├── 输入框
+    └── 发送按钮
 ```
 
-## 主容器组件
+### 数据流
+
+```
+用户输入 → ChatSender → send事件 → 父组件处理 → 更新messages → ChatBubble渲染
+                ↓
+        AI响应处理 → 流式更新 → 实时显示
+```
 
-### 基本用法
+## 🧩 组件详解
+
+### ChatContainer - 主容器
+
+主容器组件，负责整体布局和状态管理。
 
 ```vue
 <template>
@@ -96,38 +130,30 @@ ChatContainer (主容器)
     v-model:messages="messages"
     v-model:inputText="inputText"
     v-model:loading="loading"
-    :records="chatRecords"
+    v-model:record-id="activeRecordId"
+    v-model:enable-think="enableThink"
+    v-model:enable-net="enableNet"
+    :records="records"
+    :theme-mode="themeMode"
+    :primary-color="#615ced"
+    :has-header="true"
+    :has-theme-mode="true"
+    :show-workspace="true"
+    :input-height="140"
     @send="handleSend"
     @bubble-event="handleBubbleEvent"
-  />
+    @create-record="handleCreateRecord"
+    @change-record="handleChangeRecord"
+    @change-theme="handleThemeChange"
+  >
+    <!-- 插槽内容 -->
+  </ChatContainer>
 </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>
 ```
 
-## 子组件详解
-
 ### ChatBubble - 消息气泡
 
-消息气泡组件支持多种消息类型和交互操作。
+负责显示单条消息，支持多种消息类型和交互操作。
 
 ```vue
 <template>
@@ -157,9 +183,22 @@ const handleBubbleEvent = (eventName: BubbleEvent, data: ChatMessage) => {
 </template>
 ```
 
+#### 消息类型支持
+
+- **用户消息** (`role: 'user'`) - 右对齐，蓝色背景
+- **AI 助手消息** (`role: 'assistant'`) - 左对齐，白色背景
+- **系统消息** (`role: 'system'`) - 居中显示，特殊样式
+
+#### 消息状态
+
+- `loading` - 正在生成中，显示加载动画
+- `isThinking` - 正在思考，显示思考过程
+- `isError` - 错误状态，显示错误信息
+- `isTerminated` - 已终止生成
+
 ### ChatSender - 消息发送器
 
-发送器组件提供消息输入和工具按钮。
+提供消息输入、工具按钮和发送功能。
 
 ```vue
 <template>
@@ -178,13 +217,27 @@ const handleBubbleEvent = (eventName: BubbleEvent, data: ChatMessage) => {
         </el-button>
       </el-tooltip>
     </template>
+
+    <!-- 自定义发送按钮 -->
+    <template #send-button="{ state, execute }">
+      <button :disabled="!state.inputValue || state.loading" @click="execute">
+        {{ state.loading ? '停止' : '发送' }}
+      </button>
+    </template>
   </ChatSender>
 </template>
 ```
 
+#### 功能特性
+
+- **自动调整高度** - 根据内容自动调整输入框高度
+- **快捷键支持** - Enter 发送，Shift+Enter 换行
+- **工具按钮** - 支持深度思考、联网搜索等功能
+- **粘贴处理** - 智能处理粘贴的文本和图片
+
 ### ChatSidebar - 侧边栏
 
-侧边栏组件管理对话历史记录。
+管理对话历史记录和导航。
 
 ```vue
 <template>
@@ -205,13 +258,25 @@ const handleBubbleEvent = (eventName: BubbleEvent, data: ChatMessage) => {
         <span>AI对话平台</span>
       </div>
     </template>
+
+    <!-- 自定义新建按钮 -->
+    <template #new-chat-button>
+      <button class="new-chat-btn">+ 新建对话</button>
+    </template>
   </ChatSidebar>
 </template>
 ```
 
+#### 功能特性
+
+- **历史记录管理** - 创建、切换、删除对话记录
+- **搜索功能** - 快速搜索历史对话
+- **折叠展开** - 支持侧边栏折叠以节省空间
+- **拖拽调整** - 可拖拽调整侧边栏宽度
+
 ### ThinkingProcess - 思考过程
 
-展示AI的思考推理过程。
+展示 AI 的思考推理过程。
 
 ```vue
 <template>
@@ -232,53 +297,71 @@ const handleBubbleEvent = (eventName: BubbleEvent, data: ChatMessage) => {
 </template>
 ```
 
-## 事件处理
+#### 功能特性
+
+- **折叠展开** - 支持思考过程的折叠和展开
+- **Markdown 渲染** - 思考过程支持 Markdown 格式
+- **实时更新** - 思考过程中实时显示内容
 
-### 消息事件
+## 🎯 事件处理
+
+### 消息发送事件
 
 ```typescript
-// 消息发送
-const handleSend = (text: string) => {
-  // 添加用户消息
+// 发送消息
+const handleSend = (text: string, isEnableThink?: boolean, isEnableNet?: boolean) => {
+  // 1. 添加用户消息
   messages.value.push({
     id: generateId(),
     role: 'user',
     content: text,
-    timestamp: Date.now()
+    timestamp: Date.now(),
+    isThinking: isEnableThink,
+    extraData: {
+      question: text
+    }
   });
 
-  // 调用AI接口
-  callAI(text).then((response) => {
+  // 2. 调用AI接口
+  callAI(text, isEnableThink, isEnableNet).then((response) => {
     // 处理AI响应
   });
 };
+```
+
+### 气泡交互事件
 
-// 气泡交互事件
+```typescript
 const handleBubbleEvent = (eventName: BubbleEvent, message: ChatMessage) => {
   switch (eventName) {
     case 'like':
       // 点赞处理
-      message.isLiked = true;
+      message.isLiked = !message.isLiked;
       message.isDisliked = false;
       break;
+
     case 'dislike':
       // 点踩处理
+      message.isDisliked = !message.isDisliked;
       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;
@@ -287,12 +370,52 @@ const handleBubbleEvent = (eventName: BubbleEvent, message: ChatMessage) => {
 };
 ```
 
+### 记录管理事件
+
+```typescript
+// 创建新记录
+const handleCreateRecord = (messages: ChatMessage[]) => {
+  const newRecord: ChatRecord = {
+    id: generateId(),
+    name: messages[0]?.content.slice(0, 20) + '...' || '新对话',
+    content: messages[0]?.content || '',
+    type: 'text',
+    createTime: new Date().toLocaleDateString(),
+    userId: 'current-user',
+    extraData: { messages }
+  };
+
+  records.value.unshift(newRecord);
+  activeRecordId.value = newRecord.id;
+};
+
+// 切换记录
+const handleChangeRecord = (record?: ChatRecord) => {
+  if (record) {
+    messages.value = record.extraData?.messages || [];
+    activeRecordId.value = record.id;
+  }
+};
+
+// 删除记录
+const handleDeleteRecord = (record: ChatRecord) => {
+  const index = records.value.findIndex((r) => r.id === record.id);
+  if (index > -1) {
+    records.value.splice(index, 1);
+    if (activeRecordId.value === record.id) {
+      activeRecordId.value = null;
+      messages.value = [];
+    }
+  }
+};
+```
+
 ### 流式消息处理
 
 ```typescript
-import { SSEClient } from './sse-client';
+import { SSEClient } from '@kernelift/ai-chat';
 
-const handleStreamResponse = async (question: string) => {
+const handleStreamResponse = async (question: string, enableThink?: boolean) => {
   const client = new SSEClient('your-token', 'https://api.example.com');
 
   let currentMessage: ChatMessage = {
@@ -300,7 +423,8 @@ const handleStreamResponse = async (question: string) => {
     role: 'assistant',
     content: '',
     timestamp: Date.now(),
-    loading: true
+    loading: true,
+    isThinking: enableThink
   };
 
   messages.value.push(currentMessage);
@@ -310,6 +434,13 @@ const handleStreamResponse = async (question: string) => {
       currentMessage.content += content;
     },
 
+    onThinkingDelta: (content: string) => {
+      if (!currentMessage.thoughtProcess) {
+        currentMessage.thoughtProcess = '';
+      }
+      currentMessage.thoughtProcess += content;
+    },
+
     onToolCallDelta: (data: any) => {
       // 处理工具调用
       if (!currentMessage.toolCalls) {
@@ -333,12 +464,426 @@ const handleStreamResponse = async (question: string) => {
   };
 
   await client.connect('/api/chat/stream', handlers, {
-    body: { question }
+    body: { question, enable_thinking: enableThink }
   });
 };
 ```
 
-## 样式定制
+## 🎨 样式定制
+
+### CSS 变量定制
+
+```css
+/* 全局样式变量 */
+:root {
+  /* 主题色 */
+  --kl-chat-primary-color: #615ced;
+  --kl-chat-primary-rgb: 97, 92, 237;
+
+  /* 文本颜色 */
+  --kl-text-color: #1b1b1b;
+  --kl-note-color: #9ca3af;
+  --kl-process-text-color: #61666b;
+
+  /* 背景色 */
+  --kl-background-color: #fff;
+  --kl-main-background-color: #f7f8fc;
+  --kl-sender-background-color: #fff;
+
+  /* 输入框 */
+  --kl-sender-text-color: #4a4a4a;
+  --kl-tool-button-default-color: #7d7d7d;
+
+  /* 边框 */
+  --kl-border-color: #d1d5db;
+
+  /* 主题色衍生 */
+  --kl-color-primary: var(--kl-chat-primary-color);
+  --kl-color-primary-light-3: #8a86f1;
+  --kl-color-primary-light-5: #a9a6f5;
+  --kl-color-primary-light-7: #c8c6f8;
+  --kl-color-primary-light-8: #dddafc;
+  --kl-color-primary-light-9: #f2f1fe;
+}
+
+/* 暗色主题 */
+.dark {
+  --kl-chat-primary-color: #8a86f1;
+  --kl-text-color: #e5e7eb;
+  --kl-note-color: #9ca3af;
+  --kl-background-color: #1a1a1a;
+  --kl-main-background-color: #262626;
+  --kl-sender-background-color: #2d2d2d;
+  --kl-sender-text-color: #e5e7eb;
+  --kl-border-color: #374151;
+  --kl-process-text-color: #9ca3af;
+}
+```
+
+### SCSS 样式定制
+
+```scss
+// 自定义主题
+.kernelift-chat-container {
+  // 主容器样式
+  border-radius: 16px;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.1);
+  overflow: hidden;
+
+  &__aside {
+    // 侧边栏样式
+    background: linear-gradient(180deg, #ffffff 0%, #f8f9fa 100%);
+    border-right: 1px solid var(--kl-border-color);
+  }
+
+  &__messages-section {
+    // 消息区域样式
+    background-color: var(--kl-main-background-color);
+  }
+
+  &__sender {
+    // 发送器样式
+    background-color: var(--kl-sender-background-color);
+    border-top: 1px solid var(--kl-border-color);
+  }
+}
+
+// 自定义消息气泡
+.custom-chat-bubble {
+  .kernelift-chat-bubble__assistant {
+    background: linear-gradient(135deg, #ffffff 0%, #f0f4ff 100%);
+    border: 1px solid #e1e8ff;
+    border-radius: 12px;
+
+    &:hover {
+      box-shadow: 0 4px 12px rgba(97, 92, 237, 0.1);
+    }
+  }
+
+  .kernelift-chat-bubble__user {
+    &-content {
+      background: linear-gradient(135deg, var(--kl-chat-primary-color) 0%, #8a86f1 100%);
+      color: white;
+      border-radius: 12px;
+
+      &:hover {
+        opacity: 0.9;
+      }
+    }
+  }
+}
+
+// 自定义发送器
+.custom-chat-sender {
+  .kernelift-chat-sender__textarea {
+    border-radius: 8px;
+    border: 2px solid var(--kl-border-color);
+
+    &:focus {
+      border-color: var(--kl-chat-primary-color);
+      box-shadow: 0 0 0 3px rgba(97, 92, 237, 0.1);
+    }
+  }
+
+  .kernelift-chat-sender__send-button {
+    background: linear-gradient(135deg, var(--kl-chat-primary-color) 0%, #8a86f1 100%);
+    border-radius: 8px;
+
+    &:hover:not(:disabled) {
+      transform: translateY(-1px);
+      box-shadow: 0 4px 12px rgba(97, 92, 237, 0.3);
+    }
+  }
+}
+```
+
+### 响应式样式
+
+```scss
+// 移动端适配
+@media (max-width: 768px) {
+  .kernelift-chat-container {
+    height: 100vh;
+    border-radius: 0;
+
+    &__aside {
+      position: fixed;
+      left: -100%;
+      top: 0;
+      height: 100vh;
+      width: 80vw;
+      z-index: 1000;
+      transition: left 0.3s ease;
+
+      &.mobile-open {
+        left: 0;
+      }
+    }
+
+    &__main {
+      margin-left: 0;
+    }
+
+    &__sender {
+      height: 160px;
+    }
+  }
+
+  .kernelift-chat-bubble {
+    margin: 8px 12px;
+
+    &__actions {
+      opacity: 1; // 移动端始终显示操作按钮
+    }
+  }
+}
+```
+
+## 💻 完整示例
+
+### 基础聊天应用
+
+```vue
+<template>
+  <div class="chat-app">
+    <ChatContainer
+      v-model="inputText"
+      v-model:loading="senderLoading"
+      v-model:messages="messages"
+      v-model:record-id="activeRecordId"
+      :records="records"
+      :theme-mode="themeMode"
+      :is-generate-loading="generateLoading"
+      :record-actions="recordActions"
+      has-theme-mode
+      has-thinking
+      :markdown-class-name="themeMode === 'dark' ? 'prose-invert' : 'prose'"
+      @send="handleSend"
+      @cancel="handleCancel"
+      @create-record="handleCreateRecord"
+      @change-record="handleChangeRecord"
+      @bubble-event="handleBubbleEvent"
+      @change-theme="(mode) => (themeMode = mode)"
+    >
+      <!-- 自定义空状态 -->
+      <template #empty>
+        <div class="empty-state">
+          <div class="welcome-title">AI 助手</div>
+          <div class="welcome-desc">你好！有什么可以帮助你的吗？</div>
+        </div>
+      </template>
+
+      <!-- 自定义 Logo -->
+      <template #logo>
+        <div class="brand-logo">
+          <IconRender icon="material-symbols:chat" />
+          <span>AI 对话</span>
+        </div>
+      </template>
+    </ChatContainer>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onUnmounted } from 'vue';
+import {
+  ChatContainer,
+  type BubbleEvent,
+  type ChatMessage,
+  type ChatRecord,
+  type ChatRecordAction
+} from '@kernelift/ai-chat';
+import '@kernelift/ai-chat/style.css';
+import { useStorage } from '@vueuse/core';
+
+// 状态管理
+const inputText = ref('');
+const messages = ref<ChatMessage[]>([]);
+const records = useStorage<ChatRecord[]>('chat-records', []);
+const activeRecordId = ref<string | null>(null);
+const senderLoading = ref(false);
+const generateLoading = ref(false);
+const themeMode = ref<'light' | 'dark'>('light');
+
+// 记录操作
+const recordActions: ChatRecordAction[] = [
+  {
+    id: 'edit',
+    name: '编辑',
+    icon: 'edit',
+    action: (record) => {
+      console.log('编辑记录:', record);
+    }
+  },
+  {
+    id: 'delete',
+    name: '删除',
+    icon: 'delete',
+    action: (record) => {
+      records.value = records.value.filter((r) => r.id !== record.id);
+    }
+  }
+];
+
+// 发送消息
+const handleSend = async (text: string, enableThink?: boolean) => {
+  inputText.value = '';
+
+  // 添加用户消息
+  messages.value.push({
+    id: Date.now().toString(),
+    role: 'user',
+    content: text,
+    timestamp: Date.now(),
+    isThinking: enableThink
+  });
+
+  senderLoading.value = true;
+  generateLoading.value = true;
+
+  try {
+    // 模拟 AI 响应
+    await simulateAIResponse(text, enableThink);
+  } catch (error) {
+    console.error('发送失败:', error);
+  } finally {
+    senderLoading.value = false;
+    generateLoading.value = false;
+  }
+};
+
+// 模拟 AI 响应
+const simulateAIResponse = async (text: string, enableThink?: boolean) => {
+  const responseId = Date.now().toString();
+
+  messages.value.push({
+    id: responseId,
+    role: 'assistant',
+    content: '',
+    timestamp: Date.now(),
+    loading: true,
+    isThinking: enableThink
+  });
+
+  const targetMessage = messages.value.find((m) => m.id === responseId)!;
+
+  // 模拟思考过程
+  if (enableThink) {
+    targetMessage.thoughtProcess = '正在分析用户问题...\n';
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    targetMessage.thoughtProcess += '整理相关信息...\n';
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    targetMessage.thoughtProcess += '生成回答...\n';
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    targetMessage.isThinking = false;
+  }
+
+  // 模拟流式响应
+  const response = `这是对"${text}"的回答。`;
+  for (let i = 0; i < response.length; i++) {
+    targetMessage.content += response[i];
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+
+  targetMessage.loading = false;
+};
+
+// 取消生成
+const handleCancel = () => {
+  generateLoading.value = false;
+  senderLoading.value = false;
+
+  const lastMessage = messages.value[messages.value.length - 1];
+  if (lastMessage?.loading) {
+    lastMessage.loading = false;
+    lastMessage.isTerminated = true;
+  }
+};
+
+// 处理气泡事件
+const handleBubbleEvent = (event: BubbleEvent, data: ChatMessage) => {
+  switch (event) {
+    case 'like':
+      data.isLiked = !data.isLiked;
+      data.isDisliked = false;
+      break;
+    case 'dislike':
+      data.isDisliked = !data.isDisliked;
+      data.isLiked = false;
+      break;
+    case 'copy':
+      navigator.clipboard.writeText(data.content);
+      break;
+    case 'bookmark':
+      data.isBookmarked = !data.isBookmarked;
+      break;
+  }
+};
+
+// 创建记录
+const handleCreateRecord = (msgs: ChatMessage[]) => {
+  const newRecord: ChatRecord = {
+    id: Date.now().toString(),
+    name: msgs[0]?.content.slice(0, 20) + '...' || '新对话',
+    content: msgs[0]?.content || '',
+    type: 'text',
+    createTime: new Date().toLocaleDateString(),
+    userId: 'current-user',
+    extraData: { messages: msgs }
+  };
+
+  records.value.unshift(newRecord);
+  activeRecordId.value = newRecord.id;
+};
+
+// 切换记录
+const handleChangeRecord = (record?: ChatRecord) => {
+  if (record) {
+    messages.value = record.extraData?.messages || [];
+    activeRecordId.value = record.id;
+  } else {
+    messages.value = [];
+    activeRecordId.value = null;
+  }
+};
+</script>
+
+<style scoped>
+.chat-app {
+  height: 100vh;
+  padding: 20px;
+  background: #f5f5f5;
+}
+
+.empty-state {
+  text-align: center;
+  padding: 60px 20px;
+}
+
+.welcome-title {
+  font-size: 32px;
+  font-weight: bold;
+  margin-bottom: 16px;
+  color: var(--kl-chat-primary-color);
+}
+
+.welcome-desc {
+  font-size: 16px;
+  color: var(--kl-note-color);
+  line-height: 1.6;
+}
+
+.brand-logo {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 18px;
+  font-weight: bold;
+}
+</style>
+```
+
+## 📖 API 文档
 
 ### CSS 变量定制
 
@@ -809,152 +1354,288 @@ function handleScrollBottom() {
 </style>
 ```
 
-### 移动端适配示例
+### Props 属性
+
+| 属性名              | 类型                     | 默认值      | 说明               |
+| ------------------- | ------------------------ | ----------- | ------------------ |
+| `records`           | `ChatRecord[]`           | `[]`        | 聊天记录列表       |
+| `recordActions`     | `ChatRecordAction[]`     | `[]`        | 记录操作按钮配置   |
+| `hasHeader`         | `boolean`                | `true`      | 是否显示头部       |
+| `hasThemeMode`      | `boolean`                | `false`     | 是否支持主题切换   |
+| `hasThinking`       | `boolean`                | `true`      | 是否支持深度思考   |
+| `hasNetSearch`      | `boolean`                | `false`     | 是否支持联网搜索   |
+| `hasSenderTools`    | `boolean`                | `false`     | 是否显示发送工具区 |
+| `showWorkspace`     | `boolean`                | `true`      | 是否显示工作区     |
+| `showSender`        | `boolean`                | `true`      | 是否显示发送框     |
+| `isGenerateLoading` | `boolean`                | `undefined` | 是否正在生成       |
+| `defaultRecordId`   | `string`                 | `undefined` | 默认记录ID         |
+| `defaultCollapse`   | `boolean`                | `false`     | 侧边栏默认折叠     |
+| `defaultAsideWidth` | `number`                 | `250`       | 侧边栏默认宽度     |
+| `markdownClassName` | `string`                 | `undefined` | Markdown 样式类名  |
+| `primaryColor`      | `string`                 | `'#615ced'` | 主题色             |
+| `themeMode`         | `'light' \| 'dark'`      | `'light'`   | 主题模式           |
+| `enableNet`         | `boolean`                | `undefined` | 联网搜索启用状态   |
+| `enableThink`       | `boolean`                | `undefined` | 深度思考启用状态   |
+| `inputHeight`       | `number`                 | `140`       | 输入框高度         |
+| `onCopy`            | `(code: string) => void` | `undefined` | 复制代码回调       |
+| `i18n`              | `Record<string, any>`    | `zhCN`      | 国际化配置         |
+
+### v-model 双向绑定
+
+| 属性名                | 类型             | 说明             |
+| --------------------- | ---------------- | ---------------- |
+| `v-model`             | `string`         | 输入框文本       |
+| `v-model:messages`    | `ChatMessage[]`  | 消息列表         |
+| `v-model:loading`     | `boolean`        | 发送加载状态     |
+| `v-model:recordId`    | `string \| null` | 当前记录ID       |
+| `v-model:enableThink` | `boolean`        | 深度思考启用状态 |
+| `v-model:enableNet`   | `boolean`        | 联网搜索启用状态 |
+
+### Events 事件
+
+| 事件名               | 参数                                                         | 说明           |
+| -------------------- | ------------------------------------------------------------ | -------------- |
+| `send`               | `(text: string, enableThink?: boolean, enableNet?: boolean)` | 发送消息       |
+| `cancel`             | -                                                            | 取消生成       |
+| `clear`              | -                                                            | 清空聊天       |
+| `create-record`      | `(messages: ChatMessage[])`                                  | 创建记录       |
+| `change-record`      | `(record?: ChatRecord)`                                      | 切换记录       |
+| `change-collapse`    | `(collapse: boolean)`                                        | 折叠状态改变   |
+| `change-theme`       | `(theme: 'light' \| 'dark')`                                 | 主题切换       |
+| `change-aside-width` | `(width: number)`                                            | 侧边栏宽度改变 |
+| `click-logo`         | -                                                            | 点击Logo       |
+| `bubble-event`       | `(event: BubbleEvent, message: ChatMessage)`                 | 气泡交互事件   |
+| `close-workspace`    | -                                                            | 关闭工作区     |
+| `scroll-bottom`      | -                                                            | 滚动到底部     |
+
+### Slots 插槽
+
+| 插槽名                   | 参数                                                                    | 说明           |
+| ------------------------ | ----------------------------------------------------------------------- | -------------- |
+| `left-aside`             | `{ mobile: boolean }`                                                   | 左侧边栏       |
+| `aside`                  | `{ record: ChatRecord \| undefined, mobile: boolean }`                  | 主侧边栏       |
+| `logo`                   | `{ mobile: boolean }`                                                   | Logo区域       |
+| `new-chat-button`        | `{ mobile: boolean }`                                                   | 新建聊天按钮   |
+| `record-dropdown`        | `{ mobile: boolean }`                                                   | 记录下拉菜单   |
+| `header`                 | `{ record: ChatRecord \| undefined, mobile: boolean }`                  | 头部区域       |
+| `header-logo`            | `{ mobile: boolean }`                                                   | 头部Logo       |
+| `bubble-header`          | `{ data: ChatMessage, mobile: boolean }`                                | 气泡头部       |
+| `bubble-footer`          | `{ data: ChatMessage, mobile: boolean }`                                | 气泡底部       |
+| `bubble-event`           | `{ data: ChatMessage, mobile: boolean }`                                | 气泡操作区     |
+| `bubble-content-header`  | `{ data: ChatMessage, mobile: boolean }`                                | 气泡内容头部   |
+| `bubble-content-footer`  | `{ data: ChatMessage, mobile: boolean }`                                | 气泡内容底部   |
+| `bubble-thinking-header` | `{ data: ChatMessage, mobile: boolean }`                                | 思考过程头部   |
+| `bubble-loading-content` | `{ mobile: boolean }`                                                   | 加载内容       |
+| `empty`                  | `{ mobile: boolean }`                                                   | 空状态         |
+| `sender-tools`           | `{ mobile: boolean }`                                                   | 发送工具区     |
+| `sender-footer-tools`    | `{ value: string, loading: boolean, mobile: boolean }`                  | 发送器底部工具 |
+| `footer`                 | `{ mobile: boolean }`                                                   | 底部区域       |
+| `workspace`              | `{ record: ChatRecord \| undefined, mobile: boolean }`                  | 工作区         |
+| `send-button`            | `{ state: object, execute: Function, mobile: boolean }`                 | 发送按钮       |
+| `think-button`           | `{ state: object, execute: Function, mobile: boolean }`                 | 思考按钮       |
+| `net-button`             | `{ state: object, execute: Function, mobile: boolean }`                 | 联网按钮       |
+| `sender-textarea`        | `{ state: object, execute: Function, mobile: boolean, height: number }` | 输入框         |
+
+### 类型定义
+
+#### ChatMessage
+
+```typescript
+interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  loading?: boolean;
+  isThinking?: boolean;
+  thoughtCollapse?: boolean;
+  thoughtProcess?: string;
+  timestamp: number;
+  isTerminated?: boolean;
+  isLiked?: boolean;
+  isDisliked?: boolean;
+  isError?: boolean;
+  error?: string;
+  isBookmarked?: boolean;
+  nextTips?: string[];
+  toolCalls?: any[];
+  hideFooterTools?: boolean;
+  extraData?: Record<string, any>;
+}
+```
+
+#### ChatRecord
+
+```typescript
+interface ChatRecord {
+  id: string;
+  name: string;
+  content: string;
+  type: string;
+  createTime: string;
+  userId: string;
+  updateTime?: string;
+  extraData?: Record<string, any>;
+}
+```
+
+#### BubbleEvent
+
+```typescript
+type BubbleEvent = 'like' | 'dislike' | 'bookmark' | 'terminate' | 'reload' | 'copy';
+```
+
+#### ChatRecordAction
+
+```typescript
+interface ChatRecordAction {
+  id: string;
+  name: string;
+  icon?: string | Component;
+  divided?: boolean;
+  disabled?: boolean;
+  action: (record: ChatRecord) => void;
+}
+```
+
+## ❓ 常见问题
+
+### Q: 如何自定义主题色？
+
+A: 通过 `primary-color` 属性和 CSS 变量可以自定义主题色：
 
 ```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, mobile }">
-      <div class="mobile-tools">
-        <el-button :disabled="!value || loading" size="small" @click="handleQuickAction">
-          快捷操作
-        </el-button>
-      </div>
-    </template>
-  </ChatContainer>
-</template>
+<ChatContainer primary-color="#ff6b6b" />
+```
 
-<style scoped>
-/* 移动端样式优化 */
-@media (max-width: 768px) {
-  :deep(.kernelift-chat-container) {
-    padding: 4px;
-  }
+```css
+:root {
+  --kl-chat-primary-color: #ff6b6b;
+}
+```
 
-  :deep(.kernelift-chat-sender) {
-    height: 160px;
-  }
+### Q: 如何集成 AI 服务？
+
+A: 在 `send` 事件中调用你的 AI 服务接口：
+
+```typescript
+const handleSend = async (text: string) => {
+  // 添加用户消息
+  messages.value.push({
+    id: generateId(),
+    role: 'user',
+    content: text,
+    timestamp: Date.now()
+  });
 
-  :deep(.kernelift-chat-bubble__actions) {
-    opacity: 1; /* 移动端始终显示操作按钮 */
+  try {
+    // 调用 AI 服务
+    const response = await yourAIService.chat(text);
+
+    // 添加 AI 响应
+    messages.value.push({
+      id: generateId(),
+      role: 'assistant',
+      content: response.content,
+      timestamp: Date.now()
+    });
+  } catch (error) {
+    console.error('AI 服务错误:', error);
   }
-}
-</style>
+};
+```
+
+### Q: 如何实现流式响应？
+
+A: 使用内置的 SSEClient 或其他流式处理方案：
+
+```typescript
+import { SSEClient } from '@kernelift/ai-chat';
+
+const handleStreamResponse = async (question: string) => {
+  const client = new SSEClient('token', 'https://api.example.com');
+
+  const currentMessage = {
+    id: generateId(),
+    role: 'assistant',
+    content: '',
+    timestamp: Date.now(),
+    loading: true
+  };
+
+  messages.value.push(currentMessage);
+
+  await client.connect('/chat/stream', {
+    onContent: (content) => {
+      currentMessage.content += content;
+    },
+    onComplete: () => {
+      currentMessage.loading = false;
+    },
+    onError: (error) => {
+      currentMessage.loading = false;
+      currentMessage.isError = true;
+    }
+  });
+};
+```
+
+### Q: 如何在移动端使用？
+
+A: 组件内置了响应式支持，移动端会自动适配。可以通过 `mobile` 插槽参数进行移动端特定定制：
+
+```vue
+<template #sender-footer-tools="{ mobile }">
+  <div v-if="mobile" class="mobile-tools">
+    <!-- 移动端特定工具 -->
+  </div>
+</template>
+```
+
+### Q: 如何持久化聊天记录？
+
+A: 使用 `useStorage` 或其他持久化方案：
+
+```typescript
+import { useStorage } from '@vueuse/core';
+
+const records = useStorage<ChatRecord[]>('chat-records', []);
+const messages = useStorage<ChatMessage[]>('current-messages', []);
+```
+
+### Q: 如何处理长对话？
+
+A: 建议实现分页加载或记录分割：
+
+```typescript
+const handleLoadMore = async () => {
+  const olderMessages = await loadOlderMessages(currentPage);
+  messages.value.unshift(...olderMessages);
+};
+```
+
+### Q: 如何添加自定义工具按钮？
+
+A: 通过 `sender-tools` 插槽添加：
+
+```vue
+<template #sender-tools>
+  <el-tooltip content="自定义工具">
+    <el-button @click="handleCustomTool">
+      <IconRender icon="custom-icon" />
+    </el-button>
+  </el-tooltip>
+</template>
 ```
 
-## API 参考
-
-### ChatProps 接口属性说明
-
-根据提供的 `withDefaults` 配置，以下表格展示了 `ChatProps` 接口中各个属性的默认值：
-
-| 参数                | 类型                     | 默认值      | 说明                               |
-| ------------------- | ------------------------ | ----------- | ---------------------------------- |
-| `records`           | `ChatRecord[]`           | `[]`        | 聊天记录列表，默认为空数组         |
-| `recordActions`     | `ChatRecordAction[]`     | `[]`        | 聊天记录操作按钮配置，默认为空数组 |
-| `hasHeader`         | `boolean`                | `true`      | 是否显示聊天区域头部，默认显示     |
-| `hasThemeMode`      | `boolean`                | `false`     | 是否支持主题切换，默认不支持       |
-| `hasThinking`       | `boolean`                | `true`      | 是否支持深度思考功能，默认支持     |
-| `hasNetSearch`      | `boolean`                | `false`     | 是否支持联网搜索功能，默认不支持   |
-| `hasSenderTools`    | `boolean`                | `false`     | 是否显示发送工具区域，默认不显示   |
-| `showWorkspace`     | `boolean`                | `true`      | 是否显示工作区，默认显示           |
-| `showSender`        | `boolean`                | `true`      | 是否显示发送框，默认显示           |
-| `isGenerateLoading` | `boolean`                | `undefined` | 是否处于生成加载状态，无默认值     |
-| `defaultRecordId`   | `string`                 | `undefined` | 默认选中聊天记录ID，无默认值       |
-| `defaultCollapse`   | `boolean`                | `false`     | 侧边栏默认折叠状态，默认展开       |
-| `defaultAsideWidth` | `number`                 | `250`       | 侧边栏默认宽度，250像素            |
-| `markdownClassName` | `string`                 | `undefined` | Markdown内容自定义类名，无默认值   |
-| `primaryColor`      | `string`                 | `'#615ced'` | 主题主色调，默认紫色 `#615ced`     |
-| `themeMode`         | `'light' \| 'dark'`      | `'light'`   | 主题模式，默认亮色模式             |
-| `enableNet`         | `boolean`                | `undefined` | 联网搜索启用状态，无默认值         |
-| `enableThink`       | `boolean`                | `undefined` | 深度思考启用状态，无默认值         |
-| `inputHeight`       | `number`                 | `140`       | 发送框高度                         |
-| `onChat`            | `(code: string) => void` | `undefined` | 自定义点击复制代码触发             |
-
-#### 注意事项
-
-1. **无默认值属性**：以下属性没有默认值，使用时需要检查是否为 `undefined`：
-   - `isGenerateLoading`
-   - `defaultRecordId`
-   - `markdownClassName`
-   - `enableNet`
-   - `enableThink`
-2. **默认显示**：以下属性默认值为 `true`，表示默认会显示或启用：
-   - `hasHeader` - 显示头部
-   - `showWorkspace` - 显示工作区
-   - `hasThinking` - 支持深度思考
-3. **默认不显示/不支持**：以下属性默认值为 `false`，表示默认不显示或不支持：
-   - `hasThemeMode` - 主题切换功能
-   - `hasNetSearch` - 联网搜索功能
-   - `hasSenderTools` - 发送工具区域
-4. **尺寸相关**：`defaultAsideWidth` 默认值为 `250`，表示侧边栏默认宽度为250像素
-5. **颜色主题**：
-   - `primaryColor` 默认紫色 (`#615ced`)
-   - `themeMode` 默认亮色模式 (`light`)
-
-### ChatEvents 接口事件说明
-
-| 事件名               | 参数                                                                | 返回值类型 | 说明                                                             |
-| -------------------- | ------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- |
-| `send`               | `value: string`, `isEnableThink?: boolean`, `isEnableNet?: boolean` | `void`     | 发送消息时触发，携带消息内容、是否启用思考和是否启用联网搜索参数 |
-| `cancel`             | 无参数                                                              | `void`     | 取消消息生成/发送时触发                                          |
-| `clear`              | 无参数                                                              | `void`     | 清空当前聊天记录时触发                                           |
-| `create-record`      | `data: ChatMessage[]`                                               | `void`     | 创建新聊天记录时触发，携带消息数据数组                           |
-| `change-record`      | `value?: ChatRecord`                                                | `void`     | 切换聊天记录时触发，携带选中的聊天记录（可选）                   |
-| `change-collapse`    | `collapse: boolean`                                                 | `void`     | 侧边栏折叠状态改变时触发，携带当前折叠状态                       |
-| `change-theme`       | `themeMode: 'light' \| 'dark'`                                      | `void`     | 主题切换时触发，携带当前主题模式                                 |
-| `change-aside-width` | `width: number`                                                     | `void`     | 侧边栏宽度改变时触发，携带当前宽度值（像素）                     |
-| `click-logo`         | 无参数                                                              | `void`     | 点击Logo时触发                                                   |
-| `bubble-event`       | `eventName: BubbleEvent`, `data: ChatMessage`                       | `void`     | 消息气泡交互事件触发，携带事件名称和对应的消息数据               |
-| `close-workspace`    | 无参数                                                              | `void`     | 关闭工作区（右侧面板）时触发                                     |
-| `scroll-bottom`      | 无参数                                                              | `void`     | 聊天记录（左侧面板）滚动至底部时触发                             |
-
-### 补充说明
-
-2. **受控属性**：`enableNet` 和 `enableThink` 是受控属性，需要通过 `v-model:enable-net` 和 `v-model:enable-think` 进行双向绑定
-3. **事件参数**：所有事件均通过 `emit` 方法触发，父组件可以通过 `@事件名` 监听
-4. **类型定义**：表格中的 `ChatRecord`、`ChatRecordAction`、`ChatMessage`、`BubbleEvent` 等类型需要根据实际项目中的定义进行替换
-5. **默认值**：所有属性的默认值均为 `undefined`，表示组件内部会有相应的默认处理逻辑
-
-### 插槽列表
-
-| Slot 名称                | 作用域参数                                                                                                | 说明                           |
-| ------------------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| `left-aside`             | `{ mobile: boolean }`                                                                                     | 左侧侧边栏区域                 |
-| `aside`                  | `{ record: ChatRecord \| undefined, mobile: boolean }`                                                    | 主侧边栏区域，包含聊天记录列表 |
-| `logo`                   | `{ mobile: boolean }`                                                                                     | 侧边栏 Logo 区域               |
-| `new-chat-button`        | `{ mobile: boolean }`                                                                                     | 新建聊天按钮区域               |
-| `record-dropdown`        | `{ mobile: boolean }`                                                                                     | 聊天记录下拉菜单区域           |
-| `header`                 | `{ record: ChatRecord \| undefined, mobile: boolean }`                                                    | 聊天头部区域                   |
-| `header-logo`            | `{ mobile: boolean }`                                                                                     | 折叠状态下的头部 Logo          |
-| `bubble-header`          | `{ data: ChatMessage, mobile: boolean }`                                                                  | 消息气泡头部                   |
-| `bubble-footer`          | `{ data: ChatMessage, mobile: boolean }`                                                                  | 消息气泡底部                   |
-| `bubble-event`           | `{ data: ChatMessage, mobile: boolean }`                                                                  | 消息气泡事件处理区域           |
-| `bubble-content-header`  | `{ data: ChatMessage, mobile: boolean }`                                                                  | 消息气泡内容顶部               |
-| `bubble-content-footer`  | `{ data: ChatMessage, mobile: boolean }`                                                                  | 消息气泡内容底部               |
-| `bubble-thinking-header` | `{ data: ChatMessage, mobile: boolean }`                                                                  | 思考过程头部                   |
-| `bubble-loading-content` | `{ mobile: boolean }`                                                                                     | 加载中的消息内容               |
-| `empty`                  | `{ mobile: boolean }`                                                                                     | 空状态显示内容                 |
-| `sender-tools`           | `{ mobile: boolean }`                                                                                     | 发送工具区域                   |
-| `sender-footer-tools`    | `{ value: string, loading: boolean, mobile: boolean }`                                                    | 发送器底部工具区域             |
-| `footer`                 | `{ mobile: boolean }`                                                                                     | 页面底部区域                   |
-| `workspace`              | `{ record: ChatRecord \| undefined, mobile: boolean }`                                                    | 工作区内容                     |
-| `send-button`            | `{ state: { inputValue: string, loading: boolean }, execute: Function, mobile: boolean }`                 | 发送按钮                       |
-| `think-button`           | `{ state: { enableThink: boolean, hasThinking: boolean }, execute: Function, mobile: boolean }`           | 思考按钮                       |
-| `net-button`             | `{ state: { enableNet: boolean, hasNetSearch: boolean }, execute: Function, mobile: boolean }`            | 联网按钮                       |
-| `sender-textarea`        | `{ state: { inputValue: string, loading: boolean }, execute: Function, mobile: boolean, height: number }` | 发送输入文本框                 |
+## 📄 许可证
+
+GPL-3.0 License
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
 
 ---
 
-**版本**: 1.0.0  
-**兼容性**: Vue 3.3+  
-**License**: 商业使用需联系授权
+**版本**: 2.0.0  
+**更新时间**: 2024-12-25