dsh-mobile-plugin 0.1.82 → 0.1.84

package/lib/session-cleanup.cjs

@@ -9,11 +9,13 @@
  *    CANONICAL_LOG_FILENAME + compressionSuffix：0 代不带 vN，压缩时才带 .zstd）。
  *    曾经只认 `session.jsonl.zstd`，于是 0.2.0 真在用的 `session.v4.jsonl.zstd`
  *    一个都认不到 —— 表现是「清理已归档」恒回 `deleted: 0`，静默不删。
- *  - 删之前先从宿主归档集合里摘掉这些 id：宿主不会自己修剪，删完还留着就是「已归档」
- *    里一排点不开的死行，且每清一次只增不减。
  *  - 解压用 Node 自带的 zstd（DSH 自己就是这么读写日志的，宿主并不需要系统 zstd
  *    命令），不再 shell 出去：没装 zstd 命令的机器上它一缺就是 readHeader 静默返回
  *    undefined，整条删除路径空转。id 仍然取自日志第一行那条 header。
+ *  - **进程活着的时候不擦宿主的归档集合**，只删日志；擦集合放到宿主启动时
+ *    （pruneOrphanedArchivedSessionsOnce）。理由写在那个函数上：桌面端的会话列表是
+ *    连上宿主时拉的一份快照 + 之后的事件增量，进程里擦集合等于把已经删掉、却还留在
+ *    快照里的行放回正常列表。
  */
 'use strict'
 
@@ -24,6 +26,9 @@ const zlib = require('node:zlib')
 const DEFAULT_OLDER_THAN_MINUTES = 30
 const MINUTES = 60 * 1000
 
+/** 认为「宿主刚起来」的上限：装载插件只在这段时间里算启动，之后出现的调用只能是热替换。 */
+const BOOT_PRUNE_WINDOW_SECONDS = 60
+
 // 宿主认可的会话日志名。非规范名（迁移中途的临时文件、大写、前导零、带 v0）宿主自己
 // 也不认，这里同样不认 —— 认多了会把没提交的代次当会话删掉。
 const CANONICAL_LOG_FILENAME = /^session(?:\.v[1-9][0-9]*)?\.jsonl(?:\.zstd)?$/
