evolclaw 3.2.0 → 3.3.0

package/dist/core/stats/billing.js

@@ -0,0 +1,151 @@
+/**
+ * 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 文件。
+ * 包路径（$PACKAGE_ROOT/data/stats/）为基线，用户路径（$EVOLCLAW_HOME/data/stats/）为追加/覆盖。
+ * 两层合并（append），用户层行追加在包层之后——查价时 effective_from 越大越优先，天然正确。
+ */
+function _loadJsonlMerged(evolclawHome, filename) {
+    const results = [];
+    // 1. 包路径（基线）
+    const pkgFile = path.join(getPackageRoot(), 'data', 'stats', filename);
+    if (fs.existsSync(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(evolclawHome, 'data', 'stats', filename);
+    if (fs.existsSync(userFile)) {
+        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(evolclawHome) {
+    const now = Date.now();
+    if (_aliasCache && now - _aliasCacheTs < PRICE_CACHE_TTL)
+        return _aliasCache;
+    _aliasCache = _loadJsonlMerged(evolclawHome, 'model-aliases.jsonl');
+    _aliasCacheTs = now;
+    return _aliasCache;
+}
+/** 解析模型 ID → 定价表规范 ID。精确匹配 alias 表，找不到返回原 ID。 */
+export function resolveCanonicalModel(evolclawHome, model) {
+    const aliases = loadAliases(evolclawHome);
+    const entry = aliases.find(a => a.alias === model);
+    return entry ? entry.canonical : model;
+}
+function loadPrices(evolclawHome) {
+    const now = Date.now();
+    if (_priceCache && now - _priceCacheTs < PRICE_CACHE_TTL)
+        return _priceCache;
+    _priceCache = _loadJsonlMerged(evolclawHome, 'model-prices.jsonl');
+    _priceCacheTs = now;
+    return _priceCache;
+}
+/** 取 model 在 ts 时刻生效的价格行（effective_from <= ts 中最新的一条）。
+ *  精确匹配失败时，通过 model-aliases.jsonl 映射到规范 ID 再查一次。 */
+export function resolvePriceRow(evolclawHome, model, ts) {
+    const prices = loadPrices(evolclawHome);
+    let candidates = prices.filter(p => p.model === model && p.effective_from <= ts);
+    if (!candidates.length) {
+        // fallback: alias → canonical
+        const canonical = resolveCanonicalModel(evolclawHome, 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);
+}
+const BILLING_FNS = {
+    // 通用 per-token（Claude / OpenAI 兼容 / Kimi / MiniMax）
+    per_token_v1: (e, p) => {
+        const r = (p.price_input ?? 0) * e.input_tokens / 1e6
+            + (p.price_output ?? 0) * e.output_tokens / 1e6
+            + (p.price_cache_creation ?? 0) * e.cache_creation_tokens / 1e6
+            + (p.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(evolclawHome, event) {
+    const priceRow = resolvePriceRow(evolclawHome, 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(evolclawHome) {
+    const now = Date.now();
+    if (_specCache && now - _specCacheTs < PRICE_CACHE_TTL)
+        return _specCache;
+    _specCache = _loadJsonlMerged(evolclawHome, 'model-specs.jsonl');
+    _specCacheTs = now;
+    return _specCache;
+}
+/** 取模型在 ts 时刻的能力参数。找不到时返回默认值。 */
+export function resolveModelSpec(evolclawHome, model, ts) {
+    const specs = loadSpecs(evolclawHome);
+    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/core/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(evolclawHome) {
+    const file = path.join(evolclawHome, '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(evolclawHome, agentAid) {
+    const now = new Date();
+    const from_ts = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+    return _calcRangeUsd(evolclawHome, from_ts, agentAid);
+}
+/** 计算本月实际 USD 消耗。 */
+function _calcMonthUsd(evolclawHome, agentAid) {
+    const now = new Date();
+    const from_ts = new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+    return _calcRangeUsd(evolclawHome, from_ts, agentAid);
+}
+/** 计算指定时间范围的 USD 消耗（逐行算 cost）。 */
+function _calcRangeUsd(evolclawHome, from_ts, agentAid) {
+    const db = openReadonlyDb(getDbPath(evolclawHome));
+    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(evolclawHome, r);
+            total += cost.usd ?? 0;
+        }
+    }
+    finally {
+        db.close();
+    }
+    return total;
+}
+export function getBudgetStatus(evolclawHome, agentAid, peerKey) {
+    const budgets = loadBudgets(evolclawHome);
+    const cfg = _resolveCfg(budgets, agentAid, peerKey);
+    const dailyLimit = cfg.daily_usd ?? Infinity;
+    const dailyUsed = _calcTodayUsd(evolclawHome, 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(evolclawHome, 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/core/stats/db.js

@@ -0,0 +1,314 @@
+/**
+ * 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(evolclawHome) {
+    return path.join(evolclawHome, 'data', 'stats');
+}
+export function getDbPath(evolclawHome) {
+    return path.join(getStatsDir(evolclawHome), 'usage.db');
+}
+/** 获取写者单例（daemon 调用）。首次调用时建表。 */
+export function getDb(evolclawHome) {
+    if (_db)
+        return _db;
+    const sqlite = loadSqlite();
+    if (!sqlite)
+        return null;
+    const dir = getStatsDir(evolclawHome);
+    fs.mkdirSync(dir, { recursive: true });
+    const dbPath = getDbPath(evolclawHome);
+    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) {
+        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,
+      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
+    );
+    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,
+      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（evolclaw 会话）、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,
+      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);
+  `);
+    // 轻量迁移：旧库的 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}`);
+    }
+}
+/**
+ * 全量重建 usage_daily：从 usage_events 明细按天聚合重算。
+ * 用途：首次回填历史数据、每日自愈纠正写时漂移、手动 `ec stats --rebuild`。
+ * 单事务内 DELETE + INSERT...SELECT，失败回滚不破坏现有 rollup。
+ * 仅扫主库明细（往年明细已归档，但其 rollup 行已在归档前写入并永留主库）。
+ * @returns 重建后的行数，DB 不可用时返回 -1。
+ */
+export function rebuildDailyRollup(evolclawHome) {
+    const db = getDb(evolclawHome);
+    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)
+      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(*)
+      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(evolclawHome) {
+    const db = getDb(evolclawHome);
+    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(evolclawHome);
+    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(evolclawHome) {
+    const dir = getStatsDir(evolclawHome);
+    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);
+}

package/dist/core/stats/eck-vars.js

@@ -0,0 +1,84 @@
+/**
+ * eck-vars.ts — 组装 $STATS_* ECK 注入变量。
+ *
+ * 分层原则（保护 prompt cache）：
+ *   - system prompt 层：今日累计、预算状态（变化慢，稳定可缓存）
+ *   - 消息提示词层：会话级动态数据（每轮变，不注入 system）
+ */
+import { openReadonlyDb, getDbPath } from './db.js';
+import { calcCost } from './billing.js';
+import { getBudgetStatus } from './budget.js';
+function _todayRange() {
+    const now = new Date();
+    return { from_ts: Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()) };
+}
+function _calcTodayCosts(evolclawHome, agentAid, peerKey) {
+    const db = openReadonlyDb(getDbPath(evolclawHome));
+    if (!db)
+        return { usd: 0, cny: 0, input: 0, output: 0, cacheRead: 0, calls: 0 };
+    const { from_ts } = _todayRange();
+    const conds = ['ts >= ?'];
+    const params = [from_ts];
+    if (agentAid) {
+        conds.push('agent_aid = ?');
+        params.push(agentAid);
+    }
+    if (peerKey) {
+        conds.push('peer_key = ?');
+        params.push(peerKey);
+    }
+    let usd = 0, cny = 0, input = 0, output = 0, cacheRead = 0, calls = 0;
+    try {
+        const rows = db.prepare(`SELECT * FROM usage_events WHERE ${conds.join(' AND ')}`).all(...params);
+        for (const r of rows) {
+            const cost = calcCost(evolclawHome, r);
+            usd += cost.usd ?? 0;
+            cny += cost.cny ?? 0;
+            input += r.input_tokens ?? 0;
+            output += r.output_tokens ?? 0;
+            cacheRead += r.cache_read_tokens ?? 0;
+            calls++;
+        }
+    }
+    finally {
+        db.close();
+    }
+    return { usd, cny, input, output, cacheRead, calls };
+}
+/** 注入 system prompt 的变量（变化慢，可缓存）。 */
+export function buildSystemVars(evolclawHome, agentAid, peerKey) {
+    const agent = _calcTodayCosts(evolclawHome, agentAid);
+    const peer = peerKey ? _calcTodayCosts(evolclawHome, agentAid, peerKey) : { usd: 0, cny: 0 };
+    const totalIn = agent.input + agent.cacheRead;
+    const hitRate = totalIn > 0 ? ((agent.cacheRead / totalIn) * 100).toFixed(1) + '%' : '0%';
+    const budget = getBudgetStatus(evolclawHome, agentAid, peerKey);
+    return {
+        STATS_TODAY_INPUT_TOKENS: String(agent.input),
+        STATS_TODAY_OUTPUT_TOKENS: String(agent.output),
+        STATS_TODAY_CACHE_READ_TOKENS: String(agent.cacheRead),
+        STATS_TODAY_CACHE_HIT_RATE: hitRate,
+        STATS_TODAY_COST_USD: agent.usd.toFixed(4),
+        STATS_TODAY_COST_CNY: agent.cny.toFixed(4),
+        STATS_TODAY_CALL_COUNT: String(agent.calls),
+        STATS_PEER_TODAY_COST_USD: peer.usd?.toFixed(4) ?? '0',
+        STATS_PEER_TODAY_COST_CNY: peer.cny?.toFixed(4) ?? '0',
+        STATS_BUDGET_DAILY_LIMIT_USD: budget.daily_limit_usd >= 0 ? budget.daily_limit_usd.toFixed(2) : 'unlimited',
+        STATS_BUDGET_DAILY_USED_USD: budget.daily_used_usd.toFixed(4),
+        STATS_BUDGET_DAILY_REMAINING_USD: budget.daily_remaining_usd >= 0 ? budget.daily_remaining_usd.toFixed(2) : 'unlimited',
+        STATS_BUDGET_PCT_USED: budget.pct_used.toFixed(1),
+        STATS_BUDGET_WARN: String(budget.soft_warn),
+    };
+}
+/** 注入消息提示词的变量（每轮变，不进 system prompt）。 */
+export function buildTurnVars(opts) {
+    return {
+        SESSION_TURN_COUNT: String(opts.sessionTurnCount),
+        SESSION_LLM_CALL_COUNT: String(opts.sessionLlmCallCount),
+        STATS_CTX_TOTAL_TOKENS: String(opts.ctxTotalTokens ?? 0),
+        STATS_CTX_PCT: opts.ctxPct != null ? opts.ctxPct.toFixed(1) : '0',
+        STATS_CTX_SYSTEM_TOKENS: String(opts.ctxSystemTokens ?? 0),
+        STATS_CTX_MESSAGES_TOKENS: String(opts.ctxMessagesTokens ?? 0),
+        STATS_CTX_TOOLS_TOKENS: String(opts.ctxToolsTokens ?? 0),
+        STATS_BUDGET_AUTO_WARN: String(opts.autoBudgetWarn),
+    };
+}

package/dist/core/stats/index.js

@@ -0,0 +1,10 @@
+/**
+ * src/core/stats/index.ts — Stats 模块公开 API。
+ */
+export { getDb, openReadonlyDb, getStatsDir, getDbPath, archiveOldData, listArchivePaths, rebuildDailyRollup } from './db.js';
+export { normalizeUsage } from './normalizer.js';
+export { insertUsageEvent, insertContextBreakdown, insertMessageEvent, insertModelCalls } from './writer.js';
+export { calcCost, resolvePriceRow, resolveCanonicalModel, registerBillingFn } from './billing.js';
+export { queryAggregated, queryTodaySummary, querySessionTurns, queryContextBreakdown, queryTopPeers, queryTopModels, queryMessageAggregated, queryMessageTodaySummary, queryPeerList, querySummary, queryPeerDaily, queryTaskModelCalls, querySessionModelCalls } from './query.js';
+export { getBudgetStatus } from './budget.js';
+export { buildSystemVars, buildTurnVars } from './eck-vars.js';