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

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": "^2.1.1",
+    "@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-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": "^2.1.1",
+    "@zeewain/3d-avatar-sdk": "^2.1.2",
     "dayjs": "^1.11.13",
     "element-plus": "^2.10.4",
     "vite-plugin-html": "^3.2.2",

package/dist/index.d.ts

@@ -577,7 +577,7 @@ declare class ZEEAvatarSDK {
  * SDK 版本号
  * @const {string} SDK_VERSION
  */
-declare const SDK_VERSION = "2.1.1";
+declare const SDK_VERSION = "2.1.2";
 
 /**
  * Unity服务日志记录器接口
@@ -1048,7 +1048,7 @@ declare class BroadcastService extends UnityBaseService<BroadcastOperationType>
      * 处理任务错误
      * @param task - 播报任务
      * @param error - 错误对象
-     * @description 处理任务执行过程中的错误
+     * @description 处理任务执行过程中的错误，防止重复触发错误回调
      * @private
      */
     private handleTaskError;
@@ -1103,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;
 }
 
 /**

package/dist/index.es5.js

@@ -14210,7 +14210,7 @@ var ZEEAvatarSDKLib = (function (exports) {
 	   */
 	  BroadcastService.prototype.startTaskRequest = function (task) {
 	    return __awaiter(this, void 0, void 0, function () {
-	      var apiUrl, requestBody;
+	      var apiUrl, requestBody, sdkError;
 	      var _this = this;
 	      var _a;
 	      return __generator(this, function (_b) {
@@ -14245,6 +14245,25 @@ var ZEEAvatarSDKLib = (function (exports) {
 	            body: JSON.stringify(requestBody),
 	            signal: task.controller.signal,
 	            openWhenHidden: true,
+	            /**
+	             * 连接建立时的回调，用于检查 HTTP 状态码
+	             * @param response - HTTP 响应对象
+	             * @throws {SDKError} 当 HTTP 状态码异常时抛出对应的 SDKError
+	             */
+	            onopen: function onopen(response) {
+	              return __awaiter(_this, void 0, void 0, function () {
+	                var error;
+	                return __generator(this, function (_a) {
+	                  // 检查 HTTP 状态码，处理 401 token 过期等异常
+	                  if (!response.ok) {
+	                    error = this.createHttpError(response.status, response.statusText, task.id);
+	                    this.handleTaskError(task, error);
+	                    throw error;
+	                  }
+	                  return [2 /*return*/];
+	                });
+	              });
+	            },
 	            onmessage: function onmessage(event) {
 	              _this.handleTaskResponse(task, event.data);
 	            },
@@ -14252,12 +14271,15 @@ var ZEEAvatarSDKLib = (function (exports) {
 	              _this.handleTaskClose(task);
 	            },
 	            onerror: function onerror(error) {
-	              _this.handleTaskError(task, error);
-	              throw new Error("Task ".concat(task.id, " request failed: ").concat(error));
+	              // 将所有异常统一转换为 SDKError
+	              var sdkError = _this.convertToSDKError(error, task.id);
+	              _this.handleTaskError(task, sdkError);
+	              throw sdkError;
 	            }
 	          });
 	        } catch (error) {
-	          this.handleTaskError(task, error);
+	          sdkError = this.convertToSDKError(error, task.id);
+	          this.handleTaskError(task, sdkError);
 	        }
 	        return [2 /*return*/];
 	      });
@@ -14356,15 +14378,19 @@ var ZEEAvatarSDKLib = (function (exports) {
 	   * 处理任务错误
 	   * @param task - 播报任务
 	   * @param error - 错误对象
-	   * @description 处理任务执行过程中的错误
+	   * @description 处理任务执行过程中的错误，防止重复触发错误回调
 	   * @private
 	   */
 	  BroadcastService.prototype.handleTaskError = function (task, error) {
 	    var _a, _b;
+	    // 如果任务已经是失败或取消状态，不再重复处理，防止回调被多次触发
+	    if (task.status === BroadcastTaskStatus.FAILED || task.status === BroadcastTaskStatus.CANCELLED) {
+	      return;
+	    }
 	    task.status = BroadcastTaskStatus.FAILED;
 	    task.error = error;
 	    this.logger.error("Task failed - ".concat(task.id), error);
-	    // 触发错误回调
+	    // 触发错误回调（只触发一次）
 	    (_b = (_a = this.callbacks).onError) === null || _b === void 0 ? void 0 : _b.call(_a, error);
 	  };
 	  /**
@@ -14508,6 +14534,74 @@ var ZEEAvatarSDKLib = (function (exports) {
 	      this.queueProcessTimer = null;
 	    }
 	  };
+	  /**
+	   * 根据 HTTP 状态码创建对应的 SDKError
+	   * @param status - HTTP 状态码
+	   * @param statusText - HTTP 状态文本
+	   * @param taskId - 任务 ID（用于日志记录）
+	   * @returns SDKError 实例
+	   * @description 将 HTTP 错误状态码映射为对应的 SDKError
+	   * @private
+	   */
+	  BroadcastService.prototype.createHttpError = function (status, statusText, taskId) {
+	    this.logger.warn("HTTP error occurred - Task: ".concat(taskId, ", Status: ").concat(status), {
+	      status: status,
+	      statusText: statusText
+	    });
+	    switch (status) {
+	      case 401:
+	        // Token 过期或未授权
+	        return new SDKError(exports.NetworkErrorCode.UNAUTHORIZED, "Token \u5DF2\u8FC7\u671F\u6216\u65E0\u6548\uFF0C\u8BF7\u91CD\u65B0\u6388\u6743 (HTTP ".concat(status, ")"));
+	      case 403:
+	        // 禁止访问
+	        return new SDKError(exports.NetworkErrorCode.UNAUTHORIZED, "\u65E0\u6743\u9650\u8BBF\u95EE\u8BE5\u8D44\u6E90 (HTTP ".concat(status, ")"));
+	      case 404:
+	        // 资源不存在
+	        return new SDKError(exports.NetworkErrorCode.SERVER_ERROR, "\u8BF7\u6C42\u7684\u8D44\u6E90\u4E0D\u5B58\u5728 (HTTP ".concat(status, ")"));
+	      case 500:
+	      case 502:
+	      case 503:
+	      case 504:
+	        // 服务器错误
+	        return new SDKError(exports.NetworkErrorCode.SERVER_ERROR, "\u670D\u52A1\u5668\u9519\u8BEF\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5 (HTTP ".concat(status, ")"));
+	      default:
+	        // 其他 HTTP 错误
+	        return new SDKError(exports.NetworkErrorCode.CONNECTION_FAILED, "\u7F51\u7EDC\u8BF7\u6C42\u5931\u8D25: ".concat(statusText || 'Unknown Error', " (HTTP ").concat(status, ")"));
+	    }
+	  };
+	  /**
+	   * 将任意错误转换为 SDKError
+	   * @param error - 原始错误对象
+	   * @param taskId - 任务 ID（用于日志记录）
+	   * @returns SDKError 实例
+	   * @description 统一将各种类型的错误转换为 SDKError，便于上层统一处理
+	   * @private
+	   */
+	  BroadcastService.prototype.convertToSDKError = function (error, taskId) {
+	    // 如果已经是 SDKError，直接返回
+	    if (error instanceof SDKError) {
+	      return error;
+	    }
+	    // 如果是普通 Error 对象
+	    if (error instanceof Error) {
+	      // 检查是否是网络相关的错误
+	      var errorMessage_1 = error.message.toLowerCase();
+	      if (errorMessage_1.includes('timeout') || errorMessage_1.includes('timed out')) {
+	        return new SDKError(exports.NetworkErrorCode.REQUEST_TIMEOUT, "\u8BF7\u6C42\u8D85\u65F6 - Task: ".concat(taskId), error);
+	      }
+	      if (errorMessage_1.includes('network') || errorMessage_1.includes('fetch') || errorMessage_1.includes('connection')) {
+	        return new SDKError(exports.NetworkErrorCode.CONNECTION_FAILED, "\u7F51\u7EDC\u8FDE\u63A5\u5931\u8D25 - Task: ".concat(taskId, ": ").concat(error.message), error);
+	      }
+	      if (errorMessage_1.includes('abort') || errorMessage_1.includes('cancel')) {
+	        return new SDKError(exports.OperationErrorCode.OPERATION_CANCELLED, "\u64CD\u4F5C\u5DF2\u53D6\u6D88 - Task: ".concat(taskId), error);
+	      }
+	      // 默认作为操作失败处理
+	      return new SDKError(exports.OperationErrorCode.OPERATION_FAILED, "\u64AD\u62A5\u4EFB\u52A1\u6267\u884C\u5931\u8D25 - Task: ".concat(taskId, ": ").concat(error.message), error);
+	    }
+	    // 如果是字符串或其他类型
+	    var errorMessage = String(error);
+	    return new SDKError(exports.OperationErrorCode.OPERATION_FAILED, "\u64AD\u62A5\u4EFB\u52A1\u6267\u884C\u5931\u8D25 - Task: ".concat(taskId, ": ").concat(errorMessage));
+	  };
 	  return BroadcastService;
 	}(UnityBaseService);
 

package/dist/index.es5.umd.js

@@ -14213,7 +14213,7 @@
 	   */
 	  BroadcastService.prototype.startTaskRequest = function (task) {
 	    return __awaiter(this, void 0, void 0, function () {
-	      var apiUrl, requestBody;
+	      var apiUrl, requestBody, sdkError;
 	      var _this = this;
 	      var _a;
 	      return __generator(this, function (_b) {
@@ -14248,6 +14248,25 @@
 	            body: JSON.stringify(requestBody),
 	            signal: task.controller.signal,
 	            openWhenHidden: true,
+	            /**
+	             * 连接建立时的回调，用于检查 HTTP 状态码
+	             * @param response - HTTP 响应对象
+	             * @throws {SDKError} 当 HTTP 状态码异常时抛出对应的 SDKError
+	             */
+	            onopen: function onopen(response) {
+	              return __awaiter(_this, void 0, void 0, function () {
+	                var error;
+	                return __generator(this, function (_a) {
+	                  // 检查 HTTP 状态码，处理 401 token 过期等异常
+	                  if (!response.ok) {
+	                    error = this.createHttpError(response.status, response.statusText, task.id);
+	                    this.handleTaskError(task, error);
+	                    throw error;
+	                  }
+	                  return [2 /*return*/];
+	                });
+	              });
+	            },
 	            onmessage: function onmessage(event) {
 	              _this.handleTaskResponse(task, event.data);
 	            },
@@ -14255,12 +14274,15 @@
 	              _this.handleTaskClose(task);
 	            },
 	            onerror: function onerror(error) {
-	              _this.handleTaskError(task, error);
-	              throw new Error("Task ".concat(task.id, " request failed: ").concat(error));
+	              // 将所有异常统一转换为 SDKError
+	              var sdkError = _this.convertToSDKError(error, task.id);
+	              _this.handleTaskError(task, sdkError);
+	              throw sdkError;
 	            }
 	          });
 	        } catch (error) {
-	          this.handleTaskError(task, error);
+	          sdkError = this.convertToSDKError(error, task.id);
+	          this.handleTaskError(task, sdkError);
 	        }
 	        return [2 /*return*/];
 	      });
@@ -14359,15 +14381,19 @@
 	   * 处理任务错误
 	   * @param task - 播报任务
 	   * @param error - 错误对象
-	   * @description 处理任务执行过程中的错误
+	   * @description 处理任务执行过程中的错误，防止重复触发错误回调
 	   * @private
 	   */
 	  BroadcastService.prototype.handleTaskError = function (task, error) {
 	    var _a, _b;
+	    // 如果任务已经是失败或取消状态，不再重复处理，防止回调被多次触发
+	    if (task.status === BroadcastTaskStatus.FAILED || task.status === BroadcastTaskStatus.CANCELLED) {
+	      return;
+	    }
 	    task.status = BroadcastTaskStatus.FAILED;
 	    task.error = error;
 	    this.logger.error("Task failed - ".concat(task.id), error);
-	    // 触发错误回调
+	    // 触发错误回调（只触发一次）
 	    (_b = (_a = this.callbacks).onError) === null || _b === void 0 ? void 0 : _b.call(_a, error);
 	  };
 	  /**
@@ -14511,6 +14537,74 @@
 	      this.queueProcessTimer = null;
 	    }
 	  };
+	  /**
+	   * 根据 HTTP 状态码创建对应的 SDKError
+	   * @param status - HTTP 状态码
+	   * @param statusText - HTTP 状态文本
+	   * @param taskId - 任务 ID（用于日志记录）
+	   * @returns SDKError 实例
+	   * @description 将 HTTP 错误状态码映射为对应的 SDKError
+	   * @private
+	   */
+	  BroadcastService.prototype.createHttpError = function (status, statusText, taskId) {
+	    this.logger.warn("HTTP error occurred - Task: ".concat(taskId, ", Status: ").concat(status), {
+	      status: status,
+	      statusText: statusText
+	    });
+	    switch (status) {
+	      case 401:
+	        // Token 过期或未授权
+	        return new SDKError(exports.NetworkErrorCode.UNAUTHORIZED, "Token \u5DF2\u8FC7\u671F\u6216\u65E0\u6548\uFF0C\u8BF7\u91CD\u65B0\u6388\u6743 (HTTP ".concat(status, ")"));
+	      case 403:
+	        // 禁止访问
+	        return new SDKError(exports.NetworkErrorCode.UNAUTHORIZED, "\u65E0\u6743\u9650\u8BBF\u95EE\u8BE5\u8D44\u6E90 (HTTP ".concat(status, ")"));
+	      case 404:
+	        // 资源不存在
+	        return new SDKError(exports.NetworkErrorCode.SERVER_ERROR, "\u8BF7\u6C42\u7684\u8D44\u6E90\u4E0D\u5B58\u5728 (HTTP ".concat(status, ")"));
+	      case 500:
+	      case 502:
+	      case 503:
+	      case 504:
+	        // 服务器错误
+	        return new SDKError(exports.NetworkErrorCode.SERVER_ERROR, "\u670D\u52A1\u5668\u9519\u8BEF\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5 (HTTP ".concat(status, ")"));
+	      default:
+	        // 其他 HTTP 错误
+	        return new SDKError(exports.NetworkErrorCode.CONNECTION_FAILED, "\u7F51\u7EDC\u8BF7\u6C42\u5931\u8D25: ".concat(statusText || 'Unknown Error', " (HTTP ").concat(status, ")"));
+	    }
+	  };
+	  /**
+	   * 将任意错误转换为 SDKError
+	   * @param error - 原始错误对象
+	   * @param taskId - 任务 ID（用于日志记录）
+	   * @returns SDKError 实例
+	   * @description 统一将各种类型的错误转换为 SDKError，便于上层统一处理
+	   * @private
+	   */
+	  BroadcastService.prototype.convertToSDKError = function (error, taskId) {
+	    // 如果已经是 SDKError，直接返回
+	    if (error instanceof SDKError) {
+	      return error;
+	    }
+	    // 如果是普通 Error 对象
+	    if (error instanceof Error) {
+	      // 检查是否是网络相关的错误
+	      var errorMessage_1 = error.message.toLowerCase();
+	      if (errorMessage_1.includes('timeout') || errorMessage_1.includes('timed out')) {
+	        return new SDKError(exports.NetworkErrorCode.REQUEST_TIMEOUT, "\u8BF7\u6C42\u8D85\u65F6 - Task: ".concat(taskId), error);
+	      }
+	      if (errorMessage_1.includes('network') || errorMessage_1.includes('fetch') || errorMessage_1.includes('connection')) {
+	        return new SDKError(exports.NetworkErrorCode.CONNECTION_FAILED, "\u7F51\u7EDC\u8FDE\u63A5\u5931\u8D25 - Task: ".concat(taskId, ": ").concat(error.message), error);
+	      }
+	      if (errorMessage_1.includes('abort') || errorMessage_1.includes('cancel')) {
+	        return new SDKError(exports.OperationErrorCode.OPERATION_CANCELLED, "\u64CD\u4F5C\u5DF2\u53D6\u6D88 - Task: ".concat(taskId), error);
+	      }
+	      // 默认作为操作失败处理
+	      return new SDKError(exports.OperationErrorCode.OPERATION_FAILED, "\u64AD\u62A5\u4EFB\u52A1\u6267\u884C\u5931\u8D25 - Task: ".concat(taskId, ": ").concat(error.message), error);
+	    }
+	    // 如果是字符串或其他类型
+	    var errorMessage = String(error);
+	    return new SDKError(exports.OperationErrorCode.OPERATION_FAILED, "\u64AD\u62A5\u4EFB\u52A1\u6267\u884C\u5931\u8D25 - Task: ".concat(taskId, ": ").concat(errorMessage));
+	  };
 	  return BroadcastService;
 	}(UnityBaseService);
 

package/dist/index.esm.js

@@ -1915,6 +1915,19 @@ class BroadcastService extends UnityBaseService {
                     body: JSON.stringify(requestBody),
                     signal: task.controller.signal,
                     openWhenHidden: true,
+                    /**
+                     * 连接建立时的回调，用于检查 HTTP 状态码
+                     * @param response - HTTP 响应对象
+                     * @throws {SDKError} 当 HTTP 状态码异常时抛出对应的 SDKError
+                     */
+                    onopen: (response) => __awaiter(this, void 0, void 0, function* () {
+                        // 检查 HTTP 状态码，处理 401 token 过期等异常
+                        if (!response.ok) {
+                            const error = this.createHttpError(response.status, response.statusText, task.id);
+                            this.handleTaskError(task, error);
+                            throw error;
+                        }
+                    }),
                     onmessage: (event) => {
                         this.handleTaskResponse(task, event.data);
                     },
@@ -1922,13 +1935,17 @@ class BroadcastService extends UnityBaseService {
                         this.handleTaskClose(task);
                     },
                     onerror: (error) => {
-                        this.handleTaskError(task, error);
-                        throw new Error(`Task ${task.id} request failed: ${error}`);
+                        // 将所有异常统一转换为 SDKError
+                        const sdkError = this.convertToSDKError(error, task.id);
+                        this.handleTaskError(task, sdkError);
+                        throw sdkError;
                     }
                 });
             }
             catch (error) {
-                this.handleTaskError(task, error);
+                // 将所有异常统一转换为 SDKError
+                const sdkError = this.convertToSDKError(error, task.id);
+                this.handleTaskError(task, sdkError);
             }
         });
     }
