SuperAPI AI 工具集

iwsdk-build-model

编程与开发

查看项目

更新于 11-17 00:29

技能介绍

用途

本技能负责创建一个可复用的 IWSDK 3D 模型,或对已有模型做实质性修复,并确认模型从多个视角都成立,最终交给 iwsdk-compose-scene 一个稳定的 manifest 资产。它负责对象自身的几何、材质、层级、比例和细节,不负责场景 JSON,也不负责资产之间的相对摆放。UIKitML 面板属于 iwsdk-ui,不归本技能。

主要能力

  • 定义模型契约:轮廓与整体比例、主/次/三级形态、可独立阅读的部件、负空间与接触点、材质族、标准视角、需重点检查的命名部件。
  • 选择表示方式,优先级为:现有合适清单资产 → 项目自有可检查层级的 glTF → 可安装的复用资产或模板 → 需要可控尺寸/语义子部件/关节/可重复代码变化时采用确定性程序化 Object3D。
  • 由大到小建模:先轮廓与主体块,再比例相关次形态与负空间,然后接缝、支撑与功能连接,最后重复三级细节与材质区分。
  • 强制表面相对细节:斜率/曲面上的通风口、板、格栅、螺栓、鳍片、贴花、支撑等,需建立局部坐标系后再摆放,避免出现悬空或竖立的错误细节。
  • 提供捆绑的硬表面构建库(hardsurface.ts 模板),包含 loft 管道/叶片面、表面坐标系、镜像修复绕序、倒角块/锥板、span 对齐、种子随机等辅助函数。
  • 通过 CLI 或 MCP 渲染预览:默认输出前、后、右、顶、四分之一视角的单张接触表,并返回包围盒、对象/网格/几何/材质数量、渲染三角数、命名部件包围盒及缺失几何、法线异常、退化三角形、未命名网格等确定性警告;可聚焦指定命名子树。
  • 材质与素模(clay)双通道审查,将几何/附着缺陷与光照/材质响应问题分开。

使用方式

资料给出的关键操作包括:

复制捆绑起始库:

model_kit="$(find .claude/skills .agents/skills -path '*/iwsdk-build-model/assets/hardsurface.ts.template' -print -quit)"
mkdir -p src/scene-assets/lib
cp "$model_kit" src/scene-assets/lib/hardsurface.ts

渲染预览:

npx @iwsdk/cli asset render-preview \
  --input-json '{"assetId":"ship","mode":"material"}' \
  --output-file artifacts/ship-material.png
npx @iwsdk/cli asset render-preview \
  --input-json '{"assetId":"ship","mode":"clay"}' \
  --output-file artifacts/ship-clay.png

聚焦检查命名部件:

npx @iwsdk/cli asset render-preview \
  --input-json '{"assetId":"ship","mode":"clay","focus":"Ship/Hull/VentRow"}' \
  --output-file artifacts/ship-vent-row.png

流程约定:几何与材质只能放在 glTF 或 src/scene-assets/*.scene-asset.ts 中,不能写入 scene JSON;结果登记到配置的 src/assets.ts 默认清单导出;程序化导出必须是确定性、无父级的 Object3D 原型,定义中不得使用 World、DOM 状态、定时器或共享对象标识;Three.js 类要从 @iwsdk/core 导入,不能直接来自 three;新多文件模型在首个完整资产模块与清单登记通过 npm run --if-present typecheck 之前不要启动 iwsdk dev up。使用米制单位,并显式写明资产原点、前向轴、地板/接触面、尺寸包络与挂载锚点。预览保持在 640×480 或更小,缺陷可聚焦而非提高分辨率。

适用场景

WebXR/Three.js 项目中需要新增或实质性修复一个可复用模型资产时;需要为后续场景组装准备稳定 manifest 资产时;需要程序化生成可控尺寸、语义部件明确、可重复的模型时;需要独立验证模型几何、附着与材质分离是否成立时。

限制

  • 不拥有场景 JSON 或资产间摆放,重复摆放属于 iwsdk-compose-scene。
  • UIKitML 面板不归本技能。
  • 下载的模型不保证含可用语义部件,需先检查再采用,并复制到项目自有存储而非持久引用临时的 CDN URL。
  • 单张参考图只能证明可见部分,隐藏几何需标为假设。
  • 超过约 700 个网格或 100,000 渲染三角时应触发评审,而非作为目标。
  • 建议授权 2–6 个模块;模块过大时按真实所有权边界拆分,不逐部件建文件。
  • 每次预览接触表为单张有界图;调用工具时源文件约 100 行或 10 KB 视为传输硬上限。
  • 首次完整模型后默认最多两轮聚焦修正;遇到重复缺陷、振荡、诊断平台期、证据缺失或表示上限时提前停止。
  • 模型局部缺陷不得用场景变换补偿;场景光照或相机迭代需等模型通过隔离审查后再开始。