dsh-mobile-plugin 0.5.1 → 0.5.3

package/lib/mobile/local-images.js

@@ -1,25 +1,31 @@
 'use strict';
 
 /**
- * 正文图片内联：把消息文本里指向本机文件的图片语法（`![](/abs/path.png)`）换成 data URI，
- * 让手机端能直接画出来。
+ * 正文里本机图片 → 一个短编号（`![alt](dsh-local-image:<id>?w=..&h=..)`）。
  *
- * 手机拿到的只是文本，`/Users/…/a.png` 既不是手机上的文件，移动 API 也没有「按路径读文件」
- * 的能力面，原样过去只会显示成一串字面 markdown。这里把「正文里写的本机图片」拉齐到附件那种
- * 内联形状，App 不需要新增通道。
+ * 为什么不内联 base64（2026-10-29 改）：整张图的字节塞进消息正文有三个代价，全落在用户身上 ——
+ *  ① 正文里没有宽高，手机只能先按固定尺寸占位、等解码完再改；翻页时那一行高度晚到，内容被顶；
+ *  ② 体积：一张 135KB 的图进正文就是 180KB 字符，而正文整段会进本地缓存（1MiB 预算），
+ *     六七张图就把缓存吃穿 —— 于是「打开过很多次还是要重新加载」；
+ *  ③ 每次重拉历史都要重传一遍。
+ * 业界（WhatsApp / Telegram / Slack / 各家大模型客户端）都是「消息里只放引用 + 宽高」，
+ * 这里对齐同一条口径：正文只留编号，字节按编号单张取（`/session/local-image`）。
+ *
+ * 安全边界不变：**不是「按路径读文件」**。编号只由本模块在投影历史时登记，取图口只认
+ * 登记表里的编号 —— 构造一个编号读不到任何别的文件。登记表活在进程内；插件重启后老编号
+ * 取不到就如实 404，App 走「失败 + 重试」那条现成的路。
  *
  * 保守取舍——宁可保留字面 markdown，也不给半截东西：
  * - 本机路径认三种：绝对（`/x/y.png`、`file:///x/y.png`）、`~/y.png`、相对（`deliverables/a.png`，
  *   按调用方给的工作区目录解析，与桌面端同口径；没给目录就当成不是本机图）；http(s)、`data:` 不碰；
  * - 只认 png/jpg/jpeg/webp/gif，并核对魔术字节，不按扩展名撒谎；
- * - 三级体积预算（单图 / 单段 / 单次响应），超预算就保持字面；
- * - 读不到、不是普通文件、读取失败一律原样保留；
+ * - 宽高只读文件头（最多 64KB）；读不出来就不带宽高，App 那边照旧现量；
  * - 围栏代码块与行内代码里的图片语法不碰，那是写法示例。
  */
-
 const fs = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
+const crypto = require('node:crypto');
 
 /**
  * `![alt](dest)`。dest 两种写法都认：裸路径（不含空白与右括号）与 `<>` 包裹（里面可以有空格，
@@ -38,17 +44,21 @@ const MEDIA_TYPES = {
   '.gif': 'image/gif',
 };
 
-/** 单张原图上限（base64 后约 1.33 倍，见下面的字符预算）。 */
+/** 单张图上限：再大的东西不该整包回给手机（超出如实保持字面 markdown）。 */
 const MAX_IMAGE_BYTES = 2.5 * 1024 * 1024;
-/** 一段文本里内联进去的 data URI 总字符上限。 */
-const MAX_TEXT_CHARS = 3 * 1024 * 1024;
-/** 一次响应（一页历史 / 一帧 SSE / 一次镜像快照）共用的字符上限。 */
-const MAX_RESPONSE_CHARS = 5 * 1024 * 1024;
-/** data URI 复用条数：同一张图常在同一轮里出现多次（历史 + 流式 + 镜像）。 */
-const MAX_CACHE_ENTRIES = 8;
+/** 读宽高只需要文件头：JPEG 的 SOF 段可能在几百字节之后，64KB 足够覆盖绝大多实拍图。 */
+const HEAD_BYTES = 64 * 1024;
+/** 登记表上限：翻历史时同一张图反复出现也只登记一次，512 条够一两百个会话轮着用。 */
+const MAX_REGISTRY_ENTRIES = 512;
+/** 一张响应（一页历史 / 一帧 SSE / 一次镜像快照）里最多换几张：防一段文字里几十上百个图片语法。 */
+const MAX_TEXT_IMAGES = 64;
 
