dsh-prime-memory 0.11.0

package/dist/stats.js

@@ -0,0 +1,929 @@
+/**
+ * 状态面板数据通道:Host 侧注册 /rpc 通道的 dsh-memory/* 端点,
+ * Client 设置页通过 ctx.connection.rpc.call('/rpc', 'dsh-memory/xxx') 拉取。
+ *
+ * connection 是可选服务且可能晚于本插件就绪:先探测一次,未就绪则监听
+ * internal/service(事件携带 (name, impl),impl=undefined 即下线),服务
+ * 上线、下线、替换实例三种迁移都会正确释放/重挂 RPC 注册。
+ *
+ * 机密纪律:directApiKey / embedRemoteApiKey 永不出现在任何 RPC 响应与日志
+ * (settings-get/set 走 sanitizeSettings 脱敏)。
+ */
+import { createRequire } from 'node:module';
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { EFFORT_CHOICES, resolveDataDir } from './config.js';
+import { effectiveCfg } from './pipeline/runner.js';
+import { emptyRecallStats } from './hooks/recall.js';
+import { buildRouteChain, decideSendableEffort, LAYER_DEFAULT_BUDGETS, layerChainOrNull, resolveModelContextWindow, resolveModelEfforts, resolveModelRoute } from './llm.js';
+import { projectDistillChain, validateDistillChain } from './settings.js';
+import { errDetail } from './util/filelog.js';
+import { snapshotTokenCost } from './token-cost.js';
+const require = createRequire(import.meta.url);
+export const PLUGIN_VERSION = require('../package.json').version;
+/**
+ * 组装端点 deps。抽成函数是为了让"哪个控制器落入哪个字段"成为可测接缝:
+ * 反刍端点读 deps.ruminate,若此处漏注入,端点会静默恒返 {supported:false}(面板整块不渲染)。
+ * @param controller - 反刍控制器;由 index.ts 在存储可用时装配,降级时为 undefined。
+ */
+export function buildEndpointDeps(base, sources, controller) {
+    const injected = {
+        status: sources.status,
+        live: sources.live,
+        modes: sources.modes,
+        dataDir: sources.dataDir ?? resolveDataDir(base.cfg),
+        rebuild: sources.rebuild,
+        embedManager: sources.embedManager,
+        sessionInfo: sources.sessionInfo,
+        ruminate: controller,
+    };
+    return { ...base, ...injected };
+}
+export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes, dataDir, rebuild, embedManager, sessionInfo, 
+/** 反刍控制器(存储降级时为 undefined):经 buildEndpointDeps 落入 deps.ruminate。 */
+ruminate) {
+    /** 当前是否持有一段有效注册(dispose 完成后清空,允许服务重上线时重注册)。 */
+    let holding = false;
+    /** 当前 handle 绑定的 connection 实例(internal/service 第二参;用于识别实例替换)。 */
+    let registeredImpl;
+    const tryRegister = () => {
+        if (holding)
+            return;
+        const connection = ctx.get('connection');
+        if (!connection)
+            return;
+        holding = true;
+        let active = true;
+        // handle() 同步注册并返回异步 disposer(() => Promise<void>)。
+        const dispose = connection.rpc.handle('/rpc', async (endpoint, payload) => {
+            try {
+                const value = await handleEndpoint(endpoint, payload, buildEndpointDeps({ ctx, cfg, stores, logger }, { status, live, modes, dataDir, rebuild, embedManager, sessionInfo }, ruminate));
+                return { ok: true, value };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    error: { code: 'internal', message: err instanceof Error ? err.message : String(err), details: {} },
+                };
+            }
+        }, { authority: 'loopback' });
+        registeredImpl = connection;
+        if (!active) {
+            void dispose();
+            return;
+        }
+        logger.debug?.('[memory] 状态 RPC 已注册(/rpc → dsh-memory/*)');
+        disposers.push(() => {
+            active = false;
+            holding = false;
+            void dispose();
+        });
+    };
+    /** 释放全部持有注册(handle 随旧服务实例失效,holding 复位以允许重挂)。 */
+    const release = () => {
+        for (const dispose of disposers.splice(0))
+            dispose();
+    };
+    const disposers = [];
+    ctx.effect(() => {
+        tryRegister();
+        const off = ctx.on('internal/service', (name, impl) => {
+            if (name !== 'connection')
+                return;
+            if (!impl) {
+                // 服务下线:旧 handle 已随旧服务实例失效——主动释放并复位,
+                // 服务恢复时本事件再触发即可重挂(否则 holding 恒真 → RPC 永久失联)
+                release();
+                registeredImpl = undefined;
+                logger.debug?.('[memory] connection 服务下线,RPC 注册已释放(待恢复重挂)');
+                return;
+            }
+            if (impl !== registeredImpl) {
+                // 实例替换:旧 handle 失效,换新实例重挂
+                release();
+                registeredImpl = undefined;
+            }
+            tryRegister();
+        });
+        return () => {
+            off();
+            release();
+        };
+    });
+}
+async function buildStats(cfg, stores, status) {
+    // 两族 checkpoint 聚合(浏览器混合视图:总量求和、时间取最新)
+    const chat = stores.state.forFamily('chat');
+    const work = stores.state.forFamily('work');
+    const [chatScenes, workScenes, chatPersona, workPersona] = await Promise.all([
+        stores.scenes.chat.list(),
+        stores.scenes.work.list(),
+        stores.persona.chat.read(),
+        stores.persona.work.read(),
+    ]);
+    const degraded = status?.degraded() ?? false;
+    const personaChars = (chatPersona?.length ?? 0) + (workPersona?.length ?? 0);
+    const max = (a, b) => Math.max(a, b);
+    const iso = (t) => (t ? new Date(t).toISOString() : null);
+    return {
+        ok: true,
+        dataDir: resolveDataDir(cfg),
+        family: cfg.family,
+        version: PLUGIN_VERSION,
+        l0Today: await stores.l0.countToday(),
+        l1Count: stores.l1.size,
+        l1TotalExtracted: chat.totalExtracted + work.totalExtracted,
+        sceneCount: chatScenes.length + workScenes.length,
+        personaChars,
+        hasPersona: chat.hasPersona || work.hasPersona,
+        lastExtractAt: iso(max(chat.lastExtractAt, work.lastExtractAt)),
+        lastL2At: iso(max(chat.lastL2At, work.lastL2At)),
+        lastL3At: iso(max(chat.lastL3At, work.lastL3At)),
+        memoriesSinceL2: chat.newMemoriesSinceL2 + work.newMemoriesSinceL2,
+        memoriesSinceL3: chat.memoriesSinceL3 + work.memoriesSinceL3,
+        pendingExtract: status?.pending() ?? 0,
+        message: degraded ? 'degraded:存储不可用,记忆功能已停用' : 'running',
+        thresholds: { l2MinNewMemories: cfg.l2.minNewMemories, l3Interval: cfg.l3.interval },
+    };
+}
+/** RPC 字符串入参上限校验:防 loopback 面畸形超长载荷
+ *  (超长 sessionId 持久化进 session-modes.json / 超长 query 触发 jieba 全量分词 CPU 峰值)。 */
+function expectSessionId(v) {
+    if (typeof v !== 'string' || !v)
+        throw new Error('sessionId 缺失');
+    if (v.length > 512)
+        throw new Error('sessionId 过长(≤512 字符)');
+    return v;
+}
+/** 机密脱敏:两个 API key(直连蒸馏/远程嵌入)明文永不出宿主。 */
+function sanitizeSettings(s) {
+    if (!s.directApiKey && !s.embedRemoteApiKey)
+        return s;
+    return { ...s, directApiKey: '', embedRemoteApiKey: '' };
+}
+/** 端点分发表(导出供测试直调:可精确注入 rebuild/ruminate 等可选控制器,验证 deps 接线)。 */
+export async function handleEndpoint(endpoint, payload, deps) {
+    const { cfg, stores, status, live, modes, dataDir, rebuild, ruminate, embedManager, sessionInfo } = deps;
+    switch (endpoint) {
+        case 'dsh-memory/stats':
+            return buildStats(cfg, stores, status);
+        case 'dsh-memory/token-cost': {
+            const p = (payload ?? {});
+            const granularity = p.granularity === 'week' || p.granularity === 'month' ? p.granularity : 'day';
+            // rangeDays 须为正整数且不超过明细保留期(tokenCost.retentionDays,0=永久保留则放行 1~3650),否则回退默认窗口
+            const retention = cfg.tokenCost.retentionDays;
+            const upper = retention > 0 ? retention : 3650;
+            const rawDays = p.rangeDays;
+            const rangeDays = typeof rawDays === 'number' && Number.isInteger(rawDays) && rawDays > 0 && rawDays <= upper ? rawDays : 0;
+            return snapshotTokenCost(granularity, rangeDays);
+        }
+        case 'dsh-memory/session-mode-get': {
+            if (!modes)
+                throw new Error('档位存储未初始化');
+            const p = (payload ?? {});
+            const sessionId = expectSessionId(p.sessionId);
+            // 注入解析权威在 host:recall 是原始覆盖(null=跟随全局),recallResolved 是生效值
+            const s = live?.get();
+            const globalRecall = s?.recall ?? true;
+            const v = {
+                sessionId,
+                mode: modes.get(sessionId),
+                defaultMode: modes.default,
+                recall: modes.getRecall(sessionId) ?? null,
+                recallResolved: modes.resolvedRecall(sessionId, globalRecall),
+            };
+            return v;
+        }
+        case 'dsh-memory/session-mode-set': {
+            if (!modes)
+                throw new Error('档位存储未初始化');
+            const p = (payload ?? {});
+            const sessionId = expectSessionId(p.sessionId);
+            const allowed = ['auto', 'chat', 'work', 'off'];
+            if (typeof p.mode !== 'string' || !allowed.includes(p.mode)) {
+                throw new Error(`非法档位: ${String(p.mode)}(允许 ${allowed.join('/')})`);
+            }
+            // 注入覆盖可选同车:布尔 = 设置覆盖;显式 null = 清除覆盖(跟随全局);
+            // 缺省(undefined)= 仅切档、覆盖保持不动(旧 client 永不传 recall,行为不变)。
+            // 校验前置:非法 recall 在任何写穿发生前拒绝(不做部分提交)
+            if (p.recall !== undefined && typeof p.recall !== 'boolean' && p.recall !== null) {
+                throw new Error(`非法注入覆盖: ${String(p.recall)}(允许 true/false/null)`);
+            }
+            modes.set(sessionId, p.mode);
+            if (typeof p.recall === 'boolean') {
+                modes.setRecall(sessionId, p.recall);
+            }
+            else if (p.recall === null) {
+                modes.setRecall(sessionId, undefined);
+            }
+            deps.logger.info(`[memory] 会话档位设置 session=${sessionId} mode=${p.mode} recall=${JSON.stringify(modes.getRecall(sessionId) ?? null)}`);
+            const s = live?.get();
+            const v = {
+                sessionId,
+                mode: p.mode,
+                recall: modes.getRecall(sessionId) ?? null,
+                recallResolved: modes.resolvedRecall(sessionId, s?.recall ?? true),
+            };
+            return v;
+        }
+        // ── 会话级统计(悬浮卡信息区;热路径端点,见 SessionInfoSource 的零 I/O 硬规则) ──
+        case 'dsh-memory/session-stats': {
+            if (!sessionInfo)
+                return { supported: false };
+            const p = (payload ?? {});
+            const sessionId = expectSessionId(p.sessionId);
+            const mode = modes ? modes.get(sessionId) : 'auto';
+            const caps = sessionInfo.capabilities();
+            const l0Count = await sessionInfo.l0Count(sessionId);
+            const s = live?.get();
+            // 注入生效四因子短路序:部署上限 → 全局开关 → 会话覆盖 → 档位;
+            // disabled 时 reason 带第一个为假因子(悬浮卡停用文案的数据源)
+            const globalRecall = s?.recall ?? true;
+            const sessionRecall = modes ? modes.resolvedRecall(sessionId, globalRecall) : true;
+            let recallReason;
+            if (!cfg.recall.enabled)
+                recallReason = 'deploy';
+            else if (!globalRecall)
+                recallReason = 'global';
+            else if (!sessionRecall)
+                recallReason = 'session';
+            else if (mode === 'off')
+                recallReason = 'mode';
+            const recallOn = recallReason === undefined;
+            const view = sessionInfo.runnerView(sessionId, mode);
+            // lastDistillAt 统一转 ISO(与 global.lastExtractAt 口径一致,client 直接 fmtAgo)
+            const distillView = { ...view, lastDistillAt: view.lastDistillAt ? new Date(view.lastDistillAt).toISOString() : null };
+            const chat = stores.state.forFamily('chat');
+            const work = stores.state.forFamily('work');
+            const lastAt = Math.max(chat.lastExtractAt, work.lastExtractAt);
+            // 主对话模型的官方声明窗口(占用指示器分母;advisory 查询读本地快照且有缓存,
+            // 轮询热路径下稳态为 Map 命中。race 封顶防第三方适配器 resolveModelInfo 挂起拖死轮询)
+            let contextWindowTokens = null;
+            try {
+                const sel = deps.ctx.get('agentDefaultModel')?.currentSelection?.();
+                if (sel?.provider && sel?.model) {
+                    contextWindowTokens = await Promise.race([
+                        resolveModelContextWindow(deps.ctx, sel.provider, sel.model),
+                        new Promise((resolve) => setTimeout(() => resolve(null), 3_000)),
+                    ]);
+                }
+            }
+            catch {
+                /* 可选服务缺失/解析失败 = 分母未知,UI 降级 */
+            }
+            const v = {
+                supported: true,
+                sessionId,
+                mode,
+                defaultMode: modes?.default ?? cfg.family,
+                recall: {
+                    enabled: recallOn,
+                    ...(recallReason ? { reason: recallReason } : {}),
+                    ...(sessionInfo.recallStats(sessionId) ?? emptyRecallStats()),
+                },
+                memoryOccupancy: sessionInfo.memoryOccupancy(sessionId),
+                occupancyBackfill: sessionInfo.profileEstimate
+                    ? {
+                        recallTokens: sessionInfo.recallEstimate ? await sessionInfo.recallEstimate(sessionId) : null,
+                        profileTokens: sessionInfo.profileEstimate(sessionId),
+                    }
+                    : null,
+                contextWindowTokens,
+                distill: distillView,
+                l0Count,
+                retrieval: caps.vectorSearch ? (caps.ftsSearch ? 'hybrid' : 'vector') : caps.ftsSearch ? 'keyword' : 'none',
+                global: {
+                    degraded: status?.degraded() ?? false,
+                    pendingTotal: status?.pending() ?? 0,
+                    lastExtractAt: lastAt ? new Date(lastAt).toISOString() : null,
+                },
+            };
+            return v;
+        }
+        case 'dsh-memory/settings-get': {
+            const s = live?.get();
+            const budgets = s?.distillBudgets ?? { extract: 0, dedup: 0, l2: 0, l3: 0, graph: 0 };
+            // 蒸馏思考档位:current 是运行时值('' = 自动);effective 是能力探询后实际发送值
+            // ('' = 不传,跟随模型默认);options 是当前生效模型声明的档位表(空声明 → 只显示
+            // high,用户规则:无声明默认 high),fallback 是静态部署值。
+            let effortEffective = s?.reasoningEffort || cfg.llm.reasoningEffort;
+            let effortOptions = ['high'];
+            let effortRoute = null;
+            try {
+                const ecfg = effectiveCfg(cfg, live);
+                effortRoute = await resolveModelRoute(deps.ctx, ecfg);
+                const cap = await resolveModelEfforts(deps.ctx, effortRoute.provider, effortRoute.model);
+                if (cap) {
+                    effortEffective = decideSendableEffort(cap, ecfg.llm.reasoningEffort).effort;
+                    if (cap.efforts.length > 0)
+                        effortOptions = cap.efforts;
+                }
+            }
+            catch {
+                /* 路由解析/探询失败保持占位(effective 用运行时||静态值) */
+            }
+            const resp = {
+                supported: live?.supported ?? false,
+                settings: sanitizeSettings(s ?? {
+                    enabled: true, capture: true, distill: true, recall: true,
+                    reasoningEffort: '', distillProvider: '', distillModel: '', distillChain: [],
+                    distillBudgets: { extract: 0, dedup: 0, l2: 0, l3: 0, graph: 0 }, distillMaxInputChars: 0,
+                    distillLayerChains: { l1: [], l2: [], l3: [] },
+                    distillMode: '', directBaseURL: '', directApiKey: '',
+                    embedRemoteBaseURL: '', embedRemoteApiKey: '', embedRemoteModel: '', embedRemoteDimensions: 0,
+                    memoryMutate: false,
+                }),
+                // 静态部署上限(cordis.patch.yml):运行时开关与它取 AND
+                ceilings: { capture: cfg.capture.enabled, distill: cfg.extract.enabled, recall: cfg.recall.enabled },
+                effort: {
+                    current: s?.reasoningEffort ?? '',
+                    // 静态 schema 与 settings-set 写入门都以 EFFORT_CHOICES 白名单校验,这里断言回窄类型
+                    effective: effortEffective,
+                    fallback: cfg.llm.reasoningEffort,
+                    options: effortOptions,
+                    ...(effortRoute ? { route: effortRoute } : {}),
+                },
+                // 分层输出预算:current 是运行时覆盖(0 = 跟随默认),defaults 是内置默认(UI 占位/提示用)
+                budgets: {
+                    current: budgets,
+                    defaults: { ...LAYER_DEFAULT_BUDGETS },
+                    effective: {
+                        extract: budgets.extract > 0 ? budgets.extract : LAYER_DEFAULT_BUDGETS.extract,
+                        dedup: budgets.dedup > 0 ? budgets.dedup : LAYER_DEFAULT_BUDGETS.dedup,
+                        l2: budgets.l2 > 0 ? budgets.l2 : LAYER_DEFAULT_BUDGETS.l2,
+                        l3: budgets.l3 > 0 ? budgets.l3 : LAYER_DEFAULT_BUDGETS.l3,
+                        graph: budgets.graph > 0 ? budgets.graph : LAYER_DEFAULT_BUDGETS.graph,
+                    },
+                },
+                // 输入预算(字符):current 是运行时覆盖(0 = 跟随配置),fallback 是静态配置值
+                inputBudget: {
+                    current: s?.distillMaxInputChars ?? 0,
+                    fallback: cfg.llm.maxInputChars,
+                    effective: s && s.distillMaxInputChars > 0 ? s.distillMaxInputChars : cfg.llm.maxInputChars,
+                },
+            };
+            return resp;
+        }
+        case 'dsh-memory/settings-set': {
+            if (!live)
+                throw new Error('开关通道未初始化');
+            const patch = (payload ?? {});
+            const clean = {};
+            // 布尔开关组:memoryMutate(高权限写删门)与主开关同列
+            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate']) {
+                if (typeof patch[key] === 'boolean')
+                    clean[key] = patch[key];
+            }
+            // 运行时统一路由链:结构校验后整体写入(空数组 = 回到跟随部署配置)
+            if (patch.distillChain !== undefined) {
+                const err = validateDistillChain(patch.distillChain);
+                if (err)
+                    throw new Error(err);
+                clean.distillChain = patch.distillChain;
+            }
+            // 运行时按层路由链:逐层校验(头行必须显式——层覆盖不支持跟随默认模型);
+            // patch 语义只带要改的层,写入侧与存量层合并后落盘(空数组 = 该层回到跟随)
+            if (patch.distillLayerChains !== undefined) {
+                const rawLC = (patch.distillLayerChains ?? {});
+                const prev = (live.get().distillLayerChains ?? {});
+                const merged = {
+                    l1: prev.l1 ?? [],
+                    l2: prev.l2 ?? [],
+                    l3: prev.l3 ?? [],
+                };
+                for (const key of ['l1', 'l2', 'l3']) {
+                    if (rawLC[key] === undefined)
+                        continue;
+                    const err = validateDistillChain(rawLC[key], { requireExplicitHead: true });
+                    if (err)
+                        throw new Error(`层路由 ${key}:${err}`);
+                    merged[key] = rawLC[key];
+                }
+                clean.distillLayerChains = merged;
+            }
+            if (patch.reasoningEffort !== undefined) {
+                const v = String(patch.reasoningEffort);
+                // 白名单与 schema/settings 同源(config.ts EFFORT_CHOICES)
+                if (!EFFORT_CHOICES.includes(v)) {
+                    throw new Error(`非法思考档位: ${v}(允许 '' 或 ${EFFORT_CHOICES.filter((x) => x !== '').join('/')})`);
+                }
+                clean.reasoningEffort = v;
+            }
+            // 蒸馏模型运行时覆盖:供应商/模型 id 原样接受(不在此校验存在性——
+            // 供应商可被用户随后删除,解析侧按存在性回退并提示)
+            for (const key of ['distillProvider', 'distillModel']) {
+                if (patch[key] !== undefined) {
+                    const v = String(patch[key]);
+                    if (v.length > 200)
+                        throw new Error(`${key} 过长(≤200 字符)`);
+                    clean[key] = v;
+                }
+            }
+            // 分层输出预算:五键一起校验,非负整数 ≤ 100 万;0 = 跟随内置默认
+            // (键表与 DistillBudgetLayer 同步——漏白名单键 = 静默丢预算,C 节坑①)
+            if (patch.distillBudgets !== undefined) {
+                const raw = (patch.distillBudgets ?? {});
+                const budgets = {};
+                for (const key of ['extract', 'dedup', 'l2', 'l3', 'graph']) {
+                    const n = Number(raw[key] ?? 0);
+                    if (!Number.isInteger(n) || n < 0 || n > 1_000_000) {
+                        throw new Error(`distillBudgets.${key} 须为 0~1000000 的整数(0 = 跟随默认)`);
+                    }
+                    budgets[key] = n;
+                }
+                clean.distillBudgets = budgets;
+            }
+            // 输入预算(字符):0 = 跟随静态配置;正值须落在静态 schema 同款范围(1000~100 万)
+            if (patch.distillMaxInputChars !== undefined) {
+                const n = Number(patch.distillMaxInputChars);
+                if (!Number.isInteger(n) || n < 0 || n > 1_000_000 || (n > 0 && n < 1000)) {
+                    throw new Error('distillMaxInputChars 须为 0 或 1000~1000000 的整数(0 = 跟随配置)');
+                }
+                clean.distillMaxInputChars = n;
+            }
+            // 蒸馏通道运行时覆盖(direct 解耦):mode 白名单;endpoint 可回显;apiKey 属机密——
+            // 写入后存 settings,但不回读到 UI、不落本条日志(下方日志先剔除后记录)
+            if (patch.distillMode !== undefined) {
+                const m = String(patch.distillMode);
+                if (m !== '' && m !== 'host' && m !== 'direct') {
+                    throw new Error("distillMode 须为 '' | 'host' | 'direct'('' = 跟随部署配置)");
+                }
+                clean.distillMode = m;
+            }
+            if (patch.directBaseURL !== undefined) {
+                const base = String(patch.directBaseURL);
+                if (base.length > 2000)
+                    throw new Error('directBaseURL 过长(≤2000 字符)');
+                clean.directBaseURL = base;
+            }
+            if (patch.directApiKey !== undefined) {
+                const key = String(patch.directApiKey);
+                if (key.length > 2000)
+                    throw new Error('directApiKey 过长(≤2000 字符)');
+                clean.directApiKey = key;
+            }
+            // 远程嵌入连接运行时覆盖(设置 UI 可编辑):baseURL/model 回显;apiKey 属机密→脱敏;
+            // dimensions 0 = 未配置,须落在 schema 同款范围(0~8192)
+            if (patch.embedRemoteBaseURL !== undefined) {
+                const base = String(patch.embedRemoteBaseURL);
+                if (base.length > 2000)
+                    throw new Error('embedRemoteBaseURL 过长(≤2000 字符)');
+                clean.embedRemoteBaseURL = base;
+            }
+            if (patch.embedRemoteModel !== undefined) {
+                const m = String(patch.embedRemoteModel);
+                if (m.length > 200)
+                    throw new Error('embedRemoteModel 过长(≤200 字符)');
+                clean.embedRemoteModel = m;
+            }
+            if (patch.embedRemoteDimensions !== undefined) {
+                const dim = Number(patch.embedRemoteDimensions);
+                if (!Number.isInteger(dim) || dim < 0 || dim > 8192) {
+                    throw new Error('embedRemoteDimensions 须为 0~8192 的整数(0 = 未配置)');
+                }
+                clean.embedRemoteDimensions = dim;
+            }
+            if (patch.embedRemoteApiKey !== undefined) {
+                const key = String(patch.embedRemoteApiKey);
+                if (key.length > 2000)
+                    throw new Error('embedRemoteApiKey 过长(≤2000 字符)');
+                clean.embedRemoteApiKey = key;
+            }
+            if (Object.keys(clean).length === 0)
+                throw new Error('开关更新载荷为空');
+            // 日志脱敏:直连/远程 API key 永不出现在日志
+            const logSafe = { ...clean };
+            delete logSafe.directApiKey;
+            delete logSafe.embedRemoteApiKey;
+            await live.update(clean);
+            deps.logger.info(`[memory] 设置更新:${JSON.stringify(logSafe)}`);
+            const v = { ok: true, settings: sanitizeSettings(live.get()) };
+            return v;
+        }
+        case 'dsh-memory/list-records': {
+            const p = (payload ?? {});
+            if (p.query !== undefined && p.query.length > 4096)
+                throw new Error('query 过长(≤4096 字符)');
+            const limit = Math.min(Math.max(Number(p.limit) || 50, 1), 200);
+            const offset = Math.min(Math.max(Number(p.offset) || 0, 0), 1_000_000);
+            // 关键词路径:复用检索唯一缝(与召回同源),取回后做场景/Hall 过滤 + 手工分页。
+            // 检索侧单次上限 200:分页窗口触达上限时显式标记 truncated(结果可能不完整)。
+            if (p.query && p.query.trim()) {
+                const SEARCH_CAP = 200;
+                const wanted = offset + limit + 1;
+                const hits = await stores.l1.search(p.query, Math.min(wanted, SEARCH_CAP), { type: p.type || undefined });
+                let filtered = p.scene ? hits.filter((h) => h.scene_name === p.scene) : hits;
+                // Hall 过滤(检索命中不含 metadata):按 id 批量取回元数据后过滤
+                let metaById = null;
+                if (p.hall && filtered.length > 0) {
+                    const meta = new Map();
+                    for (const r of stores.l1.getByIds(filtered.map((h) => h.id))) {
+                        if (r.metadata)
+                            meta.set(r.id, r.metadata);
+                    }
+                    metaById = meta;
+                    filtered = filtered.filter((h) => (meta.get(h.id)?.hall) === p.hall);
+                }
+                const resp = {
+                    items: filtered.slice(offset, offset + limit).map((h) => hitToUiRecord({ ...h, metadata: metaById?.get(h.id) })),
+                    hasMore: filtered.length > offset + limit,
+                    total: null,
+                    truncated: wanted > SEARCH_CAP,
+                    scenes: offset === 0 ? stores.l1.distinctScenes() : undefined,
+                };
+                return resp;
+            }
+            const { items, total } = stores.l1.list({ type: p.type || undefined, scene: p.scene || undefined, hall: p.hall || undefined, limit, offset });
+            const resp = {
+                items: items.map(hitToUiRecord),
+                hasMore: offset + items.length < total,
+                total,
+                truncated: false,
+                scenes: offset === 0 ? stores.l1.distinctScenes() : undefined,
+            };
+            return resp;
+        }
+        case 'dsh-memory/records-delete': {
+            // 面板高权限删除指定记忆;写入删权限门(memoryMutate)防御
+            if (!live?.get().memoryMutate) {
+                throw new Error('记忆写删未开放:请在记忆库面板开启高权限模式');
+            }
+            const p = (payload ?? {});
+            const ids = (Array.isArray(p.ids) ? p.ids : []).filter((x) => typeof x === 'string').slice(0, 200);
+            if (ids.length === 0)
+                throw new Error('ids 缺失');
+            await stores.l1.deleteBatch(ids);
+            deps.logger.info(`[memory] 高权限删除记忆 ${ids.length} 条(${ids.join('，')})`);
+            return { deleted: ids.length };
+        }
+        // ── 知识图谱(面板图谱视图;graph 未装配时返空不报错) ──
+        case 'dsh-memory/graph-search': {
+            const p = (payload ?? {});
+            const query = typeof p.query === 'string' ? p.query : '';
+            if (query.length > 4096)
+                throw new Error('query 过长(≤4096 字符)');
+            const limit = Math.min(Math.max(Math.floor(Number(p.limit)) || 8, 1), 20);
+            const graph = stores.graph;
+            if (!graph)
+                return { items: [] };
+            const hits = graph.searchNodes(query, limit);
+            return {
+                items: hits.map((h) => ({
+                    node: h.node,
+                    score: Math.round(h.score * 100) / 100,
+                    matchedFields: h.matchedFields,
+                    matchReason: h.matchReason,
+                })),
+            };
+        }
+        case 'dsh-memory/graph-node-get': {
+            const p = (payload ?? {});
+            const id = typeof p.id === 'string' ? p.id : '';
+            if (!id || id.length > 200)
+                throw new Error('id 缺失或过长(≤200 字符)');
+            const graph = stores.graph;
+            if (!graph)
+                return { node: null, edges: [] };
+            // 悬挂 id(已归档/不存在)不解析:node=null,调用方展示"节点不存在"
+            const node = graph.getNode(id);
+            if (!node)
+                return { node: null, edges: [] };
+            return { node, edges: graph.edgesOf(id) };
+        }
+        case 'dsh-memory/scenes': {
+            // 两族拼接展示(浏览器保持混合视图;路径冲突时后写入的族覆盖显示名,读取仍各自独立)
+            const items = [];
+            for (const family of ['chat', 'work']) {
+                const summaries = await stores.scenes[family].list();
+                for (const s of summaries) {
+                    items.push({ path: s.path, family, summary: s.summary, updated: s.updated, heat: s.heat, content: (await stores.scenes[family].read(s.path)) ?? '' });
+                }
+            }
+            items.sort((a, b) => (a.updated < b.updated ? 1 : -1));
+            return { items };
+        }
+        case 'dsh-memory/persona': {
+            const [chat, work] = await Promise.all([stores.persona.chat.read(), stores.persona.work.read()]);
+            const parts = [];
+            if (chat)
+                parts.push(`<!-- family: chat -->\n${chat}`);
+            if (work)
+                parts.push(`<!-- family: work -->\n${work}`);
+            return { content: parts.join('\n\n---\n\n') };
+        }
+        case 'dsh-memory/log-tail': {
+            const p = (payload ?? {});
+            return { lines: readLogTail(join(dataDir, 'memory.log'), Math.min(Math.max(Number(p.lines) || 200, 1), 1000)) };
+        }
+        case 'dsh-memory/rebuild-status': {
+            if (!rebuild) {
+                const v = { supported: false, running: false, phase: 'idle' };
+                return v;
+            }
+            return rebuild.getStatus();
+        }
+        case 'dsh-memory/rebuild-start': {
+            if (!rebuild)
+                throw new Error('重建控制器未初始化(存储不可用)');
+            if (status?.degraded())
+                throw new Error('存储处于降级状态,无法重建');
+            const s = live?.get();
+            if (s && (!s.enabled || !s.distill))
+                throw new Error('蒸馏开关已关闭,请先开启蒸馏再重建');
+            if (!cfg.extract.enabled)
+                throw new Error('部署配置已停用蒸馏(extract.enabled=false),无法重建');
+            const result = rebuild.start();
+            deps.logger.info('[memory] 收到重建指令(设置页按钮)');
+            return result;
+        }
+        case 'dsh-memory/rebuild-cancel': {
+            if (!rebuild)
+                throw new Error('重建控制器未初始化');
+            return rebuild.requestCancel();
+        }
+        // ── 反刍(记忆消化:按需消化未蒸馏缓冲) ──
+        case 'dsh-memory/ruminate-status': {
+            if (!ruminate) {
+                const v = { supported: false, running: false, phase: 'idle' };
+                return v;
+            }
+            return ruminate.getStatus();
+        }
+        case 'dsh-memory/ruminate-start': {
+            if (!ruminate)
+                throw new Error('反刍控制器未初始化(存储不可用)');
+            if (status?.degraded())
+                throw new Error('存储处于降级状态,无法反刍');
+            const s = live?.get();
+            if (s && (!s.enabled || !s.distill))
+                throw new Error('蒸馏开关已关闭,请先开启蒸馏再反刍');
+            if (!cfg.extract.enabled)
+                throw new Error('部署配置已停用蒸馏(extract.enabled=false),无法反刍');
+            const result = await ruminate.start();
+            deps.logger.info('[memory] 收到反刍指令(设置页按钮)');
+            return result;
+        }
+        case 'dsh-memory/ruminate-cancel': {
+            if (!ruminate)
+                throw new Error('反刍控制器未初始化');
+            return ruminate.requestCancel();
+        }
+        // ── 蒸馏模型选择器(用户已配置的供应商路由) ──
+        case 'dsh-memory/llm-providers': {
+            // 供应商目录(已注册适配器的活动路由)+ 默认选择 + 当前覆盖与实际生效路由
+            // ——蒸馏路由链编辑器的数据源(供应商下拉/默认模型展示/链状态 chain 块)
+            let providers = [];
+            try {
+                providers = deps.ctx.llm.listProviders();
+            }
+            catch (err) {
+                deps.logger.warn(`[memory] 供应商列表读取失败: ${errDetail(err)}`);
+            }
+            let def = null;
+            try {
+                const sel = deps.ctx.get('agentDefaultModel')?.currentSelection?.();
+                if (sel?.provider && sel?.model)
+                    def = { provider: sel.provider, model: sel.model };
+            }
+            catch {
+                /* 可选服务缺失 = 无默认选择 */
+            }
+            const s = live?.get();
+            const current = { provider: s?.distillProvider ?? '', model: s?.distillModel ?? '' };
+            // 统一路由链块:current = 运行时链(含旧键投影);static = 部署静态回退链;
+            // effective = buildRouteChain 语义的实际链(主路由 + 有效条目去重,每条带档位候选);
+            // source 标记当前链来自运行时还是部署静态(UI 的跟随态/接管态判定)
+            const chainCurrent = projectDistillChain(s);
+            let effectiveChain = [];
+            let effective;
+            let cfgView = cfg;
+            try {
+                cfgView = effectiveCfg(cfg, live);
+                effective = await resolveModelRoute(deps.ctx, cfgView);
+                effectiveChain = buildRouteChain({ provider: effective.provider, model: effective.model, effort: cfgView.llm.primaryEffort || '' }, cfgView.llm.fallbacks, cfgView.llm.reasoningEffort);
+            }
+            catch {
+                effective = null; // 无法解析(无默认选择且未覆盖)时 UI 显示占位
+            }
+            const pinned = Boolean(cfg.llm.provider && cfg.llm.model);
+            // 蒸馏通道视图(direct 解耦编辑器数据源):runtime = settings 覆盖档('' = 跟随
+            // 部署);effective = effectiveCfg 注入后的实际档;endpoint/密钥只回显非机密部分
+            // (apiKey 明文不回传,只给布尔);directReady 供 UI 在 effective=direct 时提示
+            // "未配置全(baseURL/model)"
+            const cfgChannel = cfgView.llm;
+            const effectiveMode = cfgChannel.mode === 'direct' ? 'direct' : 'host';
+            const deployedMode = cfg.llm.mode === 'direct' ? 'direct' : 'host';
+            const effBase = (s?.directBaseURL || cfg.llm.baseURL || '').trim();
+            const effModel = (cfgChannel.model || cfg.llm.model || '').trim();
+            const channel = {
+                runtime: s?.distillMode === 'host' || s?.distillMode === 'direct' ? s.distillMode : '',
+                effective: effectiveMode,
+                runtimeBaseURL: s?.directBaseURL ?? '',
+                deployedBaseURL: cfg.llm.baseURL ?? '',
+                deployed: deployedMode,
+                runtimeApiKeySet: Boolean(s?.directApiKey),
+                deployedApiKeySet: Boolean(cfg.llm.apiKey),
+                directReady: effectiveMode === 'direct' ? effBase !== '' && effModel !== '' : true,
+            };
+            // 按层层链视图:与解析真值同径(layerChainOrNull 吃 effectiveCfg 之后的 cfgView,
+            // pinned 时运行时层链未注入、静态层链胜出;跟随层直接复用全局 effectiveChain)
+            const mkLayerView = (key) => {
+                const rt = s?.distillLayerChains?.[key] ?? [];
+                const lr = layerChainOrNull(cfgView, key);
+                const rtLive = !pinned && rt.length > 0 && !!rt[0].provider && !!rt[0].model;
+                return {
+                    runtime: rt,
+                    static: cfg.llm.layerRoutes?.[key] ?? [],
+                    effectiveChain: lr ?? effectiveChain,
+                    source: rtLive ? 'runtime' : lr ? 'static' : 'global',
+                };
+            };
+            const resp = {
+                supported: true,
+                providers,
+                default: def,
+                // 部署静态 pin(provider+model 双字段)优先于运行时选择,UI 据此禁用选择器
+                pinned,
+                current,
+                // 所选供应商是否仍在已注册路由中(用户删掉供应商后提示回退)
+                currentRegistered: current.provider === '' || providers.some((p) => p.id === current.provider),
+                effective,
+                chain: {
+                    current: chainCurrent,
+                    static: cfg.llm.fallbacks ?? [],
+                    effectiveChain,
+                    source: chainCurrent.length ? 'runtime' : 'static',
+                },
+                // 按层层链:source 三态与解析真值同径(layerChainOrNull)——pinned 下
+                // 运行时层链不生效(与 effectiveCfg 注入条件一致),存量照实返回供 UI 展示
+                layerChains: {
+                    l1: mkLayerView('l1'),
+                    l2: mkLayerView('l2'),
+                    l3: mkLayerView('l3'),
+                },
+                channel,
+            };
+            return resp;
+        }
+        case 'dsh-memory/llm-models': {
+            const p = (payload ?? {});
+            if (typeof p.provider !== 'string' || !p.provider)
+                throw new Error('provider 缺失');
+            if (p.provider.length > 200)
+                throw new Error('provider 过长(≤200 字符)');
+            // 内置适配器的 listModels 都读本地快照不触网;仍加超时兜底,
+            // 防第三方适配器实现为远端查询拖死 RPC 轮询
+            const models = await Promise.race([
+                deps.ctx.llm.listModels(p.provider),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('模型列表查询超时')), 8000)),
+            ]);
+            // 每个模型附思考档位能力表(resolveModelInfo 复用 effortCache,本地快照不触网):
+            // 统一路由链编辑器的逐行档位下拉数据源。整体限时限流,超时降级空表
+            const baseModels = models.map((m) => ({ id: m.id, name: m.name, description: m.description ?? null, efforts: [] }));
+            const providerId = p.provider;
+            const withEfforts = await Promise.race([
+                (async () => {
+                    const out = [];
+                    for (const m of models) {
+                        let efforts;
+                        try {
+                            efforts = (await resolveModelEfforts(deps.ctx, providerId, m.id))?.efforts ?? [];
+                        }
+                        catch {
+                            efforts = [];
+                        }
+                        out.push({ id: m.id, name: m.name, description: m.description ?? null, efforts });
+                    }
+                    return out;
+                })(),
+                new Promise((resolve) => setTimeout(() => resolve(baseModels), 4000)),
+            ]);
+            const resp = { provider: p.provider, models: withEfforts };
+            return resp;
+        }
+        // ── 嵌入源(远程/本地/关闭 三态)与模型管理 ──
+        case 'dsh-memory/embedding-state-get': {
+            if (!embedManager) {
+                const v = { supported: false };
+                return v;
+            }
+            const v = { supported: true, ...(await embedManager.snapshot()) };
+            return v;
+        }
+        case 'dsh-memory/embedding-source-set': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化(存储不可用)');
+            const p = (payload ?? {});
+            if (p.source !== 'remote' && p.source !== 'local' && p.source !== 'off') {
+                throw new Error('source 必须是 remote | local | off');
+            }
+            if (typeof p.activeModel === 'string' && p.activeModel.length > 200) {
+                throw new Error('activeModel 过长(≤200 字符)');
+            }
+            const r = embedManager.requestSource({ source: p.source, activeModel: p.activeModel ?? null });
+            if (!r.accepted)
+                throw new Error(r.error ?? '切换请求被拒绝');
+            deps.logger.info(`[memory] 收到嵌入源切换指令(source=${p.source}${p.activeModel ? ',model=' + p.activeModel : ''})`);
+            return { accepted: true };
+        }
+        case 'dsh-memory/embedding-download-start': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化(存储不可用)');
+            const p = (payload ?? {});
+            if (typeof p.modelId !== 'string' || !p.modelId)
+                throw new Error('modelId 缺失');
+            const r = embedManager.startDownload(p.modelId);
+            if (!r.ok)
+                throw new Error(r.error ?? '下载请求被拒绝');
+            deps.logger.info(`[memory] 收到模型下载指令(${p.modelId})`);
+            return { accepted: true };
+        }
+        case 'dsh-memory/embedding-download-cancel': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            return { cancelled: embedManager.cancelDownload() };
+        }
+        case 'dsh-memory/embedding-model-delete': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            const p = (payload ?? {});
+            if (typeof p.modelId !== 'string' || !p.modelId)
+                throw new Error('modelId 缺失');
+            return embedManager.deleteModel(p.modelId);
+        }
+        case 'dsh-memory/embedding-runtime-cancel': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            return { cancelled: embedManager.cancelRuntimeInstall() };
+        }
+        case 'dsh-memory/embedding-reindex-cancel': {
+            if (!embedManager)
+                throw new Error('嵌入管理器未初始化');
+            return { cancelled: embedManager.cancelReindex() };
+        }
+        default:
+            throw new Error(`unknown endpoint: ${endpoint}`);
+    }
+}
+/** 浏览器卡片字段(比 MemoryRecord 精简,去掉大 metadata;Hall 从 metadata 提取)。 */
+function hitToUiRecord(r) {
+    return {
+        id: r.id,
+        content: r.content,
+        type: r.type,
+        priority: r.priority ?? 60,
+        scene: r.scene_name,
+        family: r.family ?? null,
+        hall: r.metadata && typeof r.metadata.hall === 'string' ? r.metadata.hall : null,
+        timestamps: (r.timestamps ?? []).map((t) => new Date(t).toISOString()),
+        createdAt: r.createdAt ? new Date(r.createdAt).toISOString() : null,
+        updatedAt: r.updatedAt ? new Date(r.updatedAt).toISOString() : null,
+        version: r.version ?? 0,
+        sourceMessageIds: r.source_message_ids ?? [],
+        score: r.score ?? null,
+    };
+}
+/**
+ * 从文件尾反向分块读取最后 N 行:不整读全文件(轮转上限 2MB,整读会
+ * 阻塞事件循环数毫秒)。原始 Buffer 拼接后再解码——分块边界可能切在
+ * UTF-8 多字节字符中间,先 toString 再拼接会产生乱码替换符。
+ */
+function readLogTail(logPath, maxLines) {
+    let fd;
+    try {
+        fd = openSync(logPath, 'r');
+        const { size } = statSync(logPath);
+        const CHUNK = 64 * 1024;
+        const bufs = [];
+        let newlines = 0;
+        let pos = size;
+        while (pos > 0) {
+            const read = Math.min(CHUNK, pos);
+            pos -= read;
+            const buf = Buffer.alloc(read);
+            readSync(fd, buf, 0, read, pos);
+            bufs.unshift(buf);
+            // \n 是完整单字节,绝不会出现在 UTF-8 续字节里——按字节计数跨块安全
+            for (let i = 0; i < buf.length; i++)
+                if (buf[i] === 0x0a)
+                    newlines++;
+            if (newlines > maxLines)
+                break;
+        }
+        const lines = Buffer.concat(bufs).toString('utf8').split('\n').filter((l) => l.length > 0);
+        return lines.slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}