前言¶

在 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 中進行結構分析或查看晶體數據的用戶，該插件提供了直觀的視覺支持與參數概覽。