dsh-mini-remote 0.1.0 → 0.1.4

package/lib/index.js

@@ -5,9 +5,12 @@
  *   - 不代理 DSH 桌面界面（那是 dsh-pocket 的做法），手机只拿两样东西：
  *     用户发出的指令 + Agent 的最终回复。
  *   - 不监听 waterfall 事件。只订阅纯 emit 事件，避免误吞 agent 的默认行为。
- *   - 不 import 任何 @deepseek-ai/* 的运行时值。DSH 事件契约已经用 .d.ts 核实，
- *     消息对象自己造（MessageId 的 brand 在运行时是恒等函数、不做校验），
- *     这样插件加载期零外部依赖，也不会有 cordis 双副本的坑。
+ *   - 不 import 任何 @deepseek-ai/* 的运行时值，只有一个例外：@deepseek-ai/schemastery。
+ *     它只用来声明 Config（见下面 export const Config）——DSH 0.1.7 起，只有把字段标成
+ *     volatile，改它才不需要重载插件，而声明 schema 绕不开 schemastery。它由宿主提供
+ *     （写进 peerDependencies、不进 dependencies，免得出现第二份副本）。
+ *     其余照旧：事件契约已经用 .d.ts 核实，消息对象自己造（MessageId 的 brand 在运行时
+ *     是恒等函数、不做校验），插件加载期几乎没有外部依赖，也没有 cordis 双副本的坑。
  *
  * 事件契约（DSH 0.1.5-rc.2 实测）：
  *   session/event(session, event)  event = { type, seq, time, data }
@@ -22,19 +25,36 @@ import { homedir } from 'node:os'
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 
+import z from '@deepseek-ai/schemastery'
+
 import { createStore } from './store.js'
-import { createTurnTracker, visibleText } from './events.js'
-import { createMiniServer, sendJson, readBody } from './server.js'
+import { createTurnTracker, visibleText, stepSelfTalk } from './events.js'
+import { replayHistory, lastReply } from './history.js'
+import { readTailEvents } from './log-tail.js'
+import {
+  parseSlashLine, describeCommands, commandRow, commandPatch,
+  invalidCommandMessage, unknownCommandMessage,
+} from './commands.js'
+import { createMiniServer, miniControl, sendJson, readBody } from './server.js'
 import { sendExternalNotification } from './notify.js'
 import { reachableAddresses, resolveBindAddresses, isLocalRequest } from './net.js'
 import { buildPairing, tunnelUrlFor, tunnelProbeVerdict } from './pairing.js'
+import { serveState, serveEnable, serveDisable } from './serve.js'
 import { ensureCloudflared } from './cloudflared.js'
 import { startTunnel, TUNNEL_HINT } from './tunnel.js'
-import { listWorkspaces, listSessionsOf } from './tree.js'
+import { listWorkspaces, listSessionsOf, createSessionIn, createWorkspaceAt, sessionScale } from './tree.js'
+import { listRoots, listDirectory, makeDirectory } from './browse.js'
+import { listPresets, setPreset, available as presetsAvailable } from './permissions.js'
 import { buildId } from './build.js'
 
 export const name = 'dsh-mini-remote'
-export const inject = ['agents']
+// `sessionController` 是 DSH 的宿主会话业务接口（`@deepseek-ai/dsh-api-session-controller`
+// 挂上 Context 的那个），手机端要改每个会话的模型和思考强度就得靠它。
+//
+// **这一行单独加是有意的**：注入清单里写错名字不会报错，它会安静地让整个插件不加载——
+// 那就不是一行功能坏了，是整个遥控器起不来。所以先只加这行、重启，确认插件还活着，
+// 再往上加功能。真出问题也一眼知道是哪儿。
+export const inject = ['agents', 'sessionController']
 
 /** 公网隧道起不来时重试几次——向 Cloudflare 注册会偶发超时，实测大约一半概率。 */
 const TUNNEL_ATTEMPTS = 3
@@ -93,6 +113,60 @@ const DEFAULTS = {
   },
 }
 
+/**
+ * 给 schema 标上 volatile（"改了不用重载"）。
+ *
+ * 为什么要绕这一层判断：`.volatile()` 是 schemastery **3.18.3** 才加的方法，3.18.1／3.18.2
+ * 都没有。DSH 0.1.5 声明的依赖范围是 `^3.18.2`，是可以落到没有它的那一版上的——那种环境下
+ * 直接写 `.volatile()` 会在**加载插件的那一刻**抛异常，整个插件起不来，手机上什么都没有。
+ * 这个插件一贯的做法是"少了哪样就关掉哪一块，不整个倒下"，所以这里降级处理：没有这个方法
+ * 就原样返回，插件照常可用，只是少了"改配置不用重载"这一条（`liveConfig` 那边也会因此
+ * 认不出 volatile 字段，读到的就是普通值，行为与从前一致）。
+ */
+export function markVolatile(schema) {
+  return typeof schema?.volatile === 'function' ? schema.volatile() : schema
+}
+
+/**
+ * 插件设置的标准声明（DSH 0.1.7 起的做法）。宿主拿它校验 profile 补丁给我们的 config，
+ * 设置页那条编辑通道也按它生成表单——**只有标了 volatile 的字段才会出现在那张表单里**。
+ *
+ * **为什么一个 .default() 都没有**：schema 里的默认值会被 Loader 落进 config，而我们的
+ * 合并顺序是 `DEFAULTS < settings.json < config`——那样一来 schema 默认值就会盖住用户存在
+ * settings.json 里的值。留空即 undefined，deepMerge 会跳过 undefined，内置默认值照旧只在
+ * 下面 DEFAULTS 写一处。
+ *
+ * **为什么只有两个字段标 .volatile()**：标了就是承诺「改它不用重载插件」，而承诺得在代码里
+ * 兑现——这类字段必须用的时候现读（见 liveConfig）。端口和绑定地址要重新监听、隧道要重建、
+ * 口令的真相在 token 文件和手机页面的改密入口，这些改完确实要重建插件，就不标：DSH 会替我们
+ * 重载，那才是实话。宁可少标，不能乱标。
+ */
+export const Config = z.object({
+  port: z.number().description('手机上打开的那个端口。改了要重载插件（得重新监听）。'),
+  bindAddress: z.string().description("监听哪个地址：'auto'、'127.0.0.1' 或具体某个 IP。改了要重载插件。"),
+  tunnel: z.object({
+    enabled: z.boolean(),
+    cloudflaredPath: z.string(),
+  }).description('公网隧道（cloudflared）。改了要重载插件。'),
+  token: z.string().role('secret')
+    .description('访问口令。留空 = 首次启动自动生成；改口令用手机页面上的改密入口，改完要重载插件。'),
+  maxHistory: z.number().description('手机端每个会话保留多少条历史。改了要重载插件。'),
+  defaultMode: markVolatile(z.string())
+    .description("手机打开时默认进哪个模式：'minimal' 或 'chat'。改了立即生效，不用重载。"),
+  notify: markVolatile(z.object({
+    enabled: z.boolean(),
+    channel: z.string(),
+    barkUrl: z.string(),
+    ntfyUrl: z.string(),
+    ntfyTopic: z.string(),
+    telegramBotToken: z.string().role('secret'),
+    telegramChatId: z.string(),
+    onlyWhenBackground: z.boolean(),
+    maxLength: z.number(),
+    sound: z.string(),
+  })).description('外部推送（Bark / ntfy / Telegram）。改了立即生效，不用重载。'),
+})
+
 function deepMerge(base, ...overrides) {
   const out = { ...base }
   for (const patch of overrides) {
@@ -163,13 +237,44 @@ function userMessage(text, files = []) {
   })
 }
 
