dsh-layered-memory 0.8.7 → 0.8.9

package/dist/index.js

@@ -39,7 +39,7 @@ 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 { resolveModelRoute, invalidateEffortCache } from './llm.js';
+import { buildRouteChain, resolveModelRoute, invalidateEffortCache } from './llm.js';
 import { effectiveCfg } from './pipeline/runner.js';
 import { initTokenCost, resetTokenCost } from './token-cost.js';
 export const name = 'dsh-memory-plugin';
@@ -170,8 +170,11 @@ export async function apply(ctx, config) {
     // 蒸馏模型路由：启动期解析一次并记录（路由错误是最难事后排查的问题之一）；
     // 用运行时调参视图解析——用户已用 UI 覆盖蒸馏模型时，日志反映实际路由
     try {
-        const route = await resolveModelRoute(ctx, effectiveCfg(config, live));
-        logger.info(`[memory] 蒸馏模型路由: ${route.provider}/${route.model}`);
+        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)}`);
@@ -304,6 +307,9 @@ export async function apply(ctx, config) {
     // 悬浮卡信息区数据源（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(),

package/dist/llm-usage.d.ts

@@ -10,7 +10,8 @@
  * 拿不到——按仓库既有口径记输入**字符**（中文 1 字 ≈ 1 token 保守折算，
  * 见 config.ts maxInputChars 注释），报告侧如实标注。
  */
-export type DistillLayer = 'l1-extract' | 'l1-dedup' | 'l2' | 'l3';
+import type { DistillLayer } from './contract.js';
+export type { DistillLayer } from './contract.js';
 export interface DistillLayerUsage {
     calls: number;
     failures: number;

package/dist/llm.d.ts

@@ -24,21 +24,28 @@ export declare const LAYER_MAX_TOKENS_DEDUP = 8000;
 export declare const LAYER_MAX_TOKENS_L2 = 32000;
 /** L3 画像（完整 persona 文档）。 */
 export declare const LAYER_MAX_TOKENS_L3 = 16000;
-/** 分层输出预算键（运行时设置 / UI 与内置默认共用同一套键名）。 */
-export type DistillBudgetLayer = 'extract' | 'dedup' | 'l2' | 'l3';
+/** 分层输出预算键（已迁入契约 src/contract.ts；import type 供本地使用，re-export 不断裂既有引用）。 */
+import type { DistillBudgetLayer, LayerRouteKey, StaticFallbackEntry } from './contract.js';
+export type { DistillBudgetLayer } from './contract.js';
 /** 各层内置默认预算（设置页"0 = 跟随默认"的默认值来源）。 */
 export declare const LAYER_DEFAULT_BUDGETS: Record<DistillBudgetLayer, number>;
-/**
- * 解析某蒸馏层的生效输出预算：运行时覆盖（cfg.llm.budgets，由 effectiveCfg 从
- * 设置页 distillBudgets 注入，0/缺省 = 跟随）→ 内置默认 → 思考档放大
- * （high/xhigh/max ×4，reasoning 计入输出预算的历史事故防线）。
- */
-export declare function resolveLayerTokens(cfg: {
+/** resolveLayerTokens/layerEffortTrigger 需要的最小 cfg 视图（smoke 决策表用窄对象即可构造）。 */
+export interface LayerRouteCfgView {
     llm: {
         reasoningEffort: string;
+        primaryEffort?: string;
+        layerRoutes?: Partial<Record<LayerRouteKey, StaticFallbackEntry[]>>;
+        layerChainsRuntime?: Partial<Record<LayerRouteKey, StaticFallbackEntry[]>>;
         budgets?: Partial<Record<DistillBudgetLayer, number>>;
     };
-}, layer: DistillBudgetLayer): number;
+}
+/**
+ * 解析某蒸馏层的生效输出预算：运行时覆盖（cfg.llm.budgets，由 effectiveCfg 从
+ * 设置页 distillBudgets 注入，0/缺省 = 跟随）→ 内置默认 → 思考档放大
+ * （high/xhigh/max ×4，reasoning 计入输出预算的历史事故防线）。放大触发档位
+ * 跟层走（#34 D8）：层链头档位候选 > 全局主路由档位候选（primaryEffort > 静态全局）。
+ */
+export declare function resolveLayerTokens(cfg: LayerRouteCfgView, layer: DistillBudgetLayer): number;
 /**
  * 高思考档集合（输出预算 ×4 的档位）：阶段侧 layerMaxTokens 与 callLLM 的
  * 自动档防线共用同一张表——此前两处字面量表分叉（防线漏 xhigh），显式 xhigh
@@ -55,6 +62,43 @@ export declare function resolveModelRoute(ctx: Context, cfg: MemoryConfig): Prom
     provider: string;
     model: string;
 }>;
+/** 回退链条目（配置形态；reasoningEffort 为该路由的档位覆盖，'' = 跟随全局）。 */
+export interface FallbackRouteEntry {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** 链上单条路由（档位候选已解析：条目非空 > 全局静态；发送前仍过能力钳制）。 */
+export interface DistillRoute {
+    provider: string;
+    model: string;
+    effort: string;
+}
+/**
+ * 组装蒸馏路由链（纯决策，smoke 决策表缝）：主路由在前、回退条目按配置顺序在后。
+ * 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。 */
+export declare function layerKeyFor(layer: DistillLayer): LayerRouteKey;
+/** 该层的预算放大触发档位（D8）：层链头档位候选 > 全局主路由档位候选（primaryEffort > 静态全局）。 */
+export declare function layerEffortTrigger(cfg: LayerRouteCfgView, key: LayerRouteKey): string;
+/**
+ * 解析某次蒸馏调用的实际路由链（callLLM 入口）：有层标签且该层配了层链 → 层链
+ * 完整替换（buildRouteChain 复用：头行在前、条目去重、档位三级候选）；否则现行
+ * 全局解析（主路由既有优先级 + fallbacks，语义一个比特不动）。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[];
@@ -65,6 +109,12 @@ export interface ModelEffortInfo {
 export declare function invalidateEffortCache(): void;
 /** 探询某模型的思考档位能力；失败返回 null（调用方保持旧发送行为，不改判）。 */
 export declare function resolveModelEfforts(ctx: Context, provider: string, model: string): Promise<ModelEffortInfo | null>;
+/**
+ * 探询某模型的上下文窗口容量（adapter 声明的 provider-owned capacity）。
+ * 与 effortCache 同源同失效策略（invalidateEffortCache 一并清空）；
+ * 仅用于占用指示器的分母展示——分母必须与官方环同源（模型声明值），禁止 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 {
     /** 实际发送的档位；'' = 不发送（跟随模型默认） */
@@ -76,8 +126,10 @@ export declare function decideSendableEffort(cap: ModelEffortInfo | null, cfgEff
 /** 探询 + 决策 + 一次性告警（不支持/未声明时提示降级，不刷屏）。 */
 export declare function planDistillEffort(ctx: Context, provider: string, model: string, cfgEffort: string, logger?: MemoryLogger): Promise<EffortDecision>;
 /**
- * 一次完整蒸馏调用：流式收集文本，返回最终字符串。
- * 失败（error/aborted finish）抛错，由调用方兜底。
+ * 一次完整蒸馏调用（带回退链，ADR-0004）：按路由链（主路由 + llm.fallbacks）逐条
+ * 尝试，返回首个成功路由的输出。失败（error/aborted finish、网络异常、空输出）
+ * 降级下一条；调用方主动取消（signal 已中止）原样上抛不降级；全部失败抛最后一个
+ * 错误，由调用方兜底（runner 的按会话指数退避接管重试节奏）。
  *
  * 文本只从 block-end（协议保证携带**组装完成的整块**）取；text-delta 仅在
  * 适配器异常地没有发 block-end 时兜底。两者都累计会把输出翻倍。

package/dist/llm.js

@@ -22,11 +22,13 @@ export const LAYER_DEFAULT_BUDGETS = {
 /**
  * 解析某蒸馏层的生效输出预算：运行时覆盖（cfg.llm.budgets，由 effectiveCfg 从
  * 设置页 distillBudgets 注入，0/缺省 = 跟随）→ 内置默认 → 思考档放大
- * （high/xhigh/max ×4，reasoning 计入输出预算的历史事故防线）。
+ * （high/xhigh/max ×4，reasoning 计入输出预算的历史事故防线）。放大触发档位
+ * 跟层走（#34 D8）：层链头档位候选 > 全局主路由档位候选（primaryEffort > 静态全局）。
  */
 export function resolveLayerTokens(cfg, layer) {
     const override = cfg.llm.budgets?.[layer];
-    return layerMaxTokens(override && override > 0 ? override : LAYER_DEFAULT_BUDGETS[layer], cfg.llm.reasoningEffort);
+    const key = layer === 'l2' ? 'l2' : layer === 'l3' ? 'l3' : 'l1';
+    return layerMaxTokens(override && override > 0 ? override : LAYER_DEFAULT_BUDGETS[layer], layerEffortTrigger(cfg, key));
 }
 /**
  * 高思考档集合（输出预算 ×4 的档位）：阶段侧 layerMaxTokens 与 callLLM 的
@@ -54,11 +56,98 @@ export async function resolveModelRoute(ctx, cfg) {
     }
     throw new Error('无法解析蒸馏模型路由：请在插件 config 中配置 llm.provider / llm.model，或确保存在默认模型选择');
 }
+/**
+ * 组装蒸馏路由链（纯决策，smoke 决策表缝）：主路由在前、回退条目按配置顺序在后。
+ * provider/model 缺失的条目剔除；与主路由或先前条目完全相同（provider+model）的
+ * 条目跳过——注定失败的重复尝试不值得占位。每条路由携带生效档位候选：
+ * 主路由可带显式档位（运行时统一链注入 primaryEffort），条目档位非空覆盖全局。
+ */
+export function buildRouteChain(primary, fallbacks, globalEffort) {
+    const routes = [{ ...primary, effort: primary.effort || globalEffort }];
+    const seen = new Set([`${primary.provider}::${primary.model}`]);
+    for (const f of fallbacks ?? []) {
+        if (!f.provider || !f.model)
+            continue;
+        const key = `${f.provider}::${f.model}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        routes.push({ provider: f.provider, model: f.model, effort: f.reasoningEffort || globalEffort });
+    }
+    return routes;
+}
+// ── 按层独立路由（#34 / ADR-0005）：层内三级 运行时层链 > 静态层链 > 全局解析 ──
+// 层链非空即完整替换该层解析（该层主路由与回退都归层链管，全局链对该层不参与）；
+// 档位是全局偏好轴：层链空档位条目/头行仍回退全局档位（primaryEffort 之后的
+// cfg.llm.reasoningEffort 语义照旧）。pin 只废运行时侧（effectiveCfg 不注入），
+// 静态层链天然穿透——与回退链"静态配置不构成 pin 绕过"先例同源。
+/** DistillLayer（调用点四键）→ 路由层键（三键）：l1-extract/l1-dedup 同属 l1。 */
+export function layerKeyFor(layer) {
+    return layer === 'l2' ? 'l2' : layer === 'l3' ? 'l3' : 'l1';
+}
+/**
+ * 取某层的生效层链（运行时优先）。头行残缺（provider/model 缺失——手写 YAML 错误
+ * 或防御性解析后的空链头）视为该层未配置、回退全局解析：路由配置错误不致该层
+ * 蒸馏失产，与回退链"条目缺失剔除"同一防御姿态。
+ */
+function layerChainOf(cfg, key) {
+    const rt = cfg.llm.layerChainsRuntime?.[key];
+    if (rt?.length && rt[0].provider && rt[0].model)
+        return rt;
+    const st = cfg.llm.layerRoutes?.[key];
+    if (st?.length && st[0].provider && st[0].model)
+        return st;
+    return undefined;
+}
+/** 该层的预算放大触发档位（D8）：层链头档位候选 > 全局主路由档位候选（primaryEffort > 静态全局）。 */
+export function layerEffortTrigger(cfg, key) {
+    const chain = layerChainOf(cfg, key);
+    return chain
+        ? chain[0].reasoningEffort || cfg.llm.primaryEffort || cfg.llm.reasoningEffort
+        : cfg.llm.primaryEffort || cfg.llm.reasoningEffort;
+}
+/**
+ * 解析某次蒸馏调用的实际路由链（callLLM 入口）：有层标签且该层配了层链 → 层链
+ * 完整替换（buildRouteChain 复用：头行在前、条目去重、档位三级候选）；否则现行
+ * 全局解析（主路由既有优先级 + fallbacks，语义一个比特不动）。layer 缺省
+ * （bench/测试缝）= 全局解析。
+ */
+export async function resolveLayerRoutes(ctx, cfg, layer) {
+    const key = layer ? layerKeyFor(layer) : undefined;
+    const lr = key ? layerChainOrNull(cfg, key) : null;
+    if (lr)
+        return lr;
+    const primary = await resolveModelRoute(ctx, cfg);
+    return buildRouteChain(
+    // 主路由显式档位来自运行时统一链（primaryEffort，'' = 跟随全局静态）
+    { provider: primary.provider, model: primary.model, effort: cfg.llm.primaryEffort || '' }, cfg.llm.fallbacks, cfg.llm.reasoningEffort);
+}
+/** 层链解析的同步半边（llm-providers 视图与 resolveLayerRoutes 共用一条真值路径）：
+ *  该层配了有效层链 → 完整链；null = 该层跟随全局解析。 */
+export function layerChainOrNull(cfg, key) {
+    const chain = layerChainOf(cfg, key);
+    if (!chain)
+        return null;
+    return buildRouteChain({ provider: chain[0].provider, model: chain[0].model, effort: chain[0].reasoningEffort || '' }, chain.slice(1), cfg.llm.reasoningEffort);
+}
+/** 单路由持续失败的一次性告警去重表（effortWarned 同款；拓扑变化随能力缓存一起失效）。 */
+const routeDeadWarned = new Set();
+function warnRouteDeadOnce(route, logger) {
+    if (!logger)
+        return;
+    const key = `${route.provider}::${route.model}`;
+    if (routeDeadWarned.has(key))
+        return;
+    routeDeadWarned.add(key);
+    logger.warn(`[memory] 蒸馏路由 ${route.provider}/${route.model} 失败（每路由仅告警一次；逐次失败原因与降级去向见后续日志）`);
+}
 const effortCache = new Map();
 /** 清空能力缓存（llm/adapters-updated 时调用：供应商增删/改配置后重新探询）。 */
 export function invalidateEffortCache() {
     effortCache.clear();
+    contextWindowCache.clear();
     effortWarned.clear();
+    routeDeadWarned.clear();
 }
 /** 探询某模型的思考档位能力；失败返回 null（调用方保持旧发送行为，不改判）。 */
 export async function resolveModelEfforts(ctx, provider, model) {
@@ -84,6 +173,30 @@ export async function resolveModelEfforts(ctx, provider, model) {
         return null; // 不缓存失败：路由尚未注册等瞬时态，下次调用重试
     }
 }
