前言¶

在 DeepSeek Harness（DSH）裏和智能體聊 CAD 或網格模型時，常見做法是切到 FreeCAD、MeshLab 等桌面軟件打開 .step、.stl，或在對話裏只看路徑、看不到幾何。DSH 的 Web 客戶端本來側重文本與文檔預覽，工程類 3D 文件沒有統一的內嵌查看入口。

dsh-3d-viewer（維護者 yanzhaohui1999，GitHub 倉庫 yanzhaohui1999/dsh-3d-viewer）是分類爲客戶端的 DSH 插件：在側欄裏用 WebGL 打開 .step / .stp / .stl / .glb / .gltf，STEP 在瀏覽器內用 OpenCASCADE WASM 轉網格，不依賴本機 Python/OCP，也不寫臨時文件。裝了 dsh-better-sidebar 時可在文件樹裏雙擊模型；未裝時降級到 DSH 原生右側欄文檔預覽，同一套渲染器。

下面介紹定位、能力、安裝與日常使用，以及使用時的邊界與許可說明。

這是什麼¶

• 名稱：dsh-3d-viewer（npm 包名與插件標識一致，當前版本 0.1.0，見倉庫 package.json）。
• 一句話：在 DSH Web 側欄註冊 3D 模型預覽器，支持 STEP/STP/STL/GLB/GLTF。
• 運行面：僅 web 客戶端（dsh.client.platform: web，immediately: true）；宿主側 index.js 的 apply() 爲空，邏輯在構建產物 lib/client.js 中。

插件動機在 README 裏寫得很直接：CAD 的 STEP/STL 平時多在 FreeCAD 裏看；在 DSH 裏聊到模型時，若文件能在側欄直接旋轉查看，就不必切窗口、也不必先轉格式。

核心功能¶

支持的格式與解析方式¶

OpenCASCADE 的 wasm 已內聯進 lib/client.js（通過 wasmBinary 傳入），運行時不需要再額外拉取 wasm 文件。

兩條註冊路徑（軟降級）¶

1. 已安裝 dsh-better-sidebar：在其文件樹中雙擊模型文件，經 registerFileViewer 在 3D 視圖中打開。peerDependencies 要求 dsh-better-sidebar >= 0.19.0（optional）；README 建議版本 0.28.x（0.24.1 在 DSH 0.2.1 上可能停在 pending (waiting for service: webRuntime)，該服務在 0.2.1-rc.1 已改名爲 webStartup）。
2. 未安裝 better-sidebar：走 DSH 原生右側欄文檔預覽（documentPreviews + sidebar.right.tab.document），同一渲染器；註冊經 ctx.inject 子 fiber 完成，避免直接讀 documentPreviews 時 Cordis 注入錯誤。

交互與視圖¶

STEP/STL 會套用 CAD 常用的 Z-up → Y-up 旋轉；glTF 規範本身爲 Y-up，插件僅對 STEP/STL 做該旋轉（zUp 標記），避免 GLB 模型朝向錯誤。

WebGL 與界面語言¶

WebGL 上下文丟失（GPU 復位、標籤頁休眠等）時會取消默認行爲，恢復後重建渲染器並重新掛載模型，減輕黑屏卡住。

工具欄、狀態行、插件標題及「空文件 / 不支持 WebGL」等提示支持中英文：有 DSH 的 locale 服務時跟隨宿主語言（設置 → 通用）；否則按瀏覽器語言（zh* 爲中文，其餘英文）。STEP/STL/glTF 解析失敗時的診斷文案目前仍爲中文（README「沒驗證的部分」有說明）。

安裝與啓用¶

插件以本地目錄形式加入 Web profile，安裝命令須在該插件倉庫根目錄執行（不要把下面的 . 換成 GitHub 短名拼接）：

# 在倉庫根目錄執行
dsh plugin --profile web add .

README 記載：該命令會同時寫入 dependencies 和 dsh.profile.bundles（2026-11-03 在 DSH 0.2.1-rc.3 上實測，pnpm add 之後 bundles 會自動出現 dsh-3d-viewer）。也可在 Web 界面「插件」→「添加插件」→ 本地目錄填寫同一路徑。

