dsh-key-usage 0.1.1 → 0.1.3

package/lib/index.js

@@ -37,6 +37,9 @@ export function apply(ctx) {
         },
     });
     ctx.inject(['webServer'], (host) => {
-        host.effect(() => mountKeyUsageRoutes(host.webServer, sessionSource, liveQuota), 'dsh-key-usage: http routes');
+        host.effect(() => mountKeyUsageRoutes(host.webServer, sessionSource, liveQuota, {
+            // workspaceRegistry 用来读官方归档集合（拿不到就回退本地 storages/workspace.json）
+            get: (serviceName) => (typeof ctx.get === 'function' ? ctx.get(serviceName) : undefined),
+        }), 'dsh-key-usage: http routes');
     });
 }

package/lib/live-quota.js

@@ -11,7 +11,62 @@ function textOf(value) {
         return String(value);
     return null;
 }
-/** OpenCode Go：GET https://opencode.ai/zen/go/v1/usage → usage.rolling / weekly / monthly。 */
+/** 金额字段：官方既有字符串（DeepSeek）也有数字（Moonshot），两种都接受，统一输出原样字符串。 */
+function amountTextOf(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? String(value) : null;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed !== '' && Number.isFinite(Number(trimmed)) ? trimmed : null;
+    }
+    return null;
+}
+/** 金额 / 百分比的数值形态：接受 number 与数字字符串，其它一律 null。 */
+function amountOf(value) {
+    const text = amountTextOf(value);
+    if (text === null)
+        return null;
+    const parsed = Number(text);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/** epoch → ISO：13 位按毫秒、10 位按秒；越界返回 null。 */
+function isoFromEpoch(value) {
+    const milliseconds = value >= 1e11 || value < 1e9 ? value : value * 1000;
+    const date = new Date(milliseconds);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+/** 重置时间：官方为 ISO 字符串，兼容 epoch 毫秒 / 秒（数字或纯数字字符串）；识别不出时原样保留。 */
+function resetAtOf(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? isoFromEpoch(value) : null;
+    if (typeof value !== 'string' || value === '')
+        return null;
+    const trimmed = value.trim();
+    if (/^\d{9,14}$/.test(trimmed))
+        return isoFromEpoch(Number(trimmed));
+    return value;
+}
+/** 接口没返回币种时的兜底：按站点判定（Z.AI 海外站按美元计价，BigModel / Moonshot 国内站按人民币）。 */
+function currencyFromHost(requestUrl, fallback) {
+    let host = '';
+    try {
+        host = new URL(requestUrl).hostname.toLowerCase();
+    }
+    catch {
+        return fallback;
+    }
+    if (host === 'z.ai' || host.endsWith('.z.ai'))
+        return 'USD';
+    if (host === 'bigmodel.cn' || host.endsWith('.bigmodel.cn'))
+        return 'CNY';
+    if (host === 'moonshot.cn' || host.endsWith('.moonshot.cn'))
+        return 'CNY';
+    return fallback;
+}
+/**
+ * OpenCode Go：GET https://opencode.ai/zen/go/v1/usage → usage.rolling / weekly / monthly。
+ * 该端点未收录于官方文档（opencode.ai/docs/go 只指向 console），字段结构取自社区实现，见 test/fixtures/providers/opencode-go。
+ */
 const OPENCODE_GO_SCHEME = {
     url: () => 'https://opencode.ai/zen/go/v1/usage',
     parse: (body) => {
@@ -24,13 +79,14 @@ const OPENCODE_GO_SCHEME = {
             const raw = usage[sourceKey];
             if (!isObject(raw))
                 continue;
-            const percent = typeof raw.percent === 'number' ? raw.percent : Number(raw.percent);
-            if (!Number.isFinite(percent))
+            // 社区实现里 percent 可能是字符串、resetsAt 可能是 epoch，两者都按漂移兼容处理
+            const percent = amountOf(raw.percent);
+            if (percent === null)
                 continue;
             windows.push({
                 key: windowKey,
                 percent,
-                resetsAt: textOf(raw.resetsAt),
+                resetsAt: resetAtOf(raw.resetsAt),
                 status: typeof raw.status === 'string' ? raw.status : null,
             });
         }
@@ -41,22 +97,26 @@ const OPENCODE_GO_SCHEME = {
 function balanceScheme(path, parse, fallbackOrigin) {
     return {
         url: (baseURL) => new URL(path, baseURL ?? fallbackOrigin).href,
-        parse: (body) => ({ balance: isObject(body) ? parse(body) : null, windows: null }),
+        parse: (body, requestUrl) => ({ balance: isObject(body) ? parse(body, requestUrl) : null, windows: null }),
     };
 }
 const SCHEMES = {
     'opencode-go': OPENCODE_GO_SCHEME,
     // DeepSeek: GET {origin}/user/balance → balance_infos[{currency,total_balance,granted_balance,topped_up_balance}]
     'deepseek-official': balanceScheme('/user/balance', (body) => {
-        const infos = Array.isArray(body.balance_infos) ? body.balance_infos : [];
-        const info = infos.find((entry) => isObject(entry) && entry.currency === 'CNY') ?? infos[0];
-        if (!isObject(info))
+        // 文档 balance_infos[].currency 只可能是 CNY / USD：没有 CNY 项时退回第一项，并如实保留它的币种
+        const infos = (Array.isArray(body.balance_infos) ? body.balance_infos : []).filter(isObject);
+        const info = infos.find((entry) => (textOf(entry.currency) ?? '').toUpperCase() === 'CNY') ?? infos[0];
+        if (info === undefined)
+            return null;
+        const total = amountTextOf(info.total_balance);
+        const granted = amountTextOf(info.granted_balance);
+        const toppedUp = amountTextOf(info.topped_up_balance);
+        // 三个金额全缺说明结构已经漂移，判 bad-json，不返回「只有币种」的空壳成功
+        if (total === null && granted === null && toppedUp === null)
             return null;
         const balance = {};
         const currency = textOf(info.currency);
-        const total = textOf(info.total_balance);
-        const granted = textOf(info.granted_balance);
-        const toppedUp = textOf(info.topped_up_balance);
         if (currency !== null)
             balance.currency = currency;
         if (total !== null)
@@ -65,29 +125,31 @@ const SCHEMES = {
             balance.giftBalance = granted;
         if (toppedUp !== null)
             balance.topUpBalance = toppedUp;
-        return Object.keys(balance).length > 0 ? balance : null;
+        return balance;
     }, 'https://api.deepseek.com'),
     // OpenRouter: GET {origin}/api/v1/credits（需要 Management Key）
     openrouter: balanceScheme('/api/v1/credits', (body) => {
         const data = isObject(body.data) ? body.data : null;
         if (data === null)
             return null;
-        const totalCredits = typeof data.total_credits === 'number' ? data.total_credits : null;
-        const totalUsage = typeof data.total_usage === 'number' ? data.total_usage : null;
+        const totalCredits = amountOf(data.total_credits);
+        const totalUsage = amountOf(data.total_usage);
         if (totalCredits === null || totalUsage === null)
             return null;
         return { currency: 'USD', totalBalance: (totalCredits - totalUsage).toFixed(2) };
     }, 'https://openrouter.ai'),
-    // Moonshot / Kimi: GET {origin}/v1/users/me/balance
-    moonshotai: balanceScheme('/v1/users/me/balance', (body) => {
+    // Moonshot / Kimi: GET {origin}/v1/users/me/balance（文档未定义 currency 字段，国内站按人民币计）
+    moonshotai: balanceScheme('/v1/users/me/balance', (body, requestUrl) => {
         const data = isObject(body.data) ? body.data : null;
         if (data === null)
             return null;
+        const available = amountTextOf(data.available_balance);
+        const cash = amountTextOf(data.cash_balance);
+        const voucher = amountTextOf(data.voucher_balance);
+        if (available === null && cash === null && voucher === null)
+            return null;
         const balance = {};
-        const currency = textOf(data.currency);
-        const available = textOf(data.available_balance);
-        const cash = textOf(data.cash_balance);
-        const voucher = textOf(data.voucher_balance);
+        const currency = textOf(data.currency) ?? currencyFromHost(requestUrl, null);
         if (currency !== null)
             balance.currency = currency;
         if (available !== null)
@@ -96,21 +158,23 @@ const SCHEMES = {
             balance.giftBalance = voucher;
         if (cash !== null)
             balance.topUpBalance = cash;
-        return Object.keys(balance).length > 0 ? balance : null;
+        return balance;
     }, 'https://api.moonshot.cn'),
-    // Z.AI / GLM: GET {origin}/api/paas/v4/balance
-    zai: balanceScheme('/api/paas/v4/balance', (body) => {
+    // Z.AI / GLM: GET {origin}/api/paas/v4/balance（官方文档未收录，接口自带 currency 时才采信）
+    zai: balanceScheme('/api/paas/v4/balance', (body, requestUrl) => {
         const data = isObject(body.data) ? body.data : null;
         if (data === null)
             return null;
-        const balance = { currency: 'CNY' };
-        const total = textOf(data.total_balance);
-        const available = textOf(data.available_balance);
+        const total = amountTextOf(data.total_balance);
+        const available = amountTextOf(data.available_balance);
+        if (total === null && available === null)
+            return null;
+        const balance = { currency: textOf(data.currency) ?? currencyFromHost(requestUrl, 'CNY') };
         if (total !== null)
             balance.totalBalance = total;
         if (available !== null)
             balance.availableBalance = available;
-        return Object.keys(balance).length > 1 ? balance : null;
+        return balance;
     }, 'https://api.z.ai'),
 };
 /** provider id → 方案 id（事件里的 provider 可能是路由名，先取末段）。 */
@@ -133,7 +197,8 @@ async function queryOne(schemeId, apiKey, baseURL, fetchImpl) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
     try {
-        const response = await fetchImpl(scheme.url(baseURL), {
+        const requestUrl = scheme.url(baseURL);
+        const response = await fetchImpl(requestUrl, {
             headers: { Authorization: 'Bearer ' + apiKey, Accept: 'application/json' },
             signal: controller.signal,
         });
@@ -142,7 +207,8 @@ async function queryOne(schemeId, apiKey, baseURL, fetchImpl) {
         if (!response.ok)
             return { balance: null, windows: null, error: 'http-' + String(response.status) };
         const raw = await response.text();
-        if (raw.length > MAX_RESPONSE_BYTES)
+        // 上限按**字节**算：raw.length 是 UTF-16 码元数，中文响应会因此超限仍被接受
+        if (Buffer.byteLength(raw, 'utf8') > MAX_RESPONSE_BYTES)
             return { balance: null, windows: null, error: 'too-large' };
         let body;
         try {
@@ -151,7 +217,7 @@ async function queryOne(schemeId, apiKey, baseURL, fetchImpl) {
         catch {
             return { balance: null, windows: null, error: 'bad-json' };
         }
-        const parsed = scheme.parse(body);
+        const parsed = scheme.parse(body, requestUrl);
         if (parsed.balance === null && parsed.windows === null)
             return { balance: null, windows: null, error: 'bad-json' };
         return { ...parsed, error: null };

package/lib/quota-snapshots.js

@@ -0,0 +1,68 @@
+/**
+ * 余额 / 窗口快照的本地持久化。
+ *
+ * 为什么需要：宿主那份 `dsh-usage/provider-snapshots.json` 由别的组件写，本机实测从 2026-09-30
+ * 起就停更了 —— 实时查询一旦失败，界面就只剩十几天前的旧值（截图里的「已 13 天未更新」）。
+ * 这里在**每次实时查询成功后**立刻落一份自己的快照，失败时优先回落到它，
+ * 把数据断档压缩到「最近一次成功查询」为止。
+ *
+ * 约定：只写插件自己的文件（`$DSH_HOME/dsh-key-usage/quota-snapshots.json`），不碰宿主的文件；
+ * 读写失败一律忽略（返回空 / 不写），绝不影响接口可用性。
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** 读快照；文件缺失、损坏、结构不符一律返回空数组。 */
+export function readQuotaSnapshots(path) {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const providers = document?.providers;
+    if (!isObject(providers))
+        return [];
+    const entries = [];
+    for (const [id, raw] of Object.entries(providers)) {
+        if (!isObject(raw))
+            continue;
+        if (typeof raw.updatedAt !== 'number' || !Number.isFinite(raw.updatedAt))
+            continue;
+        const windows = Array.isArray(raw.windows)
+            ? raw.windows.filter((window) => isObject(window) && typeof window.key === 'string' && typeof window.percent === 'number')
+            : null;
+        entries.push({
+            provider: typeof raw.provider === 'string' ? raw.provider : id,
+            displayName: typeof raw.displayName === 'string' ? raw.displayName : null,
+            updatedAt: raw.updatedAt,
+            balance: isObject(raw.balance) ? raw.balance : null,
+            windows: windows !== null && windows.length > 0 ? windows : null,
+        });
+    }
+    return entries;
+}
+/**
+ * 合并写入：本次成功的通道覆盖旧值，其余通道保留（避免一次只刷新部分通道时把别的通道抹掉）。
+ * 先写临时文件再改名，避免读到半截 JSON；任何异常都吞掉。
+ */
+export function writeQuotaSnapshots(path, entries) {
+    if (entries.length === 0)
+        return;
+    try {
+        const merged = new Map(readQuotaSnapshots(path).map((entry) => [entry.provider, entry]));
+        for (const entry of entries)
+            merged.set(entry.provider, entry);
+        const document = { version: 1, providers: Object.fromEntries(merged) };
+        mkdirSync(dirname(path), { recursive: true });
+        const temporaryPath = path + '.tmp';
+        writeFileSync(temporaryPath, JSON.stringify(document, null, 2) + '\n', 'utf8');
+        renameSync(temporaryPath, path);
+    }
+    catch {
+        // 快照只是加速回落，写不了就不写
+    }
+}

package/lib/routes.js

@@ -7,6 +7,7 @@
  * - /dsh-key-usage/summary   总览表用的「今日 / 近 30 天」按通道汇总
  * - /dsh-key-usage/sessions  会话用量（来自宿主会话事件折叠）
  * - /dsh-key-usage/projects  项目（工作目录）用量
+ * - /dsh-key-usage/models    模型（provider + model）用量与估算成本
  *
  * 台账已停更时（本机停在 2026-09-30），按天序列会用会话事件补齐缺的日期（见 merge.ts），
  * 并在响应里用 `sessionDates` 标出来源。非本机回环请求一律 403。
@@ -19,7 +20,10 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { aggregateRange, buildPriceTable, estimateCost, readLedger, } from './ledger.js';
 import { classifyChannels, costModeLabel, extractChannels, quotaWindowLabel, readProviderSnapshots, } from './collect.js';
-import { hoursOfDate, projectRowsOf, sessionRowsOf, } from './sessions.js';
+import { schemeIdOf } from './live-quota.js';
+import { hoursOfDate, modelRowsOf, projectRowsOf, sessionRowsOf, } from './sessions.js';
+import { createArchiveSource, createTitleSource } from './session-meta.js';
+import { readQuotaSnapshots, writeQuotaSnapshots } from './quota-snapshots.js';
 import { mergeDailySeries, sessionDayRows, summarizeMergedByProvider, totalsOfMerged, } from './merge.js';
 /** 无会话服务时的兜底数据源，保证台账相关端点照常工作。 */
 export const unavailableSessionSource = {
@@ -62,9 +66,14 @@ function channelPayload(channel) {
         quotaWindowLabel: channel.quotaWindowKey === null ? null : quotaWindowLabel(channel.quotaWindowKey),
     };
 }
-export function mountKeyUsageRoutes(webServer, sessionSource = unavailableSessionSource, liveQuota = disabledLiveQuota) {
+export function mountKeyUsageRoutes(webServer, sessionSource = unavailableSessionSource, liveQuota = disabledLiveQuota, hostServices = { get: () => undefined }) {
     const ledgerPath = join(dshHomePath(), 'dsh-usage', 'usage-ledger.json');
     const snapshotPath = join(dshHomePath(), 'dsh-usage', 'provider-snapshots.json');
+    const titleSource = createTitleSource(join(dshHomePath(), 'storages', 'session_projcache.json'));
+    const archiveSource = createArchiveSource(hostServices, join(dshHomePath(), 'storages', 'workspace.json'));
+    const quotaSnapshotPath = join(dshHomePath(), 'dsh-key-usage', 'quota-snapshots.json');
+    /** 会话标题与归档状态：宿主服务/缓存文件都拿不到时返回空集合，界面自行回落。 */
+    const sessionMeta = () => ({ titles: titleSource.titles(), archived: archiveSource.archived() });
     const loadLedger = () => readLedger(ledgerPath, (path) => {
         try {
             return readFileSync(path, 'utf8');
@@ -181,15 +190,31 @@ export function mountKeyUsageRoutes(webServer, sessionSource = unavailableSessio
             const live = url.searchParams.get('fresh') === '1'
                 ? await liveQuota.refreshIfStale(channels, true)
                 : await liveQuota.refreshIfStale(channels);
+            // 实时成功立刻落一份自己的快照：下次失败时回落的是「最近一次成功」，而不是宿主那份十几天前的旧值
+            const succeeded = [];
+            for (const entry of live.values()) {
+                if (!entry.ok)
+                    continue;
+                succeeded.push({
+                    provider: entry.provider,
+                    displayName: channels.find((channel) => channel.provider === entry.provider)?.displayName ?? null,
+                    updatedAt: entry.fetchedAt,
+                    balance: entry.balance,
+                    windows: entry.windows,
+                });
+            }
+            writeQuotaSnapshots(quotaSnapshotPath, succeeded);
+            const ownSnapshots = readQuotaSnapshots(quotaSnapshotPath);
             const snapshots = readSnapshots();
             const providers = channels.map((channel) => {
                 const liveEntry = live.get(channel.provider);
-                const snapshot = snapshots.find((entry) => entry.provider === channel.provider) ?? null;
+                const supported = schemeIdOf(channel.provider) !== null;
                 if (liveEntry !== undefined && liveEntry.ok) {
                     return {
                         provider: channel.provider,
                         displayName: channel.displayName,
                         credential: channel.apiKeyEnv,
+                        supported,
                         source: 'live',
                         fetchedAt: liveEntry.fetchedAt,
                         updatedAt: liveEntry.fetchedAt,
@@ -198,17 +223,27 @@ export function mountKeyUsageRoutes(webServer, sessionSource = unavailableSessio
                         plan: liveEntry.windows === null ? null : { windows: liveEntry.windows },
                     };
                 }
+                // 回落顺序：自己的快照与宿主的快照里，取 updatedAt 更新的那一份
+                const own = ownSnapshots.find((entry) => entry.provider === channel.provider) ?? null;
+                const host = snapshots.find((entry) => entry.provider === channel.provider) ?? null;
+                const useOwn = own !== null && (host === null || own.updatedAt >= (host.updatedAt ?? 0));
+                const updatedAt = useOwn ? own.updatedAt : host?.updatedAt ?? null;
+                const fallbackBalance = useOwn ? own.balance : host?.balance ?? null;
+                const fallbackPlan = useOwn
+                    ? (own.windows === null ? null : { windows: own.windows })
+                    : host?.plan ?? null;
                 return {
                     provider: channel.provider,
-                    displayName: snapshot?.displayName ?? channel.displayName,
-                    credential: snapshot?.credential ?? channel.apiKeyEnv,
+                    displayName: host?.displayName ?? channel.displayName,
+                    credential: host?.credential ?? channel.apiKeyEnv,
+                    supported,
                     source: 'snapshot',
                     fetchedAt: null,
-                    updatedAt: snapshot?.updatedAt ?? null,
+                    updatedAt,
                     // 实时失败的原因要透出（未配置凭据 / 网络 / 鉴权），界面据此提示
-                    error: liveEntry?.error ?? (snapshot === null ? 'no-snapshot' : null),
-                    balance: snapshot?.balance ?? null,
-                    plan: snapshot?.plan ?? null,
+                    error: liveEntry?.error ?? (updatedAt === null ? 'no-snapshot' : null),
+                    balance: fallbackBalance,
+                    plan: fallbackPlan,
                 };
             });
             sendJson(response, 200, { providers });
@@ -260,7 +295,8 @@ export function mountKeyUsageRoutes(webServer, sessionSource = unavailableSessio
             const costModeOf = new Map(channels.map((channel) => [channel.provider, channel.costMode]));
             const { records, coverage } = await sessionSource.collect();
             const priceTable = buildPriceTable(loadLedger());
-            const rows = sessionRowsOf(records, knownProviders).slice(0, limit).map((row) => ({
+            const meta = sessionMeta();
+            const rows = sessionRowsOf(records, knownProviders, meta).slice(0, limit).map((row) => ({
                 ...row,
                 providerLabel: channels.find((channel) => channel.provider === row.provider)?.displayName ?? row.provider,
                 costMode: row.provider === null ? null : costModeOf.get(row.provider) ?? null,
@@ -281,7 +317,7 @@ export function mountKeyUsageRoutes(webServer, sessionSource = unavailableSessio
             const knownProviders = channels.map((channel) => channel.provider);
             const { records, coverage } = await sessionSource.collect();
             const priceTable = buildPriceTable(loadLedger());
-            const rows = projectRowsOf(records, knownProviders).slice(0, limit).map((row) => ({
+            const rows = projectRowsOf(records, knownProviders, sessionMeta()).slice(0, limit).map((row) => ({
                 ...row,
                 dominantProvider: Object.entries(row.providers).sort((first, second) => second[1] - first[1])[0]?.[0] ?? null,
                 cost: estimateCost(row.models, priceTable),
@@ -289,6 +325,29 @@ export function mountKeyUsageRoutes(webServer, sessionSource = unavailableSessio
             sendJson(response, 200, { rows, coverage, priced: priceTable.size > 0 });
         },
     });
+    webServer.register({
+        kind: 'exact',
+        path: '/dsh-key-usage/models',
+        handler: async (request, response) => {
+            if (!requireLoopback(request, response))
+                return;
+            const url = new URL(request.url ?? '/', 'http://localhost');
+            const limit = parseLimit(url.searchParams.get('limit'), 200);
+            const channels = loadChannels();
+            const knownProviders = channels.map((channel) => channel.provider);
+            const costModeOf = new Map(channels.map((channel) => [channel.provider, channel.costMode]));
+            const { records, coverage } = await sessionSource.collect();
+            const priceTable = buildPriceTable(loadLedger());
+            const rows = modelRowsOf(records, knownProviders).slice(0, limit).map((row) => ({
+                ...row,
+                providerLabel: channels.find((channel) => channel.provider === row.provider)?.displayName ?? row.provider,
+                costMode: costModeOf.get(row.provider) ?? null,
+                // 与 /sessions 同一口径：按台账反推的均价估算，不是官方账单金额
+                cost: estimateCost([{ provider: row.provider, model: row.model, tokens: row.tokens }], priceTable),
+            }));
+            sendJson(response, 200, { rows, coverage, priced: priceTable.size > 0 });
+        },
+    });
 }
 /**
  * 把实时余额 / 窗口合并进快照数组，供通道状态判定（额度百分比、余额文案）使用。

package/lib/session-meta.js

@@ -0,0 +1,101 @@
+/**
+ * 会话标题与归档状态的本地来源。
+ *
+ * - **标题**：宿主把「会话标题」存在投影缓存 `$DSH_HOME/storages/session_projcache.json`
+ *   的 `tables.sessions.<id>.rows.title.val`；只有被宿主投影过的会话才有，
+ *   其余由 `session-usage.ts` 折叠出的「首条用户提问」兜底。
+ * - **归档**：优先读宿主只读服务 `workspaceRegistry.archivedSessionIds`（官方接口）；
+ *   服务不可用时回退 `$DSH_HOME/storages/workspace.json` 的 `global.archivedSessionIds`。
+ *
+ * 两个文件都是普通 JSON，只读、不写；解析失败一律退化为「没有数据」，不影响统计。
+ */
+import { readFileSync, statSync } from 'node:fs';
+/** 宿主会话 id 两种写法（`session-<uuid>` / 裸 `<uuid>`）统一成裸 uuid 便于比对。 */
+export function normalizeSessionId(id) {
+    const lowered = id.toLowerCase();
+    return lowered.startsWith('session-') ? lowered.slice('session-'.length) : lowered;
+}
+function readJson(path, readText) {
+    const text = readText(path);
+    if (text === null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** 读取 `session_projcache.json` 里的会话标题表（按 mtime 缓存，避免每次请求都解析 2 MB JSON）。 */
+export function createTitleSource(cachePath, readText = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}) {
+    let cache = null;
+    return {
+        titles: () => {
+            let mtimeMs = 0;
+            try {
+                mtimeMs = statSync(cachePath).mtimeMs;
+            }
+            catch {
+                return new Map();
+            }
+            if (cache !== null && cache.mtimeMs === mtimeMs)
+                return cache.value;
+            const value = parseTitles(readJson(cachePath, readText));
+            cache = { mtimeMs, value };
+            return value;
+        },
+    };
+}
+/** 从投影缓存文档里取出 id → 标题（结构不符时返回空表）。 */
+export function parseTitles(document) {
+    const titles = new Map();
+    const sessions = document?.tables?.sessions;
+    if (typeof sessions !== 'object' || sessions === null)
+        return titles;
+    for (const [id, entry] of Object.entries(sessions)) {
+        const value = entry?.rows?.title?.val;
+        if (typeof value !== 'string')
+            continue;
+        const trimmed = value.trim();
+        if (trimmed !== '')
+            titles.set(normalizeSessionId(id), trimmed);
+    }
+    return titles;
+}
+/** 归档会话 id 集合（归一后用于比对）。 */
+export function createArchiveSource(host, workspacePath, readText = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}) {
+    const fromFile = () => {
+        const document = readJson(workspacePath, readText);
+        const ids = document?.global?.archivedSessionIds;
+        return new Set(Array.isArray(ids) ? ids.filter((id) => typeof id === 'string').map(normalizeSessionId) : []);
+    };
+    return {
+        archived: () => {
+            // 先用宿主官方只读 getter；拿不到再读文件（两者都是权威数据，getter 优先）
+            try {
+                const registry = host.get('workspaceRegistry');
+                if (registry !== null && registry !== undefined && Array.isArray(registry.archivedSessionIds)) {
+                    return new Set(registry.archivedSessionIds.filter((id) => typeof id === 'string').map(normalizeSessionId));
+                }
+            }
+            catch {
+                // 落到文件
+            }
+            return fromFile();
+        },
+    };
+}

package/lib/session-usage.js

@@ -86,6 +86,8 @@ export function foldSessionEvents(events) {
     let currentModel = null;
     let firstTime = null;
     let lastTime = null;
+    // 会话标题在宿主侧只对有投影的会话可见，其余用「首条用户提问」兜底
+    let firstPrompt = null;
     for (const event of events) {
         const time = typeof event.time === 'number' ? event.time : null;
         if (time !== null) {
@@ -99,6 +101,9 @@ export function foldSessionEvents(events) {
             if (model !== null)
                 currentModel = model;
         }
+        if (firstPrompt === null && event.type === 'user/message') {
+            firstPrompt = promptTextOf(event);
+        }
         const turn = event.data?.turn;
         const step = event.data?.step;
         const baseKey = Number.isInteger(turn) && Number.isInteger(step) ? `${turn}:${step}` : `seq:${event.seq}`;
@@ -119,7 +124,33 @@ export function foldSessionEvents(events) {
             buckets: bucketsOf(sample.usage),
         });
     }
-    return { samples, firstTime, lastTime };
+    return { samples, firstTime, lastTime, firstPrompt };
+}
+/** 标题兜底：取用户消息里第一个非空文本块，压平空白并截断。 */
+function promptTextOf(event) {
+    const data = event.data;
+    if (typeof data !== 'object' || data === null)
+        return null;
+    // `user/message` 的正文在 `data.content`（宿主 dsh-context 就是这么读的），
+    // `assistant/message` 才用 `data.message.content` —— 两种都认，避免形状差异导致标题全空。
+    const direct = data.content;
+    const nested = data.message?.content;
+    const content = Array.isArray(direct) ? direct : Array.isArray(nested) ? nested : null;
+    if (content === null)
+        return null;
+    for (const block of content) {
+        // 文本块既可能是对象，也可能是裸字符串
+        const text = typeof block === 'string'
+            ? block
+            : typeof block === 'object' && block !== null ? block.text : null;
+        if (typeof text !== 'string')
+            continue;
+        const flat = text.replace(/\s+/g, ' ').trim();
+        if (flat === '')
+            continue;
+        return flat.length > 60 ? flat.slice(0, 60) + '…' : flat;
+    }
+    return null;
 }
 /**
  * 缓存命中率（百分数，一位小数）：`cacheRead / (input + output + cacheRead)`。
@@ -187,6 +218,7 @@ export function summarizeSession(fold) {
         cacheHitRate: cacheHitRateOf(totals),
         firstTime: fold.firstTime,
         lastTime: fold.lastTime,
+        firstPrompt: fold.firstPrompt,
         primaryModelKey: models.length > 0 ? models[0].key : null,
         days,
         models,