Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* useUsageHistory — 首页用量仪表盘的数据 hook。
*
* 数据通道: electronAPI.maker.usage.getHistory({days}) — main 侧聚合好
* (热力图日列表 + streak + 异常 + 按模型拆分), renderer 只渲染。
*
* 首帧策略 (设计规范第 7 条 "杜绝跳变/空白帧"):
* - 上次成功的 payload 按账号持久化在 localStorage, hook 初始化时同步 hydrate —
* app 启动后卡片与页面其它部分同帧出现, 不会"过一会突然弹出"。
* - 快照是昨天的也先照常渲染 (数字几乎不变), 真实数据到了静默覆盖。
*
* 刷新策略:
* - mount 拉一次; module-local cache 让路由重挂载瞬时有数据
* - 订阅 onTodaySpendChanged (Claude $) + onTodayTokensChanged (Codex token) 作为
* "有新消费"信号, ~2s debounce 后重拉 (push payload 本身不用, 只当触发器)
* - paused=true (卡片收起) 时不订阅消费推送 — 收起用户的 per-turn 重拉成本归零;
* mount / 展开瞬间仍各拉一次, 摘要行不会陈旧
* - 数据未变时跳过快照写入与监听通知 (cache 引用不变 → 不触发重渲染)
* - main 侧为了不阻塞首帧, 冷启动可能在价格表就绪前返回 (Codex 行 estimatedCostUsd
* 缺失) — 检测到这种情况时安排一次延迟重拉补齐估算金额 (每次加载至多一次)。
*/
import { useEffect, useState } from 'react';
import {
addCompatibleRegionalMoney,
legacyUsdMoney,
normalizeRegionalMoney,
usdMoney,
zeroUsageMoney,
type RegionalMoney,
} from '../../shared/regionalMoney';
import { isDataOwnerPushCurrent } from '@/contexts/dataOwnerGeneration';
import type { Session } from '@/lib/ccAgent.types';
import { onPatch as onSessionPatch } from '@/lib/sessionsBus';
export interface UsageHistoryModel {
agentKind: 'claude-code' | 'codex' | 'pi' | 'media';
model: string;
money: RegionalMoney;
estimatedMoney: RegionalMoney | null;
inputTokens: number;
outputTokens: number;
cacheReadTokens: number;
cacheCreateTokens: number;
}
/** 每日 × 模型明细 — 右栏堆叠柱状图分段。 */
export interface UsageHistoryModelDay {
day: string;
agentKind: 'claude-code' | 'codex' | 'pi' | 'media';
model: string;
money: RegionalMoney;
apiMoney: RegionalMoney;
subscriptionEstimateMoney: RegionalMoney;
tokens: number;
inputTokens?: number;
outputTokens?: number;
cacheReadTokens?: number;
cacheCreateTokens?: number;
}
/** 参与用量合并的电脑 (main 侧 peerUsageSync 的 UsageDeviceSummary 投影)。 */
export interface UsageHistoryDevice {
deviceId: string;
name: string;
platform: string | null;
isSelf: boolean;
/** 最近一次成功读取该设备的时间; 本机与从未读到的设备为 null。 */
syncedAt: number | null;
status: 'ok' | 'syncing' | 'offline' | 'remote-disabled' | 'unsupported' | 'error';
}
const DEVICE_STATUSES = new Set<UsageHistoryDevice['status']>([
'ok',
'syncing',
'offline',
'remote-disabled',
'unsupported',
'error',
]);
export interface UsageHistoryPayload {
generatedAt: number;
todayKey: string;
stale?: boolean;
estimatesPending?: boolean;
/** tokens: 当日合计 (旧快照可能缺该字段, 消费端用 ?? 0 兜底)。 */
days: Array<{ day: string; money: RegionalMoney; tokens?: number }>;
/** 按请求的 modelDays 窗口返回每日 × 模型明细 (旧快照缺该字段时补 [])。 */
modelDaily: UsageHistoryModelDay[];
models: UsageHistoryModel[];
streak: { current: number; longest: number };
totals: {
today: RegionalMoney;
last30Days: RegionalMoney;
last30DaysWithEstimatedValue: RegionalMoney;
last30DaysEstimatedValue: RegionalMoney;
todayTokens: number;
last30DaysTokens: number;
};
anomaly: { isAnomalous: boolean; trailing7DayAvg: RegionalMoney | null };
/** 多设备范围才有: 参与合并的电脑 (含本机)。 */
devices?: UsageHistoryDevice[];
/** true = main 正在从其它电脑读取。 */
devicesSyncing?: boolean;
/** 每日 × 任务 token(「最耗 token 的任务」按范围统计)。taskKey = `${deviceId}:${sessionId}`。 */
taskDaily?: Array<{ day: string; taskKey: string; tokens: number }>;
/** taskDaily 涉及任务的元数据;deviceId 为 'local' 表示本机任务。 */
tasks?: UsageHistoryTask[];
}
export interface UsageHistoryTask {
taskKey: string;
deviceId: string;
sessionId: string;
title: string;
model: string;
providerId: string | null;
source?: string | null;
contextTokens: number;
contextWindow: number;
/** unix ms */
lastActiveAt: number;
}
/** 热力图窗口: 20 周 = 140 天。 */
const HISTORY_WINDOW_DAYS = 140;
const MODEL_WINDOW_DAYS = 30;
const REFRESH_DEBOUNCE_MS = 2000;
/**
* 多设备范围的定时重读间隔。其它电脑产生的用量没有推送到本机, 页面开着时靠它定期
* 触发 main 侧 (同样按 60s 节流的) 跨设备同步; 只看本机时不启用。
*/
const PEER_REFRESH_INTERVAL_MS = 60_000;
/** 价格表冷启动未就绪时的补拉延迟 (对齐 main 侧 5s fetch 超时 + 余量)。 */
const PRICING_RETRY_DELAY_MS = 6000;
/** main 返回 stale 磁盘快照时的补拉延迟: 让后台聚合先完成, 同时保持更新感知。 */
const STALE_RETRY_DELAY_MS = 800;
// v2 后缀:币种语义改为跟随来源(默认 USD)后,旧构建快照里的金额可能带错标
// CNY——直接换 key 让旧快照失效,首帧宁可空态也不闪现错单位;旧 key 顺手清理。
const SNAPSHOT_STORAGE_KEY = 'homeUsageDashboard.lastPayload.v2';
const LEGACY_SNAPSHOT_STORAGE_KEY = 'homeUsageDashboard.lastPayload';
const DEFAULT_SCOPE_KEY = 'anonymous';
function storageKeyForScope(scopeKey: string): string {
return `${SNAPSHOT_STORAGE_KEY}.${encodeURIComponent(scopeKey)}`;
}
interface StoredUsageHistoryDay {
day?: unknown;
money?: unknown;
costUsd?: unknown;
tokens?: unknown;
}
interface StoredUsageHistoryModelDay {
day?: unknown;
agentKind?: unknown;
model?: unknown;
money?: unknown;
amountUsd?: unknown;
apiMoney?: unknown;
apiCostUsd?: unknown;
subscriptionEstimateMoney?: unknown;
subscriptionEstimateUsd?: unknown;
tokens?: unknown;
inputTokens?: unknown;
outputTokens?: unknown;
cacheReadTokens?: unknown;
cacheCreateTokens?: unknown;
}
interface StoredUsageHistoryModel {
agentKind?: unknown;
model?: unknown;
money?: unknown;
costUsd?: unknown;
estimatedMoney?: unknown;
estimatedCostUsd?: unknown;
inputTokens?: unknown;
outputTokens?: unknown;
cacheReadTokens?: unknown;
cacheCreateTokens?: unknown;
}
interface StoredUsageHistoryPayload {
generatedAt?: unknown;
todayKey?: unknown;
stale?: unknown;
estimatesPending?: unknown;
days?: unknown;
modelDaily?: unknown;
models?: unknown;
streak?: unknown;
totals?: unknown;
anomaly?: unknown;
devices?: unknown;
}
function finiteNumber(value: unknown, fallback = 0): number {
return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
}
function isAgentKind(value: unknown): value is UsageHistoryModel['agentKind'] {
return value === 'claude-code' || value === 'codex' || value === 'pi' || value === 'media';
}
function parseDevices(value: unknown): UsageHistoryDevice[] | undefined {
if (!Array.isArray(value)) return undefined;
const devices: UsageHistoryDevice[] = [];
for (const raw of value as Array<Record<string, unknown> | null>) {
if (!raw || typeof raw.deviceId !== 'string' || typeof raw.name !== 'string') continue;
const status = raw.status as UsageHistoryDevice['status'];
devices.push({
deviceId: raw.deviceId,
name: raw.name,
platform: typeof raw.platform === 'string' ? raw.platform : null,
isSelf: raw.isSelf === true,
// 快照可能损坏:超出 Date 范围的时间格式化时会抛错,按未同步处理。
syncedAt:
typeof raw.syncedAt === 'number' &&
Number.isFinite(raw.syncedAt) &&
raw.syncedAt > 0 &&
raw.syncedAt <= 8.64e15
? raw.syncedAt
: null,
// 快照里的「读取中」没有意义: 下次打开会重新同步, 先按离线展示缓存时间。
status: DEVICE_STATUSES.has(status) && status !== 'syncing' ? status : 'offline',
});
}
return devices;
}
function readSnapshot(scopeKey: string): UsageHistoryPayload | null {
try {
localStorage.removeItem(
`${LEGACY_SNAPSHOT_STORAGE_KEY}.${encodeURIComponent(scopeKey)}`,
);
const raw = localStorage.getItem(storageKeyForScope(scopeKey));
if (!raw) return null;
const parsed = JSON.parse(raw) as StoredUsageHistoryPayload;
// 最小结构校验 — 大结构对不上才丢弃; 旧版快照缺 token 字段时补 0 继续用,
// 避免升级后首启空一帧 (首帧照常渲染, ~200ms 后真实数据静默覆盖)。
if (!Array.isArray(parsed.days) || !Array.isArray(parsed.models)) return null;
if (
!parsed.totals ||
typeof parsed.totals !== 'object' ||
Array.isArray(parsed.totals) ||
!parsed.streak ||
typeof parsed.streak !== 'object' ||
Array.isArray(parsed.streak) ||
!parsed.anomaly ||
typeof parsed.anomaly !== 'object' ||
Array.isArray(parsed.anomaly)
) {
return null;
}
const totals = parsed.totals as Record<string, unknown>;
const streak = parsed.streak as Record<string, unknown>;
const anomaly = parsed.anomaly as Record<string, unknown>;
const legacyActual = (value: unknown): RegionalMoney =>
typeof value === 'number' && Number.isFinite(value) && value >= 0
? legacyUsdMoney(value)
: zeroUsageMoney();
const legacyEstimate = (value: unknown): RegionalMoney =>
typeof value === 'number' && Number.isFinite(value) && value >= 0
? usdMoney(value, 'value-estimate', 'subscription-value')
: zeroUsageMoney('value-estimate');
const days = (parsed.days as StoredUsageHistoryDay[])
.filter((row) => typeof row?.day === 'string')
.map((row) => ({
day: row.day as string,
money: normalizeRegionalMoney(row.money) ?? legacyActual(row.costUsd),
tokens: finiteNumber(row.tokens),
}));
const modelDaily = (Array.isArray(parsed.modelDaily) ? parsed.modelDaily : [])
.filter(
(row: StoredUsageHistoryModelDay) =>
typeof row?.day === 'string' &&
typeof row.model === 'string' &&
isAgentKind(row.agentKind),
)
.map((row: StoredUsageHistoryModelDay): UsageHistoryModelDay => ({
day: row.day as string,
agentKind: row.agentKind as UsageHistoryModelDay['agentKind'],
model: row.model as string,
money:
normalizeRegionalMoney(row.money) ??
(row.agentKind === 'codex'
? legacyEstimate(row.amountUsd)
: legacyActual(row.amountUsd)),
apiMoney: normalizeRegionalMoney(row.apiMoney) ?? legacyActual(row.apiCostUsd),
subscriptionEstimateMoney:
normalizeRegionalMoney(row.subscriptionEstimateMoney) ??
legacyEstimate(row.subscriptionEstimateUsd),
tokens: finiteNumber(row.tokens),
...(typeof row.inputTokens === 'number' && Number.isFinite(row.inputTokens)
? { inputTokens: row.inputTokens }
: {}),
...(typeof row.outputTokens === 'number' && Number.isFinite(row.outputTokens)
? { outputTokens: row.outputTokens }
: {}),
...(typeof row.cacheReadTokens === 'number' && Number.isFinite(row.cacheReadTokens)
? { cacheReadTokens: row.cacheReadTokens }
: {}),
...(typeof row.cacheCreateTokens === 'number' && Number.isFinite(row.cacheCreateTokens)
? { cacheCreateTokens: row.cacheCreateTokens }
: {}),
}));
const models = (parsed.models as StoredUsageHistoryModel[])
.filter(
(row) =>
typeof row?.model === 'string' &&
isAgentKind(row.agentKind),
)
.map((row): UsageHistoryModel => ({
agentKind: row.agentKind as UsageHistoryModel['agentKind'],
model: row.model as string,
money: normalizeRegionalMoney(row.money) ?? legacyActual(row.costUsd),
estimatedMoney:
normalizeRegionalMoney(row.estimatedMoney) ??
(typeof row.estimatedCostUsd === 'number'
? legacyEstimate(row.estimatedCostUsd)
: null),
inputTokens: finiteNumber(row.inputTokens),
outputTokens: finiteNumber(row.outputTokens),
cacheReadTokens: finiteNumber(row.cacheReadTokens),
cacheCreateTokens: finiteNumber(row.cacheCreateTokens),
}));
const today = normalizeRegionalMoney(totals.today) ?? legacyActual(totals.today);
const last30Days =
normalizeRegionalMoney(totals.last30Days) ?? legacyActual(totals.last30Days);
const last30DaysEstimatedValue =
normalizeRegionalMoney(totals.last30DaysEstimatedValue) ??
legacyEstimate(totals.last30DaysEstimatedValue);
const last30DaysWithEstimatedValue =
normalizeRegionalMoney(totals.last30DaysWithEstimatedValue) ??
(last30DaysEstimatedValue.amount > 0
? (addCompatibleRegionalMoney(
[last30Days, last30DaysEstimatedValue],
) ?? last30Days)
: last30Days);
const trailing7DayAvg =
anomaly.trailing7DayAvg === null
? null
: normalizeRegionalMoney(anomaly.trailing7DayAvg) ??
legacyActual(anomaly.trailing7DayAvg);
const devices = parseDevices(parsed.devices);
return {
...(devices ? { devices } : {}),
generatedAt: finiteNumber(parsed.generatedAt, Date.now()),
todayKey: typeof parsed.todayKey === 'string' ? parsed.todayKey : '',
stale: parsed.stale === true,
estimatesPending: parsed.estimatesPending === true,
days,
modelDaily,
models,
streak: {
current: finiteNumber(streak.current),
longest: finiteNumber(streak.longest),
},
totals: {
today,
last30Days,
last30DaysWithEstimatedValue,
last30DaysEstimatedValue,
todayTokens: finiteNumber(totals.todayTokens),
last30DaysTokens: finiteNumber(totals.last30DaysTokens),
},
anomaly: {
isAnomalous: anomaly.isAnomalous === true,
trailing7DayAvg,
},
};
} catch {
return null;
}
}
function writeSnapshot(scopeKey: string, p: UsageHistoryPayload): void {
try {
localStorage.setItem(storageKeyForScope(scopeKey), JSON.stringify(p));
} catch {
/* 写不进就下次启动慢一帧, 不影响功能 */
}
}
/** 数据等价比较用的序列化 (generatedAt 每次都变, 排除)。 */
function serializeForCompare(p: UsageHistoryPayload): string {
return JSON.stringify({ ...p, generatedAt: 0 });
}
interface UsageHistoryScopeState {
cache: UsageHistoryPayload | null;
cacheSerialized: string | null;
inflight: Promise<UsageHistoryPayload | null> | null;
loadSeq: number;
pricingRetryDone: boolean;
staleRetryTimer: ReturnType<typeof setTimeout> | null;
pricingRetryTimer: ReturnType<typeof setTimeout> | null;
listeners: Set<(p: UsageHistoryPayload | null) => void>;
statusListeners: Set<(refreshing: boolean) => void>;
refreshing: boolean;
request: UsageHistoryRequest;
}
interface UsageHistoryRequest {
days: number | 'all';
modelDays: number | 'all';
allowPendingEstimates: boolean;
/** 'local' / 'all' / 其它电脑的 deviceId。 */
device: string;
/** 附带「最耗 token 的任务」数据。 */
includeTasks: boolean;
}
const scopes = new Map<string, UsageHistoryScopeState>();
function normalizeScopeKey(userId?: string | null): string {
return userId || DEFAULT_SCOPE_KEY;
}
function getScope(
scopeKey: string,
request: UsageHistoryRequest = {
days: HISTORY_WINDOW_DAYS,
modelDays: MODEL_WINDOW_DAYS,
allowPendingEstimates: false,
device: 'local',
includeTasks: false,
},
): UsageHistoryScopeState {
let state = scopes.get(scopeKey);
if (!state) {
const snapshot = readSnapshot(scopeKey);
state = {
cache: snapshot,
cacheSerialized: snapshot ? serializeForCompare(snapshot) : null,
inflight: null,
loadSeq: 0,
pricingRetryDone: false,
staleRetryTimer: null,
pricingRetryTimer: null,
listeners: new Set<(p: UsageHistoryPayload | null) => void>(),
statusListeners: new Set<(refreshing: boolean) => void>(),
refreshing: false,
request,
};
scopes.set(scopeKey, state);
}
return state;
}
function cancelScopeTimers(scope: UsageHistoryScopeState): void {
if (scope.staleRetryTimer) {
clearTimeout(scope.staleRetryTimer);
scope.staleRetryTimer = null;
}
if (scope.pricingRetryTimer) {
clearTimeout(scope.pricingRetryTimer);
scope.pricingRetryTimer = null;
}
}
function deactivateScopeIfUnused(scope: UsageHistoryScopeState): void {
if (scope.listeners.size > 0 || scope.statusListeners.size > 0) return;
cancelScopeTimers(scope);
scope.pricingRetryDone = false;
scope.inflight = null;
scope.loadSeq += 1;
setRefreshing(scope, false);
}
function setRefreshing(scope: UsageHistoryScopeState, next: boolean): void {
if (scope.refreshing === next) return;
scope.refreshing = next;
for (const fn of scope.statusListeners) fn(scope.refreshing);
}
async function load(scopeKey: string, opts?: { forceRefresh?: boolean; resetPricingRetry?: boolean }): Promise<UsageHistoryPayload | null> {
const scope = getScope(scopeKey);
if (scope.inflight && !opts?.forceRefresh) return scope.inflight;
if (opts?.resetPricingRetry) scope.pricingRetryDone = false;
const seq = ++scope.loadSeq;
setRefreshing(scope, true);
scope.inflight = window.electronAPI.maker.usage
.getHistory({
days: scope.request.days,
modelDays: scope.request.modelDays,
...(scope.request.device === 'local' ? {} : { device: scope.request.device }),
...(scope.request.includeTasks ? { includeTasks: true } : {}),
...(opts?.forceRefresh ? { forceRefresh: true } : {}),
})
.then((res) => {
if (seq === scope.loadSeq) scope.inflight = null;
if (!res || typeof res !== 'object') return null;
if (seq !== scope.loadSeq) return scope.cache;
const next = res as UsageHistoryPayload;
const nextForCache = { ...next, stale: false };
if (next.stale) {
const nextSerialized = serializeForCompare(nextForCache);
if (nextSerialized !== scope.cacheSerialized) {
scope.cache = nextForCache;
scope.cacheSerialized = nextSerialized;
writeSnapshot(scopeKey, scope.cache);
for (const fn of scope.listeners) fn(scope.cache);
}
if (!scope.staleRetryTimer) {
scope.staleRetryTimer = setTimeout(() => {
scope.staleRetryTimer = null;
if (scope.listeners.size === 0 && scope.statusListeners.size === 0) return;
void load(scopeKey);
}, STALE_RETRY_DELAY_MS);
}
return scope.cache;
}
if (next.estimatesPending) {
if (!scope.pricingRetryDone) {
scope.pricingRetryDone = true;
scope.pricingRetryTimer = setTimeout(() => {
scope.pricingRetryTimer = null;
if (scope.listeners.size === 0 && scope.statusListeners.size === 0) return;
void load(scopeKey, { forceRefresh: true });
}, PRICING_RETRY_DELAY_MS);
}
// Amount-bearing consumers wait for pricing so they never present a
// misleading value. Token-only consumers can render this payload now;
// the delayed force-refresh above still replaces it once estimates are
// available.
if (!scope.request.allowPendingEstimates) return scope.cache;
} else {
scope.pricingRetryDone = false;
}
// dirty-check: 数据未变 (仅 generatedAt 不同) → 不换 cache 引用、不写快照、
// 不通知监听 — 等价数据不触发重渲染与 JSON 落盘
const nextSerialized = serializeForCompare(nextForCache);
if (nextSerialized !== scope.cacheSerialized) {
scope.cache = nextForCache;
scope.cacheSerialized = nextSerialized;
writeSnapshot(scopeKey, scope.cache);
for (const fn of scope.listeners) fn(scope.cache);
}
return scope.cache;
})
.catch(() => {
if (seq === scope.loadSeq) scope.inflight = null;
return null;
})
.finally(() => {
if (seq === scope.loadSeq && !scope.staleRetryTimer) setRefreshing(scope, false);
});
return scope.inflight;
}
/** 影响「最耗 token 的任务」展示的任务字段。 */
const TASK_META_KEYS = ['title', 'status', 'model', 'providerId', 'source'] as const;
export type UsageHistoryWindow = number | 'all';
function normalizeWindow(value: UsageHistoryWindow | undefined, fallback: number): number | 'all' {
if (value === 'all') return 'all';
return Math.min(366, Math.max(1, Math.floor(value ?? fallback)));
}
function scopeKeyForRequest(scopeKey: string, request: UsageHistoryRequest): string {
if (
request.days === HISTORY_WINDOW_DAYS &&
request.modelDays === MODEL_WINDOW_DAYS &&
!request.allowPendingEstimates &&
request.device === 'local' &&
!request.includeTasks
) {
return scopeKey;
}
// 'local' 沿用旧 key, 升级后已有的本机快照照常 hydrate。
const deviceSuffix = request.device === 'local' ? '' : `|device=${encodeURIComponent(request.device)}`;
const taskSuffix = request.includeTasks ? '|tasks=1' : '';
return `${scopeKey}|days=${request.days}|modelDays=${request.modelDays}|allowPendingEstimates=${request.allowPendingEstimates ? 1 : 0}${deviceSuffix}${taskSuffix}`;
}
export function useUsageHistory(opts?: {
paused?: boolean;
userId?: string | null;
days?: UsageHistoryWindow;
modelDays?: UsageHistoryWindow;
/** Token-only consumers may render the payload while prices finish loading. */
allowPendingEstimates?: boolean;
/** 'local' (默认, 只看本机) / 'all' (所有设备合并) / 其它电脑的 deviceId。 */
device?: string;
/** 附带「最耗 token 的任务」数据;只有设置 → 用量历史需要(首页看板不读)。 */
includeTasks?: boolean;
}): {
history: UsageHistoryPayload | null;
refreshing: boolean;
} {
const paused = opts?.paused ?? false;
const scopeKey = normalizeScopeKey(opts?.userId);
const request: UsageHistoryRequest = {
days: normalizeWindow(opts?.days, HISTORY_WINDOW_DAYS),
modelDays: normalizeWindow(opts?.modelDays, MODEL_WINDOW_DAYS),
allowPendingEstimates: opts?.allowPendingEstimates ?? false,
device: opts?.device || 'local',
includeTasks: opts?.includeTasks ?? false,
};
const scopedKey = scopeKeyForRequest(scopeKey, request);
const scope = getScope(scopedKey, request);
const [historyState, setHistoryState] = useState<{ scopeKey: string; value: UsageHistoryPayload | null }>(() => ({
scopeKey: scopedKey,
value: scope.cache,
}));
// A null payload is pending until the first request settles. Keeping that
// invariant in the hook lets consumers distinguish initial loading from a
// settled load failure without adding a second lifecycle state owner.
const [isRefreshing, setIsRefreshing] = useState(scope.cache === null || scope.refreshing);
useEffect(() => {
const activeScope = getScope(scopedKey, request);
const setScopedHistory = (value: UsageHistoryPayload | null) => {
setHistoryState({ scopeKey: scopedKey, value });
};
activeScope.listeners.add(setScopedHistory);
activeScope.statusListeners.add(setIsRefreshing);
// 注册后立即用当前 cache 对齐一次: useState(cache) 是 render 时的快照, 若别处的
// load() 在 render 与本 effect 之间更新了 cache, 且后续 load 都命中 dirty-check
// (不再广播), 本实例会停在旧值。引用相同时 React 自动 bail out, 无重渲染成本。
setScopedHistory(activeScope.cache);
// mount 与 paused→false (展开瞬间) 都拉一次 — 折叠摘要 / 图表数据都保持新鲜。
// 收起时跳过后续 push 订阅, 避免每个 turn 触发后台重拉。
void load(scopedKey);
setIsRefreshing(activeScope.refreshing);
// paused (卡片收起): 不订阅消费推送, 收起用户的 per-turn 重拉成本归零
if (paused) {
return () => {
activeScope.listeners.delete(setScopedHistory);
activeScope.statusListeners.delete(setIsRefreshing);
deactivateScopeIfUnused(activeScope);
};
}
// 任一 agent 有新消费 → debounce 重拉 (turn 密集结束时合并成一次)
let timer: ReturnType<typeof setTimeout> | null = null;
const scheduleRefresh = () => {
if (timer) clearTimeout(timer);
timer = setTimeout(() => {
timer = null;
void load(scopedKey, { forceRefresh: true, resetPricingRetry: true });
}, REFRESH_DEBOUNCE_MS);
};
const offSpend = window.electronAPI.maker.usage.onTodaySpendChanged(scheduleRefresh);
const offTokens = window.electronAPI.maker.usage.onTodayTokensChanged(scheduleRefresh);
const offPricing = window.electronAPI.maker.usage.onModelPricingChanged(scheduleRefresh);
// 任务的标题 / 删除等元数据变化不产生用量:只需重读,Main 在出口按当前库覆盖本机任务
// 元数据,不强制重聚合。
let metaTimer: ReturnType<typeof setTimeout> | null = null;
const onTaskMetaPatch = (_sessionId: string, patch: Partial<Session>) => {
if (!TASK_META_KEYS.some((key) => key in patch)) return;
if (metaTimer) clearTimeout(metaTimer);
metaTimer = setTimeout(() => {
metaTimer = null;
void load(scopedKey);
}, REFRESH_DEBOUNCE_MS);
};
const offLocalPatch = onSessionPatch(onTaskMetaPatch);
const offPushPatch = window.electronAPI.localDb?.sessionsPush?.onPatched(
({ sessionId, patch }, stamp) => {
if (isDataOwnerPushCurrent(stamp)) onTaskMetaPatch(sessionId, patch);
},
);
const peerTimer =
request.device === 'local'
? null
: setInterval(() => void load(scopedKey), PEER_REFRESH_INTERVAL_MS);
return () => {
activeScope.listeners.delete(setScopedHistory);
activeScope.statusListeners.delete(setIsRefreshing);
deactivateScopeIfUnused(activeScope);
if (timer) clearTimeout(timer);
if (metaTimer) clearTimeout(metaTimer);
offLocalPatch();
offPushPatch?.();
offSpend();
offTokens();
offPricing();
if (peerTimer) clearInterval(peerTimer);
};
}, [paused, scopedKey]);
const history = historyState.scopeKey === scopedKey ? historyState.value : scope.cache;
const refreshing =
historyState.scopeKey === scopedKey ? isRefreshing : scope.cache === null || scope.refreshing;
return { history, refreshing };
}