dsh-mobile-plugin 0.3.1 → 0.4.1

package/lib/mobile/host-settings.js

@@ -3,19 +3,12 @@
 /**
  * 移动端「宿主设置」API：只读暴露宿主的模型提供方名单与设置命名空间。
  *
- * 桌面端有完整的设置面板（默认模型、提供方配置、凭据是否已设），手机端此前一点都看不到，
- * 只能看到一个「设置」页里全是 App 自己的偏好项。这里先把「看得到」补齐：
- * settings.describe 与 llm.providers 都是只读接口，且宿主自己已经做了脱敏
- * （secrets 只给出 path 与 set，从不返回值），所以可以原样转给手机。
- *
- * 命名空间里的 schema 字段是序列化后的 zod 树（几百个 uid/refs），对手机没有任何用处，
+ * settings.describe 与 llm.providers 都是只读接口，宿主自己已做脱敏（secrets 只给 path 与
+ * set，从不返回值），可以原样转给手机。命名空间里的 schema 是序列化后的 zod 树，对手机没用，
  * 直接丢掉，只保留 value / base / user / applies / revision 与密钥槽。
  *
- * 写入侧（POST /host-settings/mutate）与桌面端同一口径：只走宿主的 settings.mutate，
- * 用「按路径寻址的 op」（set / unset）+ expectedRevision 做乐观并发，绝不整段 replace。
- * 桌面端就是这么写的：dsh-client-ui-settings/lib/client.js 一次只提交一个 op
- * （`settings.mutate({ ns, ops: [op], expectedRevision })`），失败后重新 describe 再重试。
- * 手机上一般一次改好几个字段，所以这里一次收一组 op，但语义与桌面端逐字段提交完全一致。
+ * 写入侧（POST /host-settings/mutate）与桌面端同一口径：只走宿主的 settings.mutate，用按路径
+ * 寻址的 op（set / unset）+ expectedRevision 做乐观并发，绝不整段 replace。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
@@ -61,15 +54,12 @@ function boundValue(value, depth = 0) {
 /**
  * 从序列化的 zod 树里读出「这个命名空间的密钥写到哪个凭据引用上」。
  *
- * 宿主把两个标记留在 schema 的 meta 里：`.role('secret')` 标出密钥字段，
- * `.role('credential-ref')` 标出「写着凭据引用名」的那个字段
- * （见 dsh-web-search-deepseek/lib/index.js:240-241 的 apiKey / apiKeyEnv）。
- * settings.describe 的 secrets 槽就是由 role('secret') 生成的，而真正写入时
- * 要用的是 role('credential-ref') 指向字段的值（桌面端也是这么取的：
- * dsh-client-ui-settings-plugins/lib/client.js 的 refOf() 读 snapshot.value.apiKeyEnv）。
+ * 宿主把两个标记留在 schema 的 meta 里：`.role('secret')` 标出密钥字段，`.role('credential-ref')`
+ * 标出「写着凭据引用名」的那个字段。settings.describe 的 secrets 槽由前者生成，而真正写入时
+ * 要用后者指向字段的值。
  *
- * 这里按同一口径从 schema 推导，不写死任何命名空间；推导不出来就返回 null，
- * 于是 App 不会给没有密钥槽的设置项画密码框。
+ * 按同一口径从 schema 推导，不写死任何命名空间；推导不出来就返回 null，于是 App 不会给
+ * 没有密钥槽的设置项画密码框。
  */
 function credentialRefOf(schema, value) {
   const refs = schema && typeof schema === 'object' && !Array.isArray(schema) ? schema.refs : null;

package/lib/mobile/inbox-clean.js

@@ -3,31 +3,14 @@
 /**
  * 收件目录（`~/.dsh/mobile-inbox`）的占用统计与按龄清理。
  *
- * 手机分享进来的文件由 `uploads.js` 落到 `<收件根>/<日期>/<消毒名>`，那条通道**只进不出**：
- * 它在盘上只认文件名，不认识会话、也不认识工作区，所以没有任何「删掉这条对话就顺带清掉
- * 它传上来的文件」可言 —— 唯一的引用是会话日志正文里那句 `@路径`，那是文本，宿主不会
- * 跟着它去回收。不设一个出口，这个目录只会按天堆下去。
+ * 手机分享进来的文件由 `uploads.js` 落到 `<收件根>/<日期>/<消毒名>`，那条通道只进不出：盘上
+ * 只认文件名，不认识会话，会话日志里的 `@路径` 也不会触发回收。不设出口，目录只会按天堆。
  *
- * 因此这里的口径是**按龄**：只删 mtime 超过 `keepMs`（24 小时）的文件。
+ * 口径是按龄：只删 mtime 超过 24 小时的文件。按文件而不是按日期目录删，才和「放满一天」这个
+ * 承诺一致；今天传的文件不在范围内，正在跑的那一回合碰不到它。空出来的日期目录顺手删掉。
  *
- * 为什么是文件而不是日期目录：目录按「上传那天的本地日期」分堆，整段删会把昨天 23:50
- * 传的、才过 20 分钟的文件一起带走；按每个文件自己的 mtime 判才和「放满一天」这个承诺
- * 一致。空出来的日期目录顺手删掉。
- *
- * 为什么留着 24 小时而不是立刻删：助手拿到路径之后可能在同一个回合里反复读它，用户也可能
- * 隔一晚上让助手接着看同一份文件。今天传的文件一开始就不在清理范围内，正在跑的那一回合
- * 因此碰不到这里。
- *
- * 与 `session-cleanup.cjs` 的取舍刻意不同：那边进程活着时一条日志都不删（宿主随时可能去
- * 打开，ENOENT 会带走整个进程）；这里删的是收件目录里的普通文件，宿主只在助手明确要读
- * 某个路径时才碰它，而那个路径只有在 24 小时窗口内才可能还有人要。
- *
- * ## 自动清理是开关，默认关（2026-10-21 用户定）
- *
- * 启动时那次自动清理**只有开关打开才跑**；面板上那颗按钮永远可用（那是用户自己按的，
- * 不需要开关授权）。开关落盘在 `<DSH_HOME>/storages/mobile-plugin/inbox-auto-clear.json`，
- * 与自动更新开关同一套写法（读不到 / 读坏了都当关）—— 自动删盘这种事，缺省必须在用户
- * 这一侧，而不是「装了就替你删」。
+ * 自动清理是开关、默认关：启动时那次只有开关打开才跑，面板上的按钮永远可用。开关落盘在
+ * `<DSH_HOME>/storages/mobile-plugin/inbox-auto-clear.json`，读不到或读坏都当关。
  */
 
 const fs = require('node:fs');
@@ -241,7 +224,7 @@ function usageView(scan) {
     keepHours: Math.round(scan.keepMs / (60 * 60 * 1000)),
     /**
      * 自动清理开着没有。两个界面都靠它画那颗开关 —— 不自己猜、也不各自存一份，
-     * 真值只在这台机器的 json 里。**默认 false**（用户 2026-10-21 定）。
+     * 真值只在这台机器的 json 里。**默认 false**。
      */
     autoClear: autoClearEnabled(),
   };

package/lib/mobile/local-images.js

@@ -1,25 +1,19 @@
 'use strict';
 
 /**
- * 正文图片内联：把消息文本里指向**本机文件**的图片语法（`![](/abs/path.png)`）换成 data URI，
- * 让手机端能直接把它画出来。
+ * 正文图片内联：把消息文本里指向本机文件的图片语法（`![](/abs/path.png)`）换成 data URI，
+ * 让手机端能直接画出来。
  *
- * 为什么只能在这里换：手机拿到的只是文本，`/Users/…/a.png` 既不是手机上的文件，移动 API 也
- * 没有「按路径读文件」的能力面（见 host-bridge-endpoints 守卫的 forbidden 表），所以地址原样
- * 过去只会显示成一串字面 markdown。会话里用户自己发的图片本来就是内联形状（宿主把附件解成
- * base64，见 attachments.js 与 App 侧 chat.ts 的 images[]），这里只是把「正文里写的本机图片」
- * 拉齐到同一种形状，App 侧因此不需要新增任何通道或依赖。
+ * 手机拿到的只是文本，`/Users/…/a.png` 既不是手机上的文件，移动 API 也没有「按路径读文件」
+ * 的能力面，原样过去只会显示成一串字面 markdown。这里把「正文里写的本机图片」拉齐到附件那种
+ * 内联形状，App 不需要新增通道。
  *
- * 保守取舍（宁可保留原样的字面 markdown，也不给个半截东西）：
- * - 只认能解析成**绝对路径**的地址：`/x/y.png`、`file:///x/y.png`、`~/y.png`；
- *   http(s)、`data:`、`www.`、相对路径一律不碰。
- * - 只认 png/jpg/jpeg/webp/gif（与 app/src/services/viewmodels/image-limits.ts 的 mediaTypes
- *   同白名单），并且**核对魔术字节**：字节不是图片就放弃，绝不按扩展名撒谎。
- * - 三级体积预算（单图 / 单段文本 / 单次响应，见下方常量）：超预算的图保持字面 markdown，
- *   不截断、不缩水成半张图。
- * - 读不到、不是普通文件、读取失败：原样保留 —— 一条图片取不到不能让整段历史或整帧 SSE 挂掉。
- * - 围栏代码块与行内代码里的图片语法一律不碰：那是**写法示例**，不是要画的图；换掉会把
- *   三行代码变成几十万字符的 base64，App 的代码块会铺成很长很长的一块。
+ * 保守取舍——宁可保留字面 markdown，也不给半截东西：
+ * - 只认绝对路径（`/x/y.png`、`file:///x/y.png`、`~/y.png`），http(s)、`data:`、相对路径不碰；
+ * - 只认 png/jpg/jpeg/webp/gif，并核对魔术字节，不按扩展名撒谎；
+ * - 三级体积预算（单图 / 单段 / 单次响应），超预算就保持字面；
+ * - 读不到、不是普通文件、读取失败一律原样保留；
+ * - 围栏代码块与行内代码里的图片语法不碰，那是写法示例。
  */
 
 const fs = require('node:fs/promises');

package/lib/mobile/monitor.js

@@ -3,22 +3,14 @@
 /**
  * GET /api/mobile/v1/monitor —— 安卓后台提醒服务专用的「状态位」视图（只读）。
  *
- * 为什么单开一条：那条前台服务活在 JS 之外（App 退到后台、进程被系统回收，只有它还在），
- * 所以「这一轮跑完了 / 跑挂了 / 停下来等你回话」只能由它自己定时去问。它此前问的是完整
- * 会话清单（`?fresh=1`），而那份清单为了画侧栏还捎着**最后一条消息预览** —— 预览要为最近
- * 20 个会话各读一次 history。后台每 8 秒白读 20 次日志，只为判断「completed 翻没翻」。
+ * 那条前台服务活在 JS 之外，只能自己定时来问「这一轮跑完了 / 跑挂了 / 停下来等你回话」。
+ * 它此前问完整清单，而清单为了画侧栏还捎着最后一条消息预览，后台每 8 秒白读 20 次 history。
  *
- * 这条只回监控需要的那几格：在不在跑、刚完成没有、在等谁回话、上一轮是不是跑挂的、标题。
- * 并支持 `?rev=` 条件刷新：状态位与上次一模一样时回一句 `unchanged`，连 items 都不带
- * （稳态下这一发是几十字节）。再带上 `?wait=秒` 时，条件刷新的那一发**先挂住**，等状态位
- * 真的变了才回 —— 安卓后台服务靠它把「定时去问」变成「一有变化立刻送到」。
+ * 这条只回监控需要的那几格，支持 `?rev=` 条件刷新（状态位没变就回 unchanged）与 `?wait=秒`
+ * （条件不满足时先挂住，真变了才回），让安卓服务不必轮询。完成态仍以 completion 状态机为准，
+ * 常态下不读 history，只有「跑过、不在跑、结局还没定」的那几条才读一次。
  *
- * 完成态仍以 completion 状态机为准，与 `/sessions` 用同一本账：常态下这里**不读 history**，
- * 只有「跑过、现在不在跑、结局还没定」的那几条才读一次 —— 那是唯一能把 failedTurn 折出来
- * 的地方（事件流漏帧时全靠它，见 completion.js 的坑）。
- *
- * 刻意不进 `/sessions`：那边一旦按调用方分叉视图，镜像推送与 App 的写后刷新也会跟着
- * 受影响，而这两条都要求「一份完整清单」。分路由比加参数安全。
+ * 刻意不进 `/sessions`：那边一旦按调用方分叉视图，镜像推送与写后刷新都会受影响。
  */
 
 const { sendJson } = require('../shared/http-util');
@@ -50,8 +42,7 @@ function monitorItem(summary, state, fact) {
   // 为什么：那个按设备记账的完成态要靠「这一次真的读回了 history」才折得出来，而
   // 「刚跑完」那一刻宿主的镜像推送早把同一份预览按新指纹写进缓存了 —— 监控这一侧
   // 拿到的是缓存命中（events 为空）、永远折不出来，`completed` 就一直 false，后台
-  // 一条提醒都不会响（2026-10-25 真机：宿主日志里全是「preview cache-hit」）。
-  // 事实那本账由 turn/end 事件当场记下，不依赖预览缓存，所以拿它判完成。
+  // 一条提醒都不会响。事实那本账由 turn/end 事件当场记下，不依赖预览缓存。
   //
   // 已读水位仍然生效：这一轮结束在「这台手机读过」之前就不算提醒。
   const clearedAt = typeof state?.clearedAt === 'number' ? state.clearedAt : null;
@@ -103,7 +94,7 @@ async function buildMonitorState(ctx, deviceKey) {
   const deleted = deletedSessionIdsOf(ctx);
   const { archived } = await workspaceSessionFlags(ctx);
   // 子代理会话不参与后台提醒：它们是主轮内部的执行单元，App 侧栏也不列；把它们算进来
-  // 会在后台弹一堆「子代理跑完了」（2026-10-26 真机日志里四十多个 UUID 会话都是这种）。
+  // 会在后台弹一堆「子代理跑完了」。
   const live = summaries.filter((s) => s && typeof s.sessionId === 'string' && s.sessionId
     && s.origin !== 'subagent'
     && !deleted.has(s.sessionId) && !archived.has(s.sessionId));

package/lib/mobile/pairing.js

@@ -3,27 +3,15 @@
 /**
  * 移动端配对：手机在中转上用自己的配对码换到 token 与设备凭据。
  *
- * **这条路由归宿主，不归中转。**「谁可以进这台机器」是宿主自己的判断，配对码本来就存在
- * 宿主的 `state` 里；中转只按实例标识把请求转过来。早先这套判断长在独立的中转进程里
- * （`dsh-mobile-server/server.js` 的 `/pair`），换成 Rust 中转时整块没搬过去，于是手机
- * 按老地址 POST `/pair`、请求被中转原样转给宿主、宿主没有这条路由，只能回 405。
+ * 这条路由归宿主、不归中转：「谁可以进这台机器」是宿主自己的判断，配对码存在宿主的 state
+ * 里，中转只按实例标识把请求转过来。
  *
- * 与局域网那条（`lib/relay/lan-proxy.js` 的 `/__lan_pair`）是**同一件事的两个入口**：
- * 都是「配对码 / 票据 → 签发凭据」，差别只在网络路径。凭据本身两条路签发的是同一种 HMAC
- * （都用宿主 lanSecret 签名），所以经中转配对拿到的 token 可以直接用于局域网请求。
+ * 与局域网那条（`lib/relay/lan-proxy.js` 的 `/__lan_pair`）是同一件事的两个入口，签发的
+ * 是同一种 HMAC（都用宿主 lanSecret 签名），所以经中转配对拿到的 token 也能用于局域网请求。
  *
- * 请求体**两种形状都认**：
- *   老形状  `{ instanceId?, code, device }`   —— 旧 App，明文，一字不改地照旧处理；
- *   新形状  `{ instanceId, sealed }`          —— 协议 v2，`sealed` 是用二维码票据派生的
- *                                                密钥封的，解出来是设备主密钥与设备信息。
- * 新形状里**没有配对码**：票据本身就是资格证明。回包同样是密文 —— 里面是 token / cookie /
- * 设备凭据，明文回包等于让中转顺手拿到这台设备未来一年的通行证。
- *
- * 故意**不**在这里做的事：
- *  - 不问宿主再确认一次。宿主的配对策略（pairingPolicy）已经决定了它接不接受新设备，
- *    `deny` 时中转根本连不上；而这条路由本身就跑在宿主进程里。
- *  - 不做「多台机器撞同一个配对码」的处理。那是中转的职责（它才看得见全部实例），
- *    在这台宿主上，配对码要么对上要么对不上。
+ * 请求体两种形状都认：老 App 的 `{ instanceId?, code, device }` 明文照旧；协议 v2 的
+ * `{ instanceId, sealed }` 没有配对码，票据本身就是资格证明，回包同样是密文 —— 里面是
+ * token / cookie / 设备凭据，明文回包等于让中转拿到这台设备的长期通行证。
  */
 
 const { sendJson } = require('../shared/http-util');

package/lib/mobile/plugin-self.js

@@ -3,29 +3,12 @@
 /**
  * 移动端「这台设备上的移动端插件」自我管理：版本、来源、运行状态、更新与回滚结果。
  *
- * ## 范围：只管**我们自己这一个插件**
+ * 只管 dsh-mobile-plugin 自己在这台电脑上的版本，不碰电脑上装的全部插件：动别人的插件会把
+ * 承载 App 连接的那条链一起带走，而手机没有在电脑前的那双手。判定只有一份真源（外壳的
+ * `dshMobilePluginRuntime`），这里只做投影与瘦身。
  *
- * 手机管的是 `dsh-mobile-plugin` 自己在这台电脑上的版本 —— 不是电脑上装的全部插件
- * （那是桌面「设置 → 插件 / 插件市场」的事，App 这边不碰）。理由很直接：动别人的插件会
- * 把承载 App 连接的那条链一起带走，而手机没有在电脑前的那双手。
- *
- * ## 与 `/plugin/update/*` 那三条的关系
- *
- * 那三条是上一版给「应用更新」页做的，只有 `status / check / apply`。这里补的是同一件事
- * 在**设备页**里需要的另外几格：来源与版本要不要并成一行、更新完**有没有自动退回去**、
- * 以及「这一台能不能更新」为什么不给按钮的原因。判定仍然只有一份真源（外壳的
- * `dshMobilePluginRuntime`），这里只做投影与瘦身，不自己算。
- *
- * ## 回滚是宿主自己做的，不是手机按的
- *
- * 装坏了 App 就连不上这台设备 —— 那时候手机上任何「回滚」按钮都发不出去。所以外壳在
- * 装之前备份正在跑的那一代、装完自检（见 `lib/shell/self-check-after-swap.js`），
- * 不过就自己退回去。手机端只做两件事：
- *   · 更新后断了就按现有逻辑重连（`usePluginUpdate` 的轮询本身）；
- *   · 连上之后读 `rolledBack`，如实显示「上次装失败了，已自动退回 X」。
- *
- * `rolledBack` 由外壳落进 `lastApply`，这里只认它、**不重新判**：判据写在会真去医院的那
- * 一头，手机端各写一套只会出现两套口径。
+ * 回滚是宿主自己做的，不是手机按的：装坏了 App 就连不上，那时手机上的回滚按钮发不出去。
+ * 外壳装前备份、装完自检，不过就自己退回去；手机只读 `rolledBack` 如实显示，不重新判。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');

package/lib/mobile/plugin-update.js

@@ -3,35 +3,16 @@
 /**
  * 手机端「插件更新」：APP 的「应用更新」页直接给这台电脑上的插件升级。
  *
- * ## 为什么手机端要有这条路
+ * 自动更新（外壳的 10 分钟轮询）有闸：有对话在跑就不换文件。用户在手机上聊天时这道闸几乎
+ * 永远关着，而更新入口此前只在电脑面板（`localOnly`），手机打不到。这三条接口把它开给已配对
+ * 的手机，能力面不新增：来源判据照旧（只放行注册表来源，force 也跳不过），换代仍就地做。
  *
- * 自动更新（外壳里那个 10 分钟轮询）有一道闸：**有对话在跑就不换文件**，等下一轮。用户在
- * 手机上聊天时，这道闸几乎永远关着，而更新入口此前只在桌面控制面（`localOnly`）—— 手机
- * 根本打不到。于是「插件有新版」这件事对手机用户等于不存在。这三条接口就是把它开给已配对
- * 的手机。
+ * apply 只回一句「开始了」：装一次要跑包管理器，装完换代会把当前这一代实现连同这条路由一起
+ * 卸掉，旧代码手里的响应发不出去，结果只能靠前端轮询 status。状态里给身份而不是时间戳，
+ * 两台机器的钟不一定对得上。
  *
- * 能力面是**有意放开**的：手机本来就握着这台宿主的凭据、能发消息，而「换掉宿主上跑的插件
- * 代码」比发消息重。所以入口只做一件事、且沿用已有的两道既有判据，不新增任何能力：
- *
- *  · **来源判据不放开**：`update-install.cjs` 的 `installAllowedFor` 只放行注册表来源
- *    （`npm`）。本地目录 / `file:` tgz / `workspace:` 装的机器（开发机就是）即便带
- *    `force` 也会被拒 —— force 只跳过「有对话在跑」和「新发布先晾一会儿」，跳不过来源。
- *  · **换代仍然就地做**：装完由外壳 `runtime.reload()` 换实现代，不重启 DSH（见 lib/index.js）。
- *
- * ## 为什么 apply 只回一句「开始了」
- *
- * 装一次要跑包管理器，几十秒到几分钟；装完换代会把**当前这一代实现连同这条路由一起卸掉**，
- * 旧代码手里的响应发不出去。所以结果不能靠这条请求的返回值，只能靠前端轮询 status。
- * 顺带一个好处：apply 期间没有在飞请求，换代时 `runtime.drain()` 不用等谁。
- *
- * 状态里给的是**身份**而不是时间戳：前端用「运行中版本变了」或「appliedAt 变了」判完成，
- * 手机与电脑的钟不一定对得上，比较时间会误判。
- *
- * ## 三条接口
- *
- *  · `GET  /api/mobile/v1/plugin/update/status` 运行中/盘上版本、安装来源、上一轮更新结果
- *  · `POST /api/mobile/v1/plugin/update/check`  问 npm 注册表有没有新版（与桌面面板同一个实现）
- *  · `POST /api/mobile/v1/plugin/update/apply`  开始一次强制更新，立即返回
+ * 三条接口：status（版本 / 来源 / 上一轮结果）、check（问 npm，与桌面同一实现）、
+ * apply（强制更新，立即返回）。
  */
 
 const path = require('node:path');

package/lib/mobile/plugins.js

@@ -3,32 +3,14 @@
 /**
  * 移动端「插件清单」API：把桌面端 设置 → 插件 的只读快照搬到手机上。
  *
- * 桌面端由 dsh-client-ui-settings-plugin-inventory 渲染：一个可搜索的紧凑卡片列表，
- * 每张卡片用模块短名作标题、用小标签表示有效启停、用彩色圆点表示根 fiber 状态，
- * 展开后展示 Loader 条目 id 与 Cordis 状态；选中该标签页时才懒调用一次
- * `ctx.remote.pluginInventory.list()`，不订阅 Loader 变化（重新打开设置才取新快照）。
+ * 宿主服务 pluginInventory 不在 apiProxy 上，是 Typert Remote 服务，手机侧经
+ * host-bridge/transport.js 的 `invoke` 到达（由它补 Peer 身份与错误收敛）。
  *
- * 关键：这个宿主服务 **不在 apiProxy 上** —— 它是 Typert Remote 服务
- * （dsh-host-plugin-inventory 的 pluginInventory）。手机侧本来就能到它：
- * lib/mobile/sessions.js 早已派发 commands.execute，lib/mobile/references.js 通了
- * fileReferences / sessionReferenceResolver，这里照搬同一条路 —— 都经
- * host-bridge/transport.js 的 `invoke`，由它统一补 Peer 身份与网关错误收敛。
+ * 这个方法没有声明任何参数，args 必须是空对象，多给一个字段就会被拒。返回值是 decode 后的
+ * 业务结果本体（`{ entries: […] }`），不是 `{ok,value}` 外壳。语义按宿主原文透传：moduleName
+ * 是 npm 包名，enabled 是有效启停（与 fiberPhase 不是一回事），fiberPhase 可能为 null。
  *
- * 接口（只转发宿主的部署快照，不做任何加工）：
- *  - GET /api/mobile/v1/plugins → pluginInventory.list
- *
- * 参数：这个方法 **没有声明任何参数**，args 必须是空对象——assertExactArguments
- * 按声明逐位比对，多给一个字段就会被拒。
- *
- * 返回值形状：`gateway.invoke()` 回的是 decode 后的业务结果本体，不是
- * {ok:true,value} 外壳（那层壳是浏览器传输加的，见 lib/mobile/references.js 里的长注释）。
- * pluginInventory.list 声明的是 { entries: […] } 对象，所以 invoke 回来就是这个对象。
- *
- * 语义按宿主原文透传：
- *  - moduleName 是 npm 包名（如 @deepseek-ai/dsh-host-directory-picker-native），
- *    展示用的短名截断属于客户端的事。
- *  - enabled 是「有效启停状态」，和 fiberPhase 不是一回事：停用的条目 fiberPhase 是 null。
- *  - fiberPhase 只有 failed/pending/active/loading/unloading 五种，宿主也可能给 null。
+ * 接口：GET /api/mobile/v1/plugins → pluginInventory.list。
  */
 
 const { sendJson } = require('../shared/http-util');

package/lib/mobile/questions.js

@@ -3,31 +3,15 @@
 /**
  * 手机端提问桥（DSH 0.2.x）：`ask_user_question` 与「计划评审」。
  *
- * ≤0.1.x 的宿主把提问当成 apiProxy 事件流上的 server-request：
- * `{rpcId, payload:{type:'question/requested', sessionId, questions}}`，手机凭**帧级 rpcId**
- * 回答（`/question/respond` 把 rpcId 回给宿主那张 pending 表）。0.2.x 把 apiProxy 删了，
- * 提问只剩一个**进程内** waterfall 钩子 `user-questions/request`（`dsh-user-questions`
- * 发起，`dsh-tool-ask-user` 与 `dsh-plan-mode` 是它的两个调用方），帧级 rpcId 随之消失，
- * 于是手机既收不到卡片、也没有能回传的 id。
+ * 0.2.x 删掉了 apiProxy，提问只剩一个进程内 waterfall 钩子 `user-questions/request`，帧级
+ * rpcId 随之消失，手机既收不到卡片、也没有能回传的 id。这里按新形状补起来，App 契约不变：
+ * prepend 钩子、自己铸 rpcId 推卡、`/question/respond` 找到挂起项把回答交回钩子。
  *
- * 这里按 0.2.x 的形状把这条通道补起来，**手机端契约一行不改**（App 仍然收
- * `question/requested` + 帧级 rpcId，仍然 POST `/question/respond`）：
+ * 钩子必须 prepend：宿主的转发器在桌面窗口开着时会一直等桌面回答、不调用 `next()`。下游
+ * 总是拿到请求，桌面那张卡与手机那张同时存在，谁先答用谁的，落定后广播 `question/resolved`。
  *
- *   1. 听 `user-questions/request` 钩子（**prepend**，理由与审批桥同一条：宿主的转发器
- *      `dsh-api-remotes` 在桌面窗口开着时会一直等桌面回答、不调用 `next()`）。铸一个自己的
- *      rpcId，把卡片推给正在看这个会话的手机，然后把请求挂住。
- *   2. 下游**总是**拿到请求（桌面那张卡照旧出现，`dsh-plan-mode` 也一样），与手机那张
- *      卡同时存在：手机答得早就用手机的，桌面答得早就用桌面的，落定后广播
- *      `question/resolved`，另一边那张卡被收掉。手机在看的时候也照转，否则桌面根本
- *      没有卡可显示 —— 桌面那张卡只由「被转发的请求」长出来，切回去也补不回来
- *      （2026-10-24 用户报「APP 有卡、桌面什么都没有」的就是这条）。
- *   3. `/question/respond` 拿 rpcId 找到挂起项，把回答交回钩子 —— 这才是真正让 agent
- *      继续往下跑的那一步。
- *
- * 「计划评审」不走另一条通道：`dsh-plan-mode` 的 `exit_plan_mode` 就是拿
- * `ctx.userQuestions.ask()` 问的（问题带 `intent.kind='plan-review'`、`detail` 是计划正文、
- * 选项里有一个「批准」标签），所以这道桥同时修好它。App 的问题面板本来就渲染
- * `detail` 与 `options`，计划正文直接显示在详情里。
+ * 「计划评审」不走另一条通道：`exit_plan_mode` 就是拿 `ctx.userQuestions.ask()` 问的
+ * （`intent.kind='plan-review'`，detail 是计划正文），这道桥同时修好它。
  */
 
 const { randomUUID } = require('node:crypto');
@@ -298,17 +282,12 @@ function installQuestionBridge(ctx) {
 /**
  * POST /api/mobile/v1/question/respond —— `{rpcId, sessionId, answer:{answers}}`。
  *
- * 先查本桥的挂起项；查不到就交回 `ctx.apiProxy.respond`（0.1.x 宿主那份真 apiProxy 才是
- * 它的归宿；0.2.x 的兼容桥会如实回 `host-unsupported`，于是落到下面那条 409）。
+ * 先查本桥的挂起项；查不到就交回 `ctx.apiProxy.respond`（0.1.x 真 apiProxy 的归宿；0.2.x
+ * 兼容桥会回 `host-unsupported`，落到下面那条 409）。
  *
- * ⚠️ `respond` 在两条通道上的返回形态**不一样**，这里必须两种都受得住：
- *   - 0.1.x 的真 apiProxy → `Promise<{accepted}>`；
- *   - 0.2.x 的兼容桥（`mobile/host-bridge.js`）→ **同步对象**
- *     `{result:{ok:false,error:{code:'host-unsupported'}}}`，它压根不是 Promise。
- * 早先这里直接 `.catch()`，于是在 0.2.x 上表达缺席的那一发会抛
- * `TypeError: ctx.apiProxy.respond(...).catch is not a function`，被路由守卫兜成
- * **500 internal** 而不是下面那句 409。手机端因此只看到「提交失败」的原始异常，
- * 而桌面那张卡还挂着 —— 用户看到的就是「APP 提交没到 DSH，还得回桌面重答一遍」。
+ * respond 在两条通道上的返回形态不一样：0.1.x 是 `Promise<{accepted}>`，0.2.x 兼容桥是同步
+ * 对象。同步对象上没有 `.catch`，直接链 Promise 会抛 TypeError 被路由守卫兜成 500，而不是
+ * 409，手机只看到「提交失败」的原始异常。
  */
 async function handleQuestionRespond(ctx, req, res) {
   const body = await readJsonBody(req);
@@ -349,14 +328,10 @@ async function handleQuestionRespond(ctx, req, res) {
 }
 
 /**
- * 把回答交回旧通道的 `ctx.apiProxy.respond`，**Promise 与同步对象两种返回都收**。
- *
- * 两条通道的形态不同（见 `handleQuestionRespond` 的注释）：0.1.x 是 Promise，0.2.x 的兼容桥
- * 是同步的 `{result:{ok:false,...}}`。同步对象上没有 `.catch`，所以不能在这里链 Promise。
- * 抛错与「通道说没有」一律折算成 null —— 调用方据此如实回 409，而不是把 500 抛给手机。
+ * 把回答交回旧通道的 `ctx.apiProxy.respond`，Promise 与同步对象两种返回都收。
  *
- * 兼容桥那种 `{result:{ok:false,error:{code:'host-unsupported'}}}` 里没有任何 `accepted`
- * 字段，`accepted !== true` 自然落到 409，不必单独判 code。
+ * 0.1.x 是 Promise，0.2.x 兼容桥是同步的 `{result:{ok:false,...}}`；同步对象上没有 `.catch`，
+ * 不能链 Promise。抛错与「通道说没有」一律折算成 null，调用方据此如实回 409。
  */
 async function respondViaLegacyProxy(ctx, message) {
   const proxy = ctx && ctx.apiProxy;

package/lib/mobile/references.js

@@ -3,29 +3,15 @@
 /**
  * 移动端「引用发现」API：把桌面端输入框里的 @文件 / @会话 补全补齐到手机上。
  *
- * 桌面端由 dsh-client-ui-reference 渲染：输入 @ 后浏览器同时发起
- * fileReferences/list 与 sessionReferenceResolver/candidates 两个 Remote 调用，
- * 结果按「文件在前、会话在后」的确定性顺序分组展示；选中文件插入普通 @路径 文本，
- * 选中会话插入宿主给的规范 mention（@[label](dsh-session:…)）。
+ * 两个宿主服务（fileReferences、sessionReferenceResolver）不在 apiProxy 上，是 Typert
+ * Remote 服务，手机侧经 host-bridge/transport.js 的 `invoke` 到达。
  *
- * 关键：这两个宿主服务 **不在 apiProxy 上** —— 它们是 Typert Remote 服务
- * （dsh-file-reference 的 fileReferences、dsh-session-reference 的
- * sessionReferenceResolver）。手机侧本来就能到它们：dsh-mobile-plugin 与宿主同进程，
- * lib/mobile/sessions.js 已经派发过 commands.execute，lib/mobile/plugins.js 也走同一条路
- * 读 pluginInventory —— 都经 host-bridge/transport.js 的 `invoke`，这里照搬。
+ * 两条接口只转发发现域，不做排序或截断之外的加工：
+ *  - GET /file-references → fileReferences.list
+ *  - GET /session-references → sessionReferenceResolver.candidates
  *
- * 两条接口（都只是转发宿主的发现域，不做任何排序或截断之外的加工）：
- *  - GET /api/mobile/v1/file-references?sessionId=…&query=…     → fileReferences.list
- *  - GET /api/mobile/v1/session-references?sessionId=…&query=…  → sessionReferenceResolver.candidates
- *
- * 参数按宿主的 **wire 名** 精确校验：两个方法都是 { agentId, query }，query 是普通
- * JSON 字符串（与 messageFeedback 的 { request } 包装不同）。
- *
- * 语义按宿主原文透传：
- *  - query 是「@ 或 @" 后面的那段文字」；空串表示列出全部（宿主自己限量）。
- *  - 文件候选只有 path/kind，目录候选带在路径尾部追加 / 的责任在客户端。
- *  - 会话候选的 mention 是宿主的规范写法，客户端必须原样发送，不能拿 label 重建。
- *  - 两个域各自独立降级：任一域不可用不影响另一个域（桌面端也是这个约定）。
+ * 参数按宿主 wire 名精确校验（都是 `{ agentId, query }`）。语义透传：空 query 列出全部；
+ * 会话候选的 mention 必须原样发送，不能拿 label 重建；两个域各自独立降级。
  */
 
 const { sendJson } = require('../shared/http-util');
@@ -52,17 +38,11 @@ function errorText(error) {
 /**
  * 经网关调一次引用发现。
  *
- * 走 host-bridge/transport.js 的 `invoke`：Peer 身份与「服务/方法不存在」的收敛都在
- * 那里，本域只做自己的 503/400 翻译。**不要自己直连网关** —— 0.2.1 起
- * 要求每个请求自带 Peer，绕过去就是对 undefined 读 `.signal`，手机端 @ 补全整块失效。
+ * 走 host-bridge/transport.js 的 `invoke`：Peer 身份与「服务/方法不存在」的收敛都在那里。
+ * 不要自己直连网关 —— 0.2.1 起每个请求都要自带 Peer，绕过去就是对 undefined 读 `.signal`。
  *
- * 注意返回值形状：网关回的是 **decode 后的业务结果本体**
- * （dsh-api-gateway/lib/index.js:112 `return decode(descriptor.result, result, …)`），
- * 那层 `{ok:true,value}` 外壳是浏览器传输（connection.rpc.intercept('/api')）加的，
- * invoke 不负责包。所以形状取决于服务声明的 result schema：
- *  - messageFeedback 声明的是 ok/error 联合 → invoke 回来就是 {ok:true,value}
- *  - fileReferences.list 声明的是 z.array(…) → invoke 回来就是一个裸数组
- * 两个都认，这样宿主以后把 schema 换成联合也不会坏。
+ * 网关回的是 decode 后的业务结果本体，`{ok,value}` 外壳是浏览器传输加的：messageFeedback
+ * 声明的是联合，回 `{ok:true,value}`；fileReferences.list 声明的是数组，回裸数组。两个都认。
  *
  * @returns {Promise<{value?: unknown, error?: {code: string, message: string}}>}
  */

package/lib/mobile/relay-control.js

@@ -3,35 +3,14 @@
 /**
  * 移动端「这台设备的中转与连接配置」：读写、配对码、吊销、重连、端口自检、地址候选。
  *
- * ## 为什么手机要能改这些
+ * 这些项不会让插件代码变，最坏结果只是这台电脑从网上找不到，而重连的主动权在手机这一侧，
+ * 所以能力面有意放开给已配对手机；控制面那条 `localOnly` 路由防的是「中转进来的人」，不能
+ * 复用，这里直接持有同一份 settings 与 schema 校验，两个入口写同一份真值。
  *
- * 这七八项（中转地址、注册密钥、设备名、局域网开关与端口、手机优先走哪条、配对策略、
- * 遥控总开关）从前只有一个入口：电脑上当机面板（`/api/relay/*`，全部 `localOnly`）。
- * 于是「手机上发现连不上、想改个中转地址」这件事必须回电脑前坐下才能做，而那往往正是
- * 人不在电脑前的时候。
+ * 改地址 / 关遥控 / 吊销 / 重连 / 重启后台服务会掐断承载当前请求的隧道，所以一律先把响应
+ * 吐完再动手，手机看到 200 只代表「已受理」，结果靠重连后读状态。
  *
- * 这些项与「装/卸插件」不是一类东西：它们**不会让插件代码变**，最坏结果只是这台电脑从
- * 网上找不到 —— 而重连的主动权在手机这一侧（换地址、重新配对、同网走局域网），不会像
- * 装坏插件那样死锁。所以这一层的能力面是**有意放开给已配对手机**的。
- *
- * ## 直接调内部实现，不绕本机 HTTP
- *
- * 控制面那几条 `localOnly` 路由是为了防「中转进来的人」而存在的：它们能读进程级错误账本
- * （含堆栈）、能吊销全部授权。手机这边不能复用那道口子，所以这里**直接持有同一份
- * `settings`（relay.json 的 config store）**，走同一套 schema 校验 —— 两个入口写的是同一
- * 份真值，不会出现「面板说改了、手机说没改」。
- *
- * ## 会掐断自己那条隧道的动作
- *
- * 改中转地址 / 关遥控 / 吊销全部 / 重连 / 重启后台服务：这几条一动手，承载**这一发请求**
- * 的那条隧道就可能立刻断。所以它们一律「先把响应吐完再动手」（`AFTER_RESPONSE_MS`），
- * 手机看到 200 只代表「已经受理」，结果靠断线重连之后读状态判 —— 与插件自更新那条
- * `apply` 同一个手感，理由也一样：响应发不出去的时候，任何「返回结果」的设计都是假的。
- *
- * ## 注册密钥只进不出
- *
- * `status()` 与二维码都不回显它（宿主那边本来就这么写），这里也照做：只接受写入，
- * 状态里只报「设没设」。手机上看不到它，也就没有「读出来再抄走」这条路。
+ * 注册密钥只进不出：状态里只报「设没设」，手机看不到它。
  */
 
 const { randomBytes } = require('node:crypto');

package/lib/mobile/rpc.js

@@ -3,20 +3,12 @@
 /**
  * 调宿主 apiProxy 的两扇门：`sessions.*` 与 `agentPresets.*`。
  *
- * 抽出来是因为这两扇门此前各有两份实现——sessions.js 一份、agent-presets.js 一份
- * callAgentPresets（逐字相同），而 callSessions 是 sessions.js 内部 21 处的公共依赖，
- * 一旦 sessions.js 被拆分，21 处调用就得跟着搬家。
+ * 抽出来是因为两扇门此前各有一份逐字相同的实现，而 callSessions 是 sessions.js 里二十几处
+ * 的公共依赖。这里收的不只是转发，还有两件必须跟着走的语义：
  *
- * 这里收的不只是「转发」：callSessions 还带两件必须跟着转发走的语义。
- *
- * 1. signal 必须显式传。宿主 `sessions.<method>(request, signal)` 的第二个参数是
- *    取消信号，宿主内部 `isAborted(signal)` 直接读 `signal.aborted`、不做
- *    undefined 兜底：search 这类会查 signal 的方法不传就抛
- *    `Cannot read properties of undefined (reading 'aborted')`。
- * 2. list 的在途合流。sessions.list 会扫描所有压缩日志；同一个 Host 可能同时收到
- *    桌面 completion、移动端列表和通知监控的请求，不合流就是一次刷新被放大成 N 次
- *    磁盘扫描。**但写后刷新（?fresh=1）不能搭在途 list 的车**：被合流到的那个请求
- *    发起于写入之前，拿回来的是旧列表，于是「刚改完又显示成改之前」。
+ * 1. signal 必须显式传：宿主内部直接读 `signal.aborted`，不做 undefined 兜底，不传就抛。
+ * 2. list 的在途合流：每次 list 要扫全部压缩日志，不合流会把一次刷新放大成 N 次扫描。
+ *    但写后刷新（`?fresh=1`）不能搭车 —— 被合流到的请求发起于写入之前，拿回的是旧列表。
  *
  * 依赖方向：rpc.js → history-derive（只为 rpcId 前缀常量），是叶子之上的薄层。
  */

package/lib/mobile/schedule.js

@@ -3,42 +3,17 @@
 /**
  * 移动端「定时任务」API：把宿主 `ScheduleService` 的四件事转给手机。
  *
- * 桌面端有一套完整的定时任务：任务挂在会话上，到点把 prompt 投进会话，运行记录留在
- * 宿主里。手机端此前一条都看不到 —— 既不知道这个会话排了什么，也没法读「上次跑到
- * 什么时候」或者删掉一条排错的任务。本文件是宿主 `schedule` 服务的移动端代理。
+ * 服务走同进程直查 `ctx.get('schedule')`，不写进 `inject`：它是 Typert Remote 服务、不在
+ * apiProxy 命名空间里，写进 inject 会因为老宿主没有这个服务而挡住整个插件。
  *
- * 服务走同进程直查 `ctx.get('schedule')`，与 mobile/directory-browse.js 取
- * `directoryPicker` 是同一个先例：它是 Typert Remote 服务，不在 apiProxy 的命名空间
- * 里，写进 `inject` 反而会因为老宿主没有这个服务而挡住整个插件。
+ * 四条接口：catalog（全部任务）、list（该会话的任务）、history（一条任务的运行记录）、
+ * delete（硬删）。update 不做：手机端没有编辑入口，接一条没人调的路只会多一份参数校验。
  *
- * 四条接口对应宿主的四个公开方法：
- *  - GET  /api/mobile/v1/schedule/catalog  → `catalog()`         全部任务（active + inactive）
- *  - GET  /api/mobile/v1/schedule/list     → `catalog()` 里筛出该会话的任务（**active + inactive**）
- *  - GET  /api/mobile/v1/schedule/history  → `history({...})`    一条任务的运行记录
- *  - POST /api/mobile/v1/schedule/delete   → `delete({...})`     硬删
+ * list 走 `catalog()` 再按 sessionId 筛，不用宿主的 `list({sessionId})`：后者只回还在跑的
+ * 任务、行上没有 sessionId / status，一次性任务跑完就会从手机上「凭空消失」。
  *
- * `update` 这一批不做，别顺手接上：手机端暂时没有编辑入口，接一条没人调的路只会多一份
- * 要维护的参数校验。
- *
- * 宿主 catalog 的每项是「裸记录 + sessionId + status + 可选 lastDelivery」。手机只认一种
- * 形状：sessionId 必须带上，状态统一收成 `state`，删除 / 历史 / 修改都必须带行上的
- * sessionId，否则宿主恒回 not_found。
- *
- * **`list` 为什么不用宿主的 `list({sessionId})`**（2026-10-23 改）：宿主那个方法只回
- * **还在跑**的任务、而且回的是裸记录（没有 sessionId / status）。于是手机上按对话看任务时，
- * 一次性任务跑完就从这个入口消失了 —— 用户看到的是「任务凭空没了」，实际只是「结束了」。
- * 现在改成从 `catalog()`（active + inactive 全都有、行上带 status）里按 sessionId 筛，
- * 手机端因此能列出这条会话的全部任务（含已结束），筛选里那三档也才真正有意义。
- * 代价是一次多拉这份目录，它是宿主内存里的账、不是磁盘扫描，与统一页那一发等价。
- *
- * 收敛规则与 mobile/jobs.js 同口径：必填（id / kind / title / sessionId）坏了丢整条，
- * 可选字段坏了只丢字段 —— 少一个「下次运行时间」只是不显示，整条消失才是信息丢失。
- * 超长一律截断而不是丢整条：宿主已经校验过形状，这里的上限只防异常宿主把手机端列表
- * 撑爆。
- *
- * 服务不存在（老宿主）必须回 503 而不是空列表：App 要能分辨「这台电脑没有这个功能」
- * 和「一条任务都没有」，后者画空状态、前者画「升级宿主」。宿主调用抛错走 502，把原文
- * 带给 App —— 定时任务这块的错误多半是宿主的，插件不该换成一句「操作失败」。
+ * 收敛规则与 mobile/jobs.js 同口径：必填字段坏了丢整条，可选字段坏了只丢字段，超长截断。
+ * 服务不存在（老宿主）回 503 而不是空列表，App 才能分辨「没有这个功能」和「一条都没有」。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');