@@ -2016,15 +2033,19 @@ class BroadcastService extends UnityBaseService {
      * 处理任务错误
      * @param task - 播报任务
      * @param error - 错误对象
-     * @description 处理任务执行过程中的错误
+     * @description 处理任务执行过程中的错误，防止重复触发错误回调
      * @private
      */
     handleTaskError(task, error) {
         var _a, _b;
+        // 如果任务已经是失败或取消状态，不再重复处理，防止回调被多次触发
+        if (task.status === BroadcastTaskStatus.FAILED || task.status === BroadcastTaskStatus.CANCELLED) {
+            return;
+        }
         task.status = BroadcastTaskStatus.FAILED;
         task.error = error;
         this.logger.error(`Task failed - ${task.id}`, error);
-        // 触发错误回调
+        // 触发错误回调（只触发一次）
         (_b = (_a = this.callbacks).onError) === null || _b === void 0 ? void 0 : _b.call(_a, error);
     }
     /**
@@ -2148,6 +2169,71 @@ class BroadcastService extends UnityBaseService {
             this.queueProcessTimer = null;
         }
     }
+    /**
+     * 根据 HTTP 状态码创建对应的 SDKError
+     * @param status - HTTP 状态码
+     * @param statusText - HTTP 状态文本
+     * @param taskId - 任务 ID（用于日志记录）
+     * @returns SDKError 实例
+     * @description 将 HTTP 错误状态码映射为对应的 SDKError
+     * @private
+     */
+    createHttpError(status, statusText, taskId) {
+        this.logger.warn(`HTTP error occurred - Task: ${taskId}, Status: ${status}`, { status, statusText });
+        switch (status) {
+            case 401:
+                // Token 过期或未授权
+                return new SDKError(NetworkErrorCode.UNAUTHORIZED, `Token 已过期或无效，请重新授权 (HTTP ${status})`);
+            case 403:
+                // 禁止访问
+                return new SDKError(NetworkErrorCode.UNAUTHORIZED, `无权限访问该资源 (HTTP ${status})`);
+            case 404:
+                // 资源不存在
+                return new SDKError(NetworkErrorCode.SERVER_ERROR, `请求的资源不存在 (HTTP ${status})`);
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                // 服务器错误
+                return new SDKError(NetworkErrorCode.SERVER_ERROR, `服务器错误，请稍后重试 (HTTP ${status})`);
+            default:
+                // 其他 HTTP 错误
+                return new SDKError(NetworkErrorCode.CONNECTION_FAILED, `网络请求失败: ${statusText || 'Unknown Error'} (HTTP ${status})`);
+        }
+    }
+    /**
+     * 将任意错误转换为 SDKError
+     * @param error - 原始错误对象
+     * @param taskId - 任务 ID（用于日志记录）
+     * @returns SDKError 实例
+     * @description 统一将各种类型的错误转换为 SDKError，便于上层统一处理
+     * @private
+     */
+    convertToSDKError(error, taskId) {
+        // 如果已经是 SDKError，直接返回
+        if (error instanceof SDKError) {
+            return error;
+        }
+        // 如果是普通 Error 对象
+        if (error instanceof Error) {
+            // 检查是否是网络相关的错误
+            const errorMessage = error.message.toLowerCase();
+            if (errorMessage.includes('timeout') || errorMessage.includes('timed out')) {
+                return new SDKError(NetworkErrorCode.REQUEST_TIMEOUT, `请求超时 - Task: ${taskId}`, error);
+            }
+            if (errorMessage.includes('network') || errorMessage.includes('fetch') || errorMessage.includes('connection')) {
+                return new SDKError(NetworkErrorCode.CONNECTION_FAILED, `网络连接失败 - Task: ${taskId}: ${error.message}`, error);
+            }
+            if (errorMessage.includes('abort') || errorMessage.includes('cancel')) {
+                return new SDKError(OperationErrorCode.OPERATION_CANCELLED, `操作已取消 - Task: ${taskId}`, error);
+            }
+            // 默认作为操作失败处理
+            return new SDKError(OperationErrorCode.OPERATION_FAILED, `播报任务执行失败 - Task: ${taskId}: ${error.message}`, error);
+        }
+        // 如果是字符串或其他类型
+        const errorMessage = String(error);
+        return new SDKError(OperationErrorCode.OPERATION_FAILED, `播报任务执行失败 - Task: ${taskId}: ${errorMessage}`);
+    }
 }
 
 /**
@@ -2325,7 +2411,7 @@ function compareVersionCompatibility(version1, version2) {
  * SDK 版本号
  * @const {string} SDK_VERSION
  */
