dsh-mini-remote 0.1.7 → 0.1.9

package/lib/server.js

@@ -12,7 +12,7 @@
  *   - 只需要服务端→手机单向推送；手机发指令用普通 POST 即可
  */
 import { createServer } from 'node:http'
-import { timingSafeEqual } from 'node:crypto'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { renderPage, readArt, readImage, readSw } from './page.js'
 
 const COOKIE = 'dsh_mini_token'
@@ -168,12 +168,101 @@ export const miniControl = {
  * @param {(line:string)=>Promise<{ok:boolean, error?:string}>} [opts.onCommand] 执行一条斜杠指令
  * @param {()=>Promise<{ok:boolean, error?:string, sessionId?:string}>|{ok:boolean, error?:string, sessionId?:string}} opts.onStop
  * @param {(id:string)=>{ok:boolean, error?:string, sessionId?:string}} opts.onUnqueue
- * @returns {Promise<{port:number, addresses:string[], failed:{address:string,message:string}[], close:()=>Promise<void>, broadcast:(event:string, data:unknown)=>void}>}
+ * @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, 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 }) {
+export async function createMiniServer({ store, config, token, bindAddresses, tunnelHost, onInstruction, onCommands, onCommand, onStop, onUnqueue, onUpload, onSessionOpened, log, tree, browse, build, imageRoots }) {
   /** @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()
+    const fresh = navWorkspaceCache.value && now - navWorkspaceCache.at < NAV_CACHE_TTL_MS
+    if (!force && navWorkspaceCache.value) {
+      if (!fresh && !navWorkspaceCache.inflight) {
+        navWorkspaceCache.inflight = refreshWorkspaces(runningIds, false)
+          .finally(() => { navWorkspaceCache.inflight = null })
+      }
+      return navWorkspaceCache.value
+    }
+    if (navWorkspaceCache.inflight) return navWorkspaceCache.inflight
+    navWorkspaceCache.inflight = refreshWorkspaces(runningIds, force)
+      .finally(() => { navWorkspaceCache.inflight = null })
+    return navWorkspaceCache.inflight
+  }
+
+  async function refreshWorkspaces(runningIds, force) {
+    const started = performance.now()
+    const value = await nav.listWorkspaces(runningIds, force, true)
+    navWorkspaceCache = { value, at: Date.now(), inflight: null }
+    const elapsed = Math.round(performance.now() - started)
+    log?.info?.(`导航工作区读取 ${elapsed}ms（${value.length} 个）`)
+    return value
+  }
+
   // 没传 tree（测试里就是这样，headless 组合里也拿不到那两个服务）时给个空壳，
   // 导航栏显示「取不到」，遥控本身照常。
   // `createSession` 的空壳回 `no-controller`，跟真服务缺位时走同一条错误路径——
@@ -188,6 +277,11 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     // 模型那两个的**空壳**：测试里没有真的 DSH，照上面的样式如实说"没这个能力"。
     modelCatalog: async () => ({ ok: false, reason: 'unavailable' }),
     selectModel: async () => ({ ok: false, reason: 'unavailable' }),
+    // 子智能体那四个的空壳，同样如实说"没这个能力"，不假装有一份空列表。
+    subagents: async () => ({ ok: false, error: '这台电脑上的 DSH 没提供子智能体。' }),
+    subagentTranscript: async () => ({ ok: false, error: '这台电脑上的 DSH 没提供子智能体。' }),
+    stopSubagent: async () => ({ ok: false, error: '这台电脑上的 DSH 没提供子智能体。' }),
+    askSubagent: async () => ({ ok: false, error: '这台电脑上的 DSH 没提供子智能体。' }),
   }
 
   // 目录浏览的空壳。它**只依赖 node:fs**，不像 tree 那样依赖 DSH 的服务，
@@ -198,6 +292,39 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     makeDirectory: async () => ({ ok: false, reason: 'unavailable' }),
   }
 
+  /**
+   * 正文里写相对路径的图（`![](scratch/a.png)`）要多试的几个根：**当前已注册的工作区目录**。
+   *
+   * 为什么需要它（2026-09-28 实测确诊）：正文里的相对路径相对的是**那段对话的工作目录**，
+   * 而它可能是别的项目——那次是 `I:\DSH\dsh-jev-ultrafast`，正文写的是
+   * `scratch/preview-0.2.3-settings.png`。插件原先只按自己的两个根（仓库根、lib/art）找，
+   * 于是 404，手机上就是破图；图就在盘上，接口本身也没毛病。
+   *
+   * **只放宽「在哪找」。** 仍然要令牌、仍然只发图片扩展名、仍然卡体积、相对写法里的 `..`
+   * 仍然被拒（后两条在 page.js 的 readImage 里，这一版一个字没动）。
+   * 额外根拿不到（服务还没起来）时退回空列表，也就是原来的行为。
+   *
+   * 缓存 30 秒：列一遍注册表要遍历所有工作区，而这张表几乎不变；晚半分钟知道新建的工作区
+   * 没有影响——图的地址是用户在正文里写的，不会正好卡在那半分钟上。
+   */
+  const IMAGE_ROOTS_TTL_MS = 30_000
+  let imageRootsCache = { at: 0, list: [] }
+  function extraImageRoots() {
+    const now = Date.now()
+    if (now - imageRootsCache.at < IMAGE_ROOTS_TTL_MS) return imageRootsCache.list
+    let list = []
+    try {
+      const got = imageRoots?.()
+      // 去重：工作区里本来就可能包含插件根那个目录，重复只换来几次白跑的系统调用。
+      if (Array.isArray(got)) list = [...new Set(got.filter((r) => typeof r === 'string' && r))]
+    } catch {
+      // `workspaceRegistry.list()` 在服务还没就绪时会抛。少认几张图，不该拖垮整条取图的路。
+      list = []
+    }
+    imageRootsCache = { at: now, list }
+    return list
+  }
+
   function broadcast(event, data) {
     const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
     for (const res of clients) {
@@ -209,6 +336,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` 同一层，全程只建一次）。
@@ -237,27 +416,81 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     return clients.size > 0 || (phoneSeenAt > 0 && Date.now() - phoneSeenAt < PHONE_GRACE_MS)
   }
 
+  /**
+   * 「除了手机，还有别人在等这道题吗」——**收摊判据的第二个来源**。
+   *
+   * 手机全断开就立刻把问题还给电脑（上面那条，防的是永远卡住）；可飞书那条路
+   * （见 lib/lark.js）也能答同一道题，手机上没人不等于没人答。所以由调用方传一个
+   * `keepAlive()` 进来，它说「还挂着」就不收摊。
+   *
+   * **绝不因为这一句把题卡死**：没传、或者它抛了，一律当「没人在等」——宁可还给电脑，
+   * 也不能因为另一条路的内部错误让问题悬在半空。
+   */
+  function stillWaited(opts) {
+    try {
+      return opts?.keepAlive?.() === true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * 一道题/一条审批刚刚有结果了——**主动告诉手机页**。
+   *
+   * 为什么必须有这一条：手机和飞书可能同时看着同一道题（用户就在两个界面之间切）。
+   * 谁先答谁生效的语义本来就有（后到的那边拿到 `expired`），但那只在**后到的人自己动手**
+   * 时才说话。手机页那张卡片是推一次就留在屏幕上的，用户在飞书里答完，手机上那张还挂在
+   * 原地——他没法知道这道题已经有人答了，只能盯着它发愣（2026-10-02 真机就是这个现象）。
+   *
+   * 所以这里用**现成的 SSE 通道**补一条状态：手机页收到就把卡片收起来、换一行说明。
+   * 只说「哪一道、谁答的」，不重复推题目本身——两边都不重复打扰。
+   */
+  function notifySettled(kind, id, source) {
+    broadcast(`${kind}-done`, { id, source: source ?? '' })
+  }
+
+  /**
+   * 题挂上之后当场告诉调用方它的编号。
+   *
+   * **飞书那条路就靠这个号对号入座**（用户回的那句话是对哪一道题的答复），交出去的是
+   * 这一层内部用的编号（`q1`/`a1` 这种），不是界面上的顺序号。回调抛错只写一行日志，
+   * 不影响这道题本身——推不出去的只是「另一个界面也来问」这件事。
+   */
+  function notifyPending(opts, id) {
+    try {
+      opts?.onPending?.(id)
+    } catch (err) {
+      log?.warn?.(`遥控服务：通知另一条通路失败（${err?.message ?? err}）`)
+    }
+  }
+
   /**
    * 把这个提问推到手机上，等它答。
+   * @param {{keepAlive?: () => boolean, onPending?: (id: string) => void}} [opts]
+   *        见上面 stillWaited / notifyPending 两段说明。
    * @returns 答案对象；手机没了就返回 null，调用方据此**把问题还给电脑**。
    */
-  function askPhone(questions, agentId) {
+  function askPhone(questions, agentId, opts) {
     const id = 'q' + (++questionSeq)
     return new Promise((resolve) => {
       let watch = null
-      const settle = (value) => {
+      const settle = (value, from) => {
         if (!waitingQuestions.has(id)) return
         waitingQuestions.delete(id)
         if (watch) clearInterval(watch)
+        // 先通知、再落定：谁先答谁生效的语义一个字没动，这里只是**把结果说出去**，
+        // 让另一侧那张还挂着的卡片自己收起来（见 notifySettled）。
+        notifySettled('question', id, from ?? opts?.source)
         resolve(value)
       }
       // 题目本身也存进来（不只是 settle）：手机中途重连上来时要能补发给它，见 replayQuestions。
       waitingQuestions.set(id, { settle, agentId, questions })
+      notifyPending(opts, id)
       broadcast('question', { id, agentId, questions })
       // 用户选的是「一直等，不还回电脑」——但那不等于「手机都没了还等」。
       // 手机一旦全断开（锁屏、关了页面、网断），立刻收摊还给电脑，否则会永远卡住。
       watch = setInterval(() => {
-        if (!hasPhone()) settle(null)
+        if (!hasPhone() && !stillWaited(opts)) settle(null)
       }, 2000)
     })
   }
@@ -294,16 +527,20 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
 
   /**
    * 把一条命令确认推到手机上，等它拍板。
+   * @param {{keepAlive?: () => boolean, onPending?: (id: string) => void}} [opts]
+   *        和提问同一条：飞书那边也能拍这一板（见 lib/lark.js）。
    * @returns 'allowed-once' 或 'rejected'；手机没了返回 null，调用方据此还给电脑。
    */
-  function askApproval(req, agentId, command) {
+  function askApproval(req, agentId, command, opts) {
     const id = 'a' + (++approvalSeq)
     return new Promise((resolve) => {
       let watch = null
-      const settle = (value) => {
+      const settle = (value, from) => {
         if (!waitingApprovals.has(id)) return
         waitingApprovals.delete(id)
         if (watch) clearInterval(watch)
+        // 和提问那条同一句：通知另一侧那张卡片自己收起来（见 notifySettled）。
+        notifySettled('approval', id, from ?? opts?.source)
         resolve(value)
       }
       // 推给手机的就是这几样：工具名 + 为什么来问我。**不带命令正文**——
@@ -317,10 +554,12 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         command: typeof command === 'string' ? command : '',
       }
       waitingApprovals.set(id, { settle, agentId, view })
+      notifyPending(opts, id)
       broadcast('approval', view)
-      // 和提问同一条判据：**不倒计时，看手机还在不在**。全断开了就立刻收摊还给电脑。
+      // 和提问同一条判据：**不倒计时，看手机还在不在**。全断开了就立刻收摊还给电脑
+      // （飞书那边还挂着就除外，见 stillWaited）。
       watch = setInterval(() => {
-        if (!hasPhone()) settle(null)
+        if (!hasPhone() && !stillWaited(opts)) settle(null)
       }, 2000)
     })
   }
@@ -335,11 +574,62 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       }
     }
   }
+  /**
+   * 把一道题的答案交回去。**这是答题的唯一入口**，两个界面都走它：
+   *   手机页：POST /mini/api/answer
+   *   飞书：  miniControl.answerQuestion（见 lib/lark.js 的 onAnswer）
+   *
+   * 为什么收成一处：手机和飞书可能**同时**看着同一道题（用户就在两个人机界面之间切换），
+   * 「谁先答谁生效、另一个自动失效」不该写成两遍——这里只有一个 settle，第二个来的人
+   * 自然拿到 `expired`。这是现成的语义，不是为飞书新加的一套。
+   *
+   * @param {string} id 题号（waitingQuestions 里的那个）
+   * @param {{answers?: Array, cancel?: boolean}} input `cancel:true` = 不答：
+   *        按 settle(null) 处理，也就是和「手机全断了」**同一条路**——
+   *        调用方据此把问题还给电脑（见 lib/index.js 的 .then(answer => !answer → next())）。
+   * @param {'phone'|'feishu'} [from] 谁答的。**只用来通知另一侧**（见 notifySettled）：
+   *        「已在飞书答过」这句话要有出处，猜不得。
+   * @returns {{ok: boolean, error?: 'expired'|'bad'}}
+   */
+  function answerQuestion(id, input, from) {
+    const entry = waitingQuestions.get(id)
+    if (!entry) return { ok: false, error: 'expired' }
+    if (input?.cancel === true) {
+      entry.settle(null, from)
+      return { ok: true }
+    }
+    if (!Array.isArray(input?.answers)) return { ok: false, error: 'bad' }
+    entry.settle({ answers: input.answers }, from)
+    return { ok: true }
+  }
+
+  /**
+   * 把一条审批的结论交回去。形状、理由和 answerQuestion 一模一样（见上面那段）——
+   * 只是交回去的东西是结论，且**只认那两个值**：一个没见过的结论宁可说 bad，
+   * 也不能让电脑收到一个它看不懂的答复。
+   * @param {'phone'|'feishu'} [from] 谁拍的板。只用来通知另一侧（同 answerQuestion）。
+   */
+  function decideApproval(id, input, from) {
+    const entry = waitingApprovals.get(id)
+    if (!entry) return { ok: false, error: 'expired' }
+    if (input?.cancel === true) {
+      entry.settle(null, from)
+      return { ok: true }
+    }
+    if (input?.decision !== 'allowed-once' && input?.decision !== 'rejected') {
+      return { ok: false, error: 'bad' }
+    }
+    entry.settle(input.decision, from)
+    return { ok: true }
+  }
+
   // 把这两个能力放到插件够得着的固定位置（见文件上方 `miniControl` 的说明）。
   // 放在这里是因为它俩都已定义（函数声明本来也会提升），且不受下面那堆路由逻辑影响。
   miniControl.hasPhone = hasPhone
   miniControl.askPhone = askPhone
   miniControl.askApproval = askApproval
+  miniControl.answerQuestion = answerQuestion
+  miniControl.decideApproval = decideApproval
 
   /**
    * 把 UA 和来源地址压成一句人看的：设备类型 + 地址。
@@ -468,10 +758,11 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       // 取图有两条路，都挂在这个前缀下：
       //   ① /mini/art/<名字>.webp —— 立绘。名字受白名单限制，地址里带构建指纹，可以长缓存。
       //   ② /mini/art/?p=<路径>   —— 正文里直接写了一张图在电脑上的位置（绝对路径，或相对
-      //      项目根）。只发图片类型，地址里没有指纹，所以不让浏览器缓存。
+      //      项目根／lib/art／已注册的工作区目录）。只发图片类型，地址里没有指纹，所以不
+      //      让浏览器缓存。
       const wanted = url.searchParams.get('p')
       if (wanted) {
-        const hit = readImage(wanted)
+        const hit = readImage(wanted, extraImageRoots())
         if (!hit) {
           sendJson(res, 404, { error: 'not found' })
           return
@@ -554,6 +845,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 日志里一分钟几十次成对出现，
@@ -590,6 +890,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）`)
       }
@@ -606,6 +912,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 真的
@@ -620,7 +978,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
     }
 
@@ -636,6 +1025,43 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // ---- 子智能体 ------------------------------------------------------
+    // 列表取**当前绑定会话**名下那一份（和 send / stop 同一套口径）。
+    // 失败一律 200 + ok:false：这是"这道能力现在没有"或"这台电脑没开这条路"，
+    // 不是请求本身有错——用 4xx 会让页面上的重试逻辑把它当网络故障。
+    if (req.method === 'GET' && path === '/mini/api/subagents') {
+      const result = await loadSubagents(store.snapshot().boundSessionId)
+      sendJson(res, 200, result)
+      return
+    }
+
+    // 某一道子智能体**自己的运行过程**（它自己的会话记录重放出来的聊天记录）。
+    if (req.method === 'GET' && path === '/mini/api/subagent') {
+      const childId = url.searchParams.get('id') ?? ''
+      const result = await nav.subagentTranscript(childId, store.snapshot().boundSessionId)
+      sendJson(res, 200, result)
+      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
+    }
+
     // ---- 斜杠指令列表 ----------------------------------------------------
     // 手机在输入框里打 `/` 时要显示的那一份。**名单来自 DSH 自己的指令账本**，
     // 所以电脑上新装一个带指令的插件，手机上刷新就有了，不用改这个插件。
@@ -661,22 +1087,33 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       )
       // includeEmpty：手机能自己新建工作区了，刚建好的那个本来就是空的。
       // 不列出来的话，建完它当场消失，用户只会以为没建成。
