cc-viewer 1.7.3 → 1.7.5

package/server/lib/proxy-stats.js

@@ -0,0 +1,436 @@
+// Proxy Stats — pure functions for proxy retry statistics.
+// Detail record schema, per-day sharding, aggregate computation (availability / percentiles / streak / by-model by-path).
+//
+// Design notes:
+//   - All pure functions, independently unit-testable; no I/O side effects (except appendRecord, which only writes files and reads no state).
+//   - Details are sharded per day as proxy_YYYY-MM-DD.jsonl, synonymous with llm-retry-proxy's retry_YYYY-MM-DD.jsonl.
+//   - Aggregation is done by stats-worker (Worker thread) calling aggregateRecords; the main thread only handles appendRecord.
+//   - Fully separated from cc-viewer's existing session logs (*.jsonl written by interceptor), no cross-contamination.
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { AsyncWriteQueue } from './async-write-queue.js';
+
+// ── Detail record schema ──────────────────────────────────────────────
+// Appends one JSON line after each proxied LLM API request completes. Fields align with llm-retry-proxy's retry records.
+//
+//   ts             ISO timestamp (millisecond precision, at request completion)
+//   method         HTTP method
+//   path           Request path (without host, includes query)
+//   model          Model name (parsed from request body.model; empty string if absent)
+//   upstream_status Last upstream response status code (0 on request error / network failure)
+//   final_status   Status code returned to the client (the real last upstream failure code when retries are exhausted, e.g. 429/503; no longer hardcodes 503)
+//   attempts       Total attempt count (including the first)
+//   retries        Retry count = attempts - 1
+//   duration_ms    Total duration (milliseconds)
+//   succeeded      Whether a <400 response was ultimately received
+//   retry_codes    List of upstream error codes returned during retries, e.g. [503, 503, 429]; [] when no retries
+//
+// Note: duration uses milliseconds (cc-viewer standardizes on ms throughout), unlike llm-retry-proxy which uses seconds.
+
+/**
+ * Build a standardized proxy detail record. Fills in defaults and derives retries/succeeded.
+ * @param {object} r Raw fields
+ * @returns {object} Standardized record
+ */
+export function buildRecord(r) {
+  const attempts = Math.max(1, Number(r.attempts) || 1);
+  const retries = Math.max(0, attempts - 1);
+  const finalStatus = Number(r.finalStatus) || 0;
+  const upstreamStatus = Number(r.upstreamStatus) || 0;
+  return {
+    ts: r.ts || new Date().toISOString(),
+    method: r.method || 'POST',
+    path: r.path || '/',
+    model: typeof r.model === 'string' ? r.model : '',
+    // Profile identifier (for byProfile aggregation): defaults to 'default', compatible with the built-in max profile
+    profile_id: typeof r.profileId === 'string' && r.profileId ? r.profileId : 'default',
+    profile_name: typeof r.profileName === 'string' && r.profileName ? r.profileName : 'Default',
+    upstream_status: upstreamStatus,
+    final_status: finalStatus,
+    attempts,
+    retries,
+    duration_ms: Math.max(0, Number(r.durationMs) || 0),
+    succeeded: typeof r.succeeded === 'boolean' ? r.succeeded : finalStatus > 0 && finalStatus < 400,
+    retry_codes: Array.isArray(r.retryCodes) ? r.retryCodes.filter(c => Number.isFinite(c)) : [],
+  };
+}
+
+/**
+ * Determine whether a record is "successful": final_status < 400 (2xx/3xx success, 4xx/5xx failure).
+ * Synonymous with llm-retry-proxy's _req_succeeded.
+ */
+export function isRecordSucceeded(r) {
+  return Number(r?.final_status) > 0 && Number(r?.final_status) < 400;
+}
+
+/**
+ * Per-day sharded detail file name: proxy_YYYY-MM-DD.jsonl
+ * @param {string} dateStr e.g. "2026-07-08"
+ */
+export function dailyFileName(dateStr) {
+  return `proxy_${dateStr}.jsonl`;
+}
+
+/**
+ * Absolute path of the per-day sharded detail file.
+ * @param {string} projectDir Project log directory (LOG_DIR/<project>)
+ * @param {string} dateStr e.g. "2026-07-08"
+ */
+export function dailyFilePath(projectDir, dateStr) {
+  return join(projectDir, dailyFileName(dateStr));
+}
+
+/**
+ * Today's date string (local timezone, consistent with stats-worker's file naming convention).
+ */
+export function todayStr(d = new Date()) {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+/**
+ * Parse the date string from a proxy_YYYY-MM-DD.jsonl file name. Returns null for non-proxy detail files.
+ */
+export function parseDailyFileName(fileName) {
+  const m = /^proxy_(\d{4}-\d{2}-\d{2})\.jsonl$/.exec(fileName);
+  return m ? m[1] : null;
+}
+
+/**
+ * Append a detail record to the per-day sharded file (line-ordered, non-blocking).
+ * Creates the directory automatically on first use (mkdirSync recursive, cached).
+ *
+ * Review P2 fix: this sat on the proxy hot path (before the first response
+ * byte) doing a synchronous mkdir + appendFileSync per request. Writes now go
+ * through the shared AsyncWriteQueue (single writer, ordered, falls back to
+ * sync on process exit so records are never lost) and the mkdir runs once per
+ * directory via a process-level cache.
+ * @param {string} filePath Absolute path of the detail file
+ * @param {object} record Standardized record produced by buildRecord
+ * @param {Function} [onDone] Called after the line hits the queue's writer (tests)
+ */
+const _statsWriteQueue = new AsyncWriteQueue(''); // paths are always explicit (appendTo)
+const _dirsEnsured = new Set();
+
+export function appendRecord(filePath, record, onDone) {
+  const dir = join(filePath, '..');
+  if (!_dirsEnsured.has(dir)) {
+    try {
+      mkdirSync(dir, { recursive: true });
+      _dirsEnsured.add(dir);
+    } catch { /* No permission — the queued append will surface the failure as a silent no-op */ }
+  }
+  _statsWriteQueue.appendTo(filePath, JSON.stringify(record) + '\n', onDone);
+}
+
+/** Await all queued detail writes (tests / graceful shutdown). */
+export function flushRecords() {
+  return _statsWriteQueue.flush();
+}
+
+// ── Stats-update notifier (dependency inversion, review P2) ────────────────
+// proxy.js used to dynamically import('./server.js') to reach the statsWorker
+// singleton — if a future proxy-only process did that first, server.js's
+// module-load side effects would boot a second viewer. The owner (server.js)
+// now registers its notify callback here at load time; proxy.js just emits.
+// No listener registered (server.js not loaded) → emit is a no-op.
+let _statsUpdateListener = null;
+
+export function setProxyStatsListener(fn) {
+  _statsUpdateListener = typeof fn === 'function' ? fn : null;
+}
+
+export function emitProxyStatsUpdate(fileName) {
+  if (!_statsUpdateListener) return;
+  try {
+    _statsUpdateListener(fileName);
+  } catch (err) {
+    if (process.env.CCV_DEBUG) {
+      console.error('[CC-Viewer Proxy] proxy stats notify failed:', err?.message);
+    }
+  }
+}
+
+// ── Aggregate computation ──────────────────────────────────────────────────────
+
+/**
+ * Compute a percentile. Input must be a numerically ascending-sorted array.
+ * Uses the same nearest-rank method as llm-retry-proxy (simple, no interpolation, sufficient for discrete distributions like durations).
+ * @param {number[]} sorted Sorted array
+ * @param {number} p 0~1, e.g. 0.95
+ * @returns {number} Percentile value; returns 0 for empty array
+ */
+export function percentile(sorted, p) {
+  if (!Array.isArray(sorted) || sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0];
+  const idx = Math.min(sorted.length - 1, Math.ceil(p * sorted.length) - 1);
+  return sorted[idx];
+}
+
+/**
+ * Compute the current consecutive success/failure streak and the longest failure streak.
+ * Synonymous with llm-retry-proxy's streak logic: iterate records in time order, accumulating same-type consecutive runs.
+ * @param {object[]} records Records sorted in ascending time order
+ * @returns {{ current: {type:'success'|'failure', count:number}, worstFailure: number }}
+ */
+export function computeStreak(records) {
+  if (!Array.isArray(records) || records.length === 0) {
+    return { current: { type: 'success', count: 0 }, worstFailure: 0 };
+  }
+  let worstFailure = 0;
+  let curType = null;
+  let curCount = 0;
+  for (const r of records) {
+    const ok = isRecordSucceeded(r);
+    const type = ok ? 'success' : 'failure';
+    if (type === curType) {
+      curCount++;
+    } else {
+      curType = type;
+      curCount = 1;
+    }
+    if (type === 'failure' && curCount > worstFailure) worstFailure = curCount;
+  }
+  return { current: { type: curType || 'success', count: curCount }, worstFailure };
+}
+
+/**
+ * Aggregate a batch of detail records into a stats structure. Called by stats-worker, also used directly by /api/proxy-stats.
+ *
+ * Definitions (consistent with llm-retry-proxy):
+ *   - Upstream availability = proportion of requests that succeeded on the first attempt (retries==0 && succeeded)
+ *   - Downstream availability = proportion that ultimately succeeded after retries (succeeded)
+ *   - Difference = number of requests rescued by retries
+ *
+ * @param {object[]} records Detail record array (order is irrelevant; sorted internally)
+ * @param {object} [opts]
+ * @param {number} [opts.recentLimit=50] Number of recent detail entries to keep
+ * @returns {object} Aggregate result (proxyStats structure)
+ */
+export function aggregateRecords(records, opts = {}) {
+  const recentLimit = Number(opts.recentLimit) || 50;
+  if (!Array.isArray(records) || records.length === 0) {
+    return emptyStats();
+  }
+
+  // Sort a copy in ascending time order (streak / recent depend on order)
+  const sorted = [...records].sort((a, b) => {
+    const ta = a.ts ? Date.parse(a.ts) : 0;
+    const tb = b.ts ? Date.parse(b.ts) : 0;
+    return ta - tb;
+  });
+
+  const total = sorted.length;
+  let totalRetries = 0;
+  let succeeded = 0;
+  let failed = 0;
+  let firstOk = 0; // Succeeded on the first attempt (retries==0 && succeeded)
+  const durations = [];
+  const retryDist = new Map(); // retries -> count
+  const retryCodeCounts = new Map(); // code -> count
+  const byModelMap = new Map();
+  const byPathMap = new Map();
+  const byProfileMap = new Map();
+  let slowest = null;
+  let fastest = null;
+
+  for (const r of sorted) {
+    const retries = Number(r.retries) || 0;
+    const ok = isRecordSucceeded(r);
+    const dur = Number(r.duration_ms) || 0;
+    totalRetries += retries;
+    if (ok) {
+      succeeded++;
+      if (retries === 0) firstOk++;
+    } else {
+      failed++;
+    }
+    durations.push(dur);
+    retryDist.set(retries, (retryDist.get(retries) || 0) + 1);
+    for (const c of (r.retry_codes || [])) {
+      retryCodeCounts.set(c, (retryCodeCounts.get(c) || 0) + 1);
+    }
+    // by model
+    const model = r.model || '(unknown)';
+    if (!byModelMap.has(model)) byModelMap.set(model, newBucket());
+    accBucket(byModelMap.get(model), retries, ok, dur);
+    // by path
+    const path = r.path || '/';
+    if (!byPathMap.has(path)) byPathMap.set(path, newBucket());
+    accBucket(byPathMap.get(path), retries, ok, dur);
+    // by profile
+    const profileKey = r.profile_id || 'default';
+    if (!byProfileMap.has(profileKey)) byProfileMap.set(profileKey, { ...newBucket(), profile_name: r.profile_name || 'Default' });
+    accBucket(byProfileMap.get(profileKey), retries, ok, dur);
+    // slowest / fastest (fastest only counts successes with dur>0)
+    const candidate = { ts: r.ts, path, model, attempts: r.attempts, retries, duration_ms: dur, final_status: r.final_status, retry_codes: r.retry_codes || [] };
+    if (!slowest || dur > slowest.duration_ms) slowest = candidate;
+    if (ok && dur > 0 && (!fastest || dur < fastest.duration_ms)) fastest = candidate;
+  }
+
+  durations.sort((a, b) => a - b);
+  const p50 = percentile(durations, 0.5);
+  const p95 = percentile(durations, 0.95);
+  const p99 = percentile(durations, 0.99);
+  const maxMs = durations.length ? durations[durations.length - 1] : 0;
+  const avgMs = durations.length ? durations.reduce((s, x) => s + x, 0) / durations.length : 0;
+
+  const upstreamAvail = total ? round2(firstOk / total * 100) : 0;
+  const downstreamAvail = total ? round2(succeeded / total * 100) : 0;
+  const streak = computeStreak(sorted);
+
+  return {
+    summary: {
+      totalRequests: total,
+      totalRetries,
+      totalSucceeded: succeeded,
+      totalFailed: failed,
+      totalFirstOk: firstOk,
+      upstreamAvailabilityPct: upstreamAvail,
+      downstreamAvailabilityPct: downstreamAvail,
+      p50Ms: round3(p50),
+      p95Ms: round3(p95),
+      p99Ms: round3(p99),
+      maxMs: round3(maxMs),
+      avgMs: round3(avgMs),
+      currentStreakType: streak.current.type,
+      currentStreakCount: streak.current.count,
+      worstFailureStreak: streak.worstFailure,
+    },
+    byModel: mapToSortedArray(byModelMap, 'model'),
+    byPath: mapToSortedArray(byPathMap, 'path').slice(0, 10), // Top 10 path
+    byProfile: mapToSortedArrayWithExtra(byProfileMap, 'profile_id', 'profile_name'),
+    retryDistribution: [...retryDist.entries()]
+      .sort((a, b) => a[0] - b[0])
+      .map(([retries, count]) => ({ retries, count })),
+    retryCodes: [...retryCodeCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .map(([code, count]) => ({ code, count })),
+    slowest,
+    fastest,
+    recentRecords: sorted.slice(-recentLimit).reverse(),
+  };
+}
+
+function newBucket() {
+  return { requests: 0, retries: 0, succeeded: 0, firstOk: 0, failed: 0, durations: [] };
+}
+
+function accBucket(b, retries, ok, dur) {
+  b.requests++;
+  b.retries += retries;
+  if (ok) {
+    b.succeeded++;
+    if (retries === 0) b.firstOk++;
+  } else {
+    b.failed++;
+  }
+  b.durations.push(dur);
+}
+
+function mapToSortedArray(map, keyName) {
+  const arr = [];
+  for (const [k, b] of map.entries()) {
+    b.durations.sort((a, c) => a - c);
+    const entry = {
+      [keyName]: k,
+      requests: b.requests,
+      retries: b.retries,
+      succeeded: b.succeeded,
+      firstOk: b.firstOk,
+      failed: b.failed,
+      availabilityPct: b.requests ? round2(b.succeeded / b.requests * 100) : 0,
+      upstreamAvailabilityPct: b.requests ? round2(b.firstOk / b.requests * 100) : 0,
+      p95Ms: round3(percentile(b.durations, 0.95)),
+    };
+    arr.push(entry);
+  }
+  arr.sort((a, b) => b.requests - a.requests);
+  return arr;
+}
+
+// byProfile-specific: the bucket carries an extra profile_name field, included in the output
+function mapToSortedArrayWithExtra(map, keyName, extraName) {
+  const arr = [];
+  for (const [k, b] of map.entries()) {
+    b.durations.sort((a, c) => a - c);
+    const entry = {
+      [keyName]: k,
+      [extraName]: b[extraName] || k,
+      requests: b.requests,
+      retries: b.retries,
+      succeeded: b.succeeded,
+      firstOk: b.firstOk,
+      failed: b.failed,
+      availabilityPct: b.requests ? round2(b.succeeded / b.requests * 100) : 0,
+      upstreamAvailabilityPct: b.requests ? round2(b.firstOk / b.requests * 100) : 0,
+      p95Ms: round3(percentile(b.durations, 0.95)),
+    };
+    arr.push(entry);
+  }
+  arr.sort((a, b) => b.requests - a.requests);
+  return arr;
+}
+
+function emptyStats() {
+  return {
+    summary: {
+      totalRequests: 0, totalRetries: 0, totalSucceeded: 0, totalFailed: 0, totalFirstOk: 0,
+      upstreamAvailabilityPct: 0, downstreamAvailabilityPct: 0,
+      p50Ms: 0, p95Ms: 0, p99Ms: 0, maxMs: 0, avgMs: 0,
+      currentStreakType: 'success', currentStreakCount: 0, worstFailureStreak: 0,
+    },
+    byModel: [],
+    byPath: [],
+    byProfile: [],
+    retryDistribution: [],
+    retryCodes: [],
+    slowest: null,
+    fastest: null,
+    recentRecords: [],
+  };
+}
+
+/**
+ * Incremental cache merge at the proxy_YYYY-MM-DD.jsonl file granularity (pure function, no I/O).
+ *
+ * Proxy detail files are sharded per day and append-only: if a file's size+mtime is unchanged, its content is unchanged,
+ * so the records parsed last time can be reused, skipping redundant readFileSync+JSON.parse. stats-worker calls this
+ * function on each notifyProxyStats trigger, avoiding a full re-scan of all historical shards.
+ *
+ * @param {object} params
+ * @param {object} [params.existingCache] Previous file cache: { [fileName]: { size, lastModified, records } }
+ * @param {Array<{name:string,size:number,lastModified:string,records?:object[]}>} params.files
+ *   All current proxy detail files (worker has already statSync'd; records are only re-parsed by the worker when the file changes;
+ *   unchanged files leave records empty for cache reuse)
+ * @returns {{records:object[], cache:object}} Merged full records + new cache (for writing the next stats JSON)
+ */
+export function mergeProxyFileCache({ existingCache, files }) {
+  const cache = {};
+  const allRecords = [];
+  const existing = existingCache && typeof existingCache === 'object' ? existingCache : {};
+  for (const f of files) {
+    if (!f || !f.name) continue;
+    const cached = existing[f.name];
+    const unchanged = cached
+      && cached.size === f.size
+      && cached.lastModified === f.lastModified
+      && Array.isArray(cached.records);
+    if (unchanged) {
+      // File unchanged: reuse cached records, skip re-parsing
+      cache[f.name] = { size: f.size, lastModified: f.lastModified, records: cached.records };
+      for (const r of cached.records) allRecords.push(r);
+    } else if (Array.isArray(f.records)) {
+      // File changed (or new): use the worker's re-parsed records, update cache
+      cache[f.name] = { size: f.size, lastModified: f.lastModified, records: f.records };
+      for (const r of f.records) allRecords.push(r);
+    }
+    // Neither cached nor has records (worker provided none and no cache) → skip (worker should ensure changed files carry records)
+  }
+  return { records: allRecords, cache };
+}
+
+function round2(n) { return Math.round(n * 100) / 100; }
+function round3(n) { return Math.round(n * 1000) / 1000; }

package/server/lib/stats-worker.js

@@ -5,7 +5,7 @@
 // waste, review P1). Legacy v1 *.jsonl files are no longer counted — their
 // numbers return once the user migrates (ccv convert / the migrate prompt).
 import { parentPort } from 'node:worker_threads';
-import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { readJsonlTolerant, listSessionIds } from './v2/replay.js';
 import { dirSizeSync } from './v2/layout.js';
@@ -15,6 +15,7 @@ import {
   INTER_SESSION_TYPES, isSystemText, extractUserTexts, isSuggestionMode,
   collectPromptsFromEvents, sortEpochFiles,
 } from './user-prompt-extract.js';
+import { aggregateRecords, mergeProxyFileCache, parseDailyFileName } from './proxy-stats.js';
 
 // Prompt/preview extraction moved to the shared server/lib/user-prompt-extract.js
 // (also feeds the V2Writer prompts.jsonl cache and the log-list read side).
@@ -29,7 +30,12 @@ export { INTER_SESSION_TYPES, isSystemText, extractUserTexts };
 //      invalidates pre-discard caches so their probe units can't be reused
 //      back into filesStats, which lets the discard check sit AFTER the
 //      cache-reuse branch (cache hits skip the journal head scan entirely)
-const STATS_VERSION = 11;
+// v12: proxyStats field (proxy retry detail aggregation from per-day
+//      proxy_YYYY-MM-DD.jsonl shards; the bump invalidates v10 caches written
+//      by the pre-rebase feat/proxy-stats branch and v11 caches that lack the
+//      proxy fields). The per-file records cache lives in worker memory only
+//      (_proxyCacheByDir) — never persisted into the stats JSON.
+const STATS_VERSION = 12;
 
 /**
  * Parse one v2 session directory into the same stats shape parseJsonlFile
@@ -168,7 +174,14 @@ function generateProjectStats(projectDir, projectName, onlyFile) {
   // Scan units = v2 session dirs. The cache key is the journal's size+mtime:
   // every request/completion appends journal lines, so any change moves it.
   const sessionIds = listSessionIds(projectDir).sort();
-  if (sessionIds.length === 0) return;
+  // Proxy retry shards (proxy_YYYY-MM-DD.jsonl) live at the project top level
+  // and can exist without any v2 session (proxy-only usage) — only bail out
+  // when BOTH are absent so aggregateProxyStats still runs for proxy-only dirs.
+  let proxyFiles = [];
+  try {
+    proxyFiles = readdirSync(projectDir).filter(f => f.startsWith('proxy_') && f.endsWith('.jsonl'));
+  } catch { /* unreadable project dir → nothing to aggregate from it either */ }
+  if (sessionIds.length === 0 && proxyFiles.length === 0) return;
 
   const filesStats = {};
   const topModels = {};
@@ -234,8 +247,9 @@ function generateProjectStats(projectDir, projectName, onlyFile) {
     }
   }
 
