@xmov/avatar 2.0.0-alpha.52 → 2.0.0-alpha.54

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-alpha.52",
+  "version": "2.0.0-alpha.54",
   "description": "魔珐数字人 JS-SDK",
   "type": "module",
   "source": "src/index.ts",
@@ -10,12 +10,19 @@
       "default": "./dist/index.modern.js"
     },
     "./agent": {
-      "types": "./src/agent/index.ts",
+      "types": "./dist/agent/index.d.ts",
       "require": "./dist/agent/index.cjs",
       "default": "./dist/agent/avatar.modern.js"
     },
     "./agent/umd": "./dist/agent/index.umd.js"
   },
+  "typesVersions": {
+    "*": {
+      "agent": [
+        "dist/agent/index.d.ts"
+      ]
+    }
+  },
   "amdName": "XmovAvatar",
   "main": "./dist/index.cjs",
   "types": "./dist/index.d.ts",

package/src/agent/__tests__/agent.test.ts

@@ -2153,10 +2153,17 @@ test("XingyunAvatarAgent rejects ambiguous non-empty config sources", () => {
   );
 });
 
-test("XingyunAvatarAgent extends XmovAvatar and preserves base speak", async () => {
+test("XingyunAvatarAgent extends XmovAvatar while keeping the base class behavior unchanged", async () => {
   MockWebSocket.instances = [];
   const { agent } = createAgent();
   const XmovAvatar = require("../../index");
+  const avatar = new XmovAvatar({});
+
+  avatar.speak("legacy TTSA speak");
+  const interruptedSpeechId = avatar.interrupt("speak");
+  assert.deepEqual(avatar.speeches, [["legacy TTSA speak"]]);
+  assert.deepEqual(avatar.interrupts, ["speak"]);
+  assert.equal(interruptedSpeechId, 1);
 
   await agent.init();
   const ws = MockWebSocket.instances[0];
@@ -2167,11 +2174,6 @@ test("XingyunAvatarAgent extends XmovAvatar and preserves base speak", async ()
 
   agent.start();
   assert.equal(agent.startCalls, 1);
-  agent.speak("legacy TTSA speak");
-  assert.deepEqual(agent.speeches, [["legacy TTSA speak"]]);
-  assert.deepEqual(ws.sent, []);
-  agent.avatarOptions.onVoiceStateChange("end");
-  assert.deepEqual(ws.sent, []);
 });
 
 test("XingyunAvatarAgent restarts TTSA after same-session ready without leaving stopped state", async () => {
@@ -2200,7 +2202,7 @@ test("XingyunAvatarAgent ignores an explicit start while init is pending", () =>
   assert.equal(agent.started, false);
 });
 
-test("XingyunAvatarAgent sends frozen ask and speak payloads without client IDs or providers", async () => {
+test("XingyunAvatarAgent sends frozen ask and canonical speak payloads without client IDs or providers", async () => {
   MockWebSocket.instances = [];
   const conversations = [];
   const { agent } = createAgent({
@@ -2215,15 +2217,34 @@ test("XingyunAvatarAgent sends frozen ask and speak payloads without client IDs
   assert.deepEqual(askPayload, { type: "ask", message: { text: "hello" } });
   assert.deepEqual(conversations.at(-1), { state: "asking", text: "hello" });
 
-  await agent.speakByE2E("welcome");
+  const speakResult = agent.speak("welcome");
+  assert.equal(speakResult, undefined);
   const speakPayload = JSON.parse(ws.sent.at(-1));
   assert.deepEqual(speakPayload, {
     type: "speak",
     message: { text: "welcome", is_start: true, is_end: true },
   });
+  assert.deepEqual(conversations.at(-1), { state: "speaking-directly", text: "welcome" });
+
+  const e2eSentCount = ws.sent.length;
+  const replayExtra = { client_speak_id: "replay", client_frame: 7 };
+  const replayResult = agent.speak("<speak>replay</speak>", false, true, replayExtra);
+  assert.equal(replayResult, undefined);
+  assert.deepEqual(agent.speeches.at(-1), ["<speak>replay</speak>", false, true, replayExtra]);
+  assert.equal(ws.sent.length, e2eSentCount);
+  agent.avatarOptions.onVoiceStateChange("end", 1200);
+  assert.equal(ws.sent.length, e2eSentCount);
+
+  const sentCount = ws.sent.length;
+  await agent.speakByE2E("deprecated welcome");
+  assert.equal(ws.sent.length, sentCount + 1);
+  assert.deepEqual(JSON.parse(ws.sent.at(-1)), {
+    type: "speak",
+    message: { text: "deprecated welcome", is_start: true, is_end: true },
+  });
 });
 
-test("XingyunAvatarAgent interrupts E2E and local playback without client IDs", async () => {
+test("XingyunAvatarAgent interrupts E2E and local playback through canonical and deprecated methods", async () => {
   MockWebSocket.instances = [];
   const { agent } = createAgent();
 
@@ -2231,9 +2252,16 @@ test("XingyunAvatarAgent interrupts E2E and local playback without client IDs",
   const ws = MockWebSocket.instances[0];
   await agent.ask("cancel me");
 
-  await agent.interruptConversation("user");
+  const interruptResult = agent.interrupt();
+  assert.equal(interruptResult, 1);
   assert.deepEqual(agent.interrupts, ["speak"]);
   assert.deepEqual(JSON.parse(ws.sent.at(-1)), { type: "interrupt" });
+
+  const sentCount = ws.sent.length;
+  await agent.interruptConversation("user");
+  assert.equal(ws.sent.length, sentCount + 1);
+  assert.deepEqual(agent.interrupts, ["speak", "speak"]);
+  assert.deepEqual(JSON.parse(ws.sent.at(-1)), { type: "interrupt" });
 });
 
 test("XingyunAvatarAgent keeps ASR listening when interrupting a conversation", async () => {
@@ -2248,7 +2276,7 @@ test("XingyunAvatarAgent keeps ASR listening when interrupting a conversation",
     const recorder = browser.recorders[0];
     ws.sent = [];
 
-    await agent.interruptConversation("user");
+    agent.interrupt();
     const audioAfterInterrupt = new Blob(["audio-after-interrupt"], {
       type: "audio/webm;codecs=opus",
     });

package/src/agent/index.ts

@@ -262,7 +262,9 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     return this.agentState;
   }
 
-  // Kept for callers that adopted the first Agent preview.
+  /**
+   * @deprecated Use getAgentState() instead.
+   */
   getState() {
     return this.getAgentState();
   }
@@ -460,13 +462,6 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     }
   }
 
-  override speak(...args: Parameters<XmovAvatar["speak"]>) {
-    if (args[2] ?? true) {
-      this.suppressNextVoiceEnd = true;
-    }
-    return super.speak(...args);
-  }
-
   override async destroy(reason = "user") {
     if (this.agentDestroyed) {
       if (this.agentState !== "destroyed") {
@@ -510,7 +505,16 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     });
   }
 
-  async speakByE2E(text: string): Promise<void> {
+  override speak(text: string): string | undefined {
+    // XmovAvatar Replay dispatches recorded TTSA events through this.speak(...).
+    // Preserve that inherited multi-argument call path without exposing it as
+    // the Agent's public E2E API.
+    if (arguments.length > 1) {
+      if (arguments[2] ?? true) {
+        this.suppressNextVoiceEnd = true;
+      }
+      return super.speak(text, arguments[1], arguments[2], arguments[3]);
+    }
     this.assertRunning();
     this.suppressNextVoiceEnd = false;
     this.emitConversation({ state: "speaking-directly", text });
@@ -522,6 +526,14 @@ export default class XingyunAvatarAgent extends XmovAvatar {
         is_end: true,
       },
     });
+    return undefined;
+  }
+
+  /**
+   * @deprecated Use speak(text) instead.
+   */
+  async speakByE2E(text: string): Promise<void> {
+    this.speak(text);
   }
 
   async startASR(options: AgentASRStartOptions = {}): Promise<void> {
@@ -670,18 +682,25 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     }
   }
 
-  async interruptConversation(reason = "user") {
+  override interrupt(): number {
     if (this.agentDestroyed) {
-      return;
+      return 0;
     }
 
-    void reason;
-
     this.sendControl({
       type: "interrupt",
     });
-    super.interrupt("speak");
+    const interruptedSpeechId = super.interrupt("speak");
     this.emitConversation({ state: "interrupted" });
+    return interruptedSpeechId;
+  }
+
+  /**
+   * @deprecated Use interrupt() instead. The reason parameter is ignored.
+   */
+  async interruptConversation(reason = "user"): Promise<void> {
+    void reason;
+    this.interrupt();
   }
 
   protected override async onSessionReloaded(sessionInfo: ISessionResponse): Promise<void> {
@@ -717,10 +736,6 @@ export default class XingyunAvatarAgent extends XmovAvatar {
     }
   }
 
-  override reloadSuccess() {
-    super.reloadSuccess();
-  }
-
   private async replaceE2EConnection(sessionInfo?: AgentSessionInfo) {
     const { wsUrl, token } = this.resolveE2EConnection(sessionInfo);
     const previousClient = this.e2eClient;

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);