dsh-scnet 0.1.0

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

@@ -0,0 +1,88 @@
+# kseshell —— 海光 Z100 DCU 集群（共享模板；连接字段需按平台填写）
+#
+# SCNet 昆山集群。与郑州（zzeshell / BW1000 / gfx936）的主要差别：
+#   - 加速器是 Z100 (gfx906)，单机 4 卡、每卡 16GB（BW1000 是 8 卡 × 64GB）
+#   - 有独立的 CPU 队列，纯 CPU 作业可提交（郑州只有一个强制要 DCU 的队列）
+#   - DEF_MEM_PER_CPU=3569（郑州 3888）
+#   - DTK 路径和 SSH 端口因平台配置而异
+
+# ---- 连接 ----
+CLUSTER_ID="kseshell"
+CLUSTER_DESC="海光 Z100 DCU（昆山）"
+SSH_HOST=""
+SSH_PORT=""
+HOME_BASE="/public/home"
+
+KEY_NAME_MARKER=""
+NEEDS_UPDATE_HOSTKEYS_NO="no"            # 实测无坏签名告警
+
+# ---- 调度器 ----
+SCHEDULER="slurm"
+
+# 默认用 DCU 队列。纯 CPU 作业改用 kshcnormal（见下面 PARTITIONS_*）
+PARTITION="kshdnormal"
+
+DEF_MEM_PER_CPU="3569"                   # 实测边界：32核 111gb 通过 / 112gb 被拒
+MIN_GRES="dcu:1"                         # kshdnormal 的 QOS 强制；CPU 队列无此限制
+GRES_TYPE="dcu"
+MAX_WALLTIME="333-08:00:00"
+
+# 这个集群有多个队列，用途不同：
+#   kshcnormal   CPU 队列，3557 节点，QOS=partition_cpu，无 GRES 约束
+#   kshdnormal   DCU 队列，571 节点，QOS=partition_normal_7584，MinTRES=gres/dcu=1
+#   kshdAI       DCU 队列，39 节点，QOS=partition_kshdAI，无 GRES 强制，但时限仅 2 小时
+#   kshcsctest / kshdsctest   测试队列，时限 3 天
+PARTITION_CPU="kshcnormal"
+PARTITION_DCU="kshdnormal"
+PARTITION_DCU_SHORT="kshdAI"             # 时限 2:00:00
+
+# ---- 硬件 ----
+ACCEL_NAME="海光 Z100 DCU (Device 66a1)"
+ACCEL_ARCH="gfx906"
+ACCEL_PER_NODE="4"
+ACCEL_MEM_GB="16"                        # 实测 16368 MiB/卡
+ACCEL_CU="64"                            # Compute Unit
+ACCEL_TDP_W="300"
+CPUS_PER_NODE="32"
+CPU_MODEL="Hygon C86 7185 32-core"
+NODE_MEM_GB="123"
+NODE_COUNT="571"                         # kshdnormal；CPU 队列 3557 节点
+LOGIN_NODES="login07 等（有多台）"
+HOME_QUOTA_GB="2950"                     # /public 文件系统总量，非个人独占
+
+# ---- 软件栈 ----
+TOOLCHAIN="DTK"
+TOOLCHAIN_VERSION="26.04"
+TOOLCHAIN_PATH=""
+MODULE_LOADS="compiler/dtk/26.04"
+# 可用版本很多：22.10 / 23.04 / 23.10 / 24.04.x / 25.04.x / 26.04
+# 实测 26.04、25.04.4、24.04.3 都能正常识别 4 张 gfx906
+
+DEFAULT_VENV=""                          # 尚未建 venv；系统 python3 是 3.8.5，无 torch
+
+# ---- 网络 ----
+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=""               # 登录节点无 torch（未装），非缺库
+
+# gfx906 是 Vega 20 代架构，比 gfx936 更老：
+#   - 无 FP8 硬件支持（gfx906 连 BF16 矩阵指令都没有，只有 FP16/FP32）
+#   - 无 Matrix Core（MFMA 指令），矩阵运算靠 SIMD
+#   - 单卡仅 16GB，大模型必须多卡切分或量化
+# 具体的 torch/Triton 能力待建 venv 后实测，参考 references/adding-cluster.md
+KNOWN_LIMITATIONS="gfx906 (Vega20) 无 FP8/BF16 硬件支持、无 MFMA Matrix Core；\
+单卡显存仅 16GB；torch/Triton 可用性待实测；\
+CentOS 7.6 / glibc 2.17 环境优先使用 manylinux_2_17 wheel，onnxruntime 通常锁定 1.16.3；\
+MinerU 3.4.x 需 Python >=3.10，旧版 magika 兼容方案需单独验证 API；\
+GROMACS 原生 HIP 路径需显式确认 CMake、DTK、目标架构和 FFTW，不能把 CUDA 兼容层性能直接外推到 HIP"
+
+# ---- 作业脚本注意 ----
+# module load 必须在 login shell 里执行。非交互 shell（如 heredoc 里）module
+# 函数未定义，会静默失败、ROCM_PATH 不设置、rocminfo 无输出。
+# 解法：作业脚本用 #!/bin/bash 后直接 module load（sbatch 会走 login shell），
+# 或在 heredoc 内包一层 bash -l。

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

