dsh-scnet 0.3.0 → 0.4.1

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

@@ -0,0 +1,127 @@
+# 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.
+
+The repository scripts support Linux and macOS natively. On Windows, use WSL2; native Windows
+execution and Git Bash are not fully validated. This is separate from the official SCNet desktop
+client, which supports Windows 10+ and macOS 12 Monterey+.
+
+## 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/setup.md

@@ -3,7 +3,7 @@
 集群的主机名、端口等参数来自 `clusters/<集群短名>.conf`。
 本文用 `<集群>`、`<主机名>`、`<端口>` 表示从 profile 读出的值。
 
-## 手工配置（不用 setup-ssh.sh 时）
+## 手工配置
 
 ```bash
 # 1. 装私钥
@@ -42,14 +42,14 @@ Host <集群> <主机名>
   UpdateHostKeys no
 ```
 
-## 各选项的理由
+## SSH 选项说明
 
 **`ControlPersist 10m` 而非 `yes`**：永久驻留的 master 在笔记本休眠或换网络后会
-变成失效 socket，反而要手工清理。10 分钟覆盖一次交互操作的节奏，又能自然回收。
+变成失效 socket，可能留下需要清理的失效 socket。10 分钟覆盖一次交互操作的节奏，又能自然回收。
 实测复用后单条命令从约 2 秒降到 0.57 秒。
 
 **`ServerAliveInterval 60`**：应用层心跳，防止空闲 SSH 会话被中间网关静默切断。
-跑长任务时关键。`TCPKeepAlive` 是 TCP 层的，两者互补。
+用于保持长时间空闲会话。`TCPKeepAlive` 是 TCP 层的，两者互补。
 
 **`UpdateHostKeys no`**：部分平台的服务端对主机密钥轮换扩展返回错误签名：
 
@@ -57,9 +57,7 @@ Host <集群> <主机名>
 client_global_hostkeys_prove_confirm: server gave bad signature for RSA key 0
 ```
 
-这是平台侧实现问题，不影响安全性——首次记录的主机密钥仍在正常校验。关掉只为消除
-告警噪音。**只在遇到这个告警的集群上加**（profile 里标
-`NEEDS_UPDATE_HOSTKEYS_NO=yes`）。
+该设置仅禁用服务端主机密钥轮换扩展；首次主机密钥仍按正常流程校验。仅在出现该告警且 profile 标记 `NEEDS_UPDATE_HOSTKEYS_NO=yes` 的集群上使用。
 
 **`IdentitiesOnly yes`**：只用指定的私钥。ssh-agent 里密钥多时，避免因尝试次数
 过多被服务端拒绝。
@@ -91,7 +89,7 @@ profile 里的 `KEY_NAME_MARKER` 就是用来从这种文件名里提取用户
 `scnet-hpc` profile 使用 `_<CLUSTER_HOST>_` 占位符，所以安装时通常需要显式传
 用户名，或在本地私有 profile 中补齐真实标记。
 
-查看当前密钥指纹：
+查看密钥指纹：
 
 ```bash
 ssh-keygen -lf ~/.ssh/id_rsa_<集群>
@@ -113,7 +111,7 @@ ssh-keygen -p -f ~/.ssh/id_rsa_<集群>
 | `Connection timed out` | 端口被本地网络阻断（超算常用非 22 端口）|
 | `Bad owner or permissions on config` | `chmod 600 ~/.ssh/config` |
 | `WARNING: UNPROTECTED PRIVATE KEY` | `chmod 600 ~/.ssh/id_rsa_<集群>` |
-| 首次连接卡住不动 | 在等确认主机指纹，加 `-o StrictHostKeyChecking=accept-new` |
+| 首次连接等待主机指纹确认 | 在等确认主机指纹，加 `-o StrictHostKeyChecking=accept-new` |
 
 多数超算平台有 **IP 白名单**，换网络（家里/公司/热点）后可能连不上，
 需要去控制台加当前 IP。
