@whyshu/ba 0.1.0 → 0.1.1

package/README.md

@@ -31,6 +31,15 @@ install_bundle target = /Users/Chester/Whyshu/whyshu-ba
 
 安装后左侧栏出现图标；点击进入面板。首次打开若未配置 Key，会显示配置引导。
 
+## dsh 兼容范围（双层门禁）
+
+支持 `dsh >=0.2.0-0 <0.3.0-0`（`package.json#engines.dsh`，含 0.2.x 的 rc 预发布）。
+
+1. **宿主侧**：dsh 在导入插件代码前校验 `engines.dsh`；不匹配的 bundle 会被 skip（宿主与客户端 bundle 都不会挂载），只在 stderr 打一行原因，不阻断 `dsh web` 启动。
+2. **插件侧（兜底）**：`apply()` 顶部再自行评估版本；未适配时只打一行
+   `[@whyshu/ba] 插件已自我禁用（dsh x.y.z 未适配）` 后 `return`，**不注册任何宿主 API、不抛**。
+   排障可用环境变量 `WHYSHU_BA_DSH_VERSION` 显式指定宿主版本。
+
 ## 配置 API Key
 
 1. 币安 → 账户 → **API 管理** → 新建 API，权限只勾 **「启用读取」**（务必禁用提现、交易）。

package/dist/client.js

