Spatial Recon Kit+Node.js：3DGS导出半写识别门禁【鸿蒙心迹】

李游Leo

13人浏览 · 2026-10-11 15:39:10

李游Leo · 2026-10-11 15:39:10 发布

在展陈应用里，模型导出按钮变成绿色，并不等于这份模型已经可以进入资源库。文件名存在，可能只是输出过程开始了；文件长度看起来足够，也可能是另外一次构建残留的内容。真正容易误判的时间点，是应用刚收到“任务结束”的业务通知，而磁盘上的成果、版本清单和后续消费方尚未形成共同确认。

这篇文章不把三维重建算法再讲一遍，而是把导出结果交接这件小事拆开：什么证据允许标记为待发布，怎样发现只写了一部分的文件，为什么同长度不能代替内容一致，以及故障恢复时该保留哪些信息。以下演示采用应用自定义的Node.js固定输入，没有调用Spatial Recon Kit进行真实导出，也没有解析GS文件内部格式。

一、一个绿色按钮不能覆盖两个事实

假设展馆管理员连续为六个展品生成可供后续处理的重建成果。界面如果只给一条“已导出”，现场人员很自然地认为六份都安全。实际工程中，任务完成和制品可用是两条不同的判断链。前者来自任务状态；后者需要核对目标路径、长度、摘要、批次号，以及发布清单是否已形成可恢复的提交点。

更微妙的情况是重试。重建任务回调可能因为页面切换而晚到，同名文件可能被重新写入；如果只按文件名去重，旧回调有机会把新版本状态盖回去。这里使用taskId=EXP-1011-32、输入清单gallery_export_06、业务代次epoch=5，让“这是谁的证据”先有固定答案。画面中的06:41只是示意时间，不宣称当时发生过真实设备写入。

本例六个资源分别编号M01至M06，前四份完整，M05只写入了预期四分之一的字节，M06的实际长度正确但内容摘要不同。两种问题不可合并成一句“文件异常”：半写应优先调查中断、关闭、重试顺序；摘要不符应调查旧文件复用、内容变更与基线来源。最终业务状态是EXPORT_HOLD，不是整批“完成”。

二、先确认哪些名字属于系统，哪些属于应用

华为Spatial Recon Kit官方资料描述了空间重建和模型输出能力，HMS_SpatialRecon_ModelWriteInfo结构体中的modelFile用于指定输出文件名，文档要求其处于应用文件目录的子目录。modelFormat用于指定输出格式。这些是系统能力边界；EXP-1011-32、EXPORT_HOLD、PARTIAL_WRITE和DIGEST_MISMATCH全是本文业务模型自行定义的名称，不能拿来当官方SDK错误码。

本轮选择Node.js实现离线验收门禁，原因很简单：我们需要能在没有真实重建设备的环境下重复制造半写与同长度篡改。Node提供fs/promises、crypto.createHash和path.resolve，足以做确定性的固定输入演练。生产中真正写模型的模块是另一个接口边界，它必须把结果路径交给门禁，而不是让门禁虚构一个SDK完成事件。

官方结构体存在并不等于所有设备都能执行相同重建能力，平台、系统版本与实际接入条件仍以对应页面标注为准。本例也没有验证GS容器格式、点云完整性、可见性或重建质量。文件的字节级证据只是发布前的一道门，并非内容语义验收；把这两层分开，后面出现渲染失败才知道该去哪一层查。

三、冻结可复现的六份导出候选

本地夹具采用gallery_export_06，每一条记录保存资源ID、规范文件名、预期字节数和预期SHA-256。基线摘要不依赖本次实际读出的内容，而是由此前可信制品快照提供；如果验收时直接把刚读取的摘要同时写回“预期摘要”，比较永远通过，校验就失去意义。本演示用确定性字节数组模拟可信快照与当前文件，便于程序独立重放。

六个候选被固定为：M01gallery_main.gs4096字节，M02detail_hall.gs5120字节，M03atrium_view.gs3072字节，M04trade_corner.gs2048字节，全部通过。M05snapshot_tmp.gs预期4096、实际1024，结果为PARTIAL_WRITE；M06basement.gs预期和实际均为2048，但摘要变化，结果为DIGEST_MISMATCH。