@@ -0,0 +1,73 @@
+# zzeshell —— 海光 DCU 集群（共享模板；连接字段需按平台填写）
+#
+# 这是一个集群 profile。新增集群时复制本文件改值即可，
+# 脚本和文档都从这里读配置，不硬编码。
+
+# ---- 连接 ----
+CLUSTER_ID="zzeshell"                    # 短名，同时用作 ssh 别名
+CLUSTER_DESC="海光 BW1000 DCU（郑州）"
+SSH_HOST=""
+SSH_PORT=""
+HOME_BASE="/public/home"                 # 家目录父路径，实际家目录是 $HOME_BASE/$USER
+
+# 私钥文件名里的主机标识，用于从文件名推断用户名
+# 形如 <用户名>_<集群主机>_RsaKeyExpireTime_<日期>.txt
+KEY_NAME_MARKER=""
+
+# 平台对 SSH 主机密钥轮换扩展返回错误签名，需要 UpdateHostKeys no 抑制告警
+NEEDS_UPDATE_HOSTKEYS_NO="yes"
+
+# ---- 调度器 ----
+SCHEDULER="slurm"
+PARTITION="hx1hdnormal"
+
+# 每 CPU 默认内存（MB）。内存上限 = cpus-per-task × 此值
+DEF_MEM_PER_CPU="3888"
+
+# QOS 强制的最小 GRES。非空表示每个作业必须申请，纯 CPU 作业会被拒
+MIN_GRES="dcu:1"
+
+# GRES 类型名（--gres=<此值>:N）
+GRES_TYPE="dcu"
+
+MAX_WALLTIME="3-00:00:00"
+
+# ---- 硬件 ----
+ACCEL_NAME="海光 BW1000 DCU"
+ACCEL_ARCH="gfx936"
+ACCEL_PER_NODE="8"
+ACCEL_MEM_GB="64"
+CPUS_PER_NODE="128"
+CPU_MODEL="Hygon C86"
+NODE_MEM_GB="498"
+NODE_COUNT="16"
+LOGIN_NODES="zz-login01 / zz-login02（有负载均衡）"
+HOME_QUOTA_GB="1450"                     # /public 文件系统总量，非个人独占
+
+# ---- 软件栈 ----
+TOOLCHAIN="DTK"                          # 海光的 ROCm 发行版
+TOOLCHAIN_VERSION="26.04"
+TOOLCHAIN_PATH=""
+MODULE_LOADS="compiler/gcc/9.3.0 compiler/dtk/26.04"
+
+# 默认 venv 路径（相对家目录）。因人而异，装完可改
+DEFAULT_VENV="softwares/bitsandbytes/venv"
+
+# ---- 网络 ----
+# 登录节点可达的域名（用于文档和 pip 源选择）
+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"                          # /tmp 是否跨节点共享
+
+# ---- 已知的平台特有问题 ----
+# 登录节点缺失的库（导致无法在登录节点 import 深度学习框架）
+LOGIN_NODE_MISSING_LIBS="libmsgpackc.so.2"
+
+# 加速器不支持的能力，写进文档避免重复踩坑
+KNOWN_LIMITATIONS="Triton 不可用（libamdhip64.so 缺 hipDrvLaunchKernelEx）；\
+FP8 无硬件计算支持（torch._scaled_mm 拒绝 gfx936）；\
+bitsandbytes 8-bit 不可用（hipBLASLt 无 gfx936 INT8 algo）；\
+纯 PyTorch 软件反量化可作为大模型推理退路，但单序列解码约 0.93–1.12 tok/s；\
+依赖 Triton、硬件 FP8 或 CUDA-only kernel 的推理框架需先做计算节点探针"

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

