dsh-mobile-plugin 0.1.96 → 0.1.98

package/lib/relay/lan-proxy.js

@@ -14,7 +14,7 @@
 const http = require('node:http');
 const { WebSocketServer, WebSocket } = require('ws');
 const core = require('./core.js');
-const { isGlobalUnicastV6 } = require('./lan-network.cjs');
+const { advertisedCandidates, ipv6Candidates, isGlobalUnicastV6 } = require('./lan-network.cjs');
 const { safeEqual } = require('../shared/dshtoken');
 const { isFreshRequest } = require('../shared/fresh-request');
 const { encodeJsonBody } = require('../shared/http-util');
@@ -519,6 +519,13 @@ function createLanProxy(opts) {
                     const issued = credentials.issue(instanceId, device, token);
                     const cookieValue = core.signLanToken(lanSecret, instanceId, core.MOBILE_TOKEN_TTL_SEC);
                     setCookie(res);
+                    // 宿主自己那批直连候选一起回给手机：手输公网地址（域名 / 公网 IP）配对时，
+                    // 二维码那条路没有、也就只有这一处能拿到内网地址。回家后如果那个公网地址
+                    // 打不通（路由器不支持回环 / 域名只在外网解析），手机还能靠这批候选找到这台
+                    // 机器，否则只能删设备重配。App 的 `doPair` 本来就合并响应里的 `lanUrls`
+                    // 与 `ipv6Candidates`，这里不回它就只能记住手输的那一个地址。
+                    const directCandidates = advertisedCandidates(actualPort).map((candidate) => candidate.url).filter(Boolean);
+                    const v6Candidates = ipv6Candidates(actualPort).map((candidate) => candidate.url).filter(Boolean);
                     res.writeHead(200, { 'content-type': 'application/json' });
                     // cookie 同时放进 body：RN fetch 读不到 Set-Cookie 响应头，App 需自行携带
                     res.end(JSON.stringify({
@@ -526,6 +533,8 @@ function createLanProxy(opts) {
                       instanceId,
                       token: token || '',
                       cookie: `dsh_lan=${cookieValue}`,
+                      ...(directCandidates.length ? { lanUrls: directCandidates } : {}),
+                      ...(v6Candidates.length ? { ipv6Candidates: v6Candidates } : {}),
                       deviceId: issued.deviceId,
                       deviceCredential: issued.credential,
                       credentialExpiresAt: issued.expiresAt,

package/lib/routes/control-plane.js

@@ -49,6 +49,8 @@ const { checkForUpdate } = require('../update-registry.cjs');
 const { declaredSource } = require('../update-install.cjs');
 const { clearCompletionForAllDevices, invalidateSessionList } = require('../mobile/session-cache.js');
 const { recordSessionRead } = require('../mobile/session-last-turn.js');
+// 收件目录的占用与清理：和移动端那条路由是同一份实现（`lib/mobile/inbox-clean.js`）。
+const { scanInbox, clearInbox, usageView, setAutoClear } = require('../mobile/inbox-clean.js');
 
 /** 一次 desktop-read 上报最多带多少个会话 id（防灌爆；客户端半边一次最多也就几个）。 */
 const MAX_DESKTOP_READ_IDS = 200;
@@ -770,6 +772,38 @@ function registerControlPlaneRoutes(deps) {
       })
     }
   }) })
+  // ── 收件目录（手机分享进来的文件）──
+  //
+  // 同一份实现在移动端也有两条（`/api/mobile/v1/inbox/{status,clear}`），这里只是把它
+  // 开到网页面板上：面板与 App 读同一份扫描结果，两边不各算一套口径。
+  //
+  // 走 localOnly：清的是本机上那个固定收件目录，属于本机运维动作，和其余控制面一样。
+  // 面板侧也因此在网页管理窗口打不开时仍可由本机操作。
+  registerRoute({ kind: 'exact', path: '/api/relay/inbox/status', handler: localOnly('GET', async (_req, res) => {
+    sendJson(res, 200, usageView(await scanInbox()))
+  }) })
+  // 自动清理开关：默认关。打开后宿主每次启动顺手清一次（见 mobile/inbox-clean.js 的
+  // clearInboxOnce）。手动那颗「清理收件文件」不受它管 —— 那个是用户当场按的。
+  registerRoute({ kind: 'exact', path: '/api/relay/inbox/auto', handler: localOnly('POST', async (req, res) => {
+    let body = {}
+    try {
+      body = (await readJson(req)) || {}
+    } catch {
+      body = {}
+    }
+    if (typeof body.enabled !== 'boolean') return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'enabled 必须是布尔值' } })
+    try {
+      return sendJson(res, 200, { ok: true, data: { autoClear: setAutoClear(body.enabled) } })
+    } catch (error) {
+      return sendJson(res, 500, { ok: false, error: { code: 'write-failed', message: String(error?.message || error) } })
+    }
+  }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/inbox/clear', handler: localOnly('POST', async (_req, res) => {
+    // 面板上那颗按钮自带二次确认；这里不额外要 `confirm` 字段 —— 移动端那条要求它，
+    // 是因为那里没有既有的确认口径，而这一页的确认是界面自己的事。
+    const result = await clearInbox()
+    sendJson(res, 200, { ok: true, ...result })
+  }) })
 }
 
 // 路由字符串清单放在注册区之后，避免被按路由源码切片的契约测试误认为是真正的 handler。
