企业官网建设流程全解析

一张静态图片，几秒钟之后变成一个有层次、有光影、能转能缩放的 3D 场景，而且生成过程不是"黑盒吐一个模型文件"，而是直接产出一段可读、可改、可版本管理的 Three.js 代码。这就是 img2threejs 这个项目最抓人的地方，目前在 GitHub 上已经拿到 8.7k Star。它做的事情，本质上是把"图生 3D"这件事从"生成资产"变成了"生成代码流水线"——输入一张图，中间经过视觉理解、结构拆解、代码编排，最后输出一个能直接跑在浏览器里的 Three.js 工程。

我第一眼看到这个思路的时候是有点兴奋的，因为它绕开了传统 3D 生成里最麻烦的一环：模型格式转换和渲染管线适配。传统做法是图生 mesh，mesh 再导出 glTF/OBJ，再塞进 Three.js 加载，中间任何一步出问题都得从头查。而 img2threejs 直接把终点定在代码层，模型是代码描述出来的，改起来就是改几行 JS/TS，这对前端和 Agent 开发者来说友好太多了。下面我就按自己的理解，把这个项目的技术拆解、流水线设计、实操要点和踩坑经验完整讲一遍，适合做 Three.js 的、做 AI Agent 的、以及想搞懂"图生 3D 到底怎么落地"的读者。

1. 为什么"图生代码"比"图生模型"更适合 Web 3D

1.1 传统图生 3D 的资产链路有多重

先把这个行业的常规路径捋清楚。你给一张图，想要在网页里看到一个 3D 效果，标准链路大概是：图像 → 深度估计/多视角重建 → 点云或网格 → 网格简化与 UV 展开 → 导出 glTF → Three.js 加载 → 材质与光照调优。这条链路上每一步都有独立的工具和参数，深度估计用 MiDaS 或 Depth Anything，重建用 NeRF 或 Gaussian Splatting，网格化用 Marching Cubes，简化用 Quadric Edge Collapse，导出还得处理坐标系（Y-up 还是 Z-up）、单位缩放、贴图打包。

问题在于，这条链路里任何一环的误差都会累积。深度图边缘不准，重建出来的模型就糊；网格简化太狠，细节就丢；UV 展开不好，贴图就拉伸。更麻烦的是，最终产物是一个二进制资产，你没法用 Git 做有意义的 diff，改一个颜色可能要重新跑整条链路。对于 Web 场景来说，模型文件体积还直接决定加载速度，一个高精度 mesh 动辄几十 MB，移动端直接劝退。

1.2 代码作为 3D 的中间表示，优势在哪

img2threejs 的核心判断是：与其生成一个不可读的资产，不如生成一段可读的代码。Three.js 本身就是用代码描述场景的——几何体用BoxGeometry、SphereGeometry，材质用MeshStandardMaterial，光照用DirectionalLight、AmbientLight，相机用PerspectiveCamera。这些 API 天然就是"3D 场景的声明式描述"。

把代码当中间表示，带来几个直接好处。第一，可解释：你打开生成的.ts文件，能一眼看出这个场景由哪些几何体组成、用了什么材质、光源在哪，而不是面对一个黑盒 mesh。第二，可编辑：想换个颜色、调个位置、加个动画，直接改代码，不需要重新生成。第三，体积小：一段描述场景的代码通常几 KB 到几十 KB，比动辄几十 MB 的 mesh 小两三个数量级，加载速度完全不是一个量级。第四，可版本管理：代码能 diff、能 review、能回滚，这对团队协作是刚需。

提示：代码作为中间表示并不是万能的。对于高度有机的形体（比如人脸、雕塑、复杂生物），纯代码几何体很难还原细节，这时候还是得回到 mesh 路线。img2threejs 更适合结构化、几何感强的场景，比如建筑、产品、图标、低多边形风格。

1.3 8.7k Star 背后反映的真实需求

