dsh-mobile-plugin 0.1.82 → 0.1.85

package/lib/shell/device-ota.js

@@ -1,13 +1,9 @@
-/** 设备端临时插件 OTA：npm 保持正式来源，OTA 仅保存于 DSH home。 */
+/** 设备端临时插件 OTA：npm 保持正式来源，OTA 只落在 profile 里（见 storageRoot）。 */
 import fs from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
-import { createRequire } from 'node:module'
 import { dshHome } from '../shared/paths.js'
-import { compareVersion } from './manager.js'
-
-const require_ = createRequire(import.meta.url)
-const zlib = require_('node:zlib')
+import { compareVersion, generationModulesError } from './manager.js'
+import { movePath, readManifest, sha256Hex, unpackTarGz, verifyManifest } from './ota-package.js'
 /**
  * OTA 包落在哪。
  *
@@ -27,50 +23,55 @@ const PACKAGE = 'dsh-mobile-plugin'
 const RELAY = 'https://dsh-hub.wnluo.com/api/desktop-plugins/ota'
 const CHANNEL = 'stable'
 const PLATFORM = process.platform
+/**
+ * 平台回落的兜底标记。
+ *
+ * 这个插件是纯 JS，同一份包在 Linux/macOS/Windows 上都能跑；但中转是按平台分发的，以前
+ * 只发过 darwin 就意味着 Windows 机器永远查不到更新（`ok:false` 被当成「没有新版」）。
+ * 约定：自己平台没包时再问一次 `any`，发布方也可以直接只发一份 `any`。
+ */
+const ANY_PLATFORM = 'any'
 function validVersion(value) { return typeof value === 'string' && /^\d+\.\d+\.\d+$/.test(value) }
 function validPackageUrl(value) {
   try { return new URL(value).protocol === 'https:' } catch { return false }
 }
+/**
+ * 列出盘上可用的 OTA 代。
+ *
+ * 两条容错都是必要的：**逐个条目自己 try**（一个残目录不能让整台机器的 OTA 全部不可见——
+ * 旧实现把整个 map 包在一个 try 里，任何一份半拷贝都会让 `availableOta()` 返回空，表现为
+ * 「更新装了但界面上永远没有新版」），以及**跳过点开头的目录**（`.staging-*` 是解包中途的
+ * 暂存，不能当成一代）。
+ */
 function availableOta() {
-  try {
-    return fs.readdirSync(ROOT(), { withFileTypes: true }).filter(item => item.isDirectory()).map(item => {
+  let items
+  try { items = fs.readdirSync(ROOT(), { withFileTypes: true }) } catch { return [] }
+  const found = []
+  for (const item of items) {
+    if (!item.isDirectory() || item.name.startsWith('.')) continue
+    try {
       const pkgDir = path.join(ROOT(), item.name, PACKAGE)
       const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'))
-      if (pkg.name !== PACKAGE || !validVersion(pkg.version) || !fs.existsSync(path.join(pkgDir, 'lib', 'impl.js'))) return null
-      return { version: pkg.version, entry: path.join(pkgDir, 'lib', 'impl.js'), dir: pkgDir, pkgDir, source: 'ota' }
-    }).filter(Boolean).sort((a, b) => compareVersion(b.version, a.version))
-  } catch { return [] }
+      if (pkg.name !== PACKAGE || !validVersion(pkg.version)) continue
+      if (!fs.existsSync(path.join(pkgDir, 'lib', 'impl.js'))) continue
+      found.push({ version: pkg.version, entry: path.join(pkgDir, 'lib', 'impl.js'), dir: pkgDir, pkgDir, source: 'ota' })
+    } catch { /* 半份包 / 残目录：只跳过它自己 */ }
+  }
+  return found.sort((a, b) => compareVersion(b.version, a.version))
+}
+/** 清掉上次解包中途退出留下的暂存目录（断电 / 进程被杀时的残骸）。 */
+function sweepStaging() {
+  let items
+  try { items = fs.readdirSync(ROOT(), { withFileTypes: true }) } catch { return }
+  for (const item of items) {
+    if (!item.isDirectory() || !item.name.startsWith('.staging-')) continue
+    try { fs.rmSync(path.join(ROOT(), item.name), { recursive: true, force: true }) } catch { /* 下次再清 */ }
+  }
 }
 function clearSuperseded(version) {
   if (!validVersion(version)) return
   for (const release of availableOta()) if (compareVersion(version, release.version) >= 0) fs.rmSync(path.dirname(release.pkgDir), { recursive: true, force: true })
 }
