object-to-threejs-procedural

name	object-to-threejs-procedural
description	当用户提供或引用一张物体图片，并希望 Codex 先判断该物体能否在 Three.js 中重建，然后提取程序化雕刻规格、几何/材质/灯光方案，并实现或指导一个代码原生 3D 模型时，使用本 skill。

物体转 Three.js 程序化建模

当用户希望把一张物体参考图转化为程序化 Three.js 模型、视觉规格、重建方案、动画方案、破坏方案或代码实现时，使用本 skill。本 skill 面向代码原生重建，而非摄影测量或精确网格提取。

核心承诺

把这项任务当作照着照片做雕刻来对待：

1. 判断图片中是否含有合适的 3D 物体目标。
2. 把该物体提取为结构化的视觉与物理描述。
3. 将其从粗大形体分解到细小特征。
4. 用程序化 Three.js 几何体、生成材质、灯光以及可选的动画/破坏来重建它。
5. 在宣布完成前先做视觉与技术层面的验证。

不要假装单张图片就能产出精确的量产网格。当输出将是近似、风格化、低多边形或物理简化的重建时，请明确说明。

必需输入

至少需要：

• 一个图片路径、截图、URL 或附件图片
• 预期用途：独立模型、游戏道具、场景装饰、hero 渲染、可玩物体、可破坏物体或动画绑定

如果图片缺失或无法读取，请索要。如果预期用途缺失，则假定为浏览器实时 Three.js 道具，性能水平适合交互使用。

辅助脚本

当插件脚本能让循环更快或更可靠时就使用它们：

这些脚本位于插件根目录，而非本 skill 文件夹内。从本 SKILL.md 所在目录出发，使用 ../../scripts/...。

• ../../scripts/probe_reference_image.py <image> 检查图片类型、尺寸、宽高比以及明显的技术问题。它不能替代视觉检查。
• ../../scripts/extract_reference_pbr.py <image> --out-dir <dir> --material-id <id> --target-threshold 0.7 从图片像素中提取参考派生的反照率、粗糙度、高度、法线与 AO 贴图。当置信度低于目标阈值时，它以非零码退出。
• ../../scripts/extract_reference_pbr.py <image> --out-dir <dir> --material-id <id> --spec object-sculpt-spec.json --in-place 仅在置信度门控通过时，用可用的 referencePbr 贴图为材质打补丁，除非显式使用 --allow-low-confidence。
• ../../scripts/new_pre_spec_assessment.py "Object Name" --image <path> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json 创建预规格复杂度评估与质量契约骨架。
• ../../scripts/new_sculpt_spec.py "Object Name" --image <path> --out object-sculpt-spec.json 创建一份初始规格。
• ../../scripts/new_sculpt_spec.py "Object Name" --image <path> --assessment assessment.json --out object-sculpt-spec.json 从一份已完成的预规格评估创建初始规格。
• ../../scripts/validate_sculpt_spec.py object-sculpt-spec.json 校验必需字段、分数区间、材质引用、组件 ID、父级链接、变换以及基本体名称。
• ../../scripts/validate_sculpt_spec.py object-sculpt-spec.json --strict-quality 当规格结构合法但对其质量契约而言过于浅薄时判定失败。
• ../../scripts/sculpt_pass_orchestrator.py status object-sculpt-spec.json 报告当前锁定的构建阶段及所需证据。
• ../../scripts/sculpt_pass_orchestrator.py check object-sculpt-spec.json --pass-id blockout 除非该阶段当前已解锁或已完成，否则判定失败。
• ../../scripts/sculpt_pass_orchestrator.py sync object-sculpt-spec.json --in-place 从 reviewHistory 刷新 sculptPipeline。
• ../../scripts/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts 仅为当前解锁的构建阶段创建一个 TypeScript Three.js 工厂。
• ../../scripts/generate_threejs_factory.py object-sculpt-spec.json --pass-id structural-pass --out src/createObjectModel.ts 仅在此前各阶段均以 action=continue 通过评审后，才创建更深入的一个阶段。
• ../../scripts/make_visual_comparison_sheet.py --reference <image> --render <screenshot> --out <comparison.png> --json 创建一对完整的参考/渲染对比。AI 视觉从这同一对中为全局结果以及每个选定的语义特征评分。
• ../../scripts/append_sculpt_review.py object-sculpt-spec.json --pass-id <pass> --fidelity <0-1> --action <continue|refine-spec|refine-code|request-input|stop> --summary "..." --render-screenshot <path> --comparison-image <path> --ai-vision-score <0-1> --layer-scores-json '{"silhouetteProportion":0.8}' --feature-reviews-json <reviews.json> --ai-vision-notes "..." --camera-view <view> --in-place 记录每一次自我修正评审，以及全局与特征级的 AI 视觉证据。

