dsh-scnet 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">dsh-scnet</h1>
 
-<p align="center">在 DeepSeek Harness 里操作超算互联网（scnet.cn）及同类国产超算集群：配 SSH、生成 Slurm 作业、探测/刷新集群、运行计算节点探针、排查失败，附海光 DCU/DTK 知识。</p>
+<p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）集群：配 SSH、生成 CPU/DCU Slurm 作业、探测/刷新集群、运行计算节点探针、排查失败，附海光 DCU/DTK 知识和英文快速指南。</p>
 
 ## 这是什么
 
@@ -31,6 +31,7 @@ git 源、本地目录安装以及验证步骤见 [INSTALL.md](./INSTALL.md)。
 | zzeshell | 超算互联网 · 郑州 | 海光 BW1000 DCU (gfx936) ×8, 64GB/卡 |
 | kseshell | 超算互联网 · 昆山 | 海光 Z100 DCU (gfx906) ×4, 16GB/卡 |
 | wuzhshell | 超算互联网 · 乌镇 | 海光 Z100 DCU (gfx906) ×4, 16GB/卡 |
+| xianshell | 超算互联网 · 西安 | 海光 Z100 DCU (gfx906) ×4, 16GB/卡 |
 
 ### Tools
 
@@ -38,7 +39,7 @@ git 源、本地目录安装以及验证步骤见 [INSTALL.md](./INSTALL.md)。
 |---|---|
 | scnet_list_clusters | 列出已配置的集群 profile |
 | scnet_show_cluster | 读取指定集群的完整参数 |
-| scnet_generate_job | 按 profile 生成合规 Slurm 作业脚本 |
+| scnet_generate_job | 按 profile 生成加速器或 CPU-only Slurm 作业，支持显式分区覆盖 |
 | scnet_setup_ssh | 配置本地到集群的 SSH 连接 |
 | scnet_probe_cluster | 探测新集群并生成 profile |
 | scnet_refresh_cluster | 动态刷新已有集群的规则缓存 |
@@ -60,7 +61,8 @@ git 源、本地目录安装以及验证步骤见 [INSTALL.md](./INSTALL.md)。
 │   ├── clusters/
 │   │   ├── zzeshell.conf
 │   │   ├── kseshell.conf
-│   │   └── wuzhshell.conf
+│   │   ├── wuzhshell.conf
+│   │   └── xianshell.conf
 │   ├── scripts/
 │   └── references/
 ├── sync.sh               # 从 canonical 仓库同步
@@ -76,7 +78,7 @@ git 源、本地目录安装以及验证步骤见 [INSTALL.md](./INSTALL.md)。
 本仓库是发布面，知识内容（`skills/scnet-hpc/` 下的 SKILL.md、clusters、references、scripts）从 canonical 仓库 `lql341/scnet-hpc` 同步：
 
 ```sh
-./sync.sh                   # 默认 ../skills/scnet-hpc
+./sync.sh                   # 当前本机布局默认 ../../skills/scnet-hpc
 ./sync.sh --src /path/to/scnet-hpc
 ```
 
@@ -88,7 +90,7 @@ git 源、本地目录安装以及验证步骤见 [INSTALL.md](./INSTALL.md)。
 - 仓库不含私钥、token、用户名、密钥指纹。
 - `scnet_setup_ssh` 会写入 `~/.ssh/`，调用前确认私钥路径和集群。
 - `scnet_generate_job` 生成的 `.slurm` 可能含本机用户名，`.gitignore` 已排除。
-- 集群主机名/端口是平台公开信息，由 canonical 仓库维护。
+- SSH 接入端点仅使用平台面向用户公开提供的信息，由 canonical 仓库维护。
 - `scnet_refresh_cluster` / `scnet_run_compute_probe` 会 SSH 到远端并可能提交作业；运行前确认集群和副作用。
 - `clusters/.cache/` 是本机动态探测缓存，`.gitignore` 已排除，不应提交。
 

package/index.mjs

@@ -12,12 +12,12 @@ const SKILL_DIR = join(__dirname, 'skills', 'scnet-hpc')
 const SCRIPTS_DIR = join(SKILL_DIR, 'scripts')
 const CLUSTERS_DIR = join(SKILL_DIR, 'clusters')
 
