blender

一句话定位

为 DeepSeek Harness 接入 Blender 4.3+/5.x 后端的 3D 建模流水线，让 DSH 会话能直接对 .blend 场景做检查、写 Python、预览、渲染、导出和结构校验，并在 workspace 内安全地完成从草图到 GLB 的全流程。

核心能力

• 检查 Blender 状态、版本与场景/对象结构（场景、变换、包围盒、拓扑、材质、UV、形态键、动画）
• 导入 GLB/glTF、FBX、OBJ、STL、USD、PLY、Collada 等便携模型并落盘为版本化的 .blend 工程源
• 在 Blender 后台跑受控 bpy/bmesh Python 脚本，结果写回新的 .blend，并返回结构化证据
• 渲染临时无相机预览（等距/前后左右/顶底视角）和正式单帧/动画代表帧，输出 PNG/JPEG
• 导出 GLB/glTF、FBX、OBJ、STL、USD、PLY 等通用格式，并基于目标（Web/3D 打印/动画）做结构审计与干净进程回读校验
• 调用 26 个确定性 Helper（参考图、线框、轮廓、多视图配准、UV、贴图、外观、修复、动画 QA），通过 catalog 白名单执行

技术实现

• 语言: TypeScript (Node, ESM) + Python (Blender 驱动与 Helper 脚本)
• 关键依赖: @deepseek-ai/dsh-tools、@deepseek-ai/schemastery、Python opencv-python-headless / numpy / Pillow / scipy（按需）
• 架构模式: 注入 DSH tools 与 skills 两条注入面；Node 端用 child_process.spawn 以 --background 拉起独立 Blender 进程，通过 --python 加载 scripts/dsh_blender_driver.py 调度操作，临时目录经 JSON 传递 payload/result，每次调用独立临时目录并强制 --disable-autoexec
• 入口文件: index.js（主入口，含 Schema 与 apply）；辅助 cordis.patch.yml（默认配置插入宿主）

适用场景

适用于 DSH 用户希望由 AI 直接在 Blender 里完成 3D 建模全流程的场景：把文字描述、参考图、线框或多视图变成可编辑的 .blend 与可交付的 GLB；或在已有 .blend 上做结构体检、清理、格式转换与回读校验。默认所有读写都被限制在 DSH 会话 workspace 内，适合不希望脚本越界触碰系统其它位置的协作环境。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:CheshireJCat/blender

配置项

常见问题

Q: 安装后还需要做什么才能用？

A: 需要在系统 PATH 中能直接调用 blender（Blender 4.3+，推荐 5.x），或把 blenderExecutable 配成 Blender 绝对路径；如果要用参考图、线框、多视图、贴图、动画分析 Helper，再执行一次 dsh-blender-setup 即可。

Q: 是不是要装 BlenderMCP 或开端口？

A: 不需要。插件每次调用都新拉一个独立的 Blender 后台进程，通过 --disable-autoexec 禁止 .blend 内嵌脚本自动执行，不开放任何控制端口，宿主机之外不会暴露 Blender。

Q: blender_python 安全吗？

A: 它等价于在 Blender 里跑本地 Python，权限等同于 Blender 自身。可以在 cordis.patch.yml 里把 enablePython 设为 false 关闭它，仅保留检查、渲染、导出工具；同时默认所有路径限制在 DSH 会话 workspace 内并拒绝覆盖已有文件。

Q: 默认会覆盖我已有的 .blend 文件吗？

A: 不会。所有写工具（导入、blender_python、预览、渲染、导出）默认要求新路径不存在；如需替换需显式传 allow_overwrite=true，建议通过版本号命名（如 model.v1.blend / model.v2.blend）保留工程源。

Q: 支持哪些导入导出格式？

A: 导入支持 GLB/glTF、FBX、OBJ、STL、USD、PLY、Collada(DAE)；导出支持 GLB/glTF、FBX、OBJ、STL、USD/USDA/USDC、PLY。未指定导出格式时，工具描述建议优先选择 GLB 作为通用交付。

Q: 为什么 blender_status 显示可用，但渲染报 Blender 不在 PATH？

