dsh-scnet 0.5.1 → 0.6.1

package/README.md

@@ -4,10 +4,26 @@
 
 DSH-SCNet (`dsh-scnet` on npm) is a community-maintained DSH bundle for operating Supercomputing Network (SCNet). It packages the source [`scnet-hpc`](https://github.com/lql341/scnet-hpc) Skill, profile-aware utilities, and bounded tools for SSH, Slurm, OpenAPI files, regional resources, and Notebook discovery.
 
-Current release: **0.5.1**
+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.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.
+- Added dry-run support and one-missing-decision-at-a-time validation for job lifecycle calls.
+- Job submission reports the authoritative work directory and log paths; OpenAPI log lookup can
+  derive `std.out` and `std.err` paths from `job_id` and `work_dir`.
+
 ## Requirements
 
 - Node.js 22.19 or later
@@ -45,7 +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 |
@@ -89,6 +112,19 @@ Release order is canonical-to-downstream: update `scnet-hpc/VERSION` first; its
 synchronizes the skill and version into `dsh-scnet` and `codex-scnet-hpc`. Publish the matching
 `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
+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,23 @@
 
 <p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
 
-当前版本：**0.5.1**
+当前版本：**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。
+- 作业生命周期调用支持 `dry_run`，并按 CLI 顺序一次只提示一个缺失决策。
+- 提交结果返回权威的工作目录和日志路径；OpenAPI 日志查询支持由 `job_id` 和 `work_dir`
+  推导 `std.out`、`std.err` 路径。
+
 ## 这是什么
 
 一个 DeepSeek Harness bundle 插件，把 `scnet-hpc` 的 Agent Skill 和 bash 脚本包装成 DSH 可安装包。装好后 DSH 模型在涉及超算集群、Slurm 作业、海光 DCU/DTK 时会加载对应 skill，并可调用工具完成确定性操作。
@@ -53,7 +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 实例并脱敏敏感字段 |
@@ -105,6 +125,17 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 再把 Skill 内容和版本同步到 `dsh-scnet` 与 `codex-scnet-hpc`。下游变更审核通过后，
 才能发布对应版本的 `dsh-scnet` npm 包。
 
+下游同步合并到 `main` 后，先运行本地校验，再手动触发仓库的 `Publish DSH-SCNet` workflow，
+输入 `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,7 +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 |
@@ -60,6 +67,10 @@ Check both accelerator and CPU-only job generation. Review the output for the se
 
 `scnet_run_compute_probe` and refresh operations with compute probing submit Slurm jobs. Confirm the target cluster, account policy, accelerator count, CPU count, and time limit before execution.
 
+`scnet_submit_job` and `scnet_job_cancel` are mutating tools and consume or release real scheduler
+resources. Run them with `dry_run=true` first, confirm the resolved target region or cluster in the
+result, and never retry a timed-out submission blindly: query the job state instead.
+
 Notebook lifecycle mutations are intentionally not exposed as deterministic DSH tools in this
 release. Test them only through the Skill CLI and start with `--dry-run`.
 

package/docs/testing.zh-CN.md

@@ -61,12 +61,23 @@ 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 查看实例 | 返回脱敏实例列表 | 只读 |
 
 第 4 至 7 步只有在你有私钥和目标集群时才测，测前确认副作用。
 
+第 10b、10e 步是变更操作，会真实占用或释放调度器资源：先用 `dry_run=true` 预览，确认返回里的
+目标区域/集群，并且**不要在提交超时后盲目重试**（平台没有幂等键），先查作业状态。
+
 Notebook 创建、启动、停止和释放没有作为 DSH deterministic tool 暴露。此类操作通过
 Skill CLI 执行，并先使用 `--dry-run`。

package/index.mjs

@@ -94,6 +94,198 @@ function positiveInt(value, label) {
   return { value: String(value).trim() }
 }
 
+// ---- 作业生命周期（submit / job / logs / cancel）辅助 ----
+//
+// 设计约束来自 scnet-hpc Skill 的 SKILL.md：
+//   - 变更操作必须解析到一个确定目标（OpenAPI 允许默认区域，SSH 多 profile 时必须显式）
+//   - 提交/取消绝不自动重试
+//   - 缺失参数一次只提示一个，并给出可执行的下一步
+
+const JOB_BACKENDS = new Set(['openapi', 'ssh'])
+
+const MISSING_HINTS = {
+  name: '缺 name：请给这个作业起一个名字。',
+  command: '缺 command：请给出要在计算节点上执行的命令或脚本体。',
+  work_dir: '缺 work_dir：请给出一个绝对路径作为作业工作目录（日志默认也落在那里）。',
+  queue: '缺 queue：请指定队列；不确定可先看该区域的空闲队列。',
+  remote_path: '缺 remote_path：SSH 模式请给出远端已存在的 Slurm 脚本绝对路径。',
+  job_id: '缺 job_id：请给出作业号。',
+  path: '缺 path：请给出远端日志文件的绝对路径。',
+}
+
+// 与 CLI 的必填顺序保持一致（openapi.py 的 _submit_payload：name → command → work_dir → queue）。
+// queue 不在这里：它由队列预检统一处理，可能是自动选择、也可能是"请补一个"。
+const SUBMIT_REQUIRED_ORDER = ['name', 'command', 'work_dir']
+
+function firstMissingRequired(args, keys) {
+  for (const key of keys) {
+    if (!String(args[key] ?? '').trim()) return key
+  }
+  return ''
+}
+
+// backend 默认 openapi，不强制用户填写
+function pickBackend(value) {
+  const raw = String(value ?? '').trim().toLowerCase()
+  if (!raw) return { backend: 'openapi', argv: ['--backend', 'openapi'] }
+  if (!JOB_BACKENDS.has(raw)) return { error: `backend 只支持 openapi 或 ssh，收到 ${value}。` }
+  return { backend: raw, argv: ['--backend', raw] }
+}
+
+// region / scheduler_id 交给后端自行解析：只有用户显式给了才透传
+function openapiTargetArgs(args) {
+  const argv = []
+  const region = String(args.region ?? '').trim()
+  if (region) argv.push('--region', region)
+  const scheduler = String(args.scheduler_id ?? '').trim()
+  if (scheduler) argv.push('--scheduler-id', scheduler)
+  return argv
+}
+
+// SSH：恰好一个 profile 时自动选择；多个才要求用户补 cluster 一个参数
+async function sshClusterArg(args) {
+  const cluster = String(args.cluster ?? '').trim()
+  if (cluster) return { argv: ['--cluster', cluster], cluster }
+  const ids = await listClusterIds()
+  if (ids.length === 1) return { argv: ['--cluster', ids[0]], cluster: ids[0] }
+  return {
+    error: `存在多个集群 profile，请补 cluster 一个参数。可选：${ids.join('、') || '（无）'}`,
+  }
+}
+
+async function resolveTarget(args) {
+  const pick = pickBackend(args.backend)
+  if (pick.error) return pick
+  const argv = [...pick.argv]
+  if (pick.backend === 'openapi') {
+    argv.push(...openapiTargetArgs(args))
+    return { backend: pick.backend, argv }
+  }
+  const ssh = await sshClusterArg(args)
+  if (ssh.error) return ssh
+  argv.push(...ssh.argv)
+  return { backend: pick.backend, argv, cluster: ssh.cluster }
+}
+
+// 失败时把 --json 错误信封里的 error 取出来
+function errorTextFrom(res) {
+  const raw = String(res.stdout || '').trim() || String(res.stderr || '').trim()
+  try {
+    const parsed = JSON.parse(raw)
+    if (parsed && typeof parsed === 'object' && typeof parsed.error === 'string') {
+      return parsed.error
+    }
+  } catch {
+    // 非 JSON，退回纯文本解析
+  }
+  const matched = raw.match(/error:\s*(.+)/)
+  return matched ? matched[1].trim() : raw
+}
+
+// 一次只给一条可执行的提示（不展示整套参数清单）
+function translateScnetError(text) {
+  const value = String(text || '')
+  const missing = value.match(/missing required option:\s*([A-Za-z_]+)/)
+  if (missing) return MISSING_HINTS[missing[1]] || `缺 ${missing[1]}：这是必填参数。`
+  if (/multiple schedulers are available/i.test(value)) {
+    const list = value.split('use --scheduler-id:')[1] || ''
+    return `该区域有多个调度器，请补 scheduler_id 一个参数。候选：${list.trim()}`
+  }
+  if (/job endpoint returned an unexpected data shape/i.test(value)) {
+    return (
+      '平台没有返回这个作业的记录：作业完成一段时间后可能会从该接口消失。' +
+      '若只想看日志，请直接给日志文件的 path；若刚提交不久，可稍后重试。'
+    )
+  }
+  return value
+}
+
+function scnetJobResult(res, action) {
+  if (res.ok) return res.stdout.trim() || '{}'
+  return `${action}失败（exit ${res.code}）：\n${translateScnetError(errorTextFrom(res))}`
+}
+
+async function runScnetEnvelope(argv) {
+  const res = await runScnet(argv)
+  if (!res.ok) return { ok: false, error: translateScnetError(errorTextFrom(res)) }
+  try {
+    const parsed = JSON.parse(res.stdout)
+    return { ok: true, envelope: parsed, data: parsed?.data }
+  } catch {
+    return { ok: false, error: '后端返回的不是合法 JSON。' }
+  }
+}
+
+function parseWalltimeSeconds(value) {
+  const matched = String(value || '').trim().match(/^(?:(\d+)-)?(\d{1,2}):(\d{2}):(\d{2})$/)
+  if (!matched) return null
+  const [, days, hours, minutes, seconds] = matched
+  return Number(days || 0) * 86400 + Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds)
+}
+
+// 按是否需要加速器筛队列，空闲节点多的优先（只用于"推荐一个"，不用于静默多选一）
+function queueCandidates(queues, wantsAccelerator) {
+  return queues
+    .filter((item) => {
+      const maxDcu = Number(item?.max_dcus_per_node ?? 0)
+      return wantsAccelerator ? maxDcu > 0 : maxDcu === 0
+    })
+    .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}）` }
+  const queues = Array.isArray(check.data) ? check.data : []
+  if (queues.length === 0) return { note: '队列预检已跳过（该区域没有返回队列信息）' }
+
+  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 {
+        error:
+          `请补 queue 一个参数：该区域有 ${candidates.length} 个可用队列，` +
+          `按你要的资源建议 ${best.partition}（空闲 ${best.free_nodes} 节点）。`,
+      }
+    }
+    return {}
+  }
+
+  const hit = queues.find((item) => String(item?.partition) === queue)
+  if (!hit) {
+    const candidates = queueCandidates(queues, dcus > 0)
+    const pool = candidates.length ? candidates : queues
+    return {
+      error: `队列 ${queue} 不存在。可用队列：${pool.map((item) => item.partition).join('、')}`,
+    }
+  }
+
+  const walltime = String(args.walltime ?? '').trim()
+  if (walltime) {
+    const wanted = parseWalltimeSeconds(walltime)
+    const limit = Number(hit?.max_walltime ?? 0)
+    if (wanted !== null && Number.isFinite(limit) && limit > 0 && wanted > limit) {
+      return { error: `walltime ${walltime} 超过队列 ${queue} 的上限（${limit} 秒）。` }
+    }
+  }
+
+  const maxDcu = Number(hit?.max_dcus_per_node ?? 0)
+  if (dcus > 0 && Number.isFinite(maxDcu) && maxDcu > 0 && dcus > maxDcu) {
+    return { error: `dcus ${dcus} 超过队列 ${queue} 单节点上限 ${maxDcu}。` }
+  }
+
+  return { queue, note: `队列预检通过（${queue}）` }
+}
+
 export function apply(ctx) {
   ctx.tools.register(
     defineTool({
@@ -173,6 +365,386 @@ 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',
+      description:
+        '提交一个 SCNet 作业。默认走 OpenAPI；backend=ssh 时提交远端已存在的 Slurm 脚本。这是变更操作，会占用配额，执行前应确认目标、资源与时长。region/cluster/scheduler 能自动解析；dry_run=true 只预览请求不提交。提交成功后返回 job_id 与日志路径，可直接交给 scnet_job_logs。',
+      parameters: {
+        backend: { type: 'string', description: 'openapi（默认）或 ssh' },
+        region: { type: 'string', description: 'OpenAPI 区域；省略时由后端回落已保存的默认区域' },
+        scheduler_id: { type: 'string', description: 'OpenAPI 调度器 ID；省略时该区域只有一个调度器则自动选择' },
+        cluster: { type: 'string', description: 'SSH 集群短名；只有一个 profile 时自动选择，多个则必须指定' },
+        remote_path: { type: 'string', description: 'SSH 模式必填：远端已存在的 Slurm 脚本绝对路径' },
+        name: { type: 'string', description: 'OpenAPI 必填：作业名' },
+        command: { type: 'string', description: 'OpenAPI 必填：命令或脚本体（可多行）' },
+        work_dir: { type: 'string', description: 'OpenAPI 必填：作业工作目录（绝对路径，日志默认落在这里）' },
+        queue: { type: 'string', description: 'OpenAPI 必填：队列名；省略时仅在候选唯一时自动选择，否则会问你一个' },
+        nodes: { type: 'string', description: '节点数，默认 1' },
+        cpus: { type: 'string', description: 'CPU 核数，默认 1' },
+        dcus: { type: 'string', description: 'DCU 卡数，默认 0；部分队列的 QOS 要求至少 1（如昆山 kshdnormal）' },
+        gpus: { type: 'string', description: 'GPU 卡数，默认 0' },
+        memory: { type: 'string', description: '内存，如 12gb；省略时用调度器默认' },
+        walltime: { type: 'string', description: '时长，默认 24:00:00，格式 HH:MM:SS 或 D-HH:MM:SS' },
+        stdout: { type: 'string', description: '显式覆盖 stdout 路径；会破坏 scnet_job_logs 的便捷模式' },
+        stderr: { type: 'string', description: '显式覆盖 stderr 路径；会破坏 scnet_job_logs 的便捷模式' },
+        exclusive: { type: 'boolean', description: '独占节点（默认否）' },
+        scheduler_options: {
+          type: 'array',
+          items: { type: 'string' },
+          description: '额外的 #SBATCH 选项，逐条透传',
+        },
+        dry_run: { type: 'boolean', description: '只预览将要发送的请求，不真正提交（默认否）' },
+      },
+      timeoutMs: 180000,
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const target = await resolveTarget(args)
+        if (target.error) return target.error
+
+        const globals = [...target.argv]
+        if (args.dry_run === true) globals.push('--dry-run')
+
+        if (target.backend === 'ssh') {
+          const remotePath = String(args.remote_path ?? '').trim()
+          if (!remotePath) return MISSING_HINTS.remote_path
+          const res = await runScnet([...globals, 'submit', '--remote-path', remotePath])
+          return scnetJobResult(res, '提交作业')
+        }
+
+        for (const key of ['nodes', 'cpus', 'dcus', 'gpus']) {
+          const checked = positiveInt(args[key], key)
+          if (checked && checked.error) return checked.error
+        }
+
+        // 按 CLI 的必填顺序先做本地检查，一次只提示一个，
+        // 并避免在参数不全时就发起队列查询。
+        const missing = firstMissingRequired(args, SUBMIT_REQUIRED_ORDER)
+        if (missing) return MISSING_HINTS[missing]
+
+        const precheck = await precheckQueue(target, args)
+        if (precheck.error) return precheck.error
+        const queue = precheck.queue || String(args.queue ?? '').trim()
+
+        const argv = [...globals, 'submit']
+        const name = String(args.name ?? '').trim()
+        const command = String(args.command ?? '')
+        const workDir = String(args.work_dir ?? '').trim()
+        if (name) argv.push('--name', name)
+        if (command.trim()) argv.push('--command', command)
+        if (workDir) argv.push('--work-dir', workDir)
+        if (queue) argv.push('--queue', queue)
+        for (const [flag, key] of [
+          ['--nodes', 'nodes'],
+          ['--cpus', 'cpus'],
+          ['--dcus', 'dcus'],
+          ['--gpus', 'gpus'],
+        ]) {
+          const checked = positiveInt(args[key], key)
+          if (checked && checked.value) argv.push(flag, checked.value)
+        }
+        for (const [flag, key] of [
+          ['--memory', 'memory'],
+          ['--walltime', 'walltime'],
+          ['--stdout', 'stdout'],
+          ['--stderr', 'stderr'],
+        ]) {
+          const value = String(args[key] ?? '').trim()
+          if (value) argv.push(flag, value)
+        }
+        if (args.exclusive === true) argv.push('--exclusive')
+        const options = Array.isArray(args.scheduler_options) ? args.scheduler_options : []
+        for (const option of options) {
+          const value = String(option ?? '').trim()
+          if (value) argv.push('--scheduler-option', value)
+        }
+
+        const res = await runScnet(argv)
+        if (!res.ok) return scnetJobResult(res, '提交作业')
+        if (args.dry_run === true) return res.stdout.trim() || '{}'
+
+        let jobId = ''
+        try {
+          const parsed = JSON.parse(res.stdout)
+          jobId = String(parsed?.data?.job_id ?? parsed?.job_id ?? '')
+        } catch {
+          // 保底走下面的原始输出分支
+        }
+        if (!jobId) return `提交请求已发出，但没能解析出 job_id。原始返回：\n${res.stdout.trim()}`
+
+        // 提交后立刻取一次权威的 work_dir / 日志路径；作业较旧时该接口可能不再返回记录
+        const jobRes = await runScnetEnvelope([...target.argv, 'job', jobId])
+        let resolvedWorkDir = workDir
+        let stdoutPath = String(args.stdout ?? '').trim()
+        let stderrPath = String(args.stderr ?? '').trim()
+        let source = 'default-rule'
+        if (jobRes.ok && jobRes.data) {
+          resolvedWorkDir = String(jobRes.data.work_dir || resolvedWorkDir || '')
+          stdoutPath = String(jobRes.data.stdout || stdoutPath || '')
+          stderrPath = String(jobRes.data.stderr || stderrPath || '')
+          source = 'job'
+        }
+        if (!stdoutPath && resolvedWorkDir) {
+          const base = resolvedWorkDir.replace(/\/+$/, '')
+          stdoutPath = `${base}/std.out.${jobId}`
+          stderrPath = stderrPath || `${base}/std.err.${jobId}`
+        }
+
+        const summary = {
+          backend: target.backend,
+          region: String(args.region ?? '').trim() || '（由后端默认区域解析）',
+          scheduler_id: String(args.scheduler_id ?? '').trim() || undefined,
+          job_id: jobId,
+          queue: queue || undefined,
+          work_dir: resolvedWorkDir || undefined,
+          stdout: stdoutPath || undefined,
+          stderr: stderrPath || undefined,
+          log_paths_source: source,
+          precheck: precheck.note || undefined,
+          note: '用 scnet_job_logs 读日志：直接传上面的 path，或传 job_id + work_dir。',
+        }
+        return JSON.stringify(summary, null, 2)
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_job_show',
+      description:
+        '只读查询一个作业的状态与资源（state / exit_code / work_dir / stdout / stderr）。作业完成较久后平台可能不再返回记录，此时用 scnet_job_logs 的 path 模式读日志即可。',
+      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 则自动选择' },
+      },
+      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
+        return scnetJobResult(await runScnet([...target.argv, 'job', jobId]), '查询作业')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_job_logs',
+      description:
+        '只读读取作业日志。两种模式：显式给 path（远端绝对路径，SSH 下只能用这个）；或给 job_id + work_dir + stream，内部按平台默认命名 std.out/std.err.{job_id} 推导。path 优先。',
+      parameters: {
+        path: { type: 'string', description: '显式模式：远端日志文件的绝对路径' },
+        job_id: { type: 'string', description: '便捷模式：作业号' },
+        work_dir: { type: 'string', description: '便捷模式：作业工作目录；省略时会尝试查一次作业' },
+        stream: { type: 'string', description: '便捷模式：stdout（默认）或 stderr' },
+        lines: { type: 'string', description: '读取行数，默认 200（1-10000）' },
+        direction: { type: 'string', description: 'head 或 tail（默认 tail）' },
+        backend: { type: 'string', description: 'openapi（默认）或 ssh' },
+        region: { type: 'string', description: 'OpenAPI 区域；省略时用已保存的默认区域' },
+        scheduler_id: { type: 'string', description: 'OpenAPI 调度器 ID；省略时自动' },
+        cluster: { type: 'string', description: 'SSH 集群短名；省略时若只有一个 profile 则自动选择' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const target = await resolveTarget(args)
+        if (target.error) return target.error
+
+        const lines = positiveInt(args.lines, 'lines')
+        if (lines && lines.error) return lines.error
+
+        let path = String(args.path ?? '').trim()
+        const jobId = String(args.job_id ?? '').trim()
+        let derived = false
+
+        if (!path) {
+          if (target.backend === 'ssh') {
+            return 'SSH 模式的日志路径由作业脚本里的 #SBATCH --output 决定，无法推导；请用 path 给出远端日志文件的绝对路径。'
+          }
+          if (!jobId) return `${MISSING_HINTS.path}（或给 job_id + work_dir 走便捷模式。）`
+          const stream = String(args.stream ?? 'stdout').trim().toLowerCase()
+          if (stream !== 'stdout' && stream !== 'stderr') return 'stream 只支持 stdout 或 stderr。'
+          let workDir = String(args.work_dir ?? '').trim()
+          if (!workDir) {
+            const jobRes = await runScnetEnvelope([...target.argv, 'job', jobId])
+            if (jobRes.ok && jobRes.data?.work_dir) {
+              workDir = String(jobRes.data.work_dir)
+            } else {
+              return `缺 work_dir：查不到作业 ${jobId} 的工作目录（${jobRes.error || '平台无记录'}）。请补 work_dir，或直接用 path。`
+            }
+          }
+          const suffix = stream === 'stderr' ? 'err' : 'out'
+          path = `${workDir.replace(/\/+$/, '')}/std.${suffix}.${jobId}`
+          derived = true
+        }
+
+        const argv = [...target.argv, 'logs', '--path', path]
+        if (lines && lines.value) argv.push('--lines', lines.value)
+        const direction = String(args.direction ?? '').trim()
+        if (direction) argv.push('--direction', direction)
+
+        const res = await runScnet(argv)
+        if (!res.ok) return scnetJobResult(res, '读取日志')
+        const body = res.stdout.trim() || '{}'
+        return derived ? `${body}\n\n（日志路径由 job_id 与 work_dir 推导：${path}）` : body
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_job_cancel',
+      description:
+        '取消一个作业。这是变更操作，执行前应确认 job_id 与目标区域；dry_run=true 只预览不发送。超时后不要自动重试，先查状态。',
+      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 则自动选择' },
+        dry_run: { type: 'boolean', description: '只预览，不发送取消请求（默认否）' },
+      },
+      timeoutMs: 180000,
+      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]
+        if (args.dry_run === true) argv.push('--dry-run')
+        argv.push('cancel', jobId)
+        return scnetJobResult(await runScnet(argv), '取消作业')
+      },
+    }),
+  )
+
+  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',
@@ -486,3 +1058,15 @@ export function apply(ctx) {
     }),
   )
 }
+
+// 仅供 tests/ 使用：把作业生命周期里的纯函数暴露出来做单元测试。
+export const __testables = {
+  MISSING_HINTS,
+  SUBMIT_REQUIRED_ORDER,
+  errorTextFrom,
+  firstMissingRequired,
+  parseWalltimeSeconds,
+  pickBackend,
+  queueCandidates,
+  translateScnetError,
+}

package/package.json

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