@zeewain/3d-avatar-sdk 1.2.5 → 2.1.2

package/README.md

@@ -32,10 +32,29 @@
 
 ## 📦 安装方式
 
-> **WebGL文件来源说明**：
+> **WebGL文件与资源包说明**：
+> 
+> **1. 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文件的路径。
+> 
+> **2. 数字人资源包（必需）**
+> - **资源包获取**：从紫为云开放平台下载与SDK版本对应的数字人资源包（`版本号前两位必须一致`）。
+> - **资源包内容**：包含数字人所需的形象资源、动作资源等完整资源文件。
+> - **资源部署**：将下载的资源包解压后，部署到您的服务器或CDN服务器上。
+> - **路径配置**：通过`assetsUrl`参数配置资源包的访问地址。
+> - **路径格式**：`assetsUrl`通常格式为：`https://your-domain.com/<SDK版本号前两位>`
+>   - 示例：SDK版本为 2.1.3，则 `assetsUrl` 应配置为：`https://cdn.zeewain3d.com/webgl/2.1`
+> 
+> **3. 动作资源扩展（可选）**
+> - 动作资源可单独从开放平台下载**（版本号前两位也必须跟SDK版本号一致）**，下载后解压到资源包所在目录即可。
+> - 新增的动作将自动集成到现有资源体系中。
+> 
+> **⚠️ 版本兼容性要求**
+> - SDK版本与资源包版本的前两位版本号必须一致。
+> - 例如：SDK 2.1.x 必须使用 2.1.x 的资源包，不能使用 2.0.x 或 2.2.x 的资源包。
+> - SDK在初始化时会自动检查版本兼容性，若不兼容会抛出 `ResourceErrorCode.VERSION_INCOMPATIBLE` 错误并自动卸载。
 
 ### npm/yarn 安装（推荐）
 
