Skip to content
Back to search

dsh-blender-plugin

DSH x Blender direct realtime plugin v1.0 — let an AI model drive Blender over a direct TCP channel: viewport frames, custom-angle renders, inner-loop search, render profiling, safe decimation, headless offload, one-call GUI launch (15 tools + blender_rt_plan: 28 families / 183 ops). 配套 skill:sixtysevenlf/dsh-skill-blender-modeling

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sixtysevenlf/dsh-blender-plugin with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sixtysevenlf/dsh-blender-plugin'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sixtysevenlf--dsh-blender-plugin/badge.svg)](/listings/sixtysevenlf--dsh-blender-plugin)

HTML

<a href="/listings/sixtysevenlf--dsh-blender-plugin"><img src="/api/listings/sixtysevenlf--dsh-blender-plugin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1) Build (needs a DSH source checkout to link cordis/schemastery/dsh-tools)
cd dsh-blender-plugin
DSH_CHECKOUT=/path/to/dsh-harness bash scripts/build.sh     # produces lib/

# 2) (optional) configure — auto-detection usually just works
cp dsh-blender.config.example.json dsh-blender.config.json

# 3) Install into DSH as a profile bundle (this package declares dsh.bundle):
#    a) symlink into <profile>/node_modules/@dsh-external/dsh-blender-plugin
#    b) in the profile package.json add "link:<abs path>" to dependencies and
#       "@dsh-external/dsh-blender-plugin" to dsh.profile.bundles
#    c) dry-run: dsh --profile <profile> --dump-config   then restart DSH

# 4) Start Blender and connect the addon — two routes:
#    agent / unattended: blender_viewport(op="launch")   # boot script + spawn + polls 9876, idempotent
#    manual: start Blender → press N → "MCP for Blender" → Connect (127.0.0.1:9876)

# 5) Verify — the ONLY acceptance criterion: doctor returns kind=ok (otherwise it is NOT installed; walk §9)
curl -sS http://127.0.0.1:9877/health    # backend alive + provenance (is this process the disk copy?)
curl -sS http://127.0.0.1:9877/doctor    # FULL round-trip through bpy; "kind":"ok" is the goal
curl -sS http://127.0.0.1:9877/who       # write lease + channel metrics + effective config