实现类任务优先采用以下循环：

1. 若图片在本地，先探测（probe）图片。
2. 运行预规格评估门控（Pre-Spec Assessment Gate）：对物体做软性归类、为复杂度评分，并在撰写完整规格前写好质量契约。
3. 从已完成的评估与质量契约创建或修订 ObjectSculptSpec。 在严格校验之前，把通用的初始 featureReviewTargets 替换为该物体实际的、定义身份的语义系统。每个阶段最多保留五个关键（critical）目标和三个重要（important）目标。
4. 当材质保真度很重要且有源图片可用时，在 material-pass 之前为每个重要的材质裁切区/区域运行 extract_reference_pbr.py。将低于 0.7 的置信度当作停止/精修输入的信号，而非通过。
5. 先用常规校验验证规格，然后在代码生成前运行 --strict-quality。
6. 仅在严格质量门控通过后，或在显式记录已接受的保真度限制后，才生成工厂骨架。
7. 每次一个阶段地手工精修几何、材质、动画锚点与破坏锚点。在某个阶段的 sculpt_pass_orchestrator.py check 通过之前，不要生成或实现更深入的阶段。
8. 每个视觉阶段之后，捕获一张浏览器截图，创建一对完整的参考/渲染对比，用 AI 视觉检查一次，然后用总体、层级与语义特征分数更新 reviewHistory。
9. 运行项目的类型检查/构建与浏览器视觉评审；优先使用 Codex 应用内的 Browser 截图工具。除非用户显式要求走那条路线，否则不要仅为本 skill 安装或下载 Playwright/Chromium。

3D 术语纪律

描述必须清晰、具体，并与实时 3D 图形语言兼容。描述物体时，优先使用 references/3d-graphics-terminology.md 中的术语。

不要依赖诸如「好看」「真实」「光滑」「粗糙」「凹凸」「亮」「暗」或「脏」这类含糊描述，除非把它们翻译成技术术语：

• 几何：轮廓、拓扑意图、基本体族、倒角半径、斜切角、锥化、弯曲、扭转、布尔切割、边循环、局部形变、置换幅度
• 材质/PBR：反照率/基础色、粗糙度、金属度、法线贴图、凹凸贴图、置换贴图、环境光遮蔽、凹陷积污、边缘磨损、清漆层、透射、透明度
• 表面局部：局部遮罩、程序化噪声尺度、划痕簇、崩缺、凹痕、接缝、凹槽、凸脊、污渍、积尘、接触磨损
• 灯光/渲染：主光/补光/轮廓光、环境反射、接触阴影、阴影柔和度、色温、曝光、色调映射
• 动画/破坏：枢轴、铰链、关节、挂点、碰撞体、刚体、断裂缝、可分离碎片、冲量方向

每一条重要的视觉主张都应指明它所属的层：几何、拓扑、材质、纹理、着色器参数、灯光、动画、碰撞或破坏。对于复杂物体，在规格中包含 terminologyProfile，并将局部细节挂接到 viewEvidence。

图片验证门控

在做方案或写代码之前，检查图片并返回一个适配性裁定：

• pass：物体清晰、轮廓可读、可用程序化基本体重建
• conditional：可行，但需要假设、风格化、额外视角或降低保真度
• reject：物体信息不足，无法做出有用的程序化重建

对以下项按 0-3 打分：

