dsh-preview-blender：在 DSH 中预览 Blender .blend 文件

前言¶

DeepSeek Harness 的文档预览默认遇到 .blend 文件时会显示「二进制文件，无预览」的空状态。如果需要在工作流中快速查看场景结构、包围盒尺寸或材质分布，就需要一个能将 .blend 转换为可交互 WebGL 模型的方案。dsh-preview-blender 插件通过在 DSH 中注册渲染器，在右侧边栏将 .blend 文件渲染为可交互的 3D 视口，并提供场景统计信息。

这是什么¶

dsh-preview-blender 是一个 DSH 插件，用于在 DeepSeek Harness 的右侧边栏中预览 Blender .blend 文件。它维护者 439436269-ctrl，通过后台调用 Blender 头部模式导出 GLB，再由一个无需外部依赖的 WebGL 渲染器在浏览器中绘制场景。插件包含缓存机制，第二次打开同一文件版本几乎是毫秒级响应。

核心功能¶

1. 注册 .blend 文档预览渲染器¶

插件为 .blend 文件注册了文档预览渲染器。在 Workspace 文件列表中点击 .blend 文件，右侧边栏会显示 3D 预览，而不是默认的空状态。预览内容基于 Blender 的头部导出结果。

2. 头部 Blender 导出 GLB¶

每次打开一个 .blend 文件版本时，插件会运行一次 blender --background，通过内置 Python 脚本导出 GLB 模型文件和场景 JSON。导出时使用 export_apply、use_visible、Y-up 坐标系，不包含相机和灯光。场景 JSON 包含对象、三角形数、材质、世界空间包围盒（毫米单位）、场景单位、相机、灯光和集合信息。

3. 依赖自由的 WebGL 查看器¶

插件内置了一个为 GLB 2.0 子集编写的 WebGL 渲染器，支持轨道旋转、平移、滚轮缩放、双击重置、线框模式、自动旋转、软接触阴影和轴三角形。渲染器仅使用 POSITION + NORMAL、索引三角形、PBR 因子和节点 TRS/矩阵，不依赖 CDN 也不依赖 three.js。

4. 本地缓存¶

导出的 GLB 和场景 JSON 会缓存到 ~/.dsh/cache/preview-blender 目录。缓存键基于文件真实路径、大小、修改时间、配方和修饰符生成。第二次打开同一文件版本时，插件直接读取缓存，无需重新运行 Blender，冷转换后的热打开响应时间在几毫秒量级。

5. 场景统计面板¶

预览界面包含一个场景统计面板，列出每个对象的三角形数量和包围盒尺寸（毫米单位）、材质色块和场景单位。这些信息对 CAD 和 3D 打印工作流比较实用。

安装与启用¶

安装命令：

# 在普通（非桌面）配置文件中安装
dsh plugin --profile <profile> add dsh-preview-blender

# 桌面配置文件由 Electron 应用拥有，需要在插件管理器 UI 中添加，或手动组装后重启应用

插件会自动注册渲染器和转换路由。安装后重启 DSH。

配置¶

在 DSH 设置 → 插件中找到「Blender preview」（命名空间 preview-blender），可调整以下参数：

enabled：是否注册渲染器和转换路由，默认 true
routePath：认证转换路由路径，默认 /api/preview/blender，必须保持在 /api 下，否则会绕过认证 fence
extensions：在 3D 预览中打开的文件后缀，默认 ["blend"]
blenderPath：blender.exe 或 blender 的绝对路径，留空则自动检测 DSH_BLENDER、BLENDER_PATH、PATH 中的 blender、Steam 库以及 C:\Program Files\Blender Foundation\Blender*
cacheDir：导出的 GLB 文件和场景 JSON 存储目录，留空则使用 ~/.dsh/cache/preview-blender
timeoutMs：单次冷转换的超时时间上限，默认 180000 毫秒（3 分钟）
maxBytes：允许转换的最大文件大小，默认 1073741824 字节（1 GiB）
applyModifiers：导出时是否应用修改器，默认 true，设为 false 时导出原始状态
cacheEntries：磁盘上保留的缓存条目数量，默认 24，超过后会删除最旧的条目

工作流程¶

Workspace file click
        │
        ▼
document preview body (lib/client.js)
        │  GET /api/preview/blender?path=…&kind=info   (scene JSON)
        │  GET /api/preview/blender?path=…&kind=glb    (model bytes)
        ▼
Host half (lib/index.js, lib/route.js)
        │  cache key = sha1(realpath, size, mtime, recipe, modifiers)
        ▼
lib/blender.js ── spawn blender --background --python lib/scene.py
        │            → model.glb + scene.json (+ meta.json)
        ▼
~/.dsh/cache/preview-blender/<key>/

开发与构建¶

插件使用以下文件结构：

dev/client-body.js：客户端 UI，DSH 模块加载器使用的单 CJS 工厂
dev/viewer.js：WebGL 渲染器，在构建时拼接到 bundle 中
scripts/build-client.mjs：从 dev/ 目录下的文件构建 lib/client.js
scripts/e2e-browser.mjs：使用 Playwright 对临时 DSH 主机进行端到端测试
scripts/live-selftest.mjs：对真实 .blend 文件执行冷转换、热转换和并发转换测试
node --test test/*.test.js：单元测试

lib/client.js 是自动生成的文件，应编辑 dev/ 目录下的源文件并重新构建。DSH 客户端加载器会向 bundle 传入一个受限的 require，仅包含平台种子模块，因此运行时无法引入外部渲染器依赖。

限制与注意事项¶

冷转换耗时约 2-10 秒（Blender 启动时间占主导），后续打开同一文件版本会直接读取缓存
非常大的场景（数百万三角形）导出较慢，可能超过 timeoutMs
查看器不显示纹理，仅显示基础颜色；Blender 自带的渲染图仍是参考
不上传任何文件，Blender 在本地运行，GLB 文件保留在本地缓存中
插件以当前 DSH 进程权限运行，安装前应检查源码和许可证
插件当前兼容 DeepSeek Harness 0.2.0-rc.2 和 0.2.1-rc.2

生态背景¶

DeepSeek Harness 的理念是「一切皆插件」。dsh-preview-blender 是社区维护的 DSH 插件，与 DeepSeek 或幻方无官方从属关系。社区目录（https://www.skillhub.cn/plugins/439436269-ctrl/dsh-preview-blender）提供插件信息和提交反馈。