dsh-mini-remote 0.1.9 → 0.2.0

package/lib/server.js

@@ -13,10 +13,29 @@
  */
 import { createServer } from 'node:http'
 import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { renderPage, readArt, readImage, readSw } from './page.js'
 
 const COOKIE = 'dsh_mini_token'
 
+/**
+ * 镜像页「诊断模式」那份样本落在哪。
+ *
+ * **`scratch/` 是 gitignore 的**，所以诊断日志扔在这里不会入库；
+ * 路径按本文件的位置算（`lib/server.js` 的上一级就是插件根目录），
+ * 装到哪儿都不用再配一次。
+ *
+ * `DSH_MINI_DIAG_LOG` 可以整体换掉它——**测试用它写到临时文件**，
+ * 免得测试的样本混进真机上那一份里，让读日志的人分不清哪条是真机报的。
+ */
+function diagLogPath() {
+  const override = process.env.DSH_MINI_DIAG_LOG
+  if (override) return override
+  return fileURLToPath(new URL('../scratch/diag.log', import.meta.url))
+}
+
 /**
  * 配置的端口被占时，往后最多再试几个。
  *
@@ -137,6 +156,97 @@ export function sendJson(res, status, payload) {
   res.end(body)
 }
 
+/**
+ * 镜像那几条路径**此刻走不通**时，回给手机的那一页（调用处见 `handle` 里的兜底 404）。
+ *
+ * ## 为什么非要有它（2026-10-08 真机截图）
+ *
+ * `/mini/mirror` 那一整块路由是挂在开关上的（见 `handle` 里 `mirrorEnabled()` 那一行），
+ * 所以「开关关着」和「电脑端还没就绪」这两种时候，`/mini/mirror/…` 会掉进兜底 404，
+ * 原来回的是 `{"error":"not found"}`。**而手机那一页是把镜像嵌在 iframe 里的**：
+ * 这个 JSON 于是成了框里的**文档**，被浏览器当成页面渲染出来——用户看到的是框里一条
+ * 外星文（华为浏览器还给它套了个「美观输出」的 JSON 查看器），外面那条
+ * 「电脑端界面 / 返回」却还好端端地在，看起来就像界面坏了。**给程序看的正文跑到了人眼前。**
+ *
+ * ## 三条要求
+ *
+ * ① **人话**：现在打不开、以及下一步做什么；
+ * ② **自己会重试**：宿主刚重启那几十秒里上游地址还没解析出来，等一下它自己就好了
+ *    ——真机上「有时候打得开、有时候打不开」就是这一段（见 lib/mirror.js 的 resolveReady）；
+ * ③ **有出口**：那个框里没有别的按钮，所以给一个「返回手机页」——它给外层页发一条消息，
+ *    `lib/page.html` 里接住、把那整屏收起来。
+ *
+ * **状态码仍然是 404**：这条路此刻确实不存在（开关关着时它就该像不存在一样），
+ * 这里换掉的只是**正文**，不是「这条路存不存在」这件事本身。
+ */
+export function sendMirrorUnavailable(res) {
+  // 重试次数放在地址里（`&retry=n`）：不依赖 localStorage，也不会让框里的历史变长
+  // （用 location.replace）。**次数用尽就停下**——一直空转会烧手机的电，也永远不给交代。
+  // 入口那一下会把整个查询串丢掉，所以这个参数绝不会漏到上游去。
+  const html = `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>电脑端界面现在打不开</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; padding: 24px 18px; color: #1b1b1b; background: #fff;
+         font: 15px/1.7 system-ui, -apple-system, "Noto Sans CJK SC", sans-serif; }
+  h1 { margin: 0 0 12px; font-size: 17px; }
+  p { margin: 0 0 10px; color: #555; }
+  .acts { display: flex; gap: 10px; margin-top: 20px; }
+  button { font: inherit; padding: 10px 16px; border-radius: 2px; color: inherit;
+           border: 1px solid #d6d6d6; background: #f6f6f6; }
+  @media (prefers-color-scheme: dark) {
+    body { color: #eee; background: #111; }
+    p { color: #aaa; }
+    button { border-color: #3a3a3a; background: #1e1e1e; }
+  }
+</style>
+</head>
+<body>
+<h1>电脑端界面现在打不开</h1>
+<p id="why">正在等电脑端就绪…</p>
+<p>电脑端刚起来的那几十秒里会是这样，等一下通常就好。如果一直打不开：回到手机页，在「进阶设置」里确认「电脑端界面」是开着的，再点一次「打开」。</p>
+<div class="acts">
+  <button id="retry" type="button">重试</button>
+  <button id="back" type="button">返回手机页</button>
+</div>
+<script>(function () {
+  var MAX = 5;                 // 自己最多重试几次
+  var GAP = 2500;              // 每次之间隔多久
+  var why = document.getElementById('why');
+  var url = new URL(location.href);
+  var n = Number(url.searchParams.get('retry') || 0);
+  if (!(n >= 0)) n = 0;
+  document.getElementById('retry').addEventListener('click', function () {
+    var clean = new URL(location.href);
+    clean.searchParams.delete('retry');
+    location.replace(clean.toString());
+  });
+  document.getElementById('back').addEventListener('click', function () {
+    try { window.parent.postMessage('mini-mirror-close', '*'); } catch (e) {}
+  });
+  if (n >= MAX) {
+    why.textContent = '还没等到电脑端就绪（也可能是手机那边的开关关着）。';
+    return;
+  }
+  why.textContent = '正在等电脑端就绪…（第 ' + (n + 1) + ' 次，共 ' + MAX + ' 次）';
+  url.searchParams.set('retry', String(n + 1));
+  setTimeout(function () { location.replace(url.toString()); }, GAP);
+})();</script>
+</body>
+</html>`
+  const buf = Buffer.from(html, 'utf8')
+  res.writeHead(404, {
+    'Content-Type': 'text/html; charset=utf-8',
+    'Content-Length': buf.length,
+    'Cache-Control': 'no-store',
+  })
+  res.end(buf)
+}
+
 /**
  * @param {object} opts
  * @param {import('./store.js').createStore extends (...a:any)=>infer R ? R : never} opts.store
@@ -172,7 +282,7 @@ export const miniControl = {
  *        （由插件递进「当前已注册工作区的目录」，见 extraImageRoots 那段）
  * @returns {Promise<{port:number, addresses:string[], failed:{address:string,message:string}[], close:()=>Promise<void>, broadcast:(event:string, data:unknown)=>void, broadcastTrajectory:(payload:object)=>void, broadcastTrajectoryLive:(payload:object)=>void}>}
  */
