@zeewain/3d-avatar-sdk 1.1.0 → 1.2.0

package/README.md

@@ -1,753 +1,1606 @@
-# 数字人SDK 使用说明
-
-## 1. 产品说明
-### 1.1 产品概述
-紫为云3D写真数字人SDK采用多项AI技术实现：
-- 仿真数字人渲染
-- 音频唇形精准驱动  
-- 多终端语音交互  
-- 支持PC/Web/APP/H5全平台  
-
-**应用场景**：智能客服｜智慧政务｜文旅会展｜数字营销  
-
-### 1.2 产品功能
-| 模块         | 核心能力                                                                 |
-|:--------------:|--------------------------------------------------------------------------|
-| **语音模块** | • 语音/文本对话管理 • 多终端接入控制 • 专属音色          |
-| **交互模块** | • 语音对话交互 •  TTS语音播报 • 大屏字幕同步显示  |
-| **系统功能** | • 多背景切换 • 对话能力配置 • 实时测试体验 • 统一错误管理          |
-
-## 2. SDK使用说明
-### 2.1 核心功能
-| 功能               | 说明                                                                 | 必需性 |
-|--------------------|----------------------------------------------------------------------|:--------:|
-| **数字人渲染**     | Web端加载并渲染3D数字人模型                                          | ✅      |
-| **数字人播报**     | 通过文本/音频驱动口型表情                                            | ✅      |
-| **播报控制**       | 启动/暂停/继续/停止播报                                              | ✅      |
-| **动作控制**       | 播放预设动作库（招手/点头等）                                        | ✅      |
-| **错误管理**       | 统一的错误处理系统，分类错误码，中文化错误消息                        | ✅      |
-
-### 2.2 安装方式
-#### 2.2.1 npm安装
-
-```bash
-npm install @zeewain/3d-avatar-sdk
-```
-
-#### 2.2.2 在项目中引入
-
-##### ES6+ 模块方式（推荐）
-适用于现代浏览器和构建工具（Webpack、Vite、Rollup等）
-```javascript
-// 导入核心模块
-import { ZEEAvatarLoader, AvatarService, BroadcastService } from '@zeewain/3d-avatar-sdk'
-
-// 导入类型定义（TypeScript 项目）
-import { 
-  IAvatarAPI, 
-  IAvatarCallbackResponse, 
-  AvatarCameraType,
-  BroadcastType,
-  IBroadcastParams,
-  IBroadcastCallbacks,
-  // 错误管理相关类型
-  SDKError,
-  NetworkErrorCode,
-  OperationErrorCode,
-  ResourceErrorCode,
-  SystemErrorCode,
-  ConfigErrorCode
-} from '@zeewain/3d-avatar-sdk'
-```
-
-##### ES5 兼容方式
-适用于需要支持 IE11 等老旧浏览器的项目
-```javascript
-// ES5 模块导入（包含完整 polyfill）
-import { ZEEAvatarLoader, AvatarService, BroadcastService } from '@zeewain/3d-avatar-sdk/es5'
-
-// ES5 CommonJS 导入
-const { ZEEAvatarLoader, AvatarService, BroadcastService } = require('@zeewain/3d-avatar-sdk/es5')
-```
-
-#### 2.2.3 通过 CDN 引入
-
-##### 现代浏览器（ES6+）
-```html
-<!-- ES 模块方式 -->
-<script type="module">
-  import { ZEEAvatarLoader, AvatarService, BroadcastService } from 'https://unpkg.com/@zeewain/3d-avatar-sdk'
-  // 使用 SDK...
-</script>
-```
-
-##### 传统浏览器（UMD 全局变量）
-```html
-<!-- UMD 方式，支持现代浏览器 -->
-<script src="https://unpkg.com/@zeewain/3d-avatar-sdk"></script>
-<script>
-  const { ZEEAvatarLoader, AvatarService, BroadcastService } = window.ZEEAvatarSDK;
-  // 使用 SDK...
-</script>
-```
-
-##### 老旧浏览器（IE11 兼容）
-```html
-<!-- ES5 兼容版本，包含完整 polyfill -->
-<script src="https://unpkg.com/@zeewain/3d-avatar-sdk/es5"></script>
-<script>
-  const { ZEEAvatarLoader, AvatarService, BroadcastService } = window.ZEEAvatarSDK;
-  // 使用 SDK...
-</script>
-```
-
-#### 2.2.4 浏览器兼容性
-
-| 版本类型 | 支持的浏览器 | 文件大小 | 使用场景 |
-|:--------:|:------------|:--------:|:---------|
-| **ES6+** | Chrome 60+, Firefox 55+, Safari 10.1+, Edge 16+ | ~31KB | 现代 Web 应用（推荐） |
-| **ES5** | 包括 IE11 在内的所有浏览器 | ~170KB | 需要支持老旧浏览器 |
-
-#### 2.2.5 自动版本选择
-
-SDK 使用现代化的 `exports` 字段，支持自动版本选择：
-
-- **现代构建工具**（Webpack 5+, Vite, Rollup）：自动选择 ES 模块版本
-- **Node.js 环境**：自动选择 CommonJS 版本  
-- **浏览器环境**：根据导入方式自动选择合适版本
-- **老旧工具**：回退到传统的 `main`/`module` 字段
-
-### 2.3 接口说明
-#### 2.3.1 SDK初始化
-首先需要配置Unity WebGL构建文件的路径和认证信息：
-
-```javascript
-// SDK配置
-const config = {
-    // Unity构建文件路径配置
-    loaderUrl: './assets/Build/webgl.loader.js',
-    dataUrl: './assets/Build/webgl.data.unityweb',
-    frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
-    codeUrl: './assets/Build/webgl.wasm.unityweb',
-    
-    // 容器配置
-    containerId: 'unity-container', // 页面中放置Unity容器的元素ID
-    
-    // 认证配置
-    token: 'your-auth-token', // 用户认证token
-    env: 'prod', // 环境：'prod' | 'test' | 'custom'，默认'prod'
-    apiUrl: 'https://your-custom-api.com', // 仅当 env='custom' 时需要
-    
-    // 可选回调
-    onProgress: (progress) => {
-        console.log(`加载进度: ${Math.round(progress * 100)}%`);
-    }
-};
-
-// 创建SDK实例
-const loader = new ZEEAvatarLoader(config);
-```
-
-> **💡 提示**：Unity 资源文件较大（约19MB），建议：
-> - 将资源文件部署到 CDN 以提高加载速度
-> - 在生产环境中配置适当的缓存策略
-> - 考虑使用 IndexedDB 缓存以加速二次加载
-
-#### 2.3.2 初始化Unity环境
-调用init()方法加载并初始化Unity环境，获取Avatar API实例：
-
-```javascript
-let avatarAPI;
-let broadcastService;
-
-try {
-    // 初始化SDK，返回Avatar API实例
-    avatarAPI = await loader.init();
-    console.log('SDK 初始化成功!');
-    
-    // 获取Unity实例（可选）
-    const unityInstance = loader.getInstance();
-    const containerId = loader.getContainerId();
-    
-    // 创建播报服务实例
-    broadcastService = new BroadcastService({
-        unityInstance: unityInstance,
-        callbacks: {
-            onStart: () => console.log('播报开始'),
-            onFinish: () => console.log('播报完成'),
-            onError: (error) => console.error('播报错误:', error),
-            onPause: () => console.log('播报暂停'),
-            onResume: () => console.log('播报恢复'),
-            onStop: () => console.log('播报停止')
-        }
-    });
-    
-} catch (error) {
-    console.error('SDK 初始化失败:', error);
-}
-```
-
-#### 2.3.3 销毁SDK实例
-在不需要Unity的时候释放Unity实例：
-```javascript
-// 销毁播报服务
-if (broadcastService) {
-    broadcastService.destroy();
-}
-
-// 销毁SDK实例
-loader.destroy();
-console.log('Unity环境已销毁');
-```
-
-#### 2.3.4 加载数字人
-```javascript
-try {
-    const response = await avatarAPI.initializeAvatar(avatarCode, 'whole');
-    if (response.success) {
-        console.log('数字人加载成功');
-    } else {
-        console.error('数字人加载失败:', response.message);
-    }
-} catch (error) {
-    console.error('加载异常:', error);
-}
-```
-
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| avatarCode | string  |✅ | 数字人编码  |
-| cameraType | AvatarCameraType  |❌ | 摄像机类型：'whole' \| 'half' \| 'face'，默认'whole' |
-
-**返回值**：`Promise<IAvatarCallbackResponse>` - 包含操作结果的Promise对象
-
-#### 2.3.5 播放动作
-```javascript
-try {
-    const response = await avatarAPI.playMotion(clipCode);
-    if (response.success) {
-        console.log('动作播放成功');
-    }
-} catch (error) {
-    console.error('动作播放失败:', error);
-}
-```
-
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| clipCode | string  |✅   | 动作编码 |
-
-**返回值**：`Promise<IAvatarCallbackResponse>` -Promise对象
-
-#### 2.3.6 获取当前动作信息
-```javascript
-try {
-    // 获取动作编码和剩余时间
-    const response = await avatarAPI.getCurrentMotion(true);
-    if (response.success) {
-        console.log('动作编码:', response.data.motionId);
-        console.log('剩余时间:', response.data.motionRemainingTime); // 待机状态时返回0
-    }
-    
-    // 仅获取动作编码
-    const response2 = await avatarAPI.getCurrentMotion(false);
-    console.log('动作编码:', response2.motionId);
-} catch (error) {
-    console.error('获取动作信息失败:', error);
-}
-```
-
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| getRemainingTime | boolean  |✅   | 是否获取动作剩余时间|
-
-**返回值**：`Promise<IAvatarCallbackResponse>` - 包含动作信息的Promise对象
-
-#### 2.3.7 设置摄像机类型
-```javascript
-try {
-    const response = await avatarAPI.setCamera('face');
-    if (response.success) {
-        console.log('摄像机设置成功');
-    }
-} catch (error) {
-    console.error('摄像机设置失败:', error);
-}
-```
-
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| type | AvatarCameraType  |✅   | 摄像机类型：'whole' \| 'half' \| 'face'|
-
-#### 2.3.8 播报服务
-```javascript
-// 文本播报
-try {
-    await broadcastService.startBroadcast({
-        type: BroadcastType.TEXT, // 或 'text'
-        humanCode: avatarCode,
-        text: "欢迎使用紫为云3D数字人交互SDK",
-        voiceCode: "VOICE001",
-        volume: 1.0,
-        speed: 1.0,
-        isSubtitle: false
-    });
-} catch (error) {
-    console.error('文本播报失败:', error);
-}
-
-// 音频播报
-try {
-    await broadcastService.startBroadcast({
-        type: BroadcastType.AUDIO, // 或 'audio'
-        humanCode: avatarCode,
-        audioUrl: "https://example.com/audio.mp3",
-        text: "音频字幕内容",
-        volume: 1.0,
-        isSubtitle: true
-    });
-} catch (error) {
-    console.error('音频播报失败:', error);
-}
-```
-
-**播报参数说明**：
-
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| type | BroadcastType  |✅  | 播报类型：'text'或'audio' |
-| humanCode | string  |✅   | 数字人编码	|
-| text | string  |✅  | 播报文本内容	 |
-| voiceCode | string  |文本播报✅<br/>音频播报❌| 音色编码		|
-| audioUrl | string  |文本播报❌<br/>音频播报✅| 音频URL	(支持mp3、wav)|
-| volume | number  |❌ | 音量 (0-1.0)	默认:1.0|
-| speed | number  |❌ | 语速 (0.5-2.0)默认:1.0|
-| isSubtitle | boolean  |❌  | 是否启用字幕	(暂不支持）|
-
-#### 2.3.9 播报控制
-```javascript
-// 暂停播报
-try {
-    await broadcastService.pauseBroadcast();
-    console.log('播报已暂停');
-} catch (error) {
-    console.error('暂停失败:', error);
-}
-
-// 恢复播报
-try {
-    await broadcastService.resumeBroadcast();
-    console.log('播报已恢复');
-} catch (error) {
-    console.error('恢复失败:', error);
-}
-
-// 停止播报
-try {
-    await broadcastService.stopBroadcast();
-    console.log('播报已停止');
-} catch (error) {
-    console.error('停止失败:', error);
-}
-```
-
-#### 2.3.10 卸载数字人
-```javascript
-try {
-    const response = await avatarAPI.unloadAvatar();
-    if (response.success) {
-        console.log('数字人卸载成功');
-    }
-} catch (error) {
-    console.error('数字人卸载失败:', error);
-}
-```
-
-**返回值**：`Promise<IAvatarCallbackResponse>` - 包含操作结果的Promise对象
-
-#### 2.3.11 批量操作
-```javascript
-// 批量执行多个操作
-try {
-    const results = await avatarAPI.batchExecute([
-        { method: 'initializeAvatar', params: ['avatar001', 'whole'] },
-        { method: 'playMotion', params: ['motion001'] },
-        { method: 'setCamera', params: ['face'] }
-    ]);
-    
-    results.forEach((result, index) => {
-        if (result.success) {
-            console.log(`操作 ${index + 1} 成功`);
-        } else {
-            console.error(`操作 ${index + 1} 失败:`, result.message);
-        }
-    });
-} catch (error) {
-    console.error('批量操作异常:', error);
-}
-```
-
-#### 2.3.12 播报状态管理
-```javascript
-// 获取播报状态
-const status = broadcastService.getStatus();
-console.log('播报状态:', {
-    isActive: status.isActive,
-    pendingCallbacks: status.pendingCallbacks,
-    hasController: status.hasController
-});
-
-// 更新播报回调
-broadcastService.updateCallbacks({
-    onStart: () => console.log('新的开始回调'),
-    onError: (error) => console.error('新的错误回调:', error)
-});
-```
-
-### 2.4 错误处理
-SDK中的操作都返回Promise，建议使用try-catch处理异常。SDK使用统一的错误管理系统，所有错误都继承自`SDKError`类：
-
-```javascript
-// 导入错误类型和错误码（TypeScript项目）
-import { SDKError, NetworkErrorCode, OperationErrorCode, ResourceErrorCode, SystemErrorCode, ConfigErrorCode } from '@zeewain/3d-avatar-sdk'
-
-// 统一错误处理示例
-try {
-    const response = await avatarAPI.initializeAvatar('avatar001');
-    if (response.success) {
-        console.log('数字人加载成功');
-    }
-} catch (error) {
-    // 处理SDK错误
-    if (error instanceof SDKError) {
-        handleSDKError(error);
-    } else {
-        // 处理其他系统异常
-        console.error('系统异常:', error.message);
-    }
-}
-
-// SDK错误处理
-function handleSDKError(error) {
-    console.error('SDK错误:', error.message, '错误码:', error.code);
-    
-    // 根据错误类别处理
-    switch (error.category) {
-        case 'NETWORK':
-            handleNetworkError(error);
-            break;
-        case 'OPERATION':
-            handleOperationError(error);
-            break;
-        case 'RESOURCE':
-            handleResourceError(error);
-            break;
-        case 'SYSTEM':
-            handleSystemError(error);
-            break;
-        case 'CONFIG':
-            handleConfigError(error);
-            break;
-        default:
-            console.error('未知错误类别:', error.category);
-    }
-}
-
-// 网络错误处理
-function handleNetworkError(error) {
-    switch (error.code) {
-        case NetworkErrorCode.CONNECTION_FAILED:
-            console.error('网络连接失败，请检查网络状态');
-            break;
-        case NetworkErrorCode.REQUEST_TIMEOUT:
-            console.error('请求超时，请稍后重试');
-            break;
-        case NetworkErrorCode.SERVER_ERROR:
-            console.error('服务器错误，请稍后重试');
-            break;
-        case NetworkErrorCode.UNAUTHORIZED:
-            console.error('认证失效，请重新登录');
-            // 跳转到登录页面或刷新token
-            break;
-    }
-}
-
-// 操作错误处理
-function handleOperationError(error) {
-    switch (error.code) {
-        case OperationErrorCode.UNITY_NOT_INITIALIZED:
-            console.error('Unity实例未初始化');
-            break;
-        case OperationErrorCode.AVATAR_NOT_LOADED:
-            console.error('数字人未加载，请先加载数字人');
-            break;
-                 case OperationErrorCode.OPERATION_FAILED:
-             console.error('操作执行失败');
-            break;
-        case OperationErrorCode.OPERATION_TIMEOUT:
-            console.error('操作超时，请稍后重试');
-            break;
-        case OperationErrorCode.OPERATION_CANCELLED:
-            console.error('操作已取消');
-            break;
-    }
-}
-
-// 资源错误处理
-function handleResourceError(error) {
-    switch (error.code) {
-        case ResourceErrorCode.LOAD_FAILED:
-            console.error('资源加载失败');
-            break;
-        case ResourceErrorCode.FILE_CORRUPTED:
-            console.error('资源文件损坏');
-            break;
-        case ResourceErrorCode.NOT_FOUND:
-            console.error('资源不存在');
-            break;
-        case ResourceErrorCode.UNSUPPORTED_FORMAT:
-            console.error('资源格式不支持');
-            break;
-    }
-}
-
-// 系统错误处理
-function handleSystemError(error) {
-    if (error instanceof SDKError) {
-        switch (error.code) {
-            case SystemErrorCode.OUT_OF_MEMORY:
-                console.error('内存不足，请关闭其他应用');
-                break;
-            case SystemErrorCode.GPU_NOT_SUPPORTED:
-                console.error('GPU不支持，请更新浏览器或显卡驱动');
-                break;
-            case SystemErrorCode.WEBGL_NOT_SUPPORTED:
-                console.error('浏览器不支持WebGL');
-                break;
-            case SystemErrorCode.BROWSER_NOT_COMPATIBLE:
-                console.error('浏览器不兼容，请更新浏览器');
-                break;
-        }
-    } else {
-        console.error('系统异常:', error.message);
-        // 可以上报错误日志
-    }
-}
-
-// 配置错误处理
-function handleConfigError(error) {
-    switch (error.code) {
-        case ConfigErrorCode.INVALID_CONFIG:
-            console.error('配置参数无效');
-            break;
-        case ConfigErrorCode.MISSING_REQUIRED_PARAM:
-            console.error('缺少必需参数');
-            break;
-        case ConfigErrorCode.PARAM_OUT_OF_RANGE:
-            console.error('参数值超出范围');
-            break;
-        case ConfigErrorCode.INVALID_JSON_FORMAT:
-            console.error('JSON格式错误');
-            break;
-    }
-}
-
-// 播报错误处理
-const broadcastService = new BroadcastService({
-    unityInstance: unityInstance,
-    callbacks: {
-        onError: (error) => {
-            // 所有错误都是SDKError类型
-            console.error('播报错误:', error.message, '错误码:', error.code);
-            handleSDKError(error);
-        }
-    }
-});
-```
-
-### 2.5 SDK错误码参考表
-
-SDK使用统一的错误管理系统，所有错误都通过`SDKError`抛出：
-
-##### 网络错误 (1xxx)
-| 错误码 | 常量名 | 描述说明 | 常见发生场景 |
-| :---: | :---: | :---: | :---: |
-| 1001 | `NetworkErrorCode.CONNECTION_FAILED` | 网络连接失败 | 网络不可用、防火墙阻止、DNS解析失败 |
-| 1002 | `NetworkErrorCode.REQUEST_TIMEOUT` | 请求超时 | 网络延迟过高、服务器响应慢 |
-| 1003 | `NetworkErrorCode.SERVER_ERROR` | 服务器错误 | 服务器内部错误、API异常 |
-| 1004 | `NetworkErrorCode.UNAUTHORIZED` | 未授权访问 | Token失效、权限不足 |
-
-##### 操作错误 (2xxx)
-| 错误码 | 常量名 | 描述说明 | 常见发生场景 |
-| :---: | :---: | :---: | :---: |
-| 2001 | `OperationErrorCode.UNITY_NOT_INITIALIZED` | Unity实例未初始化 | 在Unity加载完成前调用API |
-| 2002 | `OperationErrorCode.AVATAR_NOT_LOADED` | 数字人未加载 | 在数字人加载完成前调用相关API |
-| 2003 | `OperationErrorCode.OPERATION_FAILED` | 操作执行失败 | Unity操作执行失败、消息发送失败、播报处理失败等 |
-| 2004 | `OperationErrorCode.OPERATION_TIMEOUT` | 操作超时 | 操作执行时间过长 |
-| 2005 | `OperationErrorCode.OPERATION_CANCELLED` | 操作被取消 | 用户主动取消或系统中断 |
-
-##### 资源错误 (3xxx)
-| 错误码 | 常量名 | 描述说明 | 常见发生场景 |
-| :---: | :---: | :---: | :---: |
-| 3001 | `ResourceErrorCode.LOAD_FAILED` | 资源加载失败 | 文件不存在、下载失败 |
-| 3002 | `ResourceErrorCode.FILE_CORRUPTED` | 资源文件损坏 | 文件格式错误、数据损坏 |
-| 3003 | `ResourceErrorCode.NOT_FOUND` | 资源不存在 | 指定的资源路径不存在 |
-| 3004 | `ResourceErrorCode.UNSUPPORTED_FORMAT` | 资源格式不支持 | 音频格式不支持、模型格式不兼容 |
-
-##### 系统错误 (4xxx)
-| 错误码 | 常量名 | 描述说明 | 常见发生场景 |
-| :---: | :---: | :---: | :---: |
-| 4001 | `SystemErrorCode.OUT_OF_MEMORY` | 内存不足 | 系统内存不足、浏览器内存限制 |
-| 4002 | `SystemErrorCode.GPU_NOT_SUPPORTED` | GPU不支持 | 显卡不支持WebGL、驱动过旧 |
-| 4003 | `SystemErrorCode.WEBGL_NOT_SUPPORTED` | WebGL不支持 | 浏览器不支持WebGL |
-| 4004 | `SystemErrorCode.BROWSER_NOT_COMPATIBLE` | 浏览器不兼容 | 浏览器版本过低、功能不支持 |
-
-##### 配置错误 (5xxx)
-| 错误码 | 常量名 | 描述说明 | 常见发生场景 |
-| :---: | :---: | :---: | :---: |
-| 5001 | `ConfigErrorCode.INVALID_CONFIG` | 配置参数无效 | 配置格式错误、参数类型不匹配 |
-| 5002 | `ConfigErrorCode.MISSING_REQUIRED_PARAM` | 必需参数缺失 | 缺少必需的配置项或参数 |
-| 5003 | `ConfigErrorCode.PARAM_OUT_OF_RANGE` | 参数值超出范围 | 参数值超出有效范围 |
-| 5004 | `ConfigErrorCode.INVALID_JSON_FORMAT` | JSON格式错误 | JSON解析失败、格式不正确 |
-
-#### 2.5.1 错误码使用示例
-
-```javascript
-// 检查具体的错误码
-try {
-    await avatarAPI.initializeAvatar('avatar001');
-} catch (error) {
-    if (error instanceof SDKError) {
-        // 使用错误码常量进行判断
-        if (error.code === OperationErrorCode.UNITY_NOT_INITIALIZED) {
-            console.error('Unity实例未初始化');
-        } else if (error.code === OperationErrorCode.OPERATION_FAILED) {
-            console.error('操作执行失败');
-        } else if (error.code === NetworkErrorCode.UNAUTHORIZED) {
-            console.error('认证失效，请重新登录');
-        }
-        
-        // 或者使用错误类别进行判断
-        switch (error.category) {
-            case 'NETWORK':
-                console.error('网络错误:', error.message);
-                break;
-            case 'OPERATION':
-                console.error('操作错误:', error.message);
-                break;
-            // ... 其他类别
-        }
-    }
-}
-```
-
-## 3. 注意事项
-### 3.1 Unity构建文件
-- 确保正确配置Unity构建文件的路径。
-- 如果文件部署在不同域名下，需要配置CORS。
-### 3.2 内存管理
-- 在不需要使用数字人时，调用unloadAvatar释放资源。
-- 在页面卸载前，调用destroy释放整个Unity环境。
-- 当卸载数字人后，发现浏览器内存未降低，请不用担心，Unity堆内存由引擎自主管理。
-### 3.3 数字人加载和卸载时机
-- 数字人加载成功后，才能卸载数字人。
-- 在未成功加载数字人的时候，提前卸载数字人，卸载会成功，但是会导致第二次加载数字人失败；解决方案：卸载Unity实例化，重新初始化Unity，再初始化数字人即可解决。
-### 3.4 错误处理
-- 所有异步操作都返回Promise，务必使用try-catch处理。
-- 检查response.success字段判断操作是否成功。
-- **统一错误管理系统**：所有错误都通过`SDKError`抛出，通过错误码和错误类别进行精确处理。
-- SDK错误码采用分类编码：网络错误(1xxx)、操作错误(2xxx)、资源错误(3xxx)、系统错误(4xxx)、配置错误(5xxx)。
-- 所有错误消息已本地化为中文，可直接显示给用户。
-### 3.5 性能考虑
-- 避免频繁加载/卸载数字人。
-- 音频文件不易过大。（建议<5MB）
-### 3.6 兼容性
-
-#### 3.6.1 浏览器要求
-- **基本要求**：浏览器支持 WebGL 2.0
-- **ES6+ 版本**：Chrome 60+, Firefox 55+, Safari 10.1+, Edge 16+
-- **ES5 版本**：包括 IE11 在内的所有现代浏览器
-
-#### 3.6.2 模块系统兼容性
-| 环境 | 推荐版本 | 导入方式 |
-|:-----|:---------|:---------|
-| **现代 Web 应用** | ES6+ | `import { ... } from '@zeewain/3d-avatar-sdk'` |
-| **IE11 兼容项目** | ES5 | `import { ... } from '@zeewain/3d-avatar-sdk/es5'` |
-| **CDN 引入** | 根据需要 | 见 2.2.3 CDN 引入方式 |
-
-#### 3.6.3 性能优化建议
-- **移动设备**：注意性能限制，考虑降低渲染质量
-- **资源缓存**：Web端建议对Unity资源文件使用 IndexedDB 缓存
-- **网络优化**：将Unity资源部署到CDN以提高加载速度
-
-### 3.7 认证配置
-- token在SDK初始化时配置，无需在每个API调用时传递
-- token失效时，需要重新初始化SDK或更新全局配置
-- 支持生产环境('prod')、测试环境('test')和自定义环境('custom')
-
-## 4. 常见问题
-### 4.1 Unity内容无法加载怎么办？
-
-1. 确保Unity构建文件路径配置正确;
-2. 检查浏览器控制台是否有CORS错误;
-3. 确认网络可以访问构建文件URL;
-4. 验证Unity版本与SDK兼容性;
-
-### 4.2 播报没有声音怎么办？
-
-1. 检查音量参数是否大于0;
-2. 确认音频文件URL可访问且格式受支持（MP3/WAV）;
-3. 验证是否设置了正确的音色编码;
-4. 检查浏览器是否阻止了自动播放（可能需要用户交互）;
-
-### 4.3 动作播放不生效怎么办？
-
-1. 确认数字人已成功加载;
-2. 检查动作编码是否正确;
-3. 确保token有效且有权限;
-4. 查看Unity控制台是否有错误日志;
-
-### 4.4 获取当前动作时间不生效或者返回时间为0怎么办？
-
-1. 确保getCurrentMotion接口参数是true，如果是false是无法获取当前动作剩余时间的;
-2. getCurrentMotion接口参数是true，但只能获取非待机动作的剩余时间，该当前动作如果是属于待机动作的话，返回时间就为0;
-
-### 4.5 如何获取更多音色编码、角色编码？
-
-1. 请联系技术支持获取可用音色编码列表;
-
-### 4.6 如何处理SDK错误？
-
-1. **统一错误管理系统**：所有错误都通过`SDKError`抛出，使用try-catch捕获异常;
-2. **错误码分类**：根据错误码前缀快速定位问题类型（1xxx网络、2xxx操作、3xxx资源、4xxx系统、5xxx配置）;
-3. **错误消息本地化**：所有错误消息已中文化，可直接显示给用户;
-4. **调试技巧**：使用`error.category`进行错误分类处理，使用`error.code`进行精确判断;
-5. **最佳实践**：建议根据错误类别统一处理，提供友好的用户提示;
-
-### 4.7 新版本API迁移说明
-
-如果您从旧版本SDK升级，主要变化：
-
-1. **类名变化**：`AvatarAPI` → `AvatarService`（但通过`IAvatarAPI`接口使用）
-2. **初始化方式**：token在SDK初始化时配置，不再在每个方法中传递
-3. **返回值**：所有方法都返回Promise，不再使用回调函数
-4. **参数简化**：方法参数更简洁，移除了重复的token参数
-5. **类型安全**：完整的TypeScript类型定义，更好的开发体验
-6. **错误管理升级**：
-   - 统一的`SDKError`错误类型，替代原有的`UnityServiceError`
-   - 采用分类错误码系统（1xxx-5xxx），便于精确处理
-   - 所有错误消息中文化，提供更友好的用户体验
-   - 支持错误类别判断，简化错误处理逻辑
-   - 所有错误都通过异常抛出，统一错误处理方式
-
----
-
-## 📋 更新日志
-
-### 最新版本特性
-- ✅ **统一错误管理系统**：全新的`SDKError`错误类型，替代原有的`UnityServiceError`
-- ✅ **分类错误码**：采用5类错误码系统（1xxx-5xxx），便于精确处理和调试
-- ✅ **中文化错误消息**：所有错误消息本地化为中文，提升用户体验
-- ✅ **TypeScript完整支持**：完整的错误类型定义，更好的开发体验
-- ✅ **统一异常处理**：所有错误都通过异常抛出，简化错误处理逻辑
-
+# ZEE 3D Avatar SDK 使用说明
+
+
+[![npm version](https://badge.fury.io/js/@zeewain/3d-avatar-sdk.svg)](https://badge.fury.io/js/@zeewain/3d-avatar-sdk)
+
+
+## 🚀 产品概述
+
+紫为云3D写真数字人SDK采用多项AI技术实现：
+- **仿真数字人渲染** - 高保真3D数字人模型渲染
+- **音频唇形精准驱动** - 智能口型同步技术  
+- **多终端语音交互** - 支持PC/Web/APP/H5全平台  
+- **统一SDK架构** - 单一入口，简化集成流程
+
+**应用场景**：智能客服 | 智慧政务 | 文旅会展 | 数字营销 | 在线教育
+
+## ✨ 核心特性
+
+### 🎯 统一架构设计
+- **单一入口**：`ZEEAvatarSDK` 类统一管理所有功能
+- **组合模式**：内部整合Avatar控制、播报服务等模块
+- **多实例支持**：同一页面可创建多个独立SDK实例
+- **回调隔离**：每个实例拥有独立的回调函数命名空间
+
+### 🛡️ 完善的错误管理
+- **统一错误类型**：`SDKError` 统一错误处理
+- **分类错误码**：网络(1xxx)、操作(2xxx)、资源(3xxx)、系统(4xxx)、配置(5xxx)
+- **中文化消息**：所有错误消息本地化，用户友好
+- **详细调试信息**：错误类别、错误码、详细描述
+
+### 🔧 开发者友好
+- **完整TypeScript支持**：全类型定义，智能提示
+- **Promise-based API**：现代异步编程模式
+- **统一配置管理**：一次配置，全局生效
+- **生命周期管理**：完善的资源清理机制
+
+## 📦 安装方式
+
+> **WebGL文件来源说明**：
+> - 所有WebGL构建文件（webgl.loader.js、webgl.data.unityweb、webgl.framework.js.unityweb、webgl.wasm.unityweb）均来源于SDK包（@zeewain/3d-avatar-sdk）的`dist/assets/Build/`目录。
+> - 使用SDK前，请先将这些文件从 `node_modules/@zeewain/3d-avatar-sdk/dist/assets/Build/` 目录拷贝到你项目的静态资源目录，如 `public` 目录或你的CDN服务器上。
+> - 然后在SDK初始化时，通过config参数设置这些WebGL文件的路径。
+
+### npm/yarn 安装（推荐）
+
+```bash
+# npm
+npm install @zeewain/3d-avatar-sdk
+
+# yarn
+yarn add @zeewain/3d-avatar-sdk
+
+# pnpm
+pnpm add @zeewain/3d-avatar-sdk
+```
+
+### CDN 引入
+
+```html
+<!-- ES 模块方式（现代浏览器） -->
+<script type="module">
+  import { ZEEAvatarSDK } from 'https://unpkg.com/@zeewain/3d-avatar-sdk'
+  // 使用 SDK...
+</script>
+
+<!-- UMD 方式（全局变量） -->
+<script src="https://unpkg.com/@zeewain/3d-avatar-sdk"></script>
+<script>
+  const { ZEEAvatarSDK } = window.ZEEAvatarSDKLib;
+  // 使用 SDK...
+</script>
+
+<!-- ES5 兼容版本（支持IE11） -->
+<script src="https://unpkg.com/@zeewain/3d-avatar-sdk/es5"></script>
+<script>
+  const { ZEEAvatarSDK } = window.ZEEAvatarSDKLib;
+  // 使用 SDK...
+</script>
+```
+
+> **💡 重要说明**：
+> - **SDK类名**：`ZEEAvatarSDK`（这是您在代码中使用的类）
+> - **UMD全局变量名**：`ZEEAvatarSDKLib`（这是挂载到window对象的变量名）
+> - 使用UMD方式时，需要从 `window.ZEEAvatarSDKLib` 中解构出 `ZEEAvatarSDK` 类
+
+## 🎮 快速开始
+
+### 基础使用示例
+
+```javascript
+import { ZEEAvatarSDK, AvatarCameraType, BroadcastType } from '@zeewain/3d-avatar-sdk'
+
+// 1. 创建SDK实例
+const sdk = new ZEEAvatarSDK({
+  // Unity构建文件配置
+  loaderUrl: './assets/Build/webgl.loader.js',
+  dataUrl: './assets/Build/webgl.data.unityweb',
+  frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
+  codeUrl: './assets/Build/webgl.wasm.unityweb',
+  
+  // 基础配置
+  containerId: 'unity-container',
+  token: 'your-auth-token',
+  env: 'prod',
+  
+  // 加载进度回调
+  onProgress: (progress) => {
+    console.log(`加载进度: ${Math.round(progress * 100)}%`);
+  }
+});
+
+// 2. 初始化数字人
+async function initializeAvatar() {
+  try {
+    const response = await sdk.initializeAvatar('avatar001', AvatarCameraType.WHOLE);
+    if (response.success) {
+      console.log('数字人初始化成功！');
+      
+      // 3. 播放动作
+      await sdk.playMotion('wave_hand');
+      
+      // 4. 开始播报
+      await sdk.startBroadcast({
+        type: BroadcastType.TEXT,
+        humanCode: 'avatar001',
+        text: '欢迎使用ZEE 3D Avatar SDK！',
+        voiceCode: 'VOICE001',
+        volume: 1.0,
+        speed: 1.0,
+        isSubtitle: false
+      });
+    }
+  } catch (error) {
+    console.error('初始化失败:', error);
+  }
+}
+
+// 5. 页面卸载时清理资源
+window.addEventListener('beforeunload', () => {
+  sdk.destroy();
+});
+
+// 开始初始化
+initializeAvatar();
+```
+
+### 完整应用示例
+
+```javascript
+import { 
+  ZEEAvatarSDK, 
+  AvatarCameraType, 
+  BroadcastType,
+  SDKError,
+  NetworkErrorCode,
+  OperationErrorCode
+} from '@zeewain/3d-avatar-sdk'
+
+class AvatarApp {
+  constructor() {
+    this.sdk = null;
+    this.isInitialized = false;
+    this.setupUI();
+  }
+
+  // 初始化SDK
+  async initSDK() {
+    try {
+      this.sdk = new ZEEAvatarSDK({
+        loaderUrl: './assets/Build/webgl.loader.js',
+        dataUrl: './assets/Build/webgl.data.unityweb',
+        frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
+        codeUrl: './assets/Build/webgl.wasm.unityweb',
+        containerId: 'unity-container',
+        token: 'your-auth-token',
+        env: 'prod',
+        onProgress: this.onLoadProgress.bind(this)
+      });
+
+      // 初始化数字人
+      const response = await this.sdk.initializeAvatar('avatar001', AvatarCameraType.WHOLE);
+      
+      if (response.success) {
+        this.isInitialized = true;
+        this.updateUI();
+        console.log('SDK初始化成功');
+      }
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 播放动作
+  async playMotion(motionCode) {
+    if (!this.isInitialized) {
+      console.warn('SDK未初始化');
+      return;
+    }
+
+    try {
+      const response = await this.sdk.playMotion(motionCode);
+      if (response.success) {
+        console.log('动作播放成功');
+      }
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 文本播报
+  async speakText(text, voiceCode = 'VOICE001') {
+    if (!this.isInitialized) {
+      console.warn('SDK未初始化');
+      return;
+    }
+
+    try {
+      await this.sdk.startBroadcast({
+        type: BroadcastType.TEXT,
+        humanCode: 'avatar001',
+        text: text,
+        voiceCode: voiceCode,
+        volume: 1.0,
+        speed: 1.0,
+        isSubtitle: false
+      });
+      console.log('播报开始');
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 音频播报
+  async playAudio(audioUrl, subtitleText = '') {
+    if (!this.isInitialized) {
+      console.warn('SDK未初始化');
+      return;
+    }
+
+    try {
+      await this.sdk.startBroadcast({
+        type: BroadcastType.AUDIO,
+        humanCode: 'avatar001',
+        audioUrl: audioUrl,
+        text: subtitleText,
+        volume: 1.0,
+        isSubtitle: true
+      });
+      console.log('音频播报开始');
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 播报控制
+  async pauseBroadcast() {
+    try {
+      await this.sdk.pauseBroadcast();
+      console.log('播报已暂停');
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  async resumeBroadcast() {
+    try {
+      await this.sdk.resumeBroadcast();
+      console.log('播报已恢复');
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  async stopBroadcast() {
+    try {
+      await this.sdk.stopBroadcast();
+      console.log('播报已停止');
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 摄像机控制
+  async setCamera(cameraType) {
+    if (!this.isInitialized) {
+      console.warn('SDK未初始化');
+      return;
+    }
+
+    try {
+      const response = await this.sdk.setCamera(cameraType);
+      if (response.success) {
+        console.log('摄像机设置成功');
+      }
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 获取当前动作信息
+  async getCurrentMotion() {
+    if (!this.isInitialized) {
+      console.warn('SDK未初始化');
+      return;
+    }
+
+    try {
+      const response = await this.sdk.getCurrentMotion(true);
+      if (response.success) {
+        console.log('当前动作:', response.data);
+        return response.data;
+      }
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+
+  // 加载进度回调
+  onLoadProgress(progress) {
+    const percent = Math.round(progress * 100);
+    console.log(`加载进度: ${percent}%`);
+    // 更新进度条UI
+    this.updateProgressBar(percent);
+  }
+
+  // 错误处理
+  handleError(error) {
+    console.error('SDK错误:', error);
+    
+    if (error instanceof SDKError) {
+      switch (error.code) {
+        case NetworkErrorCode.CONNECTION_FAILED:
+          this.showMessage('网络连接失败，请检查网络状态', 'error');
+          break;
+        case NetworkErrorCode.UNAUTHORIZED:
+          this.showMessage('认证失效，请重新登录', 'error');
+          break;
+        case OperationErrorCode.UNITY_NOT_INITIALIZED:
+          this.showMessage('SDK未初始化，请先初始化', 'error');
+          break;
+        case OperationErrorCode.AVATAR_NOT_LOADED:
+          this.showMessage('数字人未加载，请先加载数字人', 'error');
+          break;
+        default:
+          this.showMessage(`操作失败: ${error.message}`, 'error');
+      }
+    } else {
+      this.showMessage(`系统错误: ${error.message}`, 'error');
+    }
+  }
+
+  // UI相关方法
+  setupUI() {
+    // 设置UI事件监听器
+    document.getElementById('init-btn').addEventListener('click', () => this.initSDK());
+    document.getElementById('play-motion-btn').addEventListener('click', () => this.playMotion('wave_hand'));
+    document.getElementById('speak-btn').addEventListener('click', () => {
+      const text = document.getElementById('text-input').value;
+      this.speakText(text);
+    });
+    document.getElementById('pause-btn').addEventListener('click', () => this.pauseBroadcast());
+    document.getElementById('resume-btn').addEventListener('click', () => this.resumeBroadcast());
+    document.getElementById('stop-btn').addEventListener('click', () => this.stopBroadcast());
+    
+    // 摄像机切换
+    document.getElementById('camera-whole').addEventListener('click', () => this.setCamera(AvatarCameraType.WHOLE));
+    document.getElementById('camera-half').addEventListener('click', () => this.setCamera(AvatarCameraType.HALF));
+    document.getElementById('camera-face').addEventListener('click', () => this.setCamera(AvatarCameraType.FACE));
+  }
+
+  updateUI() {
+    // 更新UI状态
+    document.getElementById('init-btn').disabled = this.isInitialized;
+    document.getElementById('play-motion-btn').disabled = !this.isInitialized;
+    document.getElementById('speak-btn').disabled = !this.isInitialized;
+  }
+
+  updateProgressBar(percent) {
+    const progressBar = document.getElementById('progress-bar');
+    if (progressBar) {
+      progressBar.style.width = `${percent}%`;
+      progressBar.textContent = `${percent}%`;
+    }
+  }
+
+  showMessage(message, type = 'info') {
+    const messageDiv = document.getElementById('message');
+    if (messageDiv) {
+      messageDiv.textContent = message;
+      messageDiv.className = `message ${type}`;
+      setTimeout(() => {
+        messageDiv.textContent = '';
+        messageDiv.className = 'message';
+      }, 5000);
+    }
+  }
+
+  // 清理资源
+  destroy() {
+    if (this.sdk) {
+      this.sdk.destroy();
+      this.sdk = null;
+      this.isInitialized = false;
+    }
+  }
+}
+
+// 创建应用实例
+const app = new AvatarApp();
+
+// 页面卸载时清理
+window.addEventListener('beforeunload', () => {
+  app.destroy();
+});
+```
+
+## 📚 API 参考
+
+### ZEEAvatarSDK 类
+
+#### 构造函数
+
+```typescript
+constructor(config: IAvatarSDKConfig)
+```
+
+创建SDK实例，需要传入完整的配置对象。
+
+**参数说明：**
+
+```typescript
+interface IAvatarSDKConfig {
+  // Unity构建文件配置（必填）
+  loaderUrl: string;          // Unity加载器脚本URL
+  dataUrl: string;            // Unity数据文件URL  
+  frameworkUrl: string;       // Unity框架文件URL
+  codeUrl: string;            // Unity代码文件URL
+  
+  // 基础配置
+  containerId?: string;       // 容器DOM元素ID，默认'unity-container'
+  token?: string;             // 用户认证令牌
+  env?: 'dev' | 'test' | 'prod' | 'custom';  // 运行环境，默认'prod'
+  apiUrl?: string;            // 自定义API地址（env='custom'时需要）
+  resourcesUrl?: string;      // AB资源文件地址
+  idleMotionList?:string[];   // 待机动作编码列表，随机播放（排重方式），可选
+  // 回调函数
+  onProgress?: (progress: number) => void;  // 加载进度回调
+}
+```
+
+#### 核心方法
+
+##### initializeAvatar()
+
+```typescript
+async initializeAvatar(
+  avatarCode: string, 
+  cameraType?: AvatarCameraType
+): Promise<IAvatarCallbackResponse>
+```
+
+初始化数字人，这是使用SDK的第一步，会自动完成Unity环境初始化和数字人加载。
+
+**参数：**
+- `avatarCode`: 数字人编码（必填）
+- `cameraType`: 摄像机类型，可选值：
+  - `AvatarCameraType.WHOLE` - 全身视角（默认）
+  - `AvatarCameraType.HALF` - 半身视角
+  - `AvatarCameraType.FACE` - 面部视角
+
+**返回值：**
+```typescript
+interface IAvatarCallbackResponse {
+  success: boolean;    // 操作是否成功
+  message: string;     // 响应消息
+  errorCode?: number;  // 错误代码（可选）
+  data?: any;          // 返回数据（可选）
+}
+```
+
+**使用示例：**
+```javascript
+try {
+  const response = await sdk.initializeAvatar('avatar001', AvatarCameraType.WHOLE);
+  if (response.success) {
+    console.log('数字人初始化成功');
+  }
+} catch (error) {
+  console.error('初始化失败:', error);
+}
+```
+
+##### playMotion()
+
+```typescript
+async playMotion(clipCode: string): Promise<IAvatarCallbackResponse>
+```
+
+播放数字人动作。
+
+**参数：**
+- `clipCode`: 动作编码（必填）
+
+**使用示例：**
+```javascript
+try {
+  const response = await sdk.playMotion('wave_hand');
+  if (response.success) {
+    console.log('动作播放成功');
+  }
+} catch (error) {
+  console.error('动作播放失败:', error);
+}
+```
+
+##### getCurrentMotion()
+
+```typescript
+async getCurrentMotion(getRemainingTime?: boolean): Promise<IAvatarCallbackResponse>
+```
+
+获取当前播放的动作信息。
+
+**参数：**
+- `getRemainingTime`: 是否获取剩余时间，默认false
+
+**返回值：**
+```typescript
+interface IAvatarCallbackResponse {
+  success: boolean;
+  message: string;
+  data?: {
+    motionId?: string;           // 动作ID
+    motionRemainingTime?: number; // 动作剩余时间（秒）
+  };
+}
+```
+
+**使用示例：**
+```javascript
+// 获取动作编码和剩余时间
+const response = await sdk.getCurrentMotion(true);
+if (response.success) {
+  console.log('动作编码:', response.data.motionId);
+  console.log('剩余时间:', response.data.motionRemainingTime);
+}
+```
+
+##### setCamera()
+
+```typescript
+async setCamera(cameraType: AvatarCameraType): Promise<IAvatarCallbackResponse>
+```
+
+设置摄像机类型。
+
+**参数：**
+- `cameraType`: 摄像机类型
+
+**使用示例：**
+```javascript
+await sdk.setCamera(AvatarCameraType.FACE);
+```
+
+##### unloadAvatar()
+
+```typescript
+async unloadAvatar(): Promise<IAvatarCallbackResponse>
+```
+
+卸载数字人，释放数字人相关资源。
+
+**使用示例：**
+```javascript
+try {
+  const response = await sdk.unloadAvatar();
+  if (response.success) {
+    console.log('数字人卸载成功');
+  }
+} catch (error) {
+  console.error('卸载失败:', error);
+}
+```
+
+#### 播报相关方法
+
+##### startBroadcast()
+
+```typescript
+async startBroadcast(params: IBroadcastParams): Promise<void>
+```
+
+开始播报，支持文本转语音和音频播报两种模式。
+
+**参数：**
+```typescript
+interface IBroadcastParams {
+  type: BroadcastType;    // 播报类型：'text' | 'audio'
+  humanCode: string;      // 数字人编码
+  text?: string;          // 播报文本（文本播报必填）
+  audioUrl?: string;      // 音频URL（音频播报必填）
+  voiceCode?: string;     // 音色编码（文本播报必填）
+  speed?: number;         // 语速（0.5-2.0），默认1.0
+  volume: number;         // 音量（0-1.0）
+  isSubtitle: boolean;    // 是否显示字幕
+  motionList:string[];    // 播报过程中才播放的动作集合，每个动作间隔2-3秒循环播放，播报顺序根据`motionPlayMode`参数处理，默认为`随机`，可选
+  motionPlayMode?: 'random' | 'sequence'; // 动作播放模式，随机、顺序，随机=`random`，顺序=`sequence`
+}
+```
+
+**使用示例：**
+```javascript
+// 文本播报
+await sdk.startBroadcast({
+  type: BroadcastType.TEXT,
+  humanCode: 'avatar001',
+  text: '欢迎使用ZEE 3D Avatar SDK',
+  voiceCode: 'VOICE001',
+  volume: 1.0,
+  speed: 1.0,
+  isSubtitle: false
+});
+
+// 音频播报
+await sdk.startBroadcast({
+  type: BroadcastType.AUDIO,
+  humanCode: 'avatar001',
+  audioUrl: 'https://example.com/audio.mp3',
+  text: '音频字幕内容',
+  volume: 1.0,
+  isSubtitle: true
+});
+```
+
+##### pauseBroadcast()
+
+```typescript
+async pauseBroadcast(resetIdle?:boolean): Promise<void>
+```
+
+暂停当前播报。
+
+**参数**
+
+- `resetIdle`: 动作和口型是否回到待机状态，默认为false
+
+##### resumeBroadcast()
+
+```typescript
+async resumeBroadcast(): Promise<void>
+```
+
+恢复播报。
+
+##### stopBroadcast()
+
+```typescript
+async stopBroadcast(): Promise<void>
+```
+
+停止播报。
+
+##### updateBroadcastCallbacks()
+
+```typescript
+updateBroadcastCallbacks(callbacks: IBroadcastCallbacks): void
+```
+
+更新播报回调函数。
+
+**参数：**
+```typescript
+interface IBroadcastCallbacks {
+  onStart?: () => void;           // 播报开始
+  onFinish?: () => void;          // 播报完成
+  onError?: (error: Error) => void; // 播报错误
+  onPause?: () => void;           // 播报暂停
+  onResume?: () => void;          // 播报恢复
+  onStop?: () => void;            // 播报停止
+  onAbort?: () => void;           // 播报中断
+}
+```
+
+**使用示例：**
+```javascript
+sdk.updateBroadcastCallbacks({
+  onStart: () => console.log('播报开始'),
+  onFinish: () => console.log('播报完成'),
+  onError: (error) => console.error('播报错误:', error)
+});
+```
+
+##### getBroadcastStatus()
+
+```typescript
+getBroadcastStatus(): {
+  isActive: boolean;
+  isGeneratingAudio: boolean;
+  hasReceivedAudio: boolean;
+  pendingCallbacks: number;
+  hasController: boolean;
+}
+```
+
+获取播报状态信息。
+
+#### 工具方法
+
+##### updateToken()
+
+```typescript
+updateToken(token: string): void
+```
+
+更新认证Token。
+
+##### getInstanceId()
+
+```typescript
+getInstanceId(): string
+```
+
+获取SDK实例的唯一标识符。
+
+##### isSDKInitialized()
+
+```typescript
+isSDKInitialized(): boolean
+```
+
+检查SDK是否已初始化。
+
+##### isAvatarInitialized()
+
+```typescript
+isAvatarInitialized(): boolean
+```
+
+检查数字人是否已加载。
+
+##### getConfig()
+
+```typescript
+getConfig(): IAvatarSDKConfig
+```
+
+获取当前SDK配置。
+
+##### destroy()
+
+```typescript
+destroy(): void
+```
+
+销毁SDK实例，清理所有资源。**重要：页面卸载前务必调用此方法！**
+
+## 🔧 高级功能
+
+### 多实例支持
+
+新版SDK支持在同一页面创建多个独立的SDK实例，每个实例拥有独立的回调函数命名空间，避免冲突。
+
+```javascript
+// 创建多个SDK实例
+const sdk1 = new ZEEAvatarSDK({
+  loaderUrl: './assets/Build/webgl.loader.js',
+  dataUrl: './assets/Build/webgl.data.unityweb',
+  frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
+  codeUrl: './assets/Build/webgl.wasm.unityweb',
+  containerId: 'unity-container-1',
+  token: 'token1'
+});
+
+const sdk2 = new ZEEAvatarSDK({
+  loaderUrl: './assets/Build/webgl.loader.js',
+  dataUrl: './assets/Build/webgl.data.unityweb',
+  frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
+  codeUrl: './assets/Build/webgl.wasm.unityweb',
+  containerId: 'unity-container-2',
+  token: 'token2'
+});
+
+// 分别初始化不同的数字人
+await sdk1.initializeAvatar('avatar001');
+await sdk2.initializeAvatar('avatar002');
+
+// 独立控制
+await sdk1.playMotion('wave_hand');
+await sdk2.playMotion('bow');
+
+// 清理资源
+sdk1.destroy();
+sdk2.destroy();
+```
+
+### 错误处理最佳实践
+
+```javascript
+import { 
+  SDKError, 
+  NetworkErrorCode, 
+  OperationErrorCode, 
+  ResourceErrorCode,
+  SystemErrorCode,
+  ConfigErrorCode
+} from '@zeewain/3d-avatar-sdk'
+
+// 统一错误处理函数
+function handleSDKError(error) {
+  if (error instanceof SDKError) {
+    console.error(`SDK错误 [${error.code}]: ${error.message}`);
+    
+    // 根据错误类别处理
+    switch (error.category) {
+      case 'NETWORK':
+        handleNetworkError(error);
+        break;
+      case 'OPERATION':
+        handleOperationError(error);
+        break;
+      case 'RESOURCE':
+        handleResourceError(error);
+        break;
+      case 'SYSTEM':
+        handleSystemError(error);
+        break;
+      case 'CONFIG':
+        handleConfigError(error);
+        break;
+    }
+  } else {
+    console.error('系统错误:', error);
+  }
+}
+
+// 网络错误处理
+function handleNetworkError(error) {
+  switch (error.code) {
+    case NetworkErrorCode.CONNECTION_FAILED:
+      showUserMessage('网络连接失败，请检查网络状态');
+      break;
+    case NetworkErrorCode.UNAUTHORIZED:
+      showUserMessage('认证失效，请重新登录');
+      // 可以触发重新登录流程
+      redirectToLogin();
+      break;
+    case NetworkErrorCode.REQUEST_TIMEOUT:
+      showUserMessage('请求超时，请稍后重试');
+      break;
+  }
+}
+
+// 操作错误处理
+function handleOperationError(error) {
+  switch (error.code) {
+    case OperationErrorCode.UNITY_NOT_INITIALIZED:
+      showUserMessage('系统未初始化，请稍后重试');
+      break;
+    case OperationErrorCode.AVATAR_NOT_LOADED:
+      showUserMessage('数字人未加载，请先加载数字人');
+      break;
+    case OperationErrorCode.OPERATION_TIMEOUT:
+      showUserMessage('操作超时，请稍后重试');
+      break;
+  }
+}
+
+// 在SDK操作中使用
+try {
+  await sdk.initializeAvatar('avatar001');
+} catch (error) {
+  handleSDKError(error);
+}
+```
+
+### 性能优化建议
+
+#### 1. 资源预加载
+
+```javascript
+// 预加载Unity资源
+const preloadPromise = fetch('./assets/Build/webgl.data.unityweb', {
+  method: 'HEAD'
+});
+
+// 在需要时再创建SDK实例
+preloadPromise.then(() => {
+  const sdk = new ZEEAvatarSDK(config);
+  sdk.initializeAvatar('avatar001');
+});
+```
+
+#### 2. 懒加载策略
+
+```javascript
+class LazyAvatarLoader {
+  constructor() {
+    this.sdk = null;
+    this.isLoading = false;
+  }
+
+  async loadWhenNeeded() {
+    if (this.sdk || this.isLoading) return;
+    
+    this.isLoading = true;
+    try {
+      this.sdk = new ZEEAvatarSDK(config);
+      await this.sdk.initializeAvatar('avatar001');
+    } finally {
+      this.isLoading = false;
+    }
+  }
+
+  async speak(text) {
+    await this.loadWhenNeeded();
+    return this.sdk.startBroadcast({
+      type: BroadcastType.TEXT,
+      humanCode: 'avatar001',
+      text: text,
+      voiceCode: 'VOICE001',
+      volume: 1.0,
+      isSubtitle: false
+    });
+  }
+}
+```
+
+#### 3. 内存管理
+
+```javascript
+class AvatarManager {
+  constructor() {
+    this.sdk = null;
+    this.isActive = false;
+  }
+
+  async initialize() {
+    if (this.sdk) return;
+    
+    this.sdk = new ZEEAvatarSDK(config);
+    await this.sdk.initializeAvatar('avatar001');
+    this.isActive = true;
+  }
+
+  async pause() {
+    if (this.sdk && this.isActive) {
+      await this.sdk.unloadAvatar();
+      this.isActive = false;
+    }
+  }
+
+  async resume() {
+    if (this.sdk && !this.isActive) {
+      await this.sdk.initializeAvatar('avatar001');
+      this.isActive = true;
+    }
+  }
+
+  destroy() {
+    if (this.sdk) {
+      this.sdk.destroy();
+      this.sdk = null;
+      this.isActive = false;
+    }
+  }
+}
+
+// 页面可见性变化时管理资源
+const avatarManager = new AvatarManager();
+
+document.addEventListener('visibilitychange', () => {
+  if (document.hidden) {
+    avatarManager.pause();
+  } else {
+    avatarManager.resume();
+  }
+});
+```
+
+## 🚨 错误码参考
+
+### 网络错误 (1xxx)
+| 错误码 | 常量名 | 描述 | 处理建议 |
+|:------:|:-------|:-----|:---------|
+| 1001 | `NetworkErrorCode.CONNECTION_FAILED` | 网络连接失败 | 检查网络状态，重试连接 |
+| 1002 | `NetworkErrorCode.REQUEST_TIMEOUT` | 请求超时 | 检查网络延迟，稍后重试 |
+| 1003 | `NetworkErrorCode.SERVER_ERROR` | 服务器错误 | 联系技术支持 |
+| 1004 | `NetworkErrorCode.UNAUTHORIZED` | 未授权访问 | 更新Token或重新登录 |
+
+### 操作错误 (2xxx)
+| 错误码 | 常量名 | 描述 | 处理建议 |
+|:------:|:-------|:-----|:---------|
+| 2001 | `OperationErrorCode.UNITY_NOT_INITIALIZED` | Unity实例未初始化 | 先调用initializeAvatar() |
+| 2002 | `OperationErrorCode.AVATAR_NOT_LOADED` | 数字人未加载 | 确保数字人已成功加载 |
+| 2003 | `OperationErrorCode.OPERATION_FAILED` | 操作执行失败 | 检查参数和网络状态 |
+| 2004 | `OperationErrorCode.OPERATION_TIMEOUT` | 操作超时 | 稍后重试 |
+| 2005 | `OperationErrorCode.OPERATION_CANCELLED` | 操作被取消 | 重新执行操作 |
+
+### 资源错误 (3xxx)
+| 错误码 | 常量名 | 描述 | 处理建议 |
+|:------:|:-------|:-----|:---------|
+| 3001 | `ResourceErrorCode.LOAD_FAILED` | 资源加载失败 | 检查资源URL和网络 |
+| 3002 | `ResourceErrorCode.FILE_CORRUPTED` | 资源文件损坏 | 重新下载资源文件 |
+| 3003 | `ResourceErrorCode.NOT_FOUND` | 资源不存在 | 检查资源路径 |
+| 3004 | `ResourceErrorCode.UNSUPPORTED_FORMAT` | 资源格式不支持 | 使用支持的格式 |
+
+### 系统错误 (4xxx)
+| 错误码 | 常量名 | 描述 | 处理建议 |
+|:------:|:-------|:-----|:---------|
+| 4001 | `SystemErrorCode.OUT_OF_MEMORY` | 内存不足 | 关闭其他应用，释放内存 |
+| 4002 | `SystemErrorCode.GPU_NOT_SUPPORTED` | GPU不支持 | 更新显卡驱动 |
+| 4003 | `SystemErrorCode.WEBGL_NOT_SUPPORTED` | WebGL不支持 | 更新浏览器 |
+| 4004 | `SystemErrorCode.BROWSER_NOT_COMPATIBLE` | 浏览器不兼容 | 使用推荐浏览器 |
+
+### 配置错误 (5xxx)
+| 错误码 | 常量名 | 描述 | 处理建议 |
+|:------:|:-------|:-----|:---------|
+| 5001 | `ConfigErrorCode.INVALID_CONFIG` | 配置参数无效 | 检查配置格式 |
+| 5002 | `ConfigErrorCode.MISSING_REQUIRED_PARAM` | 必需参数缺失 | 补充必需参数 |
+| 5003 | `ConfigErrorCode.PARAM_OUT_OF_RANGE` | 参数值超出范围 | 调整参数值 |
+| 5004 | `ConfigErrorCode.INVALID_JSON_FORMAT` | JSON格式错误 | 检查JSON格式 |
+
+## 🌍 浏览器兼容性
+
+### 支持的浏览器版本
+
+| 浏览器 | 最低版本 | 推荐版本 | 备注 |
+|:-------|:---------|:---------|:-----|
+| **Chrome** | 60+ | 90+ | 最佳性能 |
+| **Firefox** | 55+ | 85+ | 良好支持 |
+| **Safari** | 10.1+ | 14+ | 需要WebGL 2.0 |
+| **Edge** | 16+ | 90+ | 基于Chromium |
+| **IE** | 11 | - | 需要ES5版本 |
+
+### 模块系统兼容性
+
+```javascript
+// 现代浏览器 (ES6+)
+import { ZEEAvatarSDK } from '@zeewain/3d-avatar-sdk'
+
+// IE11 兼容
+import { ZEEAvatarSDK } from '@zeewain/3d-avatar-sdk/es5'
+
+// CommonJS (Node.js)
+const { ZEEAvatarSDK } = require('@zeewain/3d-avatar-sdk')
+```
+
+### 功能检测
+
+```javascript
+// 检查WebGL支持
+function checkWebGLSupport() {
+  try {
+    const canvas = document.createElement('canvas');
+    const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
+    return !!gl;
+  } catch (e) {
+    return false;
+  }
+}
+
+// 检查浏览器兼容性
+function checkBrowserCompatibility() {
+  const checks = {
+    webgl: checkWebGLSupport(),
+    promise: typeof Promise !== 'undefined',
+    fetch: typeof fetch !== 'undefined',
+    es6: typeof Symbol !== 'undefined'
+  };
+  
+  return checks;
+}
+
+// 使用检测结果
+const compatibility = checkBrowserCompatibility();
+if (!compatibility.webgl) {
+  console.error('浏览器不支持WebGL');
+}
+```
+
+## 📋 最佳实践
+
+### 1. 生命周期管理
+
+```javascript
+class AvatarComponent {
+  constructor() {
+    this.sdk = null;
+    this.isDestroyed = false;
+  }
+
+  async mount() {
+    if (this.isDestroyed) return;
+    
+    this.sdk = new ZEEAvatarSDK(config);
+    
+    // 设置错误处理
+    this.setupErrorHandling();
+    
+    // 初始化数字人
+    await this.sdk.initializeAvatar('avatar001');
+  }
+
+  async unmount() {
+    this.isDestroyed = true;
+    
+    if (this.sdk) {
+      try {
+        await this.sdk.unloadAvatar();
+      } catch (error) {
+        console.warn('卸载数字人时出错:', error);
+      } finally {
+        this.sdk.destroy();
+        this.sdk = null;
+      }
+    }
+  }
+
+  setupErrorHandling() {
+    // 全局错误处理
+    window.addEventListener('error', (event) => {
+      if (event.error && event.error.name === 'SDKError') {
+        this.handleSDKError(event.error);
+      }
+    });
+  }
+}
+```
+
+### 2. 状态管理
+
+```javascript
+class AvatarState {
+  constructor() {
+    this.state = {
+      isInitialized: false,
+      isLoading: false,
+      isSpeaking: false,
+      currentMotion: null,
+      error: null
+    };
+    
+    this.listeners = [];
+  }
+
+  setState(newState) {
+    this.state = { ...this.state, ...newState };
+    this.notifyListeners();
+  }
+
+  subscribe(listener) {
+    this.listeners.push(listener);
+    return () => {
+      this.listeners = this.listeners.filter(l => l !== listener);
+    };
+  }
+
+  notifyListeners() {
+    this.listeners.forEach(listener => listener(this.state));
+  }
+}
+
+// 使用状态管理
+const avatarState = new AvatarState();
+
+avatarState.subscribe((state) => {
+  console.log('状态变化:', state);
+  updateUI(state);
+});
+```
+
+### 3. 配置管理
+
+```javascript
+// 配置文件 config.js
+export const avatarConfig = {
+  development: {
+    loaderUrl: './assets/Build/webgl.loader.js',
+    dataUrl: './assets/Build/webgl.data.unityweb',
+    frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
+    codeUrl: './assets/Build/webgl.wasm.unityweb',
+    containerId: 'unity-container',
+    env: 'dev',
+    token: 'dev-token'
+  },
+  production: {
+    loaderUrl: 'https://cdn.example.com/webgl.loader.js',
+    dataUrl: 'https://cdn.example.com/webgl.data.unityweb',
+    frameworkUrl: 'https://cdn.example.com/webgl.framework.js.unityweb',
+    codeUrl: 'https://cdn.example.com/webgl.wasm.unityweb',
+    containerId: 'unity-container',
+    env: 'prod',
+    token: process.env.AVATAR_TOKEN
+  }
+};
+
+// 使用配置
+const config = avatarConfig[process.env.NODE_ENV || 'development'];
+const sdk = new ZEEAvatarSDK(config);
+```
+
+## 🔄 从旧版本迁移
+
+### 主要变化
+
+| 旧版本 | 新版本 | 变化说明 |
+|:-------|:-------|:---------|
+| 多个类 | 单个类 | `ZEEAvatarLoader` + `AvatarService` + `BroadcastService` → `ZEEAvatarSDK` |
+| 分步初始化 | 统一初始化 | `init()` + `initializeAvatar()` → `initializeAvatar()` |
+| 手动管理 | 自动管理 | 内部自动管理各个服务实例 |
+| 回调冲突 | 回调隔离 | 支持多实例，回调函数完全隔离 |
+| 暴露内部 | 封装内部 | 移除 `getUnityInstance()` 等内部方法 |
+
+### 迁移示例
+
+**旧版本代码：**
+```javascript
+// 旧版本需要创建多个实例
+const loader = new ZEEAvatarLoader(config);
+const avatarAPI = await loader.init();
+const broadcastService = new BroadcastService({
+  unityInstance: loader.getInstance(),
+  callbacks: { /* ... */ }
+});
+
+// 分步初始化
+await avatarAPI.initializeAvatar('avatar001', 'whole');
+```
+
+**新版本代码：**
+```javascript
+// 新版本只需要一个实例
+const sdk = new ZEEAvatarSDK(config);
+
+// 统一初始化
+await sdk.initializeAvatar('avatar001', AvatarCameraType.WHOLE);
+```
+
+### 完整迁移指南
+
+```javascript
+// 旧版本完整代码
+class OldAvatarApp {
+  async init() {
+    // 1. 创建加载器
+    this.loader = new ZEEAvatarLoader(config);
+    
+    // 2. 初始化Unity
+    this.avatarAPI = await this.loader.init();
+    
+    // 3. 创建播报服务
+    this.broadcastService = new BroadcastService({
+      unityInstance: this.loader.getInstance(),
+      callbacks: {
+        onStart: () => console.log('播报开始'),
+        onFinish: () => console.log('播报完成')
+      }
+    });
+    
+    // 4. 初始化数字人
+    await this.avatarAPI.initializeAvatar('avatar001', 'whole');
+  }
+  
+  async speak(text) {
+    await this.broadcastService.startBroadcast({
+      type: 'text',
+      humanCode: 'avatar001',
+      text: text,
+      voiceCode: 'VOICE001',
+      volume: 1.0,
+      isSubtitle: false
+    });
+  }
+  
+  destroy() {
+    this.broadcastService?.destroy();
+    this.loader?.destroy();
+  }
+}
+
+// 新版本对应代码
+class NewAvatarApp {
+  async init() {
+    // 1. 创建SDK实例
+    this.sdk = new ZEEAvatarSDK(config);
+    
+    // 2. 设置播报回调
+    this.sdk.updateBroadcastCallbacks({
+      onStart: () => console.log('播报开始'),
+      onFinish: () => console.log('播报完成')
+    });
+    
+    // 3. 统一初始化（包含Unity初始化和数字人加载）
+    await this.sdk.initializeAvatar('avatar001', AvatarCameraType.WHOLE);
+  }
+  
+  async speak(text) {
+    await this.sdk.startBroadcast({
+      type: BroadcastType.TEXT,
+      humanCode: 'avatar001',
+      text: text,
+      voiceCode: 'VOICE001',
+      volume: 1.0,
+      isSubtitle: false
+    });
+  }
+  
+  destroy() {
+    this.sdk?.destroy();
+  }
+}
+```
+
+## ❓ 常见问题
+
+### Q1: Unity内容无法加载怎么办？
+
+**A1:** 请按以下步骤排查：
+
+1. **检查文件路径**：确保Unity构建文件路径配置正确
+2. **CORS问题**：如果文件在不同域名，需要配置CORS
+3. **网络连接**：确认网络可以访问构建文件URL
+4. **浏览器兼容性**：确认浏览器支持WebGL 2.0
+
+```javascript
+// 检查资源可访问性
+async function checkResourcesAvailability(config) {
+  const resources = [
+    config.loaderUrl,
+    config.dataUrl,
+    config.frameworkUrl,
+    config.codeUrl
+  ];
+  
+  for (const url of resources) {
+    try {
+      const response = await fetch(url, { method: 'HEAD' });
+      if (!response.ok) {
+        console.error(`资源不可访问: ${url}`);
+      }
+    } catch (error) {
+      console.error(`资源检查失败: ${url}`, error);
+    }
+  }
+}
+```
+
+### Q2: 播报没有声音怎么办？
+
+**A2:** 请检查以下几点：
+
+1. **音量设置**：确认volume参数大于0
+2. **音频格式**：确认音频文件格式为MP3或WAV
+3. **音色编码**：确认voiceCode正确
+4. **浏览器策略**：现代浏览器需要用户交互才能播放音频
+
+```javascript
+// 处理浏览器自动播放限制
+async function enableAudioPlayback() {
+  try {
+    // 创建一个静音的音频上下文
+    const audioContext = new (window.AudioContext || window.webkitAudioContext)();
+    
+    // 用户交互后恢复音频上下文
+    document.addEventListener('click', async () => {
+      if (audioContext.state === 'suspended') {
+        await audioContext.resume();
+      }
+    }, { once: true });
+  } catch (error) {
+    console.warn('音频上下文初始化失败:', error);
+  }
+}
+```
+
+### Q3: 如何处理多实例场景？
+
+**A3:** 新版SDK原生支持多实例，每个实例都有独立的回调命名空间：
+
+```javascript
+// 创建多个实例
+const instances = [];
+
+for (let i = 0; i < 3; i++) {
+  const sdk = new ZEEAvatarSDK({
+    ...config,
+    containerId: `unity-container-${i}`
+  });
+  
+  instances.push(sdk);
+  
+  // 每个实例独立初始化
+  await sdk.initializeAvatar(`avatar00${i + 1}`);
+}
+
+// 独立控制每个实例
+instances[0].playMotion('wave_hand');
+instances[1].playMotion('bow');
+instances[2].startBroadcast({
+  type: BroadcastType.TEXT,
+  humanCode: 'avatar003',
+  text: '我是第三个实例',
+  voiceCode: 'VOICE001',
+  volume: 1.0,
+  isSubtitle: false
+});
+```
+
+### Q4: 如何优化加载性能？
+
+**A4:** 建议采用以下优化策略：
+
+```javascript
+// 1. 资源预加载
+const preloadResources = async (config) => {
+  const resources = [
+    config.dataUrl,
+    config.frameworkUrl,
+    config.codeUrl
+  ];
+  
+  // 并行预加载
+  await Promise.all(
+    resources.map(url => 
+      fetch(url, { method: 'HEAD' })
+    )
+  );
+};
+
+// 2. 懒加载策略
+class LazyAvatarManager {
+  constructor(config) {
+    this.config = config;
+    this.sdk = null;
+    this.loadPromise = null;
+  }
+  
+  async load() {
+    if (this.loadPromise) return this.loadPromise;
+    
+    this.loadPromise = this.doLoad();
+    return this.loadPromise;
+  }
+  
+  async doLoad() {
+    if (this.sdk) return this.sdk;
+    
+    this.sdk = new ZEEAvatarSDK(this.config);
+    await this.sdk.initializeAvatar('avatar001');
+    return this.sdk;
+  }
+}
+
+// 3. 缓存策略
+const avatarCache = new Map();
+
+function getCachedSDK(key, config) {
+  if (!avatarCache.has(key)) {
+    avatarCache.set(key, new ZEEAvatarSDK(config));
+  }
+  return avatarCache.get(key);
+}
+```
+
+### Q5: 如何处理内存泄漏？
+
+**A5:** 务必正确管理SDK生命周期：
+
+```javascript
+class AvatarManager {
+  constructor() {
+    this.sdk = null;
+    this.isDestroyed = false;
+    
+    // 监听页面卸载事件
+    window.addEventListener('beforeunload', () => {
+      this.destroy();
+    });
+    
+    // 监听页面可见性变化
+    document.addEventListener('visibilitychange', () => {
+      if (document.hidden) {
+        this.pause();
+      } else {
+        this.resume();
+      }
+    });
+  }
+  
+  async init() {
+    if (this.isDestroyed) return;
+    
+    this.sdk = new ZEEAvatarSDK(config);
+    await this.sdk.initializeAvatar('avatar001');
+  }
+  
+  async pause() {
+    if (this.sdk) {
+      await this.sdk.unloadAvatar();
+    }
+  }
+  
+  async resume() {
+    if (this.sdk) {
+      await this.sdk.initializeAvatar('avatar001');
+    }
+  }
+  
+  destroy() {
+    this.isDestroyed = true;
+    
+    if (this.sdk) {
+      this.sdk.destroy();
+      this.sdk = null;
+    }
+  }
+}
+```
+
+## 🆚 新旧版本对比
+
+### 使用体验对比
+
+| 对比项 | 旧版本 | 新版本 | 改进说明 |
+|:-------|:-------|:-------|:---------|
+| **类数量** | 3个类 | 1个类 | 简化使用 |
+| **初始化步骤** | 4步 | 1步 | 大幅简化 |
+| **多实例支持** | ❌ | ✅ | 新增功能 |
+| **回调冲突** | 有冲突 | 完全隔离 | 问题解决 |
+| **内部暴露** | 过度暴露 | 合理封装 | 更安全 |
+| **错误处理** | 分散处理 | 统一管理 | 更规范 |
+
+### 代码量对比
+
+**旧版本：**
+```javascript
+// 需要 15+ 行代码初始化
+const loader = new ZEEAvatarLoader(config);
+const avatarAPI = await loader.init();
+const broadcastService = new BroadcastService({
+  unityInstance: loader.getInstance(),
+  callbacks: { /* ... */ }
+});
+await avatarAPI.initializeAvatar('avatar001', 'whole');
+```
+
+**新版本：**
+```javascript
+// 只需要 3 行代码
+const sdk = new ZEEAvatarSDK(config);
+await sdk.initializeAvatar('avatar001', AvatarCameraType.WHOLE);
+```
+
+
+**ZEE 3D Avatar SDK** - 让3D数字人集成变得简单而强大！ 🚀
+
+---
+
+## 📖 旧版本文档
+
+> **注意**：以下是旧版本SDK的使用说明，仅供未更新的用户参考。**强烈建议升级到新版本以获得更好的开发体验。**
+
+<details>
+<summary>点击展开旧版本文档</summary>
+
+### 旧版本使用方式
+
+#### 1. 创建多个实例
+```javascript
+// 旧版本需要分别创建多个实例
+const loader = new ZEEAvatarLoader(config);
+const avatarAPI = await loader.init();
+const broadcastService = new BroadcastService({
+  unityInstance: loader.getInstance(),
+  callbacks: {
+    onStart: () => console.log('播报开始'),
+    onFinish: () => console.log('播报完成'),
+    onError: (error) => console.error('播报错误:', error)
+  }
+});
+```
+
+#### 2. 分步初始化
+```javascript
+// 旧版本需要分步初始化
+await avatarAPI.initializeAvatar('avatar001', 'whole');
+```
+
+#### 3. 手动管理生命周期
+```javascript
+// 旧版本需要手动管理各个实例
+broadcastService.destroy();
+loader.destroy();
+```
+
+**⚠️ 旧版本问题**：
+- 多实例时回调函数冲突
+- 初始化流程复杂
+- 内部实例暴露过多
+- 错误处理不统一
+
+**🚀 升级建议**：
+请尽快升级到新版本，享受更简单、更强大的SDK体验！
+
+</details>
+