@mxmweb/aichat 1.9.7 → 1.9.8

package/README.md

@@ -1,35 +1,47 @@
-# AIChat 组件库使用说明
+# @mxmweb/aichat
 
-> npm 包名：`@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)
 
-AIChat 是一个轻量级的聊天对话组件库，专注于核心聊天功能。为简化安装，本包仅将 `react`、`react-dom`、`@mxmweb/zui` 声明为 `peerDependencies`，其它运行时依赖已内联按需打包并支持 tree-shaking。
+## ✨ 核心特性
 
-### 核心依赖安装
+- ✅ **轻量级设计**：Gzip 压缩后仅 ~78KB，专注于核心聊天功能
+- ✅ **灵活的组件系统**：支持自定义消息卡片、欢迎页、加载状态等
+- ✅ **完整的文件上传**：支持拖拽上传、多文件管理、上传状态跟踪
+- ✅ **动态主题系统**：支持运行时主题切换，所有样式可配置
+- ✅ **事件驱动架构**：通过 eventsEmit 统一处理所有交互事件
+- ✅ **TypeScript 支持**：完整的类型定义，提供良好的开发体验
+- ✅ **侧边栏扩展**：支持自定义侧边栏组件和动态表单
 
-#### 使用 pnpm（推荐）
-```bash
-pnpm add @mxmweb/aichat \
-  react react-dom @mxmweb/zui
-```
+## 📦 安装
 
-#### 使用 yarn
 ```bash
-yarn add @mxmweb/aichat \
-  react react-dom @mxmweb/zui
+# 使用 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
 ```
 
-#### 使用 npm
+### 必需依赖
+
+本库需要以下 peerDependencies：
+
 ```bash
-npm install @mxmweb/aichat \
-  react react-dom @mxmweb/zui
+pnpm add @mxmweb/zui@^1.* react@>=18 react-dom@>=18
 ```
 
 ### 样式引入
 
 在项目入口文件中引入样式：
-```ts
+
+```typescript
 import '@mxmweb/aichat/style.css';
 ```
 
@@ -41,215 +53,204 @@ import '@mxmweb/aichat/style.css';
 
 > 💡 **优化说明**：AIChat 已移除不必要的依赖，专注于核心聊天功能，确保快速加载和简洁的安装体验。
 
-本说明分为两部分：
-1. **业务层集成方案（推荐，开箱即用）**
-2. **核心组件层用法（自定义交互/高级用法）**
-
----
-
-## 1. 业务层集成方案（推荐）
+## 🚀 快速开始
 
-业务层已封装好与后端接口、消息流、文件管理、主题动态适配等核心逻辑，适合直接集成到业务系统。
-
-### 快速开始
+### 基础用法
 
 ```tsx
-import { GientechChat } from '@mxmweb/aichat';
+import React, { useState } from 'react';
+import { AiChat } from '@mxmweb/aichat';
+import '@mxmweb/aichat/style.css';
 
-export default function App() {
+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);
+    }
+  };
 
-const ChatBox =GientechChat()
   return (
-    <ChatBox
-      token={yourToken}
-      url={yourApiBaseUrl}
-      styles={{
-        theme: {
-          colors: {
-            primary: '#409EFF',        // 主色，影响按钮、边框、图标等
-            background: '#F7F8FA',     // 卡片/内容区背景色
-            border: '#E5E6EB',         // 边框色
-            text: '#222',              // 主要文字色
-            disabled: '#BFBFBF',       // 禁用色
-            info: '#409EFF',           // 信息色
-            warning: '#FFB020',        // 警告色
-            error: '#F53F3F',          // 错误色
-            shadow: '#000',            // 阴影色
-            appBackground: '#F7F8FA',  // 整体背景色
-            // ...可扩展更多
+    <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',
+            },
           },
-          icons: {
-            aiAvatar: '/ai.png',       // AI 头像
-            userAvatar: '/user.png',   // 用户头像
-            // ...可自定义更多图标
-          },
-          space: {
-            radius: 'md',              // 圆角，可用 'sm' | 'md' | 'lg' 或具体像素
-            size: 'md',                // 字体大小
-            shadow: 'md',              // 阴影
-            padding: 'md',             // 内边距
-            margin: 'md',              // 外边距
-            sidebar: '260px',          // 侧边栏宽度
-            lineHeight: 'normal',      // 行高
-            // ...
-          },
-          others: {
-            baseFontWeight: 400,       // 字重
-            // ...
-          }
-        },
-        mode: 'light', // 或 'dark'
-      }}
-      eventsEmit={(event, data) => {
-        // 监听所有交互事件
-      }}
-    />
+          mode: 'light',
+        }}
+      />
+    </div>
   );
 }
+
+export default App;
 ```
 