@@ -801,6 +835,10 @@ const WEB_ACCESS_ROUTES = new Set([
   '/api/relay/restart-sidecar',
   // 开发机的「就地重载」：能换掉本机跑着的实现，属于最该只允许本机调的那一类。
   '/api/relay/reload-implementation',
+  // 收件目录的占用与清理（面板那张「收件文件」卡）。
+  '/api/relay/inbox/status',
+  '/api/relay/inbox/clear',
+  '/api/relay/inbox/auto',
 ]);
 
 // `panelDiagnosis` 一并导出，只为让 test/panel-artifact.test.cjs 能拿临时目录跑那三条分支：

package/lib/routes/mobile-api.js

@@ -23,6 +23,9 @@ const { sendJson } = require('../http/routing.js');
 const { orderCandidates } = require('../relay/lan-network.cjs');
 
 const sessions = require('../mobile/sessions.js');
+const sessionModelOptions = require('../mobile/session-model-options.js');
+const sessionFile = require('../mobile/session-file.js');
+const stats = require('../mobile/stats.js');
 const agentPresets = require('../mobile/agent-presets.js');
 const stream = require('../mobile/stream.js');
 const events = require('../mobile/events.js');
@@ -32,15 +35,19 @@ const workspaces = require('../mobile/workspaces.js');
 const archiveClean = require('../mobile/archive-clean.js');
 const sessionLog = require('../mobile/session-log.js');
 const hostSettings = require('../mobile/host-settings.js');
+const channels = require('../mobile/channels.js');
 const deepSeekAccount = require('../mobile/deepseek-account.js');
 const skills = require('../mobile/skills.js');
 const mobileCredentials = require('../mobile/credentials.js');
 const subagents = require('../mobile/subagents.js');
 const monitor = require('../mobile/monitor.js');
 const references = require('../mobile/references.js');
+const schedule = require('../mobile/schedule.js');
 const plugins = require('../mobile/plugins.js');
 const pluginUpdate = require('../mobile/plugin-update.js');
 const uploads = require('../mobile/uploads.js');
+const inboxClean = require('../mobile/inbox-clean.js');
+const git = require('../mobile/git.js');
 const pairing = require('../mobile/pairing.js');
 const { credentialsEntry } = require('../shared/credentials-entry.js');
 // 体检接口要自报身份：版本号只有一个来源，就是包自己的 package.json（与 relay/status.js 同）。
