dsh-blender-plugin

dsh plugin --profile web add dsh-blender-plugin

DSH × Blender

[简体中文](docs/zh/README.md)

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](#features)
• [Quick start](#quick-start)
• [Tools](#tools)
• [Documentation](#documentation)
• [Troubleshooting](#troubleshooting)
• [Development](#development)
• [Support](#support)
• [License](#license)

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.zip. 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 24.9 or newer is needed only for source builds; installing from npm uses the runtime bundled with DSH. Node.js 24.9 is the minimum supported version; CI runs on Node 24.
• Blender 4.2 LTS is the tested version. Blender 4.x may work; Blender 5.x is not yet validated. 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 when rebuilding the host side; otherwise the build links against this repository's installed dependencies.

Option A: install from npm

This is the supported installation path. It does not require git clone, npm ci, or npm run build.

1. Install the bundled addon first. Download dsh_blender_bridge.zip from the latest GitHub Release, then in Blender open Edit > Preferences > Add-ons > Install, select the zip, enable DSH Blender Bridge, open the N panel in the 3D view, and click Connect.

2. Install the DSH plugin from npm. Choose the path for your DSH host:

• DSH Web or DSH TUI: install into the profile you actually run:

dsh plugin --profile <profile> add dsh-blender-plugin@3.0.6

Then restart DSH in step 3.

• DSH Desktop: open the Plugins page and install the bundle dsh-blender-plugin@3.0.6. DSH Desktop applies the bundle from the Plugins page and does not need a DSH restart.

3. Restart DSH (DSH Web and DSH TUI only). If you installed from the DSH Desktop Plugins page, skip this step.

4. Verify the installation. The only acceptance criterion for the GUI route is doctor returning kind equal to ok:

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

GUI route: curl -sS http://127.0.0.1:9877/health and /doctor; doctor.kind must be ok.

Headless-only route (no addon): blender_rt_worker(op="start") followed by op="see" must return a frame.

The addon remains the only supported Blender-side agent bridge. Disable a

…(truncated)