dsh-mobile-plugin 0.4.0 → 0.4.4

package/lib/mobile/session-file.js

@@ -3,29 +3,16 @@
 /**
  * 交付文件的字节（POST /api/mobile/v1/session/file）。
  *
- * 轮尾那张「交付文件」卡在桌面上点一下就用系统默认程序打开；手机上没有那条路 ——
- * 文件在电脑上，宿主只给了路径，App 必须先取回字节。这条路由就是那条通道。
+ * 轮尾那张「交付文件」卡在桌面上点一下就打开；手机上没有那条路，App 必须先取回字节。
  *
- * 三条边界同时成立：
+ * 三条边界：
+ * 1. 放行面 = 本会话工作区里的文件 ∪ 本会话 present 声明过的路径。前者判「解析后的落点是否
+ *    在 cwd 之下」，`../x` 落在外面就退回白名单，不在声明里就 403；后者是字符串全等的显式
+ *    声明，用于工作区之外的文件。放开工作区不等于能读这台电脑上的任意文件。
+ * 2. 相对路径按会话工作区解析：cwd 取自会话列表摘要；没有 cwd 的会话只能走 present 白名单。
+ * 3. 流式回写，不在插件进程里缓冲：几十 MB 的录屏不该整包躺在内存里。
  *
- *  1. **放行面 = 本会话工作区里的文件 ∪ 本会话 present 声明过的路径**（2026-10-25 用户拍板
- *     的第二条，见 docs/decisions.md）。前者的判法是「解析后的落点在 cwd 之下」：相对路径
- *     按 cwd 拼、绝对路径原样，然后整条路径必须在 cwd 里 —— 所以 `../x` 这种穿越落在
- *     cwd 之外，退回旧的那条白名单，不在声明里就 403。后者保持原样（`deliverables/presented`
- *     里显式声明过的、**字符串全等**），它的用处是工作区之外的文件也能交付（绝对路径、
- *     cwd 变了的老会话）。
- *
- *     **为什么敢放开工作区**：正文里模型写的 `[报告](docs/报告.md)` 就是这条路上的用户预期
- *     —— 手机上点一下能看，比「点了没反应」有意义得多；而这条会话的模型本来就能读同一个
- *     工作区，手机与电脑是同一个使用者，放宽的是「同一份工作区能不能在手机上看」，不是
- *     「能不能读这台电脑上的任意文件」（那仍然是 403，与不暴露 shell / 任意写入同一条边界）。
- *  2. **相对路径按会话工作区解析**：cwd 取自会话列表摘要（与 /session 同一个来源）。没有
- *     cwd 的会话只能走 present 那条白名单，相对路径解析不出来就回 409。
- *  3. **流式回写、不在插件进程里缓冲**：几十 MB 的录屏不该整包躺在内存里，与会话日志
- *     导出同一个理由。
- *
- * 取不到时两种失败要分得开：两条口子都不认这个路径就回 403（`outside-workspace`），
- * 认了、盘上没了回 404（`missing`）—— 前者是「这个路径不该被读」，后者是「文件被挪走了」。
+ * 两种失败分开：两条口子都不认就 403（`outside-workspace`），认了但盘上没了回 404（`missing`）。
  */
 
 const fs = require('node:fs');
@@ -36,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）。 */
@@ -118,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/session-flags.js