这个项目能拿到 8.7k Star，我觉得不是偶然。它踩中了几个正在爆发的需求交叉点。一是AI Agent 的落地场景：Agent 需要一个"能产出可执行结果"的任务，图生 3D 代码正好是一个从感知到行动的完整闭环，很适合做 Agent 的能力演示。二是Three.js 生态的成熟：Three.js 已经是 Web 3D 事实标准，围绕它的工具链、教程、社区都非常完善，生成 Three.js 代码等于直接接入了一个巨大的生态。三是低门槛 3D 创作：大量设计师、产品经理、运营同学想做 3D 效果但不会建模，图生代码让他们用一张图就能起步。

从热搜词也能看出来，three.js、typescript、agent、3d网页渲染、ai agent这些词高频出现，说明关注这个项目的人群正好是前端 + AI 的交叉群体。他们不缺 Three.js 基础，缺的是"怎么把 AI 和 3D 串起来"的工程范式，而 img2threejs 给的正是这个范式。

2. img2threejs 的流水线拆解：从像素到可运行代码

2.1 第一段：图像理解与场景语义解析

流水线的起点是图像理解。这一步的目标不是"识别图里有什么物体"这么简单，而是要提取出可用于 3D 重建的结构化信息。具体来说，需要拿到几类信息：物体的类别与数量、每个物体的大致边界框、物体的空间层次关系（谁在前谁在后、谁遮挡谁）、主色调与材质倾向（金属、木质、塑料、玻璃）、以及整体的透视关系（是正视、俯视还是斜视）。

这一步通常用多模态大模型来做，把图片喂进去，让它输出结构化的 JSON 描述。比如一张桌子的照片，模型需要输出"一张矩形桌面 + 四条圆柱桌腿 + 木质材质 + 暖色调 + 正视角度"这样的语义。这里的关键是提示词设计：要让模型输出机器可解析的字段，而不是一段散文。实践中一般会约束输出格式，比如要求返回包含objects、materials、camera、lighting字段的 JSON。

我实测下来，这一步最容易出问题的地方是空间关系判断。模型经常把前后关系搞反，或者把遮挡关系描述错。一个缓解办法是让模型同时输出每个物体的深度排序（depth order），并在提示词里明确要求"按从远到近的顺序列出物体"。另一个坑是数量误判，比如四条桌腿可能只识别出两条，这时候可以在提示词里加一句"仔细数清楚重复出现的结构件数量"。

2.2 第二段：几何体映射与参数化

拿到语义描述之后，下一步是把语义映射成 Three.js 的几何体。这一步是 img2threejs 最核心的"翻译"环节。映射规则大致是这样的：规则形状（盒子、球、圆柱、圆锥、平面）直接对应 Three.js 的内置几何体；不规则形状则用组合几何体近似，或者用ExtrudeGeometry、LatheGeometry这类参数化几何体来构造。

这里有个很重要的设计取舍：用内置几何体组合，还是用参数化几何体？内置几何体（Box、Sphere、Cylinder）性能好、代码简单，但表现力有限；参数化几何体（Extrude、Lathe、Shape）表现力强，但代码复杂、容易出错。img2threejs 的常见做法是优先用内置几何体，只有在内置几何体明显无法表达时才降级到参数化几何体。这个取舍的逻辑是：生成代码的可读性和稳定性优先于几何精度，因为用户拿到代码后大概率会手动微调，一个简单可读的代码比一个复杂精确的代码更有价值。

参数化这一步还需要处理尺寸与比例。图片是 2D 的，没有绝对尺度，所以需要建立一个相对坐标系。常见做法是设定一个基准尺寸（比如场景整体宽度为 10 个单位），然后按图片中的像素比例推算各物体的相对尺寸。这里要注意透视畸变：如果图片是斜视角度，直接按像素比例算尺寸会失真，需要先做一次透视校正，或者让模型直接输出"估计的真实比例"而不是像素比例。

2.3 第三段：材质、光照与相机配置生成