-/** path+mtime+size → data URI。会话里同一张图会被反复解析，但文件内容只读一次。 */
-const cache = new Map();
+/**
+ * 编号 → { filePath, mediaType, width?, height? }。
+ *
+ * 只由本模块登记，取图口只认这里面的编号 —— 这是「不扩能力面」的全部依据（见文件头）。
+ */
+const registry = new Map();
 
 function mediaTypeFor(filePath) {
   return MEDIA_TYPES[path.extname(filePath).toLowerCase()] || null;
@@ -119,40 +129,103 @@ function hasRelativeImage(text) {
  * `cwd` 由调用方按需补上（相对地址的解析基准，见 localImagePathOf）：`undefined` 表示
  * 「还没查过工作区目录」，空串表示「查过了，这条会话没有」。
  */
-function createTextImageBudget(limit = MAX_RESPONSE_CHARS) {
+function createTextImageBudget(limit = MAX_TEXT_IMAGES) {
   return { remaining: limit };
 }
 
-/** 读文件 → data URI（带缓存）；不满足条件一律 null。 */
-async function dataUriFor(filePath) {
-  let stat;
+/** 从文件头解析宽高；认不出来返回 null（不是错误：App 那边照旧现量）。 */
+function imageSizeOf(buf) {
+  if (buf.length >= 24 && buf[0] === 0x89 && buf.toString('latin1', 1, 4) === 'PNG') {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  }
+  if (buf.length >= 10 && buf.toString('latin1', 0, 3) === 'GIF') {
+    return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) };
+  }
+  if (buf.length >= 30 && buf.toString('latin1', 0, 4) === 'RIFF' && buf.toString('latin1', 8, 12) === 'WEBP') {
+    const kind = buf.toString('latin1', 12, 16);
+    if (kind === 'VP8X') return { width: 1 + buf.readUIntLE(24, 3), height: 1 + buf.readUIntLE(27, 3) };
+    if (kind === 'VP8 ') return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff };
+    if (kind === 'VP8L' && buf.length >= 25) {
+      const bits = buf.readUInt32LE(21);
+      return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+    }
+    return null;
+  }
+  if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+    let at = 2;
+    while (at + 9 < 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; }
+      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) };
+      }
+      if (length < 2) return null;
+      at += 2 + length;
+    }
+    return null;
+  }
+  return null;
+}
+
+/** 读文件头（最多 HEAD_BYTES）；打不开就 null。 */
+async function readHead(filePath, size) {
+  let handle;
   try {
-    stat = await fs.stat(filePath);
+    handle = await fs.open(filePath, 'r');
+    const length = Math.min(size, HEAD_BYTES);
+    const buf = Buffer.alloc(length);
+    await handle.read(buf, 0, length, 0);
+    return buf;
   } catch {
     return null;
+  } finally {
+    if (handle) await handle.close().catch(() => {});
   }
-  if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_IMAGE_BYTES) return null;
-  const key = `${filePath}:${stat.size}:${stat.mtimeMs}`;
-  const hit = cache.get(key);
-  if (hit) {
-    cache.delete(key);
-    cache.set(key, hit);
-    return hit;
-  }
-  let buf;
+}
+
+/**
+ * 登记一张本机图片，返回它的编号与宽高。
+ *
+ * 编号取「路径 + 大小 + 修改时间」的短哈希：同一张图在同一轮历史里会被反复解析，
+ * 这个组合稳定，且改过之后自然换号（图片内容变了本来就该换）。
+ */
+async function registerLocalImage(filePath) {
+  let stat;
   try {
-    buf = await fs.readFile(filePath);
+    stat = await fs.stat(filePath);
   } catch {
     return null;
   }
-  const mediaType = sniffMediaType(buf);
+  if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_IMAGE_BYTES) return null;
+  const id = crypto.createHash('sha1').update(`${filePath}:${stat.size}:${stat.mtimeMs}`).digest('hex').slice(0, 16);
+  const known = registry.get(id);
+  if (known) return { id, ...known };
+  const head = await readHead(filePath, stat.size);
+  if (!head) return null;
+  const mediaType = sniffMediaType(head);
   if (!mediaType) return null;
