Hunyuan3D 图片转 3D 资产管线

解决什么问题

把一张或多张图片变成可加载、可交互的 3D 资产，看起来是一句需求，落到实现上通常会遇到三类问题：

• 同一张照片在浏览器里能显示，但在后续流程中无法稳定复现；
• 模型生成结果没有经过校验，GLB 缺面、空网格或边界异常会被直接放进页面；
• 本地与云端生成方式混用，导致凭证泄漏、输出目录污染或“重建”被误当成精确测量。

这个技能把流程拆成明确关卡：输入检查、生成、资产校验、场景装配、浏览器验证。这样每一阶段都能独立失败，也方便定位问题出在素材、模型还是渲染层。

核心能力与关键步骤

• 输入与模式选择：

- 单张前景物体图走 single-asset；
- 同一物体的 4–12 张一致性视图走 multiview-asset；
- 已有 GLB/GLTF 进入 asset-viewer；
- 需要大面积环境覆盖的重建不属于该流程。

• 生成提供商选择：默认使用 local-free（本地 Hunyuan3D-2mini），只在用户明确需要付费质量或提供 API 契约时启用 hunyuan-cloud。
• 本地生成关卡：调用 check_hunyuan_environment.py，确认技能脚本以绝对路径执行、模型权重与缓存不进入项目目录、API 只监听预期地址、进程使用 CUDA、输入图可读且输出目录不落回模型目录。
• 云端生成关卡：在服务端适配官方接口；凭证只放在环境变量或凭据库；异步任务轮询到终态；下载保存为 GLB 并拒绝非 GLB 字节；下载后清理临时 URL 与请求日志。
• 资产校验关卡：拒绝空网格、无面、非有限边界，以及把 API 错误体误存为 GLB 的情况；优化若不可逆，则保留原始生成结果。
• Three.js 装配关卡：使用 GLTFLoader，保留 PBR 材质；根据模型世界包围盒设置相机平面、轨道距离、地面尺寸与阴影相机；实现加载、错误、resize 与释放状态。
• 浏览器验证关卡：分别在桌面与移动端加载页面；确认 GLB 返回 200、控制台无关键错误、画布非空白；测试轨道旋转、缩放、窗口与方向变化；保留截图记录到 scene.json。

适用边界与注意点

• 单图推理结果不是“度量重建”，不能把几何精度当作相机标定或测绘结果。
• 本地免费方案需要可用的 GPU；下载完成或 API 启动成功不等于推理已经跑通。
• 云接口的 endpoint、签名方式、模型 id、计费参数必须来自官方文档或可用 curl 示例，不能凭猜测拼装。
• 浏览器端只接收已下载的公开 GLB 与非敏感 scene.json；提供商配置、密钥和原始输入图不应进入前端逻辑或产物目录。