+/**
+ * 把标了 volatile 的配置字段接到 settings 上：读的时候现取，不在加载时抄一份。
+ *
+ * 为什么必须现取：DSH 对 volatile 字段的处理是「就地提交、不重建插件」——它只把新值写进那个
+ * 引用里，再 emit 一次 loader/volatile-update。要是我们加载时抄了一份，就地更新就永远看不见，
+ * 那这个声明比不声明更糟：DSH 不再重载我们，而我们手里还是旧值。
+ *
+ * 取值仍沿用原来的合并顺序：config 里显式写了就用 config（undefined 算没写），没写就用
+ * settings.json / 内置默认值那一路（`localBase` 那一份，不能拿合并了 config 的那份，
+ * 否则会把 volatile 的引用对象自己也当成"本地值"）。
+ */
+function liveConfig(settings, config, localBase) {
+  for (const [key, ref] of Object.entries(config ?? {})) {
+    if (!Config.dict?.[key]?.meta?.volatile) continue
+    if (!ref || typeof ref.get !== 'function') continue
+    let local = localBase?.[key]
+    Object.defineProperty(settings, key, {
+      enumerable: true,
+      configurable: true,
+      get: () => (ref.get() === undefined ? local : ref.get()),
+      set: (value) => { local = value },
+    })
+  }
+}
+
 export function apply(ctx, config = {}) {
   const dir = dataDir()
   mkdirSync(dir, { recursive: true })
 
   const settingsFile = join(dir, 'settings.json')
   const stored = readJson(settingsFile)
-  const settings = deepMerge(DEFAULTS, stored ?? {}, config)
+  // 两份来源分清楚：`local` 是"我们这份"（内置默认 + settings.json），`settings` 再叠上
+  // profile 补丁给的 config。volatile 字段要拿 `local` 当兜底，所以基线单独留一份。
+  const local = deepMerge(DEFAULTS, stored ?? {})
+  const settings = deepMerge(local, config)
+  // 标了 volatile 的字段改成"读的时候现取"（见 liveConfig）：这类字段改了不用重载插件。
+  liveConfig(settings, config, local)
+
   // 首次启动把默认配置落一份出来，用户才有东西可以改。
   if (stored === null) {
     writeFileSync(settingsFile, `${JSON.stringify(settings, null, 2)}\n`)
@@ -224,6 +329,13 @@ export function apply(ctx, config = {}) {
   /** DSH 的附件服务；纯 headless 组合里没有它，所以是可选的。 */
   let attachments = null
 
+  /**
+   * DSH 的斜杠指令账本（`ctx.commands`）。同样是可选的：DSH 明说无界面的组合
+   * 不提供这个面（headless / ACP 自动化），所以拿不到时就如实说「这台电脑上的
+   * DSH 没提供指令」，而不是给手机一个空名单。
+   */
+  let commandService = null
+
   /**
    * 正在流出来的那一段。
    *
@@ -714,6 +826,10 @@ export function apply(ctx, config = {}) {
     if (session.header?.origin === 'subagent') return
     const sessionId = session.id
 
+    // 手机正在看的这个会话：顺手让它的完整历史保持新鲜（一分钟最多重读一次）。
+    // 只对「当前绑定的那一个」做——手机上没在看的会话，读了也没人看，白花 CPU。
+    if (sessionId === targetSessionId()) ensureHistory(sessionId)
+
     // 会话标题（可选事件，拿到就用，拿不到就用 id 前 8 位兜底）
     if (event.type === 'session/title') {
       const title = event.data?.title ?? event.data?.text
@@ -723,8 +839,88 @@ export function apply(ctx, config = {}) {
       return
     }
 
+    // 这个会话现在用的是哪个模型、哪一档思考强度。
+    //
+    // **来源就是这儿**：DSH 每次发请求前都会广播一份 header，里面带着
+    // `config: { provider, model, reasoningEffort? }`——和 DSH 接口定义里那个
+    // `ModelSelection` 是同一个形状（见 tasks/todo.md 第 32 轮的侦察结论）。
+    // 所以读当前值不用另找接口，跟着事件走就行。
+    //
+    // 记下来给手机端显示用（2026-09-25 用户要求：手机上要能改每个会话的模型和强度）。
+    // 改完之后 DSH 会再发一份新的 header，这里跟着刷新，两边不会走散。
+    if (event.type === 'request/header') {
+      const cfg = event.data?.header?.config
+      if (cfg && typeof cfg.model === 'string') {
+        store.touchSession(sessionId, {
+          provider: typeof cfg.provider === 'string' ? cfg.provider : null,
+          model: cfg.model,
+          // 这一项可能是空的：那表示「用 provider 自己的默认」，不是出错
+          reasoningEffort: typeof cfg.reasoningEffort === 'string' ? cfg.reasoningEffort : null,
+        })
+      }
+      return
+    }
+
+    // 斜杠指令：它**不是一轮对话**，上面那个提取器不认它（会走到 `if (!action) return`
+    // 直接丢掉），所以得在这儿单独接住。
+    //
+    // 为什么值得单独一条路：指令不产生模型消息（DSH 的契约），所以它既不该长成用户
+    // 气泡，也不该被单帧模式当成「最新回复」。它是第三种东西——手机上画成一条紧凑的
+    // 「指令」行，和电脑端画在正文里是同一个意思。
+    //
+    // 开始（command/run）和收尾（command/done）靠 commandId 配对。配对逻辑和
+    // 「重放硬盘日志」那条路共用 lib/commands.js 里的映射，两边不会走散。
+    if (event.type === 'command/run' || event.type === 'command/done') {
+      // 手机还没绑会话时，谁先有动静就绑谁（和下面那条同一套口径）。
+      if (!store.state.boundSessionId) store.bind(sessionId)
+      if (sessionId !== targetSessionId()) return
+      if (event.type === 'command/run') {
+        const row = commandRow(event)
+        if (row) store.pushCommand({ ...row, sessionId })
+      } else {
+        const patch = commandPatch(event)
+        if (patch) store.settleCommand({ sessionId, ...patch })
+      }
+      store.touchSession(sessionId)
+      server?.broadcast('state', store.snapshot())
+      return
+    }
+
+    /**
+     * 一轮跑完，台词就作废。
+     *
+     * 不广播也安全：这一轮结束必然跟着一条回复或一条状态推送，手机自己会重画；
+     * 而页面那边还认着「这句我念过了」（比 at），所以旧的残留不会诈尸。
+     */
+    if (event.type === 'turn/end' && sessionId === targetSessionId()) {
+      store.setThought(sessionId, null)
+    }
+
     const action = tracker.feed(sessionId, event)
-    if (!action) return
+    if (!action) {
+      /**
+       * 到这里还不是「指令」也不是「回答」，但可能是别的会话都不管的第三种东西：
+       * 中间步骤的自言自语（鲸鱼娘的台词）。
+       *
+       * **必须在这儿接，不能等到下面。** 下面第一件事就是 `if (sessionId !==
+       * targetSessionId()) return`——那是给「会震动手机的内容」定的规矩，而台词也一样：
+       * 别的会话在想什么，跟手机正遥控的这个会话无关。
+       *
+       * 它取的是中间步骤的旁白或思考首行，**不落盘、不进历史**，所以回答区的口径
+       * （latest/history）一个字都不会因此改变——2026-09-22 用户否掉的是「过程的文字
+       * 跑进回答区」，不是「她说了句话」。
+       */
+      if (event.type === 'assistant/message') {
+        if (sessionId !== targetSessionId()) return
+        const talk = stepSelfTalk(event.data?.message?.content)
+        // 没话可说时**什么都不做**：留着上一句，比让气泡闪一下空要好。
+        if (!talk) return
+        store.setThought(sessionId, { text: talk.text, at: event.time ?? Date.now() })
+        store.touchSession(sessionId)
+        server?.broadcast('state', store.snapshot())
+      }
+      return
+    }
     store.touchSession(sessionId)
 
     // 手机还没绑会话时，谁先有动静就绑谁。
@@ -749,7 +945,9 @@ export function apply(ctx, config = {}) {
       }
       // 电脑上自己敲的指令也记一笔，聊天模式才完整。
       // 带上 id：那条也可能是**排队**排进去的，手机上要靠它对上号、标出「排队中」。
-      store.pushUser({ text: action.text, sessionId, id: action.id })
+      // 时间戳用事件自己的 `time`：硬盘重放出来的那份也是这个 `time`，两边同钟，
+      // 合成时才认得出「这条记录里已经有了」，不会接成两条（见 store.pushUser）。
+      store.pushUser({ text: action.text, sessionId, id: action.id, timestamp: event.time })
       server?.broadcast('state', store.snapshot())
       return
     }
@@ -757,6 +955,8 @@ export function apply(ctx, config = {}) {
     // action.kind === 'reply'
     store.pushReply({
       text: action.text, sessionId, reason: action.reason, interrupted: action.interrupted,
+      // 同上：和硬盘那份用同一个钟（事件的 `time`），否则同一条回复会显示两遍。
+      timestamp: event.time,
     })
     server?.broadcast('reply', {
       text: action.text,
@@ -901,6 +1101,289 @@ export function apply(ctx, config = {}) {
       + Boolean(treeServices.registry) + ' sessionQuery=' + Boolean(treeServices.query))
   })
 
+  // ------------------------------------------------------------------
+  // 点开一个会话，就把它**完整的历史**读出来（2026-09-25 用户要求）
+  //
+  // 为什么不能只靠手里那份记录：手机能点开全部会话（一个工作区常有上百条），
+  // 而插件手里那份只有「它在场时看见过的事件」——重启前跑过的、在电脑上开的，
+  // 点进去是空的。用户要的是：点开就该看到它之前的每一轮。
+  //
+  // 数据来源是 DSH 自己的会话记录（`sessionQuery.readSession`）。它有个很好的性质：
+  // **会话活着就从内存给（不读盘），睡着才去读它的日志**，而且日志是完整的
+  // （多帧 zstd 由 DSH 自己解）。所以对正在跑的那个会话，这条路几乎不要钱。
+  //
+  // 读出来的是原始事件，用 lib/history.js 重放成聊天记录——**和实时那条路
+  // 共用同一个提取器**，两条路对「哪条才算最终回答」的判断不会走散。
+  // ------------------------------------------------------------------
+
+  /** sessionId -> { at, entries, latest }。只活在内存里，不落盘（理由见 store.setReplaySource）。 */
+  const historyCache = new Map()
+  /** 正在读的那些：用户连点几下也只读一遍。 */
+  const historyPending = new Set()
+  /** 多久重读一次。会话跑着的时候历史会变长，一分钟够跟上；睡着的不变，重读也只是白读一次。 */
+  const HISTORY_TTL_MS = 60000
+
+  /**
+   * 整份读的两条红线（2026-09-25 事故后加的护栏）。
+   *
+   * 事故：手机绑定的会话是**带 310 个子会话的父会话**（26MB 压缩 / 2.2 万事件），
+   * 开机预热历史时 `readSession` 触发 v3→v4 迁移，把每个子会话整份解出来，
+   * 默认约 4GB 堆 20 秒 OOM。这两条阈值是「手机上宁可少看一点，也别把 DSH 拖死」
+   * 的取舍，都写在这儿方便调。
+   */
+  const HISTORY_MAX_CHILDREN = 20
+  const HISTORY_MAX_BYTES = 8 * 1024 * 1024
+
+  /**
+   * 手机端读历史的**上限**（2026-09-25 用户要求：读历史要有上限）。
+   *
+   * 上面两条红线决定「要不要绕开内核那条整份读」，这里三条决定
+   * 「自己读的时候最多读多少、最多给手机多少」。三层**都跟会话总量无关**：
+   *   - 窗口：只读日志末尾这么多**压缩**字节；
+   *   - 事件：窗口里最多留多少条事件（再向前对齐到一条 user 消息，让重放从一轮的开头起）；
+   *   - 条目：重放成聊天记录后，最多给手机多少条（≈ 轮数 × 2）。
+   */
+  // 窗口按「本机最坏的那条日志」实测选的（26MB / 2.2 万事件）：16MB 窗口 → 约 1.2 万事件、
+  // 197 条聊天记录、472ms、堆峰 ~400MB；4MB 窗口只有 29 条（太少）。事件上限只作极端兜底。
+  const HISTORY_TAIL_WINDOW_BYTES = 16 * 1024 * 1024
+  const HISTORY_TAIL_MAX_EVENTS = 20000
+  const HISTORY_MAX_ENTRIES = 200
+
+  /** 去 DSH 的会话记录里读一次，重放成聊天记录。读不出来返回 null。 */
+  async function readHistory(sessionId) {
+    const q = treeServices.query
+    if (typeof q?.readSession !== 'function') return null
+    try {
+      const snap = await q.readSession(sessionId)
+      // 子 agent 的会话不进手机——和实时那条路同一条口径（见 session/event 里那句）。
+      if (snap?.session?.origin === 'subagent') return null
+      const events = Array.isArray(snap?.events) ? snap.events : []
+      const entries = replayHistory(events)
+      const capped = capEntries(entries)
+      return {
+        entries: capped.entries,
+        latest: lastReply(capped.entries, sessionId),
+        truncated: capped.dropped > 0,
+        // 说「最近一段」而不是「最近 200 条」：这条记录读完之后，store 还会把
+        // 「刚发生、还没落进日志」的那一两条实时记录接在后面（见 mergeHistory），
+        // 于是手机上真看到的条数可能比这里多一两条。数字对不上就是假话，
+        // 所以这里只声称**读取的上限**，不声称列表长度。
+        note: capped.dropped > 0 ? `只显示最近一段（读取上限：${HISTORY_MAX_ENTRIES} 条）` : null,
+      }
+    } catch (err) {
+      // 老日志格式对不上、文件坏了，都会走到这儿。退回「手里那份」，**不编**。
+      console.log('[dsh-mini-remote] 这个会话的完整记录没读出来（' + sessionId + '）：'
+        + (err?.message ?? err))
+      return null
+    }
+  }
+
+  /** 聊天记录条数上限：从**尾部**留（手机上看的是最近发生的事）。 */
+  function capEntries(entries) {
+    if (!Array.isArray(entries) || entries.length <= HISTORY_MAX_ENTRIES) {
+      return { entries, dropped: 0 }
+    }
+    return { entries: entries.slice(-HISTORY_MAX_ENTRIES), dropped: entries.length - HISTORY_MAX_ENTRIES }
+  }
+
+  /**
+   * 有上限的读法：只解日志**尾部**的若干 zstd 帧，自己重放（见 lib/log-tail.js）。
+   *
+   * 什么时候用它：会话「大」的时候。那条整份读的路会把整份日志连同**所有直接子会话**
+   * 解出来（v3→v4 迁移要它们），代价一旦付出就收不回来——所以宁可少读一点。
+   * 拿不到就返回 null：由调用方如实说「没读到」，**不编内容**。
+   */
+  function readTailHistory(sessionId) {
+    let tail
+    try {
+      tail = readTailEvents(sessionId, {
+        windowBytes: HISTORY_TAIL_WINDOW_BYTES,
+        maxEvents: HISTORY_TAIL_MAX_EVENTS,
+      })
+    } catch (err) {
+      log.warn(`尾部读失败 ${sessionId}：${err?.message ?? err}`)
+      return null
+    }
+    if (!tail) return null
+    const entries = replayHistory(tail.events)
+    const capped = capEntries(entries)
+    if (!capped.entries.length) return null
+    const windowMb = (HISTORY_TAIL_WINDOW_BYTES / 1048576).toFixed(0)
+    return {
+      entries: capped.entries,
+      latest: lastReply(capped.entries, sessionId),
+      // 老实说清「读到的是不是全部」：窗口把整份都盖住了就不该再说「不是全部」。
+      truncated: tail.truncated,
+      note: tail.truncated
+        ? `这个会话很大，只显示最近一段（读取上限：${HISTORY_MAX_ENTRIES} 条 / ${windowMb}MB 窗口）`
+        : null,
+    }
+  }
+
+  /**
+   * 确保某个会话的完整历史就位。
+   *
+   * 不 await：这是个补数据的后台动作。刚切过去时界面先显示手里那份（或「正在读」），
+   * 读完广播一份新快照，手机上那一串自然就补全了。
+   */
+  async function ensureHistory(sessionId) {
+    if (!sessionId || historyPending.has(sessionId)) return
+    // 服务没到位（headless 组合）就没得读。**不能装作在读**——那会让手机上一直
+    // 显示「正在读取这个会话的记录…」，而其实谁也没去读。
+    if (typeof treeServices.query?.readSession !== 'function') return
+    const hit = historyCache.get(sessionId)
+    if (hit && Date.now() - hit.at < HISTORY_TTL_MS) return
+
+    // 先占坑：手机显示「正在读」靠的就是这个标记，**必须同步到位**——
+    // 不能等下面那次异步量规模回来（否则刚绑定那一下会显示成空会话）。
+    historyPending.add(sessionId)
+
+    // 读之前先量规模：内核那条整份读会把子会话一起解出来，代价收不回来。
+    // 「大」→ 走有上限的尾部读；「小」→ 仍走内核的完整读（日志权威，会话活着还免读盘）。
+    const scale = await sessionScale({ query: treeServices.query, sessionId })
+    const tooBigForWholeRead =
+      scale.children > HISTORY_MAX_CHILDREN || (scale.bytes ?? 0) > HISTORY_MAX_BYTES
+    let got = null
+    try {
+      if (tooBigForWholeRead) {
+        const size = scale.bytes == null ? '未知' : (scale.bytes / 1048576).toFixed(1) + 'MB'
+        log.info(`规模上限：${sessionId} 改走尾部读（子会话 ${scale.children}，日志 ${size}）`)
+        got = readTailHistory(sessionId)
+      } else {
+        got = await readHistory(sessionId)
+      }
+    } finally {
+      // 读不出来也记一笔（空结果），免得每次点进来都去读一遍坏文件。
+      if (historyCache.size >= 20) historyCache.clear()
+      historyCache.set(sessionId, {
+        at: Date.now(),
+        entries: got?.entries ?? null,
+        latest: got?.latest ?? null,
+        truncated: got?.truncated === true,
+        note:
+          got?.note ??
+          (tooBigForWholeRead ? '这个会话很大，最近这一段也没读出来' : null),
+      })
+      historyPending.delete(sessionId)
+      server?.broadcast('state', store.snapshot())
+    }
+  }
+
+  // store 取「完整历史」的地方（它拿不到 ctx，所以由插件注入一个回调）。
+  store.setReplaySource((sessionId) => {
+    const hit = historyCache.get(sessionId)
+    if (hit) {
+      return {
+        entries: hit.entries,
+        latest: hit.latest,
+        pending: false,
+        // 「这不是全部」要和内容一起给出去：手机得说清楚，不能让人以为
+        // 这个会话只有这么点内容（读历史有上限，见 HISTORY_MAX_* 那组常量）。
+        truncated: hit.truncated === true,
+        note: hit.note ?? null,
+      }
+    }
+    if (historyPending.has(sessionId)) return { entries: null, latest: null, pending: true }
+    return null
+  })
+
+  // ------------------------------------------------------------------
+  // 手机上答题：把电脑这边的提问推到手机，等它答，再把答案交还给电脑。
+  //
+  // 三条要点，都是踩过或想清楚了才这么写的：
+  //
+  // ① **必须 `{ prepend: true }`**。这条链是「遇到第一个愿意接的人就停」，而电脑上的
+  //    浏览器（经由 `dsh-api-remotes`）本来就接这个提问——排在它后面就永远轮不到我。
+  //    实测过：不带 prepend 时，挂根上、挂到 Agent 范围内，**两处都收不到**。
+  //
+  // ② **不接就让路**（`next()`）。手机没连着、问的不是手机上绑着的那个会话、
+  //    提问是空的——任何一种情况都原样让给浏览器，电脑那边照常弹窗，行为不变。
+  //    **插队不是为了抢，是为了有得选。**
+  //
+  // ③ **手机没了就把问题还回去**。用户选的是「一直等，不还回电脑」，但那不等于
+  //    「手机都关了他还等」——那种情况下电脑会永远卡住、而且没人提醒他。所以判据
+  //    不是倒计时，是「手机还在不在」。
+  // ------------------------------------------------------------------
+
+  // **注意这个监听器不是 async，这是刻意的，不是漏写。**
+  //
+  // 顾问指出的关键一条（对照 DSH 自己那个转发给远端的监听器，写法完全一致）：
+  // **「接不接」必须在同步的那一瞬间定下来，异步只用来产答案。**
+  // 它的形状是：同步判断 → 不接就同步 `return next()` → 接就同步 `return 一个将来会有答案的东西`。
+  //
+  // 我上一版是先 `await` 拿到服务、再判断、再 `return next()`——**让路的动作发生在异步之后**，
+  // 交不回派发的那个链条，于是表现为"完全没接管"，而且一句错都不报。
+  //
+  // 另外一条同样是顾问点出来的：**异步函数抛的错，同步的 try/catch 抓不到**（它是被拒绝的
+  // Promise，不是抛出的异常）。所以我之前说"日志里没报错"，**根本不能证明没出错**。
+  ctx.on('user-questions/request', function (request, next) {
+    const agentId = request?.agent?.id ?? null
+    const bound = store.snapshot().boundSessionId
+    const questions = Array.isArray(request?.questions) ? request.questions : []
+    // ——— 同步阶段：只做"接不接"的判断，绝不 await ———
+    // 能力从 `miniControl` 这个固定取用点拿（服务启动时主动放进去的），
+    // **不再经过 createMiniServer 的回执**——实测那个回执兑现出来是 undefined。
+    const phoneReady = typeof miniControl.hasPhone === 'function' ? miniControl.hasPhone() : false
+    /**
+     * **让路的那三种情况，每一种都留一行。**
+     *
+     * 2026-09-27 用户报「电脑上弹出了选项，手机上什么都没有」。当时这条链上只有
+     * 「答好了」和「出错」两句日志——正好把**让路**这半边全留白了，于是只能靠猜：
+     * 是手机没连、还是问的不是手机上绑的那个会话，日志里看不出来。
+     * 现在每次被叫到都记一行「问的是谁、手机绑的是谁、题数、手机在不在」。
+     * **不记题目正文**——那是用户自己的话。
+     */
+    if (!agentId || agentId !== bound || questions.length === 0) {
+      console.log(`[dsh-mini-remote] 提问让路：问的=${agentId ?? '无'}，手机绑的=${bound ?? '无'}，题目数=${questions.length}`)
+      return next()
+    }
+    if (!phoneReady) {
+      console.log('[dsh-mini-remote] 提问让路：手机上此刻没有连接（页面没开、锁屏或断网），交给电脑')
+      return next()
+    }
+    if (typeof miniControl.askPhone !== 'function') {
+      console.log('[dsh-mini-remote] 提问让路：拿不到 askPhone（手机服务还没起来），交给电脑')
+      return next()
+    }
+    // ——— 同步交出"将来会有答案"的东西；下面的等待都在这里，不再有同步判断 ———
+    console.log(`[dsh-mini-remote] 提问推给手机：${questions.length} 题，等它答`)
+    return miniControl.askPhone(questions, agentId).then((answer) => {
+      // 手机中途没了：把问题还给电脑，那边照常弹窗——不会两头都答不上。
+      // 这一句日志是「手机上答了、电脑上没动静」那类现象唯一能落下来的痕迹：
+      // 有它才知道手机那份答案没接上（断线、或者答晚了一步），而不是插件没在跑。
+      if (!answer) {
+        console.log('[dsh-mini-remote] 手机上没答成（连接断了、或者答晚了），这题还给电脑')
+        return next()
+      }
+      console.log('[dsh-mini-remote] 手机上答好了，交给电脑')
+      return answer
+    }).catch((err) => {
+      // 我这边出任何问题都不能把提问吞掉，一律让回电脑。
+      console.log('[dsh-mini-remote] 接管提问出错，让回电脑：' + String(err))
+      return next()
+    })
+  }, { prepend: true })
+
+  // ------------------------------------------------------------------
+  // 手机端「新建会话」要用的服务
+  // ------------------------------------------------------------------
+  // **单独 inject，绝不能并进上面那个数组**：`ctx.inject` 是「等齐了才回调」，
+  // 把一个可能不来的服务并进去，连工作区列表都会一起没了——本来只是少个按钮，
+  // 结果整个导航栏都空掉。分开就互不牵连。
+  //
+  // 拿到的是 `sessionController`（`@deepseek-ai/dsh-api-session-controller` 注册的名字），
+  // 就是网页端新建会话走的那条路。它的 `create({ workspaceId })` 内部会拼好会话、
+  // 装模型、挂 preset，最后交给 `ctx.agents.create()`。
+  //
+  // 这行日志是运行时事实的唯一来源：服务到底来没来、`create` 是不是函数，
+  // 「配置里挂了」只是推断，这里打出来的才算数。
+  const canCreate = { controller: null }
+  ctx.inject(['sessionController'], (createCtx) => {
+    canCreate.controller = createCtx.sessionController
+    console.log('[dsh-mini-remote] 新建会话已就绪：sessionController='
+      + Boolean(canCreate.controller) + ' create=' + typeof canCreate.controller?.create)
+  })
+
   // ------------------------------------------------------------------
   // 手机上传文件要用的附件服务
   // ------------------------------------------------------------------
@@ -911,6 +1394,85 @@ export function apply(ctx, config = {}) {
     console.log('[dsh-mini-remote] 附件服务已就绪：可以接收手机上传的文件')
   })
 
+  // ------------------------------------------------------------------
+  // 斜杠指令账本
+  // ------------------------------------------------------------------
+  // 走 ctx.inject、不写进 inject 数组（理由同上）。**指令列表不属于这个插件**：
+  // 它是 DSH 的账本，别的插件往里注册。手机只是多了一个「能发起指令的界面」——
+  // 所以这里不认识任何一条具体指令，也就不会有「手机上少了一条」的问题。
+  ctx.inject(['commands'], (cmdCtx) => {
+    commandService = cmdCtx.commands
+    console.log('[dsh-mini-remote] 指令服务已就绪：手机上可以执行斜杠指令')
+  })
+
+  /**
+   * 手机要的那份指令名单。
+   *
+   * 三种「拿不到」要分开说，因为下一步动作完全不同：没绑会话 / 会话没在跑 /
+   * 这台电脑没有指令服务。合成一句「取不到指令」，用户不知道该去做什么。
+   */
+  function onCommands() {
+    const sessionId = targetSessionId()
+    if (!sessionId) return { ok: false, error: '电脑上还没有可遥控的会话。' }
+    const agent = ctx.agents.get(sessionId)
+    if (!agent) {
+      return { ok: false, error: '这个会话现在没在跑，指令要先让它跑起来（发一句话）。' }
+    }
+    if (agent.session?.header?.origin === 'subagent') {
+      return { ok: false, error: '这是个子 Agent，手机上用不了它的指令。' }
+    }
+    if (!commandService) return { ok: false, error: '这台电脑上的 DSH 没提供指令。' }
+    try {
+      return { ok: true, commands: describeCommands(commandService.list(agent)) }
+    } catch (err) {
+      return { ok: false, error: `取指令列表失败：${err?.message ?? err}` }
+    }
+  }
+
+  /**
+   * 执行一条斜杠指令。
+   *
+   * **照抄 DSH 自己的语义，不自己发明**：指令行以 `/` 开头、名字是小写字母打头，
+   * 名字后面原样的一段归指令自己解释（我们连那个分隔空格都不动）。满足形状、
+   * 又确实注册过的，才交给 `execute`；其余一律**拒绝并说明**，绝不退回去当普通消息
+   * 发给模型——那正是「打错的指令白跑一轮模型」的来源。
+   *
+   * 这里**不等它跑完**（`execute` 要到处理器结束才 resolve）：指令的进度和结果是通过
+   * 会话事件（command/run、command/done）推到手机上的，和电脑端同一份账。
+   * 等它跑完会让这条 HTTP 请求一直挂着——像 /compact 这种要跑十几秒的指令，
+   * 手机上就成了「点了没反应」。
+   *
+   * 附件**这一版递不进去**：`execute` 要的是 DSH 自己那套上传小票，而手机上传走的是
+   * 另一套存储，两者不通（2026-09-25 查证）。所以这里一个附件都不传——输入框里那些
+   * 附件会原样留着，跟下一条普通消息一起发出去，不会丢。
+   */
+  async function onCommand(line) {
+    const sessionId = targetSessionId()
+    if (!sessionId) return { ok: false, error: '电脑上还没有可遥控的会话。' }
+    const agent = ctx.agents.get(sessionId)
+    if (!agent) {
+      return { ok: false, error: '这个会话现在没在跑，指令要先让它跑起来（发一句话）。' }
+    }
+    if (agent.session?.header?.origin === 'subagent') {
+      return { ok: false, error: '这是个子 Agent，手机上用不了它的指令。' }
+    }
+    if (!commandService) return { ok: false, error: '这台电脑上的 DSH 没提供指令。' }
+
+    const parsed = parseSlashLine(line)
+    if (!parsed) return { ok: false, error: invalidCommandMessage() }
+    if (!commandService.find(agent, parsed.name)) {
+      return { ok: false, error: unknownCommandMessage(parsed.name) }
+    }
+
+    // 不等：结果走事件流。但仍要接住异常，否则会变成没人处理的 Promise 拒绝，
+    // 在这台机器上表现为进程级的告警，而手机上什么也看不到。
+    const signal = new AbortController().signal
+    Promise.resolve(commandService.execute(agent, line, [], signal)).catch((err) => {
+      log.warn(`指令 /${parsed.name} 执行异常：${err?.message ?? err}`)
+    })
+    return { ok: true }
+  }
+
   /**
    * 把手机传来的字节交给 DSH 存，换一张小票回来。
    *
@@ -957,9 +1519,36 @@ export function apply(ctx, config = {}) {
     return map
   }
 
+  // 权限档位。跟建会话一样**单独一条 inject**：这个服务依赖 ctx.shell 和
+  // ctx.approval，headless 组合里根本不存在。要是跟别的服务挤在同一条 inject 里，
+  // 它不到场会把那条 inject 上的其它服务一起拖住——本项目在 tree 那三件套上
+  // 踩过这个坑，上面有注释。
+  const presets = { service: null }
+  ctx.inject(['permissionPresets'], (permCtx) => {
+    presets.service = permCtx.permissionPresets
+    console.log('[dsh-mini-remote] 权限档位已就绪：'
+      + (presetsAvailable(presets.service) ? presets.service.names.join(' / ') : '拿不到'))
+  })
+
+  /**
+   * 按 id 取会话对象。
+   *
+   * `PermissionPresetService` 的读和写都收**会话对象**而不是 id
+   * （`current(session)` / `set(session, name)`），所以得先拿 agent 再取它的 session。
+   * 拿不到就回 null——手机那边会显示「暂时读不到」，而不是整页崩掉。
+   */
+  function sessionFor(sessionId) {
+    if (!sessionId) return null
+    try {
+      return ctx.agents?.get(sessionId)?.session ?? null
+    } catch (err) {
+      return null
+    }
+  }
+
   const nav = {
-    listWorkspaces: (runningIds, force) =>
-      listWorkspaces({ registry: treeServices.registry, query: treeServices.query, runningIds, force }),
+    listWorkspaces: (runningIds, force, includeEmpty) =>
+      listWorkspaces({ registry: treeServices.registry, query: treeServices.query, runningIds, force, includeEmpty }),
     listSessionsOf: (workspaceId, limit, force) =>
       listSessionsOf({
         registry: treeServices.registry,
@@ -970,6 +1559,118 @@ export function apply(ctx, config = {}) {
         limit,
         force,
       }),
+    // 建会话：先用 inject 拿到的那个，拿不到就现读一次——`ctx.get` 对没写进 inject
+    // 的服务名是**返回 undefined**（不是抛错），所以这么写是安全的。
+    createSession: (workspaceId) =>
+      createSessionIn({
+        controller: canCreate.controller ?? ctx.get('sessionController'),
+        registry: treeServices.registry,
+        workspaceId,
+      }),
+    // 「这一刻到底能不能建会话」。给 /mini/api/version 用：那是个不用动手、
+    // 一条命令就能问的运行时事实，比翻日志快。和 createSession 同一条判据，
+    // 免得出现「探测说能、真按了却不行」。
+    canCreateSession: () =>
+      typeof (canCreate.controller ?? ctx.get('sessionController'))?.create === 'function',
+    // 登记工作区。`workspaceRegistry` 就是上面那三个服务里的 registry，
+    // 已经注入到位了，不用再开一条依赖。
+    createWorkspace: (path) =>
+      createWorkspaceAt({ registry: treeServices.registry, path }),
+    // 权限档位。作用域就是传进来的那个会话——手机只绑一个会话，所以
+    // 「当前会话」和「绑定会话」是同一件事，不用另外记状态。
+    permissions: (sessionId) =>
+      listPresets({ service: presets.service, session: sessionFor(sessionId) }),
+    setPermission: (sessionId, name) =>
+      setPreset({ service: presets.service, session: sessionFor(sessionId), name }),
+
+    // 模型与思考强度（2026-09-25 用户要求：手机上要能改每个会话的模型和强度）。
+    // `canCreate.controller` 就是 `ctx.sessionController`——和上面 createSession 同一个东西。
+    //
+    // 有个区别要记牢：**目录是全局的，选中的那个是会话级的**。所以列清单只要问一次，
+    // 「现在用哪个」得按会话问。`ModelSelection` 就是 `{ provider, model, reasoningEffort? }`，
+    // 强度不是单独一项设置，它是模型选择的一部分——这也是为什么两个按钮要一起改。
+    //
+    // 拿不到能力时如实说 `unavailable`，让手机整块不显示。**不假装只有一种模型可选**：
+    // 那会让用户以为自己的模型被换掉了。
+    modelCatalog: async () => {
+      const controller = canCreate.controller ?? ctx.get('sessionController')
+      if (typeof controller?.modelCatalog !== 'function') return { ok: false, reason: 'unavailable' }
+      return { ok: true, catalog: await controller.modelCatalog() }
+    },
+    selectModel: async (sessionId, selection) => {
+      const controller = canCreate.controller ?? ctx.get('sessionController')
+      if (typeof controller?.selectModel !== 'function') return { ok: false, reason: 'unavailable' }
+      const value = await controller.selectModel({ sessionId, ...selection })
+      return { ok: true, selected: value?.selected ?? null }
+    },
+    // 某个会话**现在到底用哪个模型**。
+    //
+    // 为什么非得问 DSH、不能自己记：插件只在会话跑起来时才从事件里看到模型
+    // （request/header），没在插件眼皮底下跑过的会话——比如重启之前用过的那些——
+    // 手里就是空的。上一版给空值兜了一个「目录默认值」，结果把一个不知道的会话
+    // 显示成上次选过的那个模型：看着像对的，其实是编的。**宁可说不知道，也不编。**
+    //
+    // 两条路，**第二条是必须的**：
+    //   ① 会话正活着 → 它的 `requestHeader()` 直接给结果，走内存，最快。
+    //   ② 会话睡在硬盘上 → 去它的日志里翻最后那条 request/header 事件。
+    //
+    // ② 不是备胎，是主路。手机上能挑的是**全部**会话（这个工作区里就有上百个），
+    // 而「活着的」通常只有开着的两三个——只走 ① 的话，用户切到绝大多数会话都只能
+    // 看到「还没问到」。查证过：147 个会话里只有 3 个是活的。
+    //
+    // 用 `sessionQuery.listEvents`：它的说明是「列出原始日志事件」，并且注明
+    // **优先取活着的、没有就读硬盘**——两件事一个方法全包，不用我自己分支。
+    sessionModel: async (sessionId) => {
+      if (!sessionId) return { ok: false, reason: 'no-id' }
+      const shape = (cfg) => ({
+        provider: typeof cfg.provider === 'string' ? cfg.provider : null,
+        model: cfg.model,
+        reasoningEffort: typeof cfg.reasoningEffort === 'string' ? cfg.reasoningEffort : null,
+      })
+
+      // ① 活着的会话：内存里就有
+      const sessions = ctx.get('sessions')
+      const live = typeof sessions?.get === 'function' ? sessions.get(sessionId) : undefined
+      const liveCfg = live && typeof live.requestHeader === 'function' ? live.requestHeader()?.config : null
+      if (liveCfg && typeof liveCfg.model === 'string') return { ok: true, model: shape(liveCfg) }
+
+      // ② 睡着的会话：读硬盘上的日志，从后往前找最后那条 request/header。
+      //
+      // **必须用 `readSession`，不能用 `listEvents`。** 后者给的是**元数据**
+      // （sessionId / seq / type / time / surface），**没有 `data`**——而配置恰恰在
+      // `data` 里。这个已经试过一次，读出来是空的，白跑一轮。`readSession` 给的是
+      // 完整的原始事件，`data.header.config` 就在里面。
+      //
+      // 读整个日志是贵的，而手机每 15 秒会来问一次，所以缓存 60 秒：桌面那边改了模型，
+      // 最迟一分钟内在手机上出现。手机自己改的那次走另一条路（那条接口会把新值直接
+      // 写进会话记录），不受这个缓存影响。
+      const cache = treeServices.modelCache || (treeServices.modelCache = new Map())
+      const hit = cache.get(sessionId)
+      if (hit && Date.now() - hit.at < 60000) return hit.value
+
+      const q = treeServices.query
+      let value
+      if (typeof q?.readSession !== 'function') {
+        value = { ok: false, reason: 'unavailable' }
+      } else {
+        try {
+          const snap = await q.readSession(sessionId)
+          const events = Array.isArray(snap?.events) ? snap.events : []
+          value = { ok: false, reason: 'no-header' }
+          for (let i = events.length - 1; i >= 0; i--) {
+            const e = events[i]
+            if (!e || e.type !== 'request/header') continue
+            const cfg = e.data?.header?.config
+            if (cfg && typeof cfg.model === 'string') { value = { ok: true, model: shape(cfg) }; break }
+          }
+        } catch (err) {
+          value = { ok: false, reason: 'read-failed', error: String(err && err.message ? err.message : err) }
+        }
+      }
+      if (cache.size > 50) cache.clear()
+      cache.set(sessionId, { at: Date.now(), value })
+      return value
+    },
   }
 
   // ------------------------------------------------------------------
@@ -985,10 +1686,18 @@ export function apply(ctx, config = {}) {
       tunnelHost,
       log,
       onInstruction,
+      onCommands,
+      onCommand,
       onUpload,
       onStop,
       onUnqueue,
+      // 手机点开会话（或刷新页面）时，把那条会话的完整历史读出来。
+      onSessionOpened: (sessionId) => ensureHistory(sessionId),
       tree: nav,
+      // 目录浏览自己读盘（理由见 lib/browse.js 开头：DSH 的目录选择器在
+      // 「Windows + 只绑回环」时会判成 native，那套动词是直接拒绝的，
+      // 会在电脑屏幕上弹框——而用户正在外面用手机）。
+      browse: { listRoots, listDirectory, makeDirectory },
       build: BUILD,
     })
       .then((instance) => {
@@ -1014,6 +1723,9 @@ export function apply(ctx, config = {}) {
         }
         // 服务起来了才谈得上开隧道：cloudflared 要指向这个端口
         if (settings.tunnel?.enabled) bringTunnelUp()
+        // 重启前手机在看哪个会话，就先把它的完整历史补上——用户打开手机时
+        // 该看到的是那个会话的全貌，而不是「重启之后才发生的事」。
+        ensureHistory(store.snapshot().boundSessionId)
       })
       .catch((err) => {
         // 记下来。设置页那边要拿它把「还在启动」和「起不来了」分开说——
@@ -1084,6 +1796,18 @@ export function apply(ctx, config = {}) {
           starting: tunnelStarting,
           error: tunnelError,
         },
+        /**
+         * Tailscale 那条路上的 HTTPS 地址。
+         *
+         * **每次刷新都现问一次**，不缓存：这个状态会被别的东西改掉——用户可能在
+         * 命令行里 `tailscale serve --https=443 off`，也可能 Tailscale 自己升级后
+         * 配置没了。缓存一份就会漂移，而漂移的表现是「面板上写着已开启、手机却打不开」，
+         * 正是 2026-09-22 隧道那次踩过的坑。
+         *
+         * 问的是 `server.port`（**实际**在听的那个），不是配置里的 port——
+         * 端口被占时服务会自己往后让，用配置值会指错。
+         */
+        serve: await serveState(server.port),
       })
       return { status: payload.ok ? 200 : 500, body: payload }
     }
@@ -1132,6 +1856,60 @@ export function apply(ctx, config = {}) {
       },
     })
 
