VASP 结果面板 vasptiger/vasp-scope

vasp-scope

在浏览器里看你集群上的 VASP 计算结果。 一个本地小服务 + 一个单文件网页面板，数据全靠 系统 ssh 实时读远端文件 —— 不写远端、不上传、只监听 127.0.0.1。

一次 ssh 取回：收敛曲线 · 能带(带高对称点) · PDOS(自旋/分元素) · NEB 能垒 · 3D 结构 · 文件与图片 · AIMD(MSD/RDF)，每一页都能单独导出 PNG / CSV。

English: vasp-scope is a local web dashboard for inspecting VASP calculation results over SSH — band structure (with high-symmetry labels), PDOS, convergence, NEB barriers, 3D structures, files/images and AIMD (MSD/RDF). Zero upload, read-only, loopback-only. Also ships as a DeepSeek Harness sidebar plugin.

文档速览

- 30 秒上手
- 为什么用它 / 什么情况下别用它（先看这两节更省时间）
- 它能显示什么
- 两种形态 · 安装 · 配置
- 自检与测试 · 常见问题
- 安全模型 · 未做与计划 · 许可

30 秒上手

前置：Node.js 18+，以及一个能免密登录的 ssh 账号（配置见 FAQ）。

1) 先确认免密 ssh 通了 ssh you@your-cluster "echo ok"

2) 配置：只填两项
cd standalone
cp config.example.json config.json
"sshHost": "mycluster" ← 或 user@host
"roots": ["/home/you/projects"] ← 允许读取的目录白名单

3) 启动
node server.js # Windows 也可以直接双击 start.bat
浏览器打开 http://127.0.0.1:8787/

自检：node smoke-test.mjs —— 逐条报告面板、/ping、/diag、/scan、/list 是否正常。

为什么用它

- 一次 ssh 取全部：宿主半边用一条远端脚本（shell + awk）把能带、高对称点、PDOS、能垒一次性压成紧凑文本，而不是逐个文件拉取 —— 在慢速跨网链路上差别很大。
- 口径都摆在明面上：能带横轴怎么排、PDOS 的正负怎么画、能垒横轴按哪种口径算 ——面板会标出来，不用你去猜它默认用了哪一种。
- 面板是单文件：public/panel.html 一个文件、零外部依赖、无构建步骤 —— 想改就改，改完刷新即见效。
- 不碰你的数据：只读、只监听本机、无遥测；远端文件一个字节都不写（见 SECURITY.md）。
- 两种用法同一套代码：不想装 DSH 就用独立版；已经在用 DeepSeek Harness 就装成侧栏插件。

什么情况下别用它

- 你要的是分析而不是查看：算有效质量、投影能带积分、扩散系数的统计与拟合 —— 那是 py4vasp / pymatgen / sumo 的活。
vasp-scope 只做"看得清、导得出"，不做二次计算。
- 数据就在本地磁盘：直接看文件或用本地可视化工具更合适，为本地目录跑一层 ssh 是绕远路。
- 需要多人协作 / 权限分级：它没有账号体系，只有"本机 127.0.0.1 + 可选 token"。

它能显示什么

| 页签 | 你在面板上能看到什么 |
| 收敛曲线 | 离子步能量与最大力；电子步 \|ΔE\| 与 rms（可切双对数）；按离子步切换；科学计数法 |
| 能带 | 能带曲线（多段自动连成一条）；高对称点字母标签；自旋 ↑/↓ 分栏 |
| PDOS | 分元素开关；自旋镜像；总态密度曲线；s / p / d 三通道；强度轴刻度 |
| 能垒 | 能量曲线与能垒；多个文件并列对比；X 轴口径可切换、可反转；任务完成状态标记 |
| 3D 结构 | 可旋转的晶胞：球 / 空间填充 / 多面体；VESTA 配色；晶轴视角；成键判据可切换 |
| 文件 | 目录树（默认收起）；文本阅读（长文件分块，不卡界面）；图片预览（png/jpg/gif/webp/bmp/svg） |
| AIMD | MSD 曲线（时间窗口可调、过原点选项、扩散系数）；RDF 多元素对 |

全局：嵌套任务树 / 表格 + 搜索、任务状态五态判定、计算类型判定（单点 / 结构优化 / AIMD / NEB …）、 逐项导出（7 类 PNG + 6 类 CSV + 全量 JSON）、多根目录下拉与每根独立扫描深度。

它读的是这些 VASP 输出（放在任务目录里即可自动识别）：OUTCAR · OSZICAR · CONTCAR/POSCAR · BAND.dat · KLABELS · KPOINTS · DOSCAR/TDOS.dat · PDOS_/IPDOS_ · 能垒的 .dat 或 image 目录 · AIMD 的 XDATCAR/MSD.dat/RDF.dat/DIFFUSION_COEFFICIENT.dat。

两种形态，一个代码库

| | 独立版 standalone/ | DSH 插件版 dsh-plugin/ |
| 依赖 | Node + 系统 ssh | DeepSeek Harness |
| 面板位置 | 浏览器标签页 | DSH 侧栏标签页 |
| 改代码生效 | 重启该服务（秒级） | 改宿主代码需重启 DSH |
| 适合 | 绝大多数人 | 已经在用 DSH 的人 |