@@ -94,6 +113,9 @@ const sdk = new ZEEAvatarSDK({
   frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
   codeUrl: './assets/Build/webgl.wasm.unityweb',
   
+  // 数字人资源包配置（必填）
+  assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
+  
   // 基础配置
   containerId: 'unity-container',
   token: 'your-auth-token',
@@ -178,6 +200,7 @@ class AvatarApp {
         dataUrl: './assets/Build/webgl.data.unityweb',
         frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
         codeUrl: './assets/Build/webgl.wasm.unityweb',
+        assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
         containerId: 'unity-container',
         token: 'your-auth-token',
         env: 'prod',
@@ -480,17 +503,23 @@ interface IAvatarSDKConfig {
   frameworkUrl: string;       // Unity框架文件URL
   codeUrl: string;            // Unity代码文件URL
   
+  // 数字人资源包配置（必填）
+  assetsUrl: string;          // 数字人资源包地址（必填）
+                              // 从开放平台下载资源包并部署后的访问地址
+                              // 格式：https://your-domain.com/<SDK版本号前两位>
+                              // 示例：https://cdn.zeewain3d.com/webgl/2.1
+                              // 注意：版本号前两位必须与SDK版本一致
+  
   // 基础配置
   containerId?: string;       // 容器DOM元素ID，默认'unity-container'
   token?: string;             // 用户认证令牌
   env?: 'dev' | 'test' | 'prod' | 'custom';  // 运行环境，默认'prod'
   apiUrl?: string;            // 自定义API地址（env='custom'时需要）
-  assetsUrl?:string;          // 自定义资源文件地址（env='custom'时有效）
-  resourcesUrl?: string;      // AB资源文件地址
-  idleMotionList?:string[];   // 待机动作编码列表，随机播放（排重方式），可选
+  idleMotionList?: string[];  // 待机动作编码列表，随机播放（排重方式），可选
+  
   // 回调函数
   onProgress?: (progress: number) => void;  // 加载进度回调，可选
-  broadcastCallbacks?:IBroadcastCallbacks; // 播报回调函数，可选
+  broadcastCallbacks?: IBroadcastCallbacks; // 播报回调函数，可选
 }
 ```
 
@@ -871,6 +900,121 @@ destroy(): void
 
 销毁SDK实例，清理所有资源。**重要：页面卸载前务必调用此方法！**
 
+## 🔄 版本兼容性管理
+
+### 自动版本检查机制
+
+SDK内置了严格的版本兼容性检查机制，确保SDK版本与资源包版本匹配，避免因版本不一致导致的运行异常。
+
+#### 版本检查规则
+
+- **检查时机**：在 `initializeAvatar()` 初始化数字人时自动进行
+- **检查范围**：SDK版本号与资源包版本号的**前两位**必须一致
+- **版本格式**：采用语义化版本号 `主版本号.次版本号.修订号`（如 2.1.3）
+- **兼容规则**：
+  - ✅ SDK 2.1.3 + 资源包 2.1.0 → 兼容
+  - ✅ SDK 2.1.3 + 资源包 2.1.5 → 兼容
+  - ❌ SDK 2.1.3 + 资源包 2.0.0 → 不兼容
+  - ❌ SDK 2.1.3 + 资源包 2.2.0 → 不兼容
+
+#### 版本不兼容时的行为
+
+当检测到版本不兼容时，SDK会：
+
+1. **抛出错误**：抛出 `ResourceErrorCode.VERSION_INCOMPATIBLE` (错误码: 3005) 错误
+2. **自动卸载**：自动调用 `destroy()` 清理已初始化的资源
+3. **详细信息**：错误消息包含SDK版本和资源包版本信息
+
+**示例错误信息：**
+```
+资源版本不兼容: SDK版本为 2.1.3，WebGL资源版本为 2.0.5，前两位版本号必须一致
+```
+
+#### 版本兼容性处理示例
+
+```javascript
+import { ZEEAvatarSDK, ResourceErrorCode, SDKError } from '@zeewain/3d-avatar-sdk'
+
+async function initAvatarWithVersionCheck() {
+  const 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',
+    assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
+    containerId: 'unity-container',
+    token: 'your-auth-token'
+  });
+
+  try {
+    const response = await sdk.initializeAvatar('avatar001');
+    
+    if (response.success) {
+      console.log('✅ 数字人初始化成功，版本检查通过');
+    }
+  } catch (error) {
+    if (error instanceof SDKError && error.code === ResourceErrorCode.VERSION_INCOMPATIBLE) {
+      // 版本不兼容错误处理
+      console.error('❌ 版本不兼容:', error.message);
+      
+      // 提示用户更新资源包
+      showUpdateNotification({
+        title: '资源包版本不匹配',
+        message: '请下载与当前SDK版本匹配的资源包',
+        action: '前往下载'
+      });
+    } else {
+      // 其他错误处理
+      console.error('初始化失败:', error);
+    }
+  }
+}
+
+// 显示更新提示
+function showUpdateNotification(options) {
+  // 显示友好的UI提示
+  const notification = document.createElement('div');
+  notification.className = 'version-notification';
+  notification.innerHTML = `
+    <h3>${options.title}</h3>
+    <p>${options.message}</p>
+    <button onclick="window.open('https://open.zeewain3d.com/downloads', '_blank')">
+      ${options.action}
+    </button>
+  `;
+  document.body.appendChild(notification);
+}
+```
+
+#### 资源包下载与部署建议
+
+1. **获取SDK版本号**
+   ```javascript
+   import { SDK_VERSION } from '@zeewain/3d-avatar-sdk'
+   console.log('当前SDK版本:', SDK_VERSION); // 如: 2.1.3
+   ```
+
+2. **下载对应资源包**
+   - 访问紫为·AI开放平台
+   - 下载版本号前两位一致的资源包（如：2.1.x 系列）
+
+3. **部署资源包**
+   - 将资源包解压到服务器或CDN
+   - 按版本号组织目录结构：`/webgl/2.1`
+   - 配置 `assetsUrl: 'https://your-cdn.com/webgl/2.1'`
+
+#### 版本升级策略
+
+当需要升级SDK版本时：
+
+**场景1：修订号升级（如 2.1.3 → 2.1.5）**
+- ✅ 资源包无需更新
+- ✅ 直接升级SDK即可
+
+**场景2：主版本号或次版本号升级（如 2.1.3 → 2.2.0 或 2.1.3 → 3.0.0）**
+- ⚠️ 需要重新下载资源包（2.2.x 或 3.0.x）
+- ⚠️ 更新 `assetsUrl` 配置为新版本路径
+
 ## 🔧 高级功能
 
 ### 🎯 智能播报队列
@@ -965,6 +1109,7 @@ const sdk1 = new ZEEAvatarSDK({
   dataUrl: './assets/Build/webgl.data.unityweb',
   frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
   codeUrl: './assets/Build/webgl.wasm.unityweb',
+  assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
   containerId: 'unity-container-1',
   token: 'token1'
 });
@@ -974,6 +1119,7 @@ const sdk2 = new ZEEAvatarSDK({
   dataUrl: './assets/Build/webgl.data.unityweb',
   frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
   codeUrl: './assets/Build/webgl.wasm.unityweb',
+  assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
   containerId: 'unity-container-2',
   token: 'token2'
 });
@@ -1063,6 +1209,26 @@ function handleOperationError(error) {
   }
 }
 
+// 资源错误处理
+function handleResourceError(error) {
+  switch (error.code) {
+    case ResourceErrorCode.LOAD_FAILED:
+      showUserMessage('资源加载失败，请检查网络或资源路径');
+      break;
+    case ResourceErrorCode.VERSION_INCOMPATIBLE:
+      showUserMessage('资源版本不兼容，请下载与SDK版本匹配的资源包');
+      // 显示详细版本信息
+      console.error('版本不兼容:', error.message);
+      break;
+    case ResourceErrorCode.NOT_FOUND:
+      showUserMessage('资源不存在，请检查assetsUrl配置');
+      break;
+    case ResourceErrorCode.FILE_CORRUPTED:
+      showUserMessage('资源文件损坏，请重新下载资源包');
+      break;
+  }
+}
+
 // 在SDK操作中使用
 try {
   await sdk.initializeAvatar('avatar001');
@@ -1204,6 +1370,7 @@ document.addEventListener('visibilitychange', () => {
 | 3002 | `ResourceErrorCode.FILE_CORRUPTED` | 资源文件损坏 | 重新下载资源文件 |
 | 3003 | `ResourceErrorCode.NOT_FOUND` | 资源不存在 | 检查资源路径 |
 | 3004 | `ResourceErrorCode.UNSUPPORTED_FORMAT` | 资源格式不支持 | 使用支持的格式 |
+| 3005 | `ResourceErrorCode.VERSION_INCOMPATIBLE` | 资源版本不兼容 | 下载与SDK版本匹配的资源包（前两位版本号一致） |
 
 ### 系统错误 (4xxx)
 | 错误码 | 常量名 | 描述 | 处理建议 |
@@ -1380,6 +1547,7 @@ export const avatarConfig = {
     dataUrl: './assets/Build/webgl.data.unityweb',
     frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
     codeUrl: './assets/Build/webgl.wasm.unityweb',
+    assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
     containerId: 'unity-container',
     env: 'dev',
     token: 'dev-token'
@@ -1389,6 +1557,7 @@ export const avatarConfig = {
     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',
+    assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
     containerId: 'unity-container',
     env: 'prod',
     token: process.env.AVATAR_TOKEN
@@ -1518,10 +1687,11 @@ class NewAvatarApp {
 
 **A1:** 请按以下步骤排查：
 
-1. **检查文件路径**：确保Unity构建文件路径配置正确
-2. **CORS问题**：如果文件在不同域名，需要配置CORS
-3. **网络连接**：确认网络可以访问构建文件URL
-4. **浏览器兼容性**：确认浏览器支持WebGL 2.0
+1. **检查文件路径**：确保Unity构建文件路径和资源包路径配置正确
+2. **检查assetsUrl**：确认资源包已正确部署且assetsUrl配置正确
+3. **CORS问题**：如果文件在不同域名，需要配置CORS
+4. **网络连接**：确认网络可以访问构建文件URL和资源包URL
+5. **浏览器兼容性**：确认浏览器支持WebGL 2.0
 
 ```javascript
 // 检查资源可访问性
@@ -1530,17 +1700,20 @@ async function checkResourcesAvailability(config) {
     config.loaderUrl,
     config.dataUrl,
     config.frameworkUrl,
-    config.codeUrl
+    config.codeUrl,
+    config.assetsUrl  // 检查资源包地址
   ];
   
   for (const url of resources) {
     try {
       const response = await fetch(url, { method: 'HEAD' });
       if (!response.ok) {
-        console.error(`资源不可访问: ${url}`);
+        console.error(`❌ 资源不可访问: ${url}`);
+      } else {
+        console.log(`✅ 资源可访问: ${url}`);
       }
     } catch (error) {
-      console.error(`资源检查失败: ${url}`, error);
+      console.error(`❌ 资源检查失败: ${url}`, error);
     }
   }
 }