@@ -0,0 +1,144 @@
+# 新增一个集群
+
+这套 skill 的集群参数都在 `clusters/*.conf`，脚本从 profile 读取。新增集群
+不需要改任何脚本或文档，只加一个 profile。
+
+## 步骤
+
+### 1. 先手工确认能连上
+
+用平台控制台下载的私钥，临时连一次：
+
+```bash
+chmod 600 <私钥>
+ssh -i <私钥> -p <端口> <用户名>@<主机名> 'hostname; whoami'
+```
+
+连不上先解决：私钥是否过期、本机 IP 是否在平台白名单、端口是否可达。
+
+### 2. 临时加一个 ssh 别名（探测脚本需要）
+
+```bash
+cat >> ~/.ssh/config <<'EOF'
+
+Host newcluster-tmp
+  HostName <主机名>
+  User <用户名>
+  Port <端口>
+  IdentityFile <私钥路径>
+  IdentitiesOnly yes
+EOF
+```
+
+### 3. 探测，自动生成 profile
+
+```bash
+./scripts/probe-cluster.sh newcluster-tmp <集群短名> > clusters/<集群短名>.conf
+```
+
+脚本会自动填：SSH 参数、调度器类型、分区、`DEF_MEM_PER_CPU`、QOS 的 `MIN_GRES`、
+节点规格、网络可达性、登录节点缺失的库、家目录容量。
+
+**探测不到的项会留空并在文件末尾列出**，不会瞎猜。
+
+### 4. 补齐手工项
+
+profile 末尾的注释列出了还需确认的。主要是：
+
+**加速器型号和架构** —— 在计算节点跑：
+
+```bash
+# AMD/海光系
+srun -p <分区> --gres=<类型>:1 --time=00:05:00 bash -lc 'module load <模块>; rocminfo | grep -i gfx'
+# NVIDIA
+srun -p <分区> --gres=gpu:1 --time=00:05:00 nvidia-smi --query-gpu=name --format=csv
+```
+
+**module 名** —— `ssh <集群> 'module avail 2>&1'` 里挑编译器和加速器 SDK。
+
+**`NEEDS_UPDATE_HOSTKEYS_NO`** —— 如果连接时看到
+`client_global_hostkeys_prove_confirm: server gave bad signature`，设成 `yes`。
+
+**`KEY_NAME_MARKER`** —— 看私钥文件名格式。若形如
+`zhangsan_xxx.scnet.cn_RsaKeyExpireTime_2027-01-01.txt`，则设
+`KEY_NAME_MARKER="_<集群主机>_"`，脚本就能自动提取用户名。
+
+### 5. 用正式流程重配连接
+
+删掉第 2 步的临时段，然后：
+
+```bash
+./scripts/setup-ssh.sh --cluster <集群短名> <私钥文件>
+```
+
+### 6. 实测加速器能力，写回 profile
+
+**这一步别省。** 国产加速器的软件栈往往落后于上游，很多想当然的能力并不存在。
+花 5 分钟测清楚，能省掉后面几天的困惑。
+
+用一个探针作业测这些：
+
+```python
+import torch
+p = torch.cuda.get_device_properties(0)
+print("arch:", getattr(p, "gcnArchName", "?"), "| major", p.major, "minor", p.minor)
+
+# 低精度数据类型
+for dt in ["float8_e4m3fn", "float8_e5m2", "float8_e8m0fnu", "bfloat16"]:
+    print(dt, hasattr(torch, dt))
+
+# 硬件加速的低精度 matmul
+try:
+    a = torch.randn(64, 128).to(torch.float8_e4m3fn).cuda()
+    b = torch.randn(128, 64).to(torch.float8_e4m3fn).cuda().t().contiguous().t()
+    torch._scaled_mm(a, b, scale_a=torch.tensor(1.).cuda(),
+                     scale_b=torch.tensor(1.).cuda(), out_dtype=torch.bfloat16)
+    print("_scaled_mm: OK")
+except Exception as e:
+    print("_scaled_mm:", type(e).__name__, str(e)[:120])
+
+# Triton（很多推理框架的前提）
+try:
+    import triton, triton.language as tl
+    @triton.jit
+    def k(x, y, o, n, BLOCK: tl.constexpr):
+        i = tl.program_id(0) * BLOCK + tl.arange(0, BLOCK)
+        m = i < n
+        tl.store(o + i, tl.load(x + i, mask=m) + tl.load(y + i, mask=m), mask=m)
+    n = 4096
+    x = torch.randn(n, device="cuda"); y = torch.randn(n, device="cuda")
+    o = torch.empty_like(x)
+    k[(triton.cdiv(n, 256),)](x, y, o, n, BLOCK=256)
+    torch.cuda.synchronize()
+    print("triton: OK, err", (o - (x + y)).abs().max().item())
+except Exception as e:
+    print("triton:", type(e).__name__, str(e)[:200])
+```
+
+把结论写进 profile 的 `KNOWN_LIMITATIONS`，格式参考已有的 profile。
+
+Triton 尤其值得测：**它不可用会连带否掉一大批推理框架**（SGLang 的 FP8 路径、
+vLLM 的 ROCm MoE 后端、transformers 的 finegrained-fp8）。提前知道能避免在框架
+适配上白费时间。
+
+## profile 字段速查
+
+必填三项：`CLUSTER_ID`、`SSH_HOST`、`SSH_PORT`。其余留空则脚本跳过、文档显示为未探测。
+
+影响脚本行为的关键项：
+
+| 字段 | 谁用 | 留空的后果 |
+|---|---|---|
+| `MIN_GRES` | 文档提示 | 不提示 QOS 强制申请加速器 |
+| `GRES_TYPE` | `new-job.sh` | 生成的脚本不含 `--gres` |
+| `DEF_MEM_PER_CPU` | `new-job.sh` | 生成的脚本不含 `--mem`，需手填 |
+| `MODULE_LOADS` | `new-job.sh` | 生成的脚本不含 `module load` |
+| `DEFAULT_VENV` | `new-job.sh` | 生成的脚本不含 venv 激活 |
+| `KEY_NAME_MARKER` | `setup-ssh.sh` | 无法从文件名推断用户名，需显式传 |
+| `NEEDS_UPDATE_HOSTKEYS_NO` | `setup-ssh.sh` | 不写 `UpdateHostKeys no` |
+| `COMPUTE_NODE_OFFLINE` | `new-job.sh` | 不设 `HF_HUB_OFFLINE` |
+
+## 非 Slurm 调度器
+
+目前 `new-job.sh` 只支持 Slurm（`SCHEDULER="slurm"`）。PBS/LSF 集群可以填
+profile 的其他字段用于文档和连接，但作业脚本要手写。

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

