HarmonyOS 7 / API 26 3DGS 重建会话卡住排查进度、取消和后台恢复实战重建会话不是普通按钮点击HarmonyOS 7 / API 26 的 3DGS 端侧重建属于很典型的长任务。它和普通页面请求不一样普通请求失败了大不了提示重试重建任务一旦卡住用户可能已经等了几十秒设备也可能在持续发热页面退出后还可能留下半截状态。所以这类功能不能只写一个“开始重建”按钮。更稳的做法是把它看成一个会话开始、运行、暂停、取消、失败、恢复、落盘每一步都要有状态。我遇到这类问题时优先排查三个点排查点表现处理方向进度是否可信进度停在 40% 或 70% 很久不动给阶段超时和重试入口取消是否完整用户退出后后台还在跑页面销毁时取消或保存任务快照恢复是否可控切后台回来显示旧进度用 sessionId 对齐当前任务这篇只看 3DGS 重建会话本身不讨论模型首屏黑屏也不讨论 Spatial Recon Kit 和 ArkGraphics 3D 的职责边界。前者适合放到模型预览文章里后者适合放到架构边界文章里。这里专门处理“重建任务为什么卡住以及怎么把状态收回来”。官方能力边界和版本前提文章面向 HarmonyOS 7 / API 26。Spatial Recon Kit 负责空间重建相关能力ArkUI 页面负责展示状态和交互持久化层负责保存任务快照和产物路径。不要把长任务状态直接绑在一个页面组件实例上。接入前要先确认三件事当前设备是否支持相关系统能力输入素材是否满足重建要求应用在后台、横竖屏切换、多窗口状态下是否能恢复会话状态。只要这三件事没定住后面写再多进度条都不可靠。案例一进度停在 70% 不动第一个案例是重建进度卡住。页面上看起来还在运行但进度长时间不变化。开发者如果只显示一个百分比用户不知道是慢、卡住还是失败。复现步骤启动一次重建任务模拟某个阶段耗时过长例如特征匹配或 3DGS 表示生成页面进度停在同一个值超过阈值如果没有阶段超时页面会一直显示运行中加入阶段超时后页面能提示“当前阶段耗时过长”并提供取消或重试。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: RecordReconStage, 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 }; }这段映射看起来简单但作用很大。用户看到“运行中”和“偏慢”是不一样的开发者看到日志也能马上知道问题卡在哪个阶段。案例二切后台回来后旧任务状态覆盖新任务第二个案例更接近线上问题。用户开始了一次重建切到后台又回来重新点了一次开始。如果页面只用一个全局状态很容易出现旧任务回调覆盖新任务的问题。复现步骤第一次启动任务生成 sessionIdA应用切后台任务暂停或变慢用户回来后重新发起任务生成 sessionIdB旧任务 A 的回调晚到如果不校验 sessionId页面会被旧状态覆盖。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): PromiseReconCancelResult { 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): Promisevoid { console.info(stop recon session sessionId); } private async keepInputForRetry(inputUri: string): Promisevoid { console.info(keep input inputUri); } private async cleanTempOutput(outputUri: string): Promisevoid { 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每次取消有收尾每个产物能落盘。这样页面才不会在后台恢复、弱设备、复杂素材里失控。