• object_isolation：一个主体物体，而非拥挤的场景
• silhouette_readability：外形与比例清晰
• depth_inference：有足够线索推断前/后/侧的厚度
• primitive_decomposition：可由球体、盒体、圆柱、管、车削/挤出形体、曲线、实例化或形变曲面构建而成
• material_procedurality：材质可用颜色、粗糙度、金属度、法线、程序化噪声、贴花或顶点色来近似
• occlusion_risk：被遮挡部分有限或可被推断
• interaction_fit：物体能支持所需的动画、物理或破坏

在以下情况下拒绝或索要另一张图片：

• 目标物体无法辨识
• 多个物体相互竞争，目标含糊不清
• 物体被严重裁切或遮挡
• 目标要求从单张图片得到精确相似度
• 主体大部分是文字、透明玻璃、毛发、烟雾、液体或精细织物，程序化近似会主导最终结果
• 所需输出是带绑定的有机角色，但只有一个平面视角可用

提取阶段

在撰写完整规格之前，先创建一份预规格评估。不要使用硬编码的领域画像。用观察到的特征与复杂度来决定规格必须做到多深。

预规格评估门控

该门控的存在是为了防止浅薄的规格。它必须发生在 componentTree 与材质定稿之前。

复杂度评分与质量契约清单请使用 references/pre-spec-assessment.md。

评估：

• 物体类别，使用软性描述词，如有机、硬表面、机械、建筑、类植物、类角色、无定形、重复结构、静态道具、articulated、deformable 或 destructible
• 复杂度等级：simple、moderate、complex 或 ultra-complex
• 轮廓复杂度
• 预期组件数量
• 层级深度
• 重复密度
• 材质层数
• 局部细节密度
• 遮挡/隐藏结构风险
• 动画/破坏就绪需求

然后写一份 qualityContract，说明对这个具体物体而言「足够好」意味着什么。契约必须包含：

• 完成定义（definition of done）
• 最低规格深度：宏观组件、中观组件、微观特征组、材质层、重复系统、评审视点
• 带质量标准、证据引用与失效模式的必需特征组
• 用于截图评审的视觉差异检查
• 当规格过于含糊时阻止代码生成的反浅薄规则

对于简单物体，这份契约可以保持紧凑。对于复杂物体，契约必须强制要求深层组件层级、重复系统、材质局部覆盖以及多个截图视点。如果质量契约仍然通用到可以套用于任何物体，就在生成代码前先精修它。

通过预规格门控后，产出一份散文式或类 JSON 形式的 ObjectSculptSpec。对复杂物体使用 schema v2：

type ObjectSculptSpec = {
  targetName: string;
  schemaVersion: "2.0";
  terminologyProfile: TerminologyProfile;
  suitability: "pass" | "conditional" | "reject";
  assumptions: string[];
  preSpecAssessment: PreSpecAssessment;
  qualityContract: QualityContract;
  coordinateFrame: {
    front: string;
    up: string;
    scaleReference: string;
  };
  silhouette: {
    boundingShape: string;
    aspectRatios: string[];
    symmetry: string;
    dominantCurves: string[];
  };
  viewEvidence: ViewEvidence[];
  componentTree: SculptComponent[];
  materials: SculptMaterial[];
  qualityTargets: QualityTargets;
  selfCorrectLoop: SelfCorrectLoop;
  sculptPipeline: SculptPipeline;
  actionReadiness: ActionReadiness;
  repetitionSystems: RepetitionSystem[];
  : [];
  : [];
  : [];
  : [];
  : ;
  : [];
  : [];
  : [];
  : [];
  : [];
};

对于每个主要组件，需捕获：

• role：body、base、limb、handle、cap、shell、ornament、connector、surface detail
• level：macro、meso 或 micro
• 重要性（importance）与置信度（confidence），取值 0 到 1
• 基本体基底：box、sphere、cylinder、cone、torus、capsule、tube、lathe、extrude、curve sweep、plane cards、instanced cluster
• 几何描述符：拓扑意图、边缘处理、倒角半径、形变栈、UV 策略、法线策略
• 尺寸：宽度、高度、深度、半径、长度、锥化比例以及置信度
• 变换：位置、旋转、缩放、锥化、弯曲、扭转、倒角、布尔切割、噪声置换
• joints：父组件、overlap、seam、hinge、socket、embedded、glued、floating
• action profile：animation role、pivot 模式/局部位置/轴、transform channels、sockets、碰撞体代理、约束、破坏行为
• 材质层：基础色、调色板变化、粗糙度、金属度、法线、凹凸、置换、透明、边缘磨损、污垢、苔藓、划痕、崩缺、湿润、纹理
• 局部特征：逐区域的痕迹、凹痕、孔洞、接缝、污渍、脊、凸起细节、刻线、贴花、崩缺以及磨损斑
• 证据引用：哪个图片区域支撑这个组件或局部特征
• 保真度等级：blockout、中等细节、特写细节

