[opensourcedex]

dsh-blender-plugin is a free, open source design & prototyping project written in Python and released under BSD-3-Clause. It has 1,540 GitHub stars, 60 forks and 3 open issues, and was last pushed 24 hours ago. On this registry it ranks #85 of 111 tracked projects in Design & Prototyping, with 5 head-to-head comparisons available. It gained 11 stars over the last 2 tracked days.

What is dsh-blender-plugin?

dsh-blender-plugin is a Blender addon paired with a Node.js backend that connects DeepSeek Harness (DSH) to a live Blender session, so an AI agent can build, inspect, validate, and export 3D scenes — built for 3D artists and technical teams already running DSH who want agent-driven modeling inside the Blender GUI they are looking at.

What it is

dsh-blender-plugin is a bridge between DeepSeek Harness and Blender, distributed as a Python addon (addon/dsh_blender_bridge.py) plus a Node.js backend. It lives in the Blender addon ecosystem and speaks to Blender through bpy and a persistent Python kernel, exposing 15 model tools that let an agent look at the scene, change it, and verify the result one step at a time. The workflow is deliberately GUI-first: the agent works against the Blender session the user is watching, taking viewport or custom-angle frames as visual feedback.

The concrete problem it solves is the gap between an AI agent and a running DSH session on one side, and a real, inspectable Blender scene on the other. Rather than replacing Blender with a scripting sandbox, it turns the open GUI session into the agent's workspace, and it replaces the ad-hoc socket bridges that otherwise occupy Blender's connection port. When no GUI is available, a persistent headless worker provides the same interactive loop, including Workbench frames, so the agent is never blind.

Key capabilities

  • GUI-first interactive modeling against the live session: scene inspection, Python execution in a persistent kernel, and viewport or custom-angle frame capture for step-by-step iteration.
  • Headless fallback mode that starts a persistent worker and returns Workbench frames when Blender has no GUI, plus one-shot headless scripts, long background jobs, parameter searches, and batch validation that do not occupy the GUI.
  • Reference-image measurement of silhouettes, holes, symmetry, readable features, and scale before modeling, returning pixel units instead of inventing millimeters when no scale is known.
  • Parametric surface construction from sections (loft), a profile swept along a rail, or a four-sided patch, with continuity, curvature, self-intersection, and thickness checks, GLB export, and a deterministic spec_hash so the same spec yields the same vertices.
  • Assembly audit and repair: validating an assembly manifest, classifying clashes, hidden overlaps, contacts, gaps, floating parts, and contained parts, applying safe repairs, gating the result, and exporting GLB, FBX, or OBJ with a manifest and merge ledger.
  • Blockout and video-reference packs: low-poly blockouts from declarative parts, orthographic and perspective reference renders, and a turntable MP4 for video models such as Seedance.
  • Visual acceptance gates that compare renders against references from the same camera, report defects with crops and measurements, run defect-injection evaluation, and block delivery when the gate is not pass.
  • Native selection and dsh-TUI integration: selected objects, collections, or sub-elements are sent into the current DSH draft, appear as a context chip on the next message, and are addressable through @ mentions, a footer channel state, and /blender status|doctor|jobs.

Who uses it and how

  • Artists and modelers who keep Blender 4.x or 5.x open and let the agent inspect, modify, and verify the scene they are looking at, one step at a time.
  • Pipeline and asset teams that need reproducible geometry: the same parametric spec produces the same spec_hash and vertices instead of hand-sculpted meshes.
  • Teams shipping assets under acceptance gates, where renders are compared against references from the same camera and delivery is blocked until the gate passes, with exports accompanied by a manifest and merge ledger.
  • Environments without a GUI, where a persistent headless worker, background jobs, and batch validation run the same interactive loop without tying up a visible session.
  • Terminal-centric users working in dsh-TUI, who attach a Blender selection as a context chip, read channel state from the footer, mention scene objects, materials, and collections with @, and check the channel with /blender without going through the model.

