dsh-prime-memory 0.11.0

package/dist/store/state.d.ts

@@ -0,0 +1,41 @@
+import type { MemoryFamily } from '../types.js';
+export interface MemoryState {
+    /** 上次 L1 抽取时间(epoch ms)。 */
+    lastExtractAt: number;
+    /** 上次 L1 抽取得到的最后一个情境名(情境连续性用)。 */
+    lastSceneName: string;
+    /** L1 累计抽取条数。 */
+    totalExtracted: number;
+    /** 自上次 L2 整合以来的新记忆数。 */
+    newMemoriesSinceL2: number;
+    /** 上次 L2 整合时间。 */
+    lastL2At: number;
+    /** 自上次 L3 蒸馏以来的新记忆数。 */
+    memoriesSinceL3: number;
+    /** 上次 L3 蒸馏时间。 */
+    lastL3At: number;
+    /** L3 是否已生成过(冷启动判定)。 */
+    hasPersona: boolean;
+    /** L2 输出请求的 L3 更新原因([PERSONA_UPDATE_REQUEST])。 */
+    personaRequestedReason?: string;
+}
+export declare function defaultState(): MemoryState;
+export declare class StateStore {
+    private readonly file;
+    private buckets;
+    private migrated;
+    constructor(file: string);
+    load(): Promise<void>;
+    /** v1 → v2 迁移发生时为 true(调用方记日志/落盘)。 */
+    get didMigrate(): boolean;
+    /** 取某族的 checkpoint(活引用——改字段后 save 生效)。 */
+    forFamily(family: MemoryFamily): MemoryState;
+    /**
+     * 重建用:两族 checkpoint 重置为默认值。
+     * 必须原地突变(Object.assign)——runner.states 等处持有桶对象的活引用,
+     * 换新对象会让引用指向已废弃的桶,后续计数写到内存孤儿上。
+     */
+    reset(): void;
+    save(): Promise<void>;
+    static pathFor(dataDir: string): string;
+}

package/dist/store/state.js

@@ -0,0 +1,72 @@
+/**
+ * 管线 checkpoint 状态。持久化在 <dataDir>/state.json。
+ *
+ * v2 起按族分桶(L2/L3 分族隔离后阈值计数、情境链各自独立);
+ * 旧平铺格式(v1)在 load 时整体迁入 chat 桶(历史数据由 chat 档蒸馏产出)。
+ */
+import * as path from 'node:path';
+import { atomicWriteJson, readJsonIfExists } from '../util/io.js';
+export function defaultState() {
+    return {
+        lastExtractAt: 0,
+        lastSceneName: '',
+        totalExtracted: 0,
+        newMemoriesSinceL2: 0,
+        lastL2At: 0,
+        memoriesSinceL3: 0,
+        lastL3At: 0,
+        hasPersona: false,
+    };
+}
+export class StateStore {
+    file;
+    // 声明即初始化:forFamily 在 load 完成前也安全(stats 面板可能早于 runner.init 拉取)
+    buckets = { chat: defaultState(), work: defaultState() };
+    migrated = false;
+    constructor(file) {
+        this.file = file;
+    }
+    async load() {
+        const raw = await readJsonIfExists(this.file);
+        if (!raw)
+            return;
+        if (raw.version === 2 && raw.families && typeof raw.families === 'object') {
+            // v2:逐族宽容合并(新字段自动带默认值)
+            this.buckets = {
+                chat: { ...defaultState(), ...(raw.families.chat ?? {}) },
+                work: { ...defaultState(), ...(raw.families.work ?? {}) },
+            };
+        }
+        else {
+            // v1 平铺 → 整体迁入 chat 桶(历史数据是 chat 档蒸馏产出)
+            this.buckets = { chat: { ...defaultState(), ...raw }, work: defaultState() };
+            this.migrated = true;
+        }
+    }
+    /** v1 → v2 迁移发生时为 true(调用方记日志/落盘)。 */
+    get didMigrate() {
+        return this.migrated;
+    }
+    /** 取某族的 checkpoint(活引用——改字段后 save 生效)。 */
+    forFamily(family) {
+        return this.buckets[family];
+    }
+    /**
+     * 重建用:两族 checkpoint 重置为默认值。
+     * 必须原地突变(Object.assign)——runner.states 等处持有桶对象的活引用,
+     * 换新对象会让引用指向已废弃的桶,后续计数写到内存孤儿上。
+     */
+    reset() {
+        for (const family of ['chat', 'work']) {
+            Object.assign(this.buckets[family], defaultState());
+            this.buckets[family].personaRequestedReason = undefined;
+        }
+    }
+    async save() {
+        const file = { version: 2, families: this.buckets };
+        await atomicWriteJson(this.file, file);
+    }
+    static pathFor(dataDir) {
+        return path.join(dataDir, 'state.json');
+    }
+}

