前言¶

DeepSeek Harness（DSH）把大模型能力嵌入本地工作流，但三维建模、渲染、视频生成这些环节仍然分散在多个工具和平台中。开发者需要手动编排命令、维护依赖、切换不同渲染管线，一旦某个环节出错就会中断整个流程。本插件为 DSH 提供一条本地三维工作流入口，把 Blenderwright、Three.js、COLMAP、ComfyUI 等现成能力串接起来，让 DeepSeek 模型在本地直接调用这些工具。

这是什么¶

dsh-local-3d-studio 是适配 DSH 的本地三维工作室插件，由 RoderickWilliams 维护。它不新建几何引擎或渲染器，而是复用已有的 Blenderwright、Three.js、COLMAP、ComfyUI、TripoSR、Hunyuan3D 2.1 等项目，通过 DSH 官方 MCP 客户端编排它们。插件负责流程编排、工具探测、缺项处理和输出整理，模型与用户之间只需要自然语言交互。

核心功能¶

工作流编排¶

插件提供从需求到交付的完整流程，按顺序调用：

• studio_compatibility：检测 DSH 宿主、DeepSeek 模型版本与本地工具版本
• studio_create：返回流程能力报告
• studio_workflow：列出每个阶段的缺项与准备动作
• studio_discover / studio_setup：发现与准备本地项目与依赖
• studio_guides / studio_catalog：提供制作指南与能力目录
• studio_plan：生成方案，支持多修订版
• studio_run(preview)：预览模式生成样例
• studio_samples：展示样例工程与样图
• studio_review：确认后进入正式制作
• studio_run(build)：正式渲染与导出

特别需求走 studio_interview / studio_confirm_requirements，修改后创建新修订版。

本地优先与缺项处理¶

优先级为：preferredProjects 目录 → 适配声明 → 已识别本地项目 → 插件托管副本。目录扫描上限为 600 个目录、两层。没有项目时，studio_setup 会展示来源并克隆官方仓库，在 dataRoot/_dependencies 建立隔离 Python 环境。权重下载会说明许可和磁盘影响，运行时开启 Hugging Face 离线模式。

自定义项目不会因被扫描到就执行代码，入口与声明先供 DeepSeek 选择，用户明确选择后才纳入方案。

Three.js 程序化建模与查看¶

没有 Blender 时，插件提供 Three.js 通道，支持以下动作：

• setup：安装 three、@gltf-transform/core、extensions 和 functions 到 <dataRoot>/_dependencies/nodejs
• demo：生成示例 GLB（立方体/球体/地面）
• generate：按 spec.objects（box / sphere / cylinder / cone / torus / plane 组合）程序化生成 GLB，自动配地面与尺寸
• inspect：报告节点、网格图元、材质、贴图数量、动画与包围盒
• edit：按 ops 修改后导出新 GLB，并生成 .viewer.html
• viewer：生成单文件 HTML 预览页，three.js 运行时与模型均以 base64 内嵌，断网可看
• render：用无头 Chrome 按 views（front/back/left/right/top/iso）截图成 PNG

spec 示例：

{ "name": "Bookshelf", "ground": true,
  "objects": [
    { "type": "box", "size": [1.2, 0.04, 0.36], "position": [0, 1.78, 0], "color": "#8a5a33" },
    { "type": "cylinder", "radius": 0.2, "height": 1.4, "position": [0, 0.7, 0], "color": "#4f7fd9" }
  ] }

ops 支持 transform（平移/旋转/缩放）、material（颜色、金属度、粗糙度、透明度、自发光、双面）、rename、remove、duplicate、scaleTo、center。材质既可按名称也可按序号指定。scaleTo 按最长边缩放到指定尺寸，而非按高度。

viewer 生成的 HTML 内嵌约 760KB 的 three.js 运行时（含 OrbitControls、GLTFLoader），模型以 base64 内嵌，断网可打开。

render 默认输出到 <预览页同名>-views/，每个视角一张 1280×900 PNG。它使用无头 Chrome（优先 channel=chrome，可用 STUDIO_CHROME_CHANNEL=msedge 切换）加载本地预览页，不联网、不依赖 Blender。

工具探测与管线选择¶

studio_probe 每次调用都实测本机，不缓存：

