dsh-prime-memory 0.11.0

package/dist/index.js

@@ -0,0 +1,344 @@
+/**
+ * dsh-memory-plugin — L0~L3 分层蒸馏记忆插件(持久组合插件)。
+ *
+ * 装配职责:数据目录与文件日志 → live 开关 → 会话档位 → 嵌入源三态解析 →
+ * 检索引擎(memory.db)与分族存储 → 蒸馏 runner/重建控制器 → 捕获/召回钩子 →
+ * 工具/RPC/bench 控制面 → 停机顺序。
+ *
+ * 存储架构(JSONL 事实源 + memory.db 主检索):见 README 与 store 层模块注释。
+ * 降级铁律:存储初始化失败只停用捕获/蒸馏,绝不拖垮宿主启动。
+ */
+import * as path from 'node:path';
+import { memorySchema, resolveDataDir } from './config.js';
+import { registerBenchControl } from './bench-control.js';
+import { registerCapture } from './hooks/capture.js';
+import { registerRecall } from './hooks/recall.js';
+import { MemoryRunner } from './pipeline/runner.js';
+import { RebuildController } from './pipeline/rebuild.js';
+import { RuminateController } from './pipeline/ruminate.js';
+import { registerMemoryRpc, PLUGIN_VERSION } from './stats.js';
+import { registerLiveSettings } from './settings.js';
+import { NoopEmbeddingService } from './store/embedding.js';
+import { EmbeddingManager, EmbeddingSourceStore, makeLocalServiceFactory, resolveInitialEmbedding, } from './store/embedding-source.js';
+import { ModelDownloadQueue } from './store/download-queue.js';
+import { PINNED_TRANSFORMERS_VERSION, RuntimeInstaller } from './store/runtime-installer.js';
+import { ensureDir } from './util/io.js';
+import { L0Store } from './store/l0.js';
+import { L1Store } from './store/l1.js';
+import { PersonaStore } from './store/persona.js';
+import { MemoryDb } from './store/sqlite.js';
+import { SceneStore } from './store/scenes.js';
+import { SessionModeStore } from './store/session-modes.js';
+import { StateStore } from './store/state.js';
+import { registerMemoryTools } from './tools/index.js';
+import { errDetail, withFileLog } from './util/filelog.js';
+import { buildRouteChain, resolveModelRoute, invalidateEffortCache } from './llm.js';
+import { effectiveCfg } from './pipeline/runner.js';
+import { pendingPathFor } from './store/pending.js';
+import { initTokenCost, resetTokenCost } from './token-cost.js';
+export const name = 'dsh-memory-plugin';
+/** 硬依赖:蒸馏要用 llm,工具注册要用 tools,召回注入要用 systemPrompt。 */
+export const inject = ['llm', 'tools', 'systemPrompt'];
+/**
+ * 插件配置 schema。导出名必须是 `Config`——cordis 运行时只读 plugin.Config
+ * (Standard Schema 接口)做校验与默认值填充;导出 `schema` 会被静默忽略,
+ * 导致 config 里嵌套对象为 undefined、apply 抛错、fiber FAILED 拖垮宿主启动。
+ */
+export const Config = memorySchema;
+export async function apply(ctx, config) {
+    let logger = {
+        debug: (m) => ctx.logger.debug(m),
+        info: (m) => ctx.logger.info(m),
+        warn: (m) => ctx.logger.warn(m),
+        error: (m) => ctx.logger.error(m),
+    };
+    const dataDir = resolveDataDir(config);
+    // dsh 宿主无持久化日志,镜像 info+ 到数据目录 memory.log 供蒸馏问题诊断
+    const fileLogger = withFileLog(dataDir, logger);
+    logger = fileLogger;
+    // 供应商拓扑变化(增删/改配置)→ 思考档位能力缓存失效,下次调用重新探询
+    ctx.on('llm/adapters-updated', () => invalidateEffortCache());
+    // 存储初始化失败只降级(禁用捕获/蒸馏),绝不拖垮宿主——
+    // 记忆是增强能力,数据目录不可写时 dsh 本体必须照常启动。
+    let storageOk = true;
+    try {
+        await ensureDir(dataDir);
+    }
+    catch (err) {
+        storageOk = false;
+        logger.error(`[memory] 数据目录不可写,记忆功能停用: ${dataDir} (${err instanceof Error ? err.message : String(err)})`);
+    }
+    // ── 记忆模式运行时开关(官方 settings 服务,live 生效;缺失时恒开) ──
+    const live = registerLiveSettings(ctx, logger);
+    /** 插件停机标志:置位后不再发起后台 embeddings 调用(dispose 序最先设置)。 */
+    let disposed = false;
+    // ── 会话档位存储(sessionId → auto/chat/work/off;默认档 = config.family) ──
+    const modes = new SessionModeStore(dataDir, config.family, logger);
+    if (storageOk) {
+        try {
+            await modes.init();
+        }
+        catch (err) {
+            logger.warn(`[memory] 会话档位载入失败(降级为默认档内存态): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // ── 嵌入源三态(远程/本地/关闭)——状态文件优先于静态配置 ──
+    const sourceStore = new EmbeddingSourceStore(dataDir, logger);
+    const installer = new RuntimeInstaller(dataDir, PINNED_TRANSFORMERS_VERSION, { logger });
+    const downloader = new ModelDownloadQueue(dataDir, {
+        mirror: config.embedding.mirror,
+        logger,
+        proxy: config.embedding.proxy,
+    });
+    const makeLocalService = makeLocalServiceFactory(installer, downloader, logger, config.embedding.maxInputChars);
+    let initial = { svc: new NoopEmbeddingService(), dims: 0 };
+    /** 管理器引用:启动重嵌链/backfill 闭包在运行期解引用(声明早于创建避免 TDZ)。 */
+    // eslint-disable-next-line prefer-const -- 声明早于创建,后续单点赋值(TS 不允许 const 无初值)
+    let embedManagerRef;
+    if (storageOk) {
+        try {
+            await sourceStore.init();
+            initial = await resolveInitialEmbedding(config, sourceStore, downloader, makeLocalService, logger);
+        }
+        catch (err) {
+            logger.warn(`[memory] 嵌入源初始解析失败(降级纯 FTS): ${errDetail(err)}`);
+        }
+    }
+    /** meta 写入永远用当前目标(杜绝启动期闭包里的陈旧 providerInfo 腐蚀 embedding_meta)。 */
+    const currentProviderInfo = () => embedManagerRef?.currentProviderInfo() ?? initial.providerInfo;
+    // ── 检索引擎(memory.db)与向量服务 ──
+    const embed = initial.svc;
+    const db = new MemoryDb(path.join(dataDir, 'memory.db'), initial.dims, logger);
+    initTokenCost(db, config.tokenCost.retentionDays);
+    // 插件卸载时关闭连接(WAL 落盘),注册一次即可
+    ctx.effect(() => () => db.close());
+    let dbInit = { needsReindex: false };
+    if (storageOk) {
+        try {
+            dbInit = db.init(initial.providerInfo);
+            if (db.isDegraded()) {
+                storageOk = false;
+                logger.error('[memory] 检索库初始化失败(schema/FTS 不可用),记忆功能停用');
+            }
+        }
+        catch (err) {
+            storageOk = false;
+            logger.error(`[memory] 检索库打开失败,记忆功能停用: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const stores = {
+        l0: new L0Store(dataDir, db, embed, logger),
+        l1: new L1Store(dataDir, db, embed, config.recall.strategy, logger, config.recall.decayHalfLifeDays),
+        // L2/L3 分族隔离:各自目录与文件(scenes/chat|work、persona-chat|work.md)
+        scenes: {
+            chat: new SceneStore(dataDir, 'chat', logger),
+            work: new SceneStore(dataDir, 'work', logger),
+        },
+        persona: {
+            chat: new PersonaStore(dataDir, 'chat', logger),
+            work: new PersonaStore(dataDir, 'work', logger),
+        },
+        state: new StateStore(StateStore.pathFor(dataDir)),
+        // 图谱存储(MemoryDb 内自治:初始化失败仅图谱 no-op,不影响主链路)
+        graph: db.graphStore,
+    };
+    if (storageOk) {
+        try {
+            await Promise.all([
+                stores.l0.init(),
+                stores.l1.init(),
+                stores.scenes.chat.init(),
+                stores.scenes.work.init(),
+                stores.persona.chat.init(),
+                stores.persona.work.init(),
+            ]);
+        }
+        catch (err) {
+            storageOk = false;
+            logger.error(`[memory] 存储初始化失败,记忆功能停用: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // 检索能力与策略说明(能力位由降级结果决定)
+    const caps = db.getCapabilities();
+    if (storageOk && config.recall.strategy !== 'keyword' && !caps.vectorSearch) {
+        logger.warn(`[memory] 检索策略 ${config.recall.strategy} 需要向量能力(embedding 未启用/不可用),本次运行按 keyword(FTS5 BM25)检索`);
+    }
+    logger.info(`[memory] 数据目录: ${dataDir}(v${PLUGIN_VERSION},默认档=${config.family},检索: FTS=${caps.ftsSearch} 向量=${caps.vectorSearch}${storageOk ? '' : ',存储不可用已停用捕获/蒸馏'})`);
+    // 蒸馏模型路由:启动期解析一次并记录(路由错误是最难事后排查的问题之一);
+    // 用运行时调参视图解析——用户已用 UI 覆盖蒸馏模型时,日志反映实际路由
+    try {
+        const cfgView = effectiveCfg(config, live);
+        const route = await resolveModelRoute(ctx, cfgView);
+        // 链长度按同一解析口径计(相同条目会被去重),排障时无需 --dump-config 即可确认回退链生效
+        const chain = buildRouteChain(route, cfgView.llm.fallbacks, cfgView.llm.reasoningEffort);
+        logger.info(`[memory] 蒸馏模型路由: ${route.provider}/${route.model}${chain.length > 1 ? `(+${chain.length - 1} 回退)` : ''}`);
+    }
+    catch (err) {
+        logger.warn(`[memory] 蒸馏模型路由解析失败: ${errDetail(err)}`);
+    }
+    // embedding 配置变化 → 后台全量重嵌入(不阻塞启动)。
+    // meta 标记条件 = 失败为 0 且缺失复查为 0(服务未就绪的空转不算成功)。
+    if (storageOk && initial.providerInfo && !db.isDegraded()) {
+        const info = initial.providerInfo;
+        if (dbInit.needsReindex) {
+            if (caps.vectorSearch) {
+                void (async () => {
+                    try {
+                        if (disposed || embedManagerRef?.isBusy())
+                            return;
+                        // 增量:配置变化路径向量表已被 drop,全部记录均"缺失",等效全量;
+                        // 活切换发起时让路(swap 会 drop 表,并发跑只是白烧嵌入调用)
+                        const shouldCancel = () => disposed || !!embedManagerRef?.isBusy();
+                        const r1 = await stores.l1.reindex({ shouldCancel });
+                        const r0 = await stores.l0.reindex({ shouldCancel });
+                        // missing 复查:嵌入服务未就绪时 reindex 短路 0/0/0——那是"没跑"不是"成功",
+                        // 不得标记 meta(否则启动链不再补,补齐被无限推迟到 backfill)
+                        const missingAfter = db.countL1VecMissing(db.getVecSkipSet('l1')) + db.countL0VecMissing(db.getVecSkipSet('l0'));
+                        if (r1.failed === 0 && r0.failed === 0 && missingAfter === 0) {
+                            db.markEmbeddingSynced(currentProviderInfo() ?? info);
+                            const skipNote = r1.skipped + r0.skipped > 0 ? `,跳过不可嵌入 ${r1.skipped + r0.skipped} 条` : '';
+                            logger.info(`[memory] 向量重建完成:L1 ${r1.written} 条,L0 ${r0.written} 条${skipNote}(原因:${dbInit.reason ?? '配置变化'})`);
+                        }
+                        else {
+                            logger.warn(`[memory] 向量重建未完成(L1 失败 ${r1.failed},L0 失败 ${r0.failed},剩缺 ${Math.max(missingAfter, 0)} 条),下次启动/补齐周期重试`);
+                        }
+                    }
+                    catch (err) {
+                        logger.warn(`[memory] 向量重建失败: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                })();
+            }
+        }
+        else {
+            // meta 已匹配或空库(initSchema 已写入),幂等重写一次
+            db.markEmbeddingSynced(currentProviderInfo() ?? info);
+        }
+        // 周期性向量补齐:嵌入失败的批次/漏网记录自动补上(30 分钟一次)。
+        // 判据 = 排除 skip 集后的缺失数(增量语义):缺 1 条只补 1 条,
+        // 零向量记录进 skip 集后不再触发——否则补齐永不收敛、每 30 分钟全量重嵌。
+        // 注册不依赖启动期 caps/providerInfo(off 起步后活切回旧源也要能补),
+        // 执行期动态查当前目标与能力位。
+        {
+            const backfill = () => {
+                void (async () => {
+                    try {
+                        if (disposed)
+                            return;
+                        const infoNow = currentProviderInfo();
+                        const capsNow = db.getCapabilities();
+                        if (!infoNow || !capsNow.vectorSearch)
+                            return;
+                        // 活切换链(安装/下载/重嵌)进行中让路——增量 reindex 天然幂等,
+                        // 但并发跑只是白烧一次嵌入调用
+                        if (embedManagerRef?.isBusy())
+                            return;
+                        const l1Missing = db.countL1VecMissing(db.getVecSkipSet('l1')) > 0;
+                        const l0Missing = db.countL0VecMissing(db.getVecSkipSet('l0')) > 0;
+                        if (!l1Missing && !l0Missing)
+                            return;
+                        const shouldCancel = () => disposed || !!embedManagerRef?.isBusy();
+                        const r1 = await stores.l1.reindex({ shouldCancel });
+                        const r0 = await stores.l0.reindex({ shouldCancel });
+                        const missingAfter = db.countL1VecMissing(db.getVecSkipSet('l1')) + db.countL0VecMissing(db.getVecSkipSet('l0'));
+                        if (r1.failed === 0 && r0.failed === 0 && missingAfter === 0) {
+                            db.markEmbeddingSynced(infoNow);
+                            logger.info(`[memory] 向量补齐完成:L1 ${r1.written} 条,L0 ${r0.written} 条(跳过不可嵌入 ${r1.skipped + r0.skipped} 条)`);
+                        }
+                        else if (r1.failed > 0 || r0.failed > 0) {
+                            logger.warn(`[memory] 向量补齐未完成(L1 失败 ${r1.failed},L0 失败 ${r0.failed}),下个周期重试`);
+                        }
+                    }
+                    catch (err) {
+                        logger.warn(`[memory] 向量补齐失败: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                })();
+            };
+            ctx.effect(() => {
+                const timer = setInterval(backfill, 30 * 60_000);
+                const first = setTimeout(backfill, 60_000);
+                return () => {
+                    clearInterval(timer);
+                    clearTimeout(first);
+                };
+            });
+        }
+    }
+    // 嵌入管理器(活切换/下载/运行时安装;存储降级时不建——RPC 走 supported=false)
+    const embedManager = storageOk && !db.isDegraded()
+        ? new EmbeddingManager({
+            dataDir,
+            cfg: config,
+            db,
+            l0: stores.l0,
+            l1: stores.l1,
+            sourceStore,
+            installer,
+            downloader,
+            initial,
+            logger,
+            makeLocal: makeLocalService,
+        })
+        : undefined;
+    embedManagerRef = embedManager;
+    const runner = new MemoryRunner(ctx, config, stores, logger, live, modes);
+    await runner.init();
+    // 档位切换同步(ADR-0003):切走按捕获档位落袋 / 切 off 挂起 / 切回清挂起
+    modes.setModeChangeHandler((sessionId, oldMode, newMode) => runner.onModeChange(sessionId, oldMode, newMode));
+    // 闲置兜底:静默达标会话的未蒸馏切片自动落袋(idleSeconds=0 关闭)
+    runner.startIdleTimer();
+    // 图谱周期补投影(cfg.graph.enabled 门控;30 分钟一次低速收敛)
+    runner.startGraphBackfillTimer();
+    // 重建控制器(存储降级时不建——RPC 端点走 supported=false 分支)
+    const rebuild = storageOk && !db.isDegraded()
+        ? new RebuildController(ctx, config, stores, db, runner, logger, live)
+        : undefined;
+    // 反刍控制器(与重建共用数据,但更轻量;存储降级时不建)
+    const ruminateFile = storageOk ? pendingPathFor(resolveDataDir(config)) : '';
+    const ruminate = storageOk && !db.isDegraded() && ruminateFile
+        ? new RuminateController(ctx, config, runner, stores, logger, live, ruminateFile)
+        : undefined;
+    let flushL0;
+    if (storageOk) {
+        flushL0 = registerCapture(ctx, config, runner, stores.l0, logger, live, modes);
+    }
+    const recall = registerRecall(ctx, config, stores, logger, live, modes, dataDir);
+    runner.setAfterRun(recall.invalidateProfile);
+    registerMemoryTools(ctx, config, stores, logger, modes, live, ruminate);
+    registerMemoryRpc(ctx, config, stores, logger, {
+        degraded: () => !storageOk || db.isDegraded(),
+        pending: () => runner.pendingCount,
+    }, live, modes, dataDir, rebuild, embedManager, 
+    // 悬浮卡信息区数据源(session-stats 热路径端点;全部内存读 + 索引 COUNT,零文件 I/O)
+    {
+        recallStats: (sid) => recall.stats(sid),
+        memoryOccupancy: (sid) => recall.occupancy(sid),
+        profileEstimate: (sid) => recall.estimateProfileTokens(sid),
+        recallEstimate: (sid) => recall.estimateRecallTokens(sid),
+        runnerView: (sid, mode) => runner.sessionView(sid, mode),
+        l0Count: (sid) => stores.l0.countBySession(sid),
+        capabilities: () => db.getCapabilities(),
+    }, ruminate);
+    // bench 控制服务(config.benchControl 门控,默认关):仅基准/调试部署注册,
+    // 供同进程的 bench-runner lifecycle 赛道触发 rebuild / 设置会话档位
+    // (宿主侧 RPC 无 call(),见 bench-control.ts)
+    if (config.benchControl && rebuild) {
+        const disposeBench = registerBenchControl(ctx, rebuild, modes, logger);
+        ctx.effect(() => () => disposeBench());
+    }
+    logger.info(`[memory] L0~L3 分层蒸馏记忆插件就绪(L1 记忆 ${storageOk ? stores.l1.size : 0} 条 | 捕获=${storageOk && config.capture.enabled} | 蒸馏=${storageOk && config.extract.enabled} | 召回=${config.recall.enabled})`);
+    // 停机顺序:置停机标志(后台 embeddings 不再发起)→ 停蒸馏取新任务 →
+    // 冲刷 L0 串行链(排队消息先落盘)→ 关库。cordis disposer 为 LIFO 逐个 await,
+    // 本 effect 晚注册故先执行;apply 中途失败时由上方早注册的 db.close 兜底(双关安全)。
+    ctx.effect(() => () => {
+        disposed = true;
+        runner.stop();
+        embedManager?.dispose();
+        downloader.dispose();
+        return (async () => {
+            await flushL0?.();
+            db.close();
+            db.graphStore.close();
+            resetTokenCost();
+        })();
+    });
+}

package/dist/llm-usage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 蒸馏用量追踪(进程内累计计数器,常开——纯内存累加,无 IO):
+ * callLLM 按层(l1-extract/l1-dedup/l2/l3)累计调用数、输入字符、输出/思考 token。
+ *
+ * 用途:基准的「记忆开销」记账——L1/L2/L3 蒸馏消耗摊到每条捕获消息。
+ * 暴露面:bench 控制服务 getDistillUsage()(config.benchControl 门控)。
+ *
+ * 输入侧说明:dsh llm 流的 usage 块只携带 output/reasoning token,输入 token
+ * 拿不到——按仓库既有口径记输入字符(中文 1 字 ≈ 1 token 保守折算)。
+ */
+import type { DistillLayer } from './contract.js';
+export type { DistillLayer } from './contract.js';
+export interface DistillLayerUsage {
+    calls: number;
+    failures: number;
+    inputChars: number;
+    outputTokens: number;
+    reasoningTokens: number;
+}
+export interface DistillUsageSnapshot {
+    layers: Record<string, DistillLayerUsage>;
+}
+/** 单次调用用量累计(callLLM 出口调用;inputChars 为实际发送的用户 prompt 字符)。 */
+export declare function recordDistillCall(layer: DistillLayer, inputChars: number, outputTokens: number, reasoningTokens: number, failed: boolean): void;
+/** 深拷贝快照(消费方拿到后不受后续累计影响)。 */
+export declare function snapshotDistillUsage(): DistillUsageSnapshot;

package/dist/llm-usage.js

@@ -0,0 +1,37 @@
+/**
+ * 蒸馏用量追踪(进程内累计计数器,常开——纯内存累加,无 IO):
+ * callLLM 按层(l1-extract/l1-dedup/l2/l3)累计调用数、输入字符、输出/思考 token。
+ *
+ * 用途:基准的「记忆开销」记账——L1/L2/L3 蒸馏消耗摊到每条捕获消息。
+ * 暴露面:bench 控制服务 getDistillUsage()(config.benchControl 门控)。
+ *
+ * 输入侧说明:dsh llm 流的 usage 块只携带 output/reasoning token,输入 token
+ * 拿不到——按仓库既有口径记输入字符(中文 1 字 ≈ 1 token 保守折算)。
+ */
+const counters = new Map();
+function bucketOf(layer) {
+    let b = counters.get(layer);
+    if (!b) {
+        b = { calls: 0, failures: 0, inputChars: 0, outputTokens: 0, reasoningTokens: 0 };
+        counters.set(layer, b);
+    }
+    return b;
+}
+/** 单次调用用量累计(callLLM 出口调用;inputChars 为实际发送的用户 prompt 字符)。 */
+export function recordDistillCall(layer, inputChars, outputTokens, reasoningTokens, failed) {
+    const b = bucketOf(layer);
+    b.calls++;
+    if (failed)
+        b.failures++;
+    b.inputChars += Math.max(0, Math.round(inputChars));
+    b.outputTokens += Math.max(0, Math.round(outputTokens));
+    b.reasoningTokens += Math.max(0, Math.round(reasoningTokens));
+}
+/** 深拷贝快照(消费方拿到后不受后续累计影响)。 */
+export function snapshotDistillUsage() {
+    const layers = {};
+    for (const [layer, b] of counters) {
+        layers[layer] = { ...b };
+    }
+    return { layers };
+}

package/dist/llm.d.ts

@@ -0,0 +1,153 @@
+/**
+ * LLM 桥:用 DSH 自身的 llm 服务跑蒸馏调用。
+ *
+ * 职责:蒸馏路由链(全局回退链 + 按层层链)、思考档位能力决策(跨供应商 effort
+ * 兼容)、分层输出预算(思考档 ×4 防线)、direct 原生 HTTP 通道、流式调用与
+ * 失败诊断、容错 JSON 解析。回退语义见 ADR-0004/0005。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from './config.js';
+import type { MemoryLogger } from './types.js';
+import { type DistillLayer } from './llm-usage.js';
+export interface LlmCallOptions {
+    system: string;
+    user: string;
+    /** 蒸馏层标签(用量记账用;四层调用点都应传)。 */
+    layer?: DistillLayer;
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+    /** 诊断日志(缺失时静默,不影响调用) */
+    logger?: MemoryLogger;
+}
+/** L1 抽取(大输入块的 JSON 记忆数组输出)。 */
+export declare const LAYER_MAX_TOKENS_EXTRACT = 16000;
+/** L1 去重(合并决策数组,输出比抽取短)。 */
+export declare const LAYER_MAX_TOKENS_DEDUP = 8000;
+/** L2 场景整合(完整场景 Markdown 文件输出,输出最重的层)。 */
+export declare const LAYER_MAX_TOKENS_L2 = 32000;
+/** L3 画像(完整 persona 文档)。 */
+export declare const LAYER_MAX_TOKENS_L3 = 16000;
+/** 图谱投影(节点/边提案 JSON;单批 ≤8 条记录,输出比 L1 抽取短)。 */
+export declare const LAYER_MAX_TOKENS_GRAPH = 8000;
+/** 分层输出预算键(契约单一事实源在 src/contract.ts)。 */
+import type { DistillBudgetLayer, LayerRouteKey, StaticFallbackEntry } from './contract.js';
+export type { DistillBudgetLayer } from './contract.js';
+/** 各层内置默认预算(设置页"0 = 跟随默认"的默认值来源)。 */
+export declare const LAYER_DEFAULT_BUDGETS: Record<DistillBudgetLayer, number>;
+/** resolveLayerTokens/layerEffortTrigger 需要的最小 cfg 视图(决策表用窄对象即可构造)。 */
+export interface LayerRouteCfgView {
+    llm: {
+        reasoningEffort: string;
+        primaryEffort?: string;
+        layerRoutes?: Partial<Record<LayerRouteKey, StaticFallbackEntry[]>>;
+        layerChainsRuntime?: Partial<Record<LayerRouteKey, StaticFallbackEntry[]>>;
+        budgets?: Partial<Record<DistillBudgetLayer, number>>;
+    };
+}
+/**
+ * 解析某蒸馏层的生效输出预算:运行时覆盖(cfg.llm.budgets,0/缺省 = 跟随)
+ * → 内置默认 → 思考档放大(high/xhigh/max ×4,reasoning 计入输出预算的历史事故
+ * 防线)。放大触发档位跟层走:层链头档位候选 > 全局主路由档位候选;
+ * graph 层无层链(不落 l1 路由),恒走全局候选。
+ */
+export declare function resolveLayerTokens(cfg: LayerRouteCfgView, layer: DistillBudgetLayer): number;
+/**
+ * 高思考档集合(输出预算 ×4 的档位):阶段侧 layerMaxTokens 与 callLLM 的
+ * 自动档防线共用同一张表——勿再在别处抄写该列表。
+ */
+export declare const HIGH_EFFORT_TIERS: readonly ["high", "xhigh", "max"];
+/**
+ * 思考档预算放大:reasoning 计入输出预算(v4-flash 事故:high 思考可吃光全部
+ * 预算致正文 0 字符)——effort 为 high/xhigh/max 时分层预算 ×4。
+ */
+export declare function layerMaxTokens(base: number, reasoningEffort: string): number;
+/** 解析蒸馏用的 provider/model:配置优先,其次当前默认选择。 */
+export declare function resolveModelRoute(ctx: Context, cfg: MemoryConfig): Promise<{
+    provider: string;
+    model: string;
+}>;
+/** 回退链条目(配置形态;reasoningEffort 为该路由的档位覆盖,'' = 跟随全局)。 */
+export interface FallbackRouteEntry {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** 链上单条路由(档位候选已解析:条目非空 > 全局静态;发送前仍过能力钳制)。 */
+export interface DistillRoute {
+    provider: string;
+    model: string;
+    effort: string;
+}
+/**
+ * 组装蒸馏路由链(纯决策,决策表缝):主路由在前、回退条目按配置顺序在后。
+ * provider/model 缺失的条目剔除;与主路由或先前条目完全相同(provider+model)的
+ * 条目跳过——注定失败的重复尝试不值得占位。每条路由携带生效档位候选:
+ * 主路由可带显式档位(运行时统一链注入 primaryEffort),条目档位非空覆盖全局。
+ */
+export declare function buildRouteChain(primary: {
+    provider: string;
+    model: string;
+    effort?: string;
+}, fallbacks: FallbackRouteEntry[] | undefined, globalEffort: string): DistillRoute[];
+/**
+ * DistillLayer(调用点五键)→ 路由层键(三键):l1-extract/l1-dedup 同属 l1;
+ * graph 无层路由键——返回 null,调用侧按"该层无层链"回全局解析,绝不落入 l1
+ * (图谱投影误用 L1 抽取链是路由配置错误,静默错路由最难排查)。
+ */
+export declare function layerKeyFor(layer: DistillLayer): LayerRouteKey | null;
+/** 该层的预算放大触发档位:层链头档位候选 > 全局主路由档位候选(primaryEffort > 静态全局)。
+ *  key=null(graph 层无层链)→ 恒走全局候选。 */
+export declare function layerEffortTrigger(cfg: LayerRouteCfgView, key: LayerRouteKey | null): string;
+/**
+ * 解析某次蒸馏调用的实际路由链(callLLM 入口):有层标签且该层配了层链 → 层链
+ * 完整替换(buildRouteChain 复用:头行在前、条目去重、档位三级候选);否则现行
+ * 全局解析。layer 缺省(bench/测试缝)= 全局解析。
+ */
+export declare function resolveLayerRoutes(ctx: Context, cfg: MemoryConfig, layer?: DistillLayer): Promise<DistillRoute[]>;
+/** 层链解析的同步半边(llm-providers 视图与 resolveLayerRoutes 共用一条真值路径):
+ *  该层配了有效层链 → 完整链;null = 该层跟随全局解析。 */
+export declare function layerChainOrNull(cfg: LayerRouteCfgView, key: LayerRouteKey): DistillRoute[] | null;
+export interface ModelEffortInfo {
+    /** 模型可设置的思考档位 id(适配器声明;空 = 未声明/不可设置) */
+    efforts: string[];
+    /** 适配器配置的默认档位(省略 effort 时的请求值) */
+    defaultEffort?: string;
+}
+/** 清空能力缓存(llm/adapters-updated 时调用:供应商增删/改配置后重新探询)。 */
+export declare function invalidateEffortCache(): void;
+/** 探询某模型的思考档位能力;失败返回 null(调用方保持旧发送行为,不改判)。 */
+export declare function resolveModelEfforts(ctx: Context, provider: string, model: string): Promise<ModelEffortInfo | null>;
+/**
+ * 探询某模型的上下文窗口容量(adapter 声明的 provider-owned capacity)。
+ * 与 effortCache 同源同失效策略;仅用于占用指示器的分母展示——分母必须与官方环
+ * 同源(模型声明值),禁止 client 自估。
+ */
+export declare function resolveModelContextWindow(ctx: Context, provider: string, model: string): Promise<number | null>;
+export type EffortDecisionReason = 'supported' | 'auto-default' | 'auto-high' | 'alias-none' | 'unsupported' | 'no-efforts' | 'no-capability';
+export interface EffortDecision {
+    /** 实际发送的档位;'' = 不发送(跟随模型默认) */
+    effort: string;
+    reason: EffortDecisionReason;
+}
+/** 纯决策:配置档位 + 模型能力 → 实际发送值(callLLM 与 settings-get 共用)。 */
+export declare function decideSendableEffort(cap: ModelEffortInfo | null, cfgEffort: string): EffortDecision;
+/** 探询 + 决策 + 一次性告警(不支持/未声明时提示降级,不刷屏)。 */
+export declare function planDistillEffort(ctx: Context, provider: string, model: string, cfgEffort: string, logger?: MemoryLogger): Promise<EffortDecision>;
+/**
+ * 一次完整蒸馏调用(带回退链,ADR-0004):按路由链(主路由 + llm.fallbacks)逐条
+ * 尝试,返回首个成功路由的输出。失败(error/aborted finish、网络异常、空输出)
+ * 降级下一条;调用方主动取消(signal 已中止)原样上抛不降级;全部失败抛最后一个
+ * 错误,由调用方兜底(runner 的按会话指数退避接管重试节奏)。
+ *
+ * llm.mode='direct' 时压缩首选走插件原生 HTTP(callDirect)——与付费 API 解耦;
+ * direct 失败(含未配置 baseURL/model)自动回退下方宿主路由链作兜底安全网。
+ *
+ * 文本只从 block-end(协议保证携带组装完成的整块)取;text-delta 仅在
+ * 适配器异常地没有发 block-end 时兜底。两者都累计会把输出翻倍。
+ */
+export declare function callLLM(ctx: Context, cfg: MemoryConfig, opts: LlmCallOptions): Promise<string>;
+/** 带诊断日志的 parseJson:解析失败时记录原始输出摘录(模型输出异常排查的关键信息)。 */
+export declare function parseJsonLogged<T>(raw: string, what: string, logger?: MemoryLogger): T;
+/** 容错地解析 LLM 输出的 JSON(剥掉可能的 ```json 围栏)。 */
+export declare function parseJson<T>(raw: string): T;