前言¶

在 DeepSeek Harness（DSH）裏讓 agent 往 HPC 集羣提交作業，常見做法是自己在終端反覆 ssh、輸密碼和手機令牌。教學二號集羣不支持密鑰登錄，只能密碼加 OTP，每開一個新 shell 或新工具鏈都要再來一遍。WSL2 用戶還會遇到另一層問題：Windows 上的學校 VPN 只接管 Windows 網絡棧，WSL 裏往往 ping 不通登錄節點。

下面介紹社區插件 dsh-pku-cluster（維護者 KonataRings）：在 DSH 側邊欄完成一次登錄後，用 OpenSSH ControlMaster 複用連接，並提供 pku 命令供 agent 與本地 shell 上傳、提交、查隊列；在 Windows + WSL2 場景下內置 loopback 中繼，讓 WSL 裏的 ssh 能經 Windows VPN 到達集羣。

這是什麼¶

dsh-pku-cluster 是 DSH 的客戶端類插件：宿主側寫 ~/.pku-cluster/ 下的登錄驅動與 CLI，客戶端側在側邊欄提供「連接集羣」面板。目標環境是北京大學未名教學二號上機賬號；loginHost 可在配置裏改，但 pku jobs 等命令按 CraneSched / Slurm 習慣編寫，換集羣需自行覈對。

插件以當前 DSH 進程權限運行，會往家目錄寫入腳本與配置。安裝前建議在 GitHub 倉庫 查看源碼與 MIT 許可證。

核心功能¶

側邊欄點「連接集羣」，輸入學號、門戶密碼和 OTP 後，狀態點變綠即表示 ControlMaster 已建立。README 說明：一次認證約可複用 8 小時（ControlPersist=8h），期間 ssh / scp / rsync 經同一條 master；密碼與 OTP 只經 stdin 交給 login.py，插件不保存密鑰。學號會寫入 ~/.pku-cluster/config.json（權限 600），不屬於機密字段。

憑據不落盤之外，還有這些已文檔化的能力：

• 多路 SSH：~/.pku-cluster/pku 提供 status、run、push / pull、sbatch、jobs、log、shell、down 等子命令，無需改 ~/.ssh/config。
• WSL 與 VPN 橋接：Windows 上插件在 WSL 虛擬網卡對應地址監聽 relayPort（默認 2222），轉發到 loginHost:22；Linux / macOS 直連登錄節點。
• 零額外 Python 依賴：登錄驅動僅用標準庫 pty。
• Diagnose：面板內自檢 Python、pty、ssh、端點可達性等，並給出修復提示。

DSH 退出或重啓時，中繼隨插件進程關閉，複用連接會失效——這是發佈版的設計，不是疏漏。

前置條件¶

不適合需要完全無人值守訪問的場景：平臺限制爲密碼 + OTP，無法密鑰免密。

安裝與啓用¶

任選一種官方方式（<profile> 換成你的 DSH profile，例如 desktop）：

從 GitHub（需本機已裝 Git）：

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

未裝 Git 時可用壓縮包（README 示例標籤爲 v0.1.1）：

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

或從 npm：

dsh plugin --profile <profile> add dsh-pku-cluster

包頁：https://www.npmjs.com/package/dsh-pku-cluster。

裝完後完全退出 DSH 再重開（不是刷新頁面）。側邊欄底部靠近「移動訪問」處會出現「連接集羣」。同一 profile 內不要重複安裝同名插件，以免路由與客戶端模塊 id 衝突。

首次使用¶

1. 校外先連 VPN，確認 Windows 上 iSecSP 的 TAP 適配器爲 Up。
2. 打開側邊欄 連接集羣，填寫學號、密碼、當前 OTP（約 30 秒有效）。
3. 點 Log in；首次會按 accept-new 接受主機指紋。
4. 面板顯示 connected、狀態點爲綠即成功。異常時用 Diagnose 逐項排查。

典型用法¶

登錄成功後，在 WSL 或本機執行 ~/.pku-cluster/pku。README 中的完整提交流程如下：

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

pku push main.py proj/
pku sbatch job.sh proj/
pku jobs
pku log proj/job.out 80

文檔強調兩點：調度器會複製腳本執行，工作目錄須寫死絕對路徑；SLURM_CPUS_PER_TASK 可能是 "4.00" 這類浮點字符串，給 OMP_NUM_THREADS 前應先取整。

若希望每個新對話裏的 agent 默認走 pku，把 README 中的「集羣（北大教學二號）」段落寫入項目的 AGENTS.md 或 skill，說明先 VPN、再側邊欄登錄，以及禁止在登錄節點跑計算、一律 sbatch。

配置（可選）¶

在 profile 的 cordis.patch.yml 裏覆蓋插件 config：

- id: pku-cluster
  name: dsh-pku-cluster
  config:
    loginHost: wmjx2-login.pku.edu.cn
    loginPort: 22
    relayPort: 2222
    distro: ''
    autoInstall: true

distro 留空時取 wsl -l -q 的第一個發行版；autoInstall: false 時插件不再自動寫入 ~/.pku-cluster/*。

適用場景與注意¶

適合：有教學二號賬號，在 DSH 裏希望 agent 直接 pku push + pku sbatch，減少終端重複認證；Windows + WSL2 且已用學校 VPN 的用戶。

不適合：其他學校集羣（需改 host 並自測隊列命令）、無頭服務器、或期望 DSH 重啓後仍保持 SSH master 而不重新登錄（發佈版中繼不獨立常駐）。

卸載示例：

dsh plugin --profile <profile> remove dsh-pku-cluster
rm -rf ~/.pku-cluster

插件不改 ~/.ssh/config，也不寫系統服務；社區目錄 skillhub.cn 插件頁 與 GitHub 相互獨立，均非 DeepSeek / 幻方官方應用商店。

結尾¶

dsh-pku-cluster 把教學二號特有的密碼 + OTP 與 WSL/VPN 網絡差異收進 DSH 側邊欄和一條 pku CLI，讓 Harness 裏的 agent 能在複用連接上完成傳文件、交作業、看隊列。需要細節、排障與兼容性說明時，以倉庫 README 爲準。

• 目錄頁：https://www.skillhub.cn/plugins/KonataRings/dsh-pku-cluster
• GitHub：https://github.com/KonataRings/dsh-pku-cluster