这个列表故意不引入“68%导出进度”。进度条可以表现任务过程，却无法推出文件可验收。批次一共六项，文件级判定四通过、两阻断，整批不得发布。界面如需展示进度，可写6/6已检查，不能写成6/6已经生成成功。后者把被审查数量误当作可交付数量，往往是事故复盘中最难追溯的歧义。

四、第一段代码：把路径纳入证据边界

先解决路径问题。不能相信清单里的相对路径天然安全；即使这些输入今天由测试脚本产生，迁移到真实制品元数据后，也可能出现../目录回退或绝对路径。我们只允许资源位于预期models根目录内部，并使用解析后的绝对路径做判断，避免随便一个同名文件混入验收集合。

import { resolve, sep } from 'node:path';

export function safeModelPath(root, fileName) {
  if (typeof fileName !== 'string' || fileName.length === 0) {
    throw new Error('EMPTY_MODEL_NAME');
  }
  const base = resolve(root);
  const full = resolve(base, fileName);
  if (!full.startsWith(base + sep)) {
    throw new Error('PATH_OUTSIDE_ROOT');
  }
  return full;
}

这里显式排除了根目录本身，避免把目录当文件读取。没有直接使用字符串替换删掉..，因为那会把一个恶意路径“修补”成另一个看似合法的路径。业务上应拒绝而不是替用户猜测目标。进一步用于跨平台时，还需结合符号链接实际路径检查、文件句柄权限和目录属主验证；字符串层面的resolve并不能独自抵御符号链接跳转。

生命周期上，路径检查只发生在读取前，不能把它视为读取完成后的永久保证。实际写入端如果还在修改文件，长度和摘要仍可能随时间变化。生产环境可以先等待写入任务确认关闭，再对同一个文件句柄做核验，必要时采用临时文件与最终文件之间的原子重命名；这些动作不属于本地演示已经完成的范围。

五、第二段代码：长度优先，摘要随后

业务上最常见的省事写法是existsSync(file)之后直接报成功。这只能证明某一瞬间有路径，无法证明内容已经稳定。下面把长度作为第一道快速拦截，完整长度一致后才做摘要读取。短文件不需要再计算哈希；同长度文件反而必须计算。这里所有错误标签都来自自建验收规则，不是Spatial Recon Kit的返回枚举。

import { readFile, stat } from 'node:fs/promises';
import { createHash } from 'node:crypto';

export async function checkOutput(fullPath, expectedBytes, expectedDigest) {
  const fileInfo = await stat(fullPath);
  if (!fileInfo.isFile()) return 'NOT_A_FILE';
  if (fileInfo.size !== expectedBytes) return 'PARTIAL_WRITE';
  const bytes = await readFile(fullPath);
  const actualDigest = createHash('sha256').update(bytes).digest('hex');
  return actualDigest === expectedDigest ? 'PASS' : 'DIGEST_MISMATCH';
}

stat()与readFile()分成了两次访问，因此存在检查时刻与使用时刻差异。本文夹具在两者之间不改写文件，所以重放结果确定；这并不构成并发写入环境下的安全证明。如果资源量很大，readFile可能一次性占用较多内存，真实项目应考虑流式摘要以及输出方完成后再读取的文件快照策略，不能直接照搬到几GB的模型制品。

如果读取过程中遇到ENOENT、权限错误或I/O异常，不应被归入DIGEST_MISMATCH。摘要不同说明字节内容可读且与基线不一样，读不到则需要READ_ERROR等独立原因。本文的六条固定输入没有触发这一分支，但错误分类设计时必须留出它，否则监控报表会把存储不可达与内容损坏混成同一类。

六、IDE示意图只验证说明是否自洽

在文章对应的开发图里，左侧工程树应出现ModelProofLedger、ExportQueuePage.ets、ProofAuditPage.ets、tools/check-export.mjs和fixtures/gallery_export_06.json；中间代码聚焦路径边界及SHA-256判定；最右侧应是名为“导出证据核验”的示意页面，底部HiLog展示任务ID和四通过两阻断。该图是生成式演示，不是DevEco真实运行截图。

