dsh-mobile-plugin 0.1.96 → 0.1.97

package/lib/mobile/session-model-options.js

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * 模型附加选项：模型之外还能调的几档（速度、输出详略……）。
+ *
+ * 宿主的模型目录只有「模型 + 推理等级」两层；别的档位是插件自己的偏好（例如 Codex
+ * 订阅插件的 speedMode / outputVerbosity），桌面端由那个插件接管整个模型菜单自己画，
+ * 所以宿主接口里根本没有这些行。这里把它们翻译成**数据**：App 收到几行就画几行，
+ * 不认识任何具体插件。
+ *
+ * 一条来源 = 一个 provider + 它的设置命名空间 + 行描述。加一个插件就是加一条；没有
+ * 来源时 `options` 为空，App 仍然只画模型和推理等级。读写都只经过宿主自己的 settings
+ * 服务（describe / mutate），不碰插件私有接口；可写字段也仅限这张表里列出的那些。
+ */
+
+const { sendJson, readJsonBody } = require('../shared/http-util');
+const { unwrap } = require('./envelope.js');
+const { invalidateSessionModels } = require('./session-cache.js');
+
+/** 行描述：id/title 给 App 画，field 是插件设置里的字段名。 */
+const OPTION_SOURCES = [
+  {
+    provider: 'openai-codex',
+    settingsNs: 'codex-subscription',
+    rows: [
+      {
+        id: 'speed',
+        title: '速度',
+        field: 'speedMode',
+        choices: [
+          { id: 'standard', name: '标准', description: '标准速度' },
+          { id: 'fast', name: '高速', description: '优先处理，消耗更多 Credits' },
+          { id: 'ultrafast', name: 'Ultrafast', description: '账号目录提供时可用，消耗更快' },
+        ],
+      },
+      {
+        id: 'verbosity',
+        title: '输出详略',
+        field: 'outputVerbosity',
+        choices: [
+          { id: 'default', name: '模型默认', description: '使用官方模型目录推荐值' },
+          { id: 'low', name: '简洁', description: '更短、更直接' },
+          { id: 'medium', name: '均衡', description: '兼顾完整性与长度' },
+          { id: 'high', name: '详细', description: '更充分的说明与结构' },
+        ],
+      },
+    ],
+  },
+];
+
+const MAX_ROWS = 12;
+const MAX_CHOICES = 32;
+
+function sourceFor(provider) {
+  return OPTION_SOURCES.find((source) => source.provider === provider);
+}
+
+/** 宿主 settings 里这个插件的命名空间视图；读不到（插件没装 / 没装 settings）返回 null。 */
+async function describeNamespace(ctx, source) {
+  let response;
+  try {
+    response = await ctx.apiProxy.settings.describe({
+      rpcId: 'mobile',
+      method: 'settings.describe',
+      payload: {},
+    });
+  } catch {
+    // 旧宿主的 apiProxy 未必有 settings 这一域：附加选项是锦上添花，别让它拖垮模型目录。
+    return null;
+  }
+  const { value, error } = unwrap(response);
+  if (error) return null;
+  // 远程那层（SettingsDescribeValue）把命名空间放在 `namespaces` 里，只有宿主进程内的
+  // settings.describe 才直接回数组 —— 两种都认，别只按其中一种写。
+  const rows = Array.isArray(value)
+    ? value
+    : (value && Array.isArray(value.namespaces) ? value.namespaces : []);
+  // 先按 profile 条目 id 认；条目 id 在别处被改过时，退回「这个命名空间里有我们认识的
+  // 字段」——总比整个功能静默消失好。
+  const namespace = rows.find((row) => row && row.ns === source.settingsNs)
+    || rows.find((row) => row && row.value && typeof row.value === 'object'
+      && source.rows.every((option) => Object.hasOwn(row.value, option.field)));
+  if (!namespace || !namespace.value || typeof namespace.value !== 'object') return null;
+  return namespace;
+}
+
+/** 这个 provider 的当前行；没有来源或读不到设置时返回空数组。 */
+async function readModelOptions(ctx, provider) {
+  const source = typeof provider === 'string' ? sourceFor(provider) : undefined;
+  if (!source) return [];
+  const namespace = await describeNamespace(ctx, source);
+  if (!namespace) return [];
+  const options = [];
+  for (const row of source.rows) {
+    const value = namespace.value[row.field];
+    if (typeof value !== 'string' || !value) continue;
+    options.push({
+      id: row.id,
+      title: row.title,
+      value,
+      choices: row.choices.map((choice) => ({ ...choice })),
+    });
+  }
+  return options.slice(0, MAX_ROWS);
+}
+
+/**
+ * 响应清洗，与 `safeModelsValue` 同一套路：宿主（以及那一层描述表）会随版本变，
+ * 进 App 之前逐字段挑出来，宁可少一行也不把半截对象糊上去。
+ */
+function safeModelOptions(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((row) => row && typeof row.id === 'string' && typeof row.title === 'string' &&
+      typeof row.value === 'string' && Array.isArray(row.choices))
+    .slice(0, MAX_ROWS)
+    .map((row) => ({
+      id: row.id.slice(0, 256),
+      title: row.title.slice(0, 512),
+      value: row.value.slice(0, 256),
+      choices: row.choices
+        .filter((choice) => choice && typeof choice.id === 'string' && typeof choice.name === 'string')
+        .slice(0, MAX_CHOICES)
+        .map((choice) => ({
+          id: choice.id.slice(0, 256),
+          name: choice.name.slice(0, 512),
+          ...(typeof choice.description === 'string' ? { description: choice.description.slice(0, 4096) } : {}),
+        })),
+    }));
+}
+
+/**
+ * 写一行。只认表里声明过的行与取值 —— 这是移动 API 上唯一一处写插件设置的入口，
+ * 不开放任意 ns / 字段。
+ */
+async function writeModelOption(ctx, provider, optionId, value) {
+  const source = sourceFor(provider);
+  const row = source ? source.rows.find((candidate) => candidate.id === optionId) : undefined;
+  if (!row) return { error: { code: 'bad-request', message: '未知的模型选项' } };
+  if (!row.choices.some((choice) => choice.id === value)) {
+    return { error: { code: 'bad-request', message: '未知的选项值' } };
+  }
+  const namespace = await describeNamespace(ctx, source);
+  if (!namespace) return { error: { code: 'host-unavailable', message: `设置里没有 ${source.settingsNs} 的可写字段` } };
+  let response;
+  try {
+    response = await ctx.apiProxy.settings.mutate({
+      rpcId: 'mobile',
+      method: 'settings.mutate',
+      payload: {
+        ns: source.settingsNs,
+        ops: [{ op: 'set', path: [row.field], value }],
+        ...(Number.isSafeInteger(namespace.revision) ? { expectedRevision: namespace.revision } : {}),
+      },
+    });
+  } catch (error) {
+    return { error: { code: 'host-call-failed', message: error instanceof Error ? error.message : String(error) } };
+  }
+  const { error } = unwrap(response);
+  if (error) return { error };
+  return { value: true };
+}
+
+/**
+ * POST /api/mobile/v1/session/model-option（token）{sessionId, provider, optionId, value}
+ *
+ * 写完作废这条会话的目录缓存，否则手机上会拿着旧值直到 20 秒 TTL 到期
+ * （与切模型那条同样的坑）。
+ */
+async function handleModelOption(ctx, req, res) {
+  const body = await readJsonBody(req);
+  if (!body || typeof body.sessionId !== 'string' || !body.sessionId ||
+      typeof body.provider !== 'string' || !body.provider ||
+      typeof body.optionId !== 'string' || !body.optionId ||
+      typeof body.value !== 'string' || !body.value) {
+    return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '需要 { sessionId, provider, optionId, value }' } });
+  }
+  const result = await writeModelOption(ctx, body.provider, body.optionId, body.value);
+  if (result.error) return sendJson(res, 400, { ok: false, error: result.error });
+  invalidateSessionModels(ctx, req, body.sessionId);
+  sendJson(res, 200, { ok: true });
+}
+
+module.exports = { OPTION_SOURCES, readModelOptions, safeModelOptions, writeModelOption, handleModelOption };

