dsh-mobile-plugin 0.5.8 → 0.5.10

package/lib/mobile/attachment-store.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * 宿主附件库的直读 —— 手机取图那条路少绕一圈。
+ *
+ * 为什么要有它：手机要一张图时，插件今天只能调宿主的取附件接口，拿回**整份 base64** 再
+ * 解成字节、分块写给手机。那一发要等宿主把整张读出来、编码完才返回，宿主主线程正忙
+ * （比如在派生一条几千条的会话）时，手机那边就是一个字节都没有 —— 2026-10-31 中转日志里
+ * 有 109 次请求整整 15 秒收不到任何字节，全部是这一条路上来的。
+ *
+ * 附件在宿主本机本来就是**按内容哈希分两级目录存的文件**（`<DSH_HOME>/attachments/v1/
+ * objects/<前两位>/<其余>`），插件和宿主同机同进程，直接从盘上流进隧道就行：首字节不等
+ * 宿主做主活，内存里也不再摊一份两兆七的 base64 字符串。
+ *
+ * **只认「我们确实告诉过手机的那几个 id」**（`remember` 在引用下发时记账）。这条不是多余的
+ * 防御：附着在会话里的图片 id 是我们自己下发的，反过来「拿任意一个 64 位十六进制串来读」
+ * 就不该成立 —— 能力面与 `session/file`、`session/local-image` 同一条口径：只读登记过的。
+ * 记账没命中、文件不在、不是加密会话，一律退回原来那条宿主接口，行为与今天完全一致。
+ *
+ * 记账只在内存里：插件重启后手机重连会重新拉一遍消息、重新登记；过期与上限见下面两个常量。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { dshHome } = require('../shared/paths.js');
+const { chunksHeaders, pipeEncrypted } = require('../shared/e2ee-chunks.js');
+
+/** 一个会话最多记多少个附件 id（会话里几千张图也不该无限涨）。 */
+const MAX_IDS_PER_SESSION = 4096;
+/** 最多记多少个会话（滚动淘汰最久没登记的）。 */
+const MAX_SESSIONS = 64;
+/** 记账多久算新鲜：超过这个时间没再被引用过，就当手机手里那份已经过期了。 */
+const TTL_MS = 30 * 60 * 1000;
+
+/** sessionId -> { at, entries: Map<attachmentId, { mediaType, at }> } */
+const SESSIONS = new Map();
+
+/** 内容哈希是 64 位小写十六进制；别的形状一律不认（顺带挡住路径穿越）。 */
+const OBJECT_ID = /^[0-9a-f]{64}$/;
+
+function nowMs() {
+  return Date.now();
+}
+
+/**
+ * 附件 id → 宿主附件库里的绝对路径。
+ *
+ * 形状不对（不是 64 位小写十六进制）直接回 null：这条路径要拼进 `createReadStream`，
+ * 校验放在这里、而不是靠调用方记得先校验。
+ */
+function objectPathOf(attachmentId) {
+  if (typeof attachmentId !== 'string' || !OBJECT_ID.test(attachmentId)) return null;
+  const root = path.join(dshHome(), 'attachments', 'v1', 'objects');
+  return path.join(root, attachmentId.slice(0, 2), attachmentId.slice(2));
+}
+
+/** 记账：这个附件我们刚在 `sessionId` 的消息里下发过（手机接下来就可能来取字节）。 */
+function remember(sessionId, attachmentId, mediaType) {
+  if (typeof sessionId !== 'string' || !sessionId) return;
+  if (typeof attachmentId !== 'string' || !OBJECT_ID.test(attachmentId)) return;
+  const at = nowMs();
+  let slot = SESSIONS.get(sessionId);
+  if (!slot) {
+    slot = { at, entries: new Map() };
+    SESSIONS.set(sessionId, slot);
+    // 会话数到顶：淘汰最久没动静的那一个（Map 保持插入顺序，第一条就是最旧的）。
+    while (SESSIONS.size > MAX_SESSIONS) {
+      const oldest = SESSIONS.keys().next().value;
+      if (oldest === undefined) break;
+      SESSIONS.delete(oldest);
+    }
+  }
+  slot.at = at;
+  slot.entries.delete(attachmentId);
+  slot.entries.set(attachmentId, {
+    at,
+    mediaType: typeof mediaType === 'string' && mediaType ? mediaType : 'application/octet-stream',
+  });
+  while (slot.entries.size > MAX_IDS_PER_SESSION) {
+    const oldest = slot.entries.keys().next().value;
+    if (oldest === undefined) break;
+    slot.entries.delete(oldest);
+  }
+}
+
+/** 这个 id 是不是我们为这条会话下发过的；是就带上当时的媒体类型。 */
+function lookup(sessionId, attachmentId, now = nowMs()) {
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  if (typeof attachmentId !== 'string' || !attachmentId) return null;
+  const slot = SESSIONS.get(sessionId);
+  if (!slot) return null;
+  if (now - slot.at > TTL_MS) {
+    SESSIONS.delete(sessionId);
+    return null;
+  }
+  const hit = slot.entries.get(attachmentId);
+  if (!hit) return null;
+  if (now - hit.at > TTL_MS) {
+    slot.entries.delete(attachmentId);
+    return null;
+  }
+  return { mediaType: hit.mediaType };
+}
+
+/** 打开一条只读流（调用方自己负责在连接关掉时 destroy）。 */
+function openObject(attachmentId) {
+  const target = objectPathOf(attachmentId);
+  if (!target) return null;
+  try {
+    const stat = fs.statSync(target);
+    if (!stat.isFile() || stat.size <= 0) return null;
+    return { path: target, size: stat.size, stream: fs.createReadStream(target) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 试一次「直接从盘上流给手机」：写成功返回 true，不该走或走不了返回 false。
+ *
+ * 三个前提缺一不可：这条请求带信封（协议 v2 才走分块）、这个 id 是我们为这条会话下发过的、
+ * 对象文件确实还在。任一不满足就交给调用方走原来那条宿主接口 —— 老插件、老会话、明文会话
+ * 的行为因此一个字都不变。
+ */
+async function streamIfRemembered(req, res, sessionId, attachmentId) {
+  const opened = req && req.__dshE2ee;
+  if (!opened || !opened.keys || !opened.req) return false;
+  const known = lookup(sessionId, attachmentId);
+  if (!known) return false;
+  const object = openObject(attachmentId);
+  if (!object) return false;
+  res.writeHead(200, chunksHeaders({
+    'x-dsh-content-type': known.mediaType,
+    'x-dsh-file-size': String(object.size),
+  }));
+  res.on('close', () => object.stream.destroy());
+  await pipeEncrypted(req, res, object.stream);
+  return true;
+}
+
+/** 测试用：清空记账。 */
+function reset() {
+  SESSIONS.clear();
+}
+
+module.exports = {
+  MAX_IDS_PER_SESSION,
+  MAX_SESSIONS,
+  TTL_MS,
+  objectPathOf,
+  remember,
+  lookup,
+  openObject,
+  streamIfRemembered,
+  reset,
+};

package/lib/mobile/attachments.js

@@ -19,6 +19,7 @@ const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const { cwdOf } = require('./session-cwd.js');
 const { inlineTextImages, createTextImageBudget, hasRelativeImage } = require('./local-images.js');
+const attachmentStore = require('./attachment-store.js');
 
 /**
  * 取不到字节的图片块：原样留着，只加一个标记。
@@ -54,7 +55,12 @@ async function resolveEventAttachments(ctx, sessionId, event, opts = {}) {
       const attachmentId = block.attachment.attachmentId;
       if (typeof attachmentId !== 'string' || !attachmentId) return block;
       // 引用模式到此为止：块原样返回，字节由手机端按 attachmentId 单张去取。
-      if (referencesOnly) return block;
+      if (referencesOnly) {
+        // 顺便记一笔：手机接下来就可能拿着这个 id 来取字节。记下来之后那条路可以直接从
+        // 宿主附件库流给它，不必再等宿主把整张图读成 base64（见 attachment-store.js）。
+        attachmentStore.remember(sessionId, attachmentId, block.attachment.mediaType || block.mediaType);
+        return block;
+      }
       let result;
       try {
         result = unwrap(await callSessions(ctx, 'attachment', { sessionId, attachmentId }));

package/lib/mobile/channels.js

@@ -17,6 +17,7 @@
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { unwrap } = require('./envelope.js');
 const { dropSessionModelsForDevice } = require('./session-cache.js');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 
 /** 自建渠道写在这个命名空间里；桌面端 `src/custom-channels.js` 的 PI_AI_NS 同值。 */
 const PI_AI_NS = 'llm-pi-ai';
@@ -280,7 +281,8 @@ async function handleChannels(ctx, req, res) {
     });
   }
 
-  sendJson(res, 200, { ok: true, channels });
+  const body = { ok: true, channels, revision: stableRevision(channels) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 /**
@@ -311,11 +313,41 @@ function lookupService(ctx, name) {
 }
 
 /**
- * POST /api/mobile/v1/channels/discover（token）{ protocol, baseUrl, apiKey? }
+ * 宿主 `llm.discoverModels` 的失败 → 中文一句（宿主的英文原话留在 `details.hostMessage`）。
+ *
+ * 宿主的原话是英文（`could not reach …`、`… answered 401; check the API key`），而 App 那边
+ * 规定英文原话不上界面（`services/http` 的 `unwrapResult` 会整句换成「电脑那边出了错，请重试」），
+ * 「连不上地址」与「Key 不对」在手机上就分不出来。所以在这一层按已经见到的几种形状换成中文：
+ * App 拿到的原话是中文就照原样显示，用户读得到下一步该干什么。
+ */
+function discoverFailureMessage(caught) {
+  const raw = caught && typeof caught.message === 'string' ? caught.message : String(caught == null ? '' : caught);
+  const code = caught && typeof caught.code === 'string' ? caught.code : '';
+  if (/could not reach/i.test(raw)) return '连不上这个地址：确认地址没写错，也确认这台电脑访问得到它';
+  const answered = /answered (\d{3})/i.exec(raw);
+  if (answered) {
+    const status = answered[1];
+    if (status === '401' || status === '403') return '这个地址要求鉴权：Key 不对或者没填';
+    return `这个地址没有模型清单这个接口（HTTP ${status}），检查地址有没有多写路径`;
+  }
+  if (/did not answer with JSON/i.test(raw)) return '这个地址回的不是模型清单，可能填成了网页地址';
+  if (/no model listing this build can read/i.test(raw)) return '这条协议取不到模型清单，手动填模型 id 吧';
+  if (/no credential for provider route/i.test(raw) || /API key is blank/i.test(raw)) {
+    return '这条渠道在这台电脑上没有可用的 Key，填一次 Key 再获取';
+  }
+  return `取模型失败${code ? `（${code}）` : ''}`;
+}
+
+/**
+ * POST /api/mobile/v1/channels/discover（token）{ id?, protocol, baseUrl, apiKey? }
  * → { ok, models: [{id,name,contextWindow?,maxTokens?,vision?}], baseUrl }
  *
  * `baseUrl` 回的是**问通的那个**：`/v1` 回退成功时保存要写它，否则聊天请求还会打到
  * 刚才失败的那个地址上。只读不落盘，用户确认清单之后再调 `/channels/save`。
+ *
+ * `id` 是编辑中的那条渠道：宿主按路由名就能在「请求没带 Key」时自己去凭据库取原来那把
+ * （`discoverModels` 的 `provider`），所以表单里 Key 留空也能取模型。新建时没有 id，
+ * 沿用当场填的那把。
  */
 async function handleChannelDiscover(ctx, req, res) {
   const body = await readJsonBody(req, 64 * 1024);
@@ -325,6 +357,10 @@ async function handleChannelDiscover(ctx, req, res) {
   }
   const base = normalizeBaseUrl(body ? body.baseUrl : undefined);
   if (base.error) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: base.error } });
