dsh-mobile-plugin 0.1.92 → 0.1.93

package/README.md

@@ -7,6 +7,7 @@ AI-HUB 手机端插件，为 DSH 提供移动 API、远程连接和局域网代
 ## 下载 AI-HUB 手机 App
 
 - [Android APK](https://app.wnluo.com/public/apps/14)
+- [Android APK（GitHub 渠道）](https://github.com/WNLUO/dsh-mobile-plugin/releases/latest/download/ai-hub-android.apk)；[历史版本](https://github.com/WNLUO/dsh-mobile-plugin/releases)
 - [App Store](https://apps.apple.com/us/app/ai-hub/id6821681438)（若暂时无法打开，可能是 App 仍在等待苹果审核通过。）
 - [TestFlight 测试版](https://testflight.apple.com/join/4fn5PCMD)
 
@@ -104,6 +105,7 @@ npm test
 - npm 包的 `repository` 字段用于关联插件列表条目；修改后需再次发布，注册表信息才会更新。
 - 插件列表收录通过向 awesome-dsh-plugin 提交 `data/plugins/<owner>__<repo>.yml` 完成。描述中的数字和 API 名称应能由代码核实；列表要求 `description.en`、`category: remote`，包需声明 `dsh.bundle`，仓库需有 `dsh-plugin` topic。
 - 仓库创建满一天的检查会自动重跑；截图可通过 `screenshots.json` 提供，也可由市场从 README 查找。
+- GitHub 的 release 页放手机 App 的 APK（下载入口见开头那一节）：资产名固定用 `ai-hub-android.apk`，并且发成正式版 —— 草稿与预发布都不会成为「最新」，README 里那条直连会随之断掉。插件自身走 npm 发布，不在本仓库发 release。
 - 隐私政策：[PRIVACY.md](PRIVACY.md)。技术支持与常见问题：[SUPPORT.md](SUPPORT.md)。
 
 ### 发布新版本

package/config/agent-presets/standard/agent.cordis.yml

@@ -162,9 +162,12 @@
       searchTimeoutMs: 60000
   # Without this row the mobile host's tool catalog has no `ask_user_question`,
   # so the App's question dock could never appear: the model simply reports that
-  # the tool is unavailable. `@deepseek-ai/dsh-host-apiproxy` already registers
-  # the `ctx.userQuestions` provider that bridges `ask()` to the mux
-  # `question/requested` frame, and the plugin's `lib/mobile/questions.js`
-  # answers it — only the tool row was missing.
+  # the tool is unavailable. The plugin's `lib/mobile/questions.js` listens on
+  # the `user-questions/request` hook (0.2.x shape) and answers it — only the
+  # tool row was missing.
+  #
+  # The package must be pinned to the runtime's own generation (0.2.0-rc.2):
+  # its peerDependencies track the runtime release exactly, and the loader
+  # disables the whole row — rather than degrade — when one does not match.
   - id: tool-ask-user
     name: '@deepseek-ai/dsh-tool-ask-user'

package/lib/impl.js

@@ -24,7 +24,7 @@ const { authorized } = require('./mobile/auth.js')
 const { createSidecarLifecycle } = require('./sidecar-lifecycle.cjs')
 const { createMirrorPusher } = require('./mirror/pusher.cjs')
 const { randomBytes } = require('node:crypto')
-const { lanUrls, advertisedCandidates, orderCandidates } = require('./relay/lan-network.cjs')
+const { lanUrls, advertisedCandidates, orderCandidates, ipv6Candidates } = require('./relay/lan-network.cjs')
 const { resolvePort } = require('./relay/port-allocator.cjs')
 const { createPreviewService } = require('./relay/preview.js')
 // 本机设备凭据库：/api/relay/revoke-all 必须同时吊销局域网直连的 dshc_ 凭据，
@@ -177,6 +177,9 @@ function pairingPayload(state, lanPort) {
     // 候选列表随二维码一起带走：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,
@@ -413,6 +416,8 @@ function apply(ctx) {
     getSidecarSnapshot: sidecarLifecycle.getSnapshot,
     // 移动端路由表那边叫它「局域网候选」，取的是同一份私网优先的清单。
     safeLanCandidates: advertisedCandidates,
+    // IPv6 直连候选单独一份：App 拿它单开一条通道、和公网中转比速度，不掺进上面那份的排序。
+    safeIpv6Candidates: ipv6Candidates,
     lanPortInUse: advertisedLanPort, // LAN 候选用实绑端口
     // 配对那条路由自己要签凭据：core 是签 token 的实现，pairingApproval 决定这台机器
     // 收不收新设备（'deny' 时一律拒）。两者本文件都已有，透传给移动端路由。

package/lib/mobile/attachments.js

@@ -1,16 +1,24 @@
 'use strict';
 
 /**
- * 图片归一：会话历史存的是 `{type:'image', attachment}` 而不是内联字节，
- * 手机端拿到后要经 session attachment RPC 把图片取回来。
+ * 图片归一：会话历史存的是 `{type:'image', attachment}` 而不是内联字节。
  *
  * 宿主事件里图片可能出现在四处：message/content、inserted 上下文项、
  * assistant chunk 的 block，以及更深的嵌套 content。全部在这里归一，
- * 这样历史与 SSE 暴露给手机端的内联图片形状是同一个。
+ * 这样历史与 SSE 暴露给手机端的图片形状是同一个。
+ *
+ * **默认（引用模式 `opts.referencesOnly`）不取字节**：图片块原样留着 `attachment`
+ * 引用，由 history-derive 投影成 `{mediaType, name?, attachmentId}`，手机端要画的时候
+ * 按 attachmentId 单张去取（`/session/attachment`）。此前这里把每张图都换成内联 base64，
+ * 一页 200 条带十几张截图的响应接近 10MB，每次进会话都要重传一遍。
+ *
+ * 只有显式传 `referencesOnly: false` 时才回到「经 session attachment RPC 取回字节」的
+ * 老行为；取不回字节的块打 `dataUnavailable` 标（语义不变，见 dataUnavailableBlock）。
  *
  * 另外一类图片在正文里：`![](/abs/path.png)` 这种指向**宿主本机文件**的写法
  * （本机绝对路径、file://、~）在手机上取不到字节，也会被 App 当成非 http 图片降级成字面
  * markdown。这里顺手按同一形状内联成 data URI（实现与预算见 local-images.js）。
+ * 这条与附件引用是两件事：它走的是正文里的路径、没有 attachmentId，预算与行为保持原样。
  */
 
 const { unwrap } = require('./envelope.js');
@@ -19,12 +27,16 @@ const { inlineTextImages, createTextImageBudget } = require('./local-images.js')
 
 /**
  * Resolve durable image references before exposing messages to mobile clients.
- * Session history stores `{type:'image', attachment}` rather than inline bytes;
- * the mobile client resolves these through the session attachment RPC.
+ *
+ * Session history stores `{type:'image', attachment}` rather than inline bytes.
+ * By default (`referencesOnly`) the block is left as a reference and the mobile
+ * client fetches the bytes per attachment (`/session/attachment`); no host RPC
+ * happens on this path at all. Pass `referencesOnly: false` for the legacy
+ * inline-bytes shape.
  *
  * Host events can carry content in several places: message/content, inserted
  * context items, or an assistant/chunk block. Keep this normalization here so
- * history and SSE expose the same inline-image shape to mobile clients.
+ * history and SSE expose the same image shape to mobile clients.
  *
  * Text blocks additionally get local-file image syntax inlined as data URIs
  * (see local-images.js); `opts.budget` is a shared per-response budget so one
@@ -47,6 +59,9 @@ async function resolveEventAttachments(ctx, sessionId, event, opts = {}) {
   if (!event || !event.data || typeof event.data !== 'object') return event;
   const data = event.data;
   const budget = opts.budget || createTextImageBudget();
+  // 引用模式（默认）：图片块只留 attachment 引用，**一次宿主 RPC 都不发**。
+  // 只有显式 referencesOnly:false 才走下面那条把字节取回来的老路。
+  const referencesOnly = opts.referencesOnly !== false;
   let nextData = data;
   let eventChanged = false;
 
@@ -59,6 +74,8 @@ async function resolveEventAttachments(ctx, sessionId, event, opts = {}) {
     if (block.type === 'image' && !block.data && block.attachment) {
       const attachmentId = block.attachment.attachmentId;
       if (typeof attachmentId !== 'string' || !attachmentId) return block;
+      // 引用模式到此为止：块原样返回，字节由手机端按 attachmentId 单张去取。
+      if (referencesOnly) return block;
       let result;
       try {
         result = unwrap(await callSessions(ctx, 'attachment', { sessionId, attachmentId }));

package/lib/mobile/history-derive.js

@@ -99,6 +99,46 @@ function toolResultParts(msg) {
   };
 }
 
+/**
+ * 图片块 → 移动端图片条目（`ChatMessage.images[]` / 工具块的 `images[]` 同一个形状）。
+ *
+ * 两条互斥的出口：
+ *  - 块上有 `attachmentId`：下发**引用** `{ mediaType, name?, attachmentId }`，**不带 data**。
+ *    字节由手机端要画的时候按 attachmentId 单张去取（`/session/attachment`），
+ *    历史响应因此不再背着几十张截图的 base64。
+ *  - 块里本来就只有内联 `data`、没有 attachmentId：照旧下发 `{ mediaType, data, name? }`。
+ *    这条兜底不能删——老日志、工具结果里存在这种直接带字节的图片块。
+ *
+ * 两条都要求 mediaType 可读（块上没有就退到 attachment 上的），否则 App 认不出来、
+ * 也没有可显示的动作，返回 null 让调用方丢掉它。
+ */
+function imageEntryOf(block) {
+  if (!block || typeof block !== 'object') return null;
+  const attachment = block.attachment && typeof block.attachment === 'object' ? block.attachment : {};
+  const attachmentId = typeof attachment.attachmentId === 'string' ? attachment.attachmentId : '';
+  const mediaType = typeof block.mediaType === 'string' && block.mediaType
+    ? block.mediaType
+    : (typeof attachment.mediaType === 'string' ? attachment.mediaType : '');
+  if (!mediaType) return null;
+  const name = typeof block.name === 'string'
+    ? block.name
+    : (typeof attachment.name === 'string' ? attachment.name : undefined);
+  if (attachmentId) return { mediaType, ...(name !== undefined ? { name } : {}), attachmentId };
+  if (typeof block.data === 'string' && block.data) return { mediaType, data: block.data, ...(name !== undefined ? { name } : {}) };
+  return null;
+}
+
+/** 把 tool/result 的图片块收成移动端图片条目（两种出口见 imageEntryOf）。 */
+function toolResultImages(parts) {
+  const out = [];
+  for (const part of parts) {
+    if (!part || typeof part !== 'object' || part.type !== 'image') continue;
+    const entry = imageEntryOf(part);
+    if (entry) out.push(entry);
+  }
+  return out;
+}
+
 /** 预扫描 tool/result 事件，构建 callId → {isError, code} 映射（对接桌面 toolRowModel 状态派生）。 */
 function buildToolResultMap(events) {
   const map = new Map();
@@ -115,10 +155,7 @@ function buildToolResultMap(events) {
        if (part && typeof part === 'object' && part.type === 'image') return '';
         try { return JSON.stringify(part); } catch { return ''; }
      }).filter(Boolean).join('');
-     const images = parts
-        .filter((part) => part && typeof part === 'object' && part.type === 'image'
-          && typeof part.data === 'string' && typeof part.mediaType === 'string')
-        .map((part) => ({ mediaType: part.mediaType, data: part.data, ...(typeof part.name === 'string' ? { name: part.name } : {}) }));
+     const images = toolResultImages(parts);
       const diffs = normalizeResultDiffs(e.data.meta);
       map.set(src.callId, { isError, code, ...(output ? { output } : {}), ...(images.length ? { images } : {}), ...(diffs ? { diffs } : {}) });
   }
@@ -142,8 +179,11 @@ function parseBlocks(blocks, toolResults) {
       // The image attachment resolver marked this block as unavailable. Keep it out of
       // visible text; pushMessage projects its retry metadata onto unavailableImages.
       continue;
-    } else if (b.type === 'image' && typeof b.data === 'string' && typeof b.mediaType === 'string') {
-      out.push({ type: 'image', mediaType: b.mediaType, data: b.data, name: typeof b.name === 'string' ? b.name : undefined });
+    } else if (b.type === 'image') {
+      // 有 attachmentId 走引用、只有内联 data 的走兜底（见 imageEntryOf）。两者都认不出
+      // 就整块丢掉——与旧行为一致，绝不能把它兜底成一段 JSON 文本。
+      const entry = imageEntryOf(b);
+      if (entry) out.push({ type: 'image', ...entry });
     } else if (b.type === 'tool-call') {
       // tool-call 块字段为 id/name/arguments（与 harness toAssistantBlock 同口径）。
       const callId = b.id != null ? String(b.id) : undefined;
@@ -336,10 +376,16 @@ function deriveMessages(events) {
       return rest;
     });
     const text = blocksToText(blocks);
+    // 图片条目统一投影：引用模式带 attachmentId 不带 data，内联兜底带 data 不带 attachmentId。
     const images = [
       ...blocks.filter((b) => b.type === 'image'),
       ...toolImages,
-    ].map(({ mediaType, data, name }) => ({ mediaType, data, name }));
+    ].map(({ mediaType, data, name, attachmentId }) => ({
+      mediaType,
+      ...(typeof name === 'string' ? { name } : {}),
+      ...(typeof attachmentId === 'string' && attachmentId ? { attachmentId } : {}),
+      ...(typeof attachmentId === 'string' && attachmentId ? {} : { data }),
+    }));
     const unavailableImages = (Array.isArray(msg.content) ? msg.content : [])
       .filter((block) => block && block.type === 'image' && block.dataUnavailable === true)
       .map((block) => {

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

@@ -86,10 +86,11 @@ async function modelCatalog(ctx, payload, signal) {
         : null)
     : null;
   const effective = sessionSelection && sessionSelection.provider && sessionSelection.model ? sessionSelection : current;
-  const routable = Array.isArray(catalog.routableProviders) ? catalog.routableProviders : [];
+  const routableProviders = Array.isArray(catalog.routableProviders) ? catalog.routableProviders : [];
   return ok({
     ...(effective ? { current: effective } : {}),
-    routable: Boolean(effective && routable.includes(effective.provider)),
+    routable: Boolean(effective && routableProviders.includes(effective.provider)),
+    routableProviders,
     groups: Array.isArray(catalog.groups) ? catalog.groups : [],
   });
 }

package/lib/mobile/session-models.js

@@ -33,6 +33,12 @@ function safeModelsValue(value) {
     }
   }
   if (typeof value.routable === 'boolean') result.routable = value.routable;
+  if (Array.isArray(value.routableProviders)) {
+    result.routableProviders = [...new Set(value.routableProviders
+      .filter((provider) => typeof provider === 'string' && provider.length > 0)
+      .slice(0, 128)
+      .map((provider) => provider.slice(0, 256)))];
+  }
   if (Array.isArray(value.groups)) {
     result.groups = value.groups
       .filter((group) => group && typeof group.id === 'string' && typeof group.name === 'string' && Array.isArray(group.models))

package/lib/mobile/session-preview.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * 会话列表的「最后一条消息」预览：为最近 / 运行中的会话补一次 history 折叠。
+ *
+ * 会话列表的标题与行数据都来自宿主 `sessions.list` 摘要，只有 `lastMessage` 要读日志，
+ * 属于重活，所以只对预览子集做（见 sessions.js 的 SESSIONS_PREVIEW_LIMIT）。
+ *
+ * 同一份预览按会话指纹复用：运行中的会话 `updatedAt` 几乎每轮都在变，指纹于是每轮都变，
+ * 10 秒的列表缓存一到期就要为每个运行中会话重读一次 history；一轮生成里手机侧 15s
+ * 轮询会反复撞上「指纹变了但预览内容其实没变」的中间态，所以另加一个更短的窗口。
+ * 非运行中的会话仍走指纹判定（它们的 updatedAt 不变，指纹不变，本来就不会重读）。
+ */
+
+const { callSessions } = require('./rpc.js');
+const { unwrap } = require('./envelope.js');
+const { deriveMessages, lastMessageOf } = require('./history-derive.js');
+const {
+  sessionPreviewStateOf, sessionPreviewInFlightStateOf, sessionPreviewClockOf,
+} = require('./session-cache.js');
+
+/** 补预览时拉取的消息条数（低到足够取最后一条预览，避免每次重活）。 */
+const HISTORY_FOR_ENRICH = 10;
+/** 运行中会话的预览重读下限。 */
+const RUNNING_PREVIEW_MIN_INTERVAL_MS = 3000;
+
+function sessionPreviewFingerprint(summary) {
+  return `${summary.updatedAt || 0}:${summary.running ? 'running' : 'idle'}:${summary.blank ? 'blank' : 'content'}`;
+}
+
+/** Read one preview at most once per unchanged session revision. */
+async function sessionPreviewFor(ctx, summary) {
+  const sessionId = summary.sessionId;
+  const fingerprint = sessionPreviewFingerprint(summary);
+  const cached = sessionPreviewStateOf(ctx).get(sessionId);
+  if (cached?.fingerprint === fingerprint) return { events: [], lastMessage: cached.lastMessage };
+
+  const inFlight = sessionPreviewInFlightStateOf(ctx);
+  const existing = inFlight.get(sessionId);
+  if (existing?.fingerprint === fingerprint) return existing.promise;
+
+  // 运行中会话的节流（见 RUNNING_PREVIEW_MIN_INTERVAL_MS）：窗口内复用上一次预览，
+  // 不为「updatedAt 又动了一下」再读一遍日志。返回空 events 与 cache-hit 分支一致
+  // ——完成态确认只在真正读回历史时进行，本轮不复用它的边沿判定。
+  const clock = sessionPreviewClockOf(ctx);
+  if (cached && summary.running && Date.now() - (clock.get(sessionId) || 0) < RUNNING_PREVIEW_MIN_INTERVAL_MS) {
+    return { events: [], lastMessage: cached.lastMessage };
+  }
+  clock.set(sessionId, Date.now());
+
+  const promise = Promise.resolve(callSessions(ctx, 'history', {
+    sessionId,
+    maxMessages: HISTORY_FOR_ENRICH,
+  })).then((response) => {
+    const h = unwrap(response);
+    if (h.error) return { events: [], lastMessage: null };
+    const events = (h.value && h.value.events) || [];
+    const messages = deriveMessages(events);
+    const last = lastMessageOf(messages);
+    const lastMessage = last ? { role: last.role, text: last.text.slice(0, 200), at: last.time } : null;
+    sessionPreviewStateOf(ctx).set(sessionId, { fingerprint, lastMessage });
+    return { events, lastMessage };
+  }).finally(() => {
+    if (inFlight.get(sessionId)?.promise === promise) inFlight.delete(sessionId);
+  });
+  inFlight.set(sessionId, { fingerprint, promise });
+  return promise;
+}
+
+module.exports = { HISTORY_FOR_ENRICH, RUNNING_PREVIEW_MIN_INTERVAL_MS, sessionPreviewFingerprint, sessionPreviewFor };

package/lib/mobile/session-send.js

@@ -71,7 +71,13 @@ async function executeCommand(ctx, sessionId, line) {
  */
 function promptOnce(ctx, clientMessageId, payload) {
   const rpcId = mobilePromptRpcId(clientMessageId);
-  if (!clientMessageId) return callSessions(ctx, 'prompt', payload, rpcId);
+  // 把这一发认回去的身份一起送进宿主的 prompt 请求（`request.requestId`，见
+  // host-bridge/endpoints.js）。宿主要是不认识它，user 消息的 `source.rpcId` 就是那个
+  // 端点自己生成的 `mobile-prompt-<uuid>` —— App 那边 `clientMessageId` 永远对不上，
+  // 只能靠「同文本 + 同图数」猜着认领乐观行（2026-10-20 真机：自己发的图一直「发送中」，
+  // 因为实时帧里的图还被漏读，张数一对不上就彻底认领不了）。
+  const request = clientMessageId ? { ...payload, requestId: rpcId } : payload;
+  if (!clientMessageId) return callSessions(ctx, 'prompt', request, rpcId);
   const state = sendIdempotencyStateOf(ctx);
   const key = `${payload.sessionId}:${clientMessageId}`;
   const now = Date.now();
@@ -79,7 +85,7 @@ function promptOnce(ctx, clientMessageId, payload) {
   if (existing && now - existing.createdAt < 60_000) return existing.promise;
   if (existing) state.delete(key);
 
-  const promise = Promise.resolve(callSessions(ctx, 'prompt', payload, rpcId));
+  const promise = Promise.resolve(callSessions(ctx, 'prompt', request, rpcId));
   // Keep the short-lived record so an in-flight/concurrent send with the same
   // clientMessageId shares one prompt. Only cache a SUCCESS: a rejection must
   // not poison later retries (a transient error should be retryable), so the

package/lib/mobile/session-snapshot.js

@@ -55,8 +55,10 @@ async function buildMessagesSnapshot(ctx, sessionId, limit = MESSAGES_DEFAULT_LI
   const { value, error } = unwrap(await callSessions(ctx, 'history', { sessionId, maxMessages: limit }));
   if (error) return { ok: false, error };
   const events = (value && value.events) || [];
+  // 引用模式：图片只下发 attachmentId，不取字节（见 attachments.js）。正文里本机图片的
+  // 内联仍走 budget，与之前一致。
   const budget = createTextImageBudget();
-  const resolvedEvents = await Promise.all(events.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget }).then((event) => entry.event ? { ...entry, event } : event)));
+  const resolvedEvents = await Promise.all(events.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget, referencesOnly: true }).then((event) => entry.event ? { ...entry, event } : event)));
   const messages = deriveMessages(resolvedEvents);
   const lastSeq = events.length ? (eventSeqOf(events[events.length - 1]) ?? 0) : 0;
   const hasMore = !!(value && value.hasMore);
@@ -169,7 +171,7 @@ async function handleMessages(ctx, req, res) {
   // 一页历史共用一个内联图片预算：正文里的本机图片越多，越靠后的那些保持字面 markdown，
   // 而不是让单次响应无限膨胀（见 local-images.js 的三级预算）。
   const budget = createTextImageBudget();
-  const resolvedEvents = await Promise.all(filtered.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget }).then((event) => entry.event ? { ...entry, event } : event)));
+  const resolvedEvents = await Promise.all(filtered.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget, referencesOnly: true }).then((event) => entry.event ? { ...entry, event } : event)));
   const messages = deriveMessages(resolvedEvents);
   const hasMore = !!(value && value.hasMore);
   const seqs = events.map(eventSeqOf).filter((seq) => Number.isSafeInteger(seq) && seq >= 0);