@@ -0,0 +1,162 @@
+# 集群环境
+
+具体参数在 `clusters/<集群短名>.conf`，本文讲通用方法。
+
+## 查当前集群的参数
+
+```bash
+cat clusters/<集群短名>.conf
+```
+
+要现场核实（profile 可能过期）：
+
+```bash
+ssh <集群> 'scontrol show partition <分区>'     # DefMemPerCPU / MaxTime / TotalNodes
+ssh <集群> 'sinfo -p <分区> -o "%n %c %m %G %t"'  # 每节点 CPU/内存/GRES/状态
+ssh <集群> 'sacctmgr show qos where name=<QOS名> format=Name,MinTRES%30,MaxTRES%30 -P'
+```
+
+节点状态含义：`idle` 空闲、`mix` 部分占用、`alloc` 全占、`drain`/`drng` 不可调度
+（维护中）。实际可用节点常少于总数。
+
+**登录节点常有负载均衡**，两次 `hostname` 结果可能不同。这不影响使用（家目录共享），
+但如果在某台登录节点起了后台进程，下次登录可能落到另一台看不到它。
+
+## 加速器软件栈
+
+国产超算的加速器 SDK 通常通过 module 加载，profile 的 `MODULE_LOADS` 记录了
+需要 load 的模块。以海光 DTK 为例：
+
+```bash
+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'
+```
+
+## Python 环境
+
+超算通常没有系统级的 torch，用 venv 或 conda env。profile 的 `DEFAULT_VENV`
+记录了常用的那个（相对家目录）。
+
+```bash
+module load <MODULE_LOADS>                       # 必须先 load
+source ~/<DEFAULT_VENV>/bin/activate
+```
+
+**顺序重要**：不 module load 就激活 venv，`import torch` 会报缺共享库：
+
+```
+ImportError: libgalaxyhip.so.5: cannot open shared object file
+```
+
+## 厂商预编译的 wheel
+
+国产加速器的 torch 等框架需要厂商适配版，文件名带厂商标记。海光的例子：
+
+```
+torch-2.7.1+das.opt1.dtk2604-cp312-...whl
+flash_attn-2.8.3+das.opt1.dtk2604.torch271-...whl
+```
+
+`+das.opt1.dtk2604` 表示针对 DTK 26.04 编译。**不要用 PyPI 的通用版覆盖这些**
+——通用版是 CUDA 或上游 ROCm 编译的，在国产加速器上跑不起来。装其他包时如果
+pip 想升级 torch，加 `--no-deps` 阻止。
+
+## 装依赖
+
+只能在**登录节点**装（计算节点无外网）：
+
+```bash
+source ~/<venv>/bin/activate
+pip install -i <PIP_INDEX> <包名>
+```
+
+`PIP_INDEX` 在 profile 里。国内源比 pypi.org 快很多。
+
+装完后**验证要在计算节点做**（登录节点可能 import 不了框架）：
+
+```bash
+srun -p <分区> --gres=<类型>:1 --cpus-per-task=8 --mem=30gb --time=00:05:00 \
+  bash -lc 'module load <模块>
+    source ~/<venv>/bin/activate
+    python3 -c "import <包名>; print(\"ok\")"'
+```
+
+## 下载模型
+
+profile 的 `NET_BLOCKED` 记录了不可达的站点。国内超算通常 `huggingface.co`
+不通，用 modelscope：
+
+```bash
+python3 -c "
+from modelscope import snapshot_download
+snapshot_download('<repo>', cache_dir='/public/home/$USER/models/_ms_cache')
+"
+```
+
+**注意一个坑**：modelscope 首次下载可能漏文件（只留 `.lock`）。用
+`allow_patterns` 单独补：
+
+```python
+snapshot_download(repo, cache_dir=..., allow_patterns=["inference/*", "*.json"])
+```
+
+下载完检查文件数是否符合预期，别假设完整。
+
+## 家目录布局约定
+
+```
+models/                所有模型权重
+scripts/               作业脚本
+├── lib/               可复用的 Python 模块（作业里通过 PYTHONPATH 引用）
+├── probes/            诊断/探针脚本
+├── deprecated/        已确认走不通的路线（隔开避免误用）
+└── logs/              作业日志（所有 #SBATCH --output 指向这里）
+softwares/             代码、venv、编译产物
+├── projects/          各项目工作目录
+└── _archive/          历史日志、一次性脚本
+```
+
+让所有 `#SBATCH --output` 指向 `scripts/logs/`，否则日志会散落在提交目录。
+
+## 迁移目录的注意事项
+
+**移动含 venv / conda env 的目录前，检查 `bin/` 下的 shebang。** conda 把解释器
+绝对路径写死在 `pip`、`torchrun` 等入口点第一行，直接移动会报 bad interpreter：
+
+```bash
+cd <env>/bin
+for f in *; do
+  head -c2 "$f" 2>/dev/null | grep -q '^#!' || continue
+  head -1 "$f" | grep -q "<旧路径>" && sed -i "1s|<旧路径>|<新路径>|" "$f"
+done
+```
+
+实际案例：移一个 conda env 需要改 57 个入口点。改完验证：
+
+```bash
+<新路径>/bin/python -c "import sys; print(sys.prefix)"
+<新路径>/bin/pip --version
+```
+
+同时检查作业脚本里的硬编码路径（`#SBATCH --output`、`source .../activate`、
+`PYTHONPATH`）。
+
+## 磁盘
+
+```bash
+df -h ~                    # 文件系统使用情况
+du -sh */ | sort -h        # 各目录体积（大目录很慢，考虑放后台）
+```
+
+注意 `df` 给的是**整个文件系统**的容量，不一定是你的个人配额。查个人配额要用
+平台特定的命令（如 `lfs quota`）或看控制台。
+
+模型权重是主要占用，几个大模型就是几百 GB。

