@xmov/avatar 2.0.0-alpha.64 → 2.0.0-alpha.66

package/dist/modules/ResourceManager.d.ts

@@ -99,6 +99,8 @@ export default class ResourceManager {
     options: TOptions;
     sdk: XmovAvatar;
     session_id?: string;
+    /** 单次 init 生命周期内的稳定 request_id，由 generateRequestId 生成；session_id 未返回时也能用于 stopSession 兜底销毁 */
+    session_request_id?: string;
     mouthShapeLib: any;
     offlineIdle: IOfflineIdle[];
     offlineCache: Map<string, {

package/dist/utils/encodeToken.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 生成 request_id：用于 startSession / stopSession 的幂等与兜底销毁。
+ * 组成：md5(机器指纹 + 毫秒时间戳 + appId)
+ * 同一次 init → destroy 生命周期内始终不变，即使 session_id 尚未返回
+ * 也能用 request_id 让服务端销毁已占用的房间资源。
+ */
+export declare function generateRequestId(appId: string): string;
 export interface Headers {
     [key: string]: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmov/avatar",
-  "version": "2.0.0-alpha.64",
+  "version": "2.0.0-alpha.66",
   "description": "魔珐数字人 JS-SDK",
   "type": "module",
   "source": "src/index.ts",

package/src/control/ttsa.ts

@@ -24,6 +24,7 @@ import '../proto/protobuf.min';
 import '../proto/face_data_pb';
 
 const proxyProtobuf = protobuf.roots.default;
+const CLIENT_QUIT_ACK_TIMEOUT_MS = 3000;
 
 const pointNameObj = {
   'connect_sdk': '连接SDK',
@@ -63,6 +64,9 @@ interface ITtsaOptions {
 export default class Ttsa {
   private TAG = "[TTSA]";
   private ws: Socket;
+  private connectedOnce = false;
+  private quitRequested = false;
+  private quitPromise: Promise<void> | null = null;
   private room: string;
   private session_id: string;
   private token: string;
@@ -182,6 +186,11 @@ export default class Ttsa {
     });
 
     ws.on("connect", () => {
+      if (this.quitRequested) {
+        ws.disconnect();
+        return;
+      }
+      this.connectedOnce = true;
       // 连接成功时清理重连定时器
       this.clearReconnectTimer();
       this.initWsTimeoutTimer();
@@ -204,6 +213,9 @@ export default class Ttsa {
       }
     });
     ws.on("first_start_timestamp", (e: any) => {
+      if (this.quitRequested) {
+        return;
+      }
       (window as any).avatarSDKLogger.log(this.TAG, "first_start_timestamp", e);
       // 前端在发送first_start_timestamp后运行帧索引
       this.firstStartTimestamp(e.server_time);
@@ -342,7 +354,7 @@ export default class Ttsa {
       this.clearOldWsTimeoutTimer();
       // 停止客户端心跳
       this.stopHeartbeat();
-      if(e === 'io client disconnect') {
+      if (this.quitRequested || e === 'io client disconnect') {
         return;
       }
       // 增加状态检查，避免重复处理断开事件
@@ -393,6 +405,10 @@ export default class Ttsa {
     }) as any;
     ws.on("client_quit", (e) => {
       (window as any).avatarSDKLogger.warn(this.TAG, "client_quit", "断开原因", e);
+      // A quit broadcast may precede its ACK. Let the local quit flow own teardown.
+      if (this.quitRequested) {
+        return;
+      }
       ws.disconnect();
       this.session_speak_req_id = 0;
       if (Object.keys(e).length) {
@@ -442,6 +458,9 @@ export default class Ttsa {
   };
   initWsTimeoutTimer = () => {
     this.clearOldWsTimeoutTimer();
+    if (this.quitRequested) {
+      return;
+    }
 
     this.wsConnectTimer = window.setTimeout(async () => {
       
@@ -658,6 +677,10 @@ export default class Ttsa {
     return this.ws.connected;
   }
 
+  get hasConnected(): boolean {
+    return this.connectedOnce;
+  }
+
   _setResumeInfoCallback(lastSessionId: string, _getResumeInfo: () => IResumeParams) {
     this._isResume = true
     this._lastSessionId = lastSessionId
@@ -682,6 +705,26 @@ export default class Ttsa {
     return `${this._uniqueSpeakId}-${this.session_id}`
   }
 
+  quit(stopReason: string, timeoutMs = CLIENT_QUIT_ACK_TIMEOUT_MS): Promise<void> {
+    if (this.quitPromise) {
+      return this.quitPromise;
+    }
+    this.quitRequested = true;
+    this.clearReconnectTimer();
+    this.clearOldWsTimeoutTimer();
+    this.stopHeartbeat();
+    this.quitPromise = this.sendClientQuit(stopReason, timeoutMs);
+    return this.quitPromise;
+  }
+
+  private async sendClientQuit(stopReason: string, timeoutMs: number): Promise<void> {
+    if (!this.ws.connected) {
+      return;
+    }
+    // ACK confirms receipt; no application-level ACK payload is assumed here.
+    await this.ws.timeout(timeoutMs).emitWithAck("client_quit", { stop_reason: stopReason });
+  }
+
   close() {
     // 使用 disconnect() 而不是 close()，disconnect() 会停止所有重连尝试
     if (this.ws) {
@@ -690,10 +733,7 @@ export default class Ttsa {
     this.clearOldWsTimeoutTimer();
     this.stopHeartbeat();
     this.session_speak_req_id = 0;
-    if (this.reconnectTimer !== -1) {
-      clearTimeout(this.reconnectTimer);
-      this.reconnectTimer = -1;
-    }
+    this.clearReconnectTimer();
     if (this.syncTimestampInterval) {
       clearInterval(this.syncTimestampInterval);
       this.syncTimestampInterval = 0; // 重置为初始值 0，保持状态统一

package/src/index.ts

@@ -1424,9 +1424,7 @@ export default class XmovAvatar {
 
     // 薄客户端模式：通知 server 端销毁，然后清理本地资源
     if (this._isClientMode) {
-      this._apiForwarder?.destroy(stop_reason);
-      await this.destroyClient();
-      this.onStatusChange(AvatarStatus.close);
+      await this.disconnectClientForDestroy(stop_reason);
       return;
     }
 
@@ -1441,6 +1439,30 @@ export default class XmovAvatar {
     return res
   }
 
+  protected async disconnectClientForDestroy(stopReason: string): Promise<void> {
+    this.replayData = null;
+    try {
+      if (this._isClientMode) {
+        this._apiForwarder?.destroy(stopReason);
+      } else if (!this.ttsa?.hasConnected) {
+        // Initialization can own a session/request before TTSA first connects.
+        // Mark an in-flight connection as quitting before waiting for DELETE.
+        await this.ttsa?.quit(stopReason);
+        await this.resourceManager.stopSession(stopReason);
+      } else {
+        this.ttsa.sendSdkPoint('close_session', {
+          reason: stopReason,
+        });
+        await this.ttsa.quit(stopReason);
+      }
+    } catch (error) {
+      (window as any).avatarSDKLogger.warn(this.TAG, "TTSA client_quit 未确认，继续释放本地资源", error);
+    } finally {
+      await this.destroyClient();
+      this.onStatusChange(AvatarStatus.close);
+    }
+  }
+
   idle() {
     if (this._isClientMode) { this._apiForwarder?.idle(); return; }
     if(this.enableClientInterrupt) {
@@ -1629,13 +1651,13 @@ export default class XmovAvatar {
     const e = Errors(params)
     if(params.code !== EErrorCode.RENDER_BODY_ERROR && params.code !== EErrorCode.RENDER_FACE_ERROR && params.code !== EErrorCode.BODY_DATA_EXPIRED) {
       this.options.onMessage(e)
-    }
-    // Sentry 错误上报（仅公有云构建时生效）
-    if (ENABLE_SENTRY && this.sentryReporter) {
-      try {
-        this.sentryReporter.captureError(e);
-      } catch (err) {
-        (window as any).avatarSDKLogger.warn(this.TAG, 'Sentry 上报失败', err);
+      // Sentry 错误上报（仅公有云构建时生效）
+      if (ENABLE_SENTRY && this.sentryReporter) {
+        try {
+          this.sentryReporter.captureError(e);
+        } catch (err) {
+          (window as any).avatarSDKLogger.warn(this.TAG, 'Sentry 上报失败', err);
+        }
       }
     }
 

package/src/modules/ResourceManager.ts

@@ -6,7 +6,7 @@ import {
 } from "../utils/DataInterface";
 import XmovAvatar from "../index";
 import { EErrorCode } from "../types/error";
-import { headersNeedSign } from "../utils/encodeToken";
+import { headersNeedSign, generateRequestId } from "../utils/encodeToken";
 // import { isDEV } from "../utils";
 import CacheManager from './cache-manager';
 
@@ -121,6 +121,8 @@ export default class ResourceManager {
   options: TOptions;
   sdk: XmovAvatar;
   session_id?: string;
+  /** 单次 init 生命周期内的稳定 request_id，由 generateRequestId 生成；session_id 未返回时也能用于 stopSession 兜底销毁 */
+  session_request_id?: string;
   mouthShapeLib: any;
   offlineIdle: IOfflineIdle[] = []
   offlineCache = new Map<string, {
@@ -304,6 +306,7 @@ export default class ResourceManager {
       onDownloadProgress?.(this.progress);
     }, 100);
     // http 请求算 10 进度
+    this.session_request_id = generateRequestId(this.options.appId);
     const result = await this.startSession();
     const res = result as unknown as ISessionResponse;
     // 先记录 session_id，确保后续 stopSession 能正确释放房间
@@ -365,6 +368,7 @@ export default class ResourceManager {
 
 
     const data = {
+      request_id: this.session_request_id,
       tag: this.options.tag,
       gateway_type: this.options.gateway_type,
       ...(this.options.asr_id !== undefined ? { asr_id: this.options.asr_id } : {}),
@@ -404,12 +408,19 @@ export default class ResourceManager {
   async stopSession(stop_reason: string) {
     try {
       const url = `${this.options.gatewayServer}`;
-      if (!this.session_id) {
+      // session_id 尚未返回时（如 init 未完成就 destroy），只要有 request_id 仍发请求，
+      // 让服务端用 request_id 匹配并销毁房间占用，避免 init 失败后的资源泄漏。
+      if (!this.session_id && !this.session_request_id) {
         return;
       }
-      const data = {
-        session_id: this.session_id,
+      const data: Record<string, any> = {
         stop_reason,
+      };
+      if (this.session_id) {
+        data.session_id = this.session_id;
+      }
+      if (this.session_request_id) {
+        data.request_id = this.session_request_id;
       }
       const { headers, data: signedData } = headersNeedSign(this.options.appId, this.options.appSecret, "DELETE", url, data);
       const response = await request(url, { method: "DELETE", data: signedData, headers: { ...headers, ...this.options.headers } });
@@ -908,5 +919,7 @@ export default class ResourceManager {
       this.bg = null;
     }
     this.progress = 0
+    this.session_id = undefined;
+    this.session_request_id = undefined;
   }
 }

package/src/utils/encodeToken.ts

@@ -1,9 +1,24 @@
 import md5 from 'blueimp-md5';
+import { generateFingerprint } from './index';
 
 function encodeWithMd5(s: string): string {
   return md5(s);
 }
 
+/**
+ * 生成 request_id：用于 startSession / stopSession 的幂等与兜底销毁。
+ * 组成：md5(机器指纹 + 毫秒时间戳 + appId)
+ * 同一次 init → destroy 生命周期内始终不变，即使 session_id 尚未返回
+ * 也能用 request_id 让服务端销毁已占用的房间资源。
+ */
+export function generateRequestId(appId: string): string {
+  const fingerprint = (() => {
+    try { return generateFingerprint(); } catch { return 'unknown'; }
+  })();
+  const payload = `${fingerprint}|${Date.now()}|${appId}`;
+  return md5(payload);
+}
+
 function escapeNonAsciiForPythonJson(value: string): string {
   return value.replace(/[^\u0000-\u007E]/g, character => {
     return `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`;