package/lib/mobile/session-models.js

@@ -14,6 +14,7 @@ const { sendJson, readJsonBody } = require('../shared/http-util');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
 const { canonicalDeviceKey, sessionModelsStateOf, invalidateSessionModels } = require('./session-cache.js');
+const { readModelOptions, safeModelOptions } = require('./session-model-options.js');
 
 const SESSION_MODELS_CACHE_MS = 20000; // 模型目录短 TTL；成功后 stale-while-revalidate
 
@@ -32,6 +33,16 @@ function safeModelsValue(value) {
       if (text) result.current[key] = text;
     }
   }
+  // 全局默认（新会话会用的那个）：App 拿它当「新对话」显示，provider/model 缺一个就不下发。
+  if (value.defaultModel && typeof value.defaultModel === 'object') {
+    const selection = {};
+    for (const key of ['provider', 'model', 'reasoningEffort']) {
+      const max = key === 'provider' ? 256 : key === 'model' ? 512 : 256;
+      const text = modelText(value.defaultModel[key], max);
+      if (text) selection[key] = text;
+    }
+    if (selection.provider && selection.model) result.defaultModel = selection;
+  }
   if (typeof value.routable === 'boolean') result.routable = value.routable;
   if (Array.isArray(value.routableProviders)) {
     result.routableProviders = [...new Set(value.routableProviders
@@ -69,6 +80,12 @@ function safeModelsValue(value) {
           })),
       }));
   }