-  // No parsable session yet (dirs without journals) — keep whatever exists.
-  if (Object.keys(filesStats).length === 0) return;
+  // No parsable session yet (dirs without journals) — keep whatever exists,
+  // unless proxy shards are present (they alone justify a stats write).
+  if (Object.keys(filesStats).length === 0 && proxyFiles.length === 0) return;
 
   // 计算全局汇总
   let totalRequests = 0;
@@ -256,6 +270,12 @@ function generateProjectStats(projectDir, projectName, onlyFile) {
     totalCacheCreation += f.summary.cache_creation_input_tokens;
   }
 
+  // 代理重试明细聚合：扫描 proxy_YYYY-MM-DD.jsonl 文件，聚合成 proxyStats。
+  // 与 token 统计同文件同 worker，避免新建独立 worker。明细文件按天分片，聚合逻辑在
+  // proxy-stats.js:aggregateRecords（纯函数，可单测）。增量优化：仅对 size+mtime 变化的分片
+  // 重新解析，未变化分片复用 worker 内存缓存（mergeProxyFileCache + _proxyCacheByDir）。
+  const proxyStats = aggregateProxyStats(projectDir);
+
   const stats = {
     _v: STATS_VERSION,
     project: projectName,
@@ -272,6 +292,7 @@ function generateProjectStats(projectDir, projectName, onlyFile) {
       cache_read_input_tokens: totalCacheRead,
       cache_creation_input_tokens: totalCacheCreation,
     },
+    proxyStats,
   };
 
   try {
@@ -281,6 +302,99 @@ function generateProjectStats(projectDir, projectName, onlyFile) {
   }
 }
 
