构建、验证与 OHPM 发布

本页只描述 voxel-kit HAR 的工程验证与发布流程。它区分三个产物：HAR 本身、使用 HAR 的 Demo/宿主工程、以及最终目标真机的可见行为。三个都通过，才是一份可以发布的预览组件。

发布前的推荐流程

改动代码/资源/公开 API
→ 更新 README、CHANGELOG、站点 API 页面与 ai-docs
→ 构建 voxelKit HAR
→ 构建 entry/独立宿主
→ 真机验证 JSON、VFP、手势和视觉
→ 检查 HAR 包内容与 SHA-256
→ 提高版本号并发布 OHPM
→ 从 registry 干净安装后再做 smoke test

不要把“已在本仓库直接引用源码编译成功”当作 OHPM 包可用的证明；发布后应从目标 registry 安装最终 .har，确保资源、README、依赖和导出都正确。

本地开发命令

# 只构建 HAR
devecocli build --modules voxelKit

# 构建 Demo，验证公开 HAR API 的本地消费
devecocli build --modules entry

# 构建并部署 Demo 到指定设备
./scripts/deploy.sh --device <device-serial>

# 开发启动
./scripts/dev.sh --device <device-serial>

# 应用日志
./scripts/logs.sh --device <device-serial> --from 5m --tail 300

不要绕过项目脚本用临时启动命令部署应用；脚本固定了模块、构建和日志约定。

devecocli build --modules voxelKit 只证明 HAR 可被构建；devecocli build --modules entry 证明仓库 Demo 能使用公开 API。渲染、触控、Picker URI 和材质资源仍需要运行在真机。

HAR 产物

voxel-preview/build/default/outputs/default/voxelKit.har

当前默认是字节码 HAR，外观为 gzip/tar 容器而非普通 ZIP；检查文件清单应使用：

tar -tzf voxel-preview/build/default/outputs/default/voxelKit.har

如果要把产物给其他项目试用，交付这个 .har 文件及对应版本号，而不是复制 src/main/ets。后者会绕开模块资源与 OHPM 元数据，无法代表真实集成方式。

voxel-kit 2.4.0 的单一 HAR 已内置：

package/libs/arm64-v8a/libvoxelkit_compiler.so
package/libs/x86_64/libvoxelkit_compiler.so

因此 OHPM 只需发布一个 voxelKit.har，消费者不应另行下载、复制或配置 .so。正式上传前应构建 release 产物，而不是把带 debug=true 元数据的日常开发包发布到稳定通道。

发布前检查

voxel-preview/oh-package.json5 的 name、version、description、license 正确。
模块根目录有 README.md、CHANGELOG.md、LICENSE，与 src/ 同级。
README 中的能力范围、示例和版本号与公开导出一致。
执行 HAR 与 entry 构建；对改动过的渲染/手势进行真机验收。

检查产物内至少有以下文件和两个 Native ABI：

tar -tzf voxel-preview/build/default/outputs/default/voxelKit.har | \
  rg '^package/(README\\.md|CHANGELOG\\.md|LICENSE|oh-package\\.json5|libs/(arm64-v8a|x86_64)/libvoxelkit_compiler\\.so)$'

记录校验和：

shasum -a 256 voxel-preview/build/default/outputs/default/voxelKit.har

在干净宿主或独立 Demo 中使用新 HAR 构建、安装和导入一份 JSON、一份 VFP。

对于涉及渲染资源、动画、手势或 Picker 的修改，第 7 步必须补充真机手动验证。对于 Reader 改动，还应覆盖无 PRVW、损坏目录 CRC、损坏区段 CRC 和超过 64 MiB 的 URI。

上传 OHPM

发布者先按组织流程配置私钥和 publish_id，再执行：

ohpm publish voxel-preview/build/default/outputs/default/voxelKit.har

上传成功后必须从目标 registry 重新安装同一版本，验证包名、README 展示、声明文件和最小预览。不得覆盖或删除已经被消费者安装的稳定版本；修复应提高版本号并发布新制品。

改动	版本建议	例子
文档/内部修复且不改变公开行为	PATCH	修正错误文案、修复稳定性问题。
新增可选 Options、独立 Reader 方法或非破坏性回调	MINOR	增加新的只读格式能力。
改变包名、公开导出、输入合同、默认行为或最低系统要求	MAJOR	更换能力边界或不兼容 API。

文档随包规则

字节码 HAR 默认打入模块根的 README.md、CHANGELOG.md、LICENSE。额外 Markdown（例如源仓库里的 DEVELOPER_GUIDE.md）不会自动进入 HAR，应在源仓库、发布页面或 README 中提供稳定的外部链接。

站点文档适合承载长篇指南与 API 参考；HAR 内 README 应保留安装、最小预览、边界和链接，避免安装者只能看到一份不完整的包说明。

发布前的推荐流程​

本地开发命令​

HAR 产物​

发布前检查​

上传 OHPM​

推荐的版本处理​

文档随包规则​