dsh-mobile-plugin 0.1.92 → 0.1.94

package/lib/mobile/stream.js

@@ -4,7 +4,13 @@
  * dsh-mobile 流式：SSE 转发目标会话的增量事件。
  *
  * 订阅宿主事件流，仅转发目标会话的 session/event 帧（增量事件），
- * 每 15s 发一行注释保持连接；客户端断开即取消订阅。
+ * 每 15s 发一行注释 + 一帧 `session/heartbeat` 数据帧；客户端断开即取消订阅。
+ *
+ * 为什么要那帧心跳：注释行只是保活，客户端一个事件都收不到。而「流被正常收尾」
+ * （中转重启、隧道掉了、宿主自己结束响应）在 App 那边看起来和「这条流还开着」一模一样
+ * —— react-native-sse 在 readyState 走到 DONE 时既不派发 error 也不派发 close。所以
+ * App 需要一个**自己数得到**的活口，两拍没到就主动断开重连（见 app 侧
+ * services/viewmodels/stream-liveness.ts）。这帧不带 seq、不进消息模型、不写缓存。
  *
  * 断线恢复：SSE 客户端重连时携带 `Last-Event-ID: <sessionId>:<seq>`（或查询参数
  * `lastSeq=<seq>`）。服务端先在 history 中回放 `seq > lastSeq` 的事件（收敛状态），
@@ -32,11 +38,30 @@ const approvals = require('./approvals.js');
 const questions = require('./questions.js');
 
 // Android React Native's XHR may buffer tiny chunked responses until its
-// internal progress threshold. Pad each SSE record so onprogress exposes it
-// promptly; the padding is an SSE comment and is ignored by clients.
+// internal progress threshold. Keep each window of records padded past that
+// threshold so onprogress exposes them promptly; the padding is an SSE comment
+// and is ignored by clients.
 const SSE_FLUSH_PADDING_BYTES = 2048;
+/**
+ * 草稿增量的补齐窗口。
+ *
+ * **只对 `assistant/chunk` 生效**：一次流式回复每秒有几十条增量，每条都补 2048 字节
+ * 等于把正文放大十几倍，而这些字节两条腿（宿主→中转、中转→手机）都是实打实要走的。
+ * 按 120ms 一个窗口补齐，界面出字节奏不变（客户端本来就攒够一个阈值才渲染一次）。
+ * 带 seq 的事件、审批卡、排队/任务帧、心跳照旧补满整份 —— 它们慢一拍就是「消息不落地」
+ * 「卡不出现」。实现见 lib/shared/sse-write.js 的 takePadding。
+ */
+const SSE_PAD_MIN_INTERVAL_MS = 120;
 const REPLAY_WINDOW = 3000; // 断线补偿回放的最大事件数
 
+/**
+ * keepalive 节奏，同时也是 `session/heartbeat` 的间隔。
+ *
+ * 必须与 App 的 `STREAM_HEARTBEAT_MS` 一致（`app/src/services/viewmodels/stream-liveness.ts`，
+ * 由 `test/stream-liveness.test.cjs` 的跨仓断言钉着）。
+ */
+const HEARTBEAT_MS = 15_000;
+
 /**
  * 可回答的审批请求帧类型。宿主 apiProxy 的 `requestedFrame()` 发的是 mux 帧
  * `approval/requested`（`rpcId` 在帧级、`approvalId` 在 payload）；会话事件
@@ -61,26 +86,56 @@ function logStream(sessionId, message, error) {
   } catch { /* ignore */ }
 }
 