@@ -17,21 +17,15 @@ const approvals = require('./approvals.js');
 const questions = require('./questions.js');
 
 /**
- * 宿主的两个**会话集合**（同一次 `workspace.list` 快照里拿到）：
+ * 宿主的两个会话集合（同一次 `workspace.list` 快照里拿到）：
  *
- *   - `archivedSessionIds`：已归档的会话。桌面端侧边栏据此把它们藏起来，而
- *     `sessions.list` 自身**不过滤**归档，所以移动端必须自己读这个集合：此前完全没读，
- *     App 的「归档会话」写是写成功了（宿主确实把 id 记进了 archivedSessionIds），列表却
- *     照旧把那一行发回手机，用户看到的就是一次毫无反馈的空操作。
- *   - `pinnedSessionIds`：已置顶的会话（宿主侧「最近置顶的在前」）。桌面端也只从这份
- *     快照读置顶，`sessions.list` 的摘要里没有置顶字段，所以移动端同样要自己读，
- *     否则 App 既画不出置顶标记、也排不到工作区最前。
+ * - `archivedSessionIds`：已归档的会话。`sessions.list` 自身不过滤归档，移动端必须自己读，
+ *   否则「归档」写成功了、列表却照旧把那一行发回手机。
+ * - `pinnedSessionIds`：已置顶的会话。摘要里没有置顶字段，不读这份快照就画不出置顶标记、
+ *   也排不到工作区最前。
  *
- * 两个集合合并成一次 RPC：它们同源同一次快照，而会话列表每 10 秒就会重建一次，
- * 分两次 `workspace.list` 等于平白给手机多塞一轮往返。
- *
- * 取不到时两个集合都回空（失败放开）：宁可多显示几行、少几个置顶，也不能因为一次
- * RPC 抖动让整个会话列表凭空变空。
+ * 两个集合合并成一次 RPC：同源同一次快照，而会话列表每 10 秒重建一次。取不到时都回空 ——
+ * 宁可多显示几行，也不能因为一次 RPC 抖动让整个列表变空。
  */
 async function workspaceSessionFlags(ctx) {
   try {

package/lib/mobile/session-mirror.js

@@ -63,12 +63,9 @@ async function buildSingleSessionMirror(ctx, sessionId, options = { limit: 200 }
 /**
  * Build mirror warm snapshots for the host mirror push.
  *
- * Two modes:
- *   1. High-priority (sessionIds provided): build ALL specified sessions at once,
- *      up to `limit` messages each.
- *   2. Background (no sessionIds): build from summaries, one session at a time,
- *      returning after each session so the caller can push incrementally.
- *      Processes at most `maxSessions` sessions per call, using cache when fresh.
+ * Two modes: high-priority (sessionIds given) builds all specified sessions at once; background
+ * (no sessionIds) builds from summaries one at a time so the caller can push incrementally,
+ * at most `maxSessions` per call, using the cache when fresh.
  *
  * @param {object} ctx - harness context
  * @param {Array} summaries - session list summaries from host
@@ -77,15 +74,11 @@ async function buildSingleSessionMirror(ctx, sessionId, options = { limit: 200 }
  * @param {string[]} [options.sessionIds] - specific sessions to build (high-priority)
  * @param {number} [options.limit=200] - max messages per session (capped at 200)
  * @param {number} [options.maxSessions=32] - max sessions to build in one call
- * @param {boolean} [options.noCache=false] - 完全绕开时间型缓存（既不读也不写）。
- *   事件驱动的推送必须传它：那个缓存只认「宿主抬了 updatedAt」这一种内容变化，
- *   一条新消息落盘而摘要还没变时，读缓存会把上一份正文当成这一份发出去。
- *   注意**不能**靠「传一个必然不同的 updatedAt」来绕（调用方以前就是这么干的）：
- *   指纹是 `updatedAt:running:limit`，同一个毫秒里的两次推送指纹相同，照样命中旧正文。
- * @returns {Promise<object>} messages map { [sessionId]: { ok, items, lastSeq, hasMore } }
- *   In background mode (no sessionIds), also sets _moreSessions on the result when
- *   there are remaining sessions beyond maxSessions, and _builtCount for how many
- *   were actually built this call.
+ * @param {boolean} [options.noCache=false] - 完全绕开时间型缓存（既不读也不写）。事件驱动的
+ *   推送必须传它：缓存只认「宿主抬了 updatedAt」这一种变化，新消息落盘而摘要未变时会把上一份
+ *   正文当成这一份发出去。也不能靠传一个必然不同的 updatedAt 来绕：同一毫秒的两次推送指纹相同。
+ * @returns {Promise<object>} messages map { [sessionId]: { ok, items, lastSeq, hasMore } }；
+ *   后台模式还会带 _moreSessions（是否还有剩余会话）与 _builtCount（本次真正构建了几个）。
  */
 async function buildMirrorWarmSnapshots(ctx, summaries, activeSessionId, options = {}) {
   const maxSessions = Math.max(1, Math.min(Number(options.maxSessions) || 32, 256));

package/lib/mobile/session-models.js

@@ -165,9 +165,9 @@ async function buildModelsSnapshot(ctx, sessionId) {
 
 /** GET /api/mobile/v1/session/models?sessionId=…（token）
  * 返回会话当前模型选择与可用模型目录（透传宿主 session.models）。
- * 响应：{ 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` 是当前渠道的附加选项行（速度、输出详略……），没有就是没有这个字段。
+ * 响应：{ ok, current, defaultModel, routable, groups, options?, failures }。
+ * `current` 是这个会话实际会用的，`defaultModel` 是全局默认（新建会话的落点），
+ * `options` 是当前渠道的附加选项行，没有就没有这个字段。
  */
 async function handleModels(ctx, req, res) {
   const url = new URL(req.url, 'http://x');

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

@@ -1,23 +1,17 @@
 'use strict';
 
 /**
- * 会话行左边那只时钟：**这一条会话有没有还在生效的自动化任务**。
+ * 会话行左边那只时钟：这一条会话有没有还在生效的自动化任务。
  *
- * 桌面上那个标记在 `@deepseek-ai/dsh-client-ui-schedule` 的 `SessionScheduleMark`：它占
- * 会话行标题前那格 16px，画一颗 14px 的 `IconClockOutlineRegular`；只在 「这一行自己的
- * 主状态是空闲」时才挂得上（有审批 / 有新消息 / 正在跑时，那一格留给状态点），归档行那格
- * 留空。手机端此前没有这个标记，用户在桌面上排了定时任务，手机上那条会话看不出任何区别。
+ * 桌面上那个标记只在会话行的主状态空闲时挂得上（有审批 / 新消息 / 正在跑时那格留给状态点），
+ * 归档行留空；手机端此前没有这个标记。
  *
- * 数据从宿主的任务目录来：`schedule.catalog()` 一次给出全部任务的 sessionId + status，
- * 按 `status === 'active'` 收成一份「哪些会话有活动任务」的集合，列表每行只要查表。**不**
- * 每行发一次 `schedule/list` —— 会话列表每 10 秒重建一次，逐行请求等于每轮几十次往返。
+ * 数据从宿主的任务目录来：`schedule.catalog()` 一次给出全部任务的 sessionId + status，按
+ * `status === 'active'` 收成集合，列表每行查表。不逐行发 `schedule/list` —— 会话列表每 10 秒
+ * 重建一次，逐行请求等于每轮几十次往返。
  *
- * 三条取舍：
- *  - **服务不在就当没有任务**（老宿主 / 极简 profile 没装）：时钟是提示性信息，为它让整个
- *    会话列表失败是拿主要功能换装饰；
- *  - **读失败也当没有**，但只吞这一条，不缓存：下一个 10 秒周期照常重问，宿主的
- *    `schedule/changed` 与目录本身都是活的；
- *  - 只看 `active`：一次性任务投完就自动结束（`status` 转 inactive），桌面上那颗也跟着消失。
+ * 三条取舍：服务不在（老宿主 / 极简 profile）就当没有任务；读失败也只吞这一条、不缓存，
+ * 下个周期照常重问；只看 active，一次性任务投完转 inactive 后标记自然消失。
  */
 
 /** 目录一次最多收多少条（与 schedule.js 的 SCHEDULE_MAX_ENTRIES 同量级，这里只用来防异常宿主）。 */

package/lib/mobile/session-send.js

@@ -43,21 +43,15 @@ function singleTextOf(content) {
 }
 
 /**
- * 经网关执行 slash 命令（commands.execute——桌面 Web 端同一条派发路径：
- * 命令注册表命中才执行，绝不经 session.prompt 发给模型；agent 由 agentId 经同一
- * agent 查找器解析，与 session.prompt 的 turnAgentFor 同源，支持冷会话自动 resume）。
+ * 经网关执行 slash 命令（commands.execute，桌面 Web 端同一条派发路径：命令注册表命中才执行，
+ * 绝不经 session.prompt 发给模型；agent 由 agentId 经同一查找器解析，支持冷会话自动 resume）。
  *
- * ⚠️ args 的键名必须**恰好**是宿主 descriptor 的 wire 名（typertGateway 的
- * assertExactArguments 只认这组名字，多一个少一个都是 gateway/arguments-invalid）。
- * descriptor：`@deepseek-ai/dsh-commands#commands/execute`，scope wire = agentId，
- * 参数 = line + submittedAttachments（encoded images 与 staged file receipts，
- * 按提交顺序排列，纯命令调用传空数组即可）。
- * 这里曾经写成 `images: []`——少了 submittedAttachments 又多了 images，导致
- * /permission、/plan 等**所有** slash 命令 400；形状守卫见
- * test/commands-execute-shape.test.cjs（改这里必须同步那张表）。
+ * args 的键名必须恰好是宿主 descriptor 的 wire 名：scope = agentId，参数 = line +
+ * submittedAttachments（encoded images 与 staged file receipts，按提交顺序，纯命令传空数组）。
+ * 多一个少一个都是 gateway/arguments-invalid，形状守卫见 test/commands-execute-shape.test.cjs。
  *
- * @returns {execution} 派发成功（CommandExecution|undefined，undefined=未知命令/语法不符）
- *   | {error} 查找或派发失败 | {missing} 网关服务未组合（调用方回退普通消息）
+ * @returns {execution} 派发成功（undefined=未知命令/语法不符）| {error} 查找或派发失败
+ *   | {missing} 网关服务未组合（调用方回退普通消息）
  */
 async function executeCommand(ctx, sessionId, line) {
   // 走 host-bridge/transport.js 的 invoke：Peer 身份与「服务/方法不存在」的收敛都在
@@ -82,8 +76,7 @@ function promptOnce(ctx, clientMessageId, payload) {
   // 把这一发认回去的身份一起送进宿主的 prompt 请求（`request.requestId`，见
   // host-bridge/endpoints.js）。宿主要是不认识它，user 消息的 `source.rpcId` 就是那个
   // 端点自己生成的 `mobile-prompt-<uuid>` —— App 那边 `clientMessageId` 永远对不上，
-  // 只能靠「同文本 + 同图数」猜着认领乐观行（2026-10-20 真机：自己发的图一直「发送中」，
-  // 因为实时帧里的图还被漏读，张数一对不上就彻底认领不了）。
+  // 只能靠「同文本 + 同图数」猜着认领乐观行（实时帧里的图一旦漏读，张数对不上就彻底认领不了）。
   const request = clientMessageId ? { ...payload, requestId: rpcId } : payload;
   if (!clientMessageId) return callSessions(ctx, 'prompt', request, rpcId);
   // 同一个 clientMessageId 在本会话里只承诺一次：内核重试、以及隔了几分钟用户手点的
@@ -176,14 +169,13 @@ async function handleSend(ctx, req, res) {
   sendJson(res, 200, { ok: true, accepted: true });
 }
 
-/** GET /api/mobile/v1/commands?sessionId=…（token）：会话有效命令目录（与桌面 Web 端命令面板
- * 同源——commands.list，即服务端命令注册表对该 agent 生效的完整清单）。
+/** GET /api/mobile/v1/commands?sessionId=…（token）：会话有效命令目录（commands.list，与桌面
+ * Web 端命令面板同源）。
  * 响应：{ ok, items:[{name, description, input?:{hint}}] }；网关未组合或失败时降级为空清单，
- * 客户端菜单据此只展示真实可执行的命令（不再硬编码）。
+ * 客户端菜单据此只展示真实可执行的命令。
  *
- * 失败一律降级成空清单是**刻意设计**：输入区不能因为目录拉不到就报错。代价是这个端点
- * 出问题时手机上看不出任何提示，「+」菜单静默只剩媒体与文件两行 —— 2026-10 宿主升到
- * 0.2.1 要求每个请求自带 Peer，这条路径没跟上，用户看到的就是「目标、计划、指令全没了」。 */
+ * 失败一律降级成空清单是刻意设计：输入区不能因为目录拉不到就报错。代价是这个端点出问题时
+ * 手机上看不出提示，「+」菜单静默只剩媒体与文件两行。 */
 async function handleCommands(ctx, req, res) {
   const sessionId = new URL(req.url, 'http://x').searchParams.get('sessionId');
   if (!sessionId) return sendJson(res, 400, { ok: false, error: { code: 'bad-request', message: '缺少 sessionId' } });

package/lib/mobile/session-snapshot.js

@@ -77,12 +77,10 @@ async function buildStatsSnapshot(ctx, sessionId) {
 /**
  * 统计投影快照（handleStats 与 buildStatsSnapshot 共用）。
  *
- * 0.2.0 把整帧投影从 session.history/page 的返回值里拆走了（page 只回
- * events/hasMore/cursor），所以「拉 1 条历史顺带取投影」这条路已经断了；改走
- * host-bridge 翻译出来的 `apiProxy.sessions.projections({ request: { sessionId } })`，
- * 返回值是 `{ asOfSeq, values }`。顺带把 plan 归一化成 planMode（plan.active 加可选的
- * pending），排队条与计划条读的是 planMode。历史轮询是每 5 秒一次的热路径，多背一次
- * 投影 RPC 划不来，所以宁可让统计单独走投影端点。
+ * 0.2.0 把整帧投影从 history/page 的返回值里拆走了，「拉一条历史顺带取投影」这条路断了；
+ * 改走 `apiProxy.sessions.projections({ request: { sessionId } })`，返回值是
+ * `{ asOfSeq, values }`。顺带把 plan 归一化成 planMode（排队条与计划条读它）。
+ * 历史轮询是每 5 秒一次的热路径，多背一次投影 RPC 划不来，所以统计单独走投影端点。
  */
 async function statsProjections(ctx, sessionId) {
   // 显式给 signal：宿主部分方法内部直接读 signal.aborted，不做 undefined 兜底。

package/lib/mobile/sessions.js

@@ -1,32 +1,16 @@
 'use strict';
 
 /**
- * 移动端会话 API 的**会话列表**与**新建会话**。
+ * 移动端会话 API 的会话列表与新建会话。
  *
- * 本文件一度是 1964 行的单体，HTTP 路由、宿主 RPC、缓存、事件派生全混在一起；而且
- * 它是 lib/mobile 下被引用最多的模块——stream / credentials / skills / subagents /
- * workspaces / host-settings 全都从它取 unwrap、callSessions、缓存访问器，于是它成了
- * 事实上的公共工具库，谁都不好动。现在按域拆开：
- *
- *   envelope.js        信封拆解（unwrap / envelopeValue），唯一的实现
- *   rpc.js             对宿主 apiProxy 的窄接口封装（callSessions / callAgentPresets）
- *   session-cache.js   按 ctx 隔离的状态表，全部 WeakMap 集中在这里
- *   attachments.js     图片附件还原
- *   completion.js      完成提醒状态机
- *   session-models.js  模型目录与切模型
- *   session-search.js  正文检索
- *   session-send.js    发消息 / slash 命令 / 读 / 附件重取 / 停 / 改名 / 分叉
- *   session-snapshot.js 消息与统计快照（镜像与分页共用）
- *   session-mirror.js  镜像整帧构建
- *   session-goal.js    目标条动作
- *   session-presets.js Agent 预设目录
- *   session-preview.js 列表行的 lastMessage 预览（按会话指纹复用 + 运行中会话的节流）
- *   session-list-shortcut.js `?rev=` 条件刷新记住的那份清单是谁
+ * 这个文件一度是一千九百多行的单体，HTTP 路由、宿主 RPC、缓存、事件派生全混在一起；现在
+ * 按域拆开：envelope（信封拆解）、rpc（窄接口封装）、session-cache（按 ctx 隔离的状态表）、
+ * attachments、completion、session-models、session-search、session-send、session-snapshot、
+ * session-mirror、session-goal、session-presets、session-preview、session-list-shortcut。
  *
  * 剩下的就是列表：GET /sessions（10 秒缓存 + fresh 绕过 + 完成态确认 + `?rev=` 条件刷新）、
- * GET /session（单会话摘要）、GET /session/head（正文水位探针）、GET /session/stats、
- * 新建会话、排队消息动作。**本文件继续从各子模块转出导出**，
- * 所以 lib/mobile 下所有 import 路径一行都不用改。
+ * 单会话摘要、正文水位探针、统计、新建会话、排队消息动作。本文件继续转出各子模块的导出，
+ * 所以 lib/mobile 下的 import 路径一行都不用改。
  */
 
 const { sendJson, readJsonBody } = require('../shared/http-util');

package/lib/mobile/stats-collect.cjs

@@ -3,31 +3,27 @@
 /**
  * 统计采集：把宿主每条会话的累计用量读出来，和水位一比，增量记进账本。
  *
- * 为什么不重放会话事件：那是 dsh-context 在桌面上干的事（它让宿主注册一份投影，
- * 每个事件折一次）。手机这边要的是「按天看个大概」，重放整条日志在宿主上是一笔
- * 每秒都在烧的开销，而我们每轮只需要一个数 —— 会话的累计用量。
+ * 不重放会话事件：手机要的是「按天看个大概」，重放整条日志是每秒都在烧的开销。所以走水位差
+ * （宿主累计值 − 账本水位 = 这次入账的量），零依赖，代价是入账日期取「插件看到增量的那一天」，
+ * 跨零点的一轮会落在后一天。首采会把历史全量入账，日期取它最后一次活动的日期，算一次性回填。
  *
- * 所以走水位差：
- *   宿主累计值 − 账本记下的水位 = 这次该入账的量。
- * 好处是零依赖（只用现有的会话投影接口，不需要宿主新能力，也不用装别家插件），
- * 代价如实说：入账日期取「插件看到增量的那一天」，跨零点的一轮会落在后一天。
- * 这是刻意的近似 —— 为一个几十分钟的边界去重放事件流不值得。
+ * 采集分三条路进来：打开统计页 / 下拉刷新（`DEFAULT_BUDGET_MS`）、宿主侧每几分钟自己跑一轮
+ * （`PERIODIC_INTERVAL_MS`，只会读真有变动的会话）、以及删除会话之前的那一刀补采。
  *
- * 首采（账本里没有这条会话）会把它的历史全量入账，日期取它最后一次活动的日期：
- * 这是一次性回填，用户装上这个版本之后第一次打开统计页就会看见过去的用量，
- * 而不是从今天零点重新计数。
+ * 清理前那次补采（`skipPreview`）不读「最后一句」：那一步要读会话日志，是整轮最重的一趟，
+ * 而删除不可恢复、时间又卡在请求预算里。宁可让首次见到的会话卡片少一行摘要。
  *
- * 采集是**按需**的（打开统计页 / 下拉刷新 / 清理已归档前补一刀），没有后台定时器：
- * 手机上没人看统计的时候不该让宿主一直读盘。
- *
- * 清理前那次补采（`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');
 
 /** 同一条会话两次采集之间的最小间隔（打开页面时的重复请求直接复用上一轮结果）。 */
@@ -39,11 +35,9 @@ const CONCURRENCY = 4;
 /**
  * 这一轮先扫「最近还在动」的会话，再按「最久没采过」补老账。
  *
- * 之前每一轮都只按最后活动时间倒序扫、1.5 秒到点就停，于是最老的那批永远排在队尾、
- * 永远采不到（实测七十多条会话从没进过账本，其中大多是子代理）。现在把队列分成两段：
- * 近 7 天有动作的照旧优先（它们才是数字在变的那批），其余的按 `collectedAt` 升序 ——
- * 采过的会顺手把时间推到当下、自动排到队尾，于是每一轮的预算都接着上一轮的地方往下走，
- * 不需要额外持久化一个游标。
+ * 只按最后活动时间倒序扫会让最老的那批永远排在队尾、永远采不到。所以队列分两段：近 7 天有
+ * 动作的优先（它们才是数字在变的那批），其余按 `collectedAt` 升序 —— 采过的会把时间推到当下、
+ * 自动排到队尾，每一轮的预算接着上一轮往下走，不需要额外持久化游标。
  */
 const RECENT_WINDOW_MS = 7 * 86400_000;
 
@@ -51,13 +45,32 @@ const RECENT_WINDOW_MS = 7 * 86400_000;
  * 一次采集的时间预算。
  *
  * 手机上点开统计页时，插件会当场把每条会话的累计用量读一遍；一百多条会话串起来能拖到
- * 十几秒（每条两趟宿主调用），用户看到的就是「点统计，转好久」（2026-10-22 真机）。
+ * 十几秒（每条两趟宿主调用），用户看到的就是「点统计，转好久」。
  * 所以给这一趟设上限：到点就停，把**已经采到的**那部分记进账本先回给手机，剩下的等
  * 下一次打开 / 下拉刷新接着采 —— 水位差是累积的，采一半不会算错，只是数字暂时偏小。
  */
 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 '';
@@ -76,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。 */
@@ -145,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;
+  }
+}
+
 /**
  * 采集串行化：同一时刻只跑一轮。
  *
@@ -182,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;
+      }
     }
   }
 
@@ -217,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;
       }
 
@@ -238,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) {
         // 最后一条消息的摘要只在真有增量时去读（它是日志，属于重活）：
         // 卡片上那一行「最后一句说了什么」比什么都更能让人认出这是哪条会话。
@@ -256,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;
         // 上下文构成是**这条会话**的快照：跟着记录走，页面才能说清「这是哪条会话的构成」。
         // 以前全局只留一份、每轮被最后读完的那条覆盖（四条并发，谁后回是谁），
         // 于是卡片上的构成跟用户此刻在用的那条毫无关系。
@@ -286,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,
 };