dsh-mobile-plugin 0.5.23 → 0.5.26

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,8 @@ 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 { mountP2P } = require('./p2p/wiring.cjs') // 点对点隧道：只有助手会话（连接从隧道里进来，不必开回环门）
 const { createPreviewService } = require('./relay/preview.js')
 const { mountTerminal, mountCli } = require('./mobile/services.js')
 // 手机打开「电脑上的网页版」时用的那枚一次性登录令牌（见 mobile/host-web.js）。
@@ -304,7 +305,9 @@ 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 })
+  // 点对点隧道：两端打洞直连、数据不经过任何服务器。挂不上就只是没这条通道。
+  const p2p = mountP2P({ mount, warn, state, saveState: core.saveState, localPort: lanPortInUse, ctx, name })
   // 每次同步前都跑一次探测，而不是只在启动时探一次：`/api/relay/config` 改了
   // lanPort 之后同样要走这条路（否则新端口被占时又会退回死地址）。并发调用复用
   // 在飞的那次——探测要占一个监听句柄，重复触发没有意义。
@@ -392,6 +395,8 @@ function apply(ctx) {
     getMirrorPush: mirror.getMirrorPush,
     // 直连隧道那一格：手机轮询 `/status` 时据此自己把通道加进来。
     getTailcat: () => (tailcat ? tailcat.status() : null),
+    // 点对点隧道那一格：手机轮询 `/status` 时据此把这条通道也算进来。
+    getP2P: () => (p2p ? p2p.status() : null),
   })
   function applyServices() {
     void syncSidecar().catch(() => undefined)
@@ -438,6 +443,8 @@ function apply(ctx) {
     pairingPayload,
     // 直连隧道：二维码要多带一段「去这个一次性节点换正式地址」，状态接口要多一行。
     tailcat,
+    // 点对点隧道：二维码要多带一段「电脑的公钥与打洞候选」，配对后两端各持一半。
+    p2p,
     restartSidecar,
     // 「手机上最近来过没有」——控制面状态里补给面板用（见 ./mobile/activity.cjs）。
     mobileActivity: activity.snapshot,
@@ -507,6 +514,8 @@ function apply(ctx) {
     registerRoute,
     // 直连隧道：已配对的手机走这条拿到自己的入口地址，不用重新扫码。
     tailcat,
+    // 点对点隧道：会合那一步（手机报上候选、这里把它拉起来并回自己的候选）。
+    p2p,
     // 预览是 WebSocket 升级路由，走的是 webServer 的另一套名字空间；与 registerRoute
     // 一样必须包在 ctx.effect 里，否则插件重载时重复注册会直接抛错。
     registerUpgradeRoute: (route) => mountRoute(route, true),

package/lib/mobile/cli/acp.js

@@ -7,8 +7,9 @@
  * 那正是这次不做「逐家适配」的关键 —— 四家 CLI 的差别全被适配器吃掉了，这里只认一种协议。
  *
  * 为什么用动态 `import()`：插件这一层是 CJS（`lib/mobile/package.json`），而 SDK 是纯 ESM。
- * 稳定入口**零运行时依赖**（zod 只是可选 peer，稳定入口没 import 它），所以这个 import 不
- * 会拖出额外的东西。
+ * 稳定入口的运行时要 zod（`dist/v1/schema/zod.gen.js` 里 `import * as z from "zod/v4"`），
+ * 所以 zod 是我们的**直接依赖**，不是可选 peer —— 靠宿主或 profile 里碰巧有一份，
+ * 装到关了自动补 peer 的环境里就是「zod 落在安装闭包之外」。
  *
  * `session/update` 一律走 `onNotification` 自己接，**不用** SDK 的 `ActiveSession`：后者会把
  * 每条更新再排进一个内部队列供 `nextUpdate()` 取，我们从不取，等于给每个会话攒一个只涨不

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/confirm.js

@@ -0,0 +1,189 @@
+'use strict';
+
+/**
+ * 付款确认：把「这一下点下去要花钱」送去宿主已有的审批通道，等人点了「同意」再放行。
+ *
+ * ## 为什么复用审批通道，而不是自己推一张卡
+ *
+ * 手机上那张确认卡、用户点按钮、结论交回来，这条链在 0.2.x 上已经由审批桥
+ * （`mobile/approvals.js`）铺好了：它 `prepend` 了宿主的 `approval/request` 钩子，钩子一响
+ * 就把卡推给正在看这条会话的手机，用户点了同意再 `settle` 回钩子的 promise。我们自己再造
+ * 一条推卡的路，等于让手机上同时存在两套确认卡、两套回答接口，谁先答都说不清。
+ *
+ * 所以这里只做一件事：以 `ctx.get('approval')` 的身份发起一次真正的审批请求。宿主的
+ * `ApprovalService.request()` 会把这次的 `approval/asked` / `approval/decided` 记进会话日志
+ * （审计里就是这么写的），再走一遍 `approval/request` waterfall —— 审批桥在那一步把卡交给
+ * 手机。拿回 `allowed-once` 才等于「用户就这一下点了同意」。
+ *
+ * ## 为什么绝对不会挂死
+ *
+ * 三处都可能「永远没人答」：手机没在看（卡没有去处）、用户在别处把这一轮取消了、钩子上
+ * 下游是个不回答的转发器。前两处各自有出路（下面判 unavailable / 跟着 signal 取消），
+ * 第三处靠一道自己的硬期限兜底：到点就回 `unavailable`，且先 `abort()` 让宿主那头把
+ * 挂起的审批一起收掉。工具调用挂在这里，模型的整轮就会一直转下去 —— 那比「没确认」
+ * 严重得多，所以宁可超时也不要等。
+ *
+ * ## 三个返回值
+ *
+ * `allowed-once`（就这一次可以） / `rejected`（问过了，答案是拒绝或取消） /
+ * `unavailable`（压根没能问到人）。调用点只认 `allowed-once`，别的一律不执行。
+ */
+
+/**
+ * 一次确认最多等多久。
+ *
+ * 够用户拿起手机看一眼再点同意，又不至于让模型的这一发停在那里。之所以不设「等到有人答
+ * 为止」：卡没推到人手上（手机没在看这条会话、用户把 App 切走了）时，等的是一个永远不来
+ * 的答案；而一次工具调用挂着一分钟以上，在模型那边就是「卡住了」。
+ */
+const APPROVAL_TIMEOUT_MS = 90_000;
+
+/**
+ * 这一步要不要人确认。判定仍由 `irreversible.js` 给，这里只挑出付款 / 下单那一类 ——
+ * 发送、提交、删除虽然也收不回来，但它们是这条任务本来就该做的事，每一步都拦会让
+ * 「让它发条消息」变成一连串确认框。
+ */
+function needsConfirmation(judged) {
+  return Boolean(judged && judged.irreversible === true && judged.kind === 'payment');
+}
+
+/**
+ * 宿主的审批服务。`ctx.get()` 而不是写进 inject：这个服务的装配顺序跟手机那几条路由无关，
+ * 注入一个当前宿主版本里没有的服务会把整个插件装载拖垮（与 `mobile/host-web.js` 同一口径）。
+ */
+function approvalOf(ctx) {
+  if (!ctx) return null;
+  try {
+    if (typeof ctx.get === 'function') {
+      const service = ctx.get('approval');
+      if (service && typeof service.request === 'function') return service;
+    }
+  } catch { /* 服务没装就往下试属性那一种写法 */ }
+  const direct = ctx.approval;
+  return direct && typeof direct.request === 'function' ? direct : null;
+}
+
+/**
+ * 这条会话的 agent。审批请求要求请求方带着自己的会话（`ApprovalService.request()` 要往
+ * 那条会话里记审计事件，还要看它的 `approval/policy`），拿不到就等于没人能答。
+ *
+ * 工具层手上一般已经握着这次调用的 agent，优先用它 —— 比按 id 去服务里捞更准，
+ * 子代理那条路径上 `agents.get(childSessionId)` 本来就取不到。
+ */
+function agentOf(ctx, sessionId, hint) {
+  if (hint && hint.session) return hint;
+  if (!ctx || typeof ctx.get !== 'function' || !sessionId) return null;
+  try {
+    const agents = ctx.get('agents');
+    if (agents && typeof agents.get === 'function') return agents.get(sessionId) || null;
+  } catch { /* 没这个服务就没有别的路可走 */ }
+  return null;
+}
+
+/** 卡片上那句话：做了什么都写进去，用户看着手机就能判断这一下该不该点。 */
+function summaryText(summary, amountText) {
+  const parts = [];
+  const head = typeof summary === 'string' ? summary.trim().slice(0, 200) : '';
+  const amount = typeof amountText === 'string' ? amountText.trim().slice(0, 60) : '';
+  if (head) parts.push(head);
+  if (amount) parts.push(`金额 ${amount}`);
+  return parts.join('；') || '操作手机：这一步涉及付款 / 下单，需要你确认';
+}
+
+/** 宿主那套结论词表收成一个三选一。取消与拒绝对调用点是一回事：都别执行。 */
+function normalizeOutcome(outcome) {
+  if (outcome === 'allowed-once') return 'allowed-once';
+  if (outcome === 'rejected' || outcome === 'cancelled') return 'rejected';
+  return 'unavailable';
+}
+
+/**
+ * 发起一次确认并等结论。
+ *
+ * @param {object} ctx 插件上下文（要能 `get('approval')`）
+ * @param {object} options
+ * @param {string} options.sessionId 这条对话
+ * @param {string} [options.summary] 卡片摘要：这一步在做什么
+ * @param {string} [options.amountText] 金额一类的字样，有就一起上卡
+ * @param {object} [options.agent] 工具层手上这次调用的 agent（有就用，没有按会话捞）
+ * @param {string} [options.toolName] 卡片上那个「工具 X」的名字
+ * @param {string} [options.callId] 与这一步的工具调用对上，便于手机与桌面对同一张卡
+ * @param {AbortSignal} [options.signal] 这一轮工具的取消信号（用户取消整轮时跟着结束）
+ * @param {boolean} [options.watching] 有没有手机在看着这条会话；明确为 false 就不必问了
+ * @param {number} [options.timeoutMs] 覆盖默认期限：调用方自己的预算比三分钟还短时用它，
+ *   确认不该比整条调用活得久
+ * @returns {Promise<'allowed-once'|'rejected'|'unavailable'>}
+ */
+async function requestConfirmation(ctx, options) {
+  const opts = options && typeof options === 'object' ? options : {};
+  const sessionId = typeof opts.sessionId === 'string' ? opts.sessionId.trim() : '';
+  // 认不出是哪条对话：卡片没有归属，宿主也会因为「没有开着的轮次」拒绝记账。
+  if (!sessionId) return 'unavailable';
+  // 没有手机在看：卡推不出去，问也白问。如实说「没问到」，别把这一步挂在那儿。
+  if (opts.watching === false) return 'unavailable';
+
+  const approval = approvalOf(ctx);
+  if (!approval) return 'unavailable';
+  const agent = agentOf(ctx, sessionId, opts.agent);
+  if (!agent || !agent.session) return 'unavailable';
+
+  const reason = summaryText(opts.summary, opts.amountText);
+  const controller = new AbortController();
+  const parent = opts.signal;
+  const onAbort = () => controller.abort();
+  if (parent && typeof parent.addEventListener === 'function') {
+    // 工具已经被取消了就别再发一张卡出来：那一轮已经没有人在等这个答案。
+    if (parent.aborted) return 'unavailable';
+    parent.addEventListener('abort', onAbort, { once: true });
+  }
+
+  const waitMs = Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+    ? Math.min(APPROVAL_TIMEOUT_MS, Math.round(opts.timeoutMs))
+    : APPROVAL_TIMEOUT_MS;
+  let timer = null;
+  // 硬期限与请求本身赛跑：即便宿主那头不理会 abort，这里也一定在期限内交出结论。
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve('unavailable');
+    }, waitMs);
+    if (typeof timer.unref === 'function') timer.unref();
+  });
+
+  try {
+    const asked = Promise.resolve()
+      .then(() => approval.request({
+        agent,
+        ...(typeof opts.toolName === 'string' && opts.toolName ? { toolName: opts.toolName } : {}),
+        ...(typeof opts.callId === 'string' && opts.callId ? { callId: opts.callId } : {}),
+        reason,
+        // 桌面与手机上的卡片都优先用这句（审批桥的 `displayReasonOf` 认 zh）。
+        displayReason: { zh: reason },
+        signal: controller.signal,
+      }))
+      // 宿主在「没有开着的轮次」「策略是 never」这些情况下会抛，一律折算成没问到。
+      .then((outcome) => normalizeOutcome(outcome), () => 'unavailable');
+    return await Promise.race([asked, deadline]);
+  } catch {
+    return 'unavailable';
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (parent && typeof parent.removeEventListener === 'function') parent.removeEventListener('abort', onAbort);
+  }
+}
+
+/** 确认没拿到时给模型的那句话。两种没拿到的原因要分开说，模型据此决定要不要请用户回来。 */
+function blockedMessage(outcome, what) {
+  const step = typeof what === 'string' && what ? what : '这一步';
+  if (outcome === 'rejected') {
+    return `${step}是付款 / 下单，需要用户确认；用户没有同意（或者这一轮被取消了），所以没有执行。把这件事如实告诉用户，别自己重试。`;
+  }
+  return `${step}是付款 / 下单，需要用户确认，但刚才没能把确认卡送到用户手上（手机没有在看这条对话，或者确认通道不可用），所以没有执行。请用户回到这条对话、在手机上看着屏幕再试一次；也可以让用户自己点这一下。`;
+}
+
+module.exports = {
+  needsConfirmation,
+  requestConfirmation,
+  blockedMessage,
+  APPROVAL_TIMEOUT_MS,
+};