+/** (provider, model) → 上下文窗口 token 数；advisory，未声明/失败为 null。 */
+const contextWindowCache = new Map();
+/**
+ * 探询某模型的上下文窗口容量（adapter 声明的 provider-owned capacity）。
+ * 与 effortCache 同源同失效策略（invalidateEffortCache 一并清空）；
+ * 仅用于占用指示器的分母展示——分母必须与官方环同源（模型声明值），禁止 client 自估。
+ */
+export async function resolveModelContextWindow(ctx, provider, model) {
+    const key = `${provider}::${model}`;
+    if (contextWindowCache.has(key))
+        return contextWindowCache.get(key) ?? null;
+    try {
+        if (typeof ctx.llm?.resolveModelInfo !== 'function')
+            return null;
+        const info = await ctx.llm.resolveModelInfo(provider, model);
+        const win = info.context?.contextWindow;
+        const val = typeof win === 'number' && Number.isFinite(win) && win > 0 ? Math.floor(win) : null;
+        contextWindowCache.set(key, val);
+        return val;
+    }
+    catch {
+        return null; // 不缓存失败：下次调用重试
+    }
+}
 /** 纯决策：配置档位 + 模型能力 → 实际发送值（callLLM 与 settings-get 共用）。 */
 export function decideSendableEffort(cap, cfgEffort) {
     if (!cap)
@@ -124,29 +237,59 @@ export async function planDistillEffort(ctx, provider, model, cfgEffort, logger)
     return d;
 }
 /**
- * 一次完整蒸馏调用：流式收集文本，返回最终字符串。
- * 失败（error/aborted finish）抛错，由调用方兜底。
+ * 一次完整蒸馏调用（带回退链，ADR-0004）：按路由链（主路由 + llm.fallbacks）逐条
+ * 尝试，返回首个成功路由的输出。失败（error/aborted finish、网络异常、空输出）
+ * 降级下一条；调用方主动取消（signal 已中止）原样上抛不降级；全部失败抛最后一个
+ * 错误，由调用方兜底（runner 的按会话指数退避接管重试节奏）。
  *
  * 文本只从 block-end（协议保证携带**组装完成的整块**）取；text-delta 仅在
  * 适配器异常地没有发 block-end 时兜底。两者都累计会把输出翻倍。
  */
 export async function callLLM(ctx, cfg, opts) {
-    const { provider, model } = await resolveModelRoute(ctx, cfg);
+    // 按层路由（#34）：opts.layer 配了层链的层走层链完整替换，其余走全局解析
+    const routes = await resolveLayerRoutes(ctx, cfg, opts.layer);
+    let lastErr;
+    for (let i = 0; i < routes.length; i++) {
+        const route = routes[i];
+        try {
+            return await callRoute(ctx, cfg, opts, route);
+        }
+        catch (err) {
+            // 调用方主动取消（重建取消/进程关闭）不是路由失败——不降级，原样上抛
+            if (opts.signal?.aborted)
+                throw err;
+            lastErr = err;
+            warnRouteDeadOnce(route, opts.logger);
+            const next = routes[i + 1];
+            if (next) {
+                opts.logger?.info(`[memory] 蒸馏路由降级 ${route.provider}/${route.model} → ${next.provider}/${next.model}（${errDetail(err)}）`);
+            }
+        }
+    }
+    throw lastErr;
+}
+/** 单路由一次尝试（callLLM 循环体；每路由新建超时信号 = 各享全额 timeoutMs）。 */
+async function callRoute(ctx, cfg, opts, route) {
+    const { provider, model } = route;
     const signal = opts.signal ?? AbortSignal.timeout(cfg.llm.timeoutMs);
     // 档位按模型能力决策（跨供应商 effort 兼容）：不支持的档位不传 + 告警一次，
-    // 空配置 = 自动（模型默认档 → high）；详见 decideSendableEffort
-    const effort = await planDistillEffort(ctx, provider, model, cfg.llm.reasoningEffort, opts.logger);
+    // 空配置 = 自动（模型默认 → high）；路由的档位候选已在链解析时定好（条目 > 全局）
+    const effort = await planDistillEffort(ctx, provider, model, route.effort, opts.logger);
     // 输入预算兜底：任何蒸馏调用的用户 prompt 不超过 maxInputChars
     // （L1 已在数据层分块，这里是 L2/L3 与异常场景的最后一道网）
     const user = opts.user.length > cfg.llm.maxInputChars
         ? `${opts.user.slice(0, cfg.llm.maxInputChars)}\n\n[输入超出 ${cfg.llm.maxInputChars} 字符预算，已截断]`
         : opts.user;
-    // 输出预算 ×4 防线跟随【实际发送】的档位：阶段侧已按原始配置的高档位
-    // （HIGH_EFFORT_TIERS）放大过，这里只补自动档（'' → 模型默认/高档）解析出
-    // 高档时的欠放大缺口——两侧共用一张表，配置本身就是高档时不再放大（防 ×16 双乘）
+    // 输出预算 ×4 防线跟随【实际发送】的档位：阶段侧已按该层放大触发档位
+    // （layerEffortTrigger：层链头候选 > 全局主路由候选）放大过，这里只补自动档
+    // （'' → 模型默认/高档）解析出高档时的欠放大缺口——两侧共用一张表与同一触发值，
+    // 配置本身就是高档时不再放大（防 ×16 双乘）
     const baseMaxTokens = opts.maxTokens ?? cfg.llm.maxTokens;
     const highTiers = HIGH_EFFORT_TIERS;
-    const maxTokens = highTiers.includes(effort.effort) && !highTiers.includes(cfg.llm.reasoningEffort)
+    const triggerEffort = opts.layer
+        ? layerEffortTrigger(cfg, layerKeyFor(opts.layer))
+        : cfg.llm.primaryEffort || cfg.llm.reasoningEffort;
+    const maxTokens = highTiers.includes(effort.effort) && !highTiers.includes(triggerEffort)
         ? layerMaxTokens(baseMaxTokens, 'high')
         : baseMaxTokens;
     const stream = ctx.llm.stream({
@@ -209,20 +352,27 @@ export async function callLLM(ctx, cfg, opts) {
         opts.logger?.warn(`[memory] LLM 调用失败 ${provider}/${model}（${((Date.now() - startedAt) / 1000).toFixed(1)}s）: ${errDetail(err)}`);
         throw err;
     }
-    if (opts.layer)
-        recordDistillCall(opts.layer, user.length, outputTokens, reasoningTokens, false);
-    if (opts.layer)
-        recordCostCall(provider, model, opts.layer, user.length, outputTokens, reasoningTokens);
     const out = (blockText || deltaText).trim();
     if (out.length === 0) {
         // 空输出是最难排查的失败：流正常结束但一个字没吐。必须记录 finish 原因、
         // token 计数与块分布，才能区分"模型只产出了 reasoning"vs"服务端返回空响应"。
+        if (opts.layer)
+            recordDistillCall(opts.layer, user.length, outputTokens, reasoningTokens, true);
+        if (opts.layer)
+            recordCostCall(provider, model, opts.layer, user.length, outputTokens, reasoningTokens);
         opts.logger?.warn(`[memory] LLM 空输出 ${provider}/${model}（${((Date.now() - startedAt) / 1000).toFixed(1)}s，finish=${finishKind || '无 finish 块'}` +
             `，输出 tokens=${outputTokens}${reasoningTokens > 0 ? `/reasoning ${reasoningTokens}` : ''}，` +
             `text-delta ${deltaBlocks} 块/${deltaText.length} 字符，reasoning ${reasoningChars} 字符，` +
             `block-end: ${[...blockEndTypes.entries()].map(([t, n]) => `${t}×${n}`).join(', ') || '无'}）` +
             (reasoningHead ? `，reasoning 摘录: ${reasoningHead}…` : ''));
+        // 空输出按路由失败处理（#31）：交给回退链降级或上抛——原先返回空串只是把失败
+        // 推迟到下游 JSON/Markdown 解析，诊断信息更差
+        throw new Error(`llm empty output: ${provider}/${model} 流正常结束但输出 0 字符`);
     }
+    if (opts.layer)
+        recordDistillCall(opts.layer, user.length, outputTokens, reasoningTokens, false);
+    if (opts.layer)
+        recordCostCall(provider, model, opts.layer, user.length, outputTokens, reasoningTokens);
     opts.logger?.info(`[memory] LLM 调用 ${provider}/${model}：输入 ${user.length} 字符 → 输出 ${out.length} 字符（${((Date.now() - startedAt) / 1000).toFixed(1)}s，finish=${finishKind || '无'}）`);
     return out;
 }

package/dist/pipeline/rebuild.d.ts

@@ -15,27 +15,8 @@ export interface RebuildStores {
     persona: Record<MemoryFamily, PersonaStore>;
     state: StateStore;
 }
-export type RebuildPhase = 'idle' | 'preparing' | 'distilling' | 'finalizing' | 'done' | 'cancelled' | 'failed';
-export interface RebuildStatus {
-    running: boolean;
-    phase: RebuildPhase;
-    /** 已完成的会话块数 / 总块数。 */
-    done: number;
-    total: number;
-    /** L0 体量（idle 时为实时预估，运行中为快照值）。 */
-    sessionCount: number;
-    messageCount: number;
-    /** 预计 LLM 抽取调用次数（下界估算：块数与字符预算取大）。 */
-    estCalls: number;
-    /** 重建产出的 L1 记录累计条数。 */
-    recordsBuilt: number;
-    cancelRequested: boolean;
-    startedAt: number | null;
-    finishedAt: number | null;
-    error: string | null;
-    /** 归档产物名（提示用户可手工找回）。 */
-    archiveNote: string | null;
-}
+import type { RebuildStatus } from '../contract.js';
+export type { RebuildPhase, RebuildStatus } from '../contract.js';
 export interface RebuildChunk {
     sessionId: string;
     messages: ConversationMessage[];

package/dist/pipeline/runner.d.ts

@@ -36,9 +36,9 @@ export interface PipelineTask {
 /** 选取下一个要执行的任务下标：最早的 live 优先，否则队首（rebuild 分块让位）。 */
 export declare function pickNextTaskIndex(tasks: PipelineTask[]): number;
 /**
- * 运行时调参视图：UI 选择器可临时覆盖蒸馏思考档位、蒸馏模型路由与分层输出预算
- * （空串/0 回退静态 config / 内置默认）。浅拷贝只覆盖 llm 一层，其余键与原 cfg
- * 共享只读引用；pipeline 全链继续收 cfg，无需感知。
+ * 运行时调参视图：设置页运行时链（distillChain）与旧单路由/档位键、分层输出预算
+ * 可临时覆盖静态 config（空串/0 回退静态 config / 内置默认）。浅拷贝只覆盖 llm
+ * 一层，其余键与原 cfg 共享只读引用；pipeline 全链继续收 cfg，无需感知。
  *
  * 蒸馏模型覆盖优先级：部署静态 pin（cfg.llm.provider+model 双字段齐）不可被
  * 运行时覆盖（部署可强制蒸馏走内网路由，防用户选择把对话外送）；未 pin 时

package/dist/pipeline/runner.js

@@ -14,9 +14,9 @@ export function pickNextTaskIndex(tasks) {
     return 0;
 }
 /**
- * 运行时调参视图：UI 选择器可临时覆盖蒸馏思考档位、蒸馏模型路由与分层输出预算
- * （空串/0 回退静态 config / 内置默认）。浅拷贝只覆盖 llm 一层，其余键与原 cfg
- * 共享只读引用；pipeline 全链继续收 cfg，无需感知。
+ * 运行时调参视图：设置页运行时链（distillChain）与旧单路由/档位键、分层输出预算
+ * 可临时覆盖静态 config（空串/0 回退静态 config / 内置默认）。浅拷贝只覆盖 llm
+ * 一层，其余键与原 cfg 共享只读引用；pipeline 全链继续收 cfg，无需感知。
  *
  * 蒸馏模型覆盖优先级：部署静态 pin（cfg.llm.provider+model 双字段齐）不可被
  * 运行时覆盖（部署可强制蒸馏走内网路由，防用户选择把对话外送）；未 pin 时
@@ -26,13 +26,31 @@ export function pickNextTaskIndex(tasks) {
 export function effectiveCfg(cfg, live) {
     const s = live?.get();
     // 思考档位：设置服务在场时运行时值整体接管——'' = 自动（按模型能力解析），
-    // 不再回退静态配置（"跟随配置"选项已删）；静态值仅无 settings 服务的部署生效
+    // 不再回退静态配置（"跟随配置"选项已删）；静态值仅无 settings 服务的部署生效。
+    // 统一路由链模式下（chain 非空）旧档位键不再参与：链内每条路由自带档位候选
     const eff = s?.reasoningEffort ?? '';
     // 可选链防御：smoke/测试缝构造的最小 cfg 可能没有 llm 字段
     const pinned = Boolean(cfg.llm?.provider && cfg.llm?.model);
-    const override = s && !pinned && s.distillProvider && s.distillModel
-        ? { provider: s.distillProvider, model: s.distillModel }
+    // 运行时统一路由链：**只认显式 distillChain**（非空即权威——主路由档位走
+    // primaryEffort、条目档位随链注入 fallbacks、旧键与全局档位接管让位）；
+    // 未配置链时旧键（distillProvider/distillModel/reasoningEffort）走下方完全
+    // 不变的旧路径——旧存量值的语义一个比特都不动（projectDistillChain 只是
+    // llm-providers 的 UI 展示视图，不参与生效逻辑）。
+    // pinned 时链整体失效（部署锁定路由，链编辑器只读）
+    const chain = s?.distillChain?.length ? s.distillChain : [];
+    const chainMode = chain.length > 0 && !pinned;
+    const chainEffort = chainMode && chain[0].reasoningEffort ? chain[0].reasoningEffort : null;
+    // 链非空即整体接管：回退链以运行时链为准（slice(1)），**单行链 = 显式无回退**
+    // （空数组覆盖静态 cfg.llm.fallbacks——"UI 所见即所跑"，审查修复的语义不对称：
+    // 此前单显式行不清静态、单空主路由行清静态，同一意图两种表达）
+    const chainFallbacks = chainMode
+        ? chain.slice(1).map((e) => ({ provider: e.provider, model: e.model, reasoningEffort: e.reasoningEffort || '' }))
         : null;
+    const override = chainMode && chain[0].provider && chain[0].model
+        ? { provider: chain[0].provider, model: chain[0].model }
+        : !chain.length && s && !pinned && s.distillProvider && s.distillModel
+            ? { provider: s.distillProvider, model: s.distillModel }
+            : null;
     const b = s?.distillBudgets;
     const budgets = b && (b.extract > 0 || b.dedup > 0 || b.l2 > 0 || b.l3 > 0)
         ? {
@@ -42,19 +60,43 @@ export function effectiveCfg(cfg, live) {
             ...(b.l3 > 0 ? { l3: b.l3 } : {}),
         }
         : null;
+    // 运行时按层路由链（#34）：非空层链逐层注入 layerChainsRuntime（解析侧层内第一
+    // 优先级）；pinned = 部署锁，运行时层链与运行时全局链一并失效（同 chainMode 的
+    // pinned 处理）；全部层为空 = 无注入（返回引用不变路径不受影响）。层键逐个
+    // ?.length 容忍部分键缺失（旧存量 settings / 手写覆盖可能只带部分层）
+    const lc = s?.distillLayerChains;
+    const layerPick = lc && !pinned
+        ? {
+            ...(lc.l1?.length ? { l1: lc.l1 } : {}),
+            ...(lc.l2?.length ? { l2: lc.l2 } : {}),
+            ...(lc.l3?.length ? { l3: lc.l3 } : {}),
+        }
+        : null;
+    const layerChains = layerPick && Object.keys(layerPick).length ? layerPick : null;
     const maxInput = s && s.distillMaxInputChars > 0 ? s.distillMaxInputChars : null;
-    // 无任何注入且（无 live，或运行时 '' 且静态本就 ''）→ 原引用返回，保持引用稳定性
-    const effNoop = eff === '' && (!live || !cfg.llm?.reasoningEffort);
-    if (!override && !budgets && !maxInput && effNoop)
+    // 旧档位键的全局接管（含给静态回退条目盖章）：仅非链模式保留（旧存量值兼容）
+    const fallbacksTakeover = !chainMode && eff && cfg.llm?.fallbacks?.length
+        ? cfg.llm.fallbacks.map((f) => ({ ...f, reasoningEffort: eff }))
+        : null;
+    // 档位注入：链模式下不走全局接管（主路由档位走 primaryEffort、条目档位在链内，
+    // 空档位条目回退的是静态全局而非运行时旧键）；非链模式保持旧整体接管语义
+    const effortInject = live && !chainMode && (eff !== '' || Boolean(cfg.llm?.reasoningEffort))
+        ? { reasoningEffort: eff }
+        : null;
+    if (!override && !budgets && !maxInput && !fallbacksTakeover && !chainEffort && !chainFallbacks && !effortInject && !layerChains)
         return cfg;
     return {
         ...cfg,
         llm: {
             ...cfg.llm,
-            ...(live ? { reasoningEffort: eff } : {}),
+            ...(effortInject ?? {}),
             ...(override ?? {}),
             ...(budgets ? { budgets } : {}),
             ...(maxInput ? { maxInputChars: maxInput } : {}),
+            ...(fallbacksTakeover ? { fallbacks: fallbacksTakeover } : {}),
+            ...(chainEffort ? { primaryEffort: chainEffort } : {}),
+            ...(chainFallbacks ? { fallbacks: chainFallbacks } : {}),
+            ...(layerChains ? { layerChainsRuntime: layerChains } : {}),
         },
     };
 }

package/dist/settings.d.ts

@@ -5,36 +5,32 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
-import { EFFORT_CHOICES } from './config.js';
-import type { DistillBudgetLayer } from './llm.js';
 import type { MemoryLogger } from './types.js';
-/** 蒸馏思考档位：'' = 自动（模型默认档 → high）；词汇表单源于 config.ts 的 EFFORT_CHOICES。 */
-export type EffortChoice = (typeof EFFORT_CHOICES)[number];
-/** 分层输出预算（与 llm.ts 的 DistillBudgetLayer 同键；0 = 跟随内置默认）。 */
-export type DistillBudgets = Record<DistillBudgetLayer, number>;
-export interface MemoryLiveSettings {
-    /** 总开关：关 = 捕获/蒸馏/召回注入全停（数据保留） */
-    enabled: boolean;
-    /** L0 捕获（原始对话落盘） */
-    capture: boolean;
-    /** L1 抽取 + L2/L3 蒸馏 */
-    distill: boolean;
-    /** 召回注入（画像/记忆上下文） */
-    recall: boolean;
-    /** 蒸馏思考档位运行时覆盖：'' = 跟随静态 config（llm.reasoningEffort） */
-    reasoningEffort: EffortChoice;
-    /** 蒸馏模型运行时覆盖（供应商 id，用户已配置的路由）：'' = 跟随静态 config/默认选择。
-     *  与 distillModel 成对生效（单字段不算）；部署静态 pin（provider+model 双字段）优先。 */
-    distillProvider: string;
-    /** 蒸馏模型运行时覆盖（模型 id）：'' = 跟随静态 config/默认选择。 */
-    distillModel: string;
-    /** 分层输出预算运行时覆盖（token）：extract/dedup/l2/l3 四层，0 = 跟随内置默认；
-     *  思考档 high/max 的 ×4 放大在覆盖值之上照常生效。 */
-    distillBudgets: DistillBudgets;
-    /** 输入预算运行时覆盖（字符，≈token）：单次蒸馏调用的输入上限，L1 按此分块、
-     *  超限截断；0 = 跟随静态配置 llm.maxInputChars。 */
-    distillMaxInputChars: number;
-}
+import type { DistillChainEntry, MemoryLiveSettings } from './contract.js';
+export type { DistillBudgets, DistillChainEntry, EffortChoice, MemoryLiveSettings } from './contract.js';
+/**
+ * 运行时统一路由链条目：[0] = 主路由（provider/model 双空 = 跟随默认模型），
+ * [1..] = 回退链（按序降级）；reasoningEffort 为该路由的档位覆盖（'' = 跟随部署全局）。
+ */
+/** 运行时路由链上限（写入门与 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（#34 层链用）：头行必须 provider+model 双显式——层键出现
+ * 即意图覆盖；"双空 = 跟随默认模型"是全局链独有语义（"默认模型 + 自定义回退"的
+ * 诉求由全局 llm.fallbacks 承担），层链禁掉双空头，消除"层链头跟随哪套全局解析"的歧义。
+ */
+export declare function validateDistillChain(chain: unknown, opts?: {
+    requireExplicitHead?: boolean;
+}): string | null;
 export interface LiveSettingsHandle {
     /** settings 服务是否可用（不可用时 UI 侧隐藏开关面板） */
     supported: boolean;