dsh-mobile-plugin 0.5.21 → 0.5.23

package/lib/mobile/extension-catalog.js

@@ -0,0 +1,244 @@
+'use strict';
+
+/**
+ * 已审核扩展清单：随 dsh-mobile-plugin 的 npm 包一起发布的第三方扩展（包内 `extensions/`）。
+ *
+ * 与开发包那条路的分界：开发包读作者电脑上的 `$DSH_HOME/extension-dev`（边写边看），这条读
+ * 插件包自带的只读目录 —— 只有审过、登记进 `extensions/catalog.json` 的包才下发，目录里有但
+ * 没登记的一律当不存在。审核闸门在清单，不在目录。
+ *
+ * 能力面只多「读这一个固定目录」：根由 `__dirname` 定位，不依赖进程 cwd，也不建目录；每个
+ * 文件的 size 与 sha256 由宿主扫目录现算，不信清单里写的数字。取文件先挡绝对路径与 `..` 段，
+ * 再 resolve 之后判前缀（带分隔符），不接受任意路径。仍然不暴露 shell、系统设置、任意文件读写。
+ *
+ * 坏包一律静默跳过：没登记、目录不在、manifest 读不出、超限（20MB / 200 个文件）都不该让整张
+ * 列表变红；catalog.json 不在或坏了就是一份空清单，不抛。取文件那条才逐个回错误码。
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { sendJson } = require('../shared/http-util');
+
+/** 审核清单文件名。只有列进来的 slug 才下发。 */
+const CATALOG_FILE = 'catalog.json';
+/** slug 直接当包目录名，所以只认这套字符；别的名字连读都不读。 */
+const SLUG_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+/** 整包上限：与开发包同一档，太重的包手机也不该整份拉。 */
+const MAX_PACKAGE_BYTES = 20 * 1024 * 1024;
+const MAX_PACKAGE_FILES = 200;
+/** 单个文件上限：一条 base64 响应要塞进手机内存，再大就不该走这条路。 */
+const MAX_FILE_BYTES = 8 * 1024 * 1024;
+
+/** 包内固定目录：从 lib/mobile/ 往上两级就是包根。不依赖 cwd、不建目录（随 npm 包发布）。 */
+function catalogRoot() {
+  return path.join(__dirname, '..', '..', 'extensions');
+}
+
+/** 400 信封：与其余移动端接口同形，App 按 code 翻人话。 */
+function fail(res, status, code, message) {
+  return sendJson(res, status, { ok: false, error: { code, message } });
+}
+
+/** manifest 里取一个非空字符串，缺了 / 类型不对 / 空串都退回默认值。 */
+function textField(value, fallback) {
+  return typeof value === 'string' && value ? value : fallback;
+}
+
+/** 清单里的可选文案：非空字符串才收，其余一律 null。 */
+function textOrNull(value) {
+  return typeof value === 'string' && value.trim() ? value : null;
+}
+
+/** 能力声明收窄成字符串数组：表外的类型与空串丢掉，重复的不给第二份。 */
+function capabilitiesOf(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const item of value) {
+    if (typeof item !== 'string' || !item.trim() || seen.has(item)) continue;
+    seen.add(item);
+    out.push(item);
+  }
+  return out;
+}
+
+function sha256Hex(raw) {
+  return crypto.createHash('sha256').update(raw).digest('hex');
+}
+
+/**
+ * 读审核清单。文件不在、读坏、形状不对都当空清单 —— 空的插件包本来就没有第三方扩展。
+ * 只收 slug / description / author / releaseNotes 四样，其余字段（包括任何 size / sha256）
+ * 一概不认：清单只负责「谁审过了」，文件事实由扫目录算。
+ */
+function readCatalog(root) {
+  let text;
+  try { text = fs.readFileSync(path.join(root, CATALOG_FILE), 'utf8'); } catch { return []; }
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { return []; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Array.isArray(parsed.packages)) return [];
+  const rows = [];
+  const seen = new Set();
+  for (const raw of parsed.packages) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) continue;
+    const slug = typeof raw.slug === 'string' ? raw.slug.trim() : '';
+    if (!SLUG_PATTERN.test(slug) || seen.has(slug)) continue;
+    seen.add(slug);
+    rows.push({
+      slug,
+      description: textOrNull(raw.description),
+      author: textOrNull(raw.author),
+      releaseNotes: textOrNull(raw.releaseNotes),
+    });
+  }
+  return rows;
+}
+
+/**
+ * 递归收集包内的普通文件，`path` 是相对包目录的 POSIX 路径。与 extension-dev.js 同一套口径：
+ * 点开头的文件与目录不看，符号链接不是普通文件，超限当场收手返回 false（先收完再判等于把
+ * 500MB 的目录整个哈希一遍）。
+ */
+function collectFiles(directory, acc) {
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!collectFiles(full, acc)) return false;
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    let raw;
+    try { raw = fs.readFileSync(full); } catch { continue; }
+    acc.bytes += raw.length;
+    acc.files.push({
+      path: path.relative(acc.root, full).split(path.sep).join('/'),
+      size: raw.length,
+      sha256: sha256Hex(raw),
+    });
+    if (acc.bytes > MAX_PACKAGE_BYTES || acc.files.length > MAX_PACKAGE_FILES) return false;
+  }
+  return true;
+}
+
+/**
+ * 扫审核清单，把每个登记过、且目录与 manifest 都在的包读成一份 Package。
+ *
+ * 入口页固定是包目录下那层 `index.html`：App 侧 `extensionEntryPath` 找的就是这个名字，
+ * `manifest.json` 里写 `main` 不生效。所以这里在列包时先确认 `index.html` 真的在文件清单里，
+ * 缺了就把整包跳过 —— 装到手机上再报「需要重新安装」，比根本不出现在清单里难查得多。
+ *
+ * 纯函数、root 由调用方给：守卫拿假目录跑，线上 handler 给包内那个固定目录。
+ */
+function listPackages(root) {
+  const packages = [];
+  for (const entry of readCatalog(root)) {
+    const directory = path.join(root, entry.slug);
+    let stats;
+    try { stats = fs.statSync(directory); } catch { continue; }
+    if (!stats.isDirectory()) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(path.join(directory, 'manifest.json'), 'utf8'));
+    } catch { continue; }
+    if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) continue;
+    const acc = { root: directory, files: [], bytes: 0 };
+    if (!collectFiles(directory, acc) || acc.files.length === 0) continue;
+    if (!acc.files.some((file) => file.path === 'index.html')) continue;
+    packages.push({
+      slug: entry.slug,
+      name: textField(manifest.name, entry.slug),
+      description: entry.description,
+      author: entry.author,
+      versionName: textField(manifest.versionName, textField(manifest.version, '0.0.0')),
+      apiVersion: textField(manifest.apiVersion, textField(manifest.api_version, '1')),
+      releaseNotes: entry.releaseNotes,
+      capabilities: capabilitiesOf(manifest.capabilities),
+      size: acc.bytes,
+      fileCount: acc.files.length,
+      files: acc.files,
+    });
+  }
+  return packages;
+}
+
+/**
+ * GET /api/mobile/v1/extension/catalog（token）
+ *
+ * 回审核过的第三方扩展清单。`root` 只是给守卫传假目录的可选参数，线上由 route() 调用时
+ * 不传，永远走包内那个固定目录。
+ */
+async function handleCatalog(_ctx, _req, res, root = catalogRoot()) {
+  sendJson(res, 200, { ok: true, packages: listPackages(root) });
+}
+
+/**
+ * GET /api/mobile/v1/extension/catalog/file?slug=…&path=…（token）
+ *
+ * 取一个已审核包里的一个文件，回 base64 与 sha256（与列表里那条同一份算法）。审核闸门对取文件
+ * 同样生效：没登记进 catalog.json 的 slug 一律 404，免得绕过清单直接把目录里的字节读走。
+ *
+ * 路径检查两道：先挡明显不该出现的（绝对路径、`..` 段），再 resolve 之后判前缀 —— 后者才是
+ * 判据，前缀比较必须带分隔符，否则 `/x/extensions/foobar` 会被 `/x/extensions/foo` 认成子路径。
+ */
+async function handleCatalogFile(_ctx, req, res, root = catalogRoot()) {
+  const url = new URL(req.url || '/', 'http://x');
+  const slug = (url.searchParams.get('slug') || '').trim();
+  const requested = (url.searchParams.get('path') || '').trim();
+  if (!slug || !requested || !SLUG_PATTERN.test(slug)) {
+    return fail(res, 400, 'bad-request', '需要合法的 slug 与 path（path 是相对包目录的路径）');
+  }
+
+  if (!readCatalog(root).some((entry) => entry.slug === slug)) {
+    return fail(res, 404, 'package-missing', `审核清单里没有 ${slug} 这个包`);
+  }
+  const directory = path.join(root, slug);
+  if (!fs.existsSync(path.join(directory, 'manifest.json'))) {
+    return fail(res, 404, 'package-missing', `${slug} 没有可下发的包（缺 manifest.json）`);
+  }
+
+  if (path.isAbsolute(requested) || requested.split(/[\\/]/).includes('..')) {
+    return fail(res, 400, 'bad-request', 'path 必须是包目录内的相对路径');
+  }
+  const target = path.resolve(directory, requested);
+  if (!target.startsWith(`${directory}${path.sep}`)) {
+    return fail(res, 400, 'bad-request', 'path 必须是包目录内的相对路径');
+  }
+
+  let stats;
+  try { stats = fs.statSync(target); } catch { stats = null; }
+  if (!stats || !stats.isFile()) {
+    return fail(res, 404, 'file-missing', `这个包里没有 ${requested}`);
+  }
+  if (stats.size > MAX_FILE_BYTES) {
+    return fail(res, 413, 'file-too-large', `单个文件上限 ${MAX_FILE_BYTES} 字节，这个超了`);
+  }
+
+  let raw;
+  try { raw = fs.readFileSync(target); } catch {
+    return fail(res, 404, 'file-missing', `这个包里没有 ${requested}`);
+  }
+
+  const relative = path.relative(directory, target).split(path.sep).join('/');
+  sendJson(res, 200, {
+    ok: true,
+    path: relative,
+    size: raw.length,
+    sha256: sha256Hex(raw),
+    content: raw.toString('base64'),
+  });
+}
+
+module.exports = {
+  catalogRoot,
+  listPackages,
+  handleCatalog,
+  handleCatalogFile,
+  MAX_PACKAGE_BYTES,
+  MAX_PACKAGE_FILES,
+  MAX_FILE_BYTES,
+};

