dsh-mobile-plugin 0.5.0 → 0.5.3

package/lib/mobile/history-derive.js

@@ -12,6 +12,30 @@
  */
 
 const { cutAssistantBlock, cutToolResultEvent, createToolNameIndex } = require('./wire-cut.js');
+const { rememberToolResults, toolResultsFor } = require('./tool-result-cache.js');
+
+/** 每一轮出过的图（工具结果里的图片块），轮号 → 图。`lookback` 也扫：它才装得下更早那一页。 */
+function collectTurnImages(entries, lookbackEntries) {
+  const byTurn = new Map();
+  for (const list of [entries, lookbackEntries]) {
+    for (const entry of list || []) {
+      const e = entry && entry.event ? entry.event : entry;
+      if (!e || e.type !== 'tool/result' || !e.data || !e.data.message) continue;
+      const turn = typeof e.data.turn === 'number' ? e.data.turn : undefined;
+      if (turn === undefined) continue;
+      const { parts } = toolResultParts(cutToolResultEvent(e, '').data.message);
+      const images = toolResultImages(parts);
+      if (images.length === 0) continue;
+      const bucket = byTurn.get(turn) || [];
+      for (const image of images) {
+        if (bucket.some((kept) => kept.attachmentId && kept.attachmentId === image.attachmentId)) continue;
+        bucket.push(image);
+      }
+      byTurn.set(turn, bucket);
+    }
+  }
+  return byTurn;
+}
 const {
   reasoningStepSummary,
   toolStepSummary,
@@ -61,12 +85,14 @@ function toolResultParts(msg) {
  * 图片块 → 移动端图片条目（`ChatMessage.images[]` / 工具块的 `images[]` 同一个形状）。
  *
  * 两条互斥的出口：
- *  - 块上有 `attachmentId`：下发**引用** `{ mediaType, name?, attachmentId }`，**不带 data**。
- *    字节由手机端要画的时候按 attachmentId 单张去取（`/session/attachment`），
+ *  - 块上有 `attachmentId`：下发**引用** `{ mediaType, name?, width?, height?, attachmentId }`，
+ *    **不带 data**。字节由手机端要画的时候按 attachmentId 单张去取（`/session/attachment`），
  *    历史响应因此不再背着几十张截图的 base64。
- *  - 块里本来就只有内联 `data`、没有 attachmentId：照旧下发 `{ mediaType, data, name? }`。
+ *  - 块里本来就只有内联 `data`、没有 attachmentId：照旧下发 `{ mediaType, data, name?, width?, height? }`。
  *    这条兜底不能删——老日志、工具结果里存在这种直接带字节的图片块。
  *
+ * 宽高两格见 `imageDimsOf`：那是「手机能不能在挂载那一帧就占好位置」的前提。
+ *
  * 两条都要求 mediaType 可读（块上没有就退到 attachment 上的），否则 App 认不出来、
  * 也没有可显示的动作，返回 null 让调用方丢掉它。
  */
@@ -81,11 +107,28 @@ function imageEntryOf(block) {
   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 } : {}) };
+  const dims = imageDimsOf(block, attachment);
+  if (attachmentId) return { mediaType, ...(name !== undefined ? { name } : {}), ...dims, attachmentId };
+  if (typeof block.data === 'string' && block.data) return { mediaType, data: block.data, ...(name !== undefined ? { name } : {}), ...dims };
   return null;
 }
 