@@ -125,7 +123,7 @@ ssh -o BatchMode=yes <集群> '<命令>'
 ```
 
 `BatchMode=yes` 让认证失败立刻返回，而不是卡在密码提示上等输入。写自动化脚本时
-必加，否则可能挂住。
+应启用，以避免自动化流程等待交互输入。
 
 ## 文件传输
 
@@ -135,4 +133,4 @@ scp <集群>:/public/home/$USER/scripts/logs/job_123.log .
 rsync -avz --progress ./dir/ <集群>:/public/home/$USER/dir/   # 大量文件
 ```
 
-走同一个长连接，不需额外配置端口。
+上述命令复用 SSH profile 中的连接参数。

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

@@ -8,9 +8,38 @@
 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 软件反量化可作为推理兜底，但需要单独做性能和精度验证。
+- **gfx936 / BW1000**：Triton、硬件 FP8 `torch._scaled_mm`、部分 bitsandbytes INT8 路径可能不可用；纯 PyTorch 软件反量化可作为兼容路径，但需要单独做性能和精度验证。
 - **gfx906 / Z100**：CentOS 7.6 的 glibc 2.17 会限制 manylinux wheel 版本；安装 Python 软件时优先选 manylinux2014 / manylinux_2_17 兼容包。MinerU 场景中，Python 3.10 + onnxruntime 1.16.3 是已验证方向，magika 版本/API 需要随源码适配。
 - **GROMACS HIP**：先验证 CMake 最低版本、DTK 的 `lib`/`lib64` CMake 路径、目标架构、FFTW 预置和 SIMD；CUDA 兼容层与原生 HIP 的性能不可直接互相推断。
 
@@ -26,18 +55,18 @@ echo "test_exit_code=$rc"
 exit "$rc"
 ```
 
-不要只看 `sacct` 的 `COMPLETED`。脚本必须显式传递最后一个测试命令的退出码，并同时读取 `.out/.err`。
+不能只依据 `sacct` 的 `COMPLETED` 判定成功。脚本必须显式传递最后一个测试命令的退出码，并同时读取 `.out/.err`。
 
 ### 公开报告模板
 
-标题采用“项目 + 加速器/平台 + 编译与性能/兼容性测试报告”。正文建议按以下顺序：
+标题采用“项目 + 加速器/平台 + 编译与性能/兼容性测试报告”。正文可按以下顺序：
 
 1. 环境信息
 2. 编译过程与主要难题
 3. 最终方案与验证结果
 4. 测试数据与资源占用
 5. 已知限制与注意事项
-6. 经验总结与通用建议
+6. 适用范围与可复用结论
 7. 附录：快速复现命令
 
 发布前扫描：

package/skills/scnet-hpc/references/troubleshooting.md

@@ -1,6 +1,6 @@
 # 排查作业失败
 
-## 第一原则：不要相信 `sacct` 的 State
+## 作业状态与实际退出码
 
 bash 脚本里 Python 崩了之后，bash 继续执行后面的行，作业以**最后一条命令**的退出码
 结束。真实案例：
@@ -10,10 +10,10 @@ $ sacct -j <JOB_ID> --format=JobID,JobName,State,ExitCode,Elapsed
 <JOB_ID> | example-job | COMPLETED | 0:0 | 00:34:32
 ```
 
-看着完美，实际上 Python 在第 3 分钟就抛了 `ValueError`，日志末尾还打印了脚本里
+该记录不能证明 Python 工作负载成功。Python 可能已在第 3 分钟抛出 `ValueError`，而日志末尾仍打印脚本中
 写的 `===== COMPLETE =====`。
 
-**排查顺序永远是：读日志 → 看 State，不是反过来。**
+排查时先读取日志和工作负载退出码，再结合调度器 State 判断。
 
 预防：脚本末尾写
 
