dsh-mobile-plugin 0.4.1 → 0.4.4

package/lib/mobile/relay-control.js

@@ -10,6 +10,11 @@
  * 改地址 / 关遥控 / 吊销 / 重连 / 重启后台服务会掐断承载当前请求的隧道，所以一律先把响应
  * 吐完再动手，手机看到 200 只代表「已受理」，结果靠重连后读状态。
  *
+ * 换中转地址是唯一**不能**「先落盘再重建」的一项：填错地址的后果就是这台电脑从网上消失，
+ * 而改地址的入口正挂在要被拆掉的那条隧道上。所以它分成两阶段 —— `stage:"prepare"` 拿新
+ * 地址真连一次（不落盘），`stage:"commit"` 才改，并在旧隧道上先发 `MIGRATE` 再重建
+ * （顺序见 lib/relay/migrate.js）。失败台账（`apply-ledger`）在 `/diagnostics` 里报出来。
+ *
  * 注册密钥只进不出：状态里只报「设没设」，手机看不到它。
  */
 
@@ -17,6 +22,8 @@ const { randomBytes } = require('node:crypto');
 
 const core = require('../relay/core.js');
 const pairingApproval = require('../relay/pairing-policy.js');
+const applyLedger = require('../relay/apply-ledger.cjs');
+const { probeInstanceId, verifyRelayRegistration } = require('../relay/verify.js');
 const { canListen } = require('../relay/port-allocator.cjs');
 const { lanCandidates, publicCandidates, ipv6Candidates } = require('../relay/lan-network.cjs');
 const { sendJson, readJsonBody } = require('../shared/http-util');
@@ -27,6 +34,9 @@ const CONFIG_BODY_MAX = 4 * 1024;
 /** 「先回包、再动手」的延迟：装/换一次隧道要几百毫秒，留一点让响应真正写完。 */
 const AFTER_RESPONSE_MS = 120;
 
+/** 换中转地址的两个阶段（见文件头）。不传 `stage` 的老客户端按 `commit` 走。 */
+const STAGES = ['prepare', 'commit'];
+
 /** 测速的单条上限，与控制面 `/probe-relays` 同一档（6 秒）。 */
 const PROBE_TIMEOUT_MS = 6000;
 
