前言¶
在 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