Getting started

Install and enable the bundled addon addon/dsh_blender_bridge.py in Blender before anything else, then run the backend with DSH installed and Node.js 20 or newer, against Blender 4.x or 5.x. Headless mode needs only the Blender executable, while GUI mode requires the addon to be installed, enabled, and connected.

How it compares

It is not an MCP-style bridge: MCP for Blender and blender_mcp serve Blender over their own socket and compete for 127.0.0.1:9876, so the bundled addon must be the only agent bridge installed. Unrelated addons for modeling, materials, rendering, or asset libraries are neither checked nor blocked, so the plugin coexists with a normal Blender addon stack.

When to use it — and when not

A self-hoster must run DSH, a Node.js 20 or newer backend, and a supported Blender version, and must keep the bundled addon as the sole agent bridge on port 127.0.0.1:9876; the dsh-TUI features each need the matching seam and stay off when that seam is missing. Teams not already running DeepSeek Harness, or those committed to an MCP-based Blender bridge, should not pick it, since the addon is the only supported bridge and headless mode is explicitly a fallback rather than the default path.

project readme (upstream, from github) — read inline

DSH × Blender

简体中文

DSH × Blender connects DeepSeek Harness to Blender so an agent can build, inspect, validate, and export 3D scenes in a real Blender session. The normal workflow is GUI-first: start Blender, connect the addon, and let the agent look, change, and verify. When no GUI is available, a persistent headless session provides the same interactive loop, including frames.

Contents

Features

  • GUI-first interactive modeling. The agent works against the Blender session you are looking at. It can inspect the scene, run Python in a persistent kernel, take a viewport or custom-angle frame, and iterate one step at a time.
  • Headless fallback with visual feedback. If Blender has no GUI, start a persistent worker and the agent can still execute code and get Workbench frames. This is a fallback path, not the default; it exists so the agent is never blind.
  • Reference-image measurement. Measure silhouettes, holes, symmetry, readable features, and scale from a reference image before modeling. If no scale is known, the tools return pixel units instead of inventing millimeters.
  • Parametric surfaces. Build reproducible surface meshes from sections (loft), a profile swept along a rail, or a four-sided patch; run continuity, curvature, self-intersection, and thickness checks; then export GLB. The same spec yields the same spec_hash and vertices instead of hand-sculpted geometry.
  • Assembly audit and repair. Validate an assembly manifest, classify clashes, hidden overlaps, contacts, gaps, floating parts, and contained parts, apply safe repairs, gate the result, and export GLB, FBX, or OBJ with a manifest and merge ledger.
  • Blockout and video-reference packs. Build low-poly blockouts from declarative parts, render orthographic and perspective reference views, and produce a turntable MP4 for video models such as Seedance.
  • Visual acceptance and delivery gates. Compare renders against references from the same camera, report defects with crops and measurements, run defect-injection evaluation, and block delivery when the gate is not pass.
  • Automation and long jobs. Run one-shot headless scripts, long background jobs, parameter searches, and batch validation without occupying the GUI.
  • Native selection. Select objects or collections in Blender and send them into the current DSH draft.
  • Works in dsh-TUI too. In dsh-TUI, a Blender selection is attached to your next message as a context chip; the footer shows the Blender channel state (connected / AI paused / rendering / jobs); @ mentions scene objects, materials, and collections; and /blender status|doctor|jobs checks the channel without going through the model. Each part needs the matching dsh-TUI seam and stays off when the seam is missing.

Quick start

Before anything else: install the bundled addon first. Use the addon shipped in this repository: addon/dsh_blender_bridge.py. It must be your only Blender-side agent bridge: do not install or run MCP for Blender, blender_mcp, or any other addon that serves Blender over its own socket, since they compete for 127.0.0.1:9876. Unrelated addons (modeling, materials, rendering, asset libraries) are fine and are neither checked nor blocked. Install and enable this addon in Blender before the other steps. If the installation below does not work, first check that this exact addon is installed, enabled, and connected.

