@xmov/avatar 2.0.0-alpha.61 → 2.0.0-alpha.63

package/dist/modules/sentry-reporter.d.ts

@@ -0,0 +1,58 @@
+import type { SDKError } from 'types/error';
+export interface SentryReporterOptions {
+    /** Traces 采样率，默认 1.0（100% 全量） */
+    tracesSampleRate?: number;
+}
+/** span 附加属性（兼容 Sentry SpanAttributeValue 的标量子集） */
+type SpanData = Record<string, string | number | boolean | undefined>;
+/**
+ * Sentry 错误上报器（隔离实例）
+ *
+ * 使用独立的 BrowserClient + Scope，不污染宿主应用的全局 Sentry 状态。
+ * 此文件仅在公有云构建（ENABLE_SENTRY=true）时被打包，
+ * 私有化构建时通过编译时常量 + 死代码消除完全移除。
+ */
+export declare class SentryReporter {
+    private client;
+    private scope;
+    private tracesSampleRate;
+    constructor(dsn: string, options?: SentryReporterOptions);
+    /**
+     * 上报 SDK 错误
+     */
+    captureError(error: SDKError): void;
+    /**
+     * 在隔离 scope 上启动一个 span 并执行回调，回调返回时自动结束。
+     * 异常时 span 自动标记 error（由 startSpan 内部处理），span 数据发往本实例的 DSN。
+     */
+    startSpan<T>(name: string, ctx: {
+        op?: string;
+        data?: SpanData;
+    }, fn: () => T): T;
+    /**
+     * 启动一个手动管理生命周期的 span（跨回调/异步时用），
+     * 返回的句柄在操作完成时调用 end() 结束 span。
+     */
+    startInactiveSpan(name: string, ctx: {
+        op?: string;
+        data?: SpanData;
+    }): {
+        end(): void;
+    };
+    /**
+     * 设置全局标签
+     */
+    setTag(key: string, value: string): void;
+    /**
+     * 设置用户信息
+     */
+    setUser(user: {
+        id?: string;
+        ip_address?: string;
+    }): void;
+    /**
+     * 销毁 Sentry 客户端，flush 未发送的事件
+     */
+    destroy(): Promise<void>;
+}
+export {};

package/dist/types/index.d.ts

