@xmov/avatar 2.0.0-beta.14 → 2.0.0-beta.16

package/dist/utils/request.d.ts

@@ -14,6 +14,7 @@ export declare function XMLRequest(options: {
     cache?: {
         enable: boolean;
     };
+    timeout?: number;
     onProgress: (progress: number, e: ProgressEvent) => void;
 }): Promise<[boolean, ArrayBuffer | string]>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmov/avatar",
-  "version": "2.0.0-beta.14",
+  "version": "2.0.0-beta.16",
   "description": "魔珐数字人 JS-SDK",
   "type": "module",
   "source": "src/index.ts",
@@ -26,8 +26,10 @@
     "src/"
   ],
   "scripts": {
-    "build": "microbundle --workers --define ENV=production,VERSION=$npm_package_version --external none --tsconfig tsconfig.json && pnpm run build:agent && node upload-sdk.js build",
+    "build": "pnpm run build:core && pnpm run build:agent && pnpm run build:e2e:cdn && pnpm run test:e2e:cdn && node upload-sdk.js build",
+    "build:core": "microbundle --workers --define ENV=production,VERSION=$npm_package_version --external none --tsconfig tsconfig.json",
     "build:agent": "microbundle --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json && node scripts/build-agent-entry.mjs",
+    "build:e2e:cdn": "microbundle --entry src/agent/cdn-entry.ts --output cdn-dist/xmovAvatar_e2e.js --format iife --external none --workers --define ENV=production,VERSION=$npm_package_version --tsconfig tsconfig.agent.json --no-pkg-main --no-sourcemap",
     "sdk": "pnpm --filter @xmov/avatar run --parallel --no-bail \"/^sdk:.+$/\"",
     "sdk:core": "microbundle watch --workers --define ENV=development,VERSION=$npm_package_version --external none --tsconfig tsconfig.json",
     "sdk:agent": "node scripts/build-agent-entry.mjs && microbundle watch --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json",
@@ -36,7 +38,8 @@
     "test:agent": "node scripts/run-agent-tests.mjs",
     "test:agent:exports": "pnpm run build:agent && node scripts/test-agent-package-exports.mjs",
     "test:agent:browser": "playwright test",
-    "lite": "node replaceString.js && npm run build && node upload-sdk.js lite",
+    "test:e2e:cdn": "node scripts/test-e2e-cdn-build.mjs",
+    "lite": "node replaceString.js && pnpm run build:core && node upload-sdk.js lite",
     "proto": "pbjs -t static-module -w closure -o src/proto/face_data_pb.js src/proto/face_data.proto",
     "commitlint": "commitlint --edit",
     "prepare": "husky"

package/src/agent/cdn-entry.ts

@@ -0,0 +1,15 @@
+import XingyunAvatarAgent, {
+  AgentE2EClient,
+  DEFAULT_AGENT_AUDIO,
+  MicrophoneController,
+} from "./index";
+
+Object.assign(XingyunAvatarAgent, {
+  AgentE2EClient,
+  DEFAULT_AGENT_AUDIO,
+  MicrophoneController,
+});
+
+(globalThis as typeof globalThis & {
+  XingyunAvatarAgent: typeof XingyunAvatarAgent;
+}).XingyunAvatarAgent = XingyunAvatarAgent;

package/src/control/RenderScheduler.ts

@@ -840,6 +840,21 @@ export default class RenderScheduler {
     }])
   }
 
