dsh-scnet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-scnet contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+<h1 align="center">dsh-scnet</h1>
+
+<p align="center">在 DeepSeek Harness 里操作超算互联网（scnet.cn）及同类国产超算集群：配 SSH、生成 Slurm 作业、探测集群、排查失败，附海光 DCU/DTK 知识。</p>
+
+## 这是什么
+
+一个 DeepSeek Harness 官方 bundle 插件，把 `scnet-hpc` 的 Agent Skill 和 bash 脚本包装成 DSH 可安装包。装好后 DSH 模型在涉及超算集群、Slurm 作业、海光 DCU/DTK 时会加载对应 skill，并可调用工具完成确定性操作。
+
+## 安装
+
+```sh
+dsh plugin --profile web add "github:lql341/dsh-scnet#main"
+```
+
+或本地目录：
+
+```sh
+git clone https://github.com/lql341/dsh-scnet.git
+cd dsh-scnet
+dsh plugin --profile web add .
+```
+
+> git 源安装会取源码而非构建产物；本插件入口是纯 JavaScript（无编译步骤），无需 allowBuilds。
+
+## 能力面
+
+### Skills
+
+| Skill | 作用 |
+|---|---|
+| scnet-hpc | 国产超算使用规范：连接、提交/监控、调试、失败排查、海光 DCU/DTK 资源索引 |
+
+### Tools
+
+| 工具 | 说明 |
+|---|---|
+| scnet_list_clusters | 列出已配置的集群 profile |
+| scnet_show_cluster | 读取指定集群的完整参数 |
+| scnet_generate_job | 按 profile 生成合规 Slurm 作业脚本 |
+| scnet_setup_ssh | 配置本地到集群的 SSH 连接 |
+| scnet_probe_cluster | 探测新集群并生成 profile |
+
+## 结构
+
+```
+.
+├── package.json          # dsh.bundle + dsh.skills
+├── cordis.patch.yml      # bundle 组合层
+├── index.mjs             # Cordis 入口，注册 5 个工具
+├── skills/scnet-hpc/     # Agent Skill + clusters/scripts/references
+├── sync.sh               # 从 canonical 仓库同步
+└── README.md
+```
+
+## 同步
+
+本仓库是发布面，知识内容（`skills/scnet-hpc/` 下的 SKILL.md、clusters、references、scripts）从 canonical 仓库 `lql341/scnet-hpc` 同步：
+
+```sh
+./sync.sh                   # 默认 ../skills/scnet-hpc
+./sync.sh --src /path/to/scnet-hpc
+```
+
+只改 canonical，本仓库跑 sync 更新；不要把 `skills/scnet-hpc/` 当手工维护目录。
+
+## 隐私与安全
+
+- 仓库不含私钥、token、用户名、密钥指纹。
+- `scnet_setup_ssh` 会写入 `~/.ssh/`，调用前确认私钥路径和集群。
+- `scnet_generate_job` 生成的 `.slurm` 可能含本机用户名，`.gitignore` 已排除。
+- 集群主机名/端口是平台公开信息；profile 中连接字段默认留空，由用户本地填写。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: scnet
+      name: dsh-scnet

package/index.mjs

