# @mxmweb/aichat

> 基于 React 的轻量级 AI 聊天对话组件库，提供核心聊天功能和灵活的扩展能力

[![npm version](https://img.shields.io/npm/v/@mxmweb/aichat.svg)](https://www.npmjs.com/package/@mxmweb/aichat)
[![npm downloads](https://img.shields.io/npm/dm/@mxmweb/aichat.svg)](https://www.npmjs.com/package/@mxmweb/aichat)
[![License](https://img.shields.io/npm/l/@mxmweb/aichat.svg)](https://github.com/your-org/aichat/blob/main/LICENSE)

## ✨ 核心特性

- ✅ **轻量级设计**：Gzip 压缩后仅 ~78KB，专注于核心聊天功能
- ✅ **灵活的组件系统**：支持自定义消息卡片、欢迎页、加载状态等
- ✅ **完整的文件上传**：支持拖拽上传、多文件管理、上传状态跟踪
- ✅ **动态主题系统**：支持运行时主题切换，所有样式可配置
- ✅ **事件驱动架构**：通过 eventsEmit 统一处理所有交互事件
- ✅ **TypeScript 支持**：完整的类型定义，提供良好的开发体验
- ✅ **侧边栏扩展**：支持自定义侧边栏组件和动态表单
- ✅ **纯 UI 组件库**：v2.0.0 版本专注于 UI 展示层，业务逻辑已分离

## 📦 安装

```bash
# 使用 pnpm（推荐）
pnpm add @mxmweb/aichat react react-dom @mxmweb/zui

# 使用 npm
npm install @mxmweb/aichat react react-dom @mxmweb/zui

# 使用 yarn
yarn add @mxmweb/aichat react react-dom @mxmweb/zui
```

### 必需依赖

本库需要以下 peerDependencies：

```bash
pnpm add @mxmweb/zui@^1.* react@>=18 react-dom@>=18
```

### 样式引入

在项目入口文件中引入样式：

```typescript
import '@mxmweb/aichat/style.css';
```

### 包大小

- **Gzip 压缩后**：~78KB
- **原始大小**：~274KB
- **CSS 大小**：~58KB (gzip: ~10KB)

> 💡 **优化说明**：AIChat 已移除不必要的依赖，专注于核心聊天功能，确保快速加载和简洁的安装体验。

## 🚀 快速开始

### 基础用法

```tsx
import React, { useState } from 'react';
import { AiChat } from '@mxmweb/aichat';
import '@mxmweb/aichat/style.css';

function App() {
  const [chatData, setChatData] = useState({
    id: 'session-1',
    messages: [],
    isNew: true,
  });

  const [status, setStatus] = useState({
    display: 'ready',
    sender: 'ready',
    app: 'ready',
  });

  const handleEventsEmit = (eventName: string, data?: any) => {
    console.log('Event:', eventName, data);
    
    if (eventName === 'sender:send') {
      // 处理消息发送
      const newMessage = {
        id: `msg-${Date.now()}`,
        type: 'user',
        time: new Date().toISOString(),
        content: data.content,
      };
      
      setChatData(prev => ({
        ...prev,
        messages: [...prev.messages, newMessage],
      }));
      
      // 模拟 AI 回复
      setTimeout(() => {
        const aiMessage = {
          id: `msg-${Date.now()}`,
          type: 'ai',
          time: new Date().toISOString(),
          content: '这是一条 AI 回复',
        };
        setChatData(prev => ({
          ...prev,
          messages: [...prev.messages, aiMessage],
        }));
      }, 1000);
    }
  };

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <AiChat
        activeSessionId="session-1"
        chatData={chatData}
        status={status}
        eventsEmit={handleEventsEmit}
        styles={{
          theme: {
            colors: {
              primary: '#409EFF',
              background: '#F7F8FA',
              text: '#222',
            },
          },
          mode: 'light',
        }}
      />
    </div>
  );
}

export default App;
```

## 🔗 链接

- **NPM**: <https://www.npmjs.com/package/@mxmweb/aichat>
- **GitHub**: <https://github.com/your-org/aichat>

## 📚 API 文档

> 📖 完整 API 文档请查看：[doc_assets/接口/](./doc_assets/接口/)

- **接口文档**: [AiChat API](./doc_assets/接口/AiChat.md)
- **更新说明**: [CHANGELOG](./doc_assets/更新说明/CHANGELOG.md)
- **v2.0.0 升级指南**: [v2.0.0升级指南](./doc_assets/更新说明/v2.0.0升级指南.md) ⭐ **新版本必读**
- **演示说明**: [演示文档](./doc_assets/演示/index.md)

### 核心组件（Core Components）

#### AiChat

核心聊天组件，提供基础的聊天界面和交互能力。

```typescript
interface AiChatProps {
  activeSessionId: string | undefined;
  chatData: ConversationData;
  sidebar?: SidebarTabConfig[];
  status: AppStatusManager;
  recommandQuestions?: string[];
  eventsEmit?: (eventName: string, data?: any, callback?: () => void) => void;
  CustomComponents?: any;
  fileUploadStatus?: any;
  styles?: Styles;
  senderConfig?: SenderConfig;
  onSenderConfigChange?: (data: {
    name: string;
    checked: boolean;
    all: Record<string, boolean>;
  }) => void;
}
```

**Props 说明**：

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| activeSessionId | string \| undefined | - | 当前激活的会话ID |
| chatData | ConversationData | 必填 | 聊天数据，包含消息列表 |
| sidebar | SidebarTabConfig[] | [] | 侧边栏配置数组 |
| status | AppStatusManager | 必填 | 应用状态管理对象 |
| recommandQuestions | string[] | [] | 推荐问题列表 |
| eventsEmit | (eventName, data, callback) => void | - | 事件回调函数 |
| CustomComponents | object | - | 自定义组件配置 |
| fileUploadStatus | any[] | [] | 文件上传状态数组 |
| styles | Styles | - | 主题样式配置 |
| senderConfig | SenderConfig | - | 发送器配置 |
| onSenderConfigChange | (data) => void | - | 发送器配置变化回调 |

## 🛠️ 技术栈

- **React** `>=18 <20` - 前端框架
- **@mxmweb/zui** `^1.*` - UI 组件库
- **TypeScript** - 类型支持
- **anime.js** - 动画库
- **lucide-react** - 图标库

## 📁 项目结构

```text
src/
├── lib_enter.ts              # 库入口，导出所有公共 API
├── style.css                 # 样式文件
├── components/               # 核心组件（统一组件目录）
│   ├── AiChat.tsx            # AiChat 核心组件
│   ├── AiChat.types.tsx      # 类型定义
│   ├── Sender/               # 发送器组件
│   │   ├── index.tsx
│   │   ├── FilesDisplay.tsx
│   │   ├── FileUpload.tsx
│   │   └── VoiceInput.tsx
│   ├── Displayer/            # 消息展示组件
│   │   ├── index.tsx
│   │   ├── DefaultAiChatBox.tsx
│   │   ├── DefaultUserChatBox.tsx
│   │   └── slate/            # Slate 富文本编辑器
│   ├── DynamicForm.tsx       # 动态表单组件
│   ├── defaultStyleSet.tsx   # 默认主题配置
│   ├── styles.config.ts      # 样式配置
│   └── ...                   # 其他组件
├── utils/                    # 工具函数
│   ├── fileIcon.tsx          # 文件类型图标工具
│   └── commonFn.tsx           # 通用工具函数
└── examples/                 # 演示实例
    ├── BaseChat/
    └── ProChat/
```

> 💡 **架构说明**：v2.0.0 版本已移除业务层代码（`LoginPage`、`servers`、`adopters`、`core`），专注于核心 UI 组件库功能。

## 🎯 使用场景

- AI 对话聊天界面
- 智能客服系统
- 知识库问答系统
- 文档对话系统
- 自定义聊天应用

## 📝 示例

查看 `src/examples/` 目录获取更多完整示例：

- **BaseChat** - 核心组件基础用法
- **ProChat** - 高级配置完整示例

## 🤝 贡献

欢迎提交 Issue 和 Pull Request。

## 📄 许可证

MIT License

## 👥 作者

- **hanfeng_Zhang**

---

⭐ 如果这个项目对你有帮助，请给它一个 Star！