对于复杂物体，不要把一切都压平成单个 details 字符串。请使用：

• viewEvidence 记录图片区域与观察到的局部特征。
• terminologyProfile 让描述与 3D 图形词汇保持一致。
• material.localOverrides 描述局部的颜色/粗糙度/凹凸差异。
• component.localFeatures 记录几何可见的细节。
• component.surfaceDetail 记录宏观粗糙度、微观粗糙度、凹凸幅度、法线图案与置换图案。
• repetitionSystems 记录重复的螺丝、叶片、鳞片、齿、珠、面板、铆钉、孔洞或缝线。
• buildPasses 说明从粗到细的雕刻顺序与验收标准。

反浅薄规则：一个复杂物体如果只有一个 root 组件、没有重复系统、没有材质局部覆盖、没有微观特征组，那么即便 JSON schema 校验通过，它也不具备实现就绪性。

动作就绪模型契约

构建每一个生成的模型时，都要当作用户之后可能要求动画、变换、物理或破坏。不要产出一坨漂亮但毫无生气的网格。

枢轴、挂点、碰撞体与破坏层级规则请使用 references/action-ready-models.md。

规格应包含 actionReadiness，且每个宏观/中观组件都应包含 actionProfile：

• animationRole：root、static、articulated、deformable、detachable、breakable、effect-emitter 或 socket-only。
• pivot：模式、局部位置、轴与置信度。使用语义枢轴，如底座、铰链、关节、质心、枝干根部、手柄挂点或自定义。
• transformChannels：是否预期发生平移、旋转、缩放、弯曲、扭转、分离、可见性或材质状态变化。
• sockets：为手、工具、枝干、轮子、盖子、抛射物、特效或后续子物体命名的挂接点。
• collider：简化的运行时代理，如 box、sphere、capsule、cylinder、凸包、复合体、触发器或 none。
• constraints：铰链限位、滑动限位、弯曲限位、弹簧行为、父级锁定或物理约束。
• destruction：breakable 标志、断裂组、接缝引用、可分离碎片、断裂冲量、碎屑材质与特效锚点。

生成规则：

• 把每个可独立变换的部件放在一个稳定的 THREE.Group 枢轴节点之下；把视觉网格作为其子级。
• 在 root.userData.sculptRuntime 中存储运行时映射：nodes、meshes、sockets、colliders 与 destructionGroups。
• 避免合并那些之后可能移动、分离、弯曲、断裂、切换材质或独立接受碰撞的部件。
• 将程序化接缝与组件边界用作未来的断裂线；不要依赖随机爆炸。
• 如果物体确实没有可动部件，仍要包含一个 root 枢轴、整体物体碰撞体与破坏策略，以便之后的整体物体动作依然易于实现。

自我修正循环

构建必须是一个反馈循环，而非盲目的单向生成。

每个构建阶段之后，暂停并对照源图片、用户需求、qualityTargets.mustMatch 以及当前的 ObjectSculptSpec 进行评审。

使用以下评审形式：

passId:
estimatedFidelity: 0..1
matched:
mismatches:
rootCause: spec gap | code gap | rendering/lighting gap | reference ambiguity | performance tradeoff
decision: continue | refine-spec | refine-code | request-input | stop
specFixes:
codeFixes:
evidence:
visualEvidence:
  referenceScreenshot:
  renderScreenshot:
  comparisonImage:
  cameraView:
  notes:
  aiVisionNotes:
aiVisionScore: 0..1
visualAcceptanceThreshold: 0..1
layerScores:
  silhouetteProportion: 0..1
  componentStructure: 0..1
  formDetail: 0..1
  materialSurface: 0..1
  lightingCamera: 0..1
featureReviews:
  - id:
    score: 0..1
    visible: true
    notes:

决策规则：

• continue：当前阶段满足其验收标准，且不威胁后续质量。
• refine-spec：实现过程揭示规格有误、不完整、含糊，或缺少组件/材质/局部特征细节。
• refine-code：规格足够，但生成的几何/材质/灯光与之不匹配。
• request-input：所需信息隐藏在图片中，或用户预期与可用证据相冲突。
• stop：达到目标保真度、用户接受了该近似，或剩余差距需要新参考/手工美术。

当决策为 refine-spec 时，先修订规格，重新运行 ../../scripts/validate_sculpt_spec.py，然后继续实现。不要围绕一份糟糕的规格给代码打补丁。当决策为 refine-code 时，保持规格稳定，修复工厂/材质/渲染代码。

只要存在规格文件，就用 ../../scripts/append_sculpt_review.py 记录评审条目。如果还没有规格文件，就在继续之前在回复中写下相同的评审摘要。

截图反馈门控

对于浏览器可渲染的构建，截图是强制性反馈，而非可选装饰。Codex 不应仅凭代码检查就判定某个视觉阶段已足够好。代码不能是图像对比的最终权威：最终的阶段决策来自 AI 视觉检查一张并排的参考/渲染对比图。

详细的截图对比清单请使用 references/browser-screenshot-feedback.md。 当形状可接受但材质、颜色、纹理或灯光保真度仍然薄弱时，使用 references/material-lighting-realism.md。 当部件挂接到父级时——枝干、肢体、手柄、腿、角、翼、缆线、管、挂点、铰接部件或装饰性附属物——使用 references/attachment-joint-correctness.md。

采用以下顺序：

1. 在浏览器或项目预览中渲染当前模型。
2. 在来自 qualityTargets.reviewViewpoints 的相关评审视点捕获一张截图。
3. 为本阶段选择语义评审目标：
   • critical：最多五个定义身份或高风险的系统；每一个都必须独立通过。
   • important：自适应评审，最多三个可疑系统；其评审后的平均分必须通过。
   • detail：记录不匹配之处但不阻塞阶段。 把重复部件归为一个语义系统。不要为每个网格都创建一个目标。
4. 用 ../../scripts/make_visual_comparison_sheet.py --reference <image> --render <screenshot> --out <comparison.png> 创建一个对比产物。
5. 用 Codex AI 视觉检查对比图，并按层评分：
   • 轮廓/比例
   • 组件位置与层级
   • 局部几何特征
   • 材质反照率、粗糙度、金属度、法线/凹凸/置换
   • 灯光、阴影、曝光与相机角度
6. 从这同一对完整图像中，独立地为每个关键语义特征评分。即便全局分数很高，只要有一个关键特征未通过，该阶段就失败。
7. 将每处不匹配归类为 spec gap、code gap、rendering/lighting gap、reference ambiguity 或 performance tradeoff。
8. 把截图对、对比图、总体 AI 视觉分数、层级分数、特征分数与批评记录到 reviewHistory.visualEvidence 与 visualEvidence。

在可用时默认使用 Codex 应用内的 Browser 截图工具。Playwright/Chromium 不是本 skill 的默认验证路径；除非用户显式要求走那条路线，否则不要仅为获取截图而安装或下载浏览器运行时。如果无法捕获截图、不存在对比图、AI 视觉尚未评审、全局分数低于阈值，或任一关键语义特征低于其阈值，就不要选择 continue；应选择 refine-spec、refine-code、request-input，或解释阻塞点。

最低门控：