+/**
+ * 这一帧是不是「流式回复里的草稿增量」——唯一可以按窗口补齐的那一类。
+ *
+ * 判据与丢帧口径同源：没有 seq 的 `assistant/chunk` 是草稿，同一轮收尾的
+ * `assistant/message` 带完整正文、重连回放也能补齐；所以把它按窗口补齐最坏只是慢一拍，
+ * 而其它帧慢一拍就可能表现为「消息不落地」「审批卡不出现」。
+ */
+function isStreamDraft(payload) {
+  if (!payload) return false;
+  // 实时帧写的是内层事件（`{type:'assistant/chunk', data}`），回放路径偶尔仍带一层
+  // `session/event` 外壳，两种形状都认。
+  const type = payload.type === 'session/event' && payload.event ? payload.event.type : payload.type;
+  return type === 'assistant/chunk';
+}
+
 /**
  * 写一条 SSE 记录（策略声明，实现见 `lib/shared/sse-write.js`）。
  *
  * 这条流的策略：软水位只丢**没有 seq** 的增量（`assistant/chunk` 是可丢弃草稿，同一轮
- * 收尾的 `assistant/message` 带完整正文且有 seq，重连回放能补齐）；每条记录补 2048 字节
- * 注释，让 RN 的 XHR 尽快吐出来。
+ * 收尾的 `assistant/message` 带完整正文且有 seq，重连回放能补齐）；草稿增量按 120ms
+ * 一个窗口补到 2048 字节以上，**成批灌入的回放**同样按窗口补齐，其余帧补满整份，
+ * 让 RN 的 XHR 尽快吐出来（见 `SSE_PAD_MIN_INTERVAL_MS`）。
+ *
+ * `options.burst` = 成批灌入（断线回放）。回放是几百到几千条连着写出去的：客户端本来
+ * 就在持续收字节、进度事件照常触发，而逐条补满分摊到一次重连就是几 MB 白字节（实测一次
+ * 903 帧的回放共 2.06MB，其中约 1.85MB 是注释）。窗口机制照样保证「每 120ms 至少一窗
+ * 2048 字节」，而且这条流的**第一条**记录总是落在空窗口上、拿到整份填充，所以「重连后
+ * 界面立刻出内容」不受影响。实时流里那条「带 seq 的帧补满整份」的理由（它可能夹在一串
+ * 慢草稿后面单独到达，慢一拍就是「消息不落地」）在成批灌入里不成立，别把它抄到回放上。
  *
+ * @param {{burst?: boolean}} [options] 成批灌入（回放）标记，见上。
  * @returns {{ok: boolean, shed?: boolean, needDrain?: boolean}}
  *   `ok:false` → 这条流该收尾（客户端走了，或积压超过硬水位）；
  *   `shed:true` → 这条**增量**帧被丢掉、连接还活着；
  *   `needDrain:true` → 写成功了，但底下已经写不动，调用方要先 await 一次 drain 再继续。
  */
-function writeSse(res, payload, frame) {
+function writeSse(res, payload, frame, options = {}) {
+  // 两条路走窗口补齐：可丢弃的草稿增量，与成批灌入的回放（见上面 options.burst）。
+  // 其余帧一律补满整份 —— 带 seq 的事件、审批卡、排队/任务帧、心跳是一次回复里真正
+  // 要落地的东西，宁可多花 2KB 也不让它们卡在客户端的缓冲里等下一次写入。
   return sharedWriteSse(res, payload, {
     frame,
-    padding: ssePadding(SSE_FLUSH_PADDING_BYTES),
+    ...(options.burst === true || isStreamDraft(payload)
+      ? { paddingBytes: SSE_FLUSH_PADDING_BYTES, padEveryMs: SSE_PAD_MIN_INTERVAL_MS }
+      : { padding: ssePadding(SSE_FLUSH_PADDING_BYTES) }),
     // 审批帧没有 seq，按默认口径会在软水位上被丢掉（见上面那条策略）。但它是「人工决策
     // 的入口」不是草稿：丢一张，手机就再也看不到那张卡（软水位只在客户端跟不上时到，
     // 回放也不覆盖这一段）。它一次审批也就一两帧，不是撑爆写队列的那类帧。
-    shedWhenBuffered: (value) => !isApprovalPayload(value) && shedWithoutSeq(value),
+    // 心跳同理必须保住：丢了它，App 会把一条健康的流判成死链（见 isLivenessHeartbeat）。
+    shedWhenBuffered: (value) => !isApprovalPayload(value) && !isLivenessHeartbeat(value) && shedWithoutSeq(value),
   });
 }
 
@@ -94,6 +149,19 @@ function isApprovalPayload(payload) {
     || type === 'question/requested' || type === 'question/resolved';
 }
 
+/**
+ * 这一帧是「App 用来数活口」的心跳，不是聊天内容。
+ *
+ * 它走和正文一样的 writeSse（所以同样受背压闸门管），但**必须**在软水位上被保住：
+ * 心跳被丢掉就等于这条流没说话，App 会在 35s 后把一条完全健康的连接判死并重连 ——
+ * 那是比「丢一张草稿」贵得多的代价。它一帧一百多字节，不是撑爆写队列的那类帧。
+ *
+ * 它不带 seq，所以**绝不能**推进 `lastDeliveredSeq`（那会让回放跳过一个真事件）。
+ */
+function isLivenessHeartbeat(payload) {
+  return Boolean(payload) && payload.type === 'session/heartbeat';
+}
+
 /**
  * 解析断线续传位置：
  *  - `Last-Event-ID: <sessionId>:<seq>`（标准 SSE 头）；
@@ -127,6 +195,13 @@ async function handleStream(ctx, req, res) {
   const url = new URL(req.url, 'http://x');
   const sessionId = url.searchParams.get('sessionId');
   if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });
+  // 子会话地址：App 打开子会话的流时带上父会话与模式（见 app/src/sse.ts 的
+  // openSessionStream 传参）。缺这两个字段就是普通会话，与历史那条同一套判定。
+  const parentSessionId = url.searchParams.get('parentSessionId');
+  const mode = url.searchParams.get('mode');
+  const streamAddress = typeof parentSessionId === 'string' && parentSessionId
+    ? { sessionId, parentSessionId, ...(mode === 'one-shot' || mode === 'continuable' ? { mode } : {}) }
+    : { sessionId };
   try {
     res.writeHead(200, {
       'content-type': 'text/event-stream; charset=utf-8',
@@ -152,8 +227,18 @@ async function handleStream(ctx, req, res) {
       clearInterval(keepAlive);
       ac.abort();
       try { res.end(); } catch { /* ignore */ }