+/**
+ * 图片的原始宽高 —— 宿主的附件里本来就有（`attachment.width` / `attachment.height`）。
+ *
+ * **不许省掉这一格。** 手机侧要靠它把图片行的高度在**挂载那一帧就占好**：没有宽高，那一行
+ * 只能先按 240 方盒占位、等图解码完 onLoad 再改成真比例；而行高在挂载之后变高，正是对话页
+ * 「先落到底、再被顶回去」的来源（贴底列表上方一变高，屏幕上的内容就往下退一段）。
+ * 宽高非法（缺失 / 非正数）时整格不出现，调用方仍按旧兜底盒处理。
+ */
+function imageDimsOf(block, attachment) {
+  const pick = (value) => (typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined);
+  const width = pick(block.width) ?? pick(attachment.width);
+  const height = pick(block.height) ?? pick(attachment.height);
+  if (width === undefined || height === undefined) return {};
+  return { width, height };
+}
+
 /** 把 tool/result 的图片块收成移动端图片条目（两种出口见 imageEntryOf）。 */
 function toolResultImages(parts) {
   const out = [];
@@ -324,10 +367,23 @@ function presentedPathsOf(events) {
  *  - command：command/run 发出行，command/done 原地升级。
  * 结构化项与消息按 seq 升序混排；旧载荷字段缺失时跳过对应项，绝不抛错。
  */
-function deriveMessages(events) {
+function deriveMessages(events, sessionId, lookbackEvents) {
   const out = [];
   // 预扫描 tool/result 事件（同批次事件内，结果可能在调用块之前/之后出现）。
-  const toolResults = buildToolResultMap(events);
+  // `lookbackEvents` 是这一页**再往前**的一小段：倒着分页时工具结果常常落在比消息更早的位置
+  // （一轮里先跑工具、最后才写正文），只看这一页就看不出这一轮出过哪些图。
+  const toolResults = buildToolResultMap(lookbackEvents && lookbackEvents.length ? events.concat(lookbackEvents) : events);
+  // 倒着分页时，一页的边界可能正好切在「工具调用」与「它的结果」之间：这一页只有调用，
+  // 结果在更新的一页（本机早就拿到过）。把那些记在进程里的结果并进来，图就跟着消息一起
+  // 下发，手机侧那一行在挂载那一帧就是终高（见 tool-result-cache.js）。
+  const remembered = toolResultsFor(sessionId);
+  if (remembered) {
+    for (const [callId, result] of remembered) {
+      if (!toolResults.has(callId)) toolResults.set(callId, result);
+    }
+  }
+  // 这一页看到的结果记下来，供更早的页用（同一进程里，后到的页是更早的那几页）。
+  rememberToolResults(sessionId, toolResults);
   // 预扫描 compaction/summary：检查点 user/message 与 summary 事件在日志里的先后不固定，
   // 用 compactionId → summary 数据把 counts 补全到同一压缩行上。
   const summaries = new Map();
@@ -505,12 +561,17 @@ function deriveMessages(events) {
     });
     const text = blocksToText(blocks);
     // 图片条目统一投影：引用模式带 attachmentId 不带 data，内联兜底带 data 不带 attachmentId。
+    //
+    // **宽高必须一起带上**（`imageDimsOf` 的口径）：手机侧靠它在挂载那一帧就把图片行的高度占好，
+    // 少这两格就只能先占 240 方盒、等解码完再改，而贴底列表上方一变高，屏幕上看到的内容就
+    // 往下退一段 —— 这正是「先落到底、再被顶回去」那一跳。
     const images = [
       ...blocks.filter((b) => b.type === 'image'),
       ...toolImages,
-    ].map(({ mediaType, data, name, attachmentId }) => ({
+    ].map(({ mediaType, data, name, attachmentId, width, height }) => ({
       mediaType,
       ...(typeof name === 'string' ? { name } : {}),
+      ...(Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0 ? { width, height } : {}),
       ...(typeof attachmentId === 'string' && attachmentId ? { attachmentId } : {}),
       ...(typeof attachmentId === 'string' && attachmentId ? {} : { data }),
     }));
@@ -568,6 +629,16 @@ function deriveMessages(events) {
     if (item.role === 'user') lastOpener = item;
   };
 
+  /**
+   * 这次压缩由哪条 slash 命令触发（`compaction/*` 上的 `sourceCommandId`）。
+   *
+   * 手动 `/compact` 时压缩行与命令行是同一件事的两半（桌面 `CompactionCommandCard` 只画一个
+   * `CompactionItem`），靠这个 id 配对，见出循环后的「认领」。
+   */
+  const commandIdOf = (data) => (data && typeof data.sourceCommandId === 'string' && data.sourceCommandId !== ''
+    ? data.sourceCommandId
+    : null);
+
   // 放入一行 compaction：同一 compactionId 只保留一行，检查点行原地替换 start 行（最终按 seq 排序归位）。
   const placeCompaction = (item) => {
     let index = compactionAt.get(item.id);
@@ -611,6 +682,9 @@ function deriveMessages(events) {
           : (msg.id != null ? String(msg.id) : null);
         if (id === null) continue;
         const s = summaries.get(id);
+        // 触发命令的 id 在检查点自己的 source 上（桌面 `compactSource` 读的就是它）。只认
+        // `compaction/*` 的 data 时，检查点先到 / 那些事件在窗口外就配不上命令行。
+        const commandId = typeof src.sourceCommandId === 'string' && src.sourceCommandId !== '' ? src.sourceCommandId : null;
         placeCompaction({
           id,
           kind: 'compaction',
@@ -618,6 +692,7 @@ function deriveMessages(events) {
           summary: s ? compactionSummaryText(s.summary) : null,
           shadowedItemCount: s ? shadowedCount(s.shadowedSeqs) : null,
           shadowedTokenCount: s ? shadowedTokens(s.shadowedTokenCount) : null,
+          ...(commandId ? { compactionCommandId: commandId } : {}),
           seq,
           time,
         });
@@ -655,6 +730,7 @@ function deriveMessages(events) {
       // 行已由检查点发出（done）时跳过，避免重复行。同一轮里已有没落定的行就**原地顶替**
       // （换 id/状态，位置留在第一次尝试那一处）—— 否则一次跑几十步就是几十条行。
       const idx = pendingCompactionAt(e.data.turn, e.data.compactionId);
+      const commandId = commandIdOf(e.data);
       if (idx < 0) {
         placeCompaction({
           id: e.data.compactionId,
@@ -666,6 +742,7 @@ function deriveMessages(events) {
           seq,
           time,
           ...(typeof e.data.turn === 'number' ? { turn: e.data.turn } : {}),
+          ...(commandId ? { compactionCommandId: commandId } : {}),
         });
       } else {
         const existing = out[idx];
@@ -675,6 +752,7 @@ function deriveMessages(events) {
           state: 'running',
           error: null,
           ...(typeof e.data.turn === 'number' ? { turn: e.data.turn } : {}),
+          ...(commandId ? { compactionCommandId: commandId } : {}),
         };
         compactionAt.set(e.data.compactionId, idx);
       }
@@ -683,6 +761,7 @@ function deriveMessages(events) {
       // 带原因。这条以前整条丢掉，于是被拒绝的压缩永远停在「正在压缩…」，失败一次都看不见。
       const error = typeof e.data.error === 'string' && e.data.error !== '' ? e.data.error : null;
       const idx = pendingCompactionAt(e.data.turn, e.data.compactionId);
+      const commandId = commandIdOf(e.data);
       if (idx < 0) {
         placeCompaction({
           id: e.data.compactionId,
@@ -695,6 +774,7 @@ function deriveMessages(events) {
           seq,
           time,
           ...(typeof e.data.turn === 'number' ? { turn: e.data.turn } : {}),
+          ...(commandId ? { compactionCommandId: commandId } : {}),
         });
       } else {
         const existing = out[idx];
@@ -703,6 +783,7 @@ function deriveMessages(events) {
           id: e.data.compactionId,
           state: error ? 'failed' : 'done',
           error,
+          ...(commandId ? { compactionCommandId: commandId } : {}),
         };
         compactionAt.set(e.data.compactionId, idx);
       }
@@ -710,12 +791,14 @@ function deriveMessages(events) {
       // 已有同 compactionId 的行（start 或检查点发出）→ 升级为 done 并补 counts；否则新增 done 行。
       const id = e.data.compactionId;
       const existing = compactionAt.has(id) ? out[compactionAt.get(id)] : null;
+      const commandId = commandIdOf(e.data);
       if (existing) {
         existing.state = 'done';
         existing.error = null;
         existing.summary = compactionSummaryText(e.data.summary);
         existing.shadowedItemCount = shadowedCount(e.data.shadowedSeqs);
         existing.shadowedTokenCount = shadowedTokens(e.data.shadowedTokenCount);
+        if (commandId) existing.compactionCommandId = commandId;
       } else {
         placeCompaction({
           id,
@@ -726,6 +809,7 @@ function deriveMessages(events) {
           shadowedTokenCount: shadowedTokens(e.data.shadowedTokenCount),
           seq,
           time,
+          ...(commandId ? { compactionCommandId: commandId } : {}),
         });
       }
     } else if (e.type === 'llm/retry' && e.data && typeof e.data.retryId === 'string' && e.data.retryId !== '' && typeof e.data.retry === 'number') {
@@ -783,7 +867,9 @@ function deriveMessages(events) {
     } else if (e.type === 'command/done' && e.data && typeof e.data.commandId === 'string' && e.data.commandId !== '') {
       // 升级同 commandId 行（name 保 run 的）；done 先到（罕见）则按 done 内容建行。
       const id = e.data.commandId;
-      const done = { kind: 'command', status: 'done', seq, time };
+      // `id` 必须落在行上：done 先到（增量窗口从命令行尾巴开始时就是这种）时这条行是新建的，
+      // 没有 id 的话 App 按 id 合并就配不上那半截 run 行 —— 屏幕上会多出一行「命令 · …」。
+      const done = { id, kind: 'command', status: 'done', seq, time };
       if (e.data.kind === 'error' || e.data.kind === 'success') done.resultKind = e.data.kind;
       if (typeof e.data.text === 'string' && e.data.text !== '') done.text = e.data.text;
       const existing = commandAt.has(id) ? out[commandAt.get(id)] : null;
@@ -825,6 +911,24 @@ function deriveMessages(events) {
       };
     }
   }
+  /**
+   * 这一轮出过的图也按轮回填到**最后一条正文**上。
+   *
+   * 倒着翻页时，工具结果（图在这里）的 seq 往往比这条正文更早 —— 那一页后到，正文先上屏，
+   * 于是这一行先按「没图」的高度排好，等下一页把图带回来才长高；它在用户头顶上，一长高就把
+   * 正看的内容推走。`lookbackEvents` 里已经能看到这一轮的结果，就先挂到正文那条上（与 App
+   * `chatRenderRows` 的 settleImages 同口径），行在挂载那一帧就是终高。
+   */
+  if (producedItems.length > 0) {
+    const byTurn = collectTurnImages(events, lookbackEvents);
+    for (const [turn, images] of byTurn) {
+      // 这一轮已经有消息带图（工具调用那条就在这一页里）：别重复挂，App 那边也会去重。
+      if (producedItems.some((entry) => entry.turn === turn && (entry.item.images?.length ?? 0) > 0)) continue;
+      const carriers = producedItems.filter((entry) => entry.turn === turn && entry.item.role !== 'user' && entry.item.text);
+      const last = carriers[carriers.length - 1];
+      if (last) last.item.images = images;
+    }
+  }
   // 产出清单按轮回填：这一轮所有 write / edit 的并集，挂到这一轮每条 assistant 消息上。
   // 挂「整轮」而不是「从写那一刻起」，与桌面 `selectProducedFiles(owner)` 同口径；正文里
   // 提到这一轮写的文件就能解析成可点（App 侧按文件名或整条路径唯一命中才画，见
@@ -835,6 +939,41 @@ function deriveMessages(events) {
       if (bucket && bucket.size > 0) item.producedFiles = [...bucket];
     }
   }
+  // 手动 `/compact` 在桌面上是**一件事**：`CompactionCommandCard` 只画一个 `CompactionItem`
+  // （标题取命令名，摘要位放条数与 token 数，条数不齐时放命令结果原文），命令行那块根本不出现。
+  // 宿主的 command/run·done 与压缩检查点由 `sourceCommandId` 连在一起，所以这里让压缩行认领
+  // 命令行：压缩行继承命令名，命令行整条不发给手机 —— 否则屏幕上会多出一行「命令 ·
+  // Compacted N history items」（名字在增量窗口里丢了就掉成「命令」，摘要是宿主 en locale 的
+  // 英文原句，手机不本地化）。
+  const commandNames = new Map();
+  for (const item of out) {
+    if (!item || item.kind !== 'command') continue;
+    const entry = {};
+    if (typeof item.name === 'string' && item.name !== '') entry.name = item.name;
+    if (typeof item.text === 'string' && item.text !== '') entry.text = item.text;
+    if (entry.name !== undefined || entry.text !== undefined) commandNames.set(item.id, entry);
+  }
+  const claimedCommands = new Set();
+  for (const item of out) {
+    if (!item || item.kind !== 'compaction') continue;
+    const commandId = item.compactionCommandId;
+    if (typeof commandId !== 'string' || commandId === '') continue;
+    const paired = commandNames.get(commandId);
+    // 标题取命令名；命令行那半截不在窗口里也写 compact —— 只有 /compact 能触发压缩，桌面
+    // `fallbackState` 同样把名字兜成 'compact'，否则这一行会掉回「上下文已压缩」。
+    item.compactionTitle = paired && paired.name !== undefined ? paired.name : 'compact';
+    // 条数不齐时摘要位用命令结果原文顶上（桌面 `fallbackSummary: node.outcome?.text`）。
+    if (paired && paired.text !== undefined && (item.shadowedItemCount == null || item.shadowedTokenCount == null)) {
+      item.compactionFallbackSummary = paired.text;
+    }
+    claimedCommands.add(commandId);
+  }
+  if (claimedCommands.size > 0) {
+    for (let index = out.length - 1; index >= 0; index -= 1) {
+      const item = out[index];
+      if (item && item.kind === 'command' && claimedCommands.has(item.id)) out.splice(index, 1);
+    }
+  }
   // 压缩行带一个空正文：直播侧的同款行本来就带 `text: ''`（App 的 `structuralItems`
   // 一条不落），历史这边少这一格时，没跟上判空修复的旧安装包会在这条行上直接读正文、
   // 当场抛错、整页崩掉（2026-10-27 真机）。标题与摘要照旧按 kind 走，不读这个字段；

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 };