前言¶

用語言模型處理機械、結構類問題時，一個常見的障礙是模型文件本身。OBJ、STL、STEP 這些格式要麼是純幾何數據，要麼是需要 CAD 內核才能離散的 BREP 實體，純語言大模型拿到的往往只是一串它無法理解的字節。以往的做法要麼在本地跑一套 CAD 工具鏈再摘錄結果，要麼乾脆放棄。

dsh-3d-model-viewer 是 DeepSeek Harness（DSH）生態裏的一個插件，思路是把這件事拆成兩步：先在 Web 界面裏把模型直接畫出來給人看，再把同一個模型轉譯成一份標準化、LLM 可讀的 JSON，交給語言模型。下面介紹它的定位、安裝和用法。

這是什麼¶

• 項目：lishLRF/dsh-3d-model-viewer，作者 lishLRF，MIT 許可證。
• 定位：在 DSH Web 界面查看 OBJ/STL/STEP 三維模型，並把模型轉譯成標準 JSON（格式標識爲 dsh-3d-model/v1），讓語言模型無需 CAD 內核也能理解一個零件。
• 支持格式：OBJ、STL、STEP（.step / .stp）。

它符合 DSH「一切皆插件」的形態，一個包包含兩個半邊：

• Host 半邊：註冊 read_3d_model 工具，Agent 可以自己讀取磁盤上的 OBJ/STL 並轉譯爲標準 JSON；同時導出轉譯庫（translateFromBytes / translateObj / translateStl 與 schema）。
• Client 半邊：按 DSH client-module 契約構建的瀏覽器 bundle，在 shell.overlay 註冊懸浮面板，用 three.js 渲染，並通過 sessions scope 觸達對話。

核心功能¶

1、在 DSH Web 界面右側的懸浮面板中展示模型，樣式對齊 DSH 主題。支持旋轉、平移、縮放，可調材質（顏色、金屬度、粗糙度、線框）、光照（環境光 + 主光），並能開啓剖面（裁剪平面）視圖。

2、把受支持的模型轉譯成統一的 dsh-3d-model/v1 JSON，附帶語義分析：表面積、體積、是否 watertight、形狀分類，以及一句自然語言描述（analysis.naturalDescription）。轉譯後大致形如：

{
  "schema": "dsh-3d-model/v1",
  "meta": { "sourceFormat": "stl", "name": "bracket.stl", "units": "mm" },
  "bounds": { "min": [0,0,0], "max": [40,20,10] },
  "summary": { "partCount": 1, "triangleCount": 1024 },
  "analysis": {
    "totalSurfaceArea": 2200.0,
    "totalVolume": 8000.0,
    "watertight": true,
    "naturalDescription": "bracket.stl: 1 part (box), ..."
  },
  "parts": [ { "id": "part-0", "vertices": [ "..." ], "indices": [ "..." ] } ]
}

3、發送到 AI：一鍵把 JSON + 提示詞寫入 DSH 輸入框，隨用戶輸入一同上傳；也可以立即作爲排隊消息發送。JSON 還支持下載和複製。

4、Agent 側：Host 半邊註冊的 read_3d_model 工具覆蓋 OBJ/STL，Agent 可以對某個文件路徑調用它並拿到標準 JSON。

STEP 格式通過瀏覽器端的 occt-import-js（OpenCascade 的 WASM 移植）離散後解析，僅 Web 查看器支持；Host 端的 read_3d_model 工具遇到 STEP 會提示需在 Web 查看器中打開。

安裝與啓用¶

環境要求：Node ≥ 20，pnpm ≥ 10。推薦用預編譯的 Release tgz 一鍵安裝：

dsh plugin --profile web add https://github.com/lishLRF/dsh-3d-model-viewer/releases/download/v0.1.1/dsh-3d-model-viewer-0.1.1.tgz

預編譯包已包含構建產物，裝完無需構建腳本授權。

然後啓動 Web 界面：

dsh web        # 等價於 dsh --profile web

