dsh-scnet 0.4.0 → 0.4.2

package/skills/scnet-hpc/SKILL.md

@@ -1,269 +1,111 @@
 ---
 name: scnet-hpc
-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.
+description: Configure and operate SCNet HPC clusters through SSH and Slurm, including profile-based resource requests, job submission and diagnosis, environment preparation, and accelerator compatibility checks. Use for SCNet access, Slurm CPU/DCU jobs, Hygon DCU/DTK, offline compute nodes, or adding and verifying cluster profiles. Treat other accelerator platforms as unverified until tested on their target compute nodes.
 ---
 
-# 国产超算集群使用规范
+# SCNet HPC
 
-面向超算互联网（SCNet）系列集群，当前收录节点以海光 DCU 为主。其他芯片平台
-只复用连接、调度和验证方法，不套用海光工具链结论。**集群参数不写在文档里，存在
-`clusters/<集群短名>.conf`**，脚本从 profile 读取，所以同一套流程能用于多个集群。
+Operate SCNet clusters from repository profiles and target-cluster evidence. The included
+accelerator guidance is validated primarily for Hygon DCU/DTK and `gfx9xx`; do not transfer
+those capability conclusions to other accelerator stacks. The repository scripts support Linux
+and macOS natively. On Windows, use WSL2; native Windows execution is not supported.
 
-## 先确认在跟哪个集群打交道
+## 中文说明
 
