dsh-plugin-blender-3d 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 walkzzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# dsh-plugin-blender-3d
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that lets the agent **drive 3D modeling** through a JSON bridge — create primitives, run boolean CSG, transform, assign materials/modifiers, query the scene, and export `STL`/`OBJ`/`PLY`/`GLTF`/`GLB`.
+
+It bundles **two interchangeable runtimes** speaking the same protocol:
+
+| Runtime | Needs Blender? | Engine | Use when |
+| --- | --- | --- | --- |
+| `headless_bridge.py` (default) | ❌ no | `trimesh` + `manifold3d` | headless servers, CI, the harness |
+| `blender_ai_bridge/` add-on | ✅ Blender 3.0+ | `bpy` | you want full Blender power |
+
+Point the tool at a running Blender (set `AIB_PORT` to the add-on's port) and the same commands upgrade to real Blender — no code change.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-plugin-blender-3d
+```
+
+Restart `dsh web` (or let HMR pick it up). The plugin registers two model-facing tools:
+
+- **`blender_model`** — `{ command, args }` → JSON result. Commands: `create_shape`, `boolean`, `transform`, `duplicate`, `delete`, `rename`, `material`, `modifier`, `mesh_edit`, `scene`, `selection`, `scene_clear`, `camera`, `light`, `render`, `export`, `import`, `script`, `command`, `document`.
+- **`blender_scene`** — lightweight scene summary (names/types/counts, no mesh data).
+
+It also contributes the **`blender-3d-modeling`** skill (auto-installed into `$DSH_HOME/skills` on first load if absent).
+
+## OOM-safe by design
+
+Heavy geometry **never** enters the Node/JSON tool channel. Exports return a `file_path`; the agent reads the model from disk with its own file tools. This is the fix for the Node `Ineffective mark-compacts near heap limit` crash that occurs when full meshes are stuffed into JSON.
+
+## Configuration
+
+| Env / config | Default | Meaning |
+| --- | --- | --- |
+| `AIB_PORT` | `13082` | bridge port (set to the add-on port to drive real Blender) |
+| `AIB_HOST` | `127.0.0.1` | bridge host |
+| `AIB_PYTHON` | `python3` | interpreter for the headless bridge |
+
+## Headless runtime deps
+
+```sh
+pip install numpy trimesh manifold3d
+```
+
+## Publish to the marketplace
+
+See [`PUBLISH.md`](./PUBLISH.md). TL;DR: `npm publish` → open a PR to
+[`awesome-dsh-plugin/awesome-dsh-plugin`](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
+adding [`registry-entry.json`](./registry-entry.json) to the list.
+
+## License
+
+MIT
+
+## Example
+
+```sh
+node examples/carve_block.mjs   # box minus sphere -> carved.stl
+```

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh bundle patch: inserts this plugin into a profile's layer stack.
+- insert:
+    - id: blender-3d
+      name: 'dsh-plugin-blender-3d'

package/lib/bridge-client.js

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Tiny HTTP client + on-demand headless-bridge lifecycle for the
+ * dsh-plugin-blender-3d tool. No external deps — Node stdlib only.
+ *
+ * The bridge is the pure-Python `headless_bridge.py` (trimesh + manifold3d).
+ * We keep Node thin: only lightweight command JSON crosses the wire; heavy
+ * geometry stays in Python and is written to disk (OOM-safe, see SKILL.md).
+ */
+
+import { spawn } from "node:child_process";
+import http from "node:http";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BRIDGE_PATH = path.join(__dirname, "runtime", "headless_bridge.py");
+
+// Module-level handle so we don't double-spawn within one harness process.
+let _child = null;
+
+function healthCheck(host, port, timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    const req = http.request(
+      { method: "GET", hostname: host, port, path: "/health" },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          try { resolve(JSON.parse(Buffer.concat(chunks).toString("utf8"))); }
+          catch { resolve(null); }
+        });
+      },
+    );
+    req.on("error", () => resolve(null));
+    req.setTimeout(timeoutMs, () => req.destroy());
+    req.end();
+  });
+}
+
+export async function ensureBridge(opts = {}) {
+  const host = opts.host || "127.0.0.1";
+  const port = Number(opts.port || process.env.AIB_PORT || 13082);
+  const python = opts.python || process.env.AIB_PYTHON || "python3";
+
+  // Already up?
+  const up = await healthCheck(host, port);
+  if (up && up.ok) return { host, port, spawned: false, health: up };
+
+  // Spawn the headless bridge detached.
+  if (!_child || _child.exitCode !== null) {
+    _child = spawn(python, [BRIDGE_PATH, "--host", host, "--port", String(port)], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env },
+    });
+    _child.on("error", () => { _child = null; });
+    try { _child.unref(); } catch { /* ignore */ }
+  }
+
+  // Poll for readiness.
+  const deadline = Date.now() + (opts.startupMs || 20000);
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 300));
+    const h = await healthCheck(host, port);
+    if (h && h.ok) return { host, port, spawned: true, health: h };
+  }
+  throw new Error(`blender bridge did not come up on http://${host}:${port}`);
+}
+
+export function sendCommand({ host, port, command, args = {}, id = 1, timeoutMs = 60000 }) {
+  return new Promise((resolve, reject) => {
+    const body = Buffer.from(JSON.stringify({ id, command, args }));
+    const req = http.request(
+      {
+        method: "POST", hostname: host, port, path: "/",
+        headers: { "Content-Type": "application/json", "Content-Length": body.length },
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => {
+          const text = Buffer.concat(chunks).toString("utf8");
+          if (res.statusCode >= 400) return reject(new Error(`HTTP ${res.statusCode}: ${text.slice(0, 300)}`));
+          try { resolve(JSON.parse(text)); } catch { resolve({ raw: text }); }
+        });
+      },
+    );
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => req.destroy(new Error("bridge timeout")));
+    req.write(body);
+    req.end();
+  });
+}
+
+export async function call(command, args, opts = {}) {
+  const { host, port } = await ensureBridge(opts);
+  const resp = await sendCommand({ host, port, command, args, timeoutMs: opts.timeoutMs });
+  if (resp && resp.error) throw new Error(resp.error);
+  if (resp && resp.result && resp.result.ok === false) {
+    throw new Error(resp.result.error || "command failed");
+  }
+  return resp && resp.result;
+}
+
+export function stopBridge() {
+  if (_child && _child.exitCode === null) { try { _child.kill(); } catch { /* ignore */ } }
+  _child = null;
+}

