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

package/README.md

@@ -3,7 +3,7 @@
 ## 1. 产品说明
 ### 1.1 产品概述
 紫为云3D写真数字人SDK采用多项AI技术实现：
-- 人脸重建与表情拟人化  
+- 仿真数字人渲染
 - 音频唇形精准驱动  
 - 多终端语音交互  
 - 支持PC/Web/APP/H5全平台  
@@ -15,8 +15,7 @@
 |:--------------:|--------------------------------------------------------------------------|
 | **语音模块** | • 语音/文本对话管理 • 多终端接入控制 • 专属音色          |
 | **交互模块** | • 语音对话交互 •  TTS语音播报 • 大屏字幕同步显示  |
-| **系统功能** | • 多背景切换 • 对话能力配置 • 实时测试体验                          |
-
+| **系统功能** | • 多背景切换 • 对话能力配置 • 实时测试体验 • 统一错误管理          |
 
 ## 2. SDK使用说明
 ### 2.1 核心功能
@@ -26,7 +25,7 @@
 | **数字人播报**     | 通过文本/音频驱动口型表情                                            | ✅      |
 | **播报控制**       | 启动/暂停/继续/停止播报                                              | ✅      |
 | **动作控制**       | 播放预设动作库（招手/点头等）                                        | ✅      |
-
+| **错误管理**       | 统一的错误处理系统，分类错误码，中文化错误消息                        | ✅      |
 
 ### 2.2 安装方式
 #### 2.2.1 npm安装
@@ -40,18 +39,35 @@ npm install @zeewain/3d-avatar-sdk
 ##### ES6+ 模块方式（推荐）
 适用于现代浏览器和构建工具（Webpack、Vite、Rollup等）
 ```javascript
-// 自动选择最佳版本（ES6+ 环境使用 ES 模块，Node.js 环境使用 CommonJS）
-import { ZEEAvatarLoader, AvatarAPI, BroadcastService } from '@zeewain/3d-avatar-sdk'
+// 导入核心模块
+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, AvatarAPI, BroadcastService } from '@zeewain/3d-avatar-sdk/es5'
+import { ZEEAvatarLoader, AvatarService, BroadcastService } from '@zeewain/3d-avatar-sdk/es5'
 
 // ES5 CommonJS 导入
-const { ZEEAvatarLoader, AvatarAPI, BroadcastService } = require('@zeewain/3d-avatar-sdk/es5')
+const { ZEEAvatarLoader, AvatarService, BroadcastService } = require('@zeewain/3d-avatar-sdk/es5')
 ```
 
 #### 2.2.3 通过 CDN 引入