The plugin auto-starts the backend (`node runtime/server.mjs`, default `127.0.0.1:9877`) and runs a **15-second watchdog** that respawns it if it dies. `blender_viewport op=stop` pauses the watchdog.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DSH × Blender
  2. [简体中文](docs/zh/README.md)
  3. 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, background headless jobs (`blender_run(kind="headless")`) still execute scripts and return rendered frames.
  4. ## Contents
  5. - [Features](#features)
  6. - [Quick start](#quick-start)
  7. - [Tools](#tools)
  8. - [Documentation](#documentation)
  9. - [Troubleshooting](#troubleshooting)
  10. - [Development](#development)
  11. - [Support](#support)
  12. - [License](#license)
  13. ## Features
  14. - **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.
  15. - **Headless jobs with visual feedback.** If Blender has no GUI, the agent submits a background headless job (`blender_run(kind="headless")`) and collects scripts, logs, and rendered frames from it. Live step-by-step interaction needs a GUI session; the job path exists so long or fresh-scene work still gets done.
  16. - **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.
  17. - **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.
  18. - **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.
  19. - **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.
  20. - **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.
  21. - **Automation and long jobs.** `blender_run` submits render or headless work and returns a job id immediately; parameter searches and batch validation run inside the GUI session through `blender_op`. Neither occupies the GUI for the whole run.
  22. - **Native selection.** Select objects or collections in Blender and send them into the current DSH draft.
  23. - **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.
  24. ## Quick start
  25. **Before anything else: install the bundled addon first.** Use the addon shipped in this repository: **extension/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. The 3.1 addon dials the Gateway and opens no inbound port, but a legacy MCP bridge still listens on 127.0.0.1:9876; two Blender-side agent bridges confuse the host. 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.
  26. ### Requirements
  27. - DSH (DeepSeek Harness) installed and working.
  28. - 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.
  29. - 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.
  30. - 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` is unsupported (it still listens on 127.0.0.1:9876) — disable it, no need to uninstall.
  31. - Optional: a DSH source checkout when rebuilding the host side; otherwise the build links against this repository's installed dependencies.
  32. ### Option A: install from npm
  33. This is the supported installation path. It does not require `git clone`, `npm ci`, or `npm run build`.
  34. 1. **Install the bundled addon first.** Download `dsh_blender_bridge.zip` from the [latest GitHub Release](https://github.com/sixtysevenlf/dsh-blender-plugin/releases/latest), then in Blender open `Edit > Preferences > Extensions > Install from Disk...`, select the zip, enable **DSH Blender Bridge**, open the `N` panel in the 3D view, and click **Connect**.
  35. 2. **Install the DSH plugin from npm.** Choose the path for your DSH host:
  36. - **DSH Web or DSH TUI:** install into the profile you actually run:
  37. dsh plugin --profile <profile> add dsh-blender-plugin@3.1.0-alpha.1
  38. Then restart DSH in step 3.
  39. - **DSH Desktop:** open the Plugins page and install the bundle `dsh-blender-plugin@3.1.0-alpha.1`. DSH Desktop applies the bundle from the Plugins page and does not need a DSH restart.
  40. 3. **Restart DSH (DSH Web and DSH TUI only).** If you installed from the DSH Desktop Plugins page, skip this step.
  41. 4. **Verify the installation.** The only acceptance criterion for the GUI route is `doctor` returning `kind` equal to `ok`:
  42. curl -sS http://127.0.0.1:39877/doctor
  43. GUI route: `curl -sS http://127.0.0.1:39877/health` and `/doctor`; `doctor.kind` must be `ok`.
  44. Headless-only route (no addon): `blender_run(action="submit", kind="headless", script="print('ok')")` followed by `wait`/`collect` must return the job and its outputs.
  45. The addon remains the only supported Blender-side agent bridge. Disable any other Blender-side agent bridge (a legacy MCP bridge still serves port 9876); ordinary modeling, material, rendering, and asset addons are unaffected.
  46. ### Option B: ask an AI agent
  47. Copy this prompt into an agent that can run commands:
  48. First install and enable the bundled addon dsh_blender_bridge.zip
  49. from the latest GitHub Release. If a bridge addon is already enabled
  50. (MCP for Blender / blender_mcp, or anything else serving Blender on
  51. ), disable it; do not uninstall the user's other addons and
  52. do not ask them to.
  53. Then install the DSH × Blender plugin from npm for my DSH profile:
  54. dsh plugin --profile <profile> add dsh-blender-plugin@3.1.0-alpha.1
  55. Read docs/AI-安装提示词.md first, follow it exactly,
  56. and finish with the acceptance check: doctor must return kind=ok for the
  57. GUI route, or a blender_run headless submit + wait must return outputs for the headless-only route.
  58. Do not skip the check and do not claim success without it.
  59. Fetch the full install prompt locally:
  60. curl -fsSL https://raw.githubusercontent.com/sixtysevenlf/dsh-blender-plugin/main/docs/AI-安装提示词.md -o AI-安装提示词.md
  61. Install the standalone modeling skill (only needed for hosts that do not load the plugin; DSH gets it bundled):
  62. curl -fsSL https://raw.githubusercontent.com/sixtysevenlf/dsh-blender-plugin/main/skills/blender-modeling/install.sh | bash
  63. ### Option C: build from source (developers)
  64. 1. **Install the bundled addon first.**
  65. Download **extension/dsh_blender_bridge.zip** from the extension/ folder of this repository. In Blender, open Edit > Preferences > Extensions > Install from Disk..., select that zip, enable DSH Blender Bridge, open the N panel in the 3D view, and click Connect. The addon dials the DSH Gateway at 127.0.0.1:39877 after Connect; it does not listen on a port. Replacing or upgrading the addon requires a Blender restart: there is no hot reload, and a 3.0.x addon keeps its old 9876 listener until Blender exits. If you previously installed the single-file `dsh_blender_bridge.py`, disable and remove it first: 3.1 installs only this Blender extension.
  66. Keep this addon as your only agent bridge. If `MCP for Blender` / `blender_mcp` (or any other Blender-side agent bridge) 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.
  67. 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. `npm run setup:dev` installs the npm and Python development dependencies (creating `.venv`); unless you are developing the plugin, use the npm install above.
  68. git clone https://github.com/sixtysevenlf/dsh-blender-plugin.git
  69. cd dsh-blender-plugin
  70. npm run setup:dev
  71. npm run build
  72. # Optional: DSH_CHECKOUT=/path/to/dsh-harness npm run build links DSH host packages
  73. 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.
  74. ln -s /absolute/path/to/dsh-blender-plugin <profile>/node_modules/dsh-blender-plugin
  75. Profile package.json:
  76. {
  77. "dependencies": {
  78. "dsh-blender-plugin": "link:/absolute/path/to/dsh-blender-plugin"
  79. },
  80. "dsh": {
  81. "profile": {
  82. "bundles": ["dsh-blender-plugin"]
  83. }
  84. }
  85. }
  86. Validate the profile and restart DSH:
  87. dsh --profile <profile> --dump-config
  88. 4. Verify the installation.
  89. GUI route:
  90. curl -sS http://127.0.0.1:39877/health
  91. curl -sS http://127.0.0.1:39877/doctor
  92. 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.
  93. Blender and the Gateway are started by the host: open Blender yourself, enable the addon, and click Connect. There is no model-facing launch tool in 3.1.
  94. Headless-only route (no addon):
  95. blender_run(action="submit", kind="headless", script="print('ok')")
  96. blender_run(action="wait", id="<jobId>")
  97. A returned job whose outputs include the script log means the headless path is working. The doctor bpy round-trip is expected to be unreachable in this mode.
  98. ## Tools
  99. The plugin exposes exactly 6 model-facing tools; all planning, audit, assembly, export, and evaluation operations live behind `blender_op` (34 families / 228 ops), so the surface stays small.
  100. | Tool | What it gives you |
  101. |---|---|
  102. | blender_session | GUI session lifecycle and ownership: list/status/doctor, attach, claim/release, grant/revoke write scopes, pause state, presence, and `action=txn` snapshots/marks for rollback. Blender and the Gateway are host-managed. |
  103. | blender_op | The capability catalog (`op="catalog"`, 34 families / 228 ops) and the execution surface for modeling, audit, assembly, delivery, and evaluation; also `action=loop|opt|preset`. Executing ops needs a ready GUI session. |
  104. | blender_py | Runs Python in the attached GUI session with a persistent kernel; `see=true` returns a frame. GUI-only: there is no headless fallback. |
  105. | blender_see | GUI capture only: `viewpoint=viewport|camera|custom`, `mode=frame|sequence`, fixed aspect/size tiers. Camera animation and batch renders go to `blender_run(kind="render")`. |
  106. | blender_run | The only job entry point: `action=submit` with `kind=render|headless` returns a job id immediately; `status/wait/collect/cancel/list` manage it; `action=tune` covers render performance. |
  107. | blender_inspect | Lists the addon's executable read-only commands and runs one with `command=` + `args=`; removed write commands return a `wrong_tool` hint. |
  108. Old 3.0 tool names are no longer registered; the migration table is in [MIGRATIONS.md](MIGRATIONS.md) §0.3.
  109. ## Virtual display (virtual-gui)
  110. On Windows and Linux the Gateway can launch an isolated Blender GUI for the agent. It defaults to `auto` on Windows after the V0 acceptance and is opt-in preview on Linux. Missing prerequisites never start silently: `blender_session start kind=virtual-gui` returns `stage=config` with the exact command, and `/blender doctor --fix` (or the add-on preferences button) installs only the same plan. One-click is limited to `xvfb` on Ubuntu 22.04/24.04 and Debian 12 through `pkexec`; VirtualGL must come from its official repository, GPU drivers are detected but never installed, and unsupported platforms get the manual command. See [configuration §5.7](docs/配置参考.md).
  111. ## Documentation
  112. - Surface algorithm: [skills/blender-modeling/references/曲面算法.md](skills/blender-modeling/references/曲面算法.md)
  113. - Step-by-step guide: [docs/操作教程.md](docs/操作教程.md)
  114. - Configuration: [docs/配置参考.md](docs/配置参考.md)
  115. - AI install prompt: [docs/AI-安装提示词.md](docs/AI-安装提示词.md)
  116. - Deployment SOP: [docs/部署SOP.md](docs/部署SOP.md)
  117. - Third-party checklist: [docs/给第三方的安装清单.md](docs/给第三方的安装清单.md)
  118. - DSH upgrade compatibility: [docs/DSH-更新适配.md](docs/DSH-更新适配.md)
  119. - Architecture: [docs/architecture.md](docs/architecture.md)
  120. - Modeling skill: [skills/blender-modeling/](skills/blender-modeling/)
  121. - Release notes: [GitHub Releases](https://github.com/sixtysevenlf/dsh-blender-plugin/releases) and [CHANGELOG.md](CHANGELOG.md)
  122. ## Troubleshooting
  123. | Symptom | What to do |
  124. |---|---|
  125. | 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. |
  126. | No GUI is available | Live interaction needs a GUI session. Submit background work with `blender_run(kind="headless")` and collect it with `action="wait"`/`collect`; rendered frames come from the job outputs. |
  127. | Another session is writing to the same scene | Claim a write scope with `blender_session(action="grant", scopes=...)`, or attach a separate GUI session; parallel jobs are fine through `blender_run`. |
  128. | 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; the 3.1 bridge dials the Gateway, but two Blender-side agent bridges still confuse the host; the legacy MCP bridge listens on 127.0.0.1:9876. |
  129. | 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. |
  130. | Followed the steps and it still does not work | Check the bundled addon first: only extension/dsh_blender_bridge.zip is supported, and it must be enabled and connected. |
  131. ## Development
  132. - Node.js **24.9** is the minimum supported version; CI runs on Node 24.
  133. - Development environment: `npm run setup:dev` after cloning discovers Python 3.11+, creates or reuses
  134. `.venv`, installs `requirements-dev.txt`, `requirements-typecheck.txt`, and npm dependencies
  135. (`npm ci --legacy-peer-deps` only when `node_modules` is missing). `npm run setup:dev -- --check`
  136. verifies without writing; `npm run setup:dev -- --force` recreates `.venv`. `.venv` and
  137. `node_modules` are never committed.
  138. - Python tests need a virtualenv with `pytest` (created by `npm run setup:dev`). Tests auto-detect
  139. `.venv`; point `PYTHON` at another interpreter when needed (`PYTHONIOENCODING=utf-8` and
  140. `PYTHONUTF8=1` on Windows); tests import the TypeScript sources directly.
  141. - The canonical command table — build, typecheck, test, lint, pack — is
  142. [`AGENTS.md` §1](AGENTS.md#1-commands-single-source). `lib/` is rebuilt from `runtime/` and `src/`; never hand-edit it.
  143. - Test layers, fixtures, and per-layer commands: [`tests/README.md`](tests/README.md).
  144. - Contribution workflow: [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`docs/zh/CONTRIBUTING.md`](docs/zh/CONTRIBUTING.md).
  145. - Bundled skill source: `skills/blender-modeling/`.
  146. ## Support
  147. If this project is useful to you, you can support its development on Afdian (爱发电): <https://afdian.com/a/sixtysevenlf>
  148. ## License
  149. The DSH host plugin is BSD-3-Clause (see [LICENSE](LICENSE)). The bundled Blender extension under [
  150. `extension/`](extension/) is GPL-3.0-or-later (see [extension/LICENSE](extension/LICENSE)) and contains
  151. MIT-licensed code derived from [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp), whose
  152. copyright and MIT notice are preserved in [extension/NOTICE](extension/NOTICE). The bundled modeling skill is MIT; see
  153. skills/blender-modeling/LICENSE and NOTICE.md. Blender is a trademark of the Blender Foundation.
skills/blender-modeling/install.sh · Bundled script · 29 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # Install the standalone blender-modeling skill for non-DSH hosts.
  3. # Usage:
  4. # curl -fsSL https://raw.githubusercontent.com/sixtysevenlf/dsh-blender-plugin/main/skills/blender-modeling/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 4 on GitHub
  5. # Installs into ~/.dsh/skills/blender-modeling.
  6. set -euo pipefail
  7. REPO_RAW="https://raw.githubusercontent.com/sixtysevenlf/dsh-blender-plugin/main"
  8. ROOT="$HOME/.dsh/skills"
  9. DEST="$ROOT/blender-modeling"
  10. mkdir -p "$DEST/references"
  11. fetch() {
  12. local src="$1"
  13. local dst="$2"
  14. curl -fsSL "$REPO_RAW/skills/blender-modeling/$src" -o "$dst"
  15. }
  16. fetch "SKILL.md" "$DEST/SKILL.md"
  17. fetch "README.md" "$DEST/README.md"
  18. fetch "NOTICE.md" "$DEST/NOTICE.md"
  19. fetch "LICENSE" "$DEST/LICENSE"
  20. for f in modeling-overview.md multiview-calibration.md 参考图通用还原SOP.md 验收清单.md 曲面算法.md; do
  21. fetch "references/$f" "$DEST/references/$f"
  22. done
  23. printf 'Installed blender-modeling skill to %s\n' "$DEST"
  24. printf 'Restart your agent or reload skills, then invoke "blender-modeling".\n'

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.