dsh-scnet 0.4.0 → 0.4.1

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

@@ -11,7 +11,7 @@
 ### 编译型软件的分层验证
 
 - **把编译放到计算节点**：C++/HIP 大型构建的峰值内存可能远高于登录节点限额。
-  编译器进程被 OOM kill 时，先换到有明确内存配额的计算作业，不要立即归因于源码。
+  编译器进程被 OOM kill 时，先换到有明确内存配额的计算作业，先排除资源限制，再判断源码问题。
 - **只生成目标架构**：显式设置目标 `gfx` 架构。默认同时生成多个架构会成倍增加
   编译时间、产物体积和峰值内存。
 - **升级工具链后重跑最小构建**：DTK/编译器升级可能改变 wrapper 头、host/device
@@ -20,7 +20,7 @@
   可见的 HSA/HIP 库或符号链接。以目标计算节点解析到的真实库文件为准，必要时通过
   CMake cache 变量显式传入，不创建全局假链接。
 - **先串行能力、后并行能力**：先完成无 MPI 的单卡最小构建和功能验证，再开启 MPI，
-  最后测试 GPU-aware 通信与多卡扩展，避免把编译器、运行库和通信栈问题混在一起。
+  最后测试 GPU-aware 通信与多卡扩展，以隔离编译器、运行库和通信栈问题。
 
 ### GPU-aware MPI 的验证边界
 
@@ -39,7 +39,7 @@ GPU-aware on/off 对照。单节点验证可先固定共享内存与 self 传输
 
 ### 已验证的典型边界
 
-- **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 的性能不可直接互相推断。
 
@@ -55,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/new-job.sh

@@ -137,9 +137,9 @@ 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=${EFFECTIVE_PARTITION}
 ${GRES_LINE}
@@ -178,7 +178,7 @@ PYEOF
 rc=\$?
 echo "### python exit=\$rc"
 date +"%Y-%m-%d %H:%M:%S"
-# 必须传播退出码，否则 python 崩了 sacct 仍显示 COMPLETED（假成功）
+# 传播工作负载退出码，避免调度器状态掩盖 Python 失败
 exit \$rc
 EOF
 
@@ -196,4 +196,4 @@ 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='；'