@@ -43,7 +43,7 @@ sbatch: error: min tres(gres/dcu) request 0 exceeds per-job max tres limit 1
 sbatch: error: QOSMinGRES
 ```
 
-忘了 `--gres=dcu:N`。这个分区**强制**每个作业至少 1 张 DCU，纯 CPU 作业也要写。
+该分区要求每个作业至少申请 1 张 DCU。补充 `--gres=dcu:N`；纯 CPU 负载也受该分区策略约束。
 
 ### `too much memory was requested relative to the number of CPUs`
 
@@ -82,7 +82,7 @@ httpcore.ConnectError: [Errno -2] Name or service not known
 ### `cannot get address for 'hipDrvLaunchKernelEx' from libamdhip64.so`
 
 Triton。DTK 26.04 的 HIP 运行时缺上游 ROCm 7 的 API，Triton 的 AMD backend 加载
-即失败。**放弃这条路**，包括所有依赖 Triton kernel 的框架（SGLang FP8、vLLM ROCm
+即失败。该软件栈不能使用此 Triton 路径，依赖对应 Triton kernel 的框架也不适用（SGLang FP8、vLLM ROCm
 MoE、transformers finegrained-fp8）。
 
 郑州集群最近还会先报另一种缺库：
@@ -91,7 +91,7 @@ MoE、transformers finegrained-fp8）。
 ImportError: libgcvm.so.17git: cannot open shared object file
 ```
 
-本质相同，都是 Triton 在当前 DTK/DCU 软件栈上不可用，不要继续调 Triton kernel。
+本质相同，都是 Triton 在当前 DTK/DCU 软件栈上不可用，继续调整 Triton kernel 参数不能解决该运行时缺失。
 
 ### `torch._scaled_mm is only supported on CUDA devices with compute capability >= 9.0 or 8.9, or ROCm MI300+`
 
@@ -114,7 +114,7 @@ cat: No such file or directory        ← 连日志都没有，因为写不进
 1. `--output` / `--error` 路径里有未展开的变量（`$USER`、`$HOME`）
 2. **日志目录不存在** —— Slurm 不会自动创建
 
-修法：`#SBATCH` 里写完整字面量路径，提交前 `mkdir -p <日志目录>`。
+处理方法：`#SBATCH` 里写完整字面量路径，提交前 `mkdir -p <日志目录>`。
 `scripts/new-job.sh` 会展开好用户名并提示建目录。
 
 ### `module load` 静默失败：作业返回 0 但 `ROCM_PATH` 没设置
@@ -129,9 +129,9 @@ ROCM_PATH=未设置
 ### python exit=0      ← 作业「成功」了
 ```
 
-这比直接报错更坑，因为退出码是 0。实测于昆山集群。
+该现象可能返回退出码 0，因此还需检查模块环境变量和探针输出。该行为已在昆山集群观测。
 
-修法：shebang 用 `#!/bin/bash -l`，或在 heredoc 内包一层 `bash -l`。
+处理方法：shebang 用 `#!/bin/bash -l`，或在 heredoc 内包一层 `bash -l`。
 `scripts/new-job.sh` 生成的脚本已经用 `bash -l`。
 
 自检：作业里打印 `echo "ROCM_PATH=${ROCM_PATH:-未设置}"`，未设置就说明没生效。
@@ -145,7 +145,7 @@ ROCM_PATH=未设置
 SyntaxError: Non-ASCII character '\xe5' ... no encoding declared
 ```
 
-修法：作业脚本里显式加载 Python 3 module：
+处理方法：作业脚本里显式加载 Python 3 module：
 
 ```bash
 module load python/3.8.10
@@ -186,7 +186,7 @@ for i in range(torch.cuda.device_count()):
 
 ### 作业一直 `PD (Priority)` 不动
 
