dsh-pku-cluster

把 北京大学未名教学二号 集群接进 DeepSeek Harness。

侧边栏点一下，输入学号、密码和手机令牌验证码，之后任意新对话都能让 agent 直接在集群上提交作业、
上传下载、查看队列——不用再开一个终端反复输密码和 OTP。

┌──────────────────────────────────────────────────────────────┐
│  侧边栏  ⋯  连接集群 ●            ← 状态点：绿=已连接          │
│           └─ 点开：学号 / 密码 / OTP / Diagnose               │
└──────────────────────────────────────────────────────────────┘

• 一次认证，8 小时复用 — 密码 + OTP 只输一次，之后 ssh / scp / rsync 都走同一条
  OpenSSH ControlMaster 连接。
• 凭据不落盘 — 密码与验证码只经 stdin 交给登录驱动，随后即被丢弃；插件不保存任何密钥。
• WSL 与 VPN 的桥 — Windows 上 VPN 只接管 Windows 网络栈，WSL2 拿不到路由；插件内置一个
  loopback 中继把这条路补上（详见工作方式）。
• 零 Python 依赖 — 登录驱动只用标准库 pty，不需要 pip、不需要 pexpect。
• 自检 — 面板里 Diagnose 逐项检查环境并给出可执行的修复建议。

目录

• 适用与不适用
• 前置条件
• 安装
• 首次使用
• 日常使用（pku 命令）
• 让 agent 知道怎么用
• 配置
• 工作方式
• 文件与卸载
• 排障
• 安全与隐私
• 已知限制与兼容性
• 开发
• FAQ
• License

适用与不适用

适合你，如果：你有北大教学二号上机账号，在 Windows（WSL2）或 Linux/macOS 上用 DSH，
希望 agent 能直接往集群提交作业。

不适合你，如果：

• 你要的是完全没有人工介入的集群访问。集群明确不支持密钥认证，只能密码 + OTP，
  所以做不到无人值守（这是平台限制，不是插件的取舍）。
• 你要连的是别的学校/别的集群。loginHost 可以改，但 pku 里的队列命令假设是 CraneSched，
  换集群需要自己核对（见兼容性）。
• 你想在服务器上无头运行。登录需要浏览器里的 OTP 与人工输入。

前置条件

安装

从 GitHub（需要机器上装 Git）

dsh plugin --profile  add git+https://github.com/KonataRings/dsh-pku-cluster.git

> pnpm 拉 git 依赖要调用 git ls-remote。没装 Git 会直接失败（ERR_PNPM_GIT_RESOLVE_FAILED），
> 这种情况用下面的压缩包方式。

从压缩包（不需要 Git）

dsh plugin --profile  add https://github.com/KonataRings/dsh-pku-cluster/archive/refs/tags/v0.1.1.tar.gz

从 npm

dsh plugin --profile  add dsh-pku-cluster

包页：

从本地目录（开发）

dsh plugin --profile desktop add link:C:\path\to\dsh-pku-cluster

装完完全退出 DSH 再重开（不是刷新页面）。侧边栏底部、靠近「移动访问」的位置会出现「连接集群」。

升级：重跑一次 add（或改版本后重装）；卸载见文件与卸载。

> 同一个 profile 里不要同时装两个同名插件（相同包名 / 路由 / 客户端模块 id 会冲突）。

首次使用

1. 连 VPN（仅校外需要）。Windows 上确认 iSecSP 的 TAP 适配器是 Up。
2. 点侧边栏 连接集群。
3. 填写：
   - 学号 — 会保存在 ~/.pku-cluster/config.json（不是机密，权限 600）；
   - 密码 — 开卡时的门户密码；
   - OTP — 手机令牌里的 6 位数字（只有 30 秒有效，别提前抄）。
4. 点 Log in。首次连接会确认主机指纹（插件已用 StrictHostKeyChecking=accept-new 自动接受）。
5. 状态点变绿、面板显示 connected 即成功。

不确定哪里不对时，点 Diagnose，它会逐项告诉你 Python、pty、ssh、端点可达性、学号是否就绪。

日常使用（pku 命令）

登录成功后，agent 和你在 WSL 里都可以用 ~/.pku-cluster/pku：

pku 会自己从 config.json 读取目标地址、端口与学号，所以你不需要改 ~/.ssh/config。

一个完整例子

# 1) 本地准备脚本
mkdir -p ~/proj && cd ~/proj
cat > job.sh <<'SH'
#!/bin/bash
#SBATCH -J myjob
set -euo pipefail
WORKDIR=/nfs-share/home/<学号>/proj      # 必须写死：调度器会把脚本复制到别处执行
cd "$WORKDIR"
RAW="${SLURM_CPUS_PER_TASK:-4}"; CPUS=$(printf '%.0f' "$RAW")
export OMP_NUM_THREADS="$CPUS" MKL_NUM_THREADS=1
source ~/miniforge3/etc/profile.d/conda.sh
conda activate dmet-minimal
python -u main.py
SH

