本文是 img2threejs 系列的第二篇深入剖析其管线架构设计、质量门控机制、以及确定性脚本 AI 视觉判断的 Token 高效利用策略。前言上一篇我们介绍了 img2threejs 的基本概念和使用方式。这篇文章我们深入它的内部架构——它是如何在保证模型质量的同时控制 Token 消耗的为什么它选择了逐 Pass 雕刻而非一次性生成这些设计决策背后的工程思考是什么架构总览确定性脚本 AI 视觉判断img2threejs 的架构哲学可以用一句话概括脚本做执行和验证AI 只做判断和创造这是它区别于普通让 AI 一次性生成代码方式的核心。┌──────────────────────────────────────────────────────────────┐ │ 确定性脚本层Python 3.10 │ │ │ │ · JSON Schema 验证 · Pipeline 状态管理 │ │ · 复杂度评估算法 · 对比图拼接 │ │ · Pass 锁定/解锁 · PBR 参数提取 │ │ · 细节清单生成框架 · 相机姿态计算 │ │ │ │ 特点零 Token 消耗、确定性、可复现、纯标准库 │ └──────────────────────────────┬───────────────────────────────┘ │ 门控信号pass/fail/block │ ┌──────────────────────────────▼───────────────────────────────┐ │ AI Agent 层 │ │ │ │ · 图片视觉分析识别结构、材质、细节 │ │ · Spec JSON 创作组件树、材质定义 │ │ · Three.js 代码编写 │ │ · 渲染截图 vs 参考图的视觉比对判分 │ │ · 自我修正决策 │ │ │ │ 特点消耗 Token、需要视觉能力、创造性工作 │ └──────────────────────────────────────────────────────────────┘为什么这样分工传统的让 AI 写 3D 模型方式通常是用户: 帮我用 Three.js 画一个杯子 AI: (一次性输出几百行代码) 用户: 不太像修一下... AI: (重新阅读全部代码 重新生成) ← 每轮都浪费大量 Tokenimg2threejs 的做法脚本: 验证图片 → 合格 ← (0 Token) AI: 分析图片 写 Spec JSON ← (集中消耗一次) 脚本: 验证 Spec 完整度 → 合格 ← (0 Token) AI: 写 blockout 代码 ← (只写一小段) 脚本: 拼对比图 ← (0 Token) AI: 看对比图 → 轮廓OK ← (少量 Token) 脚本: 解锁下一 Pass ← (0 Token) AI: 写 material 代码 ← (只写材质部分) ...Token 效率提升的关键在于不重复阅读每个 Pass 只处理增量代码不做机械工作验证、状态管理、图片拼接都交给脚本早期拦截规格不够深就不让生成代码避免浪费质量门控体系Gatesimg2threejs 设计了多层门控确保每一步都达标后才进入下一步Gate 1图片适用性门Suitability Gate# forge/stage1_intake/probe_image.py# 检查图片是否能作为 3D 重建的参考# 拒绝模糊、太小、纯平面图案、无法识别为物体的图片评判标准是否有明确的 3D 物体分辨率是否足够是否有足够的细节可分析结果pass / conditional / rejectGate 2规格深度门Strict-Quality Gate# forge/stage2_spec/validate_sculpt_spec.py --strict-quality# 检查Spec 是否足够详细到可以指导代码生成会阻止的情况复杂物体却只有一个根节点没有分解子部件没有定义重复系统比如栏杆明明是重复结构没有局部材质覆盖全部用同一个材质没有微观细节组件这个门控的价值是巨大的——一个浅薄的 Spec 会导致后续每个 Pass 都在错误的基础上修修补补最终白白消耗 Token。不如一开始就拦住逼 AI 把 Spec 写深。Gate 3截图反馈门Screenshot Feedback Gatecontinue通过的条件必须有真实的浏览器渲染截图必须有参考图 vs 渲染图的并排对比AI 视觉判分必须 ≥ 阈值默认 0.7每个关键特征的单独分数也必须达标这避免了整体看着像但细节全错的情况。比如一把刀整体轮廓分数 0.8但刀刃形状分数只有 0.3——不通过。Gate 4Divine Eye 确定性审核# forge/stage4_review/divine_eye.py# 多信号集成审核不消耗 Token# - IoU轮廓重叠度—— 硬门控# - 比例/对称性 —— 硬门控# - pHash / SSIM / edge 匹配 —— 软信号# - 只有软信号不确定时才调用 VLMAI 视觉设计精妙之处大多数明显的不通过可以被确定性算法捕获无需消耗 Token 让 AI 来看。AI 视觉只在边缘情况时才被调用。Gate 5多角度验证门# forge/stage4_review/diagnose_render_multi_angle.py# 检查从另一个角度看模型是否仍然是 3D 的# 目的防止一个贴了纹理的平面冒充 3D 模型这解决了一个隐蔽的问题如果模型只是一张 PlaneGeometry 贴上了参考图片的纹理从正面看和参考图一模一样分数满分但一旋转就露馅了。多角度门确保模型有真实的 3D 体积。Gate 6装配门Assembly Gate# forge/stage4_review/check_part_coverage.py# 检查Spec 里定义的每个组件是否都被实际构建了# 防止AI 偷懒把多个部件融合成一个 Mesh这是唯一一个检查结构而非像素的门控。一个投影了照片纹理的单一 Mesh 能通过所有视觉门控但过不了装配门——因为它没有独立的可交互部件。Pass 系统详解为什么要分 8 个 Pass核心原因关注点分离 渐进式精修如果让 AI 一次性输出完整模型代码容易顾此失彼调材质时把形状搞乱出错时不知道问题在哪一层修改时可能引入新问题分 Pass 的好处Pass关注点典型修改内容blockout整体轮廓、比例几何体类型和 scalestructural子部件拆分新增 Mesh、调整 parent-childform-refinement形体精确顶点位置、曲线参数material材质准确PBR 参数、颜色surface表面细节凹凸、纹理、磨损效果lighting光照环境灯光、环境贴图interaction可交互性socket、pivot、userDataoptimization性能合并几何体、降面Pass 锁定机制# forge/stage3_build/orchestrate_passes.py# 查看当前状态orchestrate_passes.py status spec.json# 输出: current: structural-pass, completed: [blockout]# 尝试跳过生成 material-pass 的代码generate_threejs_factory.py spec.json--pass-idmaterial-pass# 报错: build pass material-pass is locked; complete form-refinement first这保证了不会跳步——形体都没对就去调材质是浪费时间。自我修正机制每个 Pass 审核后AI 必须做出唯一决策决策含义触发条件continue通过进入下一 Pass视觉分数达标refine-specSpec 有问题回去修 Spec发现结构性设计错误refine-codeSpec 没问题代码实现有误几何/材质不对request-input需要更多信息看不清、需要另一个角度stop不可行放弃从这张图无法达到要求的精度关键设计refine-spec和refine-code的区分。很多 AI 编码场景中常见的问题是在错误的设计上反复修补代码。img2threejs 强制 AI 思考是代码写错了还是一开始的 Spec 就不对如果是 Spec 的问题回去改 Spec 然后重新验证而不是在代码层面绕路。循环终止保护# forge/stage4_review/correction_loop.py# 防止无限循环修正Token 燃烧保护# 终止条件# - 成功通过# - 重复缺陷同一个问题修了两次还在# - 振荡A修成BB修回A# - 分数停滞修了但分数不变# - 硬上限达到最大轮次当检测到 AI 陷入循环时自动升级为request-input——告诉用户我搞不定了需要你提供更好的参考图或更明确的指示。实际 Token 消耗分布以一个中等复杂物体为例约 120k tokens 总消耗┌─────────────────────────────────────────────────────────┐ │ 确定性脚本验证/状态/拼图 ~3k (2.5%) │ │ ■ │ │ 图片分析 Spec 创作 ~20k (16.7%) │ │ ■■■■■ │ │ Three.js 代码编写所有 Pass 累计 ~35k (29.2%) │ │ ■■■■■■■■■ │ │ 渲染审核循环6轮 × ~10k ~62k (51.7%) │ │ ■■■■■■■■■■■■■■■■ │ └─────────────────────────────────────────────────────────┘可以看到审核循环占了一半以上的 Token——这是保证质量的代价脚本层近乎免费——所有机械工作都不消耗 Token代码编写只占约 30%——因为是增量式的每次只写一小段零依赖的 Python 脚本设计img2threejs 的所有 Python 脚本都只用标准库# 不需要这些# pip install pillow numpy opencv-python playwright ...# 它自己实现了# - PNG 读写用 struct zlib# - 图片比较基于像素的 IoU/SSIM# - JSON Schema 验证# - 颜色空间转换CIEDE2000 色差算法这个决策看似极端但好处明显零安装成本——Clone 下来就能用不需要pip install无环境问题——不会因为 PIL 版本冲突导致 Agent 卡住Context 不浪费——不需要花 Token 让 AI 调试依赖问题ObjectSculptSpec 数据结构Spec 是整个管线的中枢以下是其核心结构{targetName:Concrete Bridge,objectClass:{primaryDomain:object,category:infrastructure},complexityTier:complex,qualityContract:{targetMinDetails:12,fidelityFloor:0.7},componentTree:[{id:deck,label:Bridge Deck,primitive:box,level:macro,dimensions:{width:20,height:0.5,depth:8},transform:{position:[0,5,0]},materialRef:concrete_weathered},{id:pier_1,label:Main Pier,primitive:cylinder,level:macro,parent:deck,dimensions:{radius:0.8,height:5},transform:{position:[-6,-2.5,0]},materialRef:concrete_smooth}],materials:[{id:concrete_weathered,baseColor:#7A7A72,metalness:0.0,roughness:0.85,surfaceFrequencyBands:[{frequency:4,amplitude:0.3,pattern:stain,role:weathering}]}],buildPasses:[{id:blockout,componentRefs:[deck,pier_1,pier_2]},{id:structural-pass,componentRefs:[railing_left,railing_right]}],reviewHistory:[]}这个 Spec 是可人工编辑的——你可以在 AI 生成后手动调整参数然后重新跑 build。与其他图片转 3D 方案的对比维度img2threejsTripoSR / InstantMeshNeRF / 3D GaussianPhotogrammetry输入1 张图片1 张图片多张图片/视频大量照片输出TypeScript 代码.glb/.obj 网格隐式表示/点云网格纹理文件大小5-50 KB代码1-10 MB10-100 MB10-500 MB可编辑性极高代码级中网格编辑低中动画支持内置socket/pivot需后处理不支持需后处理精度风格化/近似中等高多视图时最高运行时性能最优原语渲染良好较重取决于面数成本Token 费用GPU 算力GPU 算力时间设备离线可用是代码生成后需要推理需要推理是img2threejs 的独特定位是代码优先、轻量部署、可编辑可动画。它不追求照片级真实感而是追求程序化可控的高质量 3D 资产。实际应用场景探讨场景 1游戏/Web 轻量 3D 资产不想引入 .glb 文件增加打包体积用 img2threejs 生成纯代码模型Tree-shaking 后极其轻量。场景 2数字孪生大屏中的设备模型工业场景中需要在大屏上展示设备的 3D 视图。用设备照片生成 3D 模型代码比找建模师建模快得多。场景 3电商产品 3D 预览商品图片 → 3D 可旋转预览不需要每个商品都拍 360° 照片或建模。场景 4教育/演示快速把概念图转为可交互的 3D 示意模型用于教学演示。局限性与诚实声明img2threejs 在文档中多次强调自己的局限单视图局限一张图看不到背面背面靠推测镜像可见面可能不准不是照片级程序化原语组合本质上是风格化重建不是扫描级精度需要 AI Agent不是一个可以npm install然后调 API 的库需要 AI 交互式运行硬表面为主对有机形态人脸、动物毛发效果有限v1.5 改进中耗时完整管线 20-40 分钟不是实时的项目文档中明确写道“This cannot reach the requested fidelity from this image” is a valid, expected result.这种诚实的态度值得称赞——比起那些宣称一键生成完美 3D的工具img2threejs 选择了透明地告诉你什么能做、什么做不到。总结img2threejs 的架构设计体现了几个值得借鉴的工程思想分层分工机械工作交给确定性脚本免费创造性工作交给 AI收费但值得渐进式构建8 个 Pass 逐步精修比一次性生成更可控门控驱动质量在每一步设置关卡早期拦截问题避免后期浪费自我修正但有边界允许修正但防止无限循环知道什么时候该放弃并求助零依赖哲学脚本层不引入任何外部依赖消除环境问题这些设计模式不仅适用于图片转 3D对任何AI 辅助的多步骤工程管线都有参考价值。系列完。如果你对 img2threejs 感兴趣推荐直接在 Claude Code 或 Codex 中试一试——给它一张你手边物品的照片看看 AI 雕出来的效果。