-function unpackTarGz(buffer, target) {
-  const tar = zlib.gunzipSync(buffer)
-  let offset = 0
-  while (offset + 512 <= tar.length) {
-    const header = tar.subarray(offset, offset + 512)
-    if (header.every(byte => byte === 0)) break
-    const name = header.subarray(0, 100).toString().replace(/\0.*$/, '')
-    const prefix = header.subarray(345, 500).toString().replace(/\0.*$/, '')
-    const rel = path.posix.join(prefix, name)
-    const size = parseInt(header.subarray(124, 136).toString().replace(/\0.*$/, '').trim() || '0', 8)
-    const type = header[156]
-    const start = offset + 512
-    if (!rel.startsWith('package/') || rel.split('/').includes('..')) throw new Error('OTA 包含无效路径')
-    if (type === 0 || type === 48) {
-      const dest = path.join(target, PACKAGE, ...rel.split('/').slice(1))
-      fs.mkdirSync(path.dirname(dest), { recursive: true })
-      fs.writeFileSync(dest, tar.subarray(start, start + size))
-    } else if (type !== 53) throw new Error(`OTA 包包含不支持的 tar 项：${rel}`)
-    offset = start + Math.ceil(size / 512) * 512
-  }
-  const pkgDir = path.join(target, PACKAGE)
-  const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'))
-  if (pkg.name !== PACKAGE || !validVersion(pkg.version) || !fs.existsSync(path.join(pkgDir, 'lib', 'impl.js'))) throw new Error('OTA 包结构不完整')
-  return pkg.version
-}
-
 export function createDeviceOta({ fetchImpl = fetch, installed = () => null, platform = PLATFORM, channel = CHANNEL, runtime = null } = {}) {
   async function reconcileOfficial() {
     const active = runtime?.status()
@@ -87,37 +88,66 @@ export function createDeviceOta({ fetchImpl = fetch, installed = () => null, pla
     if (status?.source === 'installed') clearSuperseded(officialVersion)
     return { switched: status?.source === 'installed', status }
   }
-  async function check() {
-    await reconcileOfficial()
-    const url = `${RELAY}/latest?platform=${encodeURIComponent(platform)}&channel=${encodeURIComponent(channel)}`
+  /** 问一次中转「我该装哪个版本」；没有就返回 null（不抛）。 */
+  async function latestFor(wanted) {
+    const url = `${RELAY}/latest?platform=${encodeURIComponent(wanted)}&channel=${encodeURIComponent(channel)}`
     const response = await fetchImpl(url, { headers: { accept: 'application/json' } })
     if (!response.ok) throw new Error(`OTA relay 返回 HTTP ${response.status}`)
     const body = await response.json()
-    const release = body?.data
-    if (body?.ok !== true || !validVersion(release?.version) || release.platform !== platform || release.channel !== channel || !validPackageUrl(release.packageUrl)) throw new Error('OTA relay 没有提供匹配平台、stable channel、有效版本或 HTTPS 下载地址')
+    if (body?.ok !== true) return null
+    const release = body.data
+    if (!release || !validVersion(release.version)) return null
+    // 回落来的包平台标记是 `any`；自己平台那份必须正好对上。
+    if (release.platform !== wanted || release.channel !== channel) return null
+    if (!validPackageUrl(release.packageUrl)) return null
+    return release
+  }
+  async function check() {
+    await reconcileOfficial()
+    const release = (await latestFor(platform)) ?? (platform === ANY_PLATFORM ? null : await latestFor(ANY_PLATFORM))
+    if (!release) throw new Error('OTA relay 没有提供匹配平台、stable channel、有效版本或 HTTPS 下载地址')
     const installedVersion = installed()
     const officialVersion = installedVersion
     const ota = availableOta()[0] || null
     const otaVersion = validVersion(release.version) ? release.version : null
     const newest = [ota?.version, otaVersion].filter(validVersion).sort((a, b) => compareVersion(b, a))[0] || null
     const absorbed = Boolean(validVersion(officialVersion) && newest && compareVersion(officialVersion, newest) >= 0 && runtime?.status()?.source !== 'ota')
-    return { available: Boolean(newest && !absorbed && compareVersion(newest, installedVersion || '0.0.0') > 0), version: newest, platform: release.platform || platform, channel: release.channel || channel, installedVersion, otaVersion: ota?.version ?? null, officialVersion, absorbed, packageUrl: release.packageUrl }
+    return { available: Boolean(newest && !absorbed && compareVersion(newest, installedVersion || '0.0.0') > 0), version: newest, platform: release.platform || platform, channel: release.channel || channel, installedVersion, otaVersion: ota?.version ?? null, officialVersion, absorbed, packageUrl: release.packageUrl, sha256: typeof release.sha256 === 'string' && /^[0-9a-f]{64}$/i.test(release.sha256) ? release.sha256.toLowerCase() : null }
   }
   async function apply() {
     const info = await check()
     if (info.otaVersion && compareVersion(info.otaVersion, info.version) === 0) return { installed: true, version: info.version, source: 'ota', alreadyDownloaded: true }
     if (validVersion(info.officialVersion) && compareVersion(info.officialVersion, info.version) >= 0) return { installed: false, reason: 'npm-current-or-newer', version: info.officialVersion }
-    const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-plugin-ota-'))
+    // 暂存目录**建在目标根里面**，不是系统临时目录：最后一步要 rename 到 `<root>/<version>`，
+    // 跨盘的 rename 在 Windows 上直接 EXDEV（系统临时目录常在 C:，而 profile 可能在别的盘）。
+    fs.mkdirSync(ROOT(), { recursive: true })
+    sweepStaging()
+    const staging = fs.mkdtempSync(path.join(ROOT(), '.staging-'))
     try {
       const response = await fetchImpl(info.packageUrl)
       if (!response.ok) throw new Error(`OTA 下载失败：HTTP ${response.status}`)
-      const version = unpackTarGz(Buffer.from(await response.arrayBuffer()), staging)
+      const raw = Buffer.from(await response.arrayBuffer())
+      // 中转记了哈希就一定要对上：半个包、被中间层改过的包都在这里被挡住，而不是装上去再炸。
+      if (info.sha256 && sha256Hex(raw) !== info.sha256) {
+        throw new Error(`OTA 包校验失败：下载内容的 sha256 与中转记录不一致（预期 ${info.sha256}，实际 ${sha256Hex(raw)}）`)
+      }
+      unpackTarGz(raw, staging)
+      const pkgDir = path.join(staging, PACKAGE)
+      const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'))
+      const version = pkg && pkg.version
+      if (pkg.name !== PACKAGE || !validVersion(version)) throw new Error('OTA 包结构不完整：package.json 里的包名或版本不对')
       if (version !== info.version) throw new Error(`OTA 版本不匹配：预期 ${info.version}，实际 ${version}`)
+      if (!fs.existsSync(path.join(pkgDir, 'lib', 'impl.js'))) throw new Error('OTA 包结构不完整：缺 lib/impl.js')
+      // 有清单就逐项核对（缺文件 / 大小不符在**激活之前**失败）；老包没有清单，退回上面那两条判据。
+      const manifest = readManifest(pkgDir)
+      if (manifest) {
+        if (manifest.version !== version) throw new Error(`OTA 包清单版本与 package.json 不一致（${manifest.version} ≠ ${version}）`)
+        verifyManifest(pkgDir, manifest)
+      }
       const releaseDir = path.join(ROOT(), version)
-      fs.mkdirSync(ROOT(), { recursive: true })
       fs.rmSync(releaseDir, { recursive: true, force: true })
-      fs.renameSync(staging, releaseDir)
-      return { installed: true, version, source: 'ota' }
+      movePath(staging, releaseDir)
+      return { installed: true, version, source: 'ota', verified: Boolean(manifest) }
     } catch (error) {
       fs.rmSync(staging, { recursive: true, force: true })
       throw error
@@ -127,7 +157,7 @@ export function createDeviceOta({ fetchImpl = fetch, installed = () => null, pla
     const installedVersion = installed()
     const active = runtime?.status() ?? null
     const ota = availableOta()[0] || null
-    return { available: Boolean(ota && compareVersion(ota.version, installedVersion || '0.0.0') > 0), activeVersion: active?.version ?? installedVersion, otaVersion: ota?.version ?? null, officialVersion: installedVersion, absorbed: Boolean(installedVersion && ota && compareVersion(installedVersion, ota.version) >= 0 && active?.source !== 'ota'), channel }
+    return { available: Boolean(ota && compareVersion(ota.version, installedVersion || '0.0.0') > 0), activeVersion: active?.version ?? installedVersion, otaVersion: ota?.version ?? null, officialVersion: installedVersion, absorbed: Boolean(installedVersion && ota && compareVersion(installedVersion, ota.version) >= 0 && active?.source !== 'ota'), channel, dependencyLinkError: generationModulesError() }
   }
   async function activate() {
     const outcome = await apply()

package/lib/shell/manager.js

@@ -33,6 +33,7 @@ import { createRequire } from 'node:module'
 import path from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { availableOta, configureOtaRoot } from './device-ota.js'
+import { movePath } from './ota-package.js'
 import { dshHome } from '../shared/paths.js'
 
 /** CJS 模块缓存。实现树里 `lib/relay`、`lib/routes`、`lib/mobile` 都是 CJS。 */
@@ -251,7 +252,9 @@ function moveOtaRootIntoProfile() {
     for (const entry of fs.readdirSync(legacy)) {
       const target = path.join(next, entry)
       if (fs.existsSync(target)) continue
-      fs.renameSync(path.join(legacy, entry), target)
+      // 跨盘也能搬：`<DSH_HOME>` 与 profile 在 Windows 上很可能不在同一个盘，
+      // 那时 rename 抛 EXDEV，整段迁移会静默失败、OTA 留在树外（依赖就解析不到了）。
+      movePath(path.join(legacy, entry), target)
     }
     fs.rmSync(legacy, { recursive: true, force: true })
   } catch {
@@ -277,6 +280,18 @@ function moveOtaRootIntoProfile() {
 /** 外壳一启动就把 OTA 落盘位置定下来（见 moveOtaRootIntoProfile 的注释）。 */
 moveOtaRootIntoProfile()
 
+/**
+ * 最近一次「给 OTA 代补依赖软链」的失败原因。
+ *
+ * 软链只是兜底（落在 profile 里的一代本来就能沿祖先目录解析到 profile 的依赖），可它
+ * **在 Windows 默认没有权限建**。旧实现把失败静默吞掉，于是现场只剩一句
+ * `Cannot find module`，看不出是缺依赖还是补链失败。记在这里，由状态接口如实报出来。
+ */
+let generationLinkError = null
+export function generationModulesError() {
+  return generationLinkError
+}
+
 function ensureGenerationModules(generation) {
   if (!generation || generation.source !== 'ota' || !generation.dir) return
   // 只认真正的 `node_modules`：`findProfileNodeModules()` 找不到时会回落到 profile 根，
@@ -296,8 +311,12 @@ function ensureGenerationModules(generation) {
     }
     try {
       fs.symlinkSync(target, at, 'dir')
-    } catch {
-      // 盘上不让写（只读 home / 权限不足）就让解析失败如实报出来，别把它变成静默的空实现
+      generationLinkError = null
+    } catch (error) {
+      // Windows 默认没有建软链的权限（要开发者模式或管理员），这类失败**必须留痕**：
+      // 否则现场只有一句 `Cannot find module`，看不出是缺依赖还是补链被拒。
+      generationLinkError = `补依赖软链失败（${at} → ${target}）：${error && typeof error === 'object' ? error.code || error.message : error}`
+      try { process.stderr.write(`[dsh-mobile-plugin] ${generationLinkError}\n`) } catch { /* ignore */ }
     }
   }
   link(PROFILE_NODE_MODULES, path.join(versionDir, 'node_modules'))

package/lib/shell/ota-package.js

@@ -0,0 +1,237 @@
+/**
+ * OTA 包（npm tarball）的读取、校验与落盘。
+ *
+ * 这一层存在的唯一理由是「换一台机器也照样能装」：以前解包是 `device-ota.js` 里的六十行
+ * 手写代码，只认普通文件和目录，遇到 PAX 扩展头（macOS 的 tar 默认会带）、GNU 长文件名、
+ * 长路径就直接抛「不支持的 tar 项」；反过来，包里少几个文件它又看不出来，于是装上去之后
+ * 才在某一代运行时报「找不到某个 JS 文件」。这里把两件事一起解决：
+ *
+ *  1. **解包要认得真实世界里的 tar**：ustar 的 prefix、PAX（`x` / `g`）、GNU 长名（`L` / `K`）
+ *     都要能读；软链接、硬链接、设备文件要**明确拒绝**并说清原因（不静默跳过，否则会装出
+ *     一个缺文件的代）。
+ *  2. **装完要能证明它完整**：包里带一份 `lib/ota-manifest.json`（发布脚本生成，列出版本与
+ *     每个文件的路径和字节数），解包后逐项核对。缺文件、大小不符都在**激活之前**失败，
+ *     错误里直接点名是哪个文件。
+ *
+ * 手写 tar 解析而不是引依赖：这是发布链路上的一段自包含代码（OTA 包要能在一台刚装好
+ * DSH 的机器上被解出来，不能要求它先装点别的），而 ustar 的头部格式是固定的 512 字节。
+ */
+
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import zlib from 'node:zlib'
+
+/** 清单在包内的相对路径（相对插件包根）。 */
+export const MANIFEST_PATH = 'lib/ota-manifest.json'
+/** tar 里所有条目都必须在这个目录下，否则不是 npm 包。 */
+const ARCHIVE_PREFIX = 'package'
+
+const BLOCK = 512
+/** 文件条目的类型标记。ustar 规范允许 `\0` 表示普通文件（老实现会写 0x00）。 */
+const TYPE_FILE = new Set(['0', '\u0000'])
+const TYPE_DIR = '5'
+const TYPE_PAX = 'x'
+const TYPE_PAX_GLOBAL = 'g'
+const TYPE_GNU_LONG_NAME = 'L'
+const TYPE_GNU_LONG_LINK = 'K'
+
+function readString(buffer, start, length) {
+  const slice = buffer.subarray(start, start + length)
+  const end = slice.indexOf(0)
+  return (end === -1 ? slice : slice.subarray(0, end)).toString('utf8')
+}
+
+function readOctal(buffer, start, length) {
+  const raw = readString(buffer, start, length).trim()
+  if (!raw) return 0
+  const value = Number.parseInt(raw, 8)
+  return Number.isFinite(value) ? value : 0
+}
+
+/**
+ * 把 tar 里的路径规范成安全的相对段数组。
+ *
+ * 反斜杠**当分隔符处理**：tar 用的是 posix 路径，但包里真出现一个 `a\..\..\x` 这样的名字时，
+ * 在 Windows 上它就是三个目录层级。统一按分隔符拆开再判 `..`，两个平台的结果才一致。
+ */
+function safeSegments(relPath) {
+  const normalized = String(relPath || '').replace(/\\/g, '/')
+  if (!normalized || normalized.includes('\u0000')) throw new Error('OTA 包包含空路径或非法字符')
+  if (normalized.startsWith('/') || /^[A-Za-z]:/.test(normalized)) throw new Error(`OTA 包含绝对路径：${relPath}`)
+  const parts = normalized.split('/').filter(part => part !== '' && part !== '.')
+  if (parts.includes('..')) throw new Error(`OTA 包含越界路径：${relPath}`)
+  return parts
+}
+
+/**
+ * PAX 扩展头里取 `path=`（其余键——size/mtime/uid 之类——对安装没有意义）。
+ *
+ * PAX 的每条记录是 `<十进制总长度> <键>=<值>\n`：长度写在前头，所以不能按空格切第一段
+ * 当键名。按长度逐条前进，才不会把值里的空格或换行切坏。
+ */
+function paxPathOf(data) {
+  const text = data.toString('utf8')
+  let offset = 0
+  let found = null
+  while (offset < text.length) {
+    const space = text.indexOf(' ', offset)
+    if (space <= offset) break
+    const length = Number.parseInt(text.slice(offset, space), 10)
+    if (!Number.isFinite(length) || length <= 0) break
+    const record = text.slice(space + 1, offset + length).replace(/\n$/, '')
+    const eq = record.indexOf('=')
+    if (eq > 0 && record.slice(0, eq) === 'path') found = record.slice(eq + 1)
+    offset += length
+  }
+  return found
+}
+
+/**
+ * 把一段 tgz/tar 解析成条目数组。
+ *
+ * @param {Buffer} input gzip 或裸 tar（按 gzip 魔数区分）
+ * @returns {Array<{path: string, type: 'file'|'dir', mode: number, data: Buffer|null}>}
+ */
+export function readEntries(input) {
+  const tar = input.length >= 2 && input[0] === 0x1f && input[1] === 0x8b ? zlib.gunzipSync(input) : input
+  const entries = []
+  let offset = 0
+  // PAX / GNU 长名是「下一个条目」的修饰头，读完那一条就清掉。
+  let pendingPath = null
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK)
+    if (header.every(byte => byte === 0)) break
+    const name = readString(header, 0, 100)
+    const prefix = readString(header, 345, 155)
+    const size = readOctal(header, 124, 12)
+    const mode = readOctal(header, 100, 8) || 0o644
+    const type = String.fromCharCode(header[156]) || '0'
+    const start = offset + BLOCK
+    const end = start + size
+    if (end > tar.length) {
+      throw new Error(`OTA 包被截断：条目 ${name || '(无名)'} 声明 ${size} 字节，包内不够`)
+    }
+    const data = tar.subarray(start, end)
+    offset = start + Math.ceil(size / BLOCK) * BLOCK
+
+    if (type === TYPE_PAX) {
+      pendingPath = paxPathOf(data) ?? pendingPath
+      continue
+    }
+    if (type === TYPE_PAX_GLOBAL) continue
+    if (type === TYPE_GNU_LONG_NAME) {
+      pendingPath = data.toString('utf8').replace(/\0.*$/, '')
+      continue
+    }
+    if (type === TYPE_GNU_LONG_LINK) continue
+    if (type === '1' || type === '2' || type === '3' || type === '4' || type === '6') {
+      // 软链接/硬链接/设备文件一律拒绝：npm 包里不会有，出现了要么是包坏了要么是有人在
+      // 拼接。静默跳过会让「这一代缺一个文件」在几个小时后才以别的方式暴露。
+      throw new Error(`OTA 包里有链接或设备条目（${name}），拒绝安装；打包请用 npm pack，不要用系统 tar`)
+    }
+    // PAX / GNU 长名已经把整条路径写全了（含 `package/` 前缀），有它就不再拼 prefix。
+    const fullPath = pendingPath ?? (prefix ? `${prefix}/${name}` : name)
+    pendingPath = null
+    const segments = safeSegments(fullPath)
+    if (segments[0] !== ARCHIVE_PREFIX) {
+      throw new Error(`OTA 包条目必须以 ${ARCHIVE_PREFIX}/ 打头：${fullPath}`)
+    }
+    const normalized = segments.join('/')
+    if (type === TYPE_DIR) entries.push({ path: normalized, type: 'dir', mode, data: null })
+    else if (TYPE_FILE.has(type)) entries.push({ path: normalized, type: 'file', mode, data })
+    else throw new Error(`OTA 包里有不支持的条目类型 '${type}'（${name}）`)
+  }
+  if (!entries.length) throw new Error('OTA 包是空的：一个条目都没读出来')
+  return entries
+}
+
+/**
+ * 把包解到 `target/<packageName>`。
+ *
+ * 不解压到系统临时目录：见 `device-ota.js` 里对「暂存必须和目标同盘」的说明。
+ *
+ * @returns {{files: number}}
+ */
+export function unpackTarGz(input, target, { packageName = 'dsh-mobile-plugin' } = {}) {
+  const entries = readEntries(input)
+  let files = 0
+  for (const entry of entries) {
+    const rel = entry.path.split('/').slice(1)
+    if (!rel.length) continue
+    const dest = path.join(target, packageName, ...rel)
+    if (entry.type === 'dir') {
+      fs.mkdirSync(dest, { recursive: true })
+      continue
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true })
+    fs.writeFileSync(dest, entry.data)
+    // 可执行位只在 POSIX 上有意义；Windows 上 chmod 会变成只读标记，别去碰它。
+    if (process.platform !== 'win32' && (entry.mode & 0o111)) {
+      try { fs.chmodSync(dest, entry.mode & 0o777) } catch { /* 权限位丢了不影响 JS 加载 */ }
+    }
+    files += 1
+  }
+  return { files }
+}
+
+/**
+ * 读包内清单。没有清单（老版本打的包）返回 null——那时退回旧的「有 package.json 与
+ * impl.js 就算齐」判据，不让新代码把老包全判成坏的。
+ */
+export function readManifest(pkgDir) {
+  let raw
+  try { raw = JSON.parse(fs.readFileSync(path.join(pkgDir, MANIFEST_PATH), 'utf8')) } catch { return null }
+  if (!raw || typeof raw !== 'object' || typeof raw.version !== 'string' || !Array.isArray(raw.files)) return null
+  const files = raw.files.filter(item => item && typeof item.path === 'string' && item.path.length > 0)
+  if (files.length !== raw.files.length) return null
+  return { version: raw.version, platform: typeof raw.platform === 'string' ? raw.platform : null, files: files.map(item => ({ path: item.path, size: Number.isFinite(item.size) ? item.size : null })) }
+}
+
+/**
+ * 逐项核对清单。缺文件 / 大小不符立刻抛错，并把**具体是哪个文件**写进消息——
+ * 「找不到某个 JS 文件」这类模糊报错要在激活之前就变成可执行的结论。
+ */
+export function verifyManifest(pkgDir, manifest) {
+  if (!manifest) return 0
+  const problems = []
+  for (const item of manifest.files) {
+    const segments = safeSegments(item.path)
+    const abs = path.join(pkgDir, ...segments)
+    let stat
+    try { stat = fs.statSync(abs) } catch { problems.push(`缺文件 ${item.path}`) }
+    if (stat) {
+      if (!stat.isFile()) problems.push(`不是普通文件 ${item.path}`)
+      else if (item.size !== null && stat.size !== item.size) problems.push(`大小不符 ${item.path}（清单 ${item.size}，实际 ${stat.size}）`)
+    }
+    if (problems.length >= 5) break
+  }
+  if (problems.length) throw new Error(`OTA 包不完整，拒绝激活：${problems.join('；')}`)
+  return manifest.files.length
+}
+
+/**
+ * 移动/改名一个目录，跨盘也能成。
+ *
+ * `fs.renameSync` 在**同一文件系统**内是原子的，但 Windows 上系统临时目录与 DSH 数据目录
+ * 很可能不在一个盘，那时它抛 `EXDEV`；Windows 还可能在目标被占用时抛 `EPERM`/`EACCES`。
+ * 这条链上没有别的地方能兜住这类失败，所以在这里退化成本地复制再删源。
+ */
+export function movePath(src, dst) {
+  try {
+    fs.renameSync(src, dst)
+    return 'rename'
+  } catch (error) {
+    const code = error && typeof error === 'object' ? error.code : null
+    if (!['EXDEV', 'EPERM', 'EACCES', 'ENOTEMPTY', 'EEXIST'].includes(code)) throw error
+  }
+  fs.rmSync(dst, { recursive: true, force: true })
+  fs.cpSync(src, dst, { recursive: true })
+  fs.rmSync(src, { recursive: true, force: true })
+  return 'copy'
+}
+
+/** 下载内容的哈希。中转下发了 sha256 时用它把「拿到的包」和「发布的包」钉在一起。 */
+export function sha256Hex(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex')
+}

package/lib/sidecar-facade-worker.cjs

@@ -160,6 +160,41 @@ function snapshotRead(info) {
   }
   return body
 }
+/**
+ * 「这份配置里哪几项决定隧道要重建」。
+ *
+ * 只有决定**连到哪台、以谁的身份连**的字段在这里。配对码、名字、局域网候选都
+ * 不在此列——它们能在现有连接上重报一次注册信息就生效（见 reannounceRegistration）。
+ *
+ * 为什么要把这条显式写出来：以前 `configure()` 是无条件 `stopServices()` 把隧道和
+ * 局域网代理一起拆了重建，于是每次配置下发（哪怕一个字段没变）都是一次全断。真机
+ * 现场就是「切个网络，接下来几秒点什么都失败」，宿主日志里是一串「隧道关闭 + 局域网
+ * 代理开始监听」，跑几小时后内存堆到几个 G 把宿主撑爆。
+ */
+function tunnelSignature(c) {
+  return JSON.stringify([Boolean(c.enabled), c.relayUrl || '', c.instanceId || '', c.upstreamPort || 0, c.registerSecret || ''])
+}
+/** 「这份配置里哪几项决定局域网代理要重建」。 */
+function lanSignature(c) {
+  return JSON.stringify([Boolean(c.enabled), Boolean(c.lanEnabled), c.lanPort || 0, c.upstreamPort || 0, c.instanceId || '', c.pairingCode || '', c.lanSecret || ''])
+}
+/** 「这份配置里哪几项决定网络监视器要不要重排」。 */
+function monitorSignature(c) {
+  return JSON.stringify([Boolean(c.enabled), c.relayUrl || '', Boolean(c.lanEnabled)])
+}
+/** 当前应该上报给中转的局域网候选。 */
+function currentLanUrls() { return config.lanEnabled ? lanUrls(lanUrlPort()) : [] }
+/**
+ * 局域网候选变了：只重报注册信息，**不重建隧道**。
+ *
+ * 重建一次要把手机所有在途请求连同局域网监听一起拆掉，而这条路径（地址变化、实际
+ * 端口与首选端口不一致）本来就只是「名片上的地址要更新」。隧道还没连上时不用额外
+ * 做事：下一次 startTunnel 会按当前状态现算候选。
+ */
+function reannounceRegistration() {
+  if (!tunnel) return
+  tunnel.updateRegistration({ lanUrls: currentLanUrls() })
+}
 function stopNetworkMonitor() {
   if (networkTimer) { clearInterval(networkTimer); networkTimer = null }
 }
@@ -178,8 +213,7 @@ function startNetworkMonitor() {
     const current = lanUrls(lanUrlPort())
     if (JSON.stringify(current) === JSON.stringify(previous)) return
     previous = current
-    // lanUrls is sent during register; reconnect only after a real change.
-    startTunnel()
+    reannounceRegistration()
   }, NETWORK_POLL_MS)
 }
 function stopLan() {
@@ -196,7 +230,7 @@ function startTunnel() {
     relayUrl: core.tunnelWsUrl(config.relayUrl), instanceId: config.instanceId, pairingCode: config.pairingCode,
     name: config.name, upstream: upstream(),
     registerSecret: config.registerSecret,
-    lanUrls: config.lanEnabled ? lanUrls(lanUrlPort()) : [],
+    lanUrls: currentLanUrls(),
     readSnapshot: snapshotRead,
     // 实例身份守卫：只有还活着的那个隧道实例才许改状态。onClose / onPairRequest /
     // start().catch 都有这道闸，只有 onRegistered 漏了——而它恰恰是最容易迟到的一个
@@ -251,9 +285,9 @@ function startLan() {
     if (bound > 0) lanBoundPort = bound
     publishState()
     // 实际端口和首选端口不同时，中转侧那份 lanUrls（注册时随 metadata 上报的）
-    // 带的就是首选端口，手机从公网拿到的局域网候选全是死地址。重连一次隧道，让
-    // 中转拿到真正的端口。
-    if (changed && config.enabled && config.relayUrl) startTunnel()
+    // 带的就是首选端口，手机从公网拿到的局域网候选全是死地址。重报一次注册信息就
+    // 够了——重建隧道会把手机在途请求全掐掉，代价远大于这条名片更新。
+    if (changed) reannounceRegistration()
   }).catch(error => { if (lan === current) { lanState = 'error'; lanError = error instanceof Error ? error.message : String(error); publishState() } })
 }
 async function configure(next) {
@@ -265,12 +299,34 @@ async function configure(next) {
   if (typeof next.upstreamPort !== 'number' || !Number.isInteger(next.upstreamPort) || next.upstreamPort < 1 || next.upstreamPort > 65535) throw new Error('invalid upstreamPort')
   if (next.lanPort !== undefined && (!Number.isInteger(next.lanPort) || next.lanPort < 1024 || next.lanPort > 65535)) throw new Error('invalid lanPort')
   if (next.registerSecret !== undefined && (typeof next.registerSecret !== 'string' || next.registerSecret.length > 512)) throw new Error('invalid registerSecret')
-  await stopServices()
+  // 只重建真正变了的那一半：
+  //   - 决定隧道「连到哪台、以谁的身份连」的字段变了才重建隧道；
+  //   - 决定局域网监听的字段变了才重建局域网代理；
+  //   - 其余（配对码 / 名字 / 局域网候选）在现有连接上重报一次注册信息即可。
+  // 无条件全拆全建就是「每隔几分钟断一次 + 内存一直涨」的根因，别改回去。
+  const previous = config
+  const tunnelNeedsRebuild = tunnelSignature(previous) !== tunnelSignature(next)
+  const lanNeedsRebuild = lanSignature(previous) !== lanSignature(next)
+  const monitorNeedsRestart = monitorSignature(previous) !== monitorSignature(next)
   config = { ...next }
-  if (config.enabled) {
+  if (tunnelNeedsRebuild) {
+    stopTunnel()
     startTunnel()
+  }
+  if (lanNeedsRebuild) {
+    stopLan()
+    startLan()
+  }
+  if (!tunnelNeedsRebuild && tunnel) {
+    const patch = {}
+    if (previous.pairingCode !== config.pairingCode) patch.pairingCode = config.pairingCode
+    if (previous.name !== config.name) patch.name = config.name
+    if (lanNeedsRebuild) patch.lanUrls = currentLanUrls()
+    if (Object.keys(patch).length) tunnel.updateRegistration(patch)
+  }
+  if (monitorNeedsRestart) {
+    stopNetworkMonitor()
     startNetworkMonitor()
-    if (config.lanEnabled) startLan()
   }
   return status()
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.1.82",
+  "version": "0.1.85",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (0.2.0-rc.2 compatible, peers resolved by the host)",
   "license": "MIT",
   "type": "module",