-      const workspaces = await nav.listWorkspaces(
-        runningIds, url.searchParams.get('refresh') === '1', true,
+      const workspaces = await loadWorkspaces(
+        runningIds, url.searchParams.get('refresh') === '1',
       )
       sendJson(res, 200, { ok: true, workspaces })
       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'))
       const limit = Number.isFinite(asked) && asked > 0 ? Math.min(asked, 100) : undefined
+      const workspaceId = decodeURIComponent(wsSessions[1])
+      const started = performance.now()
       const result = await nav.listSessionsOf(
-        decodeURIComponent(wsSessions[1]),
+        workspaceId,
         limit,
         url.searchParams.get('refresh') === '1',
+        (title) => broadcast('navigation-title', title),
       )
+      log?.info?.(`导航会话读取 ${Math.round(performance.now() - started)}ms（工作区 ${workspaceId}）`)
       if (!result) {
         sendJson(res, 404, { ok: false, error: '没有这个工作区。' })
         return
@@ -787,8 +1224,9 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
 
     if (req.method === 'POST' && path === '/mini/api/answer') {
       const body = await readBody(req)
-      const waiting = waitingQuestions.get(body?.id)
-      if (!waiting) {
+      // 判据、错误文案都收在 answerQuestion 里——和飞书那条路共用同一处（见上面那段说明）。
+      const out = answerQuestion(body?.id, body, 'phone')
+      if (!out.ok && out.error === 'expired') {
         // 409 而不是 200：多半是这个提问早就结束了，如实说，别装作收下了。
         // 落一句痕：这是「手机答了、电脑没动静」唯一能查到的线索——手机那边原来
         // 把失败咽掉了，插件这边再不留痕，下次还是只能靠猜（2026-09-27）。
@@ -796,12 +1234,10 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         sendJson(res, 409, { ok: false, error: '这个提问已经结束了。' })
         return
       }
-      const answers = Array.isArray(body?.answers) ? body.answers : null
-      if (!answers) {
+      if (!out.ok) {
         sendJson(res, 400, { ok: false, error: '答案格式不对。' })
         return
       }
-      waiting.settle({ answers })
       sendJson(res, 200, { ok: true })
       return
     }
@@ -811,20 +1247,20 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     // 过期了如实说、格式不对就说格式不对，别装作收下了。
     if (req.method === 'POST' && path === '/mini/api/approval') {
       const body = await readBody(req)
-      const waiting = waitingApprovals.get(body?.id)
-      if (!waiting) {
+      // 手机页交上来的说法是 allow / deny，换成清单里的结论值；飞书那边直接交结论。
+      const decision = body?.decision === 'allow'
+        ? 'allowed-once'
+        : (body?.decision === 'deny' ? 'rejected' : body?.decision)
+      const out = decideApproval(body?.id, { ...body, decision }, 'phone')
+      if (!out.ok && out.error === 'expired') {
         console.log('[dsh-mini-remote] 手机上拍晚了：这条审批已经交回电脑（' + String(body?.id) + '），没接')
         sendJson(res, 409, { ok: false, error: '这条审批已经结束了。' })
         return
       }
-      const decision = body?.decision === 'allow'
-        ? 'allowed-once'
-        : (body?.decision === 'deny' ? 'rejected' : null)
-      if (!decision) {
+      if (!out.ok) {
         sendJson(res, 400, { ok: false, error: '审批的结论只有同意或拒绝两种。' })
         return
       }
-      waiting.settle(decision)
       sendJson(res, 200, { ok: true })
       return
     }
@@ -953,6 +1389,30 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         return
       }
 
+      if (path === '/mini/api/subagent/stop') {
+        // 停一道子智能体**当前这一轮**。父会话 id 由服务端自己取，不信请求体里的——
+        // 权限凭据是「谁的父会话」，让手机随便填就等于谁都能停别人的。
+        const childId = typeof body.id === 'string' ? body.id : ''
+        const mode = typeof body.mode === 'string' ? body.mode : ''
+        const result = await nav.stopSubagent(childId, store.snapshot().boundSessionId, mode)
+        sendJson(res, result.ok ? 200 : 409, result)
+        return
+      }
+
+      if (path === '/mini/api/subagent/ask') {
+        // 跟一道子智能体接着说一句话。同样，父会话 id 服务端自己取。
+        const childId = typeof body.id === 'string' ? body.id : ''
+        const mode = typeof body.mode === 'string' ? body.mode : ''
+        const text = typeof body.text === 'string' ? body.text.trim() : ''
+        if (!text) {
+          sendJson(res, 400, { ok: false, error: '话是空的。' })
+          return
+        }
+        const result = await nav.askSubagent(childId, store.snapshot().boundSessionId, mode, text)
+        sendJson(res, result.ok ? 200 : 409, result)
+        return
+      }
+
       if (path === '/mini/api/unqueue') {
         // 撤掉一条还在排队的指令。撤的是「手机正在遥控的那个会话」队列里的那一条，
         // 和 send / stop 同一套口径。
@@ -966,6 +1426,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 挨着：这两条都要读请求体，
@@ -975,7 +1455,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 没提供新建会话的能力。'],
@@ -987,6 +1471,8 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
           return
         }
         store.bind(created.sessionId)
+        // 新会话会改变工作区的数量；下次打开导航栏必须重新整理一次。
+        invalidateNavigation()
         const snap = store.snapshot()
         broadcast('state', snap)
         sendJson(res, 200, {
@@ -1042,7 +1528,7 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         }
         // 登记完立刻把最新的工作区列表带回去：手机拿到就能直接画出来，
         // 不用再补一趟请求，也就不会出现「建好了但列表里还没有」。
-        const workspaces = await nav.listWorkspaces(new Set(), true, true)
+        const workspaces = await loadWorkspaces(new Set(), true)
         sendJson(res, 200, {
           ok: true, created: made.created, workspace: made.workspace, workspaces,
         })
@@ -1182,6 +1668,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 { /* 已经断了 */ }