package/lib/mobile/sessions.js

@@ -20,22 +20,25 @@
  *   session-mirror.js  镜像整帧构建
  *   session-goal.js    目标条动作
  *   session-presets.js Agent 预设目录
+ *   session-preview.js 列表行的 lastMessage 预览（按会话指纹复用 + 运行中会话的节流）
  *
- * 剩下的就是列表：GET /sessions（10 秒缓存 + fresh 绕过 + 完成态确认）、GET /session、
- * GET /session/stats、新建会话、排队消息动作。**本文件继续从各子模块转出导出**，
+ * 剩下的就是列表：GET /sessions（10 秒缓存 + fresh 绕过 + 完成态确认 + `?rev=` 条件刷新）、
+ * GET /session（单会话摘要）、GET /session/head（正文水位探针）、GET /session/stats、
+ * 新建会话、排队消息动作。**本文件继续从各子模块转出导出**，
  * 所以 lib/mobile 下所有 import 路径一行都不用改。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { isFreshRequest } = require('../shared/fresh-request');
-const { listRevision } = require('../shared/list-revision.js');
+const { listRevision, unchangedListBody } = require('../shared/list-revision.js');
+// 正文水位信号：session/head 探针直接读它的快照，**不**为了「看起来有值」去现读历史。
+const { sessionSignal } = require('../shared/session-signal.js');
 const { withIdempotency, requestIdOf } = require('./idempotency.js');
 const { listTitle, deriveMessages, lastMessageOf, promptErrorObject, MODEL_UNAVAILABLE_ERROR } = require('./history-derive.js');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const {
   canonicalDeviceKey, sessionListResponseState, invalidateSessionList, deletedSessionIdsOf,
-  sessionPreviewStateOf, sessionPreviewInFlightStateOf, sessionPreviewClockOf,
   completionGenerationOf, bumpCompletionGeneration,
   completionStateOf, sessionModelsStateOf, invalidateSessionModels, sendIdempotencyStateOf,
 } = require('./session-cache.js');