-  const uri = `data:${mediaType};base64,${buf.toString('base64')}`;
-  cache.set(key, uri);
-  while (cache.size > MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value);
-  return uri;
+  const parsed = imageSizeOf(head);
+  const sane = parsed && parsed.width > 0 && parsed.height > 0
+    && parsed.width <= 30000 && parsed.height <= 30000;
+  const size = sane ? parsed : {};
+  const entry = { filePath, mediaType, ...size };
+  registry.set(id, entry);
+  while (registry.size > MAX_REGISTRY_ENTRIES) registry.delete(registry.keys().next().value);
+  return { id, ...entry };
+}
+
+/** 取图口用：只认登记表里的编号（构造不出来的编号一律 null → 404）。 */
+function localImageOf(id) {
+  if (typeof id !== 'string' || !id) return null;
+  return registry.get(id) || null;
 }
 
+/** 清空登记表（测试用）。 */
+function clearLocalImages() {
+  registry.clear();
+}
 /**
  * Markdown 里「必须保持字面」的区间：围栏代码块与行内代码。
  *
@@ -232,8 +305,10 @@ function inRanges(index, ranges) {
 }
 
 /**
- * 把一段文本里的本机图片语法换成 data URI。返回原字符串本身（`===`）表示一个字没动，
- * 调用方据此免掉不必要的对象拷贝。
+ * 把一段文本里的本机图片语法换成**短编号**（带宽高）：`![alt](dsh-local-image:<id>?w=..&h=..)`。
+ *
+ * 返回原字符串本身（`===`）表示一个字没动，调用方据此免掉不必要的对象拷贝。
+ * `budget` 只为兼容调用点保留：标识只有几十字节，不再有字符预算这回事。
  */
 async function inlineTextImages(text, budget) {
   if (typeof text !== 'string' || text.indexOf('![') < 0) return text;
@@ -241,21 +316,99 @@ async function inlineTextImages(text, budget) {
   const matches = [...text.matchAll(IMAGE_RE)].filter((m) => !inRanges(m.index, ranges));
   if (!matches.length) return text;
   const pool = budget || createTextImageBudget();
-  let textBudget = MAX_TEXT_CHARS;
+  let count = pool.remaining;
   let out = '';
   let cursor = 0;
   for (const m of matches) {
-    if (textBudget <= 0 || pool.remaining <= 0) break;
+    if (count <= 0) break;
     const filePath = localImagePathOf(m[2], pool.cwd);
     if (!filePath) continue;
-    const uri = await dataUriFor(filePath);
-    if (!uri || uri.length > textBudget || uri.length > pool.remaining) continue;
-    textBudget -= uri.length;
-    pool.remaining -= uri.length;
-    out += text.slice(cursor, m.index) + `![${m[1]}](${uri})`;
+    const entry = await registerLocalImage(filePath);
+    if (!entry) continue;
+    count -= 1;
+    pool.remaining = count;
+    const query = entry.width && entry.height ? `?w=${entry.width}&h=${entry.height}` : '';
+    out += text.slice(cursor, m.index) + `![${m[1]}](dsh-local-image:${entry.id}${query})`;
     cursor = m.index + m[0].length;
   }
   return cursor === 0 ? text : out + text.slice(cursor);
 }
+/**
+ * Markdown 里「必须保持字面」的区间：围栏代码块与行内代码。
+ *
+ * 代码块里的 `![](/tmp/a.png)` 是**写法示例**而不是要画的图。旧实现整段正则替换，
+ * 会把三行代码换成几十万字符的 base64——App 把这段按代码文本铺开，就成了很长很长
+ * 的一块（真机现象：图片语法那块刷出几十屏，要划很久）。围栏判定与 App 的
+ * `utils/markdown/parser.ts` 同口径（两边都 trim 后看 3 个以上 ` / ~）。
+ */
+function literalRanges(text) {
+  const ranges = [];
+  const lines = text.split('\n');
+  const lineStarts = [];
+  let offset = 0;
+  for (const line of lines) {
+    lineStarts.push(offset);
+    offset += line.length + 1;
+  }
+  let fence = null;
+  let fenceStart = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (fence) {
+      const close = /^(`{3,}|~{3,})[ \t]*$/.exec(line.trim());
+      if (close && close[1][0] === fence.char && close[1].length >= fence.length) {
+        ranges.push([fenceStart, lineStarts[index] + line.length]);
+        fence = null;
+      }
+      continue;
+    }
+    const open = /^(`{3,}|~{3,})/.exec(line.trim());
+    if (!open) continue;
+    fence = { char: open[1][0], length: open[1].length };
+    fenceStart = lineStarts[index];
+  }
+  // 没闭合的围栏按 App 的解析口径一直吃到文末。
+  if (fence) ranges.push([fenceStart, text.length]);
+
+  // 行内代码：同长度的反引号成对（`code`）。围栏内部的反引号已在上面标过。
+  let cursor = 0;
+  while (cursor < text.length) {
+    if (text[cursor] !== '`' || inRanges(cursor, ranges)) {
+      cursor += 1;
+      continue;
+    }
+    let ticks = 1;
+    while (text[cursor + ticks] === '`') ticks += 1;
+    let scan = cursor + ticks;
+    let closed = -1;
+    while (scan < text.length) {
+      if (text[scan] !== '`' || inRanges(scan, ranges)) {
+        scan += 1;
+        continue;
+      }
+      let run = 1;
+      while (text[scan + run] === '`') run += 1;
+      if (run === ticks) {
+        closed = scan + run;
+        break;
+      }
+      scan += run;
+    }
+    if (closed < 0) {
+      cursor += ticks;
+      continue;
+    }
+    ranges.push([cursor, closed]);
+    cursor = closed;
+  }
+  return ranges;
+}
+
+function inRanges(index, ranges) {
+  for (const [start, end] of ranges) {
+    if (index >= start && index < end) return true;
+  }
+  return false;
+}
 
-module.exports = { inlineTextImages, createTextImageBudget, localImagePathOf, hasRelativeImage };
+module.exports = { inlineTextImages, createTextImageBudget, localImagePathOf, hasRelativeImage, localImageOf, registerLocalImage, imageSizeOf, clearLocalImages };

package/lib/mobile/session-local-image.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * 正文图的字节（POST /api/mobile/v1/session/local-image）。
+ *
+ * 正文里那张图在历史投影时已经被登记成一个短编号（见 `local-images.js`），手机画到它时
+ * 拿着编号来取字节。**这不是「按路径读文件」**：只认登记表里的编号，构造一个编号读不到
+ * 任何别的文件 —— 能力面与附件那条 `session/attachment` 同一个口径。
+ *
+ * 只认 `id`、不认 sessionId：授权依据是「这张图在投影这条会话时被登记过」，而不是调用方
+ * 自报的会话号。登记表是进程级的，同一个编号从哪条会话取都一样（本来就是同一份文件）。
+ *
+ * 回 base64 JSON 而不是流：正文图都是单张位图、上限 2.5MB，与附件那条一致；大文件
+ * （视频 / 交付物）走 `session/file` 的流式那条，别混。
+ */
+
+const fs = require('node:fs/promises');
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { localImageOf } = require('./local-images.js');
+
+async function handleSessionLocalImage(ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.id !== 'string' || !body.id) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { id }' } });
+  }
+  const entry = localImageOf(body.id);
+  // 插件重启、或那条记录被挤出登记表：如实 404，让 App 把重试按钮的失败说清楚。
+  if (!entry) {
+    return sendJson(res, 404, { ok: false, error: { code: 'not-found', message: '这张图没有登记，或登记已失效' } });
+  }
+  let data;
+  try {
+    data = await fs.readFile(entry.filePath);
+  } catch {
+    return sendJson(res, 404, { ok: false, error: { code: 'missing', message: '图片文件已经不在了' } });
+  }
+  sendJson(res, 200, {
+    ok: true,
+    mediaType: entry.mediaType,
+    data: data.toString('base64'),
+    ...(entry.width && entry.height ? { width: entry.width, height: entry.height } : {}),
+  });
+}
+
+module.exports = { handleSessionLocalImage };