-```bash
-ls clusters/*.conf              # 有哪些集群
-cat clusters/<集群短名>.conf     # 看具体参数
-```
-
-回答用户关于内存上限、分区名、硬件规格的问题时，**读 profile，不要凭记忆**。
-不同集群的 `DEF_MEM_PER_CPU`、`PARTITION`、`MIN_GRES` 都不一样。
-
-| 文件 | 用途 |
-|---|---|
-| `clusters/*.conf` | 每个集群一个 profile（连接、调度器、硬件、已知问题）|
-| `clusters/_template.conf` | 新增集群的模板 |
-| `scripts/setup-ssh.sh` | 新电脑上配连接（macOS/Linux，幂等）|
-| `scripts/probe-cluster.sh` | 探测新集群，自动生成 profile |
-| `scripts/refresh-cluster.sh` | 动态刷新已有集群的规则缓存 |
-| `scripts/run-compute-probe.sh` | 在计算节点运行最小能力探针 |
-| `scripts/new-job.sh` | 按 profile 生成合规的作业脚本 |
-| `references/setup.md` | 连接配置详解、平台差异、故障排查 |
-| `references/environment.md` | 环境栈、装依赖、目录约定、迁移注意 |
-| `references/troubleshooting.md` | 排查手册、调试策略 |
-| `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` 为准，不从英文示例猜测。
-
-## 换机器
-
-本插件已随 DeepSeek Harness 安装，换机器时用 `dsh plugin --profile web add dsh-scnet` 重装即可。
-配置集群连接：
-
-```bash
-./scripts/setup-ssh.sh --cluster <集群短名> <私钥文件> <用户名>
-```
-
-只有一个 profile 时可省略 `--cluster`；公开 profile 里的 `KEY_NAME_MARKER` 是占位符，所以需要显式传用户名。
-## 新增集群
-
-```bash
-# 1. 手工确认能 ssh 上去（用平台给的私钥）
-# 2. 探测，自动填大部分字段
-./scripts/probe-cluster.sh <ssh别名> <集群短名> > clusters/<集群短名>.conf
-# 3. 补齐探测不到的项（加速器型号、module 名等），profile 里有提示
-```
-
-完整步骤见 `references/adding-cluster.md`。
-
-## 动态刷新已有集群规则
-
-profile 里的 `SSH_HOST` / `SSH_PORT` 是固定连接参数，应写死在
-`clusters/<集群短名>.conf`。其余容易随平台调整的规则
-（`DEF_MEM_PER_CPU`、`MIN_GRES`、`PARTITION`、`NET_OK`、登录节点缺库等）
-可以动态探测：
-
-```bash
-./scripts/refresh-cluster.sh --cluster <集群短名>          # 只做登录节点只读探测
-./scripts/refresh-cluster.sh --cluster <集群短名> --compute # 再提交一个 10 分钟小作业
-./scripts/refresh-cluster.sh --cluster <集群短名> --dry-run  # 只看结果，不写缓存
-```
-
-结果写到 `clusters/.cache/<集群短名>.auto.conf`，后续脚本会自动加载并覆盖
-profile 中的同名字段。删除该缓存文件即可回退到纯 profile。生成作业时可用
-`./scripts/new-job.sh --refresh ...` 先刷新再生成，或用 `--no-auto` 忽略缓存。
-
-默认只做登录节点探测，不提交作业；`--compute` 才会到计算节点实测加速器架构、
-FP8、Triton、bitsandbytes 和外网状态。
-
-分区节点数 `NODE_COUNT` 是例外：每次加载集群时都会实时查询当前
-`PARTITION` 的 `TotalNodes`，查不到才回退到 cache/profile。需要关闭时设
-`SCNET_HPC_LIVE_NODE_COUNT=no`。
-
-## 通用硬约束
-
-以下几条在国产超算上普遍存在，**具体数值查 profile**。
-
-### 1. 可能强制申请加速器
-
-若 profile 里 `MIN_GRES` 非空，该集群的 QOS 强制每个作业至少申请那么多加速器，
-**纯 CPU 作业会被拒**：
-
-```
-sbatch: error: min tres(gres/dcu) request 0 exceeds per-job max tres limit 1
-sbatch: error: QOSMinGRES
-```
-
-哪怕作业根本不用 GPU（比如只读文件的探针），也要写 `--gres=<GRES_TYPE>:1`。
-
-### 2. 内存上限 = `cpus-per-task × DEF_MEM_PER_CPU`
-
-超了直接被拒（`too much memory was requested relative to the number of CPUs`）。
-**要更多内存只能加 CPU 核数。**
-
-用 `scripts/new-job.sh` 生成脚本可避免手算。以 `DEF_MEM_PER_CPU=3888` 为例：
-
-| `--cpus-per-task` | 上限 | 安全写法 |
-|---|---|---|
-| 8 | 30.38 GB | `--mem=30gb` |
-| 16 | 60.75 GB | `--mem=60gb` |
-| 32 | 121.50 GB | `--mem=121gb` |
-
-注意 `--mem` 只是请求量，cgroup 实际按 `cpus × DEF_MEM_PER_CPU` 给
-——所以 `MaxRSS` 可能超过你写的 `--mem` 值。
-
-### 3. 登录节点可能无法 import 深度学习框架
-
-若 profile 的 `LOGIN_NODE_MISSING_LIBS` 非空，登录节点缺那些库，
-即使 `module load` 之后也 import 不了：
-
-```
-ImportError: libmsgpackc.so.2: cannot open shared object file
-```
-
-**不要在登录节点试 torch 代码然后困惑为什么报错。** 哪怕只想看一眼 tensor 的
-dtype，也要走 `srun` 或 `sbatch`。
-
-登录节点通常用于 `git`、文件管理、`sacct`/`squeue` 和准备依赖；能否访问软件源、
-下载模型或执行 `pip install` 必须查看 profile 的网络字段并现场确认。
+本技能用于通过 SSH 和 Slurm 操作 SCNet 超算集群，覆盖基于 profile 的资源申请、作业生成与诊断、环境准备，以及加速器兼容性验证。Linux 和 macOS 可直接运行仓库脚本；Windows 不提供原生脚本入口，建议使用 WSL2。官方 SCNet 客户端支持 Windows 10 及以上、macOS 12 Monterey 及以上（ARM/x86），下载地址见 [SCNet 客户端下载页](https://www.scnet.cn/ui/mall/client/download)。
 
-### 4. 计算节点通常无外网 —— 依赖必须预装
+## Source of truth
 
-profile 的 `NET_OK` / `NET_BLOCKED` 记录了登录节点的可达情况。计算节点若
-`COMPUTE_NODE_OFFLINE=yes` 则完全无外网。
+- Read `clusters/<cluster>.conf` before reporting connection, partition, memory, hardware,
+  module, network, or known-limit information.
+- Treat `clusters/.cache/<cluster>.auto.conf` as optional, time-sensitive probe data that
+  overrides matching profile fields.
+- Verify dynamic scheduler state on the target cluster when the task depends on current
+  availability, limits, or node count.
+- Do not infer one cluster's parameters from another cluster.
 
-任何**运行时从网上拉东西**的库都会在计算节点炸掉。典型的是 `transformers` 的
-`kernels` 机制（从 HF Hub 下载预编译 kernel）。作业脚本里先声明离线，
-让失败快速且信息明确：
+List available profiles with:
 
 ```bash
-export HF_HUB_OFFLINE=1
-export TRANSFORMERS_OFFLINE=1
+ls clusters/*.conf
 ```
 
-### 5. 测试任务的临时目录必须建在家目录
-
-针对任何集群提交测试或探针任务时，**不要使用 `/tmp`，也不要从根目录下创建临时
-目录**。统一在共享家目录中创建，例如 `$HOME/.scnet-hpc/tmp/$SLURM_JOB_ID`，并在
-作业中导出 `TMPDIR`、`TMP`、`TEMP` 指向该目录。这样登录节点、计算节点和后续作业
-都能访问同一份临时文件。任务结束后只清理本次作业自己的子目录。
-
-`TMP_SHARED=no` 表示系统 `/tmp` 不作为跨节点共享路径使用；即使某个集群实测 `/tmp`
-可见，测试脚本仍默认遵循上述家目录规则。
-
-### 6. 先验证二进制兼容性，再做完整安装
-
-遇到 Python/C++/GPU 软件安装问题时，先确认系统 ABI、manylinux 标签、编译器/DTK 版本和运行节点网络条件，再选择版本。不要只根据 pip/conda 能否解析依赖判断可用性；必须在目标计算节点完成最小 import、kernel、功能和端到端验证。
-
-## 提交作业
-
-```bash
-./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
-```
+If more than one profile exists, require an explicit cluster selection before generating a
+job, changing SSH configuration, submitting work, or installing software.
 
-有独立 CPU 分区时使用 `--cpu-only`，脚本读取 `PARTITION_CPU` 并省略 `--gres`；
-临时指定其他分区时使用 `--partition <名称>`。
-
-上传后先验证配额而不真排队：
-
-```bash
-ssh <集群> 'sbatch --test-only <脚本路径>'
-```
-
-返回 `Job N to start at <时间>` 表示配额合法；`Requested node configuration is
-not available` 是当前无空闲节点（配额没问题）；`too much memory` 才是超配额。
-
-### ★ 作业脚本末尾必须写 `exit $rc`
-
-**这是最容易被骗的地方。** bash 里 Python 崩了之后 bash 继续执行后面的行，
-作业以最后一条命令的退出码结束：
-
-```
-$ sacct -j <JOB_ID>
-<JOB_ID> | example-job | COMPLETED | 0:0 | 00:34:32     ← 可能是假的！
-```
+## Route the task
 
-而日志里 Python 早就抛异常了，甚至还打印了脚本末尾的 "COMPLETE" 字样。
+Read only the references required for the current operation:
 
-**判断作业成功不能只看 `sacct` 的 State，必须读日志。**
-
-## 交互式调试（推荐）
-
-通常比反复提交完整作业更适合试代码、查环境和验证假设；实际排队时间取决于分区负载：
-
-```bash
-srun -p <分区> --gres=<类型>:1 --cpus-per-task=8 --mem=30gb --time=00:10:00 \
-  bash -lc 'module load <模块>
-    source ~/<venv>/bin/activate
-    python3 -c "import torch; print(torch.__version__)"'
-
-# 交互 shell
-srun -p <分区> --gres=<类型>:1 --cpus-per-task=8 --mem=30gb \
-  --time=00:30:00 --pty bash
-```
-
-节点忙时会排队，可以 Ctrl-C 放弃改用 sbatch。
-
-**调试策略**：先用 2 分钟的小探针确认假设，再提交几十分钟的大作业。大模型加载
-动辄半小时，靠大作业试错代价太高。分层验证见 `references/troubleshooting.md`。
-
-## 常用命令
-
-```bash
-squeue -u $USER                      # 我的队列
-squeue -j <ID> --start               # 预计启动时间
-sacct -j <ID> --format=JobID,State%14,ExitCode,Elapsed,MaxRSS -P
-scancel <ID>
-sinfo -p <分区> -o "%n %c %m %G %t"   # 节点资源和状态
-```
-
-`MaxRSS` 只在作业结束后、且只在 `.batch` 子步骤那行有值。节点状态里
-`drain`/`drng` 不可调度，实际可用常少于总数。
-
-## 加速器能力边界
-
-用户询问海光开发环境、HIP、数学库、通信库、性能分析、CUDA 迁移或容器部署时，
-先读 `references/hygon-dcu-development.md`。用它定位官方资料，再以目标集群的
-module、计算节点探针和 profile 为准；不要把网页当前版本直接覆盖到集群环境。
-
-**不要假设加速器支持什么。** 即使同属 SCNet，不同芯片、DTK/驱动和框架版本的
-能力也可能不同。先读取目标 profile 的 `KNOWN_LIMITATIONS`，再用计算节点探针验证
-设备枚举、dtype、kernel、通信和真实功能。海光 DCU/DTK 的开发资料入口见
-`references/hygon-dcu-development.md`；软件兼容性验证顺序见
-`references/software-compatibility.md`。
-
-## 排查失败
-
-1. **先读日志，不要相信 `sacct` 的 State**
-2. `.err` 被 `Loading weights: ...%` 进度条刷屏时，`grep -v` 过滤掉再看
-3. 按报错分类：
-
-| 报错 | 原因 |
+| Operation | Reference |
+|---|---|
+| Configure or repair SSH access | `references/setup.md` |
+| Prepare Python, modules, virtual environments, or offline dependencies | `references/environment.md` |
+| Diagnose Slurm, runtime, library, network, or accelerator failures | `references/troubleshooting.md` |
+| Add or refresh a cluster profile | `references/adding-cluster.md` |
+| Work with Hygon DCU, DTK, HIP libraries, profiling, migration, or containers | `references/hygon-dcu-development.md` |
+| Evaluate software compatibility or prepare a public compatibility report | `references/software-compatibility.md` |
+| Provide English operating instructions | `references/quickstart-en.md` |
+
+Cluster parameters always come from the selected profile, including when an example in a
+reference uses different values.
+
+## Execution boundaries
+
+- Read-only inspection and local script generation do not authorize SSH configuration changes,
+  dependency installation, job submission, job cancellation, or remote file deletion.
+- Before a remote mutation, resolve the target cluster, command, paths, and expected effect.
+- A compute-node probe consumes scheduler resources. Run it only when the user requests
+  submission or verification that requires compute-node evidence.
+- Preserve existing SSH configuration. `scripts/setup-ssh.sh` adds a missing host entry and
+  backs up a conflicting destination key; it does not rewrite an existing host block.
+- Do not place credentials, usernames, internal hosts, node names, job IDs, private mirrors, or
+  absolute home paths in committed profiles or public reports.
+
+## Operational invariants
+
+1. **Scheduler constraints are profile-specific.** If `MIN_GRES` is non-empty, request at least
+   that accelerator resource unless an independent CPU partition is selected.
+2. **Memory requests follow the partition limit.** When `DEF_MEM_PER_CPU` is defined, keep
+   requested memory within `cpus-per-task × DEF_MEM_PER_CPU`. Use `scripts/new-job.sh` to
+   calculate a conservative value.
+3. **Framework validation belongs on compute nodes.** A login node may lack accelerator
+   libraries even after modules are loaded. Use `srun`, `sbatch`, or the compute probe for
+   imports, kernels, collectives, and accelerator capabilities.
+4. **Offline nodes require staged dependencies.** When `COMPUTE_NODE_OFFLINE=yes`, download or
+   build dependencies on a networked node and disable runtime downloads in the job.
+5. **Test files use shared storage.** Create per-job temporary directories under
+   `$HOME/.scnet-hpc/tmp/$SLURM_JOB_ID`; do not depend on `/tmp` being shared across nodes.
+6. **Job exit status must propagate.** Capture the workload return code and terminate the batch
+   script with `exit "$rc"`. Evaluate both accounting state and job logs.
+7. **Compatibility claims require target-node evidence.** Package resolution or import success
+   alone is insufficient for native extensions and accelerator software. Validate the relevant
+   ABI, import, kernel, functional, and end-to-end layers.
+
+## Repository tools
+
+| Tool | Purpose |
 |---|---|
-| `QOSMinGRES` | 忘了 `--gres` |
-| `too much memory` | 违反 `cpus × DEF_MEM_PER_CPU` |
-| `lib*.so: cannot open shared object file` | 没 `module load`，或在登录节点跑了 |
-| `Name or service not known` / `offline mode` | 计算节点在访问外网 |
-| `hipDrvLaunchKernelEx` | Triton 不可用，换纯 PyTorch 路线 |
-| `libgcvm.so.17git: cannot open shared object file` | Triton 在当前 DTK/DCU 栈不可用 |
-| `python3: command not found` | 昆山计算节点需 `module load python/3.8.10` |
-| `sacct` COMPLETED 但结果不对 | 脚本缺 `exit $rc` |
+| `scripts/setup-ssh.sh` | Install a supplied key and add an SSH host entry |
+| `scripts/new-job.sh` | Generate a profile-aware Slurm script |
+| `scripts/probe-cluster.sh` | Produce an initial profile from read-only login-node probes |
+| `scripts/refresh-cluster.sh` | Refresh dynamic profile fields; compute probing is opt-in |
+| `scripts/run-compute-probe.sh` | Submit a minimal accelerator capability probe |
 
-完整手册见 `references/troubleshooting.md`。
+Use `scripts/new-job.sh --cluster <name> ...` for routine job generation. Validate the generated
+script with `sbatch --test-only` before submission when the target cluster supports it.
 
-## 公开报告与知识沉淀
+## Evidence and reporting
 
-将集群实测结果写入公开报告或仓库前，保留环境、方法、版本、结果和限制，移除或替换以下信息：用户名、SSH 主机/端口、内部域名、IP、节点名、作业编号、绝对家目录和私有镜像地址。可用 `<USER_HOME>`、`<DTK_ROOT>`、`<CLUSTER_HOST>`、`已脱敏作业` 等占位符。
+Distinguish:
 
-公开技术记录按“环境与版本 → 问题与证据 → 解决方法 → 验证结果 → 已知限制 →
-可复用经验”组织。结论必须标明测试环境、验证范围和未验证边界；视觉样式由具体发布
-项目决定，不写进本 skill。
+- profile values;
+- live scheduler observations;
+- login-node observations;
+- compute-node observations;
+- conclusions inferred from those observations.
 
-详细的兼容性排查和报告模板见 `references/software-compatibility.md`。
+For failures, report the failing command, relevant log excerpt, scheduler state and exit code,
+target profile, and the next bounded diagnostic action. For compatibility results, state the
+software and toolchain versions, accelerator architecture, validation layer reached, and
+untested boundaries.

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

@@ -66,7 +66,7 @@ TMP_SHARED="no"                          # /tmp 是否跨节点共享
 # 登录节点缺失的库（导致无法在登录节点 import 深度学习框架）
 LOGIN_NODE_MISSING_LIBS="libgalaxyhip.so.5"
 
-# 加速器不支持的能力，写进文档避免重复踩坑
+# 已验证的加速器能力限制
 KNOWN_LIMITATIONS="Triton 不可用（实测 libgcvm.so.17git 或 libamdhip64.so 缺 hipDrvLaunchKernelEx）；\
 FP8 无硬件计算支持（torch._scaled_mm 拒绝 gfx936）；\
 bitsandbytes 8-bit 不可用（hipBLASLt 无 gfx936 INT8 algo）；\

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

@@ -1,11 +1,11 @@
 # 新增一个集群
 
 这套 skill 的集群参数都在 `clusters/*.conf`，脚本从 profile 读取。新增集群
-不需要改任何脚本或文档，只加一个 profile。
+通常只需增加一个 profile；若调度器或字段语义不同，仍需扩展脚本。
 
-## 步骤
+## 配置流程
 
-### 1. 先手工确认能连上
+### 1. 验证基础连接
 
 用平台控制台下载的私钥，临时连一次：
 
@@ -14,9 +14,9 @@ chmod 600 <私钥>
 ssh -i <私钥> -p <端口> <用户名>@<主机名> 'hostname; whoami'
 ```
 
-连不上先解决：私钥是否过期、本机 IP 是否在平台白名单、端口是否可达。
+连接失败时检查：私钥是否过期、本机 IP 是否在平台白名单、端口是否可达。
 
-### 2. 临时加一个 ssh 别名（探测脚本需要）
+### 2. 添加临时 SSH 别名
 
 ```bash
 cat >> ~/.ssh/config <<'EOF'
@@ -30,7 +30,7 @@ Host newcluster-tmp
 EOF
 ```
 
-### 3. 探测，自动生成 profile
+### 3. 生成初始 profile
 
 ```bash
 ./scripts/probe-cluster.sh newcluster-tmp <集群短名> > clusters/<集群短名>.conf
@@ -39,7 +39,7 @@ EOF
 脚本会自动填：SSH 参数、调度器类型、分区、`DEF_MEM_PER_CPU`、QOS 的 `MIN_GRES`、
 节点规格、网络可达性、登录节点缺失的库、家目录容量。
 
-**探测不到的项会留空并在文件末尾列出**，不会瞎猜。
+**探测不到的项会留空并在文件末尾列出**，不填入推测值。
 
 ### 4. 补齐手工项
 
@@ -57,12 +57,12 @@ srun -p <分区> --gres=<类型>:1 --time=00:05:00 bash -lc 'module load <模块
 srun -p <分区> --gres=gpu:1 --time=00:05:00 nvidia-smi --query-gpu=name --format=csv
 ```
 
-**module 名** —— `ssh <集群> 'module avail 2>&1'` 里挑编译器和加速器 SDK。
+**module 名** —— `ssh <集群> 'module avail 2>&1'` 中选择与目标环境匹配的编译器和加速器 SDK。
 
 **`NEEDS_UPDATE_HOSTKEYS_NO`** —— 如果连接时看到
 `client_global_hostkeys_prove_confirm: server gave bad signature`，设成 `yes`。
 
-**`KEY_NAME_MARKER`** —— 看私钥文件名格式。若形如
+**`KEY_NAME_MARKER`** —— 根据私钥文件名格式设置。若形如
 `zhangsan_xxx.scnet.cn_RsaKeyExpireTime_2027-01-01.txt`，则设
 `KEY_NAME_MARKER="_<集群主机>_"`，脚本就能自动提取用户名。
 
@@ -77,10 +77,9 @@ srun -p <分区> --gres=gpu:1 --time=00:05:00 nvidia-smi --query-gpu=name --form
 公开 profile 使用占位符时，`<用户名>` 必须显式传入；如果已在本地私有 profile
 里填了真实 `KEY_NAME_MARKER`，可以省略。
 
-### 6. 实测加速器能力，写回 profile
+### 6. 验证加速器能力并记录结论
 
-**这一步别省。** 国产加速器的软件栈往往落后于上游，很多想当然的能力并不存在。
-花 5 分钟测清楚，能省掉后面几天的困惑。
+加速器能力必须以目标计算节点的探针结果为准，不能从上游 ROCm、CUDA 或其他集群的结果推断。
 
 所有探针和测试任务的临时文件必须放在共享家目录中，例如
 `$HOME/.scnet-hpc/tmp/$SLURM_JOB_ID`。不要使用 `/tmp` 或从根目录创建临时目录；作业
@@ -127,15 +126,13 @@ except Exception as e:
 
 把结论写进 profile 的 `KNOWN_LIMITATIONS`，格式参考已有的 profile。
 
-Triton 尤其值得测：**它不可用会连带否掉一大批推理框架**（SGLang 的 FP8 路径、
-vLLM 的 ROCm MoE 后端、transformers 的 finegrained-fp8）。提前知道能避免在框架
-适配上白费时间。
+Triton 是多种推理框架的运行前提；不可用时，对应的 Triton 执行路径也不可用（SGLang 的 FP8 路径、vLLM 的 ROCm MoE 后端、transformers 的 finegrained-fp8）。该结论应在框架适配前确认。
 
 已有集群后续不必重跑完整流程，可用
 `./scripts/refresh-cluster.sh --cluster <集群短名> --compute` 动态刷新调度器、
 内存、分区、网络和计算节点能力，结果写到 `clusters/.cache/<集群短名>.auto.conf`。
 
-## profile 字段速查
+## profile 字段参考
 
 必填三项：`CLUSTER_ID`、`SSH_HOST`、`SSH_PORT`。其余留空则脚本跳过、文档显示为未探测。
 

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

@@ -2,13 +2,13 @@
 
 具体参数在 `clusters/<集群短名>.conf`，本文讲通用方法。
 
-## 查当前集群的参数
+## 读取和核验集群参数
 
 ```bash
 cat clusters/<集群短名>.conf
 ```
 
-要现场核实（profile 可能过期）：
+任务依赖当前状态时，执行现场核验：
 
 ```bash
 ssh <集群> 'scontrol show partition <分区>'     # DefMemPerCPU / MaxTime / TotalNodes
@@ -16,7 +16,7 @@ ssh <集群> 'sinfo -p <分区> -o "%n %c %m %G %t"'  # 每节点 CPU/内存/GRE
 ssh <集群> 'sacctmgr show qos where name=<QOS名> format=Name,MinTRES%30,MaxTRES%30 -P'
 ```
 
-也可以用 skill 自带的动态刷新，登录节点只读探测不会提交作业：
+也可使用动态刷新脚本，登录节点只读探测不会提交作业：
 
 ```bash
 ./scripts/refresh-cluster.sh --cluster <集群短名> --dry-run
@@ -42,7 +42,7 @@ module load compiler/gcc/9.3.0 compiler/dtk/26.04
 DTK 是海光对 ROCm 的发行版，含 HIP、rocBLAS、hipBLASLt、MIOpen、RCCL 等，
 把 ROCm 的部分库改了名（如 `libgalaxyhip.so` 对应 `libamdhip64.so`）。
 
-看有哪些可用：
+列出可用模块：
 
 ```bash
 ssh <集群> 'module avail 2>&1'
@@ -51,14 +51,14 @@ ssh <集群> 'module avail 2>&1'
 ## Python 环境
 
 超算通常没有系统级的 torch，用 venv 或 conda env。profile 的 `DEFAULT_VENV`
-记录了常用的那个（相对家目录）。
+记录默认环境路径（相对家目录）。
 
 ```bash
 module load <MODULE_LOADS>                       # 必须先 load
 source ~/<DEFAULT_VENV>/bin/activate
 ```
 
-**顺序重要**：不 module load 就激活 venv，`import torch` 会报缺共享库：
+必须先加载工具链模块，再激活 Python 环境；否则，`import torch` 会报缺共享库：
 
 ```
 ImportError: libgalaxyhip.so.5: cannot open shared object file
@@ -72,7 +72,7 @@ module load python/3.8.10
 
 ## 厂商预编译的 wheel
 
-国产加速器的 torch 等框架需要厂商适配版，文件名带厂商标记。海光的例子：
+国产加速器的 torch 等框架需要厂商适配版，文件名带厂商标记。海光示例：
 
 ```
 torch-2.7.1+das.opt1.dtk2604-cp312-...whl
@@ -85,16 +85,16 @@ pip 想升级 torch，加 `--no-deps` 阻止。
 
 ## 装依赖
 
-只能在**登录节点**装（计算节点无外网）：
+当计算节点无外网时，在具备网络访问的登录节点准备依赖：
 
 ```bash
 source ~/<venv>/bin/activate
 pip install -i <PIP_INDEX> <包名>
 ```
 
-`PIP_INDEX` 在 profile 里。国内源比 pypi.org 快很多。
+`PIP_INDEX` 在 profile 里。镜像选择以 profile 和现场可达性为准。
 
-装完后**验证要在计算节点做**（登录节点可能 import 不了框架）：
+安装后在目标计算节点验证（登录节点可能 import 不了框架）：
 
 ```bash
 srun -p <分区> --gres=<类型>:1 --cpus-per-task=8 --mem=30gb --time=00:05:00 \
@@ -115,14 +115,14 @@ snapshot_download('<repo>', cache_dir='/public/home/$USER/models/_ms_cache')
 "
 ```
 
-**注意一个坑**：modelscope 首次下载可能漏文件（只留 `.lock`）。用
+若 ModelScope 首次下载结果不完整或只保留 `.lock` 文件，可使用
 `allow_patterns` 单独补：
 
 ```python
 snapshot_download(repo, cache_dir=..., allow_patterns=["inference/*", "*.json"])
 ```
 
-下载完检查文件数是否符合预期，别假设完整。
+下载后核验所需文件、数量和校验信息。
 
 ## 家目录布局约定
 
@@ -140,7 +140,7 @@ softwares/             代码、venv、编译产物
 
 让所有 `#SBATCH --output` 指向 `scripts/logs/`，否则日志会散落在提交目录。
 
-## 迁移目录的注意事项
+## 迁移环境目录
 
 **移动含 venv / conda env 的目录前，检查 `bin/` 下的 shebang。** conda 把解释器
 绝对路径写死在 `pip`、`torchrun` 等入口点第一行，直接移动会报 bad interpreter：
@@ -153,7 +153,7 @@ for f in *; do
 done
 ```
 
-实际案例：移一个 conda env 需要改 57 个入口点。改完验证：
+迁移后验证入口脚本和环境前缀：
 
 ```bash
 <新路径>/bin/python -c "import sys; print(sys.prefix)"
@@ -170,7 +170,7 @@ df -h ~                    # 文件系统使用情况
 du -sh */ | sort -h        # 各目录体积（大目录很慢，考虑放后台）
 ```
 
-注意 `df` 给的是**整个文件系统**的容量，不一定是你的个人配额。查个人配额要用
+`df` 显示的是**整个文件系统**的容量，不一定是你的个人配额。查个人配额要用
 平台特定的命令（如 `lfs quota`）或看控制台。
 
 模型权重是主要占用，几个大模型就是几百 GB。

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

@@ -4,6 +4,10 @@ This guide covers the common workflow for SCNet clusters. Current repository pro
 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