插件安装见 dsh-plugin/INSTALL.md。仓库 topic 带 dsh-plugin，便于插件市场发现。

安装

独立版（Windows / macOS / Linux）

git clone https://github.com/<you>/vasp-scope
cd vasp-scope/standalone
cp config.example.json config.json # 填 sshHost 与 roots
node server.js # Windows: 双击 start.bat

需要 Node.js 18+（<https://nodejs.org/>）；ssh 用系统自带的（Windows 10/11 在「设置 → 应用 → 可选功能」里装 OpenSSH 客户端）。

DSH 插件版

放进 DSH profile 的插件目录，或在 profile 里 npm install <本仓库>/dsh-plugin 然后在 设置 → 插件 里启用，并重启 DSH（宿主半边是 ESM 模块，必须重启）

细节（含 PANEL_PATH 要指到你自己的面板文件）见 dsh-plugin/INSTALL.md。

配置

{
"sshHost": "mycluster", // user@host，或 ~/.ssh/config 里的别名（推荐）
"roots": ["/home/you/projects"], // 白名单：面板只能读这些目录之下
"defaultScanRoot": "/home/you/projects", // 点「刷新」默认扫哪个 "maxDepth": 8, // 扫描深度 1–16（VASP 常有 nf/nf/nf 尾链） "maxReadBytes": 524288, // 单次读取上限 "maxImageBytes": 6291456, // 图片预览上限 6 MB "token": "" // 留空 = 不鉴权（服务只监听 127.0.0.1） }

命令行临时覆盖：node server.js --port 9000 --config D:\path\config.json

自检与测试

node standalone/smoke-test.mjs # 端到端连通性自检（面板 HTML + 5 条路由）
node --test dsh-plugin/test/host.test.mjs # 宿主半边单测（路由注册等）
node --test dsh-plugin/test/client.test.mjs # 浏览器半边单测（9 项）
node tools/ci/checks.mjs # 仓库自检（面板语法 / 两半可加载 / 无个人数据）
node dsh-plugin/test/live-smoke.mjs # 打实测环境的冒烟（需先配好 sshHost / roots）
CI：以上单测与自检会随 push 在 GitHub Actions 上跑（Node 20 / 22 / 24 三档矩阵）本地跑同样这三条命令即可复现 ✓

常见问题

怎么配免密 ssh？

ssh-keygen -t ed25519
ssh-copy-id you@your-cluster # Windows 可手工把 ~/.ssh/id_ed25519.pub 追加到远端 ~/.ssh/authorized_keys ssh you@your-cluster "echo ok" # 不再问密码即成功更省事：把主机 / 端口 / 密钥写进 ~/.ssh/config，sshHost 直接填那个别名。

面板说「未连接插件 · HTTP 404」

先跑 node standalone/smoke-test.mjs；再手工验证通道：ssh <sshHost> "ls <roots[0]>"。
另外注意：要从 http://127.0.0.1:8787/ 打开，而不是直接双击 public/panel.html（后者是 file://，取不到数）。

任务列表是空的

检查 roots 是否写对；VASP 任务常在 nf/nf/nf 这类深链下，把顶栏「深度」调大（每个根各自记忆）。

只想看某一个目录 / 怎么切换目录

roots 只留一个 → 顶栏下拉会自动隐藏；留多个 → 用下拉切换，切换期间状态灯显示「取数中…」。

读取很慢

深度越大越慢：给大目录设小深度、只给课题目录设大深度。首屏只需一次 /scan + 一次首个任务取数。

与其它工具的关系

| 工具 | 它擅长什么 | 与 vasp-scope 的关系 |
| VASPKIT | 命令行后处理、生成绘图数据 | 互补：能读它产生的 PDOS_ 等口径 |
| VESTA | 晶体结构与电荷密度三维可视化 | 互补：结构页配色与键长字典参考了 VESTA 的习惯 |
| py4vasp / sumo | Python 分析与出版级出图 | 分工：统计/拟合/正式出图用它们；"打开就看、随手导出"用 vasp-scope |
| VTST tools | NEB 能量与距离提取 | 口径一致：能垒页的取数与 X 口径按其脚本语义实现 |
| DeepSeek Harness | 桌面 Agent 环境 | 宿主：插件版把面板开进它的侧栏 |

安全

谁能打开这个面板，谁就能读到你那个 ssh 账号能读到的一切 —— 面板不引入新权限：只走系统 ssh、只读 roots 白名单、不写远端、只监听 127.0.0.1。
完整边界与推荐配置见 SECURITY.md；config.json 已在 .gitignore 中，别提交。
漏洞请走私密渠道报告（见 SECURITY.md）。

未做与计划

- [ ] 多任务对比（同一图叠多条能带 / 收敛曲线）
- [ ] 图片目录级批处理（现在一个目录要发多次请求）
- [ ] CI（GitHub Actions 跑上面的测试）
- [ ] 演示模式：内置假数据，无需集群即可试用（也便于出图做截图）

欢迎 PR / issue；如果这个面板帮你省了事，给个 ⭐ 就是最好的支持。

许可

MIT，见 LICENSE。与 VASP 官方（维也纳大学 / VASP Software GmbH）无隶属关系； "VASP" 仅用于说明所处理的文件格式。