dsh-mobile-plugin 0.5.21 → 0.5.23

package/README.md

@@ -1,8 +1,6 @@
 <h3 align="center">AI-HUB 移动端插件</h3>
 
-<p align="center">
-  <img src="assets/banner.jpg" alt="AI-HUB：手机和平板上的 DSH 会话界面" width="760">
-</p>
+![AI-HUB：手机和平板上的 DSH 会话界面](https://raw.githubusercontent.com/WNLUO/dsh-mobile-plugin/main/assets/banner.jpg)
 
 <p align="center">
   <a href="https://app.wnluo.com/public/apps/14"><img alt="安卓 分发下载" src="https://img.shields.io/badge/%E5%AE%89%E5%8D%93-%E5%88%86%E5%8F%91%E4%B8%8B%E8%BD%BD-3DDC84?style=for-the-badge&logo=android&logoColor=white"></a>
@@ -22,12 +20,7 @@
 
 **AI-HUB 的手机端插件。** 装在电脑这边，手机 App 就通过一条中转隧道或局域网配对连进你的 DSH —— 看会话、接着聊、管理文件和工作区，进度实时同步。它也可以脱离桌面外壳单独跑在服务器上，当作无头宿主用。
 
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/WNLUO/dsh-mobile-plugin/main/assets/connection-dark.svg">
-    <img src="https://raw.githubusercontent.com/WNLUO/dsh-mobile-plugin/main/assets/connection-light.svg" alt="手机 App 经中转或局域网连到你电脑上的 DSH" width="720">
-  </picture>
-</p>
+![手机 App 经中转或局域网连到你电脑上的 DSH](https://raw.githubusercontent.com/WNLUO/dsh-mobile-plugin/main/assets/connection-light.svg)
 
 手机连的是**你自己那台电脑上的 DSH**，不是某个云端服务。电脑不用公网 IP，也不用在路由器上开端口：插件从内网主动往外建一条隧道，手机沿这条路回来。
 
@@ -131,9 +124,7 @@ DSH 跑在电脑上，但我不是一直坐在电脑前。出门、在别的房
 
 ## 交流与反馈
 
-<p align="center">
-  <img src="assets/wechat-group.png" alt="企业微信群二维码" width="180">
-</p>
+![企业微信群二维码](https://raw.githubusercontent.com/WNLUO/dsh-mobile-plugin/main/assets/wechat-group.png)
 
 扫上面的码进企业微信群。不方便的话发邮件到 <admin@wnluo.com> 或 <wnluo2@gmail.com>。用着顺手就给仓库点个 star，这是最实在的支持。
 

package/assets/pets/README.md

@@ -0,0 +1,9 @@
+# 内置宠物包
+
+这个目录放**随插件发版走**的默认宠物（见 [`docs/pet-overlay.md`](../../../docs/pet-overlay.md) §1）。
+
+- 每个包一个子目录，目录名就是包 id（`[a-z0-9][a-z0-9-]{0,63}`），里面一份 `pack.json`
+  加它引用的 `.gif` / `.png`。
+- 这里的包**只读**：手机上删不掉，用户想要自己的一份，就用同一个 id 在
+  `$DSH_HOME/storages/mobile-plugin/pets/<id>/` 写一份 —— 用户那份会盖住这里的。
+- 目录可以不存在、也可以是空的：宿主那边「少几个包」而已，不会报错，用户自己的包照常列。

package/assets/pets/deepy-whale/pack.json

@@ -0,0 +1,54 @@
+{
+  "schema": 1,
+  "id": "deepy-whale",
+  "name": "Deepy 小鲸鱼",
+  "author": "DSH Mobile",
+  "license": "随本项目发布，可自由修改",
+  "canvas": {
+    "w": 52,
+    "h": 52
+  },
+  "anchor": {
+    "x": 28,
+    "baseline": 48
+  },
+  "states": {
+    "idle": {
+      "file": "idle.gif"
+    },
+    "working": {
+      "file": "working.gif"
+    },
+    "attention": {
+      "file": "attention.gif"
+    },
+    "done": {
+      "file": "done.gif"
+    },
+    "error": {
+      "file": "error.gif"
+    },
+    "sleeping": {
+      "file": "sleeping.gif"
+    }
+  },
+  "tiers": {
+    "working": [
+      {
+        "min": 3,
+        "file": "working-3.gif"
+      },
+      {
+        "min": 1,
+        "file": "working.gif"
+      }
+    ]
+  },
+  "loop": [
+    "idle",
+    "working",
+    "attention",
+    "sleeping"
+  ],
+  "sleepAfterMs": 60000
+}

package/extensions/README.md

@@ -0,0 +1,64 @@
+# 已审核的第三方扩展
+
+这个目录随 `dsh-mobile-plugin` 的 npm 包一起发布。手机上「随插件发布」那一档扩展从这里读：
+宿主只认 `catalog.json` 里登记的 slug，目录里有但没登记的一律不下发。
+
+## 提交流程
+
+1. 在 `extensions/<slug>/` 放扩展包：`manifest.json` 与 `index.html` 等，形状与 App 侧现有
+   扩展包一致（自包含、相对路径引用，不许外链）。目录名就是 slug，只认字母、数字、点、
+   下划线、横线，最长 64 个字符。**入口页固定叫 `index.html`**：手机打开扩展找的就是包目录
+   下这一层，`manifest.json` 里写 `main` 指到别的文件不生效。缺 `index.html` 的包宿主列清单
+   时会直接跳过，别等装到手机上才发现打不开。
+2. 在 `extensions/catalog.json` 的 `packages` 里加一条，填 `slug`（必须与目录名一致）与
+   `description` / `author` / `releaseNotes`。
+3. 提 PR 前在本地跑一遍自验：
+
+   ```sh
+   cd dsh-mobile-plugin
+   node --test test/extension-catalog.test.cjs   # 宿主列包、入口页、取文件的判据
+   npm pack --dry-run                            # 看扩展目录是否真进了 npm 包
+   ```
+
+   想按发版那套全量口径验（含「登记的扩展都带入口页」），跑 `node scripts/preflight-release.mjs`；
+   空清单时这几条都是绿的，第一个包进来才真正验得到。
+4. 提 PR，一次只放一个包。合并即随下一次插件发版上架；从 `packages` 里删掉那一条即下架。
+
+这个目录是随包发布的只读内容，宿主不会创建它，也不会写它。
+
+## 审核口径
+
+登记即视为已审核，所以审的是包本身，不是清单里的那几行字：
+
+- 入口页第一屏能不能打开，页面有没有模仿系统界面骗用户填东西；
+- 包里会不会往外发请求。页面从 `file://` 加载，CSP 挡外链，资源必须都在包里；
+- `manifest.json` 声明的能力与实际行为对不对得上；
+- 右栏入口的图标与名字像不像 App 自带的功能（叫「设置」「账户」这类直接打回）；
+- 体积：整包不超过 20 MB、不超过 200 个文件，单文件不超过 8 MB。缺 `manifest.json`、
+  缺 `index.html`、或体积超了，宿主都会静默跳过，包根本不会出现在手机上。
+
+## 字段含义
+
+`catalog.json` 的形状是 `{"packages": [{"slug": "...", "description": "...", "author": "...", "releaseNotes": "..."}]}`。
+
+- `slug`（必填）：包目录名，也是手机侧的身份。重复只认第一条，不合规的连读都不读。
+- `description` / `author` / `releaseNotes`（可选）：只收非空字符串，缺了或不是字符串一律
+  回 `null`。`author` 写显示名加一个能联系上的方式，下架时找得到人。
+- **不要在这里写 `name`、`version`、`size`、`sha256`、`files`、`capabilities`**：文件清单与哈希
+  由宿主扫目录现算，名字、版本、能力从包自己的 `manifest.json` 读，填了也不认。
+
+宿主下发给手机的一条 Package 还带这些从包里读出来的字段：`name`、`versionName`、
+`apiVersion`、`capabilities`（从 `manifest.json` 收窄成字符串数组）、`size`、`fileCount`、
+`files`（每项 `path` / `size` / `sha256`）。
+
+## 取文件
+
+`GET /api/mobile/v1/extension/catalog/file?slug=&path=` 按清单里的文件逐个字节下发
+（base64 + sha256）。`path` 只能是包目录内的相对路径，绝对路径、`..`、resolve 之后越出包目录
+的一律拒绝。没登记进 `catalog.json` 的 slug 取不到任何文件。
+
+## 与本地开发包的区别
+
+作者边写边看用 `$DSH_HOME/extension-dev`（作者电脑上的目录，走 `/extension/dev/*`），那条路
+绕过审核，只能手动导入、界面标「本地」。这里是随插件 npm 包发布的正式来源，要上架就得走
+上面的 PR 与审核。

package/extensions/catalog.json

@@ -0,0 +1 @@
+{"packages": []}

package/lib/impl.js

@@ -30,8 +30,9 @@ const { createMirrorPusher } = require('./mirror/pusher.cjs')
 const { randomBytes } = require('node:crypto')
 const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates, withManualIpv6Candidate } = require('./relay/lan-network.cjs')
 // 配对二维码的载荷：面板与终端命令共用一份，拼装在 `./relay/pairing-payload.cjs`。
-const { pairingPayload } = require('./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 { createPreviewService } = require('./relay/preview.js')
 const { mountTerminal, mountCli } = require('./mobile/services.js')
 // 手机打开「电脑上的网页版」时用的那枚一次性登录令牌（见 mobile/host-web.js）。
@@ -53,6 +54,9 @@ const statsScheduler = require('./mobile/stats-scheduler.cjs')
 // 扩展卡的宿主侧：`extension_present` 工具与卡状态账本（见 mobile/extensions.js）。
 const { installExtensions } = require('./mobile/extensions.js')
 const { mountPhoneControl } = require('./mobile/phone/index.js') // 「让 AI 操作手机」，见 mobile/phone/
+// 公众号文章库：给 AI 的两个工具（写 / 读），见 mobile/wechat-tools.js。
+const { installWechatTools } = require('./mobile/wechat-tools.js')
+const { installPetTools } = require('./mobile/pet-tools.js') // 悬浮宠物的两个工具（看 / 写），见 mobile/pet-tools.js。
 const { activeGuard } = require('./host-guard.cjs')
 // 桌面端侧栏展开态的快照存储。桌面把这份状态只记在浏览器 localStorage 里，宿主必须
 // 有一个落盘处：客户端半边（lib/client.js）上报 → 这里 → 移动端读取。
@@ -299,6 +303,8 @@ function apply(ctx) {
   let lanPortProbe = null
   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 })
   // 每次同步前都跑一次探测，而不是只在启动时探一次：`/api/relay/config` 改了
   // lanPort 之后同样要走这条路（否则新端口被占时又会退回死地址）。并发调用复用
   // 在飞的那次——探测要占一个监听句柄，重复触发没有意义。
@@ -362,6 +368,14 @@ function apply(ctx) {
     }
     return undefined
   }, `${name}: extension tool`)
