dsh-mobile-plugin 0.4.0 → 0.4.1

package/lib/read-receipt.cjs

@@ -3,30 +3,19 @@
 /**
  * 「已读回执」台账：哪个会话在什么时候被读过，桌面端据此清掉自己的未读绿点。
  *
- * 背景：两端侧边栏的绿点来自**两份互不相干**的状态。
- *   - 手机端绿点 = 宿主按设备维度维护的完成提醒（lib/mobile/completion.js），
- *     由 `POST /api/mobile/v1/session/read` 清掉；
- *   - 桌面端绿点 = 浏览器渲染进程内存里的 `UiSession.completionUnread`
- *     （@deepseek-ai/dsh-client-ui-session），既不落盘也不过服务端。
- * 所以手机上点开一个会话，桌面那份完全不知情，绿点照旧。
+ * 两端的绿点来自两份互不相干的状态：手机端是宿主按设备维度维护的完成提醒（completion.js），
+ * 桌面端是渲染进程内存里的 `UiSession.completionUnread`，既不落盘也不过服务端。所以手机上
+ * 点开一个会话，桌面那份完全不知情。
  *
- * 这里补的就是这条缺失的通道：只要有人在某一端读过，宿主就往本模块记一条
- * `sessionId → readAt` 水位；插件的客户端半边（lib/client.js 的 startReadReceiptSync）
- * 每 2 秒拉一次 `GET /api/relay/read-receipt`，对水位前进过的会话做一次瞬时
- * `sessions.retain(id, { source: 'mainView' })` + `release()`，借桌面自己的
- * `reconcileStatus()` 把 `completionUnread` 摘掉。
+ * 这里补那条通道：只要有人在某一端读过，宿主就记一条 `sessionId → readAt` 水位；客户端半边
+ * 每 2 秒拉一次，对水位前进过的会话做一次瞬时 retain + release，借桌面自己的
+ * `reconcileStatus()` 把绿点摘掉。
  *
- * 这本台账还有第二个读者：宿主自己。手机侧栏的绿点由 App 拿「上一轮什么时候结束」和
- * 本机已读水位算出来，那一份水位（lib/mobile/session-last-turn.js 的事实地表）是进程内的，
- * 重启就空 —— 所以 `readAtOf` 让它在重启后从这盘上补回来。两头都写同一本账，
- * 「读过」这件事才不会随进程消失。
+ * 宿主自己也读这本账：`readAtOf` 让进程重启后的已读水位从盘上补回来，两头写同一本账，
+ * 「读过」才不会随进程消失。
  *
- * 为什么存 readAt 而不是一个「已读」布尔：冲突策略是 last-write-wins。
- * 桌面点开 → 客户端半边把该会话 POST 回 `/api/relay/desktop-read` → 宿主清掉
- * **所有设备**维度上的完成提醒（`clearCompletionForAllDevices`）。而「读完又来一轮」
- * 必须还能重新亮起来 —— 这一条由 completion.js 的 delete 语义本身保证：条目被清掉后
- * 重建出来的 `wasRunning` 是 false，历史折叠会拒绝确认，于是只有**之后**真正跑完的
- * 轮次才会把 completed 重新置真。
+ * 存 readAt 而不是布尔：冲突策略是 last-write-wins；「读完又来一轮」由 completion.js 的
+ * 条目重建语义保证能重新亮起来。
  */
 
 const fs = require('node:fs');

package/lib/relay/lan-network.cjs

@@ -1,12 +1,11 @@
 /**
  * 网卡枚举与候选地址：私网 / 公网 / IPv6 全球单播三份清单，外加「用户选中的那条排最前」。
  *
- * 收口在这一个文件里，是因为 App 只认「按顺序挨个试」这一种语义 —— 顺序就是优先级。
+ * 收口在一个文件里，是因为 App 只认「按顺序挨个试」这一种语义，顺序就是优先级。
  *
- * 三份的区别在**手机在哪**：私网那份是「同一个 Wi-Fi 里能直连」，公网那份是「这台机器
- * 自己就挂在公网上」，IPv6 那份是「手机在别的网络里、从公网拨过来」——最后这份是 2026-10
- * 新加的，它**不并进前两份**，因为 App 对它的用法完全不同（要和公网中转比速度，见
- * `ipv6Candidates` 的注释）。
+ * 三份的区别在手机在哪：私网是「同一个 Wi-Fi 里能直连」，公网是「这台机器自己就挂在公网上」，
+ * IPv6 是「手机在别的网络里拨过来」。IPv6 不并进前两份：App 对它的用法不同，要和公网中转
+ * 比速度。
  */
 'use strict'
 