package/lib/mobile/session-mirror.js

@@ -8,7 +8,8 @@
  * `updatedAt:running:limit` 指纹判鲜，2 分钟 TTL，上限 256 条按插入序淘汰。
  */
 
-const { buildMessagesSnapshot, buildStatsSnapshot } = require('./session-snapshot.js');
+const { buildMessagesSnapshot } = require('./session-snapshot.js');
+const { buildStatsSnapshot } = require('./session-stats.js');
 const { mirrorHistoryStateOf } = require('./session-cache.js');
 
 const MIRROR_HISTORY_CACHE_MS = 120000;  // 2 min TTL, reduces redundant rebuilds

package/lib/mobile/session-send.js

@@ -25,6 +25,7 @@ const { promptErrorObject, MODEL_UNAVAILABLE_ERROR } = require('./history-derive
 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');
 
 /**
  * `/send` 的请求体上限（**明文**字节，图片 base64）。
@@ -285,9 +286,20 @@ async function handleSessionAttachment(ctx, req, res) {
   // 让 App 那边把重试按钮的失败说清楚，而不是转圈到超时。
   if (!data) return sendJson(res, 404, { ok: false, error: { code: 'not-found', message: '附件已不可读' } });
   const attachment = (value && value.attachment) || {};
+  const mediaType = typeof attachment.mediaType === 'string' && attachment.mediaType ? attachment.mediaType : 'image/png';
+  // `dims: true` = 只要原始宽高，不要字节。老会话里宿主没存附件的宽高，正文下发时就带不上，
+  // 手机侧只能按 240 方盒先占位、等字节到了再变高（那一行一变高，屏幕上就是「跳」）。这一档
+  // 让手机在挂载那一帧就能按真比例占好：回给它的只有两格数字，整张图的 base64 不出这台电脑。
+  if (body.dims === true) {
+    const size = imageSizeOf(Buffer.from(data, 'base64'));
+    if (!size || !(size.width > 0) || !(size.height > 0)) {
+      return sendJson(res, 404, { ok: false, error: { code: 'no-dims', message: '这张图的文件头里量不出宽高' } });
+    }
+    return sendJson(res, 200, { ok: true, mediaType, width: size.width, height: size.height });
+  }
   sendJson(res, 200, {
     ok: true,
-    mediaType: typeof attachment.mediaType === 'string' && attachment.mediaType ? attachment.mediaType : 'image/png',
+    mediaType,
     data,
     ...(typeof attachment.name === 'string' ? { name: attachment.name } : {}),
   });

package/lib/mobile/session-snapshot.js

@@ -1,11 +1,12 @@
 'use strict';
 
 /**
- * 消息与统计快照：镜像推送与 /messages 分页共用的两条折叠路径。
+ * 消息快照：镜像推送与 /messages 分页共用的折叠路径。
  *
  * buildMessagesSnapshot（不解析 query）与 handleMessages（解析 beforeSeq/afterSeq/limit）
  * 共用消息折叠逻辑。普通会话走 sessions.history；子代理必须携带 durable parent address，
- * 改走 subagents.history，不能把 child sessionId 当普通会话读。
+ * 改走 subagents.history，不能把 child sessionId 当普通会话读。统计投影不在这里，
+ * 在 session-stats.js（两条路径的取数口径不同，别混回一份）。
  *
  * 上游历史接口不认 afterSeq（只认 beforeSeq/maxMessages），所以增量轮询在插件内用较大的
  * 窗口（Math.max(limit, 200)）拉最近若干事件后再按 seq 过滤；缺口超过窗口时会漏，此时
@@ -20,7 +21,7 @@ const { resolveEventAttachments } = require('./attachments.js');
 const { createTextImageBudget } = require('./local-images.js');
 const { entryWindowPayload } = require('./entry-window.js');
 
-const MESSAGES_DEFAULT_LIMIT = 50;  // /messages 默认条数
+const MESSAGES_DEFAULT_LIMIT = 50, TOOL_LOOKBACK_EVENTS = 120;  // 默认条数 / 倒着翻页时多看几条（只为认出这一轮的工具结果）
 
 function historyHttpStatus(error) {
   switch (error && error.code) {
@@ -55,58 +56,19 @@ function eventSeqOf(entry) {
 async function buildMessagesSnapshot(ctx, sessionId, limit = MESSAGES_DEFAULT_LIMIT) {
   const { value, error } = unwrap(await callSessions(ctx, 'history', { sessionId, maxMessages: limit }));
   if (error) return { ok: false, error };
-  const events = (value && value.events) || [];
+  const allEvents = (value && value.events) || [];
+  // 这一路是整窗快照，不带分页参数（宿主已按 maxMessages 截过）：多给了就只留尾部那一窗。
+  const events = allEvents.length > limit ? allEvents.slice(-limit) : allEvents;
   // 引用模式：图片只下发 attachmentId，不取字节（见 attachments.js）。正文里本机图片的
   // 内联仍走 budget，与之前一致。
   const budget = createTextImageBudget();
   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 messages = deriveMessages(resolvedEvents, sessionId);
   const lastSeq = events.length ? (eventSeqOf(events[events.length - 1]) ?? 0) : 0;
   const hasMore = !!(value && value.hasMore);
   return { ok: true, items: messages, lastSeq, hasMore };
 }
 
-/**
- * 镜像快照用的统计投影（与 handleStats 尾部投影读取保持一致）：取整帧 projections，
- * 并把 plan 归一化为 planMode，供 pushMirror 为活跃会话生成统计快照。
- */
-async function buildStatsSnapshot(ctx, sessionId) {
-  return statsProjections(ctx, sessionId);
-}
-
-/**
- * 统计投影快照（handleStats 与 buildStatsSnapshot 共用）。
- *
- * 0.2.0 把整帧投影从 history/page 的返回值里拆走了，「拉一条历史顺带取投影」这条路断了；
- * 改走 `apiProxy.sessions.projections({ request: { sessionId } })`，返回值是
- * `{ asOfSeq, values }`。顺带把 plan 归一化成 planMode（排队条与计划条读它）。
- * 历史轮询是每 15 秒一次的热路径，多背一次投影 RPC 划不来，所以统计单独走投影端点。
- */
-async function statsProjections(ctx, sessionId) {
-  // 显式给 signal：宿主部分方法内部直接读 signal.aborted，不做 undefined 兜底。
-  const controller = new AbortController();
-  let value;
-  let error;
-  try {
-    ({ value, error } = unwrap(await callSessions(ctx, 'projections', { sessionId }, 'mobile', controller.signal)));
-  } catch (thrown) {
-    // 投影读不出来不该变成一个从路由层逃出去的 rejection：handleStats 要回 400，
-    // pushMirror 那边更是一条都不能抛（抛了整帧快照就丢了）。收敛成正常错误态。
-    error = thrown && typeof thrown === 'object' && typeof thrown.code === 'string'
-      ? { code: thrown.code, message: typeof thrown.message === 'string' ? thrown.message : '读会话投影失败' }
-      : { code: 'host-call-failed', message: thrown && thrown.message ? String(thrown.message) : '读会话投影失败' };
-  }
-  if (error) return { ok: false, error };
-  const projections = value && value.values && typeof value.values === 'object' ? value.values : {};
-  const plan = projections.plan;
-  return {
-    ok: true,
-    projections: plan && typeof plan === 'object' && typeof plan.active === 'boolean'
-      ? { ...projections, planMode: { active: plan.active, ...(typeof plan.pending === 'boolean' ? { pending: plan.pending } : {}) } }
-      : projections,
-  };
-}
-
 /** GET /api/mobile/v1/session/messages?sessionId=…&beforeSeq=…&afterSeq=…&limit=…（token） */
 async function handleMessages(ctx, req, res) {
   const url = new URL(req.url, 'http://x');
@@ -135,7 +97,7 @@ async function handleMessages(ctx, req, res) {
     if (Number.isSafeInteger(parsed)) afterSeq = parsed;
   }
   const payload = { sessionId, maxMessages: limit };
-  if (beforeSeq !== null) payload.beforeSeq = beforeSeq;
+  if (beforeSeq !== null) { payload.beforeSeq = beforeSeq; payload.maxMessages = limit + TOOL_LOOKBACK_EVENTS; }
   // 上游历史接口都不支持 afterSeq（只认 beforeSeq/maxMessages），故在插件内用较大的窗口
   // 拉最近若干事件后再过滤 seq > afterSeq，覆盖常见轮询缺口；缺口超过窗口时要求客户端全量补齐。
   if (afterSeq !== null) payload.maxMessages = Math.max(limit, 200);
@@ -159,16 +121,37 @@ async function handleMessages(ctx, req, res) {
     error = normalizeHistoryError(thrown);
   }
   if (error) return sendJson(res, historyHttpStatus(error), { ok: false, error });
-  const events = (value && value.events) || [];
-  // 增量：只保留水位之后的事件；非 afterSeq 调用时 events 原样保留（行为与之前完全一致）。
-  const filtered = afterSeq !== null ? events.filter((entry) => (eventSeqOf(entry) ?? -1) > afterSeq) : events;
+  const allEvents = (value && value.events) || [];
+  const lookback = beforeSeq !== null && allEvents.length > limit ? allEvents.slice(0, -limit) : null;
+  const events = lookback ? allEvents.slice(-limit) : allEvents;
+  // 增量：游标之后的事件才是要发的行，但**折叠**仍按整窗做（见下）。
   // 一页历史共用一个内联图片预算：正文里的本机图片越多，越靠后的那些保持字面 markdown，
   // 而不是让单次响应无限膨胀（见 local-images.js 的三级预算）。
+  //
+  // 折叠要看**整窗**：压缩与 slash 命令行都是「一串事件攒出来的一行」（start → summary → end、
+  // run → done），按游标先把事件砍掉再折叠，剩下那半截就会漏成「没有摘要的压缩行」和
+  // 「没有名字的命令行」——真机现场就是屏幕上并排三行：`compact·执行中`、`上下文已压缩·
+  // 压缩摘要不可用`、`命令·Compacted 206 history items`。所以游标只用来筛**折叠出来的行**，
+  // 事件仍按整窗折叠；附件只为游标之后的事件解析（游标前那批只当上下文，不出行）。
   const budget = createTextImageBudget();
-  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 resolvedEvents = await Promise.all(events.map((entry) => {
+    const seq = eventSeqOf(entry);
+    const deliverable = afterSeq === null || !Number.isSafeInteger(seq) || seq > afterSeq;
+    const event = entry.event || entry;
+    if (!deliverable) return event;
+    return resolveEventAttachments(ctx, sessionId, event, { budget, referencesOnly: true })
+      .then((resolved) => (entry.event ? { ...entry, event: resolved } : resolved));
+  }));
+  const messages = deriveMessages(resolvedEvents, sessionId, lookback);
   const hasMore = !!(value && value.hasMore);
-  const items = wantThin ? thinEntryMessages(messages, { hasMore }) : messages;
+  const items = wantThin
+    ? thinEntryMessages(messages, { hasMore })
+    // 结构行（压缩 / 命令行）照发：它们由整段生命周期折出来，一次也就一两条，按 id 覆盖
+    // 正好把屏幕上已经歪掉的那一行修回来 —— 按游标筛掉就永远修不回来。
+    : (afterSeq === null
+      ? messages
+      : messages.filter((item) => item.kind === 'compaction' || item.kind === 'command'
+        || (Number.isSafeInteger(item.seq) && item.seq > afterSeq)));
   // 工具结果不产生消息行，但会把**缓存里已有的**工具卡从 running 补成最终态。补丁取自
   // 整个窗口（调用方游标可能已越过结果 seq）；已随消息块下发的只回状态（见 toolResultPatchesFor）。
   // 增量那一发（带 afterSeq）一律只回状态：调用方手上已有一份会话，整窗重发等于每 15 秒
@@ -193,4 +176,4 @@ async function handleMessages(ctx, req, res) {
   });
 }
 
