Nth-5620/dsh-crystal-viewer

dsh-crystal-viewer

一个用于 DeepSeek Harness（DSH）的晶体结构可视化窗口。

dsh-crystal-viewer 是一个独立的 DSH 插件，为用户提供一个窗口，可直接在 DeepSeek Harness 内部检查晶体和分子结构。它结合了交互式 3D 结构（使用 3Dmol.js 的修改版构建进行渲染）、Q 峰（电子密度峰）图层，以及一个实时参数面板，显示晶胞、对称性、元素、原子统计、Q 峰统计和精修 R 因子。

它通过 dsh-better-sidebar 的标签页注册 API 以侧边栏 / 底部停靠标签页的形式打开——与 DSH 内置的 Terminal / Browser 标签页完全一样。它还注册了一个文件预览器，因此在文件树中点击 .res / .ins / .cif / .xyz / .mol / .pdb 文件时，会以 3D 方式渲染，而不是显示普通的代码查看器。

这个插件是什么： 一个面向用户的查看器。它自行解析结构文件（晶胞、对称操作、原子、Q 峰、键）来绘制结构并填充面板。它不是晶体学计算引擎——求解 / 精修决策和深度几何分析不在本插件的范围内。

目录

- 为什么需要一个查看器
- 功能导览
- 截图
- 主视图 — 周期性结构 + 完整参数面板
- 显示样式对话框 — Atom 标签页
- 显示样式对话框 — Lattice 标签页与晶胞“Style”（堆积）
- 显示样式对话框 — View 标签页（投影与背景）
- 浅色 ⇄ 深色主题联动
- 周期性 vs. 非周期性结构
- 支持的文件格式
- 快速开始
- 开源署名与致谢
- 兼容性
- 仓库结构
- 许可证

为什么需要一个查看器

人仍然需要看到结构。这个插件就是人们用来查看并做出真正推动结构求解 / 精修工作流决策的窗口：

- 晶胞是否正确，我是否选对了空间群（还是仍然为 P1）？
- R1 / wR2 / GooF 是否已经收敛，还是我需要再进行一轮精修？
- 是否还有大的 Q 峰残留，应该将其指认为原子，还是电子密度图已经“干净”了？
- 配位几何是八面体、平面正方形，还是四面体？
所有这些都是“看一眼”的判断——正是这个查看器的用途。它渲染结构并填充面板，以便一眼就能做出这些判断。

功能导览

一份精简的、面向功能的摘要——下面每一项都会在“截图”部分进一步描述，并配有对应的图片。

3D 渲染

- 交互式 3D 结构查看器（WebGL，无 WASM 依赖）。
- 原子显示样式：None · Line · Stick · Ball and stick · CPK（空间填充） · Polyhedron（配位多面体）。
- 着色：Custom（单一统一颜色） · Color by Element（Jmol 方案） · Color by Group（周期表主族 / 过渡金属金色）。
- 键级开关（当文件带有双键 / 三键时显示它们，例如 SDF / MOL2） · 标记原子开关。
- 精细的数值控件，同时支持输入编辑和 ▲/▼ 步进器：线宽、棒半径、球半径、CPK 缩放。
- 晶格 / 晶胞盒渲染：None · Dashed line · Line · Stick，支持逐轴范围（0..2 = 2×2×2 超胞）、线宽 / 棒半径、轴着色（a·b·c 轴）或自定义颜色，以及轴标签（a / b / c）。
- 视图控件：透视（中心）⇄ 平行（正交）投影、背景（Follow theme / White / Dark gray / Custom:），以及描边边缘效果。
- 正确的鼠标滚轮缩放方向（相对缩放，不会跳回）以及不受限制的适配距离，使透视和平行投影以相同的视觉大小渲染。

晶体学

