本文是 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: (重新阅读全部代码 + 重新生成) ← 每轮都浪费大量 Token

img2threejs 的做法：

脚本: 验证图片 → 合格 ← (0 Token) AI: 分析图片 + 写 Spec JSON ← (集中消耗一次) 脚本: 验证 Spec 完整度 → 合格 ← (0 Token) AI: 写 blockout 代码 ← (只写一小段) 脚本: 拼对比图 ← (0 Token) AI: 看对比图 → "轮廓OK" ← (少量 Token) 脚本: 解锁下一 Pass ← (0 Token) AI: 写 material 代码 ← (只写材质部分) ...

Token 效率提升的关键在于：

1. 不重复阅读：每个 Pass 只处理增量代码
2. 不做机械工作：验证、状态管理、图片拼接都交给脚本
3. 早期拦截：规格不够深就不让生成代码，避免浪费

质量门控体系（Gates）

img2threejs 设计了多层门控，确保每一步都达标后才进入下一步：

Gate 1：图片适用性门（Suitability Gate）

# forge/stage1_intake/probe_image.py# 检查：图片是否能作为 3D 重建的参考？# 拒绝：模糊、太小、纯平面图案、无法识别为物体的图片

评判标准：

• 是否有明确的 3D 物体
• 分辨率是否足够
• 是否有足够的细节可分析
• 结果：pass / conditional / reject

Gate 2：规格深度门（Strict-Quality Gate）

# forge/stage2_spec/validate_sculpt_spec.py --strict-quality# 检查：Spec 是否足够详细到可以指导代码生成？

会阻止的情况：

• 复杂物体却只有一个根节点（没有分解子部件）
• 没有定义重复系统（比如栏杆明明是重复结构）
• 没有局部材质覆盖（全部用同一个材质）
• 没有微观细节组件

这个门控的价值是巨大的——一个浅薄的 Spec 会导致后续每个 Pass 都在错误的基础上修修补补，最终白白消耗 Token。不如一开始就拦住，逼 AI 把 Spec 写深。

Gate 3：截图反馈门（Screenshot Feedback Gate）

continue（通过）的条件：

1. 必须有真实的浏览器渲染截图
2. 必须有参考图 vs 渲染图的并排对比
3. AI 视觉判分必须 ≥ 阈值（默认 0.7）
4. 每个关键特征的单独分数也必须达标

这避免了"整体看着像但细节全错"的情况。比如一把刀，整体轮廓分数 0.8，但刀刃形状分数只有 0.3——不通过。

Gate 4：Divine Eye 确定性审核

# forge/stage4_review/divine_eye.py# 多信号集成审核（不消耗 Token）：# - IoU（轮廓重叠度）—— 硬门控# - 比例/对称性 —— 硬门控# - pHash / SSIM / edge 匹配 —— 软信号# - 只有软信号不确定时才调用 VLM（AI 视觉）

设计精妙之处：大多数明显的"不通过"可以被确定性算法捕获，无需消耗 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 锁定机制

# 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 必须做出唯一决策：

关键设计：refine-spec和refine-code的区分。

很多 AI 编码场景中常见的问题是"在错误的设计上反复修补代码"。img2threejs 强制 AI 思考：是代码写错了，还是一开始的 Spec 就不对？如果是 Spec 的问题，回去改 Spec 然后重新验证，而不是在代码层面绕路。

循环终止保护

# forge/stage4_review/correction_loop.py# 防止无限循环修正（Token 燃烧保护）# 终止条件：# - 成功（通过）# - 重复缺陷（同一个问题修了两次还在）# - 振荡（A修成B，B修回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 色差算法）

这个决策看似极端，但好处明显：

1. 零安装成本——Clone 下来就能用，不需要pip install
2. 无环境问题——不会因为 PIL 版本冲突导致 Agent 卡住
3. 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 方案的对比

img2threejs 的独特定位是：代码优先、轻量部署、可编辑可动画。它不追求照片级真实感，而是追求"程序化可控的高质量 3D 资产"。

实际应用场景探讨

场景 1：游戏/Web 轻量 3D 资产

不想引入 .glb 文件（增加打包体积），用 img2threejs 生成纯代码模型，Tree-shaking 后极其轻量。

场景 2：数字孪生大屏中的设备模型

工业场景中，需要在大屏上展示设备的 3D 视图。用设备照片生成 3D 模型代码，比找建模师建模快得多。

场景 3：电商产品 3D 预览

商品图片 → 3D 可旋转预览，不需要每个商品都拍 360° 照片或建模。

场景 4：教育/演示

快速把概念图转为可交互的 3D 示意模型，用于教学演示。

局限性与诚实声明

img2threejs 在文档中多次强调自己的局限：

1. 单视图局限：一张图看不到背面，背面靠推测（镜像可见面），可能不准
2. 不是照片级：程序化原语组合本质上是"风格化重建"，不是扫描级精度
3. 需要 AI Agent：不是一个可以npm install然后调 API 的库，需要 AI 交互式运行
4. 硬表面为主：对有机形态（人脸、动物毛发）效果有限（v1.5 改进中）
5. 耗时：完整管线 20-40 分钟，不是实时的

项目文档中明确写道：

“This cannot reach the requested fidelity from this image” is a valid, expected result.

这种诚实的态度值得称赞——比起那些宣称"一键生成完美 3D"的工具，img2threejs 选择了透明地告诉你什么能做、什么做不到。

总结

img2threejs 的架构设计体现了几个值得借鉴的工程思想：

1. 分层分工：机械工作交给确定性脚本（免费），创造性工作交给 AI（收费但值得）
2. 渐进式构建：8 个 Pass 逐步精修，比一次性生成更可控
3. 门控驱动质量：在每一步设置关卡，早期拦截问题，避免后期浪费
4. 自我修正但有边界：允许修正但防止无限循环，知道什么时候该"放弃并求助"
5. 零依赖哲学：脚本层不引入任何外部依赖，消除环境问题

这些设计模式不仅适用于图片转 3D，对任何"AI 辅助的多步骤工程管线"都有参考价值。

系列完。如果你对 img2threejs 感兴趣，推荐直接在 Claude Code 或 Codex 中试一试——给它一张你手边物品的照片，看看 AI "雕"出来的效果。