-#### styles 配置详细说明
-- `theme.colors`：所有颜色相关配置，**建议全部覆盖**，否则用默认色。
-- `theme.icons`：AI、用户等头像图标，支持自定义。
-- `theme.space`：圆角、阴影、字体、边距、侧边栏宽度等。
-- `theme.others`：其他扩展项，如字体粗细。
-- `mode`：'light' 或 'dark'，影响部分默认色。
-
-#### eventsEmit 可监听事件及参数
-业务层已封装常用事件，所有交互事件均通过 `eventsEmit(eventName, data)` 回调分发，常见事件如下：
-
-| 事件名                        | 说明                 | data 参数结构示例                  |
-|------------------------------|----------------------|------------------------------------|
-| sender:send                  | 发送消息             | { content, files, status, ... }    |
-| sender:send_recommandQuestion| 发送推荐问题         | { content, ... }                   |
-| sender:clear                 | 清空输入框           | { clearFn }                        |
-| sender:action_history        | 打开文件管理器       | -                                  |
-| action_copy:click            | 复制消息内容         | { content, sessionContext }         |
-| action_thumbsup              | 点赞                 | { restult, queryId }               |
-| action_thumbsdown            | 点踩                 | { restult, queryId }               |
-| action_retry                 | 重新发送             | { idx, content, ... }              |
-| fileManager:change           | 文件管理器文件变化   | { uploadedFiles, setUploadedFiles, removeFile } |
-| conversations:delete_icon_clicked | 删除会话         | { data, async_deleteConversation, ... } |
-| conversations:rename_icon_clicked | 重命名会话       | { data, async_renameConversation, ... } |
-| conversation:item_click      | 切换会话             | { sessionId, ... }                 |
-| ...                          | 其他事件             | -                                  |
-
-- **所有事件参数均为对象，具体结构可参考源码或控制台输出。**
-- 你可以在 `eventsEmit` 里拦截、扩展、上报等。
+## 🔗 链接
 
----
+- **NPM**: <https://www.npmjs.com/package/@mxmweb/aichat>
+- **GitHub**: <https://github.com/your-org/aichat>
 
-## 2. 核心组件层用法（高级/自定义场景）
+## 📚 API 文档
 
-如需自定义业务逻辑、消息流、文件上传等，可直接使用核心组件 `AiChat`，自行管理数据和交互。
+> 📖 完整 API 文档请查看：[doc_assets/接口/](./doc_assets/接口/)
 
-### 基本用法
+- **接口文档**: [AiChat API](./doc_assets/接口/AiChat.md)
+- **更新说明**: [CHANGELOG](./doc_assets/更新说明/CHANGELOG.md)
+- **演示说明**: [演示文档](./doc_assets/演示/index.md)
 