+  /**
+   * 重连成功恢复（含窗口内 socket.io 自动重连恢复、窗口外重开房间）：
+   * 数据缓存在断网进入离线时已清空（_offlineMode/_offlineRun），此处仅恢复播放状态：
+   * - 标记帧号对齐：首个 BODY/AUDIO 数据到达时按 sf 重设帧时钟
+   * - 恢复音频播放
+   * - 解码器退出离线模式（重置 _offlineLastFrame、清空离线队列）
+   * 避免离线 idle 播放推进的帧号领先服务端续推数据导致人物卡死、音画不同步
+   */
+  markReconnectRecover() {
+    // 恢复音频播放
+    this.audioRenderer.resume();
+    // 解码器退出离线模式（重置 _offlineLastFrame、清空离线队列）
+    this.decoder._reload();
+  }
+
   _offlineMode() {
     this.dataCacheQueue._clearEvent();
     const currentFrame = this.getCurrentFrameIndex() ?? 0;

package/src/control/ttsa.ts

@@ -55,6 +55,7 @@ interface ITtsaOptions {
   enterOfflineMode: () => void;
   reStartSDK: () => void;
   reconnect_client_timeout: number;
+  reconnect_timeout: number;
   sendVoiceEnd: () => void;
   getCurrentFrameIndex: () => number;
 }
@@ -77,7 +78,9 @@ export default class Ttsa {
   private enterOfflineMode: () => void;
   private reStartSDK: () => void;
   private reconnect_client_timeout: number;
-  private reconnectTimer = -1;
+  private reconnect_timeout: number;
+  private reconnectTimer = -1;          // 重开房间定时器（reconnect_client_timeout 后 stopSession + reStartSDK）
+  private socketReconnectTimer = -1;    // 停止 socket.io 自动重连定时器（reconnect_timeout 后旧房间已失效）
   private wsConnectTimer = 0;
   private enterOfflineFlag = false;
   private sendVoiceEnd: () => void;
@@ -94,13 +97,26 @@ export default class Ttsa {
   private readonly HEARTBEAT_INTERVAL = 2000;
 
   /**
-   * 清除WebSocket重连定时器
+   * 清除WebSocket重连定时器（含停止 socket.io 自动重连的定时器）
    */
   public clearReconnectTimer(): void {
     if (this.reconnectTimer !== -1) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = -1;
     }
+    // 一并清理停止 socket.io 自动重连的定时器：网络恢复后交由 socket.io 自行重连，
+    // 不再强制断开（下次 disconnect 会重新按窗口设置）
+    this.clearSocketReconnectTimer();
+  }
+
+  /**
+   * 清除停止 socket.io 自动重连的定时器
+   */
+  private clearSocketReconnectTimer(): void {
+    if (this.socketReconnectTimer !== -1) {
+      clearTimeout(this.socketReconnectTimer);
+      this.socketReconnectTimer = -1;
+    }
   }
 
   /**
@@ -146,6 +162,7 @@ export default class Ttsa {
     this.enterOfflineMode = options.enterOfflineMode;
     this.reStartSDK = options.reStartSDK;
     this.reconnect_client_timeout = options.reconnect_client_timeout;
+    this.reconnect_timeout = options.reconnect_timeout;
     this.sendVoiceEnd = options.sendVoiceEnd;
     this.getCurrentFrameIndex = options.getCurrentFrameIndex;
 
@@ -154,6 +171,9 @@ export default class Ttsa {
         token: this.token,
       },
       transports: ['websocket'],
+      // 自动重连不限制次数：在 reconnect_timeout（服务端断开旧房间的窗口）内持续尝试，
+      // 失效房间必然重连失败；超过窗口由 disconnect 处理器中的停止定时器断开，
+      // 超过 reconnect_client_timeout 由重开房间定时器兜底（stopSession + reStartSDK）
       reconnection: true,
       reconnectionAttempts: Infinity,
       reconnectionDelay: 1000,
@@ -167,17 +187,21 @@ export default class Ttsa {
       this.initWsTimeoutTimer();
       // 启动客户端心跳
       this.startHeartbeat();
+      // 重置离线处理标志：重连成功后允许下次断网正常进入离线/重连流程
+      this.enterOfflineFlag = false;
       (window as any).performanceTracker.markEnd(performanceConstant.ttsa_connect);
       const payload = {
         room: this.room,
         client_type: "web",
         invisible_mode: this.sdk.getPendingInvisibleMode(),
       };
-      // TODO: 临时处理，待后端修复
-      if(this.sdk.getStatus()=== AvatarStatus.offline) {
-        this.sdk.onStatusChange(AvatarStatus.online);
-      }
       this.send("enter_room", payload);
+      // 窗口内自动重连恢复：服务端可能不重发 first_start_timestamp，
+      // 若仅依赖 reloadSuccess 补发 online/恢复播放，状态会卡在离线导致重连后卡死。
+      // 因此重连成功即恢复（仅初始化完成且此前已离线时；初次启动 status 为 -1 不受影响）
+      if (this.sdk.getStatus() === AvatarStatus.offline && this.sdk.getIsInitialized()) {
+        this.reloadSuccess();
+      }
     });
     ws.on("first_start_timestamp", (e: any) => {
       (window as any).avatarSDKLogger.log(this.TAG, "first_start_timestamp", e);
@@ -339,11 +363,23 @@ export default class Ttsa {
         // 无网断开则进入离线模式
         this.enterOfflineMode();
       }
-      // 发起定时器，getReconnectClientTimeout时间内重连socket，超过时间则发起reStartSession
-      // 只有在网络断开时才设置重连定时器，网络恢复时由NetworkMonitor处理
-      if (!navigator.onLine) {
-        // 清除可能存在的旧定时器
-        this.clearReconnectTimer();
+      // 重连窗口策略（不再依赖 navigator.onLine，socket 断开即启动）：
+      // ① socketReconnectTimer（reconnect_timeout）：窗口内 socket.io 自动重连；
+      //    服务端会在 reconnect_timeout 后断开旧房间，因此窗口结束即停止无谓的自动重连
+      // ② reconnectTimer（reconnect_client_timeout）：仍未能重连则停止旧连接并重开房间
+      // 均仅首次设置，避免 socket.io 重连失败反复触发 disconnect 重置定时器导致永不执行；
+      // 重连成功时 connect 处理器、网络恢复时 NetworkMonitor -> clearReconnectTimer 都会取消
+      if (this.socketReconnectTimer === -1 && this.reconnect_timeout > 0) {
+        this.socketReconnectTimer = window.setTimeout(() => {
+          try {
+            ws.disconnect();
+          } catch (error) {
+            (window as any).avatarSDKLogger.warn(this.TAG, "disconnect error", error);
+          }
+          this.socketReconnectTimer = -1;
+        }, this.reconnect_timeout * 1000);
+      }
+      if (this.reconnectTimer === -1) {
         this.reconnectTimer = window.setTimeout(async () => {
           try {
             ws.disconnect();

package/src/index.ts

@@ -104,7 +104,6 @@ export default class XmovAvatar {
   private pcmCaptureMode: 'webcodec' | 'mediarecorder' | 'none' = 'none';
   private pcmEncodeId: number = 0; // 用于 reset 竞态检测，递增标识当前编码会话
 
-  private reconnectDebounceTimer = -1; // 重连防抖定时器
   private networkInfo: any = {
     rtt: 0,
     downlink: 0.0,
@@ -200,6 +199,14 @@ export default class XmovAvatar {
     return this.status
   }
 
+  /**
+   * 初始化是否完成（progress === 100）
+   * 供 TTSA 重连恢复时判断是否可提前恢复在线状态
+   */
+  public getIsInitialized() {
+    return this.isInitialized
+  }
+
   public get businessENV() {
     return this._env
   }
@@ -294,6 +301,10 @@ export default class XmovAvatar {
         // 标记初始化完成
         this.isInitialized = progress === 100;
         if(progress === 100) {
+          // 初始化完成：若 start 时因未初始化完成而未上线（状态守卫），此处补发 online
+          if (!this.pendingInvisibleMode && this.status !== AvatarStatus.online && this.status !== AvatarStatus.invisible) {
+            this.onStatusChange(AvatarStatus.online);
+          }
           this.resourceManager._setOfflineCache();
           this.ttsa?.sendSdkPoint('loadvideo_decode_time', {
             timestamp: Date.now(),
@@ -1103,6 +1114,7 @@ export default class XmovAvatar {
       token: sessionInfo.token,
       framedata_proto_version: this.resourceManager.getConfig().framedata_proto_version,
       reconnect_client_timeout: sessionInfo?.reconnect_client_timeout || 0,
+      reconnect_timeout: sessionInfo?.reconnect_timeout || 0,
       appInfo: {
         ...this.resourceManager.getAppInfo(),
         env: this._env
@@ -1111,7 +1123,7 @@ export default class XmovAvatar {
         this.ttsa?.sendSdkPoint('connect_sdk', {
           timestamp: this.startConnectTime,
         });
-        this.onDownloadProgress?.(85);
+        // 不再强行上报 85：进度以真实资源下载为准，避免重连时 UI 进度被错误拉低
         this.ttsa?.sendSdkPoint('connect_sdk_success', {
           timestamp: this.connectSuccessTime,
         });
@@ -1165,16 +1177,18 @@ export default class XmovAvatar {
   }
 
   protected start() {
-    this.renderScheduler.render();
-    this.ttsa?.start();
-    
-    // 如果初始化时设置了隐身模式，则立即进入隐身状态
+    // 先发布在线状态，再启动渲染：
+    // 避免先 render() 触发 rendering -> visible(5) 后再发 online(0)，造成 0/5 状态横跳
     if (this.pendingInvisibleMode) {
       this.pendingInvisibleMode = false;
       this.setInvisibleMode()
-    } else {
+    } else if (this.isInitialized) {
+      // 状态守卫：仅在初始化完成（progress === 100）时上线，
+      // 避免重连重建房间过程中（资源未下载完）反复触发 online -> visible 状态横跳
       this.onStatusChange(AvatarStatus.online);
     }
+    this.renderScheduler.render();
+    this.ttsa?.start();
     
   }
 
@@ -1221,7 +1235,14 @@ export default class XmovAvatar {
   }
 
   reloadSuccess() {
-    this.onStatusChange(AvatarStatus.online);
+    // 重连成功恢复：恢复音频、重置解码器离线状态、清空旧数据缓存，并按首个数据 sf 对齐帧号，
+    // 解决窗口内自动重连恢复后人物卡死（帧号错位数据被过滤）、无声音/音画不同步的问题
+    this.renderScheduler?.markReconnectRecover();
+    // 状态守卫：仅初始化完成时上线；未完成时由 onDownloadProgress(100) 补发，
+    // 避免重连重建房间过程中初始化未完成却提前进入 online
+    if (this.isInitialized) {
+      this.onStatusChange(AvatarStatus.online);
+    }
     setTimeout(() => {
       window.clearInterval(this._offlineTimer)
     }, 1000)
@@ -1636,28 +1657,13 @@ export default class XmovAvatar {
   }
 
   private triggerReconnect() {
-    // 如果已经在重连中，直接返回，避免重复触发
-    if (this.isRetrying) {
-      (window as any).avatarSDKLogger.warn(this.TAG, "正在重连中，跳过本次触发");
-      return;
-    }
-
-    if (this.reconnectDebounceTimer !== -1) {
-      clearTimeout(this.reconnectDebounceTimer);
-      this.reconnectDebounceTimer = -1;
-    }
-    if (this.retryTimer !== -1) {
-      clearTimeout(this.retryTimer);
-      this.retryTimer = -1;
-    }
-
-    this.reconnectDebounceTimer = window.setTimeout(() => {
-      this.isRetrying = false;
-      this.retryCount = 1;
-      this.retryRound = 1;
-      this.reStartSession();
-      this.reconnectDebounceTimer = -1;
-    }, 100);
+    // 网络恢复触发：无论是否正在退避重试，都取消挂起的重试定时器并立即重连（重开房间），
+    // 避免网络恢复后仍需等待当前退避窗口（最长 32s）才重连
+    this.clearAllRetryTimers();
+    this.isRetrying = false;
+    this.retryCount = 1;
+    this.retryRound = 1;
+    this.reStartSession();
   }
 
   reStartSession() {
@@ -1683,8 +1689,9 @@ export default class XmovAvatar {
       delay = Math.pow(2, this.retryCount) * 1000;
     }
 
-    // 使用setTimeout代替递归，避免调用栈溢出
-    setTimeout(async () => {
+    // 使用setTimeout代替递归，避免调用栈溢出；记录句柄以便网络恢复时取消挂起的退避重试
+    this.retryTimer = window.setTimeout(async () => {
+      this.retryTimer = -1;
       if (!this.isRetrying || this.destroyed) {
         return;
       }
@@ -1759,12 +1766,7 @@ export default class XmovAvatar {
     }, delay);
   }
   private clearAllRetryTimers() {
-    // 清理重连防抖定时器
-    if (this.reconnectDebounceTimer !== -1) {
-      clearTimeout(this.reconnectDebounceTimer);
-      this.reconnectDebounceTimer = -1;
-    }
-    // 清理重试定时器
+    // 清理重试定时器（含退避重试挂起的定时器）
     if (this.retryTimer !== -1) {
       clearTimeout(this.retryTimer);
       this.retryTimer = -1;

package/src/utils/request.ts

@@ -70,20 +70,32 @@ export function XMLRequest(options: {
   cache?: {
     enable: boolean
   }
+  timeout?: number
   onProgress: (progress: number, e: ProgressEvent) => void
 }): Promise<[boolean, ArrayBuffer | string]> {
   return new Promise((resolve, reject) => {
     const xhr = new XMLHttpRequest();
     xhr.open('GET', options.url);
     xhr.responseType = 'arraybuffer';
+    // 超时兜底：断网/请求挂起时不再永久等待（默认 60s，资源下载可能超时失败）
+    xhr.timeout = options.timeout ?? 60000;
     xhr.onload = function() {
       if (xhr.readyState === 4 && xhr.status === 200) {
         const arrayBuffer = xhr.response;
         resolve([false, arrayBuffer]);
-      } else if (xhr.status !== 200) {
-        reject([true, xhr.statusText]);
+      } else {
+        reject([true, `HTTP ${xhr.status} ${xhr.statusText}`]);
       }
     };
+    xhr.onerror = function() {
+      reject([true, 'network error']);
+    };
+    xhr.ontimeout = function() {
+      reject([true, `timeout after ${xhr.timeout}ms`]);
+    };
+    xhr.onabort = function() {
+      reject([true, 'aborted']);
+    };
     xhr.onprogress = (e) => {
       if (e.lengthComputable) {
         const percent = Math.round((e.loaded / e.total) * 100);