+    /**
+     * 开/关 Tailscale 的 HTTPS 地址。
+     *
+     * 和公网那个开关一样**只允许本机调用**（`localOnly`）：它会改这台电脑上
+     * Tailscale 的配置，不该让手机或同网段的别人碰到。
+     *
+     * 失败时把 `enableLink` 一起带回去——那是 tailnet 没开 Serve 时 Tailscale
+     * 官方印出来的开启链接。整个功能里门槛最高的就是这一步，把链接原样递给用户，
+     * 他点一下就完事；自己写一句「请到后台开启」等于把门槛加回去。
+     */
+    const offServe = webServer.register({
+      kind: 'exact',
+      path: '/mini-remote/serve',
+      handler: async (req, res) => {
+        if (!localOnly(req, res)) return
+        if (req.method !== 'POST') {
+          sendJson(res, 405, { ok: false, error: '这个地址只接受 POST。' })
+          return
+        }
+        let want
+        try {
+          want = await readBody(req)
+        } catch (err) {
+          sendJson(res, 400, { ok: false, error: `请求体读不了：${err?.message ?? err}` })
+          return
+        }
+        if (!server) {
+          sendJson(res, 503, { ok: false, error: '手机服务还在启动，过几秒再试。' })
+          return
+        }
+        try {
+          const r = want?.enabled ? await serveEnable(server.port) : await serveDisable()
+          if (!r.ok) {
+            sendJson(res, 400, {
+              ok: false,
+              error: r.error,
+              enableLink: r.enableLink ?? null,
+              reason: r.reason ?? 'other',
+            })
+            return
+          }
+        } catch (err) {
+          sendJson(res, 500, { ok: false, error: `切换 HTTPS 地址失败：${err?.message ?? err}` })
+          return
+        }
+        try {
+          const { status, body } = await pairingPayload()
+          sendJson(res, status, body)
+        } catch (err) {
+          sendJson(res, 500, { ok: false, error: `切换之后读不到状态：${err?.message ?? err}` })
+        }
+      },
+    })
+
     /**
      * 密码最短多少位。
      *
@@ -1198,9 +1976,20 @@ export function apply(ctx, config = {}) {
       },
     })
 
+    /**
+     * 卸载时把注册过的路由全部注销。
+     *
+     * **每加一条 `webServer.register` 都要往这里补一笔**，否则插件卸载后那条路由
+     * 还挂在服务器上，指向一个已经死掉的闭包——再有人打过来就是莫名其妙的报错。
+     *
+     * 2026-09-24 补：`offToken` 一直是漏的（改密码那条路由注册了却没注销），
+     * 加 HTTPS 这条时对照着数了一遍才发现。四条注册，四条注销，现在对得上。
+     */
     return () => {
       offGet?.()
       offTunnel?.()
+      offServe?.()
+      offToken?.()
     }
   })
 }