前言¶

用语言模型处理机械、结构类问题时，一个常见的障碍是模型文件本身。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 / 幻方无官方从属关系。）