-module.exports = { eventSeqOf, buildMessagesSnapshot, statsProjections, buildStatsSnapshot, handleMessages };
+module.exports = { eventSeqOf, buildMessagesSnapshot, handleMessages };

package/lib/mobile/session-stats.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * 会话统计投影：handleStats 与镜像推送共用的那一份取数口径。
+ *
+ * 0.2.0 把整帧投影从 history/page 的返回值里拆走了，「拉一条历史顺带取投影」这条路断了；
+ * 改走 `apiProxy.sessions.projections({ request: { sessionId } })`，返回值是
+ * `{ asOfSeq, values }`。顺带把 plan 归一化成 planMode（排队条与计划条读它）。
+ * 历史轮询是每 15 秒一次的热路径，多背一次投影 RPC 划不来，所以统计单独走投影端点。
+ */
+
+const { unwrap } = require('./envelope.js');
+const { callSessions } = require('./rpc.js');
+
+/**
+ * 镜像快照用的统计投影（与 handleStats 尾部投影读取保持一致）：取整帧 projections，
+ * 并把 plan 归一化为 planMode，供 pushMirror 为活跃会话生成统计快照。
+ */
+async function buildStatsSnapshot(ctx, sessionId) {
+  return statsProjections(ctx, sessionId);
+}
+
+/**
+ * 统计投影快照（handleStats 与 buildStatsSnapshot 共用）。
+ */
+async function statsProjections(ctx, sessionId) {
+  // 显式给 signal：宿主部分方法内部直接读 signal.aborted，不做 undefined 兜底。
+  const controller = new AbortController();
+  let value;
+  let error;
+  try {
+    ({ value, error } = unwrap(await callSessions(ctx, 'projections', { sessionId }, 'mobile', controller.signal)));
+  } catch (thrown) {
+    // 投影读不出来不该变成一个从路由层逃出去的 rejection：handleStats 要回 400，
+    // pushMirror 那边更是一条都不能抛（抛了整帧快照就丢了）。收敛成正常错误态。
+    error = thrown && typeof thrown === 'object' && typeof thrown.code === 'string'
+      ? { code: thrown.code, message: typeof thrown.message === 'string' ? thrown.message : '读会话投影失败' }
+      : { code: 'host-call-failed', message: thrown && thrown.message ? String(thrown.message) : '读会话投影失败' };
+  }
+  if (error) return { ok: false, error };
+  const projections = value && value.values && typeof value.values === 'object' ? value.values : {};
+  const plan = projections.plan;
+  return {
+    ok: true,
+    projections: plan && typeof plan === 'object' && typeof plan.active === 'boolean'
+      ? { ...projections, planMode: { active: plan.active, ...(typeof plan.pending === 'boolean' ? { pending: plan.pending } : {}) } }
+      : projections,
+  };
+}
+
+module.exports = { buildStatsSnapshot, statsProjections };