package/lib/mobile/phone/index.js

@@ -15,8 +15,12 @@
 
 const { createPhoneService } = require('./service.js');
 const { installPhoneTools } = require('./tools.js');
+const { installRouteHint } = require('./route-hint.js');
 const { listDevices, describeDevice } = require('./routes.js');
 const binding = require('./binding.js');
+const pacing = require('./pacing.js');
+const irreversible = require('./irreversible.js');
+const routesMemory = require('./routes-memory.js');
 
 /**
  * @param {object} ctx 插件上下文
@@ -52,12 +56,28 @@ function mountPhoneControl(ctx, deps) {
     if (!message.includes('without inject')) throw error;
   }
 
+  // 只读的历史路线查询工具：单独一路注册，不经过 tools.js 那套步数/死循环守卫（它不发动作）。
+  // 同一口径：缺 tools 注入的 profile 只少这一条，不要把整块装配掀掉。
+  try {
+    installRouteHint(ctx);
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    if (!message.includes('without inject')) throw error;
+  }
+
   ctx.effect(() => () => service.close(), `${deps.name || 'dsh-mobile-plugin'}: phone control`);
   // 路由表那边要凭据库与实例号来报设备名，而它只拿得到这个服务（装配层只转交一个对象）。
   // 挂在服务上而不是再走一遍依赖注入：多一处注入就多一处能不同步的地方。
   service.credentials = deps.credentials;
   service.instanceId = deps.instanceId;
+  // 节奏与不可逆判定是纯函数模块，挂到服务上，工具层拿同一个服务就能顺手取到，
+  // 省得再开一路依赖注入 —— 少一处注入就少一处能不同步的地方。
+  service.pacing = pacing;
+  service.irreversible = irreversible;
+  // 成功路线记忆：工具层在结局判定为成功后调 `service.routesMemory.record(...)`，查询走
+  // `phone_route_hint`。挂到服务上，与 pacing / irreversible 同一口径，少一路依赖注入。
+  service.routesMemory = routesMemory;
   return service;
 }
 
-module.exports = { mountPhoneControl, binding };
+module.exports = { mountPhoneControl, binding, pacing, irreversible, routesMemory };