evolcore 0.0.1 → 0.0.3

package/dist/stats/billing.js

@@ -0,0 +1,163 @@
+/**
+ * billing.ts — 读 model-prices.jsonl，按 billing_fn 调对应算法函数计算费用。
+ * 费用查询时实时计算，不存入 DB（价格可能变动）。
+ */
+import fs from 'fs';
+import path from 'path';
+import { getPackageRoot } from '../paths.js';
+// 价格表缓存（进程内，5 分钟 TTL）
+let _priceCache = null;
+let _priceCacheTs = 0;
+const PRICE_CACHE_TTL = 5 * 60 * 1000;
+/**
+ * 从包路径 + 用户路径合并读取 JSONL 文件。
+ * 包基线随构建产物发布在 dist/utils，源码运行时回退到 src/utils；
+ * 用户路径（$EVOLCORE_HOME/data/stats/）为追加/覆盖。
+ * 两层合并（append），用户层行追加在包层之后——查价时 effective_from 越大越优先，天然正确。
+ */
+function _loadJsonlMerged(evolcoreHome, filename) {
+    const results = [];
+    // 1. 包路径（基线）
+    const packageRoot = getPackageRoot();
+    const pkgFile = [
+        path.join(packageRoot, 'dist', 'utils', filename),
+        path.join(packageRoot, 'src', 'utils', filename),
+        path.join(packageRoot, 'data', 'stats', filename),
+    ].find(candidate => fs.existsSync(candidate));
+    if (pkgFile) {
+        try {
+            const lines = fs.readFileSync(pkgFile, 'utf-8').split('\n').filter(Boolean);
+            for (const l of lines)
+                results.push(JSON.parse(l));
+        }
+        catch { /* skip */ }
+    }
+    // 2. 用户路径（追加/覆盖）
+    const userFile = path.join(evolcoreHome, 'data', 'stats', filename);
+    if (fs.existsSync(userFile) && (!pkgFile || path.resolve(userFile) !== path.resolve(pkgFile))) {
+        try {
+            const lines = fs.readFileSync(userFile, 'utf-8').split('\n').filter(Boolean);
+            for (const l of lines)
+                results.push(JSON.parse(l));
+        }
+        catch { /* skip */ }
+    }
+    return results;
+}
+let _aliasCache = null;
+let _aliasCacheTs = 0;
+function loadAliases(evolcoreHome) {
+    const now = Date.now();
+    if (_aliasCache && now - _aliasCacheTs < PRICE_CACHE_TTL)
+        return _aliasCache;
+    _aliasCache = _loadJsonlMerged(evolcoreHome, 'model-aliases.jsonl');
+    _aliasCacheTs = now;
+    return _aliasCache;
+}
+/** 解析模型 ID → 定价表规范 ID。精确匹配 alias 表，找不到返回原 ID。 */
+export function resolveCanonicalModel(evolcoreHome, model) {
+    const aliases = loadAliases(evolcoreHome);
+    const entry = aliases.find(a => a.alias === model);
+    return entry ? entry.canonical : model;
+}
+function loadPrices(evolcoreHome) {
+    const now = Date.now();
+    if (_priceCache && now - _priceCacheTs < PRICE_CACHE_TTL)
+        return _priceCache;
+    _priceCache = _loadJsonlMerged(evolcoreHome, 'model-prices.jsonl');
+    _priceCacheTs = now;
+    return _priceCache;
+}
+/** 取 model 在 ts 时刻生效的价格行（effective_from <= ts 中最新的一条）。
+ *  精确匹配失败时，通过 model-aliases.jsonl 映射到规范 ID 再查一次。 */
+export function resolvePriceRow(evolcoreHome, model, ts) {
+    const prices = loadPrices(evolcoreHome);
+    let candidates = prices.filter(p => p.model === model && p.effective_from <= ts);
+    if (!candidates.length) {
+        // fallback: alias → canonical
+        const canonical = resolveCanonicalModel(evolcoreHome, model);
+        if (canonical !== model) {
+            candidates = prices.filter(p => p.model === canonical && p.effective_from <= ts);
+        }
+    }
+    if (!candidates.length)
+        return null;
+    return candidates.reduce((a, b) => a.effective_from >= b.effective_from ? a : b);
+}
+export const BILLING_FNS = {
+    // 通用 per-token（Claude / OpenAI 兼容 / Kimi / MiniMax）
+    per_token_v1: (e, p) => {
+        const tiers = Array.isArray(p.tiers)
+            ? p.tiers
+            : [];
+        const promptTokens = e.input_tokens + e.cache_creation_tokens + e.cache_read_tokens;
+        const tier = tiers.find(t => t.up_to_input_tokens == null || promptTokens <= t.up_to_input_tokens);
+        const price = tier ?? p;
+        const r = (price.price_input ?? 0) * e.input_tokens / 1e6
+            + (price.price_output ?? 0) * e.output_tokens / 1e6
+            + (price.price_cache_creation ?? 0) * e.cache_creation_tokens / 1e6
+            + (price.price_cache_read ?? 0) * e.cache_read_tokens / 1e6;
+        return p.currency === 'CNY' ? { cny: r } : { usd: r };
+    },
+    // DeepSeek cache_hit / cache_miss 口径
+    per_token_deepseek_v1: (e, p) => {
+        const r = (p.price_cache_hit ?? 0) * (e.cache_hit_tokens ?? 0) / 1e6
+            + (p.price_cache_miss ?? 0) * (e.cache_miss_tokens ?? 0) / 1e6
+            + (p.price_output ?? 0) * e.output_tokens / 1e6;
+        return { cny: r };
+    },
+    // Gemini 分档（按 total_context_tokens 确定所在档位）
+    per_token_tiered_v1: (e, p) => {
+        const tiers = p.tiers;
+        if (!Array.isArray(tiers))
+            return {};
+        const ctx = e.total_context_tokens ?? e.input_tokens;
+        const tier = tiers.find(t => t.up_to_tokens == null || ctx <= t.up_to_tokens) ?? tiers[tiers.length - 1];
+        const r = (tier.price_input ?? 0) * e.input_tokens / 1e6
+            + (tier.price_output ?? 0) * e.output_tokens / 1e6
+            + (tier.price_cache_read ?? 0) * e.cache_read_tokens / 1e6;
+        return p.currency === 'CNY' ? { cny: r } : { usd: r };
+    },
+    // 视觉模型（含 image_tokens 单独计费）
+    per_token_image_v1: (e, p) => {
+        const r = (p.price_input ?? 0) * e.input_tokens / 1e6
+            + (p.price_output ?? 0) * e.output_tokens / 1e6
+            + (p.price_image ?? 0) * (e.image_tokens ?? 0) / 1e6;
+        return p.currency === 'CNY' ? { cny: r } : { usd: r };
+    },
+};
+/** 注册新计费函数（扩展点）。 */
+export function registerBillingFn(id, fn) {
+    BILLING_FNS[id] = fn;
+}
+/** 计算一条 usage_event 的费用。找不到价格行时返回 {}。 */
+export function calcCost(evolcoreHome, event) {
+    const priceRow = resolvePriceRow(evolcoreHome, event.model, event.ts);
+    if (!priceRow)
+        return {};
+    const fn = BILLING_FNS[event.billing_fn] ?? BILLING_FNS[priceRow.billing_fn];
+    if (!fn)
+        return {};
+    return fn(event, priceRow);
+}
+let _specCache = null;
+let _specCacheTs = 0;
+function loadSpecs(evolcoreHome) {
+    const now = Date.now();
+    if (_specCache && now - _specCacheTs < PRICE_CACHE_TTL)
+        return _specCache;
+    _specCache = _loadJsonlMerged(evolcoreHome, 'model-specs.jsonl');
+    _specCacheTs = now;
+    return _specCache;
+}
+/** 取模型在 ts 时刻的能力参数。找不到时返回默认值。 */
+export function resolveModelSpec(evolcoreHome, model, ts) {
+    const specs = loadSpecs(evolcoreHome);
+    const t = ts ?? Date.now();
+    const candidates = specs.filter(s => s.model === model && s.effective_from <= t);
+    if (candidates.length) {
+        return candidates.reduce((a, b) => a.effective_from >= b.effective_from ? a : b);
+    }
+    // 默认值
+    return { model, effective_from: 0, context_window: 200000, max_input_tokens: 180000, max_output_tokens: 8192 };
+}