@@ -60,7 +76,7 @@ const { ZEEAvatarLoader, AvatarAPI, BroadcastService } = require('@zeewain/3d-av
 ```html
 <!-- ES 模块方式 -->
 <script type="module">
-  import { ZEEAvatarLoader, AvatarAPI, BroadcastService } from 'https://unpkg.com/@zeewain/3d-avatar-sdk'
+  import { ZEEAvatarLoader, AvatarService, BroadcastService } from 'https://unpkg.com/@zeewain/3d-avatar-sdk'
   // 使用 SDK...
 </script>
 ```
@@ -70,7 +86,7 @@ const { ZEEAvatarLoader, AvatarAPI, BroadcastService } = require('@zeewain/3d-av
 <!-- UMD 方式，支持现代浏览器 -->
 <script src="https://unpkg.com/@zeewain/3d-avatar-sdk"></script>
 <script>
-  const { ZEEAvatarLoader, AvatarAPI, BroadcastService } = window.ZEEAvatarSDK;
+  const { ZEEAvatarLoader, AvatarService, BroadcastService } = window.ZEEAvatarSDK;
   // 使用 SDK...
 </script>
 ```
@@ -80,7 +96,7 @@ const { ZEEAvatarLoader, AvatarAPI, BroadcastService } = require('@zeewain/3d-av
 <!-- ES5 兼容版本，包含完整 polyfill -->
 <script src="https://unpkg.com/@zeewain/3d-avatar-sdk/es5"></script>
 <script>
-  const { ZEEAvatarLoader, AvatarAPI, BroadcastService } = window.ZEEAvatarSDK;
+  const { ZEEAvatarLoader, AvatarService, BroadcastService } = window.ZEEAvatarSDK;
   // 使用 SDK...
 </script>
 ```
@@ -102,22 +118,34 @@ SDK 使用现代化的 `exports` 字段，支持自动版本选择：
 - **老旧工具**：回退到传统的 `main`/`module` 字段
 
 ### 2.3 接口说明
-#### 2.3.1 创建Unity实例
-首先需要配置Unity WebGL构建文件的路径，将通过npm安装的 `@zeewain/3d-avatar-sdk/dist/assets/Build/` 目录下的内容放置在开发工程目录下：
+#### 2.3.1 SDK初始化
+首先需要配置Unity WebGL构建文件的路径和认证信息：
 
 ```javascript
+// SDK配置
 const config = {
-    loaderUrl: './node_modules/@zeewain/3d-avatar-sdk/dist/assets/Build/webgl.loader.js',
-    dataUrl: './node_modules/@zeewain/3d-avatar-sdk/dist/assets/Build/webgl.data.unityweb',
-    frameworkUrl: './node_modules/@zeewain/3d-avatar-sdk/dist/assets/Build/webgl.framework.js.unityweb',
-    codeUrl: './node_modules/@zeewain/3d-avatar-sdk/dist/assets/Build/webgl.wasm.unityweb',
+    // 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)}%`);
     }
 };
 
-const sdk = new ZEEAvatarLoader(config);
+// 创建SDK实例
+const loader = new ZEEAvatarLoader(config);
 ```
 
 > **💡 提示**：Unity 资源文件较大（约19MB），建议：
@@ -125,121 +153,169 @@ const sdk = new ZEEAvatarLoader(config);
 > - 在生产环境中配置适当的缓存策略
 > - 考虑使用 IndexedDB 缓存以加速二次加载
 
-#### 2.3.2 初始化SDK
-调用init()方法加载并初始化Unity环境
+#### 2.3.2 初始化Unity环境
+调用init()方法加载并初始化Unity环境，获取Avatar API实例：
+
 ```javascript
-// 非私有化部署示例：
+let avatarAPI;
+let broadcastService;
+
 try {
-    await sdk.init();
+    // 初始化SDK，返回Avatar API实例
+    avatarAPI = await loader.init();
     console.log('SDK 初始化成功!');
     
-    // 获取Unity实例
-    const instance = sdk.getInstance();
-    const containerId = sdk.getContainerId();
-    
-    // 创建API实例
-    const apiInstance = new AvatarAPI(instance, containerId);
+    // 获取Unity实例（可选）
+    const unityInstance = loader.getInstance();
+    const containerId = loader.getContainerId();
     
     // 创建播报服务实例
-    const broadcastService = new BroadcastService(
-        'prod',  // 非私有化部署，只能用这个，否则会访问不到
-        () => localStorage.getItem('zee_token'), // 获取token的函数
-        instance
-    );
+    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);
 }
-
-// 私有化部署配置示例
-const broadcastService = new BroadcastService(
-  "https://your-private-domain.com", // 私有化域名
-  () => localStorage.getItem('zee_token'),
-  instance
-);
 ```
 
 #### 2.3.3 销毁SDK实例
 在不需要Unity的时候释放Unity实例：
 ```javascript
-sdk.destroy();
+// 销毁播报服务
+if (broadcastService) {
+    broadcastService.destroy();
+}
+
+// 销毁SDK实例
+loader.destroy();
 console.log('Unity环境已销毁');
 ```
 
-
 #### 2.3.4 加载数字人
 ```javascript