我们在内容层面区分三种状态：CHECKING表示门禁仍在扫描；EXPORT_HOLD表示本批存在阻断；EXPORT_READY只在全部证据完整且业务审核确认后才允许出现。当前固定数据永远不能得到EXPORT_READY。一张看起来精美的IDE配图也不能替代日志的可信来源，文章若引用它，只能说明设计结构和预期界面，不能据此宣称设备实际导出成功。

图文契约中的时间统一为2026年10月11日06:41；模拟日志形式为EXP-1011-32 checked=6 pass=4 blocked=2、EXP-1011-32 partial=1 digest=1和EXP-1011-32 EXPORT_HOLD spatialRecon=NOT_RUN。保留固定日志的好处，是下一轮换Demo时也能直接判断图片是否套用了旧批次任务号，不靠肉眼猜同色背景是哪一篇。

七、第三段代码：批次汇总不能越过失败项

单文件检查通过不代表整批可以发布。需要一个明确的汇总门禁，把不可信制品留在隔离集合，并让后续消费方只能查询通过的候选。以下代码假设传入的每条记录已经完成路径与字节验收，只负责计算可见清单，不负责修改磁盘或声称执行了模型输出。

export function buildExportDecision(results) {
  const accepted = results.filter(item => item.result === 'PASS');
  const blocked = results.filter(item => item.result !== 'PASS');
  const counts = new Map();
  for (const item of blocked) {
    counts.set(item.result, (counts.get(item.result) ?? 0) + 1);
  }
  return {
    checked: results.length,
    accepted: accepted.length,
    blocked: blocked.length,
    visibleIds: accepted.map(item => item.id),
    blockedReasons: Object.fromEntries(counts),
    state: blocked.length === 0 ? 'EXPORT_READY' : 'EXPORT_HOLD'
  };
}

这段代码特意让visibleIds只包含M01至M04。即使M05的文件存在，也不能把它提前展示成可分享的模型；即使M06长度正确，也必须保留在故障列表。这里的“可见”只是示例业务清单，不代表已经通过真实模型加载测试。EXPORT_READY也是应用自定义的内部发布许可，不等价于应用商店、Spatial Recon或产品层面的验收通过。

对于并发回调，还应把epoch=5与结果绑定。某次导出被取消后，如果旧代次回调晚到，汇总层必须拒绝将它并入新快照。严谨实现还需要任务归属、幂等提交序号和数据库持久化；本篇只对文件证据做离线核对，不把这些集成措施包装成已经完成的工程事实。

八、模型运行结果与计算边界

本地Node.js复演实际制造了六个小型二进制夹具文件。M01、M02、M03、M04分别使用固定字节内容写入，读取时与预期长度及SHA-256一致；M05写入1024字节而非4096；M06写入2048字节，但内容与预期摘要基线不同。该验证证明的是脚本规则面对这六组输入的分类行为，不证明GS文件内容合理，更不能证明Spatial Recon SDK已经运行。

固定输出统计为total=6、accepted=4、blocked=2，原因计数PARTIAL_WRITE=1、DIGEST_MISMATCH=1，最终EXPORT_HOLD。这里没有人为编造“渲染耗时37ms”“重建模型点数80万”等无从核查的产品指标。测试进程确实能确认几千字节文件的差异，但大模型的流式读写性能、文件系统刷新语义与系统权限仍须在目标设备上另外验证。

将这个结果做成手机主界面时，最好让四份绿色通过项和两份红色阻断项同时可见，并明确运行模式FIXTURE_ONLY、SpatialRecon NOT_RUN。如果画面只显示一张高质量3DGS预览图，反而可能误导读者认为文件已经在系统渲染器中加载；当前演示最多使用静态概念缩略图，不能把缩略图当作模型解码证据。

九、半写文件和摘要不符的排查顺序不同

M05的预期大小4096、实际1024，很像写入未收尾或阶段文件被提前曝光。排查应先看生产者是否正常退出、是否还有写句柄未关闭、写入目标是否落在临时目录，以及重试是否误拿了上次残留路径。只要文件仍可能变化，就不应该把它移到可发布清单；重新跑一遍摘要并不能替代“写入结束”的确认信号。

M06则是另一种情况：2048字节的长度完全吻合，直接按长度放行会造成假阳性。此时要核实生成任务的输入版本、摘要基线生成时点、路径是否被其他批次复用，并排查是否把“当前文件摘要”误填到预期字段。若基线本身不可信，哈希计算再准确也无法说明对象正确，需要引入可信的签名或受控元数据发布流程。

