dsh-mobile-plugin 0.4.0 → 0.4.4

package/lib/shared/list-revision.js

@@ -3,21 +3,12 @@
 /**
  * 清单内容指纹（sessions / workspaces 共用）。
  *
- * 存在的理由：手机端有两件事需要「这份清单和上次是不是同一份」——
+ * 两处要用：列表响应带 `revision`，App 连同 `generatedAt` 存进快照就能说清数据是什么时候的；
+ * 镜像推送每 500ms 完整构建一次清单，内容没变时比对 revision 就能安全跳过。
  *
- *  1. 数据新鲜度：列表响应带 `revision`，App 把它连同 `generatedAt` 一起存进快照，
- *     就能把「数据是谁在什么时候给的」显示给用户，而不是让用户自己猜；
- *  2. 镜像推送判重（见 lib/mirror/pusher.cjs）：后台 500ms tick 每轮都会完整构建
- *     sessions + workspaces，内容没变时推送一份字节完全相同的 payload 纯属浪费，
- *     比对 revision 就能安全跳过。
- *
- * 为什么用内容哈希而不是自增序号：插件随桌面 harness 频繁重启，内存里的序号每次
- * 都从 0 开始，重启后第一份快照会因为「序号变了」而被当成新内容重推一遍；内容哈希
- * 跨重启稳定（同样的清单 → 同样的 revision），这才是判重想要的性质。
- *
- * 为什么用 sha1 而不是更省的 32 位哈希：这个值会被用来**跳过推送**，一次碰撞就等于
- * 一份该推的新数据被静默丢掉。sha1 足够便宜（清单量级下每 tick 亚毫秒），不值得为
- * 几个字节冒这个风险。截断到 16 个十六进制字符只是为了让日志短一点。
+ * 用内容哈希而不是自增序号：插件随桌面 harness 频繁重启，序号每次都从 0 开始，重启后第一份
+ * 快照会被当成新内容重推。用 sha1 而不是 32 位哈希：这个值会被用来跳过推送，一次碰撞等于
+ * 一份该推的新数据被静默丢掉。截断到 16 个十六进制字符只是为了让日志短一点。
  */
 
 const crypto = require('node:crypto');

package/lib/shared/session-signal.js

@@ -3,24 +3,15 @@
 /**
  * 设备级「某个会话的正文水位涨了」信号总线。
  *
- * 与 list-signal.js（清单变了）是同一形状的第二条通道，存在的理由是对话页的第二种场景：
- * 手机上**没有打开**某个会话时，那条会话的正文此前完全没人订阅 —— 只有打开的会话才建
- * `session/stream`（app/src/hooks/useChatStream.ts 的唯一调用点），所以「在别的地方盯着
- * 列表」时，运行中的助手回复只能等下一次点开该会话才被拉下来。
+ * 与 list-signal（清单变了）形状相同，但管的是另一种场景：手机上没打开某个会话时，那条会话
+ * 的正文没人订阅，运行中的回复只能等下次点开才拉下来。插件本来就把正文推进了中转镜像，缺的
+ * 只是「这个会话的正文又长了，可以来取」这句通知。
  *
- * 而插件这边本来就把正文推到了中转镜像：镜像调度器（lib/mirror/pusher.cjs）每轮为高优先
- * 会话（运行中 / 5 分钟内动过）构建 200 条消息快照，冷会话每 500ms 轮转补一个。缺的只是
- * 「这个会话的正文又长了，你（手机）可以来取」这一句通知，本模块就是那个出口。
+ * 清单信号是全局的（一个 revision），这条是按会话的（sessionId → 已广播的消息水位 seq）。
+ * 水位取快照里真正装上的消息的最大 seq，与 App 侧缓存水位同一个 seq 空间。
  *
- * 与 list-signal 的关键差别：清单信号是**全局**的（一个 revision），这条是**按会话**的
- * （sessionId → 已广播到的消息水位 seq）。水位取的是快照里**真正装上的消息的最大 seq**
- * （见 pusher 的 messageWatermarkOf），也就是 App 侧会话缓存的水位口径（同一个 seq 空间），
- * 手机拿它和自己的缓存水位一比就知道该不该增量拉一次。
- *
- * 为什么是模块级单例：生产端（mirror/pusher.cjs，CJS）与消费端（mobile/events.js，CJS）
- * 都 require 到同一个实例，两边不需要认识对方；测试可以 createSessionSignal() 造独立实例。
- * 为什么订阅者抛错要吞掉：bus 的调用方是镜像推送链，一条写坏的 SSE 连接不能把推送拖垮
- * （真故障会从连接自身的 close 反映出来）。
+ * 做成模块级单例：生产端与消费端 require 到同一个实例，互不认识；测试可以自己造实例。
+ * 订阅者抛错要吞掉——bus 的调用方是镜像推送链，一条写坏的 SSE 连接不能把推送拖垮。
  */
 
 const NOOP_RELEASE = () => {};

package/lib/shared/sse-write.js