+  const editingId = body && typeof body.id === 'string' ? body.id.trim() : '';
+  if (editingId !== '' && !CHANNEL_ID_PATTERN.test(editingId)) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '渠道 id 不合法' } });
+  }
   const apiKey = body && typeof body.apiKey === 'string' ? body.apiKey.trim() : '';
   if (apiKey.length > MAX_KEY_CHARS) {
     return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'API Key 太长' } });
@@ -342,6 +378,7 @@ async function handleChannelDiscover(ctx, req, res) {
   for (const baseURL of discoverCandidates(base.url, protocol)) {
     try {
       const found = await llm.discoverModels(PI_AI_NS, {
+        ...(editingId === '' ? {} : { provider: editingId }),
         baseURL,
         api: protocol,
         ...(apiKey === '' ? {} : { apiKey }),
@@ -368,10 +405,16 @@ async function handleChannelDiscover(ctx, req, res) {
       lastError = caught;
     }
   }
-  // 协议层 / 渠道包的话本身就是给用户看的（「answered 401; check the API key」），原样透出。
+  // 失败说人话：宿主那几句英文摆到手机的英文过滤后面会变成「电脑那边出了错」，原文留在 details。
+  const hostMessage = String((lastError && lastError.message) || lastError).slice(0, 300);
+  const hostCode = lastError && typeof lastError.code === 'string' ? lastError.code : '';
   sendJson(res, 422, {
     ok: false,
-    error: { code: 'discover-failed', message: String((lastError && lastError.message) || lastError).slice(0, 300) },
+    error: {
+      code: 'discover-failed',
+      message: discoverFailureMessage(lastError),
+      details: { hostMessage, ...(hostCode === '' ? {} : { hostCode }) },
+    },
   });
 }
 

package/lib/mobile/events.js

@@ -16,7 +16,7 @@ const { createFrameSealer } = require('./stream.js');
 const { listSignal: sharedListSignal } = require('../shared/list-signal.js');
 const { sessionSignal: sharedSessionSignal } = require('../shared/session-signal.js');
 const { desktopViewSignal: sharedDesktopViewSignal } = require('../shared/desktop-view-signal.js');
-const { writeSse: sharedWriteSse, stableEventId: sharedEventId } = require('../shared/sse-write.js');
+const { writeSse: sharedWriteSse, stableEventId: sharedEventId, waitForDrain } = require('../shared/sse-write.js');
 
 const DEDUP_WINDOW = 2048;
 /** 心跳帧间隔。App 用它判定「这条流真的还活着」，必须与 app 侧的 SIGNAL_HEARTBEAT_MS 一致。 */
@@ -153,10 +153,35 @@ async function handleDeviceStream(ctx, req, res) {
     // shed 不是成功：不能继续读，否则这一帧代表的变更永远补不回来。
     if (result.shed) return false;
     framesSent += 1;
-    // 所有调用点都是同步回调（信号总线、心跳），没法在这里 await；写不动就如实回报，
-    // 由调用方 abort —— 这条流本来就是「断了重连、靠补发收敛」的语义。
+    // 这几处调用点都是同步回调（信号总线、心跳），没法在这里 await；写不动就如实回报，
+    // 由调用方 abort —— 这条流本来就是「断了重连、靠补发收敛」的语义。开场那一批补发
+    // 不走这里，走下面的 `writeFrameAwaiting`：那批是一口气几十上百帧，必然会撞上写缓冲。
     return !result.needDrain;
   };
+  /**
+   * 补发快照专用：写一帧，写不动就等缓冲吐出去再接着写。
+   *
+   * 与 `writeFrame` 只差一件事：`needDrain` 不是失败，是「慢」。开场补发是每台被跟踪的
+   * 会话各一帧的水位快照，会话多的机器一上来就超出一条连接的写缓冲（Node 的高水位默认
+   * 16KB），把它当失败就等于**每次连上补完就自己掐掉**，手机重连再补一遍，永远建立不起来；
+   * 顺带连「积压到软水位才 shed」那道闸都轮不到。会话流（`stream.js`）的 live 循环就是
+   * 等 drain 再继续，这里照同一套来。
+   *
+   * @returns {Promise<boolean>} 这一帧写成功（或等到了 drain）→ true；该收尾 → false。
+   */
+  const writeFrameAwaiting = async (devicePayload) => {
+    const result = writeSse(res, {
+      type: 'device/event',
+      version: 1,
+      payload: devicePayload,
+    }, null, sealFrame);
+    if (!result.ok) return false;
+    // shed 不是成功：不能继续读，否则这一帧代表的变更永远补不回来。
+    if (result.shed) return false;
+    framesSent += 1;
+    if (result.needDrain && !(await waitForDrain(res, ac.signal))) return false;
+    return true;
+  };
   /**
    * 自产的「清单变了」帧：镜像推送调度器每 500ms 比一次清单内容哈希，变了就推给手机。
    *
@@ -208,26 +233,27 @@ async function handleDeviceStream(ctx, req, res) {
    * 只读两条信号总线已经广播过的最近值，既不 bump 也不前移基准，所以不会制造新变更；
    * App 对同 revision / 同水位幂等，重连补发不会引发重复刷新。
    */
-  const replayKnownSignals = () => {
+  const replayKnownSignals = async () => {
     const list = sharedListSignal.snapshot();
     if (list && list.revision) {
-      if (!writeFrame({ type: 'device/list-changed', revision: list.revision, at: list.at || Date.now() })) return false;
+      if (!await writeFrameAwaiting({ type: 'device/list-changed', revision: list.revision, at: list.at || Date.now() })) return false;
     }
     // 桌面侧栏折叠态：手机从此只在变化时拉一次。老 App 不认识这一帧（走默认分支忽略），
     // 所以补发它不会改变老客户端的任何行为。
     const view = sharedDesktopViewSignal.snapshot();
     if (view && view.updatedAt > 0) {
-      if (!writeFrame({ type: 'device/desktop-view-changed', updatedAt: view.updatedAt, at: view.at || Date.now() })) return false;
+      if (!await writeFrameAwaiting({ type: 'device/desktop-view-changed', updatedAt: view.updatedAt, at: view.at || Date.now() })) return false;
     }
     for (const [sessionId, seq] of Object.entries(sharedSessionSignal.snapshot())) {
       if (!(seq > 0)) continue;
-      if (!writeFrame({ type: 'device/session-activity', sessionId, seq, at: Date.now() })) return false;
+      if (!await writeFrameAwaiting({ type: 'device/session-activity', sessionId, seq, at: Date.now() })) return false;
     }
     return true;
   };
-  // 补发失败说明连接已经不可写（writeSse 只在 res.write 抛错时返回 false），此时
-  // 继续跑 mux 循环只会一路失败；abort 掉让它走正常收尾。
-  if (!replayKnownSignals()) ac.abort();
+  // 补发失败说明连接真的已经不可写（writeSse 只在 res.write 抛错时返回 false），此时
+  // 继续跑 mux 循环只会一路失败；abort 掉让它走正常收尾。写缓冲满了不算失败，见
+  // `writeFrameAwaiting`。
+  if (!await replayKnownSignals()) ac.abort();
   const keepAlive = setInterval(() => {
     try { res.write(': keepalive\n\n'); } catch { ac.abort(); return; }
     // 心跳必须是**数据帧**：注释帧 App 看不见，而 App 只有「最近真的收到过帧」才敢把
@@ -273,7 +299,11 @@ async function handleDeviceStream(ctx, req, res) {
       // Keep the existing device/event JSON envelope unchanged; SSE metadata is additive.
       const sent = writeSse(res, envelope, frame, sealFrame);
       if (sent.shed) { clientGone = true; break; }
-      if (!sent.ok || sent.needDrain) { clientGone = true; break; }
+      if (!sent.ok) { clientGone = true; break; }
+      // 写不动就等一次 drain 再接着读：这条循环本来就是 async，等一等比断掉重连便宜得多
+      // （重连要补发整份快照，手机那边还要重拉一遍清单与正文）。等不到（超时或流被中断）
+      // 才收尾。
+      if (sent.needDrain && !(await waitForDrain(res, ac.signal))) { clientGone = true; break; }
       framesSent += 1;
     }
     if (!clientGone) loopEnded = true;

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

@@ -159,6 +159,33 @@ function hostRequest(ctx, namespace, method, args, signal) {
   return request;
 }
 
+/**
+ * 撤掉网关还挂着的那一发远程转发（桌面窗口那张卡挂在它上面）。
+ *
+ * 网关按**请求对象本身**登记挂起的转发，所以按 `requestRef` 认回那一发、调它自己的撤回接口：
+ * 窗口收到 `cancel` 帧后按 abort 处理，卡跟着撤，不会冒成错误提示。认不到就什么都不做 ——
+ * 老宿主没有 `pendingRemoteEvents` / `cancelRemoteEvent`，「桌面那边没卡可收」本来就是对的。
+ *
+ * 放在这里而不是调用方：调用方（提问桥）只知道「这一问的那一发撤掉」，两个成员名与迭代方式
+ * 跟 invoke / stream 一样属于传输层 —— 别在别处再摸一次 `typertGateway`。
+ *
+ * @returns {number} 真的撤掉了几发
+ */
+function cancelForwardedRequests(ctx, requestRef, reason) {
+  const gateway = gatewayOf(ctx);
+  const pending = gateway && gateway.pendingRemoteEvents;
+  if (!pending || typeof pending.values !== 'function' || typeof gateway.cancelRemoteEvent !== 'function') return 0;
+  let cancelled = 0;
+  for (const item of [...pending.values()]) {
+    if (!item || !item.source || item.source.request !== requestRef) continue;
+    try {
+      gateway.cancelRemoteEvent(item, reason);
+      cancelled += 1;
+    } catch { /* 那一发已经走了（别人先收掉）：没什么可撤的 */ }
+  }
+  return cancelled;
+}
+
 async function invoke(ctx, namespace, method, args, signal) {
   const gateway = gatewayOf(ctx);
   if (!gateway) return { error: { ...UNAVAILABLE } };
@@ -222,4 +249,4 @@ async function invokeEnvelope(ctx, namespace, method, args, signal) {
   return ok(result.value);
 }
 
-module.exports = { GATEWAY_MISSING, UNAVAILABLE, unsupported, deadline, gatewayOf, warn, pick, ok, errorOf, fail, requestId, dropUnexpectedArgs, invoke, openStream, invokeEnvelope, SYNTHETIC_DEADLINE_MS };
+module.exports = { GATEWAY_MISSING, UNAVAILABLE, unsupported, deadline, gatewayOf, warn, pick, ok, errorOf, fail, requestId, dropUnexpectedArgs, invoke, cancelForwardedRequests, openStream, invokeEnvelope, SYNTHETIC_DEADLINE_MS };

package/lib/mobile/host-settings.js

@@ -12,6 +12,7 @@
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 const { unwrap } = require('./sessions.js');
 
 const HOST_SETTINGS_MAX_NAMESPACES = 60; // 命名空间数量上限（避免异常宿主把响应撑爆）
@@ -245,7 +246,12 @@ async function handleHostSettings(ctx, req, res) {
   });
 }
 
-/** GET /api/mobile/v1/llm/providers —— 宿主的模型提供方名单（只读）。 */
+/**
+ * GET /api/mobile/v1/llm/providers —— 宿主的模型提供方名单（只读）。
+ *
+ * 带 `?rev=` 时按内容指纹走条件响应：名单没变就只回一句 `unchanged`（几十字节），
+ * 不再把整份重传一遍。手机那边把它当设备级目录缓存，进页面先摆上次那份、再拿指纹问一次。
+ */
 async function handleLlmProviders(ctx, req, res) {
   const { value, error } = unwrap(await ctx.apiProxy.llm.providers({
     rpcId: 'mobile',
@@ -257,7 +263,8 @@ async function handleLlmProviders(ctx, req, res) {
   const list = Array.isArray(value && value.providers) ? value.providers : [];
   const providers = list.map(normalizeProvider).filter(Boolean);
 
-  sendJson(res, 200, { ok: true, providers });
+  const body = { ok: true, providers, revision: stableRevision(providers) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 /**
@@ -303,6 +310,9 @@ function normalizeModelGroup(group) {
  *
  * 与 `/llm/providers` 的区别：那条只说「有哪些提供方 / 哪个在生效」，这条给出每个提供方
  * 下面真正可请求的模型 id。手机上没有活动会话时（比如从 Git 页打开选择器）也能拿到。
+ *
+ * 这一份是全仓最大的一份目录响应（每个提供方下面几十上百条模型），而它只在用户加渠道、
+ * 换模型时变，所以同样吃 `?rev=` 的条件响应：没变时几十字节说清，别整份重传。
  */
 async function handleLlmModels(ctx, req, res) {
   const { value, error } = unwrap(await ctx.apiProxy.llm.models({
@@ -314,7 +324,8 @@ async function handleLlmModels(ctx, req, res) {
 
   const list = Array.isArray(value && value.groups) ? value.groups : [];
   const groups = list.map(normalizeModelGroup).filter(Boolean).slice(0, HOST_SETTINGS_MAX_NAMESPACES);
-  sendJson(res, 200, { ok: true, groups });
+  const body = { ok: true, groups, revision: stableRevision(groups) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 const HOST_SETTINGS_MAX_OPS = 40;   // 一次写入的 op 数量上限

package/lib/mobile/local-images.js

@@ -133,6 +133,56 @@ function createTextImageBudget(limit = MAX_TEXT_IMAGES) {
   return { remaining: limit };
 }
 
+/**
+ * JPEG 的 EXIF 朝向（0x0112），没有就返回 0。
+ *
+ * 手机相机竖着拍出来的照片，像素本身是横的，靠 EXIF 里的朝向告诉播放器「先转 90°」。
+ * 宽高只按像素读的话，正文里就会出现「横盒子装竖图」：App 按 `resizeMode="contain"` 画，
+ * 图缩成中间一条、两侧一大片空白（2026-10-31 平板实测）。所以 5–8 这四档要对调宽高。
+ *
+ * 只认 JPEG：PNG / WebP 里带 eXIf 的极少，不值得为它多扫一遍。
+ */
+function jpegOrientation(buf) {
+  let at = 2;
+  while (at + 4 < buf.length) {
+    if (buf[at] !== 0xff) { at += 1; continue; }
+    const marker = buf[at + 1];
+    if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { at += 2; continue; }
+    // 到扫描数据了，后面不会再有 APP 段。
+    if (marker === 0xda) return 0;
+    const length = buf.readUInt16BE(at + 2);
+    if (length < 2) return 0;
+    if (marker === 0xe1 && at + 10 <= buf.length && buf.toString('latin1', at + 4, at + 10) === 'Exif\0\0') {
+      return tiffOrientation(buf, at + 10);
+    }
+    at += 2 + length;
+  }
+  return 0;
+}
+
+/** EXIF 里的 TIFF 头 → 朝向值；字节序按 `II` / `MM` 判，读不到返回 0。 */
+function tiffOrientation(buf, base) {
+  if (base + 8 > buf.length) return 0;
+  const order = buf.toString('latin1', base, base + 2);
+  if (order !== 'II' && order !== 'MM') return 0;
+  const little = order === 'II';
+  const u16 = (at) => (little ? buf.readUInt16LE(at) : buf.readUInt16BE(at));
+  const u32 = (at) => (little ? buf.readUInt32LE(at) : buf.readUInt32BE(at));
+  if (u16(base + 2) !== 42) return 0;
+  const ifd = base + u32(base + 4);
+  if (ifd + 2 > buf.length) return 0;
+  const count = u16(ifd);
+  for (let i = 0; i < count; i += 1) {
+    const entry = ifd + 2 + i * 12;
+    if (entry + 12 > buf.length) return 0;
+    if (u16(entry) === 0x0112) {
+      const value = u16(entry + 8);
+      return value >= 1 && value <= 8 ? value : 0;
+    }
+  }
+  return 0;
+}
+
 /** 从文件头解析宽高；认不出来返回 null（不是错误：App 那边照旧现量）。 */
 function imageSizeOf(buf) {
   if (buf.length >= 24 && buf[0] === 0x89 && buf.toString('latin1', 1, 4) === 'PNG') {
@@ -152,6 +202,10 @@ function imageSizeOf(buf) {
     return null;
   }
   if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+    // 竖拍照片的像素本身是横的，朝向 5–8 时播放器会转 90° 再画 —— 宽高必须跟着对调，
+    // 否则正文那个盒子是横的、图是竖的（见 jpegOrientation）。
+    const orientation = jpegOrientation(buf);
+    const swap = orientation >= 5 && orientation <= 8;
     let at = 2;
     while (at + 9 < buf.length) {
       if (buf[at] !== 0xff) { at += 1; continue; }
@@ -159,7 +213,9 @@ function imageSizeOf(buf) {
       if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { at += 2; continue; }
       const length = buf.readUInt16BE(at + 2);
       if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
-        return { width: buf.readUInt16BE(at + 7), height: buf.readUInt16BE(at + 5) };
+        const width = buf.readUInt16BE(at + 7);
+        const height = buf.readUInt16BE(at + 5);
+        return swap ? { width: height, height: width } : { width, height };
       }
       if (length < 2) return null;
       at += 2 + length;

package/lib/mobile/plugins.js

@@ -14,6 +14,7 @@
  */
 
 const { sendJson } = require('../shared/http-util');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 const { invoke, UNAVAILABLE: GATEWAY_UNAVAILABLE } = require('./host-bridge/transport.js');
 
 const PLUGIN_ID_MAX_CHARS = 200;      // entryId 长度上限
@@ -96,7 +97,10 @@ function statusOf(error) {
 
 /**
  * GET /api/mobile/v1/plugins
- * 成功：{ ok:true, items:[{ entryId, moduleName, enabled, fiberPhase }] }
+ * 成功：{ ok:true, items:[{ entryId, moduleName, enabled, fiberPhase }], revision }
+ *
+ * 带 `?rev=` 时走条件响应：清单没变就只回一句 `unchanged`。插件清单只在装 / 卸 / 启停 /
+ * 重启之后变，而手机每进一次「插件清单」页都要读它一遍。
  */
 async function handlePlugins(ctx, req, res) {
   const result = await callInventory(ctx);
@@ -109,7 +113,8 @@ async function handlePlugins(ctx, req, res) {
     items.push(entry);
     if (items.length >= PLUGIN_MAX_ITEMS) break;
   }
-  sendJson(res, 200, { ok: true, items });
+  const body = { ok: true, items, revision: stableRevision(items) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 module.exports = {

package/lib/mobile/questions.js

@@ -16,6 +16,7 @@
 
 const { randomUUID } = require('node:crypto');
 const { sendJson, readJsonBody } = require('../shared/http-util');
+const { cancelForwardedRequests } = require('./host-bridge/transport.js');
 
 /** sessionId → Set<sink>：正在看这个会话的手机连接（每条 SSE 一个 sink）。 */
 const watchers = new Map();
@@ -208,6 +209,8 @@ function normalizeAnswers(questions, answers) {
 /** 绑上钩子请求：从此这条挂起项「答得动」，并接上宿主的取消信号。 */
 function bindRequest(entry, request) {
   entry.bound = true;
+  // 留一个身份引用：手机答完之后要按它找回宿主转发给桌面窗口的那一发（见 cancelForwardedCards）。
+  entry.requestRef = request;
   pushCard(entry);
   const signal = request.signal;
   if (!signal || typeof signal.addEventListener !== 'function') return;
@@ -233,10 +236,10 @@ function noAnswerer(error) {
  * 挂起这条请求直到有人回答：桌面的转发与手机的卡**同时进行**，谁先答就用谁的答案。
  *
  * 桌面先答：下游给出答案，结算挂起项（手机那张卡由结算帧收掉）。
- * 手机先答：把手机的回答交回钩子。桌面那张卡由宿主自己收尾 —— 这一问落定后宿主的限时
- * 等待随之结束，桌面客户端把「被转发的请求」delegate 回来，卡跟着撤掉，会话投影也不再
- * 列这个 call。那一下会让 `downstream` 再落一次；上面的 race 已经挂着它的处理函数，迟到
- * 的那次不会冒成未处理异常，`settle` 本身也是幂等的，收卡与回答都不受影响。
+ * 手机先答：把手机的回答交回钩子，桌面那张卡由 `cancelForwardedCards` 主动收掉 —— 宿主
+ * 只在「限时提问」里给这条转发做了收尾，本桥跑的这版宿主是阻塞式提问，没人替桌面窗口
+ * 撤回那一发，卡会一直悬着直到人手动点。那一发被撤时 `downstream` 会再落一次；上面的
+ * race 已经挂着它的处理函数，迟到的那次不会冒成未处理异常，`settle` 本身也是幂等的。
  *
  * `NO_PROVIDER`（桌面没开 / 桌面把请求 delegate 回来）不是结论：手机正在看这个会话时
  * 卡还在手机上等着，继续等手机答；没人看时照旧把失败交回去，纯桌面表现一字不改。
@@ -260,6 +263,22 @@ function holdForPhone(entry, next) {
   return Promise.race([fromPhone, downstream]);
 }
 
+/**
+ * 收掉桌面那张卡：把宿主已经发给桌面窗口、还挂着的那一发转发撤掉。
+ *
+ * 桌面那张卡不是本桥画的：宿主把提问转发给桌面窗口之后，窗口自己按那一发长出一张卡，
+ * 只有三种情况会让它消失 —— 桌面自己答、这一轮被取消、宿主主动撤回那一发。「两边同时
+ * 出卡」靠的就是转发，而宿主只在「限时提问」路径上做了落定后的撤回；这版宿主的
+ * `ask_user_question` 跑的是阻塞式，手机先答之后没人去收，卡就一直悬着。
+ *
+ * 认哪一发、怎么撤都由传输层做（网关按请求对象本身登记这些挂起的转发）：这里只把「这一问
+ * 的请求对象」交出去。认不到（老宿主没这道网关）就什么都不做 —— 「桌面没卡可收」本来就是对的。
+ */
+function cancelForwardedCards(ctx, entry) {
+  if (!entry.requestRef) return;
+  cancelForwardedRequests(ctx, entry.requestRef, new Error('手机已经回答了这条提问'));
+}
+
 function onQuestionRequest(request, next) {
   const sessionId = sessionIdOfRequest(request);
   if (!sessionId) return next();
@@ -301,6 +320,7 @@ async function handleQuestionRespond(ctx, req, res) {
       return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: 'answer.answers 必须每题恰好一条、含合法 selected' } });
     }
     settle(entry, answers);
+    cancelForwardedCards(ctx, entry);
     return sendJson(res, 200, { ok: true, accepted: true });
   }
   const receipt = await respondViaLegacyProxy(ctx, {

package/lib/mobile/session-presets.js

@@ -9,6 +9,7 @@
  */
 
 const { sendJson } = require('../shared/http-util');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 const { unwrap } = require('./envelope.js');
 const { callAgentPresets } = require('./rpc.js');
 
@@ -39,14 +40,17 @@ async function handleAgentPresets(ctx, req, res) {
       ...(item.broken === true ? { broken: true } : {}),
     });
   }
-  sendJson(res, 200, {
+  const body = {
     ok: true,
     presets,
     // 与条目内的 isDefault / broken 同口径：宿主只该给布尔，非布尔一律当 false，
     // 不让 'yes' / 1 这种值被 App 当成「可以自己写预设」。
     authorable: value != null && value.authorable === true,
     hasDocument: value != null && value.hasDocument === true,
-  });
+  };
+  // 指纹只看内容：`authorable` / `hasDocument` 变了也算变，它们是同一页上的两格状态。
+  const withRevision = { ...body, revision: stableRevision(body) };
+  sendJson(res, 200, unchangedListBody(withRevision, revisionOf(req)) || withRevision);
 }
 
 module.exports = { handleAgentPresets };

package/lib/mobile/session-send.js

@@ -28,6 +28,7 @@ const { withIdempotency, requestIdOf } = require('./idempotency.js');
 const { invoke, UNAVAILABLE: GATEWAY_UNAVAILABLE } = require('./host-bridge/transport.js');
 const { recordSessionRead } = require('./session-last-turn.js');
 const { imageSizeOf } = require('./local-images.js');
+const attachmentStore = require('./attachment-store.js');
 
 /**
  * `/send` 的请求体上限（**明文**字节，图片 base64）。
@@ -281,6 +282,10 @@ async function handleSessionAttachment(ctx, req, res) {
     || typeof body.attachmentId !== 'string' || !body.attachmentId) {
     return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, attachmentId }' } });
   }
+  // 直读宿主附件库（2026-10-31）：登记过的 id 直接从本地盘流给手机，省掉「等宿主把整张
+  // 读成 base64 再返回」那一段（宿主主线程忙时手机会一个字节都收不到）。前提与回退见
+  // `attachment-store.js` 的 `streamIfRemembered`：不满足就往下走原来的宿主接口。
+  if (body.raw === true && await attachmentStore.streamIfRemembered(req, res, body.sessionId, body.attachmentId)) return;
   const { value, error } = unwrap(await callSessions(ctx, 'attachment', { sessionId: body.sessionId, attachmentId: body.attachmentId }));
   if (error) return sendJson(res, 400, { ok: false, error });
   const data = value && typeof value.data === 'string' ? value.data : '';

package/lib/mobile/stream.js

@@ -29,6 +29,7 @@ const {
   waitForDrain,
   ssePadding,
   shedWithoutSeq,
+  flushFrameBatch,
 } = require('../shared/sse-write.js');
 const { resolveEventAttachments } = require('./sessions.js');
 const { createTextImageBudget } = require('./local-images.js');
@@ -197,6 +198,7 @@ function writeSse(res, payload, frame, options = {}) {
     // 协议 v2：每帧一条独立密文（§8.3(5)）。封装器由开流那一处给 —— 它才知道这条流的
     // 请求 ts / nonce 与帧序号（AAD 要绑这三样）。
     sealFrame: typeof options.sealFrame === 'function' ? options.sealFrame : null,
+    batch: res.__dshFrameBatch === true,
   });
 }
 
@@ -392,6 +394,9 @@ async function handleStream(ctx, req, res) {
   if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
   // 子会话地址：App 打开子会话的流时带上父会话与模式（见 app/src/sse.ts 的
   // openSessionStream 传参）。缺这两个字段就是普通会话，与历史那条同一套判定。
+  // 合帧：只有 App 在流地址上带 `frameBatch=1` 才启用（老 App 不带，行为一字不变）。
+  // 合帧把一串 `assistant/chunk` 并成一帧，省掉逐帧的加密、写套接字与客户端逐帧解析。
+  const frameBatch = url.searchParams.get('frameBatch') === '1';
   const parentSessionId = url.searchParams.get('parentSessionId');
   const mode = url.searchParams.get('mode');
   const streamAddress = typeof parentSessionId === 'string' && parentSessionId
@@ -401,6 +406,8 @@ async function handleStream(ctx, req, res) {
   // **要在 writeHead 之前算**：`X-Dsh-Proto: 2` 只能在头发出去之前声明，写过头再
   // `setHeader` 是无效的（Node 会静默忽略），客户端就永远不知道帧是信封。
   const sealFrame = createFrameSealer(req);
+  // 这条连接要不要合帧：`writeSse` 是文件级函数，挂在响应对象上比穿一串参数稳。
+  if (frameBatch) res.__dshFrameBatch = true;
   const head = {
     'content-type': 'text/event-stream; charset=utf-8',
     'cache-control': 'no-cache',
@@ -628,6 +635,9 @@ async function handleStream(ctx, req, res) {
       // 明确告诉客户端「流到此为止，请带 lastSeq 重连」：它会走已验证可用的 replay
       // 路径补上缺口，而不是把静默断流当成正常状态。
       if (!ac.signal.aborted && !clientGone) {
+        // 收尾帧之前先把攒着的增量放出去：resync-required 自己会触发 flush，这一行是为了
+        // 客户端已经走了那条分支不至于把最后几帧留在缓冲里。
+        flushFrameBatch(res);
         writeSse(res, { type: 'session/resync-required', sessionId, oldestSeq: lastDeliveredSeq + 1, final: true }, null, { sealFrame });
       }
       res.end();

package/lib/shared/list-revision.js

@@ -58,4 +58,22 @@ function unchangedListBody(body, rev) {
   return { ok: true, unchanged: true, revision: body.revision, generatedAt: body.generatedAt };
 }
 
-module.exports = { stableRevision, listRevision, unchangedListBody };
+/**
+ * 请求串里的 `?rev=`（条件刷新的客户端指纹）；没有、为空或解析不出来都返回空串。
+ *
+ * 空串在 `unchangedListBody` 那里是「照常回整份」，所以老 App 不带这个参数时行为不变。
+ * 路径匹配发生在宿主那一侧、早就忽略了查询串，这里只负责取值。
+ *
+ * @param {{ url?: string }} req
+ */
+function revisionOf(req) {
+  const raw = req && typeof req.url === 'string' ? req.url : '';
+  if (!raw) return '';
+  try {
+    return (new URL(raw, 'http://x').searchParams.get('rev') || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+module.exports = { stableRevision, listRevision, unchangedListBody, revisionOf };

package/lib/shared/sse-write.js

@@ -136,6 +136,53 @@ function takePadding(res, written, padBytes, padEveryMs) {
   return padding;
 }
 
+/**
+ * 合帧：把短时间内到达的多条草稿增量并成一帧发。
+ *
+ * 为什么要它：流式回复一秒几十条 `assistant/chunk`，一帧一条就是几十次「加密 + 写套接字 +
+ * 客户端逐帧解密与解析」。并成一帧之后这几步按批走，客户端那边只需要认出 `type:'batch'`。
+ *
+ * 只有客户端在流地址上带 `frameBatch=1` 时才启用（老 App 行为一个字不变）。只并
+ * `assistant/chunk` —— 心跳、审批、排队/任务、`resync-required` 这些帧没有「晚 40ms 无所谓」
+ * 的余地，它们必须立刻发，且发之前先把已攒的增量按原顺序放出去。
+ */
+const BATCH_WINDOW_MS = 40;
+const BATCH_MAX_EVENTS = 8;
+const BATCHABLE_TYPES = new Set(['assistant/chunk']);
+/** 一条连接一份攒批状态；连接收掉后随 res 一起被回收。 */
+const BATCH_STATES = new WeakMap();
+
+/** 这一帧能不能进合帧（看内层事件类型；回放路径可能带一层 `session/event` 外壳）。 */
+function isBatchablePayload(payload) {
+  if (!payload || typeof payload !== 'object') return false;
+  const inner = payload.type === 'session/event' && payload.event ? payload.event : payload;
+  return BATCHABLE_TYPES.has(inner.type);
+}
+
+function batchStateOf(res) {
+  let state = BATCH_STATES.get(res);
+  if (!state) {
+    state = { items: [], timer: null, options: null };
+    BATCH_STATES.set(res, state);
+  }
+  return state;
+}
+
+/** 把攒下的增量立刻发成一条 `batch` 帧（幂等：没东西就直接成功）。 */
+function flushFrameBatch(res) {
+  const state = BATCH_STATES.get(res);
+  if (!state) return { ok: true };
+  if (state.timer) {
+    clearTimeout(state.timer);
+    state.timer = null;
+  }
+  if (state.items.length === 0) return { ok: true };
+  const events = state.items.splice(0);
+  const options = state.options || {};
+  // 合帧只做一次：`{batch:false}` 保证不会再被攒回去。
+  return writeSse(res, { type: 'batch', events }, { ...options, batch: false });
+}
+
 /**
  * 写一条 SSE 记录。
  *
@@ -170,7 +217,29 @@ function writeSse(res, payload, options = {}) {
      * 字段，客户端要靠 `id:` 回填 `Last-Event-ID`，而 `id:` 里的 sessionId 本来就在 URL 上。
      */
     sealFrame = null,
+    /**
+     * 这条连接要不要合帧（客户端在流地址上带 `frameBatch=1` 才给真）。
+     * 见 `flushFrameBatch` / `BATCHABLE_TYPES`。
+     */
+    batch = false,
   } = options;
+  if (batch) {
+    const state = batchStateOf(res);
+    state.options = options;
+    if (!isBatchablePayload(payload)) {
+      // 控制帧 / 心跳 / 收尾：先把攒着的增量按原顺序发完，自己再立刻发。
+      const flushed = flushFrameBatch(res);
+      if (!flushed.ok) return flushed;
+    } else {
+      state.items.push(payload);
+      if (state.items.length >= BATCH_MAX_EVENTS) return flushFrameBatch(res);
+      if (!state.timer) {
+        state.timer = setTimeout(() => { state.timer = null; flushFrameBatch(res); }, BATCH_WINDOW_MS);
+        if (typeof state.timer.unref === 'function') state.timer.unref();
+      }
+      return { ok: true, deferred: true };
+    }
+  }
   const buffered = bufferedBytesOf(res);
   if (buffered > SSE_CLOSE_BUFFERED_BYTES) return { ok: false };
   if (buffered > SSE_SHED_BUFFERED_BYTES && shedWhenBuffered(payload)) return { ok: true, shed: true };  const id = stableEventId(payload, frame, namespace);
@@ -229,6 +298,10 @@ module.exports = {
   bufferedBytesOf,
   stableEventId,
   writeSse,
+  flushFrameBatch,
+  isBatchablePayload,
+  BATCH_WINDOW_MS,
+  BATCH_MAX_EVENTS,
   waitForDrain,
   shedWithoutSeq,
 };

package/lib/update-install.cjs

@@ -8,10 +8,17 @@
  *
  * 不自己实现包管理，只驱动它：profile 的 pnpm-workspace.yaml 已经写好 node-linker、peer 等
  * 关键设置，这里只「cd 到 profile 跑一句 pnpm add <包名>@<版本>」，不传布局类开关。必要的
- * 开关有两层：auto-install-peers=false（peer 是运行时注入的，npm 上没有）、minimum-release-age=0
+ * 开关有三层：auto-install-peers=false（peer 是运行时注入的，npm 上没有）、minimum-release-age=0
  * （一检测到新版就立刻装，不等「新发布先晾一会儿」；那道策略查的是整份
- * lockfile，别的插件刚发也会连累我们），再加上 CI=1（无终端）。命令行带一份、环境变量再带一份：
- * pnpm 12 的原生 CLI 会静默忽略这两个 --config 参数，环境变量那一份还认。
+ * lockfile，别的插件刚发也会连累我们）、ignore-workspace-root-check=true（profile 自己带
+ * `pnpm-workspace.yaml`，在 pnpm 眼里就是 workspace 根；pnpm 10.4 及以前会拿
+ * `ERR_PNPM_ADDING_TO_ROOT` 把这一句 add 直接拒掉，机械地退回 PATH 上那个老 pnpm 的机器全中），
+ * 再加上 CI=1（无终端）。命令行带一份、环境变量再带一份：
+ * pnpm 12 的原生 CLI 会静默忽略这几个 --config 参数，环境变量那一份还认。
+ *
+ * 失败要**说出原因**：`failure.message` 是手机、面板与日志唯一显示的那句话，曾经只写「跑过的
+ * 命令 + 退出码」—— 排错的人拿着一张只有命令的截图，包管理器自己的报错（ERR_PNPM_* 那一行）
+ * 被丢在了 `output` 里没人看。现在报错正文跟着附上。
  *
  * 装完要**登记**：这个版本是被我们绕过晾置期装进去的，不写进 profile 的 minimumReleaseAgeExclude，
  * 它就会留在 lockfile 里，之后 pnpm 校验整份 lockfile 时把这台机器上所有安装都拒掉
@@ -102,7 +109,7 @@ function spawnEnv(dirs, env = process.env) {
 }
 
 /**
- * 每次调 pnpm 都带上的那两格策略开关，**环境变量这一份不是备份，是另一半**。
+ * 每次调 pnpm 都带上的那几格开关，**环境变量这一份不是备份，是另一半**。
  *
  * pnpm 11 两种写法都认；pnpm 12 的原生 CLI 会静默忽略部分 `--config.*`（市场在 #600 上实测
  * 过，一次装失败一次白等），但同一个键走 `PNPM_CONFIG_*` 它照读。命令行与环境变量各带一份，
@@ -111,6 +118,7 @@ function spawnEnv(dirs, env = process.env) {
 const POLICY_ENV = {
   PNPM_CONFIG_AUTO_INSTALL_PEERS: 'false',
   PNPM_CONFIG_MINIMUM_RELEASE_AGE: '0',
+  PNPM_CONFIG_IGNORE_WORKSPACE_ROOT_CHECK: 'true',
 };
 
 /** 「配置里这个包用的是哪个注册表」缓存多久：查更新两分钟一轮，源不常换。 */
@@ -428,6 +436,26 @@ function runningAgentIds(agents) {
   return ids;
 }
 
+/**
+ * 给一句失败结论附上包管理器自己说的原因。
+ *
+ * `failure.message` 是手机、面板与日志**唯一**会显示的那句话，所以它必须自带原因：只写
+ * 「跑过的命令 + 退出码」时，排错的人拿着一张只有命令的截图，一点办法都没有。pnpm 的诊断
+ * 都在 `ERR_PNPM_*` / `ERROR` 那几行里，优先挑它；一行都没有（被 kill、旧版 pnpm 换了措辞）
+ * 就退回最后一行有内容的输出 —— 进度条那种噪声先滤掉。挑不满就不硬凑，也别把整份输出塞进
+ * 一句话里：完整的那份一直留在 `output` 里。
+ */
+function withReason(message, output) {
+  const lines = String(output || '')
+    .split('\n')
+    .map(line => line.trimEnd())
+    .filter(line => line.trim() !== '' && !/^Progress:/.test(line.trim()));
+  if (lines.length === 0) return message;
+  const marked = lines.filter(line => /ERR_PNPM|ERROR/.test(line));
+  const reason = (marked.length > 0 ? marked : lines.slice(-1)).slice(0, 3).join('\n').slice(0, 600);
+  return reason === '' ? message : `${message}\n${reason}`;
+}
+
 /** 跑一条命令，收 stdout+stderr 的尾巴。超时或非零退出码都如实带出来。 */
 function run(command, args, { cwd, env, timeoutMs, spawnImpl = spawn }) {
   return new Promise(resolve => {
@@ -558,7 +586,7 @@ async function installLatest({
   const spec = `${name}@${version}`;
   // 一律带上：自动更新是「一检测到就装」，手动点的那一下同样是「现在就要」，没理由先让这道
   // 策略挡一次、再靠失败重试绕过来。命令行与环境变量各带一份，pnpm 12 只认后者（见 POLICY_ENV）。
-  const policyArgs = ['--config.auto-install-peers=false', '--config.minimum-release-age=0'];
+  const policyArgs = ['--config.auto-install-peers=false', '--config.minimum-release-age=0', '--config.ignore-workspace-root-check=true'];
   const args = picked.manager === 'pnpm'
     ? ['add', spec, ...policyArgs]
     : ['install', spec, '--no-audit', '--no-fund'];
@@ -622,7 +650,10 @@ async function installLatest({
       // 超时与「真的失败了」分开说：前者可以再试，后者多半要看输出。
       failure: {
         code: result.code === null ? 'INSTALL_ABORTED' : 'INSTALL_FAILED',
-        message: `${command} ${result.code === null ? '没能跑完' : `退出码 ${result.code}`}${result.error ? `：${result.error}` : ''}`,
+        message: withReason(
+          `${command} ${result.code === null ? '没能跑完' : `退出码 ${result.code}`}${result.error ? `：${result.error}` : ''}`,
+          output,
+        ),
       },
     };
   }
@@ -643,7 +674,10 @@ async function installLatest({
     output,
     failure: changed
       ? null
-      : { code: 'VERSION_UNCHANGED', message: `${command} 跑完了，但盘上还是 ${after ?? '读不到版本'}，这一次不算数` },
+      : {
+        code: 'VERSION_UNCHANGED',
+        message: withReason(`${command} 跑完了，但盘上还是 ${after ?? '读不到版本'}，这一次不算数`, output),
+      },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (dsh 0.2.x, peers resolved by the host)",
   "license": "MIT",
   "icon": "./icon.png",