package/skills/scnet-hpc/references/hygon-dcu-development.md

@@ -0,0 +1,74 @@
+# 海光 DCU 开发与工具库索引
+
+本页整理光合开发者社区的公开入口。站点内容会更新；版本、支持的操作系统、驱动、固件和安装包必须以官方页面当前选择结果为准，不要从本文复制旧版本组合。
+
+## 使用顺序
+
+1. 打开[开发指南](https://developer.sourcefind.cn/developer-channel)，选择 DCU 产品系列、操作系统和版本。
+2. 按页面顺序完成驱动安装、固件更新、DTK 或 DAS 环境部署，再考虑容器化部署。
+3. 打开 [DTK 资源页](https://developer.sourcefind.cn/dtk)，下载与目标系统匹配的 DTK，并从文档目录选择对应版本手册。
+4. 在计算节点用最小探针验证驱动、运行时、编译器、目标架构和所需库；集群 module 中的实际版本优先于网页示例。
+5. 需要模型、镜像、代码或课程时，从下方资源入口继续查找。
+
+## 官方入口
+
+| 入口 | 用途 |
+|---|---|
+| [开发指南](https://developer.sourcefind.cn/developer-channel) | 产品与系统选择；驱动、VBIOS、DTK、DAS、容器部署步骤 |
+| [文档中心](https://developer.sourcefind.cn/document/) | 官方文档检索；页面可能要求浏览器会话或登录 |
+| [DTK](https://developer.sourcefind.cn/dtk) | DTK 下载、文档、FAQ、教程和版本动态 |
+| [DTK 下载目录](https://download.sourcefind.cn:65024/1/main) | 安装包与版本目录 |
+| [DTK 最新文档目录](https://download.sourcefind.cn:65024/1/main/latest/Document) | 当前发布版文档集合 |
+| [DCU 上手指南](https://developer.sourcefind.cn/gitbook/dcu_tutorial/index.html) | 入门教程；可能跳转统一登录 |
+| [DAS](https://das.sourcefind.cn:55011/portal/) | 应用分析与相关工具入口 |
+| [DAP](https://dap.sourcefind.cn/) | 开发与适配平台入口 |
+| [代码仓库](https://developer.sourcefind.cn/codes/) | 示例、适配代码和项目 |
+| [模型仓库](https://developer.sourcefind.cn/modelzoo/list) | DCU 模型资源 |
+| [镜像仓库](https://harbor.sourcefind.cn:5443/) | 容器镜像；使用前确认登录和拉取权限 |
+| [科学计算](https://dos.sourcefind.cn:50275/portal/#/home) | 科学计算软件与服务 |
+| [C86 DevKit](https://c86.sourcefind.cn/documents) | 海光 CPU/C86 开发资料；不要与 DCU/DTK 文档混用 |
+| [DTK 论坛答疑区](https://forum.sourcefind.cn/cate/1_42_43_44/seq/0) | 数学库、运行时、编译器与适配问题 |
+
+## DTK 软件栈索引
+
+DTK 是面向 DCU 应用开发、优化和部署的工具包。官方资源页将其能力分为以下几层。
+
+| 类别 | 组件或主题 | 何时查 |
+|---|---|---|
+| 异构编程语言 | HIP、OpenCL、OpenACC、OpenMP；CUDA 兼容与迁移 | 新项目选编程模型，或移植 CUDA 程序 |
+| 编译与运行时 | Fortran/C/C++ 编译器、HIP Runtime、运行时库、CUDA 兼容层 | 编译失败、运行时 API、设备与内存管理 |
+| 基础数学库 | BLAS/rocBLAS、LAPACK、SPARSE | 线性代数、稀疏计算及性能调优 |
+| AI/算子库 | CNN/卷积算子库 | 深度学习算子和 dynamic shape 性能 |
+| C++ 并行库 | Thrust、CUB | 并行算法、扫描、归约和设备端原语 |
+| 通信库 | 集合通信、DUSHMEM/单边低延迟通信 | 多卡、跨卡通信和 PGAS 风格访问 |
+| 分析与调试 | 性能分析器、调试器、监控器、DAS | 定位热点、内存错误、同步错误和利用率问题 |
+| 迁移工具 | GPUfusion、CUDA 兼容工具与移植流程 | 评估和转换 CUDA 工程 |
+| 部署 | 国产操作系统、虚拟化、容器、高速互联 | 裸机/module 与容器环境选择 |
+
+官方 DTK 页面当前直接列出的手册示例包括：
+
+- `HIP Runtime API开发手册`
+- `rocBLAS库使用手册`
+- `DUSHMEM库使用手册`
+
+不要把示例文件名当成完整目录。优先进入“最新文档目录”，再按已安装 DTK 版本选择同版本手册。
+
+## 按任务选资料
+
+| 任务 | 先查 | 随后验证 |
+|---|---|---|
+| 新装环境 | 开发指南 → DTK 下载 | `module list`、编译器版本、`rocminfo` |
+| 写 HIP 程序 | HIP Runtime API、编译器文档 | 最小 kernel 编译与运行 |
+| CUDA 项目迁移 | CUDA 兼容课程、GPUfusion、移植流程 | 构建系统、架构宏、CUDA 专属 API |
+| 加速线性代数 | rocBLAS/BLAS、LAPACK、SPARSE 手册 | 数据类型、布局、目标架构、算法可用性 |
+| 深度学习算子 | CNN/卷积算子库、框架适配文档 | dynamic shape、精度、workspace 和 fallback |
+| 多卡通信 | 通信库、DUSHMEM 手册 | 拓扑、进程启动方式、跨节点支持 |
+| 性能问题 | DAS、性能分析教程、监控工具 | 热点、传输、同步、占用率 |
+| 容器部署 | 开发指南的容器化步骤、镜像仓库 | 设备映射、驱动/用户态兼容、Slurm 集成 |
+
+## 安全与准确性
+
+- 不公开记录账号、token、私钥、用户目录、作业 ID、内部地址或受限下载链接。
+- 公开页面出现的版本号只是页面抓取时的状态；安装前重新选择产品和系统。
+- 网页声明“支持”不等于目标集群可用。最终以计算节点实测和集群 profile 的 `KNOWN_LIMITATIONS` 为准。
+- 不把 ROCm/CUDA 上游能力自动等同于 DTK 能力。对 Triton、FP8、INT8、通信算法和特定架构内核逐项探测。

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

@@ -0,0 +1,136 @@
+# 连接配置详解
+
+集群的主机名、端口等参数来自 `clusters/<集群短名>.conf`。
+本文用 `<集群>`、`<主机名>`、`<端口>` 表示从 profile 读出的值。
+
+## 手工配置（不用 setup-ssh.sh 时）
+
+```bash
+# 1. 装私钥
+mkdir -p ~/.ssh && chmod 700 ~/.ssh
+cp <下载的私钥> ~/.ssh/id_rsa_<集群>
+chmod 600 ~/.ssh/id_rsa_<集群>
+
+# macOS：清除下载文件的隔离属性，否则某些工具拒绝读取
+xattr -c ~/.ssh/id_rsa_<集群>
+
+# 2. 建 socket 目录（长连接用）
+mkdir -p ~/.ssh/sockets && chmod 700 ~/.ssh/sockets
+
+# 3. 追加下面的段到 ~/.ssh/config，然后 chmod 600 ~/.ssh/config
+```
+
+```
+Host <集群> <主机名>
+  HostName <主机名>
+  User <你的用户名>
+  Port <端口>
+  IdentityFile ~/.ssh/id_rsa_<集群>
+  IdentitiesOnly yes
+  # 以下两行仅 macOS 支持，Linux 上会报 unknown option
+  UseKeychain yes
+  AddKeysToAgent yes
+  # 长连接
+  ControlMaster auto
+  ControlPath ~/.ssh/sockets/%r@%h-%p
+  ControlPersist 10m
+  # 保活
+  ServerAliveInterval 60
+  ServerAliveCountMax 3
+  TCPKeepAlive yes
+  # 仅当 profile 里 NEEDS_UPDATE_HOSTKEYS_NO=yes 时才加这行
+  UpdateHostKeys no
+```
+
+## 各选项的理由
+
+**`ControlPersist 10m` 而非 `yes`**：永久驻留的 master 在笔记本休眠或换网络后会
+变成失效 socket，反而要手工清理。10 分钟覆盖一次交互操作的节奏，又能自然回收。
+实测复用后单条命令从约 2 秒降到 0.57 秒。
+
+**`ServerAliveInterval 60`**：应用层心跳，防止空闲 SSH 会话被中间网关静默切断。
+跑长任务时关键。`TCPKeepAlive` 是 TCP 层的，两者互补。
+
+**`UpdateHostKeys no`**：部分平台的服务端对主机密钥轮换扩展返回错误签名：
+
+```
+client_global_hostkeys_prove_confirm: server gave bad signature for RSA key 0
+```
+
+这是平台侧实现问题，不影响安全性——首次记录的主机密钥仍在正常校验。关掉只为消除
+告警噪音。**只在遇到这个告警的集群上加**（profile 里标
+`NEEDS_UPDATE_HOSTKEYS_NO=yes`）。
+
+**`IdentitiesOnly yes`**：只用指定的私钥。ssh-agent 里密钥多时，避免因尝试次数
+过多被服务端拒绝。
+
+## macOS 与 Linux 差异
+
+| 项 | macOS | Linux |
+|---|---|---|
+| `UseKeychain` / `AddKeysToAgent` | 支持 | **不支持**，报 unknown option |
+| 下载文件隔离属性 | 需 `xattr -c` | 无此概念 |
+| `sed -i` | 需 `sed -i ''`（BSD sed） | `sed -i`（GNU sed） |
+
+`setup-ssh.sh` 检测 `uname -s` 自动处理前两项。
+
+## 长连接管理
+
+```bash
+ssh -O check <集群>     # 查看 master 状态
+ssh -O exit <集群>      # 手工断开（网络切换后卡住时用）
+```
+
+## 密钥有效期
+
+超算平台的私钥通常有有效期，文件名里就带，例如
+`<用户名>_<主机>_RsaKeyExpireTime_2026-10-29_12-51-40.txt` 表示 2026-10-29 过期。
+到期前从控制台重新下载并重跑 setup 脚本。
+
+profile 里的 `KEY_NAME_MARKER` 就是用来从这种文件名里提取用户名的。
+
+查看当前密钥指纹：
+
+```bash
+ssh-keygen -lf ~/.ssh/id_rsa_<集群>
+```
+
+## 加 passphrase（可选）
+
+```bash
+ssh-keygen -p -f ~/.ssh/id_rsa_<集群>
+```
+
+配合 macOS 的 `UseKeychain yes` + `AddKeysToAgent yes`，只需首次输入一次。
+
+## 常见连接失败
+
+| 现象 | 原因 |
+|---|---|
+| `Permission denied (publickey)` | 私钥过期，或本机 IP 不在平台白名单 |
+| `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` |
+
+多数超算平台有 **IP 白名单**，换网络（家里/公司/热点）后可能连不上，
+需要去控制台加当前 IP。
+
+## 在脚本里调用
+
+```bash
+ssh -o BatchMode=yes <集群> '<命令>'
+```
+
+`BatchMode=yes` 让认证失败立刻返回，而不是卡在密码提示上等输入。写自动化脚本时
+必加，否则可能挂住。
+
+## 文件传输
+
+```bash
+scp local.py <集群>:/public/home/$USER/scripts/
+scp <集群>:/public/home/$USER/scripts/logs/job_123.log .
+rsync -avz --progress ./dir/ <集群>:/public/home/$USER/dir/   # 大量文件
+```
+
+走同一个长连接，不需额外配置端口。