dsh-scnet 0.6.0 → 0.6.1

package/README.md

@@ -4,11 +4,19 @@
 
 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.0**
+Current release: **0.6.1**
 
 > 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.0
+## What's new in 0.6.1
+
+- Job details now fall back to the history endpoint when realtime records expire, with complete
+  normalized terminal states.
+- Added compact `scnet_job_list`, `scnet_limits`, and `scnet_file_transfer` tools.
+- File uploads now make the remote-directory contract explicit: the local filename is preserved
+  and must not be passed as the remote directory.
+
+## 0.6.0 highlights
 
 - Added first-class DSH tools for submitting jobs, inspecting job status, reading logs, and
   cancelling jobs through the existing SSH/OpenAPI backends.
@@ -53,11 +61,14 @@ See [Installation](./docs/installation.md) for npm, GitHub, and local-checkout w
 | `scnet_status` | Read the saved backend, SSH profile, and OpenAPI configuration |
 | `scnet_openapi_regions` | List authorized OpenAPI regions without exposing tokens |
 | `scnet_job_queues` | Query regional Slurm queues and live resource availability |
+| `scnet_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_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 |
+| `scnet_file_transfer` | Upload or download one file without overwriting by default |
 | `scnet_notebook_regions` | List Notebook-capable regions |
 | `scnet_notebook_resources` | Query Notebook CPU/GPU/DCU resources |
 | `scnet_notebook_list` | List Notebook instances with sensitive fields redacted |
@@ -102,12 +113,18 @@ 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.0`). The
+`Publish DSH-SCNet` workflow with the exact value from `package.json` (currently `0.6.1`). 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
 must stay aligned.
 
+The workflow uses npm Trusted Publishing through GitHub OIDC, so account 2FA/Passkey should remain
+enabled and no long-lived `NPM_TOKEN` is required. Configure `lql341/dsh-scnet` and
+`.github/workflows/publish.yml` as a trusted publisher in the npm package settings before the
+first OIDC release. A granular read/write token with 2FA bypass is a fallback only when Trusted
+Publishing cannot be enabled.
+
 ## Validation
 
 ```sh

package/README_CN.md

@@ -4,10 +4,16 @@
 
 <p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
 
-当前版本：**0.6.0**
+当前版本：**0.6.1**
 
 > 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。
 
+## 0.6.1 更新
+
+- 作业实时记录过期时自动回退历史接口，并补全终态映射。
+- 新增紧凑的 `scnet_job_list`、`scnet_limits`、`scnet_file_transfer` 工具。
+- 明确 OpenAPI 上传参数是远端目录，文件名沿用本地文件名，不能把文件名当作远端目录传入。
+
 ## 0.6.0 更新
 
 - 新增作业提交、状态查询、日志读取和取消作业的 DSH 工具，复用现有 SSH/OpenAPI backend。
@@ -60,11 +66,14 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 | scnet_status | 只读查看 backend、SSH profile 和 OpenAPI 配置 |
 | scnet_openapi_regions | 列出授权 OpenAPI 区域，不暴露 token |
 | scnet_job_queues | 查询区域 Slurm 队列和实时空闲资源 |
+| scnet_job_list | 紧凑列出当前或历史作业 |
+| scnet_limits | 查询用户和调度器资源限制 |
 | scnet_submit_job | 通过 OpenAPI 或 SSH 提交作业；dry_run=true 只预览请求 |
 | scnet_job_show | 查询单个作业的状态、资源与日志路径 |
 | scnet_job_logs | 按显式 path，或按 job_id + work_dir 读取作业日志 |
 | scnet_job_cancel | 取消作业；dry_run=true 只预览请求 |
 | scnet_file_list | 通过通用文件 API 列出共享存储 |
+| scnet_file_transfer | 上传或下载单个文件，默认不覆盖 |
 | scnet_notebook_regions | 列出支持 Notebook 的区域 |
 | scnet_notebook_resources | 查询 Notebook CPU/GPU/DCU 资源 |
 | scnet_notebook_list | 列出 Notebook 实例并脱敏敏感字段 |
@@ -117,11 +126,16 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 才能发布对应版本的 `dsh-scnet` npm 包。
 
 下游同步合并到 `main` 后，先运行本地校验，再手动触发仓库的 `Publish DSH-SCNet` workflow，
-输入 `package.json` 中的精确版本（当前为 `0.6.0`）。workflow 会校验 package 与 Skill
+输入 `package.json` 中的精确版本（当前为 `0.6.1`）。workflow 会校验 package 与 Skill
 版本一致，执行验证、生成 tarball、以稳定版 `latest` 标签发布，并创建对应 Git tag。
 不要只修改 `package.json`；`skills/scnet-hpc/VERSION`、package 版本和两份 README 的版本
 标记必须保持一致。
 
+该 workflow 使用 GitHub OIDC 的 npm Trusted Publishing，因此应保留账号的 2FA/Passkey，
+不需要长期保存 `NPM_TOKEN`。首次使用 OIDC 发布前，请在 npm package 设置中把
+`lql341/dsh-scnet` 与 `.github/workflows/publish.yml` 配置为 trusted publisher。只有无法
+启用 Trusted Publishing 时，才考虑使用具备 2FA bypass 的 granular read/write token。
+
 ## 隐私与安全
 
 - 仓库不含私钥、token、用户名、密钥指纹。

package/docs/testing.md

@@ -40,11 +40,14 @@ Confirm that the composed configuration includes:
 | `scnet_status` | Returns redacted local SCNet configuration |
 | `scnet_openapi_regions` | Returns authorized regions without tokens |
 | `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_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 |
