前言¶

在 DeepSeek Harness（DSH）裏做智能體或前端實驗時，工作區裏常會堆着 .glb、.fbx 或手寫 three.js 的 HTML 頁面。傳統做法是另開 Blender、在線查看器，或單獨寫 Node 腳本做格式轉換；運行時拼出來的 THREE.Scene 更難直接落成可分享的模型文件。下面介紹的插件把預覽、格式互轉和「場景 → 模型文件」放進右側欄，並給 Agent 提供同名語義的 three_export 工具。

這是什麼¶

dsh-3d-model-studio（維護者 act27）是 DSH 客戶端類 bundle 插件，當前資料中的版本爲 0.3.1，許可證 MIT。它是 three-export-kit 的 DSH 插件化版本：在右側欄預覽常見 3D 格式，並把 three.js 場景解析導出爲 GLB / glTF / FBX / OBJ / STL / PLY，支持整場景一次導出和按個體分組導出兩種粒度。既可打開已有模型文件，也可加載運行時構建的場景（HTML 頁面或粘貼代碼）。

• 目錄頁：https://www.skillhub.cn/plugins/act27/dsh-3d-model-studio
• 源碼與說明：https://github.com/act27/dsh-3d-model-studio

社區目錄站點與 DeepSeek / 幻方無官方從屬關係；安裝前建議自行查看倉庫源碼與許可證。插件以當前 DSH 進程權限運行，加載本地 HTML 時 iframe 內腳本與 GUI 同源，只應對信任的頁面使用場景導出能力。

核心功能¶

右側欄預覽與工具欄導出¶

在右側欄「文件」頁打開模型，支持 .glb、.gltf、.stl、.ply、.obj、.fbx。資料說明包含 PBR 材質、15 個貼圖槽位、多剪輯動畫與自適應取景。預覽窗口底部工具欄提供重置視角、自動旋轉、線框、貼圖、法線、地面網格、動畫切換，以及導出。

點「導出」可選 GLB、glTF、FBX、OBJ、STL、PLY。導出的是當前已加載的場景（貼圖、動畫一併保留）。落盤時優先由宿主寫到模型同目錄（<名字>.<新後綴>，同名自動 -1）；宿主通道不可用或禁用寫盤時改爲瀏覽器下載。導出前會臨時還原視口（貼圖全開、線框關閉、動畫回第 0 幀），導出後恢復你的查看狀態。

場景導出頁（HTML / 粘貼 three.js 代碼）¶

右側欄「場景導出」頁面向「代碼運行時拼出來的場景」：把 HTML 頁面或粘貼的 three.js 代碼渲染出來，再導出爲上述模型格式。

HTML 文件模式簡要步驟：

1. 選擇工作區內的 .html/.htm，或在輸入框填相對會話工作目錄或絕對路徑，點「加載並渲染」。
2. 工具用同源 iframe 執行頁面腳本，掃描 window 上可達的 THREE.Scene（頁面需暴露 scene，例如 window.scene = scene 或 window.__town = { scene }）。
3. 左下角顯示網格 / 三角面 / 材質統計；底部選格式導出，默認寫到 HTML 同目錄。
4. GLB/glTF 可選「按不透明導出」開關（默認開），用於緩解透明材質深度排序導致的遮擋問題；FBX/OBJ/STL/PLY 不受該開關影響。
5. 「拆分預覽…」進入分組導出：按連通性與包圍盒拆成獨立個體，縮略圖勾選後每個個體一個文件，寫入源文件同目錄下的 split-export/（如 object-001.glb）。資料中的 voxel-town 實測：139 網格 / 48,912 三角面 → 88 個個體。

three.js 代碼模式：粘貼代碼（使用注入的 THREE，勿 import；場景變量須名爲 scene），點「渲染代碼」後使用相同導出與拆分流程；代碼模式默認輸出到工作區根目錄的 scene-export.<後綴>。

導出前會移除燈光、霧、背景；跨 three 實例的場景會在導出前歸一化到插件引擎，避免 buffer 類型不匹配。導出字節經 /api/dsh-3d-model-studio/export 落盤；瀏覽 HTML 走 /api/dsh-3d-model-studio/browse，/scene 與 /browse 在 owner 鑑權之後，僅本機 GUI 會話可調用。