@@ -1718,6 +1891,70 @@ class AvatarManager {
 }
 ```
 
+### Q6: 遇到版本不兼容错误怎么办？
+
+**A6:** 版本不兼容错误（错误码3005）说明SDK版本与资源包版本不匹配，请按以下步骤解决：
+
+**1. 确认版本信息**
+```javascript
+import { SDK_VERSION } from '@zeewain/3d-avatar-sdk'
+console.log('当前SDK版本:', SDK_VERSION); // 如: 2.1.3
+```
+
+**2. 检查错误详情**
+```javascript
+try {
+  await sdk.initializeAvatar('avatar001');
+} catch (error) {
+  if (error.code === 3005) {
+    // 错误消息会显示具体的版本信息
+    console.error(error.message);
+    // 示例: "资源版本不兼容: SDK版本为 2.1.3，WebGL资源版本为 2.0.5，前两位版本号必须一致"
+  }
+}
+```
+
+**3. 解决方案**
+
+**方案A：更新资源包（推荐）**
+- 访问紫为·AI开放平台
+- 下载与SDK版本号前两位一致的资源包
+- 例如：SDK版本为 2.1.3，需下载 2.1.x 系列的资源包
+- 将资源包部署到服务器或CDN
+- 更新 `assetsUrl` 配置
+
+**方案B：回退SDK版本**
+```bash
+# 如果资源包是 2.1.x 版本，回退SDK到对应版本
+npm install @zeewain/3d-avatar-sdk@2.1.x
+```
+
+**4. 版本匹配示例**
+
+| SDK版本 | 兼容的资源包版本 | 是否兼容 |
+|:--------|:----------------|:---------|
+| 2.1.3   | 2.1.0, 2.1.5, 2.1.10 | ✅ 兼容 |
+| 2.1.3   | 2.0.8, 2.2.0, 3.0.0  | ❌ 不兼容 |
+
+**5. 预防措施**
+```javascript
+// 在配置文件中记录版本信息
+const config = {
+  sdkVersion: '2.1.3',  // SDK版本
+  assetsVersion: '2.1',  // 资源包版本
+  assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
+  // ... 其他配置
+};
+
+// 定期检查版本一致性
+function checkVersionConsistency(config) {
+  const sdkMajorMinor = config.sdkVersion.split('.').slice(0, 2).join('.');
+  if (sdkMajorMinor !== config.assetsVersion) {
+    console.warn('⚠️ 配置文件中SDK版本与资源包版本不匹配');
+  }
+}
+```
+
 ## 🆚 新旧版本对比
 
 ### 使用体验对比

package/dist/examples/test-umd/index.html

@@ -441,10 +441,11 @@ function updateUnityPlaceholder(display)
 		      // frameworkUrl: 'https://unpkg.com/@zeewain/3d-avatar-sdk@1.2.1/dist/assets/Build/webgl.framework.js.unityweb',
 		      // codeUrl: 'https://unpkg.com/@zeewain/3d-avatar-sdk@1.2.1/dist/assets/Build/webgl.wasm.unityweb',
 		      // 使用本地WebGL文件
-      loaderUrl: './public/assets/Build/webgl.loader.js',
+		      loaderUrl: './public/assets/Build/webgl.loader.js',
 		      dataUrl: './public/assets/Build/webgl.data.unityweb',
 		      frameworkUrl: './public/assets/Build/webgl.framework.js.unityweb',
 		      codeUrl: './public/assets/Build/webgl.wasm.unityweb',
+		      assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
 		      containerId: 'unity-container',
 		      env: 'dev',
 		      onProgress: (progress) =>

package/dist/examples/test-vue2/package.json

@@ -16,7 +16,7 @@
     "lint:all-fix": "npm run lint:fix && npm run lint:css-fix"
   },
   "dependencies": {
-    "@zeewain/3d-avatar-sdk": "^1.2.5",
+    "@zeewain/3d-avatar-sdk": "^2.1.2",
     "core-js": "^3.8.3",
     "element-ui": "^2.15.13",
     "vue": "^2.6.14"

package/dist/examples/test-vue2/src/App.vue

@@ -313,6 +313,7 @@ export default {
         dataUrl: './assets/Build/webgl.data.unityweb',
         frameworkUrl: './assets/Build/webgl.framework.js.unityweb',
         codeUrl: './assets/Build/webgl.wasm.unityweb',
+        assetsUrl: 'https://cdn.zeewain3d.com/webgl/2.1',
         containerId: 'unity-container',
 
         // 认证配置

package/dist/examples/test-vue3/package.json

@@ -24,7 +24,7 @@
     "@element-plus/icons-vue": "^2.3.1",
     "@vueuse/core": "^13.5.0",
     "@vueuse/integrations": "^13.5.0",
-    "@zeewain/3d-avatar-sdk": "^1.2.5",
+    "@zeewain/3d-avatar-sdk": "^2.1.2",
     "dayjs": "^1.11.13",
     "element-plus": "^2.10.4",
     "vite-plugin-html": "^3.2.2",

package/dist/examples/test-vue3/src/App.vue

@@ -306,7 +306,7 @@ function initializeSDKConfig(): ZEEAvatarSDK | null {
     token: globalConfig.token,
     env: globalConfig.env,
     apiUrl: globalConfig.apiBaseUrl,
-    resourcesUrl: globalConfig.resourcesUrl || undefined,
+    assetsUrl: globalConfig.assetsUrl || undefined,
     enableDebugLog: true,
     // 待机动作列表：比心，左手指示（低）
     idleMotionList: globalConfig.idleMotionListString?.split(',').filter(item => item.trim()) || [],

package/dist/examples/test-vue3/src/components/GlobalConfig.vue

@@ -27,17 +27,20 @@
               </template>
             </el-input>
           </el-form-item>
-          <el-form-item  v-if="modelValue.env === 'custom'" label="AB包地址">
+          <el-form-item label="WebGL路径" required>
             <el-input
-              v-model="modelValue.resourcesUrl"
-              placeholder="请输入AB包地址"
+              v-model="modelValue.webglPath"
+              placeholder="请输入WebGL路径"
               clearable>
+              <template #prefix> 
+                <el-icon><Folder /></el-icon>
+              </template>
             </el-input>
           </el-form-item>
-          <el-form-item label="WebGL路径" required>
+          <el-form-item label="资源路径" required>
             <el-input
-              v-model="modelValue.webglPath"
-              placeholder="请输入WebGL路径"
+              v-model="modelValue.assetsUrl"
+              placeholder="请输入资源路径"
               clearable>
               <template #prefix> 
                 <el-icon><Folder /></el-icon>

package/dist/examples/test-vue3/src/types.ts

@@ -4,6 +4,6 @@ export interface IGlobalConfig {
   env: 'dev' | 'test' | 'prod' | 'custom';
   webglPath?:string;
   apiBaseUrl?:string;
-  resourcesUrl?:string;
+  assetsUrl?:string; 
   idleMotionListString?:string;
 }

package/dist/index.d.ts

@@ -114,32 +114,6 @@ interface IUnityMessageSender<T extends string> {
     /** 发送异步消息到Unity并等待回调 */
     sendAsyncMessage(methodName: string, operation: T, parameter?: any): Promise<IUnityCallbackResponse>;
 }
-/**
- * Unity服务日志级别枚举
- * @enum {string}
- * @description 定义日志记录的级别
- */
-declare enum LogLevel {
-    DEBUG = "debug",
-    INFO = "info",
-    WARN = "warn",
-    ERROR = "error"
-}
-/**
- * Unity服务日志记录器接口
- * @interface IUnityLogger
- * @description 统一的日志记录接口
- */
-interface IUnityLogger {
-    /** 记录调试信息 */
-    debug(message: string, data?: any): void;
-    /** 记录一般信息 */
-    info(message: string, data?: any): void;
-    /** 记录警告信息 */
-    warn(message: string, data?: any): void;
-    /** 记录错误信息 */
-    error(message: string, error?: Error, data?: any): void;
-}
 
 /**
  * @fileoverview 流式播报服务接口定义
@@ -337,10 +311,8 @@ interface IAvatarSDKConfig {
     env?: 'dev' | 'test' | 'prod' | 'custom';
     /** api接口地址，仅当env为custom时有效 */
     apiUrl?: string;
-    /** 资源文件地址，仅当env为custom时有效 */
-    assetsUrl?: string;
-    /** AB资源文件地址 */
-    resourcesUrl?: string;
+    /** 资源文件地址（父级路径），从平台下载的资源文件所解压出来的目录 */
+    assetsUrl: string;
     /** Unity加载器脚本URL */
     loaderUrl: string;
     /** Unity数据文件URL */
@@ -359,6 +331,8 @@ interface IAvatarSDKConfig {
     broadcastCallbacks?: IBroadcastCallbacks;
     /** 是否启用调试日志，默认为false */
     enableDebugLog?: boolean;
+    /** 内部 WEBGL 版本 */
+    audioDrivenVersion?: string;
 }
 
 /**
@@ -400,6 +374,8 @@ interface IAvatarCallbackResponse extends IUnityCallbackResponse {
         motionId?: string;
         /** 动作剩余时间，可选 */
         motionRemainingTime?: number;
+        /** 内部 WEBGL 版本 */
+        audioDrivenVersion?: string;
     };
 }
 /**
@@ -460,8 +436,6 @@ interface IAvatarAPI {
  * @description 提供统一的SDK接口，简化用户使用体验，支持多实例
  */
 declare class ZEEAvatarSDK {
-    /** SDK配置 */
-    private config;
     /** SDK唯一标识符 */
     private readonly instanceId;
     /** Unity加载器实例 */
@@ -474,6 +448,8 @@ declare class ZEEAvatarSDK {
     private unityInstance;
     /** SDK初始化状态 */
     private isInitialized;
+    /** SDK日志 */
+    private readonly logger;
     /**
      * 构造函数
      * @param config SDK配置对象
@@ -585,7 +561,7 @@ declare class ZEEAvatarSDK {
      * 获取SDK配置
      * @returns IAvatarSDKConfig 当前配置
      */
-    getConfig(): IAvatarSDKConfig;
+    getConfig(): IAvatarSDKConfig | null;
     /**
      * 确保SDK已初始化
      * @private
@@ -593,6 +569,32 @@ declare class ZEEAvatarSDK {
     private ensureInitialized;
 }
 
+/**
+ * @fileoverview SDK 版本号常量
+ * @description 此文件由构建脚本自动生成，请勿手动修改
+ */
+/**
+ * SDK 版本号
+ * @const {string} SDK_VERSION
+ */
+declare const SDK_VERSION = "2.1.2";
+
+/**
+ * Unity服务日志记录器接口
+ * @interface ISimpleLogger
+ * @description 统一的日志记录接口
+ */
+interface ISimpleLogger {
+    /** 记录调试信息 */
+    debug(message: string, data?: any): void;
+    /** 记录一般信息 */
+    info(message: string, data?: any): void;
+    /** 记录警告信息 */
+    warn(message: string, data?: any): void;
+    /** 记录错误信息 */
+    error(message: string, error?: Error, data?: any): void;
+}
+
 /**
  * @fileoverview Unity服务抽象基类
  * @description 提供Unity服务的通用基础实现，包括回调管理、消息发送、错误处理等功能
@@ -613,7 +615,7 @@ declare abstract class UnityBaseService<T extends string> implements IUnityCallb
     /** 操作超时时间 */
     protected readonly timeout: number;
     /** 日志记录器 */
-    protected readonly logger: IUnityLogger;
+    protected readonly logger: ISimpleLogger;
     /** 最大重试次数 */
     protected readonly maxRetries: number;
     /** SDK实例唯一标识符 */
@@ -763,6 +765,7 @@ declare class AvatarService extends UnityBaseService<AvatarOperationType> implem
      * ```
      */
     initializeAvatar(avatarCode: string, cameraType?: AvatarCameraType): Promise<IAvatarCallbackResponse>;