+| `scnet_file_transfer` | Uploads or downloads one file; defaults to no overwrite |
 | `scnet_notebook_regions` | Lists Notebook-capable regions |
 | `scnet_notebook_resources` | Returns Notebook resource groups |
 | `scnet_notebook_list` | Lists redacted Notebook instances |

package/docs/testing.zh-CN.md

@@ -61,12 +61,15 @@ DEEPSEEK_API_KEY: sk-你的key
 | 8 | 用 scnet_status 查看当前配置 | 返回脱敏配置 | 只读 |
 | 9 | 用 scnet_openapi_regions 查看授权区域 | 返回区域且不含 token | 只读 |
 | 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 查看实例 | 返回脱敏实例列表 | 只读 |

package/index.mjs

@@ -365,6 +365,68 @@ export function apply(ctx) {
     }),
   )
 
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_job_list',
+      description:
+        '只读列出 SCNet 作业。默认列出当前区域正在排队或运行的作业；scope=history 时查询最近历史作业。区域、数量和历史天数都可省略，输出保持紧凑。',
+      parameters: {
+        scope: { type: 'string', description: 'active（默认）或 history' },
+        region: { type: 'string', description: '区域名称或 ID；省略时使用已保存的默认区域' },
+        limit: { type: 'number', description: '最多返回条数，默认 20，最大 100' },
+        days: { type: 'number', description: 'history 模式查询最近天数，默认 30，最大 90' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const scope = String(args.scope ?? 'active').trim().toLowerCase()
+        if (scope !== 'active' && scope !== 'history') {
+          return 'scope 只支持 active 或 history。'
+        }
+        const argv = ['--backend', 'openapi', ...regionArgs(args.region), 'jobs', '--scope', scope]
+        if (args.limit !== undefined) {
+          const checked = positiveInt(args.limit, 'limit')
+          if (checked?.error) return checked.error
+          argv.push('--limit', checked.value)
+        }
+        if (args.days !== undefined) {
+          const checked = positiveInt(args.days, 'days')
+          if (checked?.error) return checked.error
+          argv.push('--days', checked.value)
+        }
+        return scnetResult(await runScnet(argv), '查询作业列表')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_limits',
+      description:
+        '只读查询当前区域和调度器的用户资源限制。region、scheduler_id 都可省略，后端会自动解析唯一目标。',
+      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)] : []),
+          'limits',
+        ]
+        return scnetResult(await runScnet(argv), '查询资源限制')
+      },
+    }),
+  )
+
   ctx.tools.register(
     defineTool({
       name: 'scnet_submit_job',
@@ -634,6 +696,55 @@ export function apply(ctx) {
     }),
   )
 
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_file_transfer',
+      description:
+        '在本地与 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: '本地文件路径' },
+        remote_dir: { type: 'string', description: 'upload 时必填：区域共享存储中的绝对目录；文件名由 local_path 保留' },
+        remote_path: { type: 'string', description: 'download：区域共享存储中的绝对文件路径' },
+        backend: { type: 'string', description: 'openapi（默认）或 ssh' },
+        region: { type: 'string', description: 'OpenAPI 区域；省略时使用默认区域' },
+        cluster: { type: 'string', description: 'SSH 集群短名；多个 profile 时必须指定' },
+        overwrite: { type: 'boolean', description: '是否覆盖已有目标，默认否' },
+        dry_run: { type: 'boolean', description: '只预览，不传输（默认否）' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const direction = String(args.direction ?? '').trim().toLowerCase()
+        if (direction !== 'upload' && direction !== 'download') {
+          return 'direction 只支持 upload 或 download。'
+        }
+        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' && !remoteDir) return '缺少必填参数 remote_dir（目录，不是文件名）。'
+        if (direction === 'download' && !remotePath) return '缺少必填参数 remote_path。'
+        const target = await resolveTarget(args)
+        if (target.error) return target.error
+        const argv = [...target.argv]
+        if (args.dry_run === true) argv.push('--dry-run')
+        if (direction === 'upload') {
+          argv.push('upload', localPath, remoteDir)
+        } else {
+          argv.push('download', remotePath, localPath)
+        }
+        if (args.overwrite === true) argv.push('--cover')
+        return scnetResult(
+          await runScnet(argv, 180000),
+          direction === 'upload' ? '上传文件' : '下载文件',
+        )
+      },
+    }),
+  )
+
   ctx.tools.register(
     defineTool({
       name: 'scnet_file_list',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-scnet",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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.0
+0.6.1

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

@@ -110,6 +110,21 @@ python3 scripts/scnet.py --backend openapi --region <id> \
 Downloads refuse to replace an existing local path unless `--cover` is supplied. Uploads send
 `uncover` by default and require `--cover` for replacement.
 
+For uploads, the second argument is always a remote **directory**, not a complete filename.
+The uploaded filename comes from the local file. For example, uploading `mesh.bin` to
+`/public/home/alice/mesh` creates `/public/home/alice/mesh/mesh.bin`; passing
+`/public/home/alice/mesh.bin` as the second argument asks the API to use `mesh.bin` as a
+directory name.
+
+List active or historical jobs without supplying a job ID:
+
+```bash
+python3 scripts/scnet.py --backend openapi --region <id> \
+  jobs --scope active --limit 20
+python3 scripts/scnet.py --backend openapi --region <id> \
+  jobs --scope history --days 30 --limit 20
+```
+
 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

@@ -123,6 +123,11 @@ def build_parser() -> argparse.ArgumentParser:
     job = subparsers.add_parser("job", help="show one job")
     job.add_argument("job_id")
 
+    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)
+    jobs.add_argument("--days", type=int, default=30)
+
     logs = subparsers.add_parser("logs", help="read a log file")
     logs.add_argument("--path", required=True)
     logs.add_argument("--lines", type=int, default=200)
@@ -166,9 +171,9 @@ def build_parser() -> argparse.ArgumentParser:
         default="name",
     )
 
-    upload = subparsers.add_parser("upload", help="upload one file")
+    upload = subparsers.add_parser("upload", help="upload one file into a remote directory")
     upload.add_argument("local_path")
-    upload.add_argument("remote_path")
+    upload.add_argument("remote_dir", help="remote destination directory, not a filename")
     upload.add_argument("--cover", action="store_true")
     upload.add_argument(
         "--chunk-size",

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

@@ -6,6 +6,7 @@ import json
 import mimetypes
 import re
 import uuid
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Mapping
 from urllib.error import HTTPError, URLError
@@ -29,6 +30,12 @@ STATUS_MAP = {
     "statC": "COMPLETED",
     "statW": "WAITING",
     "statX": "OTHER",
+    "statDE": "CANCELLED",
+    "statD": "FAILED",
+    "statEX": "ABNORMAL",
+    "statT": "TIMEOUT",
+    "statN": "NODE_ERROR",
+    "statRQ": "REQUEUED",
 }
 WALLTIME_RE = re.compile(r"^(?:[0-9]+-)?[0-9]{1,3}:[0-9]{2}:[0-9]{2}$")
 
@@ -44,7 +51,12 @@ def _bounded_int(options: Mapping[str, Any], name: str, minimum: int) -> int:
 
 
 def normalize_job(item: Mapping[str, Any]) -> dict[str, Any]:
-    raw_state = item.get("jobStatus") or item.get("state") or ""
+    raw_state = (
+        item.get("jobStatus")
+        or item.get("jobState")
+        or item.get("state")
+        or ""
+    )
     return {
         "job_id": str(item.get("jobId") or item.get("job_id") or ""),
         "name": item.get("jobName") or item.get("name"),
@@ -76,6 +88,7 @@ class OpenAPIBackend(Backend):
             "queues",
             "limits",
             "job",
+            "jobs",
             "logs",
             "submit",
             "cancel",
@@ -335,18 +348,134 @@ class OpenAPIBackend(Backend):
 
     def op_job(self, options: Mapping[str, Any]) -> Any:
         job_id = str(require_option(options, "job_id"))
-        hpc_url, token, _, _, _ = self._hpc_context(options)
+        hpc_url, token, scheduler_id, _, _ = self._hpc_context(options)
+        realtime_error: str | None = None
+        data: Any = None
+        try:
+            data = self._json_request(
+                "GET",
+                service_endpoint(hpc_url, "hpc", f"/openapi/v2/jobs/{quote(job_id)}"),
+                token=token,
+            )
+        except BackendError as exc:
+            if not self._is_missing_job_error(str(exc)):
+                raise
+            realtime_error = str(exc)
+
+        if isinstance(data, dict):
+            candidate = data
+            if candidate.get("jobId") or candidate.get("job_id"):
+                result = normalize_job(candidate)
+                result["source"] = "realtime"
+                if options.get("raw"):
+                    result["raw"] = candidate
+                return result
+
+        history = self._history_job(
+            hpc_url,
+            token,
+            scheduler_id,
+            job_id,
+            options,
+        )
+        if not isinstance(history, dict) or not (
+            history.get("jobId") or history.get("job_id")
+        ):
+            detail = "realtime and history endpoints returned no job record"
+            if realtime_error:
+                detail += f" ({realtime_error})"
+            raise BackendError(detail)
+        result = normalize_job(history)
+        result["source"] = "history"
+        if options.get("raw"):
+            result["raw"] = history
+        return result
+
+    @staticmethod
+    def _is_missing_job_error(text: str) -> bool:
+        value = text.lower()
+        return any(
+            marker in value
+            for marker in (
+                "unexpected data shape",
+                "http 404",
+                "not found",
+                "does not exist",
+                "不存在",
+            )
+        )
+
+    def _history_job(
+        self,
+        hpc_url: str,
+        token: str,
+        scheduler_id: str,
+        job_id: str,
+        options: Mapping[str, Any],
+    ) -> 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(
+            "GET",
+            service_endpoint(hpc_url, "hpc", path),
+            token=token,
+        )
+
+    def op_jobs(self, options: Mapping[str, Any]) -> Any:
+        hpc_url, token, scheduler_id, _, _ = self._hpc_context(options)
+        scope = str(options.get("scope") or "active").strip().lower()
+        if scope not in {"active", "history"}:
+            raise BackendError("scope must be active or history")
+        limit = _bounded_int(options, "limit", 1)
+        if limit > 100:
+            raise BackendError("limit must be <= 100")
+        if scope == "active":
+            path = "/openapi/v2/jobs"
+            params = {
+                "strClusterIDList": scheduler_id,
+                "start": 0,
+                "limit": limit,
+            }
+        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", f"/openapi/v2/jobs/{quote(job_id)}"),
+            service_endpoint(hpc_url, "hpc", path) + "?" + urlencode(params),
             token=token,
         )
-        if not isinstance(data, dict):
-            raise BackendError("job endpoint returned an unexpected data shape")
-        result = normalize_job(data)
-        if options.get("raw"):
-            result["raw"] = data
-        return result
+        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")
+        result = [normalize_job(item) for item in items if isinstance(item, dict)]
+        payload = {
+            "scope": scope,
+            "items": result,
+            "total": total if total is not None else len(result),
+        }
+        return {"data": payload, "raw": data} if options.get("raw") else payload
 
     def op_logs(self, options: Mapping[str, Any]) -> Any:
         path = str(require_option(options, "path"))
@@ -580,14 +709,17 @@ class OpenAPIBackend(Backend):
 
     def op_upload(self, options: Mapping[str, Any]) -> Any:
         local_path = Path(str(require_option(options, "local_path"))).expanduser()
-        remote_path = str(require_option(options, "remote_path"))
+        remote_dir = str(
+            options.get("remote_dir")
+            or require_option(options, "remote_path")
+        )
         if not local_path.is_file():
             raise BackendError(f"local file does not exist: {local_path}")
         if (
-            not remote_path.startswith("/")
-            or "\n" in remote_path
-            or "\r" in remote_path
-            or "\x00" in remote_path
+            not remote_dir.startswith("/")
+            or "\n" in remote_dir
+            or "\r" in remote_dir
+            or "\x00" in remote_dir
         ):
             raise BackendError("remote upload directory must be absolute")
         chunk_size = int(options.get("chunk_size") or 0)
@@ -596,7 +728,7 @@ class OpenAPIBackend(Backend):
         if chunk_size and chunk_size < 1024 * 1024:
             raise BackendError("chunk size must be at least 1 MiB or 0")
         if chunk_size and local_path.stat().st_size > chunk_size:
-            return self._op_chunked_upload(local_path, remote_path, options, chunk_size)
+            return self._op_chunked_upload(local_path, remote_dir, options, chunk_size)
         efile_url, token, _ = self._efile_context(options)
         content_type = mimetypes.guess_type(local_path.name)[0] or "application/octet-stream"
         self._multipart_request(
@@ -604,13 +736,17 @@ class OpenAPIBackend(Backend):
             token,
             {
                 "cover": "cover" if options.get("cover") else "uncover",
-                "path": remote_path,
+                "path": remote_dir,
             },
             local_path.name,
             local_path.read_bytes(),
             content_type,
         )
-        return {"local_path": str(local_path), "remote_path": remote_path}
+        return {
+            "local_path": str(local_path),
+            "remote_dir": remote_dir,
+            "remote_filename": local_path.name,
+        }
 
     def _multipart_request(
         self,

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

@@ -220,7 +220,10 @@ class SSHBackend(Backend):
 
     def op_upload(self, options: Mapping[str, Any]) -> Any:
         local_path = Path(str(require_option(options, "local_path"))).expanduser()
-        remote_path = str(require_option(options, "remote_path"))
+        remote_path = str(
+            options.get("remote_dir")
+            or require_option(options, "remote_path")
+        )
         if not local_path.is_file():
             raise BackendError(f"local file does not exist: {local_path}")
         if not remote_path.startswith("/") or "\n" in remote_path:

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

@@ -7,6 +7,7 @@ import hmac
 import json
 import os
 import time
+from pathlib import Path
 from typing import Any, Mapping
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlencode, urlsplit, urlunsplit
@@ -45,6 +46,8 @@ def service_endpoint(base_url: str, service: str, suffix: str) -> str:
 class SCNetClient:
     """One authenticated OpenAPI client shared by service-specific domains."""
 
+    TOKEN_CACHE_TTL = 4 * 60 * 60
+
     def __init__(self, context: BackendContext):
         self.context = context
         self._regions_cache: list[dict[str, Any]] | None = None
@@ -55,6 +58,79 @@ class SCNetClient:
         value = os.environ.get(name)
         return value if value not in (None, "") else default
 
+    @classmethod
+    def _token_cache_paths(cls) -> tuple[Path, Path]:
+        root = Path(cls.env("XDG_CACHE_HOME", str(Path.home() / ".cache"))) / "scnet-hpc"
+        return root / "openapi-regions.json", root / "openapi-regions.lock"
+
+    @staticmethod
+    def _credential_fingerprint(user: str, access_key: str, secret_key: str) -> str:
+        value = "\0".join((user, access_key, secret_key)).encode("utf-8")
+        return hashlib.sha256(value).hexdigest()
+
+    @classmethod
+    def _read_token_cache(cls, fingerprint: str) -> list[dict[str, Any]] | None:
+        path, _ = cls._token_cache_paths()
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            if (
+                payload.get("fingerprint") != fingerprint
+                or time.time() - float(payload.get("created_at", 0)) > cls.TOKEN_CACHE_TTL
+                or not isinstance(payload.get("regions"), list)
+            ):
+                return None
+            return [item for item in payload["regions"] if isinstance(item, dict)]
+        except (OSError, TypeError, ValueError):
+            return None
+
+    @classmethod
+    def _write_token_cache(
+        cls, fingerprint: str, regions: list[dict[str, Any]]
+    ) -> None:
+        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)
+
+    @classmethod
+    def _acquire_token_cache_lock(cls) -> Path | None:
+        _, lock = cls._token_cache_paths()
+        lock.parent.mkdir(parents=True, mode=0o700, exist_ok=True)
+        for _ in range(50):
+            try:
+                fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+                os.close(fd)
+                return lock
+            except FileExistsError:
+                try:
+                    if time.time() - lock.stat().st_mtime > 30:
+                        lock.unlink()
+                        continue
+                except OSError:
+                    pass
+                time.sleep(0.2)
+        return None
+
+    @staticmethod
+    def _release_token_cache_lock(lock: Path | None) -> None:
+        if lock is not None:
+            try:
+                lock.unlink()
+            except FileNotFoundError:
+                pass
+
     def request(
         self,
         method: str,
@@ -150,25 +226,41 @@ class SCNetClient:
                 "OpenAPI credentials are not configured; run setup or set "
                 + ", ".join(missing)
             )
-        timestamp = str(int(time.time()))
-        signature = canonical_signature(access_key, timestamp, user, secret_key)
-        auth_base = self.env("SCNET_OPENAPI_AUTH_BASE", "https://api.scnet.cn")
-        data = self.request(
-            "POST",
-            auth_base.rstrip("/") + "/api/user/v3/tokens",
-            headers={
-                "user": user,
-                "accessKey": access_key,
-                "signature": signature,
-                "timestamp": timestamp,
-            },
-        )
-        if not isinstance(data, list):
-            raise BackendError("token endpoint returned an unexpected data shape")
-        self._regions_cache = [
-            item for item in data if isinstance(item, dict)
-        ]
-        return self._regions_cache
+        fingerprint = self._credential_fingerprint(user, access_key, secret_key)
+        if not refresh:
+            cached = self._read_token_cache(fingerprint)
+            if cached:
+                self._regions_cache = cached
+                return cached
+        lock = self._acquire_token_cache_lock()
+        try:
+            if not refresh:
+                cached = self._read_token_cache(fingerprint)
+                if cached:
+                    self._regions_cache = cached
+                    return cached
+            timestamp = str(int(time.time()))
+            signature = canonical_signature(access_key, timestamp, user, secret_key)
+            auth_base = self.env("SCNET_OPENAPI_AUTH_BASE", "https://api.scnet.cn")
+            data = self.request(
+                "POST",
+                auth_base.rstrip("/") + "/api/user/v3/tokens",
+                headers={
+                    "user": user,
+                    "accessKey": access_key,
+                    "signature": signature,
+                    "timestamp": timestamp,
+                },
+            )
+            if not isinstance(data, list):
+                raise BackendError("token endpoint returned an unexpected data shape")
+            self._regions_cache = [
+                item for item in data if isinstance(item, dict)
+            ]
+            self._write_token_cache(fingerprint, self._regions_cache)
+            return self._regions_cache
+        finally:
+            self._release_token_cache_lock(lock)
 
     def select_region(
         self, requested: str | None