dsh-mobile-plugin 0.4.0 → 0.4.1

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');

package/lib/mobile/approvals.js

@@ -3,40 +3,17 @@
 /**
  * 手机端审批桥（DSH 0.2.x）。
  *
- * ≤0.1.x 的宿主把审批当成 apiProxy 事件流上的 server-request：
- * `{rpcId, payload:{type:'approval/requested', approvalId, toolName, reason}}`，手机凭**帧级
- * rpcId** 回答（`/approval/respond` 的 rpcId 就是宿主 `pendingApprovals` 表的键）。0.2.x
- * 把 apiProxy 整个删了：一次审批 = 会话日志里的 `approval/asked` / `approval/decided` 事件
- * 对 + 一个**进程内** waterfall 钩子 `approval/request`（`dsh-user-approval` 发起，
- * `dsh-api-remotes` 把它转给桌面窗口那类 owner 连接，`dsh-acp` 也接同一个钩子）。
- * 帧级 rpcId 就此消失，而 App 的审批面板**刻意**只认带 rpcId 的帧（不给一个按了必然 409
- * 的按钮），于是「桌面有卡、手机上一片空白，连一条 409 都没有」。
+ * 0.2.x 删掉了 apiProxy，审批变成会话日志里的 `approval/asked` / `approval/decided` 事件对
+ * 加一个进程内 waterfall 钩子 `approval/request`，帧级 rpcId 就此消失，而 App 的审批面板
+ * 只认带 rpcId 的帧。这里按新形状把那半条通道补起来，App 契约一行不改：听 `approval/asked`
+ * 自己铸 rpcId 推卡，同时挂 `approval/request` 把手机挂成候选人，`/approval/respond` 按
+ * rpcId 找到挂起项把结论交回钩子。
  *
- * 这里按 0.2.x 的形状把那半条通道补起来，**手机端契约一行不改**（App 仍然收
- * `approval/requested` + 帧级 rpcId，仍然 POST `/approval/respond`）：
+ * 钩子必须 prepend：宿主自己的转发器在桌面窗口开着时会一直等桌面回答、不调用 `next()`，
+ * 老实排在注册顺序后面等于「桌面开着时手机永远收不到」。
  *
- *   1. 听 `session/event` 的 `approval/asked`：宿主在发起审批前**必写**这条事件（决定走
- *      哪条回答通道都不影响它），本桥据此铸一个自己的 rpcId 并把卡推给正在看这个会话的
- *      手机。approvalId 直接用宿主自己的 id —— App 靠它把 `approval/decided` 对上、自动
- *      收掉那张卡。
- *   2. 听 `approval/request` 钩子（**prepend**，见下）：把这台手机挂成候选人。手机没在看
- *      这个会话时与下游竞速：下游（桌面窗口 / ACP / 宿主默认的 fail-closed）照旧拿到请求、
- *      卡片照旧出现，手机答得早就用手机的，桌面答得早就用桌面的，输的那张卡由结算帧收掉。
- *      手机**正在看**这个会话时则不转发，由手机独家作答 —— 桌面那张卡挂在被转发的请求上，
- *      本桥没有替它收尾的口子，转发出去、手机先答，桌面那张就永远悬着（2026-10-23，
- *      与提问桥同一条坑）。
- *   3. `/approval/respond` 拿 rpcId 找到挂起项，把结论交回钩子 —— 这才是真正让 agent
- *      继续往下跑的那一步。
- *
- * ⚠️ 钩子上**没有**宿主 id（既没有 approvalId 也没有 rpcId），而且它和 `approval/asked`
- * 谁先到取决于宿主的派发顺序（事件在 `request()` 里先 append、钩子随后派发，但两者都走
- * 微任务）。所以两个来源共用一张挂起项表：先到的建项，后到的补字段（事件补真实
- * approvalId，钩子补 displayReason 与 signal）。卡片在任一路径上都不等对方。
- *
- * ⚠️ 为什么必须 prepend：宿主自己的转发器（`dsh-api-remotes`）在桌面窗口开着时会一直等
- * 桌面回答、**不调用 next()**，而且那些核心包必然先于本插件装载。老实按注册顺序排在后面
- * 等于「桌面开着时手机永远收不到」，正是这次要修的现象。prepend 是本桥能生效的前提，
- * 不是优化。
+ * 钩子上没有宿主 id，且与 `approval/asked` 的到达顺序不定，所以两个来源共用一张挂起项表：
+ * 先到的建项，后到的补字段。
  */
 
 const { randomUUID } = require('node:crypto');