package/dist/stats/budget.js

@@ -0,0 +1,93 @@
+/**
+ * budget.ts — 三档预算控制（硬上限 / 软上限 / 自主上限）。
+ */
+import fs from 'fs';
+import path from 'path';
+import { calcCost } from './billing.js';
+import { openReadonlyDb, getDbPath } from './db.js';
+function loadBudgets(evolcoreHome) {
+    const file = path.join(evolcoreHome, 'data', 'stats', 'budgets.json');
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function _resolveCfg(budgets, agentAid, peerKey) {
+    const g = budgets.global ?? {};
+    const a = agentAid ? (budgets.agents?.[agentAid] ?? {}) : {};
+    const p = peerKey ? (budgets.peers?.[peerKey] ?? {}) : {};
+    // 取最严格的限额
+    const daily_usd = Math.min(g.daily_usd ?? Infinity, a.daily_usd ?? Infinity, p.daily_usd ?? Infinity);
+    return {
+        daily_usd: isFinite(daily_usd) ? daily_usd : undefined,
+        monthly_usd: g.monthly_usd,
+        hard_limit_pct: g.hard_limit_pct ?? 100,
+        soft_limit_pct: g.soft_limit_pct ?? 80,
+        auto_limit_pct: g.auto_limit_pct ?? 60,
+        on_hard_limit: g.on_hard_limit ?? 'block',
+        downgrade_model: g.downgrade_model,
+    };
+}
+/** 计算今日实际 USD 消耗（逐行算 cost，以避免聚合误差）。 */
+function _calcTodayUsd(evolcoreHome, agentAid) {
+    const now = new Date();
+    const from_ts = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+    return _calcRangeUsd(evolcoreHome, from_ts, agentAid);
+}
+/** 计算本月实际 USD 消耗。 */
+function _calcMonthUsd(evolcoreHome, agentAid) {
+    const now = new Date();
+    const from_ts = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+    return _calcRangeUsd(evolcoreHome, from_ts, agentAid);
+}
+/** 计算指定时间范围的 USD 消耗（逐行算 cost）。 */
+function _calcRangeUsd(evolcoreHome, from_ts, agentAid) {
+    const db = openReadonlyDb(getDbPath(evolcoreHome));
+    if (!db)
+        return 0;
+    let total = 0;
+    try {
+        const clause = agentAid ? 'WHERE ts >= ? AND agent_aid = ?' : 'WHERE ts >= ?';
+        const params = agentAid ? [from_ts, agentAid] : [from_ts];
+        const rows = db.prepare(`SELECT * FROM usage_events ${clause}`).all(...params);
+        for (const r of rows) {
+            const cost = calcCost(evolcoreHome, r);
+            total += cost.usd ?? 0;
+        }
+    }
+    finally {
+        db.close();
+    }
+    return total;
+}
+export function getBudgetStatus(evolcoreHome, agentAid, peerKey) {
+    const budgets = loadBudgets(evolcoreHome);
+    const cfg = _resolveCfg(budgets, agentAid, peerKey);
+    const dailyLimit = cfg.daily_usd ?? Infinity;
+    const dailyUsed = _calcTodayUsd(evolcoreHome, agentAid);
+    const dailyRemaining = Math.max(0, dailyLimit - dailyUsed);
+    const dailyPct = isFinite(dailyLimit) && dailyLimit > 0 ? (dailyUsed / dailyLimit) * 100 : 0;
+    const monthlyLimit = cfg.monthly_usd ?? Infinity;
+    const monthlyUsed = isFinite(monthlyLimit) ? _calcMonthUsd(evolcoreHome, agentAid) : 0;
+    const monthlyRemaining = Math.max(0, monthlyLimit - monthlyUsed);
+    const monthlyPct = isFinite(monthlyLimit) && monthlyLimit > 0 ? (monthlyUsed / monthlyLimit) * 100 : 0;
+    // 取 daily/monthly 中更高的百分比作为整体判断依据
+    const pct = Math.max(dailyPct, monthlyPct);
+    return {
+        daily_limit_usd: isFinite(dailyLimit) ? dailyLimit : -1,
+        daily_used_usd: dailyUsed,
+        daily_remaining_usd: isFinite(dailyLimit) ? dailyRemaining : -1,
+        monthly_limit_usd: isFinite(monthlyLimit) ? monthlyLimit : -1,
+        monthly_used_usd: monthlyUsed,
+        monthly_remaining_usd: isFinite(monthlyLimit) ? monthlyRemaining : -1,
+        pct_used: pct,
+        hard_blocked: pct >= (cfg.hard_limit_pct ?? 100),
+        soft_warn: pct >= (cfg.soft_limit_pct ?? 80),
+        auto_warn: pct >= (cfg.auto_limit_pct ?? 60),
+        downgrade_model: cfg.downgrade_model,
+    };
+}

package/dist/stats/db.js

@@ -0,0 +1,403 @@
+/**
+ * Stats DB — SQLite 初始化、WAL、建表、索引、归档。
+ * 技术选型：node:sqlite (Node 22.5+)，与主包 config-store.ts 保持一致。
+ */
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { logger } from '../utils/logger.js';
+const requireFromHere = createRequire(import.meta.url);
+let sqliteModule; // undefined=未尝试, null=不可用
+function loadSqlite() {
+    if (sqliteModule !== undefined)
+        return sqliteModule;
+    try {
+        sqliteModule = requireFromHere('node:sqlite');
+    }
+    catch {
+        logger.warn(`[StatsDB] node:sqlite unavailable (Node < 22.5?). Stats disabled.`);
+        sqliteModule = null;
+    }
+    return sqliteModule;
+}
+// 单例：写者（daemon）持有一个 read-write 实例
+let _db = null;
+export function getStatsDir(evolcoreHome) {
+    return path.join(evolcoreHome, 'data', 'stats');
+}
+export function getDbPath(evolcoreHome) {
+    return path.join(getStatsDir(evolcoreHome), 'usage.db');
+}
+export function closeStatsDb() {
+    if (!_db)
+        return;
+    try {
+        _db.close();
+    }
+    catch { }
+    _db = null;
+}
+export function resetStatsDb(evolcoreHome) {
+    closeStatsDb();
+    return getDb(evolcoreHome);
+}
+/** 获取写者单例（daemon 调用）。首次调用时建表。 */
+export function getDb(evolcoreHome) {
+    if (_db)
+        return _db;
+    const sqlite = loadSqlite();
+    if (!sqlite)
+        return null;
+    const dir = getStatsDir(evolcoreHome);
+    fs.mkdirSync(dir, { recursive: true });
+    const dbPath = getDbPath(evolcoreHome);
+    try {
+        _db = new sqlite.DatabaseSync(dbPath);
+        _db.exec('PRAGMA journal_mode=WAL');
+        _db.exec('PRAGMA synchronous=NORMAL');
+        _initTables(_db);
+        logger.info(`[StatsDB] Opened: ${dbPath}`);
+        return _db;
+    }
+    catch (e) {
+        try {
+            _db?.close();
+        }
+        catch { }
+        _db = null;
+        logger.error(`[StatsDB] Failed to open DB: ${e}`);
+        return null;
+    }
+}
+/** 只读连接（CLI / ecweb 调用）。每次返回新连接，调用方负责 close()。 */
+export function openReadonlyDb(dbPath) {
+    const sqlite = loadSqlite();
+    if (!sqlite)
+        return null;
+    if (!fs.existsSync(dbPath))
+        return null;
+    try {
+        return new sqlite.DatabaseSync(dbPath, { readOnly: true });
+    }
+    catch (e) {
+        logger.warn(`[StatsDB] Failed to open readonly DB ${dbPath}: ${e}`);
+        return null;
+    }
+}
+function _initTables(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS usage_events (
+      id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts                    INTEGER NOT NULL,
+      agent_aid             TEXT    NOT NULL,
+      peer_key              TEXT    NOT NULL,
+      usage_subject_key     TEXT    NOT NULL DEFAULT '',
+      role                  TEXT    NOT NULL DEFAULT '',
+      peer_type             TEXT,
+      session_id            TEXT,
+      model                 TEXT    NOT NULL,
+      billing_fn            TEXT    NOT NULL,
+      input_tokens          INTEGER NOT NULL DEFAULT 0,
+      output_tokens         INTEGER NOT NULL DEFAULT 0,
+      cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+      cache_hit_tokens      INTEGER,
+      cache_miss_tokens     INTEGER,
+      image_tokens          INTEGER,
+      total_context_tokens  INTEGER,
+      turns                 INTEGER NOT NULL DEFAULT 1,
+      duration_ms           INTEGER,
+      context_window_pct    REAL,
+      cost_official_usd     REAL,
+      cost_official_cny     REAL,
+      cost_gateway_usd      REAL,
+      cost_gateway_cny      REAL
+    );
+    CREATE INDEX IF NOT EXISTS idx_ue_ts         ON usage_events(ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_agent_ts   ON usage_events(agent_aid, ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_peer_ts    ON usage_events(agent_aid, peer_key, ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_model_ts   ON usage_events(model, ts);
+    CREATE INDEX IF NOT EXISTS idx_ue_session_ts ON usage_events(session_id, ts);
+
+    CREATE TABLE IF NOT EXISTS context_breakdown (
+      id              INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts              INTEGER NOT NULL,
+      agent_aid       TEXT    NOT NULL,
+      session_id      TEXT    NOT NULL,
+      turn_count      INTEGER NOT NULL,
+      model           TEXT    NOT NULL,
+      max_tokens      INTEGER NOT NULL,
+      system_prompt   INTEGER,
+      system_tools    INTEGER,
+      mcp_tools       INTEGER,
+      custom_agents   INTEGER,
+      memory_files    INTEGER,
+      skills          INTEGER,
+      messages        INTEGER,
+      free_space      INTEGER,
+      total_estimated INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_cb_session ON context_breakdown(session_id, ts);
+    CREATE INDEX IF NOT EXISTS idx_cb_agent   ON context_breakdown(agent_aid, ts);
+
+    CREATE TABLE IF NOT EXISTS message_events (
+      id          INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts          INTEGER NOT NULL,
+      agent_aid   TEXT    NOT NULL,
+      peer_key    TEXT    NOT NULL,
+      direction   TEXT    NOT NULL,
+      msg_type    TEXT,
+      bytes       INTEGER NOT NULL DEFAULT 0,
+      encrypted   INTEGER DEFAULT 0,
+      chatmode    TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_me_ts       ON message_events(ts);
+    CREATE INDEX IF NOT EXISTS idx_me_agent_ts ON message_events(agent_aid, ts);
+    CREATE INDEX IF NOT EXISTS idx_me_peer_ts  ON message_events(agent_aid, peer_key, ts);
+
+    -- 按天预聚合表：grain = 天 × agent × peer × session × model × billing_fn。
+    -- 由 writer.ts 写时增量 UPSERT 维护，rebuildDailyRollup() 全量重建纠偏。
+    -- 保留 model+billing_fn 维度以便查询时仍按 calcCost 现算成本。
+    -- 日级行很小，永留主库、不参与年度归档。
+    CREATE TABLE IF NOT EXISTS usage_daily (
+      day          TEXT NOT NULL,           -- 'YYYY-MM-DD' localtime
+      agent_aid    TEXT NOT NULL,
+      peer_key     TEXT NOT NULL,
+      peer_type    TEXT NOT NULL DEFAULT '',-- 'private' | 'group'，由 peer_key 唯一决定
+      session_id   TEXT NOT NULL DEFAULT '',
+      model        TEXT NOT NULL,
+      billing_fn   TEXT NOT NULL,
+      input_tokens          INTEGER NOT NULL DEFAULT 0,
+      output_tokens         INTEGER NOT NULL DEFAULT 0,
+      cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+      cache_hit_tokens      INTEGER NOT NULL DEFAULT 0,
+      cache_miss_tokens     INTEGER NOT NULL DEFAULT 0,
+      image_tokens          INTEGER NOT NULL DEFAULT 0,
+      total_context_tokens  INTEGER NOT NULL DEFAULT 0,
+      turns        INTEGER NOT NULL DEFAULT 0,
+      calls        INTEGER NOT NULL DEFAULT 0,
+      cost_official_usd     REAL,
+      cost_official_cny     REAL,
+      cost_gateway_usd      REAL,
+      cost_gateway_cny      REAL,
+      PRIMARY KEY (day, agent_aid, peer_key, session_id, model, billing_fn)
+    );
+    CREATE INDEX IF NOT EXISTS idx_ud_day     ON usage_daily(day);
+    CREATE INDEX IF NOT EXISTS idx_ud_session ON usage_daily(session_id);
+
+    -- 大模型调用明细：每次大模型调用一行（尽力而为；非 Claude 拿不到逐次时降级为单行累计）。
+    -- 关联三个 ID：task_id（一次 runQuery）、session_id（evolcore 会话）、agent_session_id（SDK 会话）。
+    CREATE TABLE IF NOT EXISTS model_calls (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts            INTEGER NOT NULL,
+      task_id       TEXT    NOT NULL,
+      session_id    TEXT,
+      agent_session_id TEXT,
+      agent_aid     TEXT    NOT NULL,
+      peer_key      TEXT    NOT NULL,
+      call_index    INTEGER NOT NULL,
+      model         TEXT    NOT NULL,
+      request_id    TEXT,
+      message_id    TEXT,
+      input_tokens          INTEGER NOT NULL DEFAULT 0,
+      output_tokens         INTEGER NOT NULL DEFAULT 0,
+      cache_creation_tokens INTEGER NOT NULL DEFAULT 0,
+      cache_read_tokens     INTEGER NOT NULL DEFAULT 0,
+      context_tokens        INTEGER,
+      max_tokens            INTEGER,
+      auto_compact_tokens   INTEGER,
+      degraded      INTEGER NOT NULL DEFAULT 0
+    );
+    CREATE INDEX IF NOT EXISTS idx_mc_task        ON model_calls(task_id);
+    CREATE INDEX IF NOT EXISTS idx_mc_session     ON model_calls(session_id, ts);
+    CREATE INDEX IF NOT EXISTS idx_mc_agentsession ON model_calls(agent_session_id);
+    CREATE INDEX IF NOT EXISTS idx_mc_ts          ON model_calls(ts);
+  `);
+    // ── Schema Migration: 添加 cost 列 ───────────────────────────────────────
+    try {
+        const cols = db.prepare(`PRAGMA table_info(usage_events)`).all();
+        const hasCostCols = cols.some((c) => c.name === 'cost_official_usd');
+        if (!hasCostCols) {
+            logger.info('[StatsDB] Migrating schema: adding cost columns to usage_events and usage_daily...');
+            db.exec(`
+        ALTER TABLE usage_events ADD COLUMN cost_official_usd REAL;
+        ALTER TABLE usage_events ADD COLUMN cost_official_cny REAL;
+        ALTER TABLE usage_events ADD COLUMN cost_gateway_usd REAL;
+        ALTER TABLE usage_events ADD COLUMN cost_gateway_cny REAL;
+      `);
+            db.exec(`
+        ALTER TABLE usage_daily ADD COLUMN cost_official_usd REAL;
+        ALTER TABLE usage_daily ADD COLUMN cost_official_cny REAL;
+        ALTER TABLE usage_daily ADD COLUMN cost_gateway_usd REAL;
+        ALTER TABLE usage_daily ADD COLUMN cost_gateway_cny REAL;
+      `);
+            logger.info('[StatsDB] Migration complete. Run "ec stats --rebuild" to backfill historical costs.');
+        }
+    }
+    catch (e) {
+        logger.warn(`[StatsDB] Cost column migration failed (non-fatal): ${e}`);
+    }
+    try {
+        let cols = db.prepare(`PRAGMA table_info(usage_events)`).all();
+        if (!cols.some(c => c.name === 'usage_subject_key')) {
+            db.exec(`ALTER TABLE usage_events ADD COLUMN usage_subject_key TEXT NOT NULL DEFAULT ''`);
+            cols = db.prepare(`PRAGMA table_info(usage_events)`).all();
+        }
+        if (!cols.some(c => c.name === 'role')) {
+            db.exec(`ALTER TABLE usage_events ADD COLUMN role TEXT NOT NULL DEFAULT ''`);
+        }
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_ue_role_budget ON usage_events(agent_aid, role, usage_subject_key, ts)`);
+    }
+    catch (e) {
+        logger.warn(`[StatsDB] usage_events role budget migration failed: ${e}`);
+    }
+    // 轻量迁移：旧库的 usage_daily 可能缺 peer_type 列（无 migration 机制，CREATE IF NOT EXISTS
+    // 不会补列）。检测后 ALTER 补上；补列后旧行 peer_type 为空，需跑一次 rebuildDailyRollup 回填。
+    try {
+        const cols = db.prepare(`PRAGMA table_info(usage_daily)`).all();
+        if (!cols.some(c => c.name === 'peer_type')) {
+            db.exec(`ALTER TABLE usage_daily ADD COLUMN peer_type TEXT NOT NULL DEFAULT ''`);
+        }
+    }
+    catch (e) {
+        logger.warn(`[StatsDB] usage_daily peer_type 迁移检测失败: ${e}`);
+    }
+    // 轻量迁移：model_calls 早期只记录 usage 原始 token，task.start 自动压缩需要
+    // 使用上轮真实 context/max/compact window，避免按模型名猜窗口。
+    try {
+        const cols = db.prepare(`PRAGMA table_info(model_calls)`).all();
+        if (!cols.some(c => c.name === 'context_tokens')) {
+            db.exec(`ALTER TABLE model_calls ADD COLUMN context_tokens INTEGER`);
+        }
+        if (!cols.some(c => c.name === 'max_tokens')) {
+            db.exec(`ALTER TABLE model_calls ADD COLUMN max_tokens INTEGER`);
+        }
+        if (!cols.some(c => c.name === 'auto_compact_tokens')) {
+            db.exec(`ALTER TABLE model_calls ADD COLUMN auto_compact_tokens INTEGER`);
+        }
+    }
+    catch (e) {
+        logger.warn(`[StatsDB] model_calls context window 迁移检测失败: ${e}`);
+    }
+}
+/**
+ * 全量重建 usage_daily：从 usage_events 明细按天聚合重算。
+ * 用途：首次回填历史数据、每日自愈纠正写时漂移、手动 `ec stats --rebuild`。
+ * 单事务内 DELETE + INSERT...SELECT，失败回滚不破坏现有 rollup。
+ * 仅扫主库明细（往年明细已归档，但其 rollup 行已在归档前写入并永留主库）。
+ * @returns 重建后的行数，DB 不可用时返回 -1。
+ */
+export function rebuildDailyRollup(evolcoreHome) {
+    const db = getDb(evolcoreHome);
+    if (!db)
+        return -1;
+    try {
+        db.exec('BEGIN');
+        db.exec('DELETE FROM usage_daily');
+        db.exec(`
+      INSERT INTO usage_daily
+        (day, agent_aid, peer_key, peer_type, session_id, model, billing_fn,
+         input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens,
+         cache_hit_tokens, cache_miss_tokens, image_tokens, total_context_tokens,
+         turns, calls,
+         cost_official_usd, cost_official_cny, cost_gateway_usd, cost_gateway_cny)
+      SELECT
+        strftime('%Y-%m-%d', ts/1000, 'unixepoch', 'localtime') AS day,
+        agent_aid, peer_key, MAX(COALESCE(peer_type, '')),
+        COALESCE(session_id, ''), model, billing_fn,
+        SUM(input_tokens), SUM(output_tokens),
+        SUM(cache_creation_tokens), SUM(cache_read_tokens),
+        SUM(COALESCE(cache_hit_tokens, 0)), SUM(COALESCE(cache_miss_tokens, 0)),
+        SUM(COALESCE(image_tokens, 0)), SUM(COALESCE(total_context_tokens, 0)),
+        SUM(turns), COUNT(*),
+        SUM(COALESCE(cost_official_usd, 0)), SUM(COALESCE(cost_official_cny, 0)),
+        SUM(COALESCE(cost_gateway_usd, 0)), SUM(COALESCE(cost_gateway_cny, 0))
+      FROM usage_events
+      GROUP BY day, agent_aid, peer_key, COALESCE(session_id, ''), model, billing_fn
+    `);
+        db.exec('COMMIT');
+        const row = db.prepare('SELECT COUNT(*) AS n FROM usage_daily').get();
+        logger.info(`[StatsDB] Rebuilt usage_daily: ${row.n} rows`);
+        return row.n;
+    }
+    catch (e) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { }
+        logger.error(`[StatsDB] rebuildDailyRollup failed: ${e}`);
+        return -1;
+    }
+}
+// ── 归档 ────────────────────────────────────────────────────────────────────
+/**
+ * 归档超过一整个自然年的数据到 usage-{year}.db，然后从主库删除。
+ * 例：当前 2026-05 → 归档所有 ts < 2025-01-01 00:00:00 的数据（即 2024 年及更早）。
+ * 安全：归档失败不删除主库数据。
+ */
+export function archiveOldData(evolcoreHome) {
+    const db = getDb(evolcoreHome);
+    if (!db)
+        return;
+    const now = new Date();
+    // 归档截止：当前年份第一天 00:00:00
+    const cutoffYear = now.getFullYear(); // e.g. 2026
+    const cutoffTs = Date.UTC(cutoffYear, 0, 1); // 2026-01-01 00:00:00 UTC
+    // 找出主库中所有早于 cutoff 的年份
+    const years = db.prepare(`SELECT DISTINCT CAST(strftime('%Y', ts/1000, 'unixepoch') AS INTEGER) AS y
+     FROM usage_events WHERE ts < ? ORDER BY y`).all(cutoffTs).map((r) => r.y);
+    if (years.length === 0)
+        return;
+    const statsDir = getStatsDir(evolcoreHome);
+    const sqlite = loadSqlite();
+    if (!sqlite)
+        return;
+    for (const year of years) {
+        const archivePath = path.join(statsDir, `usage-${year}.db`);
+        const yearStart = Date.UTC(year, 0, 1);
+        const yearEnd = Date.UTC(year + 1, 0, 1);
+        try {
+            // 打开/创建归档库，建同结构表
+            const archDb = new sqlite.DatabaseSync(archivePath);
+            archDb.exec('PRAGMA journal_mode=WAL');
+            _initTables(archDb);
+            archDb.close();
+            // ATTACH 方式批量迁移（同进程内最简洁）
+            db.exec(`ATTACH DATABASE '${archivePath.replace(/'/g, "''")}' AS arch`);
+            db.exec('BEGIN');
+            db.exec(`INSERT OR IGNORE INTO arch.usage_events SELECT * FROM main.usage_events WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec(`INSERT OR IGNORE INTO arch.context_breakdown SELECT * FROM main.context_breakdown WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec(`DELETE FROM main.usage_events WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec(`DELETE FROM main.context_breakdown WHERE ts >= ${yearStart} AND ts < ${yearEnd}`);
+            db.exec('COMMIT');
+            db.exec('DETACH DATABASE arch');
+            logger.info(`[StatsDB] Archived year ${year} → ${archivePath}`);
+        }
+        catch (e) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { }
+            try {
+                db.exec('DETACH DATABASE arch');
+            }
+            catch { }
+            logger.error(`[StatsDB] Archive failed for year ${year}: ${e}`);
+        }
+    }
+    // VACUUM 回收空间（WAL 模式下安全）
+    try {
+        db.exec('VACUUM');
+    }
+    catch { }
+}
+/** 列出所有可用的归档库路径（按年份排序）。 */
+export function listArchivePaths(evolcoreHome) {
+    const dir = getStatsDir(evolcoreHome);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .map(f => { const m = f.match(/^usage-(\d{4})\.db$/); return m ? { year: +m[1], path: path.join(dir, f) } : null; })
+        .filter(Boolean);
+}