dsh-scnet 0.4.1 → 0.5.0

package/README.md

@@ -1,10 +1,10 @@
 # DSH-SCNet
 
-[English](#english) | [简体中文](#简体中文)
+[简体中文](./README_CN.md)
 
-## English
+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.
 
-DSH-SCNet (`dsh-scnet` on npm) is a community-maintained DSH bundle for operating Supercomputing Network (SCNet) clusters. It packages the canonical [`scnet-hpc`](https://github.com/lql341/scnet-hpc) skill, profile-aware shell utilities, and seven deterministic tools for SSH setup, Slurm job generation, cluster discovery, and compute-node diagnostics.
+Current release: **0.5.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.
 
@@ -42,6 +42,14 @@ See [Installation](./docs/installation.md) for npm, GitHub, and local-checkout w
 | `scnet_probe_cluster` | Produce an initial profile from read-only login-node probes |
 | `scnet_refresh_cluster` | Refresh time-sensitive profile fields; compute probing is opt-in |
 | `scnet_run_compute_probe` | Submit a minimal compute-node capability probe |
+| `scnet_status` | Read the saved backend, SSH profile, and OpenAPI configuration |
+| `scnet_openapi_regions` | List authorized OpenAPI regions without exposing tokens |
+| `scnet_job_queues` | Query regional Slurm queues and live resource availability |
+| `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 |
+| `scnet_notebook_list` | List Notebook instances with sensitive fields redacted |
+| `scnet_notebook_show` | Inspect one redacted Notebook instance |
 
 Packaged profiles currently cover Zhengzhou, Kunshan, Wuzhen, and Xi'an SCNet environments. Cluster specifications and scheduler policies remain profile-specific and should be verified against the target environment.
 
@@ -57,6 +65,8 @@ Packaged profiles currently cover Zhengzhou, Kunshan, Wuzhen, and Xi'an SCNet en
 │   ├── clusters/
 │   ├── references/
 │   └── scripts/
+│       ├── scnet_backends/
+│       └── scnet_sdk/
 ├── scripts/validate-package.mjs
 ├── docs/
 ├── sync.sh
@@ -89,6 +99,8 @@ See [Testing](./docs/testing.md) for local package installation and risk-ordered
 
 - The repository and npm package must not contain private keys, tokens, usernames, private endpoints, or local probe caches.
 - SSH configuration, remote probes, and Slurm submission are state-changing operations and require an explicit target and user authorization.
+- OpenAPI and Notebook DSH tools are read-only; lifecycle mutations remain behind the Skill CLI confirmation flow.
+- Notebook passwords and credential-bearing URL queries are redacted by default.
 - Generated Slurm files may include local usernames and are ignored by Git.
 - Accelerator compatibility claims require evidence from the target compute node.
 
@@ -98,118 +110,13 @@ The project uses the abbreviated `DSH` ecosystem identifier in its name. Referen
 
 The naming and attribution policy follows the [DeepSeek Harness brand guidelines](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.0-rc.8/BRAND_GUIDELINES.md).
 
-## License
-
-This project is released under the [MIT License](LICENSE). Subject to the license terms, the software may be used, copied, modified, merged, published, sublicensed, and distributed, including for commercial purposes.
-
-Redistributions must retain the copyright notice and the MIT license notice. The software is provided “as is,” without warranties of any kind; users are responsible for evaluating the suitability and risks of the bundle, skill instructions, cluster profiles, scripts, and generated outputs for their own environment.
-
----
-
-## 简体中文
-
-[English](#english) | [简体中文](#简体中文)
-
-<p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）集群：配 SSH、生成 CPU/DCU Slurm 作业、探测/刷新集群、运行计算节点探针、排查失败，附海光 DCU/DTK 知识和英文快速指南。</p>
-
-> 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。
-
-## 这是什么
-
-一个 DeepSeek Harness bundle 插件，把 `scnet-hpc` 的 Agent Skill 和 bash 脚本包装成 DSH 可安装包。装好后 DSH 模型在涉及超算集群、Slurm 作业、海光 DCU/DTK 时会加载对应 skill，并可调用工具完成确定性操作。
-
-## 安装
-
-推荐从 npm 安装：
-
-```sh
-dsh plugin --profile web add dsh-scnet
-```
-
-git 源、本地目录安装以及验证步骤见[安装说明](./docs/installation.zh-CN.md)。
-
-## 能力面
-
-### Skills
-
-| Skill | 作用 |
-|---|---|
-| scnet-hpc | 国产超算使用规范：连接、提交/监控、调试、失败排查、海光 DCU/DTK 资源索引 |
-
-### 内置集群
+## Versioning
 
-| 短名 | 描述 | 加速器 |
-|---|---|---|
-| zzeshell | 超算互联网 · 郑州 | 海光 BW1000 DCU (gfx936) ×8, 64GB/卡 |
-| kseshell | 超算互联网 · 昆山 | 海光 Z100 DCU (gfx906) ×4, 16GB/卡 |
-| wuzhshell | 超算互联网 · 乌镇 | 海光 Z100 DCU (gfx906) ×4, 16GB/卡 |
-| xianshell | 超算互联网 · 西安 | 海光 Z100 DCU (gfx906) ×4, 16GB/卡 |
-
-### Tools
-
-| 工具 | 说明 |
-|---|---|
-| scnet_list_clusters | 列出已配置的集群 profile |
-| scnet_show_cluster | 读取指定集群的完整参数 |
-| scnet_generate_job | 按 profile 生成加速器或 CPU-only Slurm 作业，支持显式分区覆盖 |
-| scnet_setup_ssh | 配置本地到集群的 SSH 连接 |
-| scnet_probe_cluster | 探测新集群并生成 profile |
-| scnet_refresh_cluster | 动态刷新已有集群的规则缓存 |
-| scnet_run_compute_probe | 在计算节点运行最小能力探针 |
-
-## 文档
-
-- [安装说明](./docs/installation.zh-CN.md)
-- [测试说明](./docs/testing.zh-CN.md)
-
-## 结构
-
-```
-.
-├── package.json          # dsh.bundle manifest
-├── cordis.patch.yml      # bundle 组合层
-├── index.mjs             # Cordis 入口，注册 7 个工具
-├── skills/scnet-hpc/
-│   ├── clusters/
-│   │   ├── zzeshell.conf
-│   │   ├── kseshell.conf
-│   │   ├── wuzhshell.conf
-│   │   └── xianshell.conf
-│   ├── scripts/
-│   └── references/
-├── sync.sh               # 从 canonical 仓库同步
-├── README.md             # 英文默认说明
-├── README_CN.md          # 中文说明
-├── docs/                # 中英文安装与测试文档
-├── LICENSE
-└── .gitignore
-```
-
-## 同步
-
-本仓库是发布面，知识内容（`skills/scnet-hpc/` 下的 SKILL.md、clusters、references、scripts）从 canonical 仓库 `lql341/scnet-hpc` 同步：
-
-```sh
-./sync.sh                   # 当前本机布局默认 ../../skills/scnet-hpc
-./sync.sh --src /path/to/scnet-hpc
-```
-
-只改 canonical，本仓库跑 sync 更新；不要把 `skills/scnet-hpc/` 当手工维护目录。
-`sync.sh` 会自动排除 `scripts/install.sh` 和 `clusters/.cache/`，避免把安装脚本或本机动态缓存打进发布包。
-
-## 隐私与安全
-
-- 仓库不含私钥、token、用户名、密钥指纹。
-- `scnet_setup_ssh` 会写入 `~/.ssh/`，调用前确认私钥路径和集群。
-- `scnet_generate_job` 生成的 `.slurm` 可能含本机用户名，`.gitignore` 已排除。
-- SSH 接入端点仅使用平台面向用户公开提供的信息，由 canonical 仓库维护。
-- `scnet_refresh_cluster` / `scnet_run_compute_probe` 会 SSH 到远端并可能提交作业；运行前确认集群和副作用。
-- `clusters/.cache/` 是本机动态探测缓存，`.gitignore` 已排除，不应提交。
+The npm package version matches `skills/scnet-hpc/VERSION` and follows the same SemVer release
+train as the source Skill.
 
 ## License
 
-本项目采用 [MIT License](LICENSE) 开源。除许可证正文另有规定外，使用者可以自由使用、复制、修改、合并、发布、再许可和销售本项目及其衍生作品。
-
-再发布本项目或其重要组成部分时，应保留版权声明和 MIT 许可声明。本项目按“现状”提供，不对适销性、特定用途适用性或不侵权作任何明示或默示保证；使用者应自行评估 DSH bundle、skill 说明、集群配置、脚本和生成结果在其环境中的适用性与风险。
+This project is released under the [MIT License](LICENSE). Subject to the license terms, the software may be used, copied, modified, merged, published, sublicensed, and distributed, including for commercial purposes.
 
-项目命名与归属声明遵循 [DeepSeek Harness 品牌素材使用规范](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.0-rc.8/BRAND_GUIDELINES.zh.md)。
+Redistributions must retain the copyright notice and the MIT license notice. The software is provided “as is,” without warranties of any kind; users are responsible for evaluating the suitability and risks of the bundle, skill instructions, cluster profiles, scripts, and generated outputs for their own environment.

package/README_CN.md

@@ -2,7 +2,9 @@
 
 [English](./README.md) | 简体中文
 
-<p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）集群：配 SSH、生成 CPU/DCU Slurm 作业、探测/刷新集群、运行计算节点探针、排查失败，附海光 DCU/DTK 知识和英文快速指南。</p>
+<p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
+
+当前版本：**0.5.0**
 
 > 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。
 
@@ -48,6 +50,14 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 | scnet_probe_cluster | 探测新集群并生成 profile |
 | scnet_refresh_cluster | 动态刷新已有集群的规则缓存 |
 | scnet_run_compute_probe | 在计算节点运行最小能力探针 |
+| scnet_status | 只读查看 backend、SSH profile 和 OpenAPI 配置 |
+| scnet_openapi_regions | 列出授权 OpenAPI 区域，不暴露 token |
+| scnet_job_queues | 查询区域 Slurm 队列和实时空闲资源 |
+| scnet_file_list | 通过通用文件 API 列出共享存储 |
+| scnet_notebook_regions | 列出支持 Notebook 的区域 |
+| scnet_notebook_resources | 查询 Notebook CPU/GPU/DCU 资源 |
+| scnet_notebook_list | 列出 Notebook 实例并脱敏敏感字段 |
+| scnet_notebook_show | 查询一个脱敏后的 Notebook 实例详情 |
 
 ## 文档
 
@@ -68,6 +78,8 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 │   │   ├── wuzhshell.conf
 │   │   └── xianshell.conf
 │   ├── scripts/
+│   │   ├── scnet_backends/
+│   │   └── scnet_sdk/
 │   └── references/
 ├── sync.sh               # 从 canonical 仓库同步
 ├── README.md             # 英文默认说明
@@ -96,6 +108,8 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 - `scnet_generate_job` 生成的 `.slurm` 可能含本机用户名，`.gitignore` 已排除。
 - SSH 接入端点仅使用平台面向用户公开提供的信息，由 canonical 仓库维护。
 - `scnet_refresh_cluster` / `scnet_run_compute_probe` 会 SSH 到远端并可能提交作业；运行前确认集群和副作用。
+- 新增 OpenAPI 和 Notebook DSH 工具均为只读；Notebook 生命周期变更仍通过 Skill CLI 的确认流程执行。
+- Notebook 密码和带凭据的 URL 查询参数默认脱敏。
 - `clusters/.cache/` 是本机动态探测缓存，`.gitignore` 已排除，不应提交。
 
 ## License
@@ -105,3 +119,8 @@ git 源、本地目录安装以及验证步骤见[安装说明](./docs/installat
 再发布本项目或其重要组成部分时，应保留版权声明和 MIT 许可声明。本项目按“现状”提供，不对适销性、特定用途适用性或不侵权作任何明示或默示保证；使用者应自行评估 DSH bundle、skill 说明、集群配置、脚本和生成结果在其环境中的适用性与风险。
 
 项目命名与归属声明遵循 [DeepSeek Harness 品牌素材使用规范](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.0-rc.8/BRAND_GUIDELINES.zh.md)。
+
+## 版本管理
+
+npm package 版本与 `skills/scnet-hpc/VERSION` 保持一致，并与源 Skill 使用同一套 SemVer
+发布版本。

package/docs/installation.md

@@ -58,3 +58,13 @@ dsh web
 ## Credentials
 
 Model credentials belong in the DSH credential store or its supported settings interface. SCNet private keys remain local and are supplied only when the user explicitly invokes SSH setup. Neither credential type belongs in this repository.
+
+SCNet OpenAPI uses a platform username, AccessKey, and SecretKey. Configure them through the
+bundled Skill:
+
+```sh
+python3 skills/scnet-hpc/scripts/scnet.py setup modify --mode openapi
+```
+
+On macOS credentials can be stored in Keychain. On Linux, install `libsecret-tools` for Secret
+Service; otherwise inject the documented `SCNET_OPENAPI_*` environment variables.

package/docs/installation.zh-CN.md

@@ -1,6 +1,7 @@
 # 安装 DSH-SCNet
 
-DSH-SCNet（npm 包名：`dsh-scnet`） 是一个 DeepSeek Harness（DSH）bundle 插件，把国产超算集群使用规范打包成 skill 和 7 个工具。
+DSH-SCNet（npm 包名：`dsh-scnet`）是一个 DeepSeek Harness（DSH）bundle 插件，把
+SCNet 使用规范、SSH/Slurm 工具、OpenAPI 只读资源工具和 Notebook 资源工具打包到一起。
 
 ## 前置条件
 
@@ -71,3 +72,14 @@ DEEPSEEK_API_KEY: sk-你的key
 ```
 
 保存后无需重启，下一次请求即生效。Key 只保存在本机 `~/.dsh` 下，不会写入仓库。
+
+## 配置 SCNet OpenAPI
+
+SCNet OpenAPI 使用平台用户名、AccessKey 和 SecretKey：
+
+```sh
+python3 skills/scnet-hpc/scripts/scnet.py setup modify --mode openapi
+```
+
+macOS 可保存到 Keychain。Linux 安装 `libsecret-tools` 后使用 Secret Service；否则通过
+文档定义的 `SCNET_OPENAPI_*` 环境变量注入。OpenAPI 凭据不会写入插件仓库。

package/docs/testing.md

@@ -37,6 +37,14 @@ Confirm that the composed configuration includes:
 | `scnet_list_clusters` | Returns the packaged cluster identifiers |
 | `scnet_show_cluster` | Returns the selected profile contents |
 | `scnet_generate_job` | Writes a profile-aware Slurm script in the current directory |
+| `scnet_status` | Returns redacted local SCNet configuration |
+| `scnet_openapi_regions` | Returns authorized regions without tokens |
+| `scnet_job_queues` | Returns live regional Slurm queues |
+| `scnet_file_list` | Lists shared-storage files without modification |
+| `scnet_notebook_regions` | Lists Notebook-capable regions |
+| `scnet_notebook_resources` | Returns Notebook resource groups |
+| `scnet_notebook_list` | Lists redacted Notebook instances |
+| `scnet_notebook_show` | Returns one redacted Notebook instance |
 
 Check both accelerator and CPU-only job generation. Review the output for the selected partition, memory, and GRES rules.
 
@@ -52,6 +60,9 @@ 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.
 
+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`.
+
 ## Cleanup
 
 Remove the isolated test profile after verification:

package/docs/testing.zh-CN.md

@@ -58,5 +58,15 @@ DEEPSEEK_API_KEY: sk-你的key
 | 5 | 用 scnet_probe_cluster 探测集群 | 需要真实集群，会 SSH 到远端 | 中 |
 | 6 | 用 scnet_refresh_cluster dry_run=true 刷新规则 | 输出即将写入的缓存，不落盘 | 中（会 SSH） |
 | 7 | 用 scnet_run_compute_probe 跑计算节点探针 | 返回 PROBE_ 结果 | 高（提交作业并等待） |
+| 8 | 用 scnet_status 查看当前配置 | 返回脱敏配置 | 只读 |
+| 9 | 用 scnet_openapi_regions 查看授权区域 | 返回区域且不含 token | 只读 |
+| 10 | 用 scnet_job_queues 查看昆山队列 | 返回实时队列和空闲资源 | 只读 |
+| 11 | 用 scnet_file_list 查看默认目录 | 返回共享存储文件 | 只读 |
+| 12 | 用 scnet_notebook_regions 查看区域 | 返回 Notebook 可用区域 | 只读 |
+| 13 | 用 scnet_notebook_resources 查看昆山资源 | 返回 CPU/GPU/DCU 资源 | 只读 |
+| 14 | 用 scnet_notebook_list 查看实例 | 返回脱敏实例列表 | 只读 |
 
 第 4 至 7 步只有在你有私钥和目标集群时才测，测前确认副作用。
+
+Notebook 创建、启动、停止和释放没有作为 DSH deterministic tool 暴露。此类操作通过
+Skill CLI 执行，并先使用 `--dry-run`。

package/index.mjs

@@ -31,6 +31,35 @@ function runBash(script, args, timeoutMs = 120000, cwd = SKILL_DIR) {
   })
 }
 
+function runScnet(args, timeoutMs = 120000) {
+  return new Promise((resolve) => {
+    execFile(
+      'python3',
+      [join(SCRIPTS_DIR, 'scnet.py'), '--json', ...args],
+      { cwd: SKILL_DIR, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        const code = error ? (typeof error.code === 'number' ? error.code : 1) : 0
+        resolve({
+          ok: code === 0,
+          code,
+          stdout: String(stdout || ''),
+          stderr: String(stderr || ''),
+        })
+      },
+    )
+  })
+}
+
+function scnetResult(res, action) {
+  if (res.ok) return res.stdout.trim() || '{}'
+  return `${action}失败（exit ${res.code}）：\n${res.stderr.trim() || res.stdout.trim()}`
+}
+
+function regionArgs(region) {
+  const value = String(region || '').trim()
+  return value ? ['--region', value] : []
+}
+
 function textBlock(value) {
   return [{ type: 'text', text: value }]
 }
@@ -91,6 +120,161 @@ export function apply(ctx) {
     }),
   )
 
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_status',
+      description: '只读查看 scnet-hpc 当前默认 backend、SSH profile 和 OpenAPI 区域配置；不会连接远端或修改配置。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        return scnetResult(await runScnet(['config']), '读取 SCNet 配置')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_openapi_regions',
+      description: '通过已配置的 SCNet OpenAPI 凭据只读列出授权计算区域，不显示 token。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        return scnetResult(
+          await runScnet(['--backend', 'openapi', 'clusters']),
+          '查询 OpenAPI 区域',
+        )
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_job_queues',
+      description: '通过 OpenAPI 只读查询目标区域可访问的 Slurm 队列、空闲资源和单作业限制。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用已保存的默认区域' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        return scnetResult(
+          await runScnet(['--backend', 'openapi', ...regionArgs(args.region), 'queues']),
+          '查询作业队列',
+        )
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_file_list',
+      description: '通过 OpenAPI 只读列出区域共享存储中的文件和目录。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+        path: { type: 'string', description: '绝对目录路径；省略时使用区域用户主目录' },
+        limit: { type: 'number', description: '最多返回条数，默认 100' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const argv = ['--backend', 'openapi', ...regionArgs(args.region), 'files']
+        if (args.path) argv.push('--path', String(args.path))
+        if (args.limit) argv.push('--limit', String(args.limit))
+        return scnetResult(await runScnet(argv), '查询文件')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_regions',
+      description: '只读列出支持 SCNet Notebook 服务的授权区域。',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute() {
+        return scnetResult(
+          await runScnet(['--backend', 'openapi', 'notebook', 'regions']),
+          '查询 Notebook 区域',
+        )
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_resources',
+      description: '只读查询目标区域可用于 Notebook 的 CPU/GPU/DCU 资源及当前空闲卡数。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const argv = ['--backend', 'openapi', 'notebook', 'resources']
+        if (args.region) argv.push('--region', String(args.region))
+        return scnetResult(await runScnet(argv), '查询 Notebook 资源')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_list',
+      description: '只读列出目标区域的 Notebook 实例；密码和带凭据的 URL 默认脱敏。',
+      parameters: {
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+        status: { type: 'string', description: '可选状态过滤，如 Running、Terminated、Failed' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const argv = ['--backend', 'openapi', 'notebook', 'list']
+        if (args.region) argv.push('--region', String(args.region))
+        if (args.status) argv.push('--status', String(args.status))
+        return scnetResult(await runScnet(argv), '查询 Notebook 实例')
+      },
+    }),
+  )
+
+  ctx.tools.register(
+    defineTool({
+      name: 'scnet_notebook_show',
+      description: '只读查询一个 Notebook 实例详情；敏感字段默认脱敏。',
+      parameters: {
+        notebook_id: { type: 'string', required: true, description: 'Notebook 实例 ID' },
+        region: { type: 'string', description: '区域名称或 ID；省略时使用默认区域' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => textBlock(value),
+      },
+      async execute(args) {
+        const id = String(args.notebook_id || '').trim()
+        if (!id) return '缺少必填参数 notebook_id。'
+        const argv = ['--backend', 'openapi', 'notebook', 'show', id]
+        if (args.region) argv.push('--region', String(args.region))
+        return scnetResult(await runScnet(argv), '查询 Notebook 详情')
+      },
+    }),
+  )
+
   ctx.tools.register(
     defineTool({
       name: 'scnet_show_cluster',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-scnet",
-  "version": "0.4.1",
-  "description": "Community DeepSeek Harness bundle for SCNet HPC: profile-based SSH, CPU/DCU Slurm jobs, cluster probing, compute-node diagnostics, and Hygon DCU/DTK guidance.",
+  "version": "0.5.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",
   "exports": {
@@ -43,6 +43,8 @@
     "dsh-plugin",
     "dsh-bundle",
     "slurm",
+    "openapi",
+    "notebook",
     "hpc",
     "hygon",
     "dcu",