-const SDK_VERSION = '2.1.1';
+const SDK_VERSION = '2.1.2';
 
 /**
  * @fileoverview 统一的3D数字人SDK入口类

package/dist/index.umd.cjs

@@ -1921,6 +1921,19 @@
                         body: JSON.stringify(requestBody),
                         signal: task.controller.signal,
                         openWhenHidden: true,
+                        /**
+                         * 连接建立时的回调，用于检查 HTTP 状态码
+                         * @param response - HTTP 响应对象
+                         * @throws {SDKError} 当 HTTP 状态码异常时抛出对应的 SDKError
+                         */
+                        onopen: (response) => __awaiter(this, void 0, void 0, function* () {
+                            // 检查 HTTP 状态码，处理 401 token 过期等异常
+                            if (!response.ok) {
+                                const error = this.createHttpError(response.status, response.statusText, task.id);
+                                this.handleTaskError(task, error);
+                                throw error;
+                            }
+                        }),
                         onmessage: (event) => {
                             this.handleTaskResponse(task, event.data);
                         },
@@ -1928,13 +1941,17 @@
                             this.handleTaskClose(task);
                         },
                         onerror: (error) => {
-                            this.handleTaskError(task, error);
-                            throw new Error(`Task ${task.id} request failed: ${error}`);
+                            // 将所有异常统一转换为 SDKError
+                            const sdkError = this.convertToSDKError(error, task.id);
+                            this.handleTaskError(task, sdkError);
+                            throw sdkError;
                         }
                     });
                 }
                 catch (error) {
-                    this.handleTaskError(task, error);
+                    // 将所有异常统一转换为 SDKError
+                    const sdkError = this.convertToSDKError(error, task.id);
+                    this.handleTaskError(task, sdkError);
                 }
             });
         }