故障界面不应提供一个无差别的“忽略所有警告”按钮。半写场景适合重新生成并替换阶段产物；摘要不符适合保留原件用于诊断，禁止覆盖可信版本。两者都需要操作者明确选择下一步，并对被拒绝的文件保留可复现的证据，而不是自动把红色标签改成绿色。

十、截图中的异常页应该承担证据作用

诊断页至少要显示M05、M06的文件名、预期/实际长度、被阻断原因和epoch=5。PARTIAL_WRITE与DIGEST_MISMATCH要让普通开发者一眼能区分，并有一条醒目说明：此页为本地夹具核验，不涉及真实GS解析、模型输出或设备文件写入。配图最多说明预期产品信息层级，不能拿截图中的“通过”字样替代可运行测试脚本。

如果展示日志时间线，建议使用顺序明确的06:41:11 LOAD、06:41:12 CHECK M01-M04、06:41:13 BLOCK M05、06:41:14 BLOCK M06、06:41:15 EXPORT_HOLD。时间线来自固定演示契约而不是系统HiLog采样记录；真实集成后应另加文件句柄、线程与业务任务序列号，避免多个导出任务日志互相穿插造成判断失真。

程序日志值得保留的是最小定位字段：任务ID、文件ID、算法版本、预期字节、实际字节、摘要比较结果和终态。不建议把完整资源文件路径与敏感业务名称无条件传给远程日志，因为展馆或客户的目录可能包含项目名称。日志既要方便排障，也要遵守最小披露原则，这与是否使用空间计算能力无冲突。

十一、什么时候才轮到真正的Spatial Recon接入

本地规则能回答“文件按事先约定的长度和摘要是否一致”，却不能回答“这是否是可渲染的3DGS模型”。真实接入时应从官方版本对应的输出流程取得实际文件路径，遵守应用沙箱目录约束，并在导出结束、资源释放后再启动本门禁。如果应用使用了本地C/C++接口，输出结构、指针有效期和所有权还要按当前SDK头文件核对。

有三个界限必须写在交付说明里。第一，modelFile是官方结构体字段，本文的清单JSON字段expectedSha256不是。第二，EXPORT_HOLD是自建业务终态，不是系统回调。第三，当前没有实测数据证明不同设备对文件写入刷盘、重命名以及GS扩展名采用相同语义。任何把这些假设写成官方保证的文章，都会给后续开发者留下隐患。

如果以后需要加入断点续传，也不应直接把某个分块的成功视作整个模型成功。应该在每个分块附带不可变的任务ID、偏移与摘要，并在最终组装完成后再计算整体摘要；重试同一个分块要按幂等键检查，不允许重复追加导致总长度看似正常却内容顺序错误。这是下一阶段可以扩展的架构判断，而不是当前六条夹具已经覆盖的验收能力。

十二、用反例保护实现范围

一个很好的反例是对M06只看stat.size，会得到五份“通过”，这与正确的四份有明显差距。另一个反例是遇到M05短文件时用零字节补齐，会使预期长度看似一致，却没有任何理由认为补齐后的内容是正确模型。第三个反例是把EXPORT_HOLD改成EXPORT_READY供UI演示，这会让截图好看，但违反了工程状态的实际含义。

本地回归可把这三个反例放进自动检查脚本：如果摘要核验被删去，M06必须导致测试失败；如果短文件被补齐后强行接受，M05必须导致测试失败；如果批次有任何阻断仍输出READY，汇总测试也必须失败。这样的逆向断言比单纯“测试脚本输出PASS”更能抵御未来维护人员的意外简化。

测试数据的生成策略也应写入台账，包括六个文件的大小、构造字节与预期分类。不能把通过率“4/6”写成应用在生产中的可靠性指标，它只是一组刻意覆盖分支的样本。若要评价真实模型导出可靠性，还需足够长的设备运行记录、失败采样、设备型号分布、存储空间与异常断电场景，跟本次固定演练完全不是同一件事。

十三、性能与内存的现实取舍

