前言¶
做蛋白质结构或分子对接的人，看结构的路径通常是这样的：模型帮你算了结果，然后你把 PDB 文件另存下来，切到 PyMOL 或者某个网页工具打开，再截图贴回讨论。文件在会话和外部软件之间来回倒手，切一次环境，断一次思路。
在 DSH（DeepSeek Harness）里，让模型读到一个分子文件不难，难的是让结构本身出现在会话界面里。dsh-molecule-viewer 这个插件解决的就是这一步：传入文件路径或分子数据，会话里直接渲染一个可以旋转、缩放、切换样式的 3D 分子查看器。
这是什么¶
dsh-molecule-viewer 是 DSH 的分子结构查看器插件，由 PandaAIDD 维护，MIT 许可证，npm 包名为 @dsh-plugins/dsh-molecule-viewer，当前版本 0.2.0。
它的定位一句话可以说清：传入分子文件路径或 PDB/SDF/MOL2/MOL 格式数据，在会话界面渲染交互式 3D 分子查看器，渲染能力来自 3Dmol.js。DSH 的理念是「一切皆插件」，这类客户端插件就是这一理念下的产物——不给核心加功能，需要时自己装。
核心功能¶
四种分子格式¶
支持 PDB、SDF、MOL2、MOL 四种格式。其中 PDB 支持 .pdb 和 .ent 扩展名，SDF 支持 .sdf 和 .sd。PDB 对应蛋白质、大分子一类结构，SDF 可以装多个分子。
注意 SMILES 暂不支持，插件需要的是含 3D 坐标的格式。
路径优先，服务端读取¶
可以直接把文件路径传给工具，由服务端读取，不用先把文件内容贴出来。路径写法上做了兼容：Windows 写法（D:\dir\x.pdb）、WSL 写法（/mnt/d/dir/x.pdb）和 ~/ 开头的写法都能自动识别互转，按你本来的习惯写就行。
交互式查看器¶
渲染出来的查看器支持旋转、缩放，可以实时切换 cartoon / stick / line / sphere 四种样式，也能改背景色和分子着色方式。默认样式是 stick，看蛋白质建议用 cartoon。
重启可恢复¶
查看器载荷会随 tool/result 事件持久化。也就是说重启 DSH 之后再加载历史会话，之前的分子查看器照常渲染，不需要重新调用工具。这一点依赖官方插槽实现，原版 harness 即可直接安装，不需要改核心。
轻量解析与本地打包的 3Dmol.js¶
Host 侧只做原子计数和校验，真正的解析和渲染交给浏览器端的 3Dmol.js。3Dmol.js 以 vendor/3Dmol-min.cjs（2.4.2）的形式在构建时打进 client bundle，运行时不请求 CDN，加载快、可以离线，也不受浏览器跟踪防护的影响。
安装与启用¶
用官方给出的安装命令：
dsh plugin --profile web add git+https://github.com/PandaAIDD/dsh-molecule-viewer.git
安装后需要重启生效：
dsh --profile web
重启完成后，view_molecule 工具自动可用，模型会按工具描述自动调用，不需要额外注册或配置。安装过程中，dsh plugin 会克隆仓库、安装到 profile 的 node_modules，并检测到 dsh.bundle.patch 声明后自动加入 dsh.profile.bundles。
典型用法¶
最直接的方式是在对话中描述需求，模型会自动调用工具：
帮我可视化这个分子：D:\project\Dock\data\3IPQ.pdb
也可以明确指定用哪个工具，比如直接粘贴一段没有落盘的 SDF 数据：
用 view_molecule 工具查看这段 SDF 数据：...
工具的参数规则如下：
1、path 与 data 二选一，path 优先。磁盘上有文件就传路径，按用户原始写法传即可；data 用于磁盘上没有文件的情况（如聊天中粘贴的内容），传纯文本，不要 base64 编码。
2、format（pdb | sdf | mol2 | mol）在传 data 时必填；传 path 时按扩展名自动推断，可以省略。
3、name 为显示名称（如 "1CRN"），作为查看器标题，可选。
4、style 为初始渲染样式（stick | line | sphere | cartoon），默认 stick，看蛋白质建议 cartoon。
一个补充说明：超过 2 MB 的分子内容不会内联进会话日志，此时查看器位置会显示一张摘要卡片，原子数和格式仍然可见。
适用场景与注意¶
这个插件适合在 DSH 里做结构相关工作的开发者：跑完对接想立刻看构象、读 PDB 想确认活性口袋、或者拿到 SDF 想快速核对分子形状，都可以在会话里直接完成，不用切到外部软件。
几点注意：
1、SMILES 暂不支持，需要含 3D 坐标的格式。
2、安装后必须重启 DSH 才生效。
3、路径写法虽已做 Windows/WSL 互转，但传 data 时记得同时指定 format。
4、这类插件以当前 dsh 进程的权限运行，安装前建议先到仓库检查源码与许可证，确认无误再装。
结尾¶
dsh-molecule-viewer 做的事情不复杂：把 3Dmol.js 的渲染能力接进 DSH 会话，让「算完就看」变成一个不需要切换工具的动作。路径直传、重启可恢复、离线可用这些设计，让它适合作为结构相关工作流的常驻插件。
插件在社区目录的页面：https://www.skillhub.cn/plugins/PandaAIDD/dsh-molecule-viewer 。目录是独立站点，与 DeepSeek、幻方没有官方从属关系。源码仓库：https://github.com/PandaAIDD/dsh-molecule-viewer 。