@@ -0,0 +1,221 @@
+import { execFile } from 'node:child_process'
+import { promises as fs } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+export const name = 'scnet-hpc'
+export const inject = ['tools']
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+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) {
+  return new Promise((resolve) => {
+    execFile(
+      'bash',
+      [script, ...args],
+      { cwd: SKILL_DIR, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        const code = error ? (typeof error.code === 'number' ? error.code : 1) : 0
+        resolve({
+          ok: code === 0,
+          code,
+          stdout: String(stdout || ''),
+          stderr: String(stderr || ''),
+        })
+      },
+    )
+  })
+}
+
+function textBlock(value) {
+  return [{ type: 'text', text: value }]
+}
+
+async function listClusterIds() {
+  let entries = []
+  try {
+    entries = await fs.readdir(CLUSTERS_DIR)
+  } catch {
+    return []
+  }
+  return entries
+    .filter((entry) => entry.endsWith('.conf') && !entry.startsWith('_'))
+    .map((entry) => entry.replace(/\.conf$/, ''))
+    .sort()
+}
+
+async function readProfile(id) {
+  return fs.readFile(join(CLUSTERS_DIR, `${id}.conf`), 'utf8')
+}
+
+function fieldOf(text, key) {
+  const match = text.match(new RegExp(`^${key}="?(.*?)"?$`, 'm'))
+  return match ? match[1] : ''
+}
+
+function positiveInt(value, label) {
+  if (value === undefined || value === null || String(value).trim() === '') return null
+  if (!/^[0-9]+$/.test(String(value).trim())) {
+    return { error: `${label} 必须是正整数` }
+  }
+  return { value: String(value).trim() }
+}
+
+export function apply(ctx) {
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_list_clusters',
+      description:
+        '列出 scnet-hpc 插件中已配置的超算集群 profile（短名与描述）。生成作业或配 SSH 前用它确认可用的集群短名。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        const ids = await listClusterIds()
+        if (ids.length === 0) {
+          return '没有可用的集群 profile。请在 skills/scnet-hpc/clusters/ 下新增 <短名>.conf。'
+        }
+        const lines = []
+        for (const id of ids) {
+          const text = await readProfile(id)
+          lines.push(`${id}\t${fieldOf(text, 'CLUSTER_DESC') || '（未填写描述）'}`)
+        }
+        return lines.join('\n')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_show_cluster',
+      description:
+        '读取指定集群 profile 的完整参数（内存上限、分区、GRES、DTK 路径、已知限制等）。回答硬件规格或配额问题时必须读 profile，不要凭记忆。',
+      parameters: {
+        cluster: {
+          type: 'string',
+          description: '集群短名；省略时，若只有一个 profile 则自动选择，否则报错提示可选项。',
+        },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        let id = String(args.cluster || '').trim()
+        const ids = await listClusterIds()
+        if (!id && ids.length === 1) id = ids[0]
+        if (!id) {
+          return `请指定 cluster。可用集群：${ids.join(', ') || '（无）'}`
+        }
+        try {
+          return await readProfile(id)
+        } catch {
+          return `找不到 profile：${id}。可用集群：${ids.join(', ') || '（无）'}`
+        }
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_generate_job',
+      description:
+        '按目标集群的约束生成合规的 Slurm 作业脚本（自动算 --mem、--gres、module load、离线环境变量，并在末尾写 exit $rc）。会写一个 <name>.slurm 到当前目录并返回上传/提交命令。',
+      parameters: {
+        name: { type: 'string', required: true, description: '作业名（slurm --job-name 和输出文件名）' },
+        accelerators: { type: 'string', description: '加速器数量，默认 1' },
+        cpus: { type: 'string', description: 'CPU 核数，默认 8' },
+        time: { type: 'string', description: '时长，默认 00:20:00，格式 HH:MM:SS 或 D-HH:MM:SS' },
+        cluster: { type: 'string', description: '集群短名；省略时若只有一个 profile 则自动选择' },
+        remote_user: { type: 'string', description: '远端用户名；与本地不同时填写（日志路径需要真实用户名）' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const nameVal = String(args.name || '').trim()
+        if (!nameVal) return '缺少必填参数 name。'
+
+        const accelerators = positiveInt(args.accelerators, 'accelerators')
+        if (accelerators && accelerators.error) return accelerators.error
+        const cpus = positiveInt(args.cpus, 'cpus')
+        if (cpus && cpus.error) return cpus.error
+
+        const argv = []
+        const cluster = String(args.cluster || '').trim()
+        if (cluster) argv.push('--cluster', cluster)
+        const remoteUser = String(args.remote_user || '').trim()
+        if (remoteUser) argv.push('--user', remoteUser)
+        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 res = await runBash(join(SCRIPTS_DIR, 'new-job.sh'), argv, 30000)
+        if (res.ok) return res.stdout.trim() || res.stderr.trim()
+        return `生成失败（exit ${res.code}）：\n${res.stderr.trim() || res.stdout.trim()}`
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_setup_ssh',
+      description:
+        '在本地 macOS/Linux 上配置到超算集群的 SSH 连接：安装私钥到 ~/.ssh、写 ~/.ssh/config、测试连接。幂等，重复运行只补缺失项。会修改本机 SSH 配置，执行前应向用户确认私钥路径与集群。',
+      parameters: {
+        key_path: { type: 'string', required: true, description: '从超算平台控制台下载的私钥文件绝对路径（.txt 或 PEM 私钥）' },
+        cluster: { type: 'string', description: '集群短名；省略时若只有一个 profile 则自动选择' },
+        username: { type: 'string', description: '远端用户名；省略时尝试从私钥文件名推断' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const keyPath = String(args.key_path || '').trim()
+        if (!keyPath) return '缺少必填参数 key_path。'
+        const argv = []
+        const cluster = String(args.cluster || '').trim()
+        if (cluster) argv.push('--cluster', cluster)
+        argv.push(keyPath)
+        if (args.username && String(args.username).trim()) argv.push(String(args.username).trim())
+        const res = await runBash(join(SCRIPTS_DIR, 'setup-ssh.sh'), argv, 90000)
+        const out = `${res.stdout.trim()}\n${res.stderr.trim()}`.trim()
+        return out || `setup-ssh.sh 退出码 ${res.code}，但没有输出。`
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_probe_cluster',
+      description:
+        '探测一个已能 SSH 登录的集群（调度器、分区、内存、GRES、网络、登录节点 torch 可用性），生成可直接保存为 profile 的配置文本。结果需要写回 clusters/<短名>.conf 并补齐探测不到的项。',
+      parameters: {
+        target: { type: 'string', required: true, description: 'ssh 别名或主机名（须已能免密登录）' },
+        name: { type: 'string', description: '集群短名，默认与 target 相同' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const target = String(args.target || '').trim()
+        if (!target) return '缺少必填参数 target。'
+        const argv = [target]
+        if (args.name && String(args.name).trim()) argv.push(String(args.name).trim())
+        const res = await runBash(join(SCRIPTS_DIR, 'probe-cluster.sh'), argv, 180000)
+        if (res.ok) return res.stdout.trim()
+        return `探测失败（exit ${res.code}）：\n${res.stderr.trim() || res.stdout.trim()}`
+      },
+    }),
+  )
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "dsh-scnet",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness bundle plugin for SCNet (scnet.cn) and similar domestic HPC clusters: SSH setup, Slurm job generation, cluster probing, and Hygon DCU/DTK guidance.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.mjs",
+    "cordis.patch.yml",
+    "skills"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "skills": [
+      "./skills/scnet-hpc/SKILL.md"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "dsh-bundle",
+    "slurm",
+    "hpc",
+    "hygon",
+    "dcu"
+  ],
+  "license": "MIT"
+}

package/skills/scnet-hpc/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: scnet-hpc
+description: 在超算互联网（scnet.cn）及同类国产超算集群上工作 —— 从个人电脑（macOS/Linux）配置 SSH 连接、提交和监控 Slurm 作业、交互式调试、排查作业失败、安装 Python 依赖，以及查找海光 DCU/DTK 的官方开发文档、数学库、通信库、分析调试和 CUDA 迁移工具。当任务涉及超算集群、Slurm 作业、海光 DCU / DTK / gfx9xx、DTK 工具库选型、或需要写 sbatch 脚本、判断该在登录节点还是计算节点执行某件事时使用。集群参数存在 clusters/*.conf，支持多集群。
+---
+
+# 国产超算集群使用规范
+
+面向超算互联网（scnet.cn）系列集群。**集群参数不写在文档里，存在
+`clusters/<集群短名>.conf`**，脚本从 profile 读取，所以同一套流程能用于多个集群。
+
+## 先确认在跟哪个集群打交道
+
+```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/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` | 国产超算上的软件兼容性排查、验证分层与公开报告脱敏 |
+
+## 换机器
+
+本插件已随 DeepSeek Harness 安装，换机器时用 `dsh plugin --profile web add` 重装即可。
+配置集群连接：
+
+```bash
+./scripts/setup-ssh.sh <私钥文件>              # 配连接（自动读唯一的 profile）
+```
+## 新增集群
+
+```bash
+# 1. 手工确认能 ssh 上去（用平台给的私钥）
+# 2. 探测，自动填大部分字段
+./scripts/probe-cluster.sh <ssh别名> <集群短名> > clusters/<集群短名>.conf
+# 3. 补齐探测不到的项（加速器型号、module 名等），profile 里有提示
+```
+
+完整步骤见 `references/adding-cluster.md`。
+
+## 通用硬约束
+
+以下几条在国产超算上普遍存在，**具体数值查 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`。
+
+登录节点能做：`pip install`、`git`、读写文件、`sacct`/`squeue`、下载模型。
+
+### 4. 计算节点通常无外网 —— 依赖必须预装
+
+profile 的 `NET_OK` / `NET_BLOCKED` 记录了登录节点的可达情况。计算节点若
+`COMPUTE_NODE_OFFLINE=yes` 则完全无外网。
+
+任何**运行时从网上拉东西**的库都会在计算节点炸掉。典型的是 `transformers` 的
+`kernels` 机制（从 HF Hub 下载预编译 kernel）。作业脚本里先声明离线，
+让失败快速且信息明确：
+
+```bash
+export HF_HUB_OFFLINE=1
+export TRANSFORMERS_OFFLINE=1
+```
+
+### 5. `/tmp` 通常不跨节点共享 —— 文件放家目录
+
+`TMP_SHARED=no` 时，`/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 小时
+```
+
+上传后先验证配额而不真排队：
+
+```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     ← 可能是假的！
+```
+
+而日志里 Python 早就抛异常了，甚至还打印了脚本末尾的 "COMPLETE" 字样。
+
+**判断作业成功不能只看 `sacct` 的 State，必须读日志。**
+
+## 交互式调试（推荐）
+
+比 sbatch 快得多，适合试代码、查环境、验证假设。实测约 5 秒拿到节点：
+
+```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 为准；不要把网页当前版本直接覆盖到集群环境。
+
+**不要假设加速器支持什么。** 国产加速器（海光 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`，别让下一个人重踩。
+
+## 排查失败
+
+1. **先读日志，不要相信 `sacct` 的 State**
+2. `.err` 被 `Loading weights: ...%` 进度条刷屏时，`grep -v` 过滤掉再看
+3. 按报错分类：
+
+| 报错 | 原因 |
+|---|---|
+| `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 路线 |
+| `sacct` COMPLETED 但结果不对 | 脚本缺 `exit $rc` |
+
+完整手册见 `references/troubleshooting.md`。
+
+## 公开报告与知识沉淀
+
+将集群实测结果写入公开报告或仓库前，保留环境、方法、版本、结果和限制，移除或替换以下信息：用户名、SSH 主机/端口、内部域名、IP、节点名、作业编号、绝对家目录和私有镜像地址。可用 `<USER_HOME>`、`<DTK_ROOT>`、`<CLUSTER_HOST>`、`已脱敏作业` 等占位符。
+
+报告正文沿用已有 LAMMPS 报告的结构和风格：深色渐变卡片、青绿色主色、蓝色辅助色，以及“环境信息 → 编译过程与主要难题 → 最终方案 → 测试结果 → 已知限制 → 经验总结 → 附录”的叙述顺序。公开结论必须标明测试环境、验证范围和未验证边界。
+
+详细的兼容性排查和报告模板见 `references/software-compatibility.md`。

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

@@ -0,0 +1,59 @@
+# 集群 profile 模板
+#
+# 新增集群：
+#   1. cp _template.conf <集群短名>.conf
+#   2. 填下面的值（不确定的用 scripts/probe-cluster.sh 探测）
+#   3. scripts/setup-ssh.sh --cluster <集群短名> <私钥文件>
+#
+# 只有 CLUSTER_ID / SSH_HOST / SSH_PORT 是必填，其余可留空，
+# 留空的项脚本会跳过、文档里显示为「未探测」。
+
+# ---- 连接（必填）----
+CLUSTER_ID=""                            # 短名，同时用作 ssh 别名，如 "zzeshell"
+CLUSTER_DESC=""                          # 人类可读描述，如 "海光 DCU（郑州）"
+SSH_HOST=""                              # 如 "xxx.scnet.cn"
+SSH_PORT="22"
+HOME_BASE="/public/home"                 # 家目录父路径
+
+KEY_NAME_MARKER=""                       # 私钥文件名里的主机标识，如 "_xxx.scnet.cn_"
+NEEDS_UPDATE_HOSTKEYS_NO="no"            # 平台主机密钥签名有问题时设 yes
+
+# ---- 调度器 ----
+SCHEDULER="slurm"
+PARTITION=""
+
+DEF_MEM_PER_CPU=""                       # MB。scontrol show partition <名> 里的 DefMemPerCPU
+MIN_GRES=""                              # QOS 强制的最小 GRES，如 "dcu:1"；无则留空
+GRES_TYPE=""                             # "dcu" / "gpu" / "npu" 等
+MAX_WALLTIME=""
+
+# ---- 硬件 ----
+ACCEL_NAME=""                            # 如 "海光 BW1000 DCU" / "NVIDIA A100"
+ACCEL_ARCH=""                            # 如 "gfx936" / "sm80"
+ACCEL_PER_NODE=""
+ACCEL_MEM_GB=""
+CPUS_PER_NODE=""
+CPU_MODEL=""
+NODE_MEM_GB=""
+NODE_COUNT=""
+LOGIN_NODES=""
+HOME_QUOTA_GB=""
+
+# ---- 软件栈 ----
+TOOLCHAIN=""                             # "DTK" / "CUDA" / "ROCm" 等
+TOOLCHAIN_VERSION=""
+TOOLCHAIN_PATH=""
+MODULE_LOADS=""                          # 空格分隔的 module load 参数
+
+DEFAULT_VENV=""                          # 相对家目录的 venv 路径
+
+# ---- 网络 ----
+NET_OK=""
+NET_BLOCKED=""
+PIP_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
+COMPUTE_NODE_OFFLINE="yes"               # 多数超算的计算节点无外网
+TMP_SHARED="no"
+
+# ---- 已知问题 ----
+LOGIN_NODE_MISSING_LIBS=""               # 登录节点缺失的库
+KNOWN_LIMITATIONS=""                     # 硬件/软件栈的能力缺口