dsh-mobile-plugin 0.1.57 → 0.1.59

package/README.md

@@ -77,14 +77,55 @@ DSH_HOME=/opt/dsh-mobile/.dsh DSH_MOBILE_PROFILE=mobile node host.js
   跑一次 pnpm。装了之后「设置 → 移动端 → 打开配置页面」那一页的更新卡片会直接调市场的公共
   更新接口（`/dsh-market/api/v1/*`），能在页面上检查更新、开始更新、看进度，并在需要时请
   市场代劳重启 DSH。
-- **装完/更新完要完整重启 DSH**：插件是 profile 层的 cordis bundle，进程起来时依赖树就定死了。
-  市场会把这件事报成 `restartRequired`，页面上有对应提示与按钮。
-- 发版：抬版本号（`node scripts/bump-version.mjs`）后 `npm publish`。插件不再自带发布脚本，
-  也没有「中转 OTA」这条分发源了。
+- **更新后不需要重启 DSH**（2026-10-10 起）：插件入口是一个稳定外壳，市场在 profile 里装完新版，
+  外壳会**就地换到新代码**（先把旧实现卸干净、再装新实现），面板那句「重启 DSH 才生效」不再是必须的。
+  代价与边界照实说：① **装了外壳的那一版本身仍需重启一次**（旧版本入口就是实现本身，没有外壳可换），
+  从再下一版起才真正免重启；② **外壳自己**（`lib/index.js` + `lib/shell/*`）在进程启动时就被 Node
+  缓存了，改它要等下次启动 —— 面板会用 `shellChanged` 把这件事说出来，不让你猜；③ 客户端那半个文件
+  （设置菜单里的入口）仍然是渲染器直读安装目录的，如果它改了需要刷新浏览器页面（所以这一半刻意保持
+  不变，更新界面都放在宿主吐的面板里）。
+- **自动更新**（面板 → 插件更新卡片里那个开关，默认关）：打开后每 10 分钟问一次 DSH 插件市场，
+  有新版就自动装好并**立即切换**，全程不需要重启。手动点「更新」走的是同一条路。
+- 有一个前提要认：市场**只从注册表更新**。如果这台机器上的插件是本地目录 / `file:` tgz 装的
+  （市场把它报成 `linked`），自动更新会如实跳过并说明原因 —— 要享受这条链，得先在插件市场里按包名
+  重装一次，切到 npm 来源。
+- 如果「设置 → 移动端 → 打开配置页面」打不开、页面吐一段 `panel_missing` JSON：那段文案会
+  写清是**哪一种**读不到 —— 「装完没重启」（旧实例还挂在这次安装删掉的那个目录上，最常见）、
+  「装了老版本」（0.1.47 及更早还没有这一页）还是「真没构建」（源码树里才会遇到）。三种解法
+  不同，别照着「没重启」的现场去跑 React 构建。同一句话也会进宿主 stderr。
 - 从前那套的教训记在这里：热更新只换宿主侧的实现代，**换不掉设置菜单那一半**（渲染器直接从
   安装目录读它），于是出现过「更新报成功、界面一动不动」，重启 DSH、重启 sidecar 都没用。
   现在只有一条更新路径，这类「哪一半是旧的」不再存在。
 
+### 发版流程（自己发一版更新）
+
+1. **抬版本号**：`node scripts/bump-version.mjs`（三段各 `0..999`）。
+2. **改过 `React/` 就先重建面板**：`cd React && pnpm run build`。产物 `lib/panel/index.html`
+   是**提交物**，要和源码一起提交 —— 忘了重建，发出去的就是旧页面，而仓库里没有任何东西能
+   替你发现（守卫只比字节形状，不比新旧）。
+3. **自检**：`npm test`（其中 `panel-artifact` 管产物形状与「读不到时报什么」，
+   `publish-payload` 管发布清单收得住每个会被加载的文件）；`npm pack --dry-run` 扫一眼发了什么。
+4. **发布**：`npm publish`。
+5. **核对**：`npm view dsh-mobile-plugin version`。
+6. **到机器上更新**：DSH → 设置 → 插件 里更新，**然后完整重启 DSH**。
+
+**发布这一步现在要你现场过二次验证**（2026-10 起，别以为是配错了）：
+
+- `npm publish` 会打印一条 `https://www.npmjs.com/auth/cli/…` 链接（或直接开浏览器），用账号
+  绑定的**安全密钥**确认一下，它自己接着把包发出去。
+- 所以这一步**必须能打开 www.npmjs.com**：机房/代理出口 IP 会被它的反机器人拦成 403
+  （页面写「访问暂时受限」并带上你的 IP）。换个节点或直连再发。
+- npm 已经关掉了「命令行建号」和「验证器 App（TOTP）」两条路：建号只能在网页上做，2FA 只能挂
+  安全密钥。这两件事上试命令是白费时间，认它就行。
+- 想少点一次确认，可以建一把「允许绕过 2FA」的细粒度令牌少输几次验证：
+  `npm token create --bypass-2fa --packages dsh-mobile-plugin --packages-and-scopes-permission read-write --expires 90`
+  （**最长 90 天**）。代价：这类令牌 **2027-01 起不能再直接发布**，到期或到点都得回到上面
+  那条交互式路径。
+- 还有个死结记在这里：令牌不能指向**还不存在**的包（会报
+  `You do not have access to the requested package(s)`），所以**第一版只能用浏览器验证发**，
+  令牌是「包已经存在之后」才有的便利。
+
+
 插件没有 GUI 外壳，配置入口是插件注册在 `webServer` 上的**仅限本机访问**（`localOnly` 守卫）
 的 HTTP 端点。`host.js` 启动后，其 `webServer.port` 就是下面 URL 里的 `<port>`
 （无头部署下固定 `3080`）：

