dsh-prime-memory 0.11.0

package/dist/settings.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 记忆模式运行时开关(官方 settings 服务,live 生效)。
+ * 语义:静态 config(cordis.patch.yml,部署上限)AND 运行时开关,两者同时开才工作。
+ * settings 服务缺失(如 headless)时退化为恒开——行为与无开关版本一致。
+ *
+ * v0.9.0 契约:含远程嵌入运行时覆盖四键(embedRemote*)与记忆写删门 memoryMutate
+ * (自 dist 逆向补全——settings 缺键 = 用户已存值被静默丢弃,红线)。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { MemoryLogger } from './types.js';
+import type { DistillChainEntry, MemoryLiveSettings } from './contract.js';
+export type { DistillBudgets, DistillChainEntry, EffortChoice, MemoryLiveSettings } from './contract.js';
+/** 运行时路由链上限(写入门与 UI 同限,防误粘贴巨数组撑爆 settings 存储)。 */
+export declare const DISTILL_CHAIN_MAX = 8;
+/**
+ * 运行时统一路由链的展示投影(llm-providers 的 chain.current 数据源):
+ * distillChain 非空即原样返回;为空时投影旧运行时键(distillProvider/distillModel
+ * 成对 → 单行主路由,旧档位 reasoningEffort 作为该主路由的档位)。注意:生效逻辑
+ * (effectiveCfg)只认显式 distillChain、不走本投影——旧键路径在未配链时按旧语义
+ * 原样生效。
+ */
+export declare function projectDistillChain(s: Partial<MemoryLiveSettings> | undefined): DistillChainEntry[];
+/**
+ * settings-set 写入门校验:返回错误文案(null = 通过)。
+ * opts.requireExplicitHead(层链用):头行必须 provider+model 双显式——层键出现
+ * 即意图覆盖;"双空 = 跟随默认模型"是全局链独有语义,层链禁掉双空头,消除
+ * "层链头跟随哪套全局解析"的歧义。
+ */
+export declare function validateDistillChain(chain: unknown, opts?: {
+    requireExplicitHead?: boolean;
+}): string | null;
+/**
+ * settings scope 的本地结构类型:与官方 SettingsScope<T> 的 owner 面一致
+ * (get/watch/update),但不依赖包级类型导出,跨 DSH 版本稳定。
+ */
+export interface SettingsScope<T> {
+    get(): T;
+    watch(callback: (next: T, prev: T) => void | Promise<void>): () => void;
+    update(patch: object): Promise<void>;
+}
+export interface LiveSettingsHandle {
+    /** settings 服务是否可用(不可用时 UI 侧隐藏开关面板) */
+    supported: boolean;
+    get(): MemoryLiveSettings;
+    /** UI 写入入口;不支持时抛错由 RPC 层转成业务错误 */
+    update(patch: Partial<MemoryLiveSettings>): Promise<void>;
+}
+export declare function liveSettingsSchema(): Schema<MemoryLiveSettings>;
+export declare function registerLiveSettings(ctx: Context, logger: MemoryLogger): LiveSettingsHandle;

package/dist/settings.js

