@glodon-aiot/chat-app-sdk 0.0.1-alpha.0 → 0.0.1-alpha.10

package/README.md

@@ -1,33 +1,30 @@
 # @glodon-aiot/chat-app-sdk
 
-Glodon AIoT Chat App SDK - 基于 `@coze-studio/chat-app-sdk` 的轻量级品牌包装包。
+Glodon AIoT Chat App SDK - 基于 Coze 平台的智能聊天 SDK，支持浮窗和嵌入两种模式。
 
 [![npm version](https://img.shields.io/npm/v/@glodon-aiot/chat-app-sdk.svg)](https://www.npmjs.com/package/@glodon-aiot/chat-app-sdk)
 [![npm downloads](https://img.shields.io/npm/dm/@glodon-aiot/chat-app-sdk.svg)](https://www.npmjs.com/package/@glodon-aiot/chat-app-sdk)
 [![License](https://img.shields.io/npm/l/@glodon-aiot/chat-app-sdk.svg)](https://github.com/glodon-aiot/chat-app-sdk/blob/main/LICENSE)
 
-## 📦 特性
+## ✨ 特性
 
-- ✅ **100% API 兼容**：完全继承 `@coze-studio/chat-app-sdk` 的所有功能
-- ✅ **极简维护**：轻量级包装层，无业务逻辑重复实现
-- ✅ **品牌定制**：统一到 `@glodon-aiot` 命名空间
-- ✅ **样式扩展**：支持自定义品牌样式覆盖
+- ✅ **多模式支持**：浮窗模式和嵌入模式自由切换
+- ✅ **双重引入**：支持 npm 安装和 CDN 引入
 - ✅ **类型安全**：完整的 TypeScript 类型定义
-- ✅ **多模式支持**：支持浮窗模式和嵌入模式
-- ✅ **CDN 支持**：支持通过 CDN 直接引入使用
 - ✅ **React 友好**：完美支持 React 项目集成
+- ✅ **移动端适配**：自动检测设备类型并适配布局
 
-## 📥 安装
+## 📦 安装
 
 ### NPM 安装
 
 ```bash
-# 使用 pnpm（推荐）
-pnpm add @glodon-aiot/chat-app-sdk
-
 # 使用 npm
 npm install @glodon-aiot/chat-app-sdk
 
+# 使用 pnpm
+pnpm add @glodon-aiot/chat-app-sdk
+
 # 使用 yarn
 yarn add @glodon-aiot/chat-app-sdk
 ```
@@ -36,65 +33,49 @@ yarn add @glodon-aiot/chat-app-sdk
 
 ```html
 <!-- 最新版本 -->
-<script src="https://unpkg.com/@glodon-aiot/chat-app-sdk/libs/cn/index.js"></script>
+<script src="https://unpkg.com/@glodon-aiot/chat-app-sdk@latest/libs/cn/index.js"></script>
 
 <!-- 指定版本 -->
-<script src="https://unpkg.com/@glodon-aiot/chat-app-sdk@0.0.1/libs/cn/index.js"></script>
-```
-
-### 环境要求
+<script src="https://unpkg.com/@glodon-aiot/chat-app-sdk@0.0.1-alpha.6/libs/cn/index.js"></script>
 
-- Node.js >= 18
-- React >= 18.2.0
-- ReactDOM >= 18.2.0
+<!-- 或使用 jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@glodon-aiot/chat-app-sdk@latest/libs/cn/index.js"></script>
+```
 
 ## 🚀 快速开始
 
-### 基本使用
+### NPM 使用
 
 ```typescript
-import { WebChatClient, RenderMode, Layout, Language, AuthType, ChatType } from '@glodon-aiot/chat-app-sdk';
+import { WebChatClient } from '@glodon-aiot/chat-app-sdk';
 
 // 创建聊天客户端实例
 const client = new WebChatClient({
-  // 渲染模式配置
-  mode: 'float', // 'float' | 'inlay'
-
-  // 尺寸配置（仅 float 模式生效）
-  size: {
-    width: 400,
-    height: 600,
-    maxWidth: 800,
-    maxHeight: 800,
-  },
-
-  // 容器配置
-  getContainer: () => document.getElementById('chat-container'),
+  mode: 'float', // 'float' 浮窗模式 | 'inlay' 嵌入模式
 
-  // Bot 配置
   config: {
-    type: ChatType.APP,
-    appId: 'your-app-id',
-    workflowId: 'your-workflow-id',
+    type: 'app',
+    appInfo: {
+      appId: 'your-app-id',
+      workflowId: 'your-workflow-id',
+    },
     // 可选：自定义 API 地址
     apiUrl: 'https://your-api-domain.com/api',
   },
 
-  // 认证配置
   auth: {
-    type: AuthType.TOKEN,
+    type: 'token',
     token: 'your-token',
     onRefreshToken: async () => {
-      // 实现 token 刷新逻辑
+      // Token 刷新逻辑
       return 'new-token';
     },
   },
 
-  // UI 配置
   ui: {
     base: {
-      layout: Layout.PC,
-      lang: Language.ZH_CN,
+      layout: 'pc', // 'pc' | 'mobile'
+      lang: 'zh-CN', // 'zh-CN' | 'en-US'
     },
     chatBot: {
       title: '智能助手',
@@ -103,107 +84,16 @@ const client = new WebChatClient({
   },
 });
 
-// 显示聊天窗口
+// 控制显示/隐藏
 client.showChatBot();
-
-// 隐藏聊天窗口
 client.hideChatBot();
 
 // 销毁实例
 client.destroy();
 ```
 
-## 🎯 渲染模式
-
-SDK 支持两种渲染模式：**浮窗助手模式**（默认）和**嵌入模式**。
-
-### 浮窗助手模式（Float）
-
-显示悬浮按钮，点击后弹出聊天窗口。这是默认模式。
-
-```typescript
-const client = new WebChatClient({
-  mode: 'float', // 默认值
-  size: { width: 400, height: 600 },
-  // ... 其他配置
-});
-```
-
-### 嵌入模式（Inlay）
-
-全屏展示聊天页面，自动打开，无关闭按钮。适合专门的聊天页面。
-
-```typescript
-const client = new WebChatClient({
-  mode: 'inlay',
-  getContainer: () => document.getElementById('chat-container'),
-  // ... 其他配置
-});
-```
-
-**嵌入模式会自动：**
-- ✅ 隐藏悬浮助手按钮
-- ✅ 隐藏关闭按钮
-- ✅ 全屏填满容器（100% 宽高）
-- ✅ 自动显示聊天窗口
-
-### 自定义容器渲染
-
-使用 `getContainer` 可以将整个实例（包括按钮和聊天窗口）渲染到指定容器：
-
-```typescript
-const client = new WebChatClient({
-  mode: 'float',
-  getContainer: () => document.getElementById('sidebar')!,
-   // ... 其他配置
-});
-```
-
-### React 中使用
-
-```typescript
-import { useEffect, useRef } from 'react';
-import { WebChatClient } from '@glodon-aiot/chat-app-sdk';
-
-function ChatPage() {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const clientRef = useRef<WebChatClient | null>(null);
-
-  useEffect(() => {
-    if (containerRef.current && !clientRef.current) {
-      clientRef.current = new WebChatClient({
-        mode: 'inlay',
-        getContainer: () => containerRef.current,
-        config: {
-          appId: 'your-app-id',
-          workflowId: 'your-workflow-id',
-        },
-        auth: {
-          type: AuthType.TOKEN,
-          onRefreshToken: async () => 'your-token',
-        },
-      });
-    }
-
-    return () => {
-      clientRef.current?.destroy();
-      clientRef.current = null;
-    };
-  }, []);
-
-  return (
-    <div
-      ref={containerRef}
-      style={{ width: '100%', height: '100vh' }}
-    />
-  );
-}
-```
-
 ### CDN 使用
 
-通过 CDN 引入时，SDK 会自动在 `window` 对象上暴露：
-
 ```html
 <!DOCTYPE html>
 <html>
@@ -215,16 +105,19 @@ function ChatPage() {
   <div id="chat-container" style="width: 100%; height: 100vh;"></div>
 
   <!-- 引入 SDK -->
-  <script src="https://unpkg.com/@glodon-aiot/chat-app-sdk/libs/cn/index.js"></script>
+  <script src="https://unpkg.com/@glodon-aiot/chat-app-sdk@latest/libs/cn/index.js"></script>
 
   <script>
-    // 使用全局变量
+    // 使用全局变量 GlodonAIoT
     const client = new window.GlodonAIoT.WebChatClient({
       mode: 'inlay',
       getContainer: () => document.getElementById('chat-container'),
       config: {
-        appId: 'your-app-id',
-        workflowId: 'your-workflow-id',
+        type: 'app',
+        appInfo: {
+          appId: 'your-app-id',
+          workflowId: 'your-workflow-id',
+        },
       },
       auth: {
         type: 'token',
@@ -239,306 +132,205 @@ function ChatPage() {
 </html>
 ```
 
-## 📖 API 文档
-
-### WebChatClient
+### React 使用
 
-#### 构造函数
-
-```typescript
-new WebChatClient(options: CozeChatOptions)
-```
-
-**参数说明：**
-
-| 参数                 | 类型                          | 默认值     | 说明                                                                       |
-| -------------------- | ----------------------------- | ---------- | -------------------------------------------------------------------------- |
-| options.mode         | `'float' \| 'inlay'`          | `'float'`  | 渲染模式：`'float'` 浮窗助手，`'inlay'` 嵌入模式                          |
-| options.size         | `SizeProps`                   | `undefined` | 尺寸配置（仅 float 模式生效）                                             |
-| options.getContainer | `() => HTMLElement \| null`   | `undefined` | 容器元素获取方法，返回要渲染的 DOM 元素，默认为 `document.body`           |
-| options.config       | `object`                      | -          | Bot 配置信息                                                               |
-| options.config.type  | `ChatType`                    | -          | 聊天类型：`ChatType.APP` 或 `ChatType.BOT`                                |
-| options.config.appId | `string`                      | -          | 应用 ID（type 为 APP 时必需）                                             |
-| options.config.workflowId | `string`                 | -          | 工作流 ID（type 为 APP 时必需）                                           |
-| options.config.botId | `string`                      | -          | Bot ID（type 为 BOT 时必需）                                              |
-| options.config.apiUrl| `string`                      | -          | 自定义 API 地址（可选）                                                   |
-| options.auth         | `AuthProps`                   | -          | 认证配置                                                                   |
-| options.auth.type    | `'token' \| 'oauth'`          | -          | 认证类型                                                                   |
-| options.auth.token   | `string`                      | -          | 访问令牌（token 认证时必需）                                              |
-| options.auth.onRefreshToken | `() => Promise<string>` | -          | 令牌刷新回调（可选）                                                      |
-| options.ui           | `UiProps`                     | -          | UI 配置                                                                    |
-| options.userInfo     | `OpenUserInfo`                | -          | 用户信息（可选）                                                           |
-| ~~options.el~~       | ~~`HTMLElement`~~             | -          | ~~挂载容器（已废弃，请使用 `getContainer`）~~                             |
-
-#### 实例方法
-
-| 方法            | 参数类型 | 返回值 | 说明               |
-| --------------- | -------- | ------ | ------------------ |
-| `showChatBot()` | -        | `void` | 显示聊天窗口       |
-| `hideChatBot()` | -        | `void` | 隐藏聊天窗口       |
-| `getToken()`    | -        | `string \| null` | 获取当前令牌       |
-| `destroy()`     | -        | `void` | 销毁实例，清理资源 |
-
-### 类型定义
-
-```typescript
-import type {
-  CozeChatOptions,
-  RenderMode,     // 'float' | 'inlay'
-  SizeProps,      // 尺寸配置
-  AuthProps,      // 认证配置
-  UiProps,        // UI 配置
-  OpenUserInfo,   // 用户信息
-} from '@glodon-aiot/chat-app-sdk';
-
-import {
-  ChatType,       // 聊天类型枚举
-  AuthType,       // 认证类型枚举
-  Layout,         // 布局枚举
-  Language,       // 语言枚举
-} from '@glodon-aiot/chat-app-sdk';
-```
-
-### 常用类型说明
-
-```typescript
-// 渲染模式
-type RenderMode = 'float' | 'inlay';
-
-// 尺寸配置
-interface SizeProps {
-  width?: number | string;
-  height?: number | string;
-  maxWidth?: number | string;
-  maxHeight?: number | string;
-  minWidth?: number | string;
-  minHeight?: number | string;
-}
-
-// 认证配置
-interface AuthProps {
-  type: 'token' | 'oauth';
-  token?: string;
-  onRefreshToken?: () => Promise<string>;
-}
-
-// UI 配置
-interface UiProps {
-  base?: {
-    layout?: Layout;
-    lang?: Language;
-    zIndex?: number;
-  };
-  chatBot?: {
-    title?: string;
-    width?: number | string;
-    uploadable?: boolean;
-  };
-  header?: {
-    isShow?: boolean;
-    isNeedClose?: boolean;
-  };
-  asstBtn?: {
-    isNeed?: boolean;
-  };
-}
-```
-
-完整的类型定义请参考 `@coze-studio/chat-app-sdk` [官方文档](https://github.com/coze-dev/coze-chat-sdk)。
+```tsx
+import React, { useEffect, useRef } from 'react';
+import { WebChatClient } from '@glodon-aiot/chat-app-sdk';
 
-## ⚠️ 注意事项
+function ChatComponent() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const clientRef = useRef<WebChatClient | null>(null);
 
-### 容器要求
+  useEffect(() => {
+    if (!containerRef.current) return;
 
-使用 `getContainer` 时，容器元素需要满足以下要求：
+    clientRef.current = new WebChatClient({
+      mode: 'inlay',
+      getContainer: () => containerRef.current!,
+      config: {
+        type: 'app',
+        appInfo: {
+          appId: 'your-app-id',
+          workflowId: 'your-workflow-id',
+        },
+      },
+      auth: {
+        type: 'token',
+        token: 'your-token',
+        onRefreshToken: async () => 'new-token',
+      },
+    });
 
-#### 嵌入模式（inlay）
+    return () => {
+      clientRef.current?.destroy();
+    };
+  }, []);
 
-```css
-.chat-container {
-  width: 100%;
-  height: 100vh;      /* 或其他明确的高度 */
-  position: relative; /* 可选但推荐 */
+  return (
+    <div
+      ref={containerRef}
+      style={{ width: '100%', height: '100vh' }}
+    />
+  );
 }
 ```
 
-#### 浮窗模式（float + getContainer）
+## 🎯 两种模式
 
-```css
-.sidebar {
-  position: relative; /* 必需：为 absolute 定位提供参照 */
-  width: 300px;
-  height: 100vh;
-  overflow: hidden;   /* 可选：防止内容溢出 */
-}
-```
-
-### 容器时序
+### 浮窗模式（Float）
 
-在 React 等框架中使用时，确保在容器元素挂载后再调用 `getContainer`：
+显示悬浮按钮，点击后弹出聊天窗口。适合作为页面辅助功能。
 
 ```typescript
-// ✅ 正确：使用 ref 确保元素已挂载
-const containerRef = useRef<HTMLDivElement>(null);
-
-useEffect(() => {
-  if (containerRef.current) {
-    const client = new WebChatClient({
-      getContainer: () => containerRef.current,
-      // ...
-    });
-  }
-}, []);
-
-// ❌ 错误：元素可能尚未挂载
 const client = new WebChatClient({
-  getContainer: () => document.getElementById('container'), // 可能为 null
-  // ...
+  mode: 'float', // 默认模式
+  size: {
+    width: 400,
+    height: 600
+  },
+  // ... 其他配置
 });
 ```
 
-### 模式覆盖
+### 嵌入模式（Inlay）
 
-`mode` 参数会自动配置相关 UI 参数，但用户手动配置的优先级更高：
+全屏展示聊天页面，自动打开。适合专门的聊天页面。
 
 ```typescript
-// inlay 模式默认隐藏关闭按钮，但可以手动覆盖
 const client = new WebChatClient({
   mode: 'inlay',
-  ui: {
-    header: {
-      isNeedClose: true,  // 覆盖默认配置，显示关闭按钮
-    },
-  },
-  // ...
+  getContainer: () => document.getElementById('chat-container'),
+  // ... 其他配置
 });
 ```
 
-## 🎨 样式定制
+## 📖 配置参数
+
+### WebChatClientOptions
 
-### CSS 变量覆盖
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `mode` | `'float' \| 'inlay'` | 是 | 渲染模式 |
+| `config` | `BotConfig` | 是 | Bot 配置信息 |
+| `auth` | `AuthConfig` | 是 | 认证配置 |
+| `ui` | `UIConfig` | 否 | UI 配置 |
+| `getContainer` | `() => HTMLElement` | 否 | 容器元素（inlay 模式必需） |
+| `size` | `SizeConfig` | 否 | 尺寸配置（float 模式有效） |
 
-如果需要自定义品牌样式，可以在项目中覆盖 CSS 变量：
+### BotConfig
 
-```css
-:root {
-  --glodon-primary-color: #1890ff;
-  --glodon-text-color: #333333;
-  --glodon-border-color: #d9d9d9;
-  --glodon-background-color: #ffffff;
+```typescript
+{
+  type: 'app', // 固定为 'app'
+  appInfo: {
+    appId: string,       // 应用 ID
+    workflowId: string,  // 工作流 ID
+  },
+  apiUrl?: string,       // 可选：自定义 API 地址
 }
 ```
 
-### Less 文件导入
-
-```less
-@import '@glodon-aiot/chat-app-sdk/src/style.less';
+### AuthConfig
 
-// 自定义样式
-.your-custom-class {
-  // 覆盖默认样式
-  .chat-widget {
-    border-radius: 8px;
-    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
-  }
+```typescript
+{
+  type: 'token',                              // 认证类型
+  token: string,                              // 访问令牌
+  onRefreshToken: () => string | Promise<string>, // Token 刷新回调
 }
 ```
 
-### 主题定制
+### UIConfig
 
 ```typescript
-const client = new WebChatClient({
-  // ... 其他配置
-  ui: {
-    base: {
-      layout: Layout.PC,
-      lang: Language.ZH_CN,
-      // 自定义主题
-      theme: 'dark', // 或 'light'
-    },
+{
+  base: {
+    layout: 'pc' | 'mobile',   // 布局模式
+    lang: 'zh-CN' | 'en-US',   // 语言
   },
-});
+  chatBot: {
+    title?: string,            // 聊天窗口标题
+    uploadable?: boolean,      // 是否支持上传
+  },
+  header: {
+    isShow?: boolean,          // 是否显示头部
+    isNeedClose?: boolean,     // 是否显示关闭按钮
+  },
+  asstBtn: {
+    isNeed?: boolean,          // 是否显示浮动按钮
+  },
+}
 ```
 
-## 🔧 开发指南
+## 📋 API 方法
 
-### 本地开发
+### WebChatClient 实例方法
 
-```bash
-# 安装依赖
-pnpm install
+| 方法 | 说明 |
+|------|------|
+| `showChatBot()` | 显示聊天窗口 |
+| `hideChatBot()` | 隐藏聊天窗口 |
+| `destroy()` | 销毁实例，清理资源 |
 
-# 启动开发服务器
-pnpm dev
+## 🔧 常见问题
 
-# 运行 lint
-pnpm lint
+### Q1: 如何获取 appId 和 workflowId？
 
-# 运行测试
-pnpm test
+需要从 Coze 平台获取：
+1. 登录 [Coze 平台](https://www.coze.cn/)
+2. 创建或选择你的应用
+3. 在应用设置中找到相应的 ID
 
-# 构建包
-pnpm build
-```
+### Q2: CDN 引入后如何使用？
 
-### 项目结构
+SDK 会在 `window.GlodonAIoT` 上暴露 API：
 
+```javascript
+const client = new window.GlodonAIoT.WebChatClient({
+  // 配置...
+});
 ```
-frontend/packages/glodon/chat-app-sdk/
-├── src/                    # 源码目录
-│   ├── index.ts           # 主入口文件
-│   └── style.less         # 样式文件
-├── dev/                   # 开发示例
-│   └── page/
-│       └── Client.tsx     # 测试页面
-├── libs/                  # 构建产物
-│   └── cn/
-│       └── index.js       # UMD 格式输出
-├── rspack-config/         # 构建配置
-├── package.json           # 包配置
-└── README.md             # 文档
-```
-
-### 构建配置
-
-- **开发环境**：使用 `rspack serve` 启动开发服务器
-- **生产构建**：使用 `rspack build` 生成 UMD 格式文件
-- **类型定义**：使用 `tsc` 生成 TypeScript 声明文件
-
-## 🐛 常见问题
 
-### Q: 如何获取 appId 和 workflowId？
+### Q3: 支持哪些浏览器？
 
-A: 这些参数需要从 Coze 平台获取：
-1. 登录 [Coze 平台](https://www.coze.cn/)
-2. 创建或选择你的应用
-3. 在应用设置中找到 `appId` 和 `workflowId`
-
-### Q: 支持哪些浏览器？
-
-A: 支持所有现代浏览器：
+支持所有现代浏览器：
 - Chrome >= 88
 - Firefox >= 85
 - Safari >= 14
 - Edge >= 88
 
-### Q: 如何自定义样式？
+### Q4: 如何处理 Token 过期？
 
-A: 可以通过以下方式自定义样式：
-1. 覆盖 CSS 变量
-2. 导入 Less 文件并覆盖样式
-3. 使用 `ui` 配置项调整 UI 参数
+通过 `onRefreshToken` 回调处理：
 
-### Q: 支持移动端吗？
+```typescript
+auth: {
+  type: 'token',
+  token: 'current-token',
+  onRefreshToken: async () => {
+    // 调用你的 API 获取新 token
+    const response = await fetch('/api/refresh-token');
+    const { token } = await response.json();
+    return token;
+  },
+}
+```
+
+### Q5: 如何在嵌入模式下设置容器高度？
+
+容器会自动填满 100% 高度，确保父元素有明确的高度：
 
-A: 是的，SDK 会自动检测设备类型并适配移动端布局。
+```html
+<div id="chat-container" style="height: 100vh;"></div>
+```
 
-### Q: 如何调试问题？
+## 🌐 环境要求
 
-A: 可以：
-1. 打开浏览器开发者工具查看控制台日志
-2. 检查网络请求是否正常
-3. 确认配置参数是否正确
+- **Node.js**: >= 18
+- **React**: >= 18.2.0 (如果使用 React)
+- **ReactDOM**: >= 18.2.0 (如果使用 React)
+- **浏览器**: 支持 ES6+ 的现代浏览器
 
 ## 📄 许可证
 
@@ -548,27 +340,15 @@ Apache-2.0
 
 欢迎提交 Issue 和 Pull Request！
 
-### 贡献指南
-
-1. Fork 本仓库
-2. 创建特性分支：`git checkout -b feature/amazing-feature`
-3. 提交更改：`git commit -m 'Add amazing feature'`
-4. 推送分支：`git push origin feature/amazing-feature`
-5. 提交 Pull Request
-
 ## 📞 联系我们
 
-如有问题或建议，请联系 Glodon AIoT 团队：
-
-- 🐛 问题反馈：[GitHub Issues](https://github.com/glodon-aiot/chat-app-sdk/issues)
-- 📖 文档：[项目文档](https://github.com/glodon-aiot/chat-app-sdk)
+如有问题或建议，请联系 Glodon AIoT 团队。
 
 ## 🔗 相关链接
 
 - [Coze 官方文档](https://www.coze.cn/docs/)
-- [原版 SDK](https://github.com/coze-dev/coze-chat-sdk)
-- [React 官方文档](https://react.dev/)
+- [npm 包地址](https://www.npmjs.com/package/@glodon-aiot/chat-app-sdk)
 
 ---
 
-**注意**：本包是 `@coze-studio/chat-app-sdk` 的轻量级包装，核心功能和 API 完全继承自原包。
+**Made with ❤️ by Glodon AIoT Team**