项目：FrameGuard · FR-204
写作方式：工程问题复盘 / 输入数据前置门禁
说明：文中全部批次、照片序号和界面日志为构造的技术示例，并非本人实测或真实设备截图。

从哪里开始：不是重建慢，而是输入包先天不齐

给3DGS端侧重建准备图像时，容易把注意力放在算法耗时、设备发热和模型输出上。实际上，有一类问题应当在进入重建阶段以前拦住：操作者以为拍摄了二十张，落盘目录却只有十八张，另外两张在传输或保存期间消失了。如果此时直接把文件名按字典序排好交给下一阶段，失败出现得很晚，定位时还要回头追查采集链路。这个问题不需要声称掌握某个系统重建接口才能讨论，它本质上是输入资料的一致性校验。

本文以一个虚构的文旅建筑采集任务为例，约定批次号为 FR-204，预分配帧号001至020，目录最终只有十八张，其中007和014缺失。检查后的结论必须是 BLOCKED，而不是把已有的十八张重新编号为001至018。重新编号看似填平空洞，实际上抹掉了“采集阶段曾经断开”的证据；以后结合时间戳或相机位姿时，会误以为素材没有发生中断。

华为官方空间计算能力页面介绍了3DGS端侧重建这一能力，具体接入与设备支持仍应按照对应版本的Spatial Recon Kit资料和实际设备核验。本文只建立重建输入前的帧序审计环节，使用可验证的Node.js文件系统能力，不编造重建启动、进度回调或模型导出API。这个边界很重要：输入检查通过，不等于图像质量、相机参数和最终建模结果已经达标。

约定一个足够小、能追责的数据契约

先给采集过程一个明确的编号规则：每次准备写入图像，先在队列中保留下一帧编号，保存成功后才把文件纳入可交付清单；失败时保留该编号的失败记录，而不是复用它。演示输入放在frames/目录，采用frame_001.jpg这样的固定三位编号。这不是相机输出格式的系统规定，而是FrameGuard自己定义的数据契约。若现场采用视频抽帧、照片资产URI或服务端对象存储，只要在进入此审计器前映射成统一清单，校验逻辑仍可复用。

下面的配置不是系统框架配置，而是本项目自己约定的批次说明。它特意把预期数量写死，不从现有文件数量反推：

{
  "taskId": "FR-204",
  "expectedFrames": 20,
  "filePattern": "frame_###.jpg",
  "statusOnMissing": "BLOCKED",
  "sampleMissing": ["007", "014"]
}

执行时应区分四种异常。第一种是缺号，代表预期位次不存在；第二种是同号不同扩展名，例如frame_008.jpg与frame_008.jpeg同时出现；第三种是越界，例如误混入上一批的frame_021.jpg；第四种是伪装成图像名的目录或符号链接。前三种会阻止交付，第四种不应被当作有效帧。这个检查无法判断照片是不是模糊，也无法判断该角度是否足以建模；它只回答“声明过的帧序是否齐整、唯一且在范围内”。

把审计写成纯文件系统步骤，而不是依赖某个重建SDK

下面是Node.js版本的关键实现。为了让读者复用，完整版同时放在压缩包examples/audit-frames.mjs中；这里只展示核心流程。lstat用于避免把软链接当作普通输入文件，Map按数字帧号汇总，最后在与结果文件同一目录写临时文件并重命名。重命名减小了读取者看到半份JSON的机会，但不能替代断电持久化保证，不应把它夸大为跨磁盘事务。

import { readdir, lstat, writeFile, rename } from 'node:fs/promises';
import { join, dirname } from 'node:path';

const taskId = 'FR-204';
const expectedFrames = 20;
const folder = process.argv[2]; // 由调用者提供本地采集目录
if (!folder) throw new Error('usage: node audit-frames.mjs <frames-dir>');
const found = new Map();
for (const name of await readdir(folder)) {
  const match = /^frame_(\d{3})\.(jpg|jpeg)$/i.exec(name);
  if (!match || !(await lstat(join(folder, name))).isFile()) continue;
  const id = Number(match[1]);
  found.set(id, [...(found.get(id) ?? []), name]);
}
const missing = Array.from({ length: expectedFrames }, (_, n) => n + 1)
  .filter(id => !found.has(id)).map(id => String(id).padStart(3, '0'));
const duplicate = [...found].filter(([, names]) => names.length > 1)
  .map(([id]) => String(id).padStart(3, '0'));
const outside = [...found.keys()].filter(id => id < 1 || id > expectedFrames);
const status = missing.length || duplicate.length || outside.length ? 'BLOCKED' : 'READY';
const report = { taskId, expectedFrames, available: [...found].filter(([id]) =>
  id >= 1 && id <= expectedFrames).length, missing, duplicate, outside, status };
const target = join(dirname(folder), 'report.json');
await writeFile(target + '.tmp', JSON.stringify(report, null, 2) + '\n');
await rename(target + '.tmp', target);
console.log(`[${taskId}] ${status} ${report.available}/${expectedFrames} FRAME_GAP=${missing.join(',') || '-'}`);
process.exitCode = status === 'READY' ? 0 : 2;

这段代码刻意不引入不存在的HarmonyOS JS接口，也没有尝试扫描图库系统目录。folder是开发者已合法取得并整理好的工作目录，脚本运行在开发机Node.js环境。若素材来自手机端，应该先通过应用具备权限的导出流程形成输入目录，再执行检查；绝不能据此推导出脚本能直接读取任意手机照片。

