dsh-prime-memory 0.11.0

package/dist/pipeline/ruminate.js

@@ -0,0 +1,298 @@
+import { groupPendingBySession, loadPending, } from '../store/pending.js';
+import { errDetail } from '../util/filelog.js';
+import { runSceneConsolidation } from './l2.js';
+import { runPersona } from './l3.js';
+const IDLE_STATUS = {
+    running: false,
+    phase: 'idle',
+    done: 0,
+    total: 0,
+    recordsBuilt: 0,
+    detail: null,
+    cancelRequested: false,
+    startedAt: null,
+    finishedAt: null,
+    error: null,
+};
+function groupSessions(buckets) {
+    const sessions = [];
+    for (const mode of ['auto', 'chat', 'work']) {
+        const groups = groupPendingBySession(buckets[mode]);
+        for (const g of groups) {
+            if (g.messages.length === 0)
+                continue;
+            sessions.push({ sessionId: g.sessionId, mode, messages: g.messages });
+        }
+    }
+    return sessions;
+}
+export class RuminateController {
+    ctx;
+    cfg;
+    runner;
+    stores;
+    logger;
+    live;
+    status = IDLE_STATUS;
+    cancelRequested = false;
+    /** 启动守卫:置位早于 status.running,封住"await 读取"期间的双击窗口。 */
+    starting = false;
+    sessions = [];
+    totalL1 = 0;
+    pendingFile;
+    constructor(ctx, cfg, runner, stores, logger, live, pendingFile) {
+        this.ctx = ctx;
+        this.cfg = cfg;
+        this.runner = runner;
+        this.stores = stores;
+        this.logger = logger;
+        this.live = live;
+        this.pendingFile = pendingFile;
+    }
+    /** 状态快照 */
+    getStatus() {
+        return { ...this.status };
+    }
+    /**
+     * 启动反刍:扫描 pending 三桶,按会话分组,逐个入队蒸馏;完成后强制 L2+L3。
+     * 桶形状的唯一权威是 store/pending.ts 的 loadPending——不得在本层再解析该文件。
+     */
+    async start() {
+        if (this.status.running || this.starting)
+            throw new Error('反刍已在进行中');
+        this.starting = true;
+        try {
+            const liveNow = this.live.get();
+            if (!liveNow.enabled || !liveNow.distill) {
+                throw new Error('蒸馏开关已关闭,请先开启蒸馏再反刍');
+            }
+            if (!this.cfg.extract.enabled) {
+                throw new Error('部署配置已停用蒸馏(extract.enabled=false),无法反刍');
+            }
+            // 读取 pending 三桶(loadPending 负责解包 PendingFile 并校验条目)
+            const { buckets } = await loadPending(this.pendingFile, this.logger);
+            this.sessions = groupSessions(buckets);
+            this.cancelRequested = false;
+            this.totalL1 = 0;
+            if (this.sessions.length === 0) {
+                // 没有 pending 切片 → 做 L2/L3 轻量刷新
+                return await this.doLightRefresh();
+            }
+            this.status = {
+                ...IDLE_STATUS,
+                running: true,
+                phase: 'distilling',
+                total: this.sessions.length,
+                startedAt: Date.now(),
+            };
+            this.logger.info(`[memory] 反刍开始:${this.sessions.length} 个会话待消化`);
+            // 第一个会话入队
+            this.doEnqueue(0);
+            // 此刻 status.running 已置位,后续并发 start() 由该守卫拦截
+            this.starting = false;
+            return { ...this.status };
+        }
+        catch (err) {
+            // 失败必须落状态:否则 status 仍报 idle/error:null,与面板上的报错自相矛盾
+            this.status = {
+                ...IDLE_STATUS,
+                running: false,
+                phase: 'failed',
+                error: errDetail(err),
+                finishedAt: Date.now(),
+            };
+            this.logger.warn(`[memory] 反刍启动失败: ${errDetail(err)}`);
+            throw err;
+        }
+        finally {
+            this.starting = false;
+        }
+    }
+    /** 请求取消:当前块完成后停止,已蒸馏部分保留。 */
+    requestCancel() {
+        if (!this.status.running)
+            return this.getStatus();
+        this.cancelRequested = true;
+        this.status.cancelRequested = true;
+        this.logger.info('[memory] 反刍取消已请求(当前块完成后停止)');
+        return { ...this.status };
+    }
+    /** 入队一个会话。 */
+    doEnqueue(index) {
+        if (this.cancelRequested || index >= this.sessions.length) {
+            // 已登记的会话(含被取消截断者)视为已完成,避免 done 恒 0
+            this.status.done = index;
+            // 收尾
+            void this.finalize();
+            return;
+        }
+        const session = this.sessions[index];
+        this.status.phase = 'distilling';
+        this.status.detail = `L1 蒸馏中:会话 ${session.sessionId}(第 ${index + 1}/${this.sessions.length} 个)`;
+        // 真实产出计数:enqueue 只入队,产出由 onTurnDone 在任务真正跑完后回调
+        // (此前 totalL1 从不累加,recordsBuilt 与完成日志恒为 0,修复效果无法判定)
+        this.runner.enqueue(session.sessionId, session.messages, session.mode, {
+            force: true,
+            onTurnDone: (records) => {
+                this.totalL1 += records;
+                this.status.recordsBuilt = this.totalL1;
+            },
+        });
+        // runner 的 drain 是同步循环,给一个 tick 让它消费完再入队下一个
+        setImmediate(() => this.doEnqueue(index + 1));
+    }
+    /** 收尾:强制 L2 + L3。 */
+    async finalize() {
+        try {
+            this.status.phase = 'consolidating';
+            this.status.detail = 'L2 场景整合(收尾)';
+            const liveNow = this.live.get();
+            const distillOn = liveNow.enabled && liveNow.distill;
+            // 强制 L2:把全部未整合的残余记录落进场景
+            if (this.cfg.l2.enabled && distillOn) {
+                for (const family of ['chat', 'work']) {
+                    const fstate = this.runner.states?.[family];
+                    if (!fstate)
+                        continue;
+                    // 收集本族所有记录(反刍后全部未整合)
+                    const records = this.stores.l1.list({ family, limit: 500, offset: 0 }).items;
+                    if (records.length === 0)
+                        continue;
+                    try {
+                        const t = Date.now();
+                        await runSceneConsolidation(this.ctx, this.cfg, this.stores.scenes[family], records, this.logger, family);
+                        if (fstate) {
+                            fstate.newMemoriesSinceL2 = 0;
+                            fstate.lastL2At = Date.now();
+                        }
+                        this.logger.info(`[memory] 反刍 L2 完成(family=${family},${Date.now() - t}ms,${records.length} 条记录)`);
+                    }
+                    catch (err) {
+                        this.logger.warn(`[memory] 反刍 L2 失败(family=${family}): ${errDetail(err)}`);
+                    }
+                }
+            }
+            // 强制 L3:画像更新
+            if (this.cfg.l3.enabled && distillOn) {
+                this.status.phase = 'updating';
+                this.status.detail = 'L3 画像更新';
+                for (const family of ['chat', 'work']) {
+                    try {
+                        const scenes = await this.stores.scenes[family].list();
+                        if (scenes.length === 0)
+                            continue;
+                        const fstate = this.runner.states?.[family];
+                        await runPersona(this.ctx, this.cfg, this.stores.scenes[family], this.stores.persona[family], fstate || undefined, this.logger, family);
+                        this.logger.info(`[memory] 反刍 L3 完成(family=${family})`);
+                    }
+                    catch (err) {
+                        this.logger.warn(`[memory] 反刍 L3 失败(family=${family}): ${errDetail(err)}`);
+                    }
+                }
+            }
+            this.status.phase = 'done';
+            this.finish(null);
+        }
+        catch (err) {
+            this.finish(`收尾失败: ${errDetail(err)}`);
+        }
+    }
+    /**
+     * 轻量刷新:没有 pending 时仅跑一轮 L2/L3。
+     *
+     * 为什么必须先置 running/phase:此处每次 runSceneConsolidation/runPersona 都是**真实 LLM 调用**
+     * (实测单次可达 70s+),而本方法是 `await` 的、期间 `start()` 一直挂着并占住守卫。
+     * 原先不置 running,导致刷新期间界面既无进度也无取消按钮,再点一次只得到"反刍已在进行中"
+     * 却看不到任何进展——即用户反馈的"管线进度和状态提示仍然欠缺"。
+     * 现在:先把步骤数登记为 total、每完成一步自增 done,并给出当前动作描述(detail)。
+     */
+    async doLightRefresh() {
+        const liveNow = this.live.get();
+        const distillOn = liveNow.enabled && liveNow.distill;
+        // 先算出待执行步骤(每族 L2/L3 各算一步),据此给界面一个真实进度
+        const l2Targets = [];
+        if (this.cfg.l2.enabled && distillOn) {
+            for (const family of ['chat', 'work']) {
+                const fstate = this.runner.states?.[family];
+                if (!fstate || fstate.newMemoriesSinceL2 <= 0)
+                    continue;
+                const records = this.stores.l1.list({ family, limit: 200, offset: 0 }).items;
+                if (records.length === 0)
+                    continue;
+                l2Targets.push(family);
+            }
+        }
+        const l3Targets = [];
+        if (this.cfg.l3.enabled && distillOn) {
+            for (const family of ['chat', 'work']) {
+                if (!this.runner.states?.[family])
+                    continue;
+                l3Targets.push(family);
+            }
+        }
+        this.cancelRequested = false;
+        this.status = {
+            ...IDLE_STATUS,
+            running: true,
+            phase: 'refreshing',
+            done: 0,
+            total: l2Targets.length + l3Targets.length,
+            detail: '准备轻量刷新(无未蒸馏缓冲)',
+            startedAt: Date.now(),
+        };
+        this.logger.info(`[memory] 反刍轻量刷新开始(pending 无切片):L2 ${l2Targets.length} 族 / L3 ${l3Targets.length} 族`);
+        if (l2Targets.length > 0)
+            this.status.phase = 'consolidating';
+        for (const family of l2Targets) {
+            if (this.cancelRequested)
+                break;
+            this.status.detail = `L2 场景整合(${family})`;
+            const fstate = this.runner.states?.[family];
+            const records = this.stores.l1.list({ family, limit: 200, offset: 0 }).items;
+            try {
+                await runSceneConsolidation(this.ctx, this.cfg, this.stores.scenes[family], records, this.logger, family);
+                // 仅成功后归零:失败时保留计数,留给下一次触发重试(原先先归零会静默吞掉失败)
+                if (fstate) {
+                    fstate.newMemoriesSinceL2 = 0;
+                    fstate.lastL2At = Date.now();
+                }
+            }
+            catch (err) {
+                this.logger.warn(`[memory] 反刍轻量刷新 L2 失败(family=${family}): ${errDetail(err)}`);
+            }
+            this.status.done++;
+        }
+        if (l3Targets.length > 0)
+            this.status.phase = 'updating';
+        for (const family of l3Targets) {
+            if (this.cancelRequested)
+                break;
+            this.status.detail = `L3 画像更新(${family})`;
+            const fstate = this.runner.states?.[family];
+            try {
+                await runPersona(this.ctx, this.cfg, this.stores.scenes[family], this.stores.persona[family], fstate, this.logger, family);
+            }
+            catch (err) {
+                this.logger.warn(`[memory] 反刍轻量刷新 L3 失败(family=${family}): ${errDetail(err)}`);
+            }
+            this.status.done++;
+        }
+        this.status.running = false;
+        this.status.detail = null;
+        this.status.phase = this.cancelRequested ? 'cancelled' : 'done';
+        this.status.finishedAt = Date.now();
+        const cost = this.status.finishedAt - (this.status.startedAt ?? this.status.finishedAt);
+        this.logger.info(`[memory] 反刍轻量刷新结束(${this.status.phase}):${this.status.done}/${this.status.total} 步,耗时 ${Math.round(cost / 1000)}s`);
+        return this.getStatus();
+    }
+    finish(error) {
+        this.status.running = false;
+        this.status.detail = null;
+        this.status.phase = this.cancelRequested ? 'cancelled' : 'done';
+        this.status.error = error;
+        this.status.finishedAt = Date.now();
+        this.status.recordsBuilt = this.totalL1;
+        const cost = this.status.finishedAt - (this.status.startedAt ?? this.status.finishedAt);
+        this.logger.info(`[memory] 反刍结束(${this.status.phase}):${this.status.done}/${this.status.total} 会话,产出 ${this.totalL1} 条记录,耗时 ${Math.round(cost / 1000)}s`);
+    }
+}