package/lib/mobile/sessions.js

@@ -6,7 +6,7 @@
  * 这个文件一度是一千九百多行的单体，HTTP 路由、宿主 RPC、缓存、事件派生全混在一起；现在
  * 按域拆开：envelope（信封拆解）、rpc（窄接口封装）、session-cache（按 ctx 隔离的状态表）、
  * attachments、completion、session-models、session-search、session-send、session-snapshot、
- * session-mirror、session-goal、session-presets、session-preview、session-list-shortcut。
+ * session-stats、session-mirror、session-goal、session-presets、session-preview、session-list-shortcut。
  *
  * 剩下的就是列表：GET /sessions（10 秒缓存 + fresh 绕过 + 完成态确认 + `?rev=` 条件刷新）、
  * 单会话摘要、正文水位探针、统计、新建会话、排队消息动作。本文件继续转出各子模块的导出，
@@ -32,7 +32,8 @@ const {
 const { resolveEventAttachments } = require('./attachments.js');
 const { updateCompletionStates, confirmCompletionFromHistory } = require('./completion.js');
 const { lastTurnOf } = require('./session-last-turn.js');
-const { eventSeqOf, buildMessagesSnapshot, buildStatsSnapshot, statsProjections, handleMessages } = require('./session-snapshot.js');
+const { eventSeqOf, buildMessagesSnapshot, handleMessages } = require('./session-snapshot.js');
+const { buildStatsSnapshot, statsProjections } = require('./session-stats.js');
 const { buildModelsSnapshot, handleModels, handleSelectModel } = require('./session-models.js');
 const { buildSingleSessionMirror, buildMirrorWarmSnapshots } = require('./session-mirror.js');
 const { promptOnce, handleSend, handleCommands, handleSessionRead, handleSessionAttachment, handleStop,