- 完整的周期对称性展开——该插件会闭合 SYMM 生成元集合（群乘法）并应用 LATT 晶格平移（体心 I / 面心 F / 底心 A、B、C），因此高对称性空间群（例如 MOF Fm-3m、Im-3）会渲染出完整的 1×1×1 晶胞，而不是稀疏的晶胞。该工具可以仅根据生成元 + LATT 推导出完整的一般位置集合（例如 11 行 SYMM + LATT -2 → 24 个一般位置）。
- 晶格“Style”（堆积）模式——对称操作如何应用于显示的原子（仅显示；文件绝不会被修改）：
- In Cell（默认）——应用对称性以填充完整的 1×1×1 晶胞（保留边缘原子）。
- Original——应用对称性但保留原始坐标，这些坐标可能落在晶胞之外。
- No Packing——按文件原样显示原子，不应用任何对称操作。这是在结构解析期间检查真实不对称单元的关键视图。
- Q 峰（电子密度峰）图层——渲染为独立、不成键的模型（黄色点图层），可切换。在结构解析期间直接显示未归属密度的候选。
- 晶胞盒 + 超胞 / 生长——晶胞盒样式、通过 Grow 开关或 Lattice 范围实现的超胞（2×2×2），以及轴标签。

参数面板

一个从解析文件中填充的实时 7 组面板：
1. 来源 — 文件格式 + 名称、结构标题、采集温度。
2. 精修（高亮显示）— R1 · wR2 · GooF、d_max 分辨率、观测 / 总衍射点、完整度、最高差值峰 / 最深空穴（Δρ）。
3. 晶胞 — a / b / c、α / β / γ、体积 V、波长 λ、Z。（仅周期性结构。）
4. 对称性 — 空间群提示、LATT、对称操作数量。（仅周期性结构。）
5. 元素（SFAC） — 元素列表 + UNIT: 化学式计数。
6. 原子 — 原子总数、各元素计数。
7. Q 峰 — 可折叠分组，列出未归属峰的数量以及按高度排名的前 5 个峰（标签、高度，单位为 e/ų、分数坐标），并附 max 摘要。当没有 Q 峰时完全隐藏。

该面板旨在让你一眼就能回答“它是否在收敛 / 我是否应该继续？”。

精致的用户体验

- DSH 原生主题 — 所有颜色均来自 DSH --dsw- 设计令牌，因此面板、显示样式对话框和画布背景会自动跟随宿主环境的浅色 / 深色主题（见下方主题截图）。body[data-ds-dark-theme] 上的 MutationObserver 会在你切换主题时实时重新渲染“跟随主题”背景。
- 智能 UI 适配 — 显示样式对话框仅对周期性结构显示晶格标签页；非周期性（.xyz/.mol/.pdb）结构只显示原子 + 视图标签页，并且面板会省略晶胞 / 对称性。
- 性能门控 — 当面板折叠或处于非活动状态时，该标签页会暂停其订阅 / 轮询。

截图

以下所有截图均取自在 DeepSeek Harness 会话中运行的真实插件——即 DSH UI 中的 crystal-viewer 标签页 / 窗口，与用户实际看到的效果完全一致。演示使用公开的 HKUST-1（Cu-BTC）MOF 和咖啡因分子作为示例。

主视图 — 周期性结构 + 完整参数面板

crystal-viewer 窗口中央显示交互式 3D 结构，右侧显示实时参数面板。这是 HKUST-1 / Cu-BTC（F m -3 m，a ≈ 26.29 Å）。该插件使用 CIF 的对称操作渲染出完整的晶胞——注意所有 Cu 桨轮簇和有机连接体如何填满晶胞，而不是单个不对称单元。晶胞框和轴标签均已绘制。

crystal-viewer 主视图 — HKUST-1 完整晶胞及完整参数面板

显示样式对话框 — 原子标签页

点击显示样式会在左侧滑入一个对话框（因此它永远不会遮挡右侧的参数面板）。原子标签页控制原子和键的绘制方式：

- 显示样式：无 / 线框 / 棍状 / 球棍 / CPK / 多面体。
- 着色：自定义（单一颜色）或按以下方式着色（元素 = Jmol 配色方案，或族 = 元素周期表族）。
- 键级（显示双键 / 三键）和标注原子开关。
- 上下文感知的数值字段（线宽、棍半径、球半径、CPK 缩放），支持输入即编辑以及 ▲/▼ 步进器。

Display Style 对话框 — Atom 选项卡及完整参数面板