+    handleCallback(operation: AvatarOperationType, code: number, message: string, data?: string): void;
     /**
      * 播放数字人动作
      * @param clipCode - 动作编码
@@ -1045,7 +1048,7 @@ declare class BroadcastService extends UnityBaseService<BroadcastOperationType>
      * 处理任务错误
      * @param task - 播报任务
      * @param error - 错误对象
-     * @description 处理任务执行过程中的错误
+     * @description 处理任务执行过程中的错误，防止重复触发错误回调
      * @private
      */
     private handleTaskError;
@@ -1100,6 +1103,25 @@ declare class BroadcastService extends UnityBaseService<BroadcastOperationType>
      * @private
      */
     private clearQueueProcessTimer;
+    /**
+     * 根据 HTTP 状态码创建对应的 SDKError
+     * @param status - HTTP 状态码
+     * @param statusText - HTTP 状态文本
+     * @param taskId - 任务 ID（用于日志记录）
+     * @returns SDKError 实例
+     * @description 将 HTTP 错误状态码映射为对应的 SDKError
+     * @private
+     */
+    private createHttpError;
+    /**
+     * 将任意错误转换为 SDKError
+     * @param error - 原始错误对象
+     * @param taskId - 任务 ID（用于日志记录）
+     * @returns SDKError 实例
+     * @description 统一将各种类型的错误转换为 SDKError，便于上层统一处理
+     * @private
+     */
+    private convertToSDKError;
 }
 
 /**
@@ -1174,7 +1196,9 @@ declare enum ResourceErrorCode {
     /** 资源不存在 */
     NOT_FOUND = 3003,
     /** 资源格式不支持 */