package/lib/impl.js

@@ -318,6 +318,9 @@ function apply(ctx) {
 
   registerControlPlaneRoutes({
     registerRoute,
+    // 更新的机制住在外壳（`lib/index.js`）里，代这边只把它开成本机接口。取不到就如实报
+    // 不可用（`lib/impl.js` 被单独挂载时就是这样）。
+    getPluginRuntime: () => (typeof ctx.get === 'function' ? ctx.get('dshMobilePluginRuntime') : null),
     localOnly,
     readJson,
     sendJson,

package/lib/index.js

@@ -0,0 +1,180 @@
+/**
+ * 插件入口（**稳定外壳**）。
+ *
+ * 这个文件是整条自更新链路的锚点，所以它必须尽量不变。真正的实现在**代**里：随包发布的
+ * 那份是 `lib/impl.js`，市场装新版之后 profile 里那份是新一代（新 realpath）。
+ * 外壳负责挑一代、装上去，并在更新到位后换过去，见 `lib/shell/runtime.js`。
+ *
+ * ## 为什么入口非得是「外壳 + 代」两半
+ *
+ * 宿主进程启动时就把 profile 的插件树定死了（Node 按 realpath 缓存模块）。要换实现，
+ * 只能换**这个文件 import 的东西** —— 换掉它自己就得重启进程，而重启桌面端 DSH 会在用户
+ * 不知情的情况下掐掉他正在跑的对话，这正是要避免的事。所以这里只留不会变的装载逻辑，
+ * 变动频繁的部分全部搬进代。
+ *
+ * 这一层同时是**故障边界**：代装载失败时外壳回滚到上一代并把错误暴露出去，而不是让整个
+ * 插件从宿主里消失（那会让手机连不上，且日志里只剩一行 pending）。
+ *
+ * ## 更新从哪儿来（2026-10 改）
+ *
+ * 分发交给 DSH 插件市场：它在 profile 里跑 pnpm，装完会把 `<profile>/node_modules/
+ * dsh-mobile-plugin` 指向一个新的 store 目录。外壳照着新 realpath 重新 import 一代即可，
+ * **不需要重启 DSH**。自动更新（默认关）按 `AUTO_INTERVAL_MS` 轮询，见 `shell/updater.js`。
+ */
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRuntime } from './shell/runtime.js'
+import * as updater from './shell/updater.js'
+import { installedPackageDir, installedVersion, profileNodeModules } from './shell/manager.js'
+
+export const name = 'dsh-mobile-plugin'
+export const inject = ['webServer', 'sessions']
+
+/**
+ * 装载当前代，并把「问市场 / 换代码」这套动作暴露成服务。
+ *
+ * 对照 `lib/impl.js` 的 `apply`：那边签名也是 `(ctx)`，只是它注册的是真正的移动 API；
+ * 这里注册的是「装载它」。两者的 effect 各自归属自己那层 fiber —— 外壳被卸载时，代的
+ * fiber 作为它的子节点一起被 dispose，代里那些 `ctx.effect` 的清理动作照常执行。
+ */
+export function apply(ctx) {
+  const runtime = createRuntime()
+  // 跑着的外壳的指纹。它必须在**启动时**算：之后盘上那份可能已经被市场换掉了。
+  const runningShellHash = updater.shellFingerprint(path.dirname(path.dirname(fileURLToPath(import.meta.url))))
+  const market = {
+    checking: false,
+    lastCheckedAt: null,
+    lastError: null,
+    result: null,
+    lastApply: null,
+    appliedAt: null,
+  }
+  const base = () => updater.marketBase(ctx.webServer?.port)
+  const log = (level, message, ...rest) => {
+    const fn = ctx.logger?.[level]
+    if (typeof fn === 'function') fn.call(ctx.logger, message, ...rest)
+  }
+
+  /** 查一次有没有新版。只记结果，装不装由开关或人来决定。 */
+  async function check({ force = false } = {}) {
+    if (market.checking) return market.result
+    market.checking = true
+    try {
+      market.result = await updater.checkUpdate(base())
+      market.lastError = null
+    } catch (error) {
+      market.result = null
+      market.lastError = String(error?.message || error)
+    } finally {
+      market.checking = false
+      market.lastCheckedAt = new Date().toISOString()
+    }
+    return market.result
+  }
+
+  /**
+   * 请市场装新版，装完**就地换代**。
+   *
+   * 手动与自动走的是同一条路：手动只是「现在就做一次」。市场报的 `restartRequired` 一律
+   * 不照做 —— 外壳自己换代码，这正是这个文件存在的全部理由。
+   */
+  async function applyUpdate({ force = false } = {}) {
+    const outcome = await updater.installIfNeeded(base(), { force })
+    let swapped = false
+    let status = runtime.status()
+    if (outcome.installed) {
+      status = await runtime.reload()
+      swapped = true
+      log('info', 'dsh-mobile-plugin: 已就地换到 %s（无需重启 DSH）', status.version)
+    } else if (outcome.state && outcome.state !== 'succeeded') {
+      log('warn', 'dsh-mobile-plugin: 更新没有成功（%s）%s', outcome.state, outcome.failure?.message || '')
+    }
+    market.lastApply = { ...outcome, swapped }
+    market.appliedAt = new Date().toISOString()
+    if (outcome.installed) market.lastError = null
+    return { ...outcome, swapped, status }
+  }
+
+  // 换代前要知道有没有请求在飞（见 runtime.drain）。宿主 webServer 没有中间件机制，所以
+  // 这里包一层 register，把每条路由的 handler 变成「进 +1 / 出 -1」。包的时机在任何一代
+  // 装载之前，且 `wrapHandler` 遇到不认识的形状会原样放行。
+  ctx.effect(() => {
+    const server = ctx.webServer
+    const original = server?.register
+    if (typeof original !== 'function') return () => {}
+    server.register = function register(route) {
+      return original.call(this, runtime.wrapHandler(route))
+    }
+    return () => {
+      server.register = original
+      return runtime.detach()
+    }
+  }, 'dsh-mobile-plugin: generation runtime')
+
+  ctx.reflect.provide('dshMobilePluginRuntime', {
+    status: () => ({
+      ...runtime.status(),
+      /** 盘上装着的版本（市场装完立刻变，和运行中的版本对照就能看出「要不要换」）。 */
+      installedVersion: installedVersion(),
+      /** 盘上那份的外壳指纹与跑着的对不上 = 新版本连外壳一起改了，那部分要等下次启动才生效。 */
+      runningShellHash,
+      installedShellHash: updater.shellFingerprint(installedPackageDir()),
+      shellChanged: (() => {
+        const installed = updater.shellFingerprint(installedPackageDir())
+        return installed !== null && runningShellHash !== null && installed !== runningShellHash
+      })(),
+      profileNodeModules: profileNodeModules(),
+      autoUpdate: updater.autoUpdateEnabled(),
+      autoIntervalMs: updater.AUTO_INTERVAL_MS,
+      marketBase: base(),
+      marketLastCheckedAt: market.lastCheckedAt,
+      marketLastError: market.lastError,
+      marketResult: market.result,
+      lastApply: market.lastApply,
+      appliedAt: market.appliedAt,
+    }),
+    check,
+    apply: applyUpdate,
+    reload: version => runtime.reload(version),
+    setAutoUpdate: enabled => {
+      const value = updater.setAutoUpdate(enabled)
+      log('info', 'dsh-mobile-plugin: 自动更新已%s', value ? '开启' : '关闭')
+      return value
+    },
+  })
+
+  runtime
+    .start(ctx)
+    .then(() => {
+      log('info', 'dsh-mobile-plugin: 已装载 %s（来源 %s）', runtime.status().version, runtime.status().source)
+      // 自动更新：默认关。开了才轮询；每次都是「问市场 → 装 → 就地换代」。
+      const timer = setInterval(() => {
+        if (!updater.autoUpdateEnabled()) return
+        applyUpdate().catch(error => {
+          market.lastError = String(error?.message || error)
+          log('warn', 'dsh-mobile-plugin: 自动更新失败：%s', market.lastError)
+        })
+      }, updater.AUTO_INTERVAL_MS)
+      if (typeof timer.unref === 'function') timer.unref()
+      ctx.effect(() => () => clearInterval(timer), 'dsh-mobile-plugin: auto update timer')
+      // 启动后延后一次：别和绑端口、连隧道抢带宽。
+      if (updater.autoUpdateEnabled()) {
+        const kick = setTimeout(() => {
+          applyUpdate().catch(error => {
+            market.lastError = String(error?.message || error)
+            log('warn', 'dsh-mobile-plugin: 启动时的自动更新失败：%s', market.lastError)
+          })
+        }, 10000)
+        if (typeof kick.unref === 'function') kick.unref()
+      } else {
+        // 没开自动也查一次：用户打开面板之前就知道有没有新版。
+        const kick = setTimeout(() => { check().catch(() => {}) }, 5000)
+        if (typeof kick.unref === 'function') kick.unref()
+      }
+      return undefined
+    })
+    .catch(error => {
+      log('error', 'dsh-mobile-plugin: 装载插件实现失败：%s', error?.message || error)
+    })
+}