+  // 模型之外的附加选项行（速度、输出详略……）：行数与内容都由 session-model-options.js
+  // 那张描述表决定，App 只按收到的数组逐行画。空数组不下发（旧宿主没有这个字段）。
+  if (Array.isArray(value.options)) {
+    const options = safeModelOptions(value.options);
+    if (options.length > 0) result.options = options;
+  }
   if (Array.isArray(value.failures)) result.failures = value.failures.slice(0, 64).map((failure) => ({
     ...(typeof failure?.id === 'string' ? { id: modelText(failure.id, 256) } : {}),
     ...(typeof failure?.name === 'string' ? { name: modelText(failure.name, 512) } : {}),
@@ -103,10 +120,13 @@ function startModelsRequest(ctx, entry, sessionId, fresh = false) {
     return entry.promise;
   }
   const generation = entry.generation || 0;
-  const request = Promise.resolve(callSessions(ctx, 'models', { sessionId })).then((response) => {
+  const request = Promise.resolve(callSessions(ctx, 'models', { sessionId })).then(async (response) => {
     const { value, error } = unwrap(response);
     if (error) return { error };
     const safeValue = safeModelsValue(value);
+    // 附加选项行按**当前模型所在渠道**取（宿主目录里没有这一层，见 session-model-options.js）。
+    const options = await readModelOptions(ctx, safeValue.current && safeValue.current.provider);
+    if (options.length > 0) safeValue.options = options;
     const fetchedAt = Date.now();
     if (generation === (entry.generation || 0)) {
       entry.value = safeValue;
@@ -133,7 +153,9 @@ async function buildModelsSnapshot(ctx, sessionId) {
 
 /** GET /api/mobile/v1/session/models?sessionId=…（token）
  * 返回会话当前模型选择与可用模型目录（透传宿主 session.models）。
- * 响应：{ ok, current:{provider,model,reasoningEffort?}, routable, groups:[{id,name,models:[{id,name,description?,reasoning?}]}], failures:[{id,name,message}] }
+ * 响应：{ ok, current:{provider,model,reasoningEffort?}, defaultModel:{provider,model,reasoningEffort?}, routable, groups:[{id,name,models:[{id,name,description?,reasoning?}]}], options?:[{id,title,value,choices:[{id,name,description?}]}], failures:[{id,name,message}] }
+ * `current` 是**这个会话**实际会用的；`defaultModel` 是全局默认（宿主新建会话时的落点）。
+ * `options` 是当前渠道的附加选项行（速度、输出详略……），没有就是没有这个字段。
  */
 async function handleModels(ctx, req, res) {
   const url = new URL(req.url, 'http://x');

package/lib/mobile/session-schedule-mark.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * 会话行左边那只时钟：**这一条会话有没有还在生效的自动化任务**。
+ *
+ * 桌面上那个标记在 `@deepseek-ai/dsh-client-ui-schedule` 的 `SessionScheduleMark`：它占
+ * 会话行标题前那格 16px，画一颗 14px 的 `IconClockOutlineRegular`；只在 「这一行自己的
+ * 主状态是空闲」时才挂得上（有审批 / 有新消息 / 正在跑时，那一格留给状态点），归档行那格
+ * 留空。手机端此前没有这个标记，用户在桌面上排了定时任务，手机上那条会话看不出任何区别。
+ *
+ * 数据从宿主的任务目录来：`schedule.catalog()` 一次给出全部任务的 sessionId + status，
+ * 按 `status === 'active'` 收成一份「哪些会话有活动任务」的集合，列表每行只要查表。**不**
+ * 每行发一次 `schedule/list` —— 会话列表每 10 秒重建一次，逐行请求等于每轮几十次往返。
+ *
+ * 三条取舍：
+ *  - **服务不在就当没有任务**（老宿主 / 极简 profile 没装）：时钟是提示性信息，为它让整个
+ *    会话列表失败是拿主要功能换装饰；
+ *  - **读失败也当没有**，但只吞这一条，不缓存：下一个 10 秒周期照常重问，宿主的
+ *    `schedule/changed` 与目录本身都是活的；
+ *  - 只看 `active`：一次性任务投完就自动结束（`status` 转 inactive），桌面上那颗也跟着消失。
+ */
+
+/** 目录一次最多收多少条（与 schedule.js 的 SCHEDULE_MAX_ENTRIES 同量级，这里只用来防异常宿主）。 */
+const CATALOG_MAX_ENTRIES = 500;
+
+/**
+ * 宿主 `schedule` 服务：同进程直查。
+ *
+ * 用 `ctx.get` 而不是 inject，理由与 mobile/schedule.js 相同：本插件不依赖它，缺了只该
+ * 少一个标记，不该让整个插件装不起来。
+ */
+function scheduleService(ctx) {
+  try {
+    if (!ctx || typeof ctx.get !== 'function') return null;
+    return ctx.get('schedule') || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 哪些会话还有活动自动化任务。
+ *
+ * @param ctx 插件上下文（取宿主 `schedule` 服务）
+ * @returns {Promise<Set<string>>} 有活动任务的 sessionId 集合；服务缺失或读失败时为空集
+ */
+async function activeScheduleSessions(ctx) {
+  const service = scheduleService(ctx);
+  if (!service || typeof service.catalog !== 'function') return new Set();
+  let value;
+  try {
+    value = await service.catalog();
+  } catch {
+    return new Set();
+  }
+  const records = Array.isArray(value)
+    ? value
+    : (value && Array.isArray(value.records) ? value.records : []);
+  const out = new Set();
+  for (const record of records) {
+    if (!record || typeof record !== 'object') continue;
+    if (record.status !== 'active') continue;
+    if (typeof record.sessionId !== 'string' || !record.sessionId) continue;
+    out.add(record.sessionId);
+    if (out.size >= CATALOG_MAX_ENTRIES) break;
+  }
+  return out;
+}
+
+module.exports = { activeScheduleSessions };

package/lib/mobile/session-snapshot.js

@@ -15,7 +15,7 @@
 const { sendJson } = require('../shared/http-util');
 const { unwrap } = require('./envelope.js');
 const { callSessions } = require('./rpc.js');
-const { deriveMessages } = require('./history-derive.js');
+const { deriveMessages, buildToolResultMap } = require('./history-derive.js');
 const { resolveEventAttachments } = require('./attachments.js');
 const { createTextImageBudget } = require('./local-images.js');
 
@@ -165,6 +165,16 @@ async function handleMessages(ctx, req, res) {
   const budget = createTextImageBudget();
   const resolvedEvents = await Promise.all(filtered.map((entry) => resolveEventAttachments(ctx, sessionId, entry.event || entry, { budget, referencesOnly: true }).then((event) => entry.event ? { ...entry, event } : event)));
   const messages = deriveMessages(resolvedEvents);
+  // 工具结果不产生消息行，但会把**缓存里已有的**工具卡从 running 补成最终态。补丁必须
+  // 取自整个窗口（不只是 seq > afterSeq 的那一段）：调用方游标可能已经越过结果 seq，
+  // 而工具卡还停在 running；把窗口内所有落定结果都回传，客户端按 callId 幂等打补丁。
+  const toolResults = [...buildToolResultMap(events).entries()].map(([callId, result]) => ({
+    callId,
+    state: result.isError ? (result.code === 'interrupted' ? 'stopped' : 'error') : 'ok',
+    ...(result.output ? { output: result.output } : {}),
+    ...(result.images && result.images.length ? { images: result.images } : {}),
+    ...(result.diffs && result.diffs.length ? { diffs: result.diffs } : {}),
+  }));
   const hasMore = !!(value && value.hasMore);
   const seqs = events.map(eventSeqOf).filter((seq) => Number.isSafeInteger(seq) && seq >= 0);
   const oldestSeq = seqs.length ? Math.min(...seqs) : null;
@@ -181,6 +191,7 @@ async function handleMessages(ctx, req, res) {
     lastSeq,
     ...(oldestSeq !== null ? { oldestSeq } : {}),
     ...(resyncRequired ? { resyncRequired: true } : {}),
+    ...(toolResults.length ? { toolResults } : {}),
   });
 }
 

package/lib/mobile/sessions.js

@@ -54,6 +54,8 @@ const { handleSessionSearch } = require('./session-search.js');
 const { handleAgentPresets } = require('./session-presets.js');
 const { handleGoalAction } = require('./session-goal.js');
 const { workspaceSessionFlags, pendingInteractionOf } = require('./session-flags.js');
+// 行首时钟：这一条会话还有没有活动的自动化任务（一次任务目录查询喂满整份列表）。
+const { activeScheduleSessions } = require('./session-schedule-mark.js');
 // 预览（lastMessage 补全）与它自己的重读节流：只读日志、不发写，单列一个子模块。
 const { HISTORY_FOR_ENRICH, sessionPreviewFor } = require('./session-preview.js');
 
@@ -189,6 +191,9 @@ async function buildSessionsResponse(ctx, deviceKey = 'legacy', generation = com
   // 它们，筛选视图正是为了把它们找回来（查看 / 取消归档）。
   const deleted = deletedSessionIdsOf(ctx);
   const { archived, pinned } = await workspaceSessionFlags(ctx);
+  // 行首那只时钟的判据：这一条会话还有没有活动的自动化任务（见 session-schedule-mark.js）。
+  // 与置顶 / 归档同一个位置取，一次目录查询喂满整份列表，别在渲染层逐行发请求。
+  const scheduled = await activeScheduleSessions(ctx);
   const allSummaries = summaries.filter((item) => item && !deleted.has(item.sessionId)
     && (archivedOnly === archived.has(item.sessionId)));
   // 状态跟踪覆盖完整列表，不能受预览补全上限影响。
@@ -226,6 +231,9 @@ async function buildSessionsResponse(ctx, deviceKey = 'legacy', generation = com
       // 与归档同源同一份快照。App 侧栏据此把这条排到工作区最前、并在行尾画图钉标记。
       // 和归档一样只在真置顶时出现：旧 App 忽略未知字段，行为不变。
       ...(pinned.has(s.sessionId) ? { pinned: true } : {}),
+      // 这一条会话还排着活动的自动化任务：App 侧栏在行首画那只时钟（桌面
+      // SessionScheduleMark 同口径）。只在真有任务时出现，旧 App 忽略未知字段。
+      ...(scheduled.has(s.sessionId) ? { scheduled: true } : {}),
       updatedAt: s.updatedAt || 0,
       lastMessage: null,
       ...(s.origin === 'subagent' ? { origin: s.origin } : {}),

package/lib/mobile/stats-collect.cjs

@@ -0,0 +1,257 @@
+'use strict';
+
+/**
+ * 统计采集：把宿主每条会话的累计用量读出来，和水位一比，增量记进账本。
+ *
+ * 为什么不重放会话事件：那是 dsh-context 在桌面上干的事（它让宿主注册一份投影，
+ * 每个事件折一次）。手机这边要的是「按天看个大概」，重放整条日志在宿主上是一笔
+ * 每秒都在烧的开销，而我们每轮只需要一个数 —— 会话的累计用量。
+ *
+ * 所以走水位差：
+ *   宿主累计值 − 账本记下的水位 = 这次该入账的量。
+ * 好处是零依赖（只用现有的会话投影接口，不需要宿主新能力，也不用装别家插件），
+ * 代价如实说：入账日期取「插件看到增量的那一天」，跨零点的一轮会落在后一天。
+ * 这是刻意的近似 —— 为一个几十分钟的边界去重放事件流不值得。
+ *
+ * 首采（账本里没有这条会话）会把它的历史全量入账，日期取它最后一次活动的日期：
+ * 这是一次性回填，用户装上这个版本之后第一次打开统计页就会看见过去的用量，
+ * 而不是从今天零点重新计数。
+ *
+ * 采集是**按需**的（打开统计页 / 下拉刷新 / 清理已归档前补一刀），没有后台定时器：
+ * 手机上没人看统计的时候不该让宿主一直读盘。
+ *
+ * 清理前那次补采（`skipPreview`）刻意不读「最后一句」：那一步要读会话日志，是整轮里
+ * 最重的一趟，而删除不可恢复、时间又卡在手机那条请求的预算里。为了多把几十上百条会话的
+ * 数字记进账本，宁可让首次见到的会话卡片少一行摘要 —— 标题与项目名还认得出来。
+ */
+
+const { unwrap } = require('./envelope.js');
+const { callSessions } = require('./rpc.js');
+const { sessionPreviewFor } = require('./session-preview.js');
+const ledger = require('./stats-ledger.cjs');
+
+/** 同一条会话两次采集之间的最小间隔（打开页面时的重复请求直接复用上一轮结果）。 */
+const COLLECT_INTERVAL_MS = 60_000;
+
+/** 并发读投影的条数：宿主那侧是内存里读缓存，四条并行不会把它压住。 */
+const CONCURRENCY = 4;
+
+/**
+ * 一次采集的时间预算。
+ *
+ * 手机上点开统计页时，插件会当场把每条会话的累计用量读一遍；一百多条会话串起来能拖到
+ * 十几秒（每条两趟宿主调用），用户看到的就是「点统计，转好久」（2026-10-22 真机）。
+ * 所以给这一趟设上限：到点就停，把**已经采到的**那部分记进账本先回给手机，剩下的等
+ * 下一次打开 / 下拉刷新接着采 —— 水位差是累积的，采一半不会算错，只是数字暂时偏小。
+ */
+const DEFAULT_BUDGET_MS = 1500;
+
+const num = ledger.num;
+
+function normalizePath(value) {
+  if (typeof value !== 'string') return '';
+  return value.replace(/\/+$/, '');
+}
+
+/** 宿主会话列表：拿不到就当没有（清空或报错都不该把账本弄乱）。 */
+async function listSessions(ctx) {
+  try {
+    const { value } = unwrap(await callSessions(ctx, 'list', {}, 'mobile'));
+    const items = Array.isArray(value) ? value : (value && Array.isArray(value.items) ? value.items : null);
+    if (items === null) return null;
+    return items.filter((item) => item && typeof item.sessionId === 'string' && item.sessionId);
+  } catch {
+    return null;
+  }
+}
+
+/** cwd → 项目展示名。宿主没给可用的工作区表就返回空表，卡片上就不显示项目名。 */
+async function workspaceNames(ctx) {
+  const byCwd = 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) {
+      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);
+    }
+  } catch {
+    /* 拿不到项目名不影响数字 */
+  }
+  return byCwd;
+}
+
+/** 一条会话的投影（tokenUsage / sessionStats / contextBreakdown）；读不到返回 null。 */
+async function readProjections(ctx, sessionId) {
+  const controller = new AbortController();
+  try {
+    const { value } = unwrap(await callSessions(ctx, 'projections', { sessionId }, 'mobile', controller.signal));
+    const values = value && value.values && typeof value.values === 'object' ? value.values : null;
+    return values;
+  } catch {
+    return null;
+  }
+}
+
+/** 宿主那份累计用量 → 账本口径。缺哪项就当 0，不猜。 */
+function hostUsageOf(projections) {
+  const usage = ledger.emptyUsage();
+  if (!projections || typeof projections !== 'object') return usage;
+  const token = projections.tokenUsage;
+  if (token && typeof token === 'object') {
+    usage.uncachedInputTokens = num(token.uncachedInputTokens);
+    usage.cacheReadTokens = num(token.cacheReadTokens);
+    usage.cacheWriteTokens = num(token.cacheWriteTokens);
+    usage.outputTokens = num(token.outputTokens);
+  }
+  const stats = projections.sessionStats;
+  if (stats && typeof stats === 'object') {
+    usage.turns = num(stats.turns);
+    usage.steps = num(stats.steps);
+    usage.llmMs = num(stats.llmMs);
+    usage.toolMs = num(stats.toolMs);
+  }
+  return usage;
+}
+
+/**
+ * 增量：宿主累计减水位。累计值比水位还小只可能是会话日志被重写 / 换了宿主，
+ * 这时按新值全额入账（宁可多记一次，也不要从此永远少记）。
+ */
+function diffUsage(host, watermark) {
+  const delta = ledger.emptyUsage();
+  for (const key of Object.keys(delta)) {
+    const current = num(host[key]);
+    const previous = watermark ? num(watermark[key]) : 0;
+    delta[key] = current >= previous ? current - previous : current;
+  }
+  return delta;
+}
+
+function hasDelta(usage) {
+  return Object.values(usage).some((value) => value > 0);
+}
+
+/**
+ * 采一轮。
+ *
+ * `sessionIds` 给了就只采那几条（清理前补采用），否则采整份列表；
+ * `force` 跳过 60 秒的最小间隔（用户手动刷新时要真读一次）；
+ * `skipPreview` 不读「最后一句」摘要（清理前补采用，见文件头）。
+ */
+async function collectStats(ctx, options = {}) {
+  const now = Date.now();
+  const budgetMs = Number.isFinite(options.budgetMs) && options.budgetMs > 0 ? options.budgetMs : DEFAULT_BUDGET_MS;
+  const deadline = now + budgetMs;
+  const skipPreview = options.skipPreview === true;
+  const book = ledger.readLedger();
+  const items = await listSessions(ctx);
+  if (items === null) return book;
+
+  const wanted = Array.isArray(options.sessionIds) ? new Set(options.sessionIds) : null;
+  const names = await workspaceNames(ctx);
+
+  // 消失检测只在「采整份列表」时做：定向补采拿到的是子集，凭它判「会话没了」会误标。
+  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;
+    }
+  }
+
+  // 最近有动作的排前面：预算不够采完全部时，先把用户真正在用的那几条账补上。
+  const targets = items
+    .filter((item) => !wanted || wanted.has(item.sessionId))
+    .sort((a, b) => num(b.updatedAt) - num(a.updatedAt));
+  let cursor = 0;
+
+  const worker = async () => {
+    for (;;) {
+      const index = cursor;
+      cursor += 1;
+      if (index >= targets.length) return;
+      // 预算到点就停手：剩下的等下一次（水位法不会漏，只会晚）。
+      if (Date.now() > deadline) return;
+      const summary = targets[index];
+      const sessionId = summary.sessionId;
+      const record = book.sessions[sessionId];
+      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;
+        continue;
+      }
+
+      const projections = await readProjections(ctx, sessionId);
+      if (!projections) continue;
+
+      const host = hostUsageOf(projections);
+      const watermark = record ? record.watermark : null;
+      const delta = diffUsage(host, watermark);
+      const firstSight = watermark === null;
+      // 首采：历史量一次性入账，日期取这条会话最后一次活动那天（见文件头）。
+      // 之后再有的增量一律记在「今天」—— 也就是这次观测到的日期。
+      const lastActiveAt = num(summary.updatedAt) || now;
+
+      const cwd = normalizePath(summary.cwd);
+      const workspaceName = cwd ? names.get(cwd) : undefined;
+
+      if (hasDelta(delta) || firstSight) {
+        // 最后一条消息的摘要只在真有增量时去读（它是日志，属于重活）：
+        // 卡片上那一行「最后一句说了什么」比什么都更能让人认出这是哪条会话。
+        // 清理前补采跳过这一步，把有限的时间预算全留给「多采几条会话的数字」。
+        let lastText = '';
+        if (!skipPreview) {
+          try {
+            const preview = await sessionPreviewFor(ctx, summary);
+            const text = preview && preview.lastMessage && preview.lastMessage.text;
+            if (typeof text === 'string') lastText = text.slice(0, ledger.LAST_TEXT_MAX);
+          } catch {
+            /* 读不到就不显示那一行 */
+          }
+        }
+        ledger.applyDelta(book, {
+          sessionId,
+          at: firstSight ? lastActiveAt : now,
+          delta: firstSight ? host : delta,
+          title: typeof summary.title === 'string' ? summary.title : '',
+          cwd,
+          workspaceName,
+          lastText,
+        });
+      }
+
+      const saved = book.sessions[sessionId];
+      if (saved) {
+        saved.watermark = host;
+        saved.collectedAt = now;
+        saved.gone = false;
+      }
+
+      const breakdown = projections.contextBreakdown;
+      if (breakdown && typeof breakdown === 'object') {
+        book.composition = {
+          systemTokens: num(breakdown.systemTokens),
+          toolsTokens: num(breakdown.toolsTokens),
+          messageTokens: num(breakdown.messageTokens),
+        };
+      }
+    }
+  };
+
+  await Promise.all(Array.from({ length: CONCURRENCY }, worker));
+
+  ledger.trim(book);
+  ledger.saveLedger(book);
+  return book;
+}
+
+module.exports = {
+  COLLECT_INTERVAL_MS,
+  DEFAULT_BUDGET_MS,
+  collectStats,
+  hostUsageOf,
+  diffUsage,
+};