dsh-mobile-plugin 0.5.9 → 0.5.10

package/lib/mobile/attachment-store.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * 宿主附件库的直读 —— 手机取图那条路少绕一圈。
+ *
+ * 为什么要有它：手机要一张图时，插件今天只能调宿主的取附件接口，拿回**整份 base64** 再
+ * 解成字节、分块写给手机。那一发要等宿主把整张读出来、编码完才返回，宿主主线程正忙
+ * （比如在派生一条几千条的会话）时，手机那边就是一个字节都没有 —— 2026-10-31 中转日志里
+ * 有 109 次请求整整 15 秒收不到任何字节，全部是这一条路上来的。
+ *
+ * 附件在宿主本机本来就是**按内容哈希分两级目录存的文件**（`<DSH_HOME>/attachments/v1/
+ * objects/<前两位>/<其余>`），插件和宿主同机同进程，直接从盘上流进隧道就行：首字节不等
+ * 宿主做主活，内存里也不再摊一份两兆七的 base64 字符串。
+ *
+ * **只认「我们确实告诉过手机的那几个 id」**（`remember` 在引用下发时记账）。这条不是多余的
+ * 防御：附着在会话里的图片 id 是我们自己下发的，反过来「拿任意一个 64 位十六进制串来读」
+ * 就不该成立 —— 能力面与 `session/file`、`session/local-image` 同一条口径：只读登记过的。
+ * 记账没命中、文件不在、不是加密会话，一律退回原来那条宿主接口，行为与今天完全一致。
+ *
+ * 记账只在内存里：插件重启后手机重连会重新拉一遍消息、重新登记；过期与上限见下面两个常量。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { dshHome } = require('../shared/paths.js');
+const { chunksHeaders, pipeEncrypted } = require('../shared/e2ee-chunks.js');
+
+/** 一个会话最多记多少个附件 id（会话里几千张图也不该无限涨）。 */
+const MAX_IDS_PER_SESSION = 4096;
+/** 最多记多少个会话（滚动淘汰最久没登记的）。 */
+const MAX_SESSIONS = 64;
+/** 记账多久算新鲜：超过这个时间没再被引用过，就当手机手里那份已经过期了。 */
+const TTL_MS = 30 * 60 * 1000;
+
+/** sessionId -> { at, entries: Map<attachmentId, { mediaType, at }> } */
+const SESSIONS = new Map();
+
+/** 内容哈希是 64 位小写十六进制；别的形状一律不认（顺带挡住路径穿越）。 */
+const OBJECT_ID = /^[0-9a-f]{64}$/;
+
+function nowMs() {
+  return Date.now();
+}
+
+/**
+ * 附件 id → 宿主附件库里的绝对路径。
+ *
+ * 形状不对（不是 64 位小写十六进制）直接回 null：这条路径要拼进 `createReadStream`，
+ * 校验放在这里、而不是靠调用方记得先校验。
+ */
+function objectPathOf(attachmentId) {
+  if (typeof attachmentId !== 'string' || !OBJECT_ID.test(attachmentId)) return null;
+  const root = path.join(dshHome(), 'attachments', 'v1', 'objects');
+  return path.join(root, attachmentId.slice(0, 2), attachmentId.slice(2));
+}
+
+/** 记账：这个附件我们刚在 `sessionId` 的消息里下发过（手机接下来就可能来取字节）。 */
+function remember(sessionId, attachmentId, mediaType) {
+  if (typeof sessionId !== 'string' || !sessionId) return;
+  if (typeof attachmentId !== 'string' || !OBJECT_ID.test(attachmentId)) return;
+  const at = nowMs();
+  let slot = SESSIONS.get(sessionId);
+  if (!slot) {
+    slot = { at, entries: new Map() };
+    SESSIONS.set(sessionId, slot);
+    // 会话数到顶：淘汰最久没动静的那一个（Map 保持插入顺序，第一条就是最旧的）。
+    while (SESSIONS.size > MAX_SESSIONS) {
+      const oldest = SESSIONS.keys().next().value;
+      if (oldest === undefined) break;
+      SESSIONS.delete(oldest);
+    }
+  }
+  slot.at = at;
+  slot.entries.delete(attachmentId);
+  slot.entries.set(attachmentId, {
+    at,
+    mediaType: typeof mediaType === 'string' && mediaType ? mediaType : 'application/octet-stream',
+  });
+  while (slot.entries.size > MAX_IDS_PER_SESSION) {
+    const oldest = slot.entries.keys().next().value;
+    if (oldest === undefined) break;
+    slot.entries.delete(oldest);
+  }
+}
+
+/** 这个 id 是不是我们为这条会话下发过的；是就带上当时的媒体类型。 */
+function lookup(sessionId, attachmentId, now = nowMs()) {
+  if (typeof sessionId !== 'string' || !sessionId) return null;
+  if (typeof attachmentId !== 'string' || !attachmentId) return null;
+  const slot = SESSIONS.get(sessionId);
+  if (!slot) return null;
+  if (now - slot.at > TTL_MS) {
+    SESSIONS.delete(sessionId);
+    return null;
+  }
+  const hit = slot.entries.get(attachmentId);
+  if (!hit) return null;
+  if (now - hit.at > TTL_MS) {
+    slot.entries.delete(attachmentId);
+    return null;
+  }
+  return { mediaType: hit.mediaType };
+}
+
+/** 打开一条只读流（调用方自己负责在连接关掉时 destroy）。 */
+function openObject(attachmentId) {
+  const target = objectPathOf(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, stream: fs.createReadStream(target) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 试一次「直接从盘上流给手机」：写成功返回 true，不该走或走不了返回 false。
+ *
+ * 三个前提缺一不可：这条请求带信封（协议 v2 才走分块）、这个 id 是我们为这条会话下发过的、
+ * 对象文件确实还在。任一不满足就交给调用方走原来那条宿主接口 —— 老插件、老会话、明文会话
+ * 的行为因此一个字都不变。
+ */
+async function streamIfRemembered(req, res, sessionId, attachmentId) {
+  const opened = req && req.__dshE2ee;
+  if (!opened || !opened.keys || !opened.req) return false;
+  const known = lookup(sessionId, attachmentId);
+  if (!known) return false;
+  const object = openObject(attachmentId);
+  if (!object) return false;
+  res.writeHead(200, chunksHeaders({
+    'x-dsh-content-type': known.mediaType,
+    'x-dsh-file-size': String(object.size),
+  }));
+  res.on('close', () => object.stream.destroy());
+  await pipeEncrypted(req, res, object.stream);
+  return true;
+}
+
+/** 测试用：清空记账。 */
+function reset() {
+  SESSIONS.clear();
+}
+
+module.exports = {
+  MAX_IDS_PER_SESSION,
+  MAX_SESSIONS,
+  TTL_MS,
+  objectPathOf,
+  remember,
+  lookup,
+  openObject,
+  streamIfRemembered,
+  reset,
+};

package/lib/mobile/attachments.js

@@ -19,6 +19,7 @@ const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const { cwdOf } = require('./session-cwd.js');
 const { inlineTextImages, createTextImageBudget, hasRelativeImage } = require('./local-images.js');
+const attachmentStore = require('./attachment-store.js');
 
 /**
  * 取不到字节的图片块：原样留着，只加一个标记。
@@ -54,7 +55,12 @@ async function resolveEventAttachments(ctx, sessionId, event, opts = {}) {
       const attachmentId = block.attachment.attachmentId;
       if (typeof attachmentId !== 'string' || !attachmentId) return block;
       // 引用模式到此为止：块原样返回，字节由手机端按 attachmentId 单张去取。
-      if (referencesOnly) return block;
+      if (referencesOnly) {
+        // 顺便记一笔：手机接下来就可能拿着这个 id 来取字节。记下来之后那条路可以直接从
+        // 宿主附件库流给它，不必再等宿主把整张图读成 base64（见 attachment-store.js）。
+        attachmentStore.remember(sessionId, attachmentId, block.attachment.mediaType || block.mediaType);
+        return block;
+      }
       let result;
       try {
         result = unwrap(await callSessions(ctx, 'attachment', { sessionId, attachmentId }));

package/lib/mobile/channels.js

@@ -17,6 +17,7 @@
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { unwrap } = require('./envelope.js');
 const { dropSessionModelsForDevice } = require('./session-cache.js');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 
 /** 自建渠道写在这个命名空间里；桌面端 `src/custom-channels.js` 的 PI_AI_NS 同值。 */
 const PI_AI_NS = 'llm-pi-ai';
@@ -280,7 +281,8 @@ async function handleChannels(ctx, req, res) {
     });
   }
 