@@ -1,26 +1,20 @@
 'use strict';
 
 /**
- * SSE 写帧的唯一实现：单会话流（lib/mobile/stream.js）与设备级流（lib/mobile/events.js）
- * 共用这一份。
+ * SSE 写帧的唯一实现：单会话流（lib/mobile/stream.js）与设备级流（lib/mobile/events.js）共用。
  *
- * 为什么要合并：两条流曾经各有一份几乎相同的实现，而 2026-10-17 的宿主 OOM（堆快照里
- * 17.6 万条 SSE 帧、466MB 挂在 `WriteWrap._chunks` 上，七十分钟涨到 3.9G 被杀）先修了
- * 会话流那份，隔一轮才发现设备流那份还漏着 —— 同一个坑修两遍，就是因为实现有两份。
- * 现在「这条连接上到底积压了多少字节」「软/硬水位怎么判」「SSE 记录长什么样」「稳定
- * 事件 id 怎么算」「写不动时怎么等 drain」都只在这里，两条流只在调用点上声明自己的策略。
+ * 合并是因为两份实现会让同一个坑修两遍：宿主 OOM 时先修了会话流那份，隔一轮才发现设备流那份
+ * 还漏着。现在积压字节数、软/硬水位、SSE 记录形状、稳定事件 id、等 drain 都只在这里，两条流
+ * 只在调用点声明自己的策略。
  *
- * 两条流刻意保留的差异（不是遗漏，改之前先看各自的理由）：
- *  - 丢帧口径：会话流的软水位只丢**明确可丢的增量**（只有 `assistant/chunk` 草稿：同一轮
- *    收尾的 `assistant/message` 带完整正文、重连 `replaySince` 能补齐）。`session/queue`、
- *    `session/jobs`、`session/resync-required` 这些控制帧没有 seq，但绝不能丢；设备级流的
- *    帧全是「有东西变了」的幂等信号，软水位丢弃后由调用方**断流重连**并用
- *    `replayKnownSignals()` 补发。由调用方传 `shedWhenBuffered`。
- *  - 写不动时：会话流 `await` 一次 drain（20s 超时再收尾）；设备级流直接收尾让客户端
- *    重连 —— 它没有 Last-Event-ID 续传，但连上时会 `replayKnownSignals()` 补发当前状态，
- *    所以「断开重连」是它的正常收敛路径。
- *  - 填充：会话流每条记录补 2048 字节 SSE 注释（Android RN 的 XHR 会攒小 chunk，
- *    不补就迟迟不触发 onprogress）；设备级流的帧很少、单帧也小，不补。
+ * 两条流刻意保留的差异（改之前先看理由）：
+ * - 丢帧口径：会话流的软水位只丢明确可丢的增量（`assistant/chunk` 草稿，收尾的
+ *   `assistant/message` 带完整正文）；`session/queue`、`session/jobs`、`resync-required` 这些
+ *   控制帧没有 seq 但绝不能丢。设备级流的帧全是幂等信号，丢掉后由调用方断流重连并补发。
+ * - 写不动时：会话流 await 一次 drain（20s 超时收尾）；设备级流直接收尾让客户端重连，重连
+ *   时会补发当前状态，所以断开是它的正常收敛路径。
+ * - 填充：会话流每条补 2048 字节注释（Android RN 的 XHR 会攒小 chunk，不补迟迟不触发
+ *   onprogress）；设备级流帧少且小，不补。
  */
 
 const crypto = require('crypto');
