W
AI-Wiki
SOURCE

dsh-scene-skeleton-pipeline 介绍 - 今日头条文章摘要

文档概览

这篇文章把 dsh-scene-skeleton-pipeline 定位为 DSH(DeepSeek Harness) 生态里的“编排插件”,而不是独立桌面软件、独立 CLI 或一个包办所有工作的 3D 生成应用。它的入口依赖 DSH profile、DSH 命令行或 DSH 的 Web 控制台;命令行和 Web 控制台是 DSH 提供的入口,不是插件自身提供的独立产品形态。

文章描述的核心流水线是:用户输入一段文字描述,插件调用 ComfyUI 生成概念图,再让 Blender 以无头模式生成引擎无关的 3D 场景骨架,可选追加 Unity 装配。主要产物包括 scene.blend、scene.fbx、scene.glb 和 layout.json。

文章反复强调,“场景骨架”不是完整可玩的关卡,而是一份可继续编辑的灰盒场景。它带有层级、光照、相机和参数化物件,目的是给后续真实美术资产填充、替换和精修提供基础结构。它不生成碰撞体、刚体物理、导航、触发器,也不保证白盒可行走。

关键事实

身份与入口

  • dsh-scene-skeleton-pipeline 是 DSH(DeepSeek Harness) 生态里的编排插件。
  • 它不是独立桌面软件,也不是独立 CLI。
  • 它通过 DSH profile 安装和挂载。
  • 用户入口依赖 DSH 命令行或 DSH Web 控制台。
  • 插件自己不承担所有重活,而是把 ComfyUI 出图、Blender 无头建模和可选 Unity 装配串成一条可复现流水线。

核心流水线

文章给出的主链路可以概括为:

  1. 输入一段文字描述。
  2. ComfyUI 根据文字生成一张概念图,作为视觉参考。
  3. Blender 以无头模式生成引擎无关的场景骨架。
  4. 可选把结果自动装配进 Unity。
  5. 输出 scene.blend、scene.fbx、scene.glb 和 layout.json。

这条链路对应一个典型的 文本到 3D 关卡灰盒生成流水线:文字负责表达目标,ComfyUI 负责概念视觉,Blender 负责实际灰盒几何与场景层级,Unity 适配器负责在 Unity 工程中按契约装配。

主要产物

  • scene.blend:可直接用 Blender 打开的场景文件。
  • scene.fbx:供其他 DCC 或游戏引擎导入的通用 3D 格式之一。
  • scene.glb:供支持 glTF/GLB 的工具链和引擎导入。
  • layout.json:Blender 与下游引擎之间的唯一场景布局契约,记录分组、实例资产、变换、光照和相机信息。

场景骨架的定义

文章中的“场景骨架”指可继续编辑的灰盒场景,而不是可直接游玩的完整关卡。它包含:

  • 场景层级。
  • 光照。
  • 相机。
  • 参数化物件。
  • 可供后续填充真实美术资产的空间结构。

它的定位更接近关卡原型、灰盒布局和资产摆放初稿,而不是最终游戏场景。

明确不会做的事

文章列出了一组清晰的能力边界:

  • 不接管 ComfyUI 生命周期。
  • 不负责安装、启动、停止 ComfyUI。
  • 需要用户自己先让 ComfyUI 跑起来。
  • 不支持 ComfyUI 的 UI 格式工作流。
  • 只支持 POST /prompt 的 API 格式工作流。
  • 不做图生 3D。
  • 不从概念图反推几何。
  • 不生成碰撞体。
  • 不生成刚体物理。
  • 不生成导航。
  • 不生成触发器。
  • 白盒或灰盒不保证可行走。
  • 与在线游戏自动化、内存读写、反作弊绕过无关。

重要细节

四类主链路能力

文章把插件主链路能力分为四类:环境探测、ComfyUI 出图、Blender 无头建模、文字精确布点。

1. 环境探测

check_environment 用来检查三套环境是否存在以及路径是否正确:

  • Blender。
  • ComfyUI。
  • Unity。

这个工具只做探测,不启动软件。文章特别说明,干跑或环境检查阶段如果环境不满足,节点会被标记为 blocked,后续节点会被标记为 skipped,产物只是占位,用于先确认机器和依赖是否齐备。

2. ComfyUI 出图

插件内置 txt2img 工作流,也允许用户提供自己的 API 格式工作流 JSON。输出是一张概念图,作为后续场景骨架生成的参考。

限制是:

  • 只认 API 格式工作流。
  • 不支持 ComfyUI UI 格式工作流。
  • 默认单机使用 127.0.0.1 和 8188 端口。
  • comfyUrl 可以改,但 ComfyUI 需要用户自行启动。

3. Blender 无头建模

Blender 侧以无头模式生成场景骨架。文章提到默认使用 scenic-bpy 的声明式 spec 生成参数化庭院,分为三组:

  • Terrain。
  • Buildings。
  • Props。