@@ -96,9 +96,18 @@ export interface IAvatarOptions {
      */
     onAudioPlaybackData?(data: IAudioPlaybackData): void;
     /**
-     * 每帧数据回调
-     * 返回当前帧的 face + body 原始数据（帧号、body_id 等）
+     * Sentry 错误监控配置
+     * 仅在公有云构建（ENABLE_SENTRY=true）时生效，私有化构建会忽略此配置
+     * 设为 { enabled: false } 可禁用 Sentry 上报
      */
+    sentry?: {
+        enabled?: boolean;
+        /**
+         * 性能 Traces 采样率（0-1），默认 1.0（100% 全量）
+         * 容量受限时可下调，如 0.1（10%）
+         */
+        tracesSampleRate?: number;
+    };
     onFrameDataUpdate?(data: IFrameDataUpdate): void;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmov/avatar",
-  "version": "2.0.0-alpha.61",
+  "version": "2.0.0-alpha.63",
   "description": "魔珐数字人 JS-SDK",
   "type": "module",
   "source": "src/index.ts",
@@ -43,13 +43,14 @@
     "!dist/agent/microphone.d.ts"
   ],
   "scripts": {
-    "build": "pnpm run build:core && pnpm run build:agent && pnpm run build:e2e:cdn && pnpm run test:e2e:cdn && node upload-sdk.js build",
-    "build:core": "microbundle --workers --define ENV=production,VERSION=$npm_package_version --external none --tsconfig tsconfig.json",
-    "build:agent": "microbundle --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json --no-sourcemap && node scripts/build-agent-entry.mjs",
+    "build": "pnpm run build:core && pnpm run build:agent && pnpm run build:e2e:cdn && pnpm run test:e2e:cdn && node scripts/upload-sourcemaps.mjs && node upload-sdk.js build",
+    "build:core": "microbundle --workers --define ENV=production,VERSION=$npm_package_version,ENABLE_SENTRY=true,SENTRY_DSN='https://aabed165326fc7a2a276b49aa4043be3@xmovsentry.xmov.ai/32' --external none --tsconfig tsconfig.json",
+    "build:agent": "microbundle --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json --no-sourcemap --define ENV=production,VERSION=$npm_package_version,ENABLE_SENTRY=true,SENTRY_DSN='https://aabed165326fc7a2a276b49aa4043be3@xmovsentry.xmov.ai/32' && node scripts/build-agent-entry.mjs",
+    "build:private": "microbundle --workers --define ENV=production,VERSION=$npm_package_version,ENABLE_SENTRY=false,SENTRY_DSN='' --external @sentry/browser --tsconfig tsconfig.json && node scripts/strip-sentry-imports.mjs && pnpm run build:agent",
     "build:e2e:cdn": "microbundle --entry src/agent/cdn-entry.ts --output cdn-dist/xmovAvatar_e2e.js --format iife --external none --workers --define ENV=production,VERSION=$npm_package_version --tsconfig tsconfig.agent.json --no-pkg-main --no-sourcemap",
     "sdk": "pnpm --filter @xmov/avatar run --parallel --no-bail \"/^sdk:.+$/\"",
-    "sdk:core": "microbundle watch --workers --define ENV=development,VERSION=$npm_package_version --external none --tsconfig tsconfig.json",
-    "sdk:agent": "node scripts/build-agent-entry.mjs && microbundle watch --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json",
+    "sdk:core": "microbundle watch --workers --define ENV=development,VERSION=$npm_package_version,ENABLE_SENTRY=true,SENTRY_DSN='https://aabed165326fc7a2a276b49aa4043be3@xmovsentry.xmov.ai/32' --external none --tsconfig tsconfig.json",
+    "sdk:agent": "node scripts/build-agent-entry.mjs && microbundle watch --entry src/agent/index.ts --output dist/agent --format modern,esm,cjs,umd --external @xmov/avatar --alias ../index=@xmov/avatar --globals @xmov/avatar=XmovAvatar --name XingyunAvatarAgentModule --tsconfig tsconfig.agent.json --define ENV=development,VERSION=$npm_package_version,ENABLE_SENTRY=true,SENTRY_DSN='https://aabed165326fc7a2a276b49aa4043be3@xmovsentry.xmov.ai/32'",
     "app": "cd app/ && npm run dev",
     "app:lan": "pnpm --dir app dev:lan",
     "test:agent": "node scripts/run-agent-tests.mjs",
@@ -95,6 +96,7 @@
     "ws": "^8.21.1"
   },
   "dependencies": {
+    "@sentry/browser": "^10.69.0",
     "blueimp-md5": "^2.19.0",
     "protobufjs": "^7.5.4"
   },

package/src/global.d.ts

@@ -1,4 +1,11 @@
 // src/global.d.ts