-const response = await apiInstance.initializeAvatar(token, avatarCode);
-if (response.success) {
-    console.log('数字人加载成功');
+try {
+    const response = await avatarAPI.initializeAvatar(avatarCode, 'whole');
+    if (response.success) {
+        console.log('数字人加载成功');
+    } else {
+        console.error('数字人加载失败:', response.message);
+    }
+} catch (error) {
+    console.error('加载异常:', error);
 }
 ```
 
 | 参数 | 类型 | 必填项 | 说明 |
 | :---: | :---: | :---:| :---: |
-| token | string  |是 | 用户认证token，详见token获取说明文档 |
-| avatarCode | string  |是 | 数字人编码  |
+| avatarCode | string  |✅ | 数字人编码  |
+| cameraType | AvatarCameraType  |❌ | 摄像机类型：'whole' \| 'half' \| 'face'，默认'whole' |
 
-- 返回值：0 表示成功， 失败返回错误码信息以及失败原因。
+**返回值**：`Promise<IAvatarCallbackResponse>` - 包含操作结果的Promise对象
 
-#### 2.4.5 播放动作
+#### 2.3.5 播放动作
 ```javascript
-const response = await apiInstance.playMotion(token, clipCode);
-if (response.success) {
-    console.log('动作播放成功');
+try {
+    const response = await avatarAPI.playMotion(clipCode);
+    if (response.success) {
+        console.log('动作播放成功');
+    }
+} catch (error) {
+    console.error('动作播放失败:', error);
 }
 ```
 
 | 参数 | 类型 | 必填项 | 说明 |
 | :---: | :---: | :---:| :---: |
-| token | string  |✅  | 用户认证token  |
 | clipCode | string  |✅   | 动作编码 |
-- 返回值：0 表示成功， 失败返回错误码信息以及失败原因。
 
-#### 2.4.6 获取当前动作信息
+**返回值**：`Promise<IAvatarCallbackResponse>` -Promise对象
+
+#### 2.3.6 获取当前动作信息
 ```javascript
-// 获取动作编码和剩余时间
-const response = await apiInstance.getCurrentMotion(true);
-console.log('动作编码:', response.motionId);
-console.log('剩余时间:', response.motionRemainingTime); // 当动作为待机状态（如呼吸动画）时，motionRemainingTime 固定返回0
-
-// 获取动作编码
-const response = await apiInstance.getCurrentMotion(false);
-console.log('动作编码:', response.motionId);
+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);
+}
 ```
 
 | 参数 | 类型 | 必填项 | 说明 |
 | :---: | :---: | :---:| :---: |
-| token | string  |✅  | 用户认证token  |
 | getRemainingTime | boolean  |✅   | 是否获取动作剩余时间|
-- 返回值：0 表示成功， 失败返回错误码信息以及失败原因。
 
-#### 2.4.7 播报服务
+**返回值**：`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
 // 文本播报
-await broadcastService.startBroadcast(token, {
-    type: "text",
-    humanCode: avatarCode,
-    text: "欢迎使用紫为云3D数字人交互SDK",
-    voiceCode: "VOICE001",
-    volume: 1.0,
-    speed: 1.0,
-    isSubtitle: false
-});
+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);
+}
 
 // 音频播报
-await broadcastService.startBroadcast(token, {
-    type: "audio",
-    humanCode: avatarCode,
-    audioUrl: "https://example.com/audio.mp3",
-    text: "音频字幕内容",
-    volume: 1.0,
-    isSubtitle: true
-});
+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 | string  |✅  | 播报类型：'text'或'audio' |
+| type | BroadcastType  |✅  | 播报类型：'text'或'audio' |
 | humanCode | string  |✅   | 数字人编码	|
 | text | string  |✅  | 播报文本内容	 |
 | voiceCode | string  |文本播报✅<br/>音频播报❌| 音色编码		|