1. blockout：截图证明轮廓、比例、基本体族与坐标系。
2. structural-pass：截图证明组件层级、父/子放置、joints、接缝、重复系统以及稳定的动作就绪节点边界。
3. form-refinement：截图证明倒角/斜切角/锥化/弯曲/形变、局部几何特征，且没有悬空的子级关节。
4. material-pass：截图证明反照率、粗糙度、金属度、法线/凹凸/置换、AO、污垢、磨损、局部覆盖。
5. lighting-pass：截图证明与参考无关的材质可读性，外加可选的参考灯光匹配。
6. interaction-pass：截图或短渲染捕获证明枢轴、挂点、碰撞体、动画锚点、断裂缝、可分离碎片与运行时元数据。
7. optimization-pass：三角形预算、绘制调用、实例化、LOD 与 FPS 目标。

锁定构建阶段门控

构建循环是顺序进行的。Codex 不得从一份完成的规格直接跳到打磨完成的模型。

在每个实现阶段之前：

1. 运行 ../../scripts/sculpt_pass_orchestrator.py status object-sculpt-spec.json。
2. 运行 ../../scripts/sculpt_pass_orchestrator.py check object-sculpt-spec.json --pass-id <pass>。
3. 仅生成或编辑已解锁的阶段。
4. 在 Codex 应用内 Browser 中渲染并捕获截图证据。
5. 用 ../../scripts/make_visual_comparison_sheet.py 构建一对完整的参考/渲染对比。
6. 用 AI 视觉检查一次，并记录总体、层级与关键语义特征分数，外加具体的不匹配备注。
7. 用 ../../scripts/append_sculpt_review.py ... --pass-id <pass> --action continue --render-screenshot <path> --comparison-image <path> --ai-vision-score <0-1> --layer-scores-json '<json>' --feature-reviews-json <reviews.json> --ai-vision-notes "..." --camera-view <view> --in-place 追加评审。
8. 当评审历史被手工编辑时，运行 ../../scripts/sculpt_pass_orchestrator.py sync object-sculpt-spec.json --in-place。

默认生成器是按阶段门控的。不带 --pass-id 调用 generate_threejs_factory.py 时使用 sculptPipeline.currentPass。带一个未来的 --pass-id 调用它，在此前各阶段完成之前必须失败。这是有意为之：先雕大形（blockout），再结构，再形体，然后是材质与表面细节。

材质与灯光阶段有额外的 look-dev 门控。material-pass 不得只带扁平的基础色就推进；它需要调色板、粗糙度变化、法线/凹凸/置换意图与局部遮罩。lighting-pass 不得只带环境光就推进；它需要主光/补光/轮廓光或环境光、曝光、色调映射、背景、阴影柔和度与接触阴影行为。

当 lookDevTargets.qualityPriority 为 reference-fidelity 时，施加质量优先门控：

• 重要的特写材质使用独立的反照率、粗糙度、高度/法线与 AO 通道
• 表面响应被分解为宏观、中观与微观频段
• 重要的程序化贴图至少 1024px，最好 2048px
• 如果存在源图片，重要的特写材质具备可用的 referencePbr 像素提取，置信度 >= 所配置的目标阈值，默认 0.7
• UV/投影与纹素密度意图是显式的
• 影响轮廓的浮雕使用几何或具备置换能力的拓扑
• 材质评审包含中性、掠射光特写与参考匹配的截图
• 优化发生在保真度被接受之后；不要仅为了达到某个任意的多边形下限而移除参考关键的几何

参考 PBR 提取是一个推断门控，而非魔法保证。从一张照片出发，Codex 无法唯一地还原真实的物理反照率、粗糙度、高度、法线与 AO。如果提取器置信度低于目标阈值，或渲染出的材质仍未通过截图评审，应选择 request-input、refine-spec 或 refine-code，而不是假装材质达到了所要求的保真度。

结构与形体阶段有一个挂接门控。诸如枝干、肢体、手柄、腿、角、翼、管、缆线、连接件与铰接部件之类的子附属物，必须包含 attachment.parentSocket、localStart、localEnd、contactType、embedDepth 或 overlap 与 gapTolerance。生成器应从根端点到尖端端点来构建这些部件，而不是把它们居中于某个任意变换处。

agent 应愿意说：「以当前图片无法达到所要求的保真度。」这是一个有效的自我修正结果。

重建策略

采用分层雕刻工作流：

