dsh-scnet 0.4.2 → 0.5.0

package/README.md

@@ -2,7 +2,9 @@
 
 [简体中文](./README_CN.md)
 
-DSH-SCNet (`dsh-scnet` on npm) is a community-maintained DSH bundle for operating Supercomputing Network (SCNet) clusters. It packages the canonical [`scnet-hpc`](https://github.com/lql341/scnet-hpc) skill, profile-aware shell utilities, and seven deterministic tools for SSH setup, Slurm job generation, cluster discovery, and compute-node diagnostics.
+DSH-SCNet (`dsh-scnet` on npm) is a community-maintained DSH bundle for operating Supercomputing Network (SCNet). It packages the source [`scnet-hpc`](https://github.com/lql341/scnet-hpc) Skill, profile-aware utilities, and bounded tools for SSH, Slurm, OpenAPI files, regional resources, and Notebook discovery.
+
+Current release: **0.5.0**
 
 > This is an independent community project. It is compatible with DeepSeek Harness but is not an official DeepSeek product and does not imply endorsement, partnership, or authorization by DeepSeek.
 
@@ -40,6 +42,14 @@ See [Installation](./docs/installation.md) for npm, GitHub, and local-checkout w
 | `scnet_probe_cluster` | Produce an initial profile from read-only login-node probes |
 | `scnet_refresh_cluster` | Refresh time-sensitive profile fields; compute probing is opt-in |
 | `scnet_run_compute_probe` | Submit a minimal compute-node capability probe |
+| `scnet_status` | Read the saved backend, SSH profile, and OpenAPI configuration |
+| `scnet_openapi_regions` | List authorized OpenAPI regions without exposing tokens |
+| `scnet_job_queues` | Query regional Slurm queues and live resource availability |
+| `scnet_file_list` | List shared-storage files through the common file API |
+| `scnet_notebook_regions` | List Notebook-capable regions |
+| `scnet_notebook_resources` | Query Notebook CPU/GPU/DCU resources |
+| `scnet_notebook_list` | List Notebook instances with sensitive fields redacted |
+| `scnet_notebook_show` | Inspect one redacted Notebook instance |
 
 Packaged profiles currently cover Zhengzhou, Kunshan, Wuzhen, and Xi'an SCNet environments. Cluster specifications and scheduler policies remain profile-specific and should be verified against the target environment.
 
@@ -55,6 +65,8 @@ Packaged profiles currently cover Zhengzhou, Kunshan, Wuzhen, and Xi'an SCNet en
 │   ├── clusters/
 │   ├── references/
 │   └── scripts/
+│       ├── scnet_backends/
+│       └── scnet_sdk/
 ├── scripts/validate-package.mjs
 ├── docs/
 ├── sync.sh
@@ -87,6 +99,8 @@ See [Testing](./docs/testing.md) for local package installation and risk-ordered
 
 - The repository and npm package must not contain private keys, tokens, usernames, private endpoints, or local probe caches.
 - SSH configuration, remote probes, and Slurm submission are state-changing operations and require an explicit target and user authorization.
+- OpenAPI and Notebook DSH tools are read-only; lifecycle mutations remain behind the Skill CLI confirmation flow.
+- Notebook passwords and credential-bearing URL queries are redacted by default.
 - Generated Slurm files may include local usernames and are ignored by Git.
 - Accelerator compatibility claims require evidence from the target compute node.
 
@@ -96,6 +110,11 @@ The project uses the abbreviated `DSH` ecosystem identifier in its name. Referen
 
 The naming and attribution policy follows the [DeepSeek Harness brand guidelines](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.0-rc.8/BRAND_GUIDELINES.md).
 
+## Versioning
+
+The npm package version matches `skills/scnet-hpc/VERSION` and follows the same SemVer release
+train as the source Skill.
+
 ## License
 
 This project is released under the [MIT License](LICENSE). Subject to the license terms, the software may be used, copied, modified, merged, published, sublicensed, and distributed, including for commercial purposes.

package/README_CN.md

@@ -2,7 +2,9 @@
 
 [English](./README.md) | 简体中文
 
-<p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）集群：配 SSH、生成 CPU/DCU Slurm 作业、探测/刷新集群、运行计算节点探针、排查失败，附海光 DCU/DTK 知识和英文快速指南。</p>
+<p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
+
+当前版本：**0.5.0**
 
 > 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。
 
@@ -48,6 +50,14 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 | scnet_probe_cluster | 探测新集群并生成 profile |
 | scnet_refresh_cluster | 动态刷新已有集群的规则缓存 |
 | scnet_run_compute_probe | 在计算节点运行最小能力探针 |
+| scnet_status | 只读查看 backend、SSH profile 和 OpenAPI 配置 |
+| scnet_openapi_regions | 列出授权 OpenAPI 区域，不暴露 token |
+| scnet_job_queues | 查询区域 Slurm 队列和实时空闲资源 |
+| scnet_file_list | 通过通用文件 API 列出共享存储 |
+| scnet_notebook_regions | 列出支持 Notebook 的区域 |
+| scnet_notebook_resources | 查询 Notebook CPU/GPU/DCU 资源 |
+| scnet_notebook_list | 列出 Notebook 实例并脱敏敏感字段 |
+| scnet_notebook_show | 查询一个脱敏后的 Notebook 实例详情 |
 
 ## 文档
 
@@ -68,6 +78,8 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 │   │   ├── wuzhshell.conf
 │   │   └── xianshell.conf
 │   ├── scripts/
+│   │   ├── scnet_backends/
+│   │   └── scnet_sdk/
 │   └── references/
 ├── sync.sh               # 从 canonical 仓库同步
 ├── README.md             # 英文默认说明
@@ -96,6 +108,8 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 - `scnet_generate_job` 生成的 `.slurm` 可能含本机用户名，`.gitignore` 已排除。
 - SSH 接入端点仅使用平台面向用户公开提供的信息，由 canonical 仓库维护。
 - `scnet_refresh_cluster` / `scnet_run_compute_probe` 会 SSH 到远端并可能提交作业；运行前确认集群和副作用。
+- 新增 OpenAPI 和 Notebook DSH 工具均为只读；Notebook 生命周期变更仍通过 Skill CLI 的确认流程执行。
+- Notebook 密码和带凭据的 URL 查询参数默认脱敏。
 - `clusters/.cache/` 是本机动态探测缓存，`.gitignore` 已排除，不应提交。
 
 ## License
@@ -105,3 +119,8 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 再发布本项目或其重要组成部分时，应保留版权声明和 MIT 许可声明。本项目按“现状”提供，不对适销性、特定用途适用性或不侵权作任何明示或默示保证；使用者应自行评估 DSH bundle、skill 说明、集群配置、脚本和生成结果在其环境中的适用性与风险。
 
 项目命名与归属声明遵循 [DeepSeek Harness 品牌素材使用规范](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.0-rc.8/BRAND_GUIDELINES.zh.md)。
+
+## 版本管理
+
+npm package 版本与 `skills/scnet-hpc/VERSION` 保持一致，并与源 Skill 使用同一套 SemVer
+发布版本。

package/docs/installation.md

@@ -58,3 +58,13 @@ dsh web
 ## Credentials
 
 Model credentials belong in the DSH credential store or its supported settings interface. SCNet private keys remain local and are supplied only when the user explicitly invokes SSH setup. Neither credential type belongs in this repository.
+
+SCNet OpenAPI uses a platform username, AccessKey, and SecretKey. Configure them through the
+bundled Skill:
+
+```sh
+python3 skills/scnet-hpc/scripts/scnet.py setup modify --mode openapi
+```
+
+On macOS credentials can be stored in Keychain. On Linux, install `libsecret-tools` for Secret
+Service; otherwise inject the documented `SCNET_OPENAPI_*` environment variables.

package/docs/installation.zh-CN.md

@@ -1,6 +1,7 @@
 # 安装 DSH-SCNet
 
-DSH-SCNet（npm 包名：`dsh-scnet`） 是一个 DeepSeek Harness（DSH）bundle 插件，把国产超算集群使用规范打包成 skill 和 7 个工具。
+DSH-SCNet（npm 包名：`dsh-scnet`）是一个 DeepSeek Harness（DSH）bundle 插件，把
+SCNet 使用规范、SSH/Slurm 工具、OpenAPI 只读资源工具和 Notebook 资源工具打包到一起。
 
 ## 前置条件
 
@@ -71,3 +72,14 @@ DEEPSEEK_API_KEY: sk-你的key
 ```
 
 保存后无需重启，下一次请求即生效。Key 只保存在本机 `~/.dsh` 下，不会写入仓库。
+
+## 配置 SCNet OpenAPI
+
+SCNet OpenAPI 使用平台用户名、AccessKey 和 SecretKey：
+
+```sh
+python3 skills/scnet-hpc/scripts/scnet.py setup modify --mode openapi
+```
+
+macOS 可保存到 Keychain。Linux 安装 `libsecret-tools` 后使用 Secret Service；否则通过
+文档定义的 `SCNET_OPENAPI_*` 环境变量注入。OpenAPI 凭据不会写入插件仓库。

package/docs/testing.md

@@ -37,6 +37,14 @@ Confirm that the composed configuration includes:
 | `scnet_list_clusters` | Returns the packaged cluster identifiers |
 | `scnet_show_cluster` | Returns the selected profile contents |
 | `scnet_generate_job` | Writes a profile-aware Slurm script in the current directory |
+| `scnet_status` | Returns redacted local SCNet configuration |
+| `scnet_openapi_regions` | Returns authorized regions without tokens |
+| `scnet_job_queues` | Returns live regional Slurm queues |
+| `scnet_file_list` | Lists shared-storage files without modification |
+| `scnet_notebook_regions` | Lists Notebook-capable regions |
+| `scnet_notebook_resources` | Returns Notebook resource groups |
+| `scnet_notebook_list` | Lists redacted Notebook instances |
+| `scnet_notebook_show` | Returns one redacted Notebook instance |
 
 Check both accelerator and CPU-only job generation. Review the output for the selected partition, memory, and GRES rules.
 
@@ -52,6 +60,9 @@ Check both accelerator and CPU-only job generation. Review the output for the se
 
 `scnet_run_compute_probe` and refresh operations with compute probing submit Slurm jobs. Confirm the target cluster, account policy, accelerator count, CPU count, and time limit before execution.
 
+Notebook lifecycle mutations are intentionally not exposed as deterministic DSH tools in this
+release. Test them only through the Skill CLI and start with `--dry-run`.
+
 ## Cleanup
 
 Remove the isolated test profile after verification:

package/docs/testing.zh-CN.md

@@ -58,5 +58,15 @@ DEEPSEEK_API_KEY: sk-你的key
 | 5 | 用 scnet_probe_cluster 探测集群 | 需要真实集群，会 SSH 到远端 | 中 |
 | 6 | 用 scnet_refresh_cluster dry_run=true 刷新规则 | 输出即将写入的缓存，不落盘 | 中（会 SSH） |
 | 7 | 用 scnet_run_compute_probe 跑计算节点探针 | 返回 PROBE_ 结果 | 高（提交作业并等待） |
+| 8 | 用 scnet_status 查看当前配置 | 返回脱敏配置 | 只读 |
+| 9 | 用 scnet_openapi_regions 查看授权区域 | 返回区域且不含 token | 只读 |
+| 10 | 用 scnet_job_queues 查看昆山队列 | 返回实时队列和空闲资源 | 只读 |
+| 11 | 用 scnet_file_list 查看默认目录 | 返回共享存储文件 | 只读 |
+| 12 | 用 scnet_notebook_regions 查看区域 | 返回 Notebook 可用区域 | 只读 |
+| 13 | 用 scnet_notebook_resources 查看昆山资源 | 返回 CPU/GPU/DCU 资源 | 只读 |
+| 14 | 用 scnet_notebook_list 查看实例 | 返回脱敏实例列表 | 只读 |
 
 第 4 至 7 步只有在你有私钥和目标集群时才测，测前确认副作用。
+
+Notebook 创建、启动、停止和释放没有作为 DSH deterministic tool 暴露。此类操作通过
+Skill CLI 执行，并先使用 `--dry-run`。

package/index.mjs

@@ -31,6 +31,35 @@ function runBash(script, args, timeoutMs = 120000, cwd = SKILL_DIR) {
   })
 }
 
+function runScnet(args, timeoutMs = 120000) {
+  return new Promise((resolve) => {
+    execFile(
+      'python3',
+      [join(SCRIPTS_DIR, 'scnet.py'), '--json', ...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 scnetResult(res, action) {
+  if (res.ok) return res.stdout.trim() || '{}'
+  return `${action}失败（exit ${res.code}）：\n${res.stderr.trim() || res.stdout.trim()}`
+}
+
+function regionArgs(region) {
+  const value = String(region || '').trim()
+  return value ? ['--region', value] : []
+}
+
 function textBlock(value) {
   return [{ type: 'text', text: value }]
 }
@@ -91,6 +120,161 @@ export function apply(ctx) {
     }),
   )
 
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_status',
+      description: '只读查看 scnet-hpc 当前默认 backend、SSH profile 和 OpenAPI 区域配置；不会连接远端或修改配置。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        return scnetResult(await runScnet(['config']), '读取 SCNet 配置')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_openapi_regions',
+      description: '通过已配置的 SCNet OpenAPI 凭据只读列出授权计算区域，不显示 token。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        return scnetResult(
+          await runScnet(['--backend', 'openapi', 'clusters']),
+          '查询 OpenAPI 区域',
+        )
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_job_queues',
+      description: '通过 OpenAPI 只读查询目标区域可访问的 Slurm 队列、空闲资源和单作业限制。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用已保存的默认区域' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        return scnetResult(
+          await runScnet(['--backend', 'openapi', ...regionArgs(args.region), 'queues']),
+          '查询作业队列',
+        )
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_file_list',
+      description: '通过 OpenAPI 只读列出区域共享存储中的文件和目录。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+        path: { type: 'string', description: '绝对目录路径；省略时使用区域用户主目录' },
+        limit: { type: 'number', description: '最多返回条数，默认 100' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const argv = ['--backend', 'openapi', ...regionArgs(args.region), 'files']
+        if (args.path) argv.push('--path', String(args.path))
+        if (args.limit) argv.push('--limit', String(args.limit))
+        return scnetResult(await runScnet(argv), '查询文件')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_regions',
+      description: '只读列出支持 SCNet Notebook 服务的授权区域。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        return scnetResult(
+          await runScnet(['--backend', 'openapi', 'notebook', 'regions']),
+          '查询 Notebook 区域',
+        )
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_resources',
+      description: '只读查询目标区域可用于 Notebook 的 CPU/GPU/DCU 资源及当前空闲卡数。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const argv = ['--backend', 'openapi', 'notebook', 'resources']
+        if (args.region) argv.push('--region', String(args.region))
+        return scnetResult(await runScnet(argv), '查询 Notebook 资源')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_list',
+      description: '只读列出目标区域的 Notebook 实例；密码和带凭据的 URL 默认脱敏。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+        status: { type: 'string', description: '可选状态过滤，如 Running、Terminated、Failed' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const argv = ['--backend', 'openapi', 'notebook', 'list']
+        if (args.region) argv.push('--region', String(args.region))
+        if (args.status) argv.push('--status', String(args.status))
+        return scnetResult(await runScnet(argv), '查询 Notebook 实例')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_show',
+      description: '只读查询一个 Notebook 实例详情；敏感字段默认脱敏。',
+      parameters: {
+        notebook_id: { type: 'string', required: true, description: 'Notebook 实例 ID' },
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const id = String(args.notebook_id || '').trim()
+        if (!id) return '缺少必填参数 notebook_id。'
+        const argv = ['--backend', 'openapi', 'notebook', 'show', id]
+        if (args.region) argv.push('--region', String(args.region))
+        return scnetResult(await runScnet(argv), '查询 Notebook 详情')
+      },
+    }),
+  )
+
   ctx.tools.register(
     defineTool({
       name: 'scnet_show_cluster',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-scnet",
-  "version": "0.4.2",
-  "description": "Community DeepSeek Harness bundle for SCNet HPC: profile-based SSH, CPU/DCU Slurm jobs, cluster probing, compute-node diagnostics, and Hygon DCU/DTK guidance.",
+  "version": "0.5.0",
+  "description": "Community DeepSeek Harness bundle for SCNet SSH and OpenAPI jobs, files, Notebook resources, Slurm diagnostics, and Hygon DCU/DTK guidance.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
@@ -43,6 +43,8 @@
     "dsh-plugin",
     "dsh-bundle",
     "slurm",
+    "openapi",
+    "notebook",
     "hpc",
     "hygon",
     "dcu",

package/skills/scnet-hpc/SKILL.md

@@ -1,111 +1,69 @@
 ---
 name: scnet-hpc
-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.
+description: Configure or operate SCNet HPC through SSH, OpenAPI, and pluggable future backends.
 ---
 
 # SCNet HPC
 
-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.
-
-## 中文说明
-
-本技能用于通过 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)。
-
-## Source of truth
-
-- 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.
-
-List available profiles with:
-
-```bash
-ls clusters/*.conf
-```
-
-If more than one profile exists, require an explicit cluster selection before generating a
-job, changing SSH configuration, submitting work, or installing software.
-
-## Route the task
-
-Read only the references required for the current operation:
-
-| 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 |
-|---|---|
-| `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 |
-
-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
-
-Distinguish:
-
-- profile values;
-- live scheduler observations;
-- login-node observations;
-- compute-node observations;
-- conclusions inferred from those observations.
-
-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.
+Use the selected backend, cluster profile, and target-cluster evidence. SSH is the default;
+OpenAPI is the structured control plane. Never silently switch backends.
+
+## First use and selection
+
+- Run `scripts/setup.sh new|modify|status|reset` for explicit configuration lifecycle.
+- Advanced OpenAPI discovery: `python3 scripts/scnet.py setup`.
+- Read-only preflight: `python3 scripts/scnet.py doctor`.
+- Backend precedence: `--backend`, `SCNET_HPC_BACKEND`, saved setup choice, profile
+  `DEFAULT_BACKEND`, then `ssh`.
+- Read `clusters/<cluster>.conf` before reporting static facts. Treat
+  `clusters/.cache/<cluster>.auto.conf` as optional, time-sensitive SSH probe data.
+- With multiple profiles, require an explicit cluster before access changes, installation,
+  job generation, or submission. Query the selected backend for live queues, limits, and state.
+- SSH setup is profile-scoped; record usernames and key expiry metadata per profile. OpenAPI
+  credentials are platform-scoped and discover all authorized regions/schedulers automatically.
+- OpenAPI may enable multiple regions locally, but every mutating operation must resolve to one
+  explicit/default target region.
+
+Read [references/backends.md](references/backends.md) for backend selection and extension.
+Read [references/openapi.md](references/openapi.md) for OpenAPI credentials and limits.
+
+## Route only as needed
+
+- SSH access: `references/setup.md`
+- Python/modules/offline dependencies: `references/environment.md`
+- Scheduler/runtime/accelerator diagnosis: `references/troubleshooting.md`
+- Add or refresh profiles: `references/adding-cluster.md`
+- Hygon DCU/DTK/HIP/profiling: `references/hygon-dcu-development.md`
+- Compatibility reports: `references/software-compatibility.md`
+- English instructions: `references/quickstart-en.md`
+
+Read only the selected profile and references needed for the current operation. Profile values
+override examples.
+
+## Boundaries and evidence
+
+- Read-only inspection and local generation do not authorize remote mutation.
+- Resolve backend, target, paths, command, and expected effect before submit, cancel, upload,
+  download, overwrite, deletion, or SSH configuration. Never silently retry submission.
+- Compute probes consume scheduler resources; run them only when requested or required for
+  target-node evidence.
+- Keep credentials, tokens, personal paths, internal hosts, nodes, job IDs, and private mirrors
+  out of profiles and public reports.
+- Preserve existing SSH configuration; use `scripts/setup-ssh.sh` for bounded changes.
+- Respect profile-specific partition, GRES, memory, walltime, offline-network, and shared-storage
+  constraints. Propagate workload exit status.
+- Distinguish profile values, live scheduler state, login-node evidence, compute-node evidence,
+  and inference. Treat Hygon guidance as architecture/toolchain-specific.
+
+## Stable entrypoints
+
+- `scripts/setup.sh`: first-use configuration panel.
+- `python3 scripts/scnet.py ...`: backend-neutral operations, dry-run, raw output, and doctor.
+- `python3 scripts/scnet.py notebook ...`: Notebook discovery and confirmation-driven
+  lifecycle operations. Use `--dry-run` before create/start/stop/release.
+- `scripts/new-job.sh`: profile-aware Slurm generation.
+- `scripts/refresh-cluster.sh`: SSH-derived profile refresh.
+- `scripts/probe-cluster.sh`: initial profile creation.
+- `scripts/run-compute-probe.sh`: bounded accelerator probe.
+
+Use compact normalized output by default. Request raw backend data only for diagnosis.

package/skills/scnet-hpc/VERSION

@@ -0,0 +1 @@
+0.5.0

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

@@ -5,13 +5,14 @@
 #   2. 填下面的值（不确定的用 scripts/probe-cluster.sh 探测）
 #   3. scripts/setup-ssh.sh --cluster <集群短名> <私钥文件> [用户名]
 #
-# CLUSTER_ID / SSH_HOST / SSH_PORT 是必填连接参数，应写死；其余可留空。
-# 留空的项脚本会跳过、文档里显示为「未探测」。旧 profile 漏填 SSH_HOST 时，
-# _common.sh 会临时从本机 ssh config 补全，但新集群仍建议在此显式填写。
+# CLUSTER_ID 是 profile 标识。SSH backend 还要求 SSH_HOST / SSH_PORT；OpenAPI backend
+# 要求 OPENAPI_REGION_ID，并在多调度器区域填写 OPENAPI_SCHEDULER_ID。其余可留空。
+# 旧 SSH profile 漏填 SSH_HOST 时，_common.sh 会从本机 ssh config 尝试补全。
 
-# ---- 连接（必填）----
+# ---- 通用与 SSH 连接 ----
 CLUSTER_ID=""                            # 短名，同时用作 ssh 别名，如 "zzeshell"
 CLUSTER_DESC=""                          # 人类可读描述，如 "海光 DCU（郑州）"
+DEFAULT_BACKEND="ssh"                    # ssh / openapi / 已注册的外部 backend
 SSH_HOST=""                              # 如 "xxx.scnet.cn"
 SSH_PORT="22"
 HOME_BASE="/public/home"                 # 家目录父路径
@@ -19,6 +20,11 @@ HOME_BASE="/public/home"                 # 家目录父路径
 KEY_NAME_MARKER=""                       # 私钥文件名里的主机标识，如 "_xxx.scnet.cn_"
 NEEDS_UPDATE_HOSTKEYS_NO="no"            # 平台主机密钥签名有问题时设 yes
 
+# ---- OpenAPI（可选，不得写入凭据）----
+OPENAPI_REGION_ID=""                     # SCNet 授权区域 ID
+OPENAPI_SCHEDULER_ID=""                  # 区域存在多个调度器时填写
+OPENAPI_USERNAME=""                      # 通常由区域信息自动返回
+
 # ---- 调度器 ----
 SCHEDULER="slurm"
 PARTITION=""

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

@@ -134,12 +134,17 @@ Triton 是多种推理框架的运行前提；不可用时，对应的 Triton
 
 ## profile 字段参考
 
-必填三项：`CLUSTER_ID`、`SSH_HOST`、`SSH_PORT`。其余留空则脚本跳过、文档显示为未探测。
+`CLUSTER_ID` 是 profile 标识。使用 SSH backend 时还需要 `SSH_HOST` 和 `SSH_PORT`；
+使用 OpenAPI backend 时需要 `OPENAPI_REGION_ID`，区域存在多个调度器时再填写
+`OPENAPI_SCHEDULER_ID`。不得把 AK、SK 或 token 写进 profile。
 
 影响脚本行为的关键项：
 
 | 字段 | 谁用 | 留空的后果 |
 |---|---|---|
+| `DEFAULT_BACKEND` | `scnet.py` | 默认使用 `ssh` |
+| `OPENAPI_REGION_ID` | OpenAPI backend | 多区域账户需要每次显式传 `--region` |
+| `OPENAPI_SCHEDULER_ID` | OpenAPI backend | 多调度器区域需要每次显式传 `--scheduler-id` |
 | `MIN_GRES` | 文档提示 | 不提示 QOS 强制申请加速器 |
 | `GRES_TYPE` | `new-job.sh` | 生成的脚本不含 `--gres` |
 | `DEF_MEM_PER_CPU` | `new-job.sh` | 生成的脚本不含 `--mem`，需手填 |