dsh-mobile-plugin 0.5.23 → 0.5.24

package/lib/client.js

@@ -104,7 +104,7 @@ window.__ModuleLoader__.load({
      * 浏览器侧的应用路由一律写成**文档相对**形式（没有前导斜杠），与 DSH 自己的客户端
      * 一致：宿主给 index 注入了 `<base href="./">`，页面挂在哪个前缀下，请求就跟着哪个
      * 前缀走。写成 `/api/...` 这种站点根绝对地址，DSH 被反向代理挂到子路径（例如
-     * `/dsh/`）时会直接打到站点根、拿回 404 —— 现场看到的正是「读取宿主状态失败: HTTP 404」。
+     * `/dsh/`）时会直接打到站点根、拿回 404。
      */
     const DESKTOP_VIEW_ENDPOINT = 'api/relay/desktop-view';
 
@@ -739,8 +739,7 @@ window.__ModuleLoader__.load({
         }
         if (spec.title) overlay.setAttribute('aria-label', spec.title);
         // 每次重画：读数与按钮都是这一轮的现场，别留上一轮的字。
-        // **`children` 是 HTMLCollection，没有 `slice()`**（2026-11-05 真机现场：点图标一点反应都
-        // 没有，控制台一条 TypeError 就把它吞了 —— 假元素的 `children` 是数组，测试里从没红过）。
+        // **`children` 是 HTMLCollection，没有 `slice()`**（假元素是数组，测试覆盖不到）；
         // 先摊成数组再边删边走。
         for (const child of Array.from(overlay.children || [])) child.remove();
         const card = spec.wide
@@ -931,8 +930,8 @@ window.__ModuleLoader__.load({
      *
      * 为什么不能只读一次 `/status`：那条接口自己也在窗口门后面（`WEB_ACCESS_ROUTES`），
      * 窗口关着时**不是本机**的浏览器只拿得到 423。而客户端原先规定「没地址就不去开窗口」，
-     * 两边互相锁死 —— 远程用户点了只会看到「网页地址还没就绪」，没有任何顺序能走通
-     * （2026-11-03 用户报的就是这个）。所以读不到地址时正确的动作不是放弃，而是**先开窗**：
+     * 两边互相锁死 —— 远程用户点了只会看到「网页地址还没就绪」，没有任何顺序能走通。
+     * 所以读不到地址时正确的动作不是放弃，而是**先开窗**：
      * 那条开关接口本来就对同源页面豁免，开完再读一次，地址与类别就都有了。
      *
      * 地址优先用宿主给的 `panelUrl`，拿不到再用页面自己的同源地址（见 `sameOriginPanelUrl`）。
@@ -1043,7 +1042,7 @@ window.__ModuleLoader__.load({
     /** 还没问到网页地址时的重试间隔。取到就停，不再问。 */
     const FOOTER_URL_RETRY_MS = 20000;
     /**
-     * 手机图标（用户 2026-11-02 从八个候选里挑的「刘海 + 底条」那一款）：24 画布描边，
+     * 手机图标（「刘海 + 底条」那一款）：24 画布描边，
      * 机身 6.2→17.8、圆角 2.8，顶上一条刘海、底下一条家条。比早先那版机身更满一点，
      * 因为窄高的形状按名义尺寸画出来会比旁边的方形图标显小。
      */
@@ -1053,7 +1052,7 @@ window.__ModuleLoader__.load({
       'M11 19.4h2',
     ];
     /**
-     * 告警态那颗红点（用户 2026-11-05 从四个候选里拍的「整颗转红 + 右上角一颗点」那一款）。
+     * 告警态那颗红点（「整颗转红 + 右上角一颗点」那一款）。
      *
      * 圆心在机身右上角外侧：左缘压住右上那圈圆角（机身右边到 17.8），两块同色连成一整块，
      * 所以不用再抠一圈背景色的缝隙。24 画布内放得下——最右到 22，不越界。
@@ -1062,11 +1061,11 @@ window.__ModuleLoader__.load({
      */
     const PHONE_ALERT_DOT = { cx: 18.9, cy: 5, r: 3.1 };
     /**
-     * 图标边长：展开那一行 20，窄条里的圆钮 22（用户 2026-11-02 拍的，先 18 后嫌小又抬了一档）。
+     * 图标边长：展开那一行 20，窄条里的圆钮 22。
      *
      * 那一行的账号按钮高 44、里面真正画出来的只有 24 的头像，同行其它图标是 16。20 是
      * 28 的按钮里还能四边各留 4 像素的上限；窄条那颗放进 36 的圆钮里，用 22。
-     * 别再往回调 16 / 18：手机图形窄，按名义尺寸画出来比同行的方形图标显小，用户两次都说小。
+     * 别再往回调 16 / 18：手机图形窄，按名义尺寸画出来比同行的方形图标显小。
      * 真要再大，得连按钮一起撑到 30 以上——那一行其它按钮都是 28，会开始抢。
      */
     const PHONE_GLYPH_WIDE = 20;
@@ -1116,8 +1115,8 @@ window.__ModuleLoader__.load({
      * 把「打开哪一页 / 现在能不能点」同步到元素上。
      *
      * 没有地址时**不写 href**（没有地址可写，别挂死链），但**点击处理照样挂上**：那颗图标的
-     * 点击会自己去把两小时窗口开出来、再读一次地址（见 `openConfigurationPage`）。原先这里
-     * 把 `onclick` 一起摘掉，现场就是「点了完全没反应」——2026-11-03 用户报的正是这个。
+     * 点击会自己去把两小时窗口开出来、再读一次地址（见 `openConfigurationPage`）。别把
+     * `onclick` 一起摘掉 —— 摘了就是「点了完全没反应」。
      *
      * 地址、网络类别和窗口状态都由 effect 往上同步，组件重渲染不会把它丢掉。
      */
@@ -1172,7 +1171,7 @@ window.__ModuleLoader__.load({
      * 就画在 `sidebar.footer.action` 自己那一行（居中摞在设置上方）——这一条是物理限制，
      * 不是退路。认不出那一行的时候也走这条路，入口不会消失。
      *
-     * 点下去做什么（2026-11-02 用户拍板）：宿主在 `/status` 上按请求 Host 报一个
+     * 点下去做什么：宿主在 `/status` 上按请求 Host 报一个
      * `panelScope`，图标据此分流：
      *   - `loopback`：人就在这台机器的 DSH 里，控制面本来就认它 —— 普通链接跳转；
      *   - `private` / `public`：浏览器是从别的机器来的，控制面不认它、面板会回 423，
@@ -1253,9 +1252,9 @@ window.__ModuleLoader__.load({
        * 只有**网页**（`http(s)`）才需要这一手：桌面壳里那个函数一定被拒，见 `isWebPage`。
        */
       /**
-       * 点下去做什么（2026-11-05 用户要求改过一次）。
+       * 点下去做什么。
        *
-       * **从「点了就跳浏览器」改成「点了先在这一页弹一屏」**：用户遇到问题时最缺的不是
+       * **点了先在这一页弹一屏**（不是直接跳浏览器）：用户遇到问题时最缺的不是
        * 跳过去，而是「它现在到底哪一环断了」——启动、装载、隧道、旁挂进程、自检全都在那一屏
        * 里，比一个打不开的页面有用。跳转本身没取消，挪进了那一屏里的一颗按钮。
        *
@@ -1344,9 +1343,9 @@ window.__ModuleLoader__.load({
         };
 
         /**
-         * 第一层：**只有一个简单入口**（2026-11-05 用户要求）。
+         * 第一层：**只有一个简单入口**。
          *
-         * 原来点图标一上来就是整屏读数，太重了 —— 绝大多数时候人只是想去配置页，或者去看
+         * 一上来就整屏读数太重 —— 绝大多数时候人只是想去配置页，或者去看
          * 手机为什么连不上。所以这一层只摆两块：左边「进入控制台」（= 原来那个跳转），
          * 右边「报错调试」（才进第二层那一屏）。
          */
@@ -1796,9 +1795,9 @@ window.__ModuleLoader__.load({
     }
 
     /* ── 设置里的那一项「移动端」───────────────────────────────────────────
-     * 用户 2026-11-03 要求加回来：介绍产品时说的入口就是「设置 → 移动端」，2026-11-02 那一版
-     * 把它整块下线、只留侧边栏那颗图标，于是从网页版进来的人不知道配置在哪。现在两项都在，
-     * 它们进的是同一个页面、走同一条拨号链路（图标是快捷方式，这一张是设置里的正规入口）。
+     * 设置里的「移动端」与侧边栏那颗图标进的是同一个页面、走同一条拨号链路（图标是快捷方式，
+     * 这一张是设置里的正规入口）：介绍产品时说的入口就是「设置 → 移动端」，只留图标会让从
+     * 网页版进来的人不知道配置在哪。
      *
      * 刻意只有一张薄卡：界面本体全在网页版里（A3-37），在这里再画一套等于长期维护第二套 UI，
      * 而两套迟早会打架。卡片只做两件事——说清配置在哪、把那一页开出来；开不出来就在卡上写原因。

package/lib/impl.js

@@ -32,7 +32,7 @@ const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates, withManu
 // 配对二维码的载荷：面板与终端命令共用一份，拼装在 `./relay/pairing-payload.cjs`。
 const { pairingPayload, pairingText } = require('./relay/pairing-payload.cjs')
 const { resolvePort } = require('./relay/port-allocator.cjs')
-const { mountTailcat } = require('./tailcat/wiring.cjs') // 直连隧道：入口 + 助手会话 + 启停
+const { mountTailcat, chooseTailcatTarget } = require('./tailcat/wiring.cjs') // 直连隧道：入口 + 助手会话 + 启停
 const { createPreviewService } = require('./relay/preview.js')
 const { mountTerminal, mountCli } = require('./mobile/services.js')
 // 手机打开「电脑上的网页版」时用的那枚一次性登录令牌（见 mobile/host-web.js）。
@@ -304,7 +304,7 @@ function apply(ctx) {
   const lanPortInUse = () => (state.lanEnabled && effectiveLanPort > 0 ? effectiveLanPort : state.lanPort)
   const advertisedLanPort = () => (state.lanEnabled ? sidecarLifecycle.getAdvertisedLanPort() : state.lanPort) // 对外报地址用实绑端口，见 lifecycle
   // 直连隧道：不配中转也能连的兜底通道；挂不上就只是没这条通道，中转与局域网照旧。
-  const tailcat = mountTailcat({ mount, warn, state, saveState: core.saveState, lanPortInUse, hostName: () => state.name, ctx, name })
+  const tailcat = mountTailcat({ mount, warn, state, saveState: core.saveState, targetPort: chooseTailcatTarget({ lanEnabled: () => state.lanEnabled, lanPort: lanPortInUse, webPort: () => ctx.webServer.port }), hostName: () => state.name, ctx, name })
   // 每次同步前都跑一次探测，而不是只在启动时探一次：`/api/relay/config` 改了
   // lanPort 之后同样要走这条路（否则新端口被占时又会退回死地址）。并发调用复用
   // 在飞的那次——探测要占一个监听句柄，重复触发没有意义。

package/lib/mobile/cli/mobile.js

@@ -3,34 +3,10 @@
 /**
  * `cli-*` 会话的移动端适配层：让一条 CLI 对话走宿主普通会话那一整套接口。
  *
- * CLI 会话不是宿主的会话 —— 它是一条 ACP 子进程，块表在 `cli/blocks.js` 里。但对手机来说
- * 它必须长得跟普通会话一模一样：出现在侧栏列表里、点进去有历史、能发、能停、能选模型、
- * 会弹审批卡。所以这一层只做两个方向的翻译，不新造任何接口：
- *
- *   1. **请求方向**：`sessionId` 以 `cli-` 开头的，路由层先看一眼再交给这里（见
- *      `lib/routes/mobile-api.js`）。`sessionId` 在查询串（GET）或请求体（POST）里，所以
- *      分派只发生一次，不抄任何 handler。
- *   2. **帧方向**：ACP 的块表 → 宿主那套 `session/event` 帧。App 认哪几种、缺哪个就转圈，
- *      是按 `app/src/hooks/streamFrame.ts` 与 `app/src/utils/frameWatermark.ts` 逐条对出来的：
- *      `turn/start` / `turn/end` / `user/message` / `assistant/chunk` / `tool/result` /
- *      `approval/*` / `session/title` / `session/heartbeat`。
- *
- * 三条刻意的减法（都比着「App 到底靠什么落地」做的，不是省事）：
- *
- *   - **正文与工具的过程用草稿帧，落定的内容一律走历史。** 草稿（`assistant/chunk`）不需要
- *     seq、不会被序门丢掉；一轮结束先发 `turn/end`（reason=completed），再把这一轮每个块
- *     以稳定 id 发一条 `assistant/message`。id 与 `/session/messages` 的行 id 是同一个
- *     （块的 id），所以重连 / resync 按 id 合并，不会出现两遍。`assistant/message` 放在
- *     `turn/end` **之后**：App 在「当前回合」收尾时会把这条消息当成终局消息再收一次尾，
- *     先发 turn/end 就只是就地更新，不会提前把这一轮判成结束。
- *   - **审批卡照抄宿主那一种形状**（帧级 `rpcId` + payload `approvalId`，见 `approvals.js`）。
- *     App 只认这种卡；新造一种等于卡片永远不出现。回答仍走 `/approval/respond`，在这一层
- *     按 rpcId 找回 ACP 的挂起项。
- *   - **拿不到的字段给合理缺省，不报错。** 模型目录拿不到就回只有一项的清单；统计、队列、
- *     搜索这类一律回空；这条会话在每种接口上都可用，比「主链路通了、点别的报错」重要。
- *
- * 会话本身仍归 `cli/service.js` 托管（进程、块表、审批挂起项都在那儿），这里只拿它的
- * 只读门面。
+ * CLI 会话不是宿主会话，而是一条 ACP 子进程（块表在 `cli/blocks.js`），但对手机必须长得跟普通会话一样：侧栏有它、点进去有历史、能发能停能选模型会弹审批卡。所以这一层只做两个方向的翻译、不新造接口：
+ *   请求方向：`sessionId` 以 `cli-` 开头时路由层先看一眼再交给这里（见 `lib/routes/mobile-api.js`），分派只发生一次。
+ *   帧方向：ACP 块表 → 宿主 `session/event` 帧（帧种类按 App 实际认的对齐）。
+ * 三条刻意减法：过程走草稿帧（`assistant/chunk`）、落定内容一律走历史（`assistant/message` 放在 `turn/end` 之后）；审批卡照抄宿主形状（帧级 `rpcId` + payload `approvalId`，见 `approvals.js`）；拿不到的字段给合理缺省不报错。会话本身仍归 `cli/service.js` 托管。
  */
 
 const fs = require('node:fs')

package/lib/mobile/pairing.js

@@ -12,6 +12,11 @@
  * 请求体两种形状都认：老 App 的 `{ instanceId?, code, device }` 明文照旧；协议 v2 的
  * `{ instanceId, sealed }` 没有配对码，票据本身就是资格证明，回包同样是密文 —— 里面是
  * token / cookie / 设备凭据，明文回包等于让中转拿到这台设备的长期通行证。
+ *
+ * 协议 v2 的请求体还多了个可选 `ticketId`（批量同步导入用，见 docs/device-batch-sync.md）：
+ * 有它就从一次性券表（`mobile/transfer-tickets.js`）取那张券当票据，配成功后 `consume` 作废；
+ * 没有就沿用 `state.pairingTicket`（电脑面板二维码那条路，行为不变）。券由导出方手机向目标
+ * 电脑申领、塞进二维码，所以票据不再只能是面板上那一张 —— 这是本文件相对旧签名的唯一变化。
  */
 
 const { sendJson } = require('../shared/http-util');
@@ -103,10 +108,11 @@ function readBody(req) {
  * @param {(port: number) => Array<object>} [deps.lanCandidates] 直连候选（与 `/connection-info` 同一份）
  * @param {(port: number) => Array<object>} [deps.ipv6Candidates] IPv6 直连候选
  * @param {() => number} [deps.lanPort] 宿主实绑的直连端口（配置端口被占时会换）
+ * @param {object} [deps.transferTickets] 一次性券表（transfer-tickets.js）；有它才认 `ticketId`
  * @param {(message: string) => void} deps.log
  */
 function createPairHandler(deps) {
-  const { state, core, credentials, pairingApproval, lanCandidates, ipv6Candidates, lanPort, log } = deps;
+  const { state, core, credentials, pairingApproval, lanCandidates, ipv6Candidates, lanPort, transferTickets, log } = deps;
   /**
    * 配对成功之后换掉配对码与票据（§5.1）。
    *
@@ -168,9 +174,34 @@ function createPairHandler(deps) {
     let supplied;
     let issuedExtra;
     let pairKey = null;
+    // 这次配对若用的是一次性券，记下它的 ticketId，配成功后立刻作废；面板票据那条路留 null
+    // （它靠 rotatePairing 换码换票据，不是靠这里 consume）。
+    let ticketIdToConsume = null;
     if (isSealedShape) {
+      // 票据来源：带 ticketId 就从一次性券表取（批量同步导入）；否则沿用面板那张 state 票据。
+      const ticketId = typeof body.ticketId === 'string' ? body.ticketId.trim() : '';
+      let ticket = state.pairingTicket;
+      if (ticketId) {
+        ticket = transferTickets && typeof transferTickets.resolve === 'function'
+          ? transferTickets.resolve(instanceId, ticketId)
+          : null;
+        // 券不存在 / 过期 / 已用：与「配对码错误」同形拒绝，不给探测空间。
+        // 券不存在 / 过期 / 已用：与「配对码错误」不同，这里可以点明 —— 券是不可猜的随机串
+        // （不像六位配对码能逐位试），明说「用过或过期，请另一台手机重新导出」不给出探测空间，
+        // 又能让批量导入方一眼知道该干什么，而不是对着一句「配对码错误」去重扫。
+        if (!ticket) {
+          throttle.noteFail();
+          sendJson(res, 401, {
+            ok: false,
+            code: 'transfer-ticket-invalid',
+            error: '这个二维码已被使用或已过期，请让导出方那台手机重新导出后再扫',
+          });
+          return;
+        }
+        ticketIdToConsume = ticketId;
+      }
       const opened = openSealedPairRequest({
-        ticket: state.pairingTicket,
+        ticket,
         instanceId,
         sealed,
         claimedInstanceId: typeof body.instanceId === 'string' ? body.instanceId : '',
@@ -225,8 +256,17 @@ function createPairHandler(deps) {
       return;
     }
 
-    // 成功签发之后立刻换码 + 换票据：谁截了二维码，那张图从这一刻起就没有用了。
-    if (rotatePairing) {
+    // 成功签发之后立刻作废资格：
+    //  · 用一次性券配的 → consume 那张券（同一张配不了第二台手机）；面板的码与票据不动，
+    //    因为这次配对根本没用到它们、也不该让别人的面板二维码跟着失效。
+    //  · 面板二维码那条老路 → 换码 + 换票据（谁截了那张图，从这一刻起就没有用了）。
+    if (ticketIdToConsume && transferTickets && typeof transferTickets.consume === 'function') {
+      try {
+        transferTickets.consume(instanceId, ticketIdToConsume);
+      } catch (error) {
+        log('pair ticket consume failed:', error && error.message);
+      }
+    } else if (rotatePairing) {
       try {
         rotatePairing();
       } catch (error) {

package/lib/mobile/phone/service.js

@@ -22,7 +22,7 @@
  *   - `{t:'event', kind:'needs-human'|'progress', sessionId, …}` —— 暂只记账，不转发
  *
  * 宿主 → 手机：
- *   - `{t:'op', id, sessionId, action, args}`
+ *   - `{t:'op', id, sessionId, action, args, timeout}` —— timeout 是这一发自适应算出的预算(ms)
  *   - `{t:'cancel', id}`
  *
  * 动作名是封闭的一小张表（见 `ACTIONS`）；手机端认不出的动作回 `unsupported`，宿主不会因为
@@ -40,8 +40,13 @@ const { WebSocketServer } = require('ws');
 
 /** 一条帧的上限：截图是 base64 塞在 JSON 里的，留足余量；更大的东西手机不会发。 */
 const MAX_PAYLOAD = 12 * 1024 * 1024;
-/** 心跳：手机每 20 秒至少要有一次 ping/pong 往返，否则按掉线处理（等它自己重连）。 */
+/** 心跳间隔：每 20 秒发一次 ping。 */
 const HEARTBEAT_MS = 20_000;
+/**
+ * 连续丢这么多次心跳（约 60 秒）才按掉线处理，对齐手机端 60s 看门狗。
+ * 弱网下偶发一两次丢 pong 不算掉线，免得来回假掉线、把在途 op 全抹成 offline。
+ */
+const MAX_MISSED_HEARTBEATS = 3;
 /** 单次 op 的默认预算；每个动作另有自己的一档（见 ACTIONS）。 */
 const DEFAULT_OP_TIMEOUT_MS = 30_000;
 
@@ -85,6 +90,44 @@ function createPhoneService({ authorized, onLog } = {}) {
   let closed = false;
   let seq = 0;
 
+  /** 耗时 EWMA 的平滑系数：动作耗时用 0.3，心跳 RTT 用 0.2。 */
+  const EWMA_ALPHA = 0.3;
+  const RTT_ALPHA = 0.2;
+
+  function ewma(prev, sample, alpha) {
+    if (!prev || !(prev.n > 0) || !Number.isFinite(prev.value)) return { value: sample, n: 1 };
+    return { value: prev.value * (1 - alpha) + sample * alpha, n: prev.n + 1 };
+  }
+
+  /** 成功回包按「发送 → 收到」耗时更新 perAction 与全体两类统计。 */
+  function recordLatency(link, action, sample) {
+    if (!Number.isFinite(sample) || sample < 0) return;
+    const lat = link.latency;
+    lat.perAction.set(action, ewma(lat.perAction.get(action), sample, EWMA_ALPHA));
+    lat.all = ewma(lat.all, sample, EWMA_ALPHA);
+  }
+
+  /**
+   * 某动作这一发该给多少预算：估时 est 取自本动作（样本够）或全体，套 est*2.5 + rtt*2 + 1500，
+   * 冷启动抬到 seed*1.5 兜底，最后夹进 [max(2500, seed/2), min(120000, max(seed*8, floor))]。
+   * `ACTIONS` 里的数字只是这个 seed，不再直接当预算。
+   */
+  function budgetFor(link, action) {
+    const seed = ACTIONS.get(action) || DEFAULT_OP_TIMEOUT_MS;
+    const lat = link.latency;
+    const pa = lat.perAction.get(action);
+    let est = seed;
+    if (pa && pa.n >= 2) est = pa.value;
+    else if (lat.all && lat.all.n >= 2) est = lat.all.value;
+    const rtt = lat.rtt > 0 ? lat.rtt : 0;
+    let budget = est * 2.5 + rtt * 2 + 1500;
+    const cold = Date.now() - link.connectedAt < 20_000 || !lat.all || lat.all.n < 1;
+    if (cold) budget = Math.max(budget, seed * 1.5);
+    const floor = Math.max(2500, seed * 0.5);
+    const ceil = Math.min(120_000, Math.max(seed * 8, floor));
+    return Math.round(Math.min(Math.max(budget, floor), ceil));
+  }
+
   const log = (message) => { try { onLog?.(message); } catch { /* 日志失败不影响搬运 */ } };
 
   const wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, maxPayload: MAX_PAYLOAD });
@@ -108,6 +151,7 @@ function createPhoneService({ authorized, onLog } = {}) {
       });
     }
     link.pending.clear();
+    try { clearInterval(link.heartbeat); } catch { /* 已经清过了 */ }
     try { link.socket.close(); } catch { /* 已经断了 */ }
   }
 
@@ -122,6 +166,8 @@ function createPhoneService({ authorized, onLog } = {}) {
       capabilities: hello && Array.isArray(hello.capabilities) ? hello.capabilities.filter((c) => typeof c === 'string') : [],
       connectedAt: Date.now(),
       alive: true,
+      missed: 0,
+      latency: { perAction: new Map(), all: null, rtt: 0 },
       pending: new Map(),
     };
     devices.set(deviceId, link);
@@ -137,6 +183,12 @@ function createPhoneService({ authorized, onLog } = {}) {
       if (!frame || typeof frame !== 'object') return;
       if (frame.t === 'pong') {
         link.alive = true;
+        if (Number.isFinite(link.pingAt) && link.pingAt > 0) {
+          const sample = Date.now() - link.pingAt;
+          const prev = link.latency.rtt;
+          link.latency.rtt = prev > 0 ? prev * (1 - RTT_ALPHA) + sample * RTT_ALPHA : sample;
+          link.pingAt = 0;
+        }
         return;
       }
       if (frame.t === 'hello') {
@@ -151,8 +203,12 @@ function createPhoneService({ authorized, onLog } = {}) {
         const pending = link.pending.get(text(frame.id));
         if (!pending) return;
         link.pending.delete(text(frame.id));
-        if (frame.ok) pending.settleOk(frame.data === undefined ? null : frame.data);
-        else {
+        if (frame.ok) {
+          if (pending.action && Number.isFinite(pending.sentAt)) {
+            recordLatency(link, pending.action, Date.now() - pending.sentAt);
+          }
+          pending.settleOk(frame.data === undefined ? null : frame.data);
+        } else {
           const error = frame.error && typeof frame.error === 'object' ? frame.error : {};
           pending.settleErr({
             code: text(error.code) || 'failed',
@@ -179,12 +235,19 @@ function createPhoneService({ authorized, onLog } = {}) {
     link.heartbeat = setInterval(() => {
       if (!statusOf(socket)) return;
       if (!link.alive) {
-        log(`phone ${deviceId}: 心跳丢了，按断线处理`);
-        drop(deviceId, 'offline');
-        return;
+        link.missed += 1;
+        if (link.missed >= MAX_MISSED_HEARTBEATS) {
+          log(`phone ${deviceId}: 连续 ${link.missed} 次心跳没回应，按断线处理`);
+          drop(deviceId, 'offline');
+          return;
+        }
+        log(`phone ${deviceId}: 心跳丢了（${link.missed}/${MAX_MISSED_HEARTBEATS}），再等等`);
+      } else {
+        link.missed = 0;
       }
       link.alive = false;
-      try { socket.send(JSON.stringify({ t: 'ping', at: Date.now() })); } catch { /* 下面 close 会来 */ }
+      link.pingAt = Date.now();
+      try { socket.send(JSON.stringify({ t: 'ping', at: link.pingAt })); } catch { /* 下面 close 会来 */ }
     }, HEARTBEAT_MS);
     link.heartbeat.unref?.();
 
@@ -210,7 +273,7 @@ function createPhoneService({ authorized, onLog } = {}) {
     if (!ACTIONS.has(action)) return Promise.reject({ code: 'unknown-action', message: `不支持的动作 ${action}` });
 
     const opId = nextId();
-    const budget = Number.isFinite(timeoutMs) ? timeoutMs : (ACTIONS.get(action) || DEFAULT_OP_TIMEOUT_MS);
+    const budget = Number.isFinite(timeoutMs) ? timeoutMs : budgetFor(link, action);
     return new Promise((resolve, reject) => {
       let settled = false;
       const settle = (fn, value) => {
@@ -222,6 +285,8 @@ function createPhoneService({ authorized, onLog } = {}) {
         fn(value);
       };
       const pending = {
+        action,
+        sentAt: Date.now(),
         settleOk: (data) => settle(resolve, { ok: true, data }),
         settleErr: (error) => settle(reject, error),
       };
@@ -240,7 +305,7 @@ function createPhoneService({ authorized, onLog } = {}) {
       }
       link.pending.set(opId, pending);
       try {
-        link.socket.send(JSON.stringify({ t: 'op', id: opId, sessionId: text(sessionId), action, args: args || {} }));
+        link.socket.send(JSON.stringify({ t: 'op', id: opId, sessionId: text(sessionId), action, args: args || {}, timeout: budget }));
       } catch {
         settle(reject, { code: 'offline', message: '发不出去，那台手机断开了' });
       }

package/lib/mobile/phone/tools.js

@@ -63,6 +63,8 @@ async function run(service, deviceId, sessionId, action, args, signal) {
     if (code === 'offline') throw new Error('那台手机在这期间断开了连接，这一步没有做。');
     if (code === 'timeout') throw new Error(`那台手机 ${message}。可以再试一次，或者先 phone_screen 看看它现在停在哪。`);
     if (code === 'unsupported') throw new Error(`那台手机上装的 App 版本还不支持 ${action}，需要把手机上的 App 升级到最新。`);
+    if (code === 'adb-unavailable') throw new Error('那台手机的无线调试没连上（可能被系统关了），让用户在手机上重新打开无线调试。');
+    if (code === 'warming') throw new Error('手机正在准备后台屏，大约还要几秒，稍等再试。');
     if (code === 'aborted') throw new Error('这一步被取消了。');
     throw new Error(message);
   }
@@ -246,7 +248,7 @@ function installPhoneTools(ctx, deps) {
       try {
         ref = await store.saveImage({
           data: Buffer.from(blob, 'base64'),
-          mediaType: 'image/png',
+          mediaType: data && data.format === 'jpeg' ? 'image/jpeg' : 'image/png',
           name: textOf(args.target, MAX_TEXT) || 'phone-screen',
         });
       } catch (error) {

package/lib/mobile/promo-receiver.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * 商店素材接收端（本机那个 Mac-to-eagle 桌面程序）的坐标。
+ *
+ * 为什么由插件来报：用户在手机 App 里不该填任何东西（2026-11-07 明确要求）。而「这台电脑的
+ * 局域网地址 + 桌面程序的配对密钥」只有插件这一侧知道 —— 它本来就跑在这台电脑上，局域网候选
+ * 地址（`lan-network`）和桌面程序写下的密钥文件都在本机，读一下就能把两样一起交给手机。
+ *
+ * 桌面程序不在跑 / 没装 / 还没生成密钥，就回 null：App 那边据此什么也不做（原图照旧留相册），
+ * 不会因为「这台电脑上没有它」而报错。
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/** 桌面程序的默认端口（见 Mac-to-eagle `LocalAPIServer.preferredPort`）。 */
+const DESKTOP_PORT = 47291;
+
+/** 密钥文件：桌面程序用 owner-only 权限写在应用数据目录里。 */
+function accessKeyFile() {
+  // 与 Mac-to-eagle `AppPaths.appSupport` 同一套规则：环境变量优先，其次用户应用数据目录。
+  const override = process.env.MACTOEAGLE_DATA_DIR;
+  const base = override && override.startsWith('/')
+    ? override
+    : path.join(os.homedir(), 'Library', 'Application Support', 'MacToEagle');
+  return path.join(base, 'mobile-access-key');
+}
+
+/** 读配对密钥；读不到就 null（不是错误，只说明这台电脑上没有那个程序）。 */
+function readAccessKey() {
+  try {
+    const value = fs.readFileSync(accessKeyFile(), 'utf8').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 这台电脑上、手机能拨到的那个局域网地址。
+ *
+ * 直接用 `lan-network` 那套候选（它已经滤掉了 VPN / 虚拟网卡、把私网排在前面），取第一条的
+ * 主机部分 —— 素材回传只需要一个能连通的地址，不需要像会话通道那样挨个试。
+ */
+function pickLanHost(lanCandidates) {
+  const first = Array.isArray(lanCandidates) ? lanCandidates.find((item) => item && item.url) : null;
+  if (!first) return null;
+  try {
+    return new URL(first.url).hostname;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 组装给 App 的那一格。
+ *
+ * @param {{ lanCandidates?: Array<{url?: string}> }} options 与 `/connection-info` 同一份候选
+ * @returns {{ url: string, key: string } | null}
+ */
+function promoReceiver({ lanCandidates } = {}) {
+  const key = readAccessKey();
+  if (!key) return null;
+  const host = pickLanHost(lanCandidates);
+  if (!host) return null;
+  return { url: `http://${host}:${DESKTOP_PORT}`, key };
+}
+
+module.exports = {
+  DESKTOP_PORT,
+  accessKeyFile,
+  readAccessKey,
+  pickLanHost,
+  promoReceiver,
+};