Blender 渲染器 s1lverex/dsh-plugin-blender

dsh-plugin-blender

面向 DeepSeek Harness 的 Blender：智能体通过 Blender 以无头方式渲染 3D 模型，工作台在右侧边栏获得一个 3D 查看器 面板，该面板使用 three.js 加载导出的模型并显示渲染出的图像。

宿主部分：三个模型工具加两条 HTTP 路由。客户端部分：一个侧边栏标签页。无运行时依赖——宿主使用 Node 内置模块，面板是一个预构建的 bundle。

它新增了什么

三个模型工具。

| 工具 | 用途 |
| blender_status | 正在使用的可执行文件、其版本、工作目录，以及面板列出多少个模型/渲染。 |
| blender_render | 将 3D 文件渲染为 PNG，并将图像返回给模型。.blend 文件保留自己的相机和灯光；导入的文件会自动取景。 |
| blender_export_glb | 将任何受支持的文件转换为 .glb 并发布到查看器面板。 |

一个侧边栏标签页。 右侧边栏中的 blender-viewer-tab：一个带轨道/缩放控件的 three.js 画布、一个模型选择器，以及一条 Blender 渲染结果条带（点击一个即可全面板查看）。

两条 HTTP 路由。 GET /blender/models 列出面板可以显示的内容；GET /blender/file/ 提供已扫描的文件。请求只能指定 id，永远不能指定路径，因此这些路由无法读取已扫描目录之外的内容。它们直接注册在 Web 服务器上，因此不携带会话令牌：在默认的环回绑定下，只有本机可以访问它们，但绑定到 0.0.0.0 的服务器会将该网络暴露给所列文件——在这种部署中设置 enableViewer: false。

一个 Cordis 服务。 ctx.blender 暴露 detect()、version()、listModels()、render(request, signal) 和 convertToGlb(request, signal)。

架构

┌─ Host (Node) ──────────────────────────────────────────────┐
│ lib/index.js Cordis plugin: name/inject/apply, routes │
│ lib/tools.js the three defineTool definitions │
│ lib/blender.js detection, subprocess runner, registry │
│ lib/scripts/render.py bpy: import, frame, render │
│ lib/scripts/convert_glb.py bpy: import, export GLB │
└──────────────────────────┬─────────────────────────────────┘
│ /blender/models, /blender/file/
┌──────────────────────────┴─────────────────────────────────┐
│ src/client.jsx tab type + slot registrations │
│ lib/client.js built bundle (three.js inside) │
└─ Browser (web shell) ──────────────────────────────────────┘

Blender 以 blender -b --factory-startup -noaudio --python -- 的方式驱动；每个步骤打印一行 DSH_BLENDER_RESULT {json}，宿主会解析它。渲染默认使用 CPU 上的 Cycles，这是可靠的无头引擎；EEVEE 和 Workbench 可用，但需要 GPU。

Cycles 在 CPU 上渲染，因此无人值守的 blender_render 可以在无头主机上运行。一个简单模型的 960x720x32 采样渲染耗时远低于一秒。
该面板直接加载 .glb、.gltf、.obj、.stl 和 .ply。其他所有格式（.blend、.fbx、.dae、.usd、.abc）必须先经过 blender_export_glb 处理，面板会标记这些条目。

要求

- DeepSeek Harness 0.1.5 或兼容的 0.1.x，且带有 web 配置文件
- Node.js 20 或更新版本
- Blender 3.6+（推荐 4.x）——无头模式即可，无需显示器

Blender 在加载时是可选的：没有它，工具仍会注册，但会以可操作的错误信息失败，面板仍会列出模型目录中已有的任何 .glb 文件。

安装

宿主从配置文件依赖闭包中解析 @deepseek-ai/dsh-tools，因此该包必须作为真实目录存在于其中；符号链接会将其 realpath 移出闭包，从而破坏该导入。

从 GitHub 安装（一条命令，适用于任何机器）

package.json 声明了带有 cordis.patch.yml 的 dsh.bundle，因此该仓库会作为配置文件包安装，插件行会自动组合。lib/client.js 已预先构建并提交，因此安装时不会编译任何内容。

dsh plugin --profile web add github:/dsh-plugin-blender

然后重启 dsh web（包安装会改变目录树，而实时补丁监视器不会覆盖这一点）。该机器上必须安装 Blender；其他所有内容都在包中。

从本地检出安装

SRC=/path/to/dsh-plugin-blender
cd "$SRC" && npm install && npm run build # produces lib/client.js
npm run deploy # copies lib/ into $DSH_HOME/profiles/node_modules/dsh-plugin-blender

然后向 $DSH_HOME/profiles/web/cordis.patch.yml 添加一行：

- insert:
- id: blender
name: 'dsh-plugin-blender'

随附的 web 配置文件使用 patchReload: live，因此无需重启即可识别该行。之后编辑插件的 lib/ 不会被监视——更改宿主代码后，请重新运行 npm run deploy 并重启 dsh web。

