HarmonyOS HAP 与调试工件治理：包结构、版本身份与自动化证据链

摘要：HarmonyOS 自动化测试不仅产生 HAP，还可能包含日志、Trace、截图、测试结果和调试配置。若这些工件没有统一构建身份和脱敏边界，版本回归无法复核，公开材料也容易泄漏包名、签名和设备信息。本文建立一套通用工件治理模型。

一、HAP 不是孤立文件

一次可复核测试至少关联：应用产物、版本/模块 manifest、签名身份摘要、安装结果、设备环境、测试路径、性能工件与结论。

二、构建 manifest

{
  "artifact_id": "hap-demo-21",
  "build_id": "demo-build-21",
  "module_alias": "entry_demo",
  "build_mode": "release_test",
  "api_epoch": "api_x",
  "artifact_sha256": "...",
  "signing_fingerprint_ref": "internal-only"
}

签名指纹、证书、真实包名和应用标识不可进入公开文章。

三、安装与启动证据

命令返回成功只是第一层，还应验证目标版本、前台状态、业务 ready 信号和异常退出。HDC/设备命令必须封装在 Adapter 内，上层状态机不散落平台判断。

四、调试开关生命周期

某些分析能力需要临时启用调试属性。任务开始前记录原状态，结束后在 finally 恢复；日志不得保存真实应用标识和账号。

try:
    adapter.enable_debug(task_scope)
    run_test()
finally:
    adapter.restore_debug_state()

五、工件清单

run/
  build_manifest.json
  device_environment.json
  lifecycle_events.jsonl
  metrics.json
  trace/
  screenshots_public/
  evidence_manifest.json

截图分为内部原始与公开重制版本，不能只靠裁剪认为已经脱敏。

六、跨平台公共指标

Android、HarmonyOS 和 iOS 可共享启动可用时间、帧时间、内存、功耗、成功率等语义层；采集实现和平台原始字段保持独立。缺失指标写 null + reason，不能填 0。

七、版本比较前提

固定 API/系统版本、设备档、画质、测试路径、采集器版本和调试状态。系统升级后建立新基线，避免把平台变化全部归到应用。

八、包体与模块变化

HAP 增量分析采用与 APK 类似的“清单—分类—哈希—责任模块”方法，但必须依据实际 HarmonyOS 构建和分发结构解释，不能照搬 Android 路径规则。

九、安全清理

设备端与主机端临时文件均限定在 task_id 根目录；上传并验证哈希后进入清理候选。拒绝空路径、根目录、符号链接逃逸和通配删除。

结语

HarmonyOS 工件治理的关键是把平台命令细节收进适配器，把构建、设备、测试和证据统一到 run_id。这样既能与其他移动平台共用工程体系，也不会牺牲平台特有语义和安全边界。

参考资料：HarmonyOS 调试模式示例