+/**
+ * 扫描项目目录下所有 proxy_YYYY-MM-DD.jsonl 明细文件，聚合成 proxyStats 结构。
+ * 增量优化：proxy 明细按天分片且仅追加——文件 size+mtime 未变即内容未变，复用上次解析的 records，
+ * 仅对变化/新增文件重新 readFileSync+解析（仿会话 JSONL 的 files[f] 缓存）。
+ *
+ * Review P1 fix: the per-file records cache is WORKER-MEMORY ONLY
+ * (_proxyCacheByDir). It was previously persisted as `proxyStatsFiles` inside
+ * `<project>.json`, which duplicated every raw record on disk (unbounded
+ * growth) and made every stats update rewrite — and every /api/proxy-stats
+ * read re-parse — the full history. A worker restart just re-parses the
+ * shards once; the JSON now carries only the aggregated `proxyStats`.
+ *
+ * @param {string} projectDir
+ * @returns {object} aggregated proxyStats
+ */
+const _proxyCacheByDir = new Map(); // projectDir → per-file cache {name:{records,size,lastModified}}
+
+function aggregateProxyStats(projectDir) {
+  let proxyFiles = [];
+  try {
+    proxyFiles = readdirSync(projectDir)
+      .filter(f => f.startsWith('proxy_') && f.endsWith('.jsonl'))
+      .sort();
+  } catch {
+    return aggregateRecords([]);
+  }
+  if (proxyFiles.length === 0) return aggregateRecords([]);
+
+  // Optional retention (review P2): per-day shards otherwise grow without
+  // bound and every one participates in aggregation forever. Opt-in via
+  // CCV_PROXY_STATS_RETAIN_DAYS=N — shards dated older than N days ago are
+  // deleted before aggregation (and drop out of the memory cache, which is
+  // rebuilt from the surviving file list). Deliberately OFF by default:
+  // silently deleting a user's detail history is a policy the user must
+  // choose, so without the env var nothing is ever removed.
+  const retainDays = parseInt(process.env.CCV_PROXY_STATS_RETAIN_DAYS, 10);
+  if (Number.isFinite(retainDays) && retainDays > 0) {
+    const cutoff = new Date(Date.now() - retainDays * 86400000);
+    const cutoffStr = `${cutoff.getFullYear()}-${String(cutoff.getMonth() + 1).padStart(2, '0')}-${String(cutoff.getDate()).padStart(2, '0')}`;
+    proxyFiles = proxyFiles.filter((f) => {
+      const date = parseDailyFileName(f); // strict proxy_YYYY-MM-DD.jsonl; unparsable names are never deleted
+      if (!date || date >= cutoffStr) return true;
+      try { unlinkSync(join(projectDir, f)); } catch { /* deletion failed — keep it in this scan, retry next time */ }
+      return false;
+    });
+    if (proxyFiles.length === 0) return aggregateRecords([]);
+  }
+
+  const cachedFiles = _proxyCacheByDir.get(projectDir) || {};
+
+  const files = [];
+  for (const f of proxyFiles) {
+    const filePath = join(projectDir, f);
+    let stat;
+    try {
+      stat = statSync(filePath);
+    } catch {
+      continue; // stat 失败跳过此文件
+    }
+    const size = stat.size;
+    const lastModified = stat.mtime.toISOString();
+    const cached = cachedFiles[f];
+    const unchanged = cached && cached.size === size && cached.lastModified === lastModified;
+    if (unchanged) {
+      // 命中缓存：不传 records，由 mergeProxyFileCache 复用 cached.records
+      files.push({ name: f, size, lastModified });
+    } else {
+      // 变化/新增：重新解析记录（仅变化文件）
+      const records = [];
+      try {
+        const content = readFileSync(filePath, 'utf-8');
+        for (const line of content.split('\n')) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            records.push(JSON.parse(trimmed));
+          } catch {
+            // 跳过无法解析的行
+          }
+        }
+      } catch {
+        // 文件读取失败：跳过（不进 cache，下次仍会重试）
+        continue;
+      }
+      files.push({ name: f, size, lastModified, records });
+    }
+  }
+
+  const { records: allRecords, cache } = mergeProxyFileCache({ existingCache: cachedFiles, files });
+  _proxyCacheByDir.set(projectDir, cache);
+  return aggregateRecords(allRecords);
+}
+
 /**
  * 扫描 logDir 下所有项目目录，逐个生成统计
  */