dsh-scnet 0.5.1 → 0.6.0

package/README.md

@@ -4,10 +4,18 @@
 
 DSH-SCNet (`dsh-scnet` on npm) is a community-maintained DSH bundle for operating Supercomputing Network (SCNet). It packages the source [`scnet-hpc`](https://github.com/lql341/scnet-hpc) Skill, profile-aware utilities, and bounded tools for SSH, Slurm, OpenAPI files, regional resources, and Notebook discovery.
 
-Current release: **0.5.1**
+Current release: **0.6.0**
 
 > 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
+
+- 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,6 +53,10 @@ 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_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_notebook_regions` | List Notebook-capable regions |
 | `scnet_notebook_resources` | Query Notebook CPU/GPU/DCU resources |
@@ -89,6 +101,13 @@ 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.0`). 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.
+
 ## Validation
 
 ```sh

package/README_CN.md

@@ -4,10 +4,17 @@
 
 <p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
 
-当前版本：**0.5.1**
+当前版本：**0.6.0**
 
 > 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。
 
+## 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,6 +60,10 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 | scnet_status | 只读查看 backend、SSH profile 和 OpenAPI 配置 |
 | scnet_openapi_regions | 列出授权 OpenAPI 区域，不暴露 token |
 | scnet_job_queues | 查询区域 Slurm 队列和实时空闲资源 |
+| 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_notebook_regions | 列出支持 Notebook 的区域 |
 | scnet_notebook_resources | 查询 Notebook CPU/GPU/DCU 资源 |
@@ -105,6 +116,12 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 再把 Skill 内容和版本同步到 `dsh-scnet` 与 `codex-scnet-hpc`。下游变更审核通过后，
 才能发布对应版本的 `dsh-scnet` npm 包。
 
+下游同步合并到 `main` 后，先运行本地校验，再手动触发仓库的 `Publish DSH-SCNet` workflow，
+输入 `package.json` 中的精确版本（当前为 `0.6.0`）。workflow 会校验 package 与 Skill
+版本一致，执行验证、生成 tarball、以稳定版 `latest` 标签发布，并创建对应 Git tag。
+不要只修改 `package.json`；`skills/scnet-hpc/VERSION`、package 版本和两份 README 的版本
+标记必须保持一致。
+
 ## 隐私与安全
 
 - 仓库不含私钥、token、用户名、密钥指纹。

package/docs/testing.md

@@ -40,6 +40,10 @@ 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_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_notebook_regions` | Lists Notebook-capable regions |
 | `scnet_notebook_resources` | Returns Notebook resource groups |
@@ -60,6 +64,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,6 +61,11 @@ DEEPSEEK_API_KEY: sk-你的key
 | 8 | 用 scnet_status 查看当前配置 | 返回脱敏配置 | 只读 |
 | 9 | 用 scnet_openapi_regions 查看授权区域 | 返回区域且不含 token | 只读 |
 | 10 | 用 scnet_job_queues 查看昆山队列 | 返回实时队列和空闲资源 | 只读 |
+| 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 查看默认目录 | 返回共享存储文件 | 只读 |
 | 12 | 用 scnet_notebook_regions 查看区域 | 返回 Notebook 可用区域 | 只读 |
 | 13 | 用 scnet_notebook_resources 查看昆山资源 | 返回 CPU/GPU/DCU 资源 | 只读 |
@@ -68,5 +73,8 @@ DEEPSEEK_API_KEY: sk-你的key
 
 第 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,275 @@ export function apply(ctx) {
     }),
   )
 
+  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_list',
@@ -486,3 +947,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.0",
   "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.0