npm package: @linloop/ai-chat-plugin
Description: Vue 3 AI Chat Component with customizable themes and models
Author: LinLoop
Latest version: 2.0.5

# @linloop/ai-chat-plugin

一个功能强大的 Vue 3 AI 聊天组件，支持自定义主题、模型配置、虚拟滚动和深度思考功能。

## ✨ 特性

- 🎨 完全可定制的主题系统
- 🤖 支持多种 AI 模型配置
- 📡 丰富的事件钩子和回调函数
- ⚙️ 灵活的显示选项和配置
- 🔧 完整的方法暴露和状态管理
- 📱 响应式设计和移动端适配
- 🎯 完整的 TypeScript 类型支持
- 🚀 虚拟滚动优化，支持大量消息
- 🧠 深度思考功能，显示AI思考过程
- 📊 实时状态管理和错误处理

## 📦 安装

```bash
npm install @linloop/ai-chat-plugin
# 或
yarn add @linloop/ai-chat-plugin
# 或
pnpm add @linloop/ai-chat-plugin
```

## 🚀 快速开始

### 作为组件使用

```vue
<template>
  <AiChat 
    :models="models"
    :theme-config="themeConfig"
    :default-model="defaultModel"
    :show-model-selector="true"
    :show-clear-button="true"
    :show-close-button="true"
    :auto-scroll="true"
    :max-messages="100"
    :placeholder="'请输入您的问题...'"
    :welcome-message="'欢迎使用AI助手'"
    :welcome-description="'我可以帮助您解答各种问题'"
    :show-thinking="true"
    :enable-thinking="true"
    @reply-complete="handleReplyComplete"
    @message-sent="handleMessageSent"
    @model-change="handleModelChange"
    @clear="handleClear"
    @close="handleClose"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { AiChat, type ModelConfig, type ThemeConfig } from '@linloop/ai-chat-plugin'

const models = ref<ModelConfig[]>([
  { value: 'gpt-4', label: 'GPT-4', description: 'OpenAI 最新模型' },
  { value: 'claude', label: 'Claude-3', description: 'Anthropic 最新模型' },
  { value: 'gemini', label: 'Gemini Pro', description: 'Google 最新模型' }
])

const themeConfig = ref<Partial<ThemeConfig>>({
  primaryColor: '#1890ff',
  background: '#ffffff',
  fontSize: '14px',
  fontFamily: 'system-ui, -apple-system, sans-serif',
  shadow: '0 2px 8px rgba(0, 0, 0, 0.1)',
  inputBorderColor: '#d9d9d9'
})

const defaultModel = ref('gpt-4')

const handleReplyComplete = (message) => {
  console.log('AI回复完成:', message)
}

const handleMessageSent = (message) => {
  console.log('用户消息发送:', message)
}

const handleModelChange = (model) => {
  console.log('模型切换为:', model)
}

const handleClear = () => {
  console.log('聊天记录已清空')
}

const handleClose = () => {
  console.log('聊天窗口已关闭')
}
</script>
```

### 作为插件使用

```typescript
import { createApp } from 'vue'
import AiChatPlugin from '@linloop/ai-chat-plugin'
import App from './App.vue'

const app = createApp(App)
app.use(AiChatPlugin)
app.mount('#app')
```

## 📚 完整文档

详细的 API 文档和使用示例，请查看 [组件使用说明](./src/components/ai-chat/README.md)。

## 🎨 主题配置

```typescript
interface ThemeConfig {
  primaryColor?: string;       // 主色调
  background?: string;         // 背景色
  fileUploadText?: string;     // 文件上传文本
  inputBorderRadius?: string;  // 输入框圆角
  fontSize?: string;          // 字体大小
  fontFamily?: string;        // 字体族
  shadow?: string;            // 阴影效果
  inputBorderColor?: string;  // 输入框边框颜色
  hideMessage?: boolean; // 隐藏对话框
}
```

## 🤖 模型配置

```typescript
interface ModelConfig {
  value: string;        // 模型值（唯一标识）
  label: string;        // 显示标签
  description?: string; // 模型描述
  disabled?: boolean;   // 是否禁用
}
```

## 📡 事件和回调

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| `@reply-complete` | AI回复完成时触发 | `ChatMessage` |
| `@message-sent` | 用户消息发送时触发 | `ChatMessage` |
| `@model-change` | 模型切换时触发 | `string` (模型值) |
| `@clear` | 清空聊天记录时触发 | - |
| `@close` | 关闭聊天窗口时触发 | - |