package/dist/token-cost.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 蒸馏成本看板账本:把每次蒸馏调用(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 { CostSnapshot, Granularity } from './contract.js';
+import type { DistillLayer } from './llm-usage.js';
+import type { MemoryDb } from './store/sqlite.js';
+export type { CostWindow, Granularity, ModelMetrics, LayerMetrics, LayerWindow, LayerCost, TrendBucket, TrendSnapshot, CostSnapshot, } from './contract.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;
+/** 读成本看板快照(db 未注入/降级时返回全零结构,不抛错;rangeDays>0 = 趋势展示近 N 天)。 */
+export declare function snapshotTokenCost(granularity: Granularity, rangeDays: number): CostSnapshot;

package/dist/token-cost.js

@@ -0,0 +1,185 @@
+let db = null;
+let retentionDays = 365;
+/** 插件启动时注入 db 与明细保留期(index.ts 调用;retentionDays 0 = 永久保留)。 */
+export function initTokenCost(d, retention) {
+    db = d;
+    retentionDays = Math.max(0, Math.round(retention));
+}
+/** 插件卸载时清空 db 引用(index.ts 的 ctx.effect 清理里调用,防悬空引用)。 */
+export function resetTokenCost() {
+    db = null;
+}
+/** 记录一次蒸馏调用成本(callLLM 出口调用;provider/model 由调用方传入)。 */
+export function recordCostCall(provider, model, layer, inputChars, outputTokens, reasoningTokens) {
+    if (!db)
+        return;
+    db.insertCostCall(provider, model, layer, inputChars, outputTokens, reasoningTokens, retentionDays);
+}
+/** 四窗口定义:range + 回看毫秒数(all 的 ms 恒 0)。 */
+const WINDOW_DEFS = [
+    { range: 'day', ms: 24 * 3600_000 },
+    { range: 'week', ms: 7 * 24 * 3600_000 },
+    { range: 'month', ms: 30 * 24 * 3600_000 },
+    { range: 'all', ms: 0 },
+];
+/** 趋势桶宽(毫秒)与桶数。 */
+const TREND_MS = { day: 24 * 3600_000, week: 7 * 24 * 3600_000, month: 30 * 24 * 3600_000 };
+const TREND_COUNT = { day: 30, week: 12, month: 12 };
+/**
+ * 三个归并层级(层级表格/趋势的分组口径)。
+ * 豁免约定:graph 投影调用(DistillLayer 'graph')的成本**进总额窗口与按模型
+ * 分组**(windows/byModel),但**不进分层表格与趋势**(byLayer/byLayerStats/
+ * trend)——层级表是"蒸馏管线 l1→l2→l3"的产物结构视图,图谱投影是旁路增强,
+ * 混入会破坏该表"逐层产物成本"的语义。aggregateCostByLayer 的 SQL 会原样带出
+ * 'graph' 行,此处映射时丢弃(聚合口径变更只需改这一处)。
+ */
+const LAYERS = ['l1', 'l2', 'l3'];
+/** 本地时区偏移(东正西负):把 SQL 端 UTC epoch 桶边界对齐到本地午夜。 */
+function localOffsetMs() {
+    return -new Date().getTimezoneOffset() * 60_000;
+}
+/** 已排序序列的中位数(偶数取中间两者平均;空返回 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;
+}
+/** provider/model 复合键(避免跨 provider 同名 model 在聚合里混淆)。 */
+function modelKey(provider, model) {
+    return provider + '/' + model;
+}
+/** 从某模型某粒度的 bucket 序列算均值/中位数(活跃桶口径:只除有调用的桶数)。 */
+function statOf(rows) {
+    const active = rows.filter((r) => r.calls > 0);
+    if (active.length === 0)
+        return { avgCalls: 0, avgOutput: 0, medianOutput: 0 };
+    const calls = active.reduce((s, r) => s + r.calls, 0);
+    const output = active.reduce((s, r) => s + r.outputTokens, 0);
+    return {
+        avgCalls: calls / active.length,
+        avgOutput: output / active.length,
+        medianOutput: medianOf(active.map((r) => r.outputTokens).sort((a, b) => a - b)),
+    };
+}
+/** 从 day/week/month 三组 bucket 行组装每个模型的统计指标(provider/model 复合键)。 */
+function buildModelMetrics(dayRows, weekRows, monthRows) {
+    const keys = new Set();
+    for (const r of dayRows)
+        keys.add(modelKey(r.provider, r.model));
+    for (const r of weekRows)
+        keys.add(modelKey(r.provider, r.model));
+    for (const r of monthRows)
+        keys.add(modelKey(r.provider, r.model));
+    return Array.from(keys)
+        .sort()
+        .map((key) => {
+        const d = statOf(dayRows.filter((r) => modelKey(r.provider, r.model) === key));
+        const w = statOf(weekRows.filter((r) => modelKey(r.provider, r.model) === key));
+        const m = statOf(monthRows.filter((r) => modelKey(r.provider, r.model) === key));
+        return {
+            model: key,
+            dayCalls: d.avgCalls,
+            weekCalls: w.avgCalls,
+            monthCalls: m.avgCalls,
+            dayOutput: d.avgOutput,
+            dayMedian: d.medianOutput,
+            weekOutput: w.avgOutput,
+            weekMedian: w.medianOutput,
+            monthOutput: m.avgOutput,
+            monthMedian: m.medianOutput,
+        };
+    });
+}
+/** 从某层级某粒度的 bucket 行生成连续趋势桶(空桶补 0;count 为桶数,由调用方按展示范围算)。 */
+function buildTrend(rows, granularity, now, count) {
+    const bucketMs = TREND_MS[granularity];
+    const offset = localOffsetMs();
+    const cur = Math.floor((now + offset) / bucketMs);
+    const buckets = [];
+    for (let i = count - 1; i >= 0; i--) {
+        const b = cur - i;
+        buckets.push({ ts: b * bucketMs - offset, total: 0, byModel: {} });
+    }
+    for (const r of rows) {
+        const idx = count - 1 - (cur - r.bucket);
+        if (idx < 0 || idx >= count)
+            continue;
+        const tb = buckets[idx];
+        tb.total += r.outputTokens;
+        const key = modelKey(r.provider, r.model);
+        tb.byModel[key] = (tb.byModel[key] ?? 0) + r.outputTokens;
+    }
+    return buckets;
+}
+/** 读成本看板快照(db 未注入/降级时返回全零结构,不抛错;rangeDays>0 = 趋势展示近 N 天)。 */
+export function snapshotTokenCost(granularity, rangeDays) {
+    const now = Date.now();
+    const emptyWindow = (range, ms) => ({
+        range,
+        since: ms === 0 ? 0 : now - ms,
+        calls: 0,
+        inputChars: 0,
+        outputTokens: 0,
+        reasoningTokens: 0,
+        avgOutputTokens: 0,
+        medianOutputTokens: 0,
+    });
+    if (!db) {
+        return {
+            windows: WINDOW_DEFS.map((w) => emptyWindow(w.range, w.ms)),
+            byModel: [],
+            byLayer: [],
+            byLayerStats: [],
+            trend: { granularity, byLayer: { l1: [], l2: [], l3: [] } },
+        };
+    }
+    // 四窗口总聚合(累计窗口顺带取 byModel)
+    const d = db;
+    const windows = [];
+    let byModel = [];
+    for (const w of WINDOW_DEFS) {
+        const since = w.ms === 0 ? 0 : now - w.ms;
+        const agg = d.aggregateCost(since);
+        windows.push({ range: w.range, since, ...agg.total });
+        if (w.range === 'all')
+            byModel = agg.byModel;
+    }
+    // 按层级 × 窗口聚合(层级×窗口表格):每个窗口调一次 aggregateCostByLayer,再按层组装
+    const layerByWindow = WINDOW_DEFS.map((w) => {
+        const since = w.ms === 0 ? 0 : now - w.ms;
+        return { range: w.range, rows: d.aggregateCostByLayer(since) };
+    });
+    const byLayer = LAYERS.map((layer) => ({
+        layer,
+        windows: layerByWindow.map(({ range, rows }) => {
+            const row = rows.find((r) => r.layer === layer);
+            return {
+                range,
+                calls: row?.calls ?? 0,
+                inputChars: row?.inputChars ?? 0,
+                outputTokens: row?.outputTokens ?? 0,
+                reasoningTokens: row?.reasoningTokens ?? 0,
+                avgOutputTokens: row?.avgOutputTokens ?? 0,
+                medianOutputTokens: row?.medianOutputTokens ?? 0,
+            };
+        }),
+    }));
+    // 每层级模型统计(全量历史口径)+ 趋势(按展示范围)
+    const offset = localOffsetMs();
+    const byLayerStats = [];
+    const trendByLayer = { l1: [], l2: [], l3: [] };
+    // 趋势展示范围:rangeDays > 0 = 近 N 天(强制按「日」粒度出 N 个日桶,不受周/月聚合影响);否则用默认窗口
+    const trendGranularity = rangeDays > 0 ? 'day' : granularity;
+    const trendSince = rangeDays > 0 ? now - rangeDays * 24 * 3600_000 : 0;
+    const trendCount = rangeDays > 0 ? rangeDays : TREND_COUNT[granularity];
+    for (const layer of LAYERS) {
+        const dayRows = d.aggregateByBucket(TREND_MS.day, offset, 0, layer);
+        const weekRows = d.aggregateByBucket(TREND_MS.week, offset, 0, layer);
+        const monthRows = d.aggregateByBucket(TREND_MS.month, offset, 0, layer);
+        byLayerStats.push({ layer, models: buildModelMetrics(dayRows, weekRows, monthRows) });
+        trendByLayer[layer] = buildTrend(d.aggregateByBucket(TREND_MS[trendGranularity], offset, trendSince, layer), trendGranularity, now, trendCount);
+    }
+    return { windows, byModel, byLayer, byLayerStats, trend: { granularity: trendGranularity, byLayer: trendByLayer } };
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 模型可调用工具:memory_search(L1)、conversation_search(L0)、memory_read_scene(L2/L3)、
+ * 高权限 memory_add / memory_delete。
+ *
+ * 会话档位联动:execute 的 exec.agent 即发起调用的 agent(agent.id === sessionId),
+ * memory_search 按会话档位过滤族(auto 不过滤,纯档只查本族);off 档下读类工具统一
+ * 返回提示(本会话已对记忆系统隐身)。conversation_search 检索范围保持全库。
+ * 只写会话(注入覆盖=关)同款拒读,notice 区分文案——写入走捕获钩子不经工具,
+ * 拒读不影响"只写"语义。
+ *
+ * 写删工具受 live.memoryMutate 高权限门控(默认 false):显式记忆指令语义——
+ * 用户说"记得 X" → memory_add;说"忘了/删除该记忆" → memory_delete。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from '../config.js';
+import type { LiveSettingsHandle } from '../settings.js';
+import type { RuminateController } from '../pipeline/ruminate.js';
+import type { GraphStore } from '../store/graph-store.js';
+import type { L0Store } from '../store/l0.js';
+import type { L1Store } from '../store/l1.js';
+import type { PersonaStore } from '../store/persona.js';
+import type { SceneStore } from '../store/scenes.js';
+import type { SessionModeStore } from '../store/session-modes.js';
+import type { MemoryFamily, MemoryLogger } from '../types.js';
+export declare function registerMemoryTools(ctx: Context, cfg: MemoryConfig, stores: {
+    l0: L0Store;
+    l1: L1Store;
+    scenes: Record<MemoryFamily, SceneStore>;
+    persona: Record<MemoryFamily, PersonaStore>;
+    /** 图谱存储(可选:未装配时图谱工具返回未启用提示)。 */
+    graph?: GraphStore;
+}, logger: MemoryLogger, modes: SessionModeStore, live: LiveSettingsHandle, 
+/** 反刍控制器(可选:未装配时 ruminate 工具返回未启用提示)。 */
+ruminate?: RuminateController): void;