dsh-mobile-plugin 0.5.17 → 0.5.19

package/lib/mobile/cli/blocks.js

@@ -0,0 +1,228 @@
+'use strict';
+
+/**
+ * ACP 的 `session/update` 事件 → 手机对话页认识的块（`CliBlock`）。
+ *
+ * 这一层就是整个「对话式 CLI」的翻译器，它之所以能这么薄，是因为 ACP 本身就是照着
+ * 「编辑器里的一个对话」设计的：正文、思考、工具调用、计划、审批各是独立事件，不需要
+ * 去猜终端屏幕。
+ *
+ * 两条只在这里成立的口径：
+ *
+ *   - **流式正文按 `messageId` 合并成一条块**。ACP 的 `agent_message_chunk` 是逐段推的，
+ *     同一个 `messageId` 的若干 chunk 属于同一条消息；换成新 `messageId`（或没有 id）才
+ *     另起一条。块的 `id` 直接由它派生成 `a:<messageId>`，所以重连重放与实时增量落到同一处。
+ *   - **不加 `user_message_chunk`**。宿主自己记得用户发过什么（`pushUser`），ACP 那边回显
+ *     的那一份要是也画出来，手机上每条提问都会出现两遍。
+ *
+ * 块只增不改顺序：工具调用按 `callId` 原地更新，计划整表替换（ACP 就是这么定的）。
+ */
+
+let autoSeq = 0;
+
+function nextId(prefix) {
+  autoSeq += 1;
+  return `${prefix}:${Date.now().toString(36)}-${autoSeq.toString(36)}`;
+}
+
+/** ACP 的工具状态四档 → 手机的三档（pending / in_progress 都还是「在跑」）。 */
+function toolState(status) {
+  if (status === 'completed') return 'ok';
+  if (status === 'failed') return 'error';
+  return 'running';
+}
+
+/** 工具内容的正文：ACP 允许文本 / diff / 终端引用三种，手机上只画文本那一种。 */
+function textOfToolContent(content) {
+  if (!Array.isArray(content)) return '';
+  const parts = [];
+  for (const item of content) {
+    if (!item || typeof item !== 'object') continue;
+    if (item.type === 'content' && item.content && item.content.type === 'text' && typeof item.content.text === 'string') {
+      parts.push(item.content.text);
+    } else if (item.type === 'diff' && typeof item.path === 'string') {
+      parts.push(item.path);
+    }
+  }
+  return parts.join('\n');
+}
+
+/**
+ * 工具调用的正文。
+ *
+ * 优先取结构化的 `content`（ACP 里是文本 / diff / 终端引用），没有就退到 `rawOutput`：
+ * codex 那边执行结果只出现在 `rawOutput` 里，`content` 一直是空的 —— 只认前者的话手机上
+ * 每一条工具卡都不带结果。
+ */
+function outputOf(update) {
+  const fromContent = textOfToolContent(update.content);
+  if (fromContent) return fromContent;
+  const raw = update.rawOutput;
+  if (typeof raw === 'string') return clip(raw, 4000);
+  if (raw && typeof raw === 'object') return clip(JSON.stringify(raw), 4000);
+  return '';
+}
+
+function textOfBlock(block) {
+  if (!block || typeof block !== 'object') return '';
+  if (block.type === 'text' && typeof block.text === 'string') return block.text;
+  if (block.type === 'resource_link' && typeof block.uri === 'string') return block.uri;
+  return '';
+}
+
+function clip(value, max) {
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+/**
+ * 一条会话的块表。
+ *
+ * `apply` 只改表并把「变了的块」交出来，广播由服务层做 —— 它才知道该不该攒批。
+ */
+function createBlockLog() {
+  /** 有序块；`index` 存同一批对象的引用，改属性即改表里那一份。 */
+  const blocks = [];
+  const index = new Map();
+
+  function put(block) {
+    blocks.push(block);
+    index.set(block.id, block);
+    return block;
+  }
+
+  function appendText(id, kind, text, at) {
+    const existing = index.get(id);
+    if (!existing) return put({ id, kind, text, at, streaming: true });
+    existing.text += text;
+    existing.streaming = true;
+    return existing;
+  }
+
+  return {
+    /** 只读快照（`hello` 帧用），复制一层免得调用方改了表里的对象。 */
+    list() {
+      return blocks.map((block) => ({ ...block }));
+    },
+
+    size() {
+      return blocks.length;
+    },
+
+    /** 用户发出去的这一条（我们自己的记录，见文件头）。`images` 是已存好的图片元数据。 */
+    pushUser(text, at, images) {
+      return put({
+        id: nextId('u'),
+        kind: 'user',
+        text,
+        at,
+        ...(Array.isArray(images) && images.length ? { images } : {}),
+      });
+    },
+
+    notice(level, text, at) {
+      return put({ id: nextId('n'), kind: 'notice', level, text, at });
+    },
+
+    /** 一轮结束了：把还在流式的正文收口（否则那一行永远带着光标）。 */
+    settle(at) {
+      const changed = [];
+      for (const block of blocks) {
+        if (!block.streaming) continue;
+        block.streaming = false;
+        block.at = at || block.at;
+        changed.push(block);
+      }
+      return changed;
+    },
+
+    /**
+     * 收下一条 `session/update`。
+     *
+     * 返回 `{ block }`（有块变了，广播它）、`{ title }`（只改了标题）、或 `null`（不关心）。
+     */
+    apply(update, at) {
+      if (!update || typeof update !== 'object') return null;
+      const kind = update.sessionUpdate;
+
+      if (kind === 'agent_message_chunk' || kind === 'agent_thought_chunk') {
+        const text = textOfBlock(update.content);
+        if (!text) return null;
+        const isText = kind === 'agent_message_chunk';
+        const id = `${isText ? 't' : 'r'}:${update.messageId || 'main'}`;
+        return { block: appendText(id, isText ? 'text' : 'reasoning', text, at) };
+      }
+
+      if (kind === 'tool_call') {
+        const id = `c:${update.toolCallId}`;
+        const block = {
+          id,
+          kind: 'tool',
+          callId: update.toolCallId,
+          name: typeof update.name === 'string' ? update.name : '',
+          title: typeof update.title === 'string' ? update.title : '',
+          state: toolState(update.status),
+          argsRaw: update.rawInput === undefined ? '' : clip(JSON.stringify(update.rawInput), 2000),
+          output: outputOf(update),
+          at,
+        };
+        const existing = index.get(id);
+        if (!existing) return { block: put(block) };
+        Object.assign(existing, block, { at: existing.at });
+        return { block: existing };
+      }
+
+      if (kind === 'tool_call_update') {
+        const id = `c:${update.toolCallId}`;
+        const existing = index.get(id);
+        if (!existing) return null;
+        if (typeof update.title === 'string' && update.title) existing.title = update.title;
+        if (typeof update.name === 'string' && update.name) existing.name = update.name;
+        if (update.status) existing.state = toolState(update.status);
+        if (update.rawInput !== undefined) existing.argsRaw = clip(JSON.stringify(update.rawInput), 2000);
+        const output = outputOf(update);
+        if (output) existing.output = output;
+        return { block: existing };
+      }
+
+      if (kind === 'plan') {
+        const entries = Array.isArray(update.entries) ? update.entries : [];
+        const steps = entries.map((entry) => ({
+          text: typeof entry.content === 'string' ? entry.content : '',
+          status: typeof entry.status === 'string' ? entry.status : 'pending',
+        }));
+        const existing = index.get('plan');
+        if (existing) {
+          existing.steps = steps;
+          existing.at = at;
+          return { block: existing };
+        }
+        return { block: put({ id: 'plan', kind: 'plan', steps, at }) };
+      }
+
+      if (kind === 'session_info_update') {
+        const title = typeof update.title === 'string' ? update.title.trim() : '';
+        return title ? { title } : null;
+      }
+
+      if (kind === 'notice') {
+        const title = typeof update.title === 'string' ? update.title : '';
+        const detail = typeof update.description === 'string' ? update.description : '';
+        if (!title && !detail) return null;
+        return {
+          block: put({
+            id: nextId('n'),
+            kind: 'notice',
+            level: update.severity === 'error' ? 'error' : 'info',
+            text: detail ? `${title}：${detail}` : title,
+            at,
+          }),
+        };
+      }
+
+      // `usage_update` / `available_commands_update` / 压缩那几档这一版不画。
+      return null;
+    },
+  };
+}
+
+module.exports = { createBlockLog, toolState };

package/lib/mobile/cli/config-prefs.js

@@ -0,0 +1,155 @@
+'use strict';
+
+/**
+ * 「这个 CLI 该按哪一套配置跑」—— 一台电脑每个 CLI 记一份。
+ *
+ * ACP 的配置是**会话级**的：`session/new` 之后才有 `configOptions`，`set_config_option` 只对那一条
+ * 会话生效，每开一条新对话都回到 CLI 默认档。所以这里把用户定的那套按 `agentId` 存下来，新会话
+ * 握手完、第一次发消息之前逐项套过去。只记用户显式选过的项、没选过的不猜；选项表缓存一份供没开
+ * 会话时画，但写入仍按新会话校验；写不进去不算错。文件：`$DSH_HOME/storages/mobile-plugin/cli-config.json`。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const paths = require('../../shared/paths');
+
+function storeFile() {
+  return path.join(paths.dshHome(), 'storages', 'mobile-plugin', 'cli-config.json');
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function load() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(storeFile(), 'utf8'));
+    const agents = raw && typeof raw === 'object' ? raw.agents : null;
+    return agents && typeof agents === 'object' ? agents : {};
+  } catch {
+    return {};
+  }
+}
+
+function save(agents) {
+  try {
+    fs.mkdirSync(path.dirname(storeFile()), { recursive: true });
+    fs.writeFileSync(storeFile(), JSON.stringify({ agents }, null, 0), 'utf8');
+  } catch {
+    // 写不进去只是下次开局回到 CLI 自己的默认，不影响这一条会话。
+  }
+}
+
+/**
+ * 把 ACP 的一项配置压成「够画一个下拉」的形状。
+ *
+ * ACP 的 `options` 有两种：扁平的一项一条，或者按组（`{group, name, options}`）。手机那边
+ * 只认平铺的一行选项，所以这里摊平并保留 `description`（档位说明对「这一档到底放没放开」很
+ * 关键，用户要靠它决定选哪个）。
+ */
+function choicesOf(option) {
+  const raw = Array.isArray(option && option.options) ? option.options : [];
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    if (Array.isArray(item.options)) {
+      for (const child of item.options) {
+        if (child && child.value !== undefined) {
+          out.push({
+            value: String(child.value),
+            name: text(child.name) || String(child.value),
+            ...(text(child.description) ? { description: text(child.description) } : {}),
+            ...(text(item.name) ? { group: text(item.name) } : {}),
+          });
+        }
+      }
+      continue;
+    }
+    if (item.value !== undefined) {
+      out.push({
+        value: String(item.value),
+        name: text(item.name) || String(item.value),
+        ...(text(item.description) ? { description: text(item.description) } : {}),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 会话的整份配置项 → 配置页能直接画的那张表。
+ *
+ * `category` 原样带出去：手机靠它分组（权限档 / 模型 / 思考档位 / 其它），而它是 ACP 定的
+ * 语义分类，不是我们猜的。
+ */
+function describe(configOptions) {
+  const list = Array.isArray(configOptions) ? configOptions : [];
+  const out = [];
+  for (const option of list) {
+    if (!option || typeof option.id !== 'string' || !option.id) continue;
+    const choices = choicesOf(option);
+    if (choices.length === 0) continue;
+    out.push({
+      id: option.id,
+      name: text(option.name) || option.id,
+      ...(text(option.category) ? { category: text(option.category) } : {}),
+      ...(text(option.description) ? { description: text(option.description) } : {}),
+      ...(option.currentValue !== undefined ? { currentValue: String(option.currentValue) } : {}),
+      choices,
+    });
+  }
+  return out;
+}
+
+/** 这个 CLI 记着的那一套：`{ values: {<configId>: <value>}, options: [...] }`。 */
+function prefsOf(agentId) {
+  const entry = load()[text(agentId)];
+  const values = entry && entry.values && typeof entry.values === 'object' ? entry.values : {};
+  const clean = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (key && typeof value === 'string' && value) clean[key] = value;
+  }
+  return { values: clean, options: Array.isArray(entry && entry.options) ? entry.options : [] };
+}
+
+/** 记下「这个 CLI 的某一项该用哪个值」（值空 = 撤掉这一项，回到 CLI 自己的默认）。 */
+function setValue(agentId, configId, value) {
+  const agent = text(agentId);
+  const id = text(configId);
+  if (!agent || !id) return;
+  const agents = load();
+  const entry = agents[agent] && typeof agents[agent] === 'object' ? { ...agents[agent] } : {};
+  const values = entry.values && typeof entry.values === 'object' ? { ...entry.values } : {};
+  const clean = text(value);
+  if (clean) values[id] = clean;
+  else delete values[id];
+  if (Object.keys(values).length) entry.values = values;
+  else delete entry.values;
+  if (entry.values || (Array.isArray(entry.options) && entry.options.length)) agents[agent] = entry;
+  else delete agents[agent];
+  save(agents);
+}
+
+/** 记下这个 CLI 的选项表（配置页在没开会话时也要能画出来）。 */
+function rememberOptions(agentId, configOptions) {
+  const agent = text(agentId);
+  if (!agent) return;
+  const options = describe(configOptions);
+  const agents = load();
+  if (options.length === 0) {
+    // 一家 CLI 本来就不给配置项：把旧表清掉，别让配置页停在上一版 CLI 的样子。
+    const entry = agents[agent];
+    if (!entry || !Array.isArray(entry.options) || entry.options.length === 0) return;
+    const next = { ...entry };
+    delete next.options;
+    if (next.values) agents[agent] = next;
+    else delete agents[agent];
+  } else {
+    const entry = agents[agent] && typeof agents[agent] === 'object' ? { ...agents[agent] } : {};
+    agents[agent] = { ...entry, options };
+  }
+  save(agents);
+}
+
+module.exports = { storeFile, describe, prefsOf, setValue, rememberOptions };

package/lib/mobile/cli/icons.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * CLI 品牌图标：注册表里每条都带一枚官方 SVG（`icon` 字段），这里是它的本地缓存。
+ *
+ * 为什么放插件侧而不写进 App：清单里有二十来家、还在增加，每一家一枚 SVG 写进 App 就是
+ * 每来一家都要发一次版。插件本来就在读那份注册表，顺手把图标存下来，App 只按 id 取。
+ *
+ * 缓存规则与注册表同一套：内存 → 盘上（`$DSH_HOME/storages/mobile-plugin/acp-icons.json`）
+ * → 联网拉。拉不到就空着，App 退回首字母 / 方块 —— 不为此报错。
+ *
+ * **原样留着那份 SVG，只摘掉尺寸与命名空间**：注册表里的图标有的靠 `fill`（Claude、OpenCode），
+ * 有的靠 `stroke`（Agoragentic 那一枚就是圆 + 三条线）。在插件这一层按「只留 path」筛一遍，
+ * 描边那几家会整枚消失；颜色也不在这里定 —— App 侧统一把 `currentColor` 换成主题色（见
+ * `components/CliLogo`），与 `ModelVendorBadge` 同一个规矩。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const paths = require('../../shared/paths');
+
+/** 一次拉取最多等这么久：图标是锦上添花，不该把「列清单」拖住。 */
+const FETCH_TIMEOUT_MS = 6000;
+
+/** 一枚图标在缓存里最多留这么久；注册表按小时更新，图标跟着换。 */
+const TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+let memory = null;
+
+function cacheFile() {
+  return path.join(paths.dshHome(), 'storages', 'mobile-plugin', 'acp-icons.json');
+}
+
+/**
+ * 官方 SVG → App 画得出来的那一份。
+ *
+ * 去掉 `width` / `height` 与 `xmlns`（尺寸由调用方给），`viewBox` 留着 —— 各家的画布不一样
+ * （Claude 是 1200×1200），丢了它图标会被裁掉大半。解析不出 `viewBox` 的按 24×24 处理，
+ * 这是 Simple Icons 的通用画布，也是我们内置那四家的。
+ */
+function normalizeSvg(svg) {
+  if (typeof svg !== 'string' || !svg.trim()) return '';
+  const open = svg.match(/<svg\b[^>]*>/i);
+  if (!open) return '';
+  const viewBox = (open[0].match(/viewBox="([^"]+)"/i) || [])[1] || '0 0 24 24';
+  const inner = svg
+    .slice(open.index + open[0].length)
+    .replace(/<\/svg>\s*$/i, '')
+    .replace(/<(defs|style|title|desc)\b[\s\S]*?<\/\1>/gi, '')
+    .trim();
+  if (!inner) return '';
+  return `<svg viewBox="${viewBox}" xmlns="http://www.w3.org/2000/svg">${inner}</svg>`;
+}
+
+function readCache() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+    const icons = raw && raw.icons && typeof raw.icons === 'object' ? raw.icons : null;
+    if (!icons) return null;
+    return { fetchedAt: Number(raw.fetchedAt) || 0, icons };
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(icons) {
+  try {
+    fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
+    fs.writeFileSync(cacheFile(), JSON.stringify({ fetchedAt: Date.now(), icons }), 'utf8');
+  } catch {
+    // 写不进去只是下次再拉一遍。
+  }
+}
+
+/**
+ * id → SVG 串。
+ *
+ * `entries` 是注册表条目（`{ id, icon }`），`want` 是要哪几个 id（空 = 全都要）。
+ * 只拉还没缓存过的那些，并发拉完；任何一条失败就当它没有图标。
+ */
+async function loadIcons(entries, want) {
+  const targets = (Array.isArray(entries) ? entries : [])
+    .filter((entry) => entry && typeof entry.id === 'string' && typeof entry.icon === 'string' && entry.icon);
+  const naming = new Set(Array.isArray(want) ? want : []);
+  const picked = (list) => {
+    const out = {};
+    for (const id of naming.size ? naming : Object.keys(list)) {
+      if (list[id]) out[id] = list[id];
+    }
+    return out;
+  };
+  if (targets.length === 0) return {};
+
+  const now = Date.now();
+  if (!memory || now - memory.at >= TTL_MS) {
+    const cached = readCache();
+    memory = cached && now - cached.fetchedAt < TTL_MS
+      ? { at: cached.fetchedAt, icons: cached.icons }
+      : { at: 0, icons: (cached && cached.icons) || {} };
+  }
+  const icons = { ...memory.icons };
+  const todo = targets.filter((entry) => (naming.size === 0 || naming.has(entry.id)) && !icons[entry.id]);
+  if (todo.length > 0) {
+    const fetched = await Promise.all(todo.map(async (entry) => {
+      try {
+        const res = await fetch(entry.icon, {
+          // 这台 CDN 不认裸 Node 的默认 UA（会回 403）。
+          headers: { accept: 'image/svg+xml', 'user-agent': 'dsh-mobile' },
+          signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok) return null;
+        const svg = normalizeSvg(await res.text());
+        return svg ? [entry.id, svg] : null;
+      } catch {
+        return null;
+      }
+    }));
+    let changed = false;
+    for (const pair of fetched) {
+      if (!pair) continue;
+      icons[pair[0]] = pair[1];
+      changed = true;
+    }
+    if (changed) {
+      memory = { at: now, icons };
+      writeCache(icons);
+    }
+  }
+  return picked(icons);
+}
+
+/** 测试用：清掉内存那一份。 */
+function resetIconMemory() {
+  memory = null;
+}
+
+module.exports = { loadIcons, normalizeSvg, resetIconMemory, cacheFile };

package/lib/mobile/cli/images.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * CLI 会话里的图片：发出去的那几张，以及手机上回头按 id 来取字节。
+ *
+ * 为什么不能沿用宿主那套附件：宿主的 `attachments/v1` 是会话日志的东西，CLI 会话根本没有
+ * 那份日志。所以图片在插件这边自己存一份 —— 手机发上来时字节已经在盘上（分片上传落在收件箱），
+ * 这里按**内容哈希**把它认下来（同一张图发两次只有一份），历史和实时帧里只下发一个
+ * `attachmentId`，字节等手机真的要看时再取。
+ *
+ * 两条形状与宿主那套逐字对齐（App 的 `useAttachmentUri` / 原生通道只认这两种）：
+ *
+ *   - `{ type:'image', attachment:{ attachmentId, mediaType, name?, width?, height? } }`
+ *     —— 历史和实时帧里的引用；
+ *   - `/session/attachment` 上的三种回法：默认整份 base64、`raw:true` 走分块信封、
+ *     `dims:true` 只要宽高。
+ *
+ * 宽高在存的时候就量好（`imageSizeOf` 读文件头）：不带它的话 App 只能先按 240 方盒占位、
+ * 等解码完再变高，贴底的列表里那一跳就是「内容先停对了又被顶回去」。
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const paths = require('../../shared/paths');
+const { imageSizeOf } = require('../local-images.js');
+
+/** 单张上限：与宿主那侧的附件限制同一个量级（10MB），超了就在发送时回绝。 */
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+/** 只认这四种：App 的图片块本来就只有这几种，别的一律当不支持。 */
+const MEDIA_EXT = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+};
+
+function imageRoot() {
+  return path.join(paths.dshHome(), 'storages', 'mobile-plugin', 'cli-images');
+}
+
+/** 内容哈希当 id（与宿主那套同一个口径：64 位小写十六进制）。 */
+function idOf(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function objectPath(attachmentId) {
+  if (typeof attachmentId !== 'string' || !/^[0-9a-f]{64}$/.test(attachmentId)) return null;
+  return path.join(imageRoot(), attachmentId);
+}
+
+/** 存一份字节 + 一份元数据（媒体类型与名字），回引用块用的那几格。 */
+async function saveImage({ bytes, mediaType, name }) {
+  const type = typeof mediaType === 'string' && MEDIA_EXT[mediaType] ? mediaType : 'image/png';
+  if (!Buffer.isBuffer(bytes) || bytes.length === 0) return null;
+  if (bytes.length > MAX_IMAGE_BYTES) return null;
+  const attachmentId = idOf(bytes);
+  const target = objectPath(attachmentId);
+  const root = imageRoot();
+  await fsp.mkdir(root, { recursive: true });
+  // 同一张图第二次发过来：文件已经在，元数据也够用，别再写一遍。
+  if (!fs.existsSync(target)) await fsp.writeFile(target, bytes);
+  const size = imageSizeOf(bytes);
+  const meta = { mediaType: type, ...(typeof name === 'string' && name ? { name } : {}), ...(size || {}) };
+  try {
+    await fsp.writeFile(`${target}.json`, JSON.stringify(meta), 'utf8');
+  } catch {
+    // 元数据写不进去也不该让这一发失败：媒体类型还能从文件头猜。
+  }
+  return { attachmentId, ...meta };
+}
+
+/** 按 id 取回元数据（不认识 / 不在了回 null）。 */
+function metaOf(attachmentId) {
+  const target = objectPath(attachmentId);
+  if (!target) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(`${target}.json`, 'utf8'));
+    if (!raw || typeof raw !== 'object') return null;
+    return {
+      attachmentId,
+      mediaType: typeof raw.mediaType === 'string' && MEDIA_EXT[raw.mediaType] ? raw.mediaType : 'image/png',
+      ...(typeof raw.name === 'string' && raw.name ? { name: raw.name } : {}),
+      ...(Number.isFinite(raw.width) && Number.isFinite(raw.height) ? { width: raw.width, height: raw.height } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** 按 id 打开字节（返回 `{ path, size }`；不在了回 null）。 */
+function openImage(attachmentId) {
+  const target = objectPath(attachmentId);
+  if (!target) return null;
+  try {
+    const stat = fs.statSync(target);
+    if (!stat.isFile() || stat.size <= 0) return null;
+    return { path: target, size: stat.size, ...(metaOf(attachmentId) || {}) };
+  } catch {
+    return null;
+  }
+}
+
+/** 历史 / 实时帧里的引用块（App 的 `extractImages` 认这一种）。 */
+function imageBlockOf(meta) {
+  if (!meta || typeof meta.attachmentId !== 'string') return null;
+  return {
+    type: 'image',
+    attachment: {
+      attachmentId: meta.attachmentId,
+      mediaType: meta.mediaType,
+      ...(meta.name ? { name: meta.name } : {}),
+      ...(meta.width && meta.height ? { width: meta.width, height: meta.height } : {}),
+    },
+    mediaType: meta.mediaType,
+    ...(meta.name ? { name: meta.name } : {}),
+    ...(meta.width && meta.height ? { width: meta.width, height: meta.height } : {}),
+  };
+}
+
+module.exports = {
+  MAX_IMAGE_BYTES,
+  MEDIA_EXT,
+  imageRoot,
+  saveImage,
+  metaOf,
+  openImage,
+  imageBlockOf,
+};