dsh-prime-memory 0.11.0

package/dist/store/bm25.d.ts

@@ -0,0 +1,19 @@
+export interface Bm25Doc {
+    id: string;
+    text: string;
+}
+export interface Bm25Hit {
+    id: string;
+    score: number;
+}
+export declare class Bm25Index {
+    private docs;
+    private termFreq;
+    private docLen;
+    private df;
+    private totalLen;
+    get size(): number;
+    /** 全量重建(小语料每轮重建,量级为个位数到百条)。 */
+    rebuild(docs: Bm25Doc[]): void;
+    search(query: string, topK: number, filter?: (id: string) => boolean): Bm25Hit[];
+}

package/dist/store/bm25.js

@@ -0,0 +1,63 @@
+/**
+ * 轻量 BM25 检索:与 FTS 共用同一分词器(util/text.ts 的 tokenize,
+ * jieba 词 + CJK 二元组并集)。
+ * 仅用于 L2 场景摘要的上下文选取(小语料);L0/L1 检索走 SQLite FTS5/向量。
+ */
+import { tokenize } from '../util/text.js';
+const K1 = 1.5;
+const B = 0.75;
+export class Bm25Index {
+    docs = [];
+    termFreq = [];
+    docLen = [];
+    df = new Map();
+    totalLen = 0;
+    get size() {
+        return this.docs.length;
+    }
+    /** 全量重建(小语料每轮重建,量级为个位数到百条)。 */
+    rebuild(docs) {
+        this.docs = docs;
+        this.termFreq = [];
+        this.docLen = [];
+        this.df = new Map();
+        this.totalLen = 0;
+        for (let i = 0; i < docs.length; i++) {
+            const terms = tokenize(docs[i].text);
+            const tf = new Map();
+            for (const t of terms)
+                tf.set(t, (tf.get(t) ?? 0) + 1);
+            this.termFreq.push(tf);
+            this.docLen.push(terms.length);
+            this.totalLen += terms.length;
+            for (const t of tf.keys())
+                this.df.set(t, (this.df.get(t) ?? 0) + 1);
+        }
+    }
+    search(query, topK, filter) {
+        const terms = tokenize(query);
+        if (terms.length === 0 || this.docs.length === 0)
+            return [];
+        const avgdl = this.totalLen / this.docs.length || 1;
+        const n = this.docs.length;
+        const scores = [];
+        for (let i = 0; i < n; i++) {
+            if (filter && !filter(this.docs[i].id))
+                continue;
+            const tf = this.termFreq[i];
+            const len = this.docLen[i];
+            let score = 0;
+            for (const t of new Set(terms)) {
+                const f = tf.get(t) ?? 0;
+                if (f === 0)
+                    continue;
+                const idf = Math.log(1 + (n - (this.df.get(t) ?? 0) + 0.5) / ((this.df.get(t) ?? 0) + 0.5));
+                score += idf * ((f * (K1 + 1)) / (f + K1 * (1 - B + B * (len / avgdl))));
+            }
+            if (score > 0)
+                scores.push({ i, s: score });
+        }
+        scores.sort((a, b) => b.s - a.s);
+        return scores.slice(0, topK).map(({ i, s }) => ({ id: this.docs[i].id, score: s }));
+    }
+}

package/dist/store/cost-ledger.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 蒸馏成本账本(token_cost 明细表)。
+ *
+ * 职责:明细写入(写入时按保留期滚动清理)+ 四路聚合查询(单窗口总览 / 按模型 /
+ * 按层级归并 / 按时间桶)。与检索引擎零关系——唯一耦合是共享同一个 node:sqlite
+ * 连接。成本看板是增强能力:降级/异常一律返回零值,不向上抛错。
+ * MemoryDb 的四个同名公开方法保持签名做一行委托,调用方零改动。
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { CostByModel } from '../contract.js';
+import type { MemoryLogger } from '../types.js';
+/** token_cost 单窗口成本聚合(成本看板用)。 */
+export interface CostAggregate {
+    calls: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    /** 单次调用输出 token 均值(无数据为 0)。 */
+    avgOutputTokens: number;
+    /** 单次调用输出 token 中位数(无数据为 0)。 */
+    medianOutputTokens: 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;
+}
+export declare class CostLedger {
+    private db;
+    private logger;
+    private stmtInsert;
+    private stmtDelete;
+    /** init 是否成功(未就绪 = 宿主库降级,方法全部返回零值不抛错)。 */
+    get ready(): boolean;
+    /** 建表 + 迁移 + 语句缓存(MemoryDb.initSchema 内调用;失败冒泡触发库级降级)。 */
+    init(db: DatabaseSync, logger?: MemoryLogger): void;
+    /**
+     * 记录一次蒸馏调用成本(明细表,写入时按 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 的字符折算口径)。
+     */
+    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[];
+}