lib/client.js 已構建並隨倉庫提交，安裝前不需要 npm install 或本地構建；three、occt-import-js、esbuild 僅爲 devDependencies，重裝 profile 時不會帶進運行時。

維護者若需從源碼重建客戶端 bundle：

npm ci
npm run build

典型用法¶

在 DSH 裏打開模型¶

1. 確保 Web profile 已包含本插件；推薦同時安裝 dsh-better-sidebar@0.28.x。
2. 啓動 DSH Web（例如 dsh --profile web 或你的日常 profile）。
3. 在右側欄「文件」樹中找到 .step、.stl 或 .glb 等文件：better-sidebar 路徑下雙擊打開 3D 預覽；原生文檔預覽路徑下按 DSH 文檔預覽方式打開對應擴展名文件。
4. 用鼠標旋轉、縮放、平移；需要時用工具條切換正交視圖或導出截圖。

倉庫自帶 10 mm 立方體樣例：samples/cube-10mm.step、samples/cube-10mm.stl，可用於對照驗收。

倉庫內自檢（可選）¶

維護者或審閱源碼時，可在克隆後的倉庫根目錄做 Node 與無頭瀏覽器驗收（README 已給出命令與期望輸出），例如 STEP 包圍盒校驗：

node scripts/verify-step.mjs

或指定自有文件：

node scripts/verify-step.mjs path/to/your.step

端到端渲染、STL/GLB 煙霧測試等見 README「驗收」一節；無頭 Chrome 路徑可用環境變量 CHROME_PATH 覆蓋默認的 macOS Google Chrome 路徑。

適用場景與注意¶

適合誰¶

• 在 DSH Web 裏處理機械 CAD（STEP/STL）或簡單 glTF/GLB 資源，希望在側欄內完成「看一眼幾何」而非頻繁切桌面軟件的智能體開發者或用戶。
• 已使用或願意安裝 dsh-better-sidebar、習慣在側欄文件樹裏點文件的工作流。

限制與未驗證項（來自 README）¶

• 壓縮 GLB/GLTF：僅驗過未壓縮模型；帶 DRACO / KTX2 的模型會失敗（未接解碼器）。
• 深色畫布：背景寫死 #11161c，不跟隨宿主淺色主題。
• 單位：底部讀數統一標 mm，對 STEP/STL 合理；glTF 規範無單位，數字僅表示模型空間尺寸。
• 原生降級路徑：註冊已在無 better-sidebar 的 profile 測過；但該實例未完整跑過「取字節 + 畫面」的端到端 GUI。
• 其它 DSH 版本：維護者主要在 0.2.1-rc 系列驗證；升級宿主前建議自行試跑。

安全與許可¶

• 插件代碼在 你當前 DSH 進程權限下作爲客戶端 bundle 執行；安裝前應閱讀 GitHub 源碼 與分發許可。本倉庫以 MIT 發佈；隨 lib/client.js 分發的 three.js@0.169.0（MIT）與 occt-import-js@0.0.23 / OpenCASCADE wasm（LGPL-2.1）許可文本在 licenses/ 目錄。社區目錄 SkillHub 插件頁 與 GitHub 爲公開信息來源，與 DeepSeek / 幻方無官方從屬關係；DSH 生態遵循「一切皆插件」，目錄站點爲社區彙總。

結尾¶

dsh-3d-viewer 把工程類 3D 預覽收進 DSH Web 側欄：STEP 靠瀏覽器內 WASM 網格化，STL/GLB 前端直讀，並與 better-sidebar 或原生文檔預覽兩套入口對齊。若你的對話裏經常出現模型路徑，可以在 Web profile 用官方文檔中的 dsh plugin --profile web add . 裝好插件後，直接用側欄打開 samples/cube-10mm.step 試一遍交互。

• 社區目錄：https://www.skillhub.cn/plugins/yanzhaohui1999/dsh-3d-viewer
• 源碼與完整驗收說明：https://github.com/yanzhaohui1999/dsh-3d-viewer