@@ -247,89 +323,323 @@ await broadcastService.startBroadcast(token, {
 | volume | number  |❌ | 音量 (0-1.0)	默认:1.0|
 | speed | number  |❌ | 语速 (0.5-2.0)默认:1.0|
 | isSubtitle | boolean  |❌  | 是否启用字幕	(暂不支持）|
-- 返回值：0 表示成功， 失败返回错误码信息以及失败原因。
 
-#### 2.4.8 暂停播报
+#### 2.3.9 播报控制
 ```javascript
-await broadcastService.pauseBroadcast(token);
+// 暂停播报
+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);
+}
 ```
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| token | string  |✅  | 用户认证token  |
 
-#### 2.4.9 恢复播报
+#### 2.3.10 卸载数字人
 ```javascript
-await broadcastService.resumeBroadcast(token);
+try {
+    const response = await avatarAPI.unloadAvatar();
+    if (response.success) {
+        console.log('数字人卸载成功');
+    }
+} catch (error) {
+    console.error('数字人卸载失败:', error);
+}
 ```
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| token | string  |✅  | 用户认证token  |
 
-#### 2.4.10 结束播报
+**返回值**：`Promise<IAvatarCallbackResponse>` - 包含操作结果的Promise对象
+
+#### 2.3.11 批量操作
 ```javascript
-await broadcastService.stopBroadcast(token);
+// 批量执行多个操作
+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);
+}
 ```
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| token | string  |✅  | 用户认证token  |
 
-#### 2.4.11 卸载数字人
+#### 2.3.12 播报状态管理
 ```javascript
-const response = await apiInstance.unloadAvatar(token);
-if (response.success) {
-    console.log('数字人卸载成功');
-}
+// 获取播报状态
+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)
+});
 ```
-| 参数 | 类型 | 必填项 | 说明 |
-| :---: | :---: | :---:| :---: |
-| token | string  |✅  | 用户认证token  |
-- 返回值：0 表示成功， 失败返回错误码信息以及失败原因。
 
-### 2.5 错误处理
-SDK中的操作可能会抛出异常，建议使用try-catch处理：
+### 2.4 错误处理
+SDK中的操作都返回Promise，建议使用try-catch处理异常。SDK使用统一的错误管理系统，所有错误都继承自`SDKError`类：
+
 ```javascript
-// try-catch 示例：
+// 导入错误类型和错误码（TypeScript项目）
+import { SDKError, NetworkErrorCode, OperationErrorCode, ResourceErrorCode, SystemErrorCode, ConfigErrorCode } from '@zeewain/3d-avatar-sdk'
+
+// 统一错误处理示例
 try {
-    await apiInstance.initializeAvatar(token, avatarCode);
+    const response = await avatarAPI.initializeAvatar('avatar001');
+    if (response.success) {
+        console.log('数字人加载成功');
+    }
 } catch (error) {
-    console.error('数字人加载失败:', error.message);
+    // 处理SDK错误
+    if (error instanceof SDKError) {
+        handleSDKError(error);
+    } else {
+        // 处理其他系统异常
+        console.error('系统异常:', error.message);
+    }
+}
+
+// SDK错误处理
+function handleSDKError(error) {
+    console.error('SDK错误:', error.message, '错误码:', error.code);
     
-    // 根据错误类型进行特定处理
-    if (error.message.includes('Token无效')) {
-        // 重新获取token
+    // 根据错误类别处理
+    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;
     }
 }
 
-// 错误码处理示例：
-catch (error) {
-  switch (error.code) {
-    case 7: // Token失效
-      await refreshToken(); 
-      break;
-    case 2: // 网络错误
-      showToast("网络异常，请检查连接");
-      break;
-    default:
-      console.error(`未知错误: ${error.code}`);
-  }
+// 操作错误处理
+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.6 返回编码以及对应信息参考表
+### 2.5 SDK错误码参考表
 
-| 返回编码 | 编码名称 | 描述说明 | 常见发生场景 |
+SDK使用统一的错误管理系统，所有错误都通过`SDKError`抛出：
+
+##### 网络错误 (1xxx)
+| 错误码 | 常量名 | 描述说明 | 常见发生场景 |
 | :---: | :---: | :---: | :---: |
-| 0 | 成功 | 操作成功 | 返回、操作结果正常|
-| 1 | 资源加载失败 | Unity资源加载失败 | Unity AssetBundle加载失败、纹理、音频等资源加载失败等|
-| 2 | 网络通信错误  | 网络请求相关错误 | 下载超时、连接中断、服务器错误等 |
-| 3 | 配置参数错误 | 配置数据错误或缺失 |Json解析失败、参数缺失、路径错误等 |
-| 4 | 操作执行错误 | 特定操作执行失败 | 动画播放失败、装扮应用失败、在非常规下操作数字人导致的问题等 |
-| 5 | 系统资源不足 | 系统资源限制 | 内存不足、GPU资源不足等 |
-| 6 | 状态冲突错误 | 当前状态不允许执行此操作 | 在非准备状态下执行操作等 |
-| 7 | 数据验证错误 | 数据验证或者格式错误 | 许可证无效、数据校验失败、token过期等 |
-| 8 | 第三方依赖错误 | 外部依赖或服务错误 | 云服务不可用、第三方SDK引用失败等 |
-| 9 | 其他 |  未知 | 未知 |
+| 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构建文件
@@ -342,10 +652,12 @@ catch (error) {
 ### 3.3 数字人加载和卸载时机
 - 数字人加载成功后，才能卸载数字人。
 - 在未成功加载数字人的时候，提前卸载数字人，卸载会成功，但是会导致第二次加载数字人失败；解决方案：卸载Unity实例化，重新初始化Unity，再初始化数字人即可解决。
-- 目前版本不支持数字人的返回进度，后续版本会提供。
 ### 3.4 错误处理
-- 所有异步操作都可能抛出异常，务必使用try-catch处理。
-- 检查错误消息中包含的具体错误原因。
+- 所有异步操作都返回Promise，务必使用try-catch处理。
+- 检查response.success字段判断操作是否成功。
+- **统一错误管理系统**：所有错误都通过`SDKError`抛出，通过错误码和错误类别进行精确处理。
+- SDK错误码采用分类编码：网络错误(1xxx)、操作错误(2xxx)、资源错误(3xxx)、系统错误(4xxx)、配置错误(5xxx)。
+- 所有错误消息已本地化为中文，可直接显示给用户。
 ### 3.5 性能考虑
 - 避免频繁加载/卸载数字人。
 - 音频文件不易过大。（建议<5MB）
@@ -367,17 +679,19 @@ catch (error) {
 - **移动设备**：注意性能限制，考虑降低渲染质量
 - **资源缓存**：Web端建议对Unity资源文件使用 IndexedDB 缓存
 - **网络优化**：将Unity资源部署到CDN以提高加载速度
-### 3.7 关于必填参数
-- 所有标注为✅  的参数必须提供。
-- token失效会导致接口调用失败。
+
+### 3.7 认证配置
+- token在SDK初始化时配置，无需在每个API调用时传递
+- token失效时，需要重新初始化SDK或更新全局配置
+- 支持生产环境('prod')、测试环境('test')和自定义环境('custom')
 
 ## 4. 常见问题
 ### 4.1 Unity内容无法加载怎么办？
 
 1. 确保Unity构建文件路径配置正确;
 2. 检查浏览器控制台是否有CORS错误;
-3.  确认网络可以访问构建文件URL;
-4.  验证Unity版本与SDK兼容性;
+3. 确认网络可以访问构建文件URL;
+4. 验证Unity版本与SDK兼容性;
 
 ### 4.2 播报没有声音怎么办？
 
@@ -402,3 +716,38 @@ catch (error) {
 
 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完整支持**：完整的错误类型定义，更好的开发体验
+- ✅ **统一异常处理**：所有错误都通过异常抛出，简化错误处理逻辑
+