dsh-molecule-visualization: Render 3D Molecular Structures in DeepSeek Harness Sessions

What Does It Do?

It is a DSH plugin for DeepSeek Harness that turns molecular files into an interactive 3D viewer rendered right inside the conversation. It solves the problem of structures being readable only as text and of failed renders leaving a blank canvas: you pass a file path or structure data and get a rotatable, zoomable model, with a concrete reason shown whenever something goes wrong. Its core capabilities cover multi-format parsing, ball-and-stick styling, PDB column validation with automatic repair, and timeout protection when the container is not visible.

Core Features

• Six input formats: PDB, SDF, MOL, MOL2, XYZ and Gaussian input files (geometry only); MOL is routed through the SDF parser so real molfiles are not misdetected and rendered with zero atoms.
• Visible failures: parse errors, zero atoms, unavailable WebGL and invisible containers each get their own message, with a specific cause, a suggested fix and a retry button on the card, plus an atom-count cross-check after rendering.
• Ball-and-stick style: alongside stick, line, sphere and cartoon, a ball-and-stick representation combines thin sticks with scaled spheres, switchable live together with background color and coloring.
• PDB column validation and repair: coordinates and record names are checked column by column and reported as a specific line and column; a file-wide altLoc column shift is repaired automatically with a warning.
• Path-first loading: pass a file path and the server reads it, with automatic conversion between Windows, WSL and home-directory paths so you never paste raw structure data.
• Offline and recoverable: 3Dmol.js is bundled locally into the client with no CDN request at runtime, and the payload is persisted with the tool result so viewers survive a restart.

How to Use This Plugin?

After enabling it in DSH, just describe what you want in natural language and the model calls the molecule viewer for you, for example asking it to visualize a local PDB file path. The rendered card supports mouse rotation and zoom, and lets you switch between ball-and-stick, stick, line, sphere and cartoon styles and coloring. If the card reports a failure, fix the file or container state as suggested and press retry; when the container is collapsed or hidden, the viewer reports an invisible container after about ten seconds instead of loading forever. The plugin is maintained by Kanade-Tachibana-Methyl, rewritten from an upstream MIT project and evolving independently, and written in TypeScript.

How to Troubleshoot This Plugin?

• The card reports zero atoms parsed: this usually means the format and parser do not match, so check that the extension matches the actual content, and note that MOL files are parsed as SDF.
• The card reports shifted PDB columns or non-numeric coordinates: inspect the fixed-column layout at the reported line and column; a file-wide altLoc pseudo-marker is repaired automatically with a warning.
• The viewer stays on loading forever: the viewer container is typically collapsed or hidden (display:none or zero size), so expand it and retry.
• The card reports WebGL unavailable: the current environment lacks usable graphics rendering, so open it in an environment that supports WebGL.