package/dist/pipeline/runner.d.ts

@@ -0,0 +1,167 @@
+/**
+ * 管线 Runner:串行执行 L0 → L1 → L2 → L3。
+ * 所有阶段失败只记日志,绝不向 Agent 循环抛错(失败兜底)。
+ *
+ * 会话档位:enqueue 带 mode(off 在捕获侧已被拦截);L1 待重试缓冲按档分桶;
+ * L2/L3 按记录族各自跑各自的场景/画像存储与阈值计数(分族隔离不变量)。
+ *
+ * 调度:内部是带优先级的任务列表——正常对话轮次(live)优先于重建分块(rebuild),
+ * 重建期间用户照常聊天,新轮次的蒸馏最多等一个重建块。任务串行,同一时刻至多一个在跑。
+ *
+ * 未蒸馏缓冲:pending 三桶持久化在 pending.json,进程重启不丢;init 恢复后延迟补跑一次
+ * (受 live 开关与 minMessages 阈值约束,失败维持"等下一轮同档对话"的现状语义)。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type MemoryConfig } from '../config.js';
+import type { LiveSettingsHandle } from '../settings.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 { StateStore } from '../store/state.js';
+import type { ConversationMessage, ExtractMode, MemoryFamily, MemoryLogger } from '../types.js';
+import type { FamilyStates } from './l1.js';
+export interface MemoryStores {
+    l0: L0Store;
+    l1: L1Store;
+    scenes: Record<MemoryFamily, SceneStore>;
+    persona: Record<MemoryFamily, PersonaStore>;
+    state: StateStore;
+    /** 图谱存储(可选:测试缝/未装配时图谱泵整体停用;GraphStore 自带降级 no-op)。 */
+    graph?: GraphStore;
+}
+/** 管线任务(优先级调度:live > graph > rebuild)。 */
+export interface PipelineTask {
+    kind: 'live' | 'rebuild' | 'graph';
+    run: () => Promise<unknown>;
+    /** 任务跑完后的回调(携带 run 的产出)——供反刍统计真实产出记录数。 */
+    onDone?: (result: unknown) => void;
+}
+/**
+ * 选取下一个要执行的任务下标:最早的 live 优先,其次 graph(图谱投影单批短、
+ * 让位用户轮次但优先于重建分块),否则队首。
+ */
+export declare function pickNextTaskIndex(tasks: PipelineTask[]): number;
+/**
+ * 运行时调参视图:设置页运行时链(distillChain)与旧单路由/档位键、分层输出预算、
+ * 蒸馏通道覆盖、远程嵌入覆盖可临时覆盖静态 config。浅拷贝只覆盖 llm/embedding
+ * 相关键,其余键与原 cfg 共享只读引用;pipeline 全链继续收 cfg,无需感知。
+ *
+ * 优先级表(自上而下):
+ * - 蒸馏模型:部署静态 pin(provider+model 双字段齐)> 运行时统一链 distillChain
+ *   [0]> 旧单路由键(distillProvider+distillModel 成对)> agentDefaultModel;
+ *   pinned 时链与旧键一并失效(部署锁定路由)。
+ * - 思考档位:有 settings 服务时运行时值整体接管('' = 自动);链模式主路由档位走
+ *   primaryEffort;非链模式旧键对静态回退条目盖章接管(存量兼容)。
+ * - 输出预算/输入预算/通道覆盖/远程嵌入覆盖:非零/非空运行时值直接注入对应子树。
+ */
+export declare function effectiveCfg(cfg: MemoryConfig, live?: LiveSettingsHandle): MemoryConfig;
+export declare class MemoryRunner {
+    private readonly ctx;
+    private readonly cfg;
+    private readonly stores;
+    private readonly logger;
+    private readonly live;
+    /** 会话档位只读句柄(闲置扫描跳过 off 档会话;挂起语义)。 */
+    private readonly modes?;
+    private tasks;
+    private draining;
+    /** 停止标志(dispose 序置位):不再取新任务;进行中任务自然收尾。 */
+    private stopped;
+    private pending;
+    /** 各档位桶渐进阈值(1 起步翻倍至稳态毕业;随 pending.json 持久化)。 */
+    private warmup;
+    /** 每会话最后活动时间(闲置兜底判定用)。 */
+    private lastActivity;
+    /** 每会话累计产出 L1 条数与最近蒸馏时间(session-stats 数据源;LRU 上限防泄漏)。 */
+    private sessionProduced;
+    /** 抽取连续失败退避(瞬态,不持久化:重启后允许首试再退避)。 */
+    private extractFailures;
+    /** 图谱泵在队列中的占位标志(同一时刻至多一个 graph 任务;护栏四件套之一)。 */
+    private graphPumpQueued;
+    private readonly pendingFile;
+    /** 分族 checkpoint(init 后可用;重建收尾也从这里读活引用)。 */
+    states: FamilyStates;
+    private afterRun;
+    constructor(ctx: Context, cfg: MemoryConfig, stores: MemoryStores, logger: MemoryLogger, live: LiveSettingsHandle, 
+    /** 会话档位只读句柄(闲置扫描跳过 off 档会话;挂起语义)。 */
+    modes?: {
+        get(sessionId: string): string;
+    } | undefined);
+    init(): Promise<void>;
+    /** 启动补跑:对每个非空桶的每个会话切片入队一次蒸馏尝试(受 live 开关与
+     *  生效阈值约束;不足阈值的消息等用户继续或闲置兜底,失败不无限重试)。 */
+    private scheduleStartupRetry;
+    /** L1 抽取待重试的消息条数(状态面板用)。 */
+    get pendingCount(): number;
+    /**
+     * 会话级蒸馏视图(session-stats 端点数据源;纯内存读,零 I/O)。
+     * pendingSlice = 当前档位桶中该会话的攒批切片条数(threshold 为生效阈值,含 warmup 爬坡);
+     * parkedSlices = 其余档位桶中的残留切片(换档遗留 / off 档挂起)。
+     */
+    sessionView(sessionId: string, mode: string): {
+        pendingSlice: number;
+        parkedSlices: number;
+        threshold: number | null;
+        producedRecords: number;
+        lastDistillAt: number | null;
+    };
+    /** 会话产出记账(切片成功消费时调用;LRU 淘汰最久未蒸馏会话防 Map 无界增长)。 */
+    private noteSessionDistill;
+    /** 管线跑完一轮后的回调(用于召回缓存失效)。 */
+    setAfterRun(fn: () => void): void;
+    /** 一轮对话结束后入队(L0 落盘由 capture 在 turn/end 即时完成,不排蒸馏队列)。
+     *  onTurnDone 在该任务真正跑完后回调,携带本轮新增记录数(供反刍统计真实产出)。 */
+    enqueue(sessionId: string, messages: ConversationMessage[], mode: ExtractMode, opts?: {
+        force?: boolean;
+        onTurnDone?: (records: number) => void;
+    }): void;
+    /** 重建任务入队(低优先级:让位于正常轮次;由 RebuildController 分块驱动)。 */
+    enqueueRebuildTask(run: () => Promise<unknown>): void;
+    /** 重建蒸馏轮:统一 auto 档,全量强制蒸馏(不受阈值约束)、不受缓冲 200 上限。 */
+    runRebuildTurn(sessionId: string, messages: ConversationMessage[]): Promise<number>;
+    /** 停止取新任务(插件 dispose 序调用;进行中任务照常跑完但不 await)。 */
+    stop(): void;
+    /** 启动闲置兜底定时器(index.ts 装配;idleSeconds=0 关闭)。 */
+    startIdleTimer(): void;
+    /** 闲置扫描:静默达标且有切片的会话按捕获档位落袋(off 档会话挂起跳过)。 */
+    private flushIdleSlices;
+    /** 把某会话在各桶中的切片按捕获档位逐个入队强制蒸馏(闲置兜底 / 档位切换共用)。 */
+    private enqueueSessionSlices;
+    /**
+     * 档位切换同步(session-modes 的 set() 回调,ADR-0003):
+     * 非 off 间切换 → 该会话切片立即按捕获档位蒸馏(新档位从空切片起步);
+     * 切到 off → 挂起(切片留存,闲置扫描跳过);从 off 切回 → 挂起片按捕获档位落袋。
+     */
+    onModeChange(sessionId: string, oldMode: string, newMode: string): void;
+    private pushTask;
+    /**
+     * 图谱泵任务入队(护栏四件套,见 maybeQueueGraphTask;成功投影后有积压则续排,
+     * 每轮 drain 至多消费一个 graph 任务且永远让位 live)。
+     */
+    startGraphBackfillTimer(): void;
+    /**
+     * 图谱投影泵入队判定:
+     * - 双门:部署级 cfg.graph.enabled + 运行时 live.enabled/distill,任一为假不入队;
+     * - 占位:同一时刻至多一个 graph 任务在队列(靠 graphPumpQueued 标志),永不与
+     *   live 抢位(pickNextTaskIndex 保证 live > graph);
+     * - 退避/attempts 封顶:由 GraphStore.claimNext 的 WHERE 过滤与 fail 转 dead 承接,
+     *   退避窗口内的 claim 是廉价空转,不在此重复实现。
+     */
+    private maybeQueueGraphTask;
+    private drain;
+    /** 该会话是否处于抽取退避窗口内。 */
+    private inExtractBackoff;
+    /** 缓冲落盘(每次蒸馏尝试后调用;失败只告警不阻断管线)。
+     *  非重建轮持久化前按桶截断到上限:重建取消后的大桶不至于在后续每次
+     *  蒸馏尝试时反复整量序列化落盘(多 MB 级 IO);重建轮豁免维持。 */
+    private persistPending;
+    private runTurn;
+    /**
+     * 抽取并消费一个会话切片:成功才把切片移出桶并推进爬坡阈值;失败保留切片待重试。
+     * 调用方已保证切片达到生效阈值(或 force)。背景参考按会话从 L0 现查并剔除切片
+     * 自身(ADR-0003:会话间互不污染、重启不丢背景)。
+     */
+    private extractSessionSlice;
+}