dsh-scnet 0.6.2 → 0.6.4

package/README.md

@@ -4,11 +4,18 @@
 
 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.6.2**
+Current release: **0.6.4**
 
 > 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.
 
-## What's new in 0.6.2
+## What's new in 0.6.3
+
+- Added read-only account and resource summaries plus bounded `scnet_job_wait`.
+- Submission queue preflight now fails closed and never silently selects a queue.
+- Download paths can default to the remote filename; ordinary and chunked uploads return the same
+  directory/filename result shape.
+
+## 0.6.2 highlights
 
 - Completed jobs now resolve through the fast filtered history-list endpoint rather than timing
   out on the empty history-detail response.
@@ -67,11 +74,14 @@ See [Installation](./docs/installation.md) for npm, GitHub, and local-checkout w
 | `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_account_summary` | Read account status and balance |
+| `scnet_resource_summary` | Summarize regional queues and resource limits |
 | `scnet_job_queues` | Query regional Slurm queues and live resource availability |
 | `scnet_job_list` | List active or historical jobs with compact normalized records |
 | `scnet_limits` | Read user and scheduler resource limits |
 | `scnet_submit_job` | Submit a job through OpenAPI or SSH; `dry_run=true` only previews the request |
 | `scnet_job_show` | Read one job's state, resources, and log paths |
+| `scnet_job_wait` | Wait for a job to reach a terminal state with a bounded timeout |
 | `scnet_job_logs` | Read job logs by explicit path, or by `job_id` + `work_dir` |
 | `scnet_job_cancel` | Cancel a job; `dry_run=true` only previews the request |
 | `scnet_file_list` | List shared-storage files through the common file API |
@@ -120,7 +130,7 @@ synchronizes the skill and version into `dsh-scnet` and `codex-scnet-hpc`. Publi
 `dsh-scnet` npm package only after that downstream change is reviewed.
 
 For a synchronized release, run the package validation on `main`, then trigger the repository's
-`Publish DSH-SCNet` workflow with the exact value from `package.json` (currently `0.6.2`). The
+`Publish DSH-SCNet` workflow with the exact value from `package.json` (currently `0.6.3`). The
 workflow verifies the package/Skill version match, runs validation, creates the tarball, publishes
 stable releases with the `latest` tag, and creates the matching Git tag. Do not bump only
 `package.json`: `skills/scnet-hpc/VERSION`, the package version, and both README release markers

package/README_CN.md

@@ -4,10 +4,16 @@
 
 <p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
 
-当前版本：**0.6.2**
+当前版本：**0.6.4**
 
 > 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。
 
+## 0.6.3 更新
+
+- 新增只读账户摘要、资源摘要和有界等待作业工具 `scnet_job_wait`。
+- 提交前队列预检失败会停止提交，不再静默选择队列。
+- 下载时可省略本地路径自动使用远端文件名；普通上传和分片上传返回统一结果结构。
+
 ## 0.6.2 更新
 
 - 已结束作业改用快速的历史列表过滤查询，不再卡在返回空数据的历史详情接口。
@@ -71,11 +77,14 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 | scnet_run_compute_probe | 在计算节点运行最小能力探针 |
 | scnet_status | 只读查看 backend、SSH profile 和 OpenAPI 配置 |
 | scnet_openapi_regions | 列出授权 OpenAPI 区域，不暴露 token |
+| scnet_account_summary | 查询账户状态和余额 |
+| scnet_resource_summary | 汇总区域队列和资源限制 |
 | scnet_job_queues | 查询区域 Slurm 队列和实时空闲资源 |
 | scnet_job_list | 紧凑列出当前或历史作业 |
 | scnet_limits | 查询用户和调度器资源限制 |
 | scnet_submit_job | 通过 OpenAPI 或 SSH 提交作业；dry_run=true 只预览请求 |
 | scnet_job_show | 查询单个作业的状态、资源与日志路径 |
+| scnet_job_wait | 在限定时间内等待作业进入终态 |
 | scnet_job_logs | 按显式 path，或按 job_id + work_dir 读取作业日志 |
 | scnet_job_cancel | 取消作业；dry_run=true 只预览请求 |
 | scnet_file_list | 通过通用文件 API 列出共享存储 |
