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 装配串成一条可复现流水线。
核心流水线
文章给出的主链路可以概括为:
- 输入一段文字描述。
- ComfyUI 根据文字生成一张概念图,作为视觉参考。
- Blender 以无头模式生成引擎无关的场景骨架。
- 可选把结果自动装配进 Unity。
- 输出
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 包。
- 缺贴图或模型库时会自动回退到纯色或程序化图元,主流程仍能跑通,只是视觉质感下降。
与相关概念的关系
- dsh-scene-skeleton-pipeline:本文来源文章的主角,是 DSH 生态里的编排插件。
- DSH(DeepSeek Harness):插件的承载环境,负责 profile、命令行入口和 Web 控制台入口。
- 文本到 3D 关卡灰盒生成流水线:本文描述的整体生成范式,即从文字到概念图、再到 Blender 灰盒、再到可选引擎装配。
- layout.json 场景布局契约:文章重点强调的 Blender 与下游引擎之间的唯一契约。
- LLM 场景布局规划校验:
plan_scene_layout生成带 position 和 size 的 plan,并在失败时反馈原因给模型最多重试 3 次。