package/lib/mobile/live-steps.js

@@ -48,6 +48,8 @@ function turnOf(ctx, sessionId) {
       /** 还没发出去的那几步（`drainLiveSteps` 取走）。 */
       pending: [],
       ended: false,
+      /** 这份副本属于哪一轮（宿主 turn 号）：换轮就整份作废，见 `turnForEvent`。 */
+      turnNo: null,
     };
     bucket.delete(sessionId);
     bucket.set(sessionId, turn);
@@ -57,6 +59,28 @@ function turnOf(ctx, sessionId) {
   return turn;
 }
 
+/**
+ * 把一条事件归到它所属的那一轮；**轮号一变就整份作废**。
+ *
+ * 为什么要靠事件自带的 `data.turn` 兜这一手：`noteLiveEvent` 只在这条流上收到 `turn/start`
+ * 时清桶，可断线重连后那一轮的 `turn/start` 已经在重连之前发生过、被当作「回放已覆盖」丢掉，
+ * 于是新的一轮的步骤会接着上一轮往后长，越积越多、最后全挂在最新那条消息下。每一帧增量
+ * 都带着它属于哪个 turn，用它来判就不会漏：turn 号变了就把整轮副本换掉（下一轮的步骤从空起）。
+ * 同一轮内（turn 号相同）原样沿用。
+ */
+function turnForEvent(ctx, sessionId, data) {
+  const bucket = bucketOf(ctx);
+  const explicitTurn = data && typeof data.turn === 'number' ? data.turn : null;
+  let turn = bucket.get(sessionId);
+  if (turn && explicitTurn !== null && turn.turnNo !== null && turn.turnNo !== explicitTurn) {
+    bucket.delete(sessionId);
+    turn = undefined;
+  }
+  if (!turn) turn = turnOf(ctx, sessionId);
+  if (turn.turnNo === null && explicitTurn !== null) turn.turnNo = explicitTurn;
+  return turn;
+}
+
 /** 把一段文本接到已有的那段后面，超过上限就只留尾巴。 */
 function appendText(prev, next) {
   if (typeof next !== 'string' || next === '') return prev || '';
@@ -160,11 +184,12 @@ function noteLiveEvent(ctx, sessionId, event) {
   if (event.type === 'turn/start') {
     // 新的一轮开始：上一轮的过程副本作废（换掉了，就别再让人点开旧内容）。
     bucketOf(ctx).delete(sessionId);
-    turnOf(ctx, sessionId);
+    const started = turnOf(ctx, sessionId);
+    if (data && typeof data.turn === 'number') started.turnNo = data.turn;
     return;
   }
   if (!data) return;
-  const turn = turnOf(ctx, sessionId);
+  const turn = turnForEvent(ctx, sessionId, data);
   if (event.type === 'assistant/message') {
     // 一步落定：这一步的思考按块序号收尾（后面那一步的块序号从 0 重新数）。
     closeThoughtsOfStep(turn);
@@ -303,6 +328,13 @@ function liveStepsOf(ctx, sessionId) {
   return turn.steps.map((entry) => ({ key: entry.key, step: { ...entry.step } }));
 }
 
+/** 这份直播清单属于哪一轮（宿主 turn 号）——随 `session/live-steps` 帧下发，App 据此按轮隔离。 */
+function liveStepsTurnOf(ctx, sessionId) {
+  if (!ctx || typeof sessionId !== 'string' || !sessionId) return null;
+  const turn = liveStepTurnOf(ctx).get(sessionId);
+  return turn && typeof turn.turnNo === 'number' ? turn.turnNo : null;
+}
+
 /**
  * 取走「还没告诉过手机」的那几步。
  *
@@ -354,4 +386,4 @@ function clearLiveSteps(ctx, sessionId) {
   liveStepTurnOf(ctx).delete(sessionId);
 }
 
-module.exports = { noteLiveEvent, liveStepOf, liveStepsOf, drainLiveSteps, clearLiveSteps };
+module.exports = { noteLiveEvent, liveStepOf, liveStepsOf, liveStepsTurnOf, drainLiveSteps, clearLiveSteps };

package/lib/mobile/local-images.js

@@ -18,6 +18,8 @@
  * 保守取舍——宁可保留字面 markdown，也不给半截东西：
  * - 本机路径认三种：绝对（`/x/y.png`、`file:///x/y.png`）、`~/y.png`、相对（`deliverables/a.png`，
  *   按调用方给的工作区目录解析，与桌面端同口径；没给目录就当成不是本机图）；http(s)、`data:` 不碰；
+ * - 双分隔符打头的网页地址（协议相对 `//host/…`）与 Windows 网络 / 扩展路径（`\\host\…`、`\\?\…`）
+ *   不碰：它们不是本机文件，在 Windows 上会被当成 UNC 去 stat、一读就卡几十秒；
  * - 只认 png/jpg/jpeg/webp/gif，并核对魔术字节，不按扩展名撒谎；
  * - 宽高只读文件头（最多 64KB）；读不出来就不带宽高，App 那边照旧现量；
  * - 围栏代码块与行内代码里的图片语法不碰，那是写法示例。
@@ -44,7 +46,7 @@ const MEDIA_TYPES = {
   '.gif': 'image/gif',
 };
 
-/** 单张图上限：再大的东西不该整包回给手机（超出如实保持字面 markdown）。 */
+/** 单张图上限：再大的东西不该整包回给手机。 */
 const MAX_IMAGE_BYTES = 2.5 * 1024 * 1024;
 /** 读宽高只需要文件头：JPEG 的 SOF 段可能在几百字节之后，64KB 足够覆盖绝大多实拍图。 */
 const HEAD_BYTES = 64 * 1024;
@@ -85,7 +87,9 @@ function localImagePathOf(url, cwd) {
   let value = url.trim();
   if (!value) return null;
   if (value.startsWith('<') && value.endsWith('>')) value = value.slice(1, -1).trim();
-  if (/^[a-z][a-z0-9+.-]*:/i.test(value)) {
+  // 盘符路径（`C:\…`、`C:/…`）不是 URL 协议：单字母后跟分隔符的别当成 scheme 拦掉。
+  const hasUrlScheme = /^[a-z][a-z0-9+.-]*:/i.test(value) && !/^[a-z]:[\\/]/i.test(value);
+  if (hasUrlScheme) {
     if (value.slice(0, 7).toLowerCase() !== 'file://') return null;
     try {
       value = decodeURIComponent(value.slice(7));
@@ -96,6 +100,10 @@ function localImagePathOf(url, cwd) {
   } else if (value === '~' || value.startsWith('~/')) {
     value = path.join(os.homedir(), value.slice(1));
   }
+  // 双分隔符打头的是网页地址（协议相对 `//host/…`）或 Windows 网络 / 扩展路径（`\\host\…`、
+  // `\\?\…`）。它们不是本机文件，在 Windows 上会被当成 UNC 去 stat、一读就卡几十秒；
+  // `file://` 的远程主机经上面剥完也可能落到这里，同样不认。
+  if (/^[\\/]{2}/.test(value)) return null;
   if (!path.isAbsolute(value)) {
     if (!cwd) return null;
     value = path.resolve(cwd, value);
@@ -246,6 +254,10 @@ async function readHead(filePath, size) {
  *
  * 编号取「路径 + 大小 + 修改时间」的短哈希：同一张图在同一轮历史里会被反复解析，
  * 这个组合稳定，且改过之后自然换号（图片内容变了本来就该换）。
+ *
+ * **超过单张上限的图也登记，只是标一句 `tooLarge`**：不登记的话正文里那一段就退回字面
+ * markdown，用户在手机上看到的是一串 `![](路径)` 源码 —— 既不知道发生过什么，也没有任何
+ * 入口。标了之后取图口如实回 413，App 画成「图片太大」的占位块，这才是用户能读懂的一句话。
  */
 async function registerLocalImage(filePath) {
   let stat;
@@ -254,7 +266,7 @@ async function registerLocalImage(filePath) {
   } catch {
     return null;
   }
-  if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_IMAGE_BYTES) return null;
+  if (!stat.isFile() || stat.size <= 0) 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 };
@@ -262,25 +274,161 @@ async function registerLocalImage(filePath) {
   if (!head) return null;
   const mediaType = sniffMediaType(head);
   if (!mediaType) return null;
-  const parsed = imageSizeOf(head);
+  const over = stat.size > MAX_IMAGE_BYTES;
+  const parsed = over ? null : 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 };
+  const entry = { filePath, mediaType, ...size, ...(over ? { tooLarge: true } : {}) };
   registry.set(id, entry);
-  while (registry.size > MAX_REGISTRY_ENTRIES) registry.delete(registry.keys().next().value);
+  trimRegistry();
   return { id, ...entry };
 }
 
+/** 登记表满了就淘汰最老的一条；取回来的临时文件一并删掉，别在地上留垃圾。 */
+function trimRegistry() {
+  while (registry.size > MAX_REGISTRY_ENTRIES) {
+    const oldestId = registry.keys().next().value;
+    const entry = registry.get(oldestId);
+    registry.delete(oldestId);
+    if (entry && entry.fetched && entry.filePath) fs.unlink(entry.filePath).catch(() => {});
+  }
+}
+
 /** 取图口用：只认登记表里的编号（构造不出来的编号一律 null → 404）。 */
 function localImageOf(id) {
   if (typeof id !== 'string' || !id) return null;
   return registry.get(id) || null;
 }
 
-/** 清空登记表（测试用）。 */
+/** 清空登记表（测试用）。取回来的临时文件一并删掉。 */
 function clearLocalImages() {
+  for (const entry of registry.values()) {
+    if (entry && entry.fetched && entry.filePath) fs.unlink(entry.filePath).catch(() => {});
+  }
   registry.clear();
+  loopbackUrlCache.clear();
+}
+
+/**
+ * 回环地址的主机名：出现在正文里时指的是「跑插件这台电脑自己」，手机拿着同一个地址
+ * 只会指回手机自己。生图插件常把成品图挂在自己电脑上的一个小服务上，回的就是这种地址。
+ */
+const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '0.0.0.0', '::1', '::']);
+
+/** 取回回环图片的超时：只在投影一条消息时占这一小会儿，取不到就保持字面 markdown。 */
+const LOOPBACK_FETCH_TIMEOUT_MS = 4000;
+/** 失败后多久内不再重试同一地址：翻历史碰上已经关掉的服务，不该每次都干等一次超时。 */
+const LOOPBACK_FAIL_TTL_MS = 30 * 1000;
+/** 同一地址取到过的图片编号；翻历史时直接复用，不必重复取。 */
+const loopbackUrlCache = new Map();
+
+/**
+ * `![](…)` 里的地址若是**回环地址的 http(s) 图片**，回那条地址；否则 null。
+ *
+ * 只认回环：别的远程地址一律不碰 —— 那会把「本机图片」变成「替手机随便抓任意网址」，
+ * 能力面就从「读这台电脑上的文件」扩成了代理一切出站请求。回环地址连不到外网，
+ * 只是这台电脑自己起的服务，与「读本机文件」同一类。
+ */
+function loopbackImageUrlOf(url) {
+  if (typeof url !== 'string') return null;
+  let value = url.trim();
+  if (!value) return null;
+  if (value.startsWith('<') && value.endsWith('>')) value = value.slice(1, -1).trim();
+  if (!/^https?:\/\//i.test(value)) return null;
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return null;
+  }
+  const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  return LOOPBACK_HOSTNAMES.has(hostname) ? value : null;
+}
+
+/**
+ * 取回的图片字节落成临时文件再登记：取图口按编号读 `filePath`，与磁盘上的图同一条路。
+ *
+ * 编号取内容哈希：同一张图反复出现只落一份。超过单张上限的照样登记、但标 `tooLarge`
+ * （取图口回 413，App 画「图片太大」占位），与磁盘图片那条口径一致。
+ */
+async function registerLocalImageBytes(buffer, mediaType) {
+  if (!buffer || buffer.length === 0) return null;
+  const id = crypto.createHash('sha1').update(buffer).digest('hex').slice(0, 16);
+  const known = registry.get(id);
+  if (known) return { id, ...known };
+  const over = buffer.length > MAX_IMAGE_BYTES;
+  const parsed = over ? null : imageSizeOf(buffer);
+  const sane = parsed && parsed.width > 0 && parsed.height > 0
+    && parsed.width <= 30000 && parsed.height <= 30000;
+  const size = sane ? parsed : {};
+  if (over) {
+    const entry = { filePath: '', mediaType, ...size, tooLarge: true, fetched: true };
+    registry.set(id, entry);
+    trimRegistry();
+    return { id, ...entry };
+  }
+  const ext = mediaType === 'image/jpeg' ? '.jpg'
+    : mediaType === 'image/gif' ? '.gif'
+      : mediaType === 'image/webp' ? '.webp' : '.png';
+  let filePath;
+  try {
+    const dir = path.join(os.tmpdir(), 'dsh-local-images');
+    await fs.mkdir(dir, { recursive: true });
+    filePath = path.join(dir, `${id}${ext}`);
+    await fs.writeFile(filePath, buffer);
+  } catch {
+    return null;
+  }
+  const entry = { filePath, mediaType, ...size, fetched: true };
+  registry.set(id, entry);
+  trimRegistry();
+  return { id, ...entry };
+}
+
+/**
+ * 从回环地址取回一张图片：有超时、有大小上限、必须过魔术字节。
+ *
+ * 取不到 / 不是图 / 太大 / 重定向去别处，一律返回 null，调用方保持字面 markdown ——
+ * 宁可显示成字面文本，也不能让一段历史或一帧 SSE 因为一张图取不到而挂掉（与现有口径一致）。
+ * 只走一次 GET、不跟随重定向：跟去别处就不再是「回环图片」了。
+ */
+async function fetchLoopbackImage(url) {
+  if (typeof fetch !== 'function') return null;
+  const hit = loopbackUrlCache.get(url);
+  if (hit) {
+    if (hit.id && registry.has(hit.id)) return { id: hit.id, ...registry.get(hit.id) };
+    if (!hit.id && hit.failedAt && Date.now() - hit.failedAt < LOOPBACK_FAIL_TTL_MS) return null;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), LOOPBACK_FETCH_TIMEOUT_MS);
+  let buffer;
+  try {
+    const res = await fetch(url, { signal: controller.signal, redirect: 'manual' });
+    if (!res.ok) throw new Error(`http ${res.status}`);
+    const declared = Number(res.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > MAX_IMAGE_BYTES) throw new Error('too large');
+    buffer = Buffer.from(await res.arrayBuffer());
+  } catch {
+    loopbackUrlCache.set(url, { failedAt: Date.now() });
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+  const mediaType = buffer && buffer.length > 0 && buffer.length <= MAX_IMAGE_BYTES
+    ? sniffMediaType(buffer)
+    : null;
+  if (!mediaType) {
+    loopbackUrlCache.set(url, { failedAt: Date.now() });
+    return null;
+  }
+  const entry = await registerLocalImageBytes(buffer, mediaType);
+  if (!entry) {
+    loopbackUrlCache.set(url, { failedAt: Date.now() });
+    return null;
+  }
+  loopbackUrlCache.set(url, { id: entry.id });
+  return entry;
 }
 /**
  * Markdown 里「必须保持字面」的区间：围栏代码块与行内代码。
@@ -377,9 +525,17 @@ async function inlineTextImages(text, budget) {
   let cursor = 0;
   for (const m of matches) {
     if (count <= 0) break;
+    let entry = null;
     const filePath = localImagePathOf(m[2], pool.cwd);
-    if (!filePath) continue;
-    const entry = await registerLocalImage(filePath);
+    if (filePath) {
+      entry = await registerLocalImage(filePath);
+    } else {
+      // 第二种「本机图片」：生图插件把成品图挂在自己电脑的一个回环小服务上，回的是
+      // `http://127.0.0.1:<端口>/…`。手机拿着它只会指回手机自己，所以由电脑去取回来、
+      // 按编号给手机（与磁盘图片同一条路，宽高/缓存/重试全现成）。
+      const loopbackUrl = loopbackImageUrlOf(m[2]);
+      if (loopbackUrl) entry = await fetchLoopbackImage(loopbackUrl);
+    }
     if (!entry) continue;
     count -= 1;
     pool.remaining = count;
@@ -389,82 +545,5 @@ async function inlineTextImages(text, budget) {
   }
   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, localImageOf, registerLocalImage, imageSizeOf, sniffMediaType, clearLocalImages };
+module.exports = { inlineTextImages, createTextImageBudget, localImagePathOf, hasRelativeImage, localImageOf, registerLocalImage, imageSizeOf, sniffMediaType, clearLocalImages, MAX_IMAGE_BYTES };