dsh-scnet 0.6.1 → 0.6.3

package/README.md

@@ -4,11 +4,25 @@
 
 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.1**
+Current release: **0.6.3**
 
 > 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.1
+## 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.
+- Historical field aliases such as `workdir` are normalized for log-path discovery.
+- OpenAPI operations continue without persistent caching when the cache directory is read-only.
+
+## 0.6.1 highlights
 
 - Job details now fall back to the history endpoint when realtime records expire, with complete
   normalized terminal states.
@@ -60,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 |
@@ -113,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.1`). 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,22 @@
 
 <p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
 
-当前版本：**0.6.1**
+当前版本：**0.6.3**
 
 > 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。
 
+## 0.6.3 更新
+
+- 新增只读账户摘要、资源摘要和有界等待作业工具 `scnet_job_wait`。
+- 提交前队列预检失败会停止提交，不再静默选择队列。
+- 下载时可省略本地路径自动使用远端文件名；普通上传和分片上传返回统一结果结构。
+
+## 0.6.2 更新
+
+- 已结束作业改用快速的历史列表过滤查询，不再卡在返回空数据的历史详情接口。
+- 兼容历史记录中的 `workdir` 等字段变体，可继续推导日志路径。
+- 缓存目录只读时自动降级为无持久缓存，OpenAPI 主功能不再被缓存故障阻断。
+
 ## 0.6.1 更新
 
 - 作业实时记录过期时自动回退历史接口，并补全终态映射。
@@ -65,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 列出共享存储 |
@@ -126,7 +141,7 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 才能发布对应版本的 `dsh-scnet` npm 包。
 
 下游同步合并到 `main` 后，先运行本地校验，再手动触发仓库的 `Publish DSH-SCNet` workflow，
-输入 `package.json` 中的精确版本（当前为 `0.6.1`）。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,23 +60,26 @@ 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 查看昆山队列 | 返回实时队列和空闲资源 | 只读 |
-| 10a | 用 scnet_job_list 列出当前或历史作业 | 返回紧凑作业记录 | 只读 |
-| 10b | 用 scnet_limits 查询资源限制 | 返回用户和调度器限制 | 只读 |
-| 10a | 用 scnet_submit_job（dry_run=true）预览一次提交 | 返回将要发送的请求，不真正提交 | 只读（dry_run） |
-| 10b | 用 scnet_submit_job 提交一个 5 秒小作业 | 返回 job_id、作业目录与日志路径 | 高（会消耗配额） |
-| 10c | 用 scnet_job_show 查该 job_id | 返回状态与 stdout/stderr 路径 | 只读 |
-| 10d | 用 scnet_job_logs 读该作业日志 | 返回日志内容（同时验证 path 与 job_id+work_dir 两种模式结果一致） | 只读 |
-| 10e | 用 scnet_job_cancel 取消一个作业 | 建议先用 dry_run=true 预览 | 高（变更） |
-| 11 | 用 scnet_file_list 查看默认目录 | 返回共享存储文件 | 只读 |
-| 11a | 用 scnet_file_transfer 传输一个文件 | 默认不覆盖目标 | 有副作用 |
-| 12 | 用 scnet_notebook_regions 查看区域 | 返回 Notebook 可用区域 | 只读 |
-| 13 | 用 scnet_notebook_resources 查看昆山资源 | 返回 CPU/GPU/DCU 资源 | 只读 |
-| 14 | 用 scnet_notebook_list 查看实例 | 返回脱敏实例列表 | 只读 |
+| 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 查看默认目录 | 返回共享存储文件 | 只读 |
+| 19 | 用 scnet_file_transfer 传输一个文件 | 默认不覆盖目标 | 有副作用 |
+| 20 | 用 scnet_notebook_regions 查看区域 | 返回 Notebook 可用区域 | 只读 |
+| 21 | 用 scnet_notebook_resources 查看昆山资源 | 返回 CPU/GPU/DCU 资源 | 只读 |
+| 22 | 用 scnet_notebook_list 查看实例 | 返回脱敏实例列表 | 只读 |
 
 第 4 至 7 步只有在你有私钥和目标集群时才测，测前确认副作用。
 
-第 10b、10e 步是变更操作，会真实占用或释放调度器资源：先用 `dry_run=true` 预览，确认返回里的
+第 14、17 步是变更操作，会真实占用或释放调度器资源：先用 `dry_run=true` 预览，确认返回里的
 目标区域/集群，并且**不要在提交超时后盲目重试**（平台没有幂等键），先查作业状态。
 
 Notebook 创建、启动、停止和释放没有作为 DSH deterministic tool 暴露。此类操作通过

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 || '')
@@ -197,17 +207,29 @@ function translateScnetError(text) {
       '若只想看日志，请直接给日志文件的 path；若刚提交不久，可稍后重试。'
     )
   }
+  if (/realtime and history endpoints returned no job record/i.test(value)) {
+    return '平台的实时和最近 30 天历史记录中都没有找到这个作业，请核对 job_id 和区域。'
+  }
   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 }
@@ -233,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 {
@@ -257,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)
@@ -345,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',
@@ -577,7 +643,7 @@ export function apply(ctx) {
     defineTool({
       name: 'scnet_job_show',
       description:
-        '只读查询一个作业的状态与资源（state / exit_code / work_dir / stdout / stderr）。作业完成较久后平台可能不再返回记录，此时用 scnet_job_logs 的 path 模式读日志即可。',
+        '只读查询一个作业的状态与资源（state / exit_code / work_dir / stdout / stderr）。自动先查实时记录，再回退最近 30 天历史记录；用户只需提供 job_id。',
       parameters: {
         job_id: { type: 'string', required: true, description: '作业号' },
         backend: { type: 'string', description: 'openapi（默认）或 ssh' },
@@ -599,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',
@@ -703,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' },
@@ -724,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)
@@ -734,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(
@@ -1064,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.1",
+  "version": "0.6.3",
   "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/VERSION

@@ -1 +1 @@
-0.6.1
+0.6.3

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

@@ -125,6 +125,27 @@ python3 scripts/scnet.py --backend openapi --region <id> \
   jobs --scope history --days 30 --limit 20
 ```
 