-export async function createMiniServer({ store, config, token, bindAddresses, tunnelHost, onInstruction, onCommands, onCommand, onStop, onUnqueue, onUpload, onSessionOpened, log, tree, browse, build, imageRoots }) {
+export async function createMiniServer({ store, config, token, bindAddresses, tunnelHost, onInstruction, onCommands, onCommand, onStop, onUnqueue, onUpload, onSessionOpened, log, tree, browse, build, imageRoots, mirror, mirrorEnabled }) {
   /** @type {Set<import('node:http').ServerResponse>} */
   const clients = new Set()
 
@@ -698,6 +808,49 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     attempts.delete(clientKey(req, tunnelHost?.()))
   }
 
+  /**
+   * 把**我们自己那个** `token` 查询参数摘掉，其余一个字符都不动。
+   *
+   * 为什么必须摘：那个界面的插件脚本走一条合并加载路径（`plugins/??a/client.js&rev=x`），
+   * 上游对它是**精确匹配**——多一个 `&token=...` 就当场 404，脚本一 404，界面就卡在
+   * 启动画面报「HTML did not preload @deepseek-ai/dsh-client-modules/client.js」。
+   * 这是真机上试出来的，不是推的。
+   *
+   * **逐段切、再拼回去，不走 URLSearchParams**：那条合并路径里有 `@`、`/`、`,` 这些字符，
+   * 交给它解析再序列化会被百分号编码，路径就变了——那等于换个法子把它弄坏。
+   * 只在值确实等于我们的令牌时摘，免得误伤界面自己可能用到的同名参数。
+   */
+  function stripOurToken(rawUrl) {
+    const at = rawUrl.indexOf('?')
+    if (at < 0) return rawUrl
+    const head = rawUrl.slice(0, at)
+    const parts = rawUrl.slice(at + 1).split('&')
+    const encoded = encodeURIComponent(token)
+    const kept = parts.filter((p) => p !== `token=${token}` && p !== `token=${encoded}`)
+    if (kept.length === parts.length) return rawUrl
+    return kept.length ? `${head}?${kept.join('&')}` : head
+  }
+
+  /**
+   * 把**我们自己那个** `diag=1` 摘掉，其余一个字符都不动。
+   *
+   * 和上面的 token 是同一个道理（真机上试出来的）：上游对一部分地址是**精确匹配**，
+   * 多带一个参数就当场 404。`diag` 是我们读的开关，上游不认识它，
+   * 所以往上游转之前必须摘掉。**入口那一下本来就把查询串整个丢了**，
+   * 这里管的是前缀下面的那些地址（`/mini/mirror/assets/x?diag=1` 这种）。
+   *
+   * 只摘 `diag=1` 这一个形状，别的一律不碰——上游自己要用同名参数也不至于被误伤。
+   */
+  function stripDiagFlag(rawUrl) {
+    const at = rawUrl.indexOf('?')
+    if (at < 0) return rawUrl
+    const head = rawUrl.slice(0, at)
+    const parts = rawUrl.slice(at + 1).split('&')
+    const kept = parts.filter((p) => p !== 'diag=1')
+    if (kept.length === parts.length) return rawUrl
+    return kept.length ? `${head}?${kept.join('&')}` : head
+  }
+
   async function handle(req, res) {
     const url = new URL(req.url, `http://${req.headers.host ?? 'localhost'}`)
     const path = url.pathname
@@ -822,8 +975,150 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // ---- 「进阶设置」：电脑端界面的镜像 --------------------------------
+    //
+    // 见 lib/mirror.js 开头的说明。这里只负责三件事：**认路、鉴权、放行**。
+    //
+    // ## 认路这件事比想的绕，两次才做对
+    //
+    // 那个界面里的请求有**两种**写法，两种都要能通：
+    //
+    // ① **相对的**：外壳里写的是 `<base href="./">` + `./assets/index-xxx.js`。
+    //    它本来就是按「可以被挂在任意子路径下」设计的。所以入口必须**带尾斜杠**，
+    //    并且把 `/mini/mirror/` 这个前缀剥掉再转发——否则 `./` 会解析到 `/mini/`，
+    //    那些脚本就跑到`/mini/assets/...` 上、被当成我们自己的地盘，全 404。
+    //    **第一版就是这么白屏的**（真浏览器打开验出来的：DOM 拿到了、但一片空白）。
+    // ② **绝对的**：它调 API 走 `/api/...`、插件资源走 `/plugins/...`。
+    //    这些没法靠前缀，所以反过来——**凡是不是我们自己的路径，一律转给它**。
+    //    我们自己的地盘只有 `/`、`/mini`、`/mini/*`。
+    //
+    // **鉴权不能省**：这条路由等于把整个电脑端设置面（模型配置、凭据页、
+    // 插件装卸、会话记录……）交给持有我们令牌的人。所以要求和 `/mini/api/*` 同一道门。
+    // 手机那边不必每次都带参数——入口那一下写好了 cookie，而 cookie 的 Path 是 `/`，
+    // 界面自己发的那些请求会自然带上。
+    //
+    // ## 还有一条：**我们自己的 `token` 参数不许跟着转发上去**
+    //
+    // 这是真机上试出来的：那个界面的插件脚本走一条合并加载路径
+    // （`plugins/??@a/client.js&rev=xxx`），**上游对它是精确匹配**——多带一个
+    // `&token=...` 就当场 404。而脚本一 404，界面就卡在启动画面报
+    // 「HTML did not preload @deepseek-ai/dsh-client-modules/client.js」。
+    // 所以转发前先把自己那个参数摘掉（**只在它确实是我们的令牌时摘**，
+    // 免得误伤界面自己可能用到的同名参数）。
+    if (mirror && typeof mirrorEnabled === 'function' && mirrorEnabled()) {
+      const MIRROR_PREFIX = '/mini/mirror'
+      /**
+       * **诊断模式开关**（`?diag=1`）。
+       *
+       * 之后注入的那段采样脚本只看这一个参数（见 lib/mirror.js 的 DIAG_SCRIPT），
+       * **不带它时行为完全不变**——这一条有测试钉着。
+       *
+       * 必须**在这里、在改写 `req.url` 之前**读出来：入口那一下会把查询串整个丢掉
+       * （上游那条精确匹配的路由不认我们这些参数），丢掉之后就没得读了。
+       */
+      const diag = url.searchParams.get('diag') === '1'
+      const mirrorEntry = req.method === 'GET'
+        && (path === MIRROR_PREFIX || path === `${MIRROR_PREFIX}/`)
+      const mirrorUnder = path.startsWith(`${MIRROR_PREFIX}/`)
+      const ours = path === '/' || path === '/mini' || path === '/mini/'
+        || path === '/mini/sw.js' || path.startsWith('/mini/art/')
+      // 三种都要放行：入口、挂在 `/mini/mirror/` 下面的相对路径、以及界面自己发的
+      // 绝对路径（`/api/...`、`/plugins/...`）。**第二种漏掉过一次**——剥前缀那段
+      // 就成了死代码，测试当场抓住。
+      //
+      // **第二种曾经还写错过一次**（2026-10-06 真机）：当时限制成「只收 GET」，
+      // 而界面外壳写着 `<base href="./">`，**它所有请求都带这个前缀**——于是那些 POST
+      // （`/mini/mirror/api/session/list`、`settings/describe`、`agentPresets/list` …）
+      // 全掉进我们自己的 404，界面上就是一片「加载不出来」。
+      // 前缀下面的路径**本来就只可能是界面的**（我们自己的接口都在 `/mini/api/`），
+      // 所以这里不该按方法设限。
+      // **我们自己的客户端插件在镜像里也在跑**，它按同源取 `/mini-remote/*`
+      // ——那几条是**宿主那边的**路由（`lib/index.js` 注册的），不是我们的。
+      //
+      // 可这些路径以 `/mini` 开头，会被下面那条「凡不是我们自己的地盘就转上游」判成
+      // **我们的地盘**，于是回我们自己的 404 JSON：镜像里的「手机遥控」那一节就永远读不到
+      // 配对/隧道/飞书的状态。2026-10-08 在活服务上量到：同一条路径在宿主那边是 200
+      // （7360 字节 JSON），在我们这边是 `{"error":"not found"}`。
+      //
+      // 所以把它一并转上游。**它挂在开关里面**——开关关着时一个都不接，和别的路径同一条口径。
+      const miniRemote = path === '/mini-remote' || path.startsWith('/mini-remote/')
+      const toUpstream = mirrorEntry || mirrorUnder || miniRemote
+        || (!ours && !path.startsWith('/mini'))
+      if (toUpstream) {
+        if (!isAuthorized(req, url)) {
+          if (hasCredential(req, url)) noteFailure(req)
+          sendJson(res, 401, { error: '未授权：token 不正确' })
+          return
+        }
+        noteSuccess(req)
+
+        if (mirrorEntry) {
+          // **入口这一下要把 cookie 写上**，和首页那一条同款。
+          //
+          // 为什么非要这样：那个界面进去之后，它自己会发一堆 `/api/...`、
+          // `/plugins/...` 的请求——**那些请求不会带 `?token=`**，只能靠 cookie 认。
+          // 入口这一刻是唯一一次「用户带着 token 主动进来」的机会，错过它，
+          // 界面能打开但里面每一格都是 401。
+          const provided = url.searchParams.get('token')
+          if (provided && tokenEquals(provided, token)) {
+            res.setHeader('Set-Cookie',
+              `${COOKIE}=${encodeURIComponent(token)}; Path=/; Max-Age=31536000; SameSite=Lax`)
+          }
+          if (path === MIRROR_PREFIX) {
+            // 补上尾斜杠。**这一步不是洁癖**：外壳写着 `<base href="./">`，
+            // 在 `/mini/mirror` 上它解析成 `/mini/`，在 `/mini/mirror/` 上才是
+            // `/mini/mirror/`——差这一个字符，里面的脚本会全 404、界面白屏。
+            // 补完就带上 cookie 了，所以这里不再带查询串——
+            // **只有诊断开关要带过去**：用户拿到的那条链接可能没写尾斜杠，
+            // 跳一下就把「诊断模式」丢了的话，真机上跑一次就白跑了。
+            res.writeHead(302, {
+              location: diag ? `${MIRROR_PREFIX}/?diag=1` : `${MIRROR_PREFIX}/`,
+              'cache-control': 'no-store',
+            })
+            res.end()
+            return
+          }
+          // 带斜杠的入口：就是上游的首页，**查询串整个丢掉**（里面只有我们的令牌，
+          // 上游不认识它，留着反而会被它的精确路由判成不匹配）。
+          const saved = req.url
+          req.url = '/'
+          try {
+            await mirror.handle(req, res, { diag })
+          } finally {
+            req.url = saved
+          }
+          return
+        }
+
+        // 剥掉挂载前缀：`/mini/mirror/assets/x` → 上游的 `/assets/x`。
+        // **只有这一种要改路径。** 绝对路径（`/api/...`、`/plugins/...`）原样转发——
+        // 第一版这里写成了「不是前缀就映射到 `/`」，等于把每个 API 调用都打到首页上，
+        // 是测试当场抓住的。
+        const saved = req.url
+        req.url = stripDiagFlag(stripOurToken(mirrorUnder ? req.url.slice(MIRROR_PREFIX.length) : req.url))
+        try {
+          await mirror.handle(req, res)
+        } finally {
+          req.url = saved
+        }
+        return
+      }
+    }
+
     // ---- 其余一律要鉴权 -------------------------------------------------
     if (!path.startsWith('/mini/api/')) {
+      // **镜像那几条路径走不通时，不许回那个给程序看的 JSON。**
+      //
+      // 上面那一整块镜像路由挂在开关上（`mirrorEnabled()` 同时看「开关」和「上游地址
+      // 解没解析出来」），所以「开关关着」和「电脑端还没就绪」这两种时候，`/mini/mirror/…`
+      // 会掉到这里。原来回的是 `{"error":"not found"}`——而手机那边是把镜像**嵌在 iframe 里**的，
+      // 这个 JSON 就成了框里的**文档**，被浏览器当页面渲染（2026-10-08 用户真机截图：
+      // 框里一条 `{"error":"not found"}`、外面那条「电脑端界面 / 返回」还好好地在）。
+      // 这里改回一页人话；**状态码仍然是 404**（此刻这条路确实不存在），换的只是正文。
+      if (path === '/mini/mirror' || path.startsWith('/mini/mirror/')) {
+        sendMirrorUnavailable(res)
+        return
+      }
       sendJson(res, 404, { error: 'not found' })
       return
     }
@@ -1062,6 +1357,48 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // ---- 镜像页「诊断模式」的上报口 ---------------------------------------
+    //
+    // 只有 `?diag=1` 打开的那一页会往这里发东西（见 lib/mirror.js 的 DIAG_SCRIPT）。
+    // **样本追加写到 scratch/diag.log**，一行一条、带时间戳——用户不用看，
+    // 开发者读它就能把「首帧没字」的根因定死（点击前/点击后两份样本一比，
+    // 到底哪个属性变了就露出来了）。
+    //
+    // 它不是「诊断模式」本身，只是一个**只写不读**的收件口，所以：
+    //   · 走和其他 `/mini/api/*` 同一道门（没令牌进不来）；
+    //   · 不跟着镜像开关关——开关关着时根本没有哪一页会发东西过来，跟着关没意义；
+    //   · 写失败就**如实回错误**（前端那条小条会把原话显示出来），
+    //     免得「真机跑一次、日志里什么都没有」这种事还要再猜一轮。
+    if (req.method === 'POST' && path === '/mini/api/mirror-diag') {
+      try {
+        const payload = await readBody(req)
+        const file = diagLogPath()
+        await mkdir(dirname(file), { recursive: true })
+        await appendFile(file, `\n=== ${new Date().toISOString()} ===\n${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+        sendJson(res, 200, { ok: true })
+      } catch (err) {
+        sendJson(res, 500, { ok: false, error: String((err && err.message) || err) })
+      }
+      return
+    }
+
+    // ---- 「进阶设置（电脑端界面）」的开关 ---------------------------------
+    // 只是那个开关的状态与读写；**真正的代理在 handle() 上面那一段**。
+    // 两件事分开是有意的：状态随时可查（界面进来就要知道该画成什么样），
+    // 而那条代理路由**关着时根本不存在**。
+    if (req.method === 'GET' && path === '/mini/api/mirror') {
+      const result = await nav.mirrorSetting()
+      sendJson(res, result.ok ? 200 : 503, result)
+      return
+    }
+
+    if (req.method === 'POST' && path === '/mini/api/mirror') {
+      const body = await readBody(req)
+      const result = await nav.setMirror(body?.enabled)
+      sendJson(res, result.ok ? 200 : 400, result)
+      return
+    }
+
     // ---- 斜杠指令列表 ----------------------------------------------------
     // 手机在输入框里打 `/` 时要显示的那一份。**名单来自 DSH 自己的指令账本**，
     // 所以电脑上新装一个带指令的插件，手机上刷新就有了，不用改这个插件。
@@ -1618,6 +1955,41 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     let port = startPort
     for (const address of wanted) {
       const server = createServer(onRequest)
+      // WebSocket 不走 onRequest——它是一条 `Upgrade` 握手，Node 单独发这个事件。
+      //
+      // **手机和宿主之间那条常驻连接就是 WebSocket**（`/api/remote.mux`）。少了这一段，
+      // 镜像里的界面会「一直正在重新连接」，插件那一列只剩图标没有文字、权限那栏写
+      // 「permission catalog has no active Host connection」——**看起来像一堆显示毛病，
+      // 其实全是同一条连接没通**（2026-10-06 真机报上来的）。
+      //
+      // 路由口径和 HTTP 那边保持一致：**我们自己的地盘（`/mini/...`）不转**，
+      // 开关关着就一个都不接（不给一个绕过开关的通道）。
+      // 路由口径和 HTTP 那边一致，但有一处不能照抄：官方那条连接是按页面的 base 解析出来的，
+      // 而 base 是 `/mini/mirror/`（外壳写着 base href="./"），所以它实际请求的是
+      // `/mini/mirror/api/remote.mux`——挂在镜像前缀**下面**。照 HTTP 那样「凡是 /mini/ 都拒掉」
+      // 会把它一起拒掉，界面就永远在重连。（第一版就是这么写的，靠测试改成真实路径形态才发现。）
+      const MIRROR_PREFIX = '/mini/mirror'
+      server.on('upgrade', (req, socket, head) => {
+        if (!mirror || typeof mirror.upgrade !== 'function'
+          || typeof mirrorEnabled !== 'function' || !mirrorEnabled()) {
+          socket.destroy()
+          return
+        }
+        const upPath = String(req.url ?? '/').split('?')[0]
+        const under = upPath === MIRROR_PREFIX || upPath.startsWith(`${MIRROR_PREFIX}/`)
+        const ours = !under
+          && (upPath === '/mini' || upPath === '/mini/' || upPath.startsWith('/mini/'))
+        if (ours) {
+          socket.destroy()
+          return
+        }
+        // 挂在挂载点下面的剥掉前缀，绝对路径（`/api/...`）原样转——和 HTTP 那边一致。
+        // `diag=1` 同样要摘掉（和 HTTP 那边同一个道理：上游不认它）。
+        req.url = stripDiagFlag(under
+          ? stripOurToken(req.url.slice(MIRROR_PREFIX.length) || '/')
+          : stripOurToken(req.url))
+        mirror.upgrade(req, socket, head)
+      })
       try {
         await new Promise((resolve, reject) => {
           server.once('error', reject)

package/lib/store.js

@@ -27,6 +27,18 @@ export function createStore({ file, maxHistory = 50, maxSessions = 12 }) {
     historyBySession: {}, // sessionId -> [{ role, text, timestamp, sessionId }]
     /** 手机当前遥控的那个会话。 */
     boundSessionId: null,
+    /**
+     * 「进阶设置（电脑端界面）」的开关。**默认关**。
+     *
+     * 为什么默认关：打开它 = 把这个令牌的权限**从「我们那张手机页暴露的那点事」
+     * 扩到整个电脑端设置面**（模型配置、凭据页、插件装卸、会话记录……）。
+     * 那是能力的大幅扩张，不该在用户不知情的时候发生——所以要他自己开，
+     * 而且界面上会把后果写清楚。
+     *
+     * 关着的时候那条代理路由**根本不存在**（见 server.js 里的判断），
+     * 不是「前端藏起来、后端还开着」。
+     */
+    mirrorEnabled: false,
     /** 手机会话在线状态，用于决定要不要发外部推送。 */
     presence: 'foreground',
     lastSeen: 0,
@@ -353,6 +365,9 @@ export function createStore({ file, maxHistory = 50, maxSessions = 12 }) {
           }
         }
         if (raw.boundSessionId) state.boundSessionId = raw.boundSessionId
+        // 进阶模式：**只有明确是 true 才算开**。缺失、损坏、写成别的值一律当关——
+        // 这个开关关系到权限大小，读不出来时必须往「关」那边倒。
+        if (raw.mirrorEnabled === true) state.mirrorEnabled = true
       }
     } catch {
       // 首次运行没有文件，或文件损坏——都不该让插件起不来。
@@ -372,6 +387,7 @@ export function createStore({ file, maxHistory = 50, maxSessions = 12 }) {
           latestBySession: state.latestBySession,
           historyBySession: state.historyBySession,
           boundSessionId: state.boundSessionId,
+          mirrorEnabled: state.mirrorEnabled,
         }))
         renameSync(tmp, file)
       } catch {
@@ -407,6 +423,31 @@ export function createStore({ file, maxHistory = 50, maxSessions = 12 }) {
       s.running = running
     },
 
+    /**
+     * 开/关「进阶设置（电脑端界面）」。**立即落盘**，不等那 500 毫秒的合并写。
+     *
+     * 为什么破例：这是个权限开关。用户开了之后马上就会去点那个入口，
+     * 万一这中间进程没了，重启后应当还是他最后选的那个状态——
+     * 合并写那 500 毫秒的窗口在这里不值得省。
+     */
+    setMirrorEnabled(enabled) {
+      state.mirrorEnabled = enabled === true
+      try {
+        mkdirSync(dirname(file), { recursive: true })
+        const tmp = `${file}.tmp`
+        writeFileSync(tmp, JSON.stringify({
+          latestBySession: state.latestBySession,
+          historyBySession: state.historyBySession,
+          boundSessionId: state.boundSessionId,
+          mirrorEnabled: state.mirrorEnabled,
+        }))
+        renameSync(tmp, file)
+      } catch {
+        // 落盘失败不影响本次运行——内存里那个值照常生效。
+      }
+      return state.mirrorEnabled
+    },
+
     setSubagentRunning(parentSessionId, childSessionId, running) {
       if (!parentSessionId || !childSessionId) return
       const group = state.subagentRunningBySession[parentSessionId]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mini-remote",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "DSH 极简移动端遥控器：只把「你的指令」和「AI 的最终回复」送到手机，屏蔽全部中间过程。",
   "type": "module",
   "main": "lib/index.js",
@@ -24,7 +24,7 @@
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.5-rc.2"
+    "dsh": ">=0.1.5-rc.2 <0.3.0"
   },
   "author": "xingzhen199186",
   "repository": {