dsh-mobile-plugin 0.1.77 → 0.1.82

package/README.md

@@ -74,7 +74,16 @@ pnpm add dsh-mobile-plugin@<版本>
 
 新版插件的管理面板提供「本机调试 OTA」卡片，可手动检查并安装中转发布的紧急完整包。入口仅限宿主本机访问，不会由手机或公网触发；安装后通过实现代切换生效，切换失败会恢复上一代。npm 仍是正式发布源；后续 npm 正式版本达到 OTA 版本时会接管该版本。首次发布带此功能的 npm 包需要重启一次 DSH，让稳定外壳加载 OTA 能力。
 
-发布 OTA 完整包时，在插件仓库根目录执行 `npm pack`，再按中转服务器的部署说明上传到 `dsh-hub.wnluo.com`。
+发布一个紧急完整包：在插件仓库根目录 `npm pack`，把打出来的 tgz 原样 POST 给中转（包本身就是 tar.gz，不用再解包重打）：
+
+```sh
+curl -X POST -H "authorization: Bearer <中转的 OTA 发布 token>" --data-binary @dsh-mobile-plugin-0.1.61.tgz \
+  "https://你的中转/api/desktop-plugins/ota/publish?platform=darwin&channel=stable&version=0.1.61"
+```
+
+`platform` 填 `process.platform`（`darwin` / `linux` / `win32`），`channel` 一般 `stable`。发布接口没配 token 时是关闭的，下载不受影响；版本按号比，最后发的那个才是「最新」。
+
+打包时**别用 macOS 默认的 tar 参数**——带 PAX 扩展头，宿主那边的解析器不认，会报「OTA 包结构不完整」。要 `COPYFILE_DISABLE=1 tar --no-xattrs --no-mac-metadata -czf …`，且条目以 `package/` 打头。
 
 ## 开发
 

package/lib/impl.js

@@ -62,9 +62,16 @@ export const name = 'dsh-mobile-plugin'
 //                                                  有，get trap 第一站就命中）。
 // 漏了这两个分支里的任何一个，读 `ctx.apiProxy` 都会抛
 // `cannot get property "apiProxy" without inject`：服务器宿主上 mirror 推送曾整条挂掉。
+//
+// `typertGateway` 必须出现在 inject 里（0.2.0 那一支）：宿主 RPC 全部经它派发，
+// 而它是**后于本插件**装载的服务。只 `ctx.get('typertGateway')` 而不注入，取到的是
+// 装载那一刻的空值，于是每一条事件流都抛「当前宿主版本没有提供该能力」——服务器宿主
+// 上实时推送整条挂掉，而收发消息、会话列表这些走普通请求的功能一切正常，看着像只有
+// 「刷新不实时」的小毛病。注入之后 cordis 会等服务就绪再激活本插件。
+// 旧运行时那一支不加：那版没有这个服务，注入只会让这一行永远 pending。
 export const inject = runtimeProvidesApiProxy()
   ? ['webServer', 'apiProxy', 'sessions']
