维护与扩展规则
本页不是给业务接入方增加“隐藏能力”的方法，而是给 Voxel Kit 维护者划定扩展方式：新增功能可以很多，但必须落在清晰的能力族、权限边界和性能模型上，不能把内部 ArkGraphics 对象临时泄露给宿主。
公开 API 设计原则
新增能力必须先回答：
- 它属于 Preview、Format、Validate、Convert 还是 Edit？
- 是否需要 ArkGraphics？是否需要写权限？是否会读取完整
VOX0？ - 内存上限、异步模型、失败语义和缓存可信边界是什么？
- 能否只通过稳定数据对象表达，而不是泄露 Scene、Camera、Geometry 或私有 TaskPool 输入？
只有这些边界明确后，才应在 voxel-preview/Index.ets 增加导出。
新 API 评审清单
| 问题 | 合格答案的特征 |
|---|---|
| 谁拥有资源？ | 调用方还是 HAR 清楚；dispose()、取消、重复调用语义明确。 |
| 是否异步？ | Promise 的成功点、失败类型、并发限制和大文件内存上限明确。 |
| 输入是否可信？ | 容器 CRC、语义校验、缓存命中和业务信任不会被混为一谈。 |
| 可否跨版本演进？ | 返回稳定数据对象，不让业务依赖 Scene/Camera/Mesh。 |
| 如何验证？ | 至少有构建、独立宿主、真机和损坏输入的测试方案。 |
推荐能力拆分
| 未来需求 | 建议模块 | 不应做法 |
|---|---|---|
| VOX0/PAL0 完整读取与 source hash | Format/Validate API。 | 复用预览私有 Reader 并对外承诺。 |
| JSON/VOX/GLB 导出 | Convert API。 | 将 PRVW 提取误称为 GLB 导出。 |
| 体素编辑/历史/写回 | 独立 Editor HAR。 | 给只读 Viewer 暴露可变 Scene。 |
| 网络资源加载 | 业务 SDK 或宿主。 | 让 Preview HAR 自行持有鉴权、缓存、URI 权限。 |
| 精确相机控制/事件 | 版本化 Controller API。 | 直接返回内部 Camera。 |
能力族命名建议
VoxelViewer 只读可视预览
VfpPackageReader 容器读取与区段提取
Validate API 权威体素与 source hash 语义校验（未来）
Convert API JSON / VOX / GLB 等显式转换（未来）
VoxelEditor 编辑、历史、写回（独立模块，未来）
这样，预览用户不会因为引入编辑器而承担写权限、撤销栈或完整 VOX0 恢复的成本；Reader 用户也不必为了查看目录而初始化 ArkGraphics。
资源与渲染修改守则
- 修改 PBR 描边前，先确认
unitGridTexture资源路径；不要因静态 HAR Resource 解析失败而永久切到 BORD。 - 改动动画、场景替换、延迟描边或编辑接管时，必须保留代际取消与每次异步让出后的版本复核。
- 不要把动画期间原生 Geometry 创建移回播放过程；这会造成帧抖动和完整模型闪现。
- 不要为了性能静默降采样用户体素；容量策略必须显式向上层报告。
- 坐标来源是 Z-up。需要支持 Y-up 时引入显式输入元数据或选项，不要猜测最长轴。
对可见效果的最低验证
视觉修改必须至少在：浅背景、深背景、彩色体素、纯黑体素、无/有 unitGridTexture、载入动画结束、连续双指操作这七类情形中检查。只有截图/录屏或目标机手动确认，才能证明“线条、光照、动画和手感”没有退化。
变更后的必做事项
| 改动 | 必做验证 |
|---|---|
| 公开 API | 更新所有 API/快速开始/README，构建 entry 消费回归。 |
| 纹理、描边、光照 | 真机检查深浅背景、黑色体素、动画后和编辑后。 |
| Picker/VFP 读取 | JSON、VFP 1.2、VFP 1.3、损坏 CRC、无 PRVW。 |
| 手势/相机 | 手动单指、双指平移、缩放、取消/结束和动画结束时机。 |
| VFP 规范 | 更新规范、固定样本、Reader/Compiler 验证和兼容策略。 |
| OHPM 发布 | README/CHANGELOG/LICENSE、HAR 内容、重新安装和真机 smoke。 |
文档维护
本仓库的 ai-docs/ 是工程操作记录。功能、配置、构建/发布流程或设计边界变化后必须更新：
ai-docs/context/recent-10-actions.md；- 对应
ai-docs/changelog/YYYY-MM-DD-*.md； - 必要时的
ai-docs/context/decisions.md与架构文档； - 对外 README、开发者文档和 API 参考。
这样可保证未来维护者看到的是可执行的当前事实，而不是历史实验或未落地设计。
文档目录的维护方式
- 新的预览能力放在
VoxelViewer/，先补概览页中的“解决什么问题”，再补 API、接入和排障。 - 新的格式读取能力放在
Reader-API/，必须写明容器校验、语义校验、缓存与权限边界。 - 新的构建/发布要求放在
开发与发布/，同时更新模块 README/CHANGELOG 与站点指南。 - 任何新增公开符号都至少更新：总览、快速开始、对应 API 参考、范围兼容性和测试清单。