dsh-mini-remote 0.1.0 → 0.1.4

package/lib/server.js

@@ -13,7 +13,7 @@
  */
 import { createServer } from 'node:http'
 import { timingSafeEqual } from 'node:crypto'
-import { renderPage, readArt } from './page.js'
+import { renderPage, readArt, readSw } from './page.js'
 
 const COOKIE = 'dsh_mini_token'
 
@@ -143,19 +143,60 @@ export function sendJson(res, status, payload) {
  * @param {{port:number, defaultMode:string}} opts.config
  * @param {string[]} opts.bindAddresses 要监听的地址；第一个应是 127.0.0.1
  * @param {string} opts.token
+ */
+// ---------------------------------------------------------------------------
+// 插件主体取用「推提问给手机」「手机还在不在」这两个能力的地方。
+//
+// **为什么不靠 createMiniServer 的回执**：实测那句 `mini.server = createMiniServer(…)`
+// 拿到的凭据兑现出来是 `undefined`（仪表原样打出来的），而这两个能力确实写在了函数
+// 末尾的返回对象里。回执为什么是空的还没查清，但插件真正需要的只是这两个功能能用——
+// 所以改成服务启动时**主动把能力放到这个固定位置**，插件直接来取，不经过回执那一道。
+// 这样无论回执是空的还是满的，功能都不受影响。
+//
+// 做成模块级单例：一个进程里只会起一个遥控服务（测试里会起多个，后起的覆盖先起的；
+// 有一条用例会临时替换这两个字段来验提问钩子，用完就还回去）。
+export const miniControl = {
+  askPhone: null,
+  hasPhone: null,
+}
+
+/**
+ * @param {object} opts
  * @param {() => string | null} [opts.tunnelHost] 当前公网域名（没开隧道时返回 null），只用于限速分桶
  * @param {(text:string)=>Promise<{ok:boolean, error?:string, sessionId?:string}>} opts.onInstruction
+ * @param {()=>({ok:boolean, error?:string, commands?:object[]})} [opts.onCommands] 列这台电脑上这个会话能用的斜杠指令
+ * @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}>}
  */
-export async function createMiniServer({ store, config, token, bindAddresses, tunnelHost, onInstruction, onStop, onUnqueue, onUpload, log, tree, build }) {
+export async function createMiniServer({ store, config, token, bindAddresses, tunnelHost, onInstruction, onCommands, onCommand, onStop, onUnqueue, onUpload, onSessionOpened, log, tree, browse, build }) {
   /** @type {Set<import('node:http').ServerResponse>} */
   const clients = new Set()
 
   // 没传 tree（测试里就是这样，headless 组合里也拿不到那两个服务）时给个空壳，
   // 导航栏显示「取不到」，遥控本身照常。
-  const nav = tree ?? { listWorkspaces: async () => [], listSessionsOf: async () => null }
+  // `createSession` 的空壳回 `no-controller`，跟真服务缺位时走同一条错误路径——
+  // 这样「没这个能力」只有一种说法，不用分两处处理。
+  const nav = tree ?? {
+    listWorkspaces: async () => [],
+    listSessionsOf: async () => null,
+    createSession: async () => ({ ok: false, reason: 'no-controller' }),
+    createWorkspace: async () => ({ ok: false, reason: 'no-registry' }),
+    permissions: async () => ({ ok: false, reason: 'no-service' }),
+    setPermission: async () => ({ ok: false, reason: 'no-service' }),
+    // 模型那两个的**空壳**：测试里没有真的 DSH，照上面的样式如实说"没这个能力"。
+    modelCatalog: async () => ({ ok: false, reason: 'unavailable' }),
+    selectModel: async () => ({ ok: false, reason: 'unavailable' }),
+  }
+
+  // 目录浏览的空壳。它**只依赖 node:fs**，不像 tree 那样依赖 DSH 的服务，
+  // 所以正常情况下永远用真的那个；这个空壳是给测试用的（测试不该真去读盘）。
+  const files = browse ?? {
+    listRoots: async () => ({ home: '', drives: [], recent: [] }),
+    listDirectory: async () => ({ ok: false, reason: 'unavailable' }),
+    makeDirectory: async () => ({ ok: false, reason: 'unavailable' }),
+  }
 
   function broadcast(event, data) {
     const frame = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
@@ -168,6 +209,71 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     }
   }
 
+  // ---- 手机上答题 ------------------------------------------------------
+  //
+  // **这两样必须放在这一层**（和 `clients`、`broadcast` 同一层，全程只建一次）。
+  // 我第一版把它们写在了下面路由那一堆里——那是「每来一个请求就执行一次」的地方，
+  // 于是推送提问时放进去的清单、和收答案时去读的清单**是两个不同的清单**，
+  // 答案永远对不上、功能静默失效。放错一层就会这样，所以挪回来。
+  const waitingQuestions = new Map()
+  let questionSeq = 0
+
+  /** 手机上有没有人在看。**这就是「手机还在不在」那条判据**，不倒计时。 */
+  function hasPhone() {
+    return clients.size > 0
+  }
+
+  /**
+   * 把这个提问推到手机上，等它答。
+   * @returns 答案对象；手机没了就返回 null，调用方据此**把问题还给电脑**。
+   */
+  function askPhone(questions, agentId) {
+    const id = 'q' + (++questionSeq)
+    return new Promise((resolve) => {
+      let watch = null
+      const settle = (value) => {
+        if (!waitingQuestions.has(id)) return
+        waitingQuestions.delete(id)
+        if (watch) clearInterval(watch)
+        resolve(value)
+      }
+      // 题目本身也存进来（不只是 settle）：手机中途重连上来时要能补发给它，见 replayQuestions。
+      waitingQuestions.set(id, { settle, agentId, questions })
+      broadcast('question', { id, agentId, questions })
+      // 用户选的是「一直等，不还回电脑」——但那不等于「手机都没了还等」。
+      // 手机一旦全断开（锁屏、关了页面、网断），立刻收摊还给电脑，否则会永远卡住。
+      watch = setInterval(() => {
+        if (clients.size === 0) settle(null)
+      }, 2000)
+    })
+  }
+
+  /**
+   * 把正在等的题补发给**刚连上来的那一个**连接。
+   *
+   * 题目只在上面推一次，没有第二次。可手机这一端并不总是接着：
+   * 页面正在重连、锁屏醒来刚接上、切了个网络——那一下就错过了，而电脑那边还在等，
+   * 手机上却什么都看不见（2026-09-27 用户报的「电脑弹了选项、手机上什么都没有」，
+   * 有这一类情形在里面）。所以新连接一进来就把还在等的题发给它。
+   *
+   * **只发这一个新连接，不重播给所有人**：已经在看的那个手机可能已经勾好了选项，
+   * 再推一次会把它的勾清掉。
+   */
+  function replayQuestions(res) {
+    for (const [id, entry] of waitingQuestions) {
+      try {
+        res.write(`event: question\ndata: ${JSON.stringify({ id, agentId: entry.agentId, questions: entry.questions })}\n\n`)
+      } catch {
+        return
+      }
+    }
+  }
+
+  // 把这两个能力放到插件够得着的固定位置（见文件上方 `miniControl` 的说明）。
+  // 放在这里是因为它俩都已定义（函数声明本来也会提升），且不受下面那堆路由逻辑影响。
+  miniControl.hasPhone = hasPhone
+  miniControl.askPhone = askPhone
+
   function isAuthorized(req, url) {
     const fromQuery = url.searchParams.get('token')
     const fromCookie = parseCookies(req.headers.cookie)[COOKIE]
@@ -288,6 +394,38 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // ---- service worker -------------------------------------------------
+    // 它只为系统通知而存在（见 lib/sw.js）。
+    //
+    // **这一条不鉴权，是故意的。** 别处都鉴权，这里不行，理由是时序：service worker
+    // 必须在页面加载时就注册，而 token 要等用户过了门禁页才知道（从门禁页手输进来
+    // 时连 cookie 都没有，见上面立绘那段）。要是在这儿卡一道 token，那所有手输 token
+    // 的用户都会注册失败——而失败只在浏览器控制台里报，表现就是「开关开了但永远收不到
+    // 通知」，最难查的那种。
+    //
+    // 代价是零：这个文件里没有 token、没有用户数据、对所有人都是同一份。
+    //
+    // **`Service-Worker-Allowed: /` 这一行不能省。** 页面在 `/mini`，不在 `/mini/`
+    // 底下，而这个文件从 `/mini/sw.js` 发出去，默认作用域只到 `/mini/`——够不着那个
+    // 页面，注册会直接失败。放开到根，它才管得着。
+    if (req.method === 'GET' && path === '/mini/sw.js') {
+      const src = readSw()
+      if (!src) {
+        sendJson(res, 404, { error: 'not found' })
+        return
+      }
+      const buf = Buffer.from(src, 'utf8')
+      res.writeHead(200, {
+        'Content-Type': 'text/javascript; charset=utf-8',
+        'Content-Length': buf.length,
+        'Service-Worker-Allowed': '/',
+        // 地址里带着构建指纹，内容不会在同一个地址下变化，可以放心长缓存。
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      })
+      res.end(buf)
+      return
+    }
+
     // ---- 其余一律要鉴权 -------------------------------------------------
     if (!path.startsWith('/mini/api/')) {
       sendJson(res, 404, { error: 'not found' })
@@ -311,6 +449,9 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       })
       res.write(': connected\n\n')
       clients.add(res)
+      // 留痕：手机连没连上、一共有几台，就看这一句。2026-09-27 测自言自语的这天
+      // 正是卡在这儿——「她怎么没说话」和「手机压根没连上」当时根本分不开。
+      console.log(`[dsh-mini-remote] 手机连上了，现在连着 ${clients.size} 台`)
 
       const beat = setInterval(() => {
         try {
@@ -325,9 +466,21 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       // 连上就先补一次全量状态，手机刷新后不用再单独拉一次。
       res.write(`event: state\ndata: ${JSON.stringify(store.snapshot())}\n\n`)
 
+      // 接着把还在等手机回答的题补给它——重连上来的那一下最容易错过（见 replayQuestions）。
+      replayQuestions(res)
+
+      // 顺带把这个会话的完整历史准备好：手机上「刷新一下就只剩重启之后的事」
+      // 就是这么来的（手里那份只有插件在场时看见的）。读完会再广播一份快照。
+      onSessionOpened?.(store.snapshot().boundSessionId)
+
+      // 断开只记一次：req 和 res 各会 close 一次，不挡一下就会打两遍（含义却相反）。
+      let said = false
       const cleanup = () => {
+        if (said) return
+        said = true
         clearInterval(beat)
         clients.delete(res)
+        console.log(`[dsh-mini-remote] 手机断开了，还剩 ${clients.size} 台`)
       }
       req.on('close', cleanup)
       res.on('close', cleanup)
@@ -335,13 +488,28 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
     }
 
     if (req.method === 'GET' && path === '/mini/api/state') {
-      sendJson(res, 200, store.snapshot())
+      const snap = store.snapshot()
+      // 页面刷新、重新打开：也该看到当前会话的完整历史，而不是只有重启之后的事。
+      onSessionOpened?.(snap.boundSessionId)
+      sendJson(res, 200, snap)
       return
     }
 
     // 构建指纹。重启期间旧进程还在应答，这个接口用来确认「跑的是不是新代码」。
+    //
+    // `canCreateSession` 是**运行时**事实，不是配置推断：它问的是「这一刻 DSH 真的
+    // 把会话服务给我们了吗」。配置里挂了 `dsh-api-session-controller` 只说明它该在，
+    // 而服务可能因为组合不同、启动顺序、加载失败而没来——那种情况下手机上的 ＋
+    // 会一直报「没提供这个能力」，光看代码是查不出来的。放这儿就能一条命令问清楚。
     if (req.method === 'GET' && path === '/mini/api/version') {
-      sendJson(res, 200, { ok: true, build: build ?? 'unknown' })
+      let canCreateSession = false
+      try {
+        canCreateSession = nav.canCreateSession?.() === true
+      } catch (err) {
+        // 探测本身不该把接口带崩：问不到就当没有。
+        canCreateSession = false
+      }
+      sendJson(res, 200, { ok: true, build: build ?? 'unknown', canCreateSession })
       return
     }
 
@@ -357,13 +525,34 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // ---- 斜杠指令列表 ----------------------------------------------------
+    // 手机在输入框里打 `/` 时要显示的那一份。**名单来自 DSH 自己的指令账本**，
+    // 所以电脑上新装一个带指令的插件，手机上刷新就有了，不用改这个插件。
+    //
+    // 拿不到的时候如实说为什么（会话没在跑 / 这台电脑没有指令服务），
+    // 让手机显示那句话——**不能回一个空列表**：空列表的意思是「一条指令都没有」，
+    // 那是另一回事，用户会以为自己的 `/compact` 打错了。
+    if (req.method === 'GET' && path === '/mini/api/commands') {
+      if (!onCommands) {
+        sendJson(res, 503, { ok: false, error: '这台电脑上的 DSH 没提供指令。' })
+        return
+      }
+      const result = onCommands()
+      sendJson(res, result.ok ? 200 : 409, result)
+      return
+    }
+
     // 左侧导航栏：先列工作区（便宜），展开某个再取它的会话（要读日志折标题，贵）。
     // `refresh=1` 是导航栏那个 ⟳ 按钮用的：绕过服务端缓存，真去读一遍。
     if (req.method === 'GET' && path === '/mini/api/workspaces') {
       const runningIds = new Set(
         (store.snapshot().sessions ?? []).filter((s) => s.running).map((s) => s.id),
       )
-      const workspaces = await nav.listWorkspaces(runningIds, url.searchParams.get('refresh') === '1')
+      // includeEmpty：手机能自己新建工作区了，刚建好的那个本来就是空的。
+      // 不列出来的话，建完它当场消失，用户只会以为没建成。
+      const workspaces = await nav.listWorkspaces(
+        runningIds, url.searchParams.get('refresh') === '1', true,
+      )
       sendJson(res, 200, { ok: true, workspaces })
       return
     }
@@ -385,6 +574,147 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
       return
     }
 
+    // ---- 权限档位（作用在当前绑定的那个会话上）--------------------------
+    // 拿不到服务时**如实说没这个能力**，手机据此整块不显示。
+    // 不伪装成「只有一档」——那会让用户以为自己的权限被降过。
+    if (req.method === 'GET' && path === '/mini/api/permissions') {
+      const boundSessionId = store.snapshot().boundSessionId
+      const result = await nav.permissions(boundSessionId)
+      sendJson(res, 200, { boundSessionId, ...result })
+      return
+    }
+
+    // ---- 改模型 / 改思考强度 ---------------------------------------------
+    // 作用在当前绑定的那个会话上，和权限档位同一个口径。
+    //
+    // 强度**可以不传**——那表示「用这个模型自己的默认」。我们不替它猜一个值：
+    // 猜错了用户会以为那是自己选的，而真正生效的是别的档位。
+    //
+    // 强度和模型必须**一起**交给 DSH：`ModelSelection` 里强度是模型选择的一部分，
+    // 不是一项独立设置。分两次改会出现「模型换了、强度还停在旧模型那一档」的中间态。
+    if (req.method === 'POST' && path === '/mini/api/set-model') {
+      const boundSessionId = store.snapshot().boundSessionId
+      const body = await readBody(req)
+      const result = await nav.selectModel(boundSessionId, {
+        provider: body?.provider,
+        model: body?.model,
+        ...(body?.reasoningEffort ? { reasoningEffort: body.reasoningEffort } : {}),
+      })
+      if (!result.ok) {
+        sendJson(res, 503, { ok: false, error: '这台电脑上的 DSH 没提供改模型的能力。' })
+        return
+      }
+      // 把改完的值就手记到这个会话上。
+      //
+      // 为什么非记不可：DSH 那边要等这个会话**下一次发请求**才会把新模型报出来
+      // （request/header 事件），中间这段时间插件手里还是旧值。不补这一笔，用户
+      // 改完切走再切回来就会看到旧模型——那是他自己刚改的，等于界面自己打自己的脸。
+      const sel = result.selected
+      if (sel && typeof sel.model === 'string') {
+        store.touchSession(boundSessionId, {
+          provider: typeof sel.provider === 'string' ? sel.provider : null,
+          model: sel.model,
+          reasoningEffort: typeof sel.reasoningEffort === 'string' ? sel.reasoningEffort : null,
+        })
+      }
+      sendJson(res, 200, { ok: true, boundSessionId, selected: result.selected })
+      return
+    }
+
+    // ---- 模型与思考强度（作用在当前绑定的那个会话上）----------------------
+    // 目录里带着每个模型**自己声明**支持哪几档强度（`reasoning`）。手机照着它长界面：
+    // 不支持调强度的模型，那一行就不出现——**不给一个拖了没反应的滑块**。
+    //
+    // 目录是全局的，选中的那个是会话级的，所以这里两个都给出去：清单 + 当前绑定的那个。
+    // 拿不到能力时如实说没这个能力（503），和权限档位同一个口径。
+    if (req.method === 'GET' && path === '/mini/api/models') {
+      const boundSessionId = store.snapshot().boundSessionId
+      const result = await nav.modelCatalog(boundSessionId)
+      if (!result.ok) {
+        sendJson(res, 503, { ok: false, error: '这台电脑上的 DSH 没提供模型目录。' })
+        return
+      }
+      // 「这个会话现在用哪个」以 **DSH 那边**为准：它读的是会话日志里最后那条请求配置，
+      // 重启过、插件没看见过的会话一样问得出来。
+      //
+      // 为什么要改：原来只从插件自己记的那份里取（靠 request/header 事件一点点攒），
+      // 没跑过的会话就是空的。手机上一版又给空值兜了「目录默认值」，于是把**不知道**
+      // 显示成了「上次选过的那个模型」——用户切过去看到的是一个像模像样的错答案。
+      // 现在问不到就如实给 null，怎么讲由界面决定，反正不编。
+      const asked = nav.sessionModel ? await nav.sessionModel(boundSessionId) : { ok: false }
+      const remembered = store.snapshot().sessions?.find((s) => s.id === boundSessionId) ?? null
+      const current = asked.ok
+        ? asked.model
+        : (remembered && remembered.model
+            ? {
+                provider: remembered.provider ?? null,
+                model: remembered.model,
+                reasoningEffort: remembered.reasoningEffort ?? null,
+              }
+            : null)
+      sendJson(res, 200, { ok: true, boundSessionId, current, ...result.catalog })
+      return
+    }
+
+    if (req.method === 'POST' && path === '/mini/api/answer') {
+      const body = await readBody(req)
+      const waiting = waitingQuestions.get(body?.id)
+      if (!waiting) {
+        // 409 而不是 200：多半是这个提问早就结束了，如实说，别装作收下了。
+        // 落一句痕：这是「手机答了、电脑没动静」唯一能查到的线索——手机那边原来
+        // 把失败咽掉了，插件这边再不留痕，下次还是只能靠猜（2026-09-27）。
+        console.log('[dsh-mini-remote] 手机上答晚了：这道题已经交回电脑（' + String(body?.id) + '），没接')
+        sendJson(res, 409, { ok: false, error: '这个提问已经结束了。' })
+        return
+      }
+      const answers = Array.isArray(body?.answers) ? body.answers : null
+      if (!answers) {
+        sendJson(res, 400, { ok: false, error: '答案格式不对。' })
+        return
+      }
+      waiting.settle({ answers })
+      sendJson(res, 200, { ok: true })
+      return
+    }
+
+    // ---- 目录浏览（挑工作区用）------------------------------------------
+    // 只列目录，绝不列文件、绝不读内容。手机上要的是「挑一个文件夹」。
+    if (req.method === 'GET' && path === '/mini/api/browse/roots') {
+      // 「最近用过的目录」直接拿已登记工作区的路径：那些正是他用过的地方，
+      // 不用我们另外记一份「最近打开过什么」的状态。
+      const recent = (nav.listWorkspaces ? await nav.listWorkspaces(new Set(), false) : [])
+        .map((w) => w.path)
+        .filter(Boolean)
+      sendJson(res, 200, { ok: true, ...(await files.listRoots({ recent })) })
+      return
+    }
+
+    if (req.method === 'GET' && path === '/mini/api/browse') {
+      const asked = url.searchParams.get('path')
+      if (!asked) {
+        sendJson(res, 400, { ok: false, error: '要带 path 参数。' })
+        return
+      }
+      const result = await files.listDirectory(asked)
+      if (!result.ok) {
+        // 读不出来时如实说，**不当作空目录**：空目录和「没有权限」在界面上
+        // 长得一模一样，而后者用户需要知道。
+        const known = {
+          'bad-path': [400, '这个路径不合法。'],
+          unreadable: [404, '读不到这个目录，可能是不存在或者没有权限。'],
+          // 空壳才会走到这儿（生产里 browse 一直传得进来）。口径跟其它
+          // 「没这个能力」统一成 503，不混进 500 里。
+          unavailable: [503, '这台电脑上的 DSH 没提供目录浏览。'],
+        }
+        const [status, message] = known[result.reason]
+          ?? [500, `读目录失败：${result.error ?? '原因未知'}`]
+        sendJson(res, status, { ok: false, error: message })
+        return
+      }
+      sendJson(res, 200, result)
+      return
+    }
+
     // ---- 上传文件 -------------------------------------------------------
     // 这一段**必须排在下面那个 readBody 前面**：readBody 既只认 JSON，又把请求体
     // 限死在 64 KB（MAX_BODY）。手机拍一张照片就有好几兆，走它必然失败，而且失败得
@@ -445,6 +775,25 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         return
       }
 
+      if (path === '/mini/api/command') {
+        // 执行一条斜杠指令。**结果不在这条响应里**——指令跑完会把
+        // `command/run` / `command/done` 两条事件写进会话记录，手机上那条「指令行」
+        // 是跟着事件流出现的（和电脑端同一份账）。这里只负责「收下并开跑」，
+        // 或者「不收，并说明为什么」。
+        const line = typeof body.line === 'string' ? body.line : ''
+        if (!line.trim()) {
+          sendJson(res, 400, { ok: false, error: '指令为空。' })
+          return
+        }
+        if (!onCommand) {
+          sendJson(res, 503, { ok: false, error: '这台电脑上的 DSH 没提供指令。' })
+          return
+        }
+        const result = await onCommand(line)
+        sendJson(res, result.ok ? 200 : 409, result)
+        return
+      }
+
       if (path === '/mini/api/stop') {
         // 停的是「手机正在遥控的那个会话」，和 send 同一套口径——
         // 手机上按的停止，不该停掉你在电脑上另开的那个任务。
@@ -466,6 +815,109 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         return
       }
 
+      // 在一个已有的工作区里新建会话，建完立刻把手机绑过去。
+      //
+      // 为什么排在这么靠后、而不是跟上面那条 GET 挨着：这两条都要读请求体，
+      // 而 `readBody` 在后面才调（上面那条 GET 不用读，所以能排在前面）。
+      // 同一个路径上 GET 是「列出来」、POST 是「建一个」——同一条资源的两种动作。
+      //
+      // 建完顺手 bind + 广播：手机发一次请求就完成了「建 + 切过去」，
+      // 不用再补一次 bind，也就不会出现「建好了但没切过去」这种半截状态。
+      if (req.method === 'POST' && wsSessions) {
+        const created = await nav.createSession(decodeURIComponent(wsSessions[1]))
+        if (!created.ok) {
+          const known = {
+            'no-controller': [503, '这台电脑上的 DSH 没提供新建会话的能力。'],
+            'no-workspace': [404, '没有这个工作区。'],
+          }
+          const [status, message] = known[created.reason]
+            ?? [500, `新建会话失败：${created.error ?? '原因未知'}`]
+          sendJson(res, status, { ok: false, error: message })
+          return
+        }
+        store.bind(created.sessionId)
+        const snap = store.snapshot()
+        broadcast('state', snap)
+        sendJson(res, 200, {
+          ok: true,
+          sessionId: created.sessionId,
+          workspaceTitle: created.workspaceTitle,
+          boundSessionId: created.sessionId,
+          state: snap,
+        })
+        return
+      }
+
+      // 切权限档位。作用在当前绑定的那个会话上——手机只绑一个会话，
+      // 所以「当前会话」和「绑定会话」是同一件事。
+      if (path === '/mini/api/permissions') {
+        const boundSessionId = store.snapshot().boundSessionId
+        const done = await nav.setPermission(
+          boundSessionId, typeof body.name === 'string' ? body.name : '',
+        )
+        if (!done.ok) {
+          const known = {
+            'no-service': [503, '这台电脑上的 DSH 没提供权限档位。'],
+            // 409 而不是 400：请求本身没问题，是当前状态不满足——
+            // 得先挑一个会话。
+            'no-session': [409, '还没绑定会话，先挑一个会话再切权限。'],
+            'unknown-preset': [400, '没有这个权限档位。'],
+          }
+          const [status, message] = known[done.reason]
+            ?? [500, `切换失败：${done.error ?? '原因未知'}`]
+          sendJson(res, status, { ok: false, error: message })
+          return
+        }
+        // 切完把最新状态回过去：手机据此更新高亮，不用再补一趟请求。
+        const after = await nav.permissions(boundSessionId)
+        sendJson(res, 200, { ...after, ok: true, name: done.name, boundSessionId })
+        return
+      }
+
+      // 把一个目录登记成工作区。
+      // 跟上面那条 GET 同一条路径：GET 是「列出来」，POST 是「登记一个」。
+      if (path === '/mini/api/workspaces') {
+        const target = typeof body.path === 'string' ? body.path : ''
+        const made = await nav.createWorkspace(target)
+        if (!made.ok) {
+          const known = {
+            'no-registry': [503, '这台电脑上的 DSH 没提供工作区服务。'],
+            'bad-path': [400, '没给路径。'],
+          }
+          const [status, message] = known[made.reason]
+            ?? [400, `登记不了这个目录：${made.error ?? '原因未知'}`]
+          sendJson(res, status, { ok: false, error: message })
+          return
+        }
+        // 登记完立刻把最新的工作区列表带回去：手机拿到就能直接画出来，
+        // 不用再补一趟请求，也就不会出现「建好了但列表里还没有」。
+        const workspaces = await nav.listWorkspaces(new Set(), true, true)
+        sendJson(res, 200, {
+          ok: true, created: made.created, workspace: made.workspace, workspaces,
+        })
+        return
+      }
+
+      // 在选中的目录下新建一个子目录。
+      // `name` 必须是**单个目录名**，不接受路径——手机是网络对面来的输入，
+      // 一个带 `..` 或分隔符的「名字」能让新建落到别的地方去。
+      if (path === '/mini/api/browse/mkdir') {
+        const result = await files.makeDirectory(body.path, body.name)
+        if (!result.ok) {
+          const known = {
+            'bad-name': [400, '文件夹名不合法：不能为空、不能带斜杠，也不能是 . 或 ..'],
+            'bad-path': [400, '这个路径不合法。'],
+            exists: [409, '这个名字已经有一个文件夹了。'],
+          }
+          const [status, message] = known[result.reason]
+            ?? [500, `建文件夹失败：${result.error ?? '原因未知'}`]
+          sendJson(res, status, { ok: false, error: message })
+          return
+        }
+        sendJson(res, 200, result)
+        return
+      }
+
       if (path === '/mini/api/bind') {
         const sessionId = typeof body.sessionId === 'string' ? body.sessionId : ''
         if (!sessionId) {
@@ -473,6 +925,9 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
           return
         }
         store.bind(sessionId)
+        // 切过去的这个会话，完整历史该读就读（异步补，读完再广播一份快照）。
+        // 这一下是「点开工作区里的会话，能看到它之前的每一轮」能成立的关键。
+        onSessionOpened?.(sessionId)
         const snap = store.snapshot()
         broadcast('state', snap)
         // 顺手把快照放回响应里。手机拿到就能立刻渲染，不用等 SSE 那一趟；
@@ -586,5 +1041,9 @@ export async function createMiniServer({ store, config, token, bindAddresses, tu
         server.closeAllConnections?.()
       })))
     },
+    // 给插件主体用：把提问推给手机、以及「手机还在不在」。
+    // 两个都挂在返回对象上，是因为提问是插件主体接到的，而「连着的手机」在这边。
+    askPhone,
+    hasPhone,
   }
 }