+`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.
+
 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.

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
 
@@ -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")
@@ -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()
@@ -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

@@ -38,6 +38,7 @@ STATUS_MAP = {
     "statRQ": "REQUEUED",
 }
 WALLTIME_RE = re.compile(r"^(?:[0-9]+-)?[0-9]{1,3}:[0-9]{2}:[0-9]{2}$")
+SCNET_TIMEZONE = timezone(timedelta(hours=8))
 
 
 def _bounded_int(options: Mapping[str, Any], name: str, minimum: int) -> int:
@@ -62,19 +63,23 @@ def normalize_job(item: Mapping[str, Any]) -> dict[str, Any]:
         "name": item.get("jobName") or item.get("name"),
         "state": STATUS_MAP.get(str(raw_state), raw_state),
         "raw_state": raw_state,
-        "queue": item.get("queue"),
-        "user": item.get("user"),
-        "nodes": item.get("nodeNumReq") or item.get("nodeUsed"),
-        "cpus": item.get("procNumReq") or item.get("procNumUsed"),
+        "queue": item.get("queue") or item.get("queueName"),
+        "user": item.get("user") or item.get("userName"),
+        "nodes": item.get("nodeNumReq") or item.get("nodeUsed") or item.get("nodeNum"),
+        "cpus": item.get("procNumReq") or item.get("procNumUsed") or item.get("nproc"),
         "gpus": item.get("gpuNumReq") or item.get("gpuNumUsed"),
         "dcus": item.get("dcuNumReq") or item.get("dcuNumUsed"),
-        "elapsed": item.get("jobRunTime"),
-        "submitted_at": item.get("jobSubmitTime"),
+        "elapsed": item.get("jobRunTime") or item.get("jobWalltimeUsed"),
+        "submitted_at": (
+            item.get("jobSubmitTime")
+            or item.get("jobQueueTime")
+            or item.get("queueTime")
+        ),
         "started_at": item.get("jobStartTime"),
-        "ended_at": item.get("jobEndTime"),
+        "ended_at": item.get("jobEndTime") or item.get("acctTime"),
         "exit_code": item.get("exitCode"),
         "reason": item.get("reason"),
-        "work_dir": item.get("workDir"),
+        "work_dir": item.get("workDir") or item.get("workdir"),
         "stdout": item.get("outputPath"),
         "stderr": item.get("errorPath"),
     }
@@ -87,6 +92,8 @@ class OpenAPIBackend(Backend):
             "clusters",
             "queues",
             "limits",
+            "account",
+            "resource-summary",
             "job",
             "jobs",
             "logs",
@@ -346,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)
@@ -371,16 +409,23 @@ class OpenAPIBackend(Backend):
                     result["raw"] = candidate
                 return result
 
-        history = self._history_job(
+        history_items, _, history_raw = self._history_jobs(
             hpc_url,
             token,
             scheduler_id,
-            job_id,
-            options,
+            job_id=job_id,
+            days=30,
+            limit=1,
         )
-        if not isinstance(history, dict) or not (
-            history.get("jobId") or history.get("job_id")
-        ):
+        history = next(
+            (
+                item
+                for item in history_items
+                if str(item.get("jobId") or item.get("job_id") or "") == job_id
+            ),
+            None,
+        )
+        if history is None:
             detail = "realtime and history endpoints returned no job record"
             if realtime_error:
                 detail += f" ({realtime_error})"
@@ -388,7 +433,10 @@ class OpenAPIBackend(Backend):
         result = normalize_job(history)
         result["source"] = "history"
         if options.get("raw"):
-            result["raw"] = history
+            result["raw"] = {
+                "item": history,
+                "response": history_raw,
+            }
         return result
 
     @staticmethod
@@ -405,25 +453,53 @@ class OpenAPIBackend(Backend):
             )
         )
 
-    def _history_job(
+    @staticmethod
+    def _job_items(data: Any) -> tuple[list[dict[str, Any]], int | None]:
+        if isinstance(data, dict):
+            items = data.get("items") or data.get("list") or data.get("rows") or []
+            total = data.get("total")
+        else:
+            items = data or []
+            total = None
+        if not isinstance(items, list):
+            raise BackendError("job list endpoint returned an unexpected data shape")
+        normalized_items = [item for item in items if isinstance(item, dict)]
+        return normalized_items, total
+
+    def _history_jobs(
         self,
         hpc_url: str,
         token: str,
         scheduler_id: str,
-        job_id: str,
-        options: Mapping[str, Any],
-    ) -> Any:
+        *,
+        job_id: str | None = None,
+        days: int = 30,
+        limit: int = 20,
+    ) -> tuple[list[dict[str, Any]], int | None, Any]:
         if not scheduler_id:
             raise BackendError("history lookup requires a scheduler id")
-        path = f"/openapi/v2/historyjobs/{quote(scheduler_id)}/{quote(job_id)}"
-        acct_time = str(options.get("acct_time") or "").strip()
-        if acct_time:
-            path += "?" + urlencode({"acctTime": acct_time})
-        return self._json_request(
+        end = datetime.now(SCNET_TIMEZONE)
+        start = end - timedelta(days=days)
+        params = {
+            "strClusterNameList": scheduler_id,
+            "timeType": "CUSTOM",
+            "isQueryByQueueTime": "false",
+            "start": 0,
+            "limit": limit,
+            "startTime": start.strftime("%Y-%m-%d %H:%M:%S"),
+            "endTime": end.strftime("%Y-%m-%d %H:%M:%S"),
+        }
+        if job_id:
+            params["jobId"] = job_id
+        data = self._json_request(
             "GET",
-            service_endpoint(hpc_url, "hpc", path),
+            service_endpoint(hpc_url, "hpc", "/openapi/v2/historyjobs")
+            + "?"
+            + urlencode(params),
             token=token,
         )
+        items, total = self._job_items(data)
+        return items, total, data
 
     def op_jobs(self, options: Mapping[str, Any]) -> Any:
         hpc_url, token, scheduler_id, _, _ = self._hpc_context(options)
@@ -440,35 +516,23 @@ class OpenAPIBackend(Backend):
                 "start": 0,
                 "limit": limit,
             }
+            data = self._json_request(
+                "GET",
+                service_endpoint(hpc_url, "hpc", path) + "?" + urlencode(params),
+                token=token,
+            )
+            items, total = self._job_items(data)
         else:
             days = _bounded_int(options, "days", 1)
             if days > 90:
                 raise BackendError("days must be <= 90")
-            end = datetime.now(timezone.utc)
-            start = end - timedelta(days=days)
-            path = "/openapi/v2/historyjobs"
-            params = {
-                "strClusterNameList": scheduler_id,
-                "timeType": "CUSTOM",
-                "isQueryByQueueTime": "false",
-                "start": 0,
-                "limit": limit,
-                "startTime": start.strftime("%Y-%m-%d %H:%M:%S"),
-                "endTime": end.strftime("%Y-%m-%d %H:%M:%S"),
-            }
-        data = self._json_request(
-            "GET",
-            service_endpoint(hpc_url, "hpc", path) + "?" + urlencode(params),
-            token=token,
-        )
-        if isinstance(data, dict):
-            items = data.get("items") or data.get("list") or data.get("rows") or []
-            total = data.get("total")
-        else:
-            items = data or []
-            total = None
-        if not isinstance(items, list):
-            raise BackendError("job list endpoint returned an unexpected data shape")
+            items, total, data = self._history_jobs(
+                hpc_url,
+                token,
+                scheduler_id,
+                days=days,
+                limit=limit,
+            )
         result = [normalize_job(item) for item in items if isinstance(item, dict)]
         payload = {
             "scope": scope,

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

@@ -86,28 +86,39 @@ class SCNetClient:
     @classmethod
     def _write_token_cache(
         cls, fingerprint: str, regions: list[dict[str, Any]]
-    ) -> None:
+    ) -> bool:
         path, _ = cls._token_cache_paths()
-        path.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
         temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
-        temporary.write_text(
-            json.dumps(
-                {
-                    "created_at": time.time(),
-                    "fingerprint": fingerprint,
-                    "regions": regions,
-                },
-                ensure_ascii=False,
-            ),
-            encoding="utf-8",
-        )
-        os.chmod(temporary, 0o600)
-        os.replace(temporary, path)
+        try:
+            path.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+            temporary.write_text(
+                json.dumps(
+                    {
+                        "created_at": time.time(),
+                        "fingerprint": fingerprint,
+                        "regions": regions,
+                    },
+                    ensure_ascii=False,
+                ),
+                encoding="utf-8",
+            )
+            os.chmod(temporary, 0o600)
+            os.replace(temporary, path)
+            return True
+        except OSError:
+            try:
+                temporary.unlink()
+            except OSError:
+                pass
+            return False
 
     @classmethod
     def _acquire_token_cache_lock(cls) -> Path | None:
         _, lock = cls._token_cache_paths()
-        lock.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+        try:
+            lock.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+        except OSError:
+            return None
         for _ in range(50):
             try:
                 fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
@@ -121,6 +132,8 @@ class SCNetClient:
                 except OSError:
                     pass
                 time.sleep(0.2)
+            except OSError:
+                return None
         return None
 
     @staticmethod
@@ -128,7 +141,7 @@ class SCNetClient:
         if lock is not None:
             try:
                 lock.unlink()
-            except FileNotFoundError:
+            except OSError:
                 pass
 
     def request(
@@ -257,7 +270,8 @@ class SCNetClient:
             self._regions_cache = [
                 item for item in data if isinstance(item, dict)
             ]
-            self._write_token_cache(fingerprint, self._regions_cache)
+            if lock is not None:
+                self._write_token_cache(fingerprint, self._regions_cache)
             return self._regions_cache
         finally:
             self._release_token_cache_lock(lock)