@@ -2022,15 +2039,19 @@
          * 处理任务错误
          * @param task - 播报任务
          * @param error - 错误对象
-         * @description 处理任务执行过程中的错误
+         * @description 处理任务执行过程中的错误，防止重复触发错误回调
          * @private
          */
         handleTaskError(task, error) {
             var _a, _b;
+            // 如果任务已经是失败或取消状态，不再重复处理，防止回调被多次触发
+            if (task.status === BroadcastTaskStatus.FAILED || task.status === BroadcastTaskStatus.CANCELLED) {
+                return;
+            }
             task.status = BroadcastTaskStatus.FAILED;
             task.error = error;
             this.logger.error(`Task failed - ${task.id}`, error);
-            // 触发错误回调
+            // 触发错误回调（只触发一次）
             (_b = (_a = this.callbacks).onError) === null || _b === void 0 ? void 0 : _b.call(_a, error);
         }
         /**
@@ -2154,6 +2175,71 @@
                 this.queueProcessTimer = null;
             }
         }
+        /**
+         * 根据 HTTP 状态码创建对应的 SDKError
+         * @param status - HTTP 状态码
+         * @param statusText - HTTP 状态文本
+         * @param taskId - 任务 ID（用于日志记录）
+         * @returns SDKError 实例
+         * @description 将 HTTP 错误状态码映射为对应的 SDKError
+         * @private
+         */
+        createHttpError(status, statusText, taskId) {
+            this.logger.warn(`HTTP error occurred - Task: ${taskId}, Status: ${status}`, { status, statusText });
+            switch (status) {
+                case 401:
+                    // Token 过期或未授权
+                    return new SDKError(exports.NetworkErrorCode.UNAUTHORIZED, `Token 已过期或无效，请重新授权 (HTTP ${status})`);
+                case 403:
+                    // 禁止访问
+                    return new SDKError(exports.NetworkErrorCode.UNAUTHORIZED, `无权限访问该资源 (HTTP ${status})`);
+                case 404:
+                    // 资源不存在
+                    return new SDKError(exports.NetworkErrorCode.SERVER_ERROR, `请求的资源不存在 (HTTP ${status})`);
+                case 500:
+                case 502:
+                case 503:
+                case 504:
+                    // 服务器错误
+                    return new SDKError(exports.NetworkErrorCode.SERVER_ERROR, `服务器错误，请稍后重试 (HTTP ${status})`);
+                default:
+                    // 其他 HTTP 错误
+                    return new SDKError(exports.NetworkErrorCode.CONNECTION_FAILED, `网络请求失败: ${statusText || 'Unknown Error'} (HTTP ${status})`);
+            }
+        }
+        /**
+         * 将任意错误转换为 SDKError
+         * @param error - 原始错误对象
+         * @param taskId - 任务 ID（用于日志记录）
+         * @returns SDKError 实例
+         * @description 统一将各种类型的错误转换为 SDKError，便于上层统一处理
+         * @private
+         */
+        convertToSDKError(error, taskId) {
+            // 如果已经是 SDKError，直接返回
+            if (error instanceof SDKError) {
+                return error;
+            }
+            // 如果是普通 Error 对象
+            if (error instanceof Error) {
+                // 检查是否是网络相关的错误
+                const errorMessage = error.message.toLowerCase();
+                if (errorMessage.includes('timeout') || errorMessage.includes('timed out')) {
+                    return new SDKError(exports.NetworkErrorCode.REQUEST_TIMEOUT, `请求超时 - Task: ${taskId}`, error);
+                }
+                if (errorMessage.includes('network') || errorMessage.includes('fetch') || errorMessage.includes('connection')) {
+                    return new SDKError(exports.NetworkErrorCode.CONNECTION_FAILED, `网络连接失败 - Task: ${taskId}: ${error.message}`, error);
+                }
+                if (errorMessage.includes('abort') || errorMessage.includes('cancel')) {
+                    return new SDKError(exports.OperationErrorCode.OPERATION_CANCELLED, `操作已取消 - Task: ${taskId}`, error);
+                }
+                // 默认作为操作失败处理
+                return new SDKError(exports.OperationErrorCode.OPERATION_FAILED, `播报任务执行失败 - Task: ${taskId}: ${error.message}`, error);
+            }
+            // 如果是字符串或其他类型
+            const errorMessage = String(error);
+            return new SDKError(exports.OperationErrorCode.OPERATION_FAILED, `播报任务执行失败 - Task: ${taskId}: ${errorMessage}`);
+        }
     }
 
     /**
@@ -2331,7 +2417,7 @@
      * SDK 版本号
      * @const {string} SDK_VERSION
      */
-    const SDK_VERSION = '2.1.1';
+    const SDK_VERSION = '2.1.2';
 
     /**
      * @fileoverview 统一的3D数字人SDK入口类

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zeewain/3d-avatar-sdk",
   "type": "module",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "SDK for ZEE Avatar WebGL integration",
   "author": "ZEEWain",
   "license": "MIT",