dsh-mobile-plugin 0.5.22 → 0.5.24

package/lib/mobile/phone/service.js

@@ -22,7 +22,7 @@
  *   - `{t:'event', kind:'needs-human'|'progress', sessionId, …}` —— 暂只记账，不转发
  *
  * 宿主 → 手机：
- *   - `{t:'op', id, sessionId, action, args}`
+ *   - `{t:'op', id, sessionId, action, args, timeout}` —— timeout 是这一发自适应算出的预算(ms)
  *   - `{t:'cancel', id}`
  *
  * 动作名是封闭的一小张表（见 `ACTIONS`）；手机端认不出的动作回 `unsupported`，宿主不会因为
@@ -40,8 +40,13 @@ const { WebSocketServer } = require('ws');
 
 /** 一条帧的上限：截图是 base64 塞在 JSON 里的，留足余量；更大的东西手机不会发。 */
 const MAX_PAYLOAD = 12 * 1024 * 1024;
-/** 心跳：手机每 20 秒至少要有一次 ping/pong 往返，否则按掉线处理（等它自己重连）。 */
+/** 心跳间隔：每 20 秒发一次 ping。 */
 const HEARTBEAT_MS = 20_000;
+/**
+ * 连续丢这么多次心跳（约 60 秒）才按掉线处理，对齐手机端 60s 看门狗。
+ * 弱网下偶发一两次丢 pong 不算掉线，免得来回假掉线、把在途 op 全抹成 offline。
+ */
+const MAX_MISSED_HEARTBEATS = 3;
 /** 单次 op 的默认预算；每个动作另有自己的一档（见 ACTIONS）。 */
 const DEFAULT_OP_TIMEOUT_MS = 30_000;
 
@@ -85,6 +90,44 @@ function createPhoneService({ authorized, onLog } = {}) {
   let closed = false;
   let seq = 0;
 
+  /** 耗时 EWMA 的平滑系数：动作耗时用 0.3，心跳 RTT 用 0.2。 */
+  const EWMA_ALPHA = 0.3;
+  const RTT_ALPHA = 0.2;
+
+  function ewma(prev, sample, alpha) {
+    if (!prev || !(prev.n > 0) || !Number.isFinite(prev.value)) return { value: sample, n: 1 };
+    return { value: prev.value * (1 - alpha) + sample * alpha, n: prev.n + 1 };
+  }
+
+  /** 成功回包按「发送 → 收到」耗时更新 perAction 与全体两类统计。 */
+  function recordLatency(link, action, sample) {
+    if (!Number.isFinite(sample) || sample < 0) return;
+    const lat = link.latency;
+    lat.perAction.set(action, ewma(lat.perAction.get(action), sample, EWMA_ALPHA));
+    lat.all = ewma(lat.all, sample, EWMA_ALPHA);
+  }
+
+  /**
+   * 某动作这一发该给多少预算：估时 est 取自本动作（样本够）或全体，套 est*2.5 + rtt*2 + 1500，
+   * 冷启动抬到 seed*1.5 兜底，最后夹进 [max(2500, seed/2), min(120000, max(seed*8, floor))]。
+   * `ACTIONS` 里的数字只是这个 seed，不再直接当预算。
+   */
+  function budgetFor(link, action) {
+    const seed = ACTIONS.get(action) || DEFAULT_OP_TIMEOUT_MS;
+    const lat = link.latency;
+    const pa = lat.perAction.get(action);
+    let est = seed;
+    if (pa && pa.n >= 2) est = pa.value;
+    else if (lat.all && lat.all.n >= 2) est = lat.all.value;
+    const rtt = lat.rtt > 0 ? lat.rtt : 0;
+    let budget = est * 2.5 + rtt * 2 + 1500;
+    const cold = Date.now() - link.connectedAt < 20_000 || !lat.all || lat.all.n < 1;
+    if (cold) budget = Math.max(budget, seed * 1.5);
+    const floor = Math.max(2500, seed * 0.5);
+    const ceil = Math.min(120_000, Math.max(seed * 8, floor));
+    return Math.round(Math.min(Math.max(budget, floor), ceil));
+  }
+
   const log = (message) => { try { onLog?.(message); } catch { /* 日志失败不影响搬运 */ } };
 
   const wss = new WebSocketServer({ noServer: true, perMessageDeflate: false, maxPayload: MAX_PAYLOAD });
@@ -108,6 +151,7 @@ function createPhoneService({ authorized, onLog } = {}) {
       });
     }
     link.pending.clear();