-  : ['webServer', 'sessions']
+  : ['webServer', 'sessions', 'typertGateway']
 
 export const REMOTE_CONTROL_SETTINGS_NAMESPACE = 'mobile-remote-control'
 export const RemoteControlSettingsSchema = z.object({
@@ -393,6 +400,10 @@ function apply(ctx) {
     // 移动端路由表那边叫它「局域网候选」，取的是同一份私网优先的清单。
     safeLanCandidates: advertisedCandidates,
     lanPortInUse: advertisedLanPort, // LAN 候选用实绑端口
+    // 配对那条路由自己要签凭据：core 是签 token 的实现，pairingApproval 决定这台机器
+    // 收不收新设备（'deny' 时一律拒）。两者本文件都已有，透传给移动端路由。
+    core,
+    pairingApproval,
   })
   ctx.effect(() => {
     const stopWatching = settings.watch(next => {

package/lib/mobile/history-derive.js

@@ -209,9 +209,13 @@ function lastMessageOf(messages) {
 /**
  * 从 history 事件折叠出消息与「结构化行」（wire v1 扩展，向后兼容）：
  *  - 普通消息维持现状：{ id, seq, time, role, text, blocks?, images?, clientMessageId? }（user/assistant）；
- *  - compaction：{ kind:'compaction', id, seq, time, state:'running'|'done', summary?, shadowedItemCount?, shadowedTokenCount? }；
+ *  - compaction：{ kind:'compaction', id, seq, time, state:'running'|'done'|'failed', error?, turn?,
+ *    summary?, shadowedItemCount?, shadowedTokenCount? }；
  *    压缩检查点 user/message（source.kind==='plugin' && source.plugin==='compact'）绝不渲染成用户气泡，
  *    渲染成 compaction 行（id=compactionId，state='done'），并用同 compactionId 的 compaction/summary 补 counts；
+ *    compaction/end 给这次尝试落定（带 error → state='failed' + error 原文，否则 'done'）；
+ *    **同一轮里的多次尝试只占一行**（新尝试原地顶替还没落定的那条）—— 宿主一步重试一次，
+ *    不并就是几十条「正在压缩…」；
  *  - 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>' }；
  *  - command：{ kind:'command', id:commandId, name, status:'running'|'done', resultKind?, text? }
@@ -291,6 +295,8 @@ function deriveMessages(events) {
   };
   // 结构化行按 id 唯一：compactionId → 行索引（检查点行原地替换 start 行）、retryId → 行索引（原地升级）。
   const compactionAt = new Map();
+  // 一轮里的压缩尝试行（turn → 行索引表）：同一轮的多次尝试共用一行，见 pendingCompactionAt。
+  const compactionTurns = new Map();
   const retryAt = new Map();
   // 命令行按 commandId 唯一：command/run 发出行，command/done 原地升级（保 run 的 name，位置随 done 事件 seq 归位）。
   const commandAt = new Map();
@@ -332,12 +338,31 @@ function deriveMessages(events) {
 
   // 放入一行 compaction：同一 compactionId 只保留一行，检查点行原地替换 start 行（最终按 seq 排序归位）。
   const placeCompaction = (item) => {
-    const existing = compactionAt.get(item.id);
-    if (existing !== undefined) out[existing] = item;
-    else {
-      compactionAt.set(item.id, out.length);
+    let index = compactionAt.get(item.id);
+    if (index === undefined) {
+      index = out.length;
       out.push(item);
+    } else out[index] = item;
+    compactionAt.set(item.id, index);
+    if (typeof item.turn === 'number') {
+      const list = compactionTurns.get(item.turn);
+      if (list === undefined) compactionTurns.set(item.turn, [index]);
+      else if (!list.includes(index)) list.push(index);
     }
+    return index;
+  };
+
+  // 同一轮里的多次压缩尝试只占一行：宿主一步重试一次、每次一个新 compactionId，按 id 找必然
+  // 「每次都新增一条」——一次跑几十步就是一个回合几十条「正在压缩…」。新尝试顶替这一轮里还
+  // 没落定的那条（running / failed），已经落地（done）的不顶替：那是真压过一次的记录。
+  const pendingCompactionAt = (turn, id) => {
+    if (compactionAt.has(id)) return compactionAt.get(id);
+    if (typeof turn !== 'number') return -1;
+    for (const index of compactionTurns.get(turn) || []) {
+      const row = out[index];
+      if (row && row.kind === 'compaction' && (row.state === 'running' || row.state === 'failed')) return index;
+    }
+    return -1;
   };
 
   for (const entry of events) {
@@ -376,8 +401,10 @@ function deriveMessages(events) {
     } else if (e.type === 'assistant/message' && e.data && e.data.message && e.data.message.content) {
       pushMessage(e.data.message, e);
     } else if (e.type === 'compaction/start' && e.data && typeof e.data.compactionId === 'string' && e.data.compactionId !== '') {
-      // 行已由检查点发出（done）时跳过，避免重复行。
-      if (!compactionAt.has(e.data.compactionId)) {
+      // 行已由检查点发出（done）时跳过，避免重复行。同一轮里已有没落定的行就**原地顶替**
+      // （换 id/状态，位置留在第一次尝试那一处）—— 否则一次跑几十步就是几十条行。
+      const idx = pendingCompactionAt(e.data.turn, e.data.compactionId);
+      if (idx < 0) {
         placeCompaction({
           id: e.data.compactionId,
           kind: 'compaction',
@@ -387,7 +414,46 @@ function deriveMessages(events) {
           shadowedTokenCount: null,
           seq,
           time,
+          ...(typeof e.data.turn === 'number' ? { turn: e.data.turn } : {}),
+        });
+      } else {
+        const existing = out[idx];
+        out[idx] = {
+          ...existing,
+          id: e.data.compactionId,
+          state: 'running',
+          error: null,
+          ...(typeof e.data.turn === 'number' ? { turn: e.data.turn } : {}),
+        };
+        compactionAt.set(e.data.compactionId, idx);
+      }
+    } else if (e.type === 'compaction/end' && e.data && typeof e.data.compactionId === 'string' && e.data.compactionId !== '') {
+      // 这次尝试的落定：无 error → done（summary / 检查点随后补齐 counts）、有 error → failed
+      // 带原因。这条以前整条丢掉，于是被拒绝的压缩永远停在「正在压缩…」，失败一次都看不见。
+      const error = typeof e.data.error === 'string' && e.data.error !== '' ? e.data.error : null;
+      const idx = pendingCompactionAt(e.data.turn, e.data.compactionId);
+      if (idx < 0) {
+        placeCompaction({
+          id: e.data.compactionId,
+          kind: 'compaction',
+          state: error ? 'failed' : 'done',
+          error,
+          summary: null,
+          shadowedItemCount: null,
+          shadowedTokenCount: null,
+          seq,
+          time,
+          ...(typeof e.data.turn === 'number' ? { turn: e.data.turn } : {}),
         });
+      } else {
+        const existing = out[idx];
+        out[idx] = {
+          ...existing,
+          id: e.data.compactionId,
+          state: error ? 'failed' : 'done',
+          error,
+        };
+        compactionAt.set(e.data.compactionId, idx);
       }
     } else if (e.type === 'compaction/summary' && e.data && typeof e.data.compactionId === 'string' && e.data.compactionId !== '') {
       // 已有同 compactionId 的行（start 或检查点发出）→ 升级为 done 并补 counts；否则新增 done 行。
@@ -395,6 +461,7 @@ function deriveMessages(events) {
       const existing = compactionAt.has(id) ? out[compactionAt.get(id)] : null;
       if (existing) {
         existing.state = 'done';
+        existing.error = null;
         existing.summary = compactionSummaryText(e.data.summary);
         existing.shadowedItemCount = shadowedCount(e.data.shadowedSeqs);
         existing.shadowedTokenCount = shadowedTokens(e.data.shadowedTokenCount);
@@ -486,7 +553,7 @@ function deriveMessages(events) {
         out.push({ id: `turn-${e.data.turn}`, kind: 'max-tokens', seq, time });
       }
     }
-    // tool/result、compaction/end 等其余类型照旧忽略（compaction 行已由 start 发出）。
+    // tool/result 等其余类型照旧忽略（工具结果在预扫描里配对回填；compaction 行由 start/end 发出）。
   }
   // 严格按事件 seq 升序（与消息混排；compaction 行升级/替换后位置以最终事件为准）。
   out.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));

package/lib/mobile/host-bridge/transport.js

@@ -128,11 +128,41 @@ function dropUnexpectedArgs(args, message) {
   return removed ? next : null;
 }
 
+/**
+ * 调用宿主时一并交出「本机操作者」身份。
+ *
+ * 0.2.1 起网关在派发前先 `assertPeerLive(request.peer)`：Peer 缺了就对 undefined 读
+ * `.signal`，抛 `Cannot read properties of undefined (reading 'signal')`，这里把它收敛成
+ * `host-call-failed` —— 手机上表现为 /sessions、/workspaces 一律 400，会话镜像永远
+ * 「未推送」（只有本机自算的 /status 还活着）。0.2.0 及更早没有这道检查（网关自己回落
+ * operatorPeer），也没有 `browserPeer` 这个成员，所以取不到就**不带**，行为与从前一致。
+ *
+ * 用 `ctx.get` 而不是 inject：旧宿主没这个成员、极简 profile 也可能没有这个服务，
+ * 注入一个不存在的服务会让整行永远 pending（见 impl.js 里 apiProxy 那段教训）。
+ */
+function peerOf(ctx) {
+  try {
+    const connection = ctx.get && ctx.get('connection');
+    const peer = connection && connection.browserPeer;
+    return peer && typeof peer === 'object' ? peer : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 补齐到「当前宿主认得」的请求形状：新旧宿主的差别只在这一个函数里判定。 */
+function hostRequest(ctx, namespace, method, args, signal) {
+  const request = { namespace, method, args };
+  if (signal) request.signal = signal;
+  const peer = peerOf(ctx);
+  if (peer) request.peer = peer;
+  return request;
+}
+
 async function invoke(ctx, namespace, method, args, signal) {
   const gateway = gatewayOf(ctx);
   if (!gateway) return { error: { ...UNAVAILABLE } };
-  const request = { namespace, method, args };
-  if (signal) request.signal = signal;
+  const request = hostRequest(ctx, namespace, method, args, signal);
   try {
     return { value: await gateway.invoke(request) };
   } catch (error) {
@@ -154,9 +184,7 @@ async function invoke(ctx, namespace, method, args, signal) {
 async function openStream(ctx, namespace, method, args, signal) {
   const gateway = gatewayOf(ctx);
   if (!gateway) throw Object.assign(new Error(UNAVAILABLE.message), { code: UNAVAILABLE.code });
-  const request = { namespace, method, args };
-  if (signal) request.signal = signal;
-  return gateway.stream(request);
+  return gateway.stream(hostRequest(ctx, namespace, method, args, signal));
 }
 
 async function invokeEnvelope(ctx, namespace, method, args, signal) {

package/lib/mobile/pairing.js

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * 移动端配对：手机在中转上用自己的配对码换到 token 与设备凭据。
+ *
+ * **这条路由归宿主，不归中转。**「谁可以进这台机器」是宿主自己的判断，配对码本来就存在
+ * 宿主的 `state` 里；中转只按实例标识把请求转过来。早先这套判断长在独立的中转进程里
+ * （`dsh-mobile-server/server.js` 的 `/pair`），换成 Rust 中转时整块没搬过去，于是手机
+ * 按老地址 POST `/pair`、请求被中转原样转给宿主、宿主没有这条路由，只能回 405。
+ *
+ * 与局域网那条（`lib/relay/lan-proxy.js` 的 `/__lan_pair`）是**同一件事的两个入口**：
+ * 都是「配对码 → 签发凭据」，差别只在网络路径。凭据本身两条路签发的是同一种 HMAC
+ * （都用宿主 lanSecret 签名），所以经中转配对拿到的 token 可以直接用于局域网请求。
+ *
+ * 故意**不**在这里做的事：
+ *  - 不问宿主再确认一次。宿主的配对策略（pairingPolicy）已经决定了它接不接受新设备，
+ *    `deny` 时中转根本连不上；而这条路由本身就跑在宿主进程里。
+ *  - 不做「多台机器撞同一个配对码」的处理。那是中转的职责（它才看得见全部实例），
+ *    在这台宿主上，配对码要么对上要么对不上。
+ */
+
+const { sendJson } = require('../shared/http-util');
+const { safeEqual } = require('../shared/dshtoken');
+
+/** 与局域网那条同口径：连错 5 次锁 60 秒。 */
+const PAIR_MAX_FAILS = 5;
+const PAIR_LOCK_MS = 60_000;
+
+/** ip -> { fails, lockedUntil }。放在模块作用域，两种入口共用同一份额度。 */
+const pairLocks = new Map();
+
+function isPairLocked(ip) {
+  const entry = pairLocks.get(ip);
+  return !!entry && entry.lockedUntil > Date.now();
+}
+
+function recordPairFail(ip) {
+  const entry = pairLocks.get(ip) || { fails: 0, lockedUntil: 0 };
+  entry.fails += 1;
+  if (entry.fails >= PAIR_MAX_FAILS) {
+    entry.lockedUntil = Date.now() + PAIR_LOCK_MS;
+    entry.fails = 0;
+  }
+  pairLocks.set(ip, entry);
+}
+
+function clearPairFails(ip) {
+  pairLocks.delete(ip);
+}
+
+/** 测试用：清空限流计数。 */
+function resetPairLocks() {
+  pairLocks.clear();
+}
+
+/** 请求方 IP。中转会把真实来源放进 x-real-ip（与 nginx 同一约定）。 */
+function clientIp(req) {
+  const headers = (req && req.headers) || {};
+  const raw = headers['x-real-ip'];
+  const header = Array.isArray(raw) ? raw[0] : raw;
+  if (typeof header === 'string' && header.trim()) return header.trim();
+  return (req && req.socket && req.socket.remoteAddress) || '';
+}
+
+/**
+ * 配对码错误 / 策略拒绝统一回同一响应。
+ *
+ * 分开回等于告诉对方「这个码是真的，只是被拒了」，也就是把一个免费的存在性查询送出去。
+ */
+function pairDenied(res) {
+  sendJson(res, 401, { ok: false, error: '配对码错误' });
+}
+
+/**
+ * 读请求体。配对体很小（配对码 + 设备元信息），上限给 16KB。
+ */
+function readBody(req) {
+  return new Promise((resolve) => {
+    if (!req || typeof req.on !== 'function') {
+      resolve({});
+      return;
+    }
+    let raw = '';
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      try {
+        resolve(JSON.parse(raw || '{}'));
+      } catch {
+        resolve(null);
+      }
+    };
+    req.setEncoding('utf8');
+    req.on('data', (chunk) => {
+      raw += chunk;
+      if (raw.length > 16 * 1024) {
+        raw = raw.slice(0, 16 * 1024);
+        req.destroy();
+        finish();
+      }
+    });
+    req.on('end', finish);
+    req.on('error', finish);
+  });
+}
+
+/**
+ * 构造 `/pair` 的 handler。依赖由 impl.js 注入，与移动端其它路由同一形状。
+ *
+ * @param {object} deps
+ * @param {object} deps.state  宿主状态（instanceId / pairingCode / lanSecret）
+ * @param {Function} deps.readJsonBody
+ * @param {object} deps.core    relay/core.js（签 token 用）
+ * @param {object} deps.credentials 设备凭据库（issue 接口）
+ * @param {object} deps.pairingApproval pairing-policy.js（决定这台机器收不收新设备）
+ * @param {(message: string) => void} deps.log
+ */
+function createPairHandler(deps) {
+  const { state, core, credentials, pairingApproval, log } = deps;
+
+  // ⚠️ 签名必须是 `(req, res)` **两个**参数：宿主 webServer 就是 `handler(req, res)` 调的。
+  // 写成 `(_ctx, req, res)` 会把 res 挤成 undefined，而 sendJson 的 catch 会把那个
+  // TypeError 当成「连接已关闭」吞掉——既没报错也没回包，请求永久挂住（/health 踩过）。
+  return async function handlePair(req, res) {
+    const ip = clientIp(req);
+
+    if (isPairLocked(ip)) {
+      sendJson(res, 429, { ok: false, error: '尝试过于频繁，请稍后再试' });
+      return;
+    }
+
+    const body = await readBody(req);
+    if (!body || typeof body !== 'object') {
+      sendJson(res, 400, { ok: false, error: '请求体不是合法 JSON' });
+      return;
+    }
+
+    const code = typeof body.code === 'string' ? body.code.trim() : '';
+    if (!/^\d{6}$/.test(code)) {
+      sendJson(res, 400, { ok: false, error: '配对码需为 6 位数字' });
+      return;
+    }
+
+    const expected = String(state.pairingCode || '');
+    if (!expected || !safeEqual(code, expected)) {
+      recordPairFail(ip);
+      pairDenied(res);
+      return;
+    }
+
+    // 配对码对了，还要宿主自己的策略点头：'deny' 就是明确不收新设备。
+    const decision = pairingApproval.evaluate(state.pairingPolicy, body.device);
+    if (!decision.approved) {
+      recordPairFail(ip);
+      pairDenied(res);
+      return;
+    }
+
+    // **配对码正确时不清限流计数**：被拒的尝试同样要记数，否则猜对码但被策略拒的一方
+    // 可以无限重试。只有真正放行才清零。
+    clearPairFails(ip);
+
+    const instanceId = String(state.instanceId || '');
+    const supplied = body.device && typeof body.device === 'object' ? body.device : {};
+    const device = {
+      ...Object.fromEntries(Object.entries(supplied).filter(([, value]) => value !== undefined)),
+      ip,
+    };
+
+    let issued;
+    try {
+      issued = credentials.issue(instanceId, device, '');
+    } catch (error) {
+      log('pair issue failed:', error && error.message);
+      sendJson(res, 500, { ok: false, error: 'internal error' });
+      return;
+    }
+
+    // 两样都要给，缺一样 App 就停在「配对响应缺少 token/cookie」：
+    //  - `token` 是 **bearer**（`Authorization: Bearer …`），365 天；
+    //  - `cookie` 是**中转路由**用的那张，30 天。
+    // 两者的 TTL 刻意不同，别合成一个常量（见 relay/core.js 的 MOBILE_BEARER_TTL_SEC 注释）。
+    const token = core.signLanToken(state.lanSecret, instanceId, core.MOBILE_BEARER_TTL_SEC);
+    const cookieValue = core.signLanToken(state.lanSecret, instanceId, core.MOBILE_TOKEN_TTL_SEC);
+    const hostPlatform = pairingApproval.hostPlatform().platform;
+    sendJson(res, 200, {
+      ok: true,
+      instanceId,
+      token,
+      // cookie 同时放进 body：RN 的 fetch 读不到 Set-Cookie，App 得自己带上。
+      cookie: `dsh_lan=${cookieValue}`,
+      deviceId: issued.deviceId,
+      deviceCredential: issued.credential,
+      credentialExpiresAt: issued.expiresAt,
+      // 宿主自己的系统标识，不是手机的。键名**必须是 `hostPlatform`**：App 落盘的就是它
+      //（app/src/services/pairApi.ts 读 `body.hostPlatform` 存进 `MobileSession.hostPlatform`），
+      // 局域网那条（lan-proxy.js）给的也是它。`hostPlatform()` 回的是 `{platform}` 对象，
+      // 整块展开就变成 `platform` —— App 收不到，设备行退回通用图标（真机上少的就是企鹅）。
+      ...(hostPlatform ? { hostPlatform } : {}),
+    });
+  };
+}
+
+module.exports = {
+  createPairHandler,
+  resetPairLocks,
+  clientIp,
+  PAIR_MAX_FAILS,
+  PAIR_LOCK_MS,
+};

package/lib/mobile/uploads.js

@@ -44,9 +44,43 @@ 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 }。 */
+/** 进行中的上传：uploadId → { name, stagingPath, received, bytes, expiresAt, expiryTimer }。 */
 const uploads = new Map();
 
+function removeUpload(uploadId, job) {
+  if (uploads.get(uploadId) !== job) return false;
+  uploads.delete(uploadId);
+  if (job.expiryTimer) clearTimeout(job.expiryTimer);
+  job.expiryTimer = null;
+  return true;
+}
+
+async function expireUpload(uploadId, job) {
+  if (uploads.get(uploadId) !== job) return;
+  const remaining = job.expiresAt - Date.now();
+  if (remaining > 0) {
+    job.expiryTimer = setTimeout(() => { void expireUpload(uploadId, job); }, remaining);
+    job.expiryTimer.unref?.();
+    return;
+  }
+  if (!removeUpload(uploadId, job)) return;
+  try { await fsp.unlink(job.stagingPath); } catch { /* 暂存文件可能已由磁盘清扫移除 */ }
+}
+
+function scheduleUploadExpiry(uploadId, job) {
+  if (job.expiryTimer) clearTimeout(job.expiryTimer);
+  job.expiryTimer = setTimeout(() => { void expireUpload(uploadId, job); }, Math.max(0, job.expiresAt - Date.now()));
+  job.expiryTimer.unref?.();
+}
+
+/** 清理过期上传状态及其暂存文件；传入 now 便于测试 TTL 边界。 */
+async function sweepExpiredUploads(now = Date.now()) {
+  await Promise.all([...uploads].map(async ([uploadId, job]) => {
+    if (job.expiresAt > now || !removeUpload(uploadId, job)) return;
+    try { await fsp.unlink(job.stagingPath); } catch { /* 暂存文件可能已由磁盘清扫移除 */ }
+  }));
+}
+
 /** 收件根目录。每次取用都重算，好让测试用环境变量分派。 */
 function inboxRoot() {
   const override = process.env.DSH_MOBILE_INBOX;
@@ -129,6 +163,7 @@ async function handleUploadBegin(_ctx, req, res) {
     return fail(res, 500, 'inbox-unavailable', `收件目录不可用：${error.message}`);
   }
   void sweepStaging(stagingDir);
+  void sweepExpiredUploads();
 
   const uploadId = crypto.randomUUID();
   const stagingPath = path.join(stagingDir, `${uploadId}.part`);
@@ -137,12 +172,16 @@ async function handleUploadBegin(_ctx, req, res) {
   } catch (error) {
     return fail(res, 500, 'inbox-unavailable', `无法建立暂存文件：${error.message}`);
   }
-  uploads.set(uploadId, {
+  const job = {
     name: sanitizeName(body.name),
     stagingPath,
     received: 0,
     bytes: 0,
-  });
+    expiresAt: Date.now() + STAGING_TTL_MS,
+    expiryTimer: null,
+  };
+  uploads.set(uploadId, job);
+  scheduleUploadExpiry(uploadId, job);
   sendJson(res, 200, { ok: true, uploadId, chunkSize: CHUNK_BYTES });
 }
 
@@ -169,11 +208,13 @@ async function handleUploadChunk(_ctx, req, res) {
   try {
     await fsp.appendFile(job.stagingPath, chunk);
   } catch (error) {
-    uploads.delete(String(body.uploadId));
+    removeUpload(String(body.uploadId), job);
     return fail(res, 500, 'inbox-unavailable', `写入暂存文件失败：${error.message}`);
   }
   job.received += 1;
   job.bytes += chunk.length;
+  job.expiresAt = Date.now() + STAGING_TTL_MS;
+  scheduleUploadExpiry(String(body.uploadId), job);
   sendJson(res, 200, { ok: true, received: job.received });
 }
 
@@ -183,7 +224,7 @@ async function handleUploadFinish(_ctx, req, res) {
   const uploadId = String((body && body.uploadId) || '');
   const job = uploads.get(uploadId);
   if (!job) return fail(res, 404, 'unknown-upload', '上传会话不存在或已结束');
-  uploads.delete(uploadId);
+  removeUpload(uploadId, job);
 
   const dir = path.join(inboxRoot(), today());
   try {
@@ -203,7 +244,7 @@ async function handleUploadAbort(_ctx, req, res) {
   const uploadId = String((body && body.uploadId) || '');
   const job = uploads.get(uploadId);
   if (job) {
-    uploads.delete(uploadId);
+    removeUpload(uploadId, job);
     try { await fsp.unlink(job.stagingPath); } catch { /* 已经不在了 */ }
   }
   sendJson(res, 200, { ok: true });
@@ -216,5 +257,6 @@ module.exports = {
   handleUploadAbort,
   sanitizeName,
   inboxRoot,
+  sweepExpiredUploads,
   CHUNK_BYTES,
 };