dsh-mobile-plugin 0.3.1 → 0.4.1

package/lib/host-compat.cjs

@@ -0,0 +1,120 @@
+'use strict'
+
+/**
+ * 让「官方工具行」跟着运行时换代，而不是跟着本包发版那一刻。
+ *
+ * 提问工具、交付文件工具、目录浏览后端这三个包互相用精确版本咬死，而 `dsh-app-boot` 在
+ * 装载前拿每一行跟运行时对一遍——对不上就整行禁用，现象是手机上「模型说没有这个工具」。
+ * 所以启动时先问运行时那棵树要同代的那一份，拿到就把行的 `name` 换成它的入口绝对路径，
+ * 绕开按裸名解析；拿不到就保持原样，让官方检查去禁用并打印原因。
+ *
+ * 这里只放纯函数：`host.js` 一 import 就 `boot()` 整个宿主，测试碰不得。
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+/**
+ * 预设里那两行的 id 与包名。
+ *
+ * 两个都要：都是官方工具、都精确咬版本、都不在 `dsh-web-app` 的预设里，漏掉一个对应
+ * 能力就会同样安静地消失。
+ */
+const TOOL_ROWS = Object.freeze([
+  Object.freeze({ id: 'tool-ask-user', name: '@deepseek-ai/dsh-tool-ask-user' }),
+  Object.freeze({ id: 'tool-present', name: '@deepseek-ai/dsh-tool-present' }),
+])
+
+/** 无头宿主里被钉成 browse 的目录选择后端；同样精确咬版本。 */
+const DIRECTORY_PICKER_ROW = Object.freeze({
+  id: 'directory-picker-browse',
+  name: '@deepseek-ai/dsh-host-directory-picker-browse',
+})
+
+const ROW_ID = /^(\s*)-\s+id:\s*(\S+)\s*$/
+const ROW_NAME = /^(\s+)name:\s*'([^']+)'\s*$/
+
+/**
+ * 把 `- id: <id>` 紧跟着的那个 `name:` 换成给定值。
+ *
+ * 逐行扫而不是解析 YAML 再序列化：这份预设带着大量解释性注释，解析再写回会把它们和
+ * 空行全洗掉。只认「上一行是目标 id」的 name，同一个包名出现在别处不会被误伤。
+ *
+ * @param {string} source 预设文件内容
+ * @param {Record<string, string>} targets 行 id → 新的 name（入口绝对路径）
+ * @returns {{ text: string, changed: string[] }}
+ */
+function rewriteToolNames(source, targets) {
+  const changed = []
+  let currentId = null
+  const text = source
+    .split('\n')
+    .map(line => {
+      const id = ROW_ID.exec(line)
+      if (id) {
+        currentId = id[2]
+        return line
+      }
+      if (currentId === null) return line
+      const name = ROW_NAME.exec(line)
+      if (!name || targets[currentId] === undefined) return line
+      if (name[2] === targets[currentId]) return line
+      changed.push(currentId)
+      // 单引号是 YAML 的转义形式：值里的 ' 要写成 ''。
+      return `${name[1]}name: '${targets[currentId].replace(/'/g, "''")}'`
+    })
+    .join('\n')
+  return { text, changed }
+}
+
+/**
+ * 把预设目录同步一份到 `outDir`，并把目标行换成本次运行时的入口。
+ *
+ * 每次启动都重写：两份 yml 加起来不到 8KB，而「只在变化时写」要多记一份状态，就多一处
+ * 能不一致的地方。
+ *
+ * @param {string} presetDir 包内 `config/agent-presets`
+ * @param {string} outDir 宿主可写的目标目录
+ * @param {Record<string, string>} targets 行 id → 入口绝对路径
+ * @returns {string} 真正该交给 `agent-presets` roots 的目录
+ */
+function syncPresetDir(presetDir, outDir, targets) {
+  fs.rmSync(outDir, { recursive: true, force: true })
+  fs.cpSync(presetDir, outDir, { recursive: true })
+  if (Object.keys(targets).length === 0) return outDir
+  for (const entry of fs.readdirSync(outDir, { recursive: true, withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.yml')) continue
+    const file = path.join(entry.parentPath ?? entry.path, entry.name)
+    const { text, changed } = rewriteToolNames(fs.readFileSync(file, 'utf8'), targets)
+    if (changed.length > 0) fs.writeFileSync(file, text)
+  }
+  return outDir
+}
+
+/**
+ * 把 patch 层里命中目标的 `name` 换成入口绝对路径。
+ *
+ * 只改 `insert` 里的行：其它形态的 `name` 是断言，与原名相同才会应用，改它等于让整条
+ * patch 被静默跳过。
+ *
+ * @param {Array} patches 已加载的 patch 层
+ * @param {Record<string, string>} targets 包名 → 入口绝对路径
+ * @returns {Array} 新数组，不改原对象
+ */
+function pinInsertedRows(patches, targets) {
+  const swap = (row) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return row
+    const next = targets[row.name] === undefined ? row : { ...row, name: targets[row.name] }
+    if (Array.isArray(next.insert)) return { ...next, insert: next.insert.map(swap) }
+    return next
+  }
+  return patches.map(swap)
+}
+
+module.exports = {
+  TOOL_ROWS,
+  DIRECTORY_PICKER_ROW,
+  rewriteToolNames,
+  syncPresetDir,
+  pinInsertedRows,
+}

package/lib/host-guard.cjs

@@ -3,44 +3,15 @@
 /**
  * 宿主进程级错误边界（crash guard）。
  *
- * ## 为什么要这个模块
+ * DSH 宿主是长驻进程（嵌入桌面版或由 systemd 以 `Restart=on-failure` 托管），任何逃出
+ * 事件循环的异常都会带走整个 DSH。路由层已有 `.catch`，进程层的缺口是两处：
  *
- * DSH 宿主是**长驻进程**：装在桌面版 DSH 里（macOS/Windows），也被 systemd 以
- * `Restart=on-failure` 托管（服务器无头实例）。任何一次真正逃逸到事件循环的异常都会
- * 带走整个 DSH——用户那边表现为「DSH 崩了/插件把 DSH 搞挂了」，而且桌面端连个
- * 插件隔离层都没有，插件的 bug 直接就是宿主的 bug。
+ * 1. 游离的 Promise 拒绝——Node 15+ 默认 throw 并杀进程，插件里大量 fire-and-forget；
+ * 2. 第三方回调（事件流、WS、timer）里抛错，没有 try 包着就是 uncaughtException。
  *
- * 路由层其实已经被兜住了（`dsh-host-webserver` 给每个 handler 挂了 `.catch`），
- * 但**进程层那层兜底在本插件里是完全没有的**：`grep -rn "unhandledRejection\|uncaughtException"`
- * 在整个 dsh-mobile-plugin/ 与 dsh-mobile-server/ 里零命中。缺口正在于：
- *
- *  1. **游离的 Promise 拒绝**。Node 15+ 起 `unhandledRejection` 默认行为是 *throw*，
- *     也就是**杀进程**。插件里凡是 `void someAsync()`（fire-and-forget）的地方，
- *     一个没 catch 的 reject 就等于一次 DSH 崩溃。这类点极多：自动归档轮询、
- *     镜像推送、隧道重连、遥测上报……任意一个后台任务炸一次就够了。
- *  2. **第三方回调里抛错**。宿主事件流、WS 回调、timer 回调抛出的异常没有 try 包裹，
- *     直接升级为 `uncaughtException`。
- *
- * ## 策略：记录 + 保持存活，连续 5 次才退出
- *
- * 单个异常通常不致命（最常见的是"某个后台任务这一次没成"）。一刀切退出等于把
- * 偶发故障变成必然崩溃；一味吞掉又会掩盖真正的崩溃循环。所以取中间值：
- *
- *  - **记录**：每一条都进内存账本，带时间/类型/消息/是否致命，供 `status()` 暴露
- *    （「及时阻止」的前提是能看见）；
- *  - **保持存活**：`unhandledRejection` 与单次 `uncaughtException` 都只记录并继续跑，
- *    不退出。这把「插件的偶发 bug」和「DSH 崩溃」解耦了；
- *  - **熔断**：只有 `uncaughtException` 计入致命计数，且**必须落在时间窗内**。
- *    超过 `windowMs` 没再犯就重新计数——这样捕获的是「崩溃循环」（秒级连炸），
- *    而不是「跑三个月偶发 5 次」的正常长驻。真正熔断时再主动退出，交给
- *    `Restart=on-failure` / 桌面端重启拉起，拿到一个干净的新进程。
- *
- * ## 为什么把状态机和进程接线拆开
- *
- * `createGuard()` 是纯状态机（时间/日志/退出都注入），测试可以完全确定性地驱动它，
- * 不必真的往 `process` 上挂处理器、也不会在跑测试时把测试进程搞死；
- * `installProcessGuard()` 才是那层薄薄的进程接线。这个拆分是本模块能被守卫测试
- * 覆盖的前提。
+ * 策略：全部记入内存账本并保持存活；只有 uncaughtException 计入熔断，且必须落在时间窗
+ * 内连发到 `fatalCount` 才主动退出，交给 `Restart=on-failure` 拉起。`createGuard()` 是
+ * 纯状态机，`installProcessGuard()` 才是进程接线，拆分是为了能被守卫测试覆盖。
  */
 
 const FATAL_FAULT_COUNT = 5;
@@ -187,9 +158,8 @@ function activeGuard() { return installed; }
 /**
  * 把一个可能抛/可能 reject 的调用包成「永不把异常带出去」的函数。
  *
- * 这是本模块想复用的那一块：插件里大量 fire-and-forget 的调用点（自动归档轮询、
- * 镜像推送、遥测、隧道重连……）都可以直接套一层，再也不必各自 try/catch，
- * 也再也不会有一处忘了 catch 就把 DSH 带走。
+ * 插件里大量 fire-and-forget 的调用点可以套这一层，不必各自 try/catch，也就不会
+ * 因为漏了一处 catch 把 DSH 带走。
  *
  * @param {Function} fn                 原始函数
  * @param {string}   [label]            出错时用于定位的来源名

package/lib/host-patches.cjs

@@ -8,23 +8,12 @@
 /**
  * 摘掉「按裸包名挂载本插件」的 patch 行。
  *
- * `cordis.patch.yml` 里有一行 `- insert: [{ id: dsh-mobile, name: 'dsh-mobile-plugin' }]`，
- * 那是给**桌面端**用的：DSH 的插件管理器把这个包装进
- * `~/.dsh/profiles/<profile>/node_modules`，Loader 从那里按包名解析得到 `lib/index.js`。
+ * `cordis.patch.yml` 里那行 `insert: [{ id: dsh-mobile, name: 'dsh-mobile-plugin' }]` 是
+ * 给桌面端用的：插件管理器把包装进 profile 的 `node_modules`，Loader 从那里按包名解析。
+ * 无头宿主没有那次安装，解析不到包名时 loader 会让整棵插件树加载失败，而不是留一条警告。
+ * 宿主自己用绝对路径另插一行 `mobile-api`，所以这行在这里只有害处。
  *
- * 无头宿主没有那次安装 —— 插件**就是** Loader 正在跑的那个包，没人把它放进
- * `node_modules` —— 于是这一行解析不到。而 loader 对解析失败**不是**留一条警告，是整棵树
- * 加载失败：
- *
- *   dsh-mobile-plugin: boot failed: Error: dsh-mobile-plugin: plugin tree failed to load:
- *   failed to apply loader entry include (cordis:include): failed to import loader entry
- *   dsh-mobile (dsh-mobile-plugin): Cannot find package 'dsh-mobile-plugin'
- *     code: 'ERR_MODULE_NOT_FOUND'
- *
- * （实测：服务器宿主从引入这一行的提交起就再也起不来了。）宿主自己用绝对路径另插一行
- * `mobile-api` 挂载本插件，所以这一行在这里只有害处。
- *
- * 不改 `cordis.patch.yml` 本身：桌面端还要靠它。只在无头宿主装载前从内存里摘掉。
+ * 不改 `cordis.patch.yml` 本身（桌面端还要靠它），只在无头宿主装载前从内存里摘掉。
  *
  * @param {Array} patches 已加载的 patch 层（loadOverlayPatches 的返回值）
  * @param {string} binName 本插件的包名

package/lib/http/routing.js

@@ -3,14 +3,8 @@
 /**
  * 插件 HTTP 路由基建：控制面与移动端两套守卫的共用地基。
  *
- * 这些函数此前是 lib/index.js 里的局部闭包，紧挨着 65 条路由注册写在一起。它们
- * 本身是纯函数（只依赖 req/res），却因为住在 apply() 里而无法单测——而这几条守卫
- * 恰好是最该有测试的地方：它们挡的是「谁能调控制面」「谁能调移动端」，写错一行的
- * 后果是鉴权被绕过而不是某个页面显示不出来。
- *
- * 抽出来单独放一个文件是为了让它们能被直接 require 并喂假 req/res 测试。抽出后
- * 两套守卫并排放在一个文件里，肉眼就能对照出「控制面多挡了跨站与 method，移动端只
- * 挡 token」这个刻意的不对称。
+ * 都是只依赖 req/res 的纯函数，抽到这里才能直接 require 并喂假 req/res 测试。它们挡的是
+ * 「谁能调控制面」「谁能调移动端」，写错一行的后果是鉴权被绕过，不是页面显示不出来。
  */
 
 const net = require('node:net');
@@ -123,29 +117,15 @@ const localOnly = (method, handler) => async (req, res) => {
 
 const readJson = (req) => readJsonBody(req, 256 * 1024).then(body => body || {})
 
-/**
- * 移动端路由守卫：token + 把 handler 抛出的异常统一收成 500 信封。
- *
- * 与 localOnly 的不对称是刻意的：移动端请求本来就要从公网进来，跨站不是它的风险；
- * 它的风险是「没带 token 也能读别人的会话」，所以只校验 token。
- *
- * @param {object} ctx 插件 ctx，透传给 handler
- * @param {(req: object) => boolean} authorized 移动 token 校验，由调用方注入
- * @param {() => void} [note] 通过 token 校验之后叫一声：宿主用它记「手机来过」的时刻，
- *   引导最后一页据此说「手机已经连上了」。**只在校验通过之后叫**，401 那条不算——
- *   否则随便谁打一下也能把面板骗成「连上了」。
- * @returns {(handler: (ctx: object, req: object, res: object) => Promise<unknown>) => (req: object, res: object) => Promise<unknown>}
- */
 /**
  * 移动端路由守卫：token + 协议 v2 信封 + 把 handler 抛出的异常统一收成 500 信封。
  *
  * 与 localOnly 的不对称是刻意的：移动端请求本来就要从公网进来，跨站不是它的风险；
  * 它的风险是「没带 token 也能读别人的会话」，所以只校验 token。
  *
- * **信封的顺序在这里定死**（§8.3(11)）：鉴权（token）→ 验签 → 重放 → 解封请求体 →
- * 业务 handler → 封响应。鉴权放在最前，是因为「这台设备是谁」决定了拿哪把密钥验签；
- * 而鉴权自身失败时回的是明文 401（`e2ee-unknown-device` 之外的一切凭据问题），
- * 因为 App 必须先在解不开信封的情况下读懂它。
+ * 信封顺序定死：鉴权（token）→ 验签 → 重放 → 解封请求体 → 业务 handler → 封响应。
+ * 鉴权在最前，因为「这台设备是谁」决定拿哪把密钥验签；鉴权自身失败回明文 401，
+ * App 必须能在解不开信封时读懂它。
  *
  * @param {object} ctx 插件 ctx，透传给 handler
  * @param {(req: object) => boolean} authorized 移动 token 校验，由调用方注入
@@ -251,8 +231,8 @@ const createGuarded = (ctx, authorized, note = null, extra = {}) => {
             const sealedPayload = sealResponse(req, { statusCode: chosenStatus }, sealed.keys, sealed.req, parsed)
             // **封完直接发，不再 gzip**：`content-encoding` 只能在头出去之前声明，而这个
             // 钩子跑在 `sendJson` 的 `writeHead` 之后，`setHeader` 会被静默忽略 —— 结果
-            // 是「线上是 gzip、头却说 identity」，客户端解不开，报「请求失败 (HTTP 200)」
-            // （2026-10-24 现场）。信封是 base64 密文，外层压缩本来也只省几个百分点；
+            // 是「线上是 gzip、头却说 identity」，客户端解不开，报「请求失败 (HTTP 200)」。
+            // 信封是 base64 密文，外层压缩本来也只省几个百分点；
             // 要省带宽靠载荷裁剪，不靠这一层。
             payload = JSON.stringify(sealedPayload)
           }

package/lib/impl.js

@@ -217,16 +217,14 @@ function pairingPayload(state, lanPort) {
 // 「手机上最近来过没有」同理，住在 `./mobile/activity.cjs`（守卫记、控制面状态读）。
 
 /**
- * 运行时是否自带 `@deepseek-ai/dsh-host-apiproxy`（即 `api-gateway` 那个入口）。
+ * 运行时是否自带 `@deepseek-ai/dsh-host-apiproxy`（`api-gateway` 那个入口）。
  *
- * 从本模块所在位置解析，而不是读 DSH 版本号：桌面端插件装在
- * `~/.dsh/profiles/<profile>/node_modules/dsh-mobile-plugin` 里，那里只有 `ws`，
- * 一路往上也碰不到 DSH 的依赖树（它在 app.asar 里）→ 解析不到 → 用兼容桥；
- * 无头宿主直接跑在插件包里，包内 `node_modules` 有整套 `@deepseek-ai/*` → 解析得到
- * → 用宿主自己那份。解析失败只是「没有」，不该把插件带崩。
+ * 从本模块所在位置解析，而不是读 DSH 版本号：桌面端插件装在 profile 的 node_modules 里，
+ * 往上碰不到 DSH 的依赖树（在 app.asar 里），解析不到就用兼容桥；无头宿主跑在插件包里，
+ * 包内就有整套 `@deepseek-ai/*`，解析得到就用宿主自己那份。解析失败只是「没有」。
  *
- * 这个函数在模块顶层就被 `export const inject` 用了一次，所以它必须是函数声明
- * （提升），不能写成 `const` 箭头函数 —— 那会撞上 TDZ。
+ * 模块顶层就被 `export const inject` 用了一次，所以必须是函数声明（提升），不能写成 `const`
+ * 箭头函数 —— 那会撞上 TDZ。
  */
 function runtimeProvidesApiProxy() {
   try {

package/lib/mirror/pusher.cjs

@@ -3,25 +3,11 @@
 /**
  * 镜像推送调度器：把宿主的会话状态推到中转，手机端才看得到列表与消息。
  *
- * 这 200 行原本是 apply() 里最孤立的一块——它自己一整套状态（recordMirrorPush 的三个
- * 字段、bgQueuePos/bgQueueBusy、按会话单飞的在途表），只通过 tunnelConnected() 和
- * sidecar.pushSync() 与外界打交道，混在装配代码里让 apply() 读不出主线。
+ * 三条不能丢的约束：隧道没连上就不构建快照（否则 503 刷屏，真故障被淹没）；空清单/空快照
+ * 不许广播（「没取到」与「被删光」形状相同，放行会让手机侧整行消失且零报错）；推送成功后
+ * 先 `sessionSignal.bump` 再 `announceSessionsRevision`，顺序反了手机会来取上一份镜像。
  *
- * 两条防线的取舍写在这里，别当成冗余删掉：
- * 1. 隧道没连上就不构建快照——worker 的 `/tunnel/send` 在未连接时直接回 503，旧实现
- *    照推不误，500ms 一个 tick 完整构建五份快照再撞一次 503，宿主日志被
- *    「sidecar facade request failed: 503」刷屏（约 2 行/秒），真故障信号被淹没。
- * 2. 空工作区/空会话快照不许广播——「没取到」和「真被删光」在单份快照上都是
- *    { ok: true, items: [] }，直接放行会让手机侧工作区整行消失、会话全塌进「未分组」，
- *    且中转只附一个 App 不看的 stale 标记，全程零报错。
- *
- * 注意扩展名是 .cjs：包根声明 type=module，而 lib/ 下只有 shared / mobile / relay /
- * routes / http 这几个子目录放了自己的 {"type":"commonjs"}，本目录（lib/mirror/）没有 ——
- * 所以放这里的模块必须是 .cjs，才能被同为 CJS 的 mobile/* 与 shared/* 直接 require。
- *
- * 推送成功后要做两件广播（顺序不能反）：先进 sessionSignal.bump（正文水位，驱动手机补拉
- * 没打开的会话），再 announceSessionsRevision（清单 revision，驱动列表刷新）。镜像先落地、
- * 广播后发出——反过来的话手机会立刻来取，而取的还是上一份镜像。
+ * 必须是 .cjs：包根声明 type=module，而 lib/mirror/ 没有自己的 `{"type":"commonjs"}`。
  */
 
 const path = require('node:path');
@@ -43,12 +29,9 @@ const BG_TICK_INTERVAL_MS = 500;
 /**
  * 没人看的时候，后台 tick 降到这个节拍。
  *
- * 500ms 那条节奏是给「手机正在用」准备的：清单或工作区一变，手机半秒内就该看到。
- * 但宿主一天里大部分时间没人看 —— 那时每 500ms 整轮重建一次清单/工作区，走中转的
- * 还要把快照推过一条隧道，纯属空转。
- *
- * 上限由 sidecar 的快照 TTL 卡着：镜像快照 15s 过期，降频必须明显小于它，
- * 取 5s（= TTL/3，`test/mirror-tick-budget.test.cjs` 钉着这条比例）。
+ * 500ms 是给「手机正在用」准备的：清单或工作区一变，半秒内就该看到。没人看时每 500ms
+ * 整轮重建并推一次纯属空转。上限由 sidecar 的 15s 快照 TTL 卡着，取 5s（= TTL/3，
+ * `test/mirror-tick-budget.test.cjs` 钉着这条比例）。
  */
 const IDLE_TICK_INTERVAL_MS = 5_000;
 /**
@@ -62,21 +45,13 @@ const AUDIENCE_IDLE_MS = 30_000;
 /**
  * 冷会话轮转的最小间隔（清单/工作区都没变时才生效）。
  *
- * 500ms 的 tick 不能省：清单与工作区的内容指纹就是这个节奏读宿主才发现的，
- * App 侧「镜像正常最多旧 500ms」的新鲜度契约（lib/shared/fresh-request.js、
- * lib/relay/lan-proxy.js 的 ?fresh=1、lib/mirror-snapshot.cjs 的 15s TTL）也押在它上面。
+ * 500ms 的 tick 不能省：清单与工作区的内容指纹就是这个节奏读宿主才发现的，App 侧
+ * 「镜像正常最多旧 500ms」的新鲜度契约也押在它上面。
  *
- * 但 tick 里最贵的那一段是轮转冷会话：buildSessionData 传进去的是合成 summary
- * （updatedAt = Date.now()，running = true），指纹每次都不同 ⇒ lib/mobile/session-mirror.js
- * 那层 2 分钟缓存永远命中不了，于是**每一轮都真的去宿主拉 200 条消息**，外加统计投影
- * （无缓存）与模型目录；拉完算指纹时又常常因为内容逐字段相同被判重跳过。而「冷会话」
- * 按定义（isHighPriority 之外：没在跑、5 分钟没动过）正文不可能变，每 500ms 重做一遍
- * 纯属白烧宿主 CPU/内存 —— 真机事故里宿主被内存压力拖慢时，这一路正是 504 的主要来源。
- *
- * 所以：清单或工作区指纹一变就照旧立刻整轮重建并推送（新鲜度分毫不动），两者都没变时
- * 轮转退到 5s 一次，它只剩「把还没热身过的冷会话正文补进中转镜像」这一个作用
- * （N 个冷会话最迟 N × 5s 补齐）。5s 必须明显小于 lib/mirror-snapshot.cjs 的
- * MIRROR_SNAPSHOT_TTL_MS（15s），否则 sidecar 的镜像快照会被判过期。
+ * 但 tick 里最贵的是轮转冷会话：合成 summary 让每轮指纹都不同，session-mirror 的缓存
+ * 永不命中，每 500ms 真的去拉 200 条消息，而冷会话的正文按定义不会变。所以两个指纹都没变
+ * 时轮转退到 5s 一次，只留「把冷会话正文补进镜像」这一个作用。5s 必须明显小于
+ * `MIRROR_SNAPSHOT_TTL_MS`（15s），否则 sidecar 的镜像快照会被判过期。
  */
 const BG_COLD_ROTATE_MIN_INTERVAL_MS = 5000;
 const MAX_CONCURRENT_SESSION_BUILDS = 2;
@@ -233,19 +208,10 @@ function createMirrorPusher(deps) {
   /**
    * 「这些会话的正文又长了」的唯一广播点。
    *
-   * 广播的**不是**「中转镜像里有新正文」，而是「本机这份会话的正文到了这个水位」——
-   * 手机拿水位和自己的缓存一比就知道该不该增量拉一次（走局域网直连时读的就是本进程）。
-   * 所以这条信号与「镜像有没有推成功」是两件事，不能绑在一起：
-   *
-   *  - 隧道断开（`!tunnelConnected()`）或纯局域网模式下 pushMirrorPayload 会短路，旧实现
-   *    把广播放在成功分支里，于是**一帧水位都不发** —— 手机侧非打开会话的「有新内容」
-   *    提示只能靠 60s 兜底轮询或用户点开，正好是「点开对话要等一会儿才看到内容」的来源。
-   *  - 内容未变（指纹相同）时同样不推，但快照里的水位可能已经涨过（上一帧失败过、或
-   *    这一帧由 pushMirror 用更新的事件重建）—— 这里补一次广播是幂等的。
-   *
-   * 幂等由 sessionSignal 保证（同会话水位不变或更低时不广播），所以即使在每 500ms 的
-   * tick 上调用也不会变成刷新风暴。顺序上「先落地后广播」在局域网下天然成立：正文读的
-   * 就是本进程同一份会话历史。
+   * 广播的不是「镜像里有新正文」，而是「本机这份会话的正文到了这个水位」——手机拿水位和
+   * 自己的缓存一比就知道该不该增量拉。所以它与「镜像有没有推成功」是两件事：隧道断开或
+   * 纯局域网模式下推送会短路，广播绑在成功分支里就一帧水位都发不出去，非打开会话只能靠
+   * 60s 兜底轮询。内容没变时补一次广播是幂等的，sessionSignal 保证水位不变或更低时不发。
    */
   const announceSessionActivity = (messages) => {
     if (!messages || typeof messages !== 'object') return;
@@ -331,11 +297,8 @@ function createMirrorPusher(deps) {
   /**
    * 镜像清单本身的规模（自检台账用）：会话总数、其中活跃的、其中子会话。
    *
-   * 这是插件侧能**诚实**报出的那部分规模——「宿主内存里挂着多少会话、正文占多少」插件看不到
-   * （它住在宿主进程里，没有独立视角，见 lib/mobile/self-check.cjs 的口径段）。清单每 tick 都
-   * 在重建，顺手记三个计数不额外花销。
-   *
-   * 只在真拿到清单时更新：拿不到时保留上一次的读数（连带 `at`），与「清单突然变成 0」区分开。
+   * 这是插件侧能诚实报出的那部分规模：宿主内存里挂着多少会话、正文占多少，插件看不到。
+   * 只在真拿到清单时更新，拿不到时保留上一次读数，与「清单突然变成 0」区分开。
    */
   let mirrorListSessions = 0;
   let mirrorListActiveSessions = 0;
@@ -402,20 +365,12 @@ function createMirrorPusher(deps) {
   /**
    * 构建一个会话的镜像数据（正文快照 + 统计投影 + 模型列表）。
    *
-   * `summary` 必须是**清单里的那一行**（或它的 Promise）：`session-mirror.js` 的后台缓存
-   * 指纹就是 `updatedAt:running|idle:limit`，旧实现硬塞 `{ updatedAt: Date.now(), running: true }`，
-   * 于是指纹每次都不同、2 分钟 TTL 永不命中。`running` 如实取清单值：高优先判定
-   * （isHighPriority）用的就是这个字段，不能在这里改口径。
+   * `summary` 必须是清单里的那一行（或它的 Promise）：`session-mirror.js` 的后台缓存指纹
+   * 就是 `updatedAt:running|idle:limit`，硬塞 `Date.now()` 会让 2 分钟 TTL 永不命中。
+   * `running` 如实取清单值，高优先判定用的就是它。传 Promise 是为了与清单构建并行。
    *
-   * 允许传 Promise 是因为调用点通常与清单构建并行（见 pushSessionNow）：为了拿一个真实的
-   * updatedAt 把「每条会话事件都走」的热路径改成串行两跳不划算。
-   *
-   * `reuseCache` 默认 true，但**事件驱动路径必须传 false**：那个缓存只认「宿主抬了
-   * updatedAt」这一种内容变化。一条新消息落盘而清单摘要还没变（或宿主不按消息抬
-   * updatedAt）时，缓存会把上一份正文当成这一份发出去 —— device-session-activity 的守卫
-   * 钉的正是这个场景（新消息必须广播新水位，见 test/device-session-activity.test.cjs）。
-   * 实现方式是 session-mirror 的 `noCache`（既不读也不写缓存），不是伪造 updatedAt。
-   * 收益落在「没人动的冷会话轮转」：那里每 5s 重建 200 条正文才是成本大头。
+   * `reuseCache` 默认 true，但事件驱动路径必须传 false：缓存只认「updatedAt 抬了」这一种
+   * 变化，新消息落盘而摘要未变时会把上一份正文当成这一份发出去（`noCache` 既不读也不写缓存）。
    */
   const buildSessionDataUnlocked = async (sessionId, summaryOrPromise, { reuseCache = true } = {}) => {
     const summary = summaryOrPromise && typeof summaryOrPromise.then === 'function'
@@ -425,19 +380,13 @@ function createMirrorPusher(deps) {
     // 缓存指纹，不影响正文内容本身。
     const updatedAt = (summary && summary.updatedAt) || Date.now();
     /**
-     * 子会话的正文**刻意不建**（2026-10-19）。
-     *
-     * 普通历史接口读子会话会被宿主按 durable parent address 拒掉
-     * （`session/agent-busy: subagent Sessions require their durable parent address`），
-     * 而镜像这份正文手机本来就用不到：手机打开子代理读的是子代理那条专用通道（带父会话
-     * 地址与 mode，见 lib/mobile/subagents.js 的文件头）。以前每次都照读、每次都被拒，
-     * 于是 5 秒一次的冷轮转里固定夹着一次注定失败的读取，`skippedBodies` 一路涨
-     * （真机实测 4 分钟 408 → 451），日志里那条 skip 也永远说不清到底哪坏了。
+     * 子会话的正文刻意不建：普通历史接口读子会话会被宿主按 durable parent address 拒掉
+     * （`agent-busy: subagent Sessions require their durable parent address`），而手机打开
+     * 子代理读的是专用通道（见 lib/mobile/subagents.js），这份正文本来就用不到。
      *
-     * 这里提前认出清单行上的 `origin === 'subagent'` 就不发那次请求，且 **skipReason 留空**：
-     * 它不是失败，不该进 `skippedBodies` 那本故障账。清单行本身照旧推给手机（App 靠行上的
-     * origin/parentSessionId 认子代理），stats/models 照旧构建，所以镜像载荷的形状与既有的
-     * 「正文缺席」那条路径完全一致。
+     * 提前认出清单行上的 `origin === 'subagent'` 就不发那次请求，且 skipReason 留空：它不是
+     * 失败，不该进 `skippedBodies`。清单行、stats、models 照旧构建，载荷形状与「正文缺席」
+     * 那条路径一致。
      */
     if (summary && summary.origin === 'subagent') {
       const [stats, models] = await Promise.all([
@@ -683,10 +632,9 @@ function createMirrorPusher(deps) {
         // 清单会一直挂到 15s TTL 过期，手机上已删的会话最长还能看到十几秒；而且这条路径
         // 完全不记账，运维看不出镜像为什么不动。
         //
-        // 跨包契约：中转侧对「空覆盖非空」有同口径保护，只认 emptyConfirmed === true 的
-        // 空清单（dsh-mobile-server/lib/mirror-state.js 的 installMirror，谓词与
-        // dsh-mobile-server/server.js:110 一致）。这里推的就是 buildSessionsResponse 的
-        // 原样 body，天然带这个字段。
+        // 跨包契约：中转侧对「空覆盖非空」有同口径保护，只认 emptyConfirmed === true 的空
+        // 清单（中转的镜像状态里同一条谓词）。这里推的是 buildSessionsResponse 的原样 body，
+        // 天然带这个字段。
         const workspacesBodyEmpty = await workspaces.buildWorkspacesBody(ctx).then(observeWorkspaces);
         const wsBlockedEmpty = guardWorkspaces(workspacesBodyEmpty);
         if (wsBlockedEmpty) {

package/lib/mirror-snapshot.cjs

@@ -1,33 +1,15 @@
 'use strict'
 
-// 桌面推送的「移动端镜像快照」新鲜度判定。这一个小模块独立存在，是为了能被 test/ 直接驱动
-// （与 reconnect-scheduler.cjs 同样的做法），而不是把判定散在 sidecar 的读取函数里。
+// 桌面推送的「移动端镜像快照」新鲜度判定。独立成模块是为了能被 test/ 直接驱动。
 //
-// 背景（真机缺陷）：sidecar 把 /sessions、/workspaces 两个高频读请求直接从这份镜像回，
-// 不去打扰主进程。但镜像**只能靠隧道推来**：
-//   - host 侧 pushMirrorPayload 在 `!tunnelConnected()` 时直接短路（lib/index.js:132）；
-//   - 它依赖的 sidecar `/tunnel/send` 自己也要求 `tunnel && tunnel.connected`，否则 503
-//     （sidecar-facade-worker.cjs:186-190）。
-// 于是「中转断掉、局域网仍然健康」时快照被永久冻结在最后一个版本，而 snapshotRead 依旧把
-// 它当权威读：新建的会话/工作区在 App 里**永远不出现**。实测证据（Mac 宿主，kill 掉中转后
-// 走局域网新建并发送）：
-//   POST /session/new → session-1c9b048a-…，POST /session/send → {"ok":true,"accepted":true}
-//   GET /sessions    → count 9（与 kill 之前一模一样），新会话 absent，+70s 仍 absent
-//   GET /app         → 设备侧同样看不到
-//   GET /session/messages?sessionId=<新的> → 能读到 user 'SNAPSHOT-STALE-1'
-// 最后一条说明回源主进程的通道是好的（快照里没有这个 sessionId 就自然回源），坏的只是
-// 「列表类读被冻结的镜像顶掉」。
-//
-// 修法：把镜像当**短时代读缓存**，不是权威存储——超过 TTL 就当作缺失，让调用方回源主进程。
-// 隧道连着时快照每几百毫秒就被重推一次（processBgQueue 的 500ms tick），所以 15s 足够长，
-// 快路径照常生效；一旦中转断开，最多 15s 后所有读都回源，数据重新变准。
+// 镜像只是**短时代读缓存**，不是权威存储：快照只能靠隧道推来，中转断开而局域网仍健康时
+// 它会冻在最后一个版本，列表读于是把新建的会话/工作区一直藏住。超过 TTL 就当作缺失，
+// 让调用方回源主进程。隧道连着时快照每几百毫秒重推一次，15s 足够长，快路径照常生效。
 
 const MIRROR_SNAPSHOT_TTL_MS = 15_000
 
-// 只有带可信时间戳 `at` 且在 TTL 内的快照才可用。
-// 缺 `at` 的载荷一律按陈旧处理：host 的三个推送点（lib/index.js:212 / :267 / :302）都会写
-// `at: Date.now()`，没有 `at` 说明这不是预期的镜像载荷，宁可回源也不要拿它当权威。
-// 时间戳来自同一台机器，不存在跨机时钟偏移，所以未来时间戳按不可信处理。
+// 只有带可信时间戳 `at` 且在 TTL 内的快照才可用。缺 `at` 的载荷按陈旧处理：预期的镜像载荷
+// 一定写了 `at`，没有就说明来路不对，宁可回源。时间戳来自同一台机器，未来时间戳按不可信处理。
 function isMirrorSnapshotFresh(snapshot, now = Date.now()) {
   if (!snapshot || typeof snapshot !== 'object') return false
   const at = snapshot.at

package/lib/mobile/agent-presets.js

@@ -1,34 +1,14 @@
 'use strict';
 
 /**
- * 移动端「Agent 预设管理」API：把桌面端设置页里那个预设管理分区补齐到手机上。
+ * 移动端「Agent 预设管理」API：把桌面端设置页的预设管理分区补齐到手机上。
  *
- * 桌面端由 dsh-client-ui-agent-preset 渲染四个表层，本仓库此前只补了前三个：
- *  1. 设置里的一行 / 新建会话芯片  → 手机：**已下线**。App 侧曾有一颗 composer 的
- *     AgentPresetChip（list + select），现已整颗删除 —— 手机端一律吃宿主默认档，
- *     `POST /session/select-agent-preset` 路由也一并删除（消费端没了就是死路由）。
- *  2. 会话标题旁的只读标签        → 手机：随 1 一起下线
- *  3. 名单本身                    → 手机：GET /agent-presets
- *  4. **管理分区**：名单卡片 + 只读查看器 + 复制对话框 + 删除确认
- *     —— 这才是现在手机上唯一与预设有关的界面（app 的 PresetManager）。
+ * 手机端只保留管理分区（app 的 PresetManager）：桌面那边设置里的一行与新建会话芯片已下线，
+ * 手机一律吃宿主默认档。三条路由都只转发宿主的 agentPreset 域：read / copy / remove。
  *
- * 三跳接口（都只是转发宿主的 agentPreset 域，转发函数在 lib/mobile/rpc.js，
- * 与会话域的 callSessions 住在一起）：
- *  - POST /agent-presets/read   { agentPreset }               → agentPreset.read
- *  - POST /agent-presets/copy   { from, agentPreset, name? }  → agentPreset.copy
- *  - POST /agent-presets/remove { agentPreset }               → agentPreset.remove
- *
- * 语义按宿主原文透传，不在这里自作主张：
- *  - copy 是「整份复制」，标识符会成为目录名且事后无法更改；宿主自己会重校验 id
- *    规则与重名（PresetExistsError → agent-preset-invalid），这里只做便利检查。
- *  - remove 只对 user 预设有效：随附预设宿主回 agent-preset-read-only，删不掉。
- *  - openDocument 不做。它打开的是**宿主机器**上的目录（与 host.openPath 同性质），
- *    手机点了也看不见；桌面端在没有打开器时（hasDocument:false）本来就是把目录
- *    当文本显示，手机端照此办理即可，不需要这条 RPC。
- *
- * 宿主的失败对象是「code + details」：not-found 带 available[]、read-only 带 reason、
- * invalid 带 reason（可能是 id 非法，也可能是重名），都不是给用户看的文案；
- * 按 code 说中文，同时把原文留在 details.hostMessage 里备查。
+ * 语义按宿主原文透传：copy 是整份复制，标识符成为目录名且事后无法更改；remove 只对 user
+ * 预设有效（随附预设回 agent-preset-read-only）。宿主的失败对象是 code + details，按 code
+ * 说中文，原文留在 details.hostMessage。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');