@@ -132,7 +141,7 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 才能发布对应版本的 `dsh-scnet` npm 包。
 
 下游同步合并到 `main` 后，先运行本地校验，再手动触发仓库的 `Publish DSH-SCNet` workflow，
-输入 `package.json` 中的精确版本（当前为 `0.6.2`）。workflow 会校验 package 与 Skill
+输入 `package.json` 中的精确版本（当前为 `0.6.3`）。workflow 会校验 package 与 Skill
 版本一致，执行验证、生成 tarball、以稳定版 `latest` 标签发布，并创建对应 Git tag。
 不要只修改 `package.json`；`skills/scnet-hpc/VERSION`、package 版本和两份 README 的版本
 标记必须保持一致。

package/docs/testing.md

@@ -39,11 +39,14 @@ Confirm that the composed configuration includes:
 | `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_account_summary` | Returns account status and balance |
+| `scnet_resource_summary` | Returns queues and resource limits for a region |
 | `scnet_job_queues` | Returns live regional Slurm queues |
 | `scnet_job_list` | Lists active or historical jobs |
 | `scnet_limits` | Returns user and scheduler resource limits |
 | `scnet_submit_job` | Submits a job through OpenAPI or SSH; `dry_run=true` returns the pending request only |
 | `scnet_job_show` | Returns one job's state, resources, and log paths |
+| `scnet_job_wait` | Waits for a job to reach a terminal state with a bounded timeout |
 | `scnet_job_logs` | Reads job logs by explicit path, or by `job_id` + `work_dir` |
 | `scnet_job_cancel` | Cancels one job; `dry_run=true` returns the pending request only |
 | `scnet_file_list` | Lists shared-storage files without modification |

package/docs/testing.zh-CN.md

@@ -60,12 +60,15 @@ DEEPSEEK_API_KEY: sk-你的key
 | 7 | 用 scnet_run_compute_probe 跑计算节点探针 | 返回 PROBE_ 结果 | 高（提交作业并等待） |
 | 8 | 用 scnet_status 查看当前配置 | 返回脱敏配置 | 只读 |
 | 9 | 用 scnet_openapi_regions 查看授权区域 | 返回区域且不含 token | 只读 |
+| 9a | 用 scnet_account_summary 查看账户摘要 | 返回账户状态和余额 | 只读 |
+| 9b | 用 scnet_resource_summary 查看资源摘要 | 返回队列和资源限制 | 只读 |
 | 10 | 用 scnet_job_queues 查看昆山队列 | 返回实时队列和空闲资源 | 只读 |
 | 11 | 用 scnet_job_list 列出当前或历史作业 | 返回紧凑作业记录 | 只读 |
 | 12 | 用 scnet_limits 查询资源限制 | 返回用户和调度器限制 | 只读 |
 | 13 | 用 scnet_submit_job（dry_run=true）预览一次提交 | 返回将要发送的请求，不真正提交 | 只读（dry_run） |
 | 14 | 用 scnet_submit_job 提交一个 5 秒小作业 | 返回 job_id、作业目录与日志路径 | 高（会消耗配额） |
 | 15 | 用 scnet_job_show 查该 job_id | 返回状态与 stdout/stderr 路径 | 只读 |
+| 15a | 用 scnet_job_wait 等待作业终态 | 最多等待限定时间并返回状态 | 只读 |
 | 16 | 用 scnet_job_logs 读该作业日志 | 返回日志内容（同时验证 path 与 job_id+work_dir 两种模式结果一致） | 只读 |
 | 17 | 用 scnet_job_cancel 取消一个作业 | 建议先用 dry_run=true 预览 | 高（变更） |
 | 18 | 用 scnet_file_list 查看默认目录 | 返回共享存储文件 | 只读 |

package/index.mjs

@@ -182,6 +182,16 @@ function errorTextFrom(res) {
   return matched ? matched[1].trim() : raw
 }
 
