@xmov/avatar 2.0.0-alpha.38

package/src/baseRender/AvatarRenderer.ts

@@ -0,0 +1,1559 @@
+/**
+ * 3D 渲染（身体+表情）
+ */
+import ResourceManager from "../modules/ResourceManager";
+import { DataCacheQueue, IBodyFrame } from "../control/DataCacheQueue";
+import { GLDevice } from "../utils/GLDevice";
+import { GLPipeline, GLPipelineCharData } from "../utils/GLPipeline";
+import { performanceConstant } from "../utils/perfermance";
+import { EErrorCode } from "../types/error";
+import DefaultWidgetRenderer from "../modules/TrackRenderer/render-implements";
+import { Layout, RenderState, WalkConfig } from "../types";
+import { IBRAnimationFrameData_NN } from "../utils/DataInterface";
+import SaveAndDownload from "../control/SaveAndDownload";
+import { getStyleStr, updateCanvasXOffset, isharmony } from "../utils";
+import { IRawFaceFrameData } from "types/frame-data";
+
+type Option = {
+  dataCacheQueue: DataCacheQueue;
+  resourceManager: ResourceManager;
+  saveAndDownload: SaveAndDownload;
+  forceSyncDecoder: () => void;
+  reportMessage: (message: {
+    code: EErrorCode;
+    message: string;
+    e?: object;
+  }) => void;
+  onDownloadProgress: (progress: number) => void;
+  onStateChange: (state: string) => void;
+  onRenderChange: (state: RenderState) => void;
+  sendVideoInfo: (info: { name: string; body_id: number; id: number }) => void;
+  onError: (error: any) => void;
+  sendSdkPoint: (point: string, data: any) => void;
+};
+export default class AvatarRender {
+  private TAG = "[AvatarRender]";
+  options: Option;
+  canvas = document.createElement("canvas");
+  device: GLDevice | null;
+  pipeline: GLPipeline | null;
+  currentBodyFrame: IBodyFrame | null = null;
+  lastFaceFrame: IRawFaceFrameData | null = null;
+  private isInit = false;
+  private isFirstRender = true;
+  private lastFrameState: string = "";
+  private lastRenderState: RenderState = RenderState.init;
+  private onDownloadProgress: (progress: number) => void;
+  private onStateChange?: (state: string) => void = () => {};
+  private onRenderChange?: (state: RenderState) => void = () => {};
+  private sendVideoInfo: (info: {
+    name: string;
+    body_id: number;
+    id: number;
+  }) => void = () => {};
+  private lostHandler: (event: Event) => void = () => {};
+  private restoreHandler: (event: Event) => void = () => {};
+  private avatarCanvasVisible: boolean = true;
+  private lastRealFaceFrameData: any = null; // 上一帧渲染的实时数据
+  private lastRealFaceFrame: number = -1; // 上一次实时表情数据帧号
+  private lastWeight: number = 0.0;
+
+  private lastFrameIndex = -1;
+  private saveAndDownload: SaveAndDownload;
+  private canvasOffsetX = -1;
+  private baseWalkOffset = 0; // 行走偏移基准值，setWalkConfig 时记录，用于差值补偿
+  private lastBodyOffset = 0; // 最近一次 body 帧的世界坐标偏移
+  private pendingCharData: GLPipelineCharData | null = null; // 待设置的字符数据
+  private interrupt: boolean = false; // 是否中断speak
+  private walkConfig: WalkConfig | null = null;
+  layout: Layout | null = null;
+  private allLostFrameCount = 0; // 累计丢失的帧数
+  private allLostFaceFrameCount = 0; // 累计丢失的表情帧数
+  private maxLostFrameCount = 300; // 最大允许丢失帧数
+  private forceSyncDecoder: () => void = () => {}; // 强制同步解码器到最新一帧
+  private createPipelineLock = false; // 创建 pipeline 锁
+  private restoreTimeout: any = null; // 恢复超时定时器
+  private isRecovering: boolean = false; // 是否正在恢复中
+  private recoverStartTime: number = 0; // 恢复开始时间
+
+  // ── 分阶段恢复配置（指数退避）─────────────────────────────────────
+  // light：复用现有 canvas，仅重建 GLDevice + GLPipeline（代价最小）
+  // medium：创建新 canvas 替换 DOM 节点，重建 GLDevice + GLPipeline
+  // full  ：在全量重建基础上降低渲染分辨率，作为最后手段
+  private recoveryStage: 'light' | 'medium' | 'full' = 'light';
+  // 各阶段最大尝试次数
+  // light 减为 2 次：同一 canvas 上 getContext 返回死 context，多次重试无意义
+  // 适用于 exit_on_context_lost（GPU 进程崩溃）场景，快速升级到 medium
+  private readonly recoveryMaxAttempts: Record<string, number> = { light: 2, medium: 3, full: 2 };
+  // 各阶段指数退避基础延迟（ms）：实际延迟 = baseDelay * 2^attempt
+  // light 缩短到 300ms：快速失败，尽早升级
+  // medium 增加到 4000ms：GPU 进程重启后 D3D11 设备初始化需要更长时间
+  private readonly recoveryBaseDelays: Record<string, number> = { light: 300, medium: 4000, full: 5000 };
+  // 最大延迟上限（ms），防止退避时间过长
+  private readonly recoveryMaxDelay: number = 30000;
+  // 当前阶段内已尝试次数
+  private currentStageAttempts: number = 0;
+  // 是否正在使用降级分辨率（full 阶段恢复后）
+  private isUsingReducedResolution: boolean = false;
+  // 恢复分辨率定时器
+  private resolutionRestoreTimer: any = null;
+  // 降级分辨率稳定运行时长要求（ms），超过此时间后才尝试恢复原始分辨率
+  private readonly RESOLUTION_RESTORE_DELAY: number = 30000; // 30 秒
+  private scale = 1.0; // 缩放比例
+  private sendSdkPoint: (point: string, data: any) => void = () => {};
+  private copyCanvas: HTMLCanvasElement;
+  private copyCtx: CanvasRenderingContext2D | null;
+  constructor(options: Option) {
+    this.options = options;
+    this.onDownloadProgress = options.onDownloadProgress;
+    this.onStateChange = options.onStateChange;
+    this.onRenderChange = options.onRenderChange;
+    this.sendVideoInfo = options.sendVideoInfo;
+    this.saveAndDownload = options.saveAndDownload;
+    this.forceSyncDecoder = options.forceSyncDecoder;
+    this.lostHandler = this._lostHandler.bind(this);
+    this.restoreHandler = this._restoreHandler.bind(this);
+    this.setCanvasVisibility(this.avatarCanvasVisible);
+    this.sendSdkPoint = options.sendSdkPoint;
+    // 延迟创建 GLDevice 和 GLPipeline，避免与视频解码器竞争 GPU 资源
+    // 将在 init 方法中首次创建
+    this.device = null;
+    this.pipeline = null;
+    this.copyCanvas = document.createElement('canvas');
+    this.copyCtx = this.copyCanvas.getContext('2d');
+  }
+
+  /**
+   * 重置表情相关状态（用于从隐身模式恢复渲染时）
+   */
+  resetFaceFrameState() {
+    this.lastRealFaceFrame = -1;
+    this.lastRealFaceFrameData = null;
+    this.lastWeight = 0.0;
+    (window as any).avatarSDKLogger?.log(
+      this.TAG,
+      "重置表情状态（从隐身模式恢复）"
+    );
+  }
+
+  /**
+   * 创建 pipeline 并设置字符数据
+   */
+  public createPipeline() {
+    if (this.pipeline || !this.device || this.createPipelineLock) {
+      return;
+    }
+    this.createPipelineLock = true;
+    this.pipeline = new GLPipeline(this.device, this.sendSdkPoint);
+    this.createPipelineLock = false;
+    // 如果有待设置的字符数据，立即设置
+    if (this.pendingCharData) {
+      this.pipeline.setCharData(this.pendingCharData);
+      this.pipeline.setSyncMedia();
+    }
+  }
+
+  // ── WebGL 上下文丢失 / 恢复 ──────────────────────────────────────
+
+  _lostHandler(event: Event) {
+    event.preventDefault();
+    (window as any).avatarSDKLogger.error("Context lost.", event);
+
+    // 先移除事件监听器，避免旧 device 的匿名监听器残留
+    if (this.device) {
+      try {
+        this.device.canvas.removeEventListener("webglcontextlost", this.lostHandler);
+        this.device.canvas.removeEventListener("webglcontextrestored", this.restoreHandler);
+      } catch (_) { /* ignore */ }
+    }
+
+    // 销毁旧 device 释放 GPU 资源（关键：不调用 destroy 会导致资源泄漏，
+    // 后续恢复阶段在新 canvas 上也可能因 GPU 内存耗尽而失败）
+    if (this.device) {
+      try { this.device.destroy(); } catch (_) { /* ignore */ }
+    }
+    if (this.pipeline) {
+      try { this.pipeline.destroy(); } catch (_) { /* ignore */ }
+    }
+    this.device = null;
+    this.pipeline = null;
+
+    this.options.reportMessage({
+      code: EErrorCode.WEBGL_CONTEXT_LOST,
+      message: "Context lost.",
+      e: {
+        event,
+        timestamp: Date.now(),
+      },
+    });
+
+    // 如果已经在恢复中，不重复启动恢复流程
+    if (this.isRecovering) {
+      (window as any).avatarSDKLogger.warn("Context recovery already in progress, skipping.");
+      return;
+    }
+
+    // 取消分辨率恢复计划（上下文再次丢失）
+    if (this.resolutionRestoreTimer) {
+      clearTimeout(this.resolutionRestoreTimer);
+      this.resolutionRestoreTimer = null;
+      (window as any).avatarSDKLogger.log("[Recovery] Cancelled resolution restore due to context loss");
+    }
+
+    // 初始化分阶段恢复状态
+    this.isRecovering = true;
+    this.recoverStartTime = Date.now();
+    this.recoveryStage = 'light';
+    this.currentStageAttempts = 0;
+
+    // 启动第一次恢复尝试
+    this._scheduleNextAttempt();
+  }
+
+  _restoreHandler(event: Event) {
+    // 清除定时器，因为 restored 事件已经触发
+    if (this.restoreTimeout) {
+      clearTimeout(this.restoreTimeout);
+      this.restoreTimeout = null;
+    }
+
+    if (this.isRecovering) {
+      (window as any).avatarSDKLogger.warn("Context restore event received during recovery, skipping duplicate recovery.");
+      return;
+    }
+
+    this.options.reportMessage({
+      code: EErrorCode.WEBGL_CONTEXT_RESTORED,
+      message: "Context restored event received.",
+      e: {
+        event,
+        timestamp: Date.now(),
+      },
+    });
+
+    this.isRecovering = true;
+    // 浏览器已主动恢复，优先使用 light 阶段
+    this.recoveryStage = 'light';
+    this.currentStageAttempts = 0;
+    this._recoverContext();
+  }
+
+  // ── 分阶段恢复核心 ──────────────────────────────────────────────
+
+  /**
+   * 根据当前阶段分发到对应的恢复方法
+   */
+  private _recoverContext(): void {
+    // 防止竞态条件：如果恢复已完成（device/pipeline 已存在且 context 正常），跳过
+    if (this.device && this.pipeline && this.device.gl && !this.device.gl.isContextLost()) {
+      (window as any).avatarSDKLogger.log("[Recovery] Already recovered, skipping.");
+      this.isRecovering = false;
+      return;
+    }
+
+    (window as any).avatarSDKLogger.log(
+      `[Recovery] stage=${this.recoveryStage}, attempt=${this.currentStageAttempts + 1}/${this.recoveryMaxAttempts[this.recoveryStage]}`
+    );
+
+    if (this.restoreTimeout) {
+      clearTimeout(this.restoreTimeout);
+      this.restoreTimeout = null;
+    }
+
+    let success = false;
+    try {
+      switch (this.recoveryStage) {
+        case 'light':
+          success = this._tryLightRecovery();
+          break;
+        case 'medium':
+          success = this._tryMediumRecovery();
+          break;
+        case 'full':
+          success = this._tryFullRecovery();
+          break;
+      }
+    } catch (error) {
+      (window as any).avatarSDKLogger.error(`[Recovery] stage=${this.recoveryStage} threw:`, error);
+    }
+
+    if (success) {
+      this._onRecoverySuccess();
+      return;
+    }
+
+    // 本阶段失败，判断是否还有本阶段的重试机会
+    this.currentStageAttempts++;
+    this.isRecovering = false;
+
+    const maxAttempts = this.recoveryMaxAttempts[this.recoveryStage];
+    if (this.currentStageAttempts < maxAttempts) {
+      // 本阶段还可以重试
+      this._scheduleNextAttempt();
+    } else {
+      // 本阶段用尽，升级到下一阶段
+      this._advanceStage();
+    }
+  }
+
+  /**
+   * 阶段 1 — 轻量恢复
+   * 复用现有 canvas，仅重建 GLDevice + GLPipeline
+   * 适用于：上下文偶发丢失、浏览器后台恢复
+   */
+  private _tryLightRecovery(): boolean {
+    try {
+      (window as any).avatarSDKLogger.log("[Recovery] Trying light recovery (reuse canvas)...");
+
+      // 清理残留的 device（如果有）
+      if (this.device) {
+        try {
+          this.device.canvas.removeEventListener("webglcontextlost", this.lostHandler);
+          this.device.canvas.removeEventListener("webglcontextrestored", this.restoreHandler);
+          this.device.destroy();
+        } catch (_) { /* ignore */ }
+        this.device = null;
+      }
+
+      // 在现有 canvas 上重建 GLDevice
+      this.device = new GLDevice(this.canvas);
+      this.device.canvas.addEventListener("webglcontextlost", this.lostHandler, false);
+      this.device.canvas.addEventListener("webglcontextrestored", this.restoreHandler, false);
+
+      // 验证上下文可用
+      if (!this.device.gl || this.device.gl.isContextLost()) {
+        throw new Error("WebGL context still lost after light recovery");
+      }
+
+      // 重建 pipeline
+      this.createPipelineLock = true;
+      this.pipeline = new GLPipeline(this.device, this.sendSdkPoint);
+      this.createPipelineLock = false;
+
+      if (this.pendingCharData) {
+        this.pipeline.setCharData(this.pendingCharData);
+        this.pipeline.setSyncMedia();
+      }
+      this.pipeline.reinitialize();
+      this.pipeline.setSyncMedia();
+      this.isInit = true;
+
+      return true;
+    } catch (error) {
+      (window as any).avatarSDKLogger.warn("[Recovery] Light recovery failed:", error);
+      this._reportRecoveryFailure('light', error);
+      return false;
+    }
+  }
+
+  /**
+   * 阶段 2 — 中等恢复
+   * 创建新 canvas 替换 DOM 节点，重建 GLDevice + GLPipeline
+   * 适用于：canvas 节点本身出现异常（如全屏切换导致的 DOM 重建）
+   */
+  private _tryMediumRecovery(): boolean {
+    try {
+      (window as any).avatarSDKLogger.log("[Recovery] Trying medium recovery (replace canvas)...");
+
+      // 销毁旧 device
+      if (this.device) {
+        try {
+          this.device.canvas.removeEventListener("webglcontextlost", this.lostHandler);
+          this.device.canvas.removeEventListener("webglcontextrestored", this.restoreHandler);
+          this.device.destroy();
+        } catch (_) { /* ignore */ }
+        this.device = null;
+      }
+
+      // 销毁旧 pipeline
+      if (this.pipeline) {
+        try { this.pipeline.destroy(); } catch (_) { /* ignore */ }
+        this.pipeline = null;
+      }
+
+      // 创建新 canvas 并替换 DOM 节点
+      const oldCanvas = this.canvas;
+      const oldCanvasStyle = oldCanvas.style.cssText;
+      const oldCanvasParent = oldCanvas.parentNode;
+
+      const newCanvas = document.createElement("canvas");
+      const resolution = this.options.resourceManager.getConfig()?.resolution;
+      if (resolution) {
+        newCanvas.width = resolution.width ?? 1080;
+        newCanvas.height = resolution.height ?? 1920;
+      }
+      newCanvas.setAttribute("style", oldCanvasStyle);
+
+      if (oldCanvasParent) {
+        oldCanvasParent.replaceChild(newCanvas, oldCanvas);
+      }
+      this.canvas = newCanvas;
+
+      // 在新 canvas 上初始化 GLDevice
+      this.device = new GLDevice(this.canvas);
+      this.device.canvas.addEventListener("webglcontextlost", this.lostHandler, false);
+      this.device.canvas.addEventListener("webglcontextrestored", this.restoreHandler, false);
+
+      if (!this.device.gl || this.device.gl.isContextLost()) {
+        throw new Error("WebGL context lost after medium recovery");
+      }
+
+      // 重建 pipeline
+      this.createPipelineLock = true;
+      this.pipeline = new GLPipeline(this.device, this.sendSdkPoint);
+      this.createPipelineLock = false;
+
+      if (this.pendingCharData) {
+        this.pipeline.setCharData(this.pendingCharData);
+        this.pipeline.setSyncMedia();
+      }
+      this.pipeline.reinitialize();
+      this.pipeline.setSyncMedia();
+      this.isInit = true;
+
+      return true;
+    } catch (error) {
+      (window as any).avatarSDKLogger.warn("[Recovery] Medium recovery failed:", error);
+      this._reportRecoveryFailure('medium', error);
+      return false;
+    }
+  }
+
+  /**
+   * 阶段 3 — 完全恢复（降级分辨率）
+   * 在全量重建基础上降低渲染分辨率，减少 GPU 压力
+   * 适用于：GPU 资源受限设备（笔记本集成显卡）连续上下文丢失
+   */
+  private _tryFullRecovery(): boolean {
+    try {
+      (window as any).avatarSDKLogger.log("[Recovery] Trying full recovery (reduced resolution)...");
+
+      // 销毁旧 device
+      if (this.device) {
+        try {
+          this.device.canvas.removeEventListener("webglcontextlost", this.lostHandler);
+          this.device.canvas.removeEventListener("webglcontextrestored", this.restoreHandler);
+          this.device.destroy();
+        } catch (_) { /* ignore */ }
+        this.device = null;
+      }
+
+      // 销毁旧 pipeline
+      if (this.pipeline) {
+        try { this.pipeline.destroy(); } catch (_) { /* ignore */ }
+        this.pipeline = null;
+      }
+
+      // 创建新 canvas，降低分辨率至原始的 75%
+      const oldCanvas = this.canvas;
+      const oldCanvasStyle = oldCanvas.style.cssText;
+      const oldCanvasParent = oldCanvas.parentNode;
+
+      const newCanvas = document.createElement("canvas");
+      const resolution = this.options.resourceManager.getConfig()?.resolution;
+      const scaleFactor = 0.75;
+      const targetWidth = Math.round((resolution?.width ?? 1080) * scaleFactor);
+      const targetHeight = Math.round((resolution?.height ?? 1920) * scaleFactor);
+      newCanvas.width = targetWidth;
+      newCanvas.height = targetHeight;
+      newCanvas.setAttribute("style", oldCanvasStyle);
+
+      if (oldCanvasParent) {
+        oldCanvasParent.replaceChild(newCanvas, oldCanvas);
+      }
+      this.canvas = newCanvas;
+
+      (window as any).avatarSDKLogger.log(
+        `[Recovery] Using reduced resolution: ${targetWidth}x${targetHeight} (scale=${scaleFactor})`
+      );
+
+      // 初始化 GLDevice
+      this.device = new GLDevice(this.canvas);
+      this.device.canvas.addEventListener("webglcontextlost", this.lostHandler, false);
+      this.device.canvas.addEventListener("webglcontextrestored", this.restoreHandler, false);
+
+      if (!this.device.gl || this.device.gl.isContextLost()) {
+        throw new Error("WebGL context lost after full recovery");
+      }
+
+      // 重建 pipeline
+      this.createPipelineLock = true;
+      this.pipeline = new GLPipeline(this.device, this.sendSdkPoint);
+      this.createPipelineLock = false;
+
+      if (this.pendingCharData) {
+        this.pipeline.setCharData(this.pendingCharData);
+        this.pipeline.setSyncMedia();
+      }
+      this.pipeline.reinitialize();
+      this.pipeline.setSyncMedia();
+      this.isInit = true;
+
+      return true;
+    } catch (error) {
+      (window as any).avatarSDKLogger.warn("[Recovery] Full recovery failed:", error);
+      this._reportRecoveryFailure('full', error);
+      return false;
+    }
+  }
+
+  // ── 恢复辅助方法 ────────────────────────────────────────────────
+
+  /**
+   * 恢复成功后的统一收尾处理
+   */
+  private _onRecoverySuccess(): void {
+    const recoveryTime = Date.now() - this.recoverStartTime;
+    const wasFullRecovery = this.recoveryStage === 'full';
+
+    (window as any).avatarSDKLogger.log(
+      `[Recovery] Success! stage=${this.recoveryStage}, time=${recoveryTime}ms${wasFullRecovery ? ' (reduced resolution)' : ''}`
+    );
+    this.options.reportMessage({
+      code: EErrorCode.WEBGL_CONTEXT_RECOVERED,
+      message: `Context recovered via ${this.recoveryStage} recovery in ${recoveryTime}ms.`,
+      e: {
+        timestamp: Date.now(),
+        recoveryTime,
+        stage: this.recoveryStage,
+        attempts: this.currentStageAttempts + 1,
+        reducedResolution: wasFullRecovery,
+      },
+    });
+
+    // 如果是 full 阶段恢复，标记降级分辨率并安排恢复
+    if (wasFullRecovery) {
+      this.isUsingReducedResolution = true;
+      this._scheduleResolutionRestore();
+    }
+
+    // 重置所有恢复状态
+    this.isRecovering = false;
+    this.recoveryStage = 'light';
+    this.currentStageAttempts = 0;
+  }
+
+  /**
+   * 安排恢复原始分辨率
+   * 在降级分辨率稳定运行一段时间后尝试恢复
+   */
+  private _scheduleResolutionRestore(): void {
+    // 清除之前的定时器（如果有）
+    if (this.resolutionRestoreTimer) {
+      clearTimeout(this.resolutionRestoreTimer);
+    }
+
+    (window as any).avatarSDKLogger.log(
+      `[Recovery] Scheduling resolution restore in ${this.RESOLUTION_RESTORE_DELAY}ms`
+    );
+
+    this.resolutionRestoreTimer = setTimeout(() => {
+      this._restoreOriginalResolution();
+    }, this.RESOLUTION_RESTORE_DELAY);
+  }
+
+  /**
+   * 恢复原始分辨率
+   * 尝试将 canvas 恢复到原始分辨率，如果再次丢失上下文则保持降级
+   */
+  private _restoreOriginalResolution(): void {
+    if (!this.isUsingReducedResolution || !this.device || this.device.gl.isContextLost()) {
+      (window as any).avatarSDKLogger.warn("[Recovery] Cannot restore resolution: not in reduced mode or context lost");
+      return;
+    }
+
+    try {
+      (window as any).avatarSDKLogger.log("[Recovery] Attempting to restore original resolution...");
+
+      // 获取原始分辨率配置
+      const resolution = this.options.resourceManager.getConfig()?.resolution;
+      const originalWidth = resolution?.width ?? 1080;
+      const originalHeight = resolution?.height ?? 1920;
+
+      // 保存当前 canvas 的样式
+      const currentStyle = this.canvas.style.cssText;
+      const parent = this.canvas.parentNode;
+
+      // 创建新 canvas 使用原始分辨率
+      const newCanvas = document.createElement("canvas");
+      newCanvas.width = originalWidth;
+      newCanvas.height = originalHeight;
+      newCanvas.setAttribute("style", currentStyle);
+
+      // 替换 DOM 中的 canvas
+      if (parent) {
+        parent.replaceChild(newCanvas, this.canvas);
+      }
+      this.canvas = newCanvas;
+
+      // 销毁旧的 device 和 pipeline
+      if (this.device) {
+        try {
+          this.device.canvas.removeEventListener("webglcontextlost", this.lostHandler);
+          this.device.canvas.removeEventListener("webglcontextrestored", this.restoreHandler);
+          this.device.destroy();
+        } catch (_) { /* ignore */ }
+        this.device = null;
+      }
+      if (this.pipeline) {
+        try { this.pipeline.destroy(); } catch (_) { /* ignore */ }
+        this.pipeline = null;
+      }
+
+      // 重新初始化 GLDevice
+      this.device = new GLDevice(this.canvas);
+      this.device.canvas.addEventListener("webglcontextlost", this.lostHandler, false);
+      this.device.canvas.addEventListener("webglcontextrestored", this.restoreHandler, false);
+
+      if (!this.device.gl || this.device.gl.isContextLost()) {
+        throw new Error("Context lost after resolution restore");
+      }
+
+      // 重建 pipeline
+      this.createPipelineLock = true;
+      this.pipeline = new GLPipeline(this.device, this.sendSdkPoint);
+      this.createPipelineLock = false;
+
+      if (this.pendingCharData) {
+        this.pipeline.setCharData(this.pendingCharData);
+        this.pipeline.setSyncMedia();
+      }
+      this.pipeline.reinitialize();
+      this.pipeline.setSyncMedia();
+
+      // 恢复成功
+      this.isUsingReducedResolution = false;
+      (window as any).avatarSDKLogger.log(
+        `[Recovery] Resolution restored to ${originalWidth}x${originalHeight}`
+      );
+      this.options.reportMessage({
+        code: EErrorCode.WEBGL_RESOLUTION_RESTORED,
+        message: `Resolution restored to ${originalWidth}x${originalHeight}.`,
+        e: {
+          timestamp: Date.now(),
+          resolution: { width: originalWidth, height: originalHeight },
+        },
+      });
+    } catch (error) {
+      (window as any).avatarSDKLogger.warn("[Recovery] Failed to restore resolution, keeping reduced:", error);
+      // 恢复失败，保持降级状态，不再重试
+    } finally {
+      this.resolutionRestoreTimer = null;
+    }
+  }
+
+  /**
+   * 升级恢复阶段：light → medium → full → 放弃
+   */
+  private _advanceStage(): void {
+    const stages: Array<'light' | 'medium' | 'full'> = ['light', 'medium', 'full'];
+    const currentIndex = stages.indexOf(this.recoveryStage);
+
+    if (currentIndex < stages.length - 1) {
+      const nextStage = stages[currentIndex + 1];
+      (window as any).avatarSDKLogger.log(
+        `[Recovery] Stage "${this.recoveryStage}" exhausted, upgrading to "${nextStage}"`
+      );
+      this.recoveryStage = nextStage;
+      this.currentStageAttempts = 0;
+      // 立即启动下一阶段第一次尝试
+      this._scheduleNextAttempt();
+    } else {
+      // 所有阶段全部失败，通知业务层
+      (window as any).avatarSDKLogger.error("[Recovery] All recovery stages exhausted. Giving up.");
+      this.options.reportMessage({
+        code: EErrorCode.WEBGL_CONTEXT_RECOVERY_MAX_ATTEMPTS,
+        message: "All WebGL recovery stages exhausted. SDK restart required.",
+        e: {
+          timestamp: Date.now(),
+          elapsedTime: Date.now() - this.recoverStartTime,
+          stagesAttempted: {
+            light: this.recoveryMaxAttempts.light,
+            medium: this.recoveryMaxAttempts.medium,
+            full: this.recoveryMaxAttempts.full,
+          },
+        },
+      });
+      this.isRecovering = false;
+    }
+  }
+
+  /**
+   * 按指数退避延迟安排下一次恢复尝试
+   * 延迟计算：baseDelay * 2^attempt，受 maxDelay 上限约束
+   */
+  private _scheduleNextAttempt(): void {
+    const baseDelay = this.recoveryBaseDelays[this.recoveryStage];
+    const maxAttempts = this.recoveryMaxAttempts[this.recoveryStage];
+    // 指数退避：baseDelay * 2^attempt
+    const calculatedDelay = baseDelay * Math.pow(2, this.currentStageAttempts);
+    const delay = Math.min(calculatedDelay, this.recoveryMaxDelay);
+
+    (window as any).avatarSDKLogger.log(
+      `[Recovery] Scheduling ${this.recoveryStage} attempt ${this.currentStageAttempts + 1}/${maxAttempts} in ${delay}ms (base=${baseDelay}ms, exp=${calculatedDelay}ms)`
+    );
+
+    this.restoreTimeout = setTimeout(() => {
+      this.isRecovering = true;
+      this._recoverContext();
+    }, delay);
+  }
+
+  /**
+   * 上报单次恢复失败事件
+   */
+  private _reportRecoveryFailure(stage: string, error: unknown): void {
+    this.options.reportMessage({
+      code: EErrorCode.WEBGL_CONTEXT_RECOVERY_FAILED,
+      message: `[${stage}] recovery attempt ${this.currentStageAttempts + 1}/${this.recoveryMaxAttempts[stage]} failed.`,
+      e: {
+        error,
+        stage,
+        attempt: this.currentStageAttempts + 1,
+        timestamp: Date.now(),
+      },
+    });
+  }
+
+  init(data: GLPipelineCharData | null) {
+    // this.style(this.options.resourceManager.getConfig()?.resolution?.width ?? 1080, this.options.resourceManager.getConfig()?.resolution?.height ?? 1920)
+    let charInitData = data;
+    // if (!this.device) {
+    //   return;
+    // }
+    this.style(this.options.resourceManager.getConfig()?.resolution?.width ?? 1080, this.options.resourceManager.getConfig()?.resolution?.height ?? 1920)
+    this.setCharacterCanvasAnchor();
+    if(!charInitData?.char) {
+      const charInfo = this.options.resourceManager.getMouthShapeLib().char_info;
+      charInitData = {
+        char: charInfo,
+        LUT: null,
+        transform: {
+          offsetX: 0.0,
+          offsetY: 0.0,
+          scaleX: 1.0,
+          scaleY: 1.0
+        },
+        multisample: 4
+      }
+    }
+    
+    // 保存字符数据，但不创建 pipeline
+    // pipeline 将在切换到在线模式时（resumeRender）才创建，避免在隐身模式时创建 pipeline 导致的 GPU 资源竞争
+    this.pendingCharData = charInitData;
+    this.isInit = true;
+
+    this.device = new GLDevice(this.canvas);
+    this.device.canvas.addEventListener("webglcontextlost", this.lostHandler, false);
+    this.device.canvas.addEventListener("webglcontextrestored", this.restoreHandler, false);
+    this.createPipeline();
+  }
+
+  private style(width = 0, height = 0) {
+    if (width > 0 && height > 0) {
+      // 设置canvas宽度为输入图片宽度的一半，因为输入的是左右两张图片合并的
+      this.canvas.width = width;
+      this.canvas.height = height;
+    }
+  }
+
+  /**
+   * 设置画布样式（修复transform失效 + 优化对齐逻辑 + 优雅拼接样式）
+   * @param avatar 布局配置
+   */
+  setCanvasStyle(layout: Layout) {
+    this.layout = layout;
+    // 重置偏移缓存，使下一渲染帧强制重新计算
+    this.canvasOffsetX = -1; 
+    const initPoint = this.walkConfig?.init_point ?? this.options.resourceManager.getConfig()?.walk_config?.init_point ?? null;
+    const {width = 1080, height = 1920} = this.options.resourceManager.getConfig()?.resolution ?? {width: 1080, height: 1920};
+    const [containerWidth, containerHeight] = layout.container?.size ?? [width, height];
+    // 解构并设置默认值
+    let {
+      v_align = 'center', // 垂直对齐：top/middle/bottom（修正命名逻辑）
+      h_align = 'center', // 水平对齐：left/center/right
+      scale = 1.0,
+      offset_x = 0.0,
+      offset_y = 0.0
+    } = layout.avatar || {};
+
+    // [【LiteSDK】行走2期](https://rsjqcmnt5p.feishu.cn/wiki/U2Waw2SDZikg7UkyVgxcorh7nne)
+    if(initPoint !== null && initPoint !== undefined) {
+      h_align = 'left';
+      offset_x = 0;
+    }
+
+    // 判断如果非数字，且包含vh时，根据vh计算scale  计算公式是 vh值 / 100 * 容器高度 / 分辨率高度 = scale
+    if (typeof scale === 'string' &&　scale.includes('vh')) {
+      const vhValue = parseFloat(scale.replace('vh', ''));
+      if (!isNaN(vhValue)) {
+          scale = (vhValue / 100 * containerHeight) / height;
+      } else {
+          scale = 1;
+      }
+    }
+    this.scale = Number(scale);
+    const avatarHeight = height * Number(scale);
+    const avatarWidth = width * Number(scale);
+    const marginX = avatarWidth  / 2;
+    const marginY = avatarHeight / 2;
+
+    // 基础样式（提取固定项，避免重复拼接）
+    const baseStyles = {
+      position: 'absolute',
+      zIndex: 100,
+      height: `${avatarHeight}px`,
+      width: `${avatarWidth}px`,
+      objectFit: 'contain',
+      top: 'auto',
+      right: 'auto',
+      bottom: 'auto',
+      left: 'auto',
+      marginLeft: '0',
+      marginTop: '0',
+      willChange: 'transform',
+      transform: 'translateZ(0)',
+    };
+
+    // 1. 处理水平对齐（h_align）：left/center/right
+    switch (h_align) {
+      case 'left':
+        baseStyles.left = initPoint !== null && initPoint !== undefined ? `${initPoint - marginX}px` : '0';
+        baseStyles.marginLeft = `${offset_x}px`;
+        break;
+      case 'right':
+        baseStyles.right = `-${marginX}px`;
+        baseStyles.marginLeft = `${offset_x}px`;
+        break;
+      default: // center
+        baseStyles.position = 'absolute';
+        baseStyles.left = '50%';
+        baseStyles.marginLeft = `${-marginX + offset_x}px`;
+        break;
+    }
+
+    // 2. 处理垂直对齐（v_align）：top/middle/bottom
+    switch (v_align) {
+      case 'top':
+        baseStyles.top = '0';
+        baseStyles.marginTop = `${offset_y}px`;
+        break;
+      case 'bottom':
+        baseStyles.bottom = '0';
+        baseStyles.marginTop = `${offset_y}px`;
+        break;
+      default: // middle
+        baseStyles.position = 'absolute';
+        baseStyles.top = '50%';
+        baseStyles.marginTop = `${-marginY + offset_y}px`;
+        break;
+    }
+
+    // 3. 合并transform（核心：只定义一次，避免覆盖）
+    // 4. 拼接样式字符串（优雅转换为css样式）
+    const styleStr = getStyleStr(baseStyles);
+
+    // 应用样式
+    this.canvas.setAttribute('style', styleStr);
+  }
+
+  setWalkConfig(walkConfig: WalkConfig) {
+    this.walkConfig = walkConfig;
+    // 记录当前偏移作为基准，后续渲染用差值补偿，避免后端累计偏移导致闪烁
+    this.baseWalkOffset = this.lastBodyOffset;
+    if(walkConfig.init_point != null && this.layout) {
+      this.setCanvasStyle(this.layout);
+    }
+  }
+
+  setCharacterCanvasAnchor(layout?: Layout) {
+    if(layout?.avatar) {
+      this.setCanvasStyle(layout);
+    } else if(this.options.resourceManager.getConfig()?.layout) {
+      const layout =this.options.resourceManager.getConfig()?.layout || {
+        avatar: {
+          v_align: "default",
+          h_align: "default",
+          scale: 1.0,
+          offset_x: 0.0,
+          offset_y: 0.0,
+        },
+      };
+      this.setCanvasStyle(layout);
+    } else {
+        const baseStyles = {
+        position: 'absolute',
+        zIndex: 100,
+        height: `100%`,
+        objectFit: 'contain',
+        top: 'auto',
+        right: 'auto',
+        bottom: 'auto',
+        left: 'auto',
+        marginLeft: '0',
+        marginTop: '0'
+      };
+      const styleStr = getStyleStr(baseStyles);
+      this.canvas.setAttribute('style', styleStr);
+      const auchor = this.options.resourceManager.getConfig()?.init_events?.find((item) => item.type === 'SetCharacterCanvasAnchor') || {
+        type: 'SetCharacterCanvasAnchor',
+        x_location: 0.0,
+        y_location: 0.0,
+        width: 1.0,
+        height: 1.0,
+      };
+      const {x_location, y_location, width, height} = auchor;
+      const style = this.canvas.style.cssText + `left: calc(${x_location} * 100%); top: calc(${y_location} * 100%); transform: scale(${width}, ${height}); transform-origin: top left;`
+      this.canvas.setAttribute("style", style);
+    }
+  }
+
+  // 获取权重
+  // this.lastWeight应初始化为0
+  computeWeight(frameIndex) {
+    const maxTweenStep = 12;
+
+    const frameDiff = frameIndex - this.lastFrameIndex;
+    const isLost: boolean = frameIndex > this.lastRealFaceFrame;
+
+    if (isLost) {
+      // 丢帧：权重累加步长，最大不超过1.0
+      this.lastWeight = Math.min(this.lastWeight + frameDiff, maxTweenStep);
+    } else {
+      // 未丢帧：权重递减步长，最小不低于0.0
+      this.lastWeight = Math.max(this.lastWeight - frameDiff, 0);
+    }
+    return this.lastWeight / maxTweenStep;
+  }
+
+  render(frameIndex: number): { canvas: HTMLCanvasElement; rendered: boolean } {
+    // 每次渲染时，清理过期的表情数据
+    this.options.dataCacheQueue.clearOldFaceData(frameIndex);
+    if (!this.isInit) {
+      return { canvas: this.canvas, rendered: false };
+    }
+    // 确保 device 已创建
+    // if (!this.device) {
+    //   this.device = new GLDevice(this.canvas);
+    //   this.device.canvas.addEventListener("webglcontextlost", this.lostHandler, false);
+    //   this.device.canvas.addEventListener("webglcontextrestored", this.restoreHandler, false);
+    // }
+    // 如果还没有创建，这里作为兜底方案创建（防止遗漏）
+    // if (!this.pipeline) {
+    //   this.createPipeline();
+    //   // 如果创建失败，返回 canvas
+    //   if (!this.pipeline) {
+    //     return this.canvas;
+    //   }
+    // }
+    const bodyFrame =
+      this.options.dataCacheQueue._getBodyImageBitmap(frameIndex);
+    let faceFrame = this.options.dataCacheQueue._getFaceImageBitmap(
+      frameIndex,
+      bodyFrame?.body_id ?? bodyFrame?.id ?? 0
+    );
+    let curRealFaceData = this.options.dataCacheQueue._getRealFaceImageBitmap(frameIndex, bodyFrame?.body_id ?? bodyFrame?.id ?? 0);
+    if (this.lastFrameState === "speak" && bodyFrame?.frameState !== "speak") {
+      // 从speak切出，重置表情权重相关状态
+      this.lastRealFaceFrame = -1;
+      this.lastRealFaceFrameData = null;
+      this.lastWeight = 0.0;
+    }
+    if(this.interrupt) {
+      faceFrame = curRealFaceData;
+    } else if(faceFrame?.FaceFrameData && faceFrame?.face_frame_type) {
+      // 在当前第 i 帧时，如果有实时表情数据real_face_data_i，则用其来渲染，同时更新last_real_face_data和last_real_face_data_frame
+      this.lastRealFaceFrameData = faceFrame.FaceFrameData;
+      this.lastRealFaceFrame = frameIndex;
+      // 实时数据帧连续时，权重递减
+      if (this.lastRealFaceFrame !== -1 && this.lastWeight > 0 && curRealFaceData) {
+        const lastWeight = this.computeWeight(frameIndex)
+        faceFrame = {
+          frameIndex,
+          state: bodyFrame?.frameState || 'idle',
+          body_id: bodyFrame?.body_id || -1,
+          sf: frameIndex,
+          ef: frameIndex,
+          cs: faceFrame?.cs || "",
+          face_frame_type: 0,
+          id: bodyFrame?.body_id || -1,
+          FaceFrameData: IBRAnimationFrameData_NN.interp(
+            this.lastRealFaceFrameData,
+            curRealFaceData.FaceFrameData,
+            curRealFaceData.FaceFrameData,
+            lastWeight,
+            this.options.resourceManager.resource_pack?.interpolate_joints || []
+          )
+        }
+      }
+    } else {
+      if(this.lastRealFaceFrame === -1) {
+        faceFrame = curRealFaceData;
+        // this.options.onError({
+        //   code: EErrorCode.RENDER_FACE_ERROR,
+        //   message: `第${frameIndex}帧 实时面部数据为空,原始数据渲染`,
+        //   e: JSON.stringify({ bodyFrame, faceFrame }),
+        // });
+      } else {
+        // this.options.onError({
+        //   code: EErrorCode.RENDER_FACE_ERROR,
+        //   message: `第${frameIndex}帧 实时面部数据为空，插值渲染`,
+        //   e: JSON.stringify({ bodyFrame, faceFrame }),
+        // });
+        if(curRealFaceData?.FaceFrameData) {
+          if(this.lastRealFaceFrameData === null) {
+            // 如果只有原始表情数据idle_face_data_i，若last_real_face_data为空，直接用idle_face_data_i渲染
+            faceFrame = curRealFaceData;
+          } else {
+            // 若last_real_face_data非空，则使用last_real_face_data和idle_face_data_i的插值结果来渲染
+            const lastWeight = this.computeWeight(frameIndex)
+            faceFrame = {
+              frameIndex,
+              state: bodyFrame?.frameState || 'idle',
+              body_id: bodyFrame?.body_id || -1,
+              sf: frameIndex,
+              ef: frameIndex,
+              cs: faceFrame?.cs || "",
+              face_frame_type: 0,
+              id: bodyFrame?.body_id || -1,
+              FaceFrameData: IBRAnimationFrameData_NN.interp(
+                this.lastRealFaceFrameData,
+                curRealFaceData.FaceFrameData,
+                curRealFaceData.FaceFrameData,
+                lastWeight,
+                this.options.resourceManager.resource_pack?.interpolate_joints || []
+              )
+            }
+          }
+        }
+      }
+    }
+    this._setCurrentBodyFrame(bodyFrame);
+    if (
+      ((!bodyFrame || !faceFrame) && bodyFrame?.hfd) ||
+      (!bodyFrame?.hfd && !bodyFrame?.frame)
+    ) {
+      // 判断bodyFrame和faceFrame是否为空
+      if (!bodyFrame) {
+        this.allLostFrameCount++;
+        this.options.onError({
+          code: EErrorCode.RENDER_BODY_ERROR,
+          message: `Error:  第${frameIndex}帧 bodyFrame为空`,
+          e: JSON.stringify({ bodyFrame, faceFrame }),
+        });
+      } else if (!faceFrame) {
+        this.allLostFaceFrameCount++;
+        this.options.onError({
+          code: EErrorCode.RENDER_FACE_ERROR,
+          message: `Error: 第${frameIndex}帧 faceFrame为空`,
+          e: JSON.stringify({ bodyFrame, faceFrame }),
+        });
+      }
+      if(this.allLostFrameCount === this.maxLostFrameCount) {
+        this.options.reportMessage({
+          code: EErrorCode.RENDER_DATA_MISSING,
+          message: `连续${this.maxLostFrameCount}帧 身体渲染数据缺失.`,
+        });
+        // 丢失过多帧,达到最大允许丢失帧数后,触发解码器对齐到最新的一帧
+         this.options.onError({
+          code: EErrorCode.RENDER_DATA_MISSING,
+          message: `Error: 连续${this.maxLostFrameCount}帧 身体渲染数据缺失`,
+          e: JSON.stringify({ bodyFrame, faceFrame }),
+        });
+        this.forceSyncDecoder();
+        this.allLostFrameCount = 0;
+      }
+      if(this.allLostFaceFrameCount === this.maxLostFrameCount) {
+        this.options.reportMessage({
+          code: EErrorCode.RENDER_FACE_DATA_MISSING,
+          message: `连续${this.maxLostFrameCount}帧 渲染表情数据缺失.`,
+          e: { bodyFrame, frameIndex },
+        });
+      }
+      (window as any).avatarSDKLogger.log(
+        this.TAG,
+        "render第",
+        frameIndex,
+        "丢帧，bodyFrame",
+        bodyFrame,
+        "faceFrame",
+        faceFrame
+      );
+      return { canvas: this.canvas, rendered: false };
+    } else {
+      // this.onRenderChange?.(RenderState.rendering);
+      this.allLostFrameCount = 0;
+      this.allLostFaceFrameCount = 0;
+    }
+
+    if (
+      ((bodyFrame && faceFrame?.FaceFrameData && bodyFrame?.hfd) ||
+        (!bodyFrame?.hfd && bodyFrame?.frame)) &&
+      this.device
+    ) {
+      this.sendVideoInfo({
+        name: bodyFrame.name,
+        body_id: bodyFrame.body_id,
+        id: bodyFrame.id,
+      });
+      if (bodyFrame?.frameState !== this.lastFrameState) {
+        this.onStateChange?.(bodyFrame?.frameState);
+        if (bodyFrame.frameState !== "speak") {
+          (window as any).performanceTracker.markEnd(
+            performanceConstant.start_action_render,
+            bodyFrame.frameState
+          );
+        }
+        this.lastFrameState = bodyFrame?.frameState;
+      }
+      if (this.isFirstRender) {
+        (window as any).performanceTracker.markEnd(
+          performanceConstant.first_avatar_render
+        );
+        this.isFirstRender = false;  
+        this.renderBackground();
+        (window as any).performanceTracker.markStart(
+          performanceConstant.first_render
+        );
+        this.onDownloadProgress?.(100);
+      }
+      // this.style(bodyFrame.frame.displayWidth, bodyFrame.frame.displayHeight);
+      let rendered = false;
+      if (this.pipeline) {
+        try {
+          const isEnableRobotExpression = this.options.resourceManager.getIsEnableRobotExpression()
+          const faceData = isEnableRobotExpression ? (faceFrame?.FaceFrameData  ?? null) : bodyFrame?.hfd ? (faceFrame?.FaceFrameData ?? null) : null;
+          if (faceData) {
+            this.saveAndDownload.appendMultipleToArray("render_faceData", [faceFrame]);
+          }
+          this.lastFaceFrame = faceFrame;
+          let renderBodyFrame = bodyFrame.frame;
+          if(isharmony()) {
+            this.copyCanvas.width = bodyFrame.frame.displayWidth;
+            this.copyCanvas.height = bodyFrame.frame.displayHeight;
+            this.copyCtx?.drawImage(bodyFrame.frame, 0, 0);
+            renderBodyFrame = this.copyCanvas;
+          }
+          // (window as any).avatarSDKLogger.log(
+          //   this.TAG,
+          //   "render第",
+          //   frameIndex,
+          //   "帧，bodyFrame",
+          //   bodyFrame,
+          //   "faceFrame",
+          //   faceFrame
+          // );
+          this.pipeline.renderFrame({
+            charBodyTexture: renderBodyFrame,
+            data: faceData,
+            backgroundTexture: null,
+            // 临时方案，后续需要根据实际情况调整
+            fx: this.options.resourceManager.getConfig()?.fx ?? {},
+            onPostRender: () => null
+          });
+          let pos_orig = [0, 0, 0]; //随便取了一个参考点。这里取了0号关节的位置
+          let pos_new = [...pos_orig];
+          const bodyOffset = bodyFrame?.offset ?? 0;
+          this.lastBodyOffset = bodyOffset;
+          pos_new[0] += bodyOffset - this.baseWalkOffset;
+          const transformX = this.pipeline.getBillboardTransform2D(
+            [pos_orig[0], pos_orig[1], pos_orig[2]],
+            [pos_new[0], pos_new[1], pos_new[2]]
+          ).offsetX;
+          const offset_PX = transformX * this.canvas.width * this.scale;
+          
+          if(offset_PX !== this.canvasOffsetX) {
+            this.canvasOffsetX = offset_PX;
+            if (DefaultWidgetRenderer.CUSTOM_WIDGET) {
+              DefaultWidgetRenderer.CUSTOM_WIDGET({
+                type: "set_character_canvas_offset",
+                data: offset_PX
+              });
+            } else if (DefaultWidgetRenderer.PROXY_WIDGET && DefaultWidgetRenderer.PROXY_WIDGET["set_character_canvas_offset"]) {
+              // 如果有代理的渲染器，则根据类型执行代理的渲染器
+              DefaultWidgetRenderer.PROXY_WIDGET["set_character_canvas_offset"](offset_PX);
+            } else {
+              updateCanvasXOffset(this.canvas, offset_PX);
+            }
+          }
+          this.lastFrameIndex = frameIndex;
+          rendered = true;
+        } catch (error) {
+          (window as any).avatarSDKLogger.error(this.TAG, "渲染帧失败:", error);
+          this.options.onError({
+            code: EErrorCode.WebGL_RENDER_ERROR,
+            message: `Error: 第${frameIndex}帧 webgl渲染异常`,
+            e: JSON.stringify({ bodyFrame, faceFrame, error }),
+          });
+        } finally {
+          // 渲染完成后再关闭VideoFrame
+          if (bodyFrame.frame && typeof bodyFrame.frame.close === "function") {
+            bodyFrame.frame.close();
+          }
+        }
+        this.onRenderChange?.(RenderState.rendering);
+      } else {
+        // 如果没有渲染，也要关闭VideoFrame
+        if (bodyFrame?.frame && typeof bodyFrame.frame.close === "function") {
+          bodyFrame.frame.close();
+        }
+      }
+      return { canvas: this.canvas, rendered };
+    }
+    return { canvas: this.canvas, rendered: false };
+  }
+
+  renderBackground() {
+    const background = this.options.resourceManager.getBackgroundImageElement();
+    if (!background) return;
+    const bgContainer = document.getElementById("avatar-bg-container");
+    if (!bgContainer) return;
+    // 设置背景图样式
+    bgContainer.style.backgroundImage = `url(${background.src})`;
+    // 可添加其他背景样式（如覆盖方式、定位等）
+    bgContainer.style.backgroundSize = "cover";
+    bgContainer.style.backgroundPosition = "center";
+  }
+
+  _setCurrentBodyFrame(bodyFrame?: IBodyFrame) {
+    if (bodyFrame) {
+      this.currentBodyFrame = bodyFrame;
+    }
+  }
+  _getCurrentBodyFrameInfo(frameIndex: number) {
+    if (this.currentBodyFrame && frameIndex > 0) {
+      return {
+        client_frame: frameIndex,
+        current_ani: this.currentBodyFrame.name,
+        current_ani_frame:
+          this.currentBodyFrame.frameIndex - this.currentBodyFrame.sf,
+        next_state: this.lastFrameState || "idle",
+      };
+    }
+    return {
+      client_frame: 0,
+      current_ani: "",
+      current_ani_frame: 0,
+      next_state: "idle",
+    };
+  }
+
+  /**
+   * 获取当前帧的 body 和 face 原始数据（用于回调）
+   * 不包含渲染数据，只返回帧号、body_id 等元数据
+   */
+  _getCurrentFrameData(frameIndex: number): {
+    body: { body_id: number; name: string; video_frame: number; sf: number; state: string } | null;
+    face: { body_id: number; sf: number; ef: number; state: string; face_frame_type: number } | null;
+  } {
+    const bodyFrame = this.currentBodyFrame;
+    const faceFrame = this.lastFaceFrame;
+
+    return {
+      body: bodyFrame ? {
+        body_id: bodyFrame.body_id ?? bodyFrame.id ?? 0,
+        name: bodyFrame.name,
+        video_frame: bodyFrame.frameIndex - bodyFrame.sf,
+        sf: bodyFrame.sf,
+        state: bodyFrame.frameState,
+      } : null,
+      face: faceFrame ? {
+        body_id: faceFrame.body_id ?? faceFrame.id ?? 0,
+        sf: faceFrame.sf,
+        ef: faceFrame.ef,
+        state: faceFrame.state,
+        face_frame_type: faceFrame.face_frame_type ?? 0,
+      } : null,
+    };
+  }
+  /**
+   * 设置canvas的显隐状态
+   * @param visible 是否可见
+   */
+  setCanvasVisibility(visible: boolean) {
+    this.avatarCanvasVisible = visible;
+    if (this.canvas) {
+      this.canvas.style.display = visible ? "" : "none";
+    }
+  }
+
+  /**
+   * 获取canvas的显隐状态
+   */
+  getCanvasVisibility(): boolean {
+    return this.avatarCanvasVisible;
+  }
+
+  destroy() {
+    this.allLostFrameCount = 0;
+    this.allLostFaceFrameCount = 0;
+    
+    // 清理恢复定时器
+    if (this.restoreTimeout) {
+      clearTimeout(this.restoreTimeout);
+      this.restoreTimeout = null;
+    }
+    this.isRecovering = false;
+    this.recoveryStage = 'light';
+    this.currentStageAttempts = 0;
+    
+    // 先移除事件监听器，避免在销毁过程中触发
+    if (this.device) {
+      this.device.canvas.removeEventListener(
+        "webglcontextlost",
+        this.lostHandler
+      );
+      this.device.canvas.removeEventListener(
+        "webglcontextrestored",
+        this.restoreHandler
+      );
+      
+      // 如果 pipeline 存在，先销毁 pipeline（释放 WebGL 资源）
+      if (this.pipeline) {
+        this.pipeline.destroy();
+        this.pipeline = null;
+      }
+      
+      // 最后销毁 device（会释放 WebGL context）
+      // 对于隐身的数字人，如果没有 pipeline，说明没有真正使用 WebGL
+      // 使用延迟销毁，避免在渲染关键帧时释放 GPU 资源导致其他数字人渲染异常
+      if (this.device.gl) {
+        // 保存 device 引用，延迟销毁
+        const deviceToDestroy = this.device;
+        this.device = null; // 先清除引用，避免后续操作使用
+        
+        // 延迟到下一帧销毁，给其他数字人留出完成当前渲染的时间
+        // 这样可以避免在销毁隐身数字人时影响正在说话的数字人的面部渲染
+        requestAnimationFrame(() => {
+          try {
+            if (deviceToDestroy) {
+              deviceToDestroy.destroy();
+            }
+          } catch (error) {
+            // 忽略销毁错误，避免影响其他数字人
+            (window as any).avatarSDKLogger?.warn?.('[AvatarRenderer] 销毁 device 时出错:', error);
+          }
+        });
+      } else {
+        // 如果 gl 为 null，直接清理引用
+        this.device = null;
+      }
+    }
+    
+    // 清理状态
+    this.isInit = false;
+    this.isFirstRender = true;
+    this.lastRealFaceFrame = -1;
+    this.lastRealFaceFrameData = null;
+    this.lastWeight = 0.0;
+    this.onStateChange = undefined;
+    this.lastFrameState = "";
+    this.pipeline = null;
+    this.pendingCharData = null;
+    this.scale = 1.0;
+
+    const bgContainer = document.getElementById("avatar-bg-container");
+    if (bgContainer && bgContainer.parentNode) {
+      bgContainer.parentNode.removeChild(bgContainer);
+    }
+
+
+    // 移除 canvas
+    if (this.canvas && this.canvas.parentNode) {
+      this.canvas.remove();
+    }
+  }
+  setInterrupt(interrupt: boolean) {
+    if(this.lastFaceFrame?.state !== 'speak' && interrupt) return
+    this.interrupt = interrupt;
+  }
+
+  /**
+   * [测试用] 模拟 WebGL 上下文丢失
+   * 用于测试分阶段恢复策略是否正常工作
+   * @param restoreAfterMs 自动恢复上下文的延迟时间（毫秒），设置为 0 则不自动恢复
+   * @param forceFail 强制恢复失败（用于测试 medium/full 阶段的升级逻辑）
+   */
+  public simulateContextLoss(restoreAfterMs: number = 5000, forceFail: boolean = false): void {
+    if (!this.device || !this.device.gl) {
+      (window as any).avatarSDKLogger.warn("[Test] No WebGL device available for testing");
+      return;
+    }
+
+    const gl = this.device.gl;
+    const loseExtension = gl.getExtension("WEBGL_lose_context");
+    
+    if (!loseExtension) {
+      (window as any).avatarSDKLogger.error("[Test] WEBGL_lose_context extension not available");
+      return;
+    }
+
+    (window as any).avatarSDKLogger.log("[Test] Simulating WebGL context loss...");
+    
+    // 如果设置了 forceFail，临时禁用恢复
+    if (forceFail) {
+      (window as any).avatarSDKLogger.warn("[Test] Force fail mode enabled - will not auto-restore");
+    }
+
+    // 触发上下文丢失
+    loseExtension.loseContext();
+
+    // 如果设置了自动恢复，则在指定时间后恢复上下文
+    if (restoreAfterMs > 0 && !forceFail) {
+      setTimeout(() => {
+        (window as any).avatarSDKLogger.log(`[Test] Auto-restoring context after ${restoreAfterMs}ms...`);
+        loseExtension.restoreContext();
+      }, restoreAfterMs);
+    }
+  }
+
+  /**
+   * [测试用] 获取当前恢复状态信息
+   */
+  public getRecoveryStatus(): {
+    isRecovering: boolean;
+    stage: string;
+    attempts: number;
+    maxAttempts: number;
+    isUsingReducedResolution: boolean;
+  } {
+    return {
+      isRecovering: this.isRecovering,
+      stage: this.recoveryStage,
+      attempts: this.currentStageAttempts,
+      maxAttempts: this.recoveryMaxAttempts[this.recoveryStage] || 0,
+      isUsingReducedResolution: this.isUsingReducedResolution,
+    };
+  }
+
+  /**
+   * [测试用] 批量测试分阶段恢复
+   * 依次触发多次上下文丢失，观察各阶段的恢复情况
+   */
+  public async testStagedRecovery(): Promise<void> {
+    (window as any).avatarSDKLogger.log("[Test] Starting staged recovery test...");
+    
+    const testCases = [
+      { desc: "Light recovery (should succeed)", delay: 1000, forceFail: false },
+      { desc: "Context loss again (may upgrade to medium)", delay: 8000, forceFail: false },
+    ];
+
+    for (let i = 0; i < testCases.length; i++) {
+      const tc = testCases[i];
+      (window as any).avatarSDKLogger.log(`[Test] Step ${i + 1}: ${tc.desc}`);
+      
+      await new Promise<void>((resolve) => {
+        setTimeout(() => {
+          this.simulateContextLoss(tc.delay, tc.forceFail);
+          resolve();
+        }, tc.delay);
+      });
+
+      // 等待恢复完成
+      await new Promise<void>((resolve) => setTimeout(resolve, tc.delay + 2000));
+      
+      const status = this.getRecoveryStatus();
+      (window as any).avatarSDKLogger.log(`[Test] After step ${i + 1}:`, status);
+    }
+
+    (window as any).avatarSDKLogger.log("[Test] Staged recovery test completed!");
+  }
+
+  /**
+   * 手动重启 WebGL：创建新 canvas + 新 GLDevice + 新 GLPipeline
+   * 用于分阶段恢复全部失败后的手动恢复
+   * @returns 是否成功
+   */
+  public restartWebGL(): boolean {
+    (window as any).avatarSDKLogger.log("[restartWebGL] Starting manual WebGL restart...");
+
+    // 取消所有恢复定时器
+    if (this.restoreTimeout) {
+      clearTimeout(this.restoreTimeout);
+      this.restoreTimeout = null;
+    }
+    if (this.resolutionRestoreTimer) {
+      clearTimeout(this.resolutionRestoreTimer);
+      this.resolutionRestoreTimer = null;
+    }
+    this.isRecovering = false;
+    this.recoveryStage = 'light';
+    this.currentStageAttempts = 0;
+
+    try {
+      // 销毁旧 device
+      if (this.device) {
+        try {
+          this.device.canvas.removeEventListener("webglcontextlost", this.lostHandler);
+          this.device.canvas.removeEventListener("webglcontextrestored", this.restoreHandler);
+          this.device.destroy();
+        } catch (_) { /* ignore */ }
+        this.device = null;
+      }
+
+      // 销毁旧 pipeline
+      if (this.pipeline) {
+        try { this.pipeline.destroy(); } catch (_) { /* ignore */ }
+        this.pipeline = null;
+      }
+
+      // 创建新 canvas 并替换 DOM 节点
+      const oldCanvas = this.canvas;
+      const oldCanvasStyle = oldCanvas.style.cssText;
+      const oldCanvasParent = oldCanvas.parentNode;
+
+      const newCanvas = document.createElement("canvas");
+      const resolution = this.options.resourceManager.getConfig()?.resolution;
+      if (resolution) {
+        newCanvas.width = resolution.width ?? 1080;
+        newCanvas.height = resolution.height ?? 1920;
+      }
+      newCanvas.setAttribute("style", oldCanvasStyle);
+
+      if (oldCanvasParent) {
+        oldCanvasParent.replaceChild(newCanvas, oldCanvas);
+      }
+      this.canvas = newCanvas;
+
+      // 在新 canvas 上初始化 GLDevice
+      this.device = new GLDevice(this.canvas);
+      this.device.canvas.addEventListener("webglcontextlost", this.lostHandler, false);
+      this.device.canvas.addEventListener("webglcontextrestored", this.restoreHandler, false);
+
+      // 检查 context 是否可用
+      if (!this.device.gl || this.device.gl.isContextLost()) {
+        throw new Error("WebGL context still lost after creating new canvas");
+      }
+
+      // 重建 pipeline
+      this.createPipelineLock = true;
+      this.pipeline = new GLPipeline(this.device, this.sendSdkPoint);
+      this.createPipelineLock = false;
+
+      if (this.pendingCharData) {
+        this.pipeline.setCharData(this.pendingCharData);
+        this.pipeline.setSyncMedia();
+      }
+      this.pipeline.reinitialize();
+      this.pipeline.setSyncMedia();
+      this.isInit = true;
+
+      (window as any).avatarSDKLogger.log("[restartWebGL] WebGL restart successful!");
+
+      this.options.reportMessage({
+        code: EErrorCode.WEBGL_CONTEXT_MANUAL_RESTARTED,
+        message: "WebGL context recovered via manual restart.",
+        e: {
+          timestamp: Date.now(),
+          method: "manual_restart",
+        },
+      });
+
+      return true;
+    } catch (error) {
+      (window as any).avatarSDKLogger.error("[restartWebGL] Failed:", error);
+      this._reportRecoveryFailure('manual', error);
+      return false;
+    }
+  }
+}