把失败显示成可复核信息

前置门禁不能只返回布尔值。实际团队需要知道“哪一张该重拍、是什么批次、是否允许继续”，所以报告里保留预期数、有效帧号数和具体缺口。示例FR-204得到的是十八比二十，缺007,014，状态BLOCKED。这里的available按有效编号统计；如果同一编号出现两种扩展名，虽然磁盘有两个文件，也不会把它计成两帧。这个区别能防止统计好看而原始问题仍在。

开发阶段可以将结果JSON作为本地开发预览的数据源，再由ArkUI绘制一个状态页。以下片段只有普通页面展示能力，没有连接真实建模过程；它特别避免把“点击修复”伪装成已经重新采集。@State控制页面内容，模拟器显示的数字与报告完全一致：

@Entry
@Component
struct FrameReportPage {
  @State taskId: string = 'FR-204';
  @State expected: number = 20;
  @State available: number = 18;
  @State status: string = 'BLOCKED';
  @State missing: string = '007、014';
  build() {
    Column({ space: 18 }) {
      Text('3DGS 输入帧序检查').fontSize(24).fontWeight(FontWeight.Bold)
      Text(`任务 ${this.taskId}`)
      Text(`${this.available} / ${this.expected} 帧`).fontSize(32)
      Text(this.status).fontColor(Color.Red)
      Text(`缺少帧号：${this.missing}`)
      Button('重新核对采集目录').onClick(() => {
        console.info('[FR-204] request local rescan (demo only)');
      })
    }.padding(24).width('100%')
  }
}

这张DevEco Studio风格图片完全是合成示意：界面中的FRAME_GAP 007,014是计划中的演示日志，不代表真的使用IDE编译成功，也不代表照片已经在设备端拍摄完成。与其放一个虚构的“重建成功”绿色标签，不如把真实可由脚本证明的结论停在输入阻断，这更适合严谨的工程技术文章。

调试路线：先从故意制造的坏样本开始

不建议只用二十张完整文件验证一次就宣称工具可靠。应当分别造出少一帧、多一个同号文件、越界帧、混杂文本文件、空目录五组样本，检查退出码和报告字段。比如在临时目录创建十八个占位文件（编号跳过007、014），运行脚本，预期退出码是2、missing为["007","014"]。占位文件不等于JPEG，测试只验证命名和目录扫描逻辑，不能给它贴上“图像可解码通过”的标签。

再把两张缺失帧补回，验证READY和退出码0；接着添加frame_008.jpeg，检查duplicate能否重新使状态降为BLOCKED。最后删掉临时文件夹重新执行，调用应该明确报错而不是沿用上一次report.json中的旧状态。要是将此脚本纳入CI，退出码2适合阻断后续重建任务，而文件系统错误与权限错误也应该以非零退出退出并让流水线终止。

上面手机页只是预期业务展示，不是运行数据。真机验证至少还需要检查异步读写完成后是否刷新页面、前台后台切换后是否清掉过期状态、重新选择不同批次时是否把旧任务号带入新记录。若团队采用数据库存储和多端同步，还要增加采集设备ID、序号生成侧、会话版本和跨端冲突规则，而不是让几台设备各自从001开始生成同一批次的名字。

哪些判断不能交给这道门禁

这套工具从未解析像素，它不能识别画面模糊、曝光错误、照片重复内容、时间戳被篡改和相机内参不一致。即便二十张全部存在，也未必满足3DGS重建所需的覆盖度和位姿条件。对于复杂现场，还需要把图像文件哈希、相机参数快照、时间戳和设备型号纳入更高层的输入资料包；不过那是另一层合同，不应该混入这篇专门讲帧序的工具里。特别是当照片是从视频抽帧得到时，跳号可能是人为采样策略，此时要先更新预期帧号集合，再谈校验，否则报告会制造假告警。

实际落地时，还应评估目录读写并发：扫描期间有人继续上传文件，就可能得到同一时刻不一致的结果。更可靠的做法是先让采集方生成完成标记，冻结输入目录的写入，再审计并进入后续队列；如果必须边拍边检，报告状态只能叫IN_PROGRESS，不能给出最终可交付结论。重试策略也应围绕具体缺口展开，避免从头覆盖所有现有素材。失败并不是耻辱，保留失败编号才能帮助恢复。

收尾：先对数据负责，再对模型效果负责

FrameGuard把问题限定得很窄：一批事先编号的重建输入帧，究竟齐不齐、重没重、混没混。FR-204的示例结论是BLOCKED 18/20 FRAME_GAP=007,014，这条结果既能进入本地报告，也能在ArkUI页面里明确解释给操作者。它没有完成3DGS建模，也不承诺哪个HarmonyOS设备一定支持重建，但它让错误更早、也更容易复现。对于移动端空间计算工程，这是值得独立做好的一道简单门禁。

官方资料核对： 华为开发者联盟《空间计算能力接入》https://developer.huawei.com/consumer/cn/features/spatialization；Spatial Recon Kit 3DGS管线入口https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/spatial-recon-c-spatial-recon-pipeline。本文Node.js的fs/promises、path均属Node官方标准模块，不声称它们是鸿蒙系统接口；上层系统SDK的可用性应根据目标SDK和设备另行核验。