HarmonyOS 7 新特性6：端侧重建——能力查询给票与会话拒载的真机对照及降级三步
HarmonyOS 7 新特性6：端侧重建——能力查询给票与会话拒载的真机对照及降级三步
文章目录
1、引言
端侧 3DGS 重建是 Spatial Recon Kit 里最重的一块能力：C 接口、逐帧推入 RGB 图像、会话生命周期管理、输出 PLY 点云或 MP4 运镜视频。官方文档对它的门槛说得很直白：空间重建性能开销大，仅保证 Kirin 9020/9030S/9030/9030 Pro 及以后的旗舰芯片体验；其他芯片「即使通过接口查询得到支持，也无法保证重建耗时和重建质量」。
这句话留了一个缝：「查询得到支持」之后呢？保证名单外的设备调 CreateSession 会发生什么？文档没写，而我的实测机 Mate 60 Pro（麒麟 9000S）正好站在名单外。这篇就用一台名单外的机器，把「查询」和「创建」拆成两步分别调用，看缝里到底是什么。
答案比文档说法更硬：查询说支持，创建说拒绝。以及一个顺带的发现——错误码不是按含义排队，是按触发时序排队。围绕这组读数，本篇的主体不是重建管线，是降级路径怎么做成产品语义：进不去门的人，门外的路怎么走。
环境声明：HarmonyOS 7.0.0.107 (API 26) Release，实测工程轻探（com.qingkouwei.lightrecon）；DevEco Studio 26.0.0（SDK 26.0.0.105 Release），真机 Mate 60 Pro（ALN-AL80，麒麟 9000S，1260×2720）。代码在该环境编译签名部署运行，读数全部真机实测。
2、效果展示与工程结构
轻探是一个单页诊断应用，界面三段：能力卡、读数区、降级路径卡。点「跑诊断」一次链跑完全部调用，读数原文直显，不做业务加工。
首屏：能力卡给出官方芯片保证名单原文与能力查询入口，读数区与降级卡待探测后出现。
探测完成后的完整界面——本篇的核心证据同屏：IsSupport(GS) = true，而读数区第二行 V2_createSession = 801 session=null；第三行 V3_createSessionBadPath = 801（非法路径没有拿到它自己的错误码）；后续帧推入与生命周期读数全部 skipped（无会话）。降级路径卡按「会话建不起来」的条件显示，标题直接带出拒载读数。
工程结构一个诊断一个页面：
entry/src/main/
├── cpp/
│ ├── recon_probe.cpp // NAPI 诊断：V1-V4 + 生命周期一次链
│ └── CMakeLists.txt // hms/native 搜索路径 + spatial_recon_ndk 链接
└── ets/pages/
└── ReconPage.ets // 能力卡 + 读数区 + 降级路径卡
诊断的设计规矩只有一条：诊断只报数，不判断。IsSupport 返回 true 要不要降级、801 意味着什么，解释权全部留给 ArkTS 侧的产品层与正文——诊断里写业务判断，读数就会被判断污染。
3、Kit 与 API：头文件直读的接口面
重建接口是 C 的，头文件 spatial/spatial_recon_interface.h（819 行），库 libspatial_recon_ndk.z.so，两者都在 SDK 的 hms/native 下——不是 openharmony/native，DevEco 工具链默认只搜后者，CMake 必须显式加搜索路径（配方承本卷实战5，已验证）：
set(HMS_NATIVE_ROOT "$ENV{DEVECO_SDK_HOME}/default/hms/native")
include_directories("${HMS_NATIVE_ROOT}/sysroot/usr/include")
link_directories("${HMS_NATIVE_ROOT}/sysroot/usr/lib/aarch64-linux-ohos")
target_link_libraries(entry PUBLIC spatial_recon_ndk.z ...)
接口面直读核对，全表如下（起始版本均为 6.1.0(23)，RegisterNGCallbackFunc 为 26.0.0）：
| 调用 | 签名要点 | 本篇是否调用 |
|---|---|---|
IsSupport(modelType) | 返回 bool，能力查询唯一入口 | ✅ V1 |
CreateSession(type, workPath, &session) | workPath 需可写且有足够存储 | ✅ V2/V3 |
PushFrame(session, frame) | 帧仅 1080×1440 RGB | ⏭ 无会话跳过 |
PushARFrame(session, arSession, arFrame) | AR 引擎帧直推 | ⏭ |
StartSession(session, writeInfo, cb) | 回调收终态 | ⏭ 条件触发 |
SetRunningMode(session, mode) | 每次 StartSession 后必调 | ⏭ |
GetProgress(session, &progress, &stage) | 进度 0-1 + 六阶段枚举 | ⏭ |
PauseSession / ResumeSession | 会话暂停恢复 | ⏭ |
SaveResultToFile(session, writeInfo, cb) | 产物存盘 | ⏭ |
DestroySession(session) | 不销毁则资源泄漏 | ⏭ |
错误码 9 枚（头文件枚举直读）：
| 码 | 名 | 语义 |
|---|---|---|
| 0 | SUCCESS | 成功 |
| 801 | DEVICE_NOT_SUPPORT | 设备不支持 |
| 1023700001 | EXCEEDS_MAXIMUM | 超并发上限（同时仅一个重建会话） |
| 1023700002 | INVALID_WORK_PATH | 工作路径非法 |
| 1023700003 | INVALID_FRAME_DATA | 帧数据非法 |
| 1023700004 | STAGE_NOT_INITIALIZED | 阶段未初始化 |
| 1023700005 | STAGE_BUILDING | 构建中（操作被阶段拒绝） |
| 1023700006 | STAGE_NOT_FINISHED | 未完成（如未建完就存盘） |
| 1023700007 | FAILED | 通用失败 |
帧结构体 HMS_SpatialRecon_DataFrame 的字段也值得列：焦距 focalX/Y、主点 principalX/Y、8 系数畸变、位姿 position[3]+rotation[4] 四元数、时间戳、RGB 数据指针——一帧不只是图像，是「图像+相机内外参+位姿」的完整观测包。合成帧没有真实相机，本篇给的是合法占位参数（单位四元数、零畸变、焦距取宽高量级），只为让结构体字段过校验。
4、逻辑流
诊断一次链的决策流：
降级路径的产品流（读数之后的事）：
第二张图是这篇的产品论点：降级不是异常分支，是一条有声明、有转移、有消费面的完整路径。轻探的降级卡把三步直接渲染在界面上——用户看到的不是「功能不可用」的红字，是「这条路走哪」的说明。
5、实战：两组读数与一个时序
5.1 给票与拒载
麒麟 9000S 真机读数：
| 调用 | 返回 |
|---|---|
IsSupport(SPATIAL_RECON_MODEL_TYPE_GS) | true |
CreateSession(GS, 沙箱合法路径) | 801 DEVICE_NOT_SUPPORT，session=null |
能力查询通过了，会话创建被拒。读数同屏如下（首跑界面，降级卡尚未显示——首版判定条件的缺陷见 6.2）：
官方说法「不保证耗时与质量」在这台机器上的实际表现是直接拒载——比说法更硬，也更干净：没有半死不活的重建过程，没有跑两小时出个废模型，门卫在门口就把话说明白了。
这是本卷第三次撞见「声明≠可用」：第一次是 spatialEdit 的 syscap 查询为 true 而 editGSNode 四轮稳定返回 undefined（开源中国卷实战2）；第二次是 TiledGSNode 接口 resolve 而渲染器零瓦片请求（本篇前一篇）；第三次就是这次的给票/拒载。三例的共同教训：能力查询是门票，不是承诺；产品层永远要给「持票进不去」准备路径。
5.2 错误码按触发时序排队
V3 的读数是本篇第二个发现：非法工作路径（/nonexistent_dir_@@/bad）本应触发 1023700002 INVALID_WORK_PATH，真机返回的却是 801。
解释只有一种：设备校验发生在路径校验之前。801 是门卫——不支持的设备上，路径错没错根本轮不到检查，门卫先把你拦下了。推论两条：其一，1023700002/1023700003 这类参数错误码在不支持设备上不可达，想测它们必须借保证名单内的机器；其二，错误码表不能按含义并列读（「801 设备不支持、1023700002 路径非法」并排写着，像是两个平行的失败原因），要按触发时序读——先过门卫，才谈参数。
5.3 降级三步
轻探的降级判定条件经历过一次真机修正：首版按 IsSupport == false 显示降级卡，真机跑完发现 IsSupport 是 true——按首版逻辑降级卡不显示，用户面对的是「查询说支持」却什么都做不了的界面。修正后降级条件改为 CreateSession 失败（或 IsSupport=false，两者取或）：产品语义的降级点是「会话建不起来」，不是「查询说不行」。
降级卡三步文案对应三条工程事实：声明（本机芯片不满足官方保证条件，端侧重建链不启动，避免未定义的耗时与质量）；转移（重建在外部工具完成，PC 端重建管线产出 3DGS PLY）；消费（PLY 渲染无芯片门槛——本卷轻带看与 GSStudio 两工程已真机验证渲染链路，降级不断产品跑通）。第三步是关键：重建进不来，但重建的产物进得来，产品的价值锚在产物不在管线。
6、避坑
6.1 deviceTypes 漏 phone，装机报 9568413
现象：轻探首版 deviceTypes 只写 tablet/2in1（承双模态卷习惯），在 Mate 60 Pro 上装机直接失败：code:9568413 check syscap failed and device type is not supported。
根因：Mate 60 Pro 的 const.product.devicetype 是 phone。CSDN 卷实测机是手机，deviceTypes 必须含 phone——开源中国卷的平板/2in1 习惯在这里是错的。
方案对比：A 按设备补 phone（本篇）；B 全形态声明 phone/tablet/2in1 一劳永逸（代价是每形态都要自测，声明了不测等于埋雷）。
最佳实践：选 A 并按卷说法声明——CSDN 卷声明 phone，开源中国卷声明 tablet/2in1，各卷各的设备面。
验证：补 phone 后装机成功，诊断全链跑通。
6.2 降级判定不能只看 IsSupport 单信号
现象：首版降级卡条件 IsSupport == false，真机 IsSupport=true 导致降级卡不显示，界面停在「查询说支持」的死胡同。
根因：给票与拒载分离（5.1），IsSupport 单信号不足以判定「重建链可用」。
方案对比：A 降级条件改 CreateSession 失败（本篇）；B 再加一层 StartSession 探测（多一次会话占用，且 801 已在 CreateSession 截停，无增量信息）。
最佳实践：选 A。降级点 = 会话建不起来，与产品语义对齐。
验证：修正后降级卡按 V2 读数显示，标题直接带出拒载码（图 3）。
6.3 诊断不做业务判断，读数才可信
现象：写诊断时一度想在 C 层把「801 意味着降级」写成返回字段，被自己拦下。
根因：诊断里写业务判断，读数会被判断污染——下次固件行为变了，诊断报的是旧判断不是新读数。本篇 V3 的时序发现恰恰来自「诊断如实报了 801 而不是我预期的 1023700002」：如果诊断替我判断，这个发现就没了。
最佳实践：诊断只回传 key=value 原文；判断留在 ArkTS 产品层与正文。读数区 UI 也照此设计——原文直显，不翻译。
验证：V3 读数与预期不符时，界面如实显示 801，发现得以保留。
7、总结，以及这次没测到的部分
这篇没有跑通一次重建——一台名单外的机器跑不通重建，这本身就是结果。能力查询给票、会话创建拒载的对照，把官方一句保证名单说法拆成了两个可观测的行为；错误码 801 截胡 1023700002，把错误码表从含义并列改成了时序排队；降级三步把「进不去门」从异常分支做成了产品路径。三条加起来是同一句话：门槛类能力的工程主体不在门槛内，在门槛外的路径设计。
这次没测到的部分，如实列在这里：
- V4 帧推入与 L1-L4 生命周期读数在本机不可达（无会话），输入规格约束（仅 1080×1440 RGB）与阶段枚举行为未真机验证，需保证名单内设备补测
- 1023700002/1023700003 等参数错误码的触发条件未真机验证（5.2 推论：不支持设备上不可达）
- 重建耗时、产物质量、热管理订阅（官方建议订阅 COMMON_EVENT_THERMAL_LEVEL_CHANGED）均未测——门槛内行为留待借机
- 合成帧内参为合法占位值，非真实相机标定；即便在支持设备上，占位内参的重建产物也无质量意义
门槛内的世界很精彩，门槛外的路径才是大多数设备的日常。把后者设计好，能力查询的票才有意义。
讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。
更多推荐
2
0- 0
已为社区贡献130条内容
所有评论(0)