dsh-scnet 0.4.1 → 0.5.0

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`，需手填 |

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

@@ -0,0 +1,177 @@
+# SCNet backend selection and extension
+
+The skill separates cluster intent from transport. SSH and OpenAPI are built in; future MCP
+servers, platform connectors, and site-specific gateways can be added without changing the
+task-level commands.
+
+## Selection
+
+Backend precedence:
+
+1. `--backend <name>`;
+2. `SCNET_HPC_BACKEND`;
+3. saved setup-panel `default_backend`;
+4. selected profile `DEFAULT_BACKEND`;
+5. `ssh`.
+
+Do not silently fall back between backends. A failed OpenAPI request must not become an SSH
+submission, and a failed SSH command must not be replayed through OpenAPI. Replaying mutations
+can duplicate jobs or apply them to a different region.
+
+List registered implementations and their declared capabilities:
+
+```bash
+python3 scripts/scnet.py backends
+python3 scripts/scnet.py --backend <name> capabilities
+```
+
+Built-in capability summary:
+
+| Domain / operation | SSH | OpenAPI |
+|---|---:|---:|
+| Local profiles / authorized regions | yes | yes |
+| Queues and limits | yes | yes |
+| Job status and logs | yes | yes |
+| Submit and cancel | yes | yes |
+| Upload and download | yes | yes |
+| Create remote directory | no | yes |
+| Arbitrary remote command | yes | no |
+| Modules, builds, interactive diagnosis | yes | no |
+| Notebook read-only discovery | no | yes |
+
+Use OpenAPI for structured control-plane work. Use SSH for environment setup, compilation,
+interactive inspection, full scheduler tooling, and operations not represented by a structured
+backend.
+
+## Common CLI
+
+On a new computer, start with the dependency-light Bash panel:
+
+```bash
+./scripts/setup.sh
+python3 scripts/scnet.py doctor
+```
+
+Configuration lifecycle:
+
+```bash
+./scripts/setup.sh new
+./scripts/setup.sh modify
+./scripts/setup.sh status
+./scripts/setup.sh reset
+```
+
+`new` adds a connection without replacing an existing profile/account. `modify` preserves
+unrelated configuration. `status` is read-only. `reset` is scoped and does not remove real SSH
+keys or `~/.ssh/config` unless that is performed separately and explicitly.
+
+Use `./scripts/setup.sh --skip-connect` when only local selections should be saved. The Bash
+panel can be rerun to update a profile's SSH user/key metadata. OpenAPI uses one platform
+credential set and discovers regions, users, schedulers, and home paths automatically; no region
+ID is required during setup.
+Developers
+can use `python3 scripts/scnet.py setup` for live OpenAPI region discovery. Both panels store no
+secrets; provide OpenAPI credentials through a host credential manager or environment injection.
+
+Region selection is multi-select for local enablement, followed by a single default region.
+Mutating operations remain single-region by design.
+
+Global options must appear before the operation:
+
+```bash
+python3 scripts/scnet.py --backend ssh --cluster <profile> queues
+python3 scripts/scnet.py --backend openapi --region <region-id> limits
+python3 scripts/scnet.py --backend openapi --region <region-id> job <job-id>
+```
+
+Use `--dry-run` before a mutation to inspect the normalized action without contacting the
+backend:
+
+```bash
+python3 scripts/scnet.py --backend openapi --dry-run \
+  submit --name smoke --queue debug --work-dir /absolute/work/dir \
+  --command 'echo hello'
+```
+
+Mutating examples:
+
+```bash
+python3 scripts/scnet.py --backend ssh --cluster <profile> \
+  submit --remote-path /absolute/path/job.slurm
+
+python3 scripts/scnet.py --backend openapi --region <region-id> submit \
+  --name probe --queue debug --work-dir /absolute/work/dir \
+  --command 'python3 probe.py' --dcus 1 --cpus 8 --walltime 00:10:00
+```
+
+The CLI does not interpret a command as authorization. Follow the skill's mutation boundaries
+before invoking submit, cancel, upload, download, or `exec`.
+
+## External backend protocol
+
+An external backend is an executable named:
+
+```text
+scnet-hpc-backend-<name>
+```
+
+Discover it either by:
+
+- placing it in a directory listed by `SCNET_HPC_BACKEND_PATH`; or
+- placing it on `PATH` and listing `<name>` in `SCNET_HPC_EXTERNAL_BACKENDS`.
+
+The router writes one JSON request to standard input:
+
+```json
+{
+  "protocol": "scnet-hpc.backend",
+  "protocol_version": 1,
+  "operation": "queues",
+  "profile_name": "example",
+  "profile": {},
+  "options": {}
+}
+```
+
+The executable returns one JSON object:
+
+```json
+{
+  "ok": true,
+  "protocol_version": 1,
+  "data": []
+}
+```
+
+It must implement the `capabilities` operation and return:
+
+```json
+{"ok": true, "protocol_version": 1, "data": {"capabilities": ["clusters", "queues"]}}
+```
+
+Return `{"ok": false, "error": "..."}` for a bounded failure. Never print credentials or tokens
+to standard output or standard error.
+
+## MCP and connector integration
+
+If an official SCNet MCP server becomes available, prefer its native tools when the host exposes
+them and the user has selected or authorized that connection. Keep the same normalized operation
+semantics: clusters, queues, limits, job, logs, submit, cancel, files, upload, and download.
+
+For hosts that cannot expose MCP tools directly, use a small
+`scnet-hpc-backend-mcp` bridge implementing the protocol above. Platform connectors can use the
+same adapter pattern. Do not hard-code speculative MCP tool names, schemas, or authentication
+until the official interface is available and verified.
+
+## Profiles
+
+Profiles may contain non-secret backend hints:
+
+```bash
+DEFAULT_BACKEND="ssh"
+OPENAPI_REGION_ID=""
+OPENAPI_SCHEDULER_ID=""
+OPENAPI_USERNAME=""
+```
+
+Keep AK, SK, tokens, cookies, and passwords out of profiles.

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

@@ -0,0 +1,60 @@
+# Notebook service
+
+Notebook is a separate SCNet OpenAPI service domain. It reuses platform authentication and
+region discovery, but it is not a Slurm job and does not use `hpcUrls`.
+
+Read-only commands:
+
+```bash
+python3 scripts/scnet.py --backend openapi notebook regions
+python3 scripts/scnet.py --backend openapi --region <id> notebook resources
+python3 scripts/scnet.py --backend openapi --region <id> notebook images
+python3 scripts/scnet.py --backend openapi --region <id> notebook list
+python3 scripts/scnet.py --backend openapi --region <id> notebook show <notebook-id>
+python3 scripts/scnet.py --backend openapi --region <id> notebook url <notebook-id>
+```
+
+The default output redacts SSH passwords and URL query credentials. Use `--reveal` only when
+the user explicitly needs a URL to open, and do not place the resulting value in reports or
+long-lived logs.
+
+Lifecycle commands:
+
+```bash
+python3 scripts/scnet.py --dry-run --backend openapi \
+  notebook create --region <id>
+python3 scripts/scnet.py --backend openapi \
+  notebook create --region <id>
+python3 scripts/scnet.py --backend openapi \
+  notebook start <id> --region <id>
+python3 scripts/scnet.py --backend openapi \
+  notebook stop <id> --region <id>
+python3 scripts/scnet.py --backend openapi \
+  notebook release <id> --region <id>
+```
+
+`create` automatically chooses the smallest currently available resource and the smallest
+trusted preset Jupyter image. Advanced users may override the resource group or image ID.
+
+`smoke` performs a bounded lifecycle:
+
+```bash
+python3 scripts/scnet.py --dry-run --backend openapi \
+  notebook smoke --region <id>
+python3 scripts/scnet.py --backend openapi \
+  notebook smoke --region <id>
+```
+
+It creates one minimal Notebook, waits for `Running`, validates the redacted Jupyter URL, then
+stops and releases the instance in a cleanup block.
+
+Mutations require interactive confirmation. Non-interactive callers must pass `--yes`. Release
+requires the Notebook ID in interactive mode because it is irreversible.
+
+Official API sections:
+
+- Notebook resource discovery;
+- image discovery;
+- instance list/detail;
+- Jupyter URL lookup;
+- instance lifecycle.

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

@@ -0,0 +1,140 @@
+# SCNet OpenAPI backend
+
+This backend follows the official SCNet OpenAPI 2.0 documentation reviewed on
+2026-09-26:
+
+- Overview: <https://www.scnet.cn/ac/openapi/doc/2.0/index.html>
+- Recommended AK/SK authentication:
+  <https://www.scnet.cn/ac/openapi/doc/2.0/api/safecertification/get-user-tokens-aksk.html>
+- Job submission:
+  <https://www.scnet.cn/ac/openapi/doc/2.0/api/jobmanager/job.html>
+- Creating a directory:
+  <https://www.scnet.cn/ac/openapi/doc/2.0/api/efile/folder-create.html>
+- Chunked upload and merge:
+  <https://www.scnet.cn/ac/openapi/doc/2.0/api/efile/chunk-upload.html>
+  and <https://www.scnet.cn/ac/openapi/doc/2.0/api/efile/merge-file.html>
+
+The local implementation intentionally normalizes large responses. Use `--raw` only when the
+compact result is insufficient.
+
+## Credentials
+
+Obtain AK/SK from the SCNet website:
+
+1. Sign in to SCNet.
+2. Open **Personal Center / 个人中心**.
+3. Open **Access Control / 访问控制**.
+4. Generate and download the authorization file containing AccessKey and SecretKey.
+
+Official instructions:
+<https://www.scnet.cn/ac/openapi/doc/2.0/api/safecertification/get-user-tokens-aksk.html>
+
+Preferred environment variables:
+
+```bash
+export SCNET_OPENAPI_USER="<platform-user>"
+export SCNET_OPENAPI_ACCESS_KEY="<access-key>"
+export SCNET_OPENAPI_SECRET_KEY="<secret-key>"
+```
+
+The client signs the canonical AK/timestamp/user JSON with HMAC-SHA256 and obtains a fresh
+per-region token for each invocation. It does not persist tokens. The setup panel can store the
+platform credential set in macOS Keychain or Linux Secret Service; otherwise use environment
+variables. Region IDs, region users, schedulers, and home paths are discovered and cached as
+non-secret metadata.
+
+Interactive terminals support ↑/↓ plus Enter and direct numeric selection. Press Enter without
+typing a number to accept the current/default item. SecretKey input is intentionally invisible.
+This behavior is the same in macOS Terminal/iTerm2 and Ubuntu/Debian terminals.
+Ubuntu/Debian users can install `secret-tool` with `sudo apt install libsecret-tools`.
+
+For an externally managed token:
+
+```bash
+export SCNET_OPENAPI_TOKEN="<region-token>"
+export SCNET_OPENAPI_REGION_ID="<region-id>"
+```
+
+Optional overrides:
+
+```bash
+export SCNET_OPENAPI_AUTH_BASE="https://api.scnet.cn"
+export SCNET_OPENAPI_CENTER_URL="https://www.scnet.cn/ac/openapi/v2/center"
+export SCNET_OPENAPI_SCHEDULER_ID="<scheduler-id>"
+export SCNET_OPENAPI_USERNAME="<region-user>"
+```
+
+Never put these values in a prompt, profile, repository file, generated report, or shell trace.
+Use the host's credential store or secret injection when available.
+
+## Read-only operations
+
+```bash
+python3 scripts/scnet.py --backend openapi clusters
+python3 scripts/scnet.py --backend openapi --region <id> queues
+python3 scripts/scnet.py --backend openapi --region <id> limits
+python3 scripts/scnet.py --backend openapi --region <id> job <job-id>
+python3 scripts/scnet.py --backend openapi --region <id> \
+  logs --path /absolute/path/std.out.123 --lines 200
+python3 scripts/scnet.py --backend openapi --region <id> \
+  files --path /absolute/path
+python3 scripts/scnet.py --backend openapi --region <id> \
+  mkdir /absolute/work/dir --parents
+```
+
+If a region exposes multiple schedulers, add `--scheduler-id`.
+
+## Mutations
+
+OpenAPI submission uses the documented BASIC/BASE command mode. Extra scheduler directives can
+be repeated:
+
+```bash
+python3 scripts/scnet.py --backend openapi --region <id> submit \
+  --name probe --queue debug --work-dir /absolute/work/dir \
+  --command $'module load ...\npython3 probe.py' \
+  --nodes 1 --cpus 8 --dcus 1 --walltime 00:10:00 \
+  --scheduler-option '#SBATCH --account=example'
+```
+
+Other mutations:
+
+```bash
+python3 scripts/scnet.py --backend openapi --region <id> cancel <job-id>
+python3 scripts/scnet.py --backend openapi --region <id> \
+  upload local.file /absolute/remote/directory
+python3 scripts/scnet.py --backend openapi --region <id> \
+  download /absolute/remote/file local.file
+```
+
+Downloads refuse to replace an existing local path unless `--cover` is supplied. Uploads send
+`uncover` by default and require `--cover` for replacement.
+
+Uploads larger than 8 MiB automatically use the documented burst/merge flow. Override the
+threshold and chunk size with `--chunk-size <bytes>`; use `--chunk-size 0` to force ordinary
+multipart upload. The current implementation keeps one chunk in memory at a time.
+
+Preview a mutation without contacting the backend:
+
+```bash
+python3 scripts/scnet.py --backend openapi --region <id> --dry-run \
+  submit --name probe --queue debug --work-dir /absolute/work/dir \
+  --command 'echo hello' --cpus 1 --dcus 1
+```
+
+Do not automatically retry submission or cancellation after a timeout. Query job state first:
+the public documentation does not establish an idempotency key for submission.
+
+## Known validation boundaries
+
+- The implementation is validated locally for parsing, signing, routing, normalization, and the
+  external-backend contract. Live OpenAPI operations still require testing against each
+  authorized SCNet region.
+- The official cancellation page describes one method value in prose and uses `5` in all request
+  examples. The client defaults to `5`; override it with `SCNET_OPENAPI_CANCEL_METHOD` if a live
+  region requires a different documented value.
+- Small ordinary uploads buffer one file in memory; large uploads use chunked transfer.
+- OpenAPI does not replace SSH for module discovery, environment construction, compilation,
+  interactive `srun`, performance profiling, or low-level scheduler diagnosis.
+- API success is determined by both HTTP transport and the JSON `code`; HTTP 200 alone is not
+  sufficient.

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

@@ -19,6 +19,28 @@ Check at least `PARTITION`, `PARTITION_CPU`, `GRES_TYPE`, `MIN_GRES`,
 `DEF_MEM_PER_CPU`, `MODULE_LOADS`, `COMPUTE_NODE_OFFLINE`, and
 `KNOWN_LIMITATIONS`.
 
+On a new computer, run the Bash setup panel and then its read-only doctor:
+
+```bash
+./scripts/setup.sh
+python3 scripts/scnet.py doctor
+```
+
+List available access backends:
+
+```bash
+python3 scripts/scnet.py backends
+```
+
+SSH is the default. Use OpenAPI for structured queue, limit, job, log, and file operations:
+
+```bash
+python3 scripts/scnet.py --backend openapi clusters
+python3 scripts/scnet.py --backend openapi --region <region-id> queues
+```
+
+See `references/backends.md` and `references/openapi.md` before configuring another backend.
+
 ## 2. Install the skill
 
 ```bash

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

@@ -85,6 +85,10 @@ ssh -O exit <集群>      # 手工断开（网络切换后卡住时用）
 `<用户名>_<主机>_RsaKeyExpireTime_2026-10-29_12-51-40.txt` 表示 2026-10-29 过期。
 到期前从控制台重新下载并重跑 setup 脚本。
 
+可以重复运行 `scripts/setup.sh` 更新某个 profile 的用户名和私钥。面板会从密钥文件名
+中的 `RsaKeyExpireTime_YYYY-MM-DD` 自动记录有效期，`python3 scripts/scnet.py doctor`
+会报告剩余天数和已过期状态。密钥内容不会进入配置文件。
+
 profile 里的 `KEY_NAME_MARKER` 就是用来从这种文件名里提取用户名的；公开
 `scnet-hpc` profile 使用 `_<CLUSTER_HOST>_` 占位符，所以安装时通常需要显式传
 用户名，或在本地私有 profile 中补齐真实标记。