# 2) 提交（脚本 + 同目录文件都要传）
pku push main.py proj/
pku sbatch job.sh proj/

# 3) 看队列与输出
pku jobs
pku log proj/job.out 80

> 两个高频坑：调度器会复制脚本执行（所以 cd 必须写死绝对路径，别用 dirname "$0"）；
> SLURM_CPUS_PER_TASK 是浮点字符串 "4.00"，直接给 OMP_NUM_THREADS 会让 Intel OpenMP
> 报错 abort。见 docs/troubleshooting.md。

让 agent 知道怎么用

新对话默认不知道这个约定。把下面这段加进 AGENTS.md（或做成一个 skill），就能让每个会话都用对：

## 集群（北大教学二号）
- 连接：先连 VPN，再在 DSH 侧边栏「连接集群」登录；连接状态用 `pku status` 查。
- 命令（在 WSL 里执行 `~/.pku-cluster/pku`）：
`status` / `run ''` / `push` / `pull` / `sbatch` / `jobs` / `log`。
- 规则：登录节点禁止跑计算，一律 `sbatch`；脚本里写死绝对工作目录；
`OMP_NUM_THREADS` 必须是整数。

加了之后，你可以直接说「在集群上跑一下这个输入」，agent 就会走 pku push + pku sbatch。

配置

在 profile 的 cordis.patch.yml 里覆盖，全部可选：

- id: pku-cluster
name: dsh-pku-cluster
config:
loginHost: wmjx2-login.pku.edu.cn   # 登录节点（换集群改这里）
loginPort: 22
relayPort: 2222                     # Windows 中继端口，仅 Windows 使用
distro: ''                          # 留空 = 自动取 `wsl -l -q` 的第一个
autoInstall: true                   # 首次加载时写入 ~/.pku-cluster/*

autoInstall 写入的 config.json 还包含内部字段 mode（relay / direct，由平台自动决定）
和 relayHost（留空则取 WSL 默认网关）。

工作方式

DSH 页面 / 侧边栏
│  ① 学号 + 密码 + OTP（仅经 stdin）
▼
login.py（在 WSL 或本机执行）
│  ② 打开 pty，应答 "Password:" 与 "Verification Code:"
▼
ssh -M -N -f  ──►  ③ ControlMaster（复用 8 小时）
│
├─ Windows：连 :  ← 插件进程内置的中继，只绑 WSL 网卡地址
│            └─ ④ 中继在 Windows 侧转发到 loginHost:22，从而穿过 VPN
└─ Linux / macOS：直连 loginHost:22

为什么 Windows 需要那个中继？

VPN 客户端（iSecSP / Array TAP）只接管 Windows 的网络栈。WSL2 有自己的 NAT，不继承这些路由；
networkingMode=mirrored 对点对点 TAP 适配器同样无效——实测 WSL 能拿到与主机相同的源 IP、
ip neigh 里网关是 REACHABLE，但 ping 网关失败、22 端口超时，数据包根本没出去。

于是插件在 WSL 虚拟网卡的 Windows 侧地址上监听，把连接原样转发到登录节点，WSL 里的 ssh 连这个
本地端口即可。中继只绑定 WSL 网段地址，不监听 0.0.0.0，也不对局域网暴露；随插件进程一起启停。

为什么还要 control socket？ 因为集群不支持密钥认证，每次新连接都要密码 + OTP。
ControlMaster 让「一次认证、多次复用」成为可能，这是在不牺牲二步验证的前提下的最优解。

一次登录能维持多久

发布版的连接参数是写死的，不依赖你的 ~/.ssh/config：

实际寿命 = 下面几项里最短的那个：

也就是说：只要 DSH 不重启、WSL 不重启、VPN 不掉，并且 8 小时内用过一次，就能一直用。
想跨 DSH 重启保留连接，需要把中继做成独立常驻进程——发布版没有内置（见已知限制）。

文件与卸载

插件会在你的家目录写三个文件（都在 ~/.pku-cluster/）：

卸载：

dsh plugin --profile  remove dsh-pku-cluster
rm -rf ~/.pku-cluster        # 可选：连带删除上面三个文件
ssh -O exit pku 2>/dev/null  # 可选：先断开复用连接（如果还在）

插件不改你的 ~/.ssh/config，不写 AGENTS.md，也不留计划任务或系统服务。

排障

