dsh-mini-remote 0.1.8 → 0.2.0

package/lib/server.js

@@ -12,11 +12,30 @@
  *   - 只需要服务端→手机单向推送；手机发指令用普通 POST 即可
  */
 import { createServer } from 'node:http'
-import { timingSafeEqual } from 'node:crypto'
+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
@@ -170,17 +280,73 @@ export const miniControl = {
  * @param {(id:string)=>{ok:boolean, error?:string, sessionId?:string}} opts.onUnqueue
  * @param {() => (string|undefined)[]} [opts.imageRoots] 正文里相对路径图的额外候选根
  *        （由插件递进「当前已注册工作区的目录」，见 extraImageRoots 那段）
- * @returns {Promise<{port:number, addresses:string[], failed:{address:string,message:string}[], close:()=>Promise<void>, broadcast:(event:string, data:unknown)=>void}>}
+ * @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()
 
+  /**
+   * 这条连接到底是谁——**订阅要按连接记，就得先有身份**。
+   *
+   * SSE 那边只有一个 `res`，一次普通的 POST 认不出「我是哪条流」。所以由客户端自己
+   * 生成一个随机串，两处都带上：连流时 `?clientId=…`，之后每一次开关订阅也带它。
+   * 客户端没报的（比如现在这版手机页面）服务端也给它编一个，只为日志里能对上号——
+   * 那种连接**订不了轨迹**，也就不会为这份体积付钱。
+   */
+  const clientsById = new Map()
+  /**
+   * 想要执行轨迹推送的那几条连接。
+   *
+   * 为什么必须按连接分流：轨迹的体积是回答正文的 **90.7 倍**（单轮最高约 946KB，
+   * 单条输出最大 49,930 字符），而现在的 `state` 是「每条广播都发整份快照」。
+   * 把它塞进那条路会把手机压垮，所以它走单独的增量帧，并且**只有声明要「完整」模式的
+   * 那几台**才推。声明有两条路：
+   *   ① 连上来时带 `?full=1`——断线重连之后自动重新对齐，不用先握手一次；
+   *   ② 连上之后 `POST /mini/api/trajectory/subscribe`——切模式时用，不必重连。
+   */
+  const trajectorySubscribers = new Set()
+  let clientSeq = 0
+
+  /**
+   * 「这一代服务」的编号。进程重启、服务重起都会换一个。
+   *
+   * 客户端拿它认出「对面换人了」：那种时候帧序号会从头开始，手里的轨迹该整个重拉一次。
+   * 光看 seq 是不够的——重启后 seq 也是从 1 开始，看着就像什么都没发生。
+   */
+  const EPOCH = randomBytes(4).toString('hex')
+
   // 导航栏的数据比普通状态更适合做 stale-while-revalidate：工作区和会话不会因为
   // 用户打开一次菜单就必须重新清点。第一次没有缓存时仍然等待真实结果；之后先回上次
   // 整理好的列表，再在后台刷新。手动点刷新时由请求方显式 force，保持原来的语义。
   const NAV_CACHE_TTL_MS = 30_000
   let navWorkspaceCache = { value: null, at: 0, inflight: null }
+  const SUBAGENT_CACHE_TTL_MS = 5_000
+  const subagentCaches = new Map()
+  function invalidateNavigation() {
+    navWorkspaceCache = { value: null, at: 0, inflight: null }
+  }
+
+  function invalidateSubagents(sessionId) {
+    if (sessionId) subagentCaches.delete(sessionId)
+    else subagentCaches.clear()
+  }
+
+  async function loadSubagents(sessionId) {
+    if (!sessionId) return nav.subagents(sessionId)
+    const hit = subagentCaches.get(sessionId)
+    if (hit && Date.now() - hit.at < SUBAGENT_CACHE_TTL_MS) return hit.value
+    if (hit?.inflight) return hit.inflight
+    const inflight = Promise.resolve(nav.subagents(sessionId, { includeMetrics: false, scheduleMetrics: true })).then((value) => {
+      subagentCaches.set(sessionId, { value, at: Date.now(), inflight: null })
+      return value
+    }).finally(() => {
+      const current = subagentCaches.get(sessionId)
+      if (current?.inflight === inflight) current.inflight = null
+    })
+    subagentCaches.set(sessionId, { value: hit?.value ?? null, at: hit?.at ?? 0, inflight })
+    return hit?.value ?? inflight
+  }
 
   async function loadWorkspaces(runningIds, force = false) {
     const now = Date.now()
@@ -280,6 +446,58 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     }
   }
 