@@ -22,17 +21,11 @@ function ipv4Number(address) {
 function inRange(value, start, end) { return value >= start && value <= end }
 
 /**
- * RFC1918 里**不由容器/虚拟机/虚拟网桥占掉**的那几段。
+ * RFC1918 里不由容器 / 虚拟机 / 虚拟网桥占掉的那几段。
  *
- * 172.16/12 原本是一个整段，但 Docker 默认把 `172.17.0.0/16` 给 `docker0`，于是
- * 客户机器上的 `172.17.0.1` 会被当成一条「局域网地址」摆到面板与二维码里 —— 手机拨过去
- * 要么不通，要么连到容器上的别的东西。同理 `172.18/16`（docker compose 的默认网络）、
- * `172.19/16` 与 `172.20/16`（compose / k3d 的下一批）、`172.24~172.31/16`（kubeadm 的
- * `k8s-pod-network` 与常见 overlay）也都是工具按默认值抢走的。
- *
- * 判据是「这个段是不是被某个常见的非宿主网络工具预留了」，而不是「这台机器上有没有跑它」：
- * 我们读不到网络配置，只能按默认值收敛。留下的 172.16~172.23 是 172.16/12 里没被任何
- * 主流工具默认占用的部分；真有人在这几段上跑业务网，网卡名黑名单（下一条）仍然是第一道闸。
+ * Docker 默认拿走 172.17/16，compose / k3d / kubeadm 又按默认值各占几段；把它们当候选，
+ * 手机拨过去要么不通，要么连到容器上的别的东西。我们读不到网络配置，只能按「常见工具会不会
+ * 默认占用」收敛；网卡名黑名单仍然是第一道闸。
  */
 const RESERVED_172 = [
   [0xac110000, 0xac11ffff], // 172.17/16 docker0
@@ -175,21 +168,14 @@ function lanCandidates(port, interfaces = os.networkInterfaces()) {
 }
 
 /**
- * 公网地址：同一遍扫描，挑出**真能从外网拨过来**的那些。
+ * 公网地址：同一遍扫描，挑出真能从外网拨过来的那些。
  *
  * 判据是「不在任何特殊网段里」，而不是「不是 RFC1918」——后者会把 169.254/16（链路本地）、
  * 100.64/10（CGNAT）、198.18/15（基准测试）这些同样拨不通的地址当成公网地址发出去。
- * 实测踩过：macOS 上一块多出来的网卡带着 `169.254.87.131`，被当成「公网地址」摆到面板上。
- * 这份特殊网段清单和本文件开头那句「intentionally excludes VPN/CGNAT, link-local and
- * benchmarking/test ranges」是同一条口径。
- *
- * 为什么不并进 `lanInterfaces`：那份列表的语义是「手机和这台机器在同一个 Wi-Fi 里能直连的
- * 地址」，混进公网地址会改掉 App 的探测顺序与中转上报的内容（`test/lan-network.test.cjs`
- * 既钉着「WAF 容器的 192.168.0.1 被当成候选」那次事故，也钉着「只有公网地址的机器候选为空」）。
  *
- * 需要公网地址的地方只有两处，都在取回来之后再决定怎么用：面板显示「手机该填哪个地址」，
- * 以及一台只有公网 IP 的机器上给不出任何私网候选时的兜底（见 `../impl.js` 的
- * `safeLanCandidates`）。
+ * 不并进 `lanInterfaces`：那份的语义是「同一 Wi-Fi 里能直连」，混进公网地址会改掉 App 的
+ * 探测顺序与中转上报的内容。需要公网地址的只有两处：面板显示该填哪个地址，以及一台只有
+ * 公网 IP 的机器上给不出任何私网候选时的兜底。
  */
 const NOT_PUBLIC_RANGES = [
   [0x00000000, 0x00ffffff], // 0/8        “本网络”
@@ -328,8 +314,8 @@ function ipv6Candidates(port, interfaces = os.networkInterfaces()) {
  * 对外公布的候选地址：**先私网，一个都没有时才退到公网**。
  *
  * 为什么要有这一条：`lanInterfaces` 只认 RFC1918，于是「DSH 装在一台只有公网 IP 的服务器上」
- * 时那份列表**恒为空** —— 二维码里一个可拨的地址都没有，「手机直连」这条路从根上走不通
- * （2026-10-11 用户报的现场）。只在为空时才退：有私网地址的机器，候选列表一个字都不变。
+ * 时那份列表**恒为空** —— 二维码里一个可拨的地址都没有，「手机直连」这条路从根上走不通。
+ * 只在为空时才退：有私网地址的机器，候选列表一个字都不变。
  *
  * 取不到网卡（异常）时回空清单、绝不抛：它喂的是二维码与移动端的连接信息，
  * 让它把整条控制面拖下水不值得。

package/lib/relay/lan-proxy.js

@@ -4,11 +4,10 @@
  * 局域网直连代理：手机在同一个 Wi-Fi 下直接访问
  * http://<电脑IP>:<lanPort>，带上配对拿到的令牌后代理到本机 dsh web。
  *
- * 只服务 App：未认证的请求一律 JSON 401，不给任何网页。曾经的 HTML 配对页
- * 与配对后能进入的网页本体已删除（见 docs/decisions.md 2026-10-19）。
+ * 只服务 App：未认证的请求一律 JSON 401，不给任何网页（网页版配对页与网页本体已删除）。
  *
- * 与中转隧道的关系：同网用本代理（零延迟、不依赖公网），
- * 异地走 dsh-mobile-server 中转。两者互不影响，可同时开启。
+ * 与中转隧道的关系：同网走本代理（零延迟、不依赖公网），异地走 dsh-mobile-server 中转；
+ * 两者互不影响，可同时开启。
  */
 
 const http = require('node:http');
@@ -352,22 +351,18 @@ function createLanProxy(opts) {
     /**
      * 手机走了，必须把上游这条请求一起拆掉。
      *
-     * 旧实现只挂了 `error`：手机断开之后上游请求还活着，宿主那边的响应就永远等不到
-     * `close`，于是 events 流与每条会话流的订阅**永不退订**——宿主继续往一条没人读的
-     * 连接上生成帧与正文。2026-10-19 实测：一台机器 12 条手机连接攒出 216 条上游长流，
-     * 宿主进程涨到 3.5～5G、CPU 30～40%，重启后回到 530M。同一个插件的中转路径有
-     * `httpCancel` 帧负责拆（tunnel.js），只有局域网这条路漏了。
+     * 只挂 `error` 的话，手机断开后上游请求还活着，宿主那边的响应永远等不到 `close`，events
+     * 流与每条会话流的订阅就永不退订，宿主继续往一条没人读的连接上生成帧与正文。中转路径有
+     * `httpCancel` 帧负责拆，局域网这条路同样要有。
      *
-     * `res.writableEnded` 是判据：正常活完的响应结束时就已置位，不该再去动上游；
-     * 只有「客户端提前走」才会落到 false。
+     * 判据是 `res.writableEnded`：正常活完的响应结束时就已置位，只有客户端提前走才落到 false。
      */
     res.on('close', () => {
       if (res.writableEnded) return;
       try { up.destroy() } catch { /* 已断开 */ }
     });
     // GET/HEAD 没有请求体：直接收尾发出去，不要依赖 `req` 的 `end` 事件 —— SSE 客户端的
-    // 那条连接未必会像普通 fetch 一样把请求流收掉，`pipe` 一直不 end，上游就永远不处理
-    // （2026-10-24 现场：设备级 SSE 每 32 秒重试，宿主侧一次都没进处理器）。
+    // 那条连接未必会像普通 fetch 一样把请求流收掉，`pipe` 一直不 end，上游就永远不处理。
     if (req.method === 'GET' || req.method === 'HEAD') up.end();
     else req.pipe(up);
   }
@@ -783,16 +778,14 @@ function createLanProxy(opts) {
       })
 
       /**
-       * IPv6 那条监听：拿 IPv4 实绑的端口，`::` + **显式 `ipv6Only: true`**。
+       * IPv6 那条监听：拿 IPv4 实绑的端口，`::` + 显式 `ipv6Only: true`。
        *
-       * 为什么不合成一条双栈监听：`impl.js` 的端口占用探测真去 `listen(port, '0.0.0.0')`
-       * 试探，一条双栈的 `::` 会把首选端口一律探成「被占」，于是落到内核随机端口并写盘，
-       * 端口每次启动都可能漂；反过来把探测也改成 `::`，关掉 IPv6 的机器上探测会因
-       * EAFNOSUPPORT 永远判「被占」，同样漂。各管一个协议族就没这个问题：`ipv6Only: true`
-       * 之后 v6 那个 socket 不碰 IPv4（不设这个标志在 Linux 上才会撞），同端口可以共存。
+       * 不合成一条双栈监听：`impl.js` 的端口占用探测真去 `listen(port, '0.0.0.0')` 试探，
+       * 一条双栈的 `::` 会把首选端口一律探成「被占」，于是落到内核随机端口、端口每次启动都
+       * 可能漂；把探测也改成 `::`，关掉 IPv6 的机器上又会因 EAFNOSUPPORT 永远判「被占」。
+       * 各管一个协议族就没这个问题。
        *
-       * 它是**软的**：只有「手机不在同一 Wi-Fi、只有 IPv6」时才用得上，绑不上就记一行、
-       * 只留 IPv4 直连——绝不影响 IPv4，也绝不往上抛。
+       * 它是软的：只有「手机不在同一 Wi-Fi、只有 IPv6」时才用得上，绑不上就记一行、只留 IPv4。
        */
       const startV6 = () => new Promise((onDone) => {
         const v6 = http.createServer(handleRequest);

package/lib/relay/pairing-policy.js

@@ -3,16 +3,13 @@
 /**
  * 配对授权策略。
  *
- * 被删除的桌面端用弹窗逐次确认；无头宿主没有这个界面，授权改由本地策略决定。
- * 两条链路都汇聚到父进程的 /api/relay/internal/approval：隧道收到 pairRequest 时，
- * 以及局域网代理的 onApprove。sidecar 只接受显式 true，所以 'deny' 与原来恒定
- * 返回 { approved: false } 的行为完全一致。
+ * 无头宿主没有弹窗确认界面，授权改由本地策略决定。两条链路都汇聚到父进程的
+ * `/api/relay/internal/approval`：隧道收到 pairRequest 时，以及局域网代理的 onApprove。
+ * sidecar 只接受显式 true，所以 'deny' 与恒定返回 `{ approved: false }` 等价。
  *
- *   'code' — 凭配对码放行。中转（dsh-mobile-server/server.js:400）与局域网
- *            （lib/relay/lan-proxy.js:243）在询问宿主之前都已用恒定时间比较校验过
- *            配对码，中转还有失败锁定；配对码只在用户主动索取时展示，可用
- *            /api/relay/regenerate 轮换、用 /api/relay/revoke-all 连同 lanSecret
- *            一并作废。
+ *   'code' — 凭配对码放行。两条链路在询问宿主之前都已用恒定时间比较校验过配对码，中转还有
+ *            失败锁定；配对码只在用户主动索取时展示，可用 `/api/relay/regenerate` 轮换、
+ *            用 `/api/relay/revoke-all` 连同 lanSecret 一并作废。
  *   'deny' — 拒绝一切新配对。
  */
 

package/lib/relay/preview.js

@@ -3,34 +3,17 @@
 /**
  * 预览字节管道（宿主侧）。
  *
- * 手机 App 的内置浏览器要能看到桌面机上「开发中的网页」，而那些 dev server 只监听
- * 宿主机的 127.0.0.1:<port>。手机、中转、局域网代理都够不着它，所以链路上必须有一
- * 段跑在宿主进程里的搬运工——就是这里。
+ * 手机 App 的内置浏览器要看到桌面机上「开发中的网页」，而那些 dev server 只监听宿主的
+ * 127.0.0.1:<port>，手机、中转、局域网代理都够不着。所以链路上有一段跑在宿主进程里的搬运工。
  *
- * 为什么是**字节管道**而不是又一个 HTTP 代理：
- * 一个页面不是「一次请求」而是「几百次请求」——ES 模块、CSS、图片、XHR、还有 HMR
- * 那条活着的 WebSocket。浏览器引擎自己发这些请求，App 侧的 JS 拦不住。所以端口只在
- * 建立管道时协商一次，之后这管道对内容一无所知，只搬字节。
+ * 是字节管道而不是 HTTP 代理：一个页面是几百次请求加一条活着的 HMR WebSocket，端口在建立
+ * 管道时协商一次，之后完全不解析内容。于是内置浏览器的地址栏与实际 Host 都是
+ * `localhost:3001`，dev server 生成的绝对地址自动闭环、零配置；做路径改写反而会立刻全 404。
  *
- * 这么做的收益是结构性的：内置浏览器地址栏里是 `http://localhost:3001/`，宿主机上
- * 的 dev server 看到的 Host 也是 `localhost:3001`——两边对「我在哪」的认知完全一致。
- * 于是 dev server 生成的一切绝对地址（资源路径、接口地址、跳转 Location、HMR 连接
- * 地址）都自动闭环，**dev server 零配置**。反过来说，如果这里做半吊子的路径改写，
- * `/assets/app.js` 这类绝对路径立刻全 404。
+ * 环回地址要双栈试（macOS 上不少 dev server 只监听 `::1`）。WS 升级、SSE、分块传输原样穿过。
  *
- * 这一层刻意「不认识」HTTP 与 WebSocket：
- *
- *   - 手机侧的原生模块把 WebView 写下的原始字节塞进 WebSocket 的二进制帧；
- *   - 这里 `net.connect(<环回地址>, port)` 之后双向对搬。环回地址要**双栈**试：macOS 上
- *     不少 dev server（Vite 等）默认只监听 `::1`，只拨 `127.0.0.1` 会连不上；
- *   - 中间任何一层都不解析、不改写，所以 WS 升级、SSE、分块传输、自定义子协议全都
- *     原样穿过（HMR 不用砍也不用绕——浏览器和 Vite 自己完成握手与分帧）。
- *
- * 代价要说清楚：正因为宿主无法审查内容，**端口就是这里唯一的边界**，所以下面有
- * `protectedPorts()` 那道按身份的拒绝（DSH 自身的 web 端口永远不许从预览进来）。
- *
- * 与仓库里 `dsh-mobile-server/scripts/adb-ws-bridge.cjs` 是同一个套路（原始 TCP 流包进 WebSocket 帧），
- * 那个先例证明这条路在本项目里走得通。
+ * 代价：宿主无法审查内容，端口就是唯一边界，所以 `protectedPorts()` 按身份拒绝——DSH 自身的
+ * web 端口永远不许从预览进来。
  */
 
 const net = require('node:net');

package/lib/relay/protocol.js

@@ -3,20 +3,13 @@
 /**
  * dsh-mobile-server 隧道协议 v2 编解码（取代 v1 的 JSON/base64 文本帧）。
  *
- * 每条隧道消息 = 一个 WS binary 帧：
- *   [type: 1B][id: 4B 大端][length: 4B 大端][payload: length B]
+ * 每条隧道消息 = 一个 WS binary 帧：`[type: 1B][id: 4B 大端][length: 4B 大端][payload]`。
+ * 数据通道的 payload 是原始字节（不再 base64），控制消息是 UTF-8 JSON，ping/pong 为应用层
+ * 心跳（经代理/负载均衡时比 WS 原生 ping 可靠）。
  *
- * - 数据通道（httpBody / httpChunk / wsText / wsBinary）的 payload 为
- *   原始字节，不再 base64（消除 ~33% 体积膨胀）；
- * - 控制消息（register / httpHead 等）payload 为 UTF-8 JSON；
- * - ping/pong 为应用层心跳（经代理/负载均衡时比 WS 原生 ping 更可靠）。
- *
- * 协议语义见 ../../../server/dsh-mobile-server/server/relay-core/PROTOCOL.md。
- *
- * 本文件是自包含副本（插件包不能跨目录引用中转仓库的文件），完整内联了共用类型表
- * 与编解码实现。类型表的事实源在独立中转仓库的 server/relay-core/protocol-types.js；
- * 本仓的 protocol-parity 测试钉住线格式，中转仓库另做 Rust 与 JS 字节对撞；
- * 改动帧编号后必须同步修改本文件。
+ * 本文件是自包含副本（插件包不能跨目录引用中转仓库）：完整内联了共用类型表与编解码实现。
+ * 事实源在中转仓库的 relay-core，本仓的 protocol-parity 测试钉住线格式；改动帧编号后必须
+ * 同步修改本文件。
  */
 
 const T = {

package/lib/relay/status.js

@@ -3,15 +3,12 @@
 /**
  * 中转状态视图：把「此刻这台宿主到底怎么样」拼成一份 JSON。
  *
- * 这份 JSON 有三个消费方，形状必须一模一样：桌面端设置页（`client.js`）轮询
- * `/api/mobile/v1/status`，手机端首屏也读同一条，而二维码里嵌的也是它的子集。
- * 以前它是 apply() 闭包里的一坨内联函数，混在 sidecar 生命周期与镜像推送之间——想核对
- * 某个字段拼对没有，只能通读 1000 行装配代码。抽出来之后可以直接 require 单元测试，
- * 也让 index.js 只剩装配。
+ * 这份 JSON 有三个消费方，形状必须一模一样：桌面设置页、手机首屏都轮询
+ * `/api/mobile/v1/status`，二维码里嵌的也是它的子集。抽出来之后可以直接 require 测试，
+ * index.js 只剩装配。
  *
- * 注意 `TUNNEL_ADMISSION`：它靠**正则匹配中转返回的错误文案**来判断隧道为什么被拒。
- * 这是个脆弱契约（中转改一个字就漏判），但在没有更好信号之前只能这样——错误文案是
- * 当前唯一穿过隧道边界回来的信息。判定放宽到只认关键词，见下。
+ * `TUNNEL_ADMISSION` 靠正则匹配中转返回的错误文案来判断隧道为什么被拒。这是个脆弱契约
+ * （中转改一个字就漏判），但错误文案是当前唯一穿过隧道边界回来的信号，判定放宽到只认关键词。
  */
 
 const os = require('node:os')

package/lib/relay/tunnel.js

@@ -44,18 +44,17 @@ class RelayTunnel {
    * @param {object} opts
    * @param {string} opts.relayUrl  隧道 WSS 地址（含 /tunnel），如 wss://relay.example.com/tunnel
    * @param {string} opts.instanceId
-   * @param {string} [opts.pairingCode] 仅本进程自用（面板显示）；**不发往中转**，见 registrationPayload
+   * @param {string} [opts.pairingCode] 仅本进程自用（面板显示），不发往中转
    * @param {string} [opts.name]
    * @param {string[]} [opts.lanUrls] LAN sidecar candidates (metadata only)
    * @param {object[]} [opts.lanCandidates] LAN candidate metadata (metadata only)
    * @param {string} opts.upstream  本地上游，如 http://127.0.0.1:52323
-   * @param {string} [opts.registerSecret] 中转侧 TUNNEL_REGISTER_SECRET 的对偶值。
-   *        优先于环境变量 DSH_RELAY_REGISTER_SECRET：桌面版 DSH 是从图标/启动台
-   *        拉起的，拿不到 shell 环境变量，密钥只能走 relay.json（0600）。
+   * @param {string} [opts.registerSecret] 中转侧 TUNNEL_REGISTER_SECRET 的对偶值，优先于环境
+   *   变量 DSH_RELAY_REGISTER_SECRET：桌面版从图标拉起时拿不到 shell 环境变量，密钥只能走
+   *   relay.json（0600）。
    * @param {() => void} [opts.onRegistered] 注册成功回调（用于状态展示）
    * @param {(code: number, reason: string) => void} [opts.onClose] 连接断开回调（用于断线重连）
-   * @param {(msg: {requestId: string, device?: {name?: string, ip?: string, platform?: string, osVersion?: string, version?: string, appVersion?: string, id?: string, deviceId?: string}}) => void} [opts.onPairRequest]
-   *        中转转发来的配对授权请求（手机配对码已通过校验，需桌面用户确认）
+   * @param {(msg: object) => void} [opts.onPairRequest] 中转转发来的配对授权请求（配对码已校验）
    * @param {(msg: string) => void} [opts.onLog]
    */
   constructor(opts) {
@@ -110,15 +109,11 @@ class RelayTunnel {
   }
 
   /**
-   * 发送队列积压到上限时**只丢这一帧，不断开隧道**。
+   * 发送队列积压到上限时只丢这一帧，不断开隧道。
    *
-   * 旧实现在两个分支里都 `ws.terminate()`：积压超限时把整条隧道掐掉。可积压本身是
-   * 「手机/中转读得慢」，不是「隧道坏了」——掐掉它，所有设备（包括正在正常转发的
-   * 那些）一起掉线，还要等 5s 重连。中转侧的同名判定（dsh-mobile-server/lib/proxy-http.js
-   * 的 sendFrame）已经改成只 `return false`，两侧口径必须一致：丢一帧可以恢复，
-   * 关一条隧道是全网断流。
-   *
-   * 真正的「隧道已死」由心跳兜底：PONG_TIMEOUT_MS 收不到 pong 时才会 terminate。
+   * 积压本身是「手机/中转读得慢」，不是隧道坏了；掐掉整条隧道会让所有设备一起掉线再等 5s
+   * 重连。中转侧的同名判定已经改成只 `return false`，两侧口径必须一致：丢一帧可以恢复，
+   * 关一条隧道是全网断流。真正的「隧道已死」由心跳兜底：收不到 pong 才 terminate。
    */
   dropOverBudget(bytes, frameLength) {
     const total = bytes + frameLength;

package/lib/routes/control-plane.js

@@ -3,19 +3,13 @@
 /**
  * 控制面路由（`/api/relay/*`）：桌面端设置页与宿主本机运维动作走这里。
  *
- * 与移动端路由表（lib/routes/mobile-api.js）是刻意的两套：控制面只认本机来源
- * （localOnly），移动端只认 token（guarded）。这条不对称是有原因的——控制面会读
- * 进程级错误账本（含堆栈）并且能改配置、能吊销全部授权，暴露给中转等于把桌面端的
- * 后门开到公网；反过来，移动端请求可能来自中转，根本没有本机 socket 可言。
+ * 与移动端路由表是刻意的两套：控制面只认本机来源（localOnly），移动端只认 token（guarded）。
+ * 控制面会读进程级错误账本（含堆栈）、能改配置、能吊销全部授权，暴露给中转等于把后门开到
+ * 公网；反过来移动端请求可能来自中转，根本没有本机 socket 可言。
  *
- * 抽出来的原因与移动端路由表一样：它们原本是 apply() 闭包里连着 130 多行的注册语句，
- * 混在 sidecar 生命周期与镜像推送之间，改一条路由要在 1000 行文件里找。依赖以
- * 取值器/函数注入，不捕获对象——闭包里那些 `let`（sidecarSnapshot、lanPortAdjusted、
- * sidecarState…）会被整体替换或重新赋值。`getSidecar` 尤其重要：sidecar 会被自重启换掉，
- * 拿到实例本身就等于拿到一份指向旧 facade 的快照。
- *
- * 插件更新那两条：`check` 自己问 npm 注册表（不要求外壳在场），`apply` 只委托外壳的
- * `apply`（判定 / 装 / 换代 / 落账同一层）——各自的取舍写在路由头上。
+ * 依赖以取值器 / 函数注入，不捕获对象：闭包里那些 `let`（sidecarSnapshot、sidecarState…）
+ * 会被整体替换。`getSidecar` 尤其重要：sidecar 会被自重启换掉，拿到实例就等于拿到旧 facade
+ * 的快照。
  */
 
 const fs = require('node:fs');
@@ -99,14 +93,10 @@ function createWebAccessLocalOnly({ localOnly, trustedLocalUi, webAccessWindow,
 }
 
 /**
- * 面板页（`React/` 那份 React 源码构建成的单文件 HTML）在包里的位置。
- *
- * 用 `__dirname` 而不是包根，是为了「谁跟着这份路由一起走」：HTML 是**提交物**，和
- * `lib/` 在同一份安装里，装哪个版本就带哪个版本的页面。
+ * 面板页（`React/` 构建成的单文件 HTML）在包里的位置。
  *
- * 这段注释过去写的是「控制面路由住在实现代 `lib/.live/<releaseId>/` 里，改版式不用重装」——
- * 那套「稳定外壳 + 可热替换的代」随插件 OTA 在 2026-10 一起删了（A5-02）。现在改版式只有
- * 一条路：`React/` 里重建 → 提交产物 → 发新版本 → 市场里更新 → 完整重启 DSH。
+ * 用 `__dirname` 而不是包根：HTML 是提交物，和 `lib/` 在同一份安装里，装哪个版本就带哪个
+ * 版本的页面。改版式只有一条路：`React/` 里重建 → 提交产物 → 发新版本 → 完整重启 DSH。
  */
 const PANEL_FILE = path.join(__dirname, '..', 'panel', 'index.html');
 
@@ -145,20 +135,15 @@ function panelHtml() {
 }
 
 /**
- * 面板读不到时，说清楚**是哪一种读不到**。
+ * 面板读不到时，说清楚是哪一种读不到。
  *
- * 这条是给「装了但打不开」的现场用的。过去这里只有一句「去 `React/` 里跑一次
- * pnpm run build」，那是**开发树**才遇得到的情况；装到别人机器上时它几乎总是另外两件事：
+ * 两种情形解法完全不同，所以分开报，并把路径与版本一起带上：
+ * 1. 安装目录整个不见了——市场里装/更新过、DSH 还没完整重启，跑着的仍是旧实例，而旧实例
+ *    所在的目录已被这次安装删掉。代码在内存里所以路由照常响应，`fs` 一读就 ENOENT。解法是
+ *    重启 DSH，不是去跑构建。
+ * 2. 这份安装里根本没有产物——老版本还没有这一页。解法是更新到当前版本。
  *
- *  1. **安装目录整个不见了**（2026-10-10 实测现场）：在插件市场里装/更新过、DSH 还没完整
- *     重启，跑着的仍是旧实例，而旧实例所在的 pnpm 目录已经被这次安装删掉了 —— 代码在内存里，
- *     所以路由照常响应，`fs` 一读就 ENOENT，面板页于是吐一段 JSON。解法是**重启 DSH**，
- *     不是去跑构建。
- *  2. **这份安装里根本没有产物**：0.1.47 及更早的版本还没有这一页（`files` 白名单当时
- *     没收 `lib/` 下的 html），老包里点开就是这条。解法是**更新到当前版本**。
- *
- * 两件事的解法完全不同，所以分开报，并把路径与版本一起带上 —— 下次看到这段报错，一眼就知道
- * 该重启还是该升级。三种情形由 `test/panel-artifact.test.cjs` 钉住。
+ * 三种情形由 `test/panel-artifact.test.cjs` 钉住。
  *
  * @param {{panelFile?: string, packageDir?: string}} [paths] 只给测试喂临时目录用；运行时走默认路径
  * @returns {{reason: 'install-gone'|'artifact-missing'|'unreadable', message: string}}
@@ -358,18 +343,16 @@ function registerControlPlaneRoutes(deps) {
   registerRoute({ kind: 'exact', path: '/api/relay/addresses', handler: localOnly('GET', async (_req, res) => {
     const port = lanPortInUse()
     const preferred = typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : ''
-    sendJson(res, 200, { ok: true, port, preferred, lan: lanCandidates(port), public: publicCandidates(port), ipv6: ipv6Candidates(port) })
+    // `manual` 是用户手填的直连地址（内网穿透域名）：网卡扫不出来，所以单列一格让面板回显与修改。
+    const manual = typeof state.manualLanUrl === 'string' ? state.manualLanUrl : ''
+    sendJson(res, 200, { ok: true, port, preferred, manual, lan: lanCandidates(port), public: publicCandidates(port), ipv6: ipv6Candidates(port) })
   }) })
   /**
    * 公用中转候选的测速（`POST /api/relay/probe-relays`，body `{ urls: string[] }`）。
    *
-   * **为什么必须由宿主代测**：引导页在浏览器里打开，直连那些中转域名会被 CORS 挡住
-   * ——读到的是浏览器拦截，不是真实耗时，而且会把可用入口误判成不通。宿主是本机进程，
-   * 出站没有 CORS 可言，测出来的才是用户实际能用的那条。
-   *
-   * 判定分两步：`/healthz` 回 2xx **且** `/api/mobile/v1/health` 回的 `service` 是 `dsh-mobile-relay`。
-   * 只看 `/healthz` 不行——任何静态站都可能回 200，随手敲一个域名就被当成「可用中转」。
-   * 超时的照实报 `null`（前端按「不通」排在后面），不编造数字。
+   * 必须由宿主代测：引导页在浏览器里，直连那些域名会被 CORS 挡住，读到的是浏览器拦截而不是
+   * 真实耗时。判定分两步：`/healthz` 回 2xx 且 `/api/mobile/v1/health` 回的 `service` 是
+   * `dsh-mobile-relay`——只看 `/healthz` 的话任何静态站都会被当成可用中转。超时照实报 null。
    */
   registerRoute({ kind: 'exact', path: '/api/relay/probe-relays', handler: localOnly('POST', async (req, res) => {
     const body = await readJson(req)
@@ -392,7 +375,7 @@ function registerControlPlaneRoutes(deps) {
           return { url, ms: null }
         }
         // **只认运维意义上「这一台确实是中转」**：`/healthz` 回 200 的站点满互联网都是，
-        // 光看它等于把 qq.com 也当可用中转（2026-10-24 用户实测随手敲一个就过）。
+        // 光看它等于把随便一个域名也当可用中转。
         // 中转自己那条地址体检 `/api/mobile/v1/health` 会带回 `service`，对不上就不是它。
         const who = await fetch(`${url}/api/mobile/v1/health`, { signal: controller.signal, redirect: 'follow' })
           .then((r) => (r.ok ? r.json() : null))
@@ -538,7 +521,7 @@ function registerControlPlaneRoutes(deps) {
     /**
      * `?relayUrl=` 是**只看不写**的预览：按这个候选地址生成二维码，但一个字都不落盘。
      *
-     * 给「自建中转填完就想看到码」用（2026-10-24 用户要求）。以前那版是「填完就把地址写进
+     * 给「自建中转填完就想看到码」用。以前那版是「填完就把地址写进
      * 配置」，等于拿一条还没验过的地址覆盖正在用的设置；现在预览走这里，真写入只在用户
      * 明确按下「连接中转」时发生。
      */
@@ -703,9 +686,9 @@ function registerControlPlaneRoutes(deps) {
     await syncSidecar()
     sendJson(res, 200, status())
   }) })
-  // ── 插件更新（2026-10 搬回自更新之后重新有这四条）──
+  // ── 插件更新 ──
   //
-  // 分工（2026-10-11 起）：**查归插件自己**（问 npm 注册表，`../update-registry.cjs`）、
+  // 分工：**查归插件自己**（问 npm 注册表，`../update-registry.cjs`）、
   // **装也归插件自己**（在 profile 里跑它自己的包管理器，`../update-install.cjs`），
   // **换代码留给外壳**（`lib/index.js` 的 runtime）。市场不再是这条路上的任何一环。
   //
@@ -733,7 +716,7 @@ function registerControlPlaneRoutes(deps) {
   // 拿不到（无头部署 / 没有外壳的那一版）就退回这一代自己的版本号。
   registerRoute({ kind: 'exact', path: '/api/relay/update/check', handler: localOnly('POST', async (_req, res) => {
     const runtime = pluginRuntime()
-    // 形状必须和上面那条 `update/status` **一模一样**（含 `available`）。2026-10-11 的真机现场：
+    // 形状必须和上面那条 `update/status` **一模一样**（含 `available`）：
     // 这条只回 `runtime.status()`，面板拿它 `setHost()` 覆盖掉好状态，`available` 变成 undefined，
     // 卡片当场从「宿主模式」掉进取降级那一半 —— 用户看到的现象是「有新版本却没有『立即更新』」。
     const snapshot = runtime ? { available: true, ...runtime.status() } : null
@@ -757,7 +740,7 @@ function registerControlPlaneRoutes(deps) {
   // 装器装新版、装完就地换代，并把这次结果写进它那本 `lastApply` 账 —— 面板「最近一次更新」
   // 与那颗「强制更新」按钮的「上次没装成」判据读的都是这本账。
   //
-  // 为什么这条路由不再自己去装（2026-10-12 改）：从前它自己调 `installLatestIfNeeded` 再
+  // 为什么这条路由不再自己去装：从前它自己调 `installLatestIfNeeded` 再
   // `reload`，判定确实和自动更新是同一套（外壳那条路最后也走盘上那一代的同一个函数），
   // **但结果没人落账** —— 手动（含强制）更新装完，外壳的账一动不动，面板那一行永远停在上一次
   // 自动更新的结果上。判定与记账必须是同一个动作，所以这里只负责传参、把外壳记完账的状态

package/lib/routes/mobile-api.js

@@ -3,20 +3,12 @@
 /**
  * 移动端 API 路由表（`/api/mobile/v1/*`）。
  *
- * 这块此前是 lib/index.js 里连续 120 多行的注册语句，与控制面路由、sidecar 生命周期、
- * 镜像推送调度器混在同一个 apply() 闭包里。它本身没有任何逻辑——绝大部分是「路径 → 已
- * 写好的 handler」的纯映射，只有 status / connection-info / desktop-view 三条带一点内联
- * 逻辑——但混在装配代码里有两个代价：
+ * 它本身没有逻辑，绝大部分是「路径 → 已写好的 handler」的纯映射，只有 status /
+ * connection-info / desktop-view 三条带一点内联逻辑。抽成一张表，是为了能一眼确认「App 打的
+ * 某个地址到底注册没有」——历史上 `workspace/rename` 与 `workspace/archive-session` 就是
+ * App 一直在打、插件从来没注册，手机端必然 404；这张表也能直接对着 App 侧 apiPaths.ts 核对。
  *
- *   1. 想确认「App 打的某个地址到底注册没有」必须人工通读 apply()。
- *      历史上 `workspace/rename` 与 `workspace/archive-session` 就是 App 一直在打、
- *      插件从来没注册，手机端必然 404。
- *   2. 改一条路径要在 1000 行文件里找。
- *
- * 现在它是一张可以一眼读完、可以对着 App 侧 apiPaths.ts 核对的表。
- *
- * 依赖注入只留三样：注册器、移动端守卫、以及两个会变的值。handler 们直接 require，
- * 因为它们本来就只是被这张表挂上去的。
+ * 依赖注入只留注册器、移动端守卫与几个收益于取值器的值；handler 们直接 require。
  */
 
 const { sendJson } = require('../http/routing.js');
@@ -67,25 +59,17 @@ const API_VERSION = '1';
  * @param {(handler: Function) => Function} deps.guarded 移动端守卫（token + 500 信封）
  * @param {object} deps.state 内存里的中转状态（本进程唯一真值）
  * @param {() => object} deps.hostMetadata 宿主元信息（隧道准入状态等）
- * @param {() => object} deps.getSidecarSnapshot 取快照的**取值器**。
- *   这里必须传函数而不是对象：sidecarSnapshot 是会被 applySidecarConfig 整体替换的
- *   let 变量，闭包捕获对象会让 handler 永远读到启动那一刻的旧快照（lan.updatedAt 停在
- *   进程启动时间，手机端看连接信息像失联了一样）。
+ * @param {() => object} deps.getSidecarSnapshot 取快照的取值器，必须传函数：快照会被整体替换，
+ *   闭包捕获对象会永远读到启动那一刻的旧快照。
  * @param {(port: number) => Array<object>} deps.safeLanCandidates 局域网候选地址
- * @param {(port: number) => Array<object>} deps.safeIpv6Candidates 公网 IPv6 直连候选。
- *   与上面那份并列、不并进它：手机拿这份和中转实测比快慢，掺进局域网那份就等于让它
- *   跟「同一个 Wi-Fi」共用一套失败退避（手机刚离开家里 Wi-Fi 时正是最该试它的时候）。
- * @param {() => number} deps.lanPortInUse 手机该拨的局域网端口。**必须用取值器**：
- *   sidecar 自己 bind 到的端口可能与本进程解析出的不同（两条端口自适应），只认
- *   `state.lanPort` 会把这个接口变成「报一个没人监听的端口」——真机实测过 50933
- *   死地址把手机逼回公网中转（见 impl.js 的 advertisedLanPort）。
- * @param {(route: { path: string, handler: Function }) => void} deps.registerUpgradeRoute
- *   交给 ctx.webServer 的**升级**路由注册器（`registerUpgrade`）。与 registerRoute 是
- *   两套名字空间：同一个 path 可以既有一条普通路由又有一条升级路由，但升级路由重复注册
- *   会抛错。
- * @param {object} deps.preview 预览字节管道服务（lib/relay/preview.js）。它自带鉴权与
- *   端口边界，所以**不能**包在 guarded 里——guarded 回的是 JSON，而升级请求需要的是
- *   一次拒绝或一次握手。
+ * @param {(port: number) => Array<object>} deps.safeIpv6Candidates 公网 IPv6 直连候选，与上一份
+ *   并列：手机拿它和中转比快慢，掺进局域网那份会共用失败退避。
+ * @param {() => number} deps.lanPortInUse 手机该拨的局域网端口，必须用取值器：sidecar 实绑的
+ *   端口可能与 state 里解析出的不同。
+ * @param {(route: { path: string, handler: Function }) => void} deps.registerUpgradeRoute 升级路由
+ *   注册器；与 registerRoute 是两套名字空间，同一 path 可以两者都有，但升级路由重复注册会抛错。
+ * @param {object} deps.preview 预览字节管道服务。它自带鉴权与端口边界，不能包在 guarded 里——
+ *   升级请求需要的是一次拒绝或一次握手，不是 JSON。
  */
 function registerMobileRoutes(deps) {
   const { registerRoute, registerUpgradeRoute, guarded, state, hostMetadata, getSidecarSnapshot, safeLanCandidates, safeIpv6Candidates, lanPortInUse, preview, core, pairingApproval, rotatePairing } = deps;
@@ -122,7 +106,7 @@ function registerMobileRoutes(deps) {
   // 凭据，所以这条刻意不包 guarded（豁免与理由见 test/mobile-routes.test.cjs 的
   // PUBLIC_ROUTES）。它能说的话只有服务名与版本——没有实例信息、没有任何能力面。
   // 中转侧在 server.js 的同名路径上回 'dsh-mobile-relay'，App 靠这个字段分辨
-  // 「填的是宿主还是中转」（消费方 app/src/services/addressProbe.ts）。
+  // 「填的是宿主还是中转」。
   //
   // ⚠️ 签名必须是 `(req, res)` **两个**参数：宿主 webServer 就是 `handler(req, res)` 调的，
   // 上面那条 `guarded(...)` 之所以能收 `(ctx, req, res)`，是因为那三个参数由 guarded 自己补。
@@ -278,6 +262,9 @@ function registerMobileRoutes(deps) {
   // 「宿主最近收到的快照」；从未收到过时返回 view: null，App 按桌面的折叠缺省处理。
   route('/api/mobile/v1/desktop-view', async (_ctx, _req, res) => sendJson(res, 200, { ok: true, view: desktopView.snapshot() }))
   route('/api/mobile/v1/directory/list', workspaces.handleListDirectory)
+  // 盘符层：宿主 browse 后端只列目录内容、不枚举盘符，主目录在 C 盘时手机端看不到别的盘
+  // （Windows 多硬盘现场）。枚举在被控端做，见 mobile/drive-roots.js。
+  route('/api/mobile/v1/directory/roots', workspaces.handleDirectoryRoots)
   // 右栏文件浏览器要的那一份：文件与文件夹都列、带类型/大小/修改时间，见
   // mobile/directory-listing.js。与上面那条**并存**：那条是「挑工作区目录」用的，只列
   // 能进去的目录，行为不变。