## 🔧 组件属性

| 属性名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `models` | `ModelConfig[]` | `[]` | 可选的AI模型列表 |
| `themeConfig` | `Partial<ThemeConfig>` | `{}` | 主题配置 |
| `defaultModel` | `string` | - | 默认选中的模型 |
| `autoScroll` | `boolean` | `true` | 是否自动滚动到底部 |
| `showModelSelector` | `boolean` | `true` | 是否显示模型选择器 |
| `showClearButton` | `boolean` | `true` | 是否显示清空按钮 |
| `showCloseButton` | `boolean` | `false` | 是否显示关闭按钮 |
| `maxMessages` | `number` | `100` | 最大消息数量 |
| `placeholder` | `string` | `'请输入消息...'` | 输入框占位符 |
| `welcomeMessage` | `string` | `'AI助手'` | 欢迎消息标题 |
| `welcomeDescription` | `string` | `'有什么可以帮助您的吗？'` | 欢迎消息描述 |
| `showThinking` | `boolean` | `true` | 是否显示思考状态 |
| `enableThinking` | `boolean` | `true` | 是否启用深度思考功能 |

## 🎯 方法调用

通过 `ref` 可以调用以下方法：

```vue
<template>
  <AiChat ref="aiChatRef" />
  <button @click="clearChat">清空聊天</button>
  <button @click="setModel">切换模型</button>
</template>

<script setup>
import { ref } from 'vue'

const aiChatRef = ref()

const clearChat = () => {
  aiChatRef.value?.clearChat()
}

const setModel = () => {
  aiChatRef.value?.setModel('gpt-4')
}
</script>
```

### 可用方法

- `clearChat()` - 清空聊天记录
- `setModel(model: string)` - 设置当前模型
- `addMessage(message: ChatMessage)` - 添加自定义消息
- `scrollToBottom()` - 滚动到底部
- `pauseMessage()` - 暂停AI响应

### 可用属性

- `messages` - 获取当前消息列表
- `selectedModel` - 获取当前选中的模型
- `loading` - 获取当前加载状态
- `userInput` - 获取用户输入内容

## 🧠 深度思考功能

组件支持显示AI的思考过程，包括：

- 实时显示思考状态
- 可展开/折叠的思考内容
- 思考耗时统计
- 支持暂停和继续响应

## 🚀 性能优化

- **虚拟滚动**: 使用 `vue-virtual-scroller` 优化大量消息的渲染性能
- **懒加载**: 消息按需渲染，提升用户体验
- **状态管理**: 使用 Pinia 进行状态管理
- **响应式设计**: 支持各种屏幕尺寸

## 🎯 类型支持

完整的 TypeScript 类型定义，包括：

- `ChatMessage` - 聊天消息类型
- `ThemeConfig` - 主题配置类型
- `ModelConfig` - 模型配置类型
- `AiChatProps` - 组件属性类型
- `ChatEvents` - 事件类型
- `ChatSession` - 聊天会话类型
- `Conversation` - 对话类型
- `ChatRequest` - 聊天请求类型

## 🔄 版本历史

- **v2.0.2** - 当前版本，支持深度思考、虚拟滚动等高级功能
- **v2.0.0** - 重大更新，支持主题配置、模型配置和事件钩子
- **v1.0.11** - 初始版本

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

- 提交 [GitHub Issue](https://github.com/linloop/ai-chat-monorepo/issues)
- 创建 [Pull Request](https://github.com/linloop/ai-chat-monorepo/pulls)

## 📞 支持

如有问题，请通过以下方式联系：

- 提交 GitHub Issue
- 查看项目文档
- 参与社区讨论

## 🌟 特性亮点

- **智能对话**: 支持多轮对话和上下文理解
- **模型切换**: 支持多种AI模型的无缝切换
- **主题定制**: 完全可定制的UI主题
- **性能优化**: 虚拟滚动和懒加载技术
- **深度思考**: 显示AI的思考过程
- **响应式设计**: 完美适配各种设备

---

**享受使用 AiChat 组件！** 🎉

> 这是一个功能完整、性能优异的Vue 3 AI聊天组件，适用于各种AI对话场景。