前言¶
在 DeepSeek Harness（DSH）工作區中直接查看 STL 模型，能省去在 Blender 或切片軟件間切換的時間。dsh-preview-stl 插件爲 DSH 增加了一個文檔預覽渲染器，點擊 .stl 文件即可在右側邊欄渲染出交互式 3D 視口，並輸出打印統計信息。
插件定位¶
dsh-preview-stl 是一個客戶端插件，由用戶 439436269-ctrl 維護。它解決的問題是：在本地瀏覽器中解析 STL 網格文件，無需上傳、無需後端轉換、無需額外切片軟件，直接查看模型尺寸、體積、表面積和密封性。
核心功能¶
1. 文檔預覽渲染器¶
插件註冊了一個 .stl 文件的預覽渲染器。在 Workspace 文件列表中點擊 STL 文件，右側邊欄會加載渲染視圖。
2. 瀏覽器端解析¶
STL 文件流經經過身份驗證的 /api/preview/stl 路由，在瀏覽器中完成解析：
- 二進制 STL：80 字節頭部 + uint32 三角形計數 + 每個 50 字節的三角形數據
- ASCII STL：遵循標準語法的 facet normal / outer loop / vertex 格式
文件不會上傳到服務器，也不會在宿主機上轉換。
3. 交互式 WebGL 視口¶
使用與 dsh-preview-blender 相同的依賴-free WebGL 查看器，支持以下操作：
- 軌道旋轉（orbit）
- 平移（pan）
- 滾輪縮放
- 雙擊重置視角
- 線框模式切換
- 自動旋轉
- 接觸陰影
- 三色軸三角架
STL 默認爲 Z-up 座標系，渲染前會旋轉到 Y-up 視口座標系。
4. 打印統計信息¶
插件在解析後報告以下數據：
- 文件格式（二進制 / ASCII + 頭部信息）
- 文件大小
- 三角形數量
- 焊接頂點數量
- 邊界框尺寸（毫米）
- 體積（立方釐米）
- 表面積（平方釐米）
- 密封性：邊界邊、非流形邊、退化面
密封性計算通過在網格上焊接頂點並統計邊使用次數完成。如果三角形數量超過 analysisMaxTriangles（默認 400,000），會跳過密封性檢查以避免卡頓。
5. 單位轉換¶
STL 文件本身是無單位的。插件通過 unitScale 配置項將 STL 單位映射到毫米：
unitScale = 1：假設 STL 單位爲毫米（默認）unitScale = 10：假設 STL 單位爲釐米unitScale = 25.4：假設 STL 單位爲英寸
該配置會影響尺寸、體積和表面積的顯示值。
安裝與啓用¶
插件安裝命令如下：
dsh plugin --profile <profile> add dsh-preview-stl
安裝後，插件會自動註冊渲染器和路由，配置項可在設置 → 插件 → STL preview 中調整。
配置項¶
| 鍵 | 默認值 | 說明 |
|---|---|---|
enabled |
true |
註冊渲染器和路由 |
routePath |
/api/preview/stl |
認證網格路由路徑，必須位於 /api 下 |
extensions |
["stl"] |
觸發 3D 預覽的文件後綴 |
maxBytes |
536870912 |
最大可流式傳輸的 STL 大小（512 MiB） |
chunkBytes |
1048576 |
主機端分塊讀取的字節數 |
unitScale |
1 |
STL 單位到毫米的映射 |
color |
#c7d2e2 |
視口顏色（STL 不攜帶材質） |
analysisMaxTriangles |
400000 |
超過此值跳過密封性檢查 |
適用場景¶
- 在 DSH 中快速瀏覽 STL 模型，檢查幾何完整性
- 獲取模型的打印前統計信息（尺寸、體積、表面積）
- 在無額外軟件的本地環境中查看 3D 模型
注意事項¶
- 插件依賴 DSH 0.2.x 版本（已驗證兼容
0.2.0-rc.2和0.2.1-rc.2） - 需要瀏覽器支持 WebGL（桌面應用默認具備）
- ASCII STL 中超出標準語法的頂點顏色或面屬性不會被解析
- 非常大的模型（數百萬三角形）會在主線程解析，可能需要片刻；密封性檢查會自動跳過
- 插件以當前 DSH 進程權限運行，安裝前建議檢查源碼與許可證（MIT）
生態背景¶
DeepSeek Harness 的設計理念是「一切皆插件」。dsh-preview-stl 是社區維護的插件，通過 DSH 插件目錄分發，與 DeepSeek 或幻方無官方從屬關係。
