dsh-layered-memory 0.8.5 → 0.8.7

package/dist/store/recall-dedupe.js

@@ -0,0 +1,138 @@
+/**
+ * 召回去重存储：sessionId → 已注入 L1 记录 id 集合的持久化映射。
+ *
+ * 语义（2026-08-24 设计共识）：
+ * - 同会话内已注入过的记忆不再重复注入（模型上下文已持有，重复注入浪费 token）；
+ * - 压制粒度 = 记录 id——去重合并更新会换新 id，新内容天然解除压制重新注入；
+ * - compact/clear 事件重置（上下文被压缩/清空，注入内容已丢失）；resume 不重置；
+ * - 热路径（召回 pre-step）同步内存读取，mark/reset 写穿持久化（session-modes 同款：
+ *   串行化原子写 + 失败降级内存态），任何 I/O 失败绝不抛进召回路径。
+ */
+import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
+import { atomicWriteJson, ensureDir, readJsonIfExists } from './io.js';
+/** 会话条目上限（按 updatedAt 淘汰最旧；防文件无限增长）。 */
+export const RECALL_DEDUPE_SESSION_CAP = 200;
+/** 单会话记录 id 上限（按插入序淘汰最旧；Set 迭代序即插入序）。 */
+export const RECALL_DEDUPE_IDS_CAP = 512;
+/** 条目过期清理（90 天未更新即丢弃，与 session-modes 同款量级）。 */
+const PRUNE_MS = 90 * 24 * 3600_000;
+export class RecallDedupeStore {
+    logger;
+    file;
+    entries = new Map();
+    persistFailed = false;
+    /** 串行化持久化写（避免并发原子写撞临时文件名）；init 链最前（先载入再落盘，防丢更新）。 */
+    writeChain;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'recall-dedupe.json');
+        this.writeChain = this.init();
+    }
+    /** 载入持久化映射（合并进内存——构造与载入之间发生的 mark 不丢）；失败降级内存态。 */
+    async init() {
+        const data = await readJsonIfExists(this.file);
+        if (!data?.sessions || typeof data.sessions !== 'object')
+            return;
+        const now = Date.now();
+        let count = 0;
+        for (const [sid, entry] of Object.entries(data.sessions)) {
+            if (!Array.isArray(entry?.recordIds))
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            const existing = this.entries.get(sid);
+            if (existing) {
+                // 合并：构造后、载入完成前已发生的 mark（保留较大 updatedAt）
+                for (const id of entry.recordIds)
+                    existing.ids.add(id);
+                existing.updatedAt = Math.max(existing.updatedAt, entry.updatedAt ?? 0);
+            }
+            else {
+                this.entries.set(sid, { ids: new Set(entry.recordIds), updatedAt: entry.updatedAt ?? now });
+            }
+            count++;
+        }
+        if (count > 0)
+            this.logger?.info(`[memory] 召回去重记录载入 ${count} 个会话`);
+    }
+    /** 该会话的已注入集合（热路径同步读；未出现过的会话返回空集合，惰性建条）。 */
+    seen(sessionId) {
+        let entry = this.entries.get(sessionId);
+        if (!entry) {
+            entry = { ids: new Set(), updatedAt: 0 };
+            this.entries.set(sessionId, entry);
+        }
+        return entry.ids;
+    }
+    /** 标记本轮实际注入的记录 id（写穿；调用方保证只传模型真实看到的条目）。 */
+    mark(sessionId, recordIds) {
+        if (recordIds.length === 0)
+            return;
+        const ids = this.seen(sessionId);
+        for (const id of recordIds)
+            ids.add(id);
+        // 插入序淘汰最旧（Set 迭代序 = 插入序）
+        while (ids.size > RECALL_DEDUPE_IDS_CAP) {
+            const oldest = ids.values().next().value;
+            if (oldest === undefined)
+                break;
+            ids.delete(oldest);
+        }
+        const entry = this.entries.get(sessionId);
+        entry.updatedAt = Date.now();
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 清空该会话的记录（compact/clear 后上下文已丢失，记忆需可重新注入）。 */
+    reset(sessionId) {
+        if (!this.entries.has(sessionId))
+            return;
+        this.entries.delete(sessionId);
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 等待在途持久化写完成（测试/停机用）。 */
+    flush() {
+        return this.writeChain;
+    }
+    async persist() {
+        try {
+            await ensureDir(path.dirname(this.file));
+            await atomicWriteJson(this.file, this.serialize());
+            this.persistFailed = false;
+        }
+        catch (err) {
+            if (!this.persistFailed) {
+                this.persistFailed = true;
+                this.logger?.warn(`[memory] 召回去重持久化失败（降级内存态）: ${errDetail(err)}`);
+            }
+        }
+    }
+    serialize() {
+        const now = Date.now();
+        // 超期清理 + 条数上限（按 updatedAt 淘汰最旧）
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS && e.updatedAt > 0)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > RECALL_DEDUPE_SESSION_CAP) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [sid, e] of this.entries) {
+                if (e.updatedAt > 0 && e.updatedAt < oldestAt) {
+                    oldest = sid;
+                    oldestAt = e.updatedAt;
+                }
+            }
+            if (oldest === undefined)
+                break; // 只剩惰性空条目（updatedAt=0），不占文件体积可留待过期清理
+            this.entries.delete(oldest);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries) {
+            if (e.ids.size === 0)
+                continue; // 空集合不落盘
+            sessions[sid] = { recordIds: [...e.ids], updatedAt: e.updatedAt };
+        }
+        return { version: 1, sessions };
+    }
+}