Requirements

  • DSH (DeepSeek Harness) installed and working.
  • Node.js 20 or newer for the backend.
  • Blender 4.x or 5.x. GUI mode requires the bundled addon (install it first); headless mode only needs the Blender executable.
  • Addon compatibility: the bundled addon is the only required addon and the only supported agent bridge. Other addons do not conflict; an old MCP for Blender / blender_mcp does (same 127.0.0.1:9876 port) — disable it, no need to uninstall.
  • Optional: a DSH source checkout if you want to rebuild the plugin.

Option A: ask an AI agent

Copy this prompt into an agent that can run commands:

First install and enable the bundled addon addon/dsh_blender_bridge.py
from this repository. If a bridge addon is already enabled
(MCP for Blender / blender_mcp, or anything else serving Blender on
port 9876), disable it; do not uninstall the user's other addons and
do not ask them to.
Then install the DSH × Blender plugin from
https://github.com/sixtysevenlf/dsh-blender-plugin
for my DSH profile. Read docs/AI-安装提示词.md first, follow it exactly,
and finish with the acceptance check: doctor must return kind=ok for the
GUI route, or worker start + see must return a frame for the headless-only route.
Do not skip the check and do not claim success without it.

Fetch the full install prompt locally:

curl -fsSL https://raw.githubusercontent.com/sixtysevenlf/dsh-blender-plugin/main/docs/AI-安装提示词.md -o AI-安装提示词.md

Install the standalone modeling skill (only needed for hosts that do not load the plugin; DSH gets it bundled):

curl -fsSL https://raw.githubusercontent.com/sixtysevenlf/dsh-blender-plugin/main/skills/blender-modeling/install.sh | bash

Option B: manual setup

  1. Install the bundled addon first.

    Download addon/dsh_blender_bridge.py from the addon/ folder of this repository. In Blender, open Edit > Preferences > Add-ons > Install, select that file, enable DSH Blender Bridge, open the N panel in the 3D view, and click Connect. The addon listens on 127.0.0.1:9876.

    Keep this addon as your only agent bridge. If MCP for Blender / blender_mcp (or another addon that opens its own server on 9876) is enabled, turn it off — uninstalling is not required. Your other addons can stay. If the rest of the installation does not work, check this step first.

  2. Clone the repository and, if needed, build it. The repository commits the built lib directory, so a normal clone is ready to use.

     git clone https://github.com/sixtysevenlf/dsh-blender-plugin.git
 cd dsh-blender-plugin
 # Optional: only after changing src/
 DSH_CHECKOUT=/path/to/dsh-harness bash scripts/build.sh

  3. Add the package to your DSH profile as a bundle. Link the checkout into the profile, then add the dependency and bundle entry to the profile package.json.

     ln -s /absolute/path/to/dsh-blender-plugin /node_modules/@dsh-external/dsh-blender-plugin

    Profile package.json:

     {
   "dependencies": {
     "@dsh-external/dsh-blender-plugin": "link:/absolute/path/to/dsh-blender-plugin"
   },
   "dsh": {
     "profile": {
       "bundles": ["@dsh-external/dsh-blender-plugin"]
     }
   }
 }

    Validate the profile and restart DSH:

     dsh --profile  --dump-config

  4. Verify the installation.

    GUI route:

     curl -sS http://127.0.0.1:9877/health
 curl -sS http://127.0.0.1:9877/doctor

    The only acceptance criterion for the GUI route is doctor returning kind equal to ok. If it does not, the plugin is not installed correctly.

    After DSH restarts, you can also use blender_viewport with op equal to launch. It starts Blender, enables the addon, and connects automatically.

    Headless-only route (no addon):

     blender_rt_worker(op="start", name="smoke")
 blender_rt_worker(op="see", name="smoke")

    A returned frame means the headless fallback is working. The doctor bpy round-trip is expected to be unreachable in this mode.

Tools