A: blenderExecutable 默认是字符串 blender，会依赖 shell 的 PATH 解析；如果 Blender 没装在 PATH 或装在自定义路径，需要把该项改成 Blender 可执行文件的绝对路径，例如 /Applications/Blender.app/Contents/MacOS/Blender。

Q: 怎么卸载？

A: 在宿主 DSH 的 cordis.patch.yml 中移除 blender-modeling 那段 insert，重启 dsh 即生效；本机安装残留的 .venv 与已落盘的 .blend 需手动删除。

上手难度

进阶 — 默认配置即可零配置运行 blender_status / 导入 / 预览，但要用好 blender_python 和 26 个 Helper 需要理解 Blender bpy/bmesh、参考图配准流程与 workspace 边界规则。

已知问题与限制

• blender_python 等同 Blender 本地 Python 权限，配置项 enablePython: false 可关闭该工具以减少面
• 默认拒绝覆盖已有文件、限制路径到当前 dsh 会话 workspace、强制 --disable-autoexec，不要为了绕过而修改配置
• Blender 5.x 已不包含 Mesh.use_auto_smooth，需走显式平滑/法线策略；EEVEE 折射为屏幕空间效果，存在已知视觉局限
• 渲染单一格式时会丢失部分 Blender 特性，例如 FBX 一次只能携带一个默认 Action，需要靠 NLA + 烘焙多动作；glTF 也存在已知 caveat
• 3 个维护类 Helper（Skill 图谱审计等）默认关闭，需显式开启 enableMaintenanceHelpers 才会出现在 catalog
• 输出/诊断日志有 maxOutputChars（默认 20000 字符）截断，过长堆栈可能丢失尾部
• 单次 blender_python 调用是独立 Python 命名空间，模块需要每次重新导入，持久对象靠稳定名字检索

简体中文

An installable DeepSeek Harness plugin that gives dsh a complete Blender-backed 3D production workflow. It registers one orchestrator plus 29 directly loadable domain skills, all 26 upstream analysis/validation helpers, and 13 workspace-scoped Blender tools.

Example output

Camera-free preview generated during a real dsh-blender installation smoke test.

Tools

• blender_status checks Blender, analysis Python, skills, helpers, and the active workspace.
• blender_scene_info and blender_object_info inspect scenes and object-level geometry, materials, UVs, constraints, shape keys, and animation.
• blender_import converts supported portable assets into versioned .blend sources.
• blender_python runs a small reviewed bpy/bmesh chunk and saves a versioned .blend.
• blender_preview, blender_render, and blender_render_frames create blockout, look-dev, and animation evidence for read_image QA.
• blender_export exports GLB/glTF, FBX, OBJ, STL, USD, or PLY.
• blender_validate_scene and blender_validate_export perform target-aware audits and clean-process re-import checks.
• blender_helper_catalog and blender_helper_run expose all 26 deterministic reference, wireframe, contour, multiview, UV, texture, look, repair, and animation-QA helpers.
• The bundled 30-skill stack coordinates blockout, refinement, materials, lighting, cameras, animation, reconstruction, validation, and artifact handoff.

No Blender add-on or control port is required: each operation launches a local Blender background process.

Requirements

• DeepSeek Harness 0.1.0-rc.6
• Node.js 20+
• Blender 4.3+ available as blender on PATH, or configured with an absolute path
• Python 3.10+ for the optional reference-analysis helpers

Install from npm

npx @deepseek-ai/dsh plugin --profile web add dsh-blender
npx @deepseek-ai/dsh plugin --profile web exec dsh-blender-setup
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

The setup command creates a private .venv inside the installed package and installs OpenCV, NumPy, Pillow, and SciPy. Skip it only if you do not need reference, wireframe, multiview, texture, or animation-analysis helpers.

To install a pinned GitHub release instead:

npx @deepseek-ai/dsh plugin --profile web add github:CheshireJCat/blender#v0.2.1

Develop from source

pnpm install
pnpm setup:analysis
npx @deepseek-ai/dsh plugin --profile web add .

Open http://127.0.0.1:3080, create a session whose workspace is the modeling directory, and ask dsh to use create-3d-model.

See README.zh-CN.md for configuration, security boundaries, headless use, and validation commands.