更细的「为什么」和确认方法见 docs/troubleshooting.md。
报问题时请附上：平台（Windows/Linux/macOS）、DSH 版本、面板 Diagnose 的输出、失败阶段。

安全与隐私

• 不保存密码与 OTP：只经 stdin 传给驱动；驱动应答完提示后即丢弃，连接由 OpenSSH 持有。
• 学号不是机密，但同样按 600 存放。
• HTTP 路由仅接受 loopback：req.socket.remoteAddress 必须是 127.0.0.1/::1，
  且 Host 头必须是 localhost/127.0.0.1。即使你把 DSH 通过移动访问/LAN 暴露出去，
  这个登录页也不会跟着对外（但仍不建议把 DSH 本身暴露给不可信网络）。
• 中继只绑定 WSL 网卡地址，不监听 0.0.0.0；随插件进程退出而关闭。
• 插件不读取也不修改你的 ~/.ssh 内容，只依赖系统 ssh 客户端。

已知限制与兼容性

平台限制

• 集群不支持密钥认证，因此：VPN 重连、连接闲置超时、机器休眠之后，都需要重新登录一次。
• 中继随插件进程启停：DSH 退出或重启会一并关闭中继，从而断开已建立的 master 连接。
  要跨 DSH 重启保持连接，需要把中继改成独立常驻服务（本版本未内置）。
• 登录节点不可联网、禁止跑计算；必须 sbatch 到计算节点。

兼容性

其他

• 插件不提供模型侧工具（cluster_* tool），走的是 WSL 命令 + AGENTS.md 约定；
  这样做的好处是不增加首轮工具表长度，代价是需要你写一段说明。
• 页面是英文，文档中英双语；要本地化页面文案可以改 lib/index.js 里的 PAGE。

开发

dsh-pku-cluster/
├─ lib/
│  ├─ index.js       宿主插件：路由、内置中继、资产安装、页面
│  └─ client.js      客户端模块：侧边栏按钮（sidebar.footer.action）
├─ resources/
│  ├─ login.py       登录驱动（标准库 pty）
│  └─ pku            命令行包装器
├─ docs/
│  └─ troubleshooting.md
├─ cordis.patch.yml
├─ package.json
├─ README.md / README.en.md
├─ CHANGELOG.md
└─ LICENSE

本地加载：dsh plugin --profile add link:<绝对路径>，然后重启 DSH。

改动 lib/index.js 后建议至少做：

node --check lib/index.js
node --check lib/client.js
# 用假 ctx 加载插件，验证路由注册 / loopback 守卫 / 中继绑定
node -e "import('file:///abs/path/lib/index.js').then(m=>console.log(m.name, m.inject))"

WSL 侧资源可以脱离 DSH 单独验证（用隔离的 HOME，不影响现有环境）：

T=/tmp/pku-test; mkdir -p "$T/.pku-cluster"
cp resources/login.py resources/pku "$T/.pku-cluster/"
printf '{"mode":"direct","loginHost":"wmjx2-login.pku.edu.cn","user":""}\n' > "$T/.pku-cluster/config.json"
HOME="$T" python3 "$T/.pku-cluster/login.py" --diagnose

欢迎 issue / PR。改协议行为时请一并更新 CHANGELOG.md 与
docs/troubleshooting.md。

FAQ

Q：为什么每次开机都要重新登录？
A：集群不支持密钥认证，只有密码 + OTP。ControlMaster 复用期是 8 小时，且随 VPN 断线失效。
这是平台限制，不是插件能绕过的。

Q：OTP 从哪来？
A：先在 绑定手机令牌（FreeOTP / Google Authenticator），
之后每次登录输入 App 里的 6 位数字。注意手机时间要准，否则码会不对。

Q：能同时连两个账号吗？
A：同一个 profile 只能有一个 ControlMaster。换账号：pku down → 在面板里改学号 → 重新登录。

Q：VPN 断了怎么办？
A：重连 VPN，然后在面板里再登录一次。面板状态点会变红提示。

Q：密码里有特殊字符会不会出问题？
A：不会。密码走 stdin 交给 pty，不经过任何 shell 拼接。

Q：插件会存我的密码吗？
A：不会。密码和 OTP 只在内存中短暂存在，用于应答 ssh 的两条提示。

Q：能连别的集群吗？
A：改 loginHost/loginPort 可以连上任何「密码 + OTP」的 SSH 集群，但 pku 里的
jobs/sbatch 是按 CraneSched 写的，换 Slurm 需要自己改 resources/pku。

Q：为什么 Windows 要比 Linux 多一层中继？
A：因为 WSL2 不继承 Windows 的 VPN 路由（见工作方式）。Linux/macOS 上 VPN 是
系统级的，不需要这层。

License

MIT © 2026 dsh-pku-cluster contributors