npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

dsh-blender-remote-plugin

v3.1.1

Published

DSH × Blender remote bridge (v3.1.1, GUI-first with a headless fallback): 15 model tools that let an AI agent drive a live Blender session on the same machine or in a Docker container on another host. Covers viewport and custom-angle frames, a persistent

Readme

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.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 [email protected]

      Then restart DSH in step 3.

    • DSH Desktop: open the Plugins page and install the bundle [email protected]. 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 any other bridge addon that serves port 9876; ordinary modeling, material, rendering, and asset addons are unaffected.

Option B: ask an AI agent

Copy this prompt into an agent that can run commands:

First install and enable the bundled addon dsh_blender_bridge.zip
from the latest GitHub Release. 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 npm for my DSH profile:
dsh plugin --profile <profile> add [email protected]
Read docs/ai-install-prompt.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/TheRealChickenlegs/dsh-blender-plugin/main/docs/ai-install-prompt.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/TheRealChickenlegs/dsh-blender-plugin/main/skills/blender-modeling/install.sh | bash

Option C: build from source (developers)

  1. Install the bundled addon first.

    Download addon/dsh_blender_bridge.zip from the addon/ folder of this repository. In Blender, open Edit > Preferences > Add-ons > Install, select that zip, enable DSH Blender Bridge, open the N panel in the 3D view, and click Connect. The addon listens on 127.0.0.1:9876. If you previously installed the single-file dsh_blender_bridge.py, disable and remove it first: v3.0 installs only the package zip.

    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. Developer path: clone the repository and build it. lib/ is a build artifact and is not committed, so a fresh clone must build once before use. Unless you are developing the plugin, use the npm install above.

     git clone https://github.com/TheRealChickenlegs/dsh-blender-plugin.git
     cd dsh-blender-plugin
     npm ci --legacy-peer-deps
     npm run build
     # Optional: DSH_CHECKOUT=/path/to/dsh-harness npm run build links DSH host packages
  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 <profile>/node_modules/dsh-blender-remote-plugin

    Profile package.json:

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

    Validate the profile and restart DSH:

     dsh --profile <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.

Remote Blender (Docker or another host)

The plugin's backend normally runs on the same machine as DSH, but the Blender add-on may live in a Docker container on a GPU server. Point the backend at that machine on the plugin page:

  1. Open DSH → Plugins → Blender Remote Bridge and set Blender host to the Docker host's LAN address (for example 192.168.10.25). Do not enter 0.0.0.0 there: it is a bind address, not a request address. Leave Blender add-on port at 9876 unless you changed it.

  2. In the container, set the add-on Bind address to 0.0.0.0 (N panel → DSH Blender Bridge → Connection → Bind address, or DSHBB_HOST=0.0.0.0) and publish the port:

    docker run --gpus all -p 9876:9876 -p 9877:9877 ...
  3. Set the add-on's Backend URL to an address the container can reach (for example http://192.168.10.10:9877) so native selection can be pushed back to DSH. It may also come from DSH_BLENDER_BACKEND_URL.

  4. Set workDir to a path that is valid inside the Blender environment (for example /tmp/dsh-blender). Viewport and custom-angle PNGs are returned over the bridge as base64, so they do not need to be visible on the DSH machine. Long headless jobs and exported files still need a shared volume or another way to move files.

  5. Launch and headless start a Blender process on the DSH machine. They are local-only by design; for a remote container, start Blender in the container and use Connect there.

The same options are available headlessly through DSH_BLENDER_ADDON_HOST / DSH_BLENDER_ADDON_PORT or dsh-blender.config.json (see docs/configuration.md).

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/surface-algorithms.md
  • Step-by-step guide: docs/操作教程.md (English; Chinese archive at docs/zh/操作教程.md)
  • Configuration: docs/configuration.md (Chinese archive at docs/zh/配置参考.md)
  • AI install prompt: docs/ai-install-prompt.md (Chinese archive at docs/zh/AI-安装提示词.md)
  • Deployment SOP: docs/deployment.md (Chinese archive at docs/zh/部署SOP.md)
  • Third-party checklist: docs/third-party-install-checklist.md (Chinese archive at docs/zh/给第三方的安装清单.md)
  • Release process: docs/RELEASING.md
  • Architecture: docs/architecture.md
  • Modeling skill: skills/blender-modeling/
  • Hypothesis-driven modeling: docs/hypothesis-driven-modeling-cookbook.md
  • Evidence grading and image discipline: docs/evidence-grading-and-image-discipline.md
  • Host integration contract: docs/host-integration-contract.md
  • Surface algorithms: docs/surface-algorithms.md
  • EEVEE notes: docs/eevee-notes.md
  • 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.zip is supported, and it must be enabled and connected. |

Development

  • Node.js 24.9 is the minimum supported version; CI runs on Node 24.
  • Python tests need a virtualenv with pytest. Point PYTHON at its interpreter (PYTHONIOENCODING=utf-8 and PYTHONUTF8=1 on Windows); tests import the TypeScript sources directly.
  • The canonical command table — install, build, typecheck, test, lint, pack — is AGENTS.md §1. lib/ is rebuilt from runtime/ and src/; never hand-edit it.
  • Test layers, fixtures, and per-layer commands: tests/README.md.
  • Contribution workflow: CONTRIBUTING.md · docs/zh/CONTRIBUTING.md.
  • Bundled skill source: skills/blender-modeling/.

Support

If this project is useful to you, you can support its development on Afdian (爱发电): https://afdian.com/a/sixtysevenlf

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.