前言¶
在 DSH 裏做空間相關的工作流時，模型文件往往是”看得見目錄、看不見樣子”：一個 .fbx 或 .glb 放在會話工作區裏，除了用外部建模軟件打開，很難快速判斷它長的什麼樣、有沒有動畫、材質對不對。dsh-3d-viewer 想解決的就是這一步：把工作區裏的 3D 模型直接拉到右側邊欄裏預覽，開箱即轉、即縮放、即播放動畫，不需要上傳到任何外部服務。
它的定位是 DSH 客戶端側邊欄插件，維護者是 ybniaobu，託管在 GitHub 和 npm 上，當前 GitHub 星標 1。下面按功能、安裝、用法、限制的順序介紹。
這是什麼¶
一句話：dsh-3d-viewer 是 DeepSeek Harness（DSH）的側邊欄插件，用於從當前會話的工作區預覽 3D 模型，支持 FBX、OBJ、glTF/GLB、STL。
它的關鍵約束是：不上傳、不聯網。模型文件從會話的工作區直接讀取，預覽在本地完成；插件包內自帶四個 HDRI 環境貼圖，由本地 DSH server 的一個只讀路由提供，所以切換環境也不需要訪問網絡。
核心功能¶
- 支持預覽 FBX、OBJ、glTF、GLB、STL 共五類模型。
- 在右側邊欄的文件樹裏點擊模型文件，即在預覽頁籤中打開。
- 提供軌道旋轉、縮放、材質切換、環境切換等交互。
- 支持播放模型內嵌的動畫。
- 運行時不需要網絡：HDRI 走本地 server 的
/dsh-3d-viewer/hdri/路由。 - 外部資源（FBX/glTF 貼圖、glTF 的
.bin、OBJ 的 MTL 與貼圖）從會話工作區讀取。
安裝與啓用¶
插件以 npm 包 dsh-3d-viewer 的形式分發，當前版本 0.1.1。官方推薦從 npm 安裝，也支持從本地目錄安裝。
從 npm 安裝（推薦）¶
1、打開 DSH Desktop，在側邊欄選擇 Plugins。
2、點擊 Add plugin → Install a third-party plugin。
3、輸入 dsh-3d-viewer，或輸入 dsh-3d-viewer@0.1.1 指定版本。
4、將 Registry 設置爲官方 npm registry（國內可用 npmmirror）。
5、點擊 Install，然後在 Installed plugins 下確認 3D Viewer 爲 On。
6、在任意會話中打開模型。如果沒有出現預覽，先刷新頁面；仍不行再重啓 DSH。
更新方式：在 Plugins 下移除舊版本，再安裝更高的新版本。
從本地目錄安裝（可選）¶
適用於離線或內網分發。先把插件目錄解壓到任意位置，目錄內必須包含 package.json、client.js、index.js、cordis.patch.yml 以及 assets/hdri/ 目錄。
1、打開 DSH Desktop，選擇 Plugins。
2、點擊 Add plugin → Install a third-party plugin。
3、輸入目錄的絕對路徑（例如 F:\plugins\dsh-3d-viewer），點擊 Install。
4、在 Installed plugins 下確認 3D Viewer 爲 On。
5、在任意會話中打開模型，若沒有預覽則刷新頁面，仍不行再重啓 DSH。
本地安裝是對目錄的鏈接，不是複製。安裝後不要移動、重命名或刪除該目錄，否則 DSH 下次啓動可能找不到插件。
運行要求¶
- DSH Desktop 0.2.2-rc.1 或更高版本（官方在 0.2.2-rc.1 上構建和測試）。
- 瀏覽器支持 WebGL 2；不支持時預覽會報錯。
- 模型文件需要放在會話工作區中，並能在右側邊欄的 Files 裏訪問到。
典型用法¶
1、打開任意會話，點擊對話區右上角的右側邊欄按鈕。
2、打開側邊欄的 Files（或按 Mod+P）。
3、點擊任意 .fbx、.obj、.gltf、.glb 或 .stl 文件。
4、模型在預覽頁籤中打開。文件較大或第一次切換環境時，可能需要等待幾秒。
該插件通過 dsh 包元數據裏的 client 配置，注入到 DSH 的右側邊欄與文檔預覽兩個位置，因此入口就在右側邊欄，不需要額外命令行參數。
支持的格式與限制¶
FBX：網格、層級、材質、內嵌貼圖、動畫和節點數據。
OBJ：多邊形、o/g 分組、法線、UV、頂點色、線/點圖元，以及 mtllib/MTL 和常見貼圖。
glTF / GLB：動畫、蒙皮、內嵌資源，以及外部 .bin 與貼圖。
STL：ASCII 與二進制 STL；中性雙面 PBR 材質；二進制頂點色會保留。
需要注意的幾點：
- 所有格式：文件內嵌的燈光、相機和音頻都會被移除，預覽使用插件自己的燈光與相機。
- FBX：缺失的外部貼圖會提示警告，但不阻塞幾何體加載。
- OBJ：缺失 MTL 時回退到默認材質；缺失貼圖用白色佔位。
- glTF / GLB：多個圖元共享的資源只會讀取一次。
- STL：沒有材質和動畫。
明確不支持的內容：
- 需要額外解碼器的 glTF 擴展：Draco、Meshopt、KTX2。
- DSH 無法直接解碼的貼圖格式：TGA、DDS、EXR 等（顯示爲白色佔位）。
- MTL 的
map_Ks/map_Ns尚未完整映射到 PBR（Kd/Ks/Ns/d以及漫反射、法線、凹凸、自發光、alpha、位移貼圖已支持）。
代碼結構¶
插件代碼按宿主端（Host）和客戶端（Client）兩側劃分，幾個關鍵路徑：
| 路徑 | 職責 |
|---|---|
index.js |
Host 側：註冊只讀的 /dsh-3d-viewer/hdri/ 路由，提供打包在包內的 HDRI |
src/client.js |
客戶端入口：按格式註冊文檔預覽與側邊欄槽位 |
src/formats.js |
格式註冊表：id、擴展名、標題/徽標鍵、格式歸一化 |
src/ui/ModelViewer.js |
查看器容器：加載/錯誤狀態、格式綁定、場景生命週期 |
src/scene/createSceneView.js |
場景編排：渲染器、相機、控制器、生命週期 |
src/scene/environment.js |
從 Host 路由獲取 HDRI、解碼、構建 PMREM、按 id 緩存 |
src/loaders/model-loader.js |
FBX / OBJ / glTF / GLB / STL 的異步加載與表驅動分發 |
src/vendor/FBXLoaderPbr.js |
自帶的 Three.js FBXLoader，支持金屬度/粗糙度自定義屬性 |
assets/hdri/ |
打包的 HDRI 文件（Poly Haven，CC0），由 Host 路由提供 |
包內 devDependencies 裏的 Three.js 會被預先打包進 client.js，React 則由 DSH 提供，不隨包分發。
適用場景與注意事項¶
適合這類需求：在 DSH 會話裏需要快速查看工作區中的 3D 資產，做格式或材質的初步覈對；不想爲了看一眼模型而切換到外部建模工具，也不想走任何雲端預覽。
兩點需要提前知道：
- 插件以當前 DSH 進程的權限運行，安裝前應檢查源碼與許可證（倉庫內提供
LICENSE和THIRD_PARTY_NOTICES.md，許可證爲 MIT；Three.js 爲 MIT，Poly Haven HDRI 爲 CC0）。 - 只從可信來源安裝插件。
另外，該插件收錄在社區插件目錄 SkillHub 上；社區目錄是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係，不是官方應用商店。
小結¶
dsh-3d-viewer 解決的是”在 DSH 裏快速看一眼 3D 模型”這件小事：從工作區直接讀文件、本地預覽、離線可用。安裝路徑明確（npm 或本地目錄），運行要求也寫清楚了。如果你的工作流涉及 3D 資產，可以先裝上試一下，注意確認源碼來源與許可證。
- 目錄頁：https://www.skillhub.cn/plugins/ybniaobu/dsh-3d-viewer
- GitHub：https://github.com/ybniaobu/dsh-3d-viewer
- npm：https://www.npmjs.com/package/dsh-3d-viewer