@@ -128,18 +133,12 @@ async function deleteSessionData(sessionIds) {
 }
 
 /**
- * 把已经从磁盘删掉的 id 从宿主归档集合里擦掉（删除路径的最后一步，best-effort）。
- *
- * 宿主不会自己修剪这份集合：日志删了它照样留着那些 id，于是「已归档」里是一排点不开的
- * 死行，而且每清一次就多几条、只增不减。它排在 `deleteSessionData` **之后**：日志没删成
- * 前先擦集合，中途失败就会留下「已取消归档、日志还在」的会话——用户看到的是清理只把会话
- * 移出了归档，还要重启宿主才恢复。先删后擦则日志一没就是真的删掉了，立刻生效；擦失败最多
- * 留一行死行，重试即可。宿主对本来就未归档的 id 是 no-op。
+ * 把一批 id 从宿主归档集合里擦掉（宿主对本来就未归档的 id 是 no-op）。
  *
- * 只传**真删掉**的 id：没匹配到日志的还留着日志，擦掉它的名字只会让那一行消失而没有东西被删。
+ * 唯一的调用方是宿主启动时的孤儿修剪：进程活着的时候擦集合会把桌面端快照里那些已经
+ * 删掉的行放回正常列表，理由见 pruneOrphanedArchivedSessionsOnce。
  *
- * 返回擦失败的 id（`failed`），**不抛异常**：日志已经删成功，擦集合坏了不该让整条清理
- * 报错——那等于告诉用户「没删掉」，而事实上已经删掉了。
+ * 返回擦失败的 id（`failed`），**不抛异常**：修剪是收尾，一条擦不动不该让整轮修剪停摆。
  */
 async function forgetArchivedSessions(ctx, sessionIds, rpcId) {
   const failed = []
@@ -154,6 +153,69 @@ async function forgetArchivedSessions(ctx, sessionIds, rpcId) {
   return failed
 }
 
+/**
+ * 归档集合里那些日志确实已经不在磁盘上的 id。
+ *
+ * 判据是磁盘而不是宿主的会话列表：`sessions.list` 会不会漏一条（比如没有 cwd 的会话、
+ * 宿主服务还没装好）不是这里能判断的，而「归档集合里挂着、磁盘上已经没有日志」正是
+ * 清理真正删掉的那个状态。宿主把会话 id 原样当目录名（`encodeSegment` 对正常 id 恒等），
+ * 所以先用目录名筛掉绝大多数，只对候选读一遍 header 复核 —— 别为了修剪把整库日志解一遍。
+ */
+async function archivedIdsWithoutLogs(archivedSessionIds) {
+  const orphans = new Set(archivedSessionIds)
+  if (orphans.size === 0) return []
+  for (const file of sessionFiles(path.join(dshHome(), 'sessions'))) {
+    const name = path.basename(path.dirname(file))
+    if (!orphans.has(name)) continue
+    const header = await readHeader(file)
+    // 日志读不出来也算「还在」：宁可这一轮不修剪，也不能把一条还有日志的会话移出归档。
+    orphans.delete(name)
+    if (header && typeof header.id === 'string') orphans.delete(header.id)
+    if (orphans.size === 0) break
+  }
+  return [...orphans]
+}
+
+async function pruneOrphanedArchivedSessions(ctx) {
+  const workspaceList = ctx && ctx.apiProxy && ctx.apiProxy.workspace ? ctx.apiProxy.workspace.list : undefined
+  if (typeof workspaceList !== 'function') return 0
+  const rpcId = 'dsh-mobile-plugin-archive-prune'
+  const { value, error } = unwrap(await workspaceList({ rpcId, method: 'workspace.list', payload: {} }))
+  if (error) throw new Error(`workspace.list 失败：${error.message || error.code || '未知错误'}`)
+  const archived = value && Array.isArray(value.archivedSessionIds)
+    ? value.archivedSessionIds.filter((id) => typeof id === 'string' && id)
+    : []
+  const orphans = await archivedIdsWithoutLogs(archived)
+  if (orphans.length === 0) return 0
+  const failed = await forgetArchivedSessions(ctx, orphans, rpcId)
+  return orphans.length - failed.length
+}
+
+/**
+ * 宿主进程启动时修剪一次归档集合，然后整个进程不再碰。
+ *
+ * 这件事只能在启动这一刻做：桌面端的会话列表是「连上宿主时拉的一份快照 + 之后的事件
+ * 增量」，宿主本身没有「删除会话」的接口，插件在磁盘上删日志它也看不见。进程活着的时候
+ * 擦归档集合，宿主会把「归档集合变了」广播给桌面端，桌面端就把它快照里那些其实已经
+ * 没有日志、本来被归档藏着的行放回正常列表 —— 用户报的正是「清理后它们又回来了，重启
+ * DSH 才真的消失」。启动时桌面端还没连上（或正要重连，快照本来就从磁盘重新拉），擦掉
+ * 不会放出任何行。留在集合里的死 id 不显示在任何地方：「已归档」取的是会话列表与归档
+ * 集合的交集，没有日志就没有那一行。
+ *
+ * 用进程级标记而不是模块变量：代际热替换会重跑 apply，而桌面端那条快照挂在同一个进程上。
+ */
+const PRUNE_ONCE = Symbol.for('dsh-mobile-plugin.archived-prune')
+async function pruneOrphanedArchivedSessionsOnce(ctx, log) {
+  if (globalThis[PRUNE_ONCE]) return
+  globalThis[PRUNE_ONCE] = true
+  try {
+    const pruned = await pruneOrphanedArchivedSessions(ctx)
+    if (pruned > 0) log?.(`archived session prune: dropped ${pruned} deleted session ids`)
+  } catch (error) {
+    log?.(`archived session prune failed: ${error && error.message ? error.message : String(error)}`)
+  }
+}
+
 async function cleanupSessions(ctx, args) {
   const list = ctx.apiProxy?.sessions?.list
   const workspaceList = ctx.apiProxy?.workspace?.list
@@ -188,11 +250,9 @@ async function cleanupSessions(ctx, args) {
   }
   if (args.confirm !== true) throw new Error('永久删除需要 confirm: true')
   const ids = selected.map(item => item.sessionId)
-  // 与移动端那条路由同一口径：**先删日志、再擦归档集合**。反过来会在链路中途失败时
-  // 留下「名字已从归档集合消失、日志还在」的会话（看着像只是被移出了归档，得重启宿主
-  // 才恢复）；先删则日志一没就是真的删掉了，立刻生效。擦集合是收尾，失败不改变结果。
+  // 与移动端那条路由同一口径：**只删日志**，归档集合留到宿主下次启动时修剪。进程里擦
+  // 集合会把桌面端快照里那些已经删掉的行放回正常列表（见 pruneOrphanedArchivedSessionsOnce）。
   const deletedIds = await deleteSessionData(ids)
-  await forgetArchivedSessions(ctx, deletedIds, 'dsh-mobile-plugin-session-cleanup')
   return { action: args.action, cwd, selected: ids.length, archived: 0, deleted: deletedIds.length, failed: ids.length - deletedIds.length, sessionIds: deletedIds }
 }
 
@@ -219,4 +279,23 @@ function registerSessionCleanupTool(ctx) {
   }))
 }
 
-module.exports = { cleanupSessions, registerSessionCleanupTool, deleteSessionData, forgetArchivedSessions }
+/**
+ * 装配层的入口：注册 agent 的清理工具，同时在「宿主刚起来」时修剪一遍归档集合。
+ *
+ * 两件事都是会话清理的一部分，所以共用装配层那一处 effect；impl.js 有行数兜底守卫，
+ * 别把实现搬回去。
+ */
+function installSessionCleanup(ctx) {
+  // 「宿主启动时」不能只看进程级标记：升级到这份实现那次是**热替换**进来的（进程早就在跑），
+  // 标记还没被谁设过。那一刻桌面端的会话列表快照里可能正挂着之前删掉的行，擦集合就会把它们
+  // 放回列表。所以只在进程刚起的这点窗口里修剪；晚于它就留给下次启动。
+  if (process.uptime() <= BOOT_PRUNE_WINDOW_SECONDS) {
+    // 修剪先挂：没有 tools 注入的 profile 注册不了工具（外层会吞掉这条错），但归档集合照样要收尾。
+    void pruneOrphanedArchivedSessionsOnce(ctx, (message) => {
+      try { ctx.logger?.info?.(message) } catch { /* 日志失败不影响修剪 */ }
+    })
+  }
+  registerSessionCleanupTool(ctx)
+}
+
+module.exports = { cleanupSessions, registerSessionCleanupTool, installSessionCleanup, deleteSessionData, forgetArchivedSessions, pruneOrphanedArchivedSessions, pruneOrphanedArchivedSessionsOnce }

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')
+}