1. blockout：用简单基本体与正确比例构建轮廓。
2. structural pass：添加子组件、挂点、支撑、铰链、手柄、腿、枝干、鳍或肋。
3. form refinement：给硬边倒角、锥化圆柱、弯曲管件、添加曲线扫掠、添加有机噪声，并在图片要求处打破完美对称。
4. surface pass：仅在有意义处添加生成的法线贴图、程序化噪声、顶点色，树皮/石头/金属/塑料/布料图案、划痕、湿润、污垢、边缘高光与小型重复几何。
5. material pass：调节粗糙度/金属度/清漆层/透射/透明度，使表面不会看起来像塑料（除非它本该如此）。
6. lighting pass：把实际的物体材质与照片灯光分离；创建一个中性转台灯光，外加可选的参考匹配灯光。
7. interaction pass：仅当用户需要运动或破坏时，添加枢轴、骨骼、碰撞体、动画手柄、断裂点与可分离碎片。
8. optimization pass：对重复细节做实例化，在安全处合并静态部件，限制几何密度，并保住 FPS 目标。

Three.js 实现规则

• 优先使用 TypeScript 与纯 Three.js，除非现有项目使用了另一种 Three 封装。
• 使用诸如 createObjectNameModel(spec, options) 的 Group 工厂，而非散落的网格创建。
• 让重建数据与渲染器对象保持分离，以便修订规格时无需重写场景。
• 对程序化噪声、表面变化与重复细节使用确定性种子。
• 从独立的确定性场生成不相关的 PBR 通道。绝不要把反照率纹理别名（复用）到粗糙度、高度、法线或 AO。
• 对触感材质使用宏观/中观/微观频段；单一频率的随机痕迹通常显得合成感十足。
• 对质量优先目标，先把多边形花在影响轮廓的浮雕上，并对特写材质使用 1024-2048px 贴图，然后再为性能降低质量。
• 即便首次生成的几何仅是 blockout，也要在代码元数据（userData）中保留局部材质特征。
• 对实时场景，把轮廓与材质可信度置于隐藏的微观几何之上。
• 在导入外部美术之前，先使用几何基本体、Shape 挤出、曲线/管几何、实例化、置换/噪声与生成的 canvas 纹理。
• 为未来的动画使用网格层级：body 根、可动肢体、铰接部件、可分离部件与特效发射器。
• 对挂接的子级，把枢轴放在挂接根/挂点处，并让几何从 attachment.localStart 朝 attachment.localEnd 定向。
• 对破坏，显式定义断裂组与接缝，而不是随机爆炸整个物体。
• 添加一个简单的参考相机/转台或截图角度用于视觉对比。

松林原型的经验教训

应用这些来之不易的模式：

• 含糊的「做得更好点」反馈很无力。把视觉批评转化为命名的重置：Material Realism Reset、Silhouette Reset、Water Surface Reset、Vegetation Structure Reset 等等。
• 一个可信的模型需要几何、材质、灯光与尺度彼此一致。只修一层通常会让结果看起来很假。
• 避免完美的程序化光滑。加入受控的不均匀：倒角变化、颜色斑驳、粗糙度变化、微观法线、接缝处污垢、边缘磨损与不对称。
• 让视觉进展在浏览器中保持可见。小循环胜过大而不可见的重写。
• 保护性能：对重复细节做实例化、保持碰撞简化，并避免那些只为掩盖糟糕材质而存在的几何。
• 当用户对照参考图时，在改代码之前显式指出不匹配之处。

输出格式

对于仅分析的请求，返回：

1. 适配性裁定与分数。
2. 目标物体提取。
3. 从宏观到微观的组件层级。
4. 几何策略。
5. 材质与灯光配方。
6. 动画/破坏可行性。
7. 实现方案与风险。

对于实现类请求，先简要地做上述同样的事，然后编辑代码。用类型检查/构建验证，并在存在浏览器场景时，检查截图或渲染输出。

失败处理

如果从所提供的图片无法可行地重建，不要伪装出信心。解释阻塞点，并请求以下之一：

• 前/侧/后参考图片
• 更干净、物体已隔离的图片
• 接受一个风格化近似
• 允许使用生成的占位式解读
• 一个更窄的目标，如仅轮廓、仅材质研究，或仅动画/破坏设计。