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）提供插件信息和提交反饋。