+
+// 编译时常量声明（通过 microbundle --define 注入）
+declare const VERSION: string;
+declare const ENV: string;
+declare const ENABLE_SENTRY: boolean;
+declare const SENTRY_DSN: string;
+
 // 1. 声明全局 protobuf 对象（适配 protobufjs UMD 格式）
 declare namespace globalThis {
   const protobuf: {

package/src/index.ts

@@ -8,6 +8,7 @@ import Ttsa from "./control/ttsa";
 import { DebugOverlay } from "./view/DebugOverlay";
 import NetworkMonitor from './modules/network';
 import Errors from './modules/error-handle';
+import { SentryReporter } from './modules/sentry-reporter';
 
 import { performanceConstant } from "./utils/perfermance";
 import  './utils/logger.js';
@@ -47,6 +48,9 @@ export default class XmovAvatar {
   private ttsa: Ttsa | null = null;
 
   private debugOverlay: DebugOverlay | null = null;
+  private sentryReporter: SentryReporter | null = null;
+  /** 首帧 span 句柄（init 时启动，首次 BODY 帧到达时结束） */
+  private firstFrameSpan: { end(): void } | null = null;
 
   private _offlineTimer = -1
   private readonly _offlineInterval = 300
@@ -570,6 +574,25 @@ export default class XmovAvatar {
       return;
     }
 
+    // 初始化 Sentry 错误监控（编译时常量 + 运行时配置双重控制）
+    // 编译时 ENABLE_SENTRY 决定代码是否打包，运行时 sentry.enabled 决定是否启用
+    // 提前到资源加载之前创建，使 init / resource_load span 可覆盖整个初始化过程
+    if (ENABLE_SENTRY && this.options.sentry?.enabled) {
+      try {
+        this.sentryReporter = new SentryReporter(SENTRY_DSN, {
+          tracesSampleRate: this.options.sentry?.tracesSampleRate,
+        });
+        this.sentryReporter.setTag('app_id', this.options.appId || '');
+        this.sentryReporter.setTag('env', this._env);
+      } catch (e) {
+        (window as any).avatarSDKLogger.warn(this.TAG, 'Sentry 初始化失败', e);
+      }
+    }
+    // sdk.init：初始化总耗时（含资源加载、连接就绪）
+    const initSpan = this.sentryReporter?.startInactiveSpan('sdk.init', { op: 'init' });
+    // sdk.first_frame：从初始化到首个 body 帧到达（handleMessage 首次 BODY 帧时结束）
+    this.firstFrameSpan = this.sentryReporter?.startInactiveSpan('sdk.first_frame', { op: 'render' }) ?? null;
+
     const { onDownloadProgress, initModel } = params;
     this.onDownloadProgress = (progress: number) => {
       if(progress === 15) {
@@ -586,17 +609,24 @@ export default class XmovAvatar {
       this.pendingInvisibleMode = true;
     }
 
-    // 加载资源
+    // 加载资源（sdk.resource_load：资源包下载/解析耗时）
     (window as any).performanceTracker.markStart(performanceConstant.load_resource);
     (window as any).performanceTracker.markStart(performanceConstant.first_avatar_render);
     (window as any).performanceTracker.markStart(performanceConstant.first_webgl_render);
-    const sessionInfo = await this.resourceManager.load(this.onDownloadProgress.bind(this));
+    const downloadProgress = this.onDownloadProgress;
+    const sessionInfo = this.sentryReporter
+      ? await this.sentryReporter.startSpan('sdk.resource_load', { op: 'resource.load' }, () =>
+          this.resourceManager.load(downloadProgress.bind(this))
+        )
+      : await this.resourceManager.load(downloadProgress.bind(this));
     // 如果在load过程中被销毁了，直接返回，避免继续初始化
     if(this.destroyed) {
+      initSpan?.end();
       (window as any).avatarSDKLogger.warn(this.TAG, "sdk destroyed during load, aborting after resourceManager load");
       return
     };
     if(!sessionInfo?.socket_io_url || !sessionInfo?.token) {
+      initSpan?.end();
       (window as any).avatarSDKLogger.error(this.TAG, "init error, socket_io_url or token is empty reload");
       return
     };
@@ -613,6 +643,7 @@ export default class XmovAvatar {
 
     window.addEventListener('beforeunload', this.handleBeforeUnload);
     document.addEventListener('visibilitychange', this.boundVisibilityChange);
+    initSpan?.end();
     return sessionInfo;
   }
 
@@ -1140,6 +1171,9 @@ export default class XmovAvatar {
             timestamp: Date.now(),
           });
           this.isfirstReceive = false;
+          // 结束 sdk.first_frame span（首帧数据到达）
+          this.firstFrameSpan?.end();
+          this.firstFrameSpan = null;
         }
         // 处理下行数据
         this.renderScheduler.handleData(type, data);
@@ -1374,6 +1408,14 @@ export default class XmovAvatar {
     window.removeEventListener("beforeunload", this.handleBeforeUnload);
     document.removeEventListener("visibilitychange", this.boundVisibilityChange);
 
+    // 清理 Sentry 客户端
+    if (ENABLE_SENTRY && this.sentryReporter) {
+      try {
+        this.sentryReporter.destroy();
+      } catch {}
+      this.sentryReporter = null;
+    }
+
     (window as any).avatarSDKLogger.log(this.TAG, "SDK 已销毁");
   }
 
@@ -1432,6 +1474,16 @@ export default class XmovAvatar {
 
   speak(ssml: string, is_start: boolean = true, is_end: boolean = true, extra = {client_speak_id: '', client_frame: 0}): string | undefined{
     if (this._isClientMode) { this._apiForwarder?.speak(ssml, is_start, is_end, extra); return; }
+    if(this.sentryReporter) {
+      return this.sentryReporter.startSpan('sdk.speak', {
+        op: 'speak',
+        data: { client_speak_id: extra.client_speak_id },
+      }, () => this.speakInternal(ssml, is_start, is_end, extra));
+    }
+    return this.speakInternal(ssml, is_start, is_end, extra);
+  }
+
+  private speakInternal(ssml: string, is_start: boolean = true, is_end: boolean = true, extra = {client_speak_id: '', client_frame: 0}): string | undefined{
     if(this.enableClientInterrupt && is_start) {
       this.renderScheduler.interrupt("speak");
     }
@@ -1578,6 +1630,15 @@ export default class XmovAvatar {
     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);
+      }
+    }
+
     this.ttsa?.send("client_error", params);
     this.debugOverlay?.addError(e)
   }
@@ -1691,7 +1752,13 @@ export default class XmovAvatar {
         return;
       }
       try {
-        const result = await this._reload();
+        // sdk.reconnect：单次重连耗时，带轮次/次数 tag
+        const result = this.sentryReporter
+          ? await this.sentryReporter.startSpan('sdk.reconnect', {
+              op: 'reconnect',
+              data: { round: this.retryRound, count: this.retryCount },
+            }, () => this._reload())
+          : await this._reload();
         if (!this.isRetrying || this.destroyed) {
           return;
         }

package/src/modules/sentry-reporter.ts

@@ -0,0 +1,171 @@
+import {
+  BrowserClient,
+  defaultStackParser,
+  getDefaultIntegrations,
+  makeFetchTransport,
+  Scope,
+  browserTracingIntegration,
+  startSpan,
+  startInactiveSpan,
+} from '@sentry/browser';
+
+import type { SDKError } from 'types/error';
+
+/** 渲染噪音 / 数据过期等高频低危错误码，直接过滤不上报 */
+const NOISE_ERROR_CODES = ['3205', '3206', '3305', '30005'];
+
+export interface SentryReporterOptions {
+  /** Traces 采样率，默认 1.0（100% 全量） */
+  tracesSampleRate?: number;
+}
+
+/** span 附加属性（兼容 Sentry SpanAttributeValue 的标量子集） */
+type SpanData = Record<string, string | number | boolean | undefined>;
+
+/**
+ * Sentry 错误上报器（隔离实例）
+ *
+ * 使用独立的 BrowserClient + Scope，不污染宿主应用的全局 Sentry 状态。
+ * 此文件仅在公有云构建（ENABLE_SENTRY=true）时被打包，
+ * 私有化构建时通过编译时常量 + 死代码消除完全移除。
+ */
+export class SentryReporter {
+  private client: BrowserClient;
+  private scope: Scope;
+  private tracesSampleRate: number;
+
+  constructor(dsn: string, options: SentryReporterOptions = {}) {
+    this.tracesSampleRate = options.tracesSampleRate ?? 1.0;
+
+    // 过滤掉依赖全局状态的集成，避免与宿主应用的 Sentry 实例冲突
+    const integrations = getDefaultIntegrations({}).filter(
+      (i) =>
+        ![
+          'BrowserApiErrors',
+          'BrowserSession',
+          'Breadcrumbs',
+          'GlobalHandlers',
+          'FunctionToString',
+          'Dedupe',      
+        ].includes(i.name),
+    );
+
+    // 显式加入 BrowserTracing（getDefaultIntegrations 未包含），
+    // 关闭页面加载/导航/请求自动追踪，只保留手动 startSpan 埋点，避免噪音 span
+    integrations.push(
+      browserTracingIntegration({
+        instrumentPageLoad: false,
+        instrumentNavigation: false,
+        traceFetch: false,
+        traceXHR: false,
+      }),
+    );
+
+    this.client = new BrowserClient({
+      dsn,
+      transport: makeFetchTransport,
+      stackParser: defaultStackParser,
+      integrations,
+      release: `xmov-avatar@${VERSION}`,
+      tracesSampleRate: this.tracesSampleRate,
+      beforeSend(event) {
+        // ① 白名单：仅上报 SDK 自身错误（source 标签由 scope 打标），过滤宿主页面异常
+        if (event.tags?.source !== 'xmov-avatar-sdk') {
+          return null;
+        }
+        // ② 噪音码过滤：高频渲染噪音 / 数据过期类，避免事件量过大
+        const errorCode = String(event.tags?.error_code ?? '');
+        if (NOISE_ERROR_CODES.includes(errorCode)) {
+          return null;
+        }
+        // ③ 指纹去重：按「错误码 + 消息前缀」合并，同码同消息收敛为一个 Issue
+        event.fingerprint = [
+          errorCode || 'unknown',
+          String(event.message ?? '').slice(0, 64),
+        ];
+        // ④ 上下文补全：浏览器/UA（app_id / session_id 等已在 scope 打标）
+        event.contexts = {
+          ...(event.contexts ?? {}),
+          browser: { name: navigator.userAgent.slice(0, 200) },
+        };
+        return event;
+      },
+    });
+
+    this.scope = new Scope();
+    this.scope.setClient(this.client);
+    this.scope.setTag('sdk_version', VERSION);
+    this.scope.setTag('source', 'xmov-avatar-sdk');
+    this.client.init();
+  }
+
+  /**
+   * 上报 SDK 错误
+   */
+  captureError(error: SDKError): void {
+    // 在隔离 scope 上设置本次错误的标签和上下文
+    this.scope.setTag('error_code', String(error.error_code));
+    this.scope.setTag('error_name', error.error_name);
+    this.scope.setTag('session_id', error.session_id);
+    this.scope.setExtra('code', error.code);
+    this.scope.setExtra('client_speak_id', error.client_speak_id);
+    this.scope.setExtra('timestamp', error.timestamp);
+    if (error.originalError) {
+      this.scope.setExtra('originalError', error.originalError);
+    }
+    this.scope.captureException(new Error(error.message));
+  }
+
+  /**
+   * 在隔离 scope 上启动一个 span 并执行回调，回调返回时自动结束。
+   * 异常时 span 自动标记 error（由 startSpan 内部处理），span 数据发往本实例的 DSN。
+   */
+  startSpan<T>(name: string, ctx: { op?: string; data?: SpanData }, fn: () => T): T {
+    return startSpan(
+      {
+        name,
+        op: ctx.op,
+        scope: this.scope,
+        attributes: ctx.data,
+      },
+      () => fn(),
+    );
+  }
+
+  /**
+   * 启动一个手动管理生命周期的 span（跨回调/异步时用），
+   * 返回的句柄在操作完成时调用 end() 结束 span。
+   */
+  startInactiveSpan(name: string, ctx: { op?: string; data?: SpanData }): { end(): void } {
+    const span = startInactiveSpan({
+      name,
+      op: ctx.op,
+      scope: this.scope,
+      attributes: ctx.data,
+    });
+    return {
+      end: () => span?.end(),
+    };
+  }
+
+  /**
+   * 设置全局标签
+   */
+  setTag(key: string, value: string): void {
+    this.scope.setTag(key, value);
+  }
+
+  /**
+   * 设置用户信息
+   */
+  setUser(user: { id?: string; ip_address?: string }): void {
+    this.scope.setUser(user);
+  }
+
+  /**
+   * 销毁 Sentry 客户端，flush 未发送的事件
+   */
+  async destroy(): Promise<void> {
+    await this.client.close(2000);
+  }
+}

package/src/types/index.ts

@@ -111,6 +111,19 @@ export interface IAvatarOptions {
    */
   onAudioPlaybackData?(data: IAudioPlaybackData): void;
   /**
+   * Sentry 错误监控配置
+   * 仅在公有云构建（ENABLE_SENTRY=true）时生效，私有化构建会忽略此配置
+   * 设为 { enabled: false } 可禁用 Sentry 上报
+   */
+  sentry?: {
+    enabled?: boolean
+    /**
+     * 性能 Traces 采样率（0-1），默认 1.0（100% 全量）
+     * 容量受限时可下调，如 0.1（10%）
+     */
+    tracesSampleRate?: number
+  }
+  /*
    * 每帧数据回调
    * 返回当前帧的 face + body 原始数据（帧号、body_id 等）
    */