dsh-scnet 0.6.6 → 0.6.8

package/README.md

@@ -4,17 +4,15 @@
 
 DSH-SCNet (`dsh-scnet` on npm) is a community-maintained DSH bundle for operating Supercomputing Network (SCNet). It packages the source [`scnet-hpc`](https://github.com/lql341/scnet-hpc) Skill, profile-aware utilities, and bounded tools for SSH, Slurm, OpenAPI files, regional resources, and Notebook discovery.
 
-Current release: **0.6.6**
+Current release: **0.6.8**
 
 <!-- scnet-release:start -->
-## 0.6.6 highlights
-
-- README release highlights now come from one canonical source and replace the previous release
-  block instead of accumulating a version-by-version timeline.
-- The canonical Skill and Codex Plugin now create Git tags and GitHub Releases automatically after
-  validation.
-- The DSH distribution now publishes npm, its Git tag, and its GitHub Release automatically after
-  a synchronized version reaches `main`.
+## 0.6.8 highlights
+
+- The connector now exposes stable error codes and JSON-safe envelopes for authentication,
+  callback, network, scope, region, and platform failures.
+- OAuth callback sessions are one-shot and reject replay; platform keyring adapters have no
+  plaintext fallback.
 <!-- scnet-release:end -->
 
 > 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.

package/README_CN.md

@@ -4,15 +4,14 @@
 
 <p align="center">在 DeepSeek Harness 里操作超算互联网（SCNet）：配置 SSH、管理 Slurm 作业、查询 OpenAPI 区域和文件、检查 Notebook 资源与实例，并保留海光 DCU/DTK 诊断能力。</p>
 
-当前版本：**0.6.6**
+当前版本：**0.6.8**
 
 <!-- scnet-release:start -->
-## 0.6.6 更新
+## 0.6.8 更新
 
-- README 的版本亮点改为由 canonical 单一来源生成；每次发布替换当前版本区块，不再逐版
-  堆叠成流水账。
-- canonical Skill 和 Codex Plugin 在校验通过后自动创建 Git tag 与 GitHub Release。
-- DSH 分发仓库在同步版本进入 `main` 后，自动完成 npm 发布、Git tag 和 GitHub Release。
+- connector 现在提供稳定错误码和 JSON 安全错误信封，覆盖认证、回调、网络、权限、
+  区域和平台能力失败。
+- OAuth 回调会话只允许消费一次并拒绝重放；平台 keyring 适配器不提供明文回退。
 <!-- scnet-release:end -->
 
 > 本项目是独立维护的社区项目，与 DeepSeek Harness 兼容，但不是 DeepSeek 官方产品，也不表示 DeepSeek 对本项目提供背书、合作或授权。

package/connector/contract.mjs

@@ -0,0 +1,96 @@
+const OPERATION_DEFINITIONS = {
+  login: { scope: 'openid', mutatesRemote: false, supportsDryRun: false },
+  status: { scope: 'scnet.read', mutatesRemote: false, supportsDryRun: false },
+  refresh: { scope: 'openid', mutatesRemote: false, supportsDryRun: false },
+  logout: { scope: 'openid', mutatesRemote: true, supportsDryRun: false },
+  linkAccount: { scope: 'account.link', mutatesRemote: true, supportsDryRun: true },
+  unlinkAccount: { scope: 'account.link', mutatesRemote: true, supportsDryRun: true },
+  listRegions: { scope: 'scnet.read', mutatesRemote: false, supportsDryRun: false },
+  listSchedulers: { scope: 'scnet.read', mutatesRemote: false, supportsDryRun: false },
+  listQueues: { scope: 'scnet.read', mutatesRemote: false, supportsDryRun: false },
+  submitJob: { scope: 'jobs.submit', mutatesRemote: true, supportsDryRun: true },
+  getJob: { scope: 'jobs.read', mutatesRemote: false, supportsDryRun: false },
+  cancelJob: { scope: 'jobs.cancel', mutatesRemote: true, supportsDryRun: true },
+  listFiles: { scope: 'files.read', mutatesRemote: false, supportsDryRun: false },
+  transferFile: { scope: 'files.write', mutatesRemote: true, supportsDryRun: true },
+}
+
+export const SCNET_CONNECTOR_CONTRACT_VERSION = '0.1.0'
+export const CONNECTOR_OPERATION_DEFINITIONS = Object.freeze(
+  Object.fromEntries(
+    Object.entries(OPERATION_DEFINITIONS).map(([name, definition]) => [name, Object.freeze({ ...definition })]),
+  ),
+)
+export const CONNECTOR_CAPABILITY_STATES = Object.freeze([
+  'supported',
+  'unsupported',
+  'requires-remote-host',
+])
+
+function nonEmptyString(value, label) {
+  const normalized = String(value ?? '').trim()
+  if (!normalized) throw new TypeError(`${label} must be a non-empty string`)
+  return normalized
+}
+
+function normalizeState(value, operation) {
+  const state = nonEmptyString(value, `capability ${operation}`)
+  if (!CONNECTOR_CAPABILITY_STATES.includes(state)) {
+    throw new TypeError(
+      `capability ${operation} must be one of ${CONNECTOR_CAPABILITY_STATES.join(', ')}`,
+    )
+  }
+  return state
+}
+
+export function createCapabilityMatrix(entries = {}) {
+  if (entries === null || typeof entries !== 'object' || Array.isArray(entries)) {
+    throw new TypeError('capabilities must be an object')
+  }
+  return Object.freeze(
+    Object.fromEntries(
+      Object.keys(OPERATION_DEFINITIONS).map((operation) => [
+        operation,
+        normalizeState(entries[operation] ?? 'unsupported', operation),
+      ]),
+    ),
+  )
+}
+
+export function createConnectorDescriptor({
+  id = 'scnet',
+  version = SCNET_CONNECTOR_CONTRACT_VERSION,
+  issuer,
+  capabilities = {},
+} = {}) {
+  const descriptor = {
+    contractVersion: SCNET_CONNECTOR_CONTRACT_VERSION,
+    id: nonEmptyString(id, 'connector id'),
+    version: nonEmptyString(version, 'connector version'),
+    issuer: nonEmptyString(issuer, 'issuer'),
+    capabilities: createCapabilityMatrix(capabilities),
+  }
+  return Object.freeze(descriptor)
+}
+
+export function getOperationDefinition(operation) {
+  const name = nonEmptyString(operation, 'operation')
+  const definition = CONNECTOR_OPERATION_DEFINITIONS[name]
+  if (!definition) throw new RangeError(`unsupported connector operation: ${name}`)
+  return definition
+}
+
+export function assertCapability(descriptor, operation, { allowRemoteHost = false } = {}) {
+  if (!descriptor || typeof descriptor !== 'object') {
+    throw new TypeError('connector descriptor is required')
+  }
+  const definition = getOperationDefinition(operation)
+  const state = descriptor.capabilities?.[operation]
+  if (state === 'supported' || (state === 'requires-remote-host' && allowRemoteHost)) {
+    return definition
+  }
+  if (state === 'requires-remote-host') {
+    throw new Error(`${operation} requires a remote host`)
+  }
+  throw new Error(`${operation} is not supported by connector ${descriptor.id || 'unknown'}`)
+}

package/connector/credentials.mjs

@@ -0,0 +1,42 @@
+function requiredString(value, label) {
+  const normalized = String(value ?? '').trim()
+  if (!normalized) throw new TypeError(`${label} must be a non-empty string`)
+  return normalized
+}
+
+function assertBackend(backend) {
+  if (!backend || typeof backend !== 'object') {
+    throw new TypeError('credential backend is required')
+  }
+  for (const method of ['get', 'set', 'delete']) {
+    if (typeof backend[method] !== 'function') {
+      throw new TypeError(`credential backend must implement ${method}()`)
+    }
+  }
+  return backend
+}
+
+/**
+ * Adapt a platform keyring implementation without providing a plaintext fallback.
+ * The backend owns encryption, locking, and OS-specific Secret Service behavior.
+ */
+export function createCredentialStoreAdapter({ backend, namespace = 'scnet' } = {}) {
+  const store = assertBackend(backend)
+  const prefix = requiredString(namespace, 'credential namespace')
+  const keyOf = (key) => `${prefix}.${requiredString(key, 'credential key')}`
+  return Object.freeze({
+    async get(key) {
+      return store.get(keyOf(key))
+    },
+    async set(key, value) {
+      if (value === undefined) throw new TypeError('credential value must not be undefined')
+      return store.set(keyOf(key), structuredClone(value))
+    },
+    async delete(key) {
+      return store.delete(keyOf(key))
+    },
+    async clear() {
+      if (typeof store.clear === 'function') return store.clear(prefix)
+    },
+  })
+}

package/connector/errors.mjs

@@ -0,0 +1,58 @@
+const ERROR_CODES = [
+  'AUTHENTICATION_REQUIRED',
+  'AUTHENTICATION_FAILED',
+  'SCOPE_INSUFFICIENT',
+  'NETWORK_TIMEOUT',
+  'REGION_UNAVAILABLE',
+  'PLATFORM_UNSUPPORTED',
+  'CALLBACK_REPLAY',
+  'CALLBACK_MISMATCH',
+  'CONFIGURATION_REQUIRED',
+  'INTERNAL_ERROR',
+]
+
+export const CONNECTOR_ERROR_CODES = Object.freeze(ERROR_CODES)
+
+function requiredString(value, label) {
+  const normalized = String(value ?? '').trim()
+  if (!normalized) throw new TypeError(`${label} must be a non-empty string`)
+  return normalized
+}
+
+export class ConnectorError extends Error {
+  constructor(code, message, { operation, retryable = false } = {}) {
+    if (!CONNECTOR_ERROR_CODES.includes(code)) {
+      throw new RangeError(`unsupported connector error code: ${code}`)
+    }
+    super(requiredString(message, 'error message'))
+    this.name = 'ConnectorError'
+    this.code = code
+    this.operation = operation === undefined ? undefined : requiredString(operation, 'operation')
+    this.retryable = Boolean(retryable)
+  }
+
+  toJSON() {
+    return {
+      ok: false,
+      error_code: this.code,
+      error: this.message,
+      ...(this.operation ? { operation: this.operation } : {}),
+      retryable: this.retryable,
+    }
+  }
+}
+
+export function connectorError(code, message, options) {
+  return new ConnectorError(code, message, options)
+}
+
+export function errorEnvelope(error, { operation } = {}) {
+  if (error instanceof ConnectorError) {
+    return error.toJSON()
+  }
+  return new ConnectorError(
+    'INTERNAL_ERROR',
+    error instanceof Error ? error.message : String(error || 'unknown connector error'),
+    { operation },
+  ).toJSON()
+}

package/connector/index.mjs

@@ -0,0 +1,33 @@
+export {
+  CONNECTOR_CAPABILITY_STATES,
+  CONNECTOR_OPERATION_DEFINITIONS,
+  SCNET_CONNECTOR_CONTRACT_VERSION,
+  assertCapability,
+  createCapabilityMatrix,
+  createConnectorDescriptor,
+  getOperationDefinition,
+} from './contract.mjs'
+
+export {
+  CONNECTOR_ERROR_CODES,
+  ConnectorError,
+  connectorError,
+  errorEnvelope,
+} from './errors.mjs'
+
+export {
+  createCredentialStoreAdapter,
+} from './credentials.mjs'
+
+export {
+  MemoryCredentialStore,
+  TokenLifecycle,
+  createAuthorizationRequest,
+  createAuthorizationSession,
+  createCodeVerifier,
+  createPkceChallenge,
+  createRefreshTokenRequest,
+  createTokenExchangeRequest,
+  normalizeTokenResponse,
+  validateAuthorizationCallback,
+} from './oauth2.mjs'

package/connector/oauth2.mjs

@@ -0,0 +1,291 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import { ConnectorError } from './errors.mjs'
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '[::1]', 'localhost'])
+
+function requiredString(value, label) {
+  const normalized = String(value ?? '').trim()
+  if (!normalized) throw new TypeError(`${label} must be a non-empty string`)
+  return normalized
+}
+
+function parseUrl(value, label) {
+  let parsed
+  try {
+    parsed = new URL(requiredString(value, label))
+  } catch {
+    throw new TypeError(`${label} must be a valid URL`)
+  }
+  return parsed
+}
+
+function assertHttpsEndpoint(value, label) {
+  const parsed = parseUrl(value, label)
+  if (parsed.protocol !== 'https:') {
+    throw new TypeError(`${label} must use https`)
+  }
+  return parsed
+}
+
+function assertRedirectUri(value) {
+  const parsed = parseUrl(value, 'redirectUri')
+  const isLoopback = parsed.protocol === 'http:' && LOOPBACK_HOSTS.has(parsed.hostname)
+  if (parsed.protocol !== 'https:' && !isLoopback) {
+    throw new TypeError('redirectUri must use https or a loopback http address')
+  }
+  return parsed
+}
+
+function base64url(value) {
+  return Buffer.from(value).toString('base64url')
+}
+
+export function createCodeVerifier() {
+  return base64url(randomBytes(32))
+}
+
+export function createPkceChallenge(codeVerifier) {
+  const verifier = requiredString(codeVerifier, 'codeVerifier')
+  return base64url(createHash('sha256').update(verifier).digest())
+}
+
+export function createAuthorizationRequest({
+  authorizationEndpoint,
+  clientId,
+  redirectUri,
+  issuer,
+  scope = [],
+  state = randomUUID(),
+  nonce = randomUUID(),
+  codeVerifier = createCodeVerifier(),
+} = {}) {
+  const endpoint = assertHttpsEndpoint(authorizationEndpoint, 'authorizationEndpoint')
+  const redirect = assertRedirectUri(redirectUri)
+  const client = requiredString(clientId, 'clientId')
+  const normalizedIssuer = issuer === undefined ? undefined : assertHttpsEndpoint(issuer, 'issuer').origin
+  const scopes = Array.isArray(scope) ? scope : String(scope).split(/\s+/)
+  const normalizedScopes = [...new Set(scopes.map((item) => String(item).trim()).filter(Boolean))]
+  if (normalizedScopes.length === 0) throw new TypeError('scope must contain at least one value')
+
+  const params = new URLSearchParams({
+    client_id: client,
+    redirect_uri: redirect.href,
+    response_type: 'code',
+    scope: normalizedScopes.join(' '),
+    code_challenge: createPkceChallenge(codeVerifier),
+    code_challenge_method: 'S256',
+    state: requiredString(state, 'state'),
+    nonce: requiredString(nonce, 'nonce'),
+  })
+  return Object.freeze({
+    url: `${endpoint.href}${endpoint.search ? '&' : '?'}${params}`,
+    authorizationEndpoint: endpoint.href,
+    clientId: client,
+    redirectUri: redirect.href,
+    issuer: normalizedIssuer,
+    scope: Object.freeze(normalizedScopes),
+    state,
+    nonce,
+    codeVerifier,
+  })
+}
+
+function assertExactRedirect(callbackUrl, redirectUri) {
+  const actual = parseUrl(callbackUrl, 'callbackUrl')
+  const expected = assertRedirectUri(redirectUri)
+  if (actual.origin !== expected.origin || actual.pathname !== expected.pathname) {
+    throw new Error('OAuth callback redirect URI does not match the request')
+  }
+  if (actual.port !== expected.port || actual.hash !== expected.hash) {
+    throw new Error('OAuth callback redirect URI does not match the request')
+  }
+  for (const [key, value] of expected.searchParams) {
+    if (actual.searchParams.get(key) !== value) {
+      throw new Error('OAuth callback redirect URI does not match the request')
+    }
+  }
+  return actual
+}
+
+export function validateAuthorizationCallback(callbackUrl, request) {
+  const callback = assertExactRedirect(callbackUrl, request.redirectUri)
+  const returnedState = callback.searchParams.get('state')
+  if (returnedState !== request.state) throw new Error('OAuth state mismatch')
+
+  const error = callback.searchParams.get('error')
+  if (error) {
+    const description = callback.searchParams.get('error_description')
+    throw new Error(`OAuth authorization failed: ${error}${description ? ` (${description})` : ''}`)
+  }
+
+  const code = callback.searchParams.get('code')
+  if (!code) throw new Error('OAuth callback did not contain an authorization code')
+  if (request.issuer !== undefined) {
+    const returnedIssuer = callback.searchParams.get('iss')
+    if (returnedIssuer !== request.issuer) throw new Error('OAuth issuer mismatch')
+  }
+  return Object.freeze({
+    code,
+    state: returnedState,
+    issuer: callback.searchParams.get('iss') || undefined,
+  })
+}
+
+export function createAuthorizationSession(options = {}) {
+  const request = createAuthorizationRequest(options)
+  let consumed = false
+  return Object.freeze({
+    request,
+    get consumed() {
+      return consumed
+    },
+    consumeCallback(callbackUrl) {
+      if (consumed) {
+        throw new ConnectorError(
+          'CALLBACK_REPLAY',
+          'OAuth authorization callback has already been consumed',
+          { operation: 'login' },
+        )
+      }
+      consumed = true
+      try {
+        return validateAuthorizationCallback(callbackUrl, request)
+      } catch (error) {
+        if (error instanceof ConnectorError) throw error
+        throw new ConnectorError('CALLBACK_MISMATCH', error.message, { operation: 'login' })
+      }
+    },
+  })
+}
+
+export function createTokenExchangeRequest({
+  tokenEndpoint,
+  clientId,
+  code,
+  redirectUri,
+  codeVerifier,
+}) {
+  const endpoint = assertHttpsEndpoint(tokenEndpoint, 'tokenEndpoint')
+  const redirect = assertRedirectUri(redirectUri)
+  const params = new URLSearchParams({
+    grant_type: 'authorization_code',
+    client_id: requiredString(clientId, 'clientId'),
+    code: requiredString(code, 'code'),
+    redirect_uri: redirect.href,
+    code_verifier: requiredString(codeVerifier, 'codeVerifier'),
+  })
+  return Object.freeze({
+    method: 'POST',
+    url: endpoint.href,
+    headers: Object.freeze({ 'content-type': 'application/x-www-form-urlencoded' }),
+    body: params.toString(),
+  })
+}
+
+export function createRefreshTokenRequest({ tokenEndpoint, clientId, refreshToken, scope } = {}) {
+  const endpoint = assertHttpsEndpoint(tokenEndpoint, 'tokenEndpoint')
+  const params = new URLSearchParams({
+    grant_type: 'refresh_token',
+    client_id: requiredString(clientId, 'clientId'),
+    refresh_token: requiredString(refreshToken, 'refreshToken'),
+  })
+  if (scope !== undefined) params.set('scope', requiredString(scope, 'scope'))
+  return Object.freeze({
+    method: 'POST',
+    url: endpoint.href,
+    headers: Object.freeze({ 'content-type': 'application/x-www-form-urlencoded' }),
+    body: params.toString(),
+  })
+}
+
+export function normalizeTokenResponse(response, now = Date.now()) {
+  if (!response || typeof response !== 'object') throw new TypeError('token response must be an object')
+  const accessToken = requiredString(response.access_token, 'access_token')
+  const refreshToken = response.refresh_token === undefined ? undefined : requiredString(response.refresh_token, 'refresh_token')
+  const tokenType = String(response.token_type || 'Bearer')
+  const expiresIn = Number(response.expires_in)
+  if (!Number.isFinite(expiresIn) || expiresIn <= 0) throw new TypeError('expires_in must be a positive number')
+  return Object.freeze({
+    accessToken,
+    refreshToken,
+    tokenType,
+    scope: response.scope ? String(response.scope) : undefined,
+    expiresAt: now + expiresIn * 1000,
+  })
+}
+
+export class MemoryCredentialStore {
+  #values = new Map()
+
+  async get(key) {
+    return this.#values.get(requiredString(key, 'credential key'))
+  }
+
+  async set(key, value) {
+    const normalizedKey = requiredString(key, 'credential key')
+    if (value === undefined) throw new TypeError('credential value must not be undefined')
+    this.#values.set(normalizedKey, structuredClone(value))
+  }
+
+  async delete(key) {
+    this.#values.delete(requiredString(key, 'credential key'))
+  }
+
+  async clear() {
+    this.#values.clear()
+  }
+}
+
+export class TokenLifecycle {
+  #store
+  #key
+  #now
+  #refreshPromise
+
+  constructor({ store = new MemoryCredentialStore(), key = 'scnet.tokens', now = () => Date.now() } = {}) {
+    this.#store = store
+    this.#key = requiredString(key, 'token key')
+    this.#now = now
+  }
+
+  async save(tokenResponse) {
+    const token = normalizeTokenResponse(tokenResponse, this.#now())
+    await this.#store.set(this.#key, token)
+    return this.status()
+  }
+
+  async status() {
+    const token = await this.#store.get(this.#key)
+    if (!token) return { authenticated: false, expiresAt: undefined }
+    return {
+      authenticated: true,
+      expiresAt: token.expiresAt,
+      hasRefreshToken: Boolean(token.refreshToken),
+      scope: token.scope,
+    }
+  }
+
+  async accessToken({ refresh } = {}) {
+    const token = await this.#store.get(this.#key)
+    if (!token) throw new Error('SCNet authentication required')
+    if (token.expiresAt > this.#now() + 30000) return token.accessToken
+    if (typeof refresh !== 'function' || !token.refreshToken) {
+      throw new Error('SCNet access token expired; re-authentication required')
+    }
+    if (!this.#refreshPromise) {
+      this.#refreshPromise = Promise.resolve()
+        .then(() => refresh(token.refreshToken))
+        .then((response) => this.save(response))
+        .finally(() => {
+          this.#refreshPromise = undefined
+        })
+    }
+    await this.#refreshPromise
+    const refreshed = await this.#store.get(this.#key)
+    return refreshed.accessToken
+  }
+
+  async clear() {
+    await this.#store.delete(this.#key)
+  }
+}

package/index.mjs

@@ -12,6 +12,11 @@ const SKILL_DIR = join(__dirname, 'skills', 'scnet-hpc')
 const SCRIPTS_DIR = join(SKILL_DIR, 'scripts')
 const CLUSTERS_DIR = join(SKILL_DIR, 'clusters')
 
+export function resolvePythonCandidates(env = process.env) {
+  const configured = String(env.DSH_SCNET_PYTHON ?? env.SCNET_PYTHON ?? '').trim()
+  return configured ? [configured] : ['python3', 'python']
+}
+
 function runBash(script, args, timeoutMs = 120000, cwd = SKILL_DIR) {
   return new Promise((resolve) => {
     execFile(
@@ -32,21 +37,35 @@ function runBash(script, args, timeoutMs = 120000, cwd = SKILL_DIR) {
 }
 
 function runScnet(args, timeoutMs = 120000) {
+  const candidates = resolvePythonCandidates()
+  const scriptArgs = [join(SCRIPTS_DIR, 'scnet.py'), '--json', ...args]
+
   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 || ''),
-        })
-      },
-    )
+    const attempt = (index) => {
+      const executable = candidates[index]
+      execFile(
+        executable,
+        scriptArgs,
+        { cwd: SKILL_DIR, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
+        (error, stdout, stderr) => {
+          if (error?.code === 'ENOENT' && index + 1 < candidates.length) {
+            attempt(index + 1)
+            return
+          }
+          const code = error ? (typeof error.code === 'number' ? error.code : 1) : 0
+          resolve({
+            ok: code === 0,
+            code,
+            executable,
+            stdout: String(stdout || ''),
+            stderr: error?.code === 'ENOENT'
+              ? `无法启动 Python 解释器 ${executable}；请设置 DSH_SCNET_PYTHON 或 SCNET_PYTHON 指向 Python 3。`
+              : String(stderr || ''),
+          })
+        },
+      )
+    }
+    attempt(0)
   })
 }
 