package/dist/store/runtime-installer.d.ts

@@ -60,8 +60,6 @@ export declare class RuntimeInstaller {
      * runNpm 起跑前复查即不再起新进程（否则回退的 npm 会跑到自然结束且无法再取消）。
      */
     cancel(): boolean;
-    /** 从 runtime 目录解析已安装的 transformers 模块（LocalEmbeddingService 用）。 */
-    resolveModule(): unknown;
     private pushLine;
     /** 跑一次 npm 子进程（采集尾行 + 超时 kill），返回退出码（null = 被杀死/启动失败）。 */
     private runNpm;

package/dist/store/runtime-installer.js

@@ -14,7 +14,6 @@
  * - 幂等：已装版本 == 目标版本直接就绪；版本漂移（插件升级换了钉死版本）重装覆盖。
  */
 import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -139,11 +138,6 @@ export class RuntimeInstaller {
         this.child?.kill();
         return true;
     }
-    /** 从 runtime 目录解析已安装的 transformers 模块（LocalEmbeddingService 用）。 */
-    resolveModule() {
-        const req = createRequire(path.join(this.runtimeDir, 'package.json'));
-        return req(RuntimeInstaller.packageName);
-    }
     pushLine(line) {
         const lines = this.progress.lastLines;
         lines.push(line.length > 300 ? line.slice(0, 300) + '…' : line);

package/dist/store/search-utils.d.ts

@@ -1,5 +1,22 @@
 /** 标准 RRF 常数（原论文值）；k 越大越偏向低排名项（分布更平滑）。 */
 export declare const RRF_K = 60;
+/** 衰减地板（#29 时效加权的安全边界）：老记忆最多损失一半排序分，永不沉底。
+ *  内部常量不进配置——它是安全机制不是调参旋钮。 */
+export declare const DECAY_FLOOR = 0.5;
+/**
+ * 时效衰减加权（#29，读路径专用）：score × max(FLOOR, 0.5^(Δ天/半衰期)) 后重排序。
+ *
+ * - Δ 按 updated_at（内容版本时间）起算，缺失/非法按最老 → 地板接管（零特判分支）；
+ * - 乘法保相关性主导：只在相关度相近的候选之间轮转名次（名额新鲜度），不淘汰不
+ *   硬过滤——score≈0 的新记忆乘什么都是 ≈0；hit 的原 score 字段不被改写（排序用
+ *   加权分，展示仍反映检索相关度）；
+ * - halfLifeDays ≤ 0 直接原样返回（开关关闭）；
+ * - 仅用于召回/工具检索；searchCandidates（去重候选）不得应用——写路径找同语义
+ *   旧记录要无视新旧，衰减会让去重漏检（同事实双记录）。
+ */
+export declare function applyDecayWeight<T extends {
+    score: number;
+}>(hits: T[], halfLifeDays: number, updatedAtOf: (hit: T) => number | undefined, now?: number): T[];
 /**
  * RRF 融合多个已排序列表：每项得分 = 各列表 1/(k + rank + 1) 之和。
  * 出现在多个列表的项得分累加，按得分降序返回（附 rrfScore）。

package/dist/store/search-utils.js

@@ -10,6 +10,35 @@
 import { tokenize } from '../util/text.js';
 /** 标准 RRF 常数（原论文值）；k 越大越偏向低排名项（分布更平滑）。 */
 export const RRF_K = 60;
+/** 衰减地板（#29 时效加权的安全边界）：老记忆最多损失一半排序分，永不沉底。
+ *  内部常量不进配置——它是安全机制不是调参旋钮。 */
+export const DECAY_FLOOR = 0.5;
+/**
+ * 时效衰减加权（#29，读路径专用）：score × max(FLOOR, 0.5^(Δ天/半衰期)) 后重排序。
+ *
+ * - Δ 按 updated_at（内容版本时间）起算，缺失/非法按最老 → 地板接管（零特判分支）；
+ * - 乘法保相关性主导：只在相关度相近的候选之间轮转名次（名额新鲜度），不淘汰不
+ *   硬过滤——score≈0 的新记忆乘什么都是 ≈0；hit 的原 score 字段不被改写（排序用
+ *   加权分，展示仍反映检索相关度）；
+ * - halfLifeDays ≤ 0 直接原样返回（开关关闭）；
+ * - 仅用于召回/工具检索；searchCandidates（去重候选）不得应用——写路径找同语义
+ *   旧记录要无视新旧，衰减会让去重漏检（同事实双记录）。
+ */
+export function applyDecayWeight(hits, halfLifeDays, updatedAtOf, now = Date.now()) {
+    if (!(halfLifeDays > 0) || hits.length === 0)
+        return hits;
+    const weight = (h) => {
+        const t = updatedAtOf(h);
+        if (t == null || !Number.isFinite(t))
+            return DECAY_FLOOR;
+        const days = Math.max(0, (now - t) / 86_400_000);
+        return Math.max(DECAY_FLOOR, 0.5 ** (days / halfLifeDays));
+    };
+    return hits
+        .map((h) => ({ h, weighted: h.score * weight(h) }))
+        .sort((a, b) => b.weighted - a.weighted)
+        .map((x) => x.h);
+}
 /**
  * RRF 融合多个已排序列表：每项得分 = 各列表 1/(k + rank + 1) 之和。
  * 出现在多个列表的项得分累加，按得分降序返回（附 rrfScore）。

package/dist/store/sqlite.d.ts

@@ -9,6 +9,45 @@ export interface StoreCapabilities {
     ftsSearch: boolean;
     vectorSearch: boolean;
 }
+/** token_cost 单窗口成本聚合（成本看板用）。 */
+export interface CostAggregate {
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    /** 单次调用输出 token 均值（无数据为 0）。 */
+    avgOutputTokens: number;
+    /** 单次调用输出 token 中位数（无数据为 0）。 */
+    medianOutputTokens: number;
+}
+/** 按 model 分组的成本行（成本看板用）。 */
+export interface CostByModel {
+    provider: string;
+    model: string;
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+}
+/** 按层级（l1/l2/l3 归并）分组的成本行。 */
+export interface CostByLayer {
+    layer: string;
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    avgOutputTokens: number;
+    medianOutputTokens: number;
+}
+/** 按时间桶 + provider/model 聚合的扁平行（趋势图与日均/周均/月均 + 中位数统计共用）。 */
+export interface BucketRow {
+    bucket: number;
+    provider: string;
+    model: string;
+    calls: number;
+    outputTokens: number;
+    reasoningTokens: number;
+}
 /** L1 检索命中（含 BM25/余弦归一分数）。 */
 export interface L1SearchHit {
     id: string;
@@ -44,6 +83,9 @@ export declare class MemoryDb {
     private stmtL1FtsDelete;
     private stmtL1FtsSearch;
     private stmtL1FtsSearchFamily;
+    /** token_cost 明细写入 / 滚动清理语句（构造期 prepare 缓存）。 */
+    private stmtInsertCost;
+    private stmtDeleteCost;
     private stmtUpsertL0;
     private stmtGetL0;
     /** 主表存在性点查（同 L1：防御性 FTS 删除的前置判断）。 */
@@ -145,6 +187,32 @@ export declare class MemoryDb {
     searchL1Vector(embedding: Float32Array, topK: number, family?: string): L1SearchHit[];
     /** 批量 upsert L0 消息（元数据 + FTS；embeddings 与 records 等长，可省略）。 */
     upsertL0Batch(records: L0MessageRecord[], embeddings?: Array<Float32Array | undefined>): boolean;
+    /**
+     * 记录一次蒸馏调用成本（明细表，写入时按 retentionDays 滚动清理；0 = 永久保留）。
+     * 失败/成功都记（token 照烧）；记账失败记 warn 但不阻断蒸馏（成本看板是增强能力）。
+     */
+    insertCostCall(provider: string, model: string, layer: string, inputChars: number, outputTokens: number, reasoningTokens: number, retentionDays: number): void;
+    /**
+     * 查询 token_cost 单窗口聚合（成本看板用；since 为毫秒起点，0 = 全量）。
+     * 输入口径：inputChars 是字符（llm 流拿不到输入 token，沿用 llm-usage 的字符折算口径）。
+     * 成本看板是增强能力：降级态/查询异常一律返回零值，不向上抛错。
+     * median 需取 output_tokens 序列在 JS 侧算（SQLite 无内置 median 函数）。
+     */
+    aggregateCost(since: number): {
+        total: CostAggregate;
+        byModel: CostByModel[];
+    };
+    /**
+     * 按层级归并聚合（l1 = l1-extract + l1-dedup；成本看板层级表格用）。
+     * 降级/异常返回空数组，不抛错。
+     */
+    aggregateCostByLayer(since: number): CostByLayer[];
+    /**
+     * 按时间桶（bucketMs 毫秒）+ model 聚合，返回扁平行。
+     * offsetMs 把桶边界对齐本地时区；layer 为空=全部，'l1' 归并 extract/dedup，其余精确匹配。
+     * 趋势图与「日均/周均/月均 + 中位数」统计共用：JS 侧按不同 bucketMs 调三次再聚合。
+     */
+    aggregateByBucket(bucketMs: number, offsetMs: number, since: number, layer: string): BucketRow[];
     countL0(): number;
     /** 统计 recorded_at >= iso 的消息数（状态面板"今日捕获"用）。 */
     countL0Since(iso: string): number;

package/dist/store/sqlite.js

@@ -35,6 +35,17 @@ function chunkIds(ids) {
         out.push(ids.slice(i, i + IN_CHUNK));
     return out;
 }
+function emptyCostAggregate() {
+    return { calls: 0, inputChars: 0, outputTokens: 0, reasoningTokens: 0, avgOutputTokens: 0, medianOutputTokens: 0 };
+}
+/** 已排序序列的中位数（偶数个取中间两者平均；空返回 0）。 */
+function medianOf(sorted) {
+    const n = sorted.length;
+    if (n === 0)
+        return 0;
+    const mid = Math.floor(n / 2);
+    return n % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
 export class MemoryDb {
     db;
     degraded = false;
@@ -56,6 +67,9 @@ export class MemoryDb {
     stmtL1FtsDelete;
     stmtL1FtsSearch;
     stmtL1FtsSearchFamily;
+    /** token_cost 明细写入 / 滚动清理语句（构造期 prepare 缓存）。 */
+    stmtInsertCost;
+    stmtDeleteCost;
     stmtUpsertL0;
     stmtGetL0;
     /** 主表存在性点查（同 L1：防御性 FTS 删除的前置判断）。 */
@@ -325,6 +339,25 @@ export class MemoryDb {
         this.stmtGetL0 = this.db.prepare('SELECT session_id, role, message_text, recorded_at, timestamp FROM l0_conversations WHERE record_id = ?');
         this.stmtL0Exists = this.db.prepare('SELECT 1 FROM l0_conversations WHERE record_id = ?');
         this.prepareL0VecStatements();
+        // ── token_cost：蒸馏成本明细表（成本看板用；保留期经 retentionDays 滚动清理） ──
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS token_cost (
+        ts INTEGER NOT NULL,
+        provider TEXT NOT NULL,
+        model TEXT NOT NULL,
+        layer TEXT NOT NULL,
+        input_chars INTEGER NOT NULL DEFAULT 0,
+        output_tokens INTEGER NOT NULL DEFAULT 0,
+        reasoning_tokens INTEGER NOT NULL DEFAULT 0
+      )
+    `);
+        // 迁移：provider/model 复合键引入前的旧表补 provider 列（历史行回填 unknown）
+        if (this.tableExists('token_cost') && !this.hasColumn('token_cost', 'provider')) {
+            this.db.exec("ALTER TABLE token_cost ADD COLUMN provider TEXT NOT NULL DEFAULT 'unknown'");
+        }
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_token_cost_ts ON token_cost(ts)');
+        this.stmtInsertCost = this.db.prepare('INSERT INTO token_cost (ts, provider, model, layer, input_chars, output_tokens, reasoning_tokens) VALUES (?, ?, ?, ?, ?, ?, ?)');
+        this.stmtDeleteCost = this.db.prepare('DELETE FROM token_cost WHERE ts < ?');
         // ── FTS5 全文索引（建表失败仅停用 FTS，不降级整个库） ──
         try {
             // 索引重建判据（FTS5 无法 ALTER，只能 drop 后从源表全量回灌）：
@@ -670,12 +703,19 @@ export class MemoryDb {
     /** 事务内的单条写入体（upsertL1 / upsertL1Batch 共用；调用方负责 BEGIN/COMMIT）。 */
     upsertL1InTx(record, embedding) {
         const ts = timestampsToDb(record.timestamps);
+        // 绑定层字段兜底（取 schema 列默认）：旧版 JSONL 等外部数据缺字段时 undefined
+        // 无法绑定（node:sqlite 拒绝绑定），曾致旧版导入逐条全挂、每次启动无限重试（#28）。
+        // 主表与 FTS 两条语句共用同源归一化值；type 归一化后 familyForType 也不再收到 undefined。
+        const type = record.type ?? '';
+        const priority = record.priority ?? 50;
+        const sceneName = record.scene_name ?? '';
+        const family = record.family ?? familyForType(type);
         // 防御性 FTS 删除的前置点查（主键索引，微秒级）：record_id 在 FTS 表是 UNINDEXED，
         // 按 id DELETE 是 O(N) 全表扫描——导入/重建/重嵌等"全新增"路径曾为每条记录白付一次
         // 全扫（批量写整体 O(N²)）。只有主表已有该行（覆盖/合并）才可能有旧 FTS 行需要删。
         // 同批重复 id 也能正确处理：首条插入后，第二条的点查在同一事务内已见新行。
         const ftsExisted = this.ftsAvailable ? this.stmtL1Exists.get(record.id) !== undefined : false;
-        this.stmtUpsertL1.run(record.id, record.content, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
+        this.stmtUpsertL1.run(record.id, record.content, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), family);
         // vec0 不支持 ON CONFLICT → 先删后插；零向量跳过（cosine 未定义）
         if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
             this.stmtDeleteL1Vec.run(record.id);
@@ -688,7 +728,7 @@ export class MemoryDb {
         if (this.ftsAvailable) {
             if (ftsExisted)
                 this.stmtL1FtsDelete.run(record.id);
-            this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
+            this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), family);
         }
     }
     /** 批量删除 L1（元数据 + 向量 + FTS），返回删除条数。IN 按 ≤900 分块（避变量数上限）。 */
@@ -932,22 +972,29 @@ export class MemoryDb {
         try {
             this.db.exec('BEGIN');
             for (let i = 0; i < records.length; i++) {
-                const r = records[i];
+                const rec = records[i];
+                // 绑定层字段兜底（取 schema 列默认）：同 upsertL1InTx——外部数据缺字段时
+                // undefined 无法绑定（#28）；主表/向量/FTS 共用同源归一化值
+                const sessionId = rec.sessionId ?? 'default';
+                const role = rec.role ?? '';
+                const content = rec.content ?? '';
+                const recordedAt = rec.recordedAt ?? '';
+                const timestamp = rec.timestamp ?? 0;
                 // 同 upsertL1 的点查预判：全新增路径跳过 UNINDEXED 列的 FTS 全扫删除
-                const ftsExisted = this.ftsAvailable ? this.stmtL0Exists.get(r.id) !== undefined : false;
-                this.stmtUpsertL0.run(r.id, r.sessionId, r.role, r.content, r.recordedAt, r.timestamp);
+                const ftsExisted = this.ftsAvailable ? this.stmtL0Exists.get(rec.id) !== undefined : false;
+                this.stmtUpsertL0.run(rec.id, sessionId, role, content, recordedAt, timestamp);
                 if (this.stmtDeleteL0Vec && this.stmtInsertL0Vec) {
-                    this.stmtDeleteL0Vec.run(r.id);
+                    this.stmtDeleteL0Vec.run(rec.id);
                     const vec = embeddings?.[i];
                     if (vec && !isZeroVector(vec)) {
-                        this.stmtInsertL0Vec.run(r.id, vecToBuffer(vec), r.recordedAt);
+                        this.stmtInsertL0Vec.run(rec.id, vecToBuffer(vec), recordedAt);
                     }
                 }
                 if (this.ftsAvailable) {
                     // 同 upsertL1：FTS 失败冒泡触发整批回滚，禁止"删了没补"的索引空洞。
                     if (ftsExisted)
-                        this.stmtL0FtsDelete.run(r.id);
-                    this.stmtL0FtsInsert.run(tokenizeForFts(r.content), r.content, r.id, r.sessionId, r.role, r.recordedAt, r.timestamp);
+                        this.stmtL0FtsDelete.run(rec.id);
+                    this.stmtL0FtsInsert.run(tokenizeForFts(content), content, rec.id, sessionId, role, recordedAt, timestamp);
                 }
             }
             this.db.exec('COMMIT');
@@ -964,6 +1011,135 @@ export class MemoryDb {
             return false;
         }
     }
+    /**
+     * 记录一次蒸馏调用成本（明细表，写入时按 retentionDays 滚动清理；0 = 永久保留）。
+     * 失败/成功都记（token 照烧）；记账失败记 warn 但不阻断蒸馏（成本看板是增强能力）。
+     */
+    insertCostCall(provider, model, layer, inputChars, outputTokens, reasoningTokens, retentionDays) {
+        if (this.degraded)
+            return;
+        try {
+            this.stmtInsertCost.run(Date.now(), provider, model, layer, Math.max(0, Math.round(inputChars)), Math.max(0, Math.round(outputTokens)), Math.max(0, Math.round(reasoningTokens)));
+            if (retentionDays > 0)
+                this.stmtDeleteCost.run(Date.now() - retentionDays * 24 * 3600_000);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} token_cost 记账失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * 查询 token_cost 单窗口聚合（成本看板用；since 为毫秒起点，0 = 全量）。
+     * 输入口径：inputChars 是字符（llm 流拿不到输入 token，沿用 llm-usage 的字符折算口径）。
+     * 成本看板是增强能力：降级态/查询异常一律返回零值，不向上抛错。
+     * median 需取 output_tokens 序列在 JS 侧算（SQLite 无内置 median 函数）。
+     */
+    aggregateCost(since) {
+        if (this.degraded)
+            return { total: emptyCostAggregate(), byModel: [] };
+        try {
+            const total = this.db
+                .prepare(`SELECT COUNT(*) AS calls,
+                  COALESCE(SUM(input_chars), 0) AS inputChars,
+                  COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                  COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens,
+                  COALESCE(AVG(output_tokens), 0) AS avgOutputTokens
+             FROM token_cost WHERE ts >= ?`)
+                .get(since);
+            const tokenRows = this.db
+                .prepare('SELECT output_tokens FROM token_cost WHERE ts >= ? ORDER BY output_tokens')
+                .all(since);
+            const byModel = this.db
+                .prepare(`SELECT provider, model, COUNT(*) AS calls,
+                  COALESCE(SUM(input_chars), 0) AS inputChars,
+                  COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                  COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens
+             FROM token_cost WHERE ts >= ? GROUP BY provider, model ORDER BY outputTokens DESC`)
+                .all(since);
+            return {
+                total: {
+                    calls: total.calls,
+                    inputChars: total.inputChars,
+                    outputTokens: total.outputTokens,
+                    reasoningTokens: total.reasoningTokens,
+                    avgOutputTokens: total.avgOutputTokens,
+                    medianOutputTokens: medianOf(tokenRows.map((r) => r.output_tokens)),
+                },
+                byModel,
+            };
+        }
+        catch {
+            return { total: emptyCostAggregate(), byModel: [] };
+        }
+    }
+    /**
+     * 按层级归并聚合（l1 = l1-extract + l1-dedup；成本看板层级表格用）。
+     * 降级/异常返回空数组，不抛错。
+     */
+    aggregateCostByLayer(since) {
+        if (this.degraded)
+            return [];
+        try {
+            const rows = this.db
+                .prepare(`SELECT CASE WHEN layer IN ('l1-extract','l1-dedup') THEN 'l1' ELSE layer END AS layer,
+                  COUNT(*) AS calls,
+                  COALESCE(SUM(input_chars), 0) AS inputChars,
+                  COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                  COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens,
+                  COALESCE(AVG(output_tokens), 0) AS avgOutputTokens
+             FROM token_cost WHERE ts >= ? GROUP BY layer ORDER BY layer`)
+                .all(since);
+            // 中位数需取 output_tokens 序列在 JS 侧算（SQLite 无内置 median）
+            const tokenRows = this.db
+                .prepare(`SELECT CASE WHEN layer IN ('l1-extract','l1-dedup') THEN 'l1' ELSE layer END AS layer,
+                  output_tokens
+             FROM token_cost WHERE ts >= ? ORDER BY layer, output_tokens`)
+                .all(since);
+            const medianByLayer = new Map();
+            for (const r of tokenRows) {
+                const arr = medianByLayer.get(r.layer);
+                if (arr)
+                    arr.push(r.output_tokens);
+                else
+                    medianByLayer.set(r.layer, [r.output_tokens]);
+            }
+            return rows.map((r) => ({
+                ...r,
+                medianOutputTokens: medianOf(medianByLayer.get(r.layer) ?? []),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 按时间桶（bucketMs 毫秒）+ model 聚合，返回扁平行。
+     * offsetMs 把桶边界对齐本地时区；layer 为空=全部，'l1' 归并 extract/dedup，其余精确匹配。
+     * 趋势图与「日均/周均/月均 + 中位数」统计共用：JS 侧按不同 bucketMs 调三次再聚合。
+     */
+    aggregateByBucket(bucketMs, offsetMs, since, layer) {
+        if (this.degraded)
+            return [];
+        try {
+            let sql = `SELECT CAST((ts + ?) / ? AS INTEGER) AS bucket, provider, model,
+                COUNT(*) AS calls,
+                COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens
+           FROM token_cost WHERE ts >= ?`;
+            const params = [offsetMs, bucketMs, since];
+            if (layer === 'l1') {
+                sql += ` AND layer IN ('l1-extract','l1-dedup')`;
+            }
+            else if (layer) {
+                sql += ` AND layer = ?`;
+                params.push(layer);
+            }
+            sql += ` GROUP BY bucket, provider, model ORDER BY bucket, provider, model`;
+            return this.db.prepare(sql).all(...params);
+        }
+        catch {
+            return [];
+        }
+    }
     countL0() {
         if (this.degraded)
             return 0;

package/dist/token-cost.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 蒸馏成本看板账本：把每次蒸馏调用（model × layer）的 token 成本写入 SQLite 明细表。
+ *
+ * 模块级单例 + init 注入 db：callLLM 拿不到 db（db 在 index.ts 运行时创建），
+ * 故通过 initTokenCost(db, retentionDays) 在插件启动时注入；recordCostCall 每次调用写一行明细。
+ *
+ * 与作者 llm-usage.ts 的关系：作者是"按 layer 累计的纯内存计数器"（给 bench 用）；
+ * 本模块补上三个缺口——按 model 分组、持久化（保留期可配置，默认 365 天）、面向 UI 成本看板。
+ */
+import type { DistillLayer } from './llm-usage.js';
+import type { CostByModel, MemoryDb } from './store/sqlite.js';
+/** 插件启动时注入 db 与明细保留期（index.ts 调用；retentionDays 0 = 永久保留）。 */
+export declare function initTokenCost(d: MemoryDb, retention: number): void;
+/** 插件卸载时清空 db 引用（index.ts 的 ctx.effect 清理里调用，防悬空引用）。 */
+export declare function resetTokenCost(): void;
+/** 记录一次蒸馏调用成本（callLLM 出口调用；provider/model 由调用方传入）。 */
+export declare function recordCostCall(provider: string, model: string, layer: DistillLayer, inputChars: number, outputTokens: number, reasoningTokens: number): void;
+/** 成本看板单个时间窗口（day/week/month/all）。 */
+export interface CostWindow {
+    range: 'day' | 'week' | 'month' | 'all';
+    /** 窗口起点（毫秒；all 为 0）。 */
+    since: number;
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    avgOutputTokens: number;
+    medianOutputTokens: number;
+}
+/** 成本看板时间粒度（趋势图 + 统计口径共用）。 */
+export type Granularity = 'day' | 'week' | 'month';
+/** 每模型统计指标（层级表格行；均值/中位数按 since=0 全量历史的活跃桶口径，非「最近窗口」）。 */
+export interface ModelMetrics {
+    model: string;
+    dayCalls: number;
+    weekCalls: number;
+    monthCalls: number;
+    dayOutput: number;
+    dayMedian: number;
+    weekOutput: number;
+    weekMedian: number;
+    monthOutput: number;
+    monthMedian: number;
+}
+/** 每层级（l1/l2/l3）的模型统计（层级表格）。 */
+export interface LayerMetrics {
+    layer: 'l1' | 'l2' | 'l3';
+    models: ModelMetrics[];
+}
+/** 层级 × 窗口矩阵里的单个窗口格子。 */
+export interface LayerWindow {
+    range: 'day' | 'week' | 'month' | 'all';
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    avgOutputTokens: number;
+    medianOutputTokens: number;
+}
+/** 单个层级在四个窗口的聚合（层级×窗口表格行）。 */
+export interface LayerCost {
+    layer: 'l1' | 'l2' | 'l3';
+    windows: LayerWindow[];
+}
+/** 趋势单桶。 */
+export interface TrendBucket {
+    ts: number;
+    total: number;
+    byModel: Record<string, number>;
+}
+/** 趋势快照：三个层级各一份连续桶序列。 */
+export interface TrendSnapshot {
+    granularity: Granularity;
+    byLayer: Record<'l1' | 'l2' | 'l3', TrendBucket[]>;
+}
+/** 成本看板快照（dsh-memory/token-cost 端点返回值）。 */
+export interface CostSnapshot {
+    /** day/week/month/all 四窗口聚合。 */
+    windows: CostWindow[];
+    /** 全量窗口（all）按 model 分组。 */
+    byModel: CostByModel[];
+    /** 按层级（l1/l2/l3 归并）在四个窗口的聚合（层级×窗口表格）。 */
+    byLayer: LayerCost[];
+    /** 每层级的模型统计指标（层级表格）。 */
+    byLayerStats: LayerMetrics[];
+    /** 趋势图数据。 */
+    trend: TrendSnapshot;
+}
+/** 读成本看板快照（db 未注入/降级时返回全零结构，不抛错；rangeDays>0 = 趋势展示近 N 天）。 */
+export declare function snapshotTokenCost(granularity: Granularity, rangeDays: number): CostSnapshot;