@@ -0,0 +1,355 @@
+import Schema from '@deepseek-ai/schemastery';
+import { EFFORT_CHOICES } from './config.js';
+/** 运行时路由链上限(写入门与 UI 同限,防误粘贴巨数组撑爆 settings 存储)。 */
+export const DISTILL_CHAIN_MAX = 8;
+/**
+ * 运行时统一路由链的展示投影(llm-providers 的 chain.current 数据源):
+ * distillChain 非空即原样返回;为空时投影旧运行时键(distillProvider/distillModel
+ * 成对 → 单行主路由,旧档位 reasoningEffort 作为该主路由的档位)。注意:生效逻辑
+ * (effectiveCfg)只认显式 distillChain、不走本投影——旧键路径在未配链时按旧语义
+ * 原样生效。
+ */
+export function projectDistillChain(s) {
+    if (s?.distillChain?.length)
+        return s.distillChain;
+    if (s?.distillProvider && s?.distillModel) {
+        return [{ provider: s.distillProvider, model: s.distillModel, reasoningEffort: s.reasoningEffort || '' }];
+    }
+    return [];
+}
+/**
+ * settings-set 写入门校验:返回错误文案(null = 通过)。
+ * opts.requireExplicitHead(层链用):头行必须 provider+model 双显式——层键出现
+ * 即意图覆盖;"双空 = 跟随默认模型"是全局链独有语义,层链禁掉双空头,消除
+ * "层链头跟随哪套全局解析"的歧义。
+ */
+export function validateDistillChain(chain, opts) {
+    if (!Array.isArray(chain))
+        return 'distillChain 须为数组';
+    if (chain.length > DISTILL_CHAIN_MAX)
+        return `路由链最多 ${DISTILL_CHAIN_MAX} 条`;
+    const seen = new Set();
+    for (let i = 0; i < chain.length; i++) {
+        if (!chain[i] || typeof chain[i] !== 'object')
+            return `第 ${i + 1} 行须为对象`;
+        const e = chain[i];
+        const p = typeof e.provider === 'string' ? e.provider : '';
+        const m = typeof e.model === 'string' ? e.model : '';
+        const eff = typeof e.reasoningEffort === 'string' ? e.reasoningEffort : '';
+        if (p.length > 200 || m.length > 200)
+            return `第 ${i + 1} 行 provider/model 过长(≤200 字符)`;
+        if (!EFFORT_CHOICES.includes(eff))
+            return `第 ${i + 1} 行思考档位非法: ${eff || '(空)'}`;
+        if (i === 0) {
+            if (opts?.requireExplicitHead && (!p || !m))
+                return '主路由行必须显式选择供应商与模型(层链不支持跟随默认模型)';
+            if ((p && !m) || (!p && m))
+                return '主路由行 provider 与 model 须成对(双空 = 跟随默认模型)';
+        }
+        else if (!p || !m) {
+            return `第 ${i + 1} 行回退路由必须显式选择供应商与模型`;
+        }
+        if (p && m) {
+            const key = `${p}::${m}`;
+            if (seen.has(key))
+                return `第 ${i + 1} 行与前面的路由重复(${p}/${m})`;
+            seen.add(key);
+        }
+    }
+    return null;
+}
+const NS = 'dsh-memory';
+const ALWAYS_ON = {
+    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,
+};
+/**
+ * 进程内 scope 复用(fiber 重启重挂)。
+ * dsh-settings 的 register 把注册挂在其服务自身 ctx 的 effect 上,不随本插件
+ * fiber 销毁——fiber 重启后二次 register 会抛 already registered。模块级状态在
+ * fiber 重启间存活:复用上次注册的 scope 并重挂 watcher,否则开关读写停在 stub。
+ *
+ * 同时按服务实例(cachedSvc)判活:settings 服务自身重启时其注册随服务 ctx 销毁,
+ * 旧 scope 变死引用——新实例与缓存不符时作废缓存、向新实例重新注册
+ * (用户层由服务从磁盘重解析,已存开关不丢)。
+ */
+let cachedScope;
+let cachedUnwatch;
+let cachedSvc;
+export function liveSettingsSchema() {
+    const budget = () => Schema.number().min(0).max(1_000_000).default(0);
+    // 层链条目形状与 distillChain 相同(档位必填、'' = 跟随);写入校验另在
+    // settings-set 门做逐层 requireExplicitHead(schema 层只管形状默认,语义门在 host)
+    const chainEntry = () => Schema.object({
+        provider: Schema.string().default(''),
+        model: Schema.string().default(''),
+        reasoningEffort: Schema.union([...EFFORT_CHOICES]).default(''),
+    });
+    return Schema.object({
+        enabled: Schema.boolean().default(true),
+        capture: Schema.boolean().default(true),
+        distill: Schema.boolean().default(true),
+        recall: Schema.boolean().default(true),
+        reasoningEffort: Schema.union([...EFFORT_CHOICES]).default(''),
+        distillProvider: Schema.string().default(''),
+        distillModel: Schema.string().default(''),
+        distillChain: Schema.array(chainEntry()).default([]),
+        distillLayerChains: Schema.object({
+            l1: Schema.array(chainEntry()).default([]),
+            l2: Schema.array(chainEntry()).default([]),
+            l3: Schema.array(chainEntry()).default([]),
+        }).default({ l1: [], l2: [], l3: [] }),
+        distillBudgets: Schema.object({
+            extract: budget(),
+            dedup: budget(),
+            l2: budget(),
+            l3: budget(),
+            // 图谱投影输出预算(投影 job 单批 ≤8 条记录,默认 8000)
+            graph: budget(),
+        }).default({ extract: 0, dedup: 0, l2: 0, l3: 0, graph: 0 }),
+        distillMaxInputChars: Schema.number().min(0).max(1_000_000).default(0),
+        // 蒸馏通道运行时覆盖:'' = 跟随部署 config / 'host' = 复用宿主 / 'direct' = 原生直连
+        distillMode: Schema.union(['', 'host', 'direct']).default(''),
+        directBaseURL: Schema.string().default(''),
+        // 直连 apiKey 属机密:schema 只接受字符串,不回读到 UI、不落日志
+        directApiKey: Schema.string().default(''),
+        // 远程嵌入连接运行时覆盖(设置 UI 可编辑,替代部署 YAML;dimension 上限与部署 schema 一致)
+        embedRemoteBaseURL: Schema.string().default(''),
+        embedRemoteApiKey: Schema.string().default(''),
+        embedRemoteModel: Schema.string().default(''),
+        embedRemoteDimensions: Schema.number().min(0).max(8192).default(0),
+        // 记忆写删权限门:默认 false(模型写删风险高,须显式在面板开启高权限模式)
+        memoryMutate: Schema.boolean().default(false),
+    });
+}
+export function registerLiveSettings(ctx, logger) {
+    // settings 服务可能晚于插件就绪(provider 先读盘再发布):先探测,未上线则监听补挂
+    let inner = {
+        supported: false,
+        get: () => ALWAYS_ON,
+        update: () => Promise.reject(new Error('settings 服务不可用')),
+    };
+    /** 挂接一个(新注册或复用的)scope:重挂前先摘旧 watcher,防跨重启累积。 */
+    const wireScope = (scope) => {
+        cachedUnwatch?.();
+        let current = resolveSettings(scope.get());
+        cachedUnwatch = scope.watch((next) => {
+            const prev = current;
+            current = resolveSettings(next);
+            const b = current.distillBudgets;
+            const budgetNote = (b.extract || b.dedup || b.l2 || b.l3 || b.graph)
+                ? `,输出预算=抽取 ${b.extract || '默认'}/去重 ${b.dedup || '默认'}/L2 ${b.l2 || '默认'}/L3 ${b.l3 || '默认'}/图谱 ${b.graph || '默认'}`
+                : '';
+            const inputNote = current.distillMaxInputChars > 0 ? `,输入预算=${current.distillMaxInputChars}` : '';
+            logger.info(`[memory] 记忆模式开关更新:总=${current.enabled} 捕获=${current.capture} 蒸馏=${current.distill} 召回=${current.recall}` +
+                `,蒸馏思考=${current.reasoningEffort || '跟随配置'}(此前 总=${prev.enabled})` +
+                (current.distillProvider && current.distillModel
+                    ? `,蒸馏模型=${current.distillProvider}/${current.distillModel}`
+                    : '') + budgetNote + inputNote);
+        });
+        return {
+            supported: true,
+            get: () => current,
+            update: async (patch) => {
+                await scope.update(patch);
+            },
+        };
+    };
+    /** 作废进程内缓存(服务下线/实例替换时旧注册已随服务销毁)。 */
+    const invalidateCache = () => {
+        cachedScope = undefined;
+        cachedSvc = undefined;
+        cachedUnwatch?.();
+        cachedUnwatch = undefined;
+    };
+    const tryAttach = () => {
+        const settings = ctx.get('settings');
+        if (!settings)
+            return false;
+        // 仅当缓存来自同一服务实例时才可复用——换了实例(服务重启/替换)就重新注册
+        if (cachedScope && cachedSvc === settings) {
+            try {
+                inner = wireScope(cachedScope);
+                const c = inner.get();
+                logger.info(`[memory] 记忆模式开关重挂(复用进程内注册,当前:总=${c.enabled} 捕获=${c.capture} 蒸馏=${c.distill} 召回=${c.recall}` +
+                    `,蒸馏思考=${c.reasoningEffort || '跟随配置'})`);
+                return true;
+            }
+            catch (err) {
+                logger.warn(`[memory] 记忆模式开关缓存复用失败,改为重新注册: ${err instanceof Error ? err.message : String(err)}`);
+                invalidateCache();
+            }
+        }
+        // 分支 1(全版本存在):register 返回 owner 面的 SettingsScope(get/watch/update),
+        // 本插件的 live 开关读写/UI 写入全走它——优先级高于 installSection:
+        // 后者返回 void 只走 hooks(setSource/onChange),桥接后 update 写路径不可用,
+        // 仅当宿主只暴露 installSection 时才作降级回退(见分支 2)。
+        if (typeof settings.register === 'function') {
+            try {
+                const scope = settings
+                    .register(NS, liveSettingsSchema(), { applies: 'live' });
+                cachedScope = scope;
+                cachedSvc = settings;
+                inner = wireScope(scope);
+                logger.info(`[memory] 记忆模式开关就绪(settings.register,命名空间 dsh-memory,当前:总=${inner.get().enabled} 捕获=${inner.get().capture} 蒸馏=${inner.get().distill} 召回=${inner.get().recall}` +
+                    `,蒸馏思考=${inner.get().reasoningEffort || '跟随配置'})`);
+                return true;
+            }
+            catch (err) {
+                logger.warn(`[memory] 记忆模式开关注册失败(保持全开): ${err instanceof Error ? err.message : String(err)}`);
+                return true; // 已拿到服务但注册失败,不再重试
+            }
+        }
+        // 分支 2(v0.1.2+ 服务面,仅 register 缺失时):installSection(owner, ns, schema,
+        // entry, hooks) 只回 hooks——get 走 setSource 注入的 thunk,变更通知走 onChange,
+        // update 桥接为显式拒绝(UI 写入报业务错误;宿主未删 register 时不会走到这)。
+        if (typeof settings.installSection === 'function') {
+            try {
+                let source = () => ({ ...ALWAYS_ON });
+                let notify;
+                const bridge = {
+                    get: () => resolveSettings(source()),
+                    watch: (callback) => {
+                        notify = () => void callback(bridge.get(), bridge.get());
+                        return () => {
+                            notify = undefined;
+                        };
+                    },
+                    update: () => Promise.reject(new Error('installSection 桥接模式不支持运行时写入')),
+                };
+                settings.installSection(ctx, NS, liveSettingsSchema(), { ...ALWAYS_ON }, {
+                    setSource: (current) => {
+                        source = current;
+                    },
+                    onChange: () => notify?.(),
+                });
+                cachedScope = bridge;
+                cachedSvc = settings;
+                inner = wireScope(bridge);
+                logger.info('[memory] 记忆模式开关就绪(settings.installSection 桥接,运行时写入不可用)');
+                return true;
+            }
+            catch (err) {
+                logger.warn(`[memory] 记忆模式开关 installSection 桥接失败(保持全开): ${err instanceof Error ? err.message : String(err)}`);
+                return true;
+            }
+        }
+        // 分支 3(双 API 皆无):settings 服务在但没有可用注册面——保持全开降级,
+        // 不再重试(服务面不会凭空长出新 API)。
+        logger.warn('[memory] settings 服务无可用的 register/installSection API,记忆模式开关降级为恒开');
+        return true;
+    };
+    if (!tryAttach()) {
+        logger.warn('[memory] settings 服务未就绪,记忆模式开关暂不可用(保持全开,等待服务上线)');
+    }
+    // 无论初始是否成功都监听服务迁移:下线 → 作废缓存;换实例 → 作废后立即重挂
+    ctx.on('internal/service', (name, impl) => {
+        if (name !== 'settings')
+            return;
+        if (!impl) {
+            if (cachedSvc !== undefined) {
+                invalidateCache();
+                logger.warn('[memory] settings 服务下线,开关缓存已作废(期间读数为冻结值,恢复后自动重挂)');
+            }
+            return;
+        }
+        // 实例变了才作废缓存;但 tryAttach 无条件执行(幂等)——同一事件会广播到
+        // 所有存活 fiber 的监听器,后跑的那个也必须修好自己闭包里的 inner
+        if (impl !== cachedSvc)
+            invalidateCache();
+        tryAttach();
+    });
+    return {
+        get supported() {
+            return inner.supported;
+        },
+        get: () => inner.get(),
+        update: (patch) => inner.update(patch),
+    };
+}
+/** scope.get() 的防御性解析:异常值回退默认(宁可多记不可静默停摆)。 */
+function resolveSettings(value) {
+    if (!value || typeof value !== 'object')
+        return { ...ALWAYS_ON, distillChain: [] };
+    const v = value;
+    const num = (x) => (typeof x === 'number' && Number.isFinite(x) && x >= 0 ? Math.floor(x) : 0);
+    const rawBudgets = (v.distillBudgets ?? {});
+    // 路由链逐条防御:非对象条目剔除、超长截断、非法档位归空、超限截断到上限
+    const defuseChain = (raw) => {
+        const out = [];
+        if (!Array.isArray(raw))
+            return out;
+        for (const item of raw) {
+            if (out.length >= DISTILL_CHAIN_MAX)
+                break;
+            if (!item || typeof item !== 'object')
+                continue;
+            const e = item;
+            const eff = typeof e.reasoningEffort === 'string' && EFFORT_CHOICES.includes(e.reasoningEffort)
+                ? e.reasoningEffort
+                : '';
+            out.push({
+                provider: typeof e.provider === 'string' ? e.provider.slice(0, 200) : '',
+                model: typeof e.model === 'string' ? e.model.slice(0, 200) : '',
+                reasoningEffort: eff,
+            });
+        }
+        return out;
+    };
+    const rawLayer = (v.distillLayerChains ?? {});
+    return {
+        enabled: v.enabled !== false,
+        capture: v.capture !== false,
+        distill: v.distill !== false,
+        recall: v.recall !== false,
+        reasoningEffort: typeof v.reasoningEffort === 'string' && EFFORT_CHOICES.includes(v.reasoningEffort)
+            ? v.reasoningEffort
+            : '',
+        distillProvider: typeof v.distillProvider === 'string' ? v.distillProvider : '',
+        distillModel: typeof v.distillModel === 'string' ? v.distillModel : '',
+        distillChain: defuseChain(v.distillChain),
+        distillLayerChains: {
+            l1: defuseChain(rawLayer.l1),
+            l2: defuseChain(rawLayer.l2),
+            l3: defuseChain(rawLayer.l3),
+        },
+        distillBudgets: {
+            extract: num(rawBudgets.extract),
+            dedup: num(rawBudgets.dedup),
+            l2: num(rawBudgets.l2),
+            l3: num(rawBudgets.l3),
+            graph: num(rawBudgets.graph),
+        },
+        distillMaxInputChars: num(v.distillMaxInputChars),
+        // 蒸馏通道:mode 白名单(非法归 '' = 跟随部署);端点与密钥截断防御但保留原始内容
+        distillMode: v.distillMode === 'host' || v.distillMode === 'direct' ? v.distillMode : '',
+        directBaseURL: typeof v.directBaseURL === 'string' ? v.directBaseURL.slice(0, 2000) : '',
+        directApiKey: typeof v.directApiKey === 'string' ? v.directApiKey.slice(0, 2000) : '',
+        // 远程嵌入覆盖:端点/密钥截 2000,模型名截 200,维度钳 0~8192(与部署 schema 上限一致)
+        embedRemoteBaseURL: typeof v.embedRemoteBaseURL === 'string' ? v.embedRemoteBaseURL.slice(0, 2000) : '',
+        embedRemoteApiKey: typeof v.embedRemoteApiKey === 'string' ? v.embedRemoteApiKey.slice(0, 2000) : '',
+        embedRemoteModel: typeof v.embedRemoteModel === 'string' ? v.embedRemoteModel.slice(0, 200) : '',
+        embedRemoteDimensions: typeof v.embedRemoteDimensions === 'number' && Number.isFinite(v.embedRemoteDimensions)
+            ? Math.min(Math.max(Math.floor(v.embedRemoteDimensions), 0), 8192)
+            : 0,
+        // 写删门:严格 === true(任何异常值都视为关,模型写删风险宁紧勿松)
+        memoryMutate: v.memoryMutate === true,
+    };
+}