切换到 Polyhedron 后，显示内容将替换为配位多面体：框架以细棍（仅键）显示，每个金属中心绘制为一个小球，其第一配位壳显示为半透明多面体，并加上金属到配体的键——例如 HKUST-1 中的 Cu 桨轮中心显示其正方形平面（4 × O）配位。这就是“向我展示配位几何”的视图，让“八面体？正方形平面？四面体？”的判断立刻可见。中心会根据化学特征自动检测（被供体配体包围的金属/低电负性原子），因此它既适用于周期性框架（CIF），也适用于分子配合物（XYZ/PBD）。

Display Style 对话框 — Polyhedron 显示样式

Display Style 对话框 — Lattice 选项卡与晶胞“Style”（堆积）

Lattice 选项卡同时呈现两个重要概念：

- Style — 晶胞堆积模式，即如何将对称操作应用于显示的原子（仅用于显示，绝不修改文件）：
- In Cell — 填充完整的 1×1×1 晶胞（默认；即上方的全对称视图）。
- Original — 应用对称性但保留原始坐标（可能落在晶胞之外）。
- No Packing — 按文件原样显示原子，不应用任何对称操作（真正的不对称单元）。
- Range — 每个方向显示的晶胞数（0..2 → 2×2×2 超胞）。
- Lattice — 晶胞框样式（None / Dashed line / Line / Stick）、线宽/棍半径、轴着色（a·b·c）或自定义颜色，以及轴标签。

Display Style 对话框 — Lattice 选项卡，包含 In Cell 堆积和范围控制

No Packing 模式是结构解析的关键辅助工具。在这里，同一个 HKUST-1 CIF 在几乎空白的晶胞中仅显示单个不对称单元（一个 Cu 桨轮片段）——与上方完整对称堆积的晶胞形成对比。当你需要查看原子的真实分数坐标和连接性，而不受对称等价原子干扰时，这就是你要检查的内容。

Display Style 对话框 — No Packing 显示真正的不对称单元

Display Style 对话框 — View 选项卡（投影与背景）

View 选项卡控制投影和画布背景：

- Projection：Perspective (center) ⇄ Parallel（正交视图）。
- Background：Follow theme（适应宿主浅色/深色模式）、White、Dark gray 或 Custom。
- Rendering：Outline 边缘效果。

Display Style 对话框 — View 选项卡（投影、背景、轮廓）

浅色 ⇄ 深色主题联动
整个插件——参数面板、Display Style 对话框以及 3D 画布背景——都使用 DSH --dsw- 设计令牌，并遵循 harness 主题。此处展示的是同一 HKUST-1 结构，在 harness 切换为 dark 且背景设置为 Follow theme 时的效果：画布背景变为深灰色而非白色，每个面板也同步重新换肤。主题属性上的 MutationObserver 会实时重新渲染背景，因此切换主题会立即更新视图。

深色主题——画布背景和所有面板都跟随 harness 深色模式

周期性 vs. 非周期性结构

插件会根据文件是 周期性 晶体（具有晶胞 + 对称性）还是 非周期性 分子结构进行适配。打开 caffeine 分子（一个 3D 构象）后，差异立刻显现：

- 没有晶胞框，没有晶格，没有轴标签。
- 参数面板省略了 Cell 和 Symmetry 组——只显示 Source、Elements (SFAC) 和 Atoms。
- Display Style 对话框仅显示 Atom 和 View 选项卡；Lattice 选项卡被隐藏（分子没有晶格概念）。

非周期性分子结构（caffeine）——没有晶胞，面板只显示 Source/Elements/Atoms

非周期性 Display Style 对话框——Lattice 选项卡被隐藏

支持的文件格式

| 格式 | 作用 | 说明 |
|--------|------|-------|
| .cif | 晶体学信息文件 | 自研解析器 + 对称性展开后的干净 CIF 重新输出，供 3Dmol 使用。 |
| .ins / .res | SHELX 输入 / 输出 | 自研解析器读取晶胞、对称性、SFAC/UNIT、原子、Q 峰、MOLE 组、各向异性 / riding H；.res 的 REM 块提供 R1 / wR2 / GooF、反射计数和 Δρ。以 3D 显示；README 中未展示此格式的截图。 |
| .xyz | 笛卡尔坐标 | 用于面板的轻量级解析器（非周期性）。 |
| .mol | V2000 molfile | 用于面板的轻量级解析器；原始文本送入 3Dmol（支持键级）。 |
| .pdb | 蛋白质数据库 | 用于面板的轻量级解析器；原始文本送入 3Dmol。 |
| .hkl | 反射数据 | 未解析（3D 显示不需要；R 因子来自 .res / .lst）。 |