package/dist/store/cost-ledger.js

@@ -0,0 +1,171 @@
+function emptyCostAggregate() {
+    return { calls: 0, inputChars: 0, outputTokens: 0, reasoningTokens: 0, avgOutputTokens: 0, medianOutputTokens: 0 };
+}
+/** 已排序序列的中位数(偶数个取中间两者平均;空返回 0)。SQLite 无内置 median,序列须取回 JS 计算。 */
+function medianOf(sorted) {
+    const n = sorted.length;
+    if (n === 0)
+        return 0;
+    const mid = Math.floor(n / 2);
+    return n % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+export class CostLedger {
+    db = null;
+    logger;
+    stmtInsert = null;
+    stmtDelete = null;
+    /** init 是否成功(未就绪 = 宿主库降级,方法全部返回零值不抛错)。 */
+    get ready() {
+        return this.stmtInsert !== null;
+    }
+    /** 建表 + 迁移 + 语句缓存(MemoryDb.initSchema 内调用;失败冒泡触发库级降级)。 */
+    init(db, logger) {
+        this.db = db;
+        this.logger = logger;
+        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)
+        const cols = db.prepare('PRAGMA table_info(token_cost)').all();
+        if (!cols.some((c) => c.name === 'provider')) {
+            db.exec("ALTER TABLE token_cost ADD COLUMN provider TEXT NOT NULL DEFAULT 'unknown'");
+        }
+        db.exec('CREATE INDEX IF NOT EXISTS idx_token_cost_ts ON token_cost(ts)');
+        this.stmtInsert = db.prepare('INSERT INTO token_cost (ts, provider, model, layer, input_chars, output_tokens, reasoning_tokens) VALUES (?, ?, ?, ?, ?, ?, ?)');
+        this.stmtDelete = db.prepare('DELETE FROM token_cost WHERE ts < ?');
+    }
+    /**
+     * 记录一次蒸馏调用成本(明细表,写入时按 retentionDays 滚动清理;0 = 永久保留)。
+     * 失败/成功都记(token 照烧);记账失败记 warn 但不阻断蒸馏(成本看板是增强能力)。
+     */
+    insertCostCall(provider, model, layer, inputChars, outputTokens, reasoningTokens, retentionDays) {
+        if (!this.db || !this.stmtInsert || !this.stmtDelete)
+            return;
+        try {
+            this.stmtInsert.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.stmtDelete.run(Date.now() - retentionDays * 24 * 3600_000);
+        }
+        catch (err) {
+            this.logger?.warn(`[memory][sqlite] token_cost 记账失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * 查询 token_cost 单窗口聚合(成本看板用;since 为毫秒起点,0 = 全量)。
+     * 输入口径:inputChars 是字符(llm 流拿不到输入 token,沿用 llm-usage 的字符折算口径)。
+     */
+    aggregateCost(since) {
+        if (!this.ready || !this.db)
+            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.ready || !this.db)
+            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);
+            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.ready || !this.db)
+            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 [];
+        }
+    }
+}

package/dist/store/download-queue.d.ts

@@ -0,0 +1,79 @@
+import type { MemoryLogger } from '../types.js';
+import { type CatalogEntry } from './model-catalog.js';
+import type { DownloadProgress } from '../contract.js';
+export type { DownloadPhase, DownloadProgress } from '../contract.js';
+export interface ModelStatus {
+    id: string;
+    /** none=未下载;partial=有断点/不完整;downloaded=全部文件就位且尺寸吻合。 */
+    state: 'none' | 'partial' | 'downloaded';
+    bytesOnDisk: number;
+    totalBytes: number;
+}
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export interface DownloaderOptions {
+    /** 下载镜像根(默认 https://hf-mirror.com,可配回 https://huggingface.co)。 */
+    mirror: string;
+    logger?: MemoryLogger;
+    /** 测试注入;默认 undici fetch(按需挂代理 dispatcher)。 */
+    fetchImpl?: FetchLike;
+    /** 测试注入磁盘剩余字节;默认 statfs。 */
+    freeBytes?: () => Promise<number | null>;
+    /** 单文件失败的自动重试间隔(毫秒),长度即重试次数;默认 [1000, 3000]。 */
+    retryDelaysMs?: number[];
+    /** 显式代理三态(见模块头注释)。 */
+    proxy?: string;
+}
+export declare class ModelDownloadQueue {
+    private readonly dataDir;
+    private readonly opts;
+    private progress;
+    private busy;
+    private abort;
+    /** 代理 dispatcher(按需创建;dispose 关闭连接池)。 */
+    private agent;
+    /** 默认 fetch:undici(可挂代理 dispatcher);测试注入优先。 */
+    private readonly defaultFetch;
+    constructor(dataDir: string, opts: DownloaderOptions);
+    /** 镜像根(无尾斜杠)。 */
+    private mirrorUrl;
+    /** 释放代理连接池(插件 dispose 链调用;无代理时幂等无操作)。 */
+    dispose(): void;
+    /** 当前进度快照(无任务时 null)。 */
+    getProgress(): DownloadProgress | null;
+    /** 是否有任务在跑(含校验阶段)。 */
+    isBusy(): boolean;
+    modelsDir(id: string): string;
+    /** 全目录状态扫描(设置页模型卡数据源)。 */
+    listStatus(): Promise<ModelStatus[]>;
+    /** 单模型是否已完整下载(尺寸口径,不做哈希复验——下载完成时已验过)。 */
+    isDownloaded(id: string): Promise<boolean>;
+    /** 删除已下载模型(切走后释放磁盘;正在使用/下载中的拒绝)。 */
+    deleteModel(id: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** 启动下载(串行队列:忙时直接拒绝)。resolve 在任务终态(done/error/cancelled)。 */
+    start(id: string): Promise<DownloadProgress>;
+    /** 按给定目录项启动(测试缝:合成目录项驱动状态机,不触网)。 */
+    startEntry(entry: CatalogEntry): Promise<DownloadProgress>;
+    /** 取消当前任务:中断 fetch,保留 .part 断点。 */
+    cancel(): boolean;
+    private run;
+    /** 下载单文件到最终路径(含续传与校验),返回该文件贡献的字节数。
+     *  单文件失败自动重试(默认 2 次)+ 重试换缓存键(见模块头注释):
+     *  - sha256 失配:downloadFileOnce 已删除断点 → 从零重下;
+     *  - 数量不吻合/网络错误:断点保留 → Range 续传重试;
+     *  - 取消:立即上抛不重试。 */
+    private downloadFile;
+    /** 单次尝试:续传探测 → fetch(attempt>0 追加缓存键参数)→ 落盘 → 尺寸与 sha256 校验 → rename。 */
+    private downloadFileOnce;
+    private freeBytes;
+}
+/**
+ * 解析下载代理(三态):`''`(默认)= 探测代理环境变量(HTTPS_PROXY > ALL_PROXY >
+ * HTTP_PROXY,大小写双形态,尊重 NO_PROXY);`'none'` = 禁用代理强制直连;
+ * 其他值 = 显式代理 URL。与 curl/npm 同语义。
+ */
+export declare function resolveProxyUrl(setting: string | undefined, host: string): string;
+/** 代理 URL 日志脱敏:剥掉 userinfo(内网代理常带 user:pass 凭据),只留 scheme//host。 */
+export declare function maskProxyUrl(proxy: string): string;