+  ctx.effect(() => {
+    // 缺 tools 注入的 profile 只少这两个工具；文章库本身与它的路由照常可用。
+    try { installWechatTools(ctx) } catch (error) {
+      if (!String(error).includes('without inject')) throw error
+    }
+    return undefined
+  }, `${name}: wechat article tools`)
+  mount('宠物工具', () => installPetTools(ctx)) // 缺 tools 注入的 profile 只少这两个，包目录与路由照常可用。
   mount('统计采集', () => ctx.effect(() => statsScheduler.start(ctx), `${name}: stats collect`))
   mount('过程播报', () => ctx.effect(() => installNarration(ctx), `${name}: process narration`))
 
@@ -376,6 +390,8 @@ function apply(ctx) {
     getSidecarRestartedAt: sidecarLifecycle.getRestartedAt,
     getSidecarRestartError: sidecarLifecycle.getRestartError,
     getMirrorPush: mirror.getMirrorPush,
+    // 直连隧道那一格：手机轮询 `/status` 时据此自己把通道加进来。
+    getTailcat: () => (tailcat ? tailcat.status() : null),
   })
   function applyServices() {
     void syncSidecar().catch(() => undefined)
@@ -420,6 +436,8 @@ function apply(ctx) {
     lanPortInUse: advertisedLanPort, // 二维码里的端口也必须是实绑值
     getLanPortAdjusted: () => lanPortAdjusted,
     pairingPayload,
+    // 直连隧道：二维码要多带一段「去这个一次性节点换正式地址」，状态接口要多一行。
+    tailcat,
     restartSidecar,
     // 「手机上最近来过没有」——控制面状态里补给面板用（见 ./mobile/activity.cjs）。
     mobileActivity: activity.snapshot,
@@ -487,6 +505,8 @@ function apply(ctx) {
   // 核对的「路径 → handler」表，不用在 1000 行装配代码里翻。
   mount('移动端路由', () => registerMobileRoutes({
     registerRoute,
+    // 直连隧道：已配对的手机走这条拿到自己的入口地址，不用重新扫码。
+    tailcat,
     // 预览是 WebSocket 升级路由，走的是 webServer 的另一套名字空间；与 registerRoute
     // 一样必须包在 ctx.effect 里，否则插件重载时重复注册会直接抛错。
     registerUpgradeRoute: (route) => mountRoute(route, true),

package/lib/mobile/approvals.js

@@ -18,6 +18,7 @@
 
 const { randomUUID } = require('node:crypto');
 const { sendJson, readJsonBody } = require('../shared/http-util');
+const { cancelForwardedRequests } = require('./host-bridge/transport.js');
 
 /** `/approval/respond` 只认这两种结论（与 App 的两个按钮一一对应）。 */
 const ANSWER_OUTCOMES = new Set(['allowed-once', 'rejected']);
@@ -234,6 +235,8 @@ function noteDecided(sessionId, data) {
  */
 function bindRequest(entry, request) {
   entry.bound = true;
+  // 留一个身份引用：手机答完之后要按它找回宿主转发给桌面窗口的那一发（见 cancelForwardedCards）。
+  entry.requestRef = request;
   entry.toolName = entry.toolName || (typeof request.toolName === 'string' ? request.toolName : undefined);
   entry.callId = entry.callId || (typeof request.callId === 'string' ? request.callId : undefined);
   const nicer = displayReasonOf(request) || (typeof request.reason === 'string' ? request.reason : undefined);
@@ -261,8 +264,10 @@ function bindRequest(entry, request) {
  * 输的那张卡由结算帧收掉；两边都没人答就一直挂着。
  *
  * 不传 `next`（手机正在看这个会话）就是手机独家作答：不往下游转发，桌面从源头就不弹卡。
- * 桌面那张卡挂在被转发的请求上，本桥没有替它收尾的口子，转发出去手机先答，它只会永远
- * 悬着。独家作答后结论照常走 `approval/decided`，桌面看得到裁决结果。
+ * 独家作答后结论照常走 `approval/decided`，桌面看得到裁决结果。
+ *
+ * 唯一兜不住的边角是「审批发出时手机没在看、卡已转发到桌面，之后手机才连上来」：那一发
+ * 已经转发出去，手机后来答时靠 `cancelForwardedCards` 把它撤掉（见下）。
  */
 function holdForPhone(entry, next) {
   const downstream = next === undefined
@@ -275,6 +280,20 @@ function holdForPhone(entry, next) {
   return Promise.race([entry.wait.then((result) => result.outcome), downstream]);
 }
 
+/**
+ * 收掉桌面那张审批卡：把宿主已经发给桌面窗口、还挂着的那一发转发撤掉。
+ *
+ * 手机在看这条会话时审批桥本就不转发，桌面没有卡可收；会走到这里的是那条边角 —— 审批
+ * 发出时手机没在看、卡已转发到桌面，之后手机才连上来答。那一发只有桌面自己答 / 本轮取消
+ * / 宿主撤回三条路会消失，本桥替它补上最后一条（与提问桥 2026-10-31 同一手法：把钩子收到
+ * 的请求对象交给传输层，按它认回网关 `pendingRemoteEvents` 里那一发并撤回）。认不到（老
+ * 宿主没这道网关）就什么都不做 —— 「桌面没卡可收」本来就是对的。
+ */
+function cancelForwardedCards(ctx, entry) {
+  if (!entry.requestRef) return;
+  cancelForwardedRequests(ctx, entry.requestRef, new Error('手机已经回答了这条审批'));
+}
+
 function onApprovalRequest(request, next) {
   const sessionId = sessionIdOfRequest(request);
   if (!sessionId) return next();
@@ -333,6 +352,7 @@ async function handleApprovalRespond(ctx, req, res) {
   if (entry && !entry.settled && entry.bound
     && entry.sessionId === body.sessionId && entry.approvalId === body.approvalId) {
     settle(entry, body.outcome);
+    cancelForwardedCards(ctx, entry);
     return sendJson(res, 200, { ok: true, accepted: true });
   }
   const receipt = await respondViaLegacyProxy(ctx, {

package/lib/mobile/cli/acp.js

@@ -114,32 +114,46 @@ async function startAgent({ spec, cwd, env, onUpdate, onPermission, onStderr, on
   });
 
   let promptCapabilities = null;
-  const session = await Promise.race([
-    (async () => {
-      const initialized = await conn.agent.request(sdk.methods.agent.initialize, {
-        protocolVersion: sdk.PROTOCOL_VERSION,
-        // 不认领文件系统与终端能力：四家 CLI 都有自己的文件访问，我们替它读写反而要多做
-        // 一套实现，做漏了就是一条静默失败的路。
-        clientCapabilities: { terminal: false },
-        clientInfo: CLIENT_INFO,
-      });
-      // 这家认不认图片输入：握手时它自己说。不说就按「不支持」处理 —— 硬塞 image 块过去，
-      // 有的适配器会直接回一条参数错误，把整轮提问连正文一起废掉。
-      promptCapabilities = (initialized && initialized.agentCapabilities && initialized.agentCapabilities.promptCapabilities) || null;
-      const created = await conn.agent.request(sdk.methods.agent.session.new, {
-        cwd,
-        mcpServers: [],
-      });
-      return { sessionId: created.sessionId, created };
-    })(),
-    deadline,
-  ]);
 
+  /**
+   * 收掉这条连接与它的子进程。
+   *
+   * 必须定义在握手**之前**：握手失败或超时时这里直接抛错，而那时子进程已经起来了 —— 不在这
+   * 条路径上关掉，它就成了一个没人管的孤儿进程（卡在登录界面、还在等输入）。探配置那条路会
+   * 反复进来，漏一次就是攒一个进程。
+   */
   function kill() {
     try { conn.close(); } catch { /* 已经关了 */ }
     try { child.kill('SIGTERM'); } catch { /* 已经退出 */ }
   }
 
+  let session;
+  try {
+    session = await Promise.race([
+      (async () => {
+        const initialized = await conn.agent.request(sdk.methods.agent.initialize, {
+          protocolVersion: sdk.PROTOCOL_VERSION,
+          // 不认领文件系统与终端能力：四家 CLI 都有自己的文件访问，我们替它读写反而要多做
+          // 一套实现，做漏了就是一条静默失败的路。
+          clientCapabilities: { terminal: false },
+          clientInfo: CLIENT_INFO,
+        });
+        // 这家认不认图片输入：握手时它自己说。不说就按「不支持」处理 —— 硬塞 image 块过去，
+        // 有的适配器会直接回一条参数错误，把整轮提问连正文一起废掉。
+        promptCapabilities = (initialized && initialized.agentCapabilities && initialized.agentCapabilities.promptCapabilities) || null;
+        const created = await conn.agent.request(sdk.methods.agent.session.new, {
+          cwd,
+          mcpServers: [],
+        });
+        return { sessionId: created.sessionId, created };
+      })(),
+      deadline,
+    ]);
+  } catch (error) {
+    kill();
+    throw error;
+  }
+
   return {
     child,
     sessionId: session.sessionId,

package/lib/mobile/cli/mobile.js

@@ -46,6 +46,7 @@ const { createFrameSealer } = require('../stream.js')
 const { imageBlockOf, metaOf, openImage, saveImage, MAX_IMAGE_BYTES, MEDIA_EXT } = require('./images.js')
 const { resolveFinishedUpload } = require('../uploads.js')
 const { rememberModel } = require('./model-prefs.js')
+const { setValue } = require('./config-prefs.js')
 const { statsOf } = require('./usage.js')
 const { hiddenOf, setVisible } = require('./model-visibility.js')
 const { lookupModelMeta } = require('../model-meta.js')
@@ -1197,7 +1198,12 @@ function createCliMobile(deps) {
       const effort = textOf(body.reasoningEffort)
       if (effort) {
         const effortOption = thoughtOptionOf(options)
-        if (effortOption) await session.handle.setConfigOption(effortOption.id, effort)
+        if (effortOption) {
+          await session.handle.setConfigOption(effortOption.id, effort)
+          // 在对话里调过的档位也变成「以后新开的默认」—— 与配置页写的是同一本账
+          // （`config-prefs`），两条路不分家（见 A3-80）。
+          setValue(session.agentId, effortOption.id, effort)
+        }
       }
     } catch { /* 选不动就维持原样：下一次读 models 会回真实值 */ }
   }
@@ -1213,6 +1219,7 @@ function createCliMobile(deps) {
       if (updated && Array.isArray(updated.configOptions)) session.configOptions = updated.configOptions
       const option = (session.configOptions || []).find((item) => item && item.id === optionId)
       if (option && option.category === 'model') rememberModel(session.agentId, optionId, textOf(body.value))
+      else if (option) setValue(session.agentId, optionId, textOf(body.value))
     } catch { /* 同上 */ }
   }
 

package/lib/mobile/cli/service.js

@@ -19,6 +19,7 @@
  *      带全量块重放，页面回到原样。
  */
 
+const { homedir } = require('node:os');
 const { WebSocketServer } = require('ws');
 
 const { readJsonBody, sendJson } = require('../../shared/http-util');
@@ -55,6 +56,14 @@ const FLUSH_MS = 60;
 /** 标题兜底截断长度（宿主没给 `session_info_update.title` 时用首条提问）。 */
 const TITLE_MAX = 40;
 
+/**
+ * 「探一次配置」的失败重试间隔。
+ *
+ * 探一次要起一个适配器（首次还可能要 npx 下载），不能每次进配置页都重来一遍；但也不该把
+ * 一次失败记一辈子 —— 用户多半是去装了 CLI / 登录了才回来的。
+ */
+const PROBE_RETRY_MS = 60 * 1000;
+
 class CliRequestError extends Error {
   constructor(code, message) {
     super(message);
@@ -93,6 +102,8 @@ function pendingPrefsOf(session) {
   for (const option of options) {
     if (option && option.category === 'model') skip.add(option.id);
   }
+  // 模型那一项记在 `model-prefs` 那本账里（`applyPreferredModel` 负责），这里一律跳过 ——
+  // 包括 id 不叫 `model` 的那些（claude 的 `agent` 子代理、opencode 的分组模型）。
   const out = [];
   for (const [configId, value] of Object.entries(recorded)) {
     if (skip.has(configId)) continue;
@@ -112,6 +123,38 @@ async function bodyJson(req) {
   return body;
 }
 
+/**
+ * 这一项是不是「模型」。
+ *
+ * 判据是 ACP 给的 `category`，不是 id 的字面值：codex/opencode 叫 `model`，claude 的模型
+ * 项也叫 `model`，但换一家可能就是别的名字 —— 按 id 猜就会漏掉一家，而漏掉的表现正是
+ * 「配置页勾上了、开新对话还是原来的模型」。认不出（配置页还没拿到选项表）就按 id 兜底。
+ */
+function isModelOption(options, configId) {
+  const list = Array.isArray(options) ? options : [];
+  const option = list.find((item) => item && item.id === configId);
+  if (option) return option.category === 'model';
+  return configId === 'model';
+}
+
+/**
+ * 配置页要画的「记着的那一套」。
+ *
+ * 两本账合到一处：模型记在 `model-prefs`（新会话开局由 `applyPreferredModel` 套），其余记在
+ * `config-prefs`。配置页只认一张表，所以在这里并起来 —— 不并的话，配置页里模型那一格永远
+ * 显示「跟 CLI 自己的一样」，用户选过的模型看不见。
+ */
+function valuesBodyOf(agentId, options) {
+  const values = { ...prefsOf(agentId).values };
+  const preferred = preferredModel(agentId);
+  if (preferred) values[preferred.configId] = preferred.value;
+  // 两本账里都不该有「模型」，但真出现过（旧版本写进去的）就别让它冒充生效值。
+  for (const key of Object.keys(values)) {
+    if (isModelOption(options, key) && !(preferred && preferred.configId === key)) delete values[key];
+  }
+  return values;
+}
+
 /** 会话表与它的所有出口。一个宿主进程一份（装配层建、装配层关）。 */
 function createCliService({ authorized, onLog } = {}) {
   /** sessionId → 会话。 */
@@ -142,6 +185,72 @@ function createCliService({ authorized, onLog } = {}) {
     return agentsPromise;
   }
 
+  /** agentId → `{ running, at, error, done }`：这一家探配置的状态（同时只允许一次）。 */
+  const probes = new Map();
+
+  function probeState(agentId) {
+    return probes.get(agentId) || null;
+  }
+
+  /**
+   * 现去问一次这个 CLI 有哪些可调项。
+   *
+   * 为什么要这一步：选项表是 CLI 自己在握手之后给的，缓存里只有「开过对话的那几家」。用户新
+   * 装一个 CLI、想先把权限档配好再去用，正是最需要配置页的时候，而那时缓存是空的 —— 配置页
+   * 就是一句「没有可调的项」，四个配置入口点下去长得一模一样。
+   *
+   * 代价是起一次适配器（首次还要 npx 下载），所以：同一个 CLI 同时只探一次；探到手就落缓存，
+   * 之后的配置页直接读；失败记一段时间（`PROBE_RETRY_MS`），别让用户每次进来都等一轮下载。
+   * 它不进 `sessions` 那张表 —— 这是一次性的探测进程，拿到表就关，侧栏里不该多出一行。
+   */
+  function startProbe(ctx, agentId) {
+    if (probes.has(agentId) && probes.get(agentId).running) return;
+    const entry = { running: true, at: Date.now(), error: '', done: false };
+    probes.set(agentId, entry);
+    void (async () => {
+      let handle = null;
+      try {
+        const agent = (await listAgents()).find((item) => item && item.id === agentId) || null;
+        if (!agent) throw new Error('这台电脑上没有这个 CLI');
+        const spec = resolveAgent(agent);
+        if (!spec.ok) throw new Error(spec.reason || '这个 CLI 起不来');
+        // 起在哪：配置项与目录无关，随便借一个已注册工作区（没有工作区就借家目录 —— 有些适配器
+        // 对 cwd 有要求，给个存在且可写的路径总比空串安全）。
+        const cwd = await pickProbeCwd(ctx);
+        handle = await startAgent({ spec, cwd, env: childEnv(spec.command) });
+        if (closed) return;
+        // 探到了就记下来（这家确实一项都不给时记的是空表，配置页据此说「没有可调的项」
+        // 而不是一直转圈）。
+        rememberOptions(agentId, handle.configOptions);
+        entry.error = '';
+        // 这一家**问过了**：哪怕它一项配置都不给，也不许再探第二次 —— 那等于每进一次配置页
+        // 就起一个适配器进程，而结果永远是同一张空表。
+        entry.done = true;
+      } catch (error) {
+        entry.error = error && error.message ? error.message : '问不到这个 CLI 的配置';
+        log(`cli 探配置失败（${agentId}）：${entry.error}`);
+      } finally {
+        entry.running = false;
+        entry.at = Date.now();
+        try { handle?.close(); } catch { /* 已经退了 */ }
+      }
+    })();
+  }
+
+  /** 探测进程的工作目录：优先借一个已注册工作区，取不到就用家目录。 */
+  async function pickProbeCwd(ctx) {
+    try {
+      const listed = await ctx.apiProxy.workspace.list({ rpcId: 'mobile', method: 'workspace.list', payload: {} });
+      const { value } = unwrap(listed);
+      const items = Array.isArray(value) ? value : (value && Array.isArray(value.items) ? value.items : []);
+      for (const item of items) {
+        const dir = text(item && item.path);
+        if (dir) return dir;
+      }
+    } catch { /* 取不到就退到家目录 */ }
+    return homedir();
+  }
+
   function send(ws, frame) {
     if (ws.readyState !== ws.OPEN) return;
     try { ws.send(JSON.stringify(frame)); } catch { /* 已经断了 */ }
@@ -664,11 +773,11 @@ function createCliService({ authorized, onLog } = {}) {
         const updated = await session.handle.setConfigOption(configId, body.value);
         if (updated && Array.isArray(updated.configOptions)) session.configOptions = updated.configOptions;
         // 选过的模型要记住：下一次在这个 CLI 上开新会话时自动套上（见 applyPreferredModel）。
-        // 只记模型那一项 —— 思考档 / 权限模式跟着模型走，单独记会把两边记岔。
+        // 模型只记在 `model-prefs` 那本账里；其余每一项记进 `config-prefs.js` —— 那是「下次
+        // 开局自动套上」的唯一来源，两本账各记一份的话生效的那本必须是被写的那本。
         const option = (session.configOptions || []).find((item) => item && item.id === configId);
         if (option && option.category === 'model') rememberModel(session.agentId, configId, body.value);
-        // 每一项都记：这是「下次开局自动套上」的唯一来源（见 `cli/config-prefs.js`）。
-        if (option) setValue(session.agentId, configId, text(body.value));
+        else if (option) setValue(session.agentId, configId, text(body.value));
       } else throw fail('BAD_REQUEST', '需要 configId 或 modeId');
     } catch (error) {
       if (error && error.code && STATUS_BY_CODE[error.code]) throw error;
@@ -680,11 +789,15 @@ function createCliService({ authorized, onLog } = {}) {
   /**
    * GET /cli/prefs?agent=：一个 CLI 的配置全貌（配置页读它）。
    *
-   * 配置页在**没有开会话**的时候就要能画：所以这里回的是「上次记下的选项表 + 记着的值」，
-   * 一个进程都不用起。`live` 说的是这份表是从正在跑的那条会话读的（更新），还是缓存（CLI 那之后
-   * 可能升级过）。
+   * 优先顺序：正开着的那条会话手上的表（最新）→ 记忆里那份（CLI 握过手就记下）→ **现去问一次**。
+   * 最后一档是必须的：选项表是 CLI 自己给的，一家从没在这台电脑上开过对话的 CLI（全新装的
+   * Gemini CLI 之类）记忆里一条都没有，配置页就成了一句「没有可调的项」—— 而「提前把权限配
+   * 好」正是最需要它的时候。问的那一次在后台跑（起一个适配器、拿到 `configOptions` 就关掉），
+   * 回来之前回 `pending`，App 按退避重问。
+   *
+   * `live` 说的是这份表是从跑着的会话读的；`pending` 说的是正在问。
    */
-  function handlePrefs(_ctx, req, res) {
+  async function handlePrefs(ctx, req, res) {
     const agentId = text(query(req).get('agent'));
     if (!agentId) throw fail('BAD_REQUEST', '需要 agent');
     const recorded = prefsOf(agentId);
@@ -700,12 +813,29 @@ function createCliService({ authorized, onLog } = {}) {
       live = true;
       break;
     }
+    let pending = false;
+    let probeError = '';
+    // `force` 是配置页那行「重试」：探测失败之后，用户去装了 CLI / 登了录才回来，等
+    // `PROBE_RETRY_MS` 到点是不对的 —— 他这一下就是要现在再问一次。
+    const force = query(req).get('probe') === '1';
+    if (options.length === 0 && !live) {
+      const state = probeState(agentId);
+      if (state && state.running) pending = true;
+      else if (!state || force || (!state.done && (!state.error || Date.now() - state.at > PROBE_RETRY_MS))) {
+        startProbe(ctx, agentId);
+        pending = true;
+      } else if (!state.done && state.error) {
+        probeError = state.error;
+      }
+    }
     sendJson(res, 200, {
       ok: true,
       agent: agentId,
       options,
-      values: recorded.values,
+      values: valuesBodyOf(agentId, options),
       live,
+      pending,
+      ...(probeError ? { probeError } : {}),
     });
   }
 
@@ -724,14 +854,21 @@ function createCliService({ authorized, onLog } = {}) {
    * 那几条」。配置页在没有会话时用它，所以它也不启动任何进程。
    *
    * `value` 空 = 撤掉这一项，回到 CLI 自己的默认。
+   *
+   * **模型那一项记在 `model-prefs` 那本账上**：新会话开局是 `applyPreferredModel` 在读它，
+   * 记进 `config-prefs` 只会出现「配置页勾上了、开新对话却是别的」—— 两本账各记一份时，
+   * 生效的那本必须是被写的那本。
    */
   async function handleSetPref(_ctx, req, res) {
     const body = await bodyJson(req);
     const agentId = text(body.agent);
     const configId = text(body.configId);
     if (!agentId || !configId) throw fail('BAD_REQUEST', '需要 agent 与 configId');
-    setValue(agentId, configId, text(body.value));
-    sendJson(res, 200, { ok: true, agent: agentId, values: prefsOf(agentId).values });
+    const value = text(body.value);
+    const options = prefsOf(agentId).options;
+    if (isModelOption(options, configId)) rememberModel(agentId, configId, value);
+    else setValue(agentId, configId, value);
+    sendJson(res, 200, { ok: true, agent: agentId, values: valuesBodyOf(agentId, options) });
   }
 
   /** POST cli/close { sessionId }：主动收掉一个会话（用户点「结束」）。 */
@@ -897,5 +1034,9 @@ module.exports = {
   mountCli,
   createCliService,
   pendingPrefsOf,
+  // 配置页要画的那张表与「哪一项是模型」的判据：两条都在这里，测试直接钉这两份真函数
+  // （照抄一份等价实现的话，实现写错测试照样绿）。
+  isModelOption,
+  valuesBodyOf,
   MAX_SESSIONS,
 };