The plugin exposes 15 tools. All planning, audit, assembly, export, and evaluation operations live under blender_rt_plan, so the tool list stays small.

Interaction and control

Tool What it gives you
blender_rt_see A frame of the current GUI viewport or a custom camera angle.
blender_rt_do Runs Python in Blender with a persistent kernel; can return a frame with the result.
blender_rt_watch Samples a time window or frame range and reports whether the image changed.
blender_rt_worker A persistent headless session for interactive work when no GUI is available.

Planning and operations

Tool What it gives you
blender_rt_plan The capability catalog and the execution surface for modeling, audit, assembly, delivery, and evaluation operations. Start here when you are unsure which operation to use.
blender_viewport Channel health, doctor, launch, and write-lease operations for coordinating multiple sessions.

Automation and jobs

Tool What it gives you
blender_rt_headless Runs a standalone Blender background process for batch work, validation, or rendering.
blender_rt_job Starts long work in the background and collects the result by job id; a timeout does not lose the result.
blender_rt_loop Runs a parameter search loop inside Blender and returns the best candidates.

Scene utilities

Tool What it gives you
blender_rt_txn File-level snapshots and object-level marks for rollback.
blender_rt_preset Saves, lists, applies, and exports reusable parameter presets.
blender_rt_perf Diagnoses and applies render performance settings.
blender_rt_opt Finds safe object merges to reduce scene overhead.

Addon access

Tool What it gives you
blender_rt_cmd Calls any addon command directly.
blender_rt_commands Lists available addon commands and integration states.

Documentation

  • Surface algorithm: docs/曲面算法.md
  • Step-by-step guide: docs/操作教程.md
  • Configuration: docs/配置参考.md
  • AI install prompt: docs/AI-安装提示词.md
  • Deployment SOP: docs/部署SOP.md
  • Third-party checklist: docs/给第三方的安装清单.md
  • Modeling skill: skills/blender-modeling/
  • Release notes: GitHub Releases and CHANGELOG.md

Troubleshooting

Symptom What to do
doctor does not return kind equal to ok Check that Blender is running and the addon is connected. For the GUI route this is the only valid acceptance check.
No GUI is available Use the persistent worker fallback: start a worker, then run code and request a frame.
Another session is writing to the same scene Take the write lease with blender_viewport, or use separate headless workers for parallel work.
An old MCP for Blender / blender_mcp addon is still enabled Disable it (uninstalling is not required) and use the bundled DSH Blender Bridge addon; both compete for 127.0.0.1:9876.
Images are generated but not attached Update to the latest build; the Windows path fix is included. If it persists, open the returned path directly.
Followed the steps and it still does not work Check the bundled addon first: only addon/dsh_blender_bridge.py is supported, and it must be enabled and connected.

Development

  • Run the offline test suite: npm test
  • Rebuild after changing src: DSH_CHECKOUT=/path/to/dsh-harness bash scripts/build.sh
  • Bundled skill source: skills/blender-modeling/

Support

If this project is useful to you, you can support its development on Afdian (爱发电):

License

The plugin is BSD-3-Clause. The bundled modeling skill is MIT; see skills/blender-modeling/LICENSE and NOTICE.md. Blender is a trademark of the Blender Foundation.

Frequently asked questions

Is dsh-blender-plugin free to use?

dsh-blender-plugin is open source under the BSD-3-Clause licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does dsh-blender-plugin do?

DSH × Blender 直连实时插件 v2.6.1：15 个模型工具让 AI 驱动 GUI Blender；支持 dsh-TUI（选中 chip / 页脚状态 / @ 提及 / /blender），活动状态置顶并可一键暂停 AI，原生选中/集合/子元素直送 DSH，随包建模 skill，支持 WSL / Windo

What is dsh-blender-plugin written in?

dsh-blender-plugin is primarily written in Python. Its source is publicly available at https://github.com/sixtysevenlf/dsh-blender-plugin, and it has 1,540 GitHub stars.