dsh-mobile-plugin 0.2.0 → 0.2.2

package/lib/mobile/stream.js

@@ -21,6 +21,14 @@
  * 生命周期：所有失败路径都必须经 logStream 留痕（守卫 test/stream-liveness.test.cjs
  * 逐条钉着字面量），收尾一定给客户端一帧 `session/resync-required`；keepAlive 定时器
  * 要 unref —— 它只是保活，不该把进程退出按在 15s 一拍上。
+ *
+ * 出流量的三个口子（2026-10-25，都在这一层收）：
+ *  - 草稿增量按 200ms 合并成一帧（`DRAFT_FLUSH_MS`）：一帧固定成本两三百字节，而一个
+ *    token 只有十几字节，逐帧发等于按帧收费；
+ *  - 草稿的填充窗口 250ms（`DRAFT_PAD_INTERVAL_MS`）：填充是按时间补的，120ms 就是
+ *    16KB/s 的底线，与正文多少无关；
+ *  - 推理只推每一步的开头 600 字、工具结果只推前 2000 字：运行中用户不读它们，完整内容
+ *    仍在 `assistant/message` 与 `/session/messages` 里，一个字都不丢。
  */
 
 const { sendJson } = require('../shared/http-util');
@@ -34,6 +42,7 @@ const {
   shedWithoutSeq,
 } = require('../shared/sse-write.js');
 const { resolveEventAttachments } = require('./sessions.js');
+const { createTextImageBudget } = require('./local-images.js');
 const { callSessions } = require('./rpc.js');
 const { unwrap } = require('./envelope.js');
 const { normalizeJobs } = require('./jobs.js');
@@ -78,6 +87,49 @@ const REPLAY_MAX_BYTES = 512 * 1024;
  */
 const REPLAY_MAX_GAP = 200;
 