@@ -66,8 +60,8 @@ function ssePadding(bytes) {
  * 这条连接上真正「还没发出去」的字节数。
  *
  * 只看 `res.writableLength` 是错的：它只算响应对象自己那一层，真正的积压在底下的套接字
- * 写队列里（堆快照里那些 `{chunk, encoding, callback}`）。2026-10-18 复测证实：只看前者
- * 时闸门从不触发，内存照涨。所以顺着 socket 一起看，取较大值。
+ * 写队列里（堆快照里那些 `{chunk, encoding, callback}`）。实测只看前者时闸门从不触发，
+ * 内存照涨。所以顺着 socket 一起看，取较大值。
  */
 function bufferedBytesOf(res) {
   const own = Number(res.writableLength) || 0;

package/lib/shared/workspace-guard.js

@@ -2,23 +2,15 @@
 
 // 空清单守卫（工作区 / 会话列表共用）。
 //
-// 「没取到」与「真的什么都没有」在单份快照上长得一模一样：都是
-// `{ ok: true, items: [] }`。因此读取侧必须**如实报错**（见 lib/mobile/workspaces.js
-// 的 `host-workspace-list-degraded` 与 lib/mobile/sessions.js 的
-// `host-session-list-degraded`），守卫则负责兜住「宿主确实回了合法空列表」这种情况
-// ——它和真实删除无法区分，所以按时间兜底。
+// 「没取到」与「真的什么都没有」在单份快照上长得一模一样：都是 `{ ok: true, items: [] }`。
+// 读取侧必须如实报错（见 workspaces.js / sessions.js 的 `*-list-degraded`），守卫负责兜住
+// 「宿主确实回了合法空列表」——单看一份快照区分不了它和真实删除，所以按时间兜底。
 //
-// 后果（真机缺陷）：一份空快照会一路通过推送路径的 `.ok` 判定，被当成权威清单推给
-// 中转冻结下来。中转只在响应上附一个 `stale` 标记，而 App 根本不读它，于是下一次 15s
-// 轮询就把好数据覆盖成空 —— 侧边栏工作区整行消失、其下所有会话塌进「未分组」，
-// 设备仍显示「在线」（那是另一条独立的 /status 探测线），点不开，且全程零错误提示。
+// 一份空快照若被当成权威清单推给中转，下一次 15s 轮询就会把好数据覆盖成空：侧边栏工作区
+// 整行消失、会话塌进「未分组」，而且全程零错误提示。所以距上一次确认过的非空清单不到
+// graceMs 时拒绝空清单、保留上一份镜像；超过 graceMs 则放行，让真实删除也能收敛。
 //
-// 「用户真的把工作区/会话全删了」同样表现为空列表，单看一份快照区分不了，所以按时间兜底：
-// 距上一次确认过的非空清单还不到 graceMs 时拒绝空清单、保留上一份镜像；超过 graceMs
-// 则放行，让真实删除也能收敛，不会把侧边栏永久钉死在旧数据上。
-//
-// 抽成独立模块是为了能被真正单测（早期版本把这段逻辑内联在 lib/index.js 的闭包里，
-// 只能靠 grep 源码做契约测试，行为本身一次都跑不到）。
+// 抽成独立模块是为了能被真正单测。
 
 const fs = require('node:fs')
 

package/lib/shell/device-ota.js

@@ -7,12 +7,10 @@ import { movePath, readManifest, sha256Hex, unpackTarGz, verifyManifest } from '
 /**
  * OTA 包落在哪。
  *
- * 默认 `<DSH_HOME>/plugin-ota`，但外壳知道 profile 在哪之后会把它挪到**profile 里面**
- * （`<profile>/.dsh-mobile-ota`）。原因不是洁癖：DSH 宿主的 profile-resolution 拦截层
- * 只认 `profiles/` 树内的模块，树外的裸包名走的是原生解析 —— 而宿主提供的那批 peer
- * （`@deepseek-ai/dsh-tools` 之类）压根不在 profile 的 node_modules 里，于是 OTA 代
- * 第一句 `require('@deepseek-ai/dsh-tools')` 就 MODULE_NOT_FOUND（2026-10-17 真机：
- * 0.1.80 装载失败）。落在 profile 里之后，OTA 代与装进来的那一代走**同一条**解析链。
+ * 默认 `<DSH_HOME>/plugin-ota`，外壳知道 profile 在哪之后会把它挪进 profile 里面。原因是
+ * DSH 宿主对 `profiles/` 树外的模块走原生解析，而宿主提供的 peer 不在 profile 的
+ * node_modules 里，OTA 代第一句 require 就 MODULE_NOT_FOUND。落在 profile 里之后，OTA 代与
+ * 装进来的那一代走同一条解析链。
  */
 let storageRoot = ''
 export function configureOtaRoot(dir) {

package/lib/shell/manager.js

@@ -1,31 +1,17 @@
 /**
  * 代际装载器：把「插件实现」当成可以整代替换的东西。
  *
- * 起因：宿主进程启动时就把 profile 的插件树定死了，改一次插件代码就得**完整重启
- * DSH**（Node 缓存 realpath，换 profile 链接必须重启进程）。手机那边的主机是 systemd
- * 拉起来的，重启一条命令的事；桌面这边用户得自己退出再打开，而他不想每次都做这件事。
+ * 宿主启动时就把 profile 的插件树定死了，改一次插件代码就得完整重启 DSH（Node 缓存
+ * realpath）；桌面用户不想每次都做这件事，所以要能在进程里换代。
  *
- * ## 2026-10 改：npm 正式代与紧急 OTA 代并存
+ * 正式版本由 DSH 插件市场装进 profile，紧急 OTA 把完整包落在 profile 里，两者都由这里切换。
+ * pnpm 装新版会把 `node_modules/dsh-mobile-plugin` 指向一个全新的 store 目录 ——「新目录 =
+ * 新 realpath = 新 URL」，天然绕开 ESM 缓存；所以只要认出 profile 里当前装的是哪一份，把它
+ * 当成一代接上去就够了，不需要拷贝或校验。
  *
- * 正式版本由 DSH 插件市场装进 profile；紧急 OTA 将完整包落在 `$DSH_HOME/plugin-ota/`，两者都由代际装载器切换。正式版本安装仍通过 profile 里的 pnpm 完成，安装新版会把
- * `<profile>/node_modules/dsh-mobile-plugin` 这个链接指向**一个全新的 store 目录**：
- *
- *   <profile>/node_modules/dsh-mobile-plugin -> .pnpm/dsh-mobile-plugin@0.1.58/node_modules/dsh-mobile-plugin
- *
- * 「新目录 = 新 realpath = 新 URL」，正是当年必须靠 `.live/<releaseId>` 才能拿到的东西
- * （见 `importGeneration` 里 `?v=` 那一段：同一路径换代码是骗不过 ESM 缓存的）。所以这里
- * 只要**认出 profile 里当前装的是哪一份**，把它当成一代接上去就够了 —— 不需要拷贝、
- * 不需要下载，也不需要 sha256 校验（那是市场的活儿）。
- *
- * 一代 = 一个完整包目录，`package.json` 与 `lib/impl.js` 缺一不可：`lib/*.js` 内部有
- * 80 多处相对引用（`../shared/http-util` 之类），必须保持 `lib/` 这一层的相对结构；
- * 实现里还有 `require('../dsh-mobile-credentials/lib/credentials.js')` 这种跨包相对引用，
- * 而凭据包就嵌在插件包目录内部，所以一代是**自包含**的：回滚到旧代时连凭据版本一起
- * 回滚，不会出现「旧插件配新凭据」。
- *
- * 裸包名（`ws`、`@deepseek-ai/...`）依旧沿祖先目录解析：从 `<代>/lib` 往上会经过
- * `<代>/node_modules`、profile 的 `node_modules`，最终落在同一份插件自身依赖与 peer
- * 依赖上，与基础代解析到同一份 real path，不会出现两份实例。
+ * 一代 = 一个完整包目录，`package.json` 与 `lib/impl.js` 缺一不可：`lib/*.js` 内部有大量
+ * 相对引用，凭据包也嵌在插件包目录内部，所以一代是自包含的——回滚时连凭据版本一起回滚。
+ * 裸包名沿祖先目录解析，与基础代落到同一份依赖上。
  */
 
 import fs from 'node:fs'
@@ -249,8 +235,8 @@ function evictCommonJsTree(roots) {
  * 宿主对模块解析有一层拦截：**`profiles/` 树内**的模块，裸包名会先按 profile 的
  * 本地包解析、再回落到宿主自己那份；树外的模块走原生解析。而宿主提供的那批 peer
  * （`@deepseek-ai/dsh-tools` 等）并不在 profile 的 `node_modules` 里 —— 所以 OTA 包
- * 一旦落在树外，那一代 `require('@deepseek-ai/dsh-tools')` 就是 MODULE_NOT_FOUND
- * （2026-10-17 真机：0.1.80 装载失败）。位置挪进 profile 后，OTA 代与装进来的那一代
+ * 一旦落在树外，那一代 `require('@deepseek-ai/dsh-tools')` 就是 MODULE_NOT_FOUND。
+ * 位置挪进 profile 后，OTA 代与装进来的那一代
  * 走同一条解析链，不必再靠调用点逐个打补丁。
  *
  * 老位置残留的包顺手搬过来：换代失败时它还是磁盘上的回退包，不能在升级路径上丢。
@@ -282,8 +268,7 @@ function moveOtaRootIntoProfile() {
  * Node 只沿**自己的祖先目录**找 `node_modules`，而 OTA 落在
  * `<DSH_HOME>/plugin-ota/<version>/` —— 这条路径上没有任何一份 `node_modules`。于是
  * `lib/impl.js` 第一句 `import { z } from '@deepseek-ai/schemastery'` 就报
- * `Cannot find package`，一代整个装不起来（2026-10-17 真机：0.1.79 的 OTA 装载失败，
- * 外壳按规矩回滚到旧代，机器上什么都没变）。
+ * `Cannot find package`，一代整个装不起来。外壳按规矩回滚到旧代，机器上什么都没变。
  *
  * 修法是补上基础代本来就有、而 OTA 路径上没有的那两层软链：
  *   `<version>/node_modules`                    → profile 的 `node_modules`

package/lib/shell/ota-package.js

@@ -1,20 +1,15 @@
 /**
  * OTA 包（npm tarball）的读取、校验与落盘。
  *
- * 这一层存在的唯一理由是「换一台机器也照样能装」：以前解包是 `device-ota.js` 里的六十行
- * 手写代码，只认普通文件和目录，遇到 PAX 扩展头（macOS 的 tar 默认会带）、GNU 长文件名、
- * 长路径就直接抛「不支持的 tar 项」；反过来，包里少几个文件它又看不出来，于是装上去之后
- * 才在某一代运行时报「找不到某个 JS 文件」。这里把两件事一起解决：
+ * 这一层只为「换一台机器也照样能装」：手写解包只认普通文件和目录，遇到 PAX 扩展头、GNU 长名
+ * 或长路径就抛错，而包里少几个文件又看不出来。这里把两件事一起解决：
  *
- *  1. **解包要认得真实世界里的 tar**：ustar 的 prefix、PAX（`x` / `g`）、GNU 长名（`L` / `K`）
- *     都要能读；软链接、硬链接、设备文件要**明确拒绝**并说清原因（不静默跳过，否则会装出
- *     一个缺文件的代）。
- *  2. **装完要能证明它完整**：包里带一份 `lib/ota-manifest.json`（发布脚本生成，列出版本与
- *     每个文件的路径和字节数），解包后逐项核对。缺文件、大小不符都在**激活之前**失败，
- *     错误里直接点名是哪个文件。
+ * 1. 解包要认得真实世界里的 tar：ustar 的 prefix、PAX、GNU 长名都要能读；软链接、硬链接、
+ *    设备文件明确拒绝并说清原因，不静默跳过。
+ * 2. 装完要能证明完整：包里带一份发布时生成的清单（版本 + 每个文件的路径与字节数），解包后
+ *    逐项核对，缺文件或大小不符都在激活之前失败并点名。
  *
- * 手写 tar 解析而不是引依赖：这是发布链路上的一段自包含代码（OTA 包要能在一台刚装好
- * DSH 的机器上被解出来，不能要求它先装点别的），而 ustar 的头部格式是固定的 512 字节。
+ * 手写而不是引依赖：这是发布链路上要能在一台刚装好 DSH 的机器上跑的自包含代码。
  */
 
 import crypto from 'node:crypto'

package/lib/shell/runtime.js

@@ -1,22 +1,14 @@
 /**
  * 代际运行时：把「外壳」和「某一代实现」缝在一起，并负责换代那一刻的秩序。
  *
- * 外壳（`lib/index.js`）只做两件事：启动时激活版本最高的一代，以及把换代请求转给这里。
- * 实现侧完全不知道自己是被外壳装进来的 —— 它拿到的是一个普通的 cordis `Context`，
- * 照常 `ctx.effect(...)` / `ctx.webServer.register(...)` / `ctx.reflect.provide(...)`。
+ * 外壳只做两件事：启动时激活版本最高的一代，以及把换代请求转给这里。实现侧拿到的是一个普通
+ * 的 cordis `Context`，不知道自己是被外壳装进来的。
  *
- * ## 换代为什么必须串行、而且先停后起
+ * 换代必须串行、且先停后起：一代在 `apply` 里会注册同一条路径的路由（撞路径直接抛错）、绑
+ * sidecar、起镜像推送，只能先 dispose 旧代（每个 `ctx.effect` 反向清理），再装新代。
  *
- * 一个代在 `apply` 里会往宿主注册**同一条路径**的路由（`ctx.webServer.register` 撞路径会抛
- * `webserver: duplicate exact route`），还会绑 sidecar、起镜像推送。所以不能「先装新的再
- * 卸旧的」——只能先把旧代的 fiber dispose 掉（它的每个 `ctx.effect` 会反向执行清理：路由
- * 摘掉、子进程收掉），再装新的。这个文件里的 `swapping` 锁就是保证同一时刻只有一次换代。
- *
- * ## 让路
- *
- * 手机那边随时可能有一个请求在读事件流。直接 dispose 会把 `ctx.effect` 的清理跑在别人的
- * 请求中间。所以换代前先等 `inFlight` 归零，最多等 `DRAIN_TIMEOUT_MS`（等不到也照换——
- * 卡住的请求不该拖住一次修复性更新）。
+ * 换代前先等 `inFlight` 归零，最多等 `DRAIN_TIMEOUT_MS`——把清理跑在别人的请求中间会出事，
+ * 但卡住的请求也不该拖住一次修复性更新。
  */
 
 import { importGeneration, invalidateGeneration, resolveGeneration, resolveGenerations } from './manager.js'
@@ -199,7 +191,7 @@ export function createRuntime() {
    * 旧代先停、新代后起；新代起不来就回滚把旧代装回去，并把错误留在 `lastError` 里——
    * 「更新把自己弄挂了」必须能被看见，而不是静默少个插件。
    *
-   * `options.reread` 是给**开发机**的那条路（2026-10-19）：版本号与目录都没变，只是盘上
+   * `options.reread` 是给**开发机**的那条路：版本号与目录都没变，只是盘上
    * 那几个文件被改了。默认会走上面那句「身份一致就直接返回」，于是改完代码再触发也没有
    * 任何变化 —— 开发时看到的「改了不生效」就是这么来的。带上它就先把这一代从
    * `imported` 里作废、再让 `importGeneration` 清掉 CJS 子树，强制重新读盘。
@@ -288,7 +280,7 @@ export function createRuntime() {
   /**
    * 第一次激活；最高代装载失败时按优先级尝试保留的回退代；全失败则按固定间隔重试有限次。
    *
-   * 为什么要重试（2026-10-25 真机 404）：一次失败 = **整张控制面路由表都不在**，而设置页
+   * 为什么要重试：一次失败 = **整张控制面路由表都不在**，而设置页
    * 的「移动端」照样画得出来（客户端半边按包扫描，不看宿主 fiber 活没活），于是现场只表现成
    * 「读取宿主状态失败: HTTP 404」。失败最常见的原因恰好是**可能自己好**的：注入的服务
    * （typertGateway / apiProxy）比本插件晚就位、撞上 20s 装载上限，或者第一次装载撞上

package/lib/shell/self-check-after-swap.js

@@ -1,30 +1,16 @@
 /**
- * 换代之后的自检：新版装起来之后，**手机要打的那批接口**真的能用吗？不能就退回上一代。
+ * 换代之后的自检：新版装起来之后，手机要打的那批接口真的能用吗？不能就退回上一代。
  *
- * ## 为什么这一条不能交给手机
+ * 这条不能交给手机：装坏的后果是 App 连不上这台设备，那一刻手机上的回滚按钮发不出去。
+ * 必须由还活着的宿主做完，手机只在事后读到「上次装失败了，已自动退回 X」。
  *
- * 装坏的后果是「App 连不上这台设备」。那一刻手机上没有任何按钮发得出去 —— 让 App 去按
- * 「回滚」等于让一个已经断线的客户端去救自己的连接。所以这件事必须由**还活着的宿主进程**
- * 自己做完，手机那边只在事后读到一条「上次装失败了，已自动退回 X」。
+ * 判据是打本机的 `127.0.0.1:<宿主端口>`：200 且 `service: 'dsh-mobile-plugin'` 算活；401 也
+ * 算活（守卫先核 token，说明实现与守卫都在）；404 / 别的 service / 超时算死。连不上
+ * （ECONNREFUSED）不算数——那是宿主 webServer 自己没起来，与新代无关，退回去也救不了，
+ * 如实报 `skip`。
  *
- * ## 判据：问它自己的 `/health`，看回的是什么
- *
- * 不看日志、不猜堆栈，直接打本机的 `127.0.0.1:<宿主端口>`：
- *
- *  · 回 200 + `service: 'dsh-mobile-plugin'` → 活，路由挂上了；
- *  · 回 401 → 也活：移动端守卫先核 token 再谈路由，没带 token 回 401 说明实现与守卫都在；
- *  · 回 404 / 别的 service → **死了**：端口在、但插件那批路由没挂上，手机打过去就是这个 404；
- *  · 超时 → **死了**：连上了但不回包，多半是某个 handler 卡在等一个永远不来的依赖；
- *  · 连不上（ECONNREFUSED）→ **不算数**：那是宿主 webServer 自己没起来，与新代无关，
- *    退回去也救不了。如实报 `skip`。
- *
- * 最后那一条是这次刻意分开的：把「宿主没在监听」当成「新版坏了」会退掉一次其实成功的
- * 更新（开发机上跑测试时就是这么一种现场：假 webServer 有个端口号，但没有任何东西在听）。
- *
- * ## 端口从哪儿来
- *
- * 用宿主的 `ctx.webServer.port`（运行中那一份），不是配置里的默认值 —— 端口被改过之后，
- * 配置与实绑可能不同，按配置去问会问到一个没人监听的地方，于是「自检失败」全是假的。
+ * 端口用 `ctx.webServer.port`（运行中那份），不是配置里的默认值：端口被改过之后按配置去问
+ * 会问到一个没人监听的地方。
  */
 
 /** 自检的超时上限：本机环回，正常几十毫秒。给 3 秒已经很宽。 */

package/lib/shell/updater.js

@@ -1,29 +1,16 @@
 /**
- * 更新编排：**查与装都归实现自己**，装完**就地换代**（不重启 DSH）。
+ * 更新编排：查与装都归实现自己，装完就地换代（不重启 DSH）。
  *
- * ## 为什么这件事归外壳做，而不是归面板（浏览器）
+ * 面板那颗「更新」按钮只覆盖「用户正开着页面点一下」；自动更新的定义是没人看着也要发生，
+ * 所以轮询与「装完切换」都必须在宿主进程里做。
  *
- * 面板里那颗「更新」按钮只能覆盖「用户正开着页面点一下」这一种情形；自动更新的定义是
- * **没人看着也要发生**。所以轮询和「装完切换」都必须在宿主进程里做，面板只是给它一个开关。
+ * 查问 npm 注册表、装在 profile 里跑包管理器（`update-registry.cjs` / `update-install.cjs`）。
+ * 外壳只从盘上那一代把自装模块取进来跑，所以换装法不用等重启。下面那套市场实现是兜底，只在
+ * 盘上那一代还没有自装模块时走到；市场装完会报 `restartRequired`，但本插件有外壳可以自己
+ * 换代，所以那条路里故意不调它的重启。
  *
- * ## 装法住哪儿（2026-10-11 改）
- *
- * 从前「查」和「装」都是请 DSH 插件市场代劳的（打它的 HTTP 接口）。现在两件都归实现自己：
- * 查问 npm 注册表、装在 profile 里跑它自己的包管理器（`lib/update-registry.cjs` /
- * `lib/update-install.cjs`）。外壳**只从盘上那一代**把自装模块取进来跑（`installedInstaller`），
- * 所以换装法、换判定都不用等重启 —— 盘上换了，下一次自动更新就走新的。
- *
- * 下面那套市场实现是**兜底**，只在「盘上那一代还没有自装模块」时才走到（老一代、刚回滚到
- * 旧代）。自动更新宁可暂时还走老路，也不能直接坏掉；市场装完会报 `restartRequired: true`，
- * 而本插件有外壳可以自己换代，所以那条路里**故意不调它的重启**。
- *
- * 装完新一代是**新目录**（包管理器换链接），外壳照着新 realpath 重新 import 一代即可，见
- * `lib/shell/manager.js` 与 `lib/shell/runtime.js`。
- *
- * ## 兜底那条路不做的事
- *
- * 不下载、不解包、不校验、不写 profile —— 全是市场的职责。它只回答四个问题：有没有新版、
- * 请它装、装完了没、盘上现在是什么版本。
+ * 兜底那条路不下载、不解包、不校验、不写 profile，只回答「有没有新版、装完了没、盘上是什么
+ * 版本」。
  */
 
 import fs from 'node:fs'
@@ -40,7 +27,7 @@ const { dshHome } = require_('../shared/paths.js')
 /**
  * 盘上那一代的「自己装」模块（`lib/update-install.cjs`）。
  *
- * 「装」这件事 2026-10-11 起归**实现**自己：在 profile 里跑它自己的包管理器，不再借道 DSH
+ * 「装」这件事归实现自己：在 profile 里跑它自己的包管理器，不再借道 DSH
  * 插件市场。外壳只负责把盘上那一代的模块取进来跑 —— 从**盘上**（不是外壳自己的目录）取，
  * 是为了「装法改了不用等重启」：市场以外的方式换掉那一代之后，下一次自动更新就走新装法。
  *
@@ -100,7 +87,7 @@ export function shellFingerprint(pkgDir) {
 export const PACKAGE_NAME = 'dsh-mobile-plugin'
 
 /** 自动检查的间隔与「检查一次」的超时。 */
-export const AUTO_INTERVAL_MS = 10 * 60 * 1000
+export const AUTO_INTERVAL_MS = 2 * 60 * 1000
 const REQUEST_TIMEOUT_MS = 15000
 /** 等一次安装走完的上限：pnpm 装一个包 + 校验，给足但别无限等。 */
 const INSTALL_TIMEOUT_MS = 10 * 60 * 1000
@@ -229,12 +216,12 @@ const TERMINAL = new Set(['succeeded', 'failed', 'cancelled', 'rolled-back'])
  */
 export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false, auto = false, onEvent = () => {}, packageManager = () => null, agents = () => null, beforeInstall = null, now = Date.now } = {}) {
   const before = installedVersion()
-  // 装归实现自己（2026-10-11 起）：盘上那一代里有 `update-install.cjs` 就走它。判定（有没有
+  // 装归实现自己：盘上那一代里有 `update-install.cjs` 就走它。判定（有没有
   // 新版、`link:` 来源不碰、有 agent 在跑就先别换文件）也一并交给它，别在这里抄第二份 ——
   // 外壳的自动更新与面板那颗按钮必须是同一套判定，否则会出现「手动说有新版、自动说没有」。
   //
-  // `auto` 也透下去：自动那一轮跳过「有对话在跑就先别装」那道闸（2026-10-25 用户拍板的取舍，
-  // 见 `update-install.cjs` 文件头），但没有新版时它照样什么都不做。
+  // `auto` 也透下去：自动那一轮跳过「有对话在跑就先别装」那道闸（取舍见
+  // `update-install.cjs` 文件头），但没有新版时它照样什么都不做。
   const selfInstall = await installedInstaller()
   if (selfInstall) {
     const outcome = await selfInstall({
@@ -318,7 +305,7 @@ export async function installIfNeeded(base, { name = PACKAGE_NAME, force = false
 /**
  * 换代尝试的记账：同一个版本自动只试一次。
  *
- * 一个起不来的新版每 10 分钟把手机抖一下没有任何意义 —— 第一次失败之后就该停下，等人按
+ * 一个起不来的新版每一轮把手机抖一下没有任何意义 —— 第一次失败之后就该停下，等人按
  * 那颗按钮（手动不受这个限制：那是「我知道，再来一次」）。进程重启后这份记录清零，
  * 而重启本来就会走一遍正常装载，不需要它。
  */

package/lib/sidecar-facade-worker.cjs

@@ -3,24 +3,24 @@
 /**
  * sidecar worker：真正持有「中转隧道 + 局域网代理」的那个子进程。
  *
- * 宿主不自己开 WebSocket、也不自己监听局域网端口，而是 fork 出这个 worker，用环回
- * HTTP + Bearer 令牌对话（见 lib/sidecar-facade.cjs）。这样隧道崩了、原生模块加载
- * 失败都只死一个子进程，宿主仍能如实把状态报给 /api/relay/status。
+ * 宿主不自己开 WebSocket、也不自己监听局域网端口，而是 fork 出这个 worker，用环回 HTTP +
+ * Bearer 令牌对话。隧道崩了、原生模块加载失败都只死一个子进程，宿主仍能如实回报状态。
  *
  * 三条不能忘的语义：
- *  1. 状态既要在 `/status` 上按需可查，也要在**变化的那一刻**主动 `process.send` 给宿主
- *     （publishState）：宿主的健康轮询是 10s 一次，只靠轮询的话隧道真断后它最多 10s
- *     仍以为连着、继续往一条死隧道推镜像；而「断又连」整段落在两次轮询之间时，宿主
- *     连一次「刚连上」都观测不到，那次全量补推就永远不来。
- *  2. `/tunnel/send` 先把镜像快照留在本地（localSnapshot）再尝试真发：局域网直连的手机
- *     走 snapshotRead 读这份快照，隧道断了也不至于读到一份过期镜像。
- *  3. 请求体一律先量后读（readBody + 显式上限）：`/configure` 与镜像帧都有字节上限，
- *     超限立刻 413，别让一个畸形请求把内存吃光。
+ * 1. 状态既要在 `/status` 上可查，也要在变化那一刻主动 `process.send` 给宿主：健康轮询是
+ *    10s 一次，只靠轮询的话隧道真断后宿主最多 10s 仍以为连着；「断又连」落在两次轮询之间时
+ *    那次全量补推也会漏掉。
+ * 2. `/tunnel/send` 先把快照留在本地再尝试真发：局域网直连的手机读本地这份，隧道断了也不
+ *    至于读到过期镜像。
+ * 3. 请求体一律先量后读：`/configure` 与镜像帧都有字节上限，超限立刻 413。
+ * 4. 换中转地址不是「拆了重建」：先在旧隧道上登记迁移，再建新隧道，注册不上要撤销
+ *    （见 lib/relay/migrate.js）。这条顺序是「填错地址就把自己锁在外面」的唯一解。
  */
 
 const http = require('node:http')
 const { RelayTunnel } = require('./relay/tunnel.js')
 const { T } = require('./relay/protocol.js')
+const { switchRelay } = require('./relay/migrate.js')
 const { createLanProxy } = require('./relay/lan-proxy.js')
 const { lanUrls } = require('./relay/lan-network.cjs')
 const core = require('./relay/core.js')
@@ -98,15 +98,12 @@ function authorized(req) { return typeof token === 'string' && token.length >= 6
 class BodyTooLarge extends Error {}
 /** /tunnel/send 的请求体上限。
  *
- * 这个接口收的是桌面推给移动端的镜像：整份会话列表 + 工作区 + 当前会话的完整消息、
- * 统计与模型。实测桌面一次推送就超过 1MB，而中转清洗后真正留下的只有 ~114KB——
- * 旧的 1MB 上限是在把有用的东西挡在门外。
+ * 这个接口收桌面推给移动端的镜像：整份会话列表、工作区、当前会话的完整消息与统计。桌面一次
+ * 推送就超过 1MB，旧的 1MB 上限把有用的东西挡在门外。
  *
- * 上限的依据是**中转那侧的帧上限**，不是「估个够大的数」：
- * dsh-mobile-server/lib/config.js 的 MAX_FRAME_BYTES 默认 8MB，一帧超过它，
- * 中转会以 1009 'frame too large' 直接关掉隧道（lib/protocol.js → onError）。
- * 丢一次镜像可以恢复，隧道被关掉要等重连、期间手机端全瞎——所以宁可拒也不能赌。
- * 留 64KB 余量给帧头。推得再大也只是这一次 413，隧道安然无恙。
+ * 依据是中转那侧的帧上限（默认 8MB）：一帧超过它，中转会以 1009 'frame too large' 直接关掉
+ * 隧道。丢一次镜像可以恢复，隧道被关掉要等重连、期间手机端全瞎。所以留 64KB 余量给帧头，
+ * 推得再大也只是这一次 413。
  */
 const TUNNEL_SEND_MAX_BODY = 8 * 1024 * 1024 - 64 * 1024
 
@@ -277,10 +274,14 @@ function stopLan() {
   publishState()
 }
 async function stopServices() { stopNetworkMonitor(); stopTunnel(); stopLan() }
-function startTunnel() {
-  if (!config.enabled || !config.relayUrl || !config.upstreamPort) return
-  stopTunnel(); tunnelState = 'connecting'
-  publishState()
+/**
+ * 建一条隧道并把它设成当前实例，返回它的注册 Promise（resolve = 已 registered）。
+ *
+ * **不在这里吞错**：换中转地址那条路要拿到真实的失败原因去撤销迁移登记、并把错误回给调用方
+ * （`configure` 的 503 会一路回到手机）。普通重建由 `startTunnel` 那一侧兜底 —— 状态置错 +
+ * 排重连，与旧实现一字不差。
+ */
+function openTunnel() {
   const current = new RelayTunnel({
     relayUrl: core.tunnelWsUrl(config.relayUrl), instanceId: config.instanceId,
     name: config.name, upstream: upstream(),
@@ -311,7 +312,17 @@ function startTunnel() {
     onLog: (...args) => process.stderr.write(`[dsh-ai-hub sidecar] ${args.join(' ')}\n`),
   })
   tunnel = current
-  current.start().catch(error => { if (tunnel === current) { tunnelState = 'error'; tunnelError = error instanceof Error ? error.message : String(error); publishState(); scheduleReconnect() } })
+  const ready = current.start()
+  // 挂了就如实报，并按 5s 起退避重连（旧实现在 startTunnel 的 catch 里做同一件事）。
+  // 换地址失败时这里也会排一次：配置里已经是新地址，值得继续试它，而不是悄悄退回旧地址。
+  ready.catch(error => { if (tunnel === current) { tunnelState = 'error'; tunnelError = error instanceof Error ? error.message : String(error); publishState(); scheduleReconnect() } })
+  return ready
+}
+function startTunnel() {
+  if (!config.enabled || !config.relayUrl || !config.upstreamPort) return
+  stopTunnel(); tunnelState = 'connecting'
+  publishState()
+  void openTunnel()
 }
 function startLan() {
   // 总开关关闭时不能只停隧道：旧实现漏了 `config.enabled`，于是 /api/relay/toggle
@@ -377,13 +388,35 @@ async function configure(next) {
   //   - 其余（配对码 / 名字 / 局域网候选）在现有连接上重报一次注册信息即可。
   // 无条件全拆全建就是「每隔几分钟断一次 + 内存一直涨」的根因，别改回去。
   const previous = config
+  // 中转地址变了要**先登记迁移再重建**：还握着旧地址的设备只会在旧中转上找这台电脑。
+  // 按规范形态比，避免只差一个尾斜杠就白跑一次迁移（那只是同一台中转）。
+  // 「第一次配地址」不算换地址：旧中转上没有谁握着这台电脑的旧地址，没什么要登记的，
+  // 更不该为了等注册把启动那次下发拖住。
+  const previousRelayUrl = core.normalizeRelayUrl(previous.relayUrl)
+  const relayUrlChanged = Boolean(previousRelayUrl) && previousRelayUrl !== core.normalizeRelayUrl(next.relayUrl)
   const tunnelNeedsRebuild = tunnelSignature(previous) !== tunnelSignature(next)
   const lanNeedsRebuild = lanSignature(previous) !== lanSignature(next)
   const monitorNeedsRestart = monitorSignature(previous) !== monitorSignature(next)
   config = { ...next }
   if (tunnelNeedsRebuild) {
-    stopTunnel()
-    startTunnel()
+    if (relayUrlChanged && config.enabled && config.relayUrl && config.upstreamPort) {
+      // 换地址这条路**等新隧道真的注册上**再返回：注册不上要把错误一路回给调用方，
+      // 并在旧隧道上撤销迁移登记（顺序与理由见 lib/relay/migrate.js 文件头）。
+      await switchRelay({
+        oldTunnel: tunnel,
+        relayUrl: config.relayUrl,
+        open: () => {
+          // 旧隧道还在，但重连定时器得先撤掉：否则它到点会把刚起来的新隧道又拆一遍。
+          reconnect.cancel()
+          tunnelState = 'connecting'; tunnelError = null; publishState()
+          return openTunnel()
+        },
+        drop: (old) => { if (old) { try { old.stop() } catch { /* 已经断开 */ } } },
+      })
+    } else {
+      stopTunnel()
+      startTunnel()
+    }
   }
   if (lanNeedsRebuild) {
     stopLan()
@@ -418,7 +451,15 @@ const server = http.createServer(async (req, res) => {
     if (!authorized(req)) return send(res, 401, { ok: false, error: 'unauthorized' })
     if (req.method === 'GET' && req.url === '/health') return send(res, 200, { ok: true, service: 'dsh-ai-hub-relay-sidecar', capabilities: ['relay-tunnel', 'lan-proxy', 'pairing-approval-rpc'] })
     if (req.method === 'GET' && req.url === '/status') return send(res, 200, status())
-    if (req.method === 'POST' && req.url === '/configure') { const next = await readBody(req, CONFIGURE_MAX_BODY); configuring = configuring.then(() => configure(next)); return send(res, 200, await configuring) }
+    if (req.method === 'POST' && req.url === '/configure') {
+      const next = await readBody(req, CONFIGURE_MAX_BODY)
+      const run = configuring.then(() => configure(next))
+      // 串行链本身**不许被一次失败卡死**：`configuring` 一旦是 rejected，后续每一个
+      // `.then(() => configure(...))` 都会跳过 configure 直接跟着失败 —— 一次地址填错
+      // 就能让这台宿主从此不再接受任何配置下发（隧道永远起不来，只能重启 worker）。
+      configuring = run.catch(() => undefined)
+      return send(res, 200, await run)
+    }
     if (req.method === 'POST' && req.url === '/tunnel/send') {
       const body = await readBody(req, TUNNEL_SEND_MAX_BODY);
       // 桌面→relay 主动推送（移动端镜像缓存）：复用隧道立即 sendJson；同时在本地保留快照供读取隔离。
@@ -464,22 +505,15 @@ process.once('SIGTERM', shutdown); process.once('SIGINT', shutdown)
 /**
  * 父进程（宿主）没了就自己退出：否则这里会变成一具握着隧道的尸体。
  *
- * ~~Node 的 fork 子进程不会随父进程退出~~。宿主被 Cmd+Q / 被系统内存压力清掉 / 被
- * SIGKILL 时，没有任何人会给这里发 SIGTERM，IPC 通道也只是**静默 EOF**（Node 不会
- * 替我们发 disconnect）。于是 worker 继续活着、继续握着那条 `register` 成功过的中转
- * 隧道、继续如实回答 `/api/mobile/v1/status`（它知道的宿主身份还是那一份），中转的
- * `instances` 里那条记录就永不删除 —— 手机侧栏的设备「在线」从此再也灭不掉，正文
- * 镜像也停在最后一帧。2026-10-10 真机故障，根因就在这里。
+ * 宿主被 Cmd+Q、被系统清掉或被 SIGKILL 时，没有人会给这里发 SIGTERM，IPC 也只是静默 EOF。
+ * worker 继续活着、继续握着那条注册成功过的隧道，中转的 instances 里那条记录就永不删除，
+ * 手机侧栏的设备「在线」再也灭不掉。
  *
- * 两道判据都留着，互相兜底：
- *  - `disconnect`：宿主正常退出 / 主动销毁 IPC 时立刻触发，退出最快；
- *  - ppid 巡检：宿主被 SIGKILL 时**不发** disconnect（实测只看到 ppid 变成 1），
- *    只能靠定时对账。启动时记下 ppid，之后对不上就退出；间隔与宿主那边的健康轮询
- *    同量级（10s），2s 只是让「关掉桌面 → 手机显示离线」快一点。
+ * 两道判据互相兜底：`disconnect` 在宿主正常退出时立刻触发（最快）；ppid 巡检兜住 SIGKILL
+ * （实测只看到 ppid 变成 1，不发 disconnect），启动时记下 ppid，之后对不上就退出。
  *
- * 为什么是整进程退出而不是只 `stopServices()`：隧道一关，中转最多 60s（心跳 pong
- * 超时）才删掉实例，这段时间手机仍显示在线；而孤儿进程本来就没有存在的理由，退出是
- * 最快的收敛路径（也让 `ps` 里不再留下一行认不出归属的 node 进程）。
+ * 整进程退出而不是只 `stopServices()`：隧道一关，中转要等心跳超时才删实例，这期间手机仍
+ * 显示在线；孤儿进程没有存在的理由，退出是最快的收敛路径。
  */
 const PARENT_WATCH_INTERVAL_MS = 2000
 const parentPidAtStart = process.ppid