@zeewain/3d-avatar-sdk 1.2.4 → 2.1.1

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; // 播报回调函数，可选
 }
 ```
 
@@ -750,7 +779,7 @@ updateBroadcastCallbacks(callbacks: IBroadcastCallbacks): void
 ```typescript
 interface IBroadcastCallbacks {
   onStart?: () => void;           // 播报开始
-  onFinish?: () => void;          // 播报完成
+  onFinish?: () => void;          // 播报完成（每调用一次`startBroadcast`，在播报结束后都会触发一次回调）
   onError?: (error: Error) => void; // 播报错误
   onPause?: () => void;           // 播报暂停
   onResume?: () => void;          // 播报恢复
@@ -775,8 +804,6 @@ getBroadcastStatus(): {
   isActive: boolean;
   isGeneratingAudio: boolean;
   hasReceivedAudio: boolean;
-  pendingCallbacks: number;
-  hasController: boolean;
   queueInfo?: {
     totalTasks: number;              // 队列中总任务数
     requestingTasks: number;         // 正在请求中的任务数
@@ -788,14 +815,12 @@ getBroadcastStatus(): {
 }
 ```
 
-获取播报状态信息，包括队列状态监控。
+获取播报状态信息，包括队列状态监控。`当播报队列中最后一条音频播放完毕后，队列状态信息将被重置。`
 
 **返回值说明：**
-- `isActive`: 播报服务是否活跃（有任务在队列中或正在生成音频）
+- `isActive`: 播报服务是否活跃（是否正在播报音频或正在生成音频）
 - `isGeneratingAudio`: 是否正在生成音频
-- `hasReceivedAudio`: 是否已收到音频
-- `pendingCallbacks`: 待处理的回调数量
-- `hasController`: 是否有活跃的请求控制器
+- `hasReceivedAudio`: 是否已收到至少一条音频数据
 - `queueInfo`: 队列详细信息
   - `totalTasks`: 队列中的总任务数
   - `requestingTasks`: 正在发起SSE请求的任务数
@@ -875,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` 配置为新版本路径
+
 ## 🔧 高级功能
 
 ### 🎯 智能播报队列
@@ -969,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'
 });
@@ -978,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'
 });
@@ -1067,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');
@@ -1208,6 +1370,7 @@ document.addEventListener('visibilitychange', () => {
 | 3002 | `ResourceErrorCode.FILE_CORRUPTED` | 资源文件损坏 | 重新下载资源文件 |
 | 3003 | `ResourceErrorCode.NOT_FOUND` | 资源不存在 | 检查资源路径 |
 | 3004 | `ResourceErrorCode.UNSUPPORTED_FORMAT` | 资源格式不支持 | 使用支持的格式 |
+| 3005 | `ResourceErrorCode.VERSION_INCOMPATIBLE` | 资源版本不兼容 | 下载与SDK版本匹配的资源包（前两位版本号一致） |
 
 ### 系统错误 (4xxx)
 | 错误码 | 常量名 | 描述 | 处理建议 |
@@ -1384,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'
@@ -1393,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
@@ -1522,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
 // 检查资源可访问性
@@ -1534,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);
     }
   }
 }
@@ -1722,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.4",
+    "@zeewain/3d-avatar-sdk": "^2.1.1",
     "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.4",
+    "@zeewain/3d-avatar-sdk": "^2.1.1",
     "dayjs": "^1.11.13",
     "element-plus": "^2.10.4",
     "vite-plugin-html": "^3.2.2",

package/dist/examples/test-vue3/pnpm-lock.yaml

@@ -15,8 +15,8 @@ dependencies:
     specifier: ^13.5.0
     version: 13.5.0(vue@3.5.17)
   '@zeewain/3d-avatar-sdk':
-    specifier: ^1.2.3
-    version: 1.2.3
+    specifier: ^1.2.4
+    version: 1.2.4
   dayjs:
     specifier: ^1.11.13
     version: 1.11.13
@@ -1124,11 +1124,11 @@ packages:
       - vue
     dev: false
 
-  /@zeewain/3d-avatar-sdk@1.2.3:
-    resolution: {integrity: sha512-jI/ZaoIg+vMDYluxpzTSdG4Mthcv4WhGYQsjL5Kx39qyxf0wmIUVKf7d48tmoDuVr5PtdcCa7w6uLG3I6bjVQQ==}
+  /@zeewain/3d-avatar-sdk@1.2.4:
+    resolution: {integrity: sha512-a+y9HpUjbZgObzR+RfnfjxamdAa6Nk9CWkdHMejPIsYfSogCM6UtN/Jbh1A08RzIH9xrJnsUpTm1nXvvIsT6Vw==}
     dependencies:
       '@microsoft/fetch-event-source': 2.0.1
-      core-js: 3.44.0
+      core-js: 3.45.1
     dev: false
 
   /acorn-jsx@5.3.2(acorn@8.15.0):
@@ -1493,8 +1493,8 @@ packages:
     resolution: {integrity: sha512-9vAdYbHj6x2fLKC4+oPH0kFzY/orMZyG2Aj+kNylHxKGJ/Ed4dpNyAQYwJOdqO4zdM7XpVHmyejQDcQHrnuXbw==}
     dev: false
 
-  /core-js@3.44.0:
-    resolution: {integrity: sha512-aFCtd4l6GvAXwVEh3XbbVqJGHDJt0OZRa+5ePGx3LLwi12WfexqQxcsohb2wgsa/92xtl19Hd66G/L+TaAxDMw==}
+  /core-js@3.45.1:
+    resolution: {integrity: sha512-L4NPsJlCfZsPeXukyzHFlg/i7IIVwHSItR0wg0FLNqYClJ4MQYTYLbC7EkjKYRLZF2iof2MUgN0EGy7MdQFChg==}
     requiresBuild: true
     dev: false