package/dist/stats.d.ts

@@ -0,0 +1,109 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type MemoryConfig } from './config.js';
+import { type RecallSessionStats } from './hooks/recall.js';
+import type { RebuildController } from './pipeline/rebuild.js';
+import type { RuminateController } from './pipeline/ruminate.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 { SessionModeStore } from './store/session-modes.js';
+import type { EmbeddingManager } from './store/embedding-source.js';
+import type { StateStore } from './store/state.js';
+import type { MemoryFamily, MemoryLogger } from './types.js';
+export declare const PLUGIN_VERSION: string;
+/** 运行态来源(index.ts 注入):避免 stats 撒谎字段。 */
+export interface MemoryStatusSource {
+    /** 存储是否处于降级态(数据目录/检索库不可用)。 */
+    degraded(): boolean;
+    /** L1 抽取待重试的消息条数。 */
+    pending(): number;
+}
+/**
+ * 会话级统计数据源(悬浮卡信息区;index.ts 注入)。
+ * 硬规则:本端点按"打开期间 2~5s 轮询"设计,实现只允许内存注册表读取与
+ * 索引化 SQL 点查——禁止任何文件读/目录扫描(scenes.list()/persona.read()
+ * 级别的 I/O 会把每次轮询变成数十毫秒的全量读,见 slider-spec 数据策略节)。
+ */
+export interface SessionInfoSource {
+    /** 召回统计(recall.ts 注册表;未发生检索的会话返回 undefined)。 */
+    recallStats(sessionId: string): RecallSessionStats | undefined;
+    /** 记忆上下文占用账本(context-occupancy 唯一权威实例;未注入过的会话返回 null)。 */
+    memoryOccupancy(sessionId: string): MemoryOccupancy | null;
+    /** 稳定区份额估算(旧会话回填用;缺省 = 装配未提供,回填隐藏)。 */
+    profileEstimate?(sessionId: string): number;
+    /** 召回份额回填(live surface 现扫,miss 读盘上日志;缺省 = null)。 */
+    recallEstimate?(sessionId: string): Promise<number | null> | number | null;
+    /** 蒸馏管线会话视图(runner:攒批进度/挂起切片/会话产出)。 */
+    runnerView(sessionId: string, mode: string): {
+        pendingSlice: number;
+        parkedSlices: number;
+        threshold: number | null;
+        producedRecords: number;
+        lastDistillAt: number | null;
+    };
+    /** L0 该会话已捕获消息数(索引 COUNT)。 */
+    l0Count(sessionId: string): Promise<number>;
+    /** 检索能力位(hybrid / keyword 降级判定)。 */
+    capabilities(): {
+        ftsSearch: boolean;
+        vectorSearch: boolean;
+    };
+}
+import type { MemoryOccupancy } from './contract.js';
+export type { MemoryStats } from './contract.js';
+/** 注册状态 RPC(web 侧 connection 服务可选,缺失时跳过,不影响插件主体)。 */
+/** registerMemoryRpc 形参中需要落入端点 deps 的部分。 */
+interface MemoryRpcSources {
+    status?: MemoryStatusSource;
+    live?: LiveSettingsHandle;
+    modes?: SessionModeStore;
+    dataDir?: string;
+    rebuild?: RebuildController;
+    embedManager?: EmbeddingManager;
+    sessionInfo?: SessionInfoSource;
+}
+/** 端点 deps 的注入面(ctx/cfg/stores/logger 由调用方绑定,其余由此处决定)。 */
+export type EndpointDepsInput = Omit<EndpointDeps, 'ctx' | 'cfg' | 'stores' | 'logger'>;
+/**
+ * 组装端点 deps。抽成函数是为了让"哪个控制器落入哪个字段"成为可测接缝:
+ * 反刍端点读 deps.ruminate,若此处漏注入,端点会静默恒返 {supported:false}(面板整块不渲染)。
+ * @param controller - 反刍控制器;由 index.ts 在存储可用时装配,降级时为 undefined。
+ */
+export declare function buildEndpointDeps(base: Pick<EndpointDeps, 'ctx' | 'cfg' | 'stores' | 'logger'>, sources: MemoryRpcSources, controller: RuminateController | undefined): EndpointDeps;
+export declare function registerMemoryRpc(ctx: Context, cfg: MemoryConfig, stores: {
+    l0: L0Store;
+    l1: L1Store;
+    scenes: Record<MemoryFamily, SceneStore>;
+    persona: Record<MemoryFamily, PersonaStore>;
+    state: StateStore;
+    /** 图谱存储(可选:未装配时图谱端点返空,不报错)。 */
+    graph?: GraphStore;
+}, logger: MemoryLogger, status?: MemoryStatusSource, live?: LiveSettingsHandle, modes?: SessionModeStore, dataDir?: string, rebuild?: RebuildController, embedManager?: EmbeddingManager, sessionInfo?: SessionInfoSource, 
+/** 反刍控制器(存储降级时为 undefined):经 buildEndpointDeps 落入 deps.ruminate。 */
+ruminate?: RuminateController): void;
+export interface EndpointDeps {
+    ctx: Context;
+    cfg: MemoryConfig;
+    stores: {
+        l0: L0Store;
+        l1: L1Store;
+        scenes: Record<MemoryFamily, SceneStore>;
+        persona: Record<MemoryFamily, PersonaStore>;
+        state: StateStore;
+        graph?: GraphStore;
+    };
+    status?: MemoryStatusSource;
+    live?: LiveSettingsHandle;
+    modes?: SessionModeStore;
+    dataDir: string;
+    logger: MemoryLogger;
+    rebuild?: RebuildController;
+    ruminate?: RuminateController;
+    embedManager?: EmbeddingManager;
+    sessionInfo?: SessionInfoSource;
+}
+/** 端点分发表(导出供测试直调:可精确注入 rebuild/ruminate 等可选控制器,验证 deps 接线)。 */
+export declare function handleEndpoint(endpoint: string, payload: unknown, deps: EndpointDeps): Promise<unknown>;