3D Model Generator by Three.js
该技能用于根据自然语言请求生成程序化 3D 模型，通过编写受约束的 buildModel(ctx) 模块使用 Three.js、内置构建器与辅助函数，同时让模型构造辅助、校验、导出与审查保持确定性和可复用性。
用途
Generate model-specific JavaScript while keeping model construction helpers, validation, export, and review deterministic and reusable.
工作流程
-
在本技能之外选择任务输出目录。
-
运行 node scripts/init-model-task.mjs --out <task-dir>，在不覆盖已有工作的前提下复制 build-module 模板。
-
阅读 references/build-contract.md。使用内置构建器或辅助函数前阅读 references/builder-api.md。选择格式前阅读 references/export-formats.md。
-
仅编辑 <task-dir>/model-build.mjs。导出一个 buildModel(ctx) 函数并保持其确定性。
-
使用 npm ci --prefix scripts 一次性安装固定版本运行时。
-
构建、校验并导出：
node scripts/build-and-export.mjs --build <task-dir>/model-build.mjs --out <task-dir> --formats glb,obj,stl
-
检查 <task-dir>/validation.json。修复所有错误，并评估影响所请求格式的警告。
-
渲染导出产物的确定性 PNG 预览：
node scripts/render-preview.mjs --model <task-dir>/model.glb --out <task-dir>/preview.png --views iso,front,top
阅读 references/preview-rendering.md 了解支持的格式、视图和渲染限制。
- 当交互式视觉审查有用时，运行：
node scripts/serve-viewer.mjs --artifact-dir <task-dir> --model model.glb
用可用的浏览器工具打开打印出的本地 URL。审查导出产物，而不只是源场景。需要对比源场景时使用 --source model-build.mjs。
- 仅修改 model-build.mjs、重新构建并再次审查，以此迭代。
构建规则
- 返回 THREE.Object3D 或 { root, animations, metadata }。
- 常见构造使用 ctx.builders 和 ctx.helpers。自定义几何体直接使用 ctx.THREE。
- 不要从生成的构建代码导入模块。不要访问文件、进程、环境变量、网络 API、动态导入、eval 或 Function。
- 使用 ctx.rng 而非 Math.random()，以便修订可复现。
- 除非请求另有要求，默认 Y 轴向上、单位为米。
- 用于 GLB 时优先使用 MeshStandardMaterial、MeshPhysicalMaterial 或内置材质预设。
- 默认 Node 导出路径中不要包含纹理。纹理编码需要浏览器或单独的具备图像能力的运行时。
- 设置有意义的节点名称，并将多部件资产组织在组下。
- 三角形数量与请求的用例保持比例。远处或移动端资产使用较低分段数。
校验与审查
- 先运行数值校验，再进行视觉审查。校验器检查有限的变换和顶点、空几何体、法线、边界、计数、不支持的着色器材质、纹理以及配置的限制。
- 视觉审查时检查：
- 轮廓与可识别形状；
- 相对缩放与比例；
- 对称性、对齐、接地情况与意外相交；
- 正面、背面、侧面、顶部和透视视图；
- 材质分离与最终格式保真度；
- 拓扑重要时的线框密度。
- 优先对 GLB、OBJ 或 STL 进行往返审查。当导出丢失层级、材质、变换或动画时，源模式可能看起来仍然正确。
完成标准
仅当以下条件满足时才完成模型任务：
- build 模块在无禁止能力的情况下运行；
- 校验不包含错误；
- 所请求的每个文件都存在且非空；
- 浏览器审查可用时，导出文件审查结果令人满意；
- 使用记录的种子可复现构建；
- 生成的源码和产物保留在本技能目录之外。
资源
- scripts/runtime/：稳定的构建上下文、构建器、辅助函数、带种子的 RNG、源码检查与场景校验。
- scripts/exporters/：针对特定格式的 GLB/glTF、OBJ 和 STL 导出器。
- scripts/build-and-export.mjs：主确定性流水线。
- scripts/render-preview.mjs：独立的导出模型 PNG 渲染器。
- scripts/serve-viewer.mjs：本地源与往返查看器服务器。
- assets/model-build.template.mjs：生成任务的起点。
- assets/viewer/：浏览器审查应用。
- references/build-contract.md：生成模块契约与安全规则。
- references/builder-api.md：构建器与辅助函数 API。
- references/export-formats.md：格式能力与限制。
- references/preview-rendering.md：独立预览命令与限制。