+/**
+ * 草稿增量的合并窗口。
+ *
+ * 这条流的流量有一多半是「每来一个 token 写一帧」的固定成本：一帧正文三十来个字节，线上
+ * 的 SSE 头 + 稳定 id + 加密信封要两三百字节。同一步里同一块的增量可以合并 —— 客户端就是
+ * 按块序号累积、文本按拼接处理，所以攒一小段时间再发一次，内容一个字不少。
+ *
+ * 200ms 是一次渲染周期的一点几倍：再久，正文出字就会一跳一跳；攒到 DRAFT_FLUSH_BYTES
+ * 提前发，避免一次写出去几千字节被 RN 的 XHR 一口吞下。
+ */
+const DRAFT_FLUSH_MS = 200;
+const DRAFT_FLUSH_BYTES = 1024;
+/** 可合并的增量类型：文本与工具参数都是「按块序号累积」的拼接语义。 */
+const MERGEABLE_CHUNK_TYPES = new Set(['text-delta', 'tool-call-delta']);
+
+/**
+ * 草稿填充的窗口（覆盖 `SSE_PAD_MIN_INTERVAL_MS`，只给草稿用）。
+ *
+ * 填充的唯一理由是让安卓 RN 的 XHR 越过进度阈值尽快吐字节；它按窗口补，所以流量等于
+ * 「2048 / 窗口」—— 120ms 就是 16KB/s 的底线，与正文多少无关。合并成 200ms 一帧之后，
+ * 窗口放到 250ms：每帧本身就带一两百字节正文，补到 2048 仍是 4 拍/秒的出字节奏，
+ * 底线降到 8KB/s。
+ */
+const DRAFT_PAD_INTERVAL_MS = 250;
+
+/**
+ * 推理（思考）增量在实时流里只推开头这么多字，之后改推轻量进度帧。
+ *
+ * 运行中那段思考正文用户基本不读（它自己滚、而且长得飞快），却按 token 一帧地发，是
+ * 这条流里帧数最多的一类。完整思考仍然在每一步落定的 `assistant/message` 里跟着来，
+ * 也仍然在 `/session/messages` 的历史里 —— 这里省的只是「逐字推」那一段。
+ */
+const REASONING_LIVE_CHARS = 600;
+
+/**
+ * 工具结果在实时流里最多带这么长的可见输出。
+ *
+ * 工具输出（读文件、跑命令、构建日志）是这条流里单帧最大的一类，几十到几百 KB 很常见，
+ * 而运行中那几秒用户看的是工具卡的状态与一两行摘要；要看全文时走历史那一条
+ * （`/session/messages` 的块与补丁），那里给的是全文。
+ */
+const TOOL_RESULT_LIVE_CHARS = 2000;
+
 /**
  * keepalive 节奏，同时也是 `session/heartbeat` 的间隔。
  *
@@ -152,9 +204,12 @@ function writeSse(res, payload, frame, options = {}) {
   // 要落地的东西，宁可多花 2KB 也不让它们卡在客户端的缓冲里等下一次写入。
   return sharedWriteSse(res, payload, {
     frame,
-    ...(options.burst === true || isStreamDraft(payload)
+    ...(options.burst === true
       ? { paddingBytes: SSE_FLUSH_PADDING_BYTES, padEveryMs: SSE_PAD_MIN_INTERVAL_MS }
-      : { padding: ssePadding(SSE_FLUSH_PADDING_BYTES) }),
+      : isStreamDraft(payload)
+        // 草稿已经按 200ms 合并过，窗口放到 250ms：出字仍是 4 拍/秒，底线从 16KB/s 降到 8KB/s。
+        ? { paddingBytes: SSE_FLUSH_PADDING_BYTES, padEveryMs: DRAFT_PAD_INTERVAL_MS }
+        : { padding: ssePadding(SSE_FLUSH_PADDING_BYTES) }),
     // 审批帧没有 seq，按默认口径会在软水位上被丢掉（见上面那条策略）。但它是「人工决策
     // 的入口」不是草稿：丢一张，手机就再也看不到那张卡（软水位只在客户端跟不上时到，
     // 回放也不覆盖这一段）。它一次审批也就一两帧，不是撑爆写队列的那类帧。
@@ -247,6 +302,184 @@ function createFrameSealer(req) {
   };
 }
 
+/** 工具结果被截断时留在正文末尾的说明（客户端原样显示，不参与解析）。 */
+const TOOL_RESULT_LIVE_ELIDED = '\n…（运行中只推前一段，展开时取全文）';
+
+/** 草稿增量的合并键：同一步、同一块、同一类型才可并。 */
+function chunkKeyOf(event) {
+  const data = event && event.data;
+  const chunk = data && data.chunk;
+  if (!chunk || typeof chunk.index !== 'number') return null;
+  return `${data.turn}:${data.step}:${chunk.index}:${chunk.type}`;
+}
+
+/**
+ * 把后到的增量并进已经攒着的那一帧。
+ *
+ * 只并「客户端按块序号累积」的两类：文本（拼接 `text`）与工具参数（拼接 `argumentsDelta`）。
+ * 其余类型（block-start/end、推理、协议 v2 的其它通知）一律不并 —— 它们带着语义边界，
+ * 合并等于把边界抹掉。
+ */
+function mergeDraft(into, from) {
+  const a = into && into.data && into.data.chunk;
+  const b = from && from.data && from.data.chunk;
+  if (!a || !b || a.type !== b.type) return null;
+  if (a.type === 'text-delta') {
+    if (typeof a.text !== 'string' || typeof b.text !== 'string') return null;
+    return { ...into, time: from.time, data: { ...into.data, chunk: { ...a, text: a.text + b.text } } };
+  }
+  if (a.type === 'tool-call-delta') {
+    const chunk = { ...a };
+    if (typeof b.argumentsDelta === 'string' && b.argumentsDelta) {
+      chunk.argumentsDelta = (typeof a.argumentsDelta === 'string' ? a.argumentsDelta : '') + b.argumentsDelta;
+    }
+    return { ...into, time: from.time, data: { ...into.data, chunk } };
+  }
+  return null;
+}
+
+/**
+ * 草稿缓冲区：把 200ms 内的同类增量并成一帧再写出去。
+ *
+ * 两条必须守住的语义：
+ *  - **顺序**：任何非草稿帧写之前都要 `flushAll()`，否则「攒着的正文」会跑到收尾的
+ *    `assistant/message` 后面，界面先把整段画好、又把草稿补一遍；
+ *  - **不丢**：收尾（正常结束 / 客户端断开 / 硬水位）都要先把攒着的写完，再 res.end。
+ *    合并出来的帧仍然是「可丢的草稿」（没有 seq），软水位照旧能 shed 它。
+ */
+function createDraftBuffer({ push }) {
+  const pending = [];
+  const byKey = new Map();
+  let timer = null;
+  let running = null;
+  let closed = false;
+
+  const bufferedBytes = () => pending.reduce((sum, item) => sum + item.bytes, 0);
+  const stopTimer = () => { if (timer) { clearTimeout(timer); timer = null; } };
+
+  const drain = async () => {
+    stopTimer();
+    while (pending.length && !closed) {
+      const item = pending.shift();
+      if (item.key !== null) byKey.delete(item.key);
+      if (await push(item.event, item.frame) === 'closed') {
+        closed = true;
+        pending.length = 0;
+        byKey.clear();
+      }
+    }
+  };
+
+  const schedule = () => {
+    if (timer || running || !pending.length || closed) return;
+    timer = setTimeout(() => { timer = null; void flush(); }, DRAFT_FLUSH_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+  };
+
+  function flush() {
+    if (running) return running;
+    running = drain().finally(() => {
+      running = null;
+      if (pending.length && !closed) schedule();
+    });
+    return running;
+  }
+
+  /** 把攒着的全部写完（写的过程中新攒进来的也写掉），供「非草稿帧要出去」时调用。 */
+  const flushAll = async () => {
+    while (!closed && (pending.length || running)) await flush();
+  };
+
+  const accept = (event, frame) => {
+    const key = chunkKeyOf(event);
+    const existing = key === null ? null : byKey.get(key);
+    if (existing) {
+      const merged = mergeDraft(existing.event, event);
+      if (merged) {
+        existing.event = merged;
+        existing.frame = frame;
+        existing.bytes = Buffer.byteLength(JSON.stringify(merged), 'utf8');
+        return Promise.resolve();
+      }
+    }
+    const item = { key, event, frame, bytes: Buffer.byteLength(JSON.stringify(event), 'utf8') };
+    pending.push(item);
+    if (key !== null) byKey.set(key, item);
+    if (bufferedBytes() >= DRAFT_FLUSH_BYTES) return flush();
+    schedule();
+    return Promise.resolve();
+  };
+
+  return { accept, flush, flushAll, isClosed: () => closed };
+}
+
+/**
+ * 推理增量的实时截断（见 `REASONING_LIVE_CHARS`）。
+ *
+ * 每一步只推开头那一段，之后整段丢掉 —— 不新增帧类型，也就不动 App：组头那句「正在思考」
+ * 本身一直在闪，用户看到的就是「它还在想」；完整正文在 `assistant/message` 与历史里，
+ * 一个字都不丢。返回 `null` 表示这一帧不写。
+ */
+function createReasoningGate() {
+  const state = { step: null, sent: 0 };
+  return (event) => {
+    const data = event && event.data;
+    const chunk = data && data.chunk;
+    if (!chunk || typeof chunk.index !== 'number' || typeof data.turn !== 'number') return event;
+    const step = `${data.turn}:${data.step}`;
+    if (step !== state.step) {
+      state.step = step;
+      state.sent = 0;
+    }
+    const remaining = REASONING_LIVE_CHARS - state.sent;
+    if (remaining <= 0) return null;
+    if (chunk.text.length <= remaining) {
+      state.sent += chunk.text.length;
+      return event;
+    }
+    const text = chunk.text.slice(0, remaining);
+    state.sent += text.length;
+    return { ...event, data: { ...data, chunk: { ...chunk, text } } };
+  };
+}
+
+/** 实时流里把工具结果的可见输出截到 `TOOL_RESULT_LIVE_CHARS`（两种内容形状都认）。 */
+function trimTextParts(parts, state) {
+  let changed = false;
+  const next = parts.map((part) => {
+    if (!part || typeof part !== 'object') return part;
+    if (Array.isArray(part.content)) {
+      const nested = trimTextParts(part.content, state);
+      if (nested === part.content) return part;
+      changed = true;
+      return { ...part, content: nested };
+    }
+    if (typeof part.text !== 'string' || !part.text) return part;
+    if (state.budget <= 0) {
+      changed = true;
+      return { ...part, text: TOOL_RESULT_LIVE_ELIDED.trimStart() };
+    }
+    if (part.text.length <= state.budget) {
+      state.budget -= part.text.length;
+      return part;
+    }
+    const text = `${part.text.slice(0, state.budget)}${TOOL_RESULT_LIVE_ELIDED}`;
+    state.budget = 0;
+    changed = true;
+    return { ...part, text };
+  });
+  return changed ? next : parts;
+}
+
+function truncateToolResultOutput(event) {
+  const data = event && event.data;
+  const message = data && data.message;
+  if (!message || !Array.isArray(message.content)) return event;
+  const content = trimTextParts(message.content, { budget: TOOL_RESULT_LIVE_CHARS });
+  if (content === message.content) return event;
+  return { ...event, data: { ...data, message: { ...message, content } } };
+}
+
 async function handleStream(ctx, req, res) {
   const url = new URL(req.url, 'http://x');
   const sessionId = url.searchParams.get('sessionId');
@@ -332,6 +565,9 @@ async function handleStream(ctx, req, res) {
   // 后者必须回写，否则客户端会把一次静默断流当成正常状态一直等下去。
   let clientGone = false;
   let loopEnded = false;
+  // 本机路径图片的内联预算：**一条流共用一份**，与历史那一页共用一份同口径。
+  // 此前实时帧是每帧一预算，一条消息里几张截图就能把几百 KB 到几 MB 的 base64 推过去。
+  const imageBudget = createTextImageBudget();
 
   try {
     // **先开实时流、再回放**：之前是先 replay 再 mux，两步之间的 follow 还没订阅，
@@ -347,7 +583,7 @@ async function handleStream(ctx, req, res) {
 
     // 断线续传：回放 history 中 seq > resumeSeq 的事件（收敛状态）。
     if (resumeSeq != null && resumeSeq > 0) {
-      const replay = await replaySince(ctx, sessionId, resumeSeq, res, ac.signal, (seq) => { lastDeliveredSeq = Math.max(lastDeliveredSeq, seq); }, streamAddress, sealFrame);
+      const replay = await replaySince(ctx, sessionId, resumeSeq, res, ac.signal, (seq) => { lastDeliveredSeq = Math.max(lastDeliveredSeq, seq); }, streamAddress, sealFrame, imageBudget);
       if (replay.gap && !ac.signal.aborted) {
         const value = { type: 'session/resync-required', sessionId, resumeSeq, oldestSeq: replay.oldestSeq };
         // 旧实现在这里直接 `return`：既不清 keepAlive 也不 end，漏出一条永不收尾的连接。
@@ -369,6 +605,15 @@ async function handleStream(ctx, req, res) {
         }
         return 'sent';
       };
+      // 草稿合并 + 推理限流 + 整条流共用一份内联图片预算（见上面三组常量与
+      // `createDraftBuffer` / `createReasoningGate` 的注释）。
+      const drafts = createDraftBuffer({ push });
+      const reasoningGate = createReasoningGate();
+      /**
+       * 非草稿帧写之前先把攒着的草稿写出去：草稿是按发生顺序攒的，晚写一步就会变成
+       * 「收尾的 assistant/message 先到、被并过的正文后到」，界面上同一段话画两遍。
+       */
+      const pushOrdered = async (payload, frameArg) => { await drafts.flushAll(); return push(payload, frameArg); };
       for (;;) {
         const step = firstFrame ? await firstFrame : await frameIterator.next();
         firstFrame = null;
@@ -382,34 +627,55 @@ async function handleStream(ctx, req, res) {
           // 回放已覆盖该 seq（回放与实时交界处）→ 跳过，避免重复交付。
           if (seq !== null && seq <= lastDeliveredSeq) continue;
           // 引用模式：图片只下发 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 } });
-          if (result === 'shed') continue;
-          if (result === 'closed') { clientGone = true; break; }
-          if (seq !== null) lastDeliveredSeq = seq;
+          // 预算按**整条流**共享：本机路径的图片内联（local-images.js）此前是每帧一份，
+          // 一条消息里几张截图就能把几百 KB 到几 MB 的 base64 推进去。
+          let event = await resolveEventAttachments(ctx, sessionId, p.event, { referencesOnly: true, budget: imageBudget });
+          if (event.type === 'tool/result') event = truncateToolResultOutput(event);
+          const chunk = event.data && event.data.chunk;
+          if (seq !== null || !chunk || typeof chunk.type !== 'string') {
+            // 持久事件（或不是增量的会话事件）：先把攒着的草稿写掉，再按原样写这一帧。
+            const result = await pushOrdered(event, { ...frame, payload: { ...p, event } });
+            if (result === 'shed') continue;
+            if (result === 'closed') { clientGone = true; break; }
+            if (seq !== null) lastDeliveredSeq = seq;
+          } else if (chunk.type === 'reasoning-delta') {
+            const kept = reasoningGate(event);
+            if (kept === null) continue;
+            await drafts.accept(kept, { ...frame, payload: { ...p, event: kept } });
+            if (drafts.isClosed()) { clientGone = true; break; }
+          } else if (MERGEABLE_CHUNK_TYPES.has(chunk.type)) {
+            // 被 shed 的只可能是没有 seq 的增量（见 writeSse 的软水位闸）；它不推进水位，
+            // 同一轮收尾的 assistant/message 会把完整正文补上。
+            await drafts.accept(event, { ...frame, payload: { ...p, event } });
+            if (drafts.isClosed()) { clientGone = true; break; }
+          } else {
+            // 块边界这类带语义的增量不合并，直接写（但要排在攒着的草稿后面）。
+            if (await pushOrdered(event, { ...frame, payload: { ...p, event } }) === 'closed') { clientGone = true; break; }
+          }
         } else if (p.type === 'session/queue' || p.type === 'session/projection') {
           // 队列/投影整帧转发；不假定存在可重放的宿主 API。
-          const result = await push(p, frame);
+          const result = await pushOrdered(p, frame);
           if (result === 'shed') continue;
           if (result === 'closed') { clientGone = true; break; }
         } else if (p.type === 'session/jobs') {
           // 后台任务整帧（桌面端会话头部任务面板的数据源）。宿主只在任务有变化时发，
           // 且**空数组也要转发** —— 那是「任务都结束了」的唯一信号，丢掉它就永远清不掉。
           const value = { type: 'session/jobs', sessionId, jobs: normalizeJobs(p.jobs) };
-          if (await push(value, frame) === 'closed') { clientGone = true; break; }
+          if (await pushOrdered(value, frame) === 'closed') { clientGone = true; break; }
         } else if (p.type === 'question/requested') {
           // 问题是可回答的 mux server-request，而非 session/event；保留 rpcId 供回答关联。
           const value = { ...p, rpcId: frame.rpcId };
-          if (await push(value, { ...frame, payload: value }) === 'closed') { clientGone = true; break; }
+          if (await pushOrdered(value, { ...frame, payload: value }) === 'closed') { clientGone = true; break; }
         } else if (p.type === 'question/resolved' || p.type === 'approval/requested' || p.type === 'approval/asked' || p.type === 'approval/decided' || p.type === 'approval/resolved') {
           // Approval frames are server requests/resolutions, not session/event frames;
           // forward the rpcId and approval identity so the mobile client can answer safely.
           const value = ANSWERABLE_APPROVAL_TYPES.has(p.type) && frame.rpcId ? { ...p, rpcId: frame.rpcId } : p;
-          if (await push(value, { ...frame, payload: value }) === 'closed') { clientGone = true; break; }
+          if (await pushOrdered(value, { ...frame, payload: value }) === 'closed') { clientGone = true; break; }
         }
       }
+      // 收尾也要把攒着的草稿写完：它们是正常结束前最后那一两百毫秒的正文。
+      await drafts.flushAll();
+      if (drafts.isClosed()) clientGone = true;
       if (!clientGone) loopEnded = true;
     }
   } catch (error) {
@@ -441,7 +707,7 @@ async function handleStream(ctx, req, res) {
  * 从会话 history 回放 seq > sinceSeq 的事件（升序），逐个经附件解析后写 SSE。
  * 通过 onDelivered(seq) 回报已交付的最大 seq，供上层去重。
  */
-async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, address, sealFrame = null) {
+async function replaySince(ctx, sessionId, sinceSeq, res, signal, onDelivered, address, sealFrame = null, imageBudget = null) {
   try {
     // 子会话的重放也要带父会话（同 historyAddress 的口径），否则宿主回 agent-busy，
     // 这条断线续传静默退化成「后面缺一段」。

package/lib/mobile/subagents.js

@@ -26,6 +26,7 @@
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
 const { unwrap } = require('./sessions.js');
+const { promptOnceFor } = require('./session-cache.js');
 
 const SUBAGENT_MAX_ENTRIES = 100;  // 子代理条数上限（正常宿主只有个位数）
 const SUBAGENT_ID_MAX = 200;       // 会话 id 长度上限
@@ -210,9 +211,10 @@ async function handleSubagentPrompt(ctx, req, res) {
   const clientTimeZone = typeof body.clientTimeZone === 'string' && body.clientTimeZone.trim()
     ? body.clientTimeZone.trim()
     : undefined;
+  const clientMessageId = typeof body.clientMessageId === 'string' ? body.clientMessageId.trim() : '';
 
   const controller = new AbortController();
-  const { error } = unwrap(await ctx.apiProxy.subagents.prompt({
+  const call = () => ctx.apiProxy.subagents.prompt({
     rpcId: 'mobile',
     method: 'subagent.prompt',
     payload: {
@@ -222,7 +224,14 @@ async function handleSubagentPrompt(ctx, req, res) {
       content: normalized.blocks,
       ...(clientTimeZone === undefined ? {} : { clientTimeZone }),
     },
-  }, controller.signal));
+  }, controller.signal);
+  // 续话与主会话发送走同一条重试链路（乐观行 + 超时后自动 / 手点重发），所以同样按
+  // `clientMessageId` 去重：没有它，超时的那一发多半已经在子会话里说过了，重试会说第二遍
+  // （口径见 session-cache 的 `promptOnceFor`）。
+  const response = clientMessageId
+    ? await promptOnceFor(ctx, `subagent:${parentSessionId}:${childSessionId}:${clientMessageId}`, call)
+    : await call();
+  const { error } = unwrap(response);
   if (error) return sendJson(res, 400, { ok: false, error });
 
   // 宿主回的是 { messageId }，但手机端自己生成乐观行的 clientMessageId，用不上它。

package/lib/mobile/uploads.js

@@ -281,12 +281,22 @@ async function handleUploadChunk(_ctx, req, res) {
   sendJson(res, 200, { ok: true, received: job.received });
 }
 
-/** POST /api/mobile/v1/upload/finish { uploadId } → { ok, path, name, bytes }。 */
+/** POST /api/mobile/v1/upload/finish { uploadId } → { ok, path, name, bytes }。
+ *
+ * **同一 uploadId 再收一次是回放，不是新上传**：落盘（rename）已经做完、回包却在路上丢了
+ * 的时候，手机那边只能再收一次 —— 那一发必须拿回第一次的那份结果，否则它会把一次成功的
+ * 上传判成失败、让用户白传一遍整个文件。认不出的 uploadId 仍然 404（不能靠「新建一个空
+ * 上传」蒙过去）。
+ */
 async function handleUploadFinish(_ctx, req, res) {
   const body = await readJsonBody(req);
   const uploadId = String((body && body.uploadId) || '');
   const job = uploads.get(uploadId);
-  if (!job) return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
+  if (!job) {
+    const replay = resolveFinishedUpload(uploadId);
+    if (replay) return sendJson(res, 200, { ok: true, ...replay, uploadId });
+    return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
+  }
   removeUpload(uploadId, job);
 
   const dir = path.join(inboxRoot(), today());