-排队等资源，正常现象。看预计启动时间：
+该状态表示等待调度资源。查询预计启动时间：
 
 ```bash
 squeue -j <ID> --start
@@ -197,15 +197,14 @@ sinfo -p <分区> -o "%n %t"           # 有几台 idle
 
 ## 调试策略
 
-**验证要便宜。** 大模型加载动辄半小时，用大作业试错代价太高。分层验证：
+按成本递增的顺序执行验证，避免使用完整模型诊断基础环境问题：
 
 1. **纯逻辑**（不需要 GPU/torch）→ 本地 Python 直接跑
 2. **需要 torch/DCU 但数据量小** → `srun` 交互式，约 5 秒拿到节点
 3. **小规模真实数据** → 2 分钟的 `sbatch` 探针作业
 4. **完整模型** → 最后才做
 
-真实教训：DeepSeek V4 的反量化实现，先写 16 项单元测试（2 分钟作业）验证数值正确，
-再跑完整模型。如果跳过第 3 步直接跑，每轮试错 30 分钟。
+例如，反量化实现应先通过小规模数值测试，再运行完整模型。
 
 **探针作业模板**：只读 metadata 不加载权重，几秒就出结果：
 
@@ -222,11 +221,11 @@ with safe_open(path, framework="pt", device="cpu") as f:
 # 作业跑在哪个节点
 squeue -j <ID> -o "%N"
 
-# 登到那个节点看进程（作业运行期间可以）
+# 在作业运行期间检查目标节点进程
 ssh <节点名> 'top -b -n1 -u $USER | head -20'
 
 # GPU 占用
 srun --jobid=<ID> --overlap rocm-smi
 ```
 
-`--overlap` 让新的 srun 步骤共享已有作业的资源分配，不用重新排队。
+`--overlap` 让新的 srun 步骤共享已有作业的资源分配，避免为诊断步骤重新申请一份资源。

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/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
@@ -101,11 +137,11 @@ cat > "$OUT" <<EOF
 #!/bin/bash -l
 # 目标集群: ${CLUSTER_ID} (${CLUSTER_DESC:-$SSH_HOST})
 #
-# 注意 shebang 是 "bash -l"（login shell）。有些集群的 module 函数只在 login
-# shell 里定义，用普通 "#!/bin/bash" 会让 module load 静默失败 —— 作业照样
-# 返回 0，但 ROCM_PATH 不设置、rocminfo/rocm-smi 无输出。实测于昆山集群。
+# 使用 "bash -l"，因为部分集群仅在 login
+# shell 中定义 module 函数。普通 "#!/bin/bash" 可能使 module load 静默失败，作业仍
+# 返回 0，但 ROCM_PATH 未设置且能力工具无输出。该行为已在昆山集群观测。
 #SBATCH --job-name=${NAME}
-#SBATCH --partition=${PARTITION}
+#SBATCH --partition=${EFFECTIVE_PARTITION}
 ${GRES_LINE}
 #SBATCH --nodes=1
 #SBATCH --ntasks-per-node=1
@@ -142,7 +178,7 @@ PYEOF
 rc=\$?
 echo "### python exit=\$rc"
 date +"%Y-%m-%d %H:%M:%S"
-# 必须传播退出码，否则 python 崩了 sacct 仍显示 COMPLETED（假成功）
+# 传播工作负载退出码，避免调度器状态掩盖 Python 失败
 exit \$rc
 EOF
 
@@ -153,11 +189,11 @@ 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 "上传并提交："
 echo "  scp $OUT ${CLUSTER_ID}:${HOME_DIR}/scripts/"
 echo "  ssh ${CLUSTER_ID} 'mkdir -p ${HOME_DIR}/scripts/logs && sbatch --test-only ${HOME_DIR}/scripts/$OUT'"
 echo
-echo "注意：logs 目录必须先存在，否则作业会以 exit 53 失败且不产生任何日志。"
+echo "要求：logs 目录必须先存在；否则作业会以 exit 53 失败且不产生日志。"

package/skills/scnet-hpc/scripts/refresh-cluster.sh

@@ -208,7 +208,7 @@ if [ "$COMPUTE" = yes ] && [ -n "$COMPUTE_OUT" ]; then
         IMPORT_ERR:*) KNOWN_LIMITS_NEW="${KNOWN_LIMITS_NEW:+${KNOWN_LIMITS_NEW}；}bitsandbytes 导入失败（${BNB}）" ;;
     esac
 
-    # 保留 profile 里已有的人工经验，动态结果放前面。
+    # 保留 profile 中已有的人工验证结论，并将动态结果置于前面。
     if [ -n "${KNOWN_LIMITATIONS:-}" ]; then
         OLD_IFS="$IFS"
         IFS='；'

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,6 +52,7 @@ 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_DIR="${HOME_DIR}/.scnet-hpc/probes"
 PROBE_BASE="${PROBE_DIR}/compute-probe"