默认参数化庭院包含的元素包括:

  • 地形。
  • 柱墙。
  • 拱门。
  • 树。
  • 长椅。
  • 灯柱。

文章还提到 legacy 模式:legacy 模式会生成固定体块加参考图平面,而不是默认的声明式 spec 参数化庭院。

4. 文字精确布点

plan_scene_layout 是用于文字精确布点的工具。它会让模型生成一份带 position 和 size 的布局 plan,然后由 Blender 按坐标和尺寸摆放。

该 plan 不是无条件接受,必须先通过结构校验和物理合理性校验。校验失败时,系统会把失败原因反馈给模型并要求重试,最多 3 次。三次仍然失败时返回 ok: false,不会静默接受非法 plan。

这部分对应 LLM 场景布局规划校验:模型负责提出“要摆什么”和初始坐标尺寸,校验器负责挡住结构不完整、物理关系不合理或构图明显错误的结果。

sceneSource、模板模式与 LLM 模式

文章配图说明了 sceneSource 两种取值与三条可选增强之间的关系:

  • 模板模式使用固定庭院构图。
  • LLM 模式按文字精确布点,并带物理校验与最多 3 次重试。
  • 材质映射、几何模型库、PBR 贴图三项增强默认关闭。
  • 缺依赖时三项增强会自动降级,不阻断主流程。

三个可选增强

文章列出三条可选增强,并强调它们默认全部关闭。缺依赖时自动降级,不阻断主流程。

材质映射

材质映射会给 9 个语义材质 key 注入真实 PBR 贴图。文章没有把它设定为主链路必需项;如果缺贴图或依赖,则回退到纯色或较基础的材质表现。

几何模型库

几何模型库会用 18 种资产库 type 的真实 GLB 模型替换程序化图元,目的是摆脱“积木感”。文章同时说明,模型库不自带资产,需要用户自备 GLB,例如 Kenney、Quaternius 的 CC0 包;缺失时会回退到程序化图元,场景仍能跑通。

PBR 贴图

PBR 贴图能力使用 SuperPBR 给对象生成:

  • albedo。
  • normal。
  • roughness。
  • metallic。

文章提醒,贴图需要额外磁盘空间和推理时间。灰盒输入只会得到灰色 albedo;如果追求真实质感,需要材质映射或贴图生成配合。

layout.json 的设计

文章认为整个插件设计中最关键的一点,是把 layout.json 作为 Blender 与下游引擎之间的唯一契约。它对应 layout.json 场景布局契约。

layout.json 记录的信息包括:

  • 场景分组。
  • 每个实例的资产引用。
  • 每个实例的变换。
  • 光照。
  • 相机。

文章区分了 plan 与 layout.json 的职责:

  • plan 表示“要摆什么”。
  • layout.json 表示“实际摆成什么样”。

这意味着模型规划输出并不是最终契约;Blender 按实际生成和摆放结果写出的 layout.json,才是下游 Unity、Unreal、Godot 或其他引擎装配时应遵循的数据依据。

坐标轴与 breaking change

文章说明坐标系默认是 z-up,layout.json 直接写 Blender 原生坐标,因此可以原样回灌 Blender 复现。如果要 Unity 直接消费,可以把 layoutAxis 配成 y-up。

从 v0.1.0 起,这是一个 breaking change:

  • v0.1.0 起默认 z-up。
  • 早期版本只有 y-up 一种口径。
  • 下游自己解析 layout.json 时必须先读 axis 字段。
  • 没有 axis 字段的历史文件应按 y-up 处理。

安装与环境要求

文章强调 dsh-scene-skeleton-pipeline 是源码插件,需要从本地目录安装进 DSH profile。它没有独立 CLI,也不带桌面客户端。

文中给出的安装入口示例是:

dsh plugin --profile web add /absolute/path/to/dsh-scene-skeleton-pipeline
dsh web

安装后,profile 的 package.json 会增加依赖,dsh.profile.bundles 会自动登记这个包,DSH 按包的 dsh.bundle.patch 自动挂载,不需要手工改 YAML。加载成功时日志里能看到以下项依次注册:

  • service。
  • check_environment。
  • run_scene_pipeline。
  • plan_scene_layout。

文章列出的环境要求包括:

  • Node 不低于 20,因为插件使用 ESM 和 AbortSignal.timeout。
  • DSH 需要支持 bundle 的版本,作者实测版本为 0.2.1-rc.5。
  • ComfyUI 需要用户自己先跑起来,并监听 http://127.0.0.1:8188。
  • Blender 使用 4.x 无头模式。
  • Unity 可选,要求 Unity 2022.3 LTS 以上。
  • 核心链路磁盘约 25 GB。
  • 开启 PBR 贴图再额外增加约 6.4 GB。

核心链路只需要三项配置:

  • comfyUrl。
  • blenderExe,留空时自动探测。
  • outputDir,留空时使用默认位置。