几何体只是骨架，材质和光照才是让场景"活"起来的部分。材质生成的关键是从图片中提取颜色和质感信息。颜色相对好办，取区域主色即可；质感则需要模型判断，比如高光强的是金属或塑料，漫反射均匀的是木质或布料，半透明的是玻璃。Three.js 里对应的就是MeshStandardMaterial的metalness、roughness、transparent、opacity这几个参数。

光照配置是很多人容易忽略但影响巨大的一环。一张图里的光照信息包括：主光源方向、光源色温、环境光强度、是否有阴影。img2threejs 一般会生成一个"三点光照"的基础配置——一个主光（DirectionalLight）、一个补光（DirectionalLight 或 HemisphereLight）、一个环境光（AmbientLight），然后根据图片的明暗分布调整各光源的强度和方向。相机配置则根据图片的透视关系推断：正视用较小的 FOV，广角用较大的 FOV，俯视则调整相机位置和朝向。

注意：材质参数不要一次调太满。我见过很多生成结果把metalness直接拉到 1，结果场景一片死黑，因为金属材质在没有环境贴图的情况下几乎不反射环境光。稳妥的做法是金属度控制在 0.3 到 0.7 之间，配合一张环境贴图（可以用RoomEnvironment生成）来提供反射。

2.4 第四段：代码编排与工程化输出

最后一段是把前面所有信息组装成可运行的 Three.js 工程。这一步的产物通常包括：一个场景初始化文件（创建 scene、camera、renderer）、一个物体定义文件（每个物体的几何体 + 材质 + 位置）、一个光照配置文件、以及一个入口文件（组装并启动渲染循环）。如果项目用 TypeScript，还会生成对应的类型定义。

工程化输出这块有几个细节值得说。一是模块划分：好的生成结果会把场景拆成多个模块，而不是把所有代码堆在一个文件里，这样便于维护。二是参数外置：把可调参数（颜色、尺寸、位置）抽成常量或配置对象，方便用户快速调整。三是渲染循环与响应式：生成requestAnimationFrame循环和resize监听，保证场景在不同屏幕尺寸下正常显示。四是资源清理：在组件卸载时释放几何体和材质，避免内存泄漏，这在 React/Vue 项目里尤其重要。

3. 把 img2threejs 跑起来：环境、依赖与最小可运行示例

3.1 环境准备里最容易被忽略的三件事

第一件事是Node 版本。Three.js 生态和现代构建工具对 Node 版本有要求，建议用 Node 18 LTS 或更高。低版本 Node 在装某些依赖时会报engine不匹配，或者遇到 ESM/CJS 混用的问题。第二件事是包管理器选择。npm、pnpm、yarn 都能用，但如果你要复现别人的项目，最好跟对方保持一致，因为 lock 文件不同可能导致依赖树差异。第三件事是TypeScript 配置。如果项目是 TS 写的，tsconfig.json里的moduleResolution建议设为bundler或node16，否则 Three.js 的类型声明可能解析不到。

# 推荐的环境准备流程 node -v # 确认 >= 18 npm create vite@latest my-img2threejs -- --template react-ts cd my-img2threejs npm install three npm install -D @types/three

3.2 一个最小可运行的 Three.js 场景骨架

在接入 img2threejs 的生成结果之前，先手写一个最小场景，把渲染管线跑通，这样后面出问题好定位。下面这段代码创建了一个带光照的旋转立方体，是所有 Three.js 项目的"Hello World"。

import * as THREE from 'three'; const scene = new THREE.Scene(); scene.background = new THREE.Color(0x1a1a1a); const camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.1, 1000 ); camera.position.set(4, 3, 6); camera.lookAt(0, 0, 0); const renderer = new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); document.body.appendChild(renderer.domElement); // 光照：环境光 + 主方向光 scene.add(new THREE.AmbientLight(0xffffff, 0.6)); const dirLight = new THREE.DirectionalLight(0xffffff, 1.2); dirLight.position.set(5, 8, 6); scene.add(dirLight); // 物体 const geometry = new THREE.BoxGeometry(1.5, 1.5, 1.5); const material = new THREE.MeshStandardMaterial({ color: 0x4f9dff, metalness: 0.4, roughness: 0.35, }); const cube = new THREE.Mesh(geometry, material); scene.add(cube); // 渲染循环 function animate() { requestAnimationFrame(animate); cube.rotation.y += 0.01; renderer.render(scene, camera); } animate(); // 响应式 window.addEventListener('resize', () => { camera.aspect = window.innerWidth / window.innerHeight; camera.updateProjectionMatrix(); renderer.setSize(window.innerWidth, window.innerHeight); });

