HarmonyOS 7 / API 26 3DGS 重建会话卡住排查：进度、取消和后台恢复实战

重建会话不是普通按钮点击

HarmonyOS 7 / API 26 的 3DGS 端侧重建属于很典型的长任务。它和普通页面请求不一样：普通请求失败了，大不了提示重试；重建任务一旦卡住，用户可能已经等了几十秒，设备也可能在持续发热，页面退出后还可能留下半截状态。

所以这类功能不能只写一个“开始重建”按钮。更稳的做法是把它看成一个会话：开始、运行、暂停、取消、失败、恢复、落盘，每一步都要有状态。

我遇到这类问题时，优先排查三个点：

这篇只看 3DGS 重建会话本身，不讨论模型首屏黑屏，也不讨论 Spatial Recon Kit 和 ArkGraphics 3D 的职责边界。前者适合放到模型预览文章里，后者适合放到架构边界文章里。这里专门处理“重建任务为什么卡住，以及怎么把状态收回来”。

官方能力边界和版本前提

文章面向 HarmonyOS 7 / API 26。Spatial Recon Kit 负责空间重建相关能力，ArkUI 页面负责展示状态和交互，持久化层负责保存任务快照和产物路径。不要把长任务状态直接绑在一个页面组件实例上。

接入前要先确认三件事：

1. 当前设备是否支持相关系统能力；
2. 输入素材是否满足重建要求；
3. 应用在后台、横竖屏切换、多窗口状态下是否能恢复会话状态。