-  sendJson(res, 200, { ok: true, channels });
+  const body = { ok: true, channels, revision: stableRevision(channels) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 /**

package/lib/mobile/host-settings.js

@@ -12,6 +12,7 @@
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 const { unwrap } = require('./sessions.js');
 
 const HOST_SETTINGS_MAX_NAMESPACES = 60; // 命名空间数量上限（避免异常宿主把响应撑爆）
@@ -245,7 +246,12 @@ async function handleHostSettings(ctx, req, res) {
   });
 }
 
-/** GET /api/mobile/v1/llm/providers —— 宿主的模型提供方名单（只读）。 */
+/**
+ * GET /api/mobile/v1/llm/providers —— 宿主的模型提供方名单（只读）。
+ *
+ * 带 `?rev=` 时按内容指纹走条件响应：名单没变就只回一句 `unchanged`（几十字节），
+ * 不再把整份重传一遍。手机那边把它当设备级目录缓存，进页面先摆上次那份、再拿指纹问一次。
+ */
 async function handleLlmProviders(ctx, req, res) {
   const { value, error } = unwrap(await ctx.apiProxy.llm.providers({
     rpcId: 'mobile',
@@ -257,7 +263,8 @@ async function handleLlmProviders(ctx, req, res) {
   const list = Array.isArray(value && value.providers) ? value.providers : [];
   const providers = list.map(normalizeProvider).filter(Boolean);
 
-  sendJson(res, 200, { ok: true, providers });
+  const body = { ok: true, providers, revision: stableRevision(providers) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 /**
@@ -303,6 +310,9 @@ function normalizeModelGroup(group) {
  *
  * 与 `/llm/providers` 的区别：那条只说「有哪些提供方 / 哪个在生效」，这条给出每个提供方
  * 下面真正可请求的模型 id。手机上没有活动会话时（比如从 Git 页打开选择器）也能拿到。
+ *
+ * 这一份是全仓最大的一份目录响应（每个提供方下面几十上百条模型），而它只在用户加渠道、
+ * 换模型时变，所以同样吃 `?rev=` 的条件响应：没变时几十字节说清，别整份重传。
  */
 async function handleLlmModels(ctx, req, res) {
   const { value, error } = unwrap(await ctx.apiProxy.llm.models({
@@ -314,7 +324,8 @@ async function handleLlmModels(ctx, req, res) {
 
   const list = Array.isArray(value && value.groups) ? value.groups : [];
   const groups = list.map(normalizeModelGroup).filter(Boolean).slice(0, HOST_SETTINGS_MAX_NAMESPACES);
-  sendJson(res, 200, { ok: true, groups });
+  const body = { ok: true, groups, revision: stableRevision(groups) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 const HOST_SETTINGS_MAX_OPS = 40;   // 一次写入的 op 数量上限

package/lib/mobile/local-images.js

@@ -133,6 +133,56 @@ function createTextImageBudget(limit = MAX_TEXT_IMAGES) {
   return { remaining: limit };
 }
 
+/**
+ * JPEG 的 EXIF 朝向（0x0112），没有就返回 0。
+ *
+ * 手机相机竖着拍出来的照片，像素本身是横的，靠 EXIF 里的朝向告诉播放器「先转 90°」。
+ * 宽高只按像素读的话，正文里就会出现「横盒子装竖图」：App 按 `resizeMode="contain"` 画，
+ * 图缩成中间一条、两侧一大片空白（2026-10-31 平板实测）。所以 5–8 这四档要对调宽高。
+ *
+ * 只认 JPEG：PNG / WebP 里带 eXIf 的极少，不值得为它多扫一遍。
+ */
+function jpegOrientation(buf) {
+  let at = 2;
+  while (at + 4 < 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; }
+    // 到扫描数据了，后面不会再有 APP 段。
+    if (marker === 0xda) return 0;
+    const length = buf.readUInt16BE(at + 2);
+    if (length < 2) return 0;
+    if (marker === 0xe1 && at + 10 <= buf.length && buf.toString('latin1', at + 4, at + 10) === 'Exif\0\0') {
+      return tiffOrientation(buf, at + 10);
+    }
+    at += 2 + length;
+  }
+  return 0;
+}
+
+/** EXIF 里的 TIFF 头 → 朝向值；字节序按 `II` / `MM` 判，读不到返回 0。 */
+function tiffOrientation(buf, base) {
+  if (base + 8 > buf.length) return 0;
+  const order = buf.toString('latin1', base, base + 2);
+  if (order !== 'II' && order !== 'MM') return 0;
+  const little = order === 'II';
+  const u16 = (at) => (little ? buf.readUInt16LE(at) : buf.readUInt16BE(at));
+  const u32 = (at) => (little ? buf.readUInt32LE(at) : buf.readUInt32BE(at));
+  if (u16(base + 2) !== 42) return 0;
+  const ifd = base + u32(base + 4);
+  if (ifd + 2 > buf.length) return 0;
+  const count = u16(ifd);
+  for (let i = 0; i < count; i += 1) {
+    const entry = ifd + 2 + i * 12;
+    if (entry + 12 > buf.length) return 0;
+    if (u16(entry) === 0x0112) {
+      const value = u16(entry + 8);
+      return value >= 1 && value <= 8 ? value : 0;
+    }
+  }
+  return 0;
+}
+
 /** 从文件头解析宽高；认不出来返回 null（不是错误：App 那边照旧现量）。 */
 function imageSizeOf(buf) {
   if (buf.length >= 24 && buf[0] === 0x89 && buf.toString('latin1', 1, 4) === 'PNG') {
@@ -152,6 +202,10 @@ function imageSizeOf(buf) {
     return null;
   }
   if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+    // 竖拍照片的像素本身是横的，朝向 5–8 时播放器会转 90° 再画 —— 宽高必须跟着对调，
+    // 否则正文那个盒子是横的、图是竖的（见 jpegOrientation）。
+    const orientation = jpegOrientation(buf);
+    const swap = orientation >= 5 && orientation <= 8;
     let at = 2;
     while (at + 9 < buf.length) {
       if (buf[at] !== 0xff) { at += 1; continue; }
@@ -159,7 +213,9 @@ function imageSizeOf(buf) {
       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) };
+        const width = buf.readUInt16BE(at + 7);
+        const height = buf.readUInt16BE(at + 5);
+        return swap ? { width: height, height: width } : { width, height };
       }
       if (length < 2) return null;
       at += 2 + length;

package/lib/mobile/plugins.js

@@ -14,6 +14,7 @@
  */
 
 const { sendJson } = require('../shared/http-util');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 const { invoke, UNAVAILABLE: GATEWAY_UNAVAILABLE } = require('./host-bridge/transport.js');
 
 const PLUGIN_ID_MAX_CHARS = 200;      // entryId 长度上限
@@ -96,7 +97,10 @@ function statusOf(error) {
 
 /**
  * GET /api/mobile/v1/plugins
- * 成功：{ ok:true, items:[{ entryId, moduleName, enabled, fiberPhase }] }
+ * 成功：{ ok:true, items:[{ entryId, moduleName, enabled, fiberPhase }], revision }
+ *
+ * 带 `?rev=` 时走条件响应：清单没变就只回一句 `unchanged`。插件清单只在装 / 卸 / 启停 /
+ * 重启之后变，而手机每进一次「插件清单」页都要读它一遍。
  */
 async function handlePlugins(ctx, req, res) {
   const result = await callInventory(ctx);
@@ -109,7 +113,8 @@ async function handlePlugins(ctx, req, res) {
     items.push(entry);
     if (items.length >= PLUGIN_MAX_ITEMS) break;
   }
-  sendJson(res, 200, { ok: true, items });
+  const body = { ok: true, items, revision: stableRevision(items) };
+  sendJson(res, 200, unchangedListBody(body, revisionOf(req)) || body);
 }
 
 module.exports = {

package/lib/mobile/session-presets.js

@@ -9,6 +9,7 @@
  */
 
 const { sendJson } = require('../shared/http-util');
+const { unchangedListBody, revisionOf, stableRevision } = require('../shared/list-revision.js');
 const { unwrap } = require('./envelope.js');
 const { callAgentPresets } = require('./rpc.js');
 
@@ -39,14 +40,17 @@ async function handleAgentPresets(ctx, req, res) {
       ...(item.broken === true ? { broken: true } : {}),
     });
   }
-  sendJson(res, 200, {
+  const body = {
     ok: true,
     presets,
     // 与条目内的 isDefault / broken 同口径：宿主只该给布尔，非布尔一律当 false，
     // 不让 'yes' / 1 这种值被 App 当成「可以自己写预设」。
     authorable: value != null && value.authorable === true,
     hasDocument: value != null && value.hasDocument === true,
-  });
+  };
+  // 指纹只看内容：`authorable` / `hasDocument` 变了也算变，它们是同一页上的两格状态。
+  const withRevision = { ...body, revision: stableRevision(body) };
+  sendJson(res, 200, unchangedListBody(withRevision, revisionOf(req)) || withRevision);
 }
 
 module.exports = { handleAgentPresets };

package/lib/mobile/session-send.js

@@ -28,6 +28,7 @@ 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');
+const attachmentStore = require('./attachment-store.js');
 
 /**
  * `/send` 的请求体上限（**明文**字节，图片 base64）。
@@ -281,6 +282,10 @@ async function handleSessionAttachment(ctx, req, res) {
     || typeof body.attachmentId !== 'string' || !body.attachmentId) {
     return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, attachmentId }' } });
   }
+  // 直读宿主附件库（2026-10-31）：登记过的 id 直接从本地盘流给手机，省掉「等宿主把整张
+  // 读成 base64 再返回」那一段（宿主主线程忙时手机会一个字节都收不到）。前提与回退见
+  // `attachment-store.js` 的 `streamIfRemembered`：不满足就往下走原来的宿主接口。
+  if (body.raw === true && await attachmentStore.streamIfRemembered(req, res, body.sessionId, body.attachmentId)) return;
   const { value, error } = unwrap(await callSessions(ctx, 'attachment', { sessionId: body.sessionId, attachmentId: body.attachmentId }));
   if (error) return sendJson(res, 400, { ok: false, error });
   const data = value && typeof value.data === 'string' ? value.data : '';

package/lib/mobile/stream.js

@@ -29,6 +29,7 @@ const {
   waitForDrain,
   ssePadding,
   shedWithoutSeq,
+  flushFrameBatch,
 } = require('../shared/sse-write.js');
 const { resolveEventAttachments } = require('./sessions.js');
 const { createTextImageBudget } = require('./local-images.js');
@@ -197,6 +198,7 @@ function writeSse(res, payload, frame, options = {}) {
     // 协议 v2：每帧一条独立密文（§8.3(5)）。封装器由开流那一处给 —— 它才知道这条流的
     // 请求 ts / nonce 与帧序号（AAD 要绑这三样）。
     sealFrame: typeof options.sealFrame === 'function' ? options.sealFrame : null,
+    batch: res.__dshFrameBatch === true,
   });
 }
 
@@ -392,6 +394,9 @@ async function handleStream(ctx, req, res) {
   if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
   // 子会话地址：App 打开子会话的流时带上父会话与模式（见 app/src/sse.ts 的
   // openSessionStream 传参）。缺这两个字段就是普通会话，与历史那条同一套判定。
+  // 合帧：只有 App 在流地址上带 `frameBatch=1` 才启用（老 App 不带，行为一字不变）。
+  // 合帧把一串 `assistant/chunk` 并成一帧，省掉逐帧的加密、写套接字与客户端逐帧解析。
+  const frameBatch = url.searchParams.get('frameBatch') === '1';
   const parentSessionId = url.searchParams.get('parentSessionId');
   const mode = url.searchParams.get('mode');
   const streamAddress = typeof parentSessionId === 'string' && parentSessionId
@@ -401,6 +406,8 @@ async function handleStream(ctx, req, res) {
   // **要在 writeHead 之前算**：`X-Dsh-Proto: 2` 只能在头发出去之前声明，写过头再
   // `setHeader` 是无效的（Node 会静默忽略），客户端就永远不知道帧是信封。
   const sealFrame = createFrameSealer(req);
+  // 这条连接要不要合帧：`writeSse` 是文件级函数，挂在响应对象上比穿一串参数稳。
+  if (frameBatch) res.__dshFrameBatch = true;
   const head = {
     'content-type': 'text/event-stream; charset=utf-8',
     'cache-control': 'no-cache',
@@ -628,6 +635,9 @@ async function handleStream(ctx, req, res) {
       // 明确告诉客户端「流到此为止，请带 lastSeq 重连」：它会走已验证可用的 replay
       // 路径补上缺口，而不是把静默断流当成正常状态。
       if (!ac.signal.aborted && !clientGone) {
+        // 收尾帧之前先把攒着的增量放出去：resync-required 自己会触发 flush，这一行是为了
+        // 客户端已经走了那条分支不至于把最后几帧留在缓冲里。
+        flushFrameBatch(res);
         writeSse(res, { type: 'session/resync-required', sessionId, oldestSeq: lastDeliveredSeq + 1, final: true }, null, { sealFrame });
       }
       res.end();

package/lib/shared/list-revision.js

@@ -58,4 +58,22 @@ function unchangedListBody(body, rev) {
   return { ok: true, unchanged: true, revision: body.revision, generatedAt: body.generatedAt };
 }
 
-module.exports = { stableRevision, listRevision, unchangedListBody };
+/**
+ * 请求串里的 `?rev=`（条件刷新的客户端指纹）；没有、为空或解析不出来都返回空串。
+ *
+ * 空串在 `unchangedListBody` 那里是「照常回整份」，所以老 App 不带这个参数时行为不变。
+ * 路径匹配发生在宿主那一侧、早就忽略了查询串，这里只负责取值。
+ *
+ * @param {{ url?: string }} req
+ */
+function revisionOf(req) {
+  const raw = req && typeof req.url === 'string' ? req.url : '';
+  if (!raw) return '';
+  try {
+    return (new URL(raw, 'http://x').searchParams.get('rev') || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+module.exports = { stableRevision, listRevision, unchangedListBody, revisionOf };

package/lib/shared/sse-write.js

@@ -136,6 +136,53 @@ function takePadding(res, written, padBytes, padEveryMs) {
   return padding;
 }
 
+/**
+ * 合帧：把短时间内到达的多条草稿增量并成一帧发。
+ *
+ * 为什么要它：流式回复一秒几十条 `assistant/chunk`，一帧一条就是几十次「加密 + 写套接字 +
+ * 客户端逐帧解密与解析」。并成一帧之后这几步按批走，客户端那边只需要认出 `type:'batch'`。
+ *
+ * 只有客户端在流地址上带 `frameBatch=1` 时才启用（老 App 行为一个字不变）。只并
+ * `assistant/chunk` —— 心跳、审批、排队/任务、`resync-required` 这些帧没有「晚 40ms 无所谓」
+ * 的余地，它们必须立刻发，且发之前先把已攒的增量按原顺序放出去。
+ */
+const BATCH_WINDOW_MS = 40;
+const BATCH_MAX_EVENTS = 8;
+const BATCHABLE_TYPES = new Set(['assistant/chunk']);
+/** 一条连接一份攒批状态；连接收掉后随 res 一起被回收。 */
+const BATCH_STATES = new WeakMap();
+
+/** 这一帧能不能进合帧（看内层事件类型；回放路径可能带一层 `session/event` 外壳）。 */
+function isBatchablePayload(payload) {
+  if (!payload || typeof payload !== 'object') return false;
+  const inner = payload.type === 'session/event' && payload.event ? payload.event : payload;
+  return BATCHABLE_TYPES.has(inner.type);
+}
+
+function batchStateOf(res) {
+  let state = BATCH_STATES.get(res);
+  if (!state) {
+    state = { items: [], timer: null, options: null };
+    BATCH_STATES.set(res, state);
+  }
+  return state;
+}
+
+/** 把攒下的增量立刻发成一条 `batch` 帧（幂等：没东西就直接成功）。 */
+function flushFrameBatch(res) {
+  const state = BATCH_STATES.get(res);
+  if (!state) return { ok: true };
+  if (state.timer) {
+    clearTimeout(state.timer);
+    state.timer = null;
+  }
+  if (state.items.length === 0) return { ok: true };
+  const events = state.items.splice(0);
+  const options = state.options || {};
+  // 合帧只做一次：`{batch:false}` 保证不会再被攒回去。
+  return writeSse(res, { type: 'batch', events }, { ...options, batch: false });
+}
+
 /**
  * 写一条 SSE 记录。
  *
@@ -170,7 +217,29 @@ function writeSse(res, payload, options = {}) {
      * 字段，客户端要靠 `id:` 回填 `Last-Event-ID`，而 `id:` 里的 sessionId 本来就在 URL 上。
      */
     sealFrame = null,
+    /**
+     * 这条连接要不要合帧（客户端在流地址上带 `frameBatch=1` 才给真）。
+     * 见 `flushFrameBatch` / `BATCHABLE_TYPES`。
+     */
+    batch = false,
   } = options;
+  if (batch) {
+    const state = batchStateOf(res);
+    state.options = options;
+    if (!isBatchablePayload(payload)) {
+      // 控制帧 / 心跳 / 收尾：先把攒着的增量按原顺序发完，自己再立刻发。
+      const flushed = flushFrameBatch(res);
+      if (!flushed.ok) return flushed;
+    } else {
+      state.items.push(payload);
+      if (state.items.length >= BATCH_MAX_EVENTS) return flushFrameBatch(res);
+      if (!state.timer) {
+        state.timer = setTimeout(() => { state.timer = null; flushFrameBatch(res); }, BATCH_WINDOW_MS);
+        if (typeof state.timer.unref === 'function') state.timer.unref();
+      }
+      return { ok: true, deferred: true };
+    }
+  }
   const buffered = bufferedBytesOf(res);
   if (buffered > SSE_CLOSE_BUFFERED_BYTES) return { ok: false };
   if (buffered > SSE_SHED_BUFFERED_BYTES && shedWhenBuffered(payload)) return { ok: true, shed: true };  const id = stableEventId(payload, frame, namespace);
@@ -229,6 +298,10 @@ module.exports = {
   bufferedBytesOf,
   stableEventId,
   writeSse,
+  flushFrameBatch,
+  isBatchablePayload,
+  BATCH_WINDOW_MS,
+  BATCH_MAX_EVENTS,
   waitForDrain,
   shedWithoutSeq,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mobile-plugin",
-  "version": "0.5.9",
+  "version": "0.5.10",
   "description": "Mobile API (/api/mobile/v1) and relay client for the DSH mobile app — desktop profile build (dsh 0.2.x, peers resolved by the host)",
   "license": "MIT",
   "icon": "./icon.png",