@@ -513,33 +513,44 @@ window.__ModuleLoader__.load({
     const name = 'whyshu-ba-client'
     const inject = ['slots', 'locale']
 
-    function apply(ctx) {
+    /** 安全执行一次注册：任何异常只记日志，绝不让客户端 apply 抛出（抛了会空白槽位/页面）。 */
+    function safe(label, fn) {
       try {
-        ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'whyshu-ba: dictionaries')
+        return fn()
       } catch (e) {
-        console.warn('[whyshu-ba] 语言字典注册失败:', (e && e.message) || e)
+        try {
+          console.warn('[whyshu-ba] ' + label + ' 失败（已忽略，不影响 dsh 页面）:', (e && e.message) || e)
+        } catch { /* 日志本身失败也不能抛 */ }
+        return undefined
       }
-      const t = ctx.locale.bind(NS)
-      injectCss()
-      // 自检信标：宿主 /health 会回报 clientPingAt ⇒ 能区分"bundle 没加载"与"加载了但没显示"
-      try { fetch(API + '/ping?from=client').catch(() => {}) } catch { /* noop */ }
+    }
 
-      // ⛔ 永不抛出：注册失败只影响这个面板，不能让 web boot 报 "entry did not activate"
+    function apply(ctx) {
+      // 整体 try/catch：客户端 apply 抛异常会让整个页面/槽位崩溃。
       try {
-        ctx.slots.inject('main', () => ctx.slots.register({
+        safe('语言字典', () => ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'whyshu-ba: dictionaries'))
+        const t = safe('locale.bind', () => ctx.locale.bind(NS)) || ((key) => key)
+        safe('样式注入', injectCss)
+        // 自检信标：宿主 /health 会回报 clientPingAt ⇒ 能区分"bundle 没加载"与"加载了但没显示"
+        safe('ping', () => { fetch(API + '/ping?from=client').catch(() => {}) })
+
+        // ⛔ 永不抛出：注册失败只影响这个面板，不能让 web boot 报 "entry did not activate"
+        safe('main 面板', () => ctx.slots.inject('main', () => ctx.slots.register({
           name: 'main',
           key: PANEL_ID,
           locale: NS,
-        }, BinancePanelSafe))
-        ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
+        }, BinancePanelSafe)))
+        safe('侧栏入口', () => ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
           name: 'sidebar.panellist',
           id: PANEL_ID,
           order: 20,
           locale: NS,
           label: () => t('panel'),
-        }, BinanceIcon))
+        }, BinanceIcon)))
       } catch (e) {
-        console.warn('[whyshu-ba] 面板注册失败（不影响 dsh）:', (e && e.message) || e)
+        try {
+          console.warn('[whyshu-ba] 客户端 apply 异常已忽略（不影响 dsh 页面）:', (e && e.message) || e)
+        } catch { /* noop */ }
       }
     }
 

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@whyshu/ba",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "DSH 左侧栏币安面板：主视图展示现货资产、合约持仓与行情看板（只读，API Key 仅宿主侧）",
+  "type": "module",
   "license": "MIT",
   "engines": {
-    "node": ">=24.2.0"
+    "node": ">=24.2.0",
+    "dsh": ">=0.2.0-0 <0.3.0-0"
   },
   "keywords": [
     "dsh",
@@ -30,6 +32,9 @@
     "cordis.patch.yml",
     "README.md"
   ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/compat.mjs

@@ -0,0 +1,305 @@
+/**
+ * dsh 宿主兼容闸（@whyshu/ba）
+ *
+ * 目标：**dsh 升级到未适配版本时，插件自己降级/关闭，但绝不能让 dsh web 启动失败或卡住。**
+ *
+ * 双层防线（本文件是第二层，第一层在 package.json#engines.dsh）：
+ *   ① **宿主侧（首选）**：`package.json#engines.dsh` 声明支持范围。dsh（0.2.x 起）在**导入插件代码之前**
+ *      用 `evaluatePluginCompatibility()` 检查 manifest：不匹配的 bundle 被 skip、不匹配的 entry 被
+ *      disable，只在 stderr 打一行原因，**不阻断 boot**。
+ *      ⇒ 宿主升级到未适配版本时，插件（含其客户端 bundle）根本不会被挂载。
+ *   ② **插件侧（本文件，兜底）**：宿主不认 manifest 门禁（更老版本 / 手工 patch 挂载 / 已授豁免）时，
+ *      `apply()` 顶部自行评估版本：不支持 ⇒ 只打一条明确日志后 return，**不注册任何宿主 API**。
+ *
+ * 纯函数边界：本文件**不 import 任何宿主模块**（`@deepseek-ai/*`、`cordis`、`dsh-*`）；
+ * 只用 node 内置模块（fs/module/path/url）做只读探测，且所有解析失败都返回 null、绝不抛。
+ *
+ * ⚠️ 范围语义与 dsh 自己的门禁保持一致：dsh 用
+ * `semver.satisfies(runtimeVersion, range, { includePrerelease: true })`。dsh 日常发 rc 预发布，
+ * 所以下界写 `0.2.0-0` 才能把 `0.2.0-rc.2` 算进来；上界 `0.3.0-0` 把 0.3.0 的所有预发布也挡在外面。
+ */
+import { readFileSync, realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** 支持范围（唯一真源；package.json#engines.dsh 必须与它逐字一致，有用例守着）。 */
+export const SUPPORTED_DSH_RANGE = '>=0.2.0-0 <0.3.0-0'
+/** 下界（含）。`-0` 是"该版本线最早的预发布"哨兵，不是笔误。 */
+export const SUPPORTED_DSH_MIN = '0.2.0-0'
+/** 上界（不含）。`-0` 让 0.3.0-rc.x 也算"高于上界" ⇒ 未适配。 */
+export const SUPPORTED_DSH_MAX = '0.3.0-0'
+
+/** 可显式覆盖版本探测的环境变量（排障/离线验证/宿主未暴露版本时用；顺序即优先级）。 */
+export const DSH_VERSION_ENV_KEYS = ['WHYSHU_BA_DSH_VERSION', 'DSH_VERSION']
+
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+const NUMERIC_RE = /^\d+$/
+
+/**
+ * 解析 dsh 版本号（semver；允许 `v` 前缀与 `+build` 元数据）。
+ * @param {unknown} value
+ * @returns {{raw:string, version:string, major:number, minor:number, patch:number, prerelease:string[]}|null}
+ *   解析不了返回 null（**绝不抛** —— 未知版本必须走"降级"而不是炸 boot）。
+ */
+export function parseDshVersion(value) {
+  if (typeof value !== 'string') return null
+  const raw = value.trim()
+  if (!raw) return null
+  const m = SEMVER_RE.exec(raw)
+  if (!m) return null
+  const major = Number(m[1])
+  const minor = Number(m[2])
+  const patch = Number(m[3])
+  if (![major, minor, patch].every(Number.isSafeInteger)) return null
+  const prerelease = m[4] ? m[4].split('.') : []
+  return {
+    raw,
+    version: `${major}.${minor}.${patch}${m[4] ? `-${m[4]}` : ''}`,
+    major,
+    minor,
+    patch,
+    prerelease,
+  }
+}
+
+/** semver 预发布段比较（数字段 < 非数字段；数字按数值比；前缀短的小）。 */
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0
+  if (a.length === 0) return 1   // 正式版 > 预发布
+  if (b.length === 0) return -1
+  const n = Math.max(a.length, b.length)
+  for (let i = 0; i < n; i += 1) {
+    if (i >= a.length) return -1
+    if (i >= b.length) return 1
+    const x = a[i]
+    const y = b[i]
+    const xn = NUMERIC_RE.test(x)
+    const yn = NUMERIC_RE.test(y)
+    if (xn && yn) {
+      const d = Number(x) - Number(y)
+      if (d !== 0) return d < 0 ? -1 : 1
+      continue
+    }
+    if (xn) return -1
+    if (yn) return 1
+    if (x !== y) return x < y ? -1 : 1
+  }
+  return 0
+}
+
+/** 两个已解析版本的 semver 优先级比较（build 元数据不参与）。 */
+function compareParsed(a, b) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1
+  }
+  return comparePrerelease(a.prerelease, b.prerelease)
+}
+
+/**
+ * semver 优先级比较（导出给用例/排障用）。
+ * @returns {number|null} -1 / 0 / 1；任一侧无法解析返回 null（不抛）
+ */
+export function compareDshVersions(a, b) {
+  const x = parseDshVersion(a)
+  const y = parseDshVersion(b)
+  if (!x || !y) return null
+  return compareParsed(x, y)
+}
+
+const MIN_BOUND = parseDshVersion(SUPPORTED_DSH_MIN)
+const MAX_BOUND = parseDshVersion(SUPPORTED_DSH_MAX)
+
+/** 版本是否落在支持范围内（等价于 `evaluateCompatibility(version).supported`）。 */
+export function isVersionSupported(version) {
+  const parsed = parseDshVersion(typeof version === 'string' ? version : '')
+  if (!parsed) return false
+  return compareParsed(parsed, MIN_BOUND) >= 0 && compareParsed(parsed, MAX_BOUND) < 0
+}
+
+/** 日志里的版本串截断（防御超长 env 值刷屏）。 */
+const show = (v) => {
+  const s = String(v == null ? '' : v).trim()
+  return s.length > 40 ? `${s.slice(0, 39)}…` : s
+}
+
+/**
+ * 评估宿主兼容性。**永不抛**：任何拿不准的情况都按 `supported:false`（降级）处理。
+ * @param {unknown} version dsh 版本号；null/''/无法解析 = 未知 = 不支持
+ * @returns {{supported:boolean, version:string|null, range:string, severity:'ok'|'warn', reason?:string}}
+ */
+export function evaluateCompatibility(version) {
+  const input = version == null ? '' : String(version).trim()
+  if (!input) {
+    return {
+      supported: false,
+      version: null,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: '未能识别 dsh 版本（视为未适配，插件自动禁用）',
+    }
+  }
+  const parsed = parseDshVersion(input)
+  if (!parsed) {
+    return {
+      supported: false,
+      version: input,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: `dsh 版本号无法解析（${show(input)}），视为未适配，插件自动禁用`,
+    }
+  }
+  if (compareParsed(parsed, MIN_BOUND) < 0) {
+    return {
+      supported: false,
+      version: parsed.raw,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: `dsh ${parsed.raw} 低于适配下限（要求 ${SUPPORTED_DSH_RANGE}）`,
+    }
+  }
+  if (compareParsed(parsed, MAX_BOUND) >= 0) {
+    return {
+      supported: false,
+      version: parsed.raw,
+      range: SUPPORTED_DSH_RANGE,
+      severity: 'warn',
+      reason: `dsh ${parsed.raw} 高于适配上限（要求 ${SUPPORTED_DSH_RANGE}）`,
+    }
+  }
+  return { supported: true, version: parsed.raw, range: SUPPORTED_DSH_RANGE, severity: 'ok' }
+}
+
+/** 读 package.json 的 version；读不到/不是字符串返回 ''。 */
+function readPackageVersion(packageJsonPath) {
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
+/** 安全 realpath（路径可能不存在/是虚拟路径）。 */
+function safeRealpath(p) {
+  try { return realpathSync(p) } catch { return '' }
+}
+
+/**
+ * 直接从"路径里含 `node_modules/@deepseek-ai/dsh/`"的位置推出包目录并读 package.json。
+ * 不依赖包的 `exports` 是否导出 `./package.json`（npx 缓存 / 全局安装 / 工作区三种布局都能命中）。
+ * @returns {string} 版本号；不是 dsh 路径或读不到返回 ''
+ */
+function versionFromNodeModulesPath(p) {
+  if (typeof p !== 'string' || !p) return ''
+  for (const marker of ['/node_modules/@deepseek-ai/dsh/', '/node_modules/@deepseek-ai/dsh-app-boot/']) {
+    const at = p.indexOf(marker)
+    if (at < 0) continue
+    const dir = p.slice(0, at + marker.length - 1)   // 含 .../@deepseek-ai/dsh
+    const version = readPackageVersion(join(dir, 'package.json'))
+    if (version) return version
+  }
+  return ''
+}
+
+/**
+ * 默认的"从已安装包解析 dsh 版本"实现。
+ * 候选锚点（按顺序，全部 try/catch）：process.argv 里的脚本路径 → 本插件模块路径 → cwd。
+ * 每个锚点两条路：`require.resolve('<包>/package.json')`（依赖 exports）+ 路径直推（不依赖 exports）。
+ * @returns {string} 版本号；解析不到返回 ''
+ */
+function resolveDshPackageVersion({ argv = process.argv, cwd = process.cwd() } = {}) {
+  const candidates = []
+  for (const a of Array.isArray(argv) ? argv : []) {
+    if (typeof a !== 'string' || !a.trim()) continue
+    if (a === process.execPath) continue
+    if (a.startsWith('-')) continue
+    if (!(a.startsWith('/') || a.startsWith('.') || a.includes('/') || a.includes('\\'))) continue
+    try {
+      candidates.push(a.startsWith('/') ? a : resolvePath(a))
+    } catch { /* 非法路径跳过 */ }
+  }
+  candidates.push(fileURLToPath(import.meta.url), join(cwd, 'package.json'))
+
+  for (const base of candidates) {
+    for (const name of ['@deepseek-ai/dsh/package.json', '@deepseek-ai/dsh-app-boot/package.json']) {
+      try {
+        const req = createRequire(base)
+        const version = readPackageVersion(req.resolve(name))
+        if (version) return version
+      } catch { /* 下一个锚点/包名 */ }
+    }
+    for (const p of [base, safeRealpath(base)]) {
+      const version = versionFromNodeModulesPath(p)
+      if (version) return version
+    }
+  }
+  return ''
+}
+
+/**
+ * 尽力识别当前 dsh 版本。**永不抛**，失败返回 null。
+ *
+ * 优先级：
+ *   ① env `WHYSHU_BA_DSH_VERSION` / `DSH_VERSION`（显式覆盖；离线验证/宿主未暴露版本时用）；
+ *   ② env `npm_package_name === '@deepseek-ai/dsh'` 时的 `npm_package_version`；
+ *   ③ argv 里字面出现的 `@deepseek-ai/dsh@x.y.z`（`npm exec` 形态会留下）；
+ *   ④ 包解析（见 resolveDshPackageVersion）。
+ *
+ * @param {{env?:Record<string,string|undefined>, argv?:string[], resolvePackageVersion?:Function}} [options]
+ *   仅供测试注入；生产调用不传参。
+ * @returns {string|null}
+ */
+export function readDshVersion(options = {}) {
+  try {
+    const env = (options.env && typeof options.env === 'object') ? options.env : process.env
+    const argv = Array.isArray(options.argv) ? options.argv : process.argv
+
+    for (const key of DSH_VERSION_ENV_KEYS) {
+      const v = env && typeof env[key] === 'string' ? env[key].trim() : ''
+      if (v) return v
+    }
+
+    if (env && env.npm_package_name === '@deepseek-ai/dsh' && typeof env.npm_package_version === 'string') {
+      const v = env.npm_package_version.trim()
+      if (v) return v
+    }
+
+    const literal = /@deepseek-ai\/dsh@(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/
+    for (const a of argv) {
+      if (typeof a !== 'string') continue
+      const m = literal.exec(a)
+      if (m) return m[1]
+    }
+
+    const resolvePackageVersion = typeof options.resolvePackageVersion === 'function'
+      ? options.resolvePackageVersion
+      : resolveDshPackageVersion
+    const resolved = resolvePackageVersion({ argv })
+    if (typeof resolved === 'string' && resolved.trim()) return resolved.trim()
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 兼容闸的降级动作：**只打日志，不碰任何宿主 API**（不注册端点、不监听事件、不加载子插件）。
+ *
+ * @param {object|null} ctx 宿主 context；当前刻意不使用（降级路径零宿主调用这一点有用例断言）
+ * @param {{version?:string|null, reason?:string, log?:Console}} [options]
+ * @returns {{supported:false, degraded:true, version:string|null, reason:string}}
+ */
+export function installCompatGuard(ctx, { version = null, reason = '', log = console } = {}) {
+  const shown = version ? show(version) : '未知版本'
+  const detail = String(reason || '').trim() || `不在支持范围 ${SUPPORTED_DSH_RANGE} 内`
+  const line = `[@whyshu/ba] 插件已自我禁用（dsh ${shown} 未适配）：${detail}。`
+    + 'dsh 可继续启动；升级 @whyshu/ba 到适配版本后会自动恢复。'
+    + `（排障：可设 ${DSH_VERSION_ENV_KEYS[0]} 显式指定宿主版本）`
+  try {
+    if (log && typeof log.warn === 'function') log.warn(line)
+    else if (typeof log === 'function') log(line)
+    else console.warn(line)
+  } catch { /* 日志本身失败也绝不能影响宿主启动 */ }
+  return { supported: false, degraded: true, version: version || null, reason: detail }
+}

package/src/index.js

@@ -13,6 +13,7 @@ import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { ENV_FILE, fetchOverview, hasCredentials, loadSettings } from './binance.mjs'
+import { evaluateCompatibility, installCompatGuard, readDshVersion } from './compat.mjs'
 
 /** 每次都读盘：重装后 version 仍能反映当前磁盘版本 */
 function pkgVersion() {
@@ -69,16 +70,46 @@ async function handle(req, res) {
 export const name = 'whyshu-ba'
 export const inject = ['webServer']
 
+/**
+ * 安全执行一次注册：任何异常只记日志，绝不让 apply 抛出。
+ * （apply 抛异常 = dsh 报 "entry did not activate"，严重时整个 web boot 失败。）
+ * @param {string} label 注册项描述（日志用）
+ * @param {() => unknown} fn 注册动作
+ * @returns {unknown} fn 的返回值；失败返回 undefined
+ */
+function safeRegister(label, fn) {
+  try {
+    return fn()
+  } catch (e) {
+    try {
+      console.warn(`[whyshu-ba] ${label} 注册失败（不影响 dsh 继续启动）:`, (e && e.message) || e)
+    } catch { /* 日志本身失败也不能抛 */ }
+    return undefined
+  }
+}
+
 export function apply(ctx) {
-  // ⛔ 永不抛出：插件激活失败会让整个 web boot 报 "entry did not activate"。
+  // 整体 try/catch：apply 抛异常会变成 dsh 的 "entry did not activate"（甚至 boot 失败）。
   try {
-    if (!ctx || !ctx.webServer || typeof ctx.webServer.register !== 'function') {
-      console.error('[whyshu-ba] 未拿到 webServer 服务，跳过端点注册（面板会显示 404，但 dsh 正常启动）')
+    // ① 宿主兼容闸：未适配版本（如 dsh 0.3.x）⇒ 只打一行日志后直接 return，零宿主调用。
+    const version = readDshVersion()
+    const compat = evaluateCompatibility(version)
+    if (!compat.supported) {
+      installCompatGuard(ctx, { version, reason: compat.reason })
       return
     }
-    ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/api/whyshu-ba', handler: handle }), 'whyshu-ba: read-only binance endpoints')
-    console.log(`[whyshu-ba] 已注册 /api/whyshu-ba/*（v${pkgVersion()}，只读，币安 Key 仅在宿主侧使用）`)
+
+    // ② 只读端点注册（safe 包裹；拿不到 webServer 时降级为"面板 404，dsh 正常启动"）
+    safeRegister('webServer', () => {
+      if (!ctx || !ctx.webServer || typeof ctx.webServer.register !== 'function') {
+        throw new Error('未拿到 webServer 服务，跳过端点注册')
+      }
+      ctx.effect(() => ctx.webServer.register({ kind: 'prefix', path: '/api/whyshu-ba', handler: handle }), 'whyshu-ba: read-only binance endpoints')
+    })
+    console.log(`[whyshu-ba] 已注册 /api/whyshu-ba/*（v${pkgVersion()}，dsh ${compat.version}，只读，币安 Key 仅在宿主侧使用）`)
   } catch (e) {
-    console.error('[whyshu-ba] 端点注册失败（不影响 dsh 其他功能）:', (e && e.message) || e)
+    try {
+      console.error('[whyshu-ba] apply 异常已忽略（不影响 dsh 启动）:', (e && e.message) || e)
+    } catch { /* noop */ }
   }
 }