+    try { clearInterval(link.heartbeat); } catch { /* 已经清过了 */ }
     try { link.socket.close(); } catch { /* 已经断了 */ }
   }
 
@@ -122,6 +166,8 @@ function createPhoneService({ authorized, onLog } = {}) {
       capabilities: hello && Array.isArray(hello.capabilities) ? hello.capabilities.filter((c) => typeof c === 'string') : [],
       connectedAt: Date.now(),
       alive: true,
+      missed: 0,
+      latency: { perAction: new Map(), all: null, rtt: 0 },
       pending: new Map(),
     };
     devices.set(deviceId, link);
@@ -137,6 +183,12 @@ function createPhoneService({ authorized, onLog } = {}) {
       if (!frame || typeof frame !== 'object') return;
       if (frame.t === 'pong') {
         link.alive = true;
+        if (Number.isFinite(link.pingAt) && link.pingAt > 0) {
+          const sample = Date.now() - link.pingAt;
+          const prev = link.latency.rtt;
+          link.latency.rtt = prev > 0 ? prev * (1 - RTT_ALPHA) + sample * RTT_ALPHA : sample;
+          link.pingAt = 0;
+        }
         return;
       }
       if (frame.t === 'hello') {
@@ -151,8 +203,12 @@ function createPhoneService({ authorized, onLog } = {}) {
         const pending = link.pending.get(text(frame.id));
         if (!pending) return;
         link.pending.delete(text(frame.id));
-        if (frame.ok) pending.settleOk(frame.data === undefined ? null : frame.data);
-        else {
+        if (frame.ok) {
+          if (pending.action && Number.isFinite(pending.sentAt)) {
+            recordLatency(link, pending.action, Date.now() - pending.sentAt);
+          }
+          pending.settleOk(frame.data === undefined ? null : frame.data);
+        } else {
           const error = frame.error && typeof frame.error === 'object' ? frame.error : {};
           pending.settleErr({
             code: text(error.code) || 'failed',
@@ -179,12 +235,19 @@ function createPhoneService({ authorized, onLog } = {}) {
     link.heartbeat = setInterval(() => {
       if (!statusOf(socket)) return;
       if (!link.alive) {
-        log(`phone ${deviceId}: 心跳丢了，按断线处理`);
-        drop(deviceId, 'offline');
-        return;
+        link.missed += 1;
+        if (link.missed >= MAX_MISSED_HEARTBEATS) {
+          log(`phone ${deviceId}: 连续 ${link.missed} 次心跳没回应，按断线处理`);
+          drop(deviceId, 'offline');
+          return;
+        }
+        log(`phone ${deviceId}: 心跳丢了（${link.missed}/${MAX_MISSED_HEARTBEATS}），再等等`);
+      } else {
+        link.missed = 0;
       }
       link.alive = false;
-      try { socket.send(JSON.stringify({ t: 'ping', at: Date.now() })); } catch { /* 下面 close 会来 */ }
+      link.pingAt = Date.now();
+      try { socket.send(JSON.stringify({ t: 'ping', at: link.pingAt })); } catch { /* 下面 close 会来 */ }
     }, HEARTBEAT_MS);
     link.heartbeat.unref?.();
 
@@ -210,7 +273,7 @@ function createPhoneService({ authorized, onLog } = {}) {
     if (!ACTIONS.has(action)) return Promise.reject({ code: 'unknown-action', message: `不支持的动作 ${action}` });
 
     const opId = nextId();
-    const budget = Number.isFinite(timeoutMs) ? timeoutMs : (ACTIONS.get(action) || DEFAULT_OP_TIMEOUT_MS);
+    const budget = Number.isFinite(timeoutMs) ? timeoutMs : budgetFor(link, action);
     return new Promise((resolve, reject) => {
       let settled = false;
       const settle = (fn, value) => {
@@ -222,6 +285,8 @@ function createPhoneService({ authorized, onLog } = {}) {
         fn(value);
       };
       const pending = {
+        action,
+        sentAt: Date.now(),
         settleOk: (data) => settle(resolve, { ok: true, data }),
         settleErr: (error) => settle(reject, error),
       };
@@ -240,7 +305,7 @@ function createPhoneService({ authorized, onLog } = {}) {
       }
       link.pending.set(opId, pending);
       try {
-        link.socket.send(JSON.stringify({ t: 'op', id: opId, sessionId: text(sessionId), action, args: args || {} }));
+        link.socket.send(JSON.stringify({ t: 'op', id: opId, sessionId: text(sessionId), action, args: args || {}, timeout: budget }));
       } catch {
         settle(reject, { code: 'offline', message: '发不出去，那台手机断开了' });
       }

package/lib/mobile/phone/tools.js

@@ -63,6 +63,8 @@ async function run(service, deviceId, sessionId, action, args, signal) {
     if (code === 'offline') throw new Error('那台手机在这期间断开了连接，这一步没有做。');
     if (code === 'timeout') throw new Error(`那台手机 ${message}。可以再试一次，或者先 phone_screen 看看它现在停在哪。`);
     if (code === 'unsupported') throw new Error(`那台手机上装的 App 版本还不支持 ${action}，需要把手机上的 App 升级到最新。`);
+    if (code === 'adb-unavailable') throw new Error('那台手机的无线调试没连上（可能被系统关了），让用户在手机上重新打开无线调试。');
+    if (code === 'warming') throw new Error('手机正在准备后台屏，大约还要几秒，稍等再试。');
     if (code === 'aborted') throw new Error('这一步被取消了。');
     throw new Error(message);
   }
@@ -246,7 +248,7 @@ function installPhoneTools(ctx, deps) {
       try {
         ref = await store.saveImage({
           data: Buffer.from(blob, 'base64'),
-          mediaType: 'image/png',
+          mediaType: data && data.format === 'jpeg' ? 'image/jpeg' : 'image/png',
           name: textOf(args.target, MAX_TEXT) || 'phone-screen',
         });
       } catch (error) {

package/lib/mobile/promo-receiver.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * 商店素材接收端（本机那个 Mac-to-eagle 桌面程序）的坐标。
+ *
+ * 为什么由插件来报：用户在手机 App 里不该填任何东西（2026-11-07 明确要求）。而「这台电脑的
+ * 局域网地址 + 桌面程序的配对密钥」只有插件这一侧知道 —— 它本来就跑在这台电脑上，局域网候选
+ * 地址（`lan-network`）和桌面程序写下的密钥文件都在本机，读一下就能把两样一起交给手机。
+ *
+ * 桌面程序不在跑 / 没装 / 还没生成密钥，就回 null：App 那边据此什么也不做（原图照旧留相册），
+ * 不会因为「这台电脑上没有它」而报错。
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+/** 桌面程序的默认端口（见 Mac-to-eagle `LocalAPIServer.preferredPort`）。 */
+const DESKTOP_PORT = 47291;
+
+/** 密钥文件：桌面程序用 owner-only 权限写在应用数据目录里。 */
+function accessKeyFile() {
+  // 与 Mac-to-eagle `AppPaths.appSupport` 同一套规则：环境变量优先，其次用户应用数据目录。
+  const override = process.env.MACTOEAGLE_DATA_DIR;
+  const base = override && override.startsWith('/')
+    ? override
+    : path.join(os.homedir(), 'Library', 'Application Support', 'MacToEagle');
+  return path.join(base, 'mobile-access-key');
+}
+
+/** 读配对密钥；读不到就 null（不是错误，只说明这台电脑上没有那个程序）。 */
+function readAccessKey() {
+  try {
+    const value = fs.readFileSync(accessKeyFile(), 'utf8').trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 这台电脑上、手机能拨到的那个局域网地址。
+ *
+ * 直接用 `lan-network` 那套候选（它已经滤掉了 VPN / 虚拟网卡、把私网排在前面），取第一条的
+ * 主机部分 —— 素材回传只需要一个能连通的地址，不需要像会话通道那样挨个试。
+ */
+function pickLanHost(lanCandidates) {
+  const first = Array.isArray(lanCandidates) ? lanCandidates.find((item) => item && item.url) : null;
+  if (!first) return null;
+  try {
+    return new URL(first.url).hostname;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 组装给 App 的那一格。
+ *
+ * @param {{ lanCandidates?: Array<{url?: string}> }} options 与 `/connection-info` 同一份候选
+ * @returns {{ url: string, key: string } | null}
+ */
+function promoReceiver({ lanCandidates } = {}) {
+  const key = readAccessKey();
+  if (!key) return null;
+  const host = pickLanHost(lanCandidates);
+  if (!host) return null;
+  return { url: `http://${host}:${DESKTOP_PORT}`, key };
+}
+
+module.exports = {
+  DESKTOP_PORT,
+  accessKeyFile,
+  readAccessKey,
+  pickLanHost,
+  promoReceiver,
+};

package/lib/mobile/stream.js

@@ -37,7 +37,7 @@ const { callSessions } = require('./rpc.js');
 const { unwrap } = require('./envelope.js');
 const { normalizeJobs } = require('./jobs.js');
 const { cutEvent, createToolNameIndex } = require('./wire-cut.js');
-const { noteLiveEvent, drainLiveSteps, liveStepsOf } = require('./live-steps.js');
+const { noteLiveEvent, drainLiveSteps, liveStepsOf, liveStepsTurnOf } = require('./live-steps.js');
 const approvals = require('./approvals.js');
 const questions = require('./questions.js');
 const streamRegistry = require('./stream-registry.js');
@@ -491,9 +491,9 @@ async function handleStream(ctx, req, res) {
    * 按 `key` 替换。**不带 seq**：它不是会话事件，不参与序门与水位（口径同 `session/queue`）。
    * 一行摘要由电脑算好 —— 推理全文与工具参数都不上线路（见 wire-cut.js）。
    */
-  const writeLiveSteps = (steps, full, frameArg) => {
+  const writeLiveSteps = (steps, full, frameArg, turn) => {
     if (!Array.isArray(steps)) return;
-    writeSse(res, { type: 'session/live-steps', sessionId, full, steps }, frameArg, { sealFrame });
+    writeSse(res, { type: 'session/live-steps', sessionId, full, turn: typeof turn === 'number' ? turn : null, steps }, frameArg, { sealFrame });
   };
 
   try {
@@ -521,8 +521,9 @@ async function handleStream(ctx, req, res) {
     // 开流先补一份过程清单：这条流从此刻起只发「变化的那几步」，之前跑过的那些靠这份快照
     // 铺出来（中途进会话 / 重连都走这里）。**一步都没有时就一个字都不发** —— 空快照只在
     // 告诉手机「你手上那份作废」，而那种情况由新的一轮开始时清（App 侧 `resetLiveSteps`）。
+    const openingTurn = liveStepsTurnOf(ctx, sessionId);
     const opening = liveStepsOf(ctx, sessionId);
-    if (!clientGone && opening.length > 0) writeLiveSteps(opening, true, null);
+    if (!clientGone && opening.length > 0) writeLiveSteps(opening, true, null, openingTurn);
 
     if (!clientGone) {
       // 写一帧并把三种结果统一收口：丢增量、需要等 drain、该收尾。
@@ -566,8 +567,10 @@ async function handleStream(ctx, req, res) {
           noteLiveEvent(ctx, sessionId, event);
           // 过程清单的增量：这一步刚开、或某一步的状态变了，把变化的那几行发出去。
           // 排在事件本身之前发顺序不影响判断（清单是「到此刻为止」的旁白，不是内容）。
+          // 带上这一轮的行号：App 按轮隔离，换轮就整份换掉（漏掉 turn/start 也不会串轮）。
+          const liveTurn = liveStepsTurnOf(ctx, sessionId);
           for (const changed of drainLiveSteps(ctx, sessionId)) {
-            const value = { type: 'session/live-steps', sessionId, full: false, steps: [changed] };
+            const value = { type: 'session/live-steps', sessionId, full: false, turn: liveTurn, steps: [changed] };
             if (await pushOrdered(value, null) === 'closed') { clientGone = true; break; }
           }
           if (clientGone) break;

package/lib/mobile/sync-inbox-store.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * 同步收件箱：按 `instanceId` 存密文记录的磁盘小仓库（`$DSH_HOME/storages/mobile-plugin/sync-inbox.json`）。
+ *
+ * 每台电脑给「共享同步组」当一次中转点：别的手机把一条条**已用 SGK 加密**的记录写进来，本机
+ * 只存不读、看不懂内容。记录的形状是 `{ cid, blob, createdAt }`：`cid` 是内容标识（去重键），
+ * `blob` 是 base64 的密文，`createdAt` 由本仓库在写入时打上。
+ *
+ * 三条限制决定了它是一个「短时邮箱」而不是数据库：
+ *  · **TTL 24 小时**：过期的记录在读写时顺手清掉。同步只在手机回前台时跑一次，一天足够；
+ *    再久的记录没有意义，留着只会让文件慢慢变大。
+ *  · **单条 blob 上限 8KB**：记录只是「设备清单的一项 / 一条删除指令」，本该很小；超过这个量
+ *    说明写错了东西，整条拒收。
+ *  · **单次最多 16 条**：一次同步一批设备，超过就该分批。
+ *
+ * 落盘口径照 `mobile-stats.json` 那一套：整份读、整份原子写（临时文件 + rename）。**读坏文件
+ * 时 write 绝不覆盖**——那会把盘上还没发出去的记录静默清空；读失败只有 `read()` 退化成空表。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { dshHome } = require('../shared/paths');
+
+/** 文件格式版本：将来改结构时据此决定丢弃还是迁移。 */
+const VERSION = 1;
+
+/** 记录存活上限：24 小时。 */
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+/** 单条 blob（base64 密文串）的字节上限。 */
+const MAX_BLOB_BYTES = 8 * 1024;
+
+/** 单次写入最多接收的记录条数。 */
+const MAX_RECORDS_PER_WRITE = 16;
+
+/** cid 的长度上限：它只是去重键，不拼路径，但也不该是无限长的串。 */
+const MAX_CID_LEN = 200;
+
+/**
+ * 单实例最多留多少条：TTL 已经把它压到一天的量，这一道只是文件体积的兜底（超了丢最老的）。
+ * 一条 8KB 封顶时，512 条约 4MB，仍可接受。
+ */
+const MAX_STORED_PER_INSTANCE = 512;
+
+/** 收件箱文件：跟其它移动端插件状态放同一个目录（`storages/mobile-plugin/`）。 */
+function defaultFile() {
+  return path.join(dshHome(), 'storages', 'mobile-plugin', 'sync-inbox.json');
+}
+
+/**
+ * 建一个收件箱 store。默认读 `defaultFile()` 的真实时钟；测试可注入 `file` / `now` / `ttlMs`。
+ *
+ * @param {object} [options]
+ * @param {string} [options.file]        落盘文件（测试用）
+ * @param {() => number} [options.now]   当前时刻的取值器
+ * @param {number} [options.ttlMs]       记录存活时长
+ */
+function createSyncInboxStore(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const ttlMs = Number.isFinite(options.ttlMs) && options.ttlMs > 0 ? options.ttlMs : TTL_MS;
+  const file = options.file || defaultFile();
+
+  /** 读盘并解析。文件不存在 → 空库；存在但读不懂 → 抛错（write 会用它，绝不能吞成空库）。 */
+  function readRaw() {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (error) {
+      if (error && error.code === 'ENOENT') return { version: VERSION, instances: {} };
+      throw error;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch (error) {
+      throw Object.assign(new Error(`同步收件箱文件已损坏：${error.message}`), { code: 'sync-inbox-corrupt' });
+    }
+    if (!parsed || typeof parsed !== 'object' || !parsed.instances || typeof parsed.instances !== 'object') {
+      throw Object.assign(new Error('同步收件箱文件形状不对'), { code: 'sync-inbox-corrupt' });
+    }
+    return parsed;
+  }
+
+  /** 只留形状对、未过期的记录。 */
+  function prune(list) {
+    const cutoff = now() - ttlMs;
+    return list.filter((record) => (
+      record
+      && typeof record === 'object'
+      && typeof record.cid === 'string'
+      && typeof record.blob === 'string'
+      && Number.isFinite(record.createdAt)
+      && record.createdAt > cutoff
+    ));
+  }
+
+  /** 原子写：先临时文件再 rename，写一半断电也不留半份 JSON。 */
+  function save(db) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(db), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  }
+
+  /**
+   * 读某实例的记录：`since` 之后、未过期的，按 `createdAt` 升序。
+   * 读盘失败按空表（首页拉不到不该把同步引擎整个卡死）。
+   *
+   * @param {string} instanceId
+   * @param {number} [since] 毫秒时间戳，只取严格晚于它的记录
+   * @returns {Array<{cid: string, blob: string, createdAt: number}>}
+   */
+  function read(instanceId, since) {
+    let db;
+    try {
+      db = readRaw();
+    } catch {
+      return [];
+    }
+    const list = Array.isArray(db.instances[String(instanceId || '')]) ? db.instances[String(instanceId || '')] : [];
+    const sinceMs = Number.isFinite(since) && since > 0 ? since : 0;
+    return prune(list)
+      .filter((record) => record.createdAt > sinceMs)
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .map((record) => ({ cid: record.cid, blob: record.blob, createdAt: record.createdAt }));
+  }
+
+  /**
+   * 写一批记录：按 cid 去重、裁掉越界 / 过期的，返回被接收的 cid 列表。
+   *
+   * **读坏文件会抛错、不覆盖**：盘上那份可能还有别的手机没取走的东西，绝不能当成空库重写。
+   *
+   * @param {string} instanceId
+   * @param {Array<{cid: string, blob: string}>} records
+   * @returns {string[]} 接收到的 cid（重复的也算「已在库里」）
+   */
+  function write(instanceId, records) {
+    const db = readRaw();
+    const id = String(instanceId || '');
+    const byCid = new Map(prune(Array.isArray(db.instances[id]) ? db.instances[id] : []).map((r) => [r.cid, r]));
+    const accepted = [];
+    const at = now();
+    let added = 0;
+    for (const record of Array.isArray(records) ? records : []) {
+      if (!record || typeof record !== 'object') continue;
+      const cid = typeof record.cid === 'string' ? record.cid : '';
+      const blob = typeof record.blob === 'string' ? record.blob : '';
+      if (!cid || cid.length > MAX_CID_LEN || !blob) continue;
+      if (Buffer.byteLength(blob, 'utf8') > MAX_BLOB_BYTES) continue;
+      if (byCid.has(cid)) {
+        accepted.push(cid);
+        continue;
+      }
+      if (added >= MAX_RECORDS_PER_WRITE) break;
+      byCid.set(cid, { cid, blob, createdAt: at });
+      accepted.push(cid);
+      added += 1;
+    }
+    let list = [...byCid.values()].sort((a, b) => a.createdAt - b.createdAt);
+    if (list.length > MAX_STORED_PER_INSTANCE) list = list.slice(list.length - MAX_STORED_PER_INSTANCE);
+    db.version = VERSION;
+    db.instances[id] = list;
+    save(db);
+    return accepted;
+  }
+
+  return { read, write };
+}
+
+module.exports = {
+  createSyncInboxStore,
+  defaultFile,
+  VERSION,
+  TTL_MS,
+  MAX_BLOB_BYTES,
+  MAX_RECORDS_PER_WRITE,
+  MAX_CID_LEN,
+  MAX_STORED_PER_INSTANCE,
+};

package/lib/mobile/sync.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * 设备批量同步的两组接口（`/api/mobile/v1/sync/*`，见 docs/device-batch-sync.md）。
+ *
+ *  · `POST /sync/tickets` —— 已配对的设备替同步组里将来新增的手机申领一次性入场券，连同这台
+ *    电脑的概况（名字 / 实例号 / 中转地址 / 直连候选 …）一起回给导出方，拼进二维码。
+ *  · `POST /sync/inbox` —— 别的手机把 SGK 加密的记录写进本机收件箱。
+ *  · `GET  /sync/inbox` —— 取 `since` 之后、未过期的记录。
+ *
+ * 宿主只存不读收件箱：它不认识 SGK、解不开 blob。真正的内容加解密、去重与「哪条该做什么」
+ * 全在手机上（见契约的「自动同步」节）。这里只做两件事：发券、存取密文。
+ *
+ * 三个 handler 都要求已配对（路由表里走 `guarded`），否则任何人都能领走配对资格、或往这台
+ * 电脑的收件箱塞东西。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { MAX_RECORDS_PER_WRITE } = require('./sync-inbox-store.js');
+
+/**
+ * 构造同步那组 handler。依赖由移动端路由表装配时注入。
+ *
+ * @param {object} deps
+ * @param {object} deps.state           宿主状态（instanceId / name / relayUrl / lanEnabled …）
+ * @param {object} deps.ticketStore     一次性券表（transfer-tickets.js）
+ * @param {object} deps.inboxStore      同步收件箱 store（sync-inbox-store.js）
+ * @param {(port: number) => Array<object>} [deps.safeLanCandidates] 直连候选（与 /connection-info 同一份）
+ * @param {(port: number) => Array<object>} [deps.safeIpv6Candidates] IPv6 直连候选
+ * @param {() => number} [deps.lanPortInUse] 宿主实绑的直连端口
+ * @param {() => string} [deps.hostPlatform] 宿主系统标识
+ * @param {(message: string) => void} [deps.log]
+ */
+function createSyncHandlers(deps = {}) {
+  const state = deps.state || {};
+  const ticketStore = deps.ticketStore || null;
+  const inboxStore = deps.inboxStore || null;
+  const log = typeof deps.log === 'function' ? deps.log : () => {};
+  const instanceIdOf = () => String(state.instanceId || '');
+
+  /** 这台电脑给手机的概况：新手机配对前靠它知道对面是谁、该往哪拨。 */
+  function hostSummary() {
+    const port = typeof deps.lanPortInUse === 'function' ? deps.lanPortInUse() : state.lanPort;
+    // 直连候选与 /connection-info、/pair 那份同口径：关掉局域网直连时两份都为空。
+    const lanUrls = state.lanEnabled && typeof deps.safeLanCandidates === 'function'
+      ? deps.safeLanCandidates(port).map((candidate) => candidate && candidate.url).filter(Boolean)
+      : [];
+    const ipv6Candidates = state.lanEnabled && typeof deps.safeIpv6Candidates === 'function'
+      ? deps.safeIpv6Candidates(port).map((candidate) => candidate && candidate.url).filter(Boolean)
+      : [];
+    const hostPlatform = typeof deps.hostPlatform === 'function' ? deps.hostPlatform() : (state.hostPlatform || process.platform);
+    return {
+      name: state.name || '',
+      instanceId: instanceIdOf(),
+      // 券只能走协议 v2 的 sealed 配对，所以这里报协议 2。
+      proto: 2,
+      relayUrl: state.enabled ? (state.relayUrl || null) : null,
+      lanUrls,
+      ipv6Candidates,
+      hostPlatform,
+    };
+  }
+
+  /** POST /sync/tickets：申领一次性入场券（count 默认 1、封顶 8）。 */
+  async function handleMintTickets(_ctx, req, res) {
+    if (req.method !== 'POST') { sendJson(res, 405, { ok: false, error: 'method not allowed' }); return; }
+    if (!ticketStore) { sendJson(res, 503, { ok: false, error: 'ticket store unavailable' }); return; }
+    // 空体是合法的（count 缺省 1）；读不懂 / 太大也按空对象、让 count 走默认，不因多要一个字段就失败。
+    const body = (await readJsonBody(req, 16 * 1024)) || {};
+    const tickets = ticketStore.mint(instanceIdOf(), body && body.count, {
+      ttlMs: body && body.ttlMs,
+      reusable: body && body.reusable,
+    });
+    sendJson(res, 200, { ok: true, host: hostSummary(), tickets });
+  }
+
+  /** POST /sync/inbox：写入一批密文记录，回被接收的 cid 列表。 */
+  async function handleInboxWrite(_ctx, req, res) {
+    if (!inboxStore) { sendJson(res, 503, { ok: false, error: 'inbox store unavailable' }); return; }
+    const body = await readJsonBody(req);
+    if (!body || !Array.isArray(body.records)) {
+      sendJson(res, 400, { ok: false, error: 'records 必须是数组' });
+      return;
+    }
+    if (body.records.length > MAX_RECORDS_PER_WRITE) {
+      sendJson(res, 400, { ok: false, error: `单次最多写 ${MAX_RECORDS_PER_WRITE} 条记录` });
+      return;
+    }
+    let accepted;
+    try {
+      accepted = inboxStore.write(instanceIdOf(), body.records);
+    } catch (error) {
+      // 读坏盘时 store 会抛错（绝不覆盖已有记录）；这里是那条错误落到请求上的地方。
+      log('sync inbox write failed:', error && error.message);
+      sendJson(res, 500, { ok: false, error: 'internal error' });
+      return;
+    }
+    sendJson(res, 200, { ok: true, accepted });
+  }
+
+  /** GET /sync/inbox?since=<ms>：取 `since` 之后、未过期的记录。 */
+  async function handleInboxRead(_ctx, req, res) {
+    if (!inboxStore) { sendJson(res, 503, { ok: false, error: 'inbox store unavailable' }); return; }
+    let since = 0;
+    try {
+      const query = new URL(req.url || '/', 'http://x').searchParams.get('since');
+      if (query !== null) since = Number(query);
+    } catch { /* 畸形 URL 当 since=0，返回全部未过期的 */ }
+    if (!Number.isFinite(since) || since < 0) since = 0;
+    const records = inboxStore.read(instanceIdOf(), since);
+    sendJson(res, 200, { ok: true, records });
+  }
+
+  /** 同一条路径上按 method 分派写 / 读（宿主 webServer 一个路径只能挂一个 handler）。 */
+  async function handleInbox(ctx, req, res) {
+    if (req.method === 'POST') return handleInboxWrite(ctx, req, res);
+    if (req.method === 'GET') return handleInboxRead(ctx, req, res);
+    sendJson(res, 405, { ok: false, error: 'method not allowed' });
+  }
+
+  return { handleMintTickets, handleInbox, handleInboxWrite, handleInboxRead };
+}
+
+module.exports = { createSyncHandlers };