dsh-mobile-plugin 0.5.6 → 0.5.9

package/lib/http/routing.js

@@ -58,7 +58,21 @@ const remoteRelayRequest = (req) => Boolean(
 // Rejecting cross-site fetches and pinning each route to one method closes
 // that: a control-plane call now has to be a same-origin top-level/`same-origin`
 // request, and it has to use the documented verb.
-const crossSiteRequest = (req) => {
+//
+// 只读页面（面板页）是唯一的例外，而且只放开「人点开的一页」这一种形态：社区桌面壳
+// 会把自己接住的链接原地打开，从自定义协议页跳到 `http://127.0.0.1:<端口>/api/relay/panel`
+// 时 Chromium 一定给 `sec-fetch-site: cross-site`（自定义协议与 http 不同源），
+// 按攻击挡掉，用户看到的就是整屏一句 403 JSON。判据换成 Fetch 元数据里的
+// `mode: navigate` + `dest: document`：别的网页最多能把用户带到这一页（只读 HTML），
+// 页面里偷偷发的 fetch/XHR 仍然 403。
+const documentNavigation = (req) => {
+  const headers = req?.headers && typeof req.headers === 'object' ? req.headers : {}
+  return String(headers['sec-fetch-mode'] || '').toLowerCase() === 'navigate'
+    && String(headers['sec-fetch-dest'] || '').toLowerCase() === 'document'
+}
+
+const crossSiteRequest = (req, allowDocumentNavigation = false) => {
+  if (allowDocumentNavigation === true && documentNavigation(req)) return false
   if (String(req.headers['sec-fetch-site'] || '').toLowerCase() === 'cross-site') return true
   const origin = req.headers.origin
   if (typeof origin !== 'string' || !origin) return false
@@ -103,9 +117,12 @@ const trustedLocalUi = (req) => {
 
 // `method` 可以是单个方法名，也可以是方法名数组（同一个路径上挂 GET+POST，
 // 例如 /api/relay/desktop-view 既读快照又收回传）。单方法时的 405 文案保持不变。
-const localOnly = (method, handler) => async (req, res) => {
+//
+// `options.allowDocumentNavigation` 只给那几条「本来就是给人点开看」的只读页面用，
+// 其余路由不传，跨站照旧一律拒。
+const localOnly = (method, handler, options = {}) => async (req, res) => {
   if (remoteRelayRequest(req)) return sendJson(res, 403, { ok: false, error: { code: 'local_only', message: '控制面仅允许本机访问' } })
-  if (crossSiteRequest(req)) return sendJson(res, 403, { ok: false, error: { code: 'cross_site', message: '控制面拒绝跨站请求' } })
+  if (crossSiteRequest(req, options.allowDocumentNavigation === true)) return sendJson(res, 403, { ok: false, error: { code: 'cross_site', message: '控制面拒绝跨站请求' } })
   const allowed = Array.isArray(method) ? method : [method]
   const actual = String(req.method || 'GET').toUpperCase()
   if (!allowed.includes(actual)) {

package/lib/mobile/channels.js

@@ -311,11 +311,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 +355,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 +376,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 +403,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/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-file.js

@@ -21,6 +21,7 @@ const path = require('node:path');
 const { pipeline } = require('node:stream/promises');
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { signedPath } = require('../shared/e2ee-request');
+const { FILE_CHUNK_BYTES, writeChunk } = require('../shared/e2ee-chunks.js');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const { cwdOf } = require('./session-cwd.js');
@@ -244,13 +245,13 @@ async function writeEncryptedFile(req, res, target, opened) {
         const block = pending.subarray(0, FILE_CHUNK_BYTES);
         pending = pending.subarray(FILE_CHUNK_BYTES);
         seq += 1;
-        writeBlock(res, e2ee, opened.keys.down, block, e2ee.fileAad(path0, requestNonce, seq));
+        writeChunk(res, opened.keys.down, block, e2ee.fileAad(path0, requestNonce, seq));
       }
     }
     // 尾块（可能不足一块）；空文件也给一块，否则 App 拿不到「这是个空文件」的确认。
     if (!closed) {
       seq += 1;
-      writeBlock(res, e2ee, opened.keys.down, pending, e2ee.fileAad(path0, requestNonce, seq));
+      writeChunk(res, opened.keys.down, pending, e2ee.fileAad(path0, requestNonce, seq));
     }
     if (!closed) res.end();
   } catch {
@@ -258,29 +259,15 @@ async function writeEncryptedFile(req, res, target, opened) {
   }
 }
 
-/** 写一块：`[4 字节长度][nonce][密文+tag]`，长度写的是后两段之外的密文长度。 */
-function writeBlock(res, e2ee, key, block, aad) {
-  const sealed = e2ee.seal(key, block, aad);
-  const buf = Buffer.from(sealed);
-  const cipherLen = buf.length - e2ee.NONCE_BYTES;
-  const head = Buffer.alloc(4);
-  head.writeUInt32BE(cipherLen, 0);
-  res.write(Buffer.concat([head, buf]));
-}
-
-/** 交付文件的分块大小。64KB：一块一次 AEAD，太小会让每块的 16+12 字节固定开销占比变高。 */
-const FILE_CHUNK_BYTES = 64 * 1024;
-
 /** 一块除明文字节之外还带多少：`[4 字节长度][12 字节 nonce][16 字节 tag]`。 */
 const FILE_BLOCK_OVERHEAD = 4 + 12 + 16;
 
 /**
  * 一份文件按块加密之后在网上会有多少字节。
  *
- * 块数 = `floor(size / FILE_CHUNK_BYTES)` 个满块 + **永远存在的那一块尾块**（空文件也要一块）。
- * 这个数在写之前就得用（响应头的 `content-length`），所以它必须与 `writeEncryptedFile` 的
- * 写法逐字对得上 —— 后果不对称：算少了对端读不满、算多了对端一直等，两种都是「文件打不开」。
- * 守卫拿几个跨块边界的长度钉住它。
+ * 块数 = `floor(size / FILE_CHUNK_BYTES)` 个满块 + **永远存在的那一块尾块**（空文件也要一块）：
+ * 这个数在写之前就得用（响应头的 `content-length`），所以它必须与写块那份逐字对得上 —— 后果
+ * 不对称：算少了对端读不满、算多了对端一直等，两种都是「文件打不开」。
  */
 function encryptedLengthOf(size) {
   const plain = Math.max(0, Number(size) || 0);

package/lib/mobile/session-log.js

@@ -14,11 +14,21 @@
  *
  * 与桌面客户端保持同一口径：`includeDescendants` 缺省即 true —— 导出的是「当前会话
  * + 子会话 + 附件」的整棵会话树，而不是单个会话。
+ *
+ * **封过包的请求回分块信封，明文请求照旧回 zip**（2026-10-30）。判据是 `req.__dshE2ee`：
+ * 它由移动端守卫在解封请求时挂上，只有带 `X-Dsh-Proto: 2` 的请求才有 —— 也就是说这一档
+ * 只对新 App 生效，老 App 一个字都不用改。为什么要加这一档：守卫对「v2 凭据 + 明文请求」
+ * 一律回 `e2ee-required`，而这条导出一直是绕开传输内核直发的明文请求，于是它在按 v2 配对的
+ * 手机上从来就没走到下载这一步。封了包之后，**响应也得跟着封** —— 会话树里是整段对话与附件，
+ * 明文 zip 等于把这条链路唯一的加密出口又打开一次。分块格式与 `session-file.js` 共用一套
+ * （`[4 字节长度][nonce][密文+tag]`，AAD 绑路径 / 请求 nonce / 块序号），App 那边用同一个
+ * 原生解密口读，两处口径因此只有一份。
  */
 
 const { Readable } = require('node:stream');
 const { pipeline } = require('node:stream/promises');
 const { sendJson } = require('../shared/http-util.js');
+const { chunksHeaders, pipeEncrypted } = require('../shared/e2ee-chunks.js');
 
 /**
  * 与桌面 sessionLogZipFilename 同口径的下载文件名。
@@ -82,8 +92,19 @@ async function handleSessionLog(ctx, req, res) {
   };
   const length = upstream.headers.get('content-length');
   if (length) headers['content-length'] = length;
-  res.writeHead(200, headers);
 
+  const opened = req && req.__dshE2ee;
+  if (opened && opened.keys && opened.req && upstream.body) {
+    // 真类型单独给一条头：解密之后按它认「这是一份 zip」。
+    res.writeHead(200, chunksHeaders({
+      'content-disposition': headers['content-disposition'],
+      'x-dsh-content-type': headers['content-type'],
+    }));
+    await pipeEncrypted(req, res, Readable.fromWeb(upstream.body));
+    return;
+  }
+
+  res.writeHead(200, headers);
   if (!upstream.body) return res.end();
   try {
     // 边收边写，不在插件进程里整包缓冲：会话树的附件可能很大，缓冲等于把宿主的

package/lib/mobile/session-send.js

@@ -13,7 +13,9 @@
  * 未知命令或网关未组合时回退普通消息，与桌面 miss 落入默认 sink 的行为一致。
  */
 
+const { Readable } = require('node:stream');
 const { sendJson, readJsonBody } = require('../shared/http-util');
+const { chunksHeaders, pipeEncrypted } = require('../shared/e2ee-chunks.js');
 const { inlineUploadedImageBlocks } = require('./uploads.js');
 const { unwrap } = require('./envelope.js');
 const { callSessions, mobilePromptRpcId } = require('./rpc.js');
@@ -290,6 +292,19 @@ async function handleSessionAttachment(ctx, req, res) {
   // `dims: true` = 只要原始宽高，不要字节。老会话里宿主没存附件的宽高，正文下发时就带不上，
   // 手机侧只能按 240 方盒先占位、等字节到了再变高（那一行一变高，屏幕上就是「跳」）。这一档
   // 让手机在挂载那一帧就能按真比例占好：回给它的只有两格数字，整张图的 base64 不出这台电脑。
+  // `raw: true` = 要原始字节，不要 base64（2026-10-30）。宿主给的仍是 base64，这里解成
+  // Buffer 后按分块信封流出去：手机那边落盘的是密文，靠原生解盘口边解边写，整张图的
+  // base64 不进 JS 堆 —— 一张两兆的截图在手机上原本要摊着两兆七的字符串加一份解析副本。
+  // **不封包不许走这一档**：那就成了明文传输，正好把这条路本来的意义抹掉，如实回 400。
+  if (body.raw === true) {
+    const opened = req && req.__dshE2ee;
+    if (!opened || !opened.keys || !opened.req) {
+      return sendJson(res, 400, { ok: false, error: { code: 'e2ee-required', message: '这条会话是加密的，请用信封重发' } });
+    }
+    res.writeHead(200, chunksHeaders({ 'x-dsh-content-type': mediaType }));
+    await pipeEncrypted(req, res, Readable.from([Buffer.from(data, 'base64')]));
+    return;
+  }
   if (body.dims === true) {
     const size = imageSizeOf(Buffer.from(data, 'base64'));
     if (!size || !(size.width > 0) || !(size.height > 0)) {

package/lib/relay/lan-network.cjs

@@ -352,15 +352,21 @@ function manualCandidate(value) {
 }
 
 /**
- * 候选 = 用户填的那条（有的话）在前 + 其余照旧。按 url 去重，**不删**任何一条 NIC 候选：
- * 穿透域名不通时手机还得能顺着网卡地址摸回这台机器。值不合法时原样返回 NIC 候选，
- * 不让一条坏配置把整份候选清空（那正是彻底失联的形状）。
+ * 候选 = 网卡那几条照旧 + 用户填的那条**排在最后**当兜底。按 url 去重，**不删**任何一条
+ * NIC 候选：穿透域名不通时手机还得能顺着网卡地址摸回这台机器。值不合法时原样返回 NIC
+ * 候选，不让一条坏配置把整份候选清空（那正是彻底失联的形状）。
+ *
+ * **为什么排在最后而不是最前**（2026-10-30 改）：这两类地址的快慢本来不可比 —— 同一个
+ * WiFi 里内网是几毫秒，穿透要绕公网，起步就是几十到几百毫秒。排在最前等于让手机按「先
+ * 回话的赢」这条规矩永远选中穿透域名，家里明明有内网地址却一次都不去试；现场表现就是
+ * 「以前在局域网下直连地址会自动变成内网 IP，现在不会了」。顺序是这条上唯一的表达方式，
+ * 所以内网那条必须排前面，穿透域名只当离开这个网络之后的兜底。
  */
 function withManualCandidate(list, value) {
   const manual = manualCandidate(value)
   const rest = Array.isArray(list) ? list : []
   if (!manual) return rest
-  return [manual, ...rest.filter(item => item && item.url !== manual.url)]
+  return [...rest.filter(item => item && item.url !== manual.url), manual]
 }
 
 /**
@@ -393,8 +399,8 @@ function orderCandidates(list, preferred) {
 /**
  * 报给手机的直连候选 —— 二维码、配对响应与 `/connection-info` 三处**只许走这一份**。
  *
- * 两步顺序不能反：先让「手机优先用这条」调网卡候选的顺序，再把用户手填的地址盖到最前
- * （那条是用户在手机上手打的，`preferredLanAddress` 只是面板上对网卡地址的选择，压不过它）。
+ * 两步顺序不能反：先让「手机优先用这条」调网卡候选的顺序，再把用户手填的地址**缀到末尾**
+ * 当兜底（`preferredLanAddress` 调的是同一批网卡地址之间的次序，手填的那条不属于这一批）。
  * 三处各写一遍的结果就是「画面上说这条、手机去试另一条」。
  */
 function phoneCandidates(list, options = {}) {

package/lib/routes/control-plane.js

@@ -87,7 +87,7 @@ function createWebAccessWindow({ now = Date.now, monotonicNow = () => performanc
 }
 
 function createWebAccessLocalOnly({ localOnly, trustedLocalUi, webAccessWindow, sendJson }) {
-  return (method, handler) => localOnly(method, async (req, res) => {
+  return (method, handler, options) => localOnly(method, async (req, res) => {
     const route = String(req?.url || '').split('?', 1)[0];
     if (WEB_ACCESS_ROUTES.has(route) && !trustedLocalUi(req) && !webAccessWindow.isOpen()) {
       return sendJson(res, 423, {
@@ -96,7 +96,7 @@ function createWebAccessLocalOnly({ localOnly, trustedLocalUi, webAccessWindow,
       });
     }
     return handler(req, res);
-  });
+  }, options);
 }
 
 /**
@@ -445,9 +445,12 @@ function registerControlPlaneRoutes(deps) {
     process.stderr.write(`[dsh-mobile-plugin] panel unavailable (${diagnosis.reason}) ${PANEL_FILE}: ${diagnosis.message}\n`);
     return sendJson(res, 500, { ok: false, error: { code: 'panel_missing', reason: diagnosis.reason, message: diagnosis.message, path: PANEL_FILE } });
   };
-  registerRoute({ kind: 'exact', path: '/api/relay/panel', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
-  registerRoute({ kind: 'exact', path: '/api/relay/panel/setup', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
-  registerRoute({ kind: 'exact', path: '/api/relay/panel/settings', handler: localOnly('GET', async (_req, res) => servePanel(res)) })
+  // 三条面板页是「人点开的一页」：社区桌面壳会把自己接住的链接原地打开，从自定义协议
+  // 页跳过来必带 `sec-fetch-site: cross-site`，不放开这一种形态，用户看到的就是整屏
+  // 一句 403 JSON（见 `lib/http/routing.js` 的 `documentNavigation`）。
+  registerRoute({ kind: 'exact', path: '/api/relay/panel', handler: localOnly('GET', async (_req, res) => servePanel(res), { allowDocumentNavigation: true }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/panel/setup', handler: localOnly('GET', async (_req, res) => servePanel(res), { allowDocumentNavigation: true }) })
+  registerRoute({ kind: 'exact', path: '/api/relay/panel/settings', handler: localOnly('GET', async (_req, res) => servePanel(res), { allowDocumentNavigation: true }) })
   // 桌面端工作区视图（侧栏展开态）的回传/读取。桌面端只把展开态记在浏览器
   // localStorage 里，宿主进程读不到，只能由页面内的客户端半边（lib/client.js）
   // 每 2s 变了就 POST 到这里；App 再经 /api/mobile/v1/desktop-view 取走。

package/lib/routes/mobile-api.js

@@ -189,8 +189,8 @@ function registerMobileRoutes(deps) {
     const port = typeof lanPortInUse === 'function' ? lanPortInUse() : state.lanPort
     // 用户在面板上选过的「手机优先用这条」（设置项 `preferredLanAddress`）在这里同样兑现：
     // 手机是按顺序挨个试的，所以只挪顺序、不删候选。选的那条不在了就退回宿主排序。
-    // 手填的直连地址再盖到最前面：那是用户明确指定的那条，`preferredLanAddress` 只调网卡候选
-    // 的顺序，不该把它压到后面。
+    // 手填的直连地址（穿透域名）缀在**最后**当兜底：它绕公网、比内网慢一个数量级，排在前面
+    // 就等于让手机永远选中它、家里那条内网地址一次都不试（见 `withManualCandidate` 的注释）。
     const candidates = state.lanEnabled
       ? withManualCandidate(orderCandidates(safeLanCandidates(port), state.preferredLanAddress), state.manualLanUrl)
       : []

package/lib/shared/e2ee-chunks.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * 分块信封的写出口（协议 v2，§8.3(6)）—— 会话文件、会话日志 ZIP、会话图片附件共用这一份。
+ *
+ * 块形状：`[4 字节大端长度][12 字节 nonce][密文 + 16 字节 tag]`，长度字段写的是「密文 + tag」
+ * 这一段（不含 nonce 与长度字段本身）。AAD 绑这条请求的路径、请求 nonce 与块序号 —— 块序号
+ * 让中转既不能把别的文件的字节搬进来，也不能重排或截断而不被察觉。
+ *
+ * 为什么要一个共用模块：这是跨端**逐字对齐**的那一层，手机那边是同一个原生解盘口在读
+ * （`DSHCipher.openFile`）。三条下载各写一遍，等于给自己留三个漂移点，而漂了不会有报错，
+ * 只会换来「文件打不开」。
+ */
+
+const e2ee = require('./e2ee');
+const { signedPath } = require('./e2ee-request');
+
+/** 一块的明文字节数。与 App 侧 `FILE_CHUNK_BYTES` 同值。 */
+const FILE_CHUNK_BYTES = 64 * 1024;
+
+/** 分块信封的 content-type：App 靠它判「这份字节要解，别当普通文件存」。 */
+const E2EE_CHUNKS_TYPE = 'application/x-dsh-e2ee-chunks';
+
+/**
+ * 分块信封的响应头。
+ *
+ * **不给 content-length**：这一份是边收边加密的流，总长要等上游收完才知道；而 App 那条原生
+ * 下载器只认 EOF、不靠长度判完成（要看长度的是 blob-util 那条老路，已经不用了）。
+ */
+function chunksHeaders(extra = {}) {
+  return {
+    'content-type': E2EE_CHUNKS_TYPE,
+    'cache-control': 'no-store',
+    'x-dsh-proto': '2',
+    ...extra,
+  };
+}
+
+/** 写一块：`[4 字节长度][nonce][密文+tag]`。 */
+function writeChunk(res, key, block, aad) {
+  const sealed = Buffer.from(e2ee.seal(key, block, aad));
+  const head = Buffer.alloc(4);
+  head.writeUInt32BE(sealed.length - e2ee.NONCE_BYTES, 0);
+  res.write(Buffer.concat([head, sealed]));
+}
+
+/**
+ * 把一个可读流按块加密写进 `res`（调用方已经把状态码与头写完了）。
+ *
+ * 块边界要自己攒（`pending` 不到一块就等下一段）。**空内容也要写一块**，否则 App 分不清
+ * 「这份是空的」与「一个字节都没收到」。出错时只能断开连接 —— 头已经发出去了，改不了状态码。
+ */
+async function pipeEncrypted(req, res, source) {
+  const opened = req && req.__dshE2ee;
+  if (!opened || !opened.keys || !opened.req) throw new Error('这条请求没有信封');
+  const path = signedPath(req);
+  const requestNonce = opened.req.nonce;
+  let seq = 0;
+  let pending = Buffer.alloc(0);
+  let closed = false;
+  res.on('close', () => { closed = true; });
+  try {
+    for await (const chunk of source) {
+      if (closed) break;
+      pending = pending.length ? Buffer.concat([pending, chunk]) : Buffer.from(chunk);
+      while (pending.length >= FILE_CHUNK_BYTES) {
+        const block = pending.subarray(0, FILE_CHUNK_BYTES);
+        pending = pending.subarray(FILE_CHUNK_BYTES);
+        seq += 1;
+        writeChunk(res, opened.keys.down, block, e2ee.fileAad(path, requestNonce, seq));
+      }
+    }
+    if (!closed) {
+      seq += 1;
+      writeChunk(res, opened.keys.down, pending, e2ee.fileAad(path, requestNonce, seq));
+      res.end();
+    }
+  } catch {
+    try { res.destroy(); } catch { /* 连接已关闭 */ }
+  }
+}
+
+module.exports = { FILE_CHUNK_BYTES, E2EE_CHUNKS_TYPE, chunksHeaders, writeChunk, pipeEncrypted };

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.6",
+  "version": "0.5.9",
   "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",