dsh-mobile-plugin 0.5.9 → 0.5.11

package/lib/cli/pair.cjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * 在终端里把配对二维码打出来（`dsh-mobile-plugin-pair`）。
+ *
+ * 为什么需要它：二维码那条路由只在本机屏幕或者两小时窗口里给码，而**服务器部署**上
+ * 「本机屏幕」这个概念是空的 —— 那台机器的设置页往往开不了，人也够不到它的回环地址。
+ * 能在服务器终端里敲命令的人本来就有这台机器的权限，把码打给他，信任量级与「在本机屏幕
+ * 上看码」相同，也不新增任何对外的口子。
+ *
+ * 载荷与面板同一份（`../relay/pairing-payload.cjs`），所以打出来的码一定和面板里那张能
+ * 配上同一台机器；这里只负责画图与说人话，不碰配对流程。
+ *
+ * 用法：
+ *   dsh-mobile-plugin-pair              在终端里打出二维码
+ *   dsh-mobile-plugin-pair --svg qr.svg 另外存一份 SVG（终端太窄、想发给别人时用）
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const QRCode = require('qrcode');
+const core = require('../relay/core.js');
+const { pairingPayload } = require('../relay/pairing-payload.cjs');
+
+const USAGE = `用法：
+  dsh-mobile-plugin-pair               在终端里打印配对二维码
+  dsh-mobile-plugin-pair --svg <路径>  同时把二维码存成 SVG 图片`;
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+function parseArgs(argv) {
+  const out = { svg: '' };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--svg') {
+      const next = argv[index + 1];
+      if (!next || next.startsWith('-')) return { error: '--svg 后面要跟一个文件路径' };
+      out.svg = next;
+      index += 1;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') return { help: true };
+    return { error: `不认识的参数：${arg}` };
+  }
+  return out;
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+  if (args.error) {
+    fail(`${args.error}\n\n${USAGE}`);
+    return;
+  }
+
+  // 状态文件是宿主与这里唯一的交接口：宿主每次换码换票据都会落盘，所以读到的那份就是
+  // 跑着的宿主手上那份。文件不存在时**不替它建**（`loadState()` 会建），直接说清楚。
+  if (!fs.existsSync(core.STATE_FILE)) {
+    fail(`这台机器上还没跑过这个插件（找不到 ${core.STATE_FILE}）。先启动 DSH，并在移动端插件里启用远程控制。`);
+    return;
+  }
+  const state = core.loadState();
+  if (!state.enabled) {
+    fail('远程控制还没启用：先在 DSH 的移动端设置页（或面板）里打开远程控制并保存配置。');
+    return;
+  }
+  const { payload, text } = pairingPayload(state, state.lanPort);
+  if (!payload.relayUrl && payload.lanUrls.length === 0) {
+    fail('没有可用的中转或直连地址：先在面板上配好中转地址，或打开局域网直连，再回来打码。');
+    return;
+  }
+
+  const lines = [];
+  lines.push(`宿主：${payload.name}`);
+  lines.push(`配对码：${payload.code}`);
+  lines.push(`中转地址：${payload.relayUrl || '（没配）'}`);
+  if (payload.lanUrls.length > 0) {
+    lines.push(`直连地址：${payload.lanUrls.join('  ')}`);
+    lines.push(`局域网端口：${state.lanPort}`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n\n`);
+
+  if (args.svg) {
+    const target = path.resolve(args.svg);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, await QRCode.toString(text, { type: 'svg', errorCorrectionLevel: 'M', margin: 2, width: 480 }));
+    process.stdout.write(`二维码已存成图片：${target}\n如果终端太窄扫不动，把这个文件拿下来用看图软件打开再扫。\n\n`);
+  }
+
+  // small: true 让一个字符带两行模块，绝大多数终端一行装得下；扫不动就加 --svg。
+  process.stdout.write(`${await QRCode.toString(text, { type: 'terminal', small: true, errorCorrectionLevel: 'M' })}\n`);
+  process.stdout.write('用 DSH App 扫这张码即可配对。它等于一次配对权限，别截图发给别人；配完可以在面板上点「重新生成配对码」。\n');
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  fail(`打码失败：${error && error.message ? error.message : String(error)}`);
+});

package/lib/client.js

@@ -482,6 +482,16 @@ window.__ModuleLoader__.load({
         hostHalfRetrying: '它还在后台自己重试，过几分钟刷新这一页就能看到结果；也可以点下面的按钮立刻再试一次。',
         hostHalfReload: '重新装载',
         hostHalfReloadFailed: '重新装载没成：',
+        hostHalfUnreachable: '宿主侧的自检口也没有回应：这一版插件可能还没带它（较老的版本）——先更新插件，再完整重启一次 DSH。',
+        hostHalfNoError: '宿主侧自检没报错，控制面路由却确实不在：把 DSH 完整重启一次；还不行请把这句连同插件版本发给我们。',
+        hostHalfVersion: '自检版本：',
+        diagHostReturned: '宿主返回：',
+        diagSelfCheck: '自检：',
+        diagSelfCheckNoAnswer: '没有回应（这一版可能还没带它）',
+        diagSelfCheckNoError: '没有报错',
+        diagSelfCheckRetry: '后台重试 ',
+        diagOnDisk: '碟上版本 ',
+        diagShellRestartAtStartup: '外壳改过，要重启一次 DSH',
         webAccessOn: '公网网页管理已开放，到期时间',
         webAccessOff: '公网网页管理已关闭',
         webAccessOpen: '开放网页管理 2 小时',
@@ -504,6 +514,16 @@ window.__ModuleLoader__.load({
         hostHalfRetrying: 'It is still retrying on its own in the background — reopen this item in a few minutes, or press the button below to retry right now.',
         hostHalfReload: 'Reload now',
         hostHalfReloadFailed: 'Reload failed: ',
+        hostHalfUnreachable: 'The host-side self-check did not answer either: this version of the plugin may not ship it yet (older build) — update the plugin, then restart DSH completely.',
+        hostHalfNoError: 'The host self-check reports no error, yet the control-plane routes really are missing: restart DSH completely; if that does not help, send us this line together with the plugin version.',
+        hostHalfVersion: 'self-check version: ',
+        diagHostReturned: 'Host returned: ',
+        diagSelfCheck: 'Self-check: ',
+        diagSelfCheckNoAnswer: 'no answer (this build may not ship it)',
+        diagSelfCheckNoError: 'no error reported',
+        diagSelfCheckRetry: 'background retries: ',
+        diagOnDisk: 'on disk: ',
+        diagShellRestartAtStartup: 'shell changed — DSH needs one restart',
         webAccessOn: 'Public web management is open until',
         webAccessOff: 'Public web management is closed',
         webAccessOpen: 'Open web management for 2 hours',
@@ -573,15 +593,17 @@ window.__ModuleLoader__.load({
               refreshTimer = null;
             }
             // 404 = 实现那一半没装载。它为什么没装载，只有外壳答得出来（这两条路由挂在
-            // 外壳上，实现挂了它们还在）；老版本宿主没有这条口，问不到就当没有，别报错。
+            // 外壳上，实现挂了它们还在）；老版本宿主没有这条口，问不到也得把这个事实留住
+            // （`unavailable`）——「自检口都没有回应」和「自检说没事」是两种不同的现场，
+            // 都缩成一句「重启/重装」的话，用户只能对着空白猜（2026-11-01 现场）。
             if (problem?.status === 404) {
               try {
                 const picture = await call(HOST_HALF_ENDPOINT);
                 if (!alive) return;
-                setHalf(picture && typeof picture.half === 'object' ? picture.half : null);
+                setHalf(picture && typeof picture.half === 'object' ? picture.half : { unavailable: true });
               } catch {
                 if (!alive) return;
-                setHalf(null);
+                setHalf({ unavailable: true });
               }
             } else {
               setHalf(null);
@@ -648,16 +670,59 @@ window.__ModuleLoader__.load({
 
       const missing = errorStatus === 404;
 
+      /**
+       * 诊断读数：宿主回了什么 + 外壳那份自检说了什么。
+       *
+       * 只拼进这一屏、不落盘也不上报：它的用途是让人截图发给我们（2026-11-01 用户原话：
+       * 「以后用户发过来 我也不好去排查」）。字段名用 `version=` / `source=` 这种记号而不是
+       * 翻成中文，是因为它要能贴进日志里对得上宿主那一侧。
+       */
+      const diagLines = [];
+      if (missing) {
+        diagLines.push(`${t('diagHostReturned')}${error}`);
+        if (half && half.unavailable === true) {
+          diagLines.push(`${t('diagSelfCheck')}${t('diagSelfCheckNoAnswer')}`);
+        } else if (half) {
+          const bits = [];
+          if (half.version) bits.push(`version=${half.version}`);
+          if (half.source) bits.push(`source=${half.source}`);
+          if (half.activatedAt) bits.push(`at=${half.activatedAt}`);
+          if (half.retrying) {
+            const attempts = Number.isFinite(half.retryAttempts) ? half.retryAttempts : 0;
+            bits.push(`${t('diagSelfCheckRetry')}${attempts}${half.nextRetryAt ? `→${half.nextRetryAt}` : ''}`);
+          }
+          if (half.installedVersion && half.installedVersion !== half.version) {
+            bits.push(`${t('diagOnDisk')}${half.installedVersion}`);
+          }
+          if (half.shellChanged) bits.push(t('diagShellRestartAtStartup'));
+          diagLines.push(`${t('diagSelfCheck')}${bits.length ? bits.join(' · ') : t('diagSelfCheckNoError')}`);
+        }
+      }
+
       return h('div', { className: 'dshm_root' }, [
         h('h2', { className: 'dshm_heading' }, t('heading')),
         error
           ? h('p', { className: 'dshm_error' }, missing ? t('loadMissing') : `${t('loadFailed')}: ${error}`)
           : null,
+        // 404 那屏必须自带「能拿去排查」的读数（2026-11-01 用户要求）：只写一句「宿主侧没起来」
+        // 的话，用户截图发过来我们还是不知道坏在哪一层，只能让他一次次试。
+        // 两行足够定位：宿主到底回了什么、外壳那份自检说了什么。
+        ...diagLines.map((line) => h('p', { className: 'dshm_note', key: line.slice(0, 24) }, line)),
         // 404 时把宿主那半边自己的说法贴出来：重启 / 重装这两句提示在「装载超时」那种
         // 现场是帮倒忙的，真正该做的是等它后台补齐、或者点一下重新装载。
         missing && half && typeof half.lastError === 'string' && half.lastError
           ? h('p', { className: 'dshm_note' }, `${t('hostHalfReason')}${half.lastError}`)
           : null,
+        // 问不到自检口：说明这一版插件压根没带它（比 0.5.11 老），用户这时最该做的是更新
+        // 插件，而不是继续重启 —— 原先这一支是一片空白，只留一句「重启/重装」。
+        missing && half && half.unavailable === true
+          ? h('p', { className: 'dshm_note' }, t('hostHalfUnreachable'))
+          : null,
+        // 自检说没事、路由却不在：这是「同一份 DSH 里跑着两份插件」那种现场，报出版本
+        // 才查得下去。
+        missing && half && half.unavailable !== true && !(typeof half.lastError === 'string' && half.lastError)
+          ? h('p', { className: 'dshm_note' }, `${t('hostHalfNoError')}${typeof half.version === 'string' && half.version ? `（${t('hostHalfVersion')}${half.version}）` : ''}`)
+          : null,
         missing && half && half.retrying === true
           ? h('p', { className: 'dshm_note' }, t('hostHalfRetrying'))
           : null,

package/lib/impl.js

@@ -28,7 +28,9 @@ const { deviceMetaFromHeaders } = require('./shared/device-headers.js')
 const { createSidecarLifecycle } = require('./sidecar-lifecycle.cjs')
 const { createMirrorPusher } = require('./mirror/pusher.cjs')
 const { randomBytes } = require('node:crypto')
-const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates } = require('./relay/lan-network.cjs')
+const { lanUrls, advertisedCandidates, phoneCandidates, ipv6Candidates, withManualIpv6Candidate } = require('./relay/lan-network.cjs')
+// 配对二维码的载荷：面板与终端命令共用一份，拼装在 `./relay/pairing-payload.cjs`。
+const { pairingPayload } = require('./relay/pairing-payload.cjs')
 const { resolvePort } = require('./relay/port-allocator.cjs')
 const { createPreviewService } = require('./relay/preview.js')
 // 本机设备凭据库：/api/relay/revoke-all 必须同时吊销局域网直连的 dshc_ 凭据，
@@ -93,6 +95,9 @@ export const RemoteControlSettingsSchema = z.object({
   preferredLanAddress: z.string().max(64).default(''),
   // 用户手填的直连地址（`manualLanUrl`，内网穿透域名）也随二维码一起走，见 lan-network.cjs。
   manualLanUrl: z.string().max(200).default(''),
+  // 用户手填的 IPv6 直连地址（`manualIpv6Url`，形如 `http://[240e::1]:18787`）：与上一条并列，
+  // 只是拨的是 IPv6；网卡扫不到的那条固定地址靠它兜底，候选口径见 lan-network.cjs。
+  manualIpv6Url: z.string().max(200).default(''),
 })
 
 
