dsh-mobile-plugin 0.4.1 → 0.4.4

package/lib/mobile/stats-ledger.cjs

@@ -8,8 +8,13 @@
  *
  * 口径（与桌面 dsh-context 的每日账本一致，只保留手机用得着的部分）：一天的账落在「观测到
  * 增量」的宿主本地日期上；计费 token = 未命中输入 + 缓存读 + 缓存写 + 输出，四个桶分开存；
- * 会话卡片只留最近 `MAX_SESSIONS` 条，更老的退场（`retired`）但量仍留在按天账上，水位也留着
- * —— 水位一丢，那条会话下次有动作会被当成首采、把整段历史重记一遍。
+ * 每条会话一条记录，范围内有量的都上卡片 —— 卡片条数就是页面那个「会话」数字，所以
+ * **不按展示需要裁剪**（裁了那个数字就变成上限值了，不再是真的条数）。
+ *
+ * 第三张表是模型维度 `models`：按「渠道 + 模型」攒量，服务统计页那块「模型用量」。它账的是
+ * 同一个增量 —— 也就是说这里没有「按模型拆过一遍」的原始数据，模型名取自**采集那一刻**这条
+ * 会话正在用的那个选择（见 stats-collect.cjs 文件头），会话中途换模型的那一段整体归到换后的
+ * 那个名下。这是水位法本来就有的近似，不是这里另加的简化。
  *
  * 只做纯数据（读写 + 折算），不碰网络；采集在 stats-collect.cjs，路由在 stats.js。
  */
@@ -18,20 +23,20 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const paths = require('../shared/paths');
+const { identifyVendor, vendorLogoOf } = require('./model-vendors.js');
 
 /** 账本格式版本：将来改结构时据此决定是丢弃还是迁移。 */
 const VERSION = 1;
 
-/** 会话卡片的条数上限（按最后活动时间保留最近的）。 */
-const MAX_SESSIONS = 200;
-
 /**
- * 退场卡片（已不在最近 200 条里、只留水位与身份）的条数上限。
+ * 账本里会话记录的条数上限（按最后活动时间删最老的）。
  *
- * 退场记录不展示，存在只为「它再活过来时别重记一遍历史」；每条一百来字节，
- * 留这么多足够覆盖一台机器几年的会话，再老的真删掉。
+ * 这是**文件存储**的兜底，不是统计口径：页面上那个「会话」数字就是这条记录的条数，按展示
+ * 需要裁到两百就会变成一个永远不动的上限值。所以档位抬到一台机器几年也用不完 —— 一台机器
+ * 一天最多新增百来条（子代理各算一条），四千条约等于一个月的重度使用；真要顶到，删的也是
+ * 最老的整条记录，按天的总账不受影响。
  */
-const MAX_RETIRED = 2000;
+const MAX_RECORDS = 4000;
 
 /** 按天的账保留天数（约三年；一天一百多字节，超出的从最老的开始裁）。 */
 const MAX_DAYS = 1100;
@@ -41,7 +46,8 @@ const MAX_DAYS = 1100;
  *
  * 它存在只为回答「这张卡片在这个范围里用了多少」：页面的三档范围最大 30 天，
  * 再留一倍余量足够；更老的日期按天的总账仍然还在，只是卡片不再按那条会话拆得开。
- * 不封顶的话，两百条会话 × 三年就是一份几十 MB 的 JSON，每次采集都要整份读写。
+ * 不封顶的话，几千条会话 × 三年就是一份几十 MB 的 JSON，每次采集都要整份读写。
+ * 超过这个窗口没再动过的记录会被 `trim` 瘦身（明细、最后一句、上下文构成一起丢掉）。
  */
 const MAX_DAILY_DAYS = 62;
 
@@ -57,6 +63,15 @@ const HEATMAP_DAYS = 52 * 7;
 /** 每张会话卡片上留的最后一条消息摘要长度：卡片一行装得下的大致字数。 */
 const LAST_TEXT_MAX = 120;
 