.ins / .res（SHELX 读/写）路径完全支持往返：解析结构、在 3D 中查看，并将晶胞、对称性、原子、Q 峰和精修统计信息读回面板。

快速开始

环境要求

- Node.js ≥ 22.18 —— 由 tsdown 0.22.14 要求（使用 Promise.withResolvers）。CI 运行 Node 22。
- DeepSeek Harness (DSH) Web 运行时 —— 该插件是 DSH 外部插件（bundle），由 DSH profile 加载。
- pnpm（corepack 或本地安装）。

构建

pnpm install
pnpm build        # emits lib/index.js (host) + lib/client.js (client)
pnpm typecheck
.npmrc 设置了 auto-install-peers=false，因为 DSH 宿主包（@deepseek-ai/cordis、dsh-better-sidebar、react）是在运行时从 DSH profile 的 hoisted node_modules 中解析的，而不是从 npm registry 解析。

安装到 DSH profile

dsh plugin --profile  add dsh-crystal-viewer
或者，用于本地开发：
dsh web --patch /abs/path/cordis.patch.yml

然后打开 DSH web UI，点击 Crystal 条目（侧边栏 + 菜单 / 底部 dock），并打开一个结构文件——可以通过路径输入框，或点击 Files 树中的 .res/.cif/.xyz 文件。

安装或更新客户端 bundle 后，请对浏览器进行强制刷新（Ctrl+F5）。

开源署名与致谢

本项目站在若干优秀开源项目的肩膀上。我们深深感谢它们的维护者和贡献者——LICENSE 保存了本项目的 MIT 许可证，NOTICE 记录了我们所继承的每一个第三方许可证的完整法律文本。

本插件自身的许可证：MIT

dsh-crystal-viewer 插件本身在 MIT 许可证下发布（见 LICENSE）。在 MIT 条件下，你可以自由使用、复制、修改、合并、发布、分发、再许可和销售它。

3Dmol.js——已渲染且已修改

- 项目： 3Dmol.js——面向 web 的机构级分子可视化。
- 许可证： BSD-3-Clause。
- 作用： 渲染基础（WebGL，无 WASM 依赖）。其 GLViewer 负责添加模型、应用样式、绘制晶胞并处理 CIF。
- 本插件中的修改（以修改/集成构建的形式发布）：
- 自行编写的 SHELX/CIF 对称性扩展（SYMM 生成元的群闭包 + LATT 晶格平移），使高对称空间群的 1×1×1 晶胞被完全填充。
- Q 峰多层渲染（一个单独的模型，禁用了键创建）。
- 鼠标滚轮缩放方向与步长覆盖（相对缩放；方向正确，无回跳），以及未钳制的适配距离，使 Perspective 和 Parallel 投影以相同大小渲染。

GLmol——继承自 3Dmol.js

- 项目： GLmol（GLmol – Molecular Viewer on WebGL/Javascript，v0.47）。
- 版权： 2011–2012，biochem_fan。
- 许可证： 双重许可 MIT / LGPL3。
- 作用： 捆绑在 3Dmol.js 内的基础依赖；其版权和许可证声明保留在 NOTICE 中。

React

- 项目： React 18。
- 许可证： MIT。
- 作用： UI 层（查看器、参数面板、Display Style 对话框）。

dsh-better-sidebar（DSH 插件）

- 项目： DSH-better-sidebar——本插件所接入的 DSH 侧边栏工作台。
- 许可证： MIT。
- 作用： 提供 ctx.betterSidebar 标签页 API；本插件通过它注册其 crystal-viewer 标签页。
- 可选的对等依赖——如果未安装，插件仍会加载，但不会注册任何标签页（优雅降级）。