+      return;
+    }
+    // 注释行客户端看不见，所以每一拍再补一帧数据心跳：App 靠「最近真的收到过帧」判断
+    // 这条流还在说话（见 app 侧 services/viewmodels/stream-liveness.ts）。写不出去同样
+    // 说明客户端已经不在，按上面那条路径收尾。
+    if (!writeSse(res, { type: 'session/heartbeat', sessionId, at: Date.now() }).ok) {
+      logStream(sessionId, 'heartbeat write failed', null);
+      clearInterval(keepAlive);
+      ac.abort();
+      try { res.end(); } catch { /* ignore */ }
     }
-  }, 15_000);
+  }, HEARTBEAT_MS);
   // 定时器不该拖住进程退出：宿主/worker 关停时若这条 SSE 还挂着，事件循环会被它按在
   // 15s 一拍上，收尾要等到下一次 tick 才发生（lib/sidecar-facade-worker.cjs 的
   // shutdown 就是这么做的）。测试里的 setInterval 桩没有 unref，所以先判类型。
@@ -180,7 +265,7 @@ async function handleStream(ctx, req, res) {
   try {
     // 断线续传：先回放 history 中 seq > resumeSeq 的事件（收敛状态）。
     if (resumeSeq != null && resumeSeq > 0) {
-      const replay = await replaySince(ctx, sessionId, resumeSeq, res, ac.signal, (seq) => { lastDeliveredSeq = Math.max(lastDeliveredSeq, seq); });
+      const replay = await replaySince(ctx, sessionId, resumeSeq, res, ac.signal, (seq) => { lastDeliveredSeq = Math.max(lastDeliveredSeq, seq); }, streamAddress);
       if (replay.gap && !ac.signal.aborted) {
         const value = { type: 'session/resync-required', sessionId, resumeSeq, oldestSeq: replay.oldestSeq };
         // 旧实现在这里直接 `return`：既不清 keepAlive 也不 end，漏出一条永不收尾的连接。
@@ -192,7 +277,10 @@ async function handleStream(ctx, req, res) {
       // payload 里带 sessionId：0.2.0 的宿主没有设备级事件流了，兼容桥据此收窄成
       // 这一条会话的 follow + 投影 + 任务三条流（见 mobile/host-bridge.js 的 muxFrames）。
       // 不带就是设备级视角，只会给工作区基线与全局投影 —— 这里反正只要单会话。
-      const frames = ctx.apiProxy.events.mux({ rpcId: 'mobile-stream', payload: { sessionId } }, ac.signal);
+      // 子会话必须带上父会话（`parentSessionId` + `mode`）：宿主对 origin==='subagent'
+      // 的会话拿普通地址订阅一律回 agent-busy，表现是「页面打得开、内容不更新」。
+      // 地址的拼装与历史那条同源，见 host-bridge/event-synthesis.js 的 sessionAddress。
+      const frames = ctx.apiProxy.events.mux({ rpcId: 'mobile-stream', payload: streamAddress }, ac.signal);
       // 写一帧并把三种结果统一收口：丢增量、需要等 drain、该收尾。
       // 「需要等 drain」这一步是这次 OOM 的正解 —— 写不动就停手，等底层消化完再继续，
       // 而不是把帧继续往内存里塞。
@@ -214,7 +302,8 @@ async function handleStream(ctx, req, res) {
           const seq = p.event && Number.isFinite(p.event.seq) ? p.event.seq : null;
           // 回放已覆盖该 seq（回放与实时交界处）→ 跳过，避免重复交付。
           if (seq !== null && seq <= lastDeliveredSeq) continue;
-          const event = await resolveEventAttachments(ctx, sessionId, p.event);
+          // 引用模式：图片只下发 attachmentId，不取字节（见 attachments.js）。
+          const event = await resolveEventAttachments(ctx, sessionId, p.event, { referencesOnly: true });
           // 被 shed 的只可能是没有 seq 的增量（见 writeSse 的软水位闸）；它不推进水位，
           // 同一轮收尾的 assistant/message 会把完整正文补上。
           const result = await push(event, { ...frame, payload: { ...p, event } });
@@ -273,9 +362,15 @@ async function handleStream(ctx, req, res) {
  * 从会话 history 回放 seq > sinceSeq 的事件（升序），逐个经附件解析后写 SSE。
  * 通过 onDelivered(seq) 回报已交付的最大 seq，供上层去重。
  */
-async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered) {
+async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, address) {
   try {
-    const { value } = unwrap(await callSessions(ctx, 'history', { sessionId, maxMessages: REPLAY_WINDOW }));
+    // 子会话的重放也要带父会话（同 historyAddress 的口径），否则宿主回 agent-busy，
+    // 这条断线续传静默退化成「后面缺一段」。
+    const { value } = unwrap(await callSessions(ctx, 'history', {
+      sessionId,
+      maxMessages: REPLAY_WINDOW,
+      ...(address && address.parentSessionId ? { parentSessionId: address.parentSessionId, mode: address.mode || 'continuable' } : {}),
+    }));
     const events = (value && Array.isArray(value.events)) ? value.events : [];
     const seqs = events
       .map((entry) => (entry?.event || entry)?.seq)
@@ -293,11 +388,13 @@ async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered) {
     for (const entry of candidates) {
       if (signal.aborted) break;
       const e = entry?.event || entry;
-      const event = await resolveEventAttachments(ctx, sessionId, e);
+      const event = await resolveEventAttachments(ctx, sessionId, e, { referencesOnly: true });
       // Keep replay data identical to live SSE data: the client reducer consumes
       // the event's own type (turn/start, assistant/message, etc.).
       const payload = { type: 'session/event', sessionId, event };
-      const sent = writeSse(res, event, { payload });
+      // 成批灌入：这一节几百条连着写，逐条补满 2048 字节注释等于给一次重连凭空加几 MB
+      // （见 writeSse 的 options.burst）。
+      const sent = writeSse(res, event, { payload }, { burst: true });
       if (!sent.ok) break;
       // 回放是「一次性灌几千条」，最容易把写队列撑爆：写不动就在这里等，别一口气塞完。
       if (sent.needDrain && !(await waitForDrain(res, signal))) break;

package/lib/mobile/uploads.js

@@ -9,13 +9,13 @@
  * 为什么分片，而不是一次 POST 传完：
  *   - 一次传完会把「能传多大的文件」变成一条运维配置 —— 中转的
  *     `MAX_BODY_BYTES`（dsh-mobile-server/lib/config.js）默认 50MB，插件自己的
- *     readJsonBody 默认只有 256KB。分片后单请求只有 1MB，与这些上限无关。
+ *     readJsonBody 默认只有 256KB。分片后单请求最大只有 2MB，与这些上限无关。
  *   - 手机侧网络不稳，分片能只重传坏掉的那一片，而不是整个文件。
  *
  * 为什么片内容走 base64 而不是原始字节：隧道协议本身支持原始字节
  * （lib/relay/protocol.js 的 httpBody 帧），但 App 侧没有任何「发二进制 body」的
  * 先例，RN 的 fetch 对 ArrayBuffer body 的支持也随版本变；图片通道本来就以 base64
- * 走 JSON，这里沿用同一条确定能用的路。代价是 33% 膨胀（单片 1MB → 约 1.37MB），
+ * 走 JSON，这里沿用同一条确定能用的路。代价是 33% 膨胀（单片 2MB → 约 2.73MB），
  * 仍远低于任何一层上限。
  *
  * 顺序与幂等：chunk 只接受「下一片」，重复送达同一片按重传处理（回当前 received，
@@ -32,11 +32,16 @@ const crypto = require('node:crypto');
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
 
-// 片大小 256KB（base64 后约 341KB）：客户端一次请求的硬预算是 8s（`app/src/api/core.ts`
-// 的 REQUEST_TIMEOUT_MS），1MB 片在慢速上行网络上会撞超时；片越小越稳，代价只是多几次往返。
+// 片大小的**起步值** 256KB（base64 后约 341KB）：客户端一次请求的硬预算是 8s
+// （`app/src/api/core.ts` 的 REQUEST_TIMEOUT_MS），一上来就给大片的机器会在慢速上行
+// 网络上撞超时。客户端从这一档起步、按实测周期自己往上爬，爬到 `CHUNK_MAX_BYTES` 为止 ——
+// 局域网里能一路放大，公网上爬两下就停住。所以 begin 回的是「起步值 + 上限」两个数，
+// 不是「就传这么大」。
 const CHUNK_BYTES = 256 * 1024;
-/** 单片请求体上限：1MB base64 后约 1.37MB，留出信封与转义余量。 */
-const CHUNK_MAX_BODY = 4 * 1024 * 1024;
+// 片大小的上限（原始字节）：base64 后约 2.73MB，仍在下面 8MB 的请求体预算内。
+const CHUNK_MAX_BYTES = 2 * 1024 * 1024;
+/** 单片请求体上限：4MB base64 后约 5.33MB，留出信封与转义余量。 */
+const CHUNK_MAX_BODY = 8 * 1024 * 1024;
 /** 文件名上限（按字符算，避开各文件系统的字节上限差异）。 */
 const NAME_MAX_CHARS = 120;
 /** 暂存残片的最长寿命：手机上传中断后没人来 abort 的清理依据。 */
@@ -182,7 +187,8 @@ async function handleUploadBegin(_ctx, req, res) {
   };
   uploads.set(uploadId, job);
   scheduleUploadExpiry(uploadId, job);
-  sendJson(res, 200, { ok: true, uploadId, chunkSize: CHUNK_BYTES });
+  // chunkSize 是起步值、maxChunkSize 是天花板：客户端从前者开始按实测周期往上爬。
+  sendJson(res, 200, { ok: true, uploadId, chunkSize: CHUNK_BYTES, maxChunkSize: CHUNK_MAX_BYTES });
 }
 
 /** POST /api/mobile/v1/upload/chunk { uploadId, index, data } → { ok, received }。 */
@@ -259,4 +265,5 @@ module.exports = {
   inboxRoot,
   sweepExpiredUploads,
   CHUNK_BYTES,
+  CHUNK_MAX_BYTES,
 };

package/lib/mobile/workspaces.js

@@ -15,7 +15,8 @@
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
-const { stableRevision } = require('../shared/list-revision.js');
+const { isFreshRequest } = require('../shared/fresh-request');
+const { stableRevision, unchangedListBody } = require('../shared/list-revision.js');
 // 会话列表缓存归 sessions.js 管。归档/移动会话会改变列表行本身，必须让那边立刻失效，
 // 否则手机端按完「归档会话」，那一行最长 10 秒还留在侧栏里，看着像没归档。
 const { invalidateSessionList } = require('./sessions.js');
@@ -80,8 +81,21 @@ async function buildWorkspacesBody(ctx) {
   };
 }
 
-async function handleWorkspaces(ctx, _req, res) {
-  sendJson(res, 200, await buildWorkspacesBody(ctx));
+/**
+ * GET /api/mobile/v1/workspaces?rev=<上次的 revision>（token）
+ *
+ * 与 `/sessions` 同一条条件刷新契约（形状见 `lib/shared/list-revision.js` 的
+ * `unchangedListBody`）：`rev` 与最终 body 的 revision **恰好相等**时只回一句
+ * `{ok, unchanged:true, revision, generatedAt}`，不带 items。这条路由没有响应缓存，
+ * 所以只判「这份刚构建出来的 body」。
+ * `?fresh=1` 是写后刷新，必须拿到真数据，一律不走这条。
+ */
+async function handleWorkspaces(ctx, req, res) {
+  const url = new URL(req.url, 'http://x');
+  const rev = (url.searchParams.get('rev') || '').trim();
+  const body = await buildWorkspacesBody(ctx);
+  const unchanged = isFreshRequest(req.url) ? null : unchangedListBody(body, rev);
+  sendJson(res, 200, unchanged || body);
 }
 
 /**