vasp-scope

Name: vasp-scope
Availability: InStock
Author: vasptiger

Local web dashboard for VASP results over SSH (read-only): band structure, PDOS, NEB barrier, AIMD (MSD/RDF); per-feature PNG/CSV export. 浏览器里看集群上的 VASP 计算结果 · 独立版 + DeepSeek Harness 插件

Stars: 1
Language: JavaScript
Created: Oct 12, 2026
Updated: Oct 12, 2026

Web UI

GitHub repo

Introduction

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" 仅用于说明所处理的文件格式。