@@ -147,6 +157,7 @@ function createRelayControlHandlers(deps) {
     credentials = null,
     activeGuard = () => null,
     probeUrls = null,
+    verifyRelay = null,
   } = deps || {};
 
   /**
@@ -173,6 +184,49 @@ function createRelayControlHandlers(deps) {
     return syncSidecar().catch(() => undefined);
   }
 
+  /**
+   * 把配置推下去，并**等它真的落地**（换地址那一发要等新隧道注册完）。
+   *
+   * 与 `applyNow()` 走同一条路：先让 config store 通知订阅者（桌面面板改配置也是这一条），
+   * 再等这次下发的结果。失败会一路抛上来 —— 换地址失败必须如实回给调用方，而不是先回 200
+   * 再往台账里记一笔。
+   */
+  async function applyNowAndWait() {
+    if (typeof settings.notify === 'function') {
+      try { settings.notify(); } catch { /* 退回收 syncSidecar */ }
+    }
+    return syncSidecar();
+  }
+
+  /**
+   * 试连一次新地址：`stage:"prepare"` 的全部实现。
+   *
+   * **一行都不落盘**，也不碰正在服务的隧道：用临时实例 id（`probeInstanceId`）在一个**新**
+   * 连接上注册，成功立刻断开。地址形状不对、连不上、注册被拒都把原因原样带回调用方 ——
+   * 手机上那句错误就是它。
+   */
+  async function verifyTarget(patch) {
+    const snapshot = typeof status === 'function' ? status() : {};
+    const upstreamPort = Number(snapshot?.localPort);
+    if (!Number.isInteger(upstreamPort) || upstreamPort <= 0) {
+      return { ok: false, message: '宿主没报出本地网页端口，没法试连' };
+    }
+    const runner = typeof verifyRelay === 'function' ? verifyRelay : verifyRelayRegistration;
+    try {
+      await runner({
+        relayUrl: patch.relayUrl,
+        // 临时 id 必须与正式 id 不同：中转按实例 id 认人，拿正式 id 试连会把正在服务的那条顶掉。
+        instanceId: probeInstanceId(state.instanceId),
+        upstreamPort,
+        name: typeof state.name === 'string' ? state.name : '',
+        registerSecret: patch.registerSecret === undefined ? state.registerSecret : patch.registerSecret,
+      });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, message: String(error?.message || error) };
+    }
+  }
+
   /** 地址候选：与控制面 `/addresses` 同一份来源，三份分开报（理由见 lan-network.cjs）。 */
   function addressView() {
     const port = typeof lanPortInUse === 'function' ? lanPortInUse() : state.lanPort;
@@ -238,7 +292,11 @@ function createRelayControlHandlers(deps) {
    * 一次给全：手机进这一页只要一发就能把「配了什么、现在通不通、能填哪条地址」都拿到，
    * 不需要连打四五条再自己拼。
    */
-  async function handleRelayConfig(_ctx, _req, res) {
+  async function handleRelayConfig(ctx, req, res) {
+    // POST 也收在这一条路径上：契约写的是 `POST /api/mobile/v1/relay/config`，而 App 现在打
+    // 的是 `/relay/config/save`（同一件事的两个名字）。宿主的注册器不按方法分派，所以这里
+    // 自己分一次 —— 两条入口共用下面同一份实现，不存在第二套「改配置」。
+    if (req && req.method === 'POST') return handleRelayConfigSave(ctx, req, res);
     if (!wired) return unavailable(res);
     sendJson(res, 200, {
       ok: true,
@@ -248,13 +306,19 @@ function createRelayControlHandlers(deps) {
   }
 
   /**
-   * `POST /api/mobile/v1/relay/config` —— 改配置。
+   * `POST /api/mobile/v1/relay/config/save`（`POST /relay/config` 同一份）—— 改配置。
    *
-   * 两档结果：
-   *  · 只改了不进 sidecar 的项（`preferredLanAddress` / `name`）→ 当场改完、回新配置，
-   *    手机不用重连；
-   *  · 改了会让旁路重配的项（`relayUrl` / `enabled` 相关的其余项）→ 先回 200 再说，
-   *    随后 `syncSidecar` 把新配置推下去，隧道可能断一下。
+   * 三档结果（`stage` 是这次新增的那一格，老客户端不传）：
+   *  · `stage:"prepare"` —— **一行都不落盘**，拿新地址用临时实例 id 真连一次中转，注册上了
+   *    才回 `{ok:true, verified:true, target}`，否则 400 带原因。填错地址不再等于把自己锁在
+   *    门外：先验证，再让用户点保存。
+   *  · `stage:"commit"` —— 落盘并**等这次下发真的完成**：换地址时宿主会先在旧隧道上登记
+   *    迁移、再重建（顺序见 lib/relay/migrate.js），失败会撤销登记并如实回错误。
+   *  · 不传 `stage` —— 老 App 的行为一字不差：先回 200 再让旁路去重配。隧道照旧「先登记
+   *    迁移再重建」，只是结果只能靠重连后读状态（`/diagnostics` 里有失败台账）。
+   *
+   * 只改了不进 sidecar 的项（`preferredLanAddress` / `name` / `manualLanUrl`）时当场改完、
+   * 回新配置，手机不用重连。
    */
   async function handleRelayConfigSave(_ctx, req, res) {
     if (!wired) return unavailable(res);
@@ -268,6 +332,45 @@ function createRelayControlHandlers(deps) {
     if (!parsed.ok) {
       return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: parsed.message } });
     }
+    const stage = body.stage === undefined ? null : body.stage;
+    if (stage !== null && !STAGES.includes(stage)) {
+      return sendJson(res, 400, {
+        ok: false,
+        error: { code: 'bad-request', message: `stage 只能是 ${STAGES.join(' / ')}` },
+      });
+    }
+    // ── 第一段：试连，不落盘 ──
+    if (stage === 'prepare') {
+      const target = parsed.patch.relayUrl;
+      if (target === undefined) {
+        return sendJson(res, 400, {
+          ok: false,
+          error: { code: 'bad-request', message: '试连要带新的 relayUrl（它才是要验证的那个地址）' },
+        });
+      }
+      if (!core.normalizeRelayUrl(target)) {
+        return sendJson(res, 400, {
+          ok: false,
+          verified: false,
+          target: '',
+          error: { code: 'bad-request', message: '空地址没什么可试连的：要关掉中转请直接提交' },
+        });
+      }
+      const probe = await verifyTarget(parsed.patch);
+      if (!probe.ok) {
+        return sendJson(res, 400, {
+          ok: false,
+          verified: false,
+          target: core.normalizeRelayUrl(target),
+          error: { code: 'relay-unverified', message: `这个地址连不上：${probe.message}` },
+        });
+      }
+      // 到这里为止既没调 settings.update、也没碰压载着本请求的那条隧道。
+      return sendJson(res, 200, { ok: true, verified: true, target: core.normalizeRelayUrl(target) });
+    }
+    // ── 第二段：落盘（`stage:"commit"` 或不传 stage）──
+    const urlChanged = parsed.patch.relayUrl !== undefined
+      && core.normalizeRelayUrl(parsed.patch.relayUrl) !== core.normalizeRelayUrl(state.relayUrl);
     try {
       // `notify: false` 是关键：订阅者（装配层那个 watch）一跑就会重配隧道，而那一发响应
       // 还没吐完。所以先只落盘，回完包再通知。
@@ -284,6 +387,20 @@ function createRelayControlHandlers(deps) {
       await resolveLanPort().catch(() => undefined);
     }
     const view = { ok: true, config: configView(state), addresses: addressView() };
+    // 显式 commit 且换了地址：必须等这次下发的结果。旧隧道在这期间还开着（见
+    // lib/relay/migrate.js 的 linger），所以这一发响应仍然送得回去。
+    if (stage === 'commit' && urlChanged) {
+      try {
+        await applyNowAndWait();
+      } catch (error) {
+        return sendJson(res, 502, {
+          ok: false,
+          config: configView(state),
+          error: { code: 'relay-switch-failed', message: String(error?.message || error) },
+        });
+      }
+      return sendJson(res, 200, { ...view, migrated: true });
+    }
     sendJson(res, 200, view);
     // 推给旁路：改地址 / 端口 / 局域网开关都会重配隧道与直连，这一下多半会断。
     afterResponse(() => applyNow());
@@ -480,6 +597,10 @@ function createRelayControlHandlers(deps) {
    * 隧道为什么断、局域网为什么没起来，答案在故障台账与端口自检这两处；两条一起给，
    * 手机上一页就能回答「这台到底怎么了」。
    *
+   * `apply` 那一格是「按新配置重建隧道」的失败台账：以前那一发被 `.catch(() => undefined)`
+   * 吞掉，换地址失败在手机上表现为「保存成功、然后永久离线」，谁也说不清为什么。它只留最近
+   * 一条（时间 + 一句话 + 当时要切过去的地址），不带堆栈 —— 宿主内部路径对手机没用。
+   *
    * **不搬堆栈**：台账的 message 只取第一行，截断 300 字。
    */
   async function handleRelayDiagnostics(_ctx, _req, res) {
@@ -488,6 +609,8 @@ function createRelayControlHandlers(deps) {
     sendJson(res, 200, {
       ok: true,
       faults: faultsView(),
+      /** 最近一次「按新配置重建隧道失败」的错误与时间（见上方说明）。 */
+      apply: applyLedger.view(),
       addresses: addressView(),
       /** 端口那两格的来历：「配置里写的」与「真的在监听的」可能不同。 */
       port: {
@@ -523,4 +646,5 @@ module.exports = {
   PROBE_MAX_URLS,
   FAULT_TAIL,
   NAME_MAX_CHARS,
+  STAGES,
 };

package/lib/mobile/session-cwd.js

@@ -0,0 +1,28 @@
+'use strict';
+
+/**
+ * 会话的工作区目录：正文里相对路径的解析基准。
+ *
+ * 两处在用，口径必须是同一个 —— 正文里的图片（`local-images.js` 按它把 `deliverables/a.png`
+ * 换成内嵌字节）与点开正文里的文件链接（`session-file.js` 按它找文件）。
+ *
+ * 它是**可选的旁路**：取不到就回空串，调用方一律退回「只认绝对路径」的旧行为。这条跑在
+ * 历史投影与 SSE 的同一条管线上，抛一次会让整页消息或一整帧事件一起挂掉，所以这里不抛。
+ */
+
+const { unwrap } = require('./envelope.js');
+const { callSessions } = require('./rpc.js');
+
+/** 会话的工作区目录（相对路径的解析基准）。取不到就回空串，由调用方决定怎么办。 */
+async function cwdOf(ctx, sessionId) {
+  try {
+    const { value } = unwrap(await callSessions(ctx, 'list', {}));
+    const items = (value && value.items) || [];
+    const row = items.find((item) => item && item.sessionId === sessionId);
+    return row && typeof row.cwd === 'string' ? row.cwd : '';
+  } catch {
+    return '';
+  }
+}
+
+module.exports = { cwdOf };

package/lib/mobile/session-file.js

@@ -23,6 +23,7 @@ const { sendJson, readJsonBody } = require('../shared/http-util');
 const { signedPath } = require('../shared/e2ee-request');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
+const { cwdOf } = require('./session-cwd.js');
 const { presentedPathsOf } = require('./history-derive.js');
 
 /** 单文件上限：手机内存与中转链路都不适合再大的东西（超出如实报 413）。 */
@@ -105,18 +106,6 @@ function isInsideWorkspace(cwd, target) {
   return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
-/** 会话的工作区目录（相对路径的解析基准）。取不到就回空串，由调用方决定怎么办。 */
-async function cwdOf(ctx, sessionId) {
-  try {
-    const { value } = unwrap(await callSessions(ctx, 'list', {}));
-    const items = (value && value.items) || [];
-    const row = items.find((item) => item && item.sessionId === sessionId);
-    return row && typeof row.cwd === 'string' ? row.cwd : '';
-  } catch {
-    return '';
-  }
-}
-
 /**
  * POST { sessionId, path } → 该文件的原始字节。
  *

package/lib/mobile/stats-collect.cjs

@@ -7,15 +7,23 @@
  * （宿主累计值 − 账本水位 = 这次入账的量），零依赖，代价是入账日期取「插件看到增量的那一天」，
  * 跨零点的一轮会落在后一天。首采会把历史全量入账，日期取它最后一次活动的日期，算一次性回填。
  *
- * 采集是按需的（打开统计页 / 下拉刷新 / 清理已归档前补一刀），没有后台定时器。
+ * 采集分三条路进来：打开统计页 / 下拉刷新（`DEFAULT_BUDGET_MS`）、宿主侧每几分钟自己跑一轮
+ * （`PERIODIC_INTERVAL_MS`，只会读真有变动的会话）、以及删除会话之前的那一刀补采。
  *
  * 清理前那次补采（`skipPreview`）不读「最后一句」：那一步要读会话日志，是整轮最重的一趟，
  * 而删除不可恢复、时间又卡在请求预算里。宁可让首次见到的会话卡片少一行摘要。
+ *
+ * 模型维度（`book.models`）是**近似**，写清楚省得以后有人当账本该有的精度去用：增量记在
+ * 「采集到它的这一刻这条会话正在用的模型」名下（`readSessionModel`）。水位法只认观测点，
+ * 会话中途换模型、而换模型到下一次采集之间的量分不开了，整段归到换后的那个 —— 这与首采
+ * 回填记在「最后活动那天」是同一种近似。想要真按模型拆，得让宿主按模型累计用量，那是另一
+ * 件事（现在的投影只有会话级累计）。
  */
 
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const { sessionPreviewFor } = require('./session-preview.js');
+const { listTitle } = require('./history-derive.js');
 const ledger = require('./stats-ledger.cjs');
 
 /** 同一条会话两次采集之间的最小间隔（打开页面时的重复请求直接复用上一轮结果）。 */
@@ -43,7 +51,26 @@ const RECENT_WINDOW_MS = 7 * 86400_000;
  */
 const DEFAULT_BUDGET_MS = 1500;
 
+/**
+ * 删除会话之前那次补采的预算。
+ *
+ * 统计页那 1.5 秒是为了别让用户转好久；删除是不可恢复的，值得多等几秒把账补全，但不能
+ * 超过 App 单发请求的 8 秒总预算。两条删除路径（手机那个「清理已归档」按钮、agent 的
+ * 删除工具）共用这一个数，改预算别只改一处。
+ */
+const DELETING_COLLECT_BUDGET_MS = 6_000;
+
+/** 宿主侧定期采集的间隔。
+ *
+ * 以前只在「有人打开统计页 / 下拉刷新 / 点清理」时采，水位差就把「上次观测到现在」的整段
+ * 用量记在**观测到它的那一天**：连着几天没打开页面，那几天的量全压到最后一天，按天图上是
+ * 一片空白加一根尖柱。定期跑一轮之后，归属误差从「几天」收到「几分钟」，顺带把「清理前
+ * 没采到的那一截」一起收掉。一轮的开销靠 `seenUpdatedAt` 兜住：一点没动的会话连投影都不读。
+ */
+const PERIODIC_INTERVAL_MS = 5 * 60_000;
+
 const num = ledger.num;
+const billedOf = ledger.billedOf;
 
 function normalizePath(value) {
   if (typeof value !== 'string') return '';
@@ -62,22 +89,28 @@ async function listSessions(ctx) {
   }
 }
 
-/** cwd → 项目展示名。宿主没给可用的工作区表就返回空表，卡片上就不显示项目名。 */
+/**
+ * cwd → 项目展示名。
+ *
+ * 宿主 `workspace.list` 的形状是「数组或 `{ items }`」，条目上目录叫 `path`、展示名是
+ * `title`（与 App 侧那份 `Workspace` 同一套）。以前按 `{ workspaces }` + `cwd` / `name`
+ * 读，三个字段一个都对不上，真机上卡片从来就没有过项目名——而这条取不到的错是静默的。
+ */
 async function workspaceNames(ctx) {
-  const byCwd = new Map();
+  const byPath = new Map();
   try {
     const { value } = unwrap(await ctx.apiProxy.workspace.list({ rpcId: 'mobile', method: 'workspace.list', payload: {} }));
-    const workspaces = value && Array.isArray(value.workspaces) ? value.workspaces : [];
-    for (const workspace of workspaces) {
+    const items = Array.isArray(value) ? value : (value && Array.isArray(value.items) ? value.items : []);
+    for (const workspace of items) {
       if (!workspace || typeof workspace !== 'object') continue;
-      const cwd = normalizePath(workspace.cwd);
-      const name = typeof workspace.name === 'string' ? workspace.name : '';
-      if (cwd && name) byCwd.set(cwd, name);
+      const dir = normalizePath(workspace.path);
+      const name = typeof workspace.title === 'string' ? workspace.title : '';
+      if (dir && name) byPath.set(dir, name);
     }
   } catch {
     /* 拿不到项目名不影响数字 */
   }
-  return byCwd;
+  return byPath;
 }
 
 /** 一条会话的投影（tokenUsage / sessionStats / contextBreakdown）；读不到返回 null。 */
@@ -131,6 +164,50 @@ function hasDelta(usage) {
   return Object.values(usage).some((value) => value > 0);
 }
 
+/**
+ * 会话标题：宿主列表摘要里的 title 投影（与 `/sessions` 那条列表同一份来源，见 `listTitle`）。
+ *
+ * 摘要顶层的 `title` 是不存在的字段（以前照着它读，于是账本里几百条记录的标题全是空串，
+ * 卡片只能退到目录名兜底）。这里只取投影里那个真标题：取不到就留空，由 App 用目录末段兜底。
+ */
+function titleOf(summary) {
+  const projected = summary && summary.projections && summary.projections.values
+    ? summary.projections.values.title
+    : '';
+  return typeof projected === 'string' ? projected : '';
+}
+
+/**
+ * 这条会话此刻的渠道 + 模型（`session.models` 的 `current`），读不到返回 null。
+ *
+ * 展示名要另外去 `groups` 里对：宿主 `current` 只给 id，页面那块模型卡得画「渠道名 / 模型名」。
+ * 对不上（模型已从目录里消失、渠道被卸载）就留空串，归属仍按 id 记 —— 名字对不上不等于这条
+ * 用量没有主，而且账本读盘也不拿展示名当有效性判据（见 `sanitizeModelSelection`）。
+ *
+ * 任何异常都返回 null：统计是旁路，不能因为这条读失败就把整轮记账丢掉。
+ */
+async function readSessionModel(ctx, sessionId) {
+  try {
+    const { value, error } = unwrap(await callSessions(ctx, 'models', { sessionId }));
+    if (error || !value || typeof value !== 'object') return null;
+    const current = value.current;
+    if (!current || typeof current !== 'object') return null;
+    const selection = ledger.sanitizeModelSelection({ provider: current.provider, model: current.model });
+    if (!selection) return null;
+    const groups = Array.isArray(value.groups) ? value.groups : [];
+    const group = groups.find((item) => item && item.id === selection.provider);
+    const models = group && Array.isArray(group.models) ? group.models : [];
+    const entry = models.find((item) => item && item.id === selection.model);
+    return ledger.sanitizeModelSelection({
+      ...selection,
+      providerName: group ? group.name : '',
+      modelName: entry ? entry.name : '',
+    });
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 采集串行化：同一时刻只跑一轮。
  *
@@ -168,12 +245,17 @@ async function collectOnce(ctx, options = {}) {
 
   const wanted = Array.isArray(options.sessionIds) ? new Set(options.sessionIds) : null;
   const names = await workspaceNames(ctx);
+  // 这一轮有没有真改过账本：定期采集在空闲时应当一个字节都不写（见 PERIODIC_INTERVAL_MS）。
+  let touched = false;
 
   // 消失检测只在「采整份列表」时做：定向补采拿到的是子集，凭它判「会话没了」会误标。
   if (!wanted) {
     const liveIds = new Set(items.map((item) => item.sessionId));
     for (const [sessionId, record] of Object.entries(book.sessions)) {
-      if (!liveIds.has(sessionId)) record.gone = true;
+      if (!liveIds.has(sessionId) && !record.gone) {
+        record.gone = true;
+        touched = true;
+      }
     }
   }
 
@@ -203,10 +285,27 @@ async function collectOnce(ctx, options = {}) {
       const summary = targets[index];
       const sessionId = summary.sessionId;
       const record = book.sessions[sessionId];
+      const title = titleOf(summary);
+      /** 名字补上 / 重新出现在列表里：这两件都要落盘，数字一个不动。 */
+      const renameIfNeeded = () => {
+        if (title && title !== record.title) {
+          record.title = title;
+          touched = true;
+        }
+        if (record.gone) {
+          record.gone = false;
+          touched = true;
+        }
+      };
       if (!options.force && record && record.collectedAt && now - record.collectedAt < COLLECT_INTERVAL_MS) {
         // 还没到下一次采集的点：只把可能变了的名字补上，数字一个字不动。
-        if (typeof summary.title === 'string' && summary.title) record.title = summary.title;
-        record.gone = false;
+        renameIfNeeded();
+        continue;
+      }
+      // 宿主摘要的 `updatedAt` 与上次读到的一模一样 = 这条一点没动过，水位差必然是 0。
+      // 定期采集每几分钟一轮，靠这一条把空闲那几轮压成「一次列表调用」。
+      if (!options.force && record && record.seenUpdatedAt && num(summary.updatedAt) <= num(record.seenUpdatedAt)) {
+        renameIfNeeded();
         continue;
       }
 
@@ -224,6 +323,23 @@ async function collectOnce(ctx, options = {}) {
       const cwd = normalizePath(summary.cwd);
       const workspaceName = cwd ? names.get(cwd) : undefined;
 
+      // 模型只在「这一轮真会往模型表里记东西」时才去读：三种情形 —— 首采（全量要挂到模型
+      // 名下）、有增量、以及老账本里那条会话已经有量却还没有模型（升级当天的回填）。
+      // 其余轮次一条都不读，否则定期采集每 5 分钟就给每条会话多一趟宿主调用。
+      const needsModel = firstSight || hasDelta(delta) || Boolean(record && !record.model && billedOf(record.billed) > 0);
+      const model = needsModel ? await readSessionModel(ctx, sessionId) : null;
+      // 老账本回填：这条会话在升级前记过累计量，但它没有模型维度，模型卡会是 0 —— 把它那条
+      // 会话的累计量一次性复制进模型桶。日期与会话最后一次活动那天一致（同一条近似）。
+      // 首采不在这里做：首采的 delta 就是全量，已经跟着 applyDelta 记进模型桶了，再补一次会翻倍。
+      if (model && record && !record.model && billedOf(record.billed) > 0 && !firstSight) {
+        ledger.applyModelUsage(book, {
+          model,
+          day: ledger.dayKeyOf(num(record.lastAt) || lastActiveAt),
+          usage: record.billed,
+        });
+        touched = true;
+      }
+
       if (hasDelta(delta) || firstSight) {
         // 最后一条消息的摘要只在真有增量时去读（它是日志，属于重活）：
         // 卡片上那一行「最后一句说了什么」比什么都更能让人认出这是哪条会话。
@@ -242,18 +358,26 @@ async function collectOnce(ctx, options = {}) {
           sessionId,
           at: firstSight ? lastActiveAt : now,
           delta: firstSight ? host : delta,
-          title: typeof summary.title === 'string' ? summary.title : '',
+          title,
           cwd,
           workspaceName,
           lastText,
+          model,
         });
+        touched = true;
       }
 
       const saved = book.sessions[sessionId];
       if (saved) {
+        // 这一刻的模型落在这条会话的记录上：它换过模型的话，下一次增量就记到新模型名下
+        // （这一轮的量仍按「采集这一刻」归，见文件头）。
+        if (model) saved.model = model;
         saved.watermark = host;
         saved.collectedAt = now;
         saved.gone = false;
+        // 记下这一次读到的那条会话 `updatedAt`：下一轮它没变就不用再读投影（见文件头的间隔说明）。
+        saved.seenUpdatedAt = num(summary.updatedAt) || now;
+        touched = true;
         // 上下文构成是**这条会话**的快照：跟着记录走，页面才能说清「这是哪条会话的构成」。
         // 以前全局只留一份、每轮被最后读完的那条覆盖（四条并发，谁后回是谁），
         // 于是卡片上的构成跟用户此刻在用的那条毫无关系。
@@ -272,15 +396,22 @@ async function collectOnce(ctx, options = {}) {
 
   await Promise.all(Array.from({ length: CONCURRENCY }, worker));
 
-  ledger.trim(book);
-  ledger.saveLedger(book);
+  // 一点没改就别写盘：定期采集空闲时要真的不花钱，而整份 JSON 每次重写一遍不是免费的。
+  if (touched) {
+    ledger.trim(book);
+    ledger.saveLedger(book);
+  }
   return book;
 }
 
 module.exports = {
   COLLECT_INTERVAL_MS,
   DEFAULT_BUDGET_MS,
+  DELETING_COLLECT_BUDGET_MS,
+  PERIODIC_INTERVAL_MS,
   collectStats,
   hostUsageOf,
   diffUsage,
+  titleOf,
+  readSessionModel,
 };