-```tsx
-import { AiChat } from '@mxmweb/aichat';
+### 核心组件（Core Components）
 
-export default function MyChatApp() {
-  // 你需要自行管理 chatData、status、eventsEmit 等
-  return (
-    <AiChat
-      chatData={yourChatData}
-      status={yourStatus}
-      eventsEmit={yourEventsEmit}
-      styles={{
-        theme: {
-          colors: {
-            primary: '#409EFF',
-            background: '#F7F8FA',
-            // ...
-          },
-        },
-      }}
-      sidebar={yourSidebarConfig} // 侧边栏配置（可选）
-      recommandQuestions={[]}     // 推荐问题（可选）
-      senderConfig={yourSenderConfig} // 发送器配置（可选）
-      fileUploadStatus={[]}       // 文件上传状态（可选）
-      CustomComponents={{         // 自定义组件（可选）
-        AiChatBox: (msg, idx) => <MyAiChatBox {...msg} />, // 自定义AI消息卡片
-        UserChatBox: (msg, idx) => <MyUserChatBox {...msg} />, // 自定义用户消息卡片
-        WelcomeComponent: () => <MyWelcome />,
-        LogoBox: () => <MyLogo />,
-        // ...
-      }}
-      onSenderConfigChange={fn}   // 发送器配置变化回调（可选）
-    />
-  );
+#### 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 配置项说明
-| 属性名              | 类型/说明                                   |
-|---------------------|---------------------------------------------|
-| chatData            | { messages: any[], ... } 聊天数据           |
-| status              | { display, sender, app } 状态管理           |
-| eventsEmit          | (eventName: string, data: any) => void      |
-| styles              | 主题与样式配置，详见上文                    |
-| sidebar             | 侧边栏配置数组（可选）                      |
-| recommandQuestions  | 推荐问题数组（可选）                        |
-| senderConfig        | 发送器配置（可选）                          |
-| fileUploadStatus    | 文件上传状态数组（可选）                    |
-| CustomComponents    | 自定义组件（可选）                          |
-| onSenderConfigChange| 发送器配置变化回调（可选）                  |
-
-### eventsEmit 事件说明（核心层）
-核心层所有交互事件均通过 `eventsEmit(eventName, data)` 分发，**你需要自行处理**。常见事件：
-
-| 事件名                        | 说明                 | data 参数结构示例                  |
-|------------------------------|----------------------|------------------------------------|
-| sender:send                  | 发送消息             | { content, files, status, ... }    |
-| sender:clear                 | 清空输入框           | { clearFn }                        |
-| sender:action_history        | 打开文件管理器       | -                                  |
-| action_copy:click            | 复制消息内容         | { content, sessionContext }         |
-| action_thumbsup              | 点赞                 | { restult, queryId }               |
-| action_thumbsdown            | 点踩                 | { restult, queryId }               |
-| action_retry                 | 重新发送             | { idx, content, ... }              |
-| fileManager:change           | 文件管理器文件变化   | { uploadedFiles, setUploadedFiles, removeFile } |
-| ...                          | 其他事件             | -                                  |
-
-- 你可以根据业务需要自定义事件处理逻辑。
-- 事件参数结构与业务层一致，详见源码。
-
-### 典型用法
-```tsx
-<AiChat
-  chatData={...}
-  status={...}
-  eventsEmit={(event, data) => {
-    if (event === 'sender:send') {
-      // 处理消息发送
-    }
-    if (event === 'action_copy:click') {
-      // 处理复制
-    }
-    // ...
-  }}
-  styles={...}
-/>
+**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                 # 样式文件
+├── core/                     # 核心组件
+│   ├── AiChat.tsx            # AiChat 核心组件
+│   ├── AiChat.types.tsx      # 类型定义
+│   ├── Sender/               # 发送器组件
+│   │   ├── index.tsx
+│   │   ├── FilesDisplay.tsx
+│   │   └── FileUpload.tsx
+│   ├── Displayer/            # 消息展示组件
+│   │   ├── index.tsx
+│   │   ├── DefaultAiChatBox.tsx
+│   │   └── DefaultUserChatBox.tsx
+│   ├── DynamicForm.tsx       # 动态表单组件
+│   ├── defaultStyleSet.tsx   # 默认主题配置
+│   └── ...
+├── adopters/                 # 业务扩展组件（不导出）
+│   ├── GientechChat/
+│   └── HeadLessChat/
+└── examples/                 # 演示实例
+    ├── BaseChat/
+    └── ProChat/
 ```
 
----
+## 🎯 使用场景
 
-## 主题动态适配说明
-- 所有颜色、背景、边框、图标等均可通过 `styles.theme` 配置覆盖
-- 组件内部不再硬编码颜色，支持 run-time 主题切换
-- 参考 `defaultStyleSet.tsx` 的结构进行扩展
+- AI 对话聊天界面
+- 智能客服系统
+- 知识库问答系统
+- 文档对话系统
+- 自定义聊天应用
 
----
+## 📝 示例
 
-## 事件说明
-- 所有交互事件（如发送、复制、点赞、文件上传等）均通过 `eventsEmit` 回调分发
-- 业务层已封装常用事件，核心层需自行处理
+查看 `src/examples/` 目录获取更多完整示例：
 
----
+- **BaseChat** - 核心组件基础用法
+- **ProChat** - 高级配置完整示例
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request。
+
+## 📄 许可证
+
+MIT License
+
+## 👥 作者
 
-## 文件管理说明
-- 支持多文件上传、历史文件、会话文件、上传进度、去重
-- 业务层已自动处理，核心层需自行实现
+- **hanfeng_Zhang**
 
 ---
 
-如需更多高级用法或二次开发，请参考源码及注释。
+⭐ 如果这个项目对你有帮助，请给它一个 Star！