@@ -1173,5 +1192,6 @@ export const __testables = {
   parseWalltimeSeconds,
   pickBackend,
   queueCandidates,
+  resolvePythonCandidates,
   translateScnetError,
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "dsh-scnet",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "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": {
     ".": "./index.mjs",
+    "./connector": "./connector/index.mjs",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
@@ -26,8 +27,11 @@
   },
   "files": [
     "index.mjs",
+    "connector",
     "cordis.patch.yml",
     "skills",
+    "!skills/**/__pycache__",
+    "!skills/**/*.pyc",
     "docs",
     "README_CN.md",
     "README.md",

package/skills/scnet-hpc/VERSION

@@ -1 +1 @@
-0.6.6
+0.6.8

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

@@ -50,6 +50,20 @@ ssh <集群> 'module avail 2>&1'
 
 ## Python 环境
 
+### 本地脚本解释器
+
+Linux Desktop 可将随包 Python 的绝对路径注入本地脚本：
+
+```bash
+export DSH_SCNET_PYTHON=/path/to/bundled/python
+# 通用环境也可使用：
+export SCNET_PYTHON=/path/to/python3
+```
+
+`DSH_SCNET_PYTHON` 优先于 `SCNET_PYTHON`。脚本会验证解释器确实是 Python 3；
+未注入时才按 `python3`、`python` 顺序探测。该设置只影响本机的 OpenAPI CLI 和作业
+脚本生成，不会把本机解释器路径传到远端计算节点。
+
 超算通常没有系统级的 torch，用 venv 或 conda env。profile 的 `DEFAULT_VENV`
 记录默认环境路径（相对家目录）。
 

package/skills/scnet-hpc/scripts/_common.sh

@@ -12,6 +12,37 @@ CLUSTER_DIR="$REPO_ROOT/clusters"
 die() { printf '错误: %s\n' "$1" >&2; exit 1; }
 info() { printf '  %s\n' "$1"; }
 
+# Resolve the local Python 3 interpreter without assuming that every desktop
+# distribution exposes the command as `python3`. Desktop hosts may inject an
+# absolute path through DSH_SCNET_PYTHON; SCNET_PYTHON is the portable alias.
+resolve_python() {
+    local configured="${DSH_SCNET_PYTHON:-${SCNET_PYTHON:-}}"
+    local candidate resolved
+
+    if [ -n "$configured" ]; then
+        if [ -x "$configured" ]; then
+            resolved="$configured"
+        else
+            resolved="$(command -v "$configured" 2>/dev/null || true)"
+        fi
+        [ -n "$resolved" ] || return 1
+        "$resolved" -c 'import sys; raise SystemExit(0 if sys.version_info.major == 3 else 1)' \
+            >/dev/null 2>&1 || return 1
+        printf '%s\n' "$resolved"
+        return 0
+    fi
+
+    for candidate in python3 python; do
+        resolved="$(command -v "$candidate" 2>/dev/null || true)"
+        [ -n "$resolved" ] || continue
+        "$resolved" -c 'import sys; raise SystemExit(0 if sys.version_info.major == 3 else 1)' \
+            >/dev/null 2>&1 || continue
+        printf '%s\n' "$resolved"
+        return 0
+    done
+    return 1
+}
+
 list_clusters() {
     find "$CLUSTER_DIR" -maxdepth 1 -name '*.conf' ! -name '_*' -exec basename {} .conf \; 2>/dev/null | sort
 }

package/skills/scnet-hpc/scripts/new-job.sh

@@ -132,6 +132,7 @@ fi
 
 OUT="${NAME}.slurm"
 [ -e "$OUT" ] && die "$OUT 已存在"
+PYTHON_BIN="$(resolve_python)" || die "本机需要 Python 3；请设置 DSH_SCNET_PYTHON 或 SCNET_PYTHON"
 
 cat > "$OUT" <<EOF
 #!/bin/bash -l

package/skills/scnet-hpc/scripts/setup.sh

@@ -370,8 +370,8 @@ if [ -z "$ACTION" ]; then
 fi
 
 if [ "$ACTION" = status ] || [ "$ACTION" = reset ]; then
-    if command -v python3 >/dev/null 2>&1; then
-        exec python3 "$SCRIPT_DIR/scnet.py" setup "$ACTION"
+    if PYTHON_BIN="$(resolve_python)"; then
+        exec "$PYTHON_BIN" "$SCRIPT_DIR/scnet.py" setup "$ACTION"
     fi
     [ "$ACTION" = status ] || die "reset 需要 Python 3 以执行安全的分范围重置"
     config_root="${XDG_CONFIG_HOME:-$HOME/.config}/scnet-hpc"
@@ -450,16 +450,16 @@ if [ "$BACKEND" = ssh ] || [ "$BACKEND" = both ]; then
 fi
 
 if [ "$BACKEND" = openapi ] || [ "$BACKEND" = both ]; then
-    if command -v python3 >/dev/null 2>&1; then
+    if PYTHON_BIN="$(resolve_python)"; then
         printf '%s\n' \
             "OpenAPI 使用一组平台 AK/SK 自动发现全部授权区域。" >&2
         openapi_args=(setup "$ACTION" --mode openapi)
         [ "$SKIP_CONNECT" = yes ] && openapi_args+=(--skip-connect)
-        python3 "$SCRIPT_DIR/scnet.py" "${openapi_args[@]}"
+        "$PYTHON_BIN" "$SCRIPT_DIR/scnet.py" "${openapi_args[@]}"
     else
         printf '%s\n' \
             "OpenAPI backend 需要 Python 3；SSH 配置不受影响。" \
-            "安装 Python 3 后运行：python3 scripts/scnet.py setup --mode openapi" >&2
+            "请设置 DSH_SCNET_PYTHON 或 SCNET_PYTHON 指向 Python 3，或安装 python3。" >&2
     fi
 fi