驗證生效有三種方式：

1、Web 界面右上角出現「三維模型查看器」面板。
2、讓 Agent 對某個 .obj / .stl 路徑調用 read_3d_model，應返回標準 JSON，說明 Host 工具已註冊。
3、不啓動也能檢查組合結果：

dsh --profile web --dump-config

輸出中找到 # == dsh-3d-model-viewer 這一層即爲成功。

卸載命令：

dsh plugin --profile web remove dsh-3d-model-viewer

如果從 GitHub 源碼安裝（dsh plugin --profile web add github:lishLRF/dsh-3d-model-viewer），注意兩點：pnpm ≥ 10 會拒絕執行 git 依賴的 prepare 構建腳本，需要把 allowBuilds: dsh-3d-model-viewer: true 寫進 profile 的 pnpm-workspace.yaml 再重跑 add；由於 prepare 會在你機器上執行腳本，建議鎖定 commit 形如 github:lishLRF/dsh-3d-model-viewer#<sha>。

典型用法¶

1、打開一個會話，在「三維模型查看器」面板中點擊「加載模型」或直接拖拽文件（.obj .stl .step .stp）。
2、旋轉、平移、縮放查看，調節材質與光照，需要時開啓剖面視圖。
3、（可選）在「模型描述」文本框裏寫下模型說明，它會寫入標準 JSON 的 meta.description，隨「發送到 AI」一起提供給 LLM，減少誤判。
4、點擊「發送到 AI」把 JSON + 提示詞追加到輸入框，或選擇「立即發送」；也可以「下載 JSON」/「複製 JSON」導出文檔。

想快速驗證，項目內置了三個示例模型，直接在面板里加載即可：

面板的開關可以在「設置 → 插件」的配置頁裏控制，選擇會持久化到瀏覽器。headless/TUI profile 仍然可以使用 read_3d_model 工具，只是沒有查看器面板。

適用場景與注意¶

適合的人：在 DSH 上做智能體、且工作流涉及零件或三維模型文件的開發者——需要讓人先看到模型，再讓 Agent 基於幾何信息（尺寸、體積、是否封閉等）進行討論或推理。

使用前有幾點需要知道：

• 環境要求 Node ≥ 20、pnpm ≥ 10；面板功能依賴 web profile。
• STEP 的 WASM 二進制默認從固定 CDN 加載，無法與打包後的 client.js 同路徑部署。離線部署需要修改 src/client/load.ts 中的 STEP_WASM_URL（或在 bundle 旁託管 .wasm）後重新構建。
• 材質文件（mtllib）只做盡力解析名字和顏色，完整的 MTL 貼圖/BRDF 加載不在 v1 範圍。
• 單位方面，OBJ/STL 默認爲 unknown（格式本身不帶單位），STEP 在存在單位信息時會讀取；模型不自動居中，保留源座標。

另外，插件以當前 dsh 進程的權限運行，read_3d_model 可以讀取磁盤上你指定的文件路徑。安裝任何第三方插件前，建議先檢查其源碼與許可證：本項目爲 MIT，但 occt-import-js 封裝了 OpenCascade（LGPL-2.1 + 例外），OCCT 的 WASM 是獨立動態加載的二進制，細節見倉庫的 LICENSE 與 THIRD_PARTY_NOTICES.md。

結尾¶

dsh-3d-model-viewer 解決的問題很具體：讓人在 DSH Web 界面裏直接看到 OBJ/STL/STEP 模型，同時把同一份幾何轉譯成 dsh-3d-model/v1 這樣的標準 JSON，讓語言模型不依賴 CAD 內核也能拿到尺寸、體積、形狀分類這些可用的信息。如果你的智能體工作流裏常出現三維模型文件，值得一試。

• 社區目錄頁：https://www.skillhub.cn/plugins/lishLRF/dsh-3d-model-viewer
• GitHub 倉庫：https://github.com/lishLRF/dsh-3d-model-viewer

（社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。）