Agent 工具 three_export¶

在工作區按路徑轉換模型，或用 inspect 只讀統計，參數語義與 UI 導出一致：

示例（來自 README）：

// 轉 FBX 給 Blender
{ "input": "assets/robot.glb" }

// 轉 GLB 並限制貼圖 2048
{ "input": "assets/robot.fbx", "format": "glb", "maxTextureSize": 2048 }

// 只看模型規模
{ "action": "inspect", "input": "assets/robot.glb" }

Agent 側走獨立 Node 轉換管線，與瀏覽器內預覽導出共用同一套導出語義。

安裝與啓用¶

本包是標準 DSH bundle（package.json 含 dsh.bundle.patch）。要求 DSH >= 0.2.2-rc.1、Node >= 20。發佈後可從 npm 包名安裝：

# 在 DSH 插件頁「添加插件」輸入包名，或：
#   plugin_manager action=install_bundle target="dsh-3d-model-studio"
# CLI：
#   dsh plugin --profile desktop add dsh-3d-model-studio

也可從 Git 倉庫安裝：

#   plugin_manager action=install_bundle target="https://github.com/act27/dsh-3d-model-studio"

本地開發或離線安裝需先打 tarball，再由 DSH 安裝（不要用目錄 link 安裝，資料說明 link 可能導致依賴未安裝或刪除 bundle 時誤傷源碼目錄）：

# 1) 打 tarball（會先在本目錄安裝運行時依賴）
pwsh -NoProfile -File .\scripts\install.ps1
# 產物：dist\dsh-3d-model-studio-0.3.1.tgz

# 2) 在 DSH 裏安裝（target 用本目錄下 tarball 的絕對路徑）
#   plugin_manager action=install_bundle target="<本目錄>\dist\dsh-3d-model-studio-0.3.1.tgz"

裝完 profile 資料中約 74 MB（含 three 與可選 @napi-rs/canvas）。修改源碼後需重新執行 scripts/install.ps1 與 install_bundle 並重啓 DSH；Host 半代碼不隨 HMR 自動生效，可按提示重啓或禁用/啓用 bundle 強制重載。

典型用法¶

預覽並轉換工作區模型：在「文件」頁打開 assets/robot.glb，用工具欄導出爲 FBX，或在對話中讓 Agent 調用 three_export，input 填 assets/robot.glb。

從 voxel-town 類 HTML 導出 GLB：在「場景導出」選 voxel-town.html，加載後點 GLB；需要進 Blender 逐個編輯時走「拆分預覽…」，勾選個體導出到 split-export/。

無 GUI 時復現場景：資料提到可用 Node 腳本重建場景後導出，需與頁面一致的場景構造與固定隨機種子；可參考倉庫示例中的 scripts/export-model.mjs（node scripts/export-model.mjs --all）。

適用場景與注意¶

適合在 DSH 會話內快速查看模型、在 glTF/FBX/OBJ/STL/PLY 之間轉換，以及把程序化 three.js 場景固化成文件供下游 DCC 或引擎使用。分組導出面向合併大網格或大量 Group 組成的場景，自動跳過地形與零碎裝飾，主體建築、角色、道具類對象更易單獨勾選。

注意：場景導出執行的是你提供的 HTML/代碼，等價於在本機以 GUI 權限運行頁面腳本；ShaderMaterial 無法直接進 glTF，導出前會替換爲可導出的標準材質。無 GUI 的 Node 路徑需自行補齊 three 在 Node 下的環境依賴（README 中說明了 FileReader、requestAnimationFrame 等要點）。

結尾¶

dsh-3d-model-studio 把 3D 預覽、多格式導出和 three.js 場景解析收進 DSH 右側欄，並用 three_export 讓智能體在同一語義下批處理工作區模型。需要功能細節、截圖與 Agent 返回字段時，以倉庫 README 爲準。

• 社區目錄：https://www.skillhub.cn/plugins/act27/dsh-3d-model-studio
• GitHub：https://github.com/act27/dsh-3d-model-studio