@@ -118,7 +125,18 @@ function registerMobileRoutes(deps) {
   registerRoute({
     kind: 'exact',
     path: '/api/mobile/v1/pair',
-    handler: pairing.createPairHandler({ state, core, credentials: credentialsEntry(), pairingApproval, log: (...args) => console.warn('[dsh-mobile-plugin] [pair]', ...args) }),
+    handler: pairing.createPairHandler({
+      state,
+      core,
+      credentials: credentialsEntry(),
+      pairingApproval,
+      // 配对响应顺手把宿主当前的直连候选带回去（与 `/connection-info` 同一份取值）：
+      // 手输公网地址配对时没有二维码，这是手机拿到内网地址的唯一机会。
+      lanCandidates: safeLanCandidates,
+      ipv6Candidates: safeIpv6Candidates,
+      lanPort: lanPortInUse,
+      log: (...args) => console.warn('[dsh-mobile-plugin] [pair]', ...args),
+    }),
   })
   // 局域网/中转连接信息。**这条由宿主自己回答**：中转只转发，不再代答。
   // 纯局域网配对（App 只扫到局域网二维码、完全不经中转）需要一个宿主自己回答的地址，
@@ -170,6 +188,8 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/session', sessions.handleSession)
   route('/api/mobile/v1/session/messages', sessions.handleMessages)
   route('/api/mobile/v1/session/attachment', sessions.handleSessionAttachment)
+  // 交付文件卡要的字节：只放行本会话 present 声明过的路径（见 mobile/session-file.js）。
+  route('/api/mobile/v1/session/file', sessionFile.handleSessionFile)
   route('/api/mobile/v1/session/send', sessions.handleSend)
   // 正文水位探针：App 进对话前先问一句「这条会话的正文到哪个水位了」，跟本地缓存水位
   // 一比就知道要不要重拉全量历史（几十字节换几兆）。**只读信号快照**：信号里没有就如实
@@ -182,7 +202,12 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/session/fork', sessions.handleFork)
   route('/api/mobile/v1/session/models', sessions.handleModels)
   route('/api/mobile/v1/session/select-model', sessions.handleSelectModel)
+  // 模型之外的附加选项（速度、输出详略……）：写一条已声明的行，落地是宿主自己的设置。
+  route('/api/mobile/v1/session/model-option', sessionModelOptions.handleModelOption)
   route('/api/mobile/v1/session/stats', sessions.handleStats)
+  // 统计总览（统计页）。账本落在宿主家里（`$DSH_HOME/mobile-stats.json`），与会话日志
+  // 无关：归档只是挪位置，清理删的是日志，历史数字都还在 —— 见 mobile/stats-ledger.cjs。
+  route('/api/mobile/v1/stats/overview', stats.handleStatsOverview)
   // 正文检索（宿主 session.search 的移动端代理）：只回 { sessionId, snippet }，
   // 标题 / 工作区由 App 用自己轮询到的会话列表拼接，见 mobile/sessions.js。
   route('/api/mobile/v1/session/search', sessions.handleSessionSearch)
@@ -226,6 +251,24 @@ function registerMobileRoutes(deps) {
   // 「清理所有已归档的对话」（侧栏归档视图的文字按钮）：按 workspace.list 的归档集合全量清理，
   // 且 body 必须带 confirm: true（磁盘删除不可恢复）。
   route('/api/mobile/v1/workspace/clear-archived', archiveClean.handleClearArchived)
+  // Git 管理器（docs/git-manager.md）：手机上的仓库概览 / 变更 / 历史 / 分支都是读，
+  // 暂存 / 提交 / 切分支是写。能力面是一组固定命名的动词，不接受透传命令；每个请求都带
+  // workspaceId 与（可选的）仓库根，插件再校验它确实属于这个项目识别出来的仓库。
+  route('/api/mobile/v1/git/repo', git.handleGitRepo)
+  route('/api/mobile/v1/git/status', git.handleGitStatus)
+  route('/api/mobile/v1/git/diff', git.handleGitDiff)
+  route('/api/mobile/v1/git/log', git.handleGitLog)
+  route('/api/mobile/v1/git/show', git.handleGitShow)
+  route('/api/mobile/v1/git/branches', git.handleGitBranches)
+  route('/api/mobile/v1/git/overview', git.handleGitOverview)
+  route('/api/mobile/v1/git/stage', git.handleGitStage)
+  route('/api/mobile/v1/git/unstage', git.handleGitUnstage)
+  route('/api/mobile/v1/git/commit', git.handleGitCommit)
+  route('/api/mobile/v1/git/checkout', git.handleGitCheckout)
+  // 推当前分支到它的上游：只做这一档，不收分支名 / 远端名 / force 开关。
+  route('/api/mobile/v1/git/push', git.handleGitPush)
+  // AI 写提交信息：只读 `git diff --cached`，调宿主 llm 服务，回一行文案；不提交、不推送。
+  route('/api/mobile/v1/git/commit-message', git.handleGitCommitMessage)
   // 桌面端 `/export` 其实是两步：命令本身只留一行 transcript 标记，真正的下载由
   // @deepseek-ai/dsh-session-log-export 在浏览器侧监听 command/executed 后拉
   // `GET /api/session.export` 完成。手机端没有浏览器下载管理器，而那个端点绑在宿主
@@ -242,6 +285,16 @@ function registerMobileRoutes(deps) {
   // 改设置：与桌面端同一个 settings.mutate（按路径寻址的 op + expectedRevision 乐观并发）。
   route('/api/mobile/v1/host-settings/mutate', hostSettings.handleHostSettingsMutate)
   route('/api/mobile/v1/llm/providers', hostSettings.handleLlmProviders)
+  // 宿主的模型目录（`llm.models`）：每个提供方下面真正可请求的模型 id，给「用哪个模型做
+  // AI commit」这类选择器用 —— 它不需要活动会话，与 `/session/models` 不是一回事。
+  route('/api/mobile/v1/llm/models', hostSettings.handleLlmModels)
+  // 渠道管理（见 mobile/channels.js）：只对「本机自建」那一类（`llm-pi-ai` 里的路由）
+  // 提供增删；插件 / 宿主注册的提供方只列出来，一个写操作都不做。获取模型由宿主代问
+  // （端点常在内网，手机直连未必通），与桌面面板的 `discoverModels` 同一条路。
+  route('/api/mobile/v1/channels', channels.handleChannels)
+  route('/api/mobile/v1/channels/discover', channels.handleChannelDiscover)
+  route('/api/mobile/v1/channels/save', channels.handleChannelSave)
+  route('/api/mobile/v1/channels/delete', channels.handleChannelDelete)
   // 技能目录（宿主 skill.list 的移动端只读代理）。桌面端敲「/」时命令候选菜单里
   // 混着技能（@deepseek-ai/dsh-client-ui-skill 注册的 inputTriggers source），
   // 手机端此前只有 commands.list 的命令目录，技能一个都看不到，见 mobile/skills.js。
@@ -268,6 +321,15 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/file-references', references.handleFileReferences)
   route('/api/mobile/v1/session-references', references.handleSessionReferences)
 
+  // 定时任务（宿主 ScheduleService 的移动端代理）：目录、会话内 active 任务、运行记录、
+  // 删除。桌面端有一套完整的定时任务面板，手机端此前一条都看不到；服务同进程直查
+  // `ctx.get('schedule')`，宿主没有它时这四条统一回 503 而不是空列表，
+  // 见 mobile/schedule.js。`update` 这一批没接：手机端还没有编辑入口。
+  route('/api/mobile/v1/schedule/catalog', schedule.handleScheduleCatalog)
+  route('/api/mobile/v1/schedule/list', schedule.handleScheduleList)
+  route('/api/mobile/v1/schedule/history', schedule.handleScheduleHistory)
+  route('/api/mobile/v1/schedule/delete', schedule.handleScheduleDelete)
+
   // 桌面端 设置 → 插件 的只读部署快照，由 dsh-host-plugin-inventory 拥有，
   // 经 typertGateway 命名空间 pluginInventory 取，见 mobile/plugins.js。
   route('/api/mobile/v1/plugins', plugins.handlePlugins)
@@ -288,6 +350,13 @@ function registerMobileRoutes(deps) {
   route('/api/mobile/v1/upload/chunk', uploads.handleUploadChunk)
   route('/api/mobile/v1/upload/finish', uploads.handleUploadFinish)
   route('/api/mobile/v1/upload/abort', uploads.handleUploadAbort)
+  // 同一个收件目录的出口：上面四条只往里放，这两条报占用、按龄清掉（见 mobile/inbox-clean.js）。
+  // 落盘的文件不认识会话，所以没有「删掉这条对话就顺带清掉它传上来的文件」这条路 ——
+  // 唯一的出口只能按龄，口径写在那个文件头。
+  route('/api/mobile/v1/inbox/status', inboxClean.handleInboxStatus)
+  route('/api/mobile/v1/inbox/clear', inboxClean.handleInboxClear)
+  // 自动清理开关：默认关，打开后宿主每次启动顺手清一次（面板那颗按钮不受它管）。
+  route('/api/mobile/v1/inbox/auto', inboxClean.handleInboxAuto)
 
   // 内置浏览器预览（App 侧「点 localhost 链接在内置浏览器里打开」的宿主端一半）。
   //

package/lib/session-cleanup.cjs

@@ -46,6 +46,8 @@ const HEADER_MAX_BYTES = 64 * 1024
 
 const { envelopeValue, unwrap } = require('./mobile/envelope.js')
 const { rememberDeletedSessionIds } = require('./mobile/session-cache.js')
+// 收件目录的启动清理与这里共用同一个「宿主刚起来」的窗口，实现见 mobile/inbox-clean.js。
+const { clearInboxOnce } = require('./mobile/inbox-clean.js')
 
 function asItems(response) {
   const value = envelopeValue(response)
@@ -469,6 +471,12 @@ function installSessionCleanup(ctx) {
     void pruneOrphanedArchivedSessionsOnce(ctx, (message) => {
       try { ctx.logger?.info?.(message) } catch { /* 日志失败不影响修剪 */ }
     })
+    // 收件目录（手机分享进来的文件）也在这里顺手清一次：它只进不出，不点按钮就没人管。
+    // 与上面那条同一个「宿主刚起来」的窗口，但两者互不依赖 —— 收件目录的口径只看 mtime，
+    // 碰不到任何会话日志（见 mobile/inbox-clean.js 的文件头）。
+    void clearInboxOnce((message) => {
+      try { ctx.logger?.info?.(message) } catch { /* 日志失败不影响清理 */ }
+    })
   }
   registerSessionCleanupTool(ctx)
 }

package/lib/shared/sse-write.js

@@ -11,10 +11,11 @@
  * 事件 id 怎么算」「写不动时怎么等 drain」都只在这里，两条流只在调用点上声明自己的策略。
  *
  * 两条流刻意保留的差异（不是遗漏，改之前先看各自的理由）：
- *  - 丢帧口径：会话流的软水位只丢**没有 seq** 的增量（`assistant/chunk` 是草稿，同一轮
- *    收尾的 `assistant/message` 带完整正文、重连 `replaySince` 能补齐）；设备级流的帧
- *    全是「有东西变了」的幂等信号，软水位一律丢，下一次变更或重连补发会再补上。
- *    由调用方传 `shedWhenBuffered`。
+ *  - 丢帧口径：会话流的软水位只丢**明确可丢的增量**（只有 `assistant/chunk` 草稿：同一轮
+ *    收尾的 `assistant/message` 带完整正文、重连 `replaySince` 能补齐）。`session/queue`、
+ *    `session/jobs`、`session/resync-required` 这些控制帧没有 seq，但绝不能丢；设备级流的
+ *    帧全是「有东西变了」的幂等信号，软水位丢弃后由调用方**断流重连**并用
+ *    `replayKnownSignals()` 补发。由调用方传 `shedWhenBuffered`。
  *  - 写不动时：会话流 `await` 一次 drain（20s 超时再收尾）；设备级流直接收尾让客户端
  *    重连 —— 它没有 Last-Event-ID 续传，但连上时会 `replayKnownSignals()` 补发当前状态，
  *    所以「断开重连」是它的正常收敛路径。
@@ -42,8 +43,18 @@ const SSE_CLOSE_BUFFERED_BYTES = 16 * 1024 * 1024;
  */
 const SSE_DRAIN_TIMEOUT_MS = 20_000;
 
-/** 默认丢帧口径：没有 seq 的帧可以丢，有 seq 的不能（丢了不回放就在手机上留个洞）。 */
-const shedWithoutSeq = (payload) => !Number.isFinite(payload && payload.seq);
+/**
+ * 默认丢帧口径：只有**明确可丢**的无 seq 增量帧可以丢；有 seq 的一律不能丢。
+ *
+ * 旧实现是「没有 seq 就丢」，结果把 `session/queue` / `session/jobs` /
+ * `session/resync-required` 这些控制帧一起丢了 —— 它们没有 seq，但丢了没有回放路径，
+ * 队列/任务面板会永久停在旧状态，gap 提示也到不了客户端。
+ */
+const SHEDDABLE_INCREMENTAL_TYPES = new Set(['assistant/chunk']);
+const shedWithoutSeq = (payload) => {
+  if (!payload || !SHEDDABLE_INCREMENTAL_TYPES.has(payload.type)) return false;
+  return !Number.isFinite(payload.seq);
+};
 
 /** 每条记录后面补的 SSE 注释（客户端忽略内容，只用来把小 chunk 撑过 RN 的缓冲阈值）。 */
 function ssePadding(bytes) {

package/lib/shell/device-ota.js

@@ -72,20 +72,70 @@ 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 })
 }
+/**
+ * 把**正在跑的那一代**复制成一份能从盘上回退的包（`<root>/<version>/dsh-mobile-plugin`）。
+ *
+ * 为什么必须复制：包管理器装新版会把旧的 store 目录整个带走，旧代码从此只剩内存里那一份。
+ * 新版装上了却起不来时，外壳当场回滚到内存里那份（看着一切正常）；可**下次重启**就只能拿
+ * 盘上那份坏的去装载，所有代都失败 = 插件整个不在（手机连不上、面板也没有）。回退目录本来
+ * 就是干这个的（`availableOta` 列出来，启动时按版本从高到低逐个试），缺的只是「有人往里放
+ * 一份能跑的」。
+ *
+ * 调用点是「真正要装之前」（见 `updater.js` 的 `beforeInstall`），所以拿到的就是那份还在跑、
+ * 还装得上的代码。`node_modules` 不复制：那是 profile 的依赖树，复制既慢又会被相对布局骗到；
+ * 落在 profile 里的这一代与 OTA 代走同一条解析链（见 `manager.js` 的 `moveOtaRootIntoProfile`）。
+ *
+ * 不抛错：备份是「多一层保险」，它失败不该挡住一次更新 —— 原因如实回给调用方去记日志。
+ */
+export function snapshotGeneration(sourceDir, version) {
+  if (!validVersion(version) || typeof sourceDir !== 'string' || !sourceDir) {
+    return { created: false, error: '版本号或目录不可用' }
+  }
+  const target = path.join(ROOT(), version, PACKAGE)
+  if (fs.existsSync(path.join(target, 'lib', 'impl.js'))) return { created: false, existing: true, dir: target }
+  let source = sourceDir
+  try {
+    source = fs.realpathSync(sourceDir)
+  } catch {
+    return { created: false, error: '要备份的那一代已经读不到了' }
+  }
+  if (!fs.existsSync(path.join(source, 'lib', 'impl.js'))) return { created: false, error: '要备份的那一代缺 lib/impl.js' }
+  fs.mkdirSync(ROOT(), { recursive: true })
+  // 先落到 `.staging-*`（`availableOta` 与 `sweepStaging` 都按这个前缀跳过/回收），
+  // 复制完整了再一次性改名为 `<version>`：半个包不能被当成一代。
+  const staging = fs.mkdtempSync(path.join(ROOT(), '.staging-fallback-'))
+  try {
+    fs.cpSync(source, path.join(staging, PACKAGE), {
+      recursive: true,
+      // 软链接按实体复制：旧布局里凭据包有时是「与插件包同级」的链接，照着链子复制会在旧目录
+      // 被删之后悬空 —— 这一份必须自己就装得起来，所以把链接指向的内容抄实。
+      dereference: true,
+      filter: entry => path.basename(entry) !== 'node_modules',
+    })
+    fs.rmSync(path.join(ROOT(), version), { recursive: true, force: true })
+    movePath(staging, path.join(ROOT(), version))
+    return { created: true, dir: target }
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true })
+    return { created: false, error: String((error && error.message) || error) }
+  }
+}
 export function createDeviceOta({ fetchImpl = fetch, installed = () => null, platform = PLATFORM, channel = CHANNEL, runtime = null } = {}) {
   async function reconcileOfficial() {
     const active = runtime?.status()
     const officialVersion = installed()
     if (!runtime || !validVersion(officialVersion)) return { switched: false, status: active ?? null }
     if (active?.source === 'installed') {
-      clearSuperseded(officialVersion)
+      // 只有「跑着的就是他盘上那一版」才算接管成功，这时才回收回退包。
+      // 换代失败时跑着的仍是旧版、盘上已是新版 —— 那份副本是下次重启唯一的活路，不能删。
+      if (active.version === officialVersion) clearSuperseded(officialVersion)
       return { switched: false, status: active }
     }
     if (active?.source !== 'ota' || !validVersion(active.version) || compareVersion(officialVersion, active.version) < 0) {
       return { switched: false, status: active ?? null }
     }
     const status = await runtime.reload()
-    if (status?.source === 'installed') clearSuperseded(officialVersion)
+    if (status?.source === 'installed' && status.version === officialVersion) clearSuperseded(officialVersion)
     return { switched: status?.source === 'installed', status }
   }
   /** 问一次中转「我该装哪个版本」；没有就返回 null（不抛）。 */

package/lib/shell/manager.js

@@ -32,7 +32,7 @@ import fs from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
-import { availableOta, configureOtaRoot } from './device-ota.js'
+import { availableOta, configureOtaRoot, snapshotGeneration } from './device-ota.js'
 import { movePath } from './ota-package.js'
 import { dshHome } from '../shared/paths.js'
 
@@ -161,6 +161,20 @@ export function installedVersion() {
   return dir ? readPackageVersion(path.join(dir, 'package.json')) : null
 }
 
+/**
+ * 装之前把**正在跑的那一代**备份进回退目录（换代的保险，见 `device-ota.js` 的
+ * `snapshotGeneration`：包管理器一跑就把旧目录带走了）。
+ *
+ * 只有「跑着的就是盘上装着的那一代」才备份 —— 跑 OTA 代时盘上那份不是活代码，复制它对不上号。
+ * 返回 `snapshotGeneration` 的结果，拿不到就回 null（备份失败不该挡住更新）。
+ */
+export function snapshotRunningGeneration(running) {
+  const dir = installedPackageDir()
+  if (!dir || !running || !running.version || running.source !== 'installed') return null
+  if (installedVersion() !== running.version) return null
+  return snapshotGeneration(dir, running.version)
+}
+
 /**
  * 取版本号最高的代。
  *

package/lib/shell/updater.js

@@ -31,7 +31,7 @@ import path from 'node:path'
 import { createHash } from 'node:crypto'
 import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
-import { installedPackageDir, installedVersion, profileNodeModules } from './manager.js'
+import { installedPackageDir, installedVersion, profileNodeModules, compareVersion } from './manager.js'
 
 const require_ = createRequire(import.meta.url)
 const { dshHome } = require_('../shared/paths.js')
@@ -82,7 +82,7 @@ function installedPackageDirSafe() {
  */
 export function shellFingerprint(pkgDir) {
   if (!pkgDir) return null
-  const files = ['lib/index.js', 'lib/shell/runtime.js', 'lib/shell/manager.js', 'lib/shell/updater.js']
+  const files = ['lib/index.js', 'lib/shell/runtime.js', 'lib/shell/manager.js', 'lib/shell/updater.js', 'lib/shell/device-ota.js', 'lib/shell/ota-package.js']
   const hash = createHash('sha256')
   let seen = 0
   for (const rel of files) {
@@ -227,7 +227,7 @@ const TERMINAL = new Set(['succeeded', 'failed', 'cancelled', 'rolled-back'])
  * 装完了但盘上版本没变（市场报成功、文件没落），这里如实返回 `installed: false`，不让调用方
  * 以为换过代码 —— 「状态说成功、代码没换」是这个仓库吃过最贵的一次亏。
  */
-export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false, onEvent = () => {}, packageManager = () => null, agents = () => null, now = Date.now } = {}) {
+export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false, onEvent = () => {}, packageManager = () => null, agents = () => null, beforeInstall = null, now = Date.now } = {}) {
   const before = installedVersion()
   // 装归实现自己（2026-10-11 起）：盘上那一代里有 `update-install.cjs` 就走它。判定（有没有
   // 新版、`link:` 来源不碰、有 agent 在跑就先别换文件）也一并交给它，别在这里抄第二份 ——
@@ -242,6 +242,8 @@ export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false
       // 实现在代里，它没有宿主 ctx，只有外壳有。
       packageManager: packageManager(),
       agents: agents(),
+      // 装之前把正在跑的那一代备份走：包管理器一跑，旧目录就没了。
+      beforeInstall,
     })
     return {
       installed: outcome.installed === true,
@@ -307,18 +309,163 @@ export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false
   }
 }
 