+/**
+ * 模型标识的落盘上限（与 `session-models.js` 下发目录时那份截断一致）。
+ *
+ * 渠道 / 模型的 id 与展示名由宿主给，长度不可控；账本每次采集都要整份读写，一条几百 KB 的
+ * 名字会把文件撑成没法解释的大小。id 与目录同一套上限，两边的 id 才拼得出同一个桶名。
+ */
+const MODEL_PROVIDER_MAX = 256;
+const MODEL_NAME_MAX = 512;
+
 /** 用量字段：四个 token 桶 + 轮次/步数/耗时。顺序即写盘顺序，便于人工比对。 */
 const USAGE_KEYS = [
   'uncachedInputTokens',
@@ -80,7 +95,56 @@ function emptyDay() {
 }
 
 function emptyLedger() {
-  return { version: VERSION, updatedAt: 0, days: {}, sessions: {}, composition: null };
+  return { version: VERSION, updatedAt: 0, days: {}, sessions: {}, models: {}, composition: null };
+}
+
+function textOf(value, max) {
+  return typeof value === 'string' ? value.slice(0, max) : '';
+}
+
+/**
+ * 模型名 → 桶名。任一为空都算「不知道是哪个模型」，返回空串表示不要建桶。
+ *
+ * 别把空的那半拼成 `\u0000` 之后当垃圾筒：宿主读不到当前模型、或某个插件不上报渠道时，
+ * 所有那类用量都会挤进同一个 `\u0000xxx` 桶，页面上一条「模型」指向不存在的东西。
+ */
+function modelKeyOf(provider, model) {
+  return provider && model ? `${provider}\u0000${model}` : '';
+}
+
+/**
+ * 模型选择的清洗：provider / model 缺一个才算没有，展示名缺了留空串。
+ *
+ * 展示名不算有效性判据：目录里那条模型下架了、渠道被卸载了，都只是「名字对不上」，这条用量
+ * 该记在哪个渠道哪个模型名下仍然是确定的。以前把「展示名齐不齐」当成归属是否有效的判据，
+ * 于是这种记录一重启读盘就变回「没有模型」，下一轮又触发一次老账本回填，同一段累计量在
+ * 模型桶里翻倍。
+ *
+ * 展示名按「非空才覆盖」的规矩用，空串不能把已经记下的名字擦掉。
+ */
+function sanitizeModelSelection(source) {
+  if (!source || typeof source !== 'object') return null;
+  const provider = textOf(source.provider, MODEL_PROVIDER_MAX);
+  const model = textOf(source.model, MODEL_NAME_MAX);
+  if (!provider || !model) return null;
+  return {
+    provider,
+    providerName: textOf(source.providerName, MODEL_NAME_MAX),
+    model,
+    modelName: textOf(source.modelName, MODEL_NAME_MAX),
+  };
+}
+
+function emptyModelBucket(selection) {
+  return {
+    provider: selection.provider,
+    providerName: selection.providerName,
+    model: selection.model,
+    modelName: selection.modelName,
+    billed: emptyUsage(),
+    daily: {},
+    lastAt: 0,
+  };
 }
 
 /** 账本文件：`$DSH_HOME/mobile-stats.json`（DSH_HOME 在调用时解析，便于测试注入）。 */
@@ -121,6 +185,18 @@ function startDayOf(range, now) {
   return null;
 }
 
+/**
+ * `YYYY-MM-DD` → 那天本地零点的毫秒数。
+ *
+ * 模型桶只有「记在哪一天」，没有更细的时刻（增量是按会话水位差算的，采集那一刻才知道量，
+ * 不知道它具体花在哪几分钟）。老账本回填那一笔只有日期，`lastAt` 只能落到那天零点上 ——
+ * 它只用于「计费量相同」时的排序，差半天不要紧。
+ */
+function dayStartAt(day) {
+  const [year, month, date] = day.split('-').map((part) => Number(part));
+  return new Date(year, month - 1, date).getTime();
+}
+
 function sanitizeUsage(source) {
   const usage = emptyUsage();
   if (!source || typeof source !== 'object') return usage;
@@ -178,19 +254,48 @@ function sanitizeLedger(raw) {
         lastAt: num(value.lastAt),
         collectedAt: num(value.collectedAt),
         gone: value.gone === true,
-        // 退场 = 这条卡片已经不在最近 MAX_SESSIONS 里，只留水位与身份。
-        retired: value.retired === true,
+        // 上一次读到的那条会话 `updatedAt`：定期采集靠它跳过「一点没动」的会话。
+        seenUpdatedAt: num(value.seenUpdatedAt),
         billed,
         // 这条会话自己那份按天用量：卡片上的数字要跟着页面范围走（见 `rangeUsageOf`）。
         daily,
         // 最后一次观测到的上下文构成：跟着会话走，不再全局只留一份。
         composition: readComposition(value.composition),
+        // 采集那一刻这条会话用的渠道 + 模型。升级前的老记录没有这一栏，当没有。
+        model: sanitizeModelSelection(value.model),
         // 水位是「宿主那边这条会话的累计值」，缺省为 null 表示还没采过（首采全量入账）。
         watermark: value.watermark && typeof value.watermark === 'object' ? sanitizeUsage(value.watermark) : null,
       };
     }
   }
 