-function runBash(script, args, timeoutMs = 120000) {
+function runBash(script, args, timeoutMs = 120000, cwd = SKILL_DIR) {
   return new Promise((resolve) => {
     execFile(
       'bash',
       [script, ...args],
-      { cwd: SKILL_DIR, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
+      { cwd, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
       (error, stdout, stderr) => {
         const code = error ? (typeof error.code === 'number' ? error.code : 1) : 0
         resolve({
@@ -126,7 +126,7 @@ export function apply(ctx) {
     defineTool({
       name: 'scnet_generate_job',
       description:
-        '按目标集群的约束生成合规的 Slurm 作业脚本（自动算 --mem、--gres、module load、离线环境变量，并在末尾写 exit $rc）。会写一个 <name>.slurm 到当前目录并返回上传/提交命令。',
+        '按目标集群约束生成 Slurm 作业脚本。支持加速器作业、cpu_only CPU 分区和显式 partition 覆盖；自动计算内存、按需申请 GRES、加载 module、设置离线环境并传播退出码。',
       parameters: {
         name: { type: 'string', required: true, description: '作业名（slurm --job-name 和输出文件名）' },
         accelerators: { type: 'string', description: '加速器数量，默认 1' },
@@ -134,6 +134,8 @@ export function apply(ctx) {
         time: { type: 'string', description: '时长，默认 00:20:00，格式 HH:MM:SS 或 D-HH:MM:SS' },
         cluster: { type: 'string', description: '集群短名；省略时若只有一个 profile 则自动选择' },
         remote_user: { type: 'string', description: '远端用户名；与本地不同时填写（日志路径需要真实用户名）' },
+        cpu_only: { type: 'boolean', description: '使用 profile 的 PARTITION_CPU 且不申请 GRES（默认否）' },
+        partition: { type: 'string', description: '显式覆盖目标 Slurm 分区；需自行确认该分区的 GRES 规则' },
         refresh: { type: 'boolean', description: '是否在生成前运行 refresh-cluster.sh 刷新动态规则（默认否）' },
         no_auto: { type: 'boolean', description: '是否忽略 clusters/.cache/*.auto.conf 动态缓存（默认否）' },
       },
@@ -155,15 +157,21 @@ export function apply(ctx) {
         if (cluster) argv.push('--cluster', cluster)
         const remoteUser = String(args.remote_user || '').trim()
         if (remoteUser) argv.push('--user', remoteUser)
+        if (args.cpu_only === true) argv.push('--cpu-only')
+        const partition = String(args.partition || '').trim()
+        if (partition) argv.push('--partition', partition)
         if (args.refresh === true) argv.push('--refresh')
         if (args.no_auto === true) argv.push('--no-auto')
         argv.push(nameVal)
-        if (accelerators) argv.push(accelerators.value)
-        if (cpus) argv.push(cpus.value)
-        if (args.time && String(args.time).trim()) argv.push(String(args.time).trim())
+        const time = String(args.time || '').trim()
+        if (accelerators || cpus || time) {
+          argv.push(accelerators?.value || (args.cpu_only === true ? '0' : '1'))
+        }
+        if (cpus || time) argv.push(cpus?.value || '8')
+        if (time) argv.push(time)
 
         const timeoutMs = args.refresh === true ? 240000 : 30000
-        const res = await runBash(join(SCRIPTS_DIR, 'new-job.sh'), argv, timeoutMs)
+        const res = await runBash(join(SCRIPTS_DIR, 'new-job.sh'), argv, timeoutMs, process.cwd())
         if (res.ok) return res.stdout.trim() || res.stderr.trim()
         return `生成失败（exit ${res.code}）：\n${res.stderr.trim() || res.stdout.trim()}`
       },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-scnet",
-  "version": "0.2.1",
-  "description": "DeepSeek Harness bundle plugin for SCNet (scnet.cn) and similar domestic HPC clusters: SSH setup, Slurm job generation, cluster probing/refresh, compute-node capability probes, and Hygon DCU/DTK guidance.",
+  "version": "0.4.0",
+  "description": "DeepSeek Harness plugin for SCNet HPC: SSH setup, CPU/DCU Slurm jobs, cluster probing, compute-node diagnostics, and Hygon DCU/DTK guidance.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -40,7 +40,8 @@
     "slurm",
     "hpc",
     "hygon",
-    "dcu"
+    "dcu",
+    "scnet"
   ],
   "license": "MIT"
 }

package/skills/scnet-hpc/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: scnet-hpc
-description: 在超算互联网（scnet.cn）及同类国产超算集群上工作 —— 从个人电脑（macOS/Linux）配置 SSH 连接、提交和监控 Slurm 作业、交互式调试、排查作业失败、安装 Python 依赖，以及查找海光 DCU/DTK 的官方开发文档、数学库、通信库、分析调试和 CUDA 迁移工具。当任务涉及超算集群、Slurm 作业、海光 DCU / DTK / gfx9xx、DTK 工具库选型、或需要写 sbatch 脚本、判断该在登录节点还是计算节点执行某件事时使用。集群参数存在 clusters/*.conf，支持多集群。
+description: 在超算互联网（SCNet）集群上配置 SSH、使用 Slurm、申请 CPU/DCU 资源、提交和排查作业、安装依赖及验证国产加速器兼容性；当前深度验证以海光 DCU/DTK/gfx9xx 为主。Use for SCNet HPC tasks involving SSH setup, Slurm jobs, login versus compute nodes, CPU/DCU resource requests, Hygon DCU, DTK, gfx9xx, sbatch/srun, offline compute nodes, cluster profiles, or accelerator compatibility. Other SCNet accelerators must be verified on their target cluster.
 ---
 
 # 国产超算集群使用规范
 
-面向超算互联网（scnet.cn）系列集群。**集群参数不写在文档里，存在
+面向超算互联网（SCNet）系列集群，当前收录节点以海光 DCU 为主。其他芯片平台
+只复用连接、调度和验证方法，不套用海光工具链结论。**集群参数不写在文档里，存在
 `clusters/<集群短名>.conf`**，脚本从 profile 读取，所以同一套流程能用于多个集群。
 
 ## 先确认在跟哪个集群打交道
@@ -33,6 +34,10 @@ cat clusters/<集群短名>.conf     # 看具体参数
 | `references/adding-cluster.md` | 新增集群的完整步骤 |
 | `references/hygon-dcu-development.md` | 海光 DCU 开发流程、DTK 工具库与官方资源索引 |
 | `references/software-compatibility.md` | 国产超算上的软件兼容性排查、验证分层与公开报告脱敏 |
+| `references/quickstart-en.md` | English quick start for SSH, Slurm, CPU/DCU jobs, and troubleshooting |
+
+用户使用英文提问或需要英文操作说明时，读取 `references/quickstart-en.md`；集群具体
+参数仍以 `clusters/*.conf` 为准，不从英文示例猜测。
 
 ## 换机器
 
@@ -123,7 +128,8 @@ ImportError: libmsgpackc.so.2: cannot open shared object file
 **不要在登录节点试 torch 代码然后困惑为什么报错。** 哪怕只想看一眼 tensor 的
 dtype，也要走 `srun` 或 `sbatch`。
 
-登录节点能做：`pip install`、`git`、读写文件、`sacct`/`squeue`、下载模型。
+登录节点通常用于 `git`、文件管理、`sacct`/`squeue` 和准备依赖；能否访问软件源、
+下载模型或执行 `pip install` 必须查看 profile 的网络字段并现场确认。
 
 ### 4. 计算节点通常无外网 —— 依赖必须预装
 
@@ -139,9 +145,15 @@ export HF_HUB_OFFLINE=1
 export TRANSFORMERS_OFFLINE=1
 ```
 
-### 5. `/tmp` 通常不跨节点共享 —— 文件放家目录
+### 5. 测试任务的临时目录必须建在家目录
+
+针对任何集群提交测试或探针任务时，**不要使用 `/tmp`，也不要从根目录下创建临时
+目录**。统一在共享家目录中创建，例如 `$HOME/.scnet-hpc/tmp/$SLURM_JOB_ID`，并在
+作业中导出 `TMPDIR`、`TMP`、`TEMP` 指向该目录。这样登录节点、计算节点和后续作业
+都能访问同一份临时文件。任务结束后只清理本次作业自己的子目录。
 
-`TMP_SHARED=no` 时，`/tmp` 在计算节点是本地的，作业之间不可见。
+`TMP_SHARED=no` 表示系统 `/tmp` 不作为跨节点共享路径使用；即使某个集群实测 `/tmp`
+可见，测试脚本仍默认遵循上述家目录规则。
 
 ### 6. 先验证二进制兼容性，再做完整安装
 
@@ -153,8 +165,12 @@ export TRANSFORMERS_OFFLINE=1
 ./scripts/new-job.sh <作业名> [加速器数] [cpu数] [时长]
 ./scripts/new-job.sh probe                 # 1 卡, 8 核, 20 分钟
 ./scripts/new-job.sh infer 8 32 01:30:00   # 8 卡, 32 核, 1.5 小时
+./scripts/new-job.sh --cpu-only build 0 32 01:00:00
 ```
 
+有独立 CPU 分区时使用 `--cpu-only`，脚本读取 `PARTITION_CPU` 并省略 `--gres`；
+临时指定其他分区时使用 `--partition <名称>`。
+
 上传后先验证配额而不真排队：
 
 ```bash
@@ -180,7 +196,7 @@ $ sacct -j <JOB_ID>
 
 ## 交互式调试（推荐）
 
-比 sbatch 快得多，适合试代码、查环境、验证假设。实测约 5 秒拿到节点：
+通常比反复提交完整作业更适合试代码、查环境和验证假设；实际排队时间取决于分区负载：
 
 ```bash
 srun -p <分区> --gres=<类型>:1 --cpus-per-task=8 --mem=30gb --time=00:10:00 \
@@ -217,25 +233,11 @@ sinfo -p <分区> -o "%n %c %m %G %t"   # 节点资源和状态
 先读 `references/hygon-dcu-development.md`。用它定位官方资料，再以目标集群的
 module、计算节点探针和 profile 为准；不要把网页当前版本直接覆盖到集群环境。
 
-**不要假设加速器支持什么。** 国产加速器（海光 DCU、寒武纪、昇腾）的软件栈往往
-落后于上游，很多 CUDA/ROCm 上想当然的能力并不存在。profile 的
-`KNOWN_LIMITATIONS` 记录了已探明的缺口。
-
-以 zzeshell 的海光 gfx936 为例，实测结论：
-
-| 能力 | 结果 |
-|---|---|
-| FP8 存储 + `.to(bfloat16)` 转换 | ✅ |
-| `torch._scaled_mm`（硬件 FP8 matmul） | ❌ 需 SM89+/SM90+ 或 ROCm MI300+ |
-| **Triton** | ❌ `libamdhip64.so` 缺 `hipDrvLaunchKernelEx` |
-| bitsandbytes 4-bit / 8-bit | ✅ 需补丁 / ❌ 无 INT8 algo |
-
-Triton 那条影响最大：**任何依赖 Triton kernel 的推理框架都跑不起来**
-——SGLang FP8 路径、vLLM ROCm MoE 后端、transformers `finegrained-fp8` 都在此列。
-遇到这类需求先想清楚有没有纯 PyTorch 的退路，别花时间在框架适配上。
-
-碰到新集群时，用一个探针作业实测这些能力，把结论写回 profile 的
-`KNOWN_LIMITATIONS`，别让下一个人重踩。
+**不要假设加速器支持什么。** 即使同属 SCNet，不同芯片、DTK/驱动和框架版本的
+能力也可能不同。先读取目标 profile 的 `KNOWN_LIMITATIONS`，再用计算节点探针验证
+设备枚举、dtype、kernel、通信和真实功能。海光 DCU/DTK 的开发资料入口见
+`references/hygon-dcu-development.md`；软件兼容性验证顺序见
+`references/software-compatibility.md`。
 
 ## 排查失败
 
@@ -260,6 +262,8 @@ Triton 那条影响最大：**任何依赖 Triton kernel 的推理框架都跑
 
 将集群实测结果写入公开报告或仓库前，保留环境、方法、版本、结果和限制，移除或替换以下信息：用户名、SSH 主机/端口、内部域名、IP、节点名、作业编号、绝对家目录和私有镜像地址。可用 `<USER_HOME>`、`<DTK_ROOT>`、`<CLUSTER_HOST>`、`已脱敏作业` 等占位符。
 
-报告正文沿用已有 LAMMPS 报告的结构和风格：深色渐变卡片、青绿色主色、蓝色辅助色，以及“环境信息 → 编译过程与主要难题 → 最终方案 → 测试结果 → 已知限制 → 经验总结 → 附录”的叙述顺序。公开结论必须标明测试环境、验证范围和未验证边界。
+公开技术记录按“环境与版本 → 问题与证据 → 解决方法 → 验证结果 → 已知限制 →
+可复用经验”组织。结论必须标明测试环境、验证范围和未验证边界；视觉样式由具体发布
+项目决定，不写进本 skill。
 
 详细的兼容性排查和报告模板见 `references/software-compatibility.md`。

package/skills/scnet-hpc/clusters/_template.conf

@@ -24,6 +24,7 @@ SCHEDULER="slurm"
 PARTITION=""
 
 DEF_MEM_PER_CPU=""                       # MB。scontrol show partition <名> 里的 DefMemPerCPU
+DEF_MEM_PER_CPU_CPU=""                   # 可选：CPU 分区不同于默认分区时填写
 MIN_GRES=""                              # QOS 强制的最小 GRES，如 "dcu:1"；无则留空
 GRES_TYPE=""                             # "dcu" / "gpu" / "npu" 等
 MAX_WALLTIME=""

package/skills/scnet-hpc/clusters/xianshell.conf

@@ -0,0 +1,66 @@
+# xianshell —— 西安集群（eshell111.hpccube.com）
+#
+# 2026-08-17 完成登录节点、Slurm 和计算节点实测。
+# 计算探针使用 xahdnormal 分区、1 张 DCU，并将所有临时文件放在共享家目录。
+
+# ---- 连接 ----
+CLUSTER_ID="xianshell"
+CLUSTER_DESC="西安集群（eshell111）"
+SSH_HOST="eshell111.hpccube.com"
+SSH_PORT="65082"
+HOME_BASE="/work/home"
+
+# 私钥文件名形如：<用户名>_eshell111.hpccube.com_RsaKeyExpireTime_<日期>.txt
+KEY_NAME_MARKER="_eshell111.hpccube.com_"
+NEEDS_UPDATE_HOSTKEYS_NO="no"
+
+# ---- 调度器 ----
+SCHEDULER="slurm"
+PARTITION="xahdnormal"
+DEF_MEM_PER_CPU="3570"
+MIN_GRES="dcu:1"                         # sbatch --test-only 实测：不申请即 QOSMinGRES
+GRES_TYPE="dcu"
+MAX_WALLTIME="333-08:00:00"
+
+# xahcnormal 是异构 CPU 队列（5609 节点，少量节点也带 DCU）。
+PARTITION_CPU="xahcnormal"
+PARTITION_DCU="xahdnormal"
+
+# ---- 硬件 ----
+ACCEL_NAME="海光 Z100 DCU (Z100SM)"
+ACCEL_ARCH="gfx906"
+ACCEL_PER_NODE="4"
+ACCEL_MEM_GB="16"                        # PyTorch 实测 16368 MiB
+CPUS_PER_NODE="32"                       # Slurm xahdnormal 可调度 CPU；节点物理 64 核
+CPU_MODEL="Hygon C86 7285 32-core Processor"
+NODE_MEM_GB="123"
+NODE_COUNT="465"
+LOGIN_NODES="登录节点（实测，公开 profile 已脱敏）"
+HOME_QUOTA_GB="450"                      # /work 文件系统容量，非个人独占配额
+
+# ---- 软件栈 ----
+TOOLCHAIN="DTK"
+TOOLCHAIN_VERSION="26.04"
+TOOLCHAIN_PATH="/public/software/compiler/dtk-26.04"
+MODULE_LOADS="compiler/dtk/26.04"
+PYTHON_MODULE="python/3.8.10"             # 计算节点显式加载，避免依赖用户私有 PATH
+DEFAULT_VENV=""
+
+# 平台自带的可运行 PyTorch 环境（能力探针专用）：
+#   module load Pytorch/1.10.0-hpcx-gcc-7.3.1
+# 该模块会 purge 环境并改用 DTK 22.10.1，不能与上面的 DTK 26.04 同时加载。
+
+# ---- 网络 ----
+NET_OK="pypi.org pypi.tuna.tsinghua.edu.cn modelscope.cn github.com"
+NET_BLOCKED="huggingface.co"
+PIP_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
+COMPUTE_NODE_OFFLINE="yes"
+TMP_SHARED="no"
+
+# ---- 已知问题 ----
+LOGIN_NODE_MISSING_LIBS=""
+KNOWN_LIMITATIONS="平台 PyTorch 1.10.0a0+git2040069-dtk2210 仅探测到 BF16，无 FP8 dtype，torch._scaled_mm 跳过；\
+Triton 未安装；bitsandbytes 未安装；计算节点无法访问 pypi.org；\
+平台 PyTorch module 固定加载 DTK 22.10.1，与默认 DTK 26.04 不可混用；\
+远端缺少 C.UTF-8 locale，SSH 和作业启动会产生 setlocale 警告但不影响执行；\
+测试任务临时目录必须使用 \$HOME/.scnet-hpc/tmp/\$SLURM_JOB_ID，不使用 /tmp"

package/skills/scnet-hpc/references/adding-cluster.md

@@ -82,6 +82,10 @@ srun -p <分区> --gres=gpu:1 --time=00:05:00 nvidia-smi --query-gpu=name --form
 **这一步别省。** 国产加速器的软件栈往往落后于上游，很多想当然的能力并不存在。
 花 5 分钟测清楚，能省掉后面几天的困惑。
 
+所有探针和测试任务的临时文件必须放在共享家目录中，例如
+`$HOME/.scnet-hpc/tmp/$SLURM_JOB_ID`。不要使用 `/tmp` 或从根目录创建临时目录；作业
+启动后应导出 `TMPDIR`、`TMP`、`TEMP` 指向该目录。
+
 用一个探针作业测这些：
 
 ```python

package/skills/scnet-hpc/references/quickstart-en.md

@@ -0,0 +1,123 @@
+# SCNet HPC English Quick Start
+
+This guide covers the common workflow for SCNet clusters. Current repository profiles focus
+mainly on Hygon DCU/DTK systems. Always read the target profile before using a partition,
+memory value, accelerator type, module, or home-directory path.
+
+## 1. Inspect the available profiles
+
+```bash
+ls clusters/*.conf
+sed -n '1,220p' clusters/<cluster>.conf
+```
+
+Check at least `PARTITION`, `PARTITION_CPU`, `GRES_TYPE`, `MIN_GRES`,
+`DEF_MEM_PER_CPU`, `MODULE_LOADS`, `COMPUTE_NODE_OFFLINE`, and
+`KNOWN_LIMITATIONS`.
+
+## 2. Install the skill
+
+```bash
+git clone https://github.com/lql341/scnet-hpc.git
+cd scnet-hpc
+./scripts/install.sh
+```
+
+The repository is designed to be shared by Codex, Claude Code, and OpenCode. Installation
+paths depend on the local agent layout; `install.sh --link` is useful when developing the
+skill from a shared source directory.
+
+## 3. Configure SSH
+
+Download the private key from the SCNet console, then run:
+
+```bash
+./scripts/setup-ssh.sh --cluster <cluster> <private-key-file> <username>
+ssh <cluster>
+```
+
+The script installs the key under `~/.ssh`, adds an SSH config entry, and tests the
+connection. Do not commit private keys, usernames, internal node names, or personal paths.
+
+## 4. Generate a Slurm job
+
+Accelerator job:
+
+```bash
+./scripts/new-job.sh --cluster <cluster> myjob 1 8 00:20:00
+```
+
+CPU-only job, when the profile defines `PARTITION_CPU`:
+
+```bash
+./scripts/new-job.sh --cluster <cluster> --cpu-only build 0 32 01:00:00
+```
+
+Explicit partition override:
+
+```bash
+./scripts/new-job.sh --cluster <cluster> --partition <partition> probe 1 8 00:10:00
+```
+
+The generator calculates a safe memory request from the profile, adds GRES only when
+needed, configures a shared temporary directory, enables offline mode when appropriate,
+and propagates the program exit code.
+
+Create the remote log directory before submission:
+
+```bash
+ssh <cluster> 'mkdir -p ~/scripts/logs'
+```
+
+Upload the generated script and validate the request before queueing it:
+
+```bash
+scp myjob.slurm <cluster>:~/scripts/
+ssh <cluster> 'sbatch --test-only ~/scripts/myjob.slurm'
+ssh <cluster> 'sbatch ~/scripts/myjob.slurm'
+```
+
+## 5. Monitor and debug
+
+```bash
+squeue -u "$USER"
+squeue -j <job-id> --start
+sacct -j <job-id> --format=JobID,State%14,ExitCode,Elapsed,MaxRSS -P
+scancel <job-id>
+```
+
+Do not trust `COMPLETED` alone. Read both stdout and stderr, and make sure the job script
+ends with the real program exit code.
+
+For short experiments, request an interactive allocation with `srun`. Use the partition,
+GRES type, CPU count, and memory limit from the target profile.
+
+## 6. SCNet environment rules
+
+- Login nodes are for source management, dependency preparation, file operations, and
+  scheduler commands. Whether package indexes and model sites are reachable is cluster-specific.
+- Compute nodes are often offline. Download dependencies, models, and kernels before the job.
+- A DCU partition may require at least one accelerator even for a CPU-oriented command.
+- Memory limits may be tied to `cpus-per-task × DefMemPerCPU`.
+- Do not use system `/tmp` for files that must be shared across login and compute nodes.
+- Loading a module on a login node does not prove that the runtime works on a compute node.
+- Hygon DCU software capabilities depend on the exact DTK, driver, framework, and `gfx` target.
+
+## 7. Refresh and probe a cluster
+
+```bash
+./scripts/refresh-cluster.sh --cluster <cluster> --dry-run
+./scripts/refresh-cluster.sh --cluster <cluster>
+./scripts/refresh-cluster.sh --cluster <cluster> --compute
+```
+
+The default refresh performs read-only login-node checks. `--compute` submits a small Slurm
+job to test the accelerator runtime and therefore consumes cluster resources.
+
+For detailed diagnostics, see the Chinese references:
+
+- `references/setup.md`
+- `references/environment.md`
+- `references/troubleshooting.md`
+- `references/software-compatibility.md`
+- `references/hygon-dcu-development.md`

package/skills/scnet-hpc/references/software-compatibility.md

@@ -8,6 +8,35 @@
 4. **依赖路径**：区分 pip/conda 解析失败、运行时动态库失败、框架 kernel 不支持和模型/数据下载失败。
 5. **端到端结果**：记录成功条件、性能、显存/内存、失败日志和未验证范围。
 
+### 编译型软件的分层验证
+
+- **把编译放到计算节点**：C++/HIP 大型构建的峰值内存可能远高于登录节点限额。
+  编译器进程被 OOM kill 时，先换到有明确内存配额的计算作业，不要立即归因于源码。
+- **只生成目标架构**：显式设置目标 `gfx` 架构。默认同时生成多个架构会成倍增加
+  编译时间、产物体积和峰值内存。
+- **升级工具链后重跑最小构建**：DTK/编译器升级可能改变 wrapper 头、host/device
+  编译模式或默认链接路径。保存 verbose compile command，与上一版本逐项比较。
+- **区分节点环境**：登录/CPU 节点可能加载得到 module，却缺少只在加速器节点完整
+  可见的 HSA/HIP 库或符号链接。以目标计算节点解析到的真实库文件为准，必要时通过
+  CMake cache 变量显式传入，不创建全局假链接。
+- **先串行能力、后并行能力**：先完成无 MPI 的单卡最小构建和功能验证，再开启 MPI，
+  最后测试 GPU-aware 通信与多卡扩展，避免把编译器、运行库和通信栈问题混在一起。
+
+### GPU-aware MPI 的验证边界
+
+系统 MPI 能启动多进程，不代表它带加速器感知能力。先记录 MPI 构建参数，并做
+GPU-aware on/off 对照。单节点验证可先固定共享内存与 self 传输，减少 UCX/IB
+站点配置带来的变量；这只能证明单节点路径，不能外推到跨节点通信。
+
+多卡扩展通常同时依赖足够大的问题规模、较高的计算/通信比以及可用的 GPU-aware
+路径。小问题或低计算密度任务扩展不佳，不足以单独证明硬件或 MPI 配置错误。
+
+### 数值与性能验收
+
+加速器移植至少应同时报告：CPU/参考实现的关键数值偏差、守恒量或长期稳定性、
+单卡问题规模扫描、固定规模的 1/2/单节点全卡强扩展、GPU-aware on/off 对照、
+峰值内存/显存，以及每项测试的退出码和完整日志。性能通过不能替代正确性验证。
+
 ### 已验证的典型边界
 
 - **gfx936 / BW1000**：Triton、硬件 FP8 `torch._scaled_mm`、部分 bitsandbytes INT8 路径可能不可用；纯 PyTorch 软件反量化可作为推理兜底，但需要单独做性能和精度验证。

package/skills/scnet-hpc/scripts/_common.sh

@@ -98,9 +98,17 @@ parse_cluster_arg() {
     REST=()
     while [ $# -gt 0 ]; do
         case "$1" in
-            --cluster) CLUSTER="${2:-}"; shift 2 ;;
+            --cluster)
+                [ $# -ge 2 ] || die "--cluster 缺少参数"
+                CLUSTER="$2"
+                shift 2
+                ;;
             --cluster=*) CLUSTER="${1#*=}"; shift ;;
             *) REST+=("$1"); shift ;;
         esac
     done
+    if [ -n "$CLUSTER" ]; then
+        [[ "$CLUSTER" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]] \
+            || die "集群短名包含不安全字符"
+    fi
 }

package/skills/scnet-hpc/scripts/compute-probe.py

@@ -104,11 +104,12 @@ try:
 except Exception:
     emit("NET_PYPI", "OFFLINE")
 
-# /tmp 是否跨节点共享无法只靠单节点可靠判断，这里只记录文件系统信息
+# 测试任务统一使用家目录中的 TMPDIR；记录实际路径，确认规则生效。
 try:
-    emit("TMP_FSTYPE", str(os.statvfs("/tmp").f_fsid))
+    tmp_dir = os.environ.get("TMPDIR", "")
+    emit("TMPDIR", tmp_dir)
+    emit("TMP_IN_HOME", "1" if tmp_dir and os.path.commonpath([os.path.expanduser("~"), tmp_dir]) == os.path.expanduser("~") else "0")
 except Exception as exc:
-    emit("TMP_FSTYPE", "ERR:" + short_error(exc))
-emit("TMP_SHARED", "UNKNOWN")
+    emit("TMPDIR", "ERR:" + short_error(exc))
 
 print("PROBE_EXIT=0", flush=True)

package/skills/scnet-hpc/scripts/new-job.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # 生成一个符合目标集群所有约束的作业脚本骨架。
 #
-#   ./new-job.sh [--cluster <集群短名>] <作业名> [加速器数] [cpu数] [时长]
+#   ./new-job.sh [--cluster <集群短名>] [--cpu-only] [--partition <分区>] \
+#     <作业名> [加速器数] [cpu数] [时长]
 #
 # 内存按 cpus × DEF_MEM_PER_CPU 自动取安全值，避免手算出错。
 
@@ -16,11 +17,16 @@ set -- "${REST[@]+${REST[@]}}"
 REMOTE_USER=""
 REFRESH=no
 USE_AUTO=yes
+CPU_ONLY=no
+PARTITION_OVERRIDE=""
 ARGS=()
 while [ $# -gt 0 ]; do
     case "$1" in
-        --user) REMOTE_USER="${2:-}"; shift 2 ;;
+        --user) [ $# -ge 2 ] || die "--user 缺少参数"; REMOTE_USER="$2"; shift 2 ;;
         --user=*) REMOTE_USER="${1#*=}"; shift ;;
+        --partition) [ $# -ge 2 ] || die "--partition 缺少参数"; PARTITION_OVERRIDE="$2"; shift 2 ;;
+        --partition=*) PARTITION_OVERRIDE="${1#*=}"; shift ;;
+        --cpu-only) CPU_ONLY=yes; shift ;;
         --refresh) REFRESH=yes; shift ;;
         --no-auto) USE_AUTO=no; shift ;;
         *) ARGS+=("$1"); shift ;;
@@ -35,17 +41,32 @@ TIME="${4:-00:20:00}"
 
 if [ -z "$NAME" ]; then
     cat >&2 <<EOF
-用法: $0 [--cluster <集群短名>] [--user <远端用户名>] [--refresh|--no-auto] <作业名> [加速器数] [cpu数] [时长]
+用法: $0 [--cluster <集群短名>] [--user <远端用户名>] [--cpu-only]
+       [--partition <分区>] [--refresh|--no-auto] <作业名> [加速器数] [cpu数] [时长]
 
 例子:
   $0 probe                    # 1 卡, 8 核, 20 分钟（探针）
   $0 infer 8 32 01:30:00      # 8 卡, 32 核, 1.5 小时（大模型）
+  $0 --cpu-only build 0 32 01:00:00  # 使用 profile 的 CPU 分区，不申请加速器
 
 可用集群: $(list_clusters | tr '\n' ' ')
 EOF
     exit 1
 fi
 
+[[ "$NAME" =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ ]] \
+    || die "作业名只允许 1-64 个字母、数字、点、下划线或连字符，且必须以字母或数字开头"
+[[ "$ACCEL" =~ ^[0-9]+$ ]] || die "加速器数必须是非负整数"
+[[ "$CPUS" =~ ^[1-9][0-9]*$ ]] || die "CPU 数必须是正整数"
+[[ "$TIME" =~ ^([0-9]+-)?[0-9]{1,2}:[0-9]{2}:[0-9]{2}$ ]] \
+    || die "时长格式应为 HH:MM:SS 或 D-HH:MM:SS"
+if [ -n "$REMOTE_USER" ]; then
+    [[ "$REMOTE_USER" =~ ^[A-Za-z0-9._-]+$ ]] || die "远端用户名包含不安全字符"
+fi
+if [ -n "$PARTITION_OVERRIDE" ]; then
+    [[ "$PARTITION_OVERRIDE" =~ ^[A-Za-z0-9._-]+$ ]] || die "分区名包含不安全字符"
+fi
+
 if [ "$REFRESH" = yes ]; then
     "$REPO_ROOT/scripts/refresh-cluster.sh" --cluster "${CLUSTER:-}"
 fi
@@ -56,6 +77,17 @@ load_cluster "$CLUSTER"
 [ "${SCHEDULER:-slurm}" = "slurm" ] \
     || die "暂只支持 slurm，${CLUSTER_ID} 用的是 ${SCHEDULER}"
 
+if [ "$CPU_ONLY" = yes ]; then
+    [ -n "${PARTITION_CPU:-}" ] \
+        || die "${CLUSTER_ID} profile 未定义 PARTITION_CPU，不能使用 --cpu-only"
+    EFFECTIVE_PARTITION="${PARTITION_OVERRIDE:-$PARTITION_CPU}"
+    ACCEL=0
+    [ -n "${DEF_MEM_PER_CPU_CPU:-}" ] && DEF_MEM_PER_CPU="$DEF_MEM_PER_CPU_CPU"
+else
+    EFFECTIVE_PARTITION="${PARTITION_OVERRIDE:-${PARTITION:-}}"
+fi
+[ -n "$EFFECTIVE_PARTITION" ] || die "目标分区为空，请补 profile 或使用 --partition"
+
 # 内存上限 = cpus × DEF_MEM_PER_CPU，留 1GB 余量避免边界抖动
 if [ -n "${DEF_MEM_PER_CPU:-}" ]; then
     MEM_MB=$(( CPUS * DEF_MEM_PER_CPU ))
@@ -70,15 +102,19 @@ fi
 
 # QOS 强制申请加速器时必须写 --gres
 GRES_LINE=""
-if [ -n "${GRES_TYPE:-}" ]; then
+if [ "$CPU_ONLY" != yes ] && [ -n "${GRES_TYPE:-}" ] && [ "$ACCEL" -gt 0 ]; then
     GRES_LINE="#SBATCH --gres=${GRES_TYPE}:${ACCEL}"
     [ -n "${MIN_GRES:-}" ] && GRES_LINE="$GRES_LINE          # 必须：QOS 要求最少 ${MIN_GRES}"
 fi
+if [ "$CPU_ONLY" != yes ] && [ -n "${MIN_GRES:-}" ] && [ "$ACCEL" -eq 0 ]; then
+    die "默认/指定分区要求至少 ${MIN_GRES}；请申请加速器或使用 --cpu-only"
+fi
 
 # 远端用户名。#SBATCH 是注释行，Slurm 不做变量展开 —— 日志路径里写 $USER
 # 会被当成字面量目录名，作业以 exit 53 失败且不产生日志。所以这里必须展开成
 # 真实用户名。默认取本地用户名，不同时用 --user 覆盖。
 REMOTE_USER="${REMOTE_USER:-${REMOTE_USER_DETECTED:-$(whoami)}}"
+[[ "$REMOTE_USER" =~ ^[A-Za-z0-9._-]+$ ]] || die "探测到的远端用户名包含不安全字符，请用 --user 显式指定"
 HOME_DIR="${HOME_BASE}/${REMOTE_USER}"
 
 # 脚本体（非 #SBATCH 行）里可以正常用 $USER
@@ -105,7 +141,7 @@ cat > "$OUT" <<EOF
 # shell 里定义，用普通 "#!/bin/bash" 会让 module load 静默失败 —— 作业照样
 # 返回 0，但 ROCM_PATH 不设置、rocminfo/rocm-smi 无输出。实测于昆山集群。
 #SBATCH --job-name=${NAME}
-#SBATCH --partition=${PARTITION}
+#SBATCH --partition=${EFFECTIVE_PARTITION}
 ${GRES_LINE}
 #SBATCH --nodes=1
 #SBATCH --ntasks-per-node=1
@@ -119,6 +155,13 @@ module purge
 ${MODULES}
 ${VENV_LINE}
 
+# 集群测试/作业的临时文件统一放共享家目录，不使用节点本地 /tmp。
+JOB_TMPDIR="${HOME_DIR}/.scnet-hpc/tmp/\${SLURM_JOB_ID:-manual-\$\$}"
+mkdir -p "\$JOB_TMPDIR"
+export TMPDIR="\$JOB_TMPDIR"
+export TMP="\$JOB_TMPDIR"
+export TEMP="\$JOB_TMPDIR"
+
 ${OFFLINE_LINES}
 
 echo "### node=\$(hostname) jobid=\$SLURM_JOB_ID"
@@ -146,7 +189,7 @@ sed -i.bak '/^$/N;/^\n$/D' "$OUT" 2>/dev/null && rm -f "$OUT.bak"
 
 echo "已生成 $OUT"
 echo "  集群=${CLUSTER_ID}  ${GRES_TYPE:-加速器}=${ACCEL}  CPU=${CPUS}  内存=${MEM_NOTE}  时长=${TIME}"
-echo "  分区=${PARTITION:-未设置}  节点数=${NODE_COUNT:-未探测}（来源：${NODE_COUNT_SOURCE:-profile/cache}）"
+echo "  分区=${EFFECTIVE_PARTITION}  模式=$([ "$CPU_ONLY" = yes ] && echo CPU || echo accelerator)  节点数=${NODE_COUNT:-未探测}（来源：${NODE_COUNT_SOURCE:-profile/cache}）"
 echo "  日志目录=${HOME_DIR}/scripts/logs（用户名 ${REMOTE_USER}，不对请加 --user）"
 echo
 echo "上传并提交："

package/skills/scnet-hpc/scripts/run-compute-probe.sh

@@ -19,21 +19,32 @@ PYTHON_BIN=""
 
 while [ $# -gt 0 ]; do
     case "$1" in
-        --cpus) CPUS="${2:-$CPUS}"; shift 2 ;;
+        --cpus) [ $# -ge 2 ] || die "--cpus 缺少参数"; CPUS="$2"; shift 2 ;;
         --cpus=*) CPUS="${1#*=}"; shift ;;
-        --time) TIME="${2:-$TIME}"; shift 2 ;;
+        --time) [ $# -ge 2 ] || die "--time 缺少参数"; TIME="$2"; shift 2 ;;
         --time=*) TIME="${1#*=}"; shift ;;
-        --accelerators) ACCEL="${2:-$ACCEL}"; shift 2 ;;
+        --accelerators) [ $# -ge 2 ] || die "--accelerators 缺少参数"; ACCEL="$2"; shift 2 ;;
         --accelerators=*) ACCEL="${1#*=}"; shift ;;
-        --user) REMOTE_USER="${2:-}"; shift 2 ;;
+        --user) [ $# -ge 2 ] || die "--user 缺少参数"; REMOTE_USER="$2"; shift 2 ;;
         --user=*) REMOTE_USER="${1#*=}"; shift ;;
-        --python) PYTHON_BIN="${2:-}"; shift 2 ;;
+        --python) [ $# -ge 2 ] || die "--python 缺少参数"; PYTHON_BIN="$2"; shift 2 ;;
         --python=*) PYTHON_BIN="${1#*=}"; shift ;;
         -h|--help) sed -n '2,10p' "$0" | sed 's/^# \?//'; exit 0 ;;
         *) die "未知参数: $1" ;;
     esac
 done
 
+[[ "$CPUS" =~ ^[1-9][0-9]*$ ]] || die "CPU 数必须是正整数"
+[[ "$ACCEL" =~ ^[1-9][0-9]*$ ]] || die "加速器数必须是正整数"
+[[ "$TIME" =~ ^([0-9]+-)?[0-9]{1,2}:[0-9]{2}:[0-9]{2}$ ]] \
+    || die "时长格式应为 HH:MM:SS 或 D-HH:MM:SS"
+if [ -n "$REMOTE_USER" ]; then
+    [[ "$REMOTE_USER" =~ ^[A-Za-z0-9._-]+$ ]] || die "远端用户名包含不安全字符"
+fi
+if [ -n "$PYTHON_BIN" ]; then
+    [[ "$PYTHON_BIN" =~ ^[A-Za-z0-9_./-]+$ ]] || die "Python 命令包含不安全字符"
+fi
+
 [ -n "${CLUSTER:-}" ] || die "请用 --cluster <集群短名> 指定集群。"
 load_cluster "$CLUSTER"
 
@@ -41,8 +52,10 @@ load_cluster "$CLUSTER"
 [ -n "${PARTITION:-}" ] || die "${CLUSTER_ID} 的 PARTITION 为空，无法提交计算节点探针。"
 
 REMOTE_USER="${REMOTE_USER:-${REMOTE_USER_DETECTED:-$(whoami)}}"
+[[ "$REMOTE_USER" =~ ^[A-Za-z0-9._-]+$ ]] || die "探测到的远端用户名包含不安全字符，请用 --user 显式指定"
 HOME_DIR="${HOME_BASE}/${REMOTE_USER}"
-PROBE_BASE="${HOME_DIR}/scnet-hpc-probe"
+PROBE_DIR="${HOME_DIR}/.scnet-hpc/probes"
+PROBE_BASE="${PROBE_DIR}/compute-probe"
 
 ssh_cmd() { ssh -o BatchMode=yes -o ConnectTimeout=20 -o ServerAliveInterval=15 -o ServerAliveCountMax=3 "$@"; }
 scp_cmd() { scp -o BatchMode=yes -o ConnectTimeout=20 "$@"; }
@@ -95,6 +108,13 @@ module purge
 ${MODULE_LINE}
 ${PYTHON_MODULE_LINE}
 ${VENV_LINE}
+
+# 探针临时文件必须位于共享家目录，不能使用计算节点本地 /tmp。
+JOB_TMPDIR="${HOME_DIR}/.scnet-hpc/tmp/\${SLURM_JOB_ID:-manual-\$\$}"
+mkdir -p "\$JOB_TMPDIR"
+export TMPDIR="\$JOB_TMPDIR"
+export TMP="\$JOB_TMPDIR"
+export TEMP="\$JOB_TMPDIR"
 export HF_HUB_OFFLINE=1
 export TRANSFORMERS_OFFLINE=1
 
@@ -115,7 +135,7 @@ echo "PROBE_EXIT=\$rc"
 exit \$rc
 EOF
 
-ssh_cmd "$CLUSTER_ID" "mkdir -p ${HOME_DIR}/scripts/logs"
+ssh_cmd "$CLUSTER_ID" "mkdir -p ${HOME_DIR}/scripts/logs ${PROBE_DIR} ${HOME_DIR}/.scnet-hpc/tmp"
 scp_cmd -q "$TMPDIR_LOCAL/compute-probe.py" "${CLUSTER_ID}:${PROBE_BASE}.py"
 scp_cmd -q "$TMPDIR_LOCAL/probe.slurm" "${CLUSTER_ID}:${PROBE_BASE}.slurm"
 
@@ -129,4 +149,4 @@ else
     printf '%s\n' "$ERR" >&2
 fi
 
-ssh_cmd "$CLUSTER_ID" "rm -f ${PROBE_BASE}.py ${PROBE_BASE}.slurm ${HOME_DIR}/scripts/logs/scnet-hpc-probe_${JOBID}.out ${HOME_DIR}/scripts/logs/scnet-hpc-probe_${JOBID}.err"
+ssh_cmd "$CLUSTER_ID" "rm -f ${PROBE_BASE}.py ${PROBE_BASE}.slurm ${HOME_DIR}/scripts/logs/scnet-hpc-probe_${JOBID}.out ${HOME_DIR}/scripts/logs/scnet-hpc-probe_${JOBID}.err; rm -rf ${HOME_DIR}/.scnet-hpc/tmp/${JOBID}"