@xmov/avatar 2.0.1 → 2.1.0

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
   }
@@ -270,6 +277,7 @@ export default class XmovAvatar {
       gatewayServer,
       cacheServer,
       config:_config,
+      audioOnlyMode: options.audioOnlyMode || false,
       onNetworkInfo(networkInfo) {
         self.networkInfo = networkInfo;
         options.onNetworkInfo?.(networkInfo);
@@ -293,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(),
@@ -1039,12 +1051,28 @@ export default class XmovAvatar {
 
   visibilitychange() {
     if (document.hidden) {
-      // this.offlineMode()
-      // tab 回来时，强制同步解帧队列
-      // this.renderScheduler.forceSyncDecoder();
+      // 进入后台：暂停渲染循环和解码器（省电）、清空音频与表情数据
+      // 仅渲染中暂停（resumeRender 要求 paused 状态才能恢复），
+      // 其他状态（init/stopped/隐身 paused）只停止音频，避免强制暂停后无法恢复
+      const rs = this.renderScheduler?.getRenderState();
+      if (rs === RenderState.rendering || rs === RenderState.resumed) {
+        this.renderScheduler?.pauseRender();
+      } else {
+        this.renderScheduler?.pauseForBackground();
+      }
     } else {
-      if (this.ttsa?.getStatus()) {
-        this.renderScheduler.forceSyncDecoder();
+      // 回到前台：若处于暂停态则恢复渲染（内部已 forceSyncDecoder 对齐最新帧）
+      if (this.renderScheduler?.getRenderState() === RenderState.paused) {
+        this.renderScheduler?.resumeRender();
+      } else if (this.ttsa?.getStatus()) {
+        // 未暂停但连接正常：兜底同步解帧队列
+        this.renderScheduler?.forceSyncDecoder();
+      }
+      // WebSocket 在后台断开且已进入离线模式，网络可用则主动触发重连，
+      // 否则用户切回前台续播时无响应且无任何报错
+      if (!this.ttsa?.getStatus() && this.status === AvatarStatus.offline && NetworkMonitor.ONLINE) {
+        (window as any).avatarSDKLogger.warn(this.TAG, "切回前台发现连接已断开，主动触发重连");
+        this.onlineMode();
       }
       // tab 切换回来时，恢复音频捕获的 AudioContext
       if (this.captureAudioCtx && this.captureAudioCtx.state === 'suspended') {
@@ -1086,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
@@ -1094,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,
         });
@@ -1148,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();
     
   }
 
@@ -1204,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)
@@ -1350,7 +1388,7 @@ export default class XmovAvatar {
     // 薄客户端模式：通知 server 端销毁，然后清理本地资源
     if (this._isClientMode) {
       this._apiForwarder?.destroy(stop_reason);
-      this.destroyClient();
+      await this.destroyClient();
       this.onStatusChange(AvatarStatus.close);
       return;
     }
@@ -1358,8 +1396,8 @@ export default class XmovAvatar {
     this.ttsa?.sendSdkPoint('close_session', {
       reason: stop_reason,
     });
-    this.destroyClient();
     const res = await this.resourceManager.stopSession(stop_reason);
+    await this.destroyClient();
     if(res) {
       this.onStatusChange(AvatarStatus.close);
     }
@@ -1480,6 +1518,8 @@ export default class XmovAvatar {
     });
     this.incompleteInitializationCleanupPromise = (async () => {
       try {
+        // 先等待房间释放完成，再清理本地资源，避免房间泄漏
+        await stopSessionPromise;
         await this.destroyClient();
       } catch (error) {
         (window as any).avatarSDKLogger.warn(this.TAG, '清理初始化未完成的本地资源时出错', error);
@@ -1617,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() {
@@ -1664,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;
       }
@@ -1740,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/modules/ResourceManager.ts

@@ -17,7 +17,7 @@ import CacheManager from './cache-manager';
 type TOptions = Pick<
   IAvatarOptions,
   "appId" | "appSecret" | "gatewayServer" | 'cacheServer' | "sdkInstance" | "config" | "headers" | "gateway_type" | "tag" |
-  "asr_id" | "llm_id" | "session_speak_req_id"
+  "asr_id" | "llm_id" | "session_speak_req_id" | "audioOnlyMode"
 > & {
   sessionRequestData?: Record<string, unknown>
   onNetworkInfo(quality: INetworkInfo): void
@@ -205,12 +205,14 @@ export default class ResourceManager {
   private isProcessingVideo = false; // 防止在视频处理过程中清理缓存
   private cacheServer?: CacheManager;
   private startSessionTimer: any = null;
+  private audioOnlyMode: boolean = false;
 
   // 新增：正在下载的视频跟踪
   private downloadingVideos = new Map<string, Promise<ArrayBuffer | undefined>>();
   first_load = true;
   constructor(options: TOptions) {
     this.options = options;
+    this.audioOnlyMode = options.audioOnlyMode || false;
     this.sdk = options.sdkInstance as XmovAvatar;
     this.mouthShapeLib = {
       char_info: null,
@@ -303,9 +305,15 @@ export default class ResourceManager {
     }, 100);
     // http 请求算 10 进度
     const result = await this.startSession();
-    // 如果在 startSession 过程中被销毁了，直接返回，避免继续加载资源
+    const res = result as unknown as ISessionResponse;
+    // 先记录 session_id，确保后续 stopSession 能正确释放房间
+    if (res?.session_id) {
+      this.session_id = res.session_id;
+    }
+    // 如果在 startSession 过程中被销毁了，释放刚创建的房间并返回，避免房间泄漏
     if (this.destroyed) {
       (window as any).avatarSDKLogger.warn(this.TAG, "sdk destroyed during load, aborting after startSession");
+      await this.stopSession("destroy_during_init");
       return null;
     }
     if (!result) {
@@ -318,15 +326,15 @@ export default class ResourceManager {
     this.startSessionTimer = null;
     this.progress = 15;
     onDownloadProgress?.(this.progress);
-    const res = result as unknown as ISessionResponse;
-    this.session_id = res?.session_id;
     this.resource_pack = res.resource_pack;
     this.config = res.config as any;
     this.offlineIdle = res.resource_pack?.offline_idle || []
     if (this.resource_pack) {
-      await this.loadMouthShapeLib(onDownloadProgress);
+      if(!this.audioOnlyMode) {
+        await this.loadMouthShapeLib(onDownloadProgress);
+      }
       this.getBackgroundImage();
-      if (!this.mouthShapeLib?.char_info && res?.resource_pack?.face_ani_char_data) {
+      if (!this.mouthShapeLib?.char_info && res?.resource_pack?.face_ani_char_data && !this.audioOnlyMode) {
         return null
       }
     }
@@ -838,6 +846,11 @@ export default class ResourceManager {
     }
     const res = result as unknown as ISessionResponse;
     this.session_id = res?.session_id;
+    // 重连过程中被销毁，释放刚创建的房间，避免房间泄漏
+    if (this.destroyed) {
+      await this.stopSession("destroy_during_reload");
+      return null;
+    }
     this.resource_pack = res.resource_pack;
     this.config = res.config as any;
     this.offlineIdle = res.resource_pack?.offline_idle || []

package/src/modules/decoder.ts

@@ -279,12 +279,32 @@ export default class ParallelDecoder {
 
   _startWorker(file: bodyFile) {
     const taskId = this.currentTaskId;
-    const worker = new Worker(workerURL);
+    let worker: Worker;
+    try {
+      worker = new Worker(workerURL);
+    } catch (err) {
+      this.reportMessage({
+        code: EErrorCode.INIT_WORKER_ERROR,
+        message: '初始化视频抽帧Worker失败',
+        e: err as object,
+      });
+      return;
+    }
     const id = `${file.body_id ?? file.id ?? 0}_${file.name}`;
     const data = file.data;
     const dataCopy = new ArrayBuffer(data.byteLength);
     new Uint8Array(dataCopy).set(new Uint8Array(data));
 
+    // 监听 Worker 运行时错误（脚本加载/解析失败等）
+    worker.addEventListener("error", (err) => {
+      if (taskId !== this.currentTaskId) return;
+      this.reportMessage({
+        code: EErrorCode.INIT_WORKER_ERROR,
+        message: '视频抽帧Worker运行时错误',
+        e: err as object,
+      });
+    });
+
     const onMessage = (e: MessageEvent) => {
       if (taskId !== this.currentTaskId) return; // 只处理当前任务
       if (e.data.type === "frame") {
@@ -335,6 +355,19 @@ export default class ParallelDecoder {
         }
         this._tryStartNext();
       } else if (e.data.type === "error") {
+        // 根据 Worker 上报的 error 内容区分错误码
+        // Worker 中有两处 postMessage({ type: 'error' }):
+        //   1. VideoDecoder error 回调 → 视频抽帧错误 (VIDEO_FRAME_EXTRACT_ERROR)
+        //   2. 解码配置不支持 → 视频流处理错误 (PROCESS_VIDEO_STREAM_ERROR)
+        const errorMsg = e.data.error ?? '';
+        const code = errorMsg.includes('不支持')
+          ? EErrorCode.PROCESS_VIDEO_STREAM_ERROR
+          : EErrorCode.VIDEO_FRAME_EXTRACT_ERROR;
+        this.reportMessage({
+          code,
+          message: errorMsg || '视频解码错误',
+          e: { fileName: file.name, error: errorMsg } as object,
+        });
         const task = this.tasks.get(id);
         if (task) {
           task.status = "error";

package/src/utils/capability-checker.ts

@@ -58,11 +58,11 @@ function checkWebGL2Sync(): ICapabilityCheckItem {
 
 /**
  * 同步检查音频系统（PCM 或 MSE 任一可用即可）
- * 
+ *
  * SDK 有两种音频播放器：
  * 1. PCM 播放器：AudioWorklet + AudioContext（raw_audio = true）
  * 2. MSE 播放器：MediaSource + HTMLAudioElement（raw_audio = false）
- * 
+ *
  * 两者二选一，任一可用则 SDK 音频能力可用
  */
 function checkAudioSystemSync(): ICapabilityCheckItem {
@@ -110,17 +110,27 @@ function checkAudioSystemSync(): ICapabilityCheckItem {
 
 /**
  * 同步检查 WebCodecs API 是否存在（不探测具体编解码器）
+ *
+ * 与 streaming-video.ts 解码策略一致标注平台解码路径：
+ * - Android（含 OpenHarmony/ArkWeb）：prefer-software 软解码
+ * - 其余环境：默认配置（硬解码）
+ * 实际解码配置支持度由异步 checkWebCodecsDetailed 探测
  */
 function checkWebCodecsSync(): ICapabilityCheckItem {
   const hasVideoDecoder = typeof (window as any).VideoDecoder !== 'undefined';
-  const supported = hasVideoDecoder;
+  const userAgent = (navigator.userAgent || '').toLowerCase();
+  const isAndroid = /android/.test(userAgent) || /openharmony|arkweb/.test(userAgent);
 
   return {
     name: 'webcodecs',
-    supported,
+    supported: hasVideoDecoder,
     severity: 'fatal',
-    reason: supported ? undefined : '浏览器不支持 WebCodecs VideoDecoder API',
-    detail: { hasVideoDecoder },
+    reason: hasVideoDecoder ? undefined : '浏览器不支持 WebCodecs VideoDecoder API',
+    detail: {
+      hasVideoDecoder,
+      isAndroid,
+      hardwareAcceleration: isAndroid ? 'prefer-software' : 'default',
+    },
   };
 }
 
@@ -139,14 +149,14 @@ function checkWorkerSync(): ICapabilityCheckItem {
 
 /**
  * 同步检查所有浏览器能力（用于 constructor 快速校验）
- * 
+ *
  * 检查项：
  * - secureContext：安全上下文（HTTPS / localhost）
  * - webgl2：WebGL2 渲染能力
  * - audio：音频播放能力（PCM 或 MSE 任一可用即可）
  * - webcodecs：WebCodecs API 存在性
  * - worker：Web Worker 支持
- * 
+ *
  * 音频检查逻辑：SDK 有两种音频播放器（PCM 和 MSE），只需其中一种可用即可
  * - PCM 播放器依赖：AudioContext + AudioWorkletNode
  * - MSE 播放器依赖：MediaSource
@@ -186,13 +196,17 @@ export function checkCapabilitySync(audioOnlyMode = false): ICapabilityCheckRepo
 
 /**
  * 异步检查 WebCodecs 详细编解码器支持
+ *
+ * 与 streaming-video.ts 解码策略一致：
+ * - Android（含 OpenHarmony/ArkWeb）：主路径为 prefer-software 软解码，默认配置兜底
+ * - 其余环境：主路径为默认配置（硬解码）
+ * 逐 codec 探测两种配置的支持度，并按平台主路径判定 SDK 可用性
  */
 async function checkWebCodecsDetailed(): Promise<ICapabilityCheckItem> {
   try {
     const hasVideoDecoder = typeof (window as any).VideoDecoder !== 'undefined';
-    const supported = hasVideoDecoder;
 
-    if (!supported) {
+    if (!hasVideoDecoder) {
       return {
         name: 'webcodecs',
         supported: false,
@@ -202,29 +216,89 @@ async function checkWebCodecsDetailed(): Promise<ICapabilityCheckItem> {
       };
     }
 
+    // 平台判定与 streaming-video.ts 保持一致
+    const userAgent = (navigator.userAgent || '').toLowerCase();
+    const isAndroid = /android/.test(userAgent) || /openharmony|arkweb/.test(userAgent);
+
+    // 探测配置补全尺寸字段：与业务 isConfigSupported(config) 一致（纯 codec 在部分浏览器被拒）
+    const probeW = 2160;
+    const probeH = 1920;
+
     // 探测具体编解码器支持
-    let codecSupport: Record<string, boolean> = {};
+    // 注意：WebCodecs 的 codec 字段是纯编解码器字符串（如 avc1.640032），
+    //       不能用 video/mp4; codecs="..." 的 MIME 形式（会导致 isConfigSupported 抛异常）
+    let codecSupport: Record<string, { default: boolean; software: boolean | null; error?: string }> = {};
     const testCodecs = [
-      'video/mp4; codecs="avc1.42E01E"',  // H.264 Baseline
-      'video/mp4; codecs="avc1.4D001F"',  // H.264 Main
-      'video/mp4; codecs="avc1.64001F"',  // H.264 High
+      'avc1.42E01E',  // H.264 Baseline
+      'avc1.4D001F',  // H.264 Main
+      'avc1.64001F',  // H.264 High
     ];
+
+    // 主路径（平台默认解码配置）与兜底（默认配置）任一支持即判定可用
+    let primarySupported = false;
+    let fallbackSupported = false;
+    // 探测过程是否出现异常（区别于"确实不支持"）：异常时降级 warn，避免误杀可用环境
+    let probeFailed = false;
     for (const codec of testCodecs) {
       try {
-        const result = await (window as any).VideoDecoder.isConfigSupported({
+        // 默认配置（浏览器默认/硬解），业务兜底路径
+        const defaultResult = await (window as any).VideoDecoder.isConfigSupported({
           codec,
+          codedWidth: probeW,
+          codedHeight: probeH,
         });
-        codecSupport[codec] = result.supported;
+        const defaultOk = !!defaultResult?.supported;
+        if (defaultOk) {
+          fallbackSupported = true;
+        }
+
+        // Android 主路径：prefer-software 软解码（与 streaming-video.ts 一致）
+        let softwareOk: boolean | null = null;
+        if (isAndroid) {
+          try {
+            const softwareResult = await (window as any).VideoDecoder.isConfigSupported({
+              codec,
+              codedWidth: probeW,
+              codedHeight: probeH,
+              hardwareAcceleration: 'prefer-software',
+            });
+            softwareOk = !!softwareResult?.supported;
+          } catch {
+            softwareOk = false;
+          }
+          if (softwareOk) {
+            primarySupported = true;
+          }
+        } else if (defaultOk) {
+          primarySupported = true;
+        }
+
+        codecSupport[codec] = { default: defaultOk, software: softwareOk };
       } catch {
-        codecSupport[codec] = false;
+        // isConfigSupported 抛异常：探测方式受限（如浏览器实现差异），非"确实不支持"
+        probeFailed = true;
+        codecSupport[codec] = { default: false, software: null, error: 'probe-failed' };
       }
     }
 
+    const supported = primarySupported || fallbackSupported;
+    // 探测异常且无任何配置支持：降级 warn（运行时业务用真实 config 的 isConfigSupported 为准）
+    const severity = probeFailed && !supported ? 'warn' : 'fatal';
     return {
       name: 'webcodecs',
-      supported: true,
-      severity: 'fatal',
-      detail: { hasVideoDecoder, codecSupport },
+      supported,
+      severity,
+      reason: supported
+        ? undefined
+        : severity === 'warn'
+          ? 'WebCodecs 探测异常（运行时将以实际视频配置二次确认）'
+          : '浏览器不支持 H.264 解码（默认/软解配置均不可用）',
+      detail: {
+        hasVideoDecoder,
+        isAndroid,
+        hardwareAcceleration: isAndroid ? 'prefer-software' : 'default',
+        codecSupport,
+      },
     };
   } catch (e) {
     return {
@@ -332,7 +406,7 @@ async function checkWorkerDetailed(): Promise<ICapabilityCheckItem> {
 
 /**
  * 异步检查所有浏览器能力（详细版，用于 init 阶段详细探测）
- * 
+ *
  * 包含更详细的编解码器探测和 Worker 执行测试
  */
 export async function checkCapability(audioOnlyMode = false): Promise<ICapabilityCheckReport> {

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

package/src/view/DebugOverlay.ts

@@ -71,12 +71,17 @@ export class DebugOverlay {
   }
 
   public show(): void {
-    if (this.container) {
+    if (!this.container) {
+      this.createOverlay();
+    }
+    if(this.container) {
       this.container.style.display = "block";
-      return;
     }
-    this.createOverlay();
-    this.updateInterval = window.setInterval(() => this.updateTextOnly(), 200);
+    // 重启定时器：hide() 会清除 updateInterval，再次 show 时需要重建
+    // 否则界面显示但内容永不刷新
+    if (!this.updateInterval) {
+      this.updateInterval = window.setInterval(() => this.updateTextOnly(), 200);
+    }
     this.updateTextOnly();
   }