dsh-scene-skeleton-pipeline

2) 最小配置（设置 → 场景骨架流水线）

核心链路只需要三项：comfyUrl（默认 http://127.0.0.1:8188）、blenderExe（留空自动探测）、 outputDir（留空用 $DSH_HOME/scene-skeleton-pipeline/outputs）。要启用 Unity 装配再填 unityProjectPath 并把 enableUnityAdapter 打开。完整字段见配置项。

配置项

字段	说明
blenderExe	Blender 可执行文件（空 = 自动探测；macOS 默认 /Applications/Blender.app/Contents/MacOS/Blender）
comfyUrl	ComfyUI 地址（默认 http://127.0.0.1:8188）
comfyWorkflowPath	ComfyUI API 格式工作流 JSON（空 = 内置 txt2img 模板）
comfyCheckpoint	checkpoint 文件名（空 = 自动取 /object_info 里的第一个）
comfyNegativePrompt	负向提示词（空 = 内置默认）
unityProjectPath	Unity 工程根目录（需含 ProjectSettings/ProjectVersion.txt；仅适配器需要）
unityExe	Unity 可执行文件（空 = 按工程 m_EditorVersion 自动探测）
outputDir	产物目录（空 = $DSH_HOME/scene-skeleton-pipeline/outputs）
blenderSceneMode	scenic（默认，声明式）或 legacy（旧固定体块 + 参考图平面）
scenicWidth / scenicDepth / scenicWallHeight	scenic 庭院参数（默认 24 / 20 / 3.2 米）
enableUnityAdapter	是否追加 Unity 装配节点（默认 false）
sceneSource	template（默认，用 scenic spec 的固定布局）或 llm（按 layoutObjects 的 plan 精确摆放）
layoutObjects	sceneSource='llm' 的布局来源：plan JSON 文件路径，或直接内联 JSON 字符串
layoutAxis	layout.json 坐标系：z-up（默认，Blender 原生）或 y-up（Unity 转换值）
layoutValidation	精确布局的物理合理性容差（JSON 对象，面板可改）：maxCollisionOverlap（默认 0.1 m）、maxFloatHeight（0.3 m）、groundTolerance（0.05 m）、sceneBounds（[-50, 50]）
assetLibraryPath	材质贴图根目录（可选）：lib/asset-library.json 里每个材质 key 的 albedoPath 等相对它解析；留空 = 纯色 fallback（见「材质映射」）
assetModelPath	几何模型根目录（可选）：lib/asset-library.json 里每个 type 的 modelPath 相对它解析；留空 = 全部程序化图元（见「几何模型库配置」）
enableTextureGeneration	是否用 SuperPBR 给对象生成 PBR 贴图（默认 false；可选增强，见下文「可选增强：PBR 贴图」）
textureResolution	贴图分辨率（默认 512，256–2048；越大越慢、越吃显存）
textureObjects	main（默认：地面 + 柱/墙/拱门/门房）或 all（三组全部对象；每对象一次推理，很慢）
texturePromptPrefix	预留给贴图阶段的文本前缀（当前版本仅记录，尚未参与推理）

保存后配置写两处：$DSH_HOME/scene-skeleton-pipeline/config.json（权威）与 profile 的 cordis.patch.yml （bundle 安装时可用；--patch 开发覆盖层下宿主会拒绝写 profile，属预期）。

几何模型库配置（asset-library 的 GLB 资产）

默认装配用程序化简单图元（柱=圆柱+顶底、树=圆柱+圆锥等），够做灰盒但「积木感」强。 配置 assetModelPath 后，sceneSource='llm' 的装配会优先用真实 .glb/.gltf 模型替换图元，摆脱积木感。

工作原理：lib/asset-library.json 里每个 type 有一个可选 modelPath（相对 assetModelPath）。 装配某个对象时：

1. 若 assetModelPath/.modelPath 存在 → bpy.ops.import_scene.gltf() 导入真实模型；
2. Join 合并所有 mesh（删掉导入的空节点/灯光/相机）；
3. 底部中心对齐原点：把包围盒的底部中心平移到局部原点（贴地，不悬空）；
4. 等比缩放：按 plan 的高度比例统一缩放（scale = plan高度 / 模型高度，宽高深同比例，不拉伸）；
5. 保留自带材质：模型带材质槽就用它自带的；没有材质槽才回退 _material(key) 纯色/材质映射；
6. 重命名为对象 id、打 asset_source="model"、挂到对应分组 Empty 下。

找不到模型时回退程序化图元（打 asset_source="primitive"），不会让流水线失败。

内置资产速配指南（4 个 CC0 包，全部可免费商用；下载解压后按下方文件夹名放入 assetModelPath 根目录）：

资产包	下载链接	解压后创建的文件夹	覆盖的 type（放入的 .glb 文件名）
Kenney「Nature Kit」		kenney_nature/	tree→tree_pine.glb、bush→bush.glb、rock→rock_large.glb
Kenney「Fantasy Town Kit」		kenney_fantasy/	fountain→fountain.glb、lantern→lantern.glb、planter→planter.glb
Quaternius「Medieval Village MegaKit」		quaternius_medieval/	column→column_stone.glb、wall→wall_stone.glb、archway→arch_stone.glb、gatehouse→gatehouse.glb、platform→floor_stone.glb、stairs→stairs_stone.glb、bench→bench.glb
Quaternius「Survival Kit」		quaternius_survival/	crate→crate.glb、barrel→barrel.glb、statue→statue.glb、table→table.glb、chair→chair.glb

这些 modelPath 是标准契约（写在 lib/asset-library.json，每个 type 还带 license: "CC0" 与 sourceUrl 来源链接）。包里文件命名不一定完全一致——只要把包里对应语义的 .glb 重命名成上表 路径放进对应文件夹即可。

未下载任何包时：项目会平滑回退到程序化图元（asset_source="primitive"），全链路测试照常全绿、 不报错（verify-geometry-mapping.sh 有专门的「18 种 type 全量回退」断言覆盖这一点）。

注意：几何映射只换几何，不换贴图。真实模型若带自带贴图就直接用；想要统一风格，配合 「可选增强：PBR 贴图（SuperPBR）」一起开，SuperPBR 会给替换后的模型重新生成独立材质。

结果与面板：summary.geometryMapping = { modelsUsed, primitivesFallback }，面板显示 「几何映射：使用 N 个真实模型，M 个回退图元」。

验证：bash scripts/verify/verify-geometry-mapping.sh（fixture GLB → 未配置全 primitive / 配置后 tree=model 且底部对齐 + 等比缩放 + 高度匹配 plan / 回退 primitive + 回归）。