+  /**
+   * 只发给「要轨迹」的那几台连接。**别人一个字节都不收**。
+   *
+   * 帧里只有这一批的变化（新条目 + 改动），不是整份：整份单轮最高约 946KB，而
+   * 一次工具调用也就是一条几 KB 的条目。`seq` 让客户端认出漏帧，`epoch` 认出重启。
+   */
+  function broadcastTrajectory(payload) {
+    if (!trajectorySubscribers.size) return
+    const frame = `event: trajectory\ndata: ${JSON.stringify({ epoch: EPOCH, ...payload })}\n\n`
+    for (const res of trajectorySubscribers) {
+      try {
+        res.write(frame)
+      } catch {
+        trajectorySubscribers.delete(res)
+        clients.delete(res)
+      }
+    }
+  }
+
+  /**
+   * 轨迹的活片段（2026-10-04 用户解禁「流式不做」，只给完整模式看）：模型正在想的
+   * 那一句，随打字顺出来。和上面那条增量帧走**同一批连接**（就是完整模式那几条），
+   * 但**不占它的 seq/epoch**——它是「还没落定」的影子，落定的字由增量帧接管。
+   */
+  function broadcastTrajectoryLive(payload) {
+    if (!trajectorySubscribers.size) return
+    const frame = `event: trajectory-live\ndata: ${JSON.stringify(payload)}\n\n`
+    for (const res of trajectorySubscribers) {
+      try {
+        res.write(frame)
+      } catch {
+        trajectorySubscribers.delete(res)
+        clients.delete(res)
+      }
+    }
+  }
+
+  /**
+   * 按身份名开/关轨迹推送。
+   * @returns 点到的连接数。**0 = 那条连接已经不在了**，客户端据此重连一次
+   *          （不然会出现「以为订上了，其实一条都收不到」这种最难查的静默状态）。
+   */
+  function setTrajectorySubscription(clientId, on) {
+    const group = clientsById.get(clientId)
+    if (!group) return 0
+    for (const res of group) {
+      if (on) trajectorySubscribers.add(res)
+      else trajectorySubscribers.delete(res)
+    }
+    return group.size
+  }
+
   // ---- 手机上答题 ------------------------------------------------------
   //
   // **这两样必须放在这一层**（和 `clients`、`broadcast` 同一层，全程只建一次）。
@@ -590,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
@@ -714,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
     }
@@ -737,6 +1140,15 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       })
       res.write(': connected\n\n')
       clients.add(res)
+      // 这条连接的身份 + 它要不要轨迹。身份是客户端自己报的随机串（见 clientsById），
+      // 没报就编一个：编出来的那种订不了轨迹，也就不用替这份体积付钱。
+      const askedClientId = String(url.searchParams.get('clientId') ?? '').slice(0, 64)
+      const clientId = askedClientId || `anon${++clientSeq}`
+      let sameId = clientsById.get(clientId)
+      if (!sameId) clientsById.set(clientId, (sameId = new Set()))
+      sameId.add(res)
+      // `?full=1` = 「我这一端是完整模式」：连上就订上，重连之后自动重新对齐。
+      if (url.searchParams.get('full') === '1') trajectorySubscribers.add(res)
       // 留痕：手机连没连上、一共有几台，就看这一句。2026-09-27 测自言自语的这天
       // 正是卡在这儿——「她怎么没说话」和「手机压根没连上」当时根本分不开。
       // 还要看**是谁**连的、**活了多久**：2026-09-27 日志里一分钟几十次成对出现，
@@ -773,6 +1185,12 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         said = true
         clearInterval(beat)
         clients.delete(res)
+        trajectorySubscribers.delete(res)
+        const group = clientsById.get(clientId)
+        if (group) {
+          group.delete(res)
+          if (!group.size) clientsById.delete(clientId)
+        }
         console.log(`[dsh-mini-remote] 手机断开了，还剩 ${clients.size} 台`
           + `（${who}，活了 ${Date.now() - openedAt} ms）`)
       }