这段代码跑通之后，你就有了一个"容器"。img2threejs 生成的结果，本质上就是把上面这段里的geometry、material、light部分替换成从图片解析出来的内容。理解这一点，后面看生成代码就不会懵。

3.3 接入生成结果时的目录组织建议

生成结果不要直接往App.tsx里塞。建议按下面的结构组织，这样后续维护和替换都方便：

src/ scene/ SceneRoot.ts // 场景初始化与渲染循环 objects/ Table.ts // 单个物体的定义 Chair.ts materials/ palette.ts // 统一色板与材质参数 lighting/ setup.ts // 光照配置 assets/ textures/ // 贴图资源

把每个物体拆成独立文件的好处是：改一个物体不影响其他物体，也方便做懒加载。材质参数集中到palette.ts里，改配色只需要动一个文件。光照单独抽出来，是因为光照调整往往需要反复试，独立文件便于快速迭代。

4. 生成质量调优：让"能跑"变成"好看"

4.1 几何体比例失真的三种典型表现与修正

生成结果最常见的毛病就是比例不对。第一种是整体过大或过小，导致相机要么穿模要么看不清。修正方法是给场景加一个自动适配逻辑：计算所有物体的包围盒（Box3），然后根据包围盒尺寸自动调整相机距离。第二种是物体之间比例失调，比如桌腿比桌面还粗。这通常是语义解析阶段尺寸估计不准导致的，修正方法是引入"参考物"概念——在提示词里让模型以某个已知物体为基准推算其他物体尺寸。第三种是位置错位，物体之间该接触的没接触、该对齐的没对齐。修正方法是生成后做一次"吸附对齐"，把相邻物体的边界对齐到同一平面。

// 自动适配相机距离 const box = new THREE.Box3().setFromObject(scene); const size = box.getSize(new THREE.Vector3()); const center = box.getCenter(new THREE.Vector3()); const maxDim = Math.max(size.x, size.y, size.z); const fitDistance = maxDim / (2 * Math.tan((camera.fov * Math.PI) / 360)); camera.position.copy(center).add(new THREE.Vector3(1, 0.8, 1).normalize().multiplyScalar(fitDistance * 1.6)); camera.lookAt(center);

4.2 材质"塑料感"太重怎么破

生成结果另一个高频问题是所有东西看起来都像塑料。根因是材质参数太单一，roughness和metalness没有区分度。破解思路是按材质类别设置参数区间，而不是所有物体用同一套参数。下面这张表是我实测下来比较稳的参数区间，可以直接抄。

除了参数，环境贴图是提升质感的关键。没有环境贴图，金属和玻璃就是死板的纯色。Three.js 提供了RoomEnvironment可以程序化生成一张环境贴图，不需要外部 HDR 文件，非常适合生成场景。

import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js'; const pmrem = new THREE.PMREMGenerator(renderer); scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;

4.3 光照太平、没有立体感的调整思路

如果生成结果看起来"扁扁的"，问题基本出在光照。三点光照是基础，但很多人只加了环境光和一个方向光，导致阴影缺失、明暗对比不足。我的调整顺序是：先把环境光压到 0.3 到 0.5，让暗部有层次但不死黑；然后主光强度拉到 1.0 到 1.5，方向从侧上方打，制造明暗交界；再加一个补光从另一侧以 0.3 到 0.5 的强度填充暗部；最后开启阴影，让物体在地面或彼此之间投下阴影，立体感立刻就出来了。

