dsh-mobile-plugin 0.1.75 → 0.1.77

package/README.md

@@ -4,6 +4,12 @@
 
 AI-HUB 手机端插件，为 DSH 提供移动 API、远程连接和局域网代理。插件也可作为无头 Cordis Host 独立运行，不依赖桌面外壳或 Electron。
 
+## 下载 AI-HUB 手机 App
+
+- [Android APK](https://app.wnluo.com/public/apps/14)
+- [App Store](https://apps.apple.com/us/app/ai-hub/id6821681438)（若暂时无法打开，可能是 App 仍在等待苹果审核通过。）
+- [TestFlight 测试版](https://testflight.apple.com/join/4fn5PCMD)
+
 ## 功能
 
 - 通过 relay v2 隧道连接手机 App，并支持局域网代理。

package/lib/mobile/attachments.js

@@ -30,6 +30,19 @@ const { inlineTextImages, createTextImageBudget } = require('./local-images.js')
  * (see local-images.js); `opts.budget` is a shared per-response budget so one
  * paged history response or mirror snapshot stays bounded.
  */
+/**
+ * 取不到字节的图片块：原样留着，只加一个标记。
+ *
+ * 这里**绝不能抛，也绝不能返回 null**：resolveBlock 的结果会直接摊进整段历史响应或
+ * 一整帧 SSE，一个 null/异常会让整页消息一起挂掉（见 dev-map A3-33 的刻意设计）。
+ * 加标记是因为「附件取不到」和「这条消息本来就没有这张图」在 App 侧长得一样（都只有
+ * attachment 没有 data），不加标记就只能跟着静默消失——用户既不知道有过一张图，
+ * 也没有任何重试入口。
+ */
+function dataUnavailableBlock(block) {
+  return { ...block, dataUnavailable: true };
+}
+
 async function resolveEventAttachments(ctx, sessionId, event, opts = {}) {
   if (!event || !event.data || typeof event.data !== 'object') return event;
   const data = event.data;
@@ -50,9 +63,9 @@ async function resolveEventAttachments(ctx, sessionId, event, opts = {}) {
       try {
         result = unwrap(await callSessions(ctx, 'attachment', { sessionId, attachmentId }));
       } catch {
-        return block;
+        return dataUnavailableBlock(block);
       }
-      if (result.error || !result.value || typeof result.value.data !== 'string') return block;
+      if (result.error || !result.value || typeof result.value.data !== 'string') return dataUnavailableBlock(block);
       const attachment = result.value.attachment || block.attachment;
       return {
         type: 'image',

package/lib/mobile/history-derive.js

@@ -198,26 +198,6 @@ function retryFailure(failure) {
   return out.code !== undefined || out.message !== undefined ? out : null;
 }
 
-/** 上下文行的 label 提取（与桌面 contextProvenance 同口径；取不到为 null）。 */
-function contextLabelOf(source) {
-  const kind = source.kind;
-  if (kind === 'session-reference') {
-    for (const ref of Array.isArray(source.references) ? source.references : []) {
-      if (ref && typeof ref.label === 'string' && ref.label) return ref.label;
-    }
-    return null;
-  }
-  if (kind === 'agent-instructions') {
-    for (const change of Array.isArray(source.changes) ? source.changes : []) {
-      if (change && typeof change.path === 'string' && change.path) return change.path;
-    }
-    return null;
-  }
-  if (kind === 'plugin') return typeof source.plugin === 'string' && source.plugin ? source.plugin : null;
-  if (kind === 'skill-invocation') return typeof source.name === 'string' && source.name ? source.name : null;
-  return typeof kind === 'string' ? kind : null;
-}
-
 /** 列表/概览的 lastMessage 预览只取有 role 的消息项（结构化行不参与预览）。 */
 function lastMessageOf(messages) {
   for (let i = messages.length - 1; i >= 0; i--) {
@@ -234,7 +214,6 @@ function lastMessageOf(messages) {
  *    渲染成 compaction 行（id=compactionId，state='done'），并用同 compactionId 的 compaction/summary 补 counts；
  *  - retry：{ kind:'retry', id: retryId, seq, time, status:'scheduled'|'started', retry, maxRetries, delayMs?, failure? }；
  *  - turn-error / max-tokens：{ kind:'turn-error', id:'turn-<turn>', message, code? } / { kind:'max-tokens', id:'turn-<turn>' }；
- *  - context：{ kind:'context', id:'ctx-<msgId>', contextRole:'inject'|'recall', contextLabel, text }；
  *  - command：{ kind:'command', id:commandId, name, status:'running'|'done', resultKind?, text? }
  *    （command/run 发出行，command/done 原地升级：name 保 run 的，resultKind/text 取 done 的）。
  * 结构化项与消息按事件 seq 升序混排返回；旧载荷字段缺失时跳过对应项，绝不抛错。
@@ -388,18 +367,8 @@ function deriveMessages(events) {
         continue;
       }
       if (src && typeof src === 'object' && src.kind !== 'user') {
-        // 上下文注入/召回（session-reference→召回，其余 kind→注入）；无文本或无可唯一 id 则跳过该项。
-        const text = blocksToText(parseBlocks(msg.content));
-        if (text === '' || msg.id == null) continue;
-        out.push({
-          id: `ctx-${String(msg.id)}`,
-          kind: 'context',
-          contextRole: src.kind === 'session-reference' ? 'recall' : 'inject',
-          contextLabel: contextLabelOf(src),
-          text,
-          seq,
-          time,
-        });
+        // 上下文注入/召回（session-reference→召回，其余 kind→注入）：桌面 `isVisibleChatNode`
+        // 只放行携带 tool-addition/tool-removal 的上下文节点，这类提示一律不显示 —— 不下发。
         continue;
       }
       // 普通用户消息（source 缺失或 kind==='user'）沿用原折叠。
@@ -601,7 +570,6 @@ module.exports = {
   buildToolResultMap,
   parseBlocks,
   blocksToText,
-  contextLabelOf,
   lastMessageOf,
   MOBILE_PROMPT_RPC_PREFIX,
   clientMessageIdFromSource,

package/lib/mobile/host-bridge/event-synthesis.js

@@ -30,15 +30,55 @@ async function* tolerate(frames, what, ctx) {
   }
 }
 
-/** 单会话事件流：follow 的 live 事件（跳过 snapshot，历史走 session.history）。 */
-async function* sessionEventFrames(ctx, sessionId, signal) {
-  const frames = await openStream(ctx, 'session', 'follow', {
-    request: { address: { kind: 'session', sessionId }, maxMessages: 1 },
-  }, signal);
-  for await (const frame of tolerate(frames, `session/${sessionId}`, ctx)) {
-    if (!frame || frame.type !== 'event' || !frame.event) continue;
+/**
+ * follow 流的一帧 → 0..n 个 mux 帧（事件原样转发；实时增量通知合成 assistant/chunk）。
+ *
+ * 0.2.0 的宿主把逐块流式增量从「会话事件」里拿了出去：正文/推理的每个 delta 只以 follow 流的
+ * `assistant-stream` 通知下发，而且**要显式传 `assistantStream: true` 才发**，事件流里只剩
+ * 「一步落定」的 `assistant/message`。不订阅通知的话，正文与运行中明细都只能在一步结束时整块
+ * 出现（真机故障 2026-10-21：回复整段蹦出来、运行中那一行没有实时明细）。
+ *
+ * 合成事件用的是移动协议早已认识的 `assistant/chunk` 形状，但**不带 seq** —— 它没有持久化
+ * 事件的身份，不该参与客户端的 seq 序门、去重与续传水位（App 侧对无 seq 帧一律放行），
+ * turn/step 由最近一次 start 通知补上。设备级推送只看 turn/start、turn/end、session/title
+ * （`lib/mobile/events.js` 的 LIST_EVENT_INNER），合成增量到不了那条通道，不会形成推送风暴。
+ *
+ * `state` 是这条流的记账（{ turn, step, streaming }），由调用方持有 —— 一帧的处理要看
+ * 「之前收到过什么」。snapshot 帧不需要处理：历史走 session.history。
+ */
+function* followFramePayloads(frame, sessionId, state) {
+  if (!frame) return;
+  if (frame.type === 'event') {
+    if (!frame.event) return;
+    // 增量只交付一次：宿主若同时把 chunk 也当成事件发，以通知为准（通知先到）。
+    if (state.streaming && frame.event.type === 'assistant/chunk') return;
     yield { payload: { type: 'session/event', sessionId, event: frame.event } };
+    return;
+  }
+  const notice = frame.type === 'assistant-stream' ? frame.frame : null;
+  if (!notice) return;
+  if (notice.type === 'start') {
+    if (Number.isSafeInteger(notice.turn)) state.turn = notice.turn;
+    if (Number.isSafeInteger(notice.step)) state.step = notice.step;
+    return;
   }
+  if (notice.type !== 'chunk' || !notice.chunk || typeof notice.chunk !== 'object') return;
+  // 块序号在通知帧上，chunk 自己也带一份；自己没带就补上（App 侧按 chunk.index 拼草稿）。
+  const chunk = typeof notice.chunk.index === 'number' || typeof notice.index !== 'number'
+    ? notice.chunk
+    : { ...notice.chunk, index: notice.index };
+  state.streaming = true;
+  yield {
+    payload: {
+      type: 'session/event',
+      sessionId,
+      event: {
+        type: 'assistant/chunk',
+        time: Number.isFinite(notice.time) ? notice.time : Date.now(),
+        data: { turn: state.turn, step: state.step, chunk },
+      },
+    },
+  };
 }
 
 /** 后台任务整帧。宿主 job/list 是流，首帧即全量 rows，之后按变化推。 */
@@ -174,20 +214,23 @@ function muxFrames(ctx, request, signal) {
     }
     const control = openStream(ctx, 'session', 'control', {}, signal).then((frames) => tolerate(frames, 'session/control', ctx));
     const jobs = openStream(ctx, 'job', 'list', { request: { sessionId } }, signal).then((frames) => tolerate(frames, `job/${sessionId}`, ctx));
+    // assistantStream: 逐块增量只走这条流的 assistant-stream 通知（见 followFramePayloads）。
     const follow = openStream(ctx, 'session', 'follow', {
-      request: { address: { kind: 'session', sessionId }, maxMessages: 1 },
+      request: { address: { kind: 'session', sessionId }, maxMessages: 1, assistantStream: true },
     }, signal).then((frames) => tolerate(frames, `session/${sessionId}`, ctx));
     const projections = projectionState();
-    const sources = await Promise.all([control, jobs, follow].map((promise) => promise.then(async function* wrap(iterable) {
+    const followState = { turn: null, step: null, streaming: false };
+    const sources = await Promise.all([['control', control], ['jobs', jobs], ['follow', follow]].map(([source, promise]) => promise.then(async function* wrap(iterable) {
       for await (const frame of iterable) {
-        if (frame && frame.type === 'rows') {
+        if (source === 'follow') {
+          // follow 一帧可能产出 0..n 个 mux 帧（事件原样 + 增量通知合成 chunk 事件）。
+          yield* followFramePayloads(frame, sessionId, followState);
+        } else if (frame && frame.type === 'rows') {
           yield { payload: { type: 'session/jobs', sessionId, jobs: Array.isArray(frame.jobs) ? frame.jobs : [] } };
         } else if (frame && frame.type === 'baseline') {
           yield* applyBaseline(frame, projections, sessionId, ctx);
         } else if (frame && frame.type === 'projection') {
           yield* applyUpdate(frame, projections, sessionId, ctx);
-        } else if (frame && frame.type === 'event' && frame.event) {
-          yield { payload: { type: 'session/event', sessionId, event: frame.event } };
         }
       }
     }).catch((error) => {

package/lib/mobile/session-send.js

@@ -275,4 +275,33 @@ async function handleFork(ctx, req, res) {
   sendJson(res, outcome.status, outcome.body);
 }
 
-module.exports = { singleTextOf, executeCommand, promptOnce, handleSend, handleCommands, handleSessionRead, handleStop, handleRename, handleFork };
+/**
+ * POST /api/mobile/v1/session/attachment（token）{sessionId, attachmentId}
+ * → {ok, mediaType, data, name?}
+ *
+ * 单张图片附件重取。App 在「认得出这张图、但上一次没取回字节」时给一个重试按钮，
+ * 按 attachmentId 只补这一张。不复用 /session/messages 重拉历史：那条按游标重装整个
+ * 消息列表，会把用户已经向上翻出去的更早几页丢掉。
+ */
+async function handleSessionAttachment(ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.sessionId !== 'string' || !body.sessionId
+    || typeof body.attachmentId !== 'string' || !body.attachmentId) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, attachmentId }' } });
+  }
+  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 : '';
+  // 附件已被会话清理掉时宿主回的是空字节：这不是「稍后再试就好」，如实回 404，
+  // 让 App 那边把重试按钮的失败说清楚，而不是转圈到超时。
+  if (!data) return sendJson(res, 404, { ok: false, error: { code: 'not-found', message: '附件已不可读' } });
+  const attachment = (value && value.attachment) || {};
+  sendJson(res, 200, {
+    ok: true,
+    mediaType: typeof attachment.mediaType === 'string' && attachment.mediaType ? attachment.mediaType : 'image/png',
+    data,
+    ...(typeof attachment.name === 'string' ? { name: attachment.name } : {}),
+  });
+}
+
+module.exports = { singleTextOf, executeCommand, promptOnce, handleSend, handleCommands, handleSessionRead, handleSessionAttachment, handleStop, handleRename, handleFork };

package/lib/mobile/sessions.js

@@ -15,7 +15,7 @@
  *   completion.js      完成提醒状态机
  *   session-models.js  模型目录与切模型
  *   session-search.js  正文检索
- *   session-send.js    发消息 / slash 命令 / 读 / 停 / 改名 / 分叉
+ *   session-send.js    发消息 / slash 命令 / 读 / 附件重取 / 停 / 改名 / 分叉
  *   session-snapshot.js 消息与统计快照（镜像与分页共用）
  *   session-mirror.js  镜像整帧构建
  *   session-goal.js    目标条动作
@@ -42,12 +42,10 @@ const {
 const { resolveEventAttachments } = require('./attachments.js');
 const { updateCompletionStates, confirmCompletionFromHistory } = require('./completion.js');
 const { buildMessagesSnapshot, buildStatsSnapshot, statsProjections, handleMessages } = require('./session-snapshot.js');
-const { safeModelsValue, buildModelsSnapshot, handleModels, handleSelectModel } = require('./session-models.js');
+const { buildModelsSnapshot, handleModels, handleSelectModel } = require('./session-models.js');
 const { buildSingleSessionMirror, buildMirrorWarmSnapshots } = require('./session-mirror.js');
-const {
-  promptOnce, handleSend, handleCommands, handleSessionRead,
-  handleStop, handleRename, handleFork,
-} = require('./session-send.js');
+const { promptOnce, handleSend, handleCommands, handleSessionRead, handleSessionAttachment, handleStop,
+  handleRename, handleFork } = require('./session-send.js');
 const { handleSessionSearch } = require('./session-search.js');
 const { handleAgentPresets } = require('./session-presets.js');
 const { handleGoalAction } = require('./session-goal.js');
@@ -406,12 +404,6 @@ async function handleNew(ctx, req, res) {
     if (!sessionId) {
       return { status: 500, body: { ok: false, error: { code: 'internal', message: '新建会话未返回 sessionId' } } };
     }
-    // 创建响应携带宿主当前选择；APP 可立即显示，完整目录仍可后台刷新。
-    let models;
-    try {
-      const result = unwrap(await callSessions(ctx, 'models', { sessionId }));
-      if (!result.error) models = safeModelsValue(result.value);
-    } catch { /* 模型目录不可用时仍允许创建会话 */ }
     // 新建的会话要立刻出现在列表里，否则手机端最长 10 秒看不到它。
     invalidateSessionList(ctx);
     return {
@@ -421,7 +413,6 @@ async function handleNew(ctx, req, res) {
         sessionId,
         cwd: payload.cwd || null,
         ...(value && typeof value.agentPreset === 'string' ? { agentPreset: value.agentPreset } : {}),
-        ...(models?.current ? { models } : {}),
       },
     };
   });
@@ -487,6 +478,7 @@ module.exports = {
   handleSend,
   handleCommands,
   handleSessionRead,
+  handleSessionAttachment,
   handleStop,
   handleRename,
   handleFork,

package/lib/mobile/uploads.js

@@ -0,0 +1,220 @@
+'use strict';
+
+/**
+ * 移动端文件分片上传：把手机分享进来的文件落到宿主机固定收件目录。
+ *
+ * 四步：begin（登记文件名，拿 uploadId 与片大小）→ chunk（按 index 顺序追加）→
+ * finish（落盘成 `<收件根>/<日期>/<文件名>`，重名自动加后缀）→ abort（放弃）。
+ *
+ * 为什么分片，而不是一次 POST 传完：
+ *   - 一次传完会把「能传多大的文件」变成一条运维配置 —— 中转的
+ *     `MAX_BODY_BYTES`（dsh-mobile-server/lib/config.js）默认 50MB，插件自己的
+ *     readJsonBody 默认只有 256KB。分片后单请求只有 1MB，与这些上限无关。
+ *   - 手机侧网络不稳，分片能只重传坏掉的那一片，而不是整个文件。
+ *
+ * 为什么片内容走 base64 而不是原始字节：隧道协议本身支持原始字节
+ * （lib/relay/protocol.js 的 httpBody 帧），但 App 侧没有任何「发二进制 body」的
+ * 先例，RN 的 fetch 对 ArrayBuffer body 的支持也随版本变；图片通道本来就以 base64
+ * 走 JSON，这里沿用同一条确定能用的路。代价是 33% 膨胀（单片 1MB → 约 1.37MB），
+ * 仍远低于任何一层上限。
+ *
+ * 顺序与幂等：chunk 只接受「下一片」，重复送达同一片按重传处理（回当前 received，
+ * 不再追加），跳号直接 409 —— 客户端因此不需要在重试前先问进度。
+ *
+ * 落盘根目录固定 `~/.dsh/mobile-inbox`（收件专目录，与工作区解耦，工作区被删也不
+ * 影响已收到的文件）。`DSH_MOBILE_INBOX` 可覆盖，只给测试用。
+ */
+
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+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 片在慢速上行网络上会撞超时；片越小越稳，代价只是多几次往返。
+const CHUNK_BYTES = 256 * 1024;
+/** 单片请求体上限：1MB base64 后约 1.37MB，留出信封与转义余量。 */
+const CHUNK_MAX_BODY = 4 * 1024 * 1024;
+/** 文件名上限（按字符算，避开各文件系统的字节上限差异）。 */
+const NAME_MAX_CHARS = 120;
+/** 暂存残片的最长寿命：手机上传中断后没人来 abort 的清理依据。 */
+const STAGING_TTL_MS = 24 * 60 * 60 * 1000;
+/** 分片必须是标准 base64：Node 的 Buffer.from 会静默丢弃非法字符，光靠解码判不出坏片。 */
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+/** 进行中的上传：uploadId → { name, stagingPath, received, bytes }。 */
+const uploads = new Map();
+
+/** 收件根目录。每次取用都重算，好让测试用环境变量分派。 */
+function inboxRoot() {
+  const override = process.env.DSH_MOBILE_INBOX;
+  return override ? path.resolve(override) : path.join(os.homedir(), '.dsh', 'mobile-inbox');
+}
+
+/**
+ * 清成一个能安全当作文件名的名字：去掉路径成分、文件系统保留字符与控制字符，
+ * 压掉连续空白，掐掉前导点（避免生成隐藏文件），并限长（保住扩展名）。
+ */
+function sanitizeName(raw) {
+  const base = path.basename(String(raw == null ? '' : raw).replace(/\\/g, '/'));
+  const cleaned = base
+    .replace(/[/\\:*?"<>|\u0000-\u001f\u007f]/g, '_')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^\.+/, '')
+    .trim();
+  if (!cleaned) return '未命名文件';
+  if (cleaned.length <= NAME_MAX_CHARS) return cleaned;
+  const ext = path.extname(cleaned).slice(0, 16);
+  return cleaned.slice(0, NAME_MAX_CHARS - ext.length) + ext;
+}
+
+/** 本地日期 yyyy-mm-dd（收件目录按天分堆，`os` 本地时区更贴近「今天收到的」）。 */
+function today() {
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+/** 在 dir 下给 name 找一个不冲突的落点（`名字-1.ext`、`名字-2.ext`…）。 */
+async function uniquePath(dir, name) {
+  const ext = path.extname(name);
+  const stem = name.slice(0, name.length - ext.length) || '未命名文件';
+  for (let i = 0; i < 200; i += 1) {
+    const candidate = path.join(dir, i === 0 ? name : `${stem}-${i}${ext}`);
+    try {
+      await fsp.access(candidate);
+    } catch {
+      return candidate;
+    }
+  }
+  return path.join(dir, `${stem}-${Date.now()}${ext}`);
+}
+
+/** 清掉过期残片；尽力而为，失败不影响本次上传。 */
+async function sweepStaging(stagingDir) {
+  let entries;
+  try {
+    entries = await fsp.readdir(stagingDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - STAGING_TTL_MS;
+  await Promise.all(entries.map(async (entry) => {
+    if (!entry.isFile() || !entry.name.endsWith('.part')) return;
+    const target = path.join(stagingDir, entry.name);
+    try {
+      const stat = await fsp.stat(target);
+      if (stat.mtimeMs < cutoff) await fsp.unlink(target);
+    } catch { /* 已被别人清掉 */ }
+  }));
+}
+
+function fail(res, status, code, message) {
+  return sendJson(res, status, { ok: false, error: { code, message } });
+}
+
+/** POST /api/mobile/v1/upload/begin → { ok, uploadId, chunkSize }。 */
+async function handleUploadBegin(_ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.name !== 'string' || !body.name.trim()) {
+    return fail(res, 400, 'bad-request', '需要 { name }');
+  }
+  const stagingDir = path.join(inboxRoot(), '.staging');
+  try {
+    await fsp.mkdir(stagingDir, { recursive: true });
+  } catch (error) {
+    return fail(res, 500, 'inbox-unavailable', `收件目录不可用：${error.message}`);
+  }
+  void sweepStaging(stagingDir);
+
+  const uploadId = crypto.randomUUID();
+  const stagingPath = path.join(stagingDir, `${uploadId}.part`);
+  try {
+    await fsp.writeFile(stagingPath, Buffer.alloc(0));
+  } catch (error) {
+    return fail(res, 500, 'inbox-unavailable', `无法建立暂存文件：${error.message}`);
+  }
+  uploads.set(uploadId, {
+    name: sanitizeName(body.name),
+    stagingPath,
+    received: 0,
+    bytes: 0,
+  });
+  sendJson(res, 200, { ok: true, uploadId, chunkSize: CHUNK_BYTES });
+}
+
+/** POST /api/mobile/v1/upload/chunk { uploadId, index, data } → { ok, received }。 */
+async function handleUploadChunk(_ctx, req, res) {
+  const body = await readJsonBody(req, CHUNK_MAX_BODY);
+  if (!body) return fail(res, 413, 'too-large', '分片过大或不是合法 JSON');
+
+  const job = uploads.get(String(body.uploadId == null ? '' : body.uploadId));
+  if (!job) return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
+
+  const index = Number(body.index);
+  if (!Number.isInteger(index) || index < 0) return fail(res, 400, 'bad-request', 'index 必须是非负整数');
+  if (typeof body.data !== 'string') return fail(res, 400, 'bad-request', 'data 必须是 base64 字符串');
+  if (index < job.received) return sendJson(res, 200, { ok: true, received: job.received });
+  if (index > job.received) {
+    return fail(res, 409, 'out-of-order', `期望分片 ${job.received}，收到 ${index}`);
+  }
+
+  const chunk = Buffer.from(body.data, 'base64');
+  if (!BASE64_RE.test(body.data) || body.data.length % 4 !== 0) {
+    return fail(res, 400, 'bad-request', 'data 不是合法 base64');
+  }
+  try {
+    await fsp.appendFile(job.stagingPath, chunk);
+  } catch (error) {
+    uploads.delete(String(body.uploadId));
+    return fail(res, 500, 'inbox-unavailable', `写入暂存文件失败：${error.message}`);
+  }
+  job.received += 1;
+  job.bytes += chunk.length;
+  sendJson(res, 200, { ok: true, received: job.received });
+}
+
+/** POST /api/mobile/v1/upload/finish { uploadId } → { ok, path, name, bytes }。 */
+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', '上传会话不存在或已结束');
+  uploads.delete(uploadId);
+
+  const dir = path.join(inboxRoot(), today());
+  try {
+    await fsp.mkdir(dir, { recursive: true });
+    const target = await uniquePath(dir, job.name);
+    await fsp.rename(job.stagingPath, target);
+    sendJson(res, 200, { ok: true, path: target, name: path.basename(target), bytes: job.bytes });
+  } catch (error) {
+    try { await fsp.unlink(job.stagingPath); } catch { /* 已经不在了 */ }
+    return fail(res, 500, 'inbox-unavailable', `落盘失败：${error.message}`);
+  }
+}
+
+/** POST /api/mobile/v1/upload/abort { uploadId } → { ok }。 */
+async function handleUploadAbort(_ctx, req, res) {
+  const body = await readJsonBody(req);
+  const uploadId = String((body && body.uploadId) || '');
+  const job = uploads.get(uploadId);
+  if (job) {
+    uploads.delete(uploadId);
+    try { await fsp.unlink(job.stagingPath); } catch { /* 已经不在了 */ }
+  }
+  sendJson(res, 200, { ok: true });
+}
+
+module.exports = {
+  handleUploadBegin,
+  handleUploadChunk,
+  handleUploadFinish,
+  handleUploadAbort,
+  sanitizeName,
+  inboxRoot,
+  CHUNK_BYTES,
+};

package/lib/mobile/workspaces.js

@@ -15,7 +15,7 @@
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');
-const { listRevision } = require('../shared/list-revision.js');
+const { stableRevision } = require('../shared/list-revision.js');
 // 会话列表缓存归 sessions.js 管。归档/移动会话会改变列表行本身，必须让那边立刻失效，
 // 否则手机端按完「归档会话」，那一行最长 10 秒还留在侧栏里，看着像没归档。
 const { invalidateSessionList } = require('./sessions.js');
@@ -74,7 +74,8 @@ async function buildWorkspacesBody(ctx) {
     // App 把 generatedAt + revision 存进快照用于展示「数据时间」，emptyConfirmed
     // 让「用户真的删光了工作区」不必再靠连续两次空去猜。
     generatedAt: Date.now(),
-    revision: listRevision(items),
+    // 归档集合也是工作区快照语义的一部分；仅它变化时也必须让镜像推送判为新版本。
+    revision: stableRevision({ items, archivedSessionIds }),
     emptyConfirmed: items.length === 0,
   };
 }