4. 只要这三件事没定住，后面写再多进度条都不可靠。

   案例一：进度停在 70% 不动

   第一个案例是重建进度卡住。页面上看起来还在运行，但进度长时间不变化。开发者如果只显示一个百分比，用户不知道是慢、卡住，还是失败。

   复现步骤

   1. 启动一次重建任务；
   2. 模拟某个阶段耗时过长，例如特征匹配或 3DGS 表示生成；
   3. 页面进度停在同一个值超过阈值；
   4. 如果没有阶段超时，页面会一直显示运行中；
   5. 加入阶段超时后，页面能提示“当前阶段耗时过长”，并提供取消或重试。

   6. type ReconStage = 'prepare' | 'extractFrames' | 'matchFeature' | 'buildGaussian' | 'persist' | 'done';
      
      interface ReconStageState {
        sessionId: string;
        stage: ReconStage;
        percent: number;
        startedAt: number;
        updatedAt: number;
        tips: string;
      }
      
      const STAGE_TIMEOUT: Record<ReconStage, number> = {
        prepare: 5000,
        extractFrames: 15000,
        matchFeature: 30000,
        buildGaussian: 45000,
        persist: 10000,
        done: 0
      };
      
      export class ReconProgressWatchdog {
        isTimeout(state: ReconStageState, now: number): boolean {
          const limit = STAGE_TIMEOUT[state.stage];
          if (limit <= 0) {
            return false;
          }
          return now - state.updatedAt > limit;
        }
      
        buildTimeoutTips(state: ReconStageState): string {
          return '重建任务停在 ' + state.stage + ' 阶段较久，可以先取消并保留输入素材';
        }
      }

      这里不要只看总耗时。总耗时长不一定有问题，因为素材复杂时本来就慢。真正有用的是阶段耗时：哪个阶段长时间没有更新，哪个阶段就要给用户一个明确反馈。

      页面状态要区分运行和卡住

      type ReconViewPhase = 'idle' | 'running' | 'slow' | 'failed' | 'done';
      
      interface ReconViewState {
        phase: ReconViewPhase;
        percent: number;
        primaryText: string;
        secondaryText: string;
        canCancel: boolean;
        canRetry: boolean;
      }
      
      export function mapStageToView(state: ReconStageState, timeout: boolean): ReconViewState {
        if (timeout) {
          return {
            phase: 'slow',
            percent: state.percent,
            primaryText: '重建还在处理，但当前阶段耗时偏长',
            secondaryText: state.tips,
            canCancel: true,
            canRetry: false
          };
        }
      
        return {
          phase: 'running',
          percent: state.percent,
          primaryText: '正在生成 3DGS 空间模型',
          secondaryText: state.tips,
          canCancel: true,
          canRetry: false
        };
      }

      这段映射看起来简单，但作用很大。用户看到“运行中”和“偏慢”是不一样的，开发者看到日志也能马上知道问题卡在哪个阶段。

      案例二：切后台回来后，旧任务状态覆盖新任务

      第二个案例更接近线上问题。用户开始了一次重建，切到后台，又回来重新点了一次开始。如果页面只用一个全局状态，很容易出现旧任务回调覆盖新任务的问题。

      复现步骤

      1. 第一次启动任务，生成 sessionId=A；
      2. 应用切后台，任务暂停或变慢；
      3. 用户回来后重新发起任务，生成 sessionId=B；
      4. 旧任务 A 的回调晚到；
      5. 如果不校验 sessionId，页面会被旧状态覆盖。

      6. interface ReconSessionSnapshot {
           sessionId: string;
           inputUri: string;
           stage: ReconStage;
           percent: number;
           outputUri: string;
           updatedAt: number;
         }
         
         export class ReconSessionStore {
           private currentSessionId: string = '';
           private snapshot: ReconSessionSnapshot | null = null;
         
           start(inputUri: string): ReconSessionSnapshot {
             const sessionId = 'recon-' + Date.now();
             this.currentSessionId = sessionId;
             this.snapshot = {
               sessionId,
               inputUri,
               stage: 'prepare',
               percent: 0,
               outputUri: '',
               updatedAt: Date.now()
             };
             return { ...this.snapshot };
           }
         
           acceptUpdate(next: ReconSessionSnapshot): boolean {
             if (next.sessionId !== this.currentSessionId) {
               return false;
             }
             this.snapshot = { ...next, updatedAt: Date.now() };
             return true;
           }
         
           current(): ReconSessionSnapshot | null {
             return this.snapshot ? { ...this.snapshot } : null;
           }
         
           clear(sessionId: string): void {
             if (sessionId === this.currentSessionId) {
               this.currentSessionId = '';
               this.snapshot = null;
             }
           }
         }

         这里的关键是 acceptUpdate。任何来自重建会话的回调都必须带 sessionId。只有当前会话才允许更新页面。旧任务晚回来，只记录日志，不覆盖 UI。

         取消动作要真正收尾

         重建任务取消不只是把进度条隐藏。至少要做三件事：停止当前会话、保存可恢复信息、释放临时资源。

         interface ReconCancelResult {
           sessionId: string;
           stopped: boolean;
           retainedInput: boolean;
           message: string;
         }
         
         export class ReconCancelController {
           async cancel(session: ReconSessionSnapshot | null): Promise<ReconCancelResult> {
             if (!session) {
               return { sessionId: '', stopped: true, retainedInput: false, message: '没有正在运行的重建任务' };
             }
         
             await this.stopNativeSession(session.sessionId);
             await this.keepInputForRetry(session.inputUri);
             await this.cleanTempOutput(session.outputUri);
         
             return {
               sessionId: session.sessionId,
               stopped: true,
               retainedInput: true,
               message: '已取消重建，输入素材已保留，可以稍后重试'
             };
           }
         
           private async stopNativeSession(sessionId: string): Promise<void> {
             console.info('stop recon session ' + sessionId);
           }
         
           private async keepInputForRetry(inputUri: string): Promise<void> {
             console.info('keep input ' + inputUri);
           }
         
           private async cleanTempOutput(outputUri: string): Promise<void> {
             if (outputUri.length > 0) {
               console.info('clean temp output ' + outputUri);
             }
           }
         }

         这样写的好处是，取消以后用户还能重试，开发者也知道临时产物有没有清掉。不要把取消写成“关闭弹窗”，那只是界面消失了，任务不一定停了。

         推荐的状态流

         阶段	页面表现	技术动作
         prepare	检查设备和输入素材	能力检测、文件校验
         extractFrames	显示素材解析进度	记录阶段开始时间
         matchFeature	提示空间特征匹配	阶段超时监控
         buildGaussian	显示模型生成进度	支持取消和失败恢复
         persist	保存结果	写入产物路径和封面
         done	进入预览	交给 ArkGraphics 3D 展示

         这个状态流不是为了好看，而是为了避免“任务在跑，但没人知道它跑到哪了”。3DGS 重建越耗时，状态越要细。

         最后总结

         3DGS 重建会话卡住时，不要只盯着百分比。百分比只是结果，真正要看的是阶段、更新时间、sessionId、取消动作和恢复策略。

         HarmonyOS 7 / API 26 的 3DGS 能力适合做更有空间感的体验，但接入方式不能停留在 Demo。只要涉及端侧重建，就要把它当成长任务治理：每个阶段有时间边界，每个回调带 sessionId，每次取消有收尾，每个产物能落盘。这样页面才不会在后台恢复、弱设备、复杂素材里失控。