+/**
+ * 换代尝试的记账：同一个版本自动只试一次。
+ *
+ * 一个起不来的新版每 10 分钟把手机抖一下没有任何意义 —— 第一次失败之后就该停下，等人按
+ * 那颗按钮（手动不受这个限制：那是「我知道，再来一次」）。进程重启后这份记录清零，
+ * 而重启本来就会走一遍正常装载，不需要它。
+ */
+const swapAttempts = new Map()
+
+/** 同一时刻只跑一次更新：自动轮询与手按按钮撞一起时，第二个直接等第一次的结果。 */
+let applying = null
+
+/**
+ * 一次完整的更新：装（若需要）→ 换代 → 落账。
+ *
+ * 手动与自动走的是同一个函数 —— 自动只是「没人按」的那一种（`auto: true`）。
+ * 账必须**成功失败都落**：这套东西最贵的一次教训是「状态说成功、代码没换」，第二贵的是
+ * 「失败了但没人记得」，面板与手机都靠这本账判结果，漏落一次它们就永远停在上一次。
+ */
+export function performUpdate(options = {}) {
+  if (applying) return applying
+  applying = runUpdate(options).finally(() => { applying = null })
+  return applying
+}
+
+async function runUpdate({ runtime, base, hostService = () => null, updateState, beforeInstall = null, log = () => {}, force = false, auto = false } = {}) {
+  const status = () => {
+    try { return runtime.status() ?? {} } catch { return {} }
+  }
+  const beforeVersion = installedVersion() ?? status().version ?? null
+  const runningBefore = status().version ?? null
+  let outcome
+  try {
+    outcome = await installIfNeeded(base, {
+      force,
+      beforeInstall,
+      packageManager: () => hostService('profileContext')?.packageManager ?? null,
+      agents: () => hostService('agents'),
+    })
+  } catch (error) {
+    // 装那步就炸了（注册表 / 网络 / 权限）：账照样要落，否则面板停在上一轮、手机那边
+    // 只能等到超时才说得出「没成」。
+    const message = String(error?.message || error)
+    updateState.lastApply = {
+      installed: false,
+      skipped: false,
+      state: 'failed',
+      beforeVersion,
+      installedVersion: beforeVersion,
+      swapped: false,
+      restartRequired: false,
+      refreshRequired: false,
+      retryable: false,
+      failure: { code: 'install_failed', message },
+    }
+    updateState.appliedAt = new Date().toISOString()
+    updateState.lastError = message
+    throw error
+  }
+
+  const disk = installedVersion()
+  // 要换代时换到**盘上那一份**：装成功了是它；「早就装上了、只是没换过来」也是它。
+  const newerOnDisk = disk !== null && runningBefore !== null && compareVersion(disk, runningBefore) > 0
+  let swapped = false
+  let swapFailure = null
+  let deferred = false
+  if (outcome.installed === true || newerOnDisk) {
+    const attempt = await swapTo(runtime, disk ?? runningBefore, { auto, log })
+    swapped = attempt.swapped
+    swapFailure = attempt.failure
+    deferred = attempt.deferred === true
+  }
+  const lastApply = {
+    ...outcome,
+    installed: outcome.installed === true,
+    swapped,
+    state: swapFailure ? 'installed-not-swapped' : (outcome.state ?? (outcome.installed || outcome.skipped ? 'succeeded' : 'failed')),
+    failure: swapFailure ?? outcome.failure ?? null,
+    // 换代由外壳就地做，市场那套「装完要重启」在本项目一律不照做。只为如实上报。
+    restartRequired: false,
+    refreshRequired: false,
+  }
+  updateState.lastApply = lastApply
+  updateState.appliedAt = new Date().toISOString()
+  if (lastApply.installed && !swapFailure) updateState.lastError = null
+  if (swapFailure && !deferred) {
+    // 装上了、换不过来：抛给路由（桌面按 500 + `swap_failed` 说人话），账已经落了，
+    // 手机读 status 也能立刻判出结果，不必等到超时。
+    throw new Error(swapFailure.message)
+  }
+  return { ...lastApply, status: status() }
+}
+
+/**
+ * 换到盘上那一代。
+ *
+ * 失败只回错误、不抛：调用方要先落账再决定要不要抛。`auto` 为真时同一版本只试一次
+ * （见 `swapAttempts`），手动调用不受限制。
+ */
+async function swapTo(runtime, target, { auto = false, log = () => {} } = {}) {
+  const key = String(target ?? '')
+  const tried = swapAttempts.get(key) ?? 0
+  if (auto && tried >= 1) {
+    return {
+      swapped: false,
+      deferred: true,
+      failure: {
+        code: 'swap_deferred',
+        message: `盘上的 ${key} 已经自动试过一次换代、没成：重启一次 DSH 才会用它，或者再按一次更新重试。`,
+      },
+    }
+  }
+  swapAttempts.set(key, Math.max(tried, 1))
+  try {
+    const status = await runtime.reload()
+    swapAttempts.delete(key)
+    log('info', 'dsh-mobile-plugin: 已就地换到 %s（无需重启 DSH）', status?.version ?? key)
+    return { swapped: true, status }
+  } catch (error) {
+    return {
+      swapped: false,
+      failure: { code: 'swap_failed', message: `新版已经装到盘上（${key}），但换代码没成：${String(error?.message || error)}` },
+    }
+  }
+}
+
+/**
+ * 盘上比运行中新：补一次换代。
+ *
+ * 什么时候会走到这里：上一次换代失败了（回滚到旧代继续跑，盘上已是新版），或者新版是别的
+ * 途径装进来的（市场界面、手工装）。这两种情况下盘上的代码不会自己生效 —— 而这个插件存在
+ * 的理由就是「不用重启 DSH」，所以它得自己补上这一步。
+ */
+export async function reconcileInstalledGeneration({ runtime, log = () => {} } = {}) {
+  let running = null
+  try { running = runtime.status()?.version ?? null } catch { return null }
+  const disk = installedVersion()
+  if (!disk || !running || compareVersion(disk, running) <= 0) return null
+  // 不在这里喊话：真去换时 `swapTo` 会记成功、失败那条下面自己记。卡住的机器每 10 分钟
+  // 一行「补一次换代」纯属噪声，而真相在 `lastApply`（面板「运行中 / 盘上」两列也在报）。
+  const attempt = await swapTo(runtime, disk, { auto: true, log })
+  if (attempt.failure && !attempt.deferred) log('warn', 'dsh-mobile-plugin: %s', attempt.failure.message)
+  return attempt.status ?? null
+}
+
 /** 自动更新开关的落盘文件：`<DSH_HOME>/storages/mobile-plugin/auto-update.json`。 */
 function autoUpdateFile() {
   return path.join(dshHome(), 'storages', 'mobile-plugin', 'auto-update.json')
 }
 