+  // 模型维度。老账本没有这张表是正常的（升级前没记过），按空处理 —— 别因为它缺字段就把
+  // 整份账本当坏的丢掉，那是 `version` 的事。
+  if (raw.models && typeof raw.models === 'object') {
+    for (const value of Object.values(raw.models)) {
+      const selection = sanitizeModelSelection(value);
+      if (!selection) continue;
+      const key = modelKeyOf(selection.provider, selection.model);
+      if (!key) continue;
+      const daily = {};
+      if (value.daily && typeof value.daily === 'object') {
+        for (const [day, usageOfDay] of Object.entries(value.daily)) {
+          if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || !usageOfDay || typeof usageOfDay !== 'object') continue;
+          daily[day] = sanitizeUsage(usageOfDay);
+        }
+      }
+      ledger.models[key] = {
+        provider: selection.provider,
+        providerName: selection.providerName,
+        model: selection.model,
+        modelName: selection.modelName,
+        billed: sanitizeUsage(value.billed),
+        daily,
+        lastAt: num(value.lastAt),
+      };
+    }
+  }
+
   if (raw.composition && typeof raw.composition === 'object') {
     // 老账本只有一份全局构成（每轮被最后读完的那条覆盖）。留着当兜底：
     // 没有任何一条会话带自己的构成时才用它。
@@ -237,35 +342,53 @@ function forgetLedger() {
 }
 
 /**
- * 裁剪：会话卡片按最后活动时间保留最近的。
+ * 裁剪：只防文件无限长，不动「有多少条会话」这个口径。
  *
- * 超出的卡片**不删记录、只标退场**（`retired`）：水位与身份留着，那条会话以后再活跃
- * 就不会被当成首采、把整段历史重记一遍。退场记录自己也封顶，最老的先删。
+ * 两道都跟**存储**有关，跟页面显示无关：
+ *  - 每条记录自己那份按天用量只服务三档范围里最大的 30 天，最老的日子从它自己的账上裁掉，
+ *    按天的总账不动；
+ *  - 超过 `MAX_DAILY_DAYS` 没再动过的记录顺手瘦身：明细、最后一句、上下文构成一起丢掉，
+ *    只留身份 + 累计 + 水位。它照旧算一条会话（`all` 那档用累计值），只是最近这几档本来就
+ *    轮不到它，留着一百多字节的摘要和几十天明细纯属占地方。
+ *
+ * 记录条数超过 `MAX_RECORDS` 才真删，删最老的整条：水位跟着一起没，那条会话以后再活跃会
+ * 被当成首采、把整段历史重记一遍 —— 所以档位要抬到几年也用不完，别拿它当展示上限。
  */
 function trim(ledger) {
-  const sessionIds = Object.keys(ledger.sessions);
-  if (sessionIds.length > MAX_SESSIONS) {
-    // 已经在退场里的不参与排位：它们本来就该往后排，重新算一遍只会来回抖动。
-    const live = sessionIds.filter((id) => ledger.sessions[id].retired !== true);
-    const retired = sessionIds.filter((id) => ledger.sessions[id].retired === true);
-    if (live.length > MAX_SESSIONS) {
-      live.sort((a, b) => num(ledger.sessions[b].lastAt) - num(ledger.sessions[a].lastAt));
-      for (const id of live.slice(MAX_SESSIONS)) ledger.sessions[id].retired = true;
+  const staleBefore = addDays(dayKeyOf(Date.now()), -MAX_DAILY_DAYS);
+  for (const record of Object.values(ledger.sessions)) {
+    if (record.daily) {
+      const own = Object.keys(record.daily).sort();
+      if (own.length > MAX_DAILY_DAYS) {
+        for (const day of own.slice(0, own.length - MAX_DAILY_DAYS)) delete record.daily[day];
+      }
     }
-    // 退场池按最后活动时间留最新的那一批，其余真删。
-    const pool = [...retired, ...live.slice(MAX_SESSIONS)];
-    if (pool.length > MAX_RETIRED) {
-      pool.sort((a, b) => num(ledger.sessions[b].lastAt) - num(ledger.sessions[a].lastAt));
-      for (const id of pool.slice(MAX_RETIRED)) delete ledger.sessions[id];
+    const lastDay = num(record.lastAt) > 0 ? dayKeyOf(num(record.lastAt)) : '';
+    if (lastDay && lastDay < staleBefore) {
+      record.daily = {};
+      record.lastText = '';
+      record.composition = null;
     }
   }
-  // 每条会话自己那份按天用量也有上限：它只服务「这张卡片在这个范围里用了多少」，
-  // 最老的那些日子从它自己的账上裁掉，按天的总账不动。
-  for (const record of Object.values(ledger.sessions)) {
-    if (!record.daily) continue;
-    const own = Object.keys(record.daily).sort();
-    if (own.length > MAX_DAILY_DAYS) {
-      for (const day of own.slice(0, own.length - MAX_DAILY_DAYS)) delete record.daily[day];
+  const sessionIds = Object.keys(ledger.sessions);
+  if (sessionIds.length > MAX_RECORDS) {
+    sessionIds.sort((a, b) => num(ledger.sessions[b].lastAt) - num(ledger.sessions[a].lastAt));
+    for (const id of sessionIds.slice(MAX_RECORDS)) delete ledger.sessions[id];
+  }
+  // 模型桶只裁它自己那份按天用量，不按条数裁：一台机器用过的「渠道 + 模型」组合是十几个的
+  // 量级，裁条数没有意义；而 `daily` 与每条会话那份一样只服务最近这几档范围。
+  if (ledger.models && typeof ledger.models === 'object') {
+    for (const [key, bucket] of Object.entries(ledger.models)) {
+      if (!bucket || typeof bucket !== 'object') {
+        delete ledger.models[key];
+        continue;
+      }
+      const own = Object.keys(bucket.daily || {}).sort();
+      if (own.length > MAX_DAILY_DAYS) {
+        for (const day of own.slice(0, own.length - MAX_DAILY_DAYS)) delete bucket.daily[day];
+      }
+      // 一点量都没有、明细也裁空了的桶留着只会让页面出现一张全 0 的卡。
+      if (billedOf(bucket.billed) === 0 && Object.keys(bucket.daily || {}).length === 0) delete ledger.models[key];
     }
   }
   const days = Object.keys(ledger.days).sort();
@@ -285,20 +408,55 @@ function emptySession(at) {
     lastAt: 0,
     collectedAt: 0,
     gone: false,
-    retired: false,
+    seenUpdatedAt: 0,
     billed: emptyUsage(),
     daily: {},
     composition: null,
+    model: null,
     watermark: null,
   };
 }
 
+/**
+ * 只往模型表里记一笔（纯函数，原地改并返回账本）。
+ *
+ * 它不碰 `days` 也不碰 `sessions`：这唯一一个调用点是「老账本回填」—— 一条会话在升级前
+ * 已经记过累计量，但账本里没有模型维度；补这张卡的时候把它的累计量在**那条会话的记录上**
+ * 已经存在的那份 `billed` 复制进模型桶即可，按天总账与卡片都不该因此多出一份量。
+ *
+ * `day` 与 `days` / `sessions.daily` 那次记账用同一个日期（首采回填也是同一天），
+ * `at` 可不传：老账本的记录上只有最后活动日，落到那天零点就够了（见 `dayStartAt`）。
+ */
+function applyModelUsage(ledger, entry) {
+  const selection = sanitizeModelSelection(entry && entry.model);
+  if (!selection) return ledger;
+  const key = modelKeyOf(selection.provider, selection.model);
+  if (!key) return ledger;
+  if (!ledger.models || typeof ledger.models !== 'object') ledger.models = {};
+  const bucket = ledger.models[key] || (ledger.models[key] = emptyModelBucket(selection));
+  // 名字以最新的为准；空名不覆盖（渠道被卸载 / 宿主这一轮没带目录时不至于把已知名字擦掉）。
+  if (selection.providerName) bucket.providerName = selection.providerName;
+  if (selection.modelName) bucket.modelName = selection.modelName;
+  const usage = sanitizeUsage(entry.usage);
+  for (const usageKey of USAGE_KEYS) bucket.billed[usageKey] += usage[usageKey];
+  const day = typeof entry.day === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(entry.day)
+    ? entry.day
+    : dayKeyOf(Date.now());
+  const daily = bucket.daily[day] || (bucket.daily[day] = emptyUsage());
+  for (const usageKey of USAGE_KEYS) daily[usageKey] += usage[usageKey];
+  bucket.lastAt = Math.max(bucket.lastAt, num(entry.at) || dayStartAt(day));
+  return ledger;
+}
+
 /**
  * 把一次采集到的增量记进账本（纯函数，原地改并返回它）。
  *
  * `entry.date` 只在「首采回填」时传：一条会话第一次被采到时，它历史上有多少量我们都
  * 不知道发生在哪天，只能记到它最后一次活动的那天 —— 记到今天会让今天凭空多出一大截，
  * 记到创建那天又会让所有历史堆在最早一天。两者都是近似，取「最后活动日」更接近直觉。
+ *
+ * `entry.model` 是这个选择时可选带的 `{ provider, providerName, model, modelName }`：给了就
+ * 把同一份 `delta` 也记进模型桶。名字为空的半个组合不建桶（见 `modelKeyOf`）。
  */
 function applyDelta(ledger, entry) {
   const sessionId = entry.sessionId;
@@ -320,8 +478,6 @@ function applyDelta(ledger, entry) {
   for (const key of USAGE_KEYS) ownDay[key] += delta[key];
   record.lastAt = Math.max(record.lastAt, at);
   if (!record.firstAt) record.firstAt = at;
-  // 退场的卡片又有了新用量：回到列表里来（水位一直在，所以这次只记增量）。
-  record.retired = false;
   if (entry.title) record.title = entry.title;
   if (entry.cwd) record.cwd = entry.cwd;
   if (entry.workspaceName) record.workspaceName = entry.workspaceName;
@@ -329,6 +485,9 @@ function applyDelta(ledger, entry) {
   if (typeof entry.lastText === 'string' && entry.lastText) {
     record.lastText = entry.lastText.slice(0, LAST_TEXT_MAX);
   }
+  // 模型维度：同一份增量在「采集这一刻这条会话正在用的模型」名下再记一笔。日期与上面两处
+  // 必须同一个（首采回填也是），否则模型卡和按天账在切范围时会各说一套。
+  if (entry.model) applyModelUsage(ledger, { model: entry.model, day: date, at, usage: delta });
   return ledger;
 }
 
@@ -361,8 +520,7 @@ function usageInRange(record, startDay, today) {
  * 逐日序列会把范围内每一天都列出来（没有活动的补 0），柱状图靠它保持等距。
  *
  * 三块口径必须对得上：`kpi` 是范围内总量，`sessions` 里的每张卡片是这条会话在同一个范围里
- * 的用量，`retired` / `untracked` 把不在卡片上的那部分明说出来 —— 卡片加起来解释不了总量，
- * 是页面被读成「数据对不上」的根源。
+ * 的用量，`untracked` 把「卡片解释不了总量」的那一截（老版本删过记录，只剩按天账）明说出来。
  */
 function summarize(ledger, range, now) {
   const today = dayKeyOf(now);
@@ -423,22 +581,11 @@ function summarize(ledger, range, now) {
   }
 
   const sessions = [];
-  let retiredSessions = 0;
-  let retiredBilled = 0;
   // 构成快照取「最近有动作的那条会话」：每轮只在不是同一条时换，不再被并发读完的最后一条覆盖。
   let composition = null;
   let compositionSession = null;
   for (const [sessionId, record] of Object.entries(ledger.sessions)) {
     const usage = usageInRange(record, startDay, today);
-    if (record.retired === true) {
-      // 退场记录只留水位，不上卡片：它的量早就记在按天的账上了。范围里有量时在汇总行报个数。
-      const billed = billedOf(usage);
-      if (billed > 0) {
-        retiredSessions += 1;
-        retiredBilled += billed;
-      }
-      continue;
-    }
     if (record.composition && num(record.lastAt) > num(compositionSession && compositionSession.lastAt)) {
       composition = {
         systemTokens: num(record.composition.systemTokens),
@@ -449,6 +596,7 @@ function summarize(ledger, range, now) {
     }
     const billedTokens = billedOf(usage);
     // 范围内一个 token、一轮都没有的会话不上卡片：切到「近 7 天」时老会话不该占着位置。
+    // 除此之外一条都不许筛 —— 卡片条数就是页面上那个「会话」数字。
     if (billedTokens === 0 && num(usage.turns) === 0) continue;
     sessions.push({
       sessionId,
@@ -469,17 +617,53 @@ function summarize(ledger, range, now) {
     if (b.billedTokens !== a.billedTokens) return b.billedTokens - a.billedTokens;
     return b.lastAt - a.lastAt;
   });
+  // 「会话」这一格就是条款数：范围内有量的会话全部在这儿，没有第二条口径。
   kpi.sessions = sessions.length;
 
-  // 卡片 + 退场合计之后仍然少的那一截：老版本把整条记录删掉过（水位与明细都没了），
-  // 按天的账上却还留着那些天。明说出来，别让用户自己拿计算器发现差额。
-  // 只报量、不报条数 —— 那些会话连记录都没了，条数是编不出来的。
-  const tracked = sessions.reduce((sum, row) => sum + row.billedTokens, 0) + retiredBilled;
+  // 卡片加起来仍然少的那一截：老版本把整条记录删掉过（水位与明细都没了），按天的账上却还
+  // 留着那些天。只报量、不报条数 —— 那些会话连记录都没了，条数是编不出来的。
+  const tracked = sessions.reduce((sum, row) => sum + row.billedTokens, 0);
   const untrackedBilled = Math.max(0, rangeBilled - tracked);
 
   // 没有任何一条会话带自己的构成时（升级前的老账本），退回那份全局快照。
   if (!composition && ledger.composition) composition = { ...ledger.composition };
 
+  // 模型卡：折算口径与每张会话卡完全一致（同一个 `usageInRange`），页面切范围时两块一起动。
+  const models = [];
+  // 这一份里认出来的厂商，只带**用到的那几个**图标（`icon` 是一段 SVG 标记，App 用 SvgXml
+  // 直接画）：一次响应几十条模型行各自背一份图标没有意义。
+  const vendors = {};
+  for (const bucket of Object.values(ledger.models || {})) {
+    if (!bucket || typeof bucket !== 'object') continue;
+    const usage = usageInRange(bucket, startDay, today);
+    const billedTokens = billedOf(usage);
+    const turns = num(usage.turns);
+    // 与卡片同一条规矩：范围内一个 token、一轮都没有的组合不上卡。
+    if (billedTokens === 0 && turns === 0) continue;
+    // 厂商从模型名 / 模型 id 认，认不出再用渠道兜（见 model-vendors.js）；认不出就不带，
+    // 页面那一行退回首字母徽标。
+    const vendor = identifyVendor(bucket);
+    const logo = vendor ? vendorLogoOf(vendor) : null;
+    if (logo) vendors[vendor] = logo;
+    models.push({
+      provider: bucket.provider || '',
+      providerName: bucket.providerName || '',
+      model: bucket.model || '',
+      modelName: bucket.modelName || '',
+      ...(logo ? { vendor } : {}),
+      uncachedInputTokens: num(usage.uncachedInputTokens),
+      cacheReadTokens: num(usage.cacheReadTokens),
+      cacheWriteTokens: num(usage.cacheWriteTokens),
+      outputTokens: num(usage.outputTokens),
+      billedTokens,
+      turns,
+      // 请求数取 `usage.steps`，与按天账同一个口径（见 applyDelta 里的那条注释）。
+      requests: num(usage.steps),
+      lastAt: num(bucket.lastAt),
+    });
+  }
+  models.sort((a, b) => (b.billedTokens !== a.billedTokens ? b.billedTokens - a.billedTokens : b.lastAt - a.lastAt));
+
   return {
     generatedAt: now,
     range,
@@ -488,16 +672,18 @@ function summarize(ledger, range, now) {
     heatmap,
     ...(composition ? { composition } : {}),
     ...(compositionSession ? { compositionSessionId: compositionSession.sessionId } : {}),
-    retired: { sessions: retiredSessions, tokens: retiredBilled },
     untrackedBilled,
     sessions,
+    // 一个桶都没有也要给空数组：App 那边缺这个字段就整块不画，给空数组才是「画一块空」。
+    models,
+    // 一个厂商都没认出来时整项不出：老 App 不认识这个字段，新 App 缺它就是「没有图标」。
+    ...(Object.keys(vendors).length > 0 ? { vendors } : {}),
   };
 }
 
 module.exports = {
   VERSION,
-  MAX_SESSIONS,
-  MAX_RETIRED,
+  MAX_RECORDS,
   MAX_DAYS,
   MAX_DAILY_DAYS,
   HEATMAP_DAYS,
@@ -506,7 +692,9 @@ module.exports = {
   readLedger,
   saveLedger,
   forgetLedger,
+  sanitizeLedger,
   applyDelta,
+  applyModelUsage,
   summarize,
   trim,
   dayKeyOf,
@@ -515,5 +703,7 @@ module.exports = {
   emptyUsage,
   billedOf,
   usageInRange,
+  modelKeyOf,
+  sanitizeModelSelection,
   num,
 };

package/lib/mobile/stats-scheduler.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+/**
+ * 统计账本的宿主侧定时采集：每几分钟自己跑一轮。
+ *
+ * 以前采集只在「有人打开统计页 / 下拉刷新 / 点清理」时才发生，水位差于是把「上次观测到现在」
+ * 的整段用量记在**观测到它的那一天**：连着几天没打开页面，那几天的量就整批压到最后一天，
+ * 按天图上是几天空白加一根尖柱。这一轮挪到宿主身上之后，归属误差从「几天」变成「几分钟」，
+ * 顺带把「会话在下次采集之前被删掉」那个丢数窗口一起收掉。
+ *
+ * 一轮只读真有变动的会话（采集器按摘要的 `updatedAt` 跳过一点没动的），空闲时连账本文件
+ * 都不重写 —— 平时几乎不花钱，别因为「每几分钟一次」就以为它在扫盘。
+ *
+ * 定时器归这里，不归装配层（`test/assembly-layer.test.cjs` 钉着）。
+ */
+
+const { collectStats, DEFAULT_BUDGET_MS, PERIODIC_INTERVAL_MS } = require('./stats-collect.cjs');
+
+/** 启动后第一轮等一会儿：宿主刚起来时各服务还在就位，不抢那几十毫秒。 */
+const FIRST_RUN_DELAY_MS = 30_000;
+
+/**
+ * 开始定期采集，返回停表函数（`ctx.effect` 的清理那一半）。
+ *
+ * 两条定时器都 `unref()`：它们是旁路，不该把进程留住等它们跑完。
+ */
+function start(ctx) {
+  const run = () => {
+    void collectStats(ctx, { budgetMs: DEFAULT_BUDGET_MS }).catch(() => undefined);
+  };
+  const first = setTimeout(run, FIRST_RUN_DELAY_MS);
+  const timer = setInterval(run, PERIODIC_INTERVAL_MS);
+  first.unref?.();
+  timer.unref?.();
+  return () => {
+    clearTimeout(first);
+    clearInterval(timer);
+  };
+}
+
+module.exports = { start, FIRST_RUN_DELAY_MS, PERIODIC_INTERVAL_MS };