DSH × Blender — Direct Realtime Plugin (Shareable Edition)

🤖 Installing with an AI agent? Don't let it guess — send it the repo URL together with this: "Read §2 Requirements, §3 Install and §9 Troubleshooting in the README, plus AGENTS.md, before doing anything. Then run doctor — it is not installed until kind=ok; if it fails, walk §9."

Ready-to-paste prompt: docs/AI-安装提示词.md

Support · Buy me a coffee

This plugin is open source and free (BSD-3-Clause): every feature is available to everyone — no paywall, no license key, no "sponsor edition". If it saved you some time, you're welcome to buy me a coffee: it's a voluntary donation, not a purchase.

A few things, so there's no misunderstanding:

• A donation is not a purchase — it buys no service, license, customization or priority. Issues and PRs are triaged on their own merits, regardless of donations.
• Donations don't change the license — the code stays BSD-3-Clause for everyone, with identical features.
• These are personal appreciation codes for small, voluntary gifts only; not for business or commercial payments. For commercial support, custom work or collaboration, open an issue and we'll do it properly (contract + invoice).
• Please don't repost, forward or reuse the QR codes for anything outside this project.
• The images live in the repo under docs/images/ — click one to open the full-size original (1080×1621 / 1027×1027); if GitHub image loading is unreliable from mainland China, just open the files directly from the repository.

🌐 Language: English (this page) · 简体中文

🧩 Companion skill: blender-modeling — the process and the acceptance criteria for modeling / assembly (multi-agent division of labour, reference-image-driven shapes, six pitfalls, numeric assembly gates). The plugin owns the channel; the skill owns how to build and how to verify.

🏷 Version: v1.0 (package 1.0.0) — the first stable release. The model-facing surface is frozen at 15 tools, and the plan channel exposes 28 families · 183 ops.

Let an AI model actually drive Blender — no clicking, no screenshots-into-prompt, no MCP server. One direct TCP channel (addon 127.0.0.1:9876 · backend 127.0.0.1:9877) gives the model 15 tools: see the viewport · edit the scene · watch a time window · run an inner search loop · profile and fix render perf · decimate objects safely · offload heavy work to a headless process · batch long work as jobs · roll back · store parameter presets · call any addon command · judge / verify / export through the contract layer · operate the channel itself.

Acceptance is unchanged and unforgiving: blender_viewport(op="doctor") must return kind=ok. If it does not, it is not installed — walk §9.

1. What you get (30-second tour)

Detailed walkthrough (Chinese): docs/操作教程.md · configuration reference (Chinese): docs/配置参考.md · deployment SOP: docs/部署SOP.md. This README covers the same ground in condensed English.

2. Requirements

1. Blender 4.x / 5.x running in GUI mode — this channel needs a live GUI session (-b is only used by the headless tools).
2. Blender addon MCP for Blender (not bundled) listening on 127.0.0.1:9876. It must provide at least: ping, get_scene_info, get_world_state_snapshot, get_object_info(name), get_viewport_screenshot(max_size, filepath, format), execute_code(code). The harveyxiacn enhanced blender_mcp_addon is also supported (different wire protocol — the plugin adapts automatically; addonProtocol, default auto, see docs/配置参考.md §6). That implementation has none of the five asset integrations, and the corresponding commands fail loudly instead of pretending. Enable it in Blender, then in a 3D viewport press N → MCP for Blender panel → Connect. Compatibility probe: node runtime/_probe_tools.mjs. Protocol self-test (no Blender needed): node tests/protocol_selftest.mjs.
3. Node.js ≥ 20.
4. DSH (DeepSeek Harness) — this package registers tools as a DSH plugin (inject: ['tools']). Works with DSH in WSL + Blender on Windows (WSL interop is used to spawn blender.exe), with DSH and Blender on the same Windows machine (path mapping degrades gracefully), and — as of v1.0.4 — with native Linux (not WSL): host and Blender share one OS, so no cross-OS path rewriting happens (/home/… reaches Blender as-is) and blender_viewport op=doctor reports your own distro. Blender is found via which blender; set DSH_BLENDER_EXE if it lives elsewhere. Default working dir: os.tmpdir()/dsh-blender-rt (see docs/配置参考.md §5).
5. macOS — supported. Host and Blender run on the same machine, so there is no cross-OS path mapping: Blender is auto-detected under /Applications (Blender*.app, including ~/Applications and /Volumes/*/Applications), and the working dir defaults to ~/.dsh-blender-rt. Set DSH_BLENDER_EXE / blenderExe only if you installed Blender somewhere non-standard; blender_viewport op=doctor prints what was detected.

3. Install (5 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.

4. First contact (three calls)

blender_viewport(op="doctor")                          # health + effective config
blender_rt_see(max_size=560)                           # what the model sees right now
blender_rt_see(from="9,-9,6", look_at="0,0,1")         # a different angle, user viewport untouched

5. What's new in v1.0

• First stable release. The model-facing surface is frozen at 15 tools; the plan channel is 28 families · 183 ops. A capability lock inside npm test pins both numbers and the 15 tool names — losing a family, an op or a tool turns the build red.
• macOS is a first-class host: identity path mapping, .app auto-detection, ~/.dsh-blender-rt working dir, and a /proc-free backend kill path. blender_viewport(op="launch") cold-starts a connected GUI Blender (measured 2.5 s). npm run test:mac = 45 assertions; npm run test:gui = 11/11 on a real machine.
• Five capability families landed — 21 ops, zero new tools: sculpt_* (numpy displacement brushes; bpy.ops.sculpt.brush_stroke does not work from Python on Blender 5.2 — don't try it), fix_* (repair / decimate), uv_* (smart project / unwr