-    UNSUPPORTED_FORMAT = 3004
+    UNSUPPORTED_FORMAT = 3004,
+    /** 资源版本不兼容 */
+    VERSION_INCOMPATIBLE = 3005
 }
 /**
  * 系统错误码 (4xxx)
@@ -1338,7 +1362,7 @@ declare class ZEEAvatarLoader {
      * @param config - Unity配置对象
      * @description 初始化数字人加载器，创建Unity加载器实例
      */
-    constructor(config: IAvatarSDKConfig);
+    constructor();
     /**
      * 初始化数字人SDK
      * @returns Promise<IAvatarAPI> 返回Avatar API的Promise
@@ -1399,5 +1423,5 @@ declare class ZEEAvatarLoader {
     protected initGlobalConfig(): void;
 }
 
-export { AvatarCameraType, AvatarOperationType, AvatarService, BroadcastOperationType, BroadcastService, BroadcastType, ConfigErrorCode, ERROR_CODE_MAP, ErrorCategory, LogLevel, NetworkErrorCode, OperationErrorCode, ResourceErrorCode, SDKError, SystemErrorCode, UnityOperationStatus, ZEEAvatarLoader, ZEEAvatarSDK, getErrorInfo };
-export type { IAvatarAPI, IAvatarCallbackResponse, IAvatarSDKConfig, IBroadcastAPI, IBroadcastCallbacks, IBroadcastParams, IBroadcastResponse, IBroadcastServiceConfig, IUnityCallbackManager, IUnityCallbackResponse, IUnityInstance, IUnityLogger, IUnityMessageSender, IUnityServiceConfig, SDKErrorCode, TOperationType };
+export { AvatarCameraType, AvatarOperationType, AvatarService, BroadcastOperationType, BroadcastService, BroadcastType, ConfigErrorCode, ERROR_CODE_MAP, ErrorCategory, NetworkErrorCode, OperationErrorCode, ResourceErrorCode, SDKError, SDK_VERSION, SystemErrorCode, UnityOperationStatus, ZEEAvatarLoader, ZEEAvatarSDK, getErrorInfo };
+export type { IAvatarAPI, IAvatarCallbackResponse, IAvatarSDKConfig, IBroadcastAPI, IBroadcastCallbacks, IBroadcastParams, IBroadcastResponse, IBroadcastServiceConfig, IUnityCallbackManager, IUnityCallbackResponse, IUnityInstance, IUnityMessageSender, IUnityServiceConfig, SDKErrorCode, TOperationType };