dsh-mobile-plugin 0.4.0 → 0.4.1

package/lib/mobile/host-bridge/event-synthesis.js

@@ -52,10 +52,9 @@ function sessionHint(request) {
 /**
  * 这条单会话流该按哪种地址订阅。
  *
- * 子会话必须换成 `{kind:'subagent'}` 的 durable 地址：宿主 `validateAddress` 对
- * `origin === 'subagent'` 的会话拿普通地址一律回 agent-busy，subscribe 直接失败 ——
- * 表现就是「子代理页面打得开，但内容永远不自己更新」。请求体里带上 `parentSessionId`
- * 就是「这是个子会话」的信号（与历史那条同源，见 stream.js 的 handleStream）。
+ * 子会话必须换成 `{kind:'subagent'}` 的 durable 地址：宿主对 `origin === 'subagent'` 的会话
+ * 拿普通地址一律回 agent-busy，subscribe 直接失败，表现是「子代理页面打得开，但内容永远
+ * 不自己更新」。请求体里的 `parentSessionId` 就是「这是个子会话」的信号。
  */
 function sessionAddress(payload) {
   const sessionId = payload && payload.sessionId;
@@ -86,11 +85,9 @@ const BASELINE_DELTA_TYPES = new Set(['text-delta', 'reasoning-delta', 'tool-cal
 /**
  * 展开 follow 首帧里那条「正在跑的那一步已生成的内容」。
  *
- * 宿主的 follow 第一帧是 `{type:'snapshot', cursor, assistantStream:{ revision, activeAttempt }}`，
- * `activeAttempt.stream` 是一份**压缩过的**增量记录（连续同块 delta 被压成
- * `{type:'text-chunks', index, time0, dt, texts}` 这类一条记录多个成员），
- * `nextIndex` 是「下一帧实时增量应有的密排位置」，也就是这条前缀展开后应有的成员数。
- * 中途进入会话的人只有这一份，宿主不会把已发过的实时帧补给他。
+ * 首帧的 `assistantStream.activeAttempt.stream` 是一份压缩过的增量记录（连续同块 delta 被
+ * 压成一条记录多个成员），`nextIndex` 是展开后应有的成员数。中途进入会话的人只有这一份，
+ * 宿主不会把已发过的实时帧补给他。
  *
  * 返回 `[{ time, chunk }]`；形状认不出就跳过那一条记录，绝不让整条流挂掉。
  */
@@ -166,20 +163,15 @@ function coalesceBaselineStream(members) {
 /**
  * follow 流的一帧 → 0..n 个 mux 帧（事件原样转发；实时增量通知合成 assistant/chunk）。
  *
- * 0.2.0 的宿主把逐块流式增量从「会话事件」里拿了出去：正文/推理的每个 delta 只以 follow 流的
- * `assistant-stream` 通知下发，而且**要显式传 `assistantStream: true` 才发**，事件流里只剩
- * 「一步落定」的 `assistant/message`。不订阅通知的话，正文与运行中明细都只能在一步结束时整块
- * 出现（真机故障 2026-10-21：回复整段蹦出来、运行中那一行没有实时明细）。
+ * 0.2.0 把逐块流式增量从会话事件里拿了出去：每个 delta 只以 follow 流的 `assistant-stream`
+ * 通知下发，而且要显式传 `assistantStream: true` 才发，事件流里只剩「一步落定」的
+ * `assistant/message`。不订阅通知的话，正文与运行中明细都只能在一步结束时整块出现。
  *
- * 合成事件用的是移动协议早已认识的 `assistant/chunk` 形状，但**不带 seq** —— 它没有持久化
- * 事件的身份，不该参与客户端的 seq 序门、去重与续传水位（App 侧对无 seq 帧一律放行），
- * turn/step 由最近一次 start 通知补上。设备级推送只看 turn/start、turn/end、session/title
- * （`lib/mobile/events.js` 的 LIST_EVENT_INNER），合成增量到不了那条通道，不会形成推送风暴。
+ * 合成的 `assistant/chunk` 不带 seq：它没有持久化事件的身份，不该参与客户端的 seq 序门、
+ * 去重与续传水位（App 对无 seq 帧一律放行），turn/step 由最近一次 start 通知补上。
  *
- * `state` 是这条流的记账（{ turn, step, streaming }），由调用方持有 —— 一帧的处理要看
- * 「之前收到过什么」。历史正文走 session.history，但首帧 snapshot 里那份
- * `assistantStream.activeAttempt` 不能丢：中途进入会话的人拿不到开跑之前的实时增量，
- * 那一段只存在于这份基线里（见 expandBaselineStream）。
+ * `state` 是这条流的记账（{ turn, step, streaming }），由调用方持有。首帧 snapshot 里那份
+ * `assistantStream.activeAttempt` 不能丢：中途进入会话的人拿不到开跑之前的实时增量。
  */
 function* followFramePayloads(frame, sessionId, state) {
   if (!frame) return;
@@ -293,22 +285,16 @@ function projectionState() {
 }
 
 /**
- * 宿主投影 `inbox` → 移动端 `session/queue` 帧的**平铺 items**。
+ * 宿主投影 `inbox` → 移动端 `session/queue` 帧的平铺 items。
  *
  * 形状差是这条链上唯一的坑：宿主把 inbox 定义成按键分组的对象
- * `{ 'next-turn': Message[], 'next-step': Message[] }`（桌面 bundle 里
- * `@deepseek-ai/dsh-agent-loop/inbox` 的 `key: 'inbox'` + `wire.view: (state) => state`，
- * 桌面 QueueDock 读的也正是 `inbox['next-turn']`），而移动端帧的约定是数组
- * `[{ id, placement, message }]`（`app/src/types/chatStream.ts` 的 QueueItem、
- * `app/src/hooks/streamFrame.ts` 的 `session/queue` 分支）。原样转发对象时 App 的
- * `Array.isArray(items)` 判定失败、整帧被静默丢弃 —— 排队条一次都不显示。
+ * `{ 'next-turn': Message[], 'next-step': Message[] }`，而移动端帧的约定是数组
+ * `[{ id, placement, message }]`。原样转发对象时 App 的 `Array.isArray(items)` 判定失败、
+ * 整帧被静默丢弃，排队条一次都不显示。
  *
- * `next-turn`（等下一轮才开始的消息）→ `placement: 'queued'`，QueueDock 只认这一个值。
- * `next-step`（已收下、等本步末尾注入的插话）→ `placement: 'steering'`：排队条与正文列表都
- * 只认 `queued`，所以它不会多画一行；它的用处是「宿主已经收下了」这条回执 —— 插话从发出去
- * 到真被插进去中间可能隔着好几个工具往返，此前手机上只挂着一颗「发送中…」。页脚那排插话
- * 气泡会把本机自己发的那几条排掉（`steeringForFooter`），不会与待发气泡双画。
- * `message.id` 用宿主行自己的 id，App 靠它与正文去重（chatRenderRows）。
+ * `next-turn` → `placement: 'queued'`（排队条只认这个值）；`next-step` → `'steering'`，
+ * 它只是「宿主已经收下了」的回执，不会多画一行。`message.id` 用宿主行自己的 id，App 靠它
+ * 与正文去重。
  */
 function queueItems(inbox, ctx) {
   const items = [];
@@ -385,7 +371,7 @@ function muxFrames(ctx, request, signal) {
       // **设备级这一支不能跟着宿主那几条流一起结束**：这条 SSE 还捎带着插件自己产的
       // 清单变更、正文水位与 15s 心跳（由 `handleDeviceStream` 直接写这条连接）。
       // 迭代器一返回，SSE 立刻收尾，手机端只会看到「连几秒就断」：信号永远不「活着」，
-      // 兜底轮询降不下去，每次重连还要重放一遍水位（2026-10-24 现场：17 帧后 loopEnded）。
+      // 兜底轮询降不下去，每次重连还要重放一遍水位。
       // 单会话那一支不适用 —— 会话结束了就该收尾。
       if (!signal || signal.aborted) return;
       await new Promise((resolve) => {

package/lib/mobile/host-bridge/shims.js

@@ -72,24 +72,16 @@ async function historyViaPage(ctx, payload, signal) {
 /**
  * `session.models` → `session.modelCatalog` + 会话自己的 `session/projections`。
  *
- * 宿主改成全局目录了（args 为空），字段也换了名：default → current、
- * routableProviders 变成「能不能用这个 provider」。移动端要的 groups 结构两边一致，
- * 原样带过去即可。
+ * 宿主改成全局目录了（args 为空），字段也换了名：default → current；移动端要的 groups 结构
+ * 两边一致，原样带过去即可。
  *
- * 但 `default` 是**全局**默认，不是「这个会话实际用的模型」。会话自己的模型记在
- * `session/projections` 的 `modelSelection` 投影里（`next` 是「下一次请求要用」，
- * 落到 `lastUsed` 是「最近一次真正跑过的」）；只有会话从没选过模型时，投影里才没有
- * 这一项，此时才回落到全局默认。桌面端「切到某个对话显示那个对话的模型」读的正是
- * 这份会话级投影，不是全局默认。移动端这里也要对同一口径，否则 A、B 两个会话各选
- * 了不同模型，手机却都显示同一个「默认模型」。
+ * `default` 是全局默认，不是「这个会话实际用的模型」。会话自己的模型记在
+ * `session/projections` 的 `modelSelection` 投影里（`next` 是下一次请求要用，`lastUsed` 是
+ * 最近一次真正跑过的）；从没选过时才回落到全局默认。读不到投影不是错误，退回全局默认即可，
+ * 别让整个模型面板消失。
  *
- * 读不到投影（会话不存在 / 宿主没挂投影能力）时不升级成错误：退回全局默认即可，
- * 让模型目录照常下发，宁可少一次会话级精修也不让整个模型面板消失。
- *
- * `defaultModel` 单独回一份**全局默认**，与 `current` 分开：宿主的新会话读的就是
- * 「最近一次成功保存的默认值」（`session.create` 不带模型时落这一条），所以 App 要
- * 显示「新对话会用哪个模型」只能看它 —— 拿任何一个会话的 `current` 去顶都是猜，
- * 会话各自选过的模型未必是默认。旧 App 忽略这个字段，行为不变。
+ * `defaultModel` 单独回一份全局默认：宿主的新会话读的就是最近一次成功保存的默认值，所以
+ * App 要显示「新对话会用哪个模型」只能看它，拿任何一个会话的 `current` 去顶都是猜。
  */
 async function modelCatalog(ctx, payload, signal) {
   const sessionId = payload && typeof payload.sessionId === 'string' ? payload.sessionId : '';
@@ -208,13 +200,11 @@ async function projectionBaseline(ctx, signal) {
 /**
  * `subagents.list` → `session.control` 投影基线 + `session.list`。
  *
- * 0.2.0 撤掉了 subagent.list 这个 RPC，但目录数据一条没少：它变成了会话投影里的
- * `subagentCatalog` 键，桌面端 @deepseek-ai/dsh-client-ui-subagent 的 CatalogDropdown
- * 就是读 `state.projectionsBySession` 渲染的。投影基线一次给出**全部**会话的 values，
- * 父子两层的目录在同一帧里 —— hasChildren 因此不需要按子会话再发 N 次投影查询。
+ * 0.2.0 撤掉了 subagent.list，但目录数据没少：它变成会话投影里的 `subagentCatalog` 键。
+ * 投影基线一次给出全部会话的 values，父子两层的目录在同一帧里，hasChildren 不需要再按子
+ * 会话逐个查。
  *
- * 投影里没有的是运行时状态：跑没在跑、父会话在不在线。桌面端也是拿 sessions.list 的
- * summaries 合成 activity 的，这里同口径再取一次会话列表，两边判定完全一致。
+ * 投影里没有运行时状态（跑没在跑、父会话在不在线），所以同口径再取一次会话列表的 summaries。
  */
 async function subagentCatalog(ctx, payload, signal) {
   const parentSessionId = payload && payload.parentSessionId;

package/lib/mobile/host-bridge.js

@@ -3,23 +3,13 @@
 /**
  * 0.2.0 兼容桥：旧 `apiProxy` 调用形状 → 宿主 `typertGateway`。
  *
- * 背景：DSH 0.2.0 删掉了 `apiProxy` 服务（整个 app.asar 里零命中），宿主 RPC 全部改走
- * `ctx.get('typertGateway')` 的 `invoke({namespace, method, args, signal})` / `stream(...)`。
- * 但本插件 17 个移动端模块历史上都是这一套：
+ * 0.2.0 删掉了 `apiProxy` 服务，宿主 RPC 全改走 `ctx.get('typertGateway')` 的 invoke /
+ * stream。本插件十几个移动端模块都按旧形状调用（`ctx.apiProxy.<ns>.<method>(…)`，返回
+ * `{ result: { ok, value|error } }`），这里提供同名同形状的服务，内部翻译成 gateway 调用并
+ * 把结果包回旧信封；将来宿主若恢复真 apiProxy，删掉这个目录即可。
  *
- *   请求：`ctx.apiProxy.<ns>.<method>({ rpcId, method: '<ns>.<method>', payload }, signal)`
- *   返回：`{ result: { ok: true, value } }` 或 `{ result: { ok: false, error } }`
- *
- * 与其逐个改 55 处调用点（每处都要对上宿主的 wire 参数名，而参数名错了只在运行时
- * 报 `gateway/arguments-invalid`），这里提供**同名同形状**的服务，内部翻译成
- * gateway 调用并把结果包回旧信封 —— 17 个文件一行都不用动，将来 DSH 若恢复真
- * `apiProxy`，把这个目录删掉、apply 里那一行 provide 去掉即可。
- *
- * 本文件只剩装配：把端点表铺成 `apiProxy.<ns>.<method>` 的形状。实现分四份：
- *   host-bridge/transport.js       网关传输与信封翻译（唯一知道「宿主怎么调」的地方）
- *   host-bridge/endpoints.js       端点表（键 ⇄ 宿主 wire 名与参数形状）
- *   host-bridge/shims.js           没有 1:1 端点、需要跨端点合成的几处
- *   host-bridge/event-synthesis.js 旧设备级 events.mux ⇄ 0.2.0 拆开的三条流
+ * 本文件只剩装配：实现分四份——transport（网关传输与信封翻译）、endpoints（端点表）、
+ * shims（需要跨端点合成的那几处）、event-synthesis（旧 mux ⇄ 三条新流）。
  */
 
 const { ENDPOINTS } = require('./host-bridge/endpoints.js');
@@ -31,10 +21,8 @@ const { unsupported, UNAVAILABLE } = require('./host-bridge/transport.js');
 /**
  * 把端点表铺成旧的 `apiProxy.<ns>.<method>` 形状。
  *
- * 键表直接从 ENDPOINTS 推，不再手写一份 `<ns>` → 方法名数组：两份表迟早会对不上，
- * 而对不上的后果不是报错，是 `ctx.apiProxy.<ns>.<method> is not a function` 这种在
- * 别的模块、别的请求里炸出来的 TypeError（新增 sessions.projections 时就漏登记过一次，
- * /session/stats 会跟着一起挂）。现在新增端点只改 ENDPOINTS 一处。
+ * 键表直接从 ENDPOINTS 推，不再手写一份：两份表对不上时的症状不是报错，而是别的模块里炸
+ * 出 `ctx.apiProxy.<ns>.<method> is not a function`。新增端点只改 ENDPOINTS 一处。
  */
 function createApiProxy(ctx) {
   const namespaces = {};

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