采用SHA-256有一个直接代价：需要读取全部文件内容。小夹具只有几KB，性能压力几乎可以忽略；真实展陈模型可能大得多，全量读入缓冲区既占内存也会干扰同机渲染。生产方案应考虑流式哈希、校验队列限流与磁盘I/O预算，并在低电量或后台状态下遵守系统资源约束，不能拿Node测试环境的执行速度推断手机端表现。

另一个取舍是同步还是异步。导出完成回调触发后，可以把校验任务排入单独的串行队列，先明确CHECK_PENDING而不是直接弹出“发布完成”。若用户此时关闭页面，后台任务是否继续必须由应用生命周期与平台后台机制决定。不能因为脚本有async/await，就假定系统一定允许它在后台无限运行。

用户可感知的反馈也不应该只有一个笼统百分比。更实用的是显示“已核验4项、等待2项异常处理”，同时允许复制非敏感的诊断代码。这样产品人员不用理解什么是哈希，也能知道当下是“不能分享”而不是“还剩2个文件没下载”。对流程边界的表达本身就是工程质量的一部分。

十四、验收清单应该先要求证据，再要求体验

这个Demo的验收层次有明确先后。第一层是固定输入规则：路径不能越界，六项按预期分类，摘要不符不能混入通过集合。第二层是集成校验：真实导出事件与产物路径能可靠对应，页面销毁后旧回调不覆盖新代次，存储失败能形成独立的可恢复状态。第三层才是真实设备上的模型加载、渲染质量和资源占用验收。

当前只做到了第一层中的一部分。模型生成、真实GS解析、SDK调用与设备性能全部标记为NOT_RUN。这不是为了把演示写得保守，而是为了让下一位接手的人知道哪些论断已经可以重放，哪些仍只是设计。尤其不能把漂亮的IDE示意图当成“已经通过DevEco编译”的证据，文章中的脚本使用的是Node.js独立执行环境。

跨批次去重也应采用同样的证据观。本篇与此前涉及3DGS姿态正交判定的内容共享技术背景，但具体工程问题已变为导出结果的字节级完整性与发布门禁；与此前PixelMap租约屏障不同，这里不讨论图像对象释放，而讨论文件产物生命周期。相同方向允许继续深入，但不能只改一个Demo名再重复旧结论。

十五、留给下一次集成的接口边界

若要把ModelProofLedger真正接到HarmonyOS工程，建议将生产者、证据采集者、发布者分成三个角色。生产者只生成制品并报告自己的任务阶段；证据采集者在文件稳定后检查路径、长度与摘要；发布者只消费经过验收的清单快照。这样即使未来更换输出格式或使用不同重建服务，发布条件也不需要随着页面按钮逻辑大幅修改。

三者之间传递的不是简单布尔值，而是含taskId、epoch、manifestVersion、fileId和结果摘要的结构化记录。任何旧代次的完成通知都只能归档，不能覆盖当前快照。对于重试任务，应在同一任务号下增加尝试序列，避免把不同尝试写到同一个文件名。如何做到原子提交、如何限制校验并发、如何治理长期积累的失败文件，是上线前尚未解决的工程工作。

这次固定演练的结论很克制：六份候选中四份证据完整、两份必须阻断，业务状态保持EXPORT_HOLD。它证明了把半写与摘要不符拆成不同原因的价值，没有证明任何一次真实3DGS重建已成功。后续只有把官方输出接口、文件稳定确认、真实设备测试与这份规则连接起来，才能把“文件存在”升级为“可交接的模型证据”。

十六、资料与边界说明

官方参考：华为《HMS_SpatialRecon_ModelWriteInfo》，更新日期2026-08-29，https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/api/capi-spatialrecon-hms-spatialrecon-modelwriteinfo；华为HarmonyOS空间计算能力介绍，https://developer.huawei.com/consumer/cn/features/spatialization。前者用于核对modelFile和modelFormat的官方字段及起始系统要求，后者用于确定3DGS端侧重建属于何种平台能力。

本文代码为可在Node.js环境独立测试的业务示例。gallery_export_06是固定文件夹中的小型二进制夹具，数据源、SHA-256基线、异常原因和终态全部由应用示例定义；没有华为设备上的导出测试结果，也没有声称通过DevEco Studio、AppGallery Connect或任何真机模型质量验收。读者将其迁移到实际项目时，需要重新核对SDK版本、设备条件、文件权限和调用生命周期。