+function errorCodeFrom(res) {
+  const raw = String(res.stdout || '').trim() || String(res.stderr || '').trim()
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed.error_code === 'string' ? parsed.error_code : ''
+  } catch {
+    return ''
+  }
+}
+
 // 一次只给一条可执行的提示（不展示整套参数清单）
 function translateScnetError(text) {
   const value = String(text || '')
@@ -203,14 +213,23 @@ function translateScnetError(text) {
   return value
 }
 
+function translateScnetFailure(res) {
+  const code = errorCodeFrom(res)
+  if (code === 'AUTHENTICATION_FAILED') return 'SCNet 认证失败：请检查 OpenAPI 配置或重新运行 setup。'
+  if (code === 'QUEUE_QUERY_FAILED') return '队列查询失败，已停止提交；请先检查区域、调度器和凭据。'
+  if (code === 'NO_QUEUE_AVAILABLE') return '当前资源条件下没有可用队列，请调整资源或选择其他区域。'
+  if (code === 'NETWORK_TIMEOUT') return 'SCNet 请求超时：请稍后重试；提交/取消类操作不要盲目重试。'
+  return translateScnetError(errorTextFrom(res))
+}
+
 function scnetJobResult(res, action) {
   if (res.ok) return res.stdout.trim() || '{}'
-  return `${action}失败（exit ${res.code}）：\n${translateScnetError(errorTextFrom(res))}`
+  return `${action}失败（exit ${res.code}）：\n${translateScnetFailure(res)}`
 }
 
 async function runScnetEnvelope(argv) {
   const res = await runScnet(argv)
-  if (!res.ok) return { ok: false, error: translateScnetError(errorTextFrom(res)) }
+  if (!res.ok) return { ok: false, error: translateScnetFailure(res) }
   try {
     const parsed = JSON.parse(res.stdout)
     return { ok: true, envelope: parsed, data: parsed?.data }
@@ -236,22 +255,18 @@ function queueCandidates(queues, wantsAccelerator) {
     .sort((a, b) => Number(b?.free_nodes ?? 0) - Number(a?.free_nodes ?? 0))
 }
 
-// best-effort 队列预检：查得到就校验，查不到不阻塞提交
+// 提交前队列预检：查询失败或空结果都必须阻止提交，不能把失败当成可提交。
 async function precheckQueue(target, args) {
   const check = await runScnetEnvelope([...target.argv, 'queues'])
-  if (!check.ok) return { note: `队列预检已跳过（${check.error}）` }
+  if (!check.ok) return { error: `队列查询失败，已停止提交：${check.error}` }
   const queues = Array.isArray(check.data) ? check.data : []
-  if (queues.length === 0) return { note: '队列预检已跳过（该区域没有返回队列信息）' }
+  if (queues.length === 0) return { error: '队列查询成功但没有可用队列，已停止提交。' }
 
   const queue = String(args.queue ?? '').trim()
   const dcus = Number(String(args.dcus ?? '').trim() || 0)
 
   if (!queue) {
     const candidates = queueCandidates(queues, dcus > 0)
-    if (candidates.length === 1) {
-      const only = candidates[0]
-      return { queue: String(only.partition), note: `已自动选择队列 ${only.partition}` }
-    }
     if (candidates.length > 1) {
       const best = candidates[0]
       return {
@@ -260,7 +275,10 @@ async function precheckQueue(target, args) {
           `按你要的资源建议 ${best.partition}（空闲 ${best.free_nodes} 节点）。`,
       }
     }
-    return {}
+    if (candidates.length === 1) {
+      return { error: `请确认 queue：当前唯一可用队列是 ${candidates[0].partition}（不会自动选择计费队列）。` }
+    }
+    return { error: '没有找到匹配当前资源需求的可用队列。' }
   }
 
   const hit = queues.find((item) => String(item?.partition) === queue)
@@ -348,6 +366,51 @@ export function apply(ctx) {
     }),
   )
 
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_account_summary',
+      description:
+        '只读查询当前 SCNet 账户摘要，包括用户名、账户状态、余额、默认区域和区域信息；不需要额外参数。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        return scnetResult(
+          await runScnet(['--backend', 'openapi', 'account']),
+          '查询账户摘要',
+        )
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_resource_summary',
+      description:
+        '只读汇总目标区域的队列、空闲资源和用户资源限制；region 可省略，后端会使用默认区域。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+        scheduler_id: { type: 'string', description: '调度器 ID；多调度器时填写' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const argv = [
+          '--backend',
+          'openapi',
+          ...regionArgs(args.region),
+          ...(args.scheduler_id ? ['--scheduler-id', String(args.scheduler_id)] : []),
+          'resource-summary',
+        ]
+        return scnetResult(await runScnet(argv), '查询资源摘要')
+      },
+    }),
+  )
+
   ctx.tools.register(
     defineTool({
       name: 'scnet_job_queues',
@@ -602,6 +665,43 @@ export function apply(ctx) {
     }),
   )
 
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_job_wait',
+      description:
+        '只读等待一个作业进入终态。默认最多等待 300 秒、每 10 秒查询一次；不会提交、取消或自动重试作业。',
+      parameters: {
+        job_id: { type: 'string', required: true, description: '作业号' },
+        backend: { type: 'string', description: 'openapi（默认）或 ssh' },
+        region: { type: 'string', description: 'OpenAPI 区域；省略时使用默认区域' },
+        scheduler_id: { type: 'string', description: 'OpenAPI 调度器 ID；多调度器时填写' },
+        cluster: { type: 'string', description: 'SSH 集群短名；多个 profile 时必须指定' },
+        wait_timeout: { type: 'number', description: '最长等待秒数，默认 300，最大 600' },
+        interval: { type: 'number', description: '查询间隔秒数，默认 10，范围 1-60' },
+      },
+      timeoutMs: 660000,
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const jobId = String(args.job_id ?? '').trim()
+        if (!jobId) return MISSING_HINTS.job_id
+        const target = await resolveTarget(args)
+        if (target.error) return target.error
+        const argv = [...target.argv, 'wait', jobId]
+        for (const [flag, key] of [['--wait-timeout', 'wait_timeout'], ['--interval', 'interval']]) {
+          if (args[key] !== undefined) {
+            const checked = positiveInt(args[key], key)
+            if (checked?.error) return checked.error
+            argv.push(flag, checked.value)
+          }
+        }
+        return scnetJobResult(await runScnet(argv, 660000), '等待作业')
+      },
+    }),
+  )
+
   ctx.tools.register(
     defineTool({
       name: 'scnet_job_logs',
@@ -706,7 +806,7 @@ export function apply(ctx) {
         '在本地与 SCNet 区域共享存储之间传输一个文件。direction=upload 或 download；upload 的 remote_dir 是目录而不是文件名。默认不覆盖，执行前应确认区域和路径，dry_run=true 只预览。',
       parameters: {
         direction: { type: 'string', required: true, description: 'upload 或 download' },
-        local_path: { type: 'string', required: true, description: '本地文件路径' },
+        local_path: { type: 'string', description: '本地文件路径；download 省略时使用远端文件名' },
         remote_dir: { type: 'string', description: 'upload 时必填：区域共享存储中的绝对目录；文件名由 local_path 保留' },
         remote_path: { type: 'string', description: 'download：区域共享存储中的绝对文件路径' },
         backend: { type: 'string', description: 'openapi（默认）或 ssh' },
@@ -727,7 +827,7 @@ export function apply(ctx) {
         const localPath = String(args.local_path ?? '').trim()
         const remoteDir = String(args.remote_dir ?? '').trim()
         const remotePath = String(args.remote_path ?? '').trim()
-        if (!localPath) return '缺少必填参数 local_path。'
+        if (direction === 'upload' && !localPath) return '缺少必填参数 local_path。'
         if (direction === 'upload' && !remoteDir) return '缺少必填参数 remote_dir（目录，不是文件名）。'
         if (direction === 'download' && !remotePath) return '缺少必填参数 remote_path。'
         const target = await resolveTarget(args)
@@ -737,7 +837,8 @@ export function apply(ctx) {
         if (direction === 'upload') {
           argv.push('upload', localPath, remoteDir)
         } else {
-          argv.push('download', remotePath, localPath)
+          argv.push('download', remotePath)
+          if (localPath) argv.push(localPath)
         }
         if (args.overwrite === true) argv.push('--cover')
         return scnetResult(
@@ -1067,6 +1168,7 @@ export const __testables = {
   MISSING_HINTS,
   SUBMIT_REQUIRED_ORDER,
   errorTextFrom,
+  errorCodeFrom,
   firstMissingRequired,
   parseWalltimeSeconds,
   pickBackend,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-scnet",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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",

package/skills/scnet-hpc/SKILL.md

@@ -5,8 +5,9 @@ description: Configure or operate SCNet HPC through SSH, OpenAPI, and pluggable
 
 # SCNet HPC
 
-Use the selected backend, cluster profile, and target-cluster evidence. SSH is the default;
-OpenAPI is the structured control plane. Never silently switch backends.
+Use OpenAPI AK/SK as the preferred backend for structured cluster operations. Keep SSH as the
+secondary backend for environment setup, compilation, interactive diagnosis, and operations not
+available through the API. Never silently switch backends.
 
 ## First use and selection
 
@@ -14,7 +15,7 @@ OpenAPI is the structured control plane. Never silently switch backends.
 - 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`.
+  `DEFAULT_BACKEND`, then `openapi`.
 - 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,

package/skills/scnet-hpc/VERSION

@@ -1 +1 @@
-0.6.2
+0.6.4

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

@@ -12,7 +12,7 @@
 # ---- 通用与 SSH 连接 ----
 CLUSTER_ID=""                            # 短名，同时用作 ssh 别名，如 "zzeshell"
 CLUSTER_DESC=""                          # 人类可读描述，如 "海光 DCU（郑州）"
-DEFAULT_BACKEND="ssh"                    # ssh / openapi / 已注册的外部 backend
+DEFAULT_BACKEND="openapi"                # openapi（推荐）/ ssh / 已注册的外部 backend
 SSH_HOST=""                              # 如 "xxx.scnet.cn"
 SSH_PORT="22"
 HOME_BASE="/public/home"                 # 家目录父路径

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

@@ -142,7 +142,7 @@ Triton 是多种推理框架的运行前提；不可用时，对应的 Triton
 
 | 字段 | 谁用 | 留空的后果 |
 |---|---|---|
-| `DEFAULT_BACKEND` | `scnet.py` | 默认使用 `ssh` |
+| `DEFAULT_BACKEND` | `scnet.py` | 默认使用 `openapi` |
 | `OPENAPI_REGION_ID` | OpenAPI backend | 多区域账户需要每次显式传 `--region` |
 | `OPENAPI_SCHEDULER_ID` | OpenAPI backend | 多调度器区域需要每次显式传 `--scheduler-id` |
 | `MIN_GRES` | 文档提示 | 不提示 QOS 强制申请加速器 |

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

@@ -12,7 +12,7 @@ Backend precedence:
 2. `SCNET_HPC_BACKEND`;
 3. saved setup-panel `default_backend`;
 4. selected profile `DEFAULT_BACKEND`;
-5. `ssh`.
+5. `openapi`.
 
 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
@@ -39,7 +39,7 @@ Built-in capability summary:
 | 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,
+Use OpenAPI as the preferred structured control-plane backend. Use SSH for environment setup, compilation,
 interactive inspection, full scheduler tooling, and operations not represented by a structured
 backend.
 
@@ -168,7 +168,7 @@ until the official interface is available and verified.
 Profiles may contain non-secret backend hints:
 
 ```bash
-DEFAULT_BACKEND="ssh"
+DEFAULT_BACKEND="openapi"
 OPENAPI_REGION_ID=""
 OPENAPI_SCHEDULER_ID=""
 OPENAPI_USERNAME=""

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

@@ -128,6 +128,20 @@ python3 scripts/scnet.py --backend openapi --region <id> \
 `job <job-id>` checks the realtime endpoint first and automatically falls back to the filtered
 history-list endpoint. The caller does not need to provide `acctTime`.
 
+Account and resource summaries are read-only:
+
+```bash
+python3 scripts/scnet.py --backend openapi --region <id> account
+python3 scripts/scnet.py --backend openapi --region <id> resource-summary
+```
+
+Wait for a job with a bounded timeout:
+
+```bash
+python3 scripts/scnet.py --backend openapi --region <id> \
+  wait <job-id> --wait-timeout 300 --interval 10
+```
+
 Region tokens are cached under `${XDG_CACHE_HOME:-~/.cache}/scnet-hpc` when that location is
 writable. Cache locking or writes are best-effort; an unavailable cache never blocks an OpenAPI
 operation.

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

@@ -32,7 +32,8 @@ List available access backends:
 python3 scripts/scnet.py backends
 ```
 
-SSH is the default. Use OpenAPI for structured queue, limit, job, log, and file operations:
+OpenAPI with AK/SK is the preferred default for structured queue, limit, job, log, and file
+operations. Use SSH for environment setup and interactive shell work:
 
 ```bash
 python3 scripts/scnet.py --backend openapi clusters

package/skills/scnet-hpc/scripts/scnet.py

@@ -15,6 +15,7 @@ import shlex
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 from typing import Any, Mapping
 
@@ -59,7 +60,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--backend",
         help=(
             "backend name; defaults to SCNET_HPC_BACKEND, saved setup choice, "
-            "profile DEFAULT_BACKEND, then ssh"
+            "profile DEFAULT_BACKEND, then openapi"
         ),
     )
     parser.add_argument("--cluster", help="local cluster profile name")
@@ -120,9 +121,19 @@ def build_parser() -> argparse.ArgumentParser:
     limits = subparsers.add_parser("limits", help="show scheduler or user resource limits")
     limits.add_argument("--partition")
 
+    account = subparsers.add_parser("account", help="show account summary")
+    resource_summary = subparsers.add_parser(
+        "resource-summary", help="show region resources and limits"
+    )
+
     job = subparsers.add_parser("job", help="show one job")
     job.add_argument("job_id")
 
+    wait = subparsers.add_parser("wait", help="wait for one job to reach a terminal state")
+    wait.add_argument("job_id")
+    wait.add_argument("--wait-timeout", type=int, default=300)
+    wait.add_argument("--interval", type=int, default=10)
+
     jobs = subparsers.add_parser("jobs", help="list active or historical jobs")
     jobs.add_argument("--scope", choices=("active", "history"), default="active")
     jobs.add_argument("--limit", type=int, default=20)
@@ -192,7 +203,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     download = subparsers.add_parser("download", help="download one file or folder")
     download.add_argument("remote_path")
-    download.add_argument("local_path")
+    download.add_argument("local_path", nargs="?")
     download.add_argument("--cover", action="store_true")
 
     execute = subparsers.add_parser("exec", help="run an SSH command")
@@ -209,7 +220,7 @@ def choose_backend(
         or os.environ.get("SCNET_HPC_BACKEND")
         or str(user_config.get("default_backend") or "")
         or profile.get("DEFAULT_BACKEND")
-        or "ssh"
+        or "openapi"
     )
 
 
@@ -225,6 +236,68 @@ def compact_output(operation: str, data: Any) -> str:
     return json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True)
 
 
+def _job_terminal(state: Any) -> bool:
+    value = str(state or "").upper()
+    return value in {
+        "COMPLETED",
+        "FAILED",
+        "CANCELLED",
+        "TIMEOUT",
+        "NODE_ERROR",
+        "ABNORMAL",
+        "EXITING",
+        "EXITED",
+        "DONE",
+        "OUT_OF_MEMORY",
+        "NODE_FAIL",
+    }
+
+
+def wait_for_job(backend, options: Mapping[str, Any]) -> dict[str, Any]:
+    timeout = int(options.get("wait_timeout") or 300)
+    interval = int(options.get("interval") or 10)
+    if timeout < 1 or timeout > 600:
+        raise BackendError("wait_timeout must be between 1 and 600 seconds")
+    if interval < 1 or interval > 60:
+        raise BackendError("interval must be between 1 and 60 seconds")
+    started = time.monotonic()
+    while True:
+        latest = backend.execute("job", options)
+        if isinstance(latest, dict) and _job_terminal(latest.get("state")):
+            latest["waited_seconds"] = round(time.monotonic() - started, 1)
+            latest["timed_out"] = False
+            return latest
+        elapsed = time.monotonic() - started
+        if elapsed >= timeout:
+            return {
+                "job": latest,
+                "waited_seconds": round(elapsed, 1),
+                "timed_out": True,
+            }
+        time.sleep(min(interval, timeout - elapsed))
+
+
+def error_code_for(text: str) -> str:
+    value = str(text).lower()
+    if "credentials are not configured" in value or "token" in value and "expired" in value:
+        return "AUTHENTICATION_FAILED"
+    if "region" in value and ("not available" in value or "missing" in value):
+        return "REGION_NOT_FOUND"
+    if "scheduler" in value and ("not available" in value or "multiple" in value):
+        return "SCHEDULER_NOT_FOUND"
+    if "queue" in value and ("not found" in value or "no available" in value):
+        return "QUEUE_QUERY_FAILED"
+    if "job" in value and ("not found" in value or "no job record" in value):
+        return "JOB_NOT_FOUND"
+    if "already exists" in value:
+        return "FILE_TARGET_EXISTS"
+    if "does not exist" in value or "not found" in value and "file" in value:
+        return "FILE_NOT_FOUND"
+    if "timed out" in value or "timeout" in value:
+        return "NETWORK_TIMEOUT"
+    return "BACKEND_ERROR"
+
+
 def _ask(prompt: str, default: str = "") -> str:
     suffix = f" [{default}]" if default else ""
     answer = input(f"{prompt}{suffix}: ").strip()
@@ -870,14 +943,14 @@ def setup_panel(
     print("自动探测区域、调度器和 SSH 元数据；只要求输入必要凭据。\n")
     _print_terminal_help()
 
-    current_default = str(current.get("default_backend") or "ssh")
+    current_default = str(current.get("default_backend") or "openapi")
     if mode == "all":
         backend = _choose(
             "选择默认 backend：",
-            ["SSH（推荐，支持环境和深度诊断）", "OpenAPI（结构化控制面）"],
-            1 if current_default == "ssh" else 2,
+            ["OpenAPI（推荐，结构化控制面）", "SSH（环境配置和深度诊断）"],
+            1 if current_default == "openapi" else 2,
         )
-        default_backend = "ssh" if backend.startswith("SSH") else "openapi"
+        default_backend = "openapi" if backend.startswith("OpenAPI") else "ssh"
         configure_ssh = _ask_yes_no(
             "是否添加或更新一个 SSH 区域？", default=default_backend == "ssh"
         )
@@ -1506,6 +1579,9 @@ def main(argv: list[str] | None = None) -> int:
             openapi_config = user_config.get("openapi", {})
             if isinstance(openapi_config, dict):
                 apply_openapi_defaults(options, openapi_config)
+            if args.operation == "download" and not options.get("local_path"):
+                remote_path = str(options.get("remote_path") or "").rstrip("/")
+                options["local_path"] = remote_path.rsplit("/", 1)[-1] or "download"
             if args.operation == "notebook":
                 if backend_name != "openapi":
                     raise BackendError(
@@ -1532,6 +1608,8 @@ def main(argv: list[str] | None = None) -> int:
                     "name": backend.name,
                     "capabilities": sorted(backend.capabilities),
                 }
+            elif args.operation == "wait":
+                data = wait_for_job(backend, options)
             elif args.operation == "exec":
                 options["command"] = " ".join(args.command).strip()
                 data = backend.execute(args.operation, options)
@@ -1564,6 +1642,7 @@ def main(argv: list[str] | None = None) -> int:
                     {
                         "ok": False,
                         "operation": args.operation,
+                        "error_code": error_code_for(str(exc)),
                         "error": str(exc),
                     },
                     ensure_ascii=False,

package/skills/scnet-hpc/scripts/scnet_backends/openapi.py

@@ -92,6 +92,8 @@ class OpenAPIBackend(Backend):
             "clusters",
             "queues",
             "limits",
+            "account",
+            "resource-summary",
             "job",
             "jobs",
             "logs",
@@ -351,6 +353,37 @@ class OpenAPIBackend(Backend):
         result = {target: data.get(source) for source, target in key_map.items()}
         return {"data": result, "raw": data} if options.get("raw") else result
 
+    def op_account(self, options: Mapping[str, Any]) -> Any:
+        _, token, region = self._center(options)
+        url = self._env(
+            "SCNET_OPENAPI_USER_URL",
+            "https://www.scnet.cn/ac/openapi/v2/user",
+        )
+        data = self._json_request("GET", url, token=token)
+        if not isinstance(data, dict):
+            raise BackendError("user endpoint returned an unexpected data shape")
+        result = {
+            "user": data.get("userName"),
+            "account_name": data.get("accountName"),
+            "account_status": data.get("accountStatus"),
+            "balance": data.get("accountBalance"),
+            "computer_center": data.get("computerCenter"),
+            "region_id": region.get("clusterId"),
+            "region_name": region.get("clusterName"),
+        }
+        return {"data": result, "raw": data} if options.get("raw") else result
+
+    def op_resource_summary(self, options: Mapping[str, Any]) -> Any:
+        _, _, region = self._center(options)
+        queues = self.op_queues(options)
+        limits = self.op_limits(options)
+        return {
+            "region_id": region.get("clusterId"),
+            "region_name": region.get("clusterName"),
+            "queues": queues,
+            "limits": limits,
+        }
+
     def op_job(self, options: Mapping[str, Any]) -> Any:
         job_id = str(require_option(options, "job_id"))
         hpc_url, token, scheduler_id, _, _ = self._hpc_context(options)

package/skills/scnet-hpc/scripts/scnet_backends/profile.py

@@ -58,7 +58,7 @@ def list_profiles(repo_root: Path) -> list[dict[str, str]]:
                 "name": path.stem,
                 "cluster_id": profile.get("CLUSTER_ID", path.stem),
                 "description": profile.get("CLUSTER_DESC", ""),
-                "default_backend": profile.get("DEFAULT_BACKEND", "ssh"),
+                "default_backend": profile.get("DEFAULT_BACKEND", "openapi"),
             }
         )
     return result

package/skills/scnet-hpc/scripts/setup.sh

@@ -345,7 +345,7 @@ case "$(uname -s)" in
             && grep -Eq '^ID=(ubuntu|debian)$' /etc/os-release; then
             printf '%s\n' \
                 "Ubuntu/Debian：在 Terminal 中使用 ↑/↓ 和 Enter，也可输入编号；Ctrl+C 可取消。" \
-                "如需安全保存 AK/SK：sudo apt install libsecret-tools" >&2
+                "本机安全保存 AK/SK 可安装 libsecret-tools（sudo apt install libsecret-tools）；使用环境变量时无需安装。" >&2
         else
             printf '%s\n' "Linux：使用 ↑/↓ 和 Enter，也可输入编号；Ctrl+C 可取消。" >&2
         fi
@@ -382,12 +382,12 @@ fi
 
 if [ -z "$BACKEND" ]; then
     BACKEND=$(choose "选择要管理的 backend：" \
+        "openapi（推荐：平台级 AK/SK 和多区域）" \
         "ssh（区域级用户名和私钥）" \
-        "openapi（平台级 AK/SK 和多区域）" \
         "both（同时管理）")
     case "$BACKEND" in
-        ssh*) BACKEND=ssh ;;
         openapi*) BACKEND=openapi ;;
+        ssh*) BACKEND=ssh ;;
         both*) BACKEND=both ;;
     esac
 fi
@@ -429,7 +429,7 @@ fi
 
 DEFAULT_BACKEND="$BACKEND"
 if [ "$BACKEND" = both ]; then
-    DEFAULT_BACKEND=$(choose "选择默认 backend：" "ssh" "openapi")
+    DEFAULT_BACKEND=$(choose "选择默认 backend：" "openapi" "ssh")
 fi
 
 if [ "$BACKEND" = ssh ] || [ "$BACKEND" = both ]; then