前言¶
在 DeepSeek Harness（DSH）里浏览工作区文件时，.blend 这类二进制资产往往只能看到「无法预览」的占位状态。若要在本地核对模型尺度、三角面数量或材质基色，通常要单独打开 Blender，打断在 Harness 里的查阅节奏。下面介绍社区插件 dsh-blend-preview：在右侧栏文档预览里把场景转成可交互的 3D 视口，并附带面向 CAD / 3D 打印常用的场景统计信息。
这是什么¶
dsh-blend-preview（GitHub：439436269-ctrl/dsh-blend-preview，npm 包名同插件 id）由维护者 439436269-ctrl 发布，分类为客户端插件。它为 .blend 注册文档预览渲染器：在工作区文件列表中点击 .blend 后，右侧栏不再显示内置的空预览，而是用无外部 CDN、不依赖 three.js 的自研 WebGL 查看器绘制导出的 GLB，并提供场景信息面板。
转换在本地完成：Host 侧对每个文件版本调用一次 blender --background 导出 GLB 与场景 JSON，结果缓存在 ~/.dsh/cache/blend-preview，二次打开可在毫秒级命中缓存。
核心功能¶
文档预览与交互视口¶
- 为
.blend（及配置中的其他后缀）注册预览渲染器，点击即于右侧栏打开。 - 查看器支持轨道旋转、平移、滚轮缩放、双击复位、线框模式、自动旋转、柔和接触阴影与坐标轴指示；不加载 CDN，运行时也不引入额外渲染库依赖。
无头导出与缓存¶
- 每个文件版本执行一次后台 Blender，产出 GLB 与 scene JSON（对象、三角面、材质、毫米级真实尺寸、单位、相机、灯光、集合等元数据）。
- 缓存目录默认
~/.dsh/cache/blend-preview；缓存键基于真实路径、大小、mtime、配方与 modifier 设置。官方说明中，小型场景冷转换约 2–10 秒（Blender 启动占主导），暖启动打开约数毫秒；旋转缩放不会再次启动 Blender。
场景统计面板¶
面向工程核对：逐对象三角面数、包围盒尺寸（毫米）、材质色块、场景单位等，便于与 CAD / 3D 打印工作流对照。视口内材质以 Principled 基色转 sRGB 色块展示，不显示贴图；完整渲染仍以 Blender 侧输出为准。
安全与范围¶
- 转换路由默认
/api/blend-preview，须留在/api下以便连接服务做 Host/Origin 与会话校验，避免任意本地文件被未授权暴露。 - 导出为静态场景：手写 glTF 2.0 子集渲染器，不支持纹理、蒙皮与动画；
lib/scene.py使用 Y-up、export_apply、可见对象等约定导出。
环境要求¶
- DeepSeek Harness 0.2.x（
package.json声明与0.2.0-rc.2、0.2.1-rc.2兼容）。 - Blender 3.6 / 4.x / 5.x 已安装。插件会尝试
DSH_BLENDER、BLENDER_PATH、PATH上的blender、Steam 库及 Windows 默认安装路径；若安装位置特殊，在配置中设置blenderPath。 - 浏览器或 DSH 桌面端需具备 WebGL（桌面应用自带）。
- Node >= 22（插件包
engines要求；运行 DSH Host 时由你的 DSH 环境满足）。
安装与启用¶
普通（非 desktop）配置档可用 CLI 安装：
# into a normal (non-desktop) profile
dsh plugin --profile <profile> add dsh-blend-preview
desktop 配置档由 Electron 应用持有，需在插件管理 UI 中添加，或手动合成配置后重启应用。包内附带 cordis.patch.yml，安装后会自动写入插件行。安装后需重启 DSH。
插件以当前 DSH 进程权限运行；安装前建议在 GitHub 阅读源码与 MIT 许可证，确认本机 Blender 调用与缓存路径符合你的安全策略。
配置项¶
在 Settings → Plugins → Blender preview（命名空间 blend-preview）中调整：
| Key | 默认值 | 含义 |
|---|---|---|
enabled |
true |
是否注册渲染器与转换路由。 |
routePath |
/api/blend-preview |
需认证的转换路由；须位于 /api 下，否则认证围栏失效并回退默认路径。 |
extensions |
["blend"] |
使用 3D 预览的文件后缀。 |
blenderPath |
""（自动） |
blender / blender.exe 的绝对路径。 |
cacheDir |
"" → ~/.dsh/cache/blend-preview |
GLB 与 scene JSON 缓存目录。 |
timeoutMs |
180000 |
单次冷转换的最长等待时间（毫秒）。 |
maxBytes |
1073741824 |
允许转换的最大 .blend 体积（1 GiB）。 |
applyModifiers |
true |
导出时应用 modifier，使预览更接近 Blender 渲染结果。 |
cacheEntries |
24 |
磁盘上保留的缓存转换份数，超出后淘汰最旧项。 |
典型用法¶
- 安装插件并重启 DSH，确认本机 Blender 可被自动发现，或在
blenderPath中填写路径。 - 在工作区文件树中点击某个
.blend。 - 右侧栏首次打开会触发 Host 转换；等待 GLB 与 JSON 就绪后，在视口中旋转、缩放、切换线框或自动旋转，并在场景信息面板查看对象面数与毫米级包围盒。
- 再次打开同一文件版本应直接读缓存；修改并保存
.blend后，因 mtime/大小变化会重新转换。
数据流（与 README 一致）：客户端预览体请求 GET /api/blend-preview?path=…&kind=info 与 kind=glb → Host 查缓存或 spawn blender --background --python lib/scene.py → 写入缓存目录下的 model.glb、scene.json 等。不上传云端：Blender 与 GLB 均留在本机。
适用场景与注意¶
适合：在 DSH 工作区内快速浏览 Blender 资产、核对打印/机械尺寸与面数、避免为看一眼模型频繁切换应用。
限制（以官方 README 为准）：
- 超大场景（数百万三角面）导出慢，可能触及
timeoutMs。 - 视口不显示贴图，仅基色；动画、蒙皮不在导出范围内。
- 冷转换依赖本机 Blender 性能与场景复杂度。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区收录站点，与 DeepSeek / 幻方无官方从属关系。
链接¶
- 目录页：https://www.skillhub.cn/plugins/439436269-ctrl/dsh-blend-preview
- 源码与说明：https://github.com/439436269-ctrl/dsh-blend-preview
当前 npm 版本 0.1.0；若行为与文档不一致，以仓库 README 与 CHANGELOG.md 为准。