renderer.shadowMap.enabled = true; renderer.shadowMap.type = THREE.PCFSoftShadowMap; const keyLight = new THREE.DirectionalLight(0xffffff, 1.3); keyLight.position.set(6, 10, 6); keyLight.castShadow = true; keyLight.shadow.mapSize.set(2048, 2048); keyLight.shadow.camera.near = 0.5; keyLight.shadow.camera.far = 50; scene.add(keyLight); const fillLight = new THREE.DirectionalLight(0xbfd4ff, 0.4); fillLight.position.set(-6, 4, -4); scene.add(fillLight);

提示：阴影贴图分辨率不是越高越好。2048 已经能满足大多数场景，4096 会明显增加 GPU 开销，移动端可能掉帧。如果场景很大，优先调整shadow.camera的near/far和范围，而不是一味提高分辨率。

4.4 性能优化：从 60 帧掉到 20 帧的排查路径

生成场景跑起来之后，如果帧率不理想，按下面的顺序排查。第一步看几何体数量：如果场景里有几百个独立 mesh，draw call 会爆掉，解决办法是用InstancedMesh合并重复物体，或者用BufferGeometryUtils.mergeGeometries合并静态几何体。第二步看材质数量：每个不同材质都是一次 draw call，能复用就复用。第三步看阴影：阴影是性能大户，如果场景不需要阴影就关掉，需要的话限制阴影相机范围。第四步看像素比：setPixelRatio不要超过 2，高分屏上 3 倍像素比会让渲染量翻倍还多。第五步看贴图尺寸：贴图不要超过 2048，能压缩就压缩。

import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js'; // 合并多个静态几何体，减少 draw call const geometries = meshes.map((m) => m.geometry.clone().applyMatrix4(m.matrix)); const merged = mergeGeometries(geometries); const mergedMesh = new THREE.Mesh(merged, sharedMaterial); scene.add(mergedMesh);

5. 把 img2threejs 接进 Agent：从单次生成到自动化流水线

5.1 为什么这个项目天然适合 Agent 架构

img2threejs 的流水线本身就是"多步骤、有中间产物、每步可校验"的结构，这正好是 Agent 擅长的场景。一个典型的 Agent 化改造是：把图像理解、几何映射、材质生成、代码编排拆成四个工具（tool），由一个 Agent 负责调度。Agent 拿到图片后，先调用图像理解工具拿到语义 JSON，再调用几何映射工具拿到几何描述，然后调用材质工具，最后调用代码生成工具产出文件。每一步的中间产物都可以被 Agent 检查，发现问题可以回退重试。

这种架构的好处是可观测、可干预。传统端到端模型是黑盒，出问题只能整体重跑；Agent 化之后，你能看到每一步的输出，哪一步不对就修哪一步。比如图像理解把桌腿数量搞错了，你只需要重跑这一步，不用重新生成整个场景。

5.2 工具函数的接口设计要点

把每一步封装成工具时，接口设计要遵循"输入输出都是结构化数据"的原则。图像理解工具的输入是图片 URL 或 base64，输出是固定 schema 的 JSON；几何映射工具的输入是语义 JSON，输出是几何描述数组；代码生成工具的输入是几何描述 + 材质描述，输出是文件内容字符串。每个工具都应该是幂等的，同样的输入给同样的输出，这样便于缓存和重试。