@@ -266,14 +243,12 @@ function bindRequest(entry, request) {
 /**
  * 挂起这条请求直到有人给结论。
  *
- * 传了 `next` 就与下游竞速（手机没在看这个会话时的路径）：`next()` 一调，桌面窗口那张卡
- * 照旧出现。手机答得早就用手机的；下游答得早就用下游的 —— 谁先给结论谁算数，输的那张卡
- * 由结算帧收掉。两边都没人答时这里会一直挂着，和今天宿主自己的行为一致（审批本来就等人工）。
+ * 传了 `next` 就与下游竞速：`next()` 一调，桌面窗口那张卡照旧出现，谁先给结论谁算数，
+ * 输的那张卡由结算帧收掉；两边都没人答就一直挂着。
  *
- * **不传 `next`（手机正在看这个会话）就是手机独家作答**：不往下游转发，桌面从源头就不弹卡
- * ——桌面那张卡挂在「被转发的请求」上，而本桥没有替那条请求收尾的口子（收尾权在宿主网关
- * 手里），手机答完它只会永远悬着，与提问桥同一条坑（2026-10-23）。独家作答后结论照常走
- * `approval/decided` 落进会话记录，桌面看得到裁决结果，只是没有可点的卡。
+ * 不传 `next`（手机正在看这个会话）就是手机独家作答：不往下游转发，桌面从源头就不弹卡。
+ * 桌面那张卡挂在被转发的请求上，本桥没有替它收尾的口子，转发出去手机先答，它只会永远
+ * 悬着。独家作答后结论照常走 `approval/decided`，桌面看得到裁决结果。
  */
 function holdForPhone(entry, next) {
   const downstream = next === undefined
@@ -369,12 +344,11 @@ async function handleApprovalRespond(ctx, req, res) {
 }
 
 /**
- * 把结论交回旧通道的 `ctx.apiProxy.respond`，**Promise 与同步对象两种返回都收**。
+ * 把结论交回旧通道的 `ctx.apiProxy.respond`，Promise 与同步对象两种返回都收。
  *
- * 两条通道形态不同：0.1.x 的真 apiProxy 回 Promise，0.2.x 的兼容桥
- * （`mobile/host-bridge.js`）回同步的 `{result:{ok:false,error:{code:'host-unsupported'}}}`——
- * 同步对象上没有 `.catch`，早先直接链 Promise 会在 0.2.x 抛 TypeError、被路由守卫兜成 500。
- * 抛错与「通道说不认」一律折算成 null，调用方据此如实回 409。
+ * 两条通道形态不同：0.1.x 的真 apiProxy 回 Promise，0.2.x 的兼容桥回同步对象。同步对象上
+ * 没有 `.catch`，直接链 Promise 会抛 TypeError 被路由守卫兜成 500。抛错与「通道说不认」
+ * 一律折算成 null，调用方据此如实回 409。
  */
 async function respondViaLegacyProxy(ctx, message) {
   const proxy = ctx && ctx.apiProxy;

package/lib/mobile/archive-clean.js

@@ -1,18 +1,14 @@
 'use strict';
 
 /**
- * 移动端「清理所有已归档的对话」：按宿主归档集合确定清理范围，把它们排进待删队列。
+ * 移动端「清理所有已归档的对话」：按宿主归档集合确定范围，把它们排进待删队列。
  *
- * 以 workspace.list 的 archivedSessionIds 为清理范围，不用可能过时的列表状态缩小范围；
- * 请求必须显式带 confirm: true —— 磁盘删除不可恢复，手机端「少点一次」不值得把它变成滑一下就没了的动作。
+ * 范围取 workspace.list 的 archivedSessionIds，不用可能过时的列表状态缩小范围；请求必须
+ * 显式带 confirm: true，磁盘删除不可恢复。
  *
- * **这里不删磁盘**：只把 id 排进 session-cleanup.cjs 的待删队列，日志留到宿主下次启动时删
- * （见那个文件的 deleteQueuedArchivedSessions）。宿主没有「删除会话」接口，进程活着的时候
- * 它随时可能去打开那些文件 —— 文件不在就是一次未捕获的 ENOENT，宿主整个退出、桌面端闪退
- * （2026-10-20 真机现场）。本进程只把 id 压进删除集，让手机列表立刻看不到它们。
- *
- * 也**不擦宿主的归档集合**：进程里擦会把桌面端快照里那些其实已经没有日志的行放回正常列表。
- * 归档集合的收尾同样在宿主启动时做，见 pruneOrphanedArchivedSessionsOnce。
+ * 这里不删磁盘，也不擦宿主的归档集合：只把 id 排进 session-cleanup.cjs 的待删队列，由宿主
+ * 下次启动时删。活着的宿主随时可能去打开那些文件，文件不在就是一次未捕获的 ENOENT，会带走
+ * 整个进程。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
@@ -26,16 +22,11 @@ const { queueArchivedClearIds } = require('../session-cleanup.cjs');
 /**
  * 清理前这次补采的预算。
  *
- * 统计页那次只给 `DEFAULT_BUDGET_MS`（1.5 秒）是为了别让用户点开统计转好久；清理是
- * 不可恢复的删除，值得多等几秒把账补全。上限卡在 App 单发请求的 8 秒总预算之内
- * （`app/src/api/core.ts` 的 `REQUEST_TIMEOUT_MS`），否则手机先报超时、清理由这边照旧
- * 执行，用户会以为没成功。
- *
- * 同时这次补采跳过「最后一句」预览（`skipPreview`）：那一步要读会话日志，是整轮里
- * 最重的一趟。删日志前先把数字记住，比给即将消失的卡片多留一行摘要重要。
+ * 统计页只给 1.5 秒是为了别让用户转好久；清理是不可恢复的删除，值得多等几秒把账补全，
+ * 但不能超过 App 单发请求的 8 秒总预算，否则手机先报超时、这边照旧执行。
  *
- * 极端多的归档（几千条）仍可能到点停手 —— 彻底兜住要把补采挪到请求之外，那是另一套
- * 生命周期；这里先把「几百条」这个真实量级覆盖掉，不让它再沿用统计页的 1.5 秒。
+ * 这次补采跳过「最后一句」预览：那一步要读会话日志，是整轮最重的一趟。删日志前先把数字
+ * 记住，比给即将消失的卡片多留一行摘要重要。
  */
 const CLEAR_ARCHIVED_COLLECT_BUDGET_MS = 6_000;
 

package/lib/mobile/attachments.js

@@ -3,53 +3,28 @@
 /**
  * 图片归一：会话历史存的是 `{type:'image', attachment}` 而不是内联字节。
  *
- * 宿主事件里图片可能出现在四处：message/content、inserted 上下文项、
- * assistant chunk 的 block，以及更深的嵌套 content。全部在这里归一，
- * 这样历史与 SSE 暴露给手机端的图片形状是同一个。
+ * 宿主事件里图片可能出现在四处：message/content、inserted 上下文项、assistant chunk 的
+ * block，以及更深的嵌套 content；全部在这里归一，历史与 SSE 暴露给手机的图片形状才一致。
  *
- * **默认（引用模式 `opts.referencesOnly`）不取字节**：图片块原样留着 `attachment`
- * 引用，由 history-derive 投影成 `{mediaType, name?, attachmentId}`，手机端要画的时候
- * 按 attachmentId 单张去取（`/session/attachment`）。此前这里把每张图都换成内联 base64，
- * 一页 200 条带十几张截图的响应接近 10MB，每次进会话都要重传一遍。
+ * 默认（`referencesOnly`）不取字节：图片块留着 `attachment` 引用，由 history-derive 投影成
+ * `{mediaType, name?, attachmentId}`，手机按 attachmentId 单张去取。每张都内联 base64 会把
+ * 一页 200 条带截图的响应推到近 10MB。只有显式 `referencesOnly: false` 才取回字节，取不到
+ * 的打 `dataUnavailable` 标。
  *
- * 只有显式传 `referencesOnly: false` 时才回到「经 session attachment RPC 取回字节」的
- * 老行为；取不回字节的块打 `dataUnavailable` 标（语义不变，见 dataUnavailableBlock）。
- *
- * 另外一类图片在正文里：`![](/abs/path.png)` 这种指向**宿主本机文件**的写法
- * （本机绝对路径、file://、~）在手机上取不到字节，也会被 App 当成非 http 图片降级成字面
- * markdown。这里顺手按同一形状内联成 data URI（实现与预算见 local-images.js）。
- * 这条与附件引用是两件事：它走的是正文里的路径、没有 attachmentId，预算与行为保持原样。
+ * 正文里 `![](/abs/path.png)` 这类指向宿主本机文件的写法另有内联（见 local-images.js），
+ * 与附件引用是两件事：它没有 attachmentId。
  */
 
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const { inlineTextImages, createTextImageBudget } = require('./local-images.js');
 
-/**
- * Resolve durable image references before exposing messages to mobile clients.
- *
- * Session history stores `{type:'image', attachment}` rather than inline bytes.
- * By default (`referencesOnly`) the block is left as a reference and the mobile
- * client fetches the bytes per attachment (`/session/attachment`); no host RPC
- * happens on this path at all. Pass `referencesOnly: false` for the legacy
- * inline-bytes shape.
- *
- * Host events can carry content in several places: message/content, inserted
- * context items, or an assistant/chunk block. Keep this normalization here so
- * history and SSE expose the same image shape to mobile clients.
- *
- * Text blocks additionally get local-file image syntax inlined as data URIs
- * (see local-images.js); `opts.budget` is a shared per-response budget so one
- * paged history response or mirror snapshot stays bounded.
- */
 /**
  * 取不到字节的图片块：原样留着，只加一个标记。
  *
- * 这里**绝不能抛，也绝不能返回 null**：resolveBlock 的结果会直接摊进整段历史响应或
- * 一整帧 SSE，一个 null/异常会让整页消息一起挂掉（见 dev-map A3-33 的刻意设计）。
- * 加标记是因为「附件取不到」和「这条消息本来就没有这张图」在 App 侧长得一样（都只有
- * attachment 没有 data），不加标记就只能跟着静默消失——用户既不知道有过一张图，
- * 也没有任何重试入口。
+ * 这里绝不能抛，也绝不能返回 null：结果会直接摊进整段历史响应或一整帧 SSE，一个 null
+ * 或异常会让整页消息一起挂掉。加标记是因为「附件取不到」和「本来就没有这张图」在 App 侧
+ * 长得一样，不加标记就只能静默消失，用户也不知道有过一张图。
  */
 function dataUnavailableBlock(block) {
   return { ...block, dataUnavailable: true };

package/lib/mobile/channels.js

@@ -3,35 +3,15 @@
 /**
  * 移动端「渠道管理」API：列出这台宿主上的渠道，并增删「本机自建」那一类。
  *
- * ## 两类渠道，只有一类能改
+ * 判据不是「谁建的」，而是这条 provider 在不在 `llm-pi-ai` 的 `providers` 里：在 = 本机配置
+ * 的、可增删（设置走 `settings.mutate`，Key 走 `credentials.set` / `unset`）；不在 = 别的
+ * 插件提供的、只读，移动端一个写操作都不做。
  *
- * 手机上的模型目录（`/session/models`、`/llm/models`）把两种来源混在一起：
- *  - **插件 / 宿主注册的提供方**：账号登录、渠道开关都由它自己的插件说了算
- *    （免费模型插件那十几家、官方 DeepSeek 等）。移动端**一个写操作都不做**——
- *    那不是我们的渠道，改它就是越界。App 那边只保留「本机显示 / 不显示」的开关。
- *  - **本机自建渠道**：`llm-pi-ai` 设置命名空间里 `providers` 下的每一条路由
- *    （协议 + 地址 + 一把 Key + 模型清单）。桌面端免费模型面板的「添加渠道」写的
- *    就是这一层，所以手机照同一份口径做：`settings.mutate` 按路径 set / unset，
- *    凭据走 `credentials.set` / `unset`。
+ * 不读桌面面板另存的那份自建渠道元数据：那是另一个插件的私有状态，两个进程抢同一个文件
+ * 只会写出半截。代价是两边列表的标记会对不上，但真源都是 `llm-pi-ai` 的路由表。
  *
- * 判据不是「谁建的」，而是**这条 provider 在不在 `llm-pi-ai` 的 providers 里**：
- * 在 = 本机配置的、可增删；不在 = 别的插件提供的、只读。所以用户手写在
- * `cordis.patch.yml` 里的 pi-ai 路由也会被列成可删——那是他自己机器上的配置，
- * App 在删除前会二次确认并写出渠道名与地址。
- *
- * ## 为什么不用「免费模型插件的元数据」
- *
- * 桌面面板另存了一份 `$DSH_HOME/our-free-model/custom.json`（描述、介绍、关掉的模型）。
- * 手机不读也不写：那是另一个插件的私有状态，两个进程抢同一个文件只会写出半截。
- * 代价是手机上删掉的渠道，桌面面板的「自建渠道」列表里会显示成「路由缺失」；反过来
- * 手机上建的渠道，桌面面板不会把它当成自己建的。两边都不影响模型选择器——真源是
- * `llm-pi-ai` 的路由表。
- *
- * ## 获取模型为什么在宿主侧发
- *
- * 渠道端点常常在内网 / 只有这台电脑能直连（本机网关、局域网模型服务）。手机直接发
- * 请求既可能不通，也绕过了宿主自己的协议适配。这里借宿主 `llm.discoverModels`
- * （桌面面板同一条路）在电脑上问一次，只回模型 id / 名字，不落盘。
+ * 获取模型在宿主侧发：渠道端点常常只有这台电脑能直连，这里借宿主 `llm.discoverModels` 问
+ * 一次，只回 id 与名字；手机直接发既可能不通，也绕过宿主的协议适配。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
@@ -146,15 +126,12 @@ function normalizeModels(raw) {
 /**
  * 一条渠道 → pi-ai 的 provider profile。
  *
- * 只写「必须显式说」的字段，与桌面端 `profileOf` 一致：自建路由没有内置目录，协议必须
- * 点名；思考档位不写就是「不思考」，所以这里给默认四档而不是省略。
+ * 只写必须显式说的字段，与桌面端 `profileOf` 一致：自建路由没有内置目录，协议必须点名；
+ * 思考档位不写就是「不思考」，所以这里给默认四档。
  *
- * **编辑时按已有那一条做基底**（`existing`）：手机上的表单只有名称 / 协议 / 地址 /
- * 模型 id，能力字段（上下文、输出上限、图片、思考档位）根本不在界面上。直接按缺省值
- * 重写，等于用户改一次名字就把桌面面板里精细调过的参数全冲掉。所以：
- *  - 同一模型仍在清单里 → 沿用它的能力字段；
- *  - 新加的模型 → 表单报了就用表单的，没报才落缺省；
- *  - 其它不认识的字段（用户手写的）原样带回去。
+ * 编辑时按已有那一条做基底：手机表单只有名称 / 协议 / 地址 / 模型 id，能力字段不在界面上，
+ * 直接按缺省值重写等于改一次名字就把桌面调过的参数全冲掉。同一模型沿用原能力字段，新加的
+ * 模型用表单值或缺省，不认识的字段原样带回去。
  */
 function profileOf(channel, existing) {
   const previous = new Map();
@@ -413,12 +390,9 @@ function takenIdsOf(registered, providers) {
  * { id?, name, protocol, baseUrl, apiKey?, models: [{id, name?, contextWindow?, maxTokens?, vision?}] }
  * → { ok, channel }
  *
- * 带 `id` = 编辑那一条（id 不变、Key 可以留空表示沿用原来的）；不带 = 新建（Key 必填）。
- * 写 Key → 写路由，两步都成了才回成功；路由写失败就把**这一次新写的** Key 清掉（回滚），
- * 不留一条「有 Key 没路由」的孤儿凭据。编辑时用户没重填 Key，就没有可回滚的东西。
- * **路由只能按路径写**：`settings.mutate` 的 `set path:['providers', id]` 一次只动这一段——
- * 整段覆盖会把用户手写的其它路由抹掉（桌面端 2026-10-19 踩过：保存一次自建渠道，
- * 另一条路由整段蒸发）。
+ * 带 `id` = 编辑那一条（id 不变、Key 留空表示沿用原来的）；不带 = 新建（Key 必填）。
+ * 写 Key → 写路由，两步都成了才回成功；路由写失败就把这一次新写的 Key 清掉，不留孤儿凭据。
+ * 路由只能按路径写：整段覆盖会把用户手写的其它路由抹掉。
  */
 async function handleChannelSave(ctx, req, res) {
   const body = await readJsonBody(req, 64 * 1024);

package/lib/mobile/credential-upgrade.js

@@ -2,24 +2,15 @@
 
 /**
  * 旧凭据原地升级：把协议 v1 的会话（HMAC 令牌 / 只带配对码的 `dshc_`）换成带设备主密钥的
- * T1，让一台早就配好的手机不用重新扫码就能开始加密。
+ * T1，早配好的手机不用重新扫码就能开始加密。
  *
- * **主密钥以手机为准**（2026-10-24 修）：手机在本地生成 `deviceKey` 与 `keyId`，这次升级
- * 请求里明文带上，宿主原样存进凭据库、把同一个 `keyId` 回给手机。宿主**不能**自己生成
- * 一把再回标识 —— 那会让两端各拿一把钥匙，升级完手机立刻按 v2 封请求，而宿主用另一把
- * 验签，之后每一条请求都是 `e2ee-bad-signature`，比不升级更糟。
+ * 主密钥以手机为准：手机在本地生成 `deviceKey` 与 `keyId`，升级请求里明文带上，宿主原样存
+ * 库并把同一个 keyId 回给手机。宿主自己生成一把再回标识会让两端各拿一把钥匙，升级完每条
+ * 请求都是 `e2ee-bad-signature`。明文上行是一次性取舍——老会话没有别的保密通道，不这么做
+ * 只能重新扫码；升级后所有流量仍由这把钥匙端到端加密。
  *
- * 明文上行是一次性的取舍：老会话手上只有旧凭据，既没有二维码里那张票据，也没有任何别的
- * 保密通道（局域网直连与公网 IPv6 直连都是明文 HTTP，中转本来就按「不可信的那一跳」设计）。
- * 不这么做就只能让用户重新扫一次码。升级之后所有流量仍由这把钥匙端到端加密。
- *
- * 换成什么不在本次判断里：拿到完整一套（凭据 + 密钥 + 标识）才回补丁，缺一样就当没升级。
- *
- * **请求体必须现读**（2026-10-25 修）：这条路服务的恰好是协议 v1 的老会话，而老会话发的
- * 是明文 —— 守卫只为「带信封」的那条路预先解好 `req.body`，明文请求的字节还挂在 socket 上
- * 没人读过。原来这里直接取 `req.body`，于是永远拿到空对象、宿主每次都回「没升级」，手机
- * 那边一次都没成功过（真机表现是「App 与插件都更新了，设备行仍旧写链路未加密」）。
- * 现在与其它移动端路由同一条读法（`readJsonBody`：`req.body` 有就用，没有就读流）。
+ * 请求体必须现读：这条路服务的恰好是发明文的老会话，守卫只替带信封的请求解好 `req.body`，
+ * 直接取只会永远拿到空对象。拿到完整一套（凭据 + 密钥 + 标识）才算升级。
  */
 
 const crypto = require('node:crypto');