Introduction¶

When working with spatial workflows in DSH, model files often appear as “visible directories but invisible appearances”: a .fbx or .glb sitting in the session workspace, other than opening it with external modeling software, makes it hard to quickly judge its appearance, whether it has animations, or if the materials are correct. dsh-3d-viewer aims to solve this step: dragging 3D models directly from the workspace into the right sidebar for preview. It works out of the box for rotation, zooming, and playing animations, without needing to upload to any external service.

Its positioning is a DSH client sidebar plugin, maintained by ybniaobu, hosted on GitHub and npm, currently with 1 GitHub star. The following introduces it in the order of features, installation, usage, and limitations.

What is this¶

In one sentence: dsh-3d-viewer is a sidebar plugin for DeepSeek Harness (DSH) to preview 3D models from the current session’s workspace, supporting FBX, OBJ, glTF/GLB, STL.

Its key constraint is: No upload, no internet. Model files are read directly from the session workspace, and previewing is done locally; the plugin package includes four HDRI environment maps provided by a read-only route of the local DSH server, so switching environments also requires no network access.

Core Features¶

• Support previewing FBX, OBJ, glTF, GLB, STL (5 categories).
• Clicking a model file in the file tree of the right sidebar opens it in the preview tab.
• Provide interactions such as orbit rotation, zooming, material switching, and environment switching.
• Support playing embedded animations in models.
• No network required at runtime: HDRI uses the local server’s /dsh-3d-viewer/hdri/ route.
• External resources (FBX/glTF textures, glTF .bin, OBJ’s MTL and textures) are read from the session workspace.

Installation and Enabling¶

The plugin is distributed as the npm package dsh-3d-viewer, current version 0.1.1. The official recommendation is to install from npm, but installation from a local directory is also supported.

Install from npm (Recommended)¶

1. Open DSH Desktop and select Plugins in the sidebar.
2. Click Add plugin → Install a third-party plugin.
3. Enter dsh-3d-viewer, or enter dsh-3d-viewer@0.1.1 to specify a version.
4. Set Registry to the official npm registry (npmmirror is available in China).
5. Click Install, then confirm that 3D Viewer is On under Installed plugins.
6. Open a model in any session. If the preview does not appear, refresh the page first; if it still doesn’t work, restart DSH.

Update method: Remove the old version under Plugins and install a newer version.

Install from local directory (Optional)¶

Suitable for offline or intranet distribution. First, unzip the plugin directory to any location; the directory must contain package.json, client.js, index.js, cordis.patch.yml, and the assets/hdri/ directory.

1. Open DSH Desktop and select Plugins.
2. Click Add plugin → Install a third-party plugin.
3. Enter the absolute path to the directory (e.g., F:\plugins\dsh-3d-viewer) and click Install.
4. Confirm that 3D Viewer is On under Installed plugins.
5. Open a model in any session; if there is no preview, refresh the page; if it still doesn’t work, restart DSH.

Local installation is a link to the directory, not a copy. Do not move, rename, or delete the directory after installation, otherwise DSH might fail to find the plugin on its next start.

Runtime Requirements¶

• DSH Desktop 0.2.2-rc.1 or higher (official builds and tests are on 0.2.2-rc.1).
• Browser supports WebGL 2; the preview will error if not supported.
• Model files must be placed in the session workspace and accessible in the Files tab of the right sidebar.

Typical Usage¶

1. Open any session and click the right sidebar button in the top right of the chat area.
2. Open the sidebar’s Files (or press Mod+P).
3. Click any .fbx, .obj, .gltf, .glb, or .stl file.
4. The model opens in the preview tab. If the file is large or switching environments for the first time, you may need to wait a few seconds.

The plugin is injected into DSH’s right sidebar and document preview positions via the client configuration in the dsh package metadata, so the entry point is the right sidebar, no extra command-line arguments are needed.

Supported Formats and Limitations¶

FBX: Meshes, hierarchies, materials, embedded textures, animations, and node data.

OBJ: Polygons, o/g groups, normals, UV, vertex colors, line/point primitives, as well as mtllib/MTL and common textures.

glTF/GLB: Animations, skinning, embedded resources, and external .bin and textures.

STL: ASCII and binary STL; neutral two-sided PBR materials; binary vertex colors are preserved.

Points to note:

• All formats: Embedded lights, cameras, and audio in files will be removed; the preview uses the plugin’s own lights and camera.
• FBX: Missing external textures will show a warning but will not block geometry loading.
• OBJ: Falls back to default material if MTL is missing; uses white placeholder if textures are missing.
• glTF/GLB: Resources shared by multiple primitives are only read once.
• STL: No materials and no animations.

Explicitly unsupported content:

• glTF extensions requiring extra decoders: Draco, Meshopt, KTX2.
• Texture formats DSH cannot decode directly: TGA, DDS, EXR, etc. (displayed as white placeholders).
• MTL’s map_Ks / map_Ns are not yet fully mapped to PBR (Kd/Ks/Ns/d as well as diffuse, normal, bump, emissive, alpha, displacement maps are supported).

Code Structure¶

The plugin code is divided into the Host side and Client side, with a few key paths:

Three.js in the package’s devDependencies is pre-bundled into client.js; React is provided by DSH and is not distributed with the package.

Applicable Scenarios and Precautions¶

Suitable for needs where you need to quickly check 3D assets in the workspace within a DSH session for initial format or material verification; you don’t want to switch to external modeling tools just to look at a model, and you don’t want to use any cloud preview.

Two points to know in advance:

• The plugin runs with the permissions of the current DSH process. Before installing, check the source code and license (LICENSE and THIRD_PARTY_NOTICES.md are provided in the repo; license is MIT; Three.js is MIT; Poly Haven HDRI is CC0).
• Only install plugins from trusted sources.

Additionally, this plugin is listed in the community plugin directory SkillHub; the community directory is an independent site with no official affiliation with DeepSeek or Huafang, and is not an official app store.

Summary¶

dsh-3d-viewer solves the small task of “quickly glancing at a 3D model in DSH”: reading files directly from the workspace, local preview, offline availability. The installation path is clear (npm or local directory), and runtime requirements are clearly stated. If your workflow involves 3D assets, you can try installing it first, making sure to verify the source code and license.

• Directory page: 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