interface SceneSemantic { objects: Array<{ id: string; category: string; bbox: [number, number, number, number]; depthOrder: number; materialHint: string; colorHint: string; }>; camera: { angle: string; fov: number }; lighting: { direction: string; warmth: string }; } async function analyzeImage(imageUrl: string): Promise<SceneSemantic> { // 调用多模态模型，返回结构化语义 // 关键：约束输出 schema，失败时重试 }

5.3 并发与重试：Agent 跑批量任务时的坑

如果你要用 Agent 批量处理图片，并发控制是必须的。多模态模型的调用通常有速率限制，无脑并发会触发限流。稳妥的做法是用一个并发池，限制同时进行的请求数（比如 3 到 5 个），失败的请求进入重试队列，重试时加指数退避。另外，中间产物要落盘缓存，同一张图重复处理时直接读缓存，既省钱又快。

还有一个容易被忽略的点是超时处理。图像理解这一步可能因为图片太大或模型响应慢而超时，如果不设超时，整个流水线会卡死。建议给每个工具调用设一个合理的超时（比如 30 秒），超时后走降级逻辑，比如用更简单的提示词重试，或者返回一个基础场景。

6. 实操中踩过的坑与对应解法

6.1 贴图不显示：从加载路径到色彩空间

Three.js 贴图不显示是新手高频问题，我自己也踩过。排查顺序是这样的：先看路径对不对，浏览器控制台如果有 404，那就是路径问题，注意 Vite 项目里静态资源要放public目录或用import引入。再看加载时机，贴图是异步加载的，如果在加载完成前就渲染，会显示成默认色，解决办法是用TextureLoader的onLoad回调，或者用LoadingManager统一管理。最后看色彩空间，颜色贴图要设texture.colorSpace = THREE.SRGBColorSpace，否则颜色会发灰。

const loader = new THREE.TextureLoader(); const texture = loader.load('/textures/wood.jpg', (tex) => { tex.colorSpace = THREE.SRGBColorSpace; tex.wrapS = tex.wrapT = THREE.RepeatWrapping; tex.repeat.set(2, 2); material.map = tex; material.needsUpdate = true; });

6.2 生成代码里的类型报错怎么快速定位

TypeScript 项目里，生成代码经常有类型报错。最常见的几类：Object3D和Mesh的类型不匹配（scene.add接受Object3D，但访问.material需要断言成Mesh）；Vector3的set参数数量不对；Material的联合类型没收敛。快速定位的办法是看报错行号，然后对照 Three.js 的类型定义。如果生成代码里大量用了any，建议手动补类型，因为any会掩盖真正的错误。

注意：不要为了消错而到处加as any。类型报错往往暴露的是真实的逻辑问题，比如把一个Group当成Mesh用。花几分钟补对类型，比后面运行时崩溃再回来查要划算得多。

6.3 场景加载慢、首屏白屏的优化组合拳

首屏白屏通常是因为场景初始化阻塞了主线程，或者资源太大。优化组合拳是：代码分割，把 3D 场景做成懒加载组件，首屏先渲染占位内容；资源预加载，用LoadingManager显示加载进度；几何体简化，生成阶段就控制几何体复杂度，不要生成几十万面的球体；贴图压缩，用 WebP 替代 PNG/JPG，体积能小一半以上；渐进式渲染，先渲染低精度版本，再逐步替换成高精度。

const manager = new THREE.LoadingManager(); manager.onProgress = (url, loaded, total) => { console.log(`加载进度: ${loaded}/${total}`); }; manager.onLoad = () => { // 全部资源加载完成，隐藏 loading };

6.4 移动端适配：触摸交互与性能降级

移动端和桌面端差异很大。交互上，桌面用OrbitControls的鼠标拖拽，移动端要支持单指旋转、双指缩放，OrbitControls本身支持触摸，但要注意touch-action的 CSS 设置，否则会和页面滚动冲突。性能上，移动端 GPU 弱，需要降级：像素比限制到 1.5，阴影贴图降到 1024 或直接关阴影，几何体面数减半，关闭抗锯齿或改用 FXAA。检测方式可以用navigator.hardwareConcurrency或简单的 UA 判断，但更稳的是做一次性能探测，根据首帧耗时动态调整。

const isMobile = /Mobi|Android/i.test(navigator.userAgent); renderer.setPixelRatio(isMobile ? Math.min(window.devicePixelRatio, 1.5) : Math.min(window.devicePixelRatio, 2)); if (isMobile) { renderer.shadowMap.enabled = false; }

7. 这套流水线还能往哪些方向延展

7.1 从单图到多图：多视角融合提升精度

单张图的信息量有限，尤其是深度信息。如果能提供同一物体的多张不同角度图片，图像理解阶段就能做多视角融合，几何估计会准很多。实现思路是让模型分别解析每张图，然后做一次"视角对齐"，把不同视角下的物体描述合并成一个统一的三维描述。这一步的难点在于视角对齐，需要估计每张图的相机位姿，或者让模型直接输出"相对视角关系"。

7.2 加动画：让生成的场景动起来

静态场景只是起点，加上动画才是"会动的 3D"。Three.js 的动画系统支持关键帧动画（AnimationClip+AnimationMixer）和程序化动画（在渲染循环里改属性）。对于生成场景，程序化动画更容易自动生成，比如让物体缓慢旋转、让光源做周期性移动、让相机做环绕运动。这些都可以在代码生成阶段作为"动画配置"注入。

const clock = new THREE.Clock(); function animate() { requestAnimationFrame(animate); const t = clock.getElapsedTime(); // 相机环绕 camera.position.x = Math.sin(t * 0.3) * 8; camera.position.z = Math.cos(t * 0.3) * 8; camera.lookAt(0, 0, 0); renderer.render(scene, camera); }

7.3 与设计工具打通：从 Figma 到 3D 场景

一个很自然的延展是把输入从"图片"扩展到"设计稿"。Figma 里的图层结构本身就带有语义信息（图层名、分组、层级），比纯图片更容易解析。如果能读取 Figma 的图层树，几何映射的准确率会大幅提升，因为图层边界框直接就是物体的位置和尺寸。这条路线的工程价值很高，适合做设计工具插件的团队。

7.4 生成结果的可编辑性：可视化编辑器

生成代码之后，如果用户不会写代码，还是没法改。一个自然的延展是配一个可视化编辑器，把生成的场景参数（位置、旋转、缩放、颜色、材质）暴露成 UI 控件，用户拖拖拽拽就能调整，调整结果实时反映到代码里。这本质上是把"代码作为中间表示"的优势进一步放大——因为场景是代码描述的，所以任何参数都能被程序化修改。

8. 我个人的几点实操体会

做这类"图生 3D 代码"的项目，我最大的体会是不要追求一步到位。生成结果第一版大概率是歪的、丑的、比例不对的，这很正常。正确的做法是先把流水线跑通，拿到一个"能看"的结果，然后针对最影响观感的问题逐个优化。我通常的优化顺序是：先修比例和位置（影响最大），再修材质和光照（影响质感），最后修细节和动画（锦上添花）。

第二个体会是中间产物一定要可视化。图像理解输出的 JSON、几何映射输出的参数，都应该能直观看到。我习惯在开发阶段把这些中间结果打印到页面上，或者存成 JSON 文件，这样出问题的时候能快速定位是哪一步的锅。纯黑盒调试的效率太低了。

第三个体会是提示词的稳定性比提示词的"聪明"更重要。很多人喜欢把提示词写得很复杂很花哨，但实际跑起来输出格式经常飘。我的经验是提示词要短、要明确、要带输出格式约束，宁可让模型少做点推理，也要保证输出能被程序稳定解析。格式飘了，后面全白搭。

最后一个体会是性能要一开始就考虑。生成场景很容易越加越多，几何体、光源、贴图一路堆上去，等到发现卡了再优化，改动成本很高。我的做法是定一个性能预算，比如 draw call 不超过 100、总面数不超过 50 万、贴图总大小不超过 5MB，生成阶段就按这个预算控制，超了就简化。

这套流水线的价值不在于"生成得多完美"，而在于它把 3D 创作的门槛降到了"有一张图就行"，同时保留了代码的可编辑性。对于做 Web 3D 和 AI Agent 的人来说，这是一个非常值得研究的工程范式，里面的每一步拆解、每一个取舍，都能迁移到其他"AI 生成可执行产物"的场景里。