@@ -49,22 +52,13 @@ const { promptOnce, handleSend, handleCommands, handleSessionRead, handleSession
 const { handleSessionSearch } = require('./session-search.js');
 const { handleAgentPresets } = require('./session-presets.js');
 const { handleGoalAction } = require('./session-goal.js');
+// 预览（lastMessage 补全）与它自己的重读节流：只读日志、不发写，单列一个子模块。
+const { HISTORY_FOR_ENRICH, sessionPreviewFor } = require('./session-preview.js');
 const approvals = require('./approvals.js');
 const questions = require('./questions.js');
 
-const HISTORY_FOR_ENRICH = 10;      // 补标题/预览时拉取的消息条数（低到足够取最后一条预览，避免每次重活）
 const SESSIONS_PREVIEW_LIMIT = 20;  // 仅为最近/运行中的会话补最后消息预览
 const SESSION_LIST_CACHE_MS = 10000;  // 会话列表增料缓存（降低手机轮询对桌面的冲击）
-/**
- * 运行中会话的预览重读下限。
- *
- * 运行中的会话 updatedAt 几乎每轮都在变，`sessionPreviewFingerprint` 于是每轮都变，
- * 10 秒的列表缓存一到期就要为每个运行中会话重读一次 history（HISTORY_FOR_ENRICH 条）。
- * 一轮生成里手机侧 15s 轮询会反复撞上「指纹变了但预览内容其实没变」的中间态。
- * 这里给运行中会话单独加一个更短的窗口：窗口内复用上一次预览，不重读日志。
- * 非运行中的会话仍走指纹判定（它们的 updatedAt 不变，指纹不变，本来就不会重读）。
- */
-const RUNNING_PREVIEW_MIN_INTERVAL_MS = 3000;
 
 /**
  * 宿主的两个**会话集合**（同一次 `workspace.list` 快照里拿到）：
@@ -96,47 +90,32 @@ async function workspaceSessionFlags(ctx) {
   }
 }
 
-function sessionPreviewFingerprint(summary) {
-  return `${summary.updatedAt || 0}:${summary.running ? 'running' : 'idle'}:${summary.blank ? 'blank' : 'content'}`;
-}
-
-/** Read one preview at most once per unchanged session revision. */
-async function sessionPreviewFor(ctx, summary) {
-  const sessionId = summary.sessionId;
-  const fingerprint = sessionPreviewFingerprint(summary);
-  const cached = sessionPreviewStateOf(ctx).get(sessionId);
-  if (cached?.fingerprint === fingerprint) return { events: [], lastMessage: cached.lastMessage };
-
-  const inFlight = sessionPreviewInFlightStateOf(ctx);
-  const existing = inFlight.get(sessionId);
-  if (existing?.fingerprint === fingerprint) return existing.promise;
-
-  // 运行中会话的节流（见 RUNNING_PREVIEW_MIN_INTERVAL_MS）：窗口内复用上一次预览，
-  // 不为「updatedAt 又动了一下」再读一遍日志。返回空 events 与 cache-hit 分支一致
-  // ——完成态确认只在真正读回历史时进行，本轮不复用它的边沿判定。
-  const clock = sessionPreviewClockOf(ctx);
-  if (cached && summary.running && Date.now() - (clock.get(sessionId) || 0) < RUNNING_PREVIEW_MIN_INTERVAL_MS) {
-    return { events: [], lastMessage: cached.lastMessage };
+/**
+ * GET /api/mobile/v1/session/head?sessionId=…&parentSessionId=…&mode=…（token）
+ *
+ * 「这条会话的正文到哪个水位了」——App 进对话前先问一句，跟本地缓存水位一比就知道要不要
+ * 重新拉全量历史。几十字节换几兆。
+ *
+ * `seq` 取 `sessionSignal.peek(sessionId)`：镜像推送每轮都会 bump，语义正是「快照里真正
+ * 装上的消息的最大 seq」，与 App 的缓存水位同一个 seq 空间。
+ *
+ * `known` = `seq > 0`。**信号里没有时如实回 `known:false`**（插件刚重启、还没轮到推这个
+ * 会话），让 App 退回全量拉取；绝不为了「看起来有值」现读一次历史——那样这个探针本身
+ * 就变成了它要省掉的那次请求。
+ *
+ * 子代理（带 parentSessionId）直接回 `{seq:0, known:false}`：镜像里刻意不存子会话正文
+ * （见 dev-map A3-14 的「子会话的正文刻意不进镜像」），没有水位可言。
+ */
+async function handleSessionHead(_ctx, req, res) {
+  const url = new URL(req.url, 'http://x');
+  const sessionId = url.searchParams.get('sessionId');
+  if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
+  const parentSessionId = url.searchParams.get('parentSessionId');
+  if (parentSessionId !== null && parentSessionId !== '') {
+    return sendJson(res, 200, { ok: true, seq: 0, known: false });
   }
-  clock.set(sessionId, Date.now());
-
-  const promise = Promise.resolve(callSessions(ctx, 'history', {
-    sessionId,
-    maxMessages: HISTORY_FOR_ENRICH,
-  })).then((response) => {
-    const h = unwrap(response);
-    if (h.error) return { events: [], lastMessage: null };
-    const events = (h.value && h.value.events) || [];
-    const messages = deriveMessages(events);
-    const last = lastMessageOf(messages);
-    const lastMessage = last ? { role: last.role, text: last.text.slice(0, 200), at: last.time } : null;
-    sessionPreviewStateOf(ctx).set(sessionId, { fingerprint, lastMessage });
-    return { events, lastMessage };
-  }).finally(() => {
-    if (inFlight.get(sessionId)?.promise === promise) inFlight.delete(sessionId);
-  });
-  inFlight.set(sessionId, { fingerprint, promise });
-  return promise;
+  const seq = sessionSignal.peek(sessionId);
+  sendJson(res, 200, { ok: true, seq, known: seq > 0 });
 }
 
 /** GET /api/mobile/v1/sessions（token） */
@@ -153,6 +132,10 @@ async function handleSessions(ctx, req, res) {
   // 与 fresh 的区别：它只绕开这层缓存，不需要作废在途构建，也不 bump 朝代号（没有写入）。
   const url = new URL(req.url, 'http://x');
   const archivedOnly = url.searchParams.get('archived') === '1';
+  // 条件刷新（?rev=<上次的 revision>）：内容没变就只回一句 unchanged，不带 items。
+  // fresh=1（写后刷新必须拿到真数据）与 archived=1（归档子集不是同一份内容）一律不走。
+  const rev = (url.searchParams.get('rev') || '').trim();
+  const revEligible = !wantFresh && !archivedOnly;
   // 只有新客户端显式带分页参数时才切片；旧客户端不带参数仍拿到完整归档列表。
   const hasPaging = archivedOnly && (url.searchParams.has('offset') || url.searchParams.has('limit'));
   const parsedOffset = Number(url.searchParams.get('offset') ?? 0);
@@ -168,13 +151,21 @@ async function handleSessions(ctx, req, res) {
     cache.updatedAt = 0;
     generation = bumpCompletionGeneration(ctx, deviceKey);
   }
+  // 条件刷新的转换点：拿到**最终要回的 body**之后才判，且只在上面那两条短路条件
+  // （rev 缺失/为空、fresh=1、archived=1）都不成立时才认。unchanged 响应本身不写缓存、
+  // 也不进在途构建的合流判定——它只是同一份内容的一句话说清。
+  const respond = (status, body) => {
+    const unchanged = status === 200 && revEligible ? unchangedListBody(body, rev) : null;
+    return sendJson(res, status, unchanged || body);
+  };
+
   if (!bypassCache && cache.value && now - cache.updatedAt < SESSION_LIST_CACHE_MS) {
-    return sendJson(res, 200, cache.value);
+    return respond(200, cache.value);
   }
 
   if (!bypassCache && cache.promise) {
     const response = await cache.promise;
-    return sendJson(res, response.status, response.body);
+    return respond(response.status, response.body);
   }
 
   // 变更信号（镜像推送调度器先看见清单变了）会调 dropSessionListCache 丢掉这层缓存，
@@ -197,7 +188,7 @@ async function handleSessions(ctx, req, res) {
         cache.updatedAt = Date.now();
       }
     }
-    return sendJson(res, response.status, response.body);
+    return respond(response.status, response.body);
   } finally {
     if (cache.promise === promise) cache.promise = null;
   }
@@ -455,6 +446,7 @@ module.exports = {
   SESSIONS_PREVIEW_LIMIT,
   handleSessions,
   handleSession,
+  handleSessionHead,
   handleStats,
   handleNew,
   handleQueueUpdate,