@@ -789,6 +1207,58 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    /**
+     * 执行轨迹：手机「完整」模式要的那一组一组过程。
+     *
+     * **它不在 `state` 快照里**，这是这次改动最要紧的一条：实测轨迹正文是回答正文的
+     * 90.7 倍（单轮最高约 946KB），而快照是**每条广播都发整份**的——塞进去等于把
+     * 每一次工具调用都变成一次几百 KB 的推送（公网隧道下尤其不可接受）。
+     * 所以全量快照照旧，轨迹走增量帧（`event: trajectory`），这份接口只负责
+     * 「重连 / 切到完整模式 / 换个会话时，一次把当前这一段补齐」。
+     *
+     * `turn=N` 只给那一轮：手机切回来时想对齐的是**当前正在跑的那一轮**，不必把
+     * 前面一百多条条目再拖一遍。
+     *
+     * 和 /state 同一条口径：没读过这个会话的记录就先读一次（`onSessionOpened`），
+     * 读完会广播 state；手机据此再拉一次，那时 `loading` 就不是 true 了。
+     */
+    if (req.method === 'GET' && path === '/mini/api/trajectory') {
+      const asked = url.searchParams.get('sessionId')
+      const sessionId = asked || store.targetSessionId()
+      if (!sessionId) {
+        sendJson(res, 200, {
+          ok: true, sessionId: null, epoch: EPOCH, seq: 0, turn: null,
+          turns: [], truncated: false, note: null, loading: false,
+        })
+        return
+      }
+      let onlyTurn = null
+      if (url.searchParams.has('turn')) {
+        onlyTurn = Number(url.searchParams.get('turn'))
+        if (!Number.isFinite(onlyTurn)) {
+          sendJson(res, 400, { ok: false, error: 'turn 要是一个数字。' })
+          return
+        }
+      }
+      onSessionOpened?.(sessionId)
+      const view = store.trajectoryOf(sessionId)
+      const turns = onlyTurn === null
+        ? view.turns
+        : view.turns.filter((g) => g.turn === onlyTurn)
+      sendJson(res, 200, {
+        ok: true,
+        sessionId,
+        epoch: EPOCH,
+        seq: view.seq,
+        turn: onlyTurn,
+        turns,
+        truncated: view.truncated,
+        note: view.note ?? null,
+        loading: view.loading === true,
+      })
+      return
+    }
+
     // 构建指纹。重启期间旧进程还在应答，这个接口用来确认「跑的是不是新代码」。
     //
     // `canCreateSession` 是**运行时**事实，不是配置推断：它问的是「这一刻 DSH 真的
@@ -803,7 +1273,38 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         // 探测本身不该把接口带崩：问不到就当没有。
         canCreateSession = false
       }
-      sendJson(res, 200, { ok: true, build: build ?? 'unknown', canCreateSession })
+      // 版本号问**正在跑的这只 Host**（见 index.js 的 dshVersion）。
+      // 早先这里是读磁盘上的 package.json，桌面端读不到，一直报 unknown。
+      const version = (await nav.dshVersion?.()) || 'unknown'
+      sendJson(res, 200, { ok: true, build: build ?? 'unknown', dshVersion: version, canCreateSession })
+      return
+    }
+
+    // 插件列表：手机端「插件」页面用。分三块——
+    //   bundles  ：npm 包（官方可装的 + 用户装的第三方）
+    //   cards    ：官方那几张**设置卡片**（终端 / Agent 循环 / 子智能体 / 网页搜索）。
+    //             它们不是包，是注册了设置页的官方插件，宿主这边只能照 DSH 客户端
+    //              源码列一张表 + 按「宿主 served 了那个命名空间没」筛选。
+    //   entries/presets：**内置插件**（Cordis Loader 的实时条目表），也就是
+    //             「全局插件」和「会话插件」两块。2026-10-04 用户指出：内置插件
+    //             不能拿 npm 包充数（那只有几个），DSH 是「一切皆插件，无特权核心」。
+    // 三块各带各的错：一块读不到不该把另两块也弄没。
+    if (req.method === 'GET' && path === '/mini/api/plugins') {
+      const [list, inv, official] = await Promise.all([
+        nav.pluginList?.() ?? { ok: false, reason: 'unavailable' },
+        nav.pluginInventory?.() ?? { ok: false, reason: 'unavailable' },
+        nav.officialPlugins?.() ?? { ok: false, reason: 'unavailable' },
+      ])
+      sendJson(res, 200, {
+        ok: list.ok !== false || inv.ok !== false,
+        bundles: list.bundles ?? [],
+        bundlesError: list.ok === false ? String(list.reason || '读不到') : '',
+        official: official.cards ?? [],
+        officialError: official.ok === false ? String(official.reason || '读不到') : '',
+        entries: inv.entries ?? [],
+        presets: inv.presets ?? [],
+        builtinError: inv.ok === false ? String(inv.reason || '读不到') : '',
+      })
       return
     }
 
@@ -824,7 +1325,7 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     // 失败一律 200 + ok:false：这是"这道能力现在没有"或"这台电脑没开这条路"，
     // 不是请求本身有错——用 4xx 会让页面上的重试逻辑把它当网络故障。
     if (req.method === 'GET' && path === '/mini/api/subagents') {
-      const result = await nav.subagents(store.snapshot().boundSessionId)
+      const result = await loadSubagents(store.snapshot().boundSessionId)
       sendJson(res, 200, result)
       return
     }
