dsh-mini-remote 0.1.0 → 0.1.3

package/client/client.js

@@ -25,6 +25,7 @@ window.__ModuleLoader__.load({
     var PAIRING_PATH = '/mini-remote/pairing';
     var TOKEN_PATH = '/mini-remote/token';
     var TUNNEL_PATH = '/mini-remote/tunnel';
+    var SERVE_PATH = '/mini-remote/serve';
 
     // 颜色走 DSH 主题变量（真名前缀是 --dsw-alias-，深浅色自动跟随）。
     // 每个变量都带一个浅色兜底值，变量缺失时界面仍然可读。
@@ -73,6 +74,11 @@ window.__ModuleLoader__.load({
       var pwdErrState = useState(null);
       var pwdError = pwdErrState[0];
       var setPwdError = pwdErrState[1];
+      // HTTPS 开关的失败信息单独存一份（不是复用上面的 failure）：它要多带一条
+      // 「点这里去开启」的链接，一条字符串装不下。
+      var serveErrState = useState(null);
+      var serveError = serveErrState[0];
+      var setServeError = serveErrState[1];
 
       // 同源 GET，不带任何 token：这台电脑自己读得到，别人的电脑读不到。
       useEffect(function () {
@@ -180,6 +186,57 @@ window.__ModuleLoader__.load({
           .then(function () { setBusy(false); });
       };
 
+      /**
+       * 开/关 Tailscale 的 HTTPS 地址。
+       *
+       * 失败时**不复用上面那个 failure**：这条要多带一条「点这里去开启」的链接，
+       * 一条字符串装不下。而那条链接恰恰是整个功能里门槛最高的一步——tailnet
+       * 后台的一个一次性开关。Tailscale 官方把它印在报错里了，原样递给用户就行。
+       *
+       * 成功与否的判据是响应体里有没有 `reason`：serve 失败那条路带它，
+       * 配对信息那条路不带。配对信息本身也可能是 `ok:false`（比如一条地址都没有），
+       * 那种情况照旧交给 setInfo，让面板自己把它画成错误块。
+       */
+      var toggleServe = function (enabled) {
+        if (busy) return;
+        setBusy(true);
+        setServeError(null);
+        fetch(SERVE_PATH, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ enabled: enabled }),
+        })
+          .then(function (res) {
+            return res.json().then(
+              function (body) { return { status: res.status, body: body }; },
+              function () { return { status: res.status, body: null }; },
+            );
+          })
+          .then(function (r) {
+            var b = (r.body && typeof r.body === 'object') ? r.body : null;
+            if (!b) {
+              setServeError({
+                error: '切换 HTTPS 地址失败：服务返回了 HTTP ' + r.status + '。',
+                enableLink: null,
+              });
+              return;
+            }
+            if (b.reason) {
+              setServeError({ error: b.error || '开 HTTPS 地址失败了。', enableLink: b.enableLink || null });
+              return;
+            }
+            setInfo(b);
+            setFailure(null);
+          })
+          .catch(function (err) {
+            setServeError({
+              error: '切换 HTTPS 地址失败：' + ((err && err.message) || String(err)),
+              enableLink: null,
+            });
+          })
+          .then(function () { setBusy(false); });
+      };
+
       return h('div', { style: styles.card },
         h('div', { style: styles.title }, '手机遥控'),
         h('div', { style: styles.muted }, '手机扫码就能用，不用输密码——密码已经编在二维码里了。'),
@@ -192,11 +249,20 @@ window.__ModuleLoader__.load({
           busy: busy,
           pwdError: pwdError,
           savePassword: savePassword,
+        }, {
+          // **摊平再传**。serveError 自己是 `{error, enableLink}`，如果直接写成
+          // `{error: serveError}`，serveBlock 里的 `err.error` 拿到的就是整个对象，
+          // 而 `h('div', {}, 对象)` 渲染出来是一个**空**的 div——错误文字一个字都不
+          // 显示，界面上看上去只是「点了没反应」。2026-09-24 就是这么踩进去的：
+          // 状态和渲染全是对的，只有最后一步取错了字段。
+          error: serveError ? serveError.error : null,
+          enableLink: serveError ? serveError.enableLink : null,
+          toggle: toggleServe,
         }),
       );
     }
 
-    function content(info, failure, copied, copy, busy, toggle, pwd) {
+    function content(info, failure, copied, copy, busy, toggle, pwd, serve) {
       if (failure) return h('div', { style: styles.error }, failure);
       if (!info) return h('div', { style: styles.loading }, '正在读取配对信息…');
 
@@ -220,9 +286,86 @@ window.__ModuleLoader__.load({
       // 出错时也要把开关露出来：不然「隧道起不来」会让整个面板变成一条报错，
       // 用户连关掉它的地方都找不到。
       if (info.tunnel) blocks.push(tunnelBlock(info.tunnel, busy, toggle));
+      // HTTPS 那一块：**不管配对信息成功还是失败都要出现**。失败时尤其要出现——
+      // tailnet 没开 Serve 的时候，用户需要的正是那条开启链接，而那时候面板上
+      // 其它东西多半也在报错，正好是他最需要指路的时候。
+      if (info.serve || serve.error) blocks.push(serveBlock(info.serve, serve, busy));
       return h('div', null, blocks);
     }
 
+    /**
+     * Tailscale 的 HTTPS 地址这一块。
+     *
+     * 为什么值得单独占一块：手机端有三样东西被明文 http 挡着——完成后提醒、
+     * 语音输入、剪贴板的完整能力。浏览器只在加密连接上才给用。
+     * 开了这个，Tailscale 那条路上就多出一个 https:// 地址，那三样才有得谈。
+     *
+     * **它不是第四条路**：同一台电脑、同一个服务、同一条 Tailscale 通道，
+     * 只是把连接换成加密的。上面那条明文的照旧能用，也照旧显示。
+     */
+    function serveBlock(st, err, busy) {
+      var on = Boolean(st && st.on);
+      var installed = !st || st.installed !== false;
+      var other = st && st.urlOfOtherPort ? st.urlOfOtherPort : null;
+      var needsLogin = Boolean(st && st.needsLogin);
+      // 服务端已经算好了该说哪句话，界面照说就行。
+      var stateError = st && st.error ? st.error : null;
+      var status;
+      if (!installed) {
+        status = '这台电脑上没装 Tailscale，所以开不了。上面那条「在外面用（Tailscale）」里有下载链接。';
+      } else if (on) {
+        status = '已开启。上面那条「Tailscale（加密）」就是它——出门在外用它，地址不用写端口。';
+      } else if (needsLogin) {
+        // 这一步的下一步动作和「没开」完全不同：他得先去登录，登录之后那个地址才会存在。
+        // 合成一句「没开」，一个还没登录的人会反复点开关，怎么点都没反应。
+        status = 'Tailscale 装了，但这个账号还没登录。先在电脑上登录一次——手机要连的那个地址，是登录之后才有的。';
+      } else if (stateError) {
+        status = '问不出来 Tailscale 现在是什么状态。';
+      } else if (other) {
+        // 不能含糊地说「没开」：用户会以为是自己这台电脑不支持。
+        status = 'Tailscale 的 serve 配着，但它指的是别的端口，不是这个插件。想给手机用的话，把下面这个开关打开。';
+      } else {
+        status = '没开。开了之后 Tailscale 那条路上会多一个 https:// 地址——手机浏览器只在加密连接上才肯给用通知和麦克风。'
+          + '第一次开要在浏览器里确认一下（Tailscale 后台的一个开关），插件代不了你点。';
+      }
+
+      // 两条链接都是 Tailscale 官方给的，原样递过去。这是整个功能里门槛最高的两步：
+      // 一次是登录，一次是给 tailnet 开 Serve。自己写一句「请到后台开启」等于把门槛加回去。
+      var loginUrl = needsLogin && st.loginUrl ? st.loginUrl : null;
+      var enableUrl = (err && err.enableLink) || (st && st.enableLink) || null;
+      var shownError = (err && err.error) || stateError;
+
+      return h('div', { key: 'serve', style: styles.block },
+        h('div', { style: styles.entryTitle }, 'HTTPS 地址（Tailscale）'),
+        h('div', { style: styles.muted }, '和上面那条 Tailscale 是同一台电脑，区别只在连接加不加密。地址好记，也不用写端口。'),
+        h('label', { style: styles.toggleRow },
+          h('input', {
+            type: 'checkbox',
+            checked: on,
+            disabled: Boolean(busy) || !installed || needsLogin,
+            onChange: function (e) { err.toggle(e.target.checked); },
+          }),
+          h('span', null, on ? '已开启' : '开启'),
+        ),
+        h('div', { style: shownError ? styles.detail : styles.muted }, status),
+        loginUrl ? h('a', {
+          href: loginUrl,
+          target: '_blank',
+          rel: 'noreferrer',
+          style: styles.link,
+        }, '点这里去登录（Tailscale 官方页面）') : null,
+        enableUrl ? h('a', {
+          href: enableUrl,
+          target: '_blank',
+          rel: 'noreferrer',
+          style: styles.link,
+        }, '点这里去开启（Tailscale 官方页面）') : null,
+        // 失败原文照登，别吞。这条路上最可能的失败是「tailnet 还没开 Serve」，
+        // 而那种情况 Tailscale 会印出一条开启链接——上面那条链接才是用户要的东西。
+        err && err.error ? h('div', { style: styles.error }, err.error) : null,
+      );
+    }
+
     /**
      * 没探到 Tailscale 时的那一行：说清楚缺什么、去哪儿拿。
      *

package/lib/browse.js

@@ -0,0 +1,216 @@
+/**
+ * 电脑目录浏览，给手机挑工作区用。
+ *
+ * ## 为什么自己用 node:fs 实现，而不是用 DSH 的目录选择器
+ *
+ * DSH 有 `@deepseek-ai/dsh-host-directory-picker`，能力是分叉的：一种是 native
+ * （在**电脑屏幕上**弹系统选择框），一种是 browse（纯数据，什么都不往电脑屏幕上画）。
+ * 哪个生效由 `directory-picker-auto` 开机时判：
+ *
+ *     if (facts.bindHost !== "127.0.0.1") return "browse";
+ *     if (facts.ssh)                       return "browse";
+ *     if (platform === "darwin" || platform === "win32") return "native";
+ *
+ * 也就是说：**Windows + 只绑回环地址（大多数人的默认配置）→ 判成 native**。
+ * 而 native 模式下 `list` / `createDirectory` 这类动词是**直接被拒绝**的，不是降级
+ * 模拟（那套设计明确说 refused verbs are refused, not approximated）。
+ * 结果就是：用户坐在电脑前，手机上点「新建工作区」，电脑屏幕上弹出一个框——
+ * 而他正在外面用手机。这条路走不通。
+ *
+ * 所以我们自己读目录。理由不是「更简单」，是**跟绑定地址无关、行为可预测**：
+ * 不管 DSH 绑回环还是绑局域网、不管有没有走 SSH，手机看到的都是同一份数据。
+ *
+ * ## 边界
+ *
+ * 只列**目录**，绝不列文件、绝不读文件内容。手机上要的是「挑一个文件夹」，
+ * 文件既是噪音也是不必要的暴露。
+ *
+ * ## 关于「手机传来的路径不可信」
+ *
+ * 手机是网络对面来的输入，所以这里对路径只做两件事：**规范化**（`resolve` 掉
+ * `..`、`.`）和**拒绝畸形输入**（空字节、非字符串）。不做白名单式的根限制，
+ * 因为「挑一个项目文件夹」本来就要能走到任意盘；真正的闸门是那道 token，
+ * 它才是「谁在跟我说话」的判据。这里防的是**畸形路径导致的意外文件操作**，
+ * 不是防已通过认证的用户去访问自己的电脑。
+ */
+import { mkdir, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, parse, resolve, sep } from 'node:path'
+
+/** 一次最多列多少个子目录。手机上再多也划不动，而且超大目录读起来很慢。 */
+export const MAX_DIRS = 300
+
+/** 「最近用过的目录」最多给几个。 */
+export const MAX_RECENT = 8
+
+/**
+ * 目录名合不合法。口径照 DSH 自己的校验来，只多一条空字节：
+ * 空字节在 Windows 上会让底层调用抛一个很难看的错，早点挡住。
+ *
+ * 注意这里挡的是**名字**（单个目录名），不是路径——路径是另一回事，
+ * 它要允许 `I:\a\b` 这种带分隔符的形态。
+ */
+export function validDirName(name) {
+  return typeof name === 'string'
+    && name.trim() !== ''
+    && name !== '.'
+    && name !== '..'
+    && !/[/\\]/.test(name)
+    && !name.includes('\0')
+}
+
+/**
+ * 规范化手机传来的路径。
+ *
+ * `resolve` 会把 `..` 和 `.` 算掉，所以 `I:\a\..\..\Windows` 会变成 `I:\Windows`——
+ * 这是**故意的**：我们不去猜用户想干什么，只保证拿去读的是一条干净的绝对路径。
+ * 畸形输入（不是字符串、空字节）直接拒绝，不试着修补。
+ */
+export function normalizePath(input) {
+  if (typeof input !== 'string') return null
+  const trimmed = input.trim()
+  if (trimmed === '' || trimmed.includes('\0')) return null
+  return resolve(trimmed)
+}
+
+/**
+ * 从根到目标的那一串祖先，做面包屑用。
+ *
+ * 纯字符串运算，不碰磁盘：面包屑要在目录读失败时照样画得出来，
+ * 不然用户会卡在一个空白页面上，连退都退不回去。
+ */
+export function ancestorsOf(full) {
+  const { root } = parse(full)
+  const out = [{ name: root, path: root }]
+  let cur = root
+  for (const part of full.slice(root.length).split(sep)) {
+    if (!part) continue
+    cur = join(cur, part)
+    out.push({ name: part, path: cur })
+  }
+  return out
+}
+
+/**
+ * 盘符列表（Windows）。
+ *
+ * 用 A–Z 逐个 stat 探，不 spawn 任何进程：探测本身很便宜，而且结果缓存一次——
+ * 盘符在一个会话里不会变，没必要每次开面板都探 26 次。
+ * 非 Windows 上只有一个根 `/`。
+ */
+let drivesCache = null
+async function drivesOf() {
+  if (process.platform !== 'win32') return [sep]
+  if (drivesCache) return drivesCache
+  const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('')
+  const found = await Promise.all(letters.map(async (letter) => {
+    const root = letter + ':' + sep
+    try {
+      const info = await stat(root)
+      return info.isDirectory() ? root : null
+    } catch (err) {
+      // 没这个盘、或者是个空的光驱——都当作不存在。
+      return null
+    }
+  }))
+  drivesCache = found.filter(Boolean)
+  return drivesCache
+}
+
+/**
+ * 常用位置。手机打开「新建工作区」时看到的第一屏。
+ *
+ * 起点为什么要给这些、而不是直接甩盘符：这个插件的门槛要低到非技术用户能走通。
+ * 从 `C:\` 一层层点进去找一个项目文件夹，是要人自己知道路径长什么样；
+ * 而「主目录 / 盘符 / 最近用过的」这三样，大多数时候点两下就到地方了。
+ *
+ * `recent` 由调用方给（我们拿的是已登记工作区的路径）——那些正是「他用过的目录」，
+ * 而且不用我们另外记一份「最近打开过什么」的状态。
+ */
+export async function listRoots({ recent = [] } = {}) {
+  const home = homedir()
+  const seen = new Set([home.toLowerCase()])
+  const recentOut = []
+  for (const p of recent) {
+    if (typeof p !== 'string' || !p) continue
+    const key = p.toLowerCase()
+    if (seen.has(key)) continue
+    seen.add(key)
+    recentOut.push(p)
+    if (recentOut.length >= MAX_RECENT) break
+  }
+  return { home, drives: await drivesOf(), recent: recentOut }
+}
+
+/**
+ * 列一个目录下的**子目录**。
+ *
+ * 读不出来时**如实抛错**，不吞掉当作空目录：空目录和「没有权限读」在界面上
+ * 长得一模一样，而后者用户需要知道（他可能是选错了地方，也可能是权限问题）。
+ */
+export async function listDirectory(input) {
+  const full = normalizePath(input)
+  if (!full) return { ok: false, reason: 'bad-path' }
+
+  let entries
+  try {
+    entries = await readdir(full, { withFileTypes: true })
+  } catch (err) {
+    return { ok: false, reason: 'unreadable', error: String(err?.code ?? err?.message ?? err) }
+  }
+
+  const dirs = []
+  const links = []
+  for (const entry of entries) {
+    if (entry.isDirectory()) dirs.push(entry.name)
+    // 符号链接 / 目录联接自己不说自己通向哪儿，得问一次 stat。
+    // 只对链接做这一步：普通条目已经在 dirent 里带类型了，不必每条都 stat。
+    else if (entry.isSymbolicLink()) links.push(entry.name)
+  }
+  for (const name of links) {
+    try {
+      const info = await stat(join(full, name))
+      if (info.isDirectory()) dirs.push(name)
+    } catch (err) {
+      // 断掉的链接：跳过，不是错误。
+    }
+  }
+
+  // 排序要**不区分大小写**：Windows 的文件名本来就不区分大小写，
+  // 按码点排会把所有大写开头的目录全排到前面，看起来像乱的。
+  dirs.sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }))
+
+  const truncated = dirs.length > MAX_DIRS
+  return {
+    ok: true,
+    path: full,
+    ancestors: ancestorsOf(full),
+    dirs: dirs.slice(0, MAX_DIRS).map((name) => ({ name, path: join(full, name) })),
+    total: dirs.length,
+    truncated,
+  }
+}
+
+/**
+ * 在一个目录下新建一个子目录。
+ *
+ * **`name` 必须是单个合法目录名**（见 validDirName），不接受路径：手机传来的东西
+ * 当不可信处理，一个带 `..` 或分隔符的「名字」能让新建落到别的地方去。
+ *
+ * 不用 `recursive: true`：父目录必须已经存在，那是调用方选中的地方。
+ * 加了 recursive 反而会把「父目录没了」这种真实错误悄悄糊过去。
+ */
+export async function makeDirectory(parentInput, name) {
+  if (!validDirName(name)) return { ok: false, reason: 'bad-name' }
+  const parent = normalizePath(parentInput)
+  if (!parent) return { ok: false, reason: 'bad-path' }
+
+  const target = join(parent, name)
+  try {
+    await mkdir(target)
+  } catch (err) {
+    if (err?.code === 'EEXIST') return { ok: false, reason: 'exists' }
+    return { ok: false, reason: 'failed', error: String(err?.code ?? err?.message ?? err) }
+  }
+  return { ok: true, path: target }
+}

package/lib/commands.js

@@ -0,0 +1,166 @@
+/**
+ * 斜杠指令：手机作为一个「发起指令的界面」，问 DSH 自己的指令账本。
+ *
+ * 为什么不是自己实现一套：指令是别的插件注册到宿主上的（`ctx.commands.register`），
+ * 手机端不该也不可能重写它们。DSH 把「注册 / 列出 / 执行」放在 `ctx.commands` 服务里，
+ * 电脑上的网页端走的是同一个服务（它经过 remote 那一层），所以这里**照抄 DSH 的语义**，
+ * 只是换了调用它的地方——手机上装了新插件带来的指令，会自动出现在手机列表里。
+ *
+ * 这个文件里放的都是**纯逻辑**（`test/commands.test.mjs` 直接测），
+ * 真正碰服务的地方在 index.js。
+ *
+ * 三条来自 DSH 文档与类型定义的事实（不要自己发明）：
+ *   ① 指令行的语法：**第 0 个字节必须是斜杠**，接着是小写名字（字母、数字、`_`、`-`），
+ *      再往后要么结束、要么是空白；名字之后的每个字节（**包括那个分隔空格**）都是
+ *      `rawInput`，由指令自己解释。不满足这个形状、或者名字不认识的，**拒绝，不当成提示词**。
+ *   ② 执行会往会话记录里追加一对日志事件：`command/run`（`commandId`、`name`、`args`）
+ *      和 `command/done`（`commandId`、`kind`、`text`），靠 `commandId` 配对。
+ *      指令**不产生模型消息**——所以它既不该长成用户气泡，也不该被当成 AI 的回答。
+ *   ③ 描述符（`list()` 的返回）是「给发现界面看的」：`name`、`description`，
+ *      外加可选的 `input.hint`（要参数时给用户看的一句话）和 `input.attachments`。
+ */
+
+/**
+ * DSH 自己的指令行正则——**逐字照抄** dsh-commands 里 `parseCommand` 用的那条
+ * （`/^\/([a-z][a-z0-9_-]*)(?=$|[\t\n\r ])/u`）。
+ *
+ * 照抄而不是"写个差不多的"：名字必须以**小写字母**开头（`/9x`、`/_x` 都不是指令），
+ * 后面的空白集是 `\t\n\r ` 这四个（不是 `\s`）。差一个字符，手机和电脑就会对
+ * "这行算不算指令"给出不同答案，而这种分歧极难被发现。
+ */
+const COMMAND_RE = /^\/([a-z][a-z0-9_-]*)(?=$|[\t\n\r ])/u
+
+/**
+ * 按 DSH 的语法拆一行指令。
+ *
+ * @param {unknown} line
+ * @returns {{name:string, rawInput:string}|null} 不是指令行 → null
+ */
+export function parseSlashLine(line) {
+  if (typeof line !== 'string') return null
+  const m = COMMAND_RE.exec(line)
+  if (!m) return null
+  // 名字之后**原样**保留，包括那个分隔空格——这是 DSH 的口径（`rawInput` 含前导空白），
+  // 指令自己拥有这段语法，我们不许替它 trim。
+  return { name: m[1], rawInput: line.slice(m[0].length) }
+}
+
+/**
+ * 电脑网页端专有、宿主**根本没有**注册的两条指令。
+ *
+ * 这不是我们编的：`/model` 和 `/file` 是浏览器端自己的贡献（`ctx.commandUi.register`），
+ * 宿主目录里没有它们（2026-09-25 查证）。手机上打这两条，`find()` 必然落空——
+ * 如果只说一句「没有这条指令」，用户会以为是自己打错了，可电脑上明明有。
+ */
+const BROWSER_ONLY = {
+  model: '这是电脑网页端专有的指令。手机上是点顶栏那一行换模型。',
+  file: '这是电脑网页端专有的指令。手机上用输入框旁边的回形针传文件。',
+}
+
+/** 这行连指令的形状都不是（比如 `/9x`、`/Model`——DSH 的名字必须以小写字母开头）。 */
+export function invalidCommandMessage() {
+  return '这不是一条指令。指令要以 / 开头，名字只能用小写字母、数字、- 和 _。'
+}
+
+/** 形状对，但账本里没有这个名字。 */
+export function unknownCommandMessage(name) {
+  const special = BROWSER_ONLY[name]
+  if (special) return `/${name} 不是这台电脑上的指令：${special}`
+  return `没有 /${name} 这条指令。`
+}
+
+/**
+ * 把 `list()` 给的描述符翻成手机要的那几样，并按名字排序。
+ *
+ * 只搬手机用得上的字段：多搬字段等于替未来的自己许下承诺，DSH 那边加字段就会漂。
+ *
+ * @param {unknown} descriptors
+ */
+export function describeCommands(descriptors) {
+  const rows = []
+  for (const d of Array.isArray(descriptors) ? descriptors : []) {
+    const name = typeof d?.name === 'string' ? d.name : ''
+    if (!name) continue
+    const hint = typeof d?.input?.hint === 'string' && d.input.hint ? d.input.hint : null
+    rows.push({
+      name,
+      description: typeof d?.description === 'string' ? d.description : '',
+      hint,
+      // 「这条指令收不收附件」。手机这一版不带附件执行，但把实情告诉用户，
+      // 总比让他对着一条声明了要附件的指令发呆强。
+      attachments: d?.input?.attachments === true,
+    })
+  }
+  rows.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  return rows
+}
+
+/**
+ * `command/run` → 一条「正在执行」的记录。
+ *
+ * 时间戳用**事件自己的 `time`**，不用 `Date.now()`：手机上那份历史和硬盘重放出来的
+ * 那份要靠时间戳合成（见 store.js 的 mergeHistory），两边用同一个钟才不会接重。
+ */
+export function commandRow(event) {
+  const data = event?.data
+  if (!data || typeof data.commandId !== 'string' || typeof data.name !== 'string') return null
+  return {
+    role: 'command',
+    commandId: data.commandId,
+    name: data.name,
+    args: typeof data.args === 'string' ? data.args : '',
+    kind: 'running',
+    text: null,
+    timestamp: typeof event?.time === 'number' ? event.time : null,
+  }
+}
+
+/** `command/done` → 用来给上面那条收尾的那几个字段。 */
+export function commandPatch(event) {
+  const data = event?.data
+  if (!data || typeof data.commandId !== 'string') return null
+  return {
+    commandId: data.commandId,
+    kind: data.kind === 'error' ? 'error' : 'success',
+    text: typeof data.text === 'string' && data.text ? data.text : null,
+  }
+}
+
+/**
+ * 把两个指令事件折进一串记录里——**重放和实时共用这一个映射**。
+ *
+ * 和 events.js 的提取器是同一个道理：两条路各写一套配对逻辑的话，
+ * 迟早一边显示「执行中」、一边显示结果，或者干脆配对错行。
+ *
+ * @param {Array<object>} rows 就地修改
+ * @param {{type?:string, time?:number, data?:any}} event
+ * @returns {boolean} 这个事件是不是指令事件（是就表示已被处理）
+ */
+export function foldCommandEvent(rows, event) {
+  if (event?.type === 'command/run') {
+    const row = commandRow(event)
+    if (row) rows.push(row)
+    return true
+  }
+  if (event?.type === 'command/done') {
+    const patch = commandPatch(event)
+    if (!patch) return true
+    // 从后往前找：一次会话里同时跑两条同名指令也可能，认 commandId 才稳。
+    for (let i = rows.length - 1; i >= 0; i--) {
+      if (rows[i]?.role === 'command' && rows[i].commandId === patch.commandId) {
+        rows[i].kind = patch.kind
+        rows[i].text = patch.text
+        return true
+      }
+    }
+    // 只看见 done、没看见 run（窗口从中间截断、或者插件是中途起来的）：
+    // 补一条没有名字的记录，**不能丢**——用户会看到结果却不知道是哪条指令。
+    // name 留空，界面按「指令」显示即可。这条只在重放里可能出现。
+    rows.push({
+      role: 'command', commandId: patch.commandId, name: '', args: '',
+      kind: patch.kind, text: patch.text, timestamp: typeof event?.time === 'number' ? event.time : null,
+    })
+    return true
+  }
+  return false
+}

package/lib/history.js

@@ -0,0 +1,72 @@
+/**
+ * 把一个会话**已经跑完的历史**重放成手机上要显示的那一串。
+ *
+ * 为什么需要它：手机能点开**全部**会话（一个工作区里常有上百条），而插件手里那份
+ * 记录只有「它在场时看见过的事件」——重启前跑过的、在电脑上开的会话，点进去是空的。
+ * 用户 2026-09-25 提的要求是：点开一个会话，就该看到它之前的每一轮。
+ *
+ * 数据来源是 DSH 自己的会话记录（`sessionQuery.readSession`，见 index.js），
+ * 这里只负责把那一串原始事件**重放**成聊天记录。
+ *
+ * **关键：提取器必须和实时那条路是同一个**（`events.js` 的 `createTurnTracker`）。
+ * 两条路各写一套判断的话，「哪条才算最终回答」迟早会走散——一边显示旁白、
+ * 一边显示回答，用户看到的就是同一个会话在两个地方长得不一样。
+ */
+import { createTurnTracker } from './events.js'
+import { foldCommandEvent } from './commands.js'
+
+/**
+ * @param {Array<{type:string, time?:number, data?:any}>} events DSH 的原始事件，**按发生顺序**。
+ * @returns {Array<{role:'user'|'assistant'|'command', text?:string|null, timestamp:number|null,
+ *                  id?:string|null, reason?:string, interrupted?:boolean,
+ *                  commandId?:string, name?:string, args?:string, kind?:string}>}
+ */
+export function replayHistory(events) {
+  const tracker = createTurnTracker()
+  const out = []
+  for (const event of events ?? []) {
+    // 斜杠指令（`command/run` / `command/done`）不是「一轮」，提取器不认它——
+    // 可它确实写在会话记录里，电脑端也确实画在正文里。用和实时那条路**同一个**
+    // 折叠函数（lib/commands.js）接住，两边才不会一个显示「执行中」、一个显示结果。
+    if (foldCommandEvent(out, event)) continue
+    // 会话 id 在这里没有意义：一个会话的日志只会喂给一个 tracker，
+    // 传个固定值就行，不必把 id 一路带进来。
+    const action = tracker.feed('replay', event)
+    if (!action) continue
+    const timestamp = typeof event?.time === 'number' ? event.time : null
+    if (action.kind === 'user') {
+      out.push({ role: 'user', text: action.text, id: action.id ?? null, timestamp })
+    } else {
+      out.push({
+        role: 'assistant',
+        text: action.text,
+        timestamp,
+        reason: action.reason,
+        interrupted: action.interrupted === true,
+      })
+    }
+  }
+  return out
+}
+
+/**
+ * 从重放出来的记录里取最后一条最终回复，做成单帧模式要的那个形状。
+ *
+ * 返回 null 表示「这个会话还没有过最终回复」——那时单帧模式该显示空，
+ * **不能拿用户自己那句话顶上**，也不能拿旁白顶上。
+ */
+export function lastReply(entries, sessionId) {
+  for (let i = (entries?.length ?? 0) - 1; i >= 0; i--) {
+    const m = entries[i]
+    if (m.role !== 'assistant') continue
+    return {
+      text: m.text,
+      sessionId,
+      title: '',
+      timestamp: m.timestamp,
+      reason: m.reason,
+      interrupted: m.interrupted === true,
+    }
+  }
+  return null
+}