一旦会话存在，该标签页会自动打开。也可以从右侧边栏的 + 页面（“3D Viewer”）手动打开。

发布（维护者）

GITHUB_TOKEN=... npm run publish:github # creates the repo, sets the dsh-plugin topic, pushes
GITHUB_TOKEN=... npm run publish:market # forks the registry and opens the entry PR

该令牌是经典 PAT，具有 repo（或 public_repo）和 read:user 权限。市场为每个插件列出一个 YAML 条目（data/plugins/__.yml），并要求仓库声明 dsh.bundle 且至少存在一天，因此在首次推送后的第二天运行市场步骤。

Blender 检测

按以下顺序：blenderPath 配置、$BLENDER_PATH、PATH 上的 blender，然后是常见安装位置（/usr/bin、/snap/bin、/opt、~/.local/share/blender*、~/.local/bin、macOS 的 Blender.app、Windows 的 Program Files）。blender_status 会报告最终使用了哪一个。

配置参考

| 键 | 类型 | 默认值 | 含义 |
| blenderPath | string | '' | 显式的 Blender 可执行文件路径。为空表示自动检测。 |
| workDir | string | $DSH_HOME/blender | 存放 models/ 和 renders/。加载时创建。 |
| modelDirs | string[] | [] | 在面板中列出并提供服务的额外目录（扫描深度 4 层，最多 400 个文件）。 |
| timeoutMs | number | 300000 | 每次渲染的预算；超时后 Blender 进程会被终止。 |
| defaultWidth | number | 960 | 默认渲染宽度。 |
| defaultHeight | number | 720 | 默认渲染高度。 |
| defaultSamples | number | 32 | 默认 Cycles 采样数。 |
| defaultEngine | string | cycles | cycles、eevee 或 workbench。 |
| enableViewer | boolean | true | 注册查看器路由。 |

每个键都是可选的；一行只需要 id 和 name。

工具

blender_render

| 参数 | 含义 |
| file | 要渲染的模型或 .blend 文件。 |
| output | 输出路径或文件名；默认为 workDir/renders 中带时间戳的 PNG。 |
| width、height、samples、engine | 覆盖本次渲染的默认值。 |
| frame | 动画 .blend 的动画帧。 |
| camera | .blend 中用于渲染的相机名称。 |
| transparent | 使用 alpha 背景渲染。 |

当 .blend 自带相机时，会通过其自身的相机进行渲染；否则（以及对于所有导入的格式），相机会被放置以框住几何体，并且仅当场景没有灯光时才会添加主光 + 补光对。PNG 会被保存，作为附件发布以便多模态模型实际接收到它，并在面板中列出。

blender_export_glb

file 加上可选的 name；写入 workDir/models/.glb，移除相机和灯光，以 Y-up 导出，并返回几何体统计信息。

验证

npm run build # lib/client.js
npm run verify # structural checks on both halves
npm run client # loads the bundle like the shell does, activates it, renders the panel
npm run smoke # real headless Blender: convert, render, .blend render, HTTP routes
npm run viewer # Chromium screenshot of the panel showing a Blender-exported model

npm run smoke 会将一个立方体 .obj 和一个 .blend 写入临时目录，转换
并渲染两者，断言 GLB 魔数和 PNG 签名，然后在真实套接字上提供捕获的路由，并检查列表、内容类型、未知 id（404）和路径遍历尝试（404）。
npm run client 通过桩模块表评估 lib/client.js，针对桩 shell
上下文运行 apply()，并对注册的标签页进行服务端渲染。npm run viewer 将真实的面板组件打包为独立页面，在 Chromium 中加载它并截图 three.js 画布（写入 test/viewer-shot.png）。当 Blender 或 Playwright 缺失时，依赖 Blender 的脚本会以退出码 0 退出并显示跳过通知。

故障排除

"Blender was not found" — 安装 Blender，将其放到 PATH 上，或设置行配置中的 blenderPath；blender_status 会回显尝试过的路径。

面板显示“还没有模型” —— 尚未导出任何内容。请让 agent 运行 blender_export_glb，或将一个 .glb 放入 $DSH_HOME/blender/models。

该标签页没有出现 —— 请确认 lib/client.js 存在且已构建，该行的 name 与包名完全一致，并且 closure 中部署的副本就是你编辑的那个（npm run deploy）。对宿主 lib/ 的更改需要重启 dsh web。

模型渲染为黑色或空白 —— 对没有几何体的文件进行 Cycles 渲染会失败，并提示“the scene contains no mesh geometry to render”。对于导入的文件，自动相机会根据网格边界计算，因此仅包含相机、灯光或空对象的文件无法被取景。

渲染很慢 —— 降低 samples（8–16 就足以判断形状），降低分辨率，或在有 GPU 时使用 engine: workbench。

许可证

MIT