@@ -837,6 +1338,67 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // ---- 繁忙时的发送行为 ------------------------------------------------
+    // 智能体跑着的时候，你发的那句话是排队等这一轮跑完（queue），还是当场插进去
+    // 让它调整方向（steer）。**PC 上的「设置 → 通用 → 繁忙时的发送行为」就是它**，
+    // 两端共用宿主那一份用户设置文档（用户 2026-10-05 拍板）。
+    //
+    // 读不到就如实说 unavailable，手机那边整条不显示——**不摆一个假的开关**。
+    if (req.method === 'GET' && path === '/mini/api/busy-enter') {
+      const result = await nav.busyEnterSetting()
+      sendJson(res, result.ok ? 200 : 503, result)
+      return
+    }
+
+    if (req.method === 'POST' && path === '/mini/api/busy-enter') {
+      const body = await readBody(req)
+      const result = await nav.setBusyEnter(body?.value)
+      sendJson(res, result.ok ? 200 : 400, result)
+      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 自己的指令账本**，
     // 所以电脑上新装一个带指令的插件，手机上刷新就有了，不用改这个插件。
@@ -869,6 +1431,13 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // Agent 模式清单（2026-10-04）：手机新建会话时挑模式用。拿不到能力时如实回
+    // unavailable——手机那边会直接建默认模式，**不摆没得选的选择题**。
+    if (path === '/mini/api/agent-presets' && req.method === 'GET') {
+      sendJson(res, 200, await nav.agentPresets?.() ?? { ok: false, reason: 'unavailable' })
+      return
+    }
+
     const wsSessions = /^\/mini\/api\/workspaces\/([^/]+)\/sessions$/.exec(path)
     if (req.method === 'GET' && wsSessions) {
       const asked = Number(url.searchParams.get('limit'))
@@ -1194,6 +1763,26 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         return
       }
 
+      if (path === '/mini/api/trajectory/subscribe') {
+        // 开/关轨迹推送（见 trajectorySubscribers）。**只点到 clientId 名下那条连接**，
+        // 别的连接一个字节都不受影响——单帧/聊天模式的手机不该为这份体积付钱。
+        const clientId = typeof body.clientId === 'string' ? body.clientId.trim() : ''
+        if (!clientId) {
+          sendJson(res, 400, { ok: false, error: 'clientId 不能空——订阅是按连接记的。' })
+          return
+        }
+        const on = body.on !== false
+        const hit = setTrajectorySubscription(clientId, on)
+        if (!hit) {
+          // 认不出这条连接：多半是那条流已经断了（或者连流时没报 clientId）。
+          // **如实说没订上**，别让手机以为订上了却一条都收不到——那是最难查的一种静默失败。
+          sendJson(res, 404, { ok: false, error: '这条连接已经不在了，重新连一次流。' })
+          return
+        }
+        sendJson(res, 200, { ok: true, clientId, subscribed: on, connections: hit, epoch: EPOCH })
+        return
+      }
+
       // 在一个已有的工作区里新建会话，建完立刻把手机绑过去。
       //
       // 为什么排在这么靠后、而不是跟上面那条 GET 挨着：这两条都要读请求体，
@@ -1203,7 +1792,11 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       // 建完顺手 bind + 广播：手机发一次请求就完成了「建 + 切过去」，
       // 不用再补一次 bind，也就不会出现「建好了但没切过去」这种半截状态。
       if (req.method === 'POST' && wsSessions) {
-        const created = await nav.createSession(decodeURIComponent(wsSessions[1]))
+        // agentPreset（2026-10-04，手机上也能选模式）：选了才带，没选让 DSH 用默认。
+        const preset = typeof body.agentPreset === 'string' && body.agentPreset.trim()
+          ? body.agentPreset.trim()
+          : undefined
+        const created = await nav.createSession(decodeURIComponent(wsSessions[1]), preset)
         if (!created.ok) {
           const known = {
             'no-controller': [503, '这台电脑上的 DSH 没提供新建会话的能力。'],
@@ -1216,7 +1809,7 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         }
         store.bind(created.sessionId)
         // 新会话会改变工作区的数量；下次打开导航栏必须重新整理一次。
-        navWorkspaceCache = { value: null, at: 0, inflight: null }
+        invalidateNavigation()
         const snap = store.snapshot()
         broadcast('state', snap)
         sendJson(res, 200, {
@@ -1362,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)
@@ -1412,6 +2040,12 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     /** 想绑但失败的地址，交给调用方决定怎么提示。 */
     failed,
     broadcast,
+    /** 执行轨迹的增量帧：只发给声明了「完整」模式的那几条连接（见 broadcastTrajectory）。 */
+    broadcastTrajectory,
+    /** 轨迹的活片段帧：同一批连接，不占 seq/epoch（见 broadcastTrajectoryLive）。 */
+    broadcastTrajectoryLive,
+    invalidateNavigation,
+    invalidateSubagents,
     close: async () => {
       for (const res of clients) {
         try { res.end() } catch { /* 已经断了 */ }