• 探测 Blender、COLMAP、FFmpeg、FFprobe、Python 的真实路径与版本
• 访问 comfyuiUrl（默认 http://127.0.0.1:8188）的 /system_stats，并扫描常见 ComfyUI 目录里的 main.py
• 给出 pipeline：Blender 可用时建模走 blenderwright，否则走 three-procedural；重建需要 COLMAP；AI3D 需要 ComfyUI 可达

插件系统提示里写死了这条规则：Blender 可用就走 Blenderwright；不可用就用 studio_three action=generate 程序化建模、action=render 出多视角图，并在交付时说明实际用了哪条路线。

输出与交付¶

输出在 dataRoot/p_<项目编号>/revision-N/ 下，包含方案、日志、预览、工程、模型和用户要求的视频。旧版本保留。素材按原样复制，不移动用户原文件。GLB 更适合带贴图导入；依赖外部贴图的 OBJ / glTF 请通过本地项目适配器完整准备。

请求动画时，studio_create(outputs:["model","animation"]) 的后续方案必须包含视频和多帧；请求正式效果图时添加 render-images，方案必须列出 artifacts.renders。样例必须保留真实 .blend 工程，最终图片、模型与视频必须分别生成；概念图、拍点 JSON 或低分辨率预览不能替代正式交付。

配置项¶

在现有 profile 的补丁中覆盖 local-3d-studio 的 config，只复制需要的字段，避免覆盖原有配置：

• dataRoot：项目、修订历史、托管依赖的专用目录
• projectRoots / preferredProjects：本地项目发现范围和优先目录
• inputRoots：允许读取的参考素材目录，默认包含工作目录、桌面和 DSH 附件目录
• blender / ffmpeg / ffprobe / colmap：自动发现失败时指定 .exe 或可执行文件
• aiPython：已有模型环境的 Python
• blenderwrightPython：已有 Blenderwright 环境
• mediaPython：用户已有、包含 librosa 的独立环境；也可用 studio_setup(media) 准备
• modelRoute / visionMode：宿主没有公开当前模型元数据时的可选补充；不填写 API Key
• triposrWeights / hunyuanWeights：已有本地权重目录
• comfyuiUrl / comfyuiWorkflow：现有本地 ComfyUI 服务和 API 格式工作流，只允许回环地址
• skillPaths：已有 grilling、ffmpeg 等 skill 的 SKILL.md 路径，按需读取，不复制或重新安装其整个项目
• taskTimeoutMinutes：一次任务的总时限，默认 180 分钟
• maxFrames：默认 3600
• hunyuanPaint：默认 false，PBR 还需要上游文档所列扩展及本地辅助权重，不要在硬件未满足时开启

安装与启用¶

基础环境：

• DSH 0.2.1 系列
• Node 22+
• Python 3.10+
• Blender 4.2+ 桌面版（Blenderwright 需要）
• Git（缺少项目自动克隆需要）
• FFmpeg / FFprobe（视频和音乐步骤需要）

在你现有的 DSH profile 上安装，不必更换 DeepSeek 模型配置。将 YOUR_PROFILE 替换为正在使用的 profile 名：

dsh plugin --profile YOUR_PROFILE add E:/DeepSeek/deepseek-3d-studio

也可以安装交付的 .tgz：

dsh plugin --profile YOUR_PROFILE add E:/DeepSeek/deepseek-3d-studio/dist/dsh-local-3d-studio-0.1.0.tgz

随后用原来的命令重新打开该 profile。不要为安装本插件重建或覆盖现有 profile。默认包不带 postinstall 下载脚本，不会在安装时悄悄下载大模型。

典型用法¶

首次对话可以这样说：

使用本地三维工作室。先识别我的硬件和已有项目，缺少必要能力再准备。帮我做一个科幻维修机器人，先给基础模型样例，再问我是否有特别需求。

若 Blender 尚未安装，插件会明确报告需要配置的路径。Blender 可使用其官方安装版或便携版；本插件不自行执行系统级安装。Blenderwright 源码和 Python 依赖可以通过 studio_setup 获取。之后每次制作使用专用的空白 Blender 进程，动态加载已有 addon，不更改用户的 Blender 偏好或占用其已有工程。

适用场景与注意¶

适合已经搭建好 DSH 环境、本地已有 Blender、Three.js、ComfyUI 等工具链的用户。插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

短结尾¶

本插件为 DSH 提供了一条本地三维工作流入口，复用现成建模、渲染与生成工具，让 DeepSeek 模型在本地直接编排三维任务。更多细节与源码见：https://github.com/RoderickWilliams/dsh-local-3d-studio