-/** 读开关。读不到 / 读坏了都当「关」——自动装东西这种事，缺省必须在用户这一侧。 */
+/** 未设置过默认自动更新；显式关闭保持关闭，配置损坏时不改动盘上插件。 */
 export function autoUpdateEnabled() {
   try {
     const raw = JSON.parse(fs.readFileSync(autoUpdateFile(), 'utf8'))
     return raw?.enabled === true
-  } catch {
-    return false
+  } catch (error) {
+    return error?.code === 'ENOENT'
   }
 }
 

package/lib/update-install.cjs

@@ -281,6 +281,8 @@ function run(command, args, { cwd, env, timeoutMs, spawnImpl = spawn }) {
  * @param {string} options.profileNodeModules profile 的 `node_modules` 目录
  * @param {string} options.version           要装的版本（注册表给的）
  * @param {boolean} [options.force]          true = 跳过「新发布先晾一会儿」的门槛
+ * @param {() => any} [options.beforeInstall] 真正跑包管理器**之前**调一次（外壳用它把正在跑的
+ *   那一代复制进回退目录）。包管理器一跑就把旧的 store 目录清掉了，晚一步没得复制。
  * @returns {Promise<{installed, skipped, beforeVersion, installedVersion, source, command, output, failure}>}
  */
 async function installLatest({
@@ -296,6 +298,7 @@ async function installLatest({
   // 宿主发布的调用方式（`profileContext.packageManager`）。**优先用它**，理由见
   // `normalizeInvocation` 的文件注释（版本对不上会把 profile 的 store 认错）。
   packageManager = null,
+  beforeInstall = null,
   onEvent = () => {},
 } = {}) {
   const beforeVersion = installedVersion(profileNodeModules, name);
@@ -356,6 +359,14 @@ async function installLatest({
     );
   }
 
+  // 备份正在跑的那一代：包的活就落在下面那一行 spawn 上，它一跑旧目录就没了。
+  // 备份失败不该挡住更新（那是多一层保险），所以这里吞掉它的异常，由调用方记日志。
+  if (typeof beforeInstall === 'function') {
+    try {
+      await beforeInstall({ beforeVersion, command: null });
+    } catch { /* 备份失败不挡更新 */ }
+  }
+
   const spec = `${name}@${version}`;
   const releaseAgeFlag = '--config.minimum-release-age=0';
   const args = picked.manager === 'pnpm'