package/lib/index.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: MIT
+/**
+ * dsh-plugin-blender-3d — DeepSeek Harness Cordis plugin.
+ *
+ * Registers a model-facing `blender_model` tool that drives 3D modeling
+ * through a JSON bridge (create primitives, boolean CSG, transform, material,
+ * modifier, scene, selection, export STL/OBJ/PLY/GLTF, run scripts). The
+ * bridge is the bundled pure-Python `headless_bridge.py` (trimesh + manifold3d,
+ * no Blender required) and is started on demand and kept alive for the session.
+ *
+ * The same protocol is spoken by the bundled Blender add-on
+ * (`runtime/blender_ai_bridge/`), so pointing the tool at a running Blender
+ * (AIB_PORT) upgrades to full Blender power with no code change.
+ *
+ * OOM-safe: heavy geometry never enters the Node/JSON channel — exports return
+ * a `file_path` the agent reads from disk with its own file tools.
+ */
+
+import { call, ensureBridge, stopBridge } from "./bridge-client.js";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+
+export const name = "dsh-plugin-blender-3d";
+export const inject = ["tools", "effect"];
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLED_SKILL = path.join(__dirname, "..", "skill", "blender-3d-modeling", "SKILL.md");
+
+/** Hand-rolled JSON Schema (zero deps), mirroring the skill-search preset. */
+function schema(spec) {
+  const properties = {};
+  const required = [];
+  for (const [k, m] of Object.entries(spec || {})) {
+    properties[k] = { type: m.type, ...(m.description ? { description: m.description } : {}) };
+    if (m.required) required.push(k);
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+
+/** Idempotently materialize the bundled skill into the user skill root. */
+function installSkill() {
+  try {
+    const dshHome = process.env.DSH_HOME;
+    if (!dshHome) return;
+    const destDir = path.join(dshHome, "skills", "blender-3d-modeling");
+    const dest = path.join(destDir, "SKILL.md");
+    if (fs.existsSync(dest)) return;            // don't clobber an existing/newer skill
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(BUNDLED_SKILL, dest);
+  } catch { /* best-effort; never break boot */ }
+}
+
+export function apply(ctx, config = {}) {
+  installSkill();
+
+  const opts = {
+    host: config.host || process.env.AIB_HOST || "127.0.0.1",
+    port: config.port || process.env.AIB_PORT || 13082,
+    python: config.python || process.env.AIB_PYTHON || "python3",
+    startupMs: config.startupMs || 20000,
+    timeoutMs: config.timeoutMs || 60000,
+  };
+
+  ctx.tools.register({
+    name: "blender_model",
+    description:
+      "Drive 3D modeling through the Blender AI bridge. Pass a `command` and " +
+      "`args`; the bridge runs it and returns a JSON result. Commands: " +
+      "create_shape, boolean, transform, duplicate, delete, rename, material, " +
+      "modifier, mesh_edit, scene, selection, scene_clear, camera, light, render, " +
+      "export, import, script, command, document. Exports return a file_path " +
+      "(read the model from disk with your file tools — geometry is never inlined). " +
+      "First call auto-starts a headless Python bridge (trimesh+manifold3d); set " +
+      "AIB_PORT to drive a real Blender running the bundled add-on instead.",
+    parameters: schema({
+      command: { type: "string", required: true, description: "bridge command, e.g. create_shape / boolean / export / scene" },
+      args: { type: "object", description: "command arguments object" },
+    }),
+    output: {
+      schema: { type: "object", additionalProperties: false, properties: { text: { type: "string" } }, required: ["text"] },
+      render: (_a, v) => [{ type: "text", text: v.text }],
+    },
+    async execute(args, _exec) {
+      const command = args?.command;
+      const commandArgs = args?.args || {};
+      if (!command) throw new Error("blender_model requires a `command` string");
+      const result = await call(command, commandArgs, opts);
+      return { text: JSON.stringify(result, null, 2) };
+    },
+  });
+
+  // Optional: a thin `blender_scene` convenience tool for quick inspection.
+  ctx.tools.register({
+    name: "blender_scene",
+    description:
+      "Return a lightweight summary of the current 3D scene (object names, types, " +
+      "locations, vertex/face counts). No mesh data — OOM-safe. Equivalent to " +
+      "blender_model {command:'scene'}.",
+    parameters: schema({}),
+    output: {
+      schema: { type: "object", additionalProperties: false, properties: { text: { type: "string" } }, required: ["text"] },
+      render: (_a, v) => [{ type: "text", text: v.text }],
+    },
+    async execute(_a, _exec) {
+      const result = await call("scene", {}, opts);
+      return { text: JSON.stringify(result, null, 2) };
+    },
+  });
+
+  // Stop the spawned bridge when the harness tears down this composition.
+  try {
+    ctx.effect(function* () { yield async () => stopBridge(); }, "blender-3d-bridge");
+  } catch { /* effect service unavailable — ignore */ }
+}
+
+export { ensureBridge };

package/lib/runtime/blender_ai_bridge/README.md

@@ -0,0 +1,57 @@
+# Blender AI Bridge — DeepSeek Harness 插件
+
+一个 Blender add-on，把 Blender 的 3D 建模能力通过 **HTTP JSON 命令 API** 暴露出来，
+让外部 agent（DeepSeek harness）可以驱动建模：创建图元、布尔运算、变换、材质、修改器、
+场景查询、选择、导出、运行脚本。
+
+> 设计与工作区里 `chili3d` 的浏览器桥接同源：插件内开服务、harness 发命令、结果回 JSON。
+> 关键防 OOM：**导出只回文件路径，不把网格二进制塞 JSON**；harness 再从磁盘读模型。
+
+## 安装到 Blender
+
+1. `Edit > Preferences > Add-ons > Install…`
+2. 选择本目录打包后的 `blender_ai_bridge.zip`（把整个 `blender_ai_bridge/` 目录压缩成 zip）。
+3. 勾选启用 **AI Bridge (DeepSeek Harness)**。
+4. 在 3D 视图侧栏（按 `N`）打开 **AI Bridge** 面板，点 **Start**。
+   或设端口：`Preferences > Add-ons > AI Bridge` 里改 Host/Port（默认 `127.0.0.1:13080`）。
+
+## 无头运行（无界面，CI/服务器）
+
+```bash
+AIB_PORT=13080 blender --background --python /workspace/blender_ai_bridge/headless_start.py
+```
+
+服务起来后 `GET http://127.0.0.1:13080/health` 返回 `{"ok":true,"blender":[4,2,0],...}`。
+
+## 命令协议
+
+`POST /` body：`{"id":1,"command":"create_shape","args":{"type":"box","dx":2,"dy":3,"dz":4}}`
+响应：`{"id":1,"result":{"ok":true,"name":"Cube","type":"box",...}}` 或 `{"id":1,"error":"..."}`
+
+| command | args 摘要 |
+|---|---|
+| `create_shape` | `type` box/sphere/ico_sphere/cylinder/cone/torus/plane/grid/circle/monkey + 尺寸 + `location`/`rotation`/`name` |
+| `boolean` | `target`,`tools`/`tool`,`operation` union/difference/intersect,`apply`,`remove_tools`,`solver` |
+| `transform` | `name`,`location`,`rotation`,`scale`,`rotation_degrees` |
+| `duplicate` / `delete` / `rename` | 对象复制/删除/改名 |
+| `material` | `action` create/assign/list + `color`,`metallic`,`roughness` |
+| `modifier` | `action` add/remove/list + `type` subsurf/bevel/array/mirror/solidify + `params`,`apply` |
+| `mesh_edit` | `name`,`action` subdivide/extrude/inset/recalc_normals |
+| `scene` / `selection` / `scene_clear` | 轻量场景/选择查询（不回网格数据） |
+| `camera` / `light` / `render` | 相机/灯光/渲染到文件 |
+| `export` | `format` stl/obj/ply/fbx/gltf/glb/blend + `path`/`names` → 返回 `file_path` |
+| `import` | `format` + `path` |
+| `script` / `command` / `document` | 执行 Python / Blender operator / 新建保存打开 |
+
+## 版本兼容
+
+- 导出自动适配 3.x（`export_mesh.stl`/`export_scene.obj`）与 4.1+（`wm.stl_export`/`wm.obj_export`）。
+- 布尔修改器 4.0+ 设 `solver`（默认 `EXACT`）。
+- `bl_info` 声明 `blender: (3,0,0)`，3.0+ 均可加载。
+
+## 文件
+
+- `__init__.py` — add-on 入口、注册、N 面板、偏好设置、后台模式自启
+- `server.py` — HTTP 服务 + 主线程 marshal（bpy.ops 线程不安全，经 `bpy.app.timers` 转回主线程）
+- `commands.py` — 命令处理器（bpy/bmesh）
+- `headless_start.py` — `blender --background` 启动器

package/lib/runtime/blender_ai_bridge/__init__.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+bl_info = {
+    "name": "AI Bridge (DeepSeek Harness)",
+    "author": "DeepSeek Harness",
+    "version": (1, 0, 0),
+    "blender": (3, 0, 0),
+    "location": "View3D > Sidebar (N) > AI Bridge",
+    "description": "Expose a JSON command API over HTTP so an external agent "
+                   "(DeepSeek harness) can drive 3D modeling: primitives, "
+                   "booleans, transforms, materials, modifiers, scene, "
+                   "selection, export, scripts.",
+    "category": "Interface",
+}
+
+import bpy
+from bpy.props import StringProperty, IntProperty, BoolProperty
+from bpy.types import Operator, Panel, AddonPreferences
+
+from . import server as _server
+
+# Single shared server instance for the add-on.
+_SERVER = _server.BridgeHTTPServer()
+
+
+# --------------------------------------------------------------------------- #
+# operators
+# --------------------------------------------------------------------------- #
+class AIB_OT_start(Operator):
+    bl_idname = "aib.start"
+    bl_label = "Start AI Bridge"
+    bl_description = "Start the HTTP bridge server on the configured port"
+
+    def execute(self, context):
+        prefs = _prefs(context)
+        _SERVER.host = prefs.host
+        _SERVER.port = prefs.port
+        try:
+            _SERVER.start()
+        except OSError as exc:
+            self.report({'ERROR'}, "Failed to start: %s" % exc)
+            return {'CANCELLED'}
+        _server.ensure_timer()
+        prefs.running = True
+        self.report({'INFO'}, "AI Bridge on %s" % _SERVER.url())
+        return {'FINISHED'}
+
+
+class AIB_OT_stop(Operator):
+    bl_idname = "aib.stop"
+    bl_label = "Stop AI Bridge"
+    bl_description = "Stop the HTTP bridge server"
+
+    def execute(self, context):
+        _SERVER.stop()
+        _prefs(context).running = False
+        self.report({'INFO'}, "AI Bridge stopped")
+        return {'FINISHED'}
+
+
+class AIB_OT_status(Operator):
+    bl_idname = "aib.status"
+    bl_label = "Bridge Status"
+    bl_description = "Print bridge status to the info area"
+
+    def execute(self, context):
+        state = "running at %s" % _SERVER.url() if _SERVER.running else "stopped"
+        self.report({'INFO'}, "AI Bridge %s" % state)
+        return {'FINISHED'}
+
+
+# --------------------------------------------------------------------------- #
+# panel
+# --------------------------------------------------------------------------- #
+class AIB_PT_panel(Panel):
+    bl_label = "AI Bridge"
+    bl_idname = "AIB_PT_panel"
+    bl_space_type = 'VIEW_3D'
+    bl_region_type = 'UI'
+    bl_category = "AI Bridge"
+
+    def draw(self, context):
+        prefs = _prefs(context)
+        layout = self.layout
+        col = layout.column(align=True)
+        if _SERVER.running:
+            col.label(text="Running: %s" % _SERVER.url(), icon='CHECKMARK')
+            col.operator("aib.stop", icon='PAUSE')
+        else:
+            col.label(text="Stopped", icon='X')
+            col.operator("aib.start", icon='PLAY')
+        col.separator()
+        col.prop(prefs, "host")
+        col.prop(prefs, "port")
+        col.separator()
+        box = col.box()
+        box.label(text="Commands:", icon='SCRIPT')
+        for line in ("create_shape, boolean, transform",
+                     "duplicate, delete, material, modifier",
+                     "scene, selection, export, import",
+                     "camera, light, render, script"):
+            box.label(text=line)
+
+
+# --------------------------------------------------------------------------- #
+# preferences
+# --------------------------------------------------------------------------- #
+def _prefs(context):
+    return context.preferences.addons[__name__].preferences
+
+
+class AIBPreferences(AddonPreferences):
+    bl_idname = __name__
+
+    host: StringProperty(name="Host", default="127.0.0.1")
+    port: IntProperty(name="Port", default=13080, min=1, max=65535)
+    running: BoolProperty(name="Running", default=False)
+
+    def draw(self, context):
+        layout = self.layout
+        layout.prop(self, "host")
+        layout.prop(self, "port")
+        if _SERVER.running:
+            layout.operator("aib.stop")
+        else:
+            layout.operator("aib.start")
+
+
+# --------------------------------------------------------------------------- #
+# registration
+# --------------------------------------------------------------------------- #
+_classes = (AIB_OT_start, AIB_OT_stop, AIB_OT_status, AIB_PT_panel, AIBPreferences)
+
+
+def register():
+    for cls in _classes:
+        bpy.utils.register_class(cls)
+    # Auto-start in headless mode so `blender --background --python` just works.
+    try:
+        if bpy.app.background:
+            bpy.app.handlers.event_timer  # noqa: B018 - probe attribute
+            _SERVER.host = "127.0.0.1"
+            _SERVER.port = int(__import__("os").environ.get("AIB_PORT", "13080"))
+            _SERVER.start()
+            _server.ensure_timer()
+    except Exception:
+        pass
+
+
+def unregister():
+    _SERVER.stop()
+    for cls in reversed(_classes):
+        try:
+            bpy.utils.unregister_class(cls)
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    register()