兼容性

DeepSeek Harness 版本

已针对 DeepSeek Harness (DSH) v0.1.1-rc.2（稳定版，端口 3080）和 v0.1.2-alpha.1（开发者通道，端口 3081）进行验证和开发。该插件在 dsh.plugin.json 中声明 engines.dsh: ">=0.1.0"，面向 DSH dsh-external bundle/plugin 接口。

建议： 运行 DSH 开发者通道 / alpha 配置文件以获取最新的 harness API，或运行稳定的 0.1.1-rc.2 配置文件——两者均受支持。安装/更新后请强制刷新浏览器（Ctrl+F5）。

插件兼容性

- dsh-better-sidebar——标签页入口所必需。该插件通过 ctx.betterSidebar 注册其 crystal-viewer 标签页。已针对 v0.17.1 验证（可选对等依赖；缺失时优雅降级）。
- @deepseek-ai/dsh-client-——DSH 客户端运行时 / locale / UI-slots / conversation / modules 模块由 DSH 配置文件注入（package.json 的 dsh 字段中的客户端 bundle inject 列表）。

已知行为与限制

- Q 峰显示要求结构实际包含 Q 峰（标记为 Q# 的 .res 行）；不含 Q 峰的结构则没有 Q 峰图层。
- 解析是面向显示的（轻量），而非完整的晶体学引擎。深度分析（孪晶、无序占位合并、空间群推导、SQUEEZE、CheckCIF）有意不在此查看器的范围内。
- 我们不维护或重新分发 3Dmol.js 上游；我们附带的是一个修改过的打包构建。参见 LICENSE 及上文的署名部分。

仓库布局

dsh-crystal-viewer/
├── src/
│   ├── index.ts              # host half: /crystal-viewer/api/read route (optional fallback)
│   ├── client/
│   │   ├── index.tsx         # client half: registerTab (entry, same mechanism as Terminal/Browser)
│   │   ├── CrystalViewer.tsx  # 3D canvas (3Dmol): atom model + Q-peak model + Display Style + toolbar
│   │   ├── CrystalEmbed.tsx  # file previewer (clicking a structure file in the Files tree)
│   │   ├── CrystalPanel.tsx  # parameter panel (7 groups, incl. Refinement + Q-peak stats)
│   │   ├── display/          # displayStyle.ts (settings model + math) / render.ts / DisplayStylePanel.tsx
│   │   └── useCrystalModel.ts# path/format → structure → CrystalModel/ViewerModel
│   └── crystal-parse/
│       ├── shelx.ts          # self-written .ins/.res parser (CELL/symmetry/atoms/Q peaks/MOLE)
│       ├── model.ts          # CrystalModel / ViewerModel / QPeak types
│       ├── assemble.ts       # parsed structure → CrystalModel/ViewerModel + formatFromPath
│       ├── cif.ts            # CrystalModel → atomCif/qPeakCif + symmetry expansion (group closure + LATT)
│       ├── cif-parse.ts      # generic .cif parser
│       ├── xyz-parse.ts      # generic .xyz parser
│       ├── mol-parse.ts      # generic .mol (V2000) parser
│       ├── pdb-parse.ts      # 通用 .pdb 解析器
│       ├── parse.ts          # 统一调度（ins/res/cif/xyz/mol/pdb）
│       └── lst.ts            # .lst 精修统计
├── docs/
│   └── assets/               # README 截图
├── LICENSE                   # MIT（本项目）
├── NOTICE                    # 第三方声明（3Dmol.js、GLmol、React、better-sidebar）
├── package.json / dsh.plugin.json / cordis.patch.yml
├── tsconfig.json / tsdown.config.ts
└── README.md

许可证

- 本插件： MIT（见 LICENSE）。
- 导入/修改的项目： 3Dmol.js（BSD-3-Clause）、GLmol（MIT/LGPL3 双许可）、React（MIT）、dsh-better-sidebar（MIT）。

我们深深感谢这些项目的维护者。如果您使用本插件，请同时遵守他们的许可证——完整的第三方文本见 NOTICE。

感谢所有开源维护者，是你们的工作让这一切成为可能。