@@ -111,6 +116,7 @@ function configOf(state) {
     registerSecret: typeof state.registerSecret === 'string' ? state.registerSecret : '',
     preferredLanAddress: typeof state.preferredLanAddress === 'string' ? state.preferredLanAddress : '',
     manualLanUrl: typeof state.manualLanUrl === 'string' ? state.manualLanUrl : '',
+    manualIpv6Url: typeof state.manualIpv6Url === 'string' ? state.manualIpv6Url : '',
   }
 }
 
@@ -166,44 +172,6 @@ function createConfigStore(state) {
   }
 }
 
-function pairingPayload(state, lanPort) {
-  const port = Number.isInteger(lanPort) ? lanPort : state.lanPort
-  // 面板上选过的「手机优先用这条」在这里兑现：只挪到最前，其余继续当兜底（App 按顺序挨个试）。
-  const candidates = state.lanEnabled
-    ? phoneCandidates(advertisedCandidates(port), { preferred: state.preferredLanAddress, manual: state.manualLanUrl })
-    : []
-  const urls = candidates.map(candidate => candidate.url).filter(Boolean)
-  const relayUrl = state.relayUrl || ''
-  const payload = {
-    type: 'dsh-pair',
-    version: 1,
-    name: state.name || os.hostname(),
-    instanceId: state.instanceId,
-    code: state.pairingCode,
-    // 协议版本与一次性票据（§8.3(1)）。
-    //
-    // `proto: 2` 由**宿主**写、也由宿主生成，中转没有任何机会改写它 —— 所以「新 App 被
-    // 中转骗回明文」这个问题从一开始就不存在。`ticket` 是 32 字节随机数，手机拿它派生
-    // 配对密钥；二维码是屏幕对摄像头，这条通道完全绕开中转。
-    //
-    // 老 App 只取自己认识的那几个字段，多出来的两个会被忽略 —— 一张二维码同时服务新旧两种。
-    proto: 2,
-    ticket: state.pairingTicket || '',
-    relayUrl,
-    lanUrls: urls,
-    // 候选列表随二维码一起带走：App 配对后即使换了网段，也能按这份列表
-    // 依次重试而不用先回到公网中转去问。
-    lanCandidates: candidates.map(candidate => candidate.url).filter(Boolean),
-    // IPv6 直连候选（理想情况下是手机**不在同一个 Wi-Fi 里**时唯一能拨到的地址）：不参与上面
-    // 那份的排序，顺序由 App 侧拿它和公网中转实测比出来；直连监听没开就没有这条通道。
-    ipv6Candidates: state.lanEnabled ? ipv6Candidates(port).map(candidate => candidate.url).filter(Boolean) : [],
-  }
-  return {
-    payload,
-    text: `dshpair://v1?data=${encodeURIComponent(JSON.stringify(payload))}`,
-  }
-}
-
 // 上报给 App 的候选地址（私网优先、没有私网才退公网）住在 `./relay/lan-network.cjs`
 // 的 `advertisedCandidates`：那是地址策略，不是装配。这里只把它转交给三处消费点。
 // 「手机上最近来过没有」同理，住在 `./mobile/activity.cjs`（守卫记、控制面状态读）。
@@ -490,7 +458,8 @@ function apply(ctx) {
     // 移动端那边的「局域网候选」：私网优先的清单 + 用户手填的直连地址（网卡扫不出的域名）。
     safeLanCandidates: (port) => phoneCandidates(advertisedCandidates(port), { manual: state.manualLanUrl }),
     // IPv6 直连候选单独一份：App 拿它单开一条通道、和公网中转比速度，不掺进上面那份的排序。
-    safeIpv6Candidates: ipv6Candidates,
+    // 手填的那条同样缀在最后（只追加、不删网卡候选），手机每次核对连接信息都重新拿到它。
+    safeIpv6Candidates: (port) => withManualIpv6Candidate(ipv6Candidates(port), state.manualIpv6Url),
     lanPortInUse: advertisedLanPort, // LAN 候选用实绑端口
     // 配对那条路由自己要签凭据：core 是签 token 的实现，pairingApproval 决定这台机器
     // 收不收新设备（'deny' 时一律拒）。两者本文件都已有，透传给移动端路由。

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);
 }
 
 /**