前言¶

在 DeepSeek Harness (DSH) 的开发与使用中，涉及结构分析的任务通常需要处理 .cif、.res 或 .xyz 等文件。仅通过文本查看器阅读原子坐标往往难以直观判断晶胞对称性、配位几何或电子密度峰。dsh-crystal-viewer 为 DSH 提供了一个原生的 3D 结构可视化窗口，旨在解决这一痛点，让用户在 DSH 界面内直接进行结构检查。

插件介绍¶

这是一个独立的 DSH 插件，为人类用户提供了一个在 DeepSeek Harness 内部检查晶体和分子结构的窗口。它结合了一个交互式 3D 结构渲染器（基于 WebGL，无 WASM 依赖）、一个 Q-peak（电子密度峰）层以及一个实时参数面板。插件通过 dsh-better-sidebar API 注册为侧边栏或底部停靠选项卡，并注册了文件预览器，以便在文件树中点击文件时直接渲染 3D 视图。

核心功能¶

该插件提供了以下能力：

1. 3D 渲染与显示

   • 交互式查看器：支持鼠标操作，使用 WebGL 渲染。
   • 原子样式：支持 None、Line、Stick、Ball and stick、CPK（空间填充）、Polyhedron（配位多面体）等显示模式。
   • 颜色与标注：支持自定义颜色、按元素着色、按族着色；支持键序显示切换和原子标签切换。
   • 晶胞控制：支持晶胞/单位晶格框渲染（None、Dashed、Line、Stick），以及视角控制（Perspective/Parallel 投影、背景色、轮廓）。

2. 晶体学特性

   • Q-peak 图层：显示未分配的电子密度峰，作为独立模型渲染。
   • 对称性扩展：基于文件的 SYMM 生成器和 LATT 晶格参数，正确处理高对称性空间群的周期性扩展。

3. 实时参数面板

   • 插件自动解析文件，实时展示参数，包括：源文件信息、精修参数（R1、wR2、GooF 等）、晶胞参数、对称性、元素统计、原子统计及 Q-peak 列表。

4. 文件集成与主题

   • 文件预览：注册为文件预览器，支持 .res、.ins、.cif、.xyz、.mol、.pdb 格式。
   • 主题支持：遵循 DSH --dsw-* 设计令牌，自动适配 DSH 的亮/暗主题。

安装与启用¶

根据提供的资料，未列出具体的安装命令。用户需通过项目目录页或 GitHub 仓库获取插件。

典型用法¶

在 DSH 界面中，用户可以直接点击文件树中的结构文件（如 .cif、.pdb 等），插件会自动在侧边栏或底部停靠选项卡中打开晶体视图。或者，开发者可以通过 dsh-better-sidebar API 的选项卡注册机制手动调用该窗口。

适用场景与注意¶

• 定位：这是一个面向人类的“查看器”，不具备晶体学计算功能（如结构求解和精修），仅用于可视化与参数查看。
• 权限：插件在当前 DSH 进程权限下运行。
• 安全：安装前应检查源码与许可证（MIT）。

总结¶

对于需要在 DSH 中进行结构分析或查看晶体数据的用户，该插件提供了直观的视觉支持与参数概览。