示例流程

文章用“一座带台阶、四角有石柱的日式庭院”说明从文字到可打开场景的完整流程。

第一步:干跑检查

先进行 dry run,不启动任何软件,只做依赖检查和节点编排:

run_scene_pipeline({ prompt: "一座带台阶的日式庭院,四角有石柱", dryRun: true })

如果环境不满足,节点会标记为 blocked,后续节点标记为 skipped,产物为占位。这一步的目的不是生成最终结果,而是确认机器、路径、依赖是否齐全。

第二步:生成精确布点 plan

把想精确布点的内容交给 plan_scene_layout:

plan_scene_layout({ sceneDescription: "东侧有喷泉,四角各一根石柱,北侧一段矮墙,西南一棵树", savePath: "./courtyard-plan.json", width: 24, depth: 20 })

该工具会生成带坐标和尺寸的 plan,并进行物理合理性校验。校验失败时,会逐条列出原因让模型重试;最多重试 3 次,三次不过返回 ok: false。

第三步:真实执行

真实执行时关闭 dry run:

run_scene_pipeline({ prompt: "一座带台阶的日式庭院,四角有石柱", dryRun: false })

文章给出的耗时范围是:

  • ComfyUI 出图约 1 到 1.5 分钟。
  • Blender 无头建模约 2 到 5 秒。
  • 如果开启 Unity 适配器,再运行约 10 到 15 秒。

产物会落在 outputDir 下 jobs 的对应目录中:

  • comfy 目录放概念图。
  • blender 目录放 scene.blend 和 layout.json。
  • 开启贴图时会有 textures。
  • 开启 Unity 时会有 unity。

第四步:打开验收

文章给出的验收方式包括:

  • 在 Blender 里直接打开 scene.blend。
  • 预期能看到 SceneSkeleton_Root 下挂着 Terrain、Buildings、Props 三组,以及方向光和相机。
  • 在 Unity 中打开装配好的场景。
  • 在其他引擎中导入 scene.fbx 或 scene.glb,并按 layout.json 摆位。

应用场景

文章认为该插件最适合需要快速搭建关卡骨架、再往里填真实资产的游戏和工具类项目。

关卡原型快速搭建

使用一段自然语言描述先生成一版可编辑灰盒,比从空白场景手工摆放更快。团队可以先验证空间、构图、尺度和基本动线,再替换真实资产。

多引擎复用布局

同一份 layout.json 可以供 Unity、Unreal、Godot 等引擎消费。不同引擎按各自坐标系口径适配摆位,不需要每换一次引擎就重新手摆。

自动化资产流水线

插件把概念图生成、灰盒建模、下游装配串成可复现流水线。配合 CC0 贴图和模型库后,可以批量生成风格相对统一的场景骨架。

教学与演示

文章提到参数化庭院的 spec 是一个直观案例,适合演示“一段文字如何变成一个带层级的 3D 场景”。

实测与风险提示

文章称,作者在一个真实在用的 Unity 工程上完整跑过一次真实执行,job 状态为 done。该测试中,原有资产 0 个被改写或删除,只新增了插件自己的 11 个文件。文章用这个案例说明插件在接入已有 Unity 工程时不会主动破坏原有资产,但这仍然是文中描述的一次实测结果,不等于所有工程都没有集成风险。

文章也列出多条实操注意事项:

  • 它是灰盒,不是成品;不会复刻概念图中的建筑形体。
  • 产出多为程序化图元或声明式 spec,真实质感需要材质映射或贴图生成。
  • LLM 布点成功率不是 100%。
  • plan_scene_layout 虽有校验和 3 次重试,复杂描述仍可能给出不合理构图。
  • 建议配合 savePath 把 plan 落盘后人工检查再用。
  • 插件不安装、不启动、不停止 ComfyUI、Blender、Unity。
  • 插件不接 MCP 桥接。
  • ComfyUI 需要用户自己先跑起来。
  • 核心链路约需 25 GB 磁盘。
  • 开 PBR 贴图再加约 6.4 GB。
  • 8 GB 显存可以跑但会慢。
  • 贴图建议使用 512 分辨率。
  • textureObjects 建议用 main,不要用 all。
  • 每个对象一次推理;48 对象场景可能需要十几分钟。
  • v0.1.0 起坐标轴默认 z-up,下游解析 layout.json 要先读 axis 字段。
  • Unity 直消费时建议把 layoutAxis 配成 y-up。
  • 贴图、材质映射、几何模型库都不自带资产。
  • 贴图需要自备 CC0 资源,例如 Poly Haven、ambientCG。
  • 模型库需要自备 GLB,例如 Kenney、Quaternius 的 CC0 包。
  • 缺贴图或模型库时会自动回退到纯色或程序化图元,主流程仍能跑通,只是视觉质感下降。

与相关概念的关系

相关条目