dsh-blender-plugin README

项目的 README,来自 github.com/sixtysevenlf/dsh-blender-plugin。合并为一个 markdown 文件:README.md。

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, background headless jobs (blender_run(kind="headless")) still execute scripts and return rendered frames.

Contents

Features

Quick start

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.

Requirements

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 > Extensions > Install from Disk..., 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:39877/doctor
    

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

    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.

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.

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
), 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-安装提示词.md first, follow it exactly,
and finish with the acceptance check: doctor must return kind=ok for the
GUI route, or a blender_run headless submit + wait must return outputs 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 C: build from source (developers)

  1. Install the bundled addon first.

    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.

    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.

  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.

     git clone https://github.com/sixtysevenlf/dsh-blender-plugin.git
     cd dsh-blender-plugin
     npm run setup:dev
     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-plugin
    

    Profile package.json:

     {
       "dependencies": {
         "dsh-blender-plugin": "link:/absolute/path/to/dsh-blender-plugin"
       },
       "dsh": {
         "profile": {
           "bundles": ["dsh-blender-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:39877/health
     curl -sS http://127.0.0.1:39877/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.

    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.

    Headless-only route (no addon):

     blender_run(action="submit", kind="headless", script="print('ok')")
     blender_run(action="wait", id="<jobId>")
    

    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.

Tools

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.

Tool What it gives you
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.
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
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.
blender_see GUI capture only: `viewpoint=viewport
blender_run The only job entry point: action=submit with `kind=render
blender_inspect Lists the addon's executable read-only commands and runs one with command= + args=; removed write commands return a wrong_tool hint.

Old 3.0 tool names are no longer registered; the migration table is in MIGRATIONS.md §0.3.

Virtual display (virtual-gui)

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.

Documentation

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 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.
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.
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.
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 extension/dsh_blender_bridge.zip is supported, and it must be enabled and connected.

Development

Support

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

License

The DSH host plugin is BSD-3-Clause (see LICENSE). The bundled Blender extension under extension/ is GPL-3.0-or-later (see extension/LICENSE) and contains MIT-licensed code derived from ahujasid/blender-mcp, whose copyright and MIT notice are preserved in extension/NOTICE. The bundled modeling skill is MIT; see skills/blender-modeling/LICENSE and NOTICE.md. Blender is a trademark of the Blender Foundation.

dsh-blender-plugin (sixtysevenlf/dsh-blender-plugin)

正在搜索数据库…

这是什么?在 DeepSeek Harness(DSH)与正在运行的 Blender 图形界面会话之间建立一条直接的 TCP 通道,为 AI 模型提供 15 个工具,用于查看、编辑、批量处理、验证和回滚场景;你可以直接在 Blender 中选中对象,再交给 AI 处理。
这是 Blender 插件还是 DSH 插件?同一个软件包的两个部分:一个在 Blender 图形界面内运行的 Blender 插件(addon/dsh_blender_bridge.py),以及一个 DSH 插件(通过 cordis.patch.yml 声明 dsh.bundle),用于运行 Node.js 后端并提供 15 个模型工具。
使用前我需要准备什么?以图形界面模式运行的 Blender 4.x 或 5.x,用于后端的 Node.js 20+,以及已安装的 DeepSeek Harness(DSH),因为这是一个 DSH 插件;只有在从源码重新构建时,才需要完整的 DSH 源码检出版本。
我能继续使用原版的 MCP for Blender 插件吗?不能。从 v2.3 起,只支持随附的 dsh_blender_bridge.py 插件;旧的上游 'MCP for Blender' 以及 harveyxiacn 集成已被移除,安装本插件前必须先将其禁用。
在 WSL 中运行 DSH、而 Blender 运行在 Windows 上,能用吗?可以。支持在 WSL 中运行 DSH、Blender 运行在 Windows 上的组合,通过 WSL 互操作实现(默认开启);Windows、原生 Linux 或 macOS 上的同系统环境会被自动检测。
15 个模型工具到底能做什么?它们涵盖视口截图、在 Blender 主线程中运行 Python、网格减面与审计、无头渲染和基于工作进程的渲染、事务级回滚、参数预设以及长时间任务管理,并可串联成“模型 → 审计 → 修复”或“带贴图交付”等工作流。
v2.5 新增的 AI 暂停按钮是做什么的?Blender 的 N 面板现在会显示实时活动行和一键 Pause AI 按钮;暂停期间,DSH 发来的写入命令会返回 AIPAUSED,只有只读查询仍可执行,恢复只能在 Blender 面板中操作。
怎样把我在 Blender 中的当前选择发送给 AI?在 Blender 中选中对象,然后按 N → Selection → DSH → send;所选内容会放入当前 DSH 聊天草稿中,而不会自动发送。提供 Multi(对象)或 Collection(集合)模式,并且从 v2.4 起支持选中顶点、边、面或骨骼等子元素。
我能不用点击,而是按名称引用对象吗?可以,在聊天中输入 @,即可按名称选择场景对象、材质或集合(使用 object:/material:/collection: 前缀),这样模型拿到的是准确名称,而不必猜测。
大小
10.5 MB
星标
2.2K
时长
2个月
提交 · 90 天