dsh-layered-memory 0.8.7 → 0.8.8

package/dist/index.d.ts

@@ -59,7 +59,7 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
         timeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
         includePersona: import("@deepseek-ai/schemastery").default<boolean, boolean>;
         includeSceneNav: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-        strategy: import("@deepseek-ai/schemastery").default<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
+        strategy: import("@deepseek-ai/schemastery").default<"hybrid" | "keyword" | "embedding", "hybrid" | "keyword" | "embedding">;
         scoreThreshold: import("@deepseek-ai/schemastery").default<number, number>;
         decayHalfLifeDays: import("@deepseek-ai/schemastery").default<number, number>;
     }>, Schemastery.ObjectT<{
@@ -70,7 +70,7 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
         timeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
         includePersona: import("@deepseek-ai/schemastery").default<boolean, boolean>;
         includeSceneNav: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-        strategy: import("@deepseek-ai/schemastery").default<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
+        strategy: import("@deepseek-ai/schemastery").default<"hybrid" | "keyword" | "embedding", "hybrid" | "keyword" | "embedding">;
         scoreThreshold: import("@deepseek-ai/schemastery").default<number, number>;
         decayHalfLifeDays: import("@deepseek-ai/schemastery").default<number, number>;
     }>>;
@@ -100,6 +100,15 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     llm: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
         provider: import("@deepseek-ai/schemastery").default<string, string>;
         model: import("@deepseek-ai/schemastery").default<string, string>;
+        fallbacks: import("@deepseek-ai/schemastery").default<({
+            provider?: string | null | undefined;
+            model?: string | null | undefined;
+            reasoningEffort?: "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | null | undefined;
+        } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<{
+            provider: import("@deepseek-ai/schemastery").default<string, string>;
+            model: import("@deepseek-ai/schemastery").default<string, string>;
+            reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
+        }>[]>;
         maxTokens: import("@deepseek-ai/schemastery").default<number, number>;
         reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
         temperature: import("@deepseek-ai/schemastery").default<number, number>;
@@ -108,6 +117,15 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     }>, Schemastery.ObjectT<{
         provider: import("@deepseek-ai/schemastery").default<string, string>;
         model: import("@deepseek-ai/schemastery").default<string, string>;
+        fallbacks: import("@deepseek-ai/schemastery").default<({
+            provider?: string | null | undefined;
+            model?: string | null | undefined;
+            reasoningEffort?: "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | null | undefined;
+        } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<{
+            provider: import("@deepseek-ai/schemastery").default<string, string>;
+            model: import("@deepseek-ai/schemastery").default<string, string>;
+            reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
+        }>[]>;
         maxTokens: import("@deepseek-ai/schemastery").default<number, number>;
         reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
         temperature: import("@deepseek-ai/schemastery").default<number, number>;
@@ -172,7 +190,7 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
         timeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
         includePersona: import("@deepseek-ai/schemastery").default<boolean, boolean>;
         includeSceneNav: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-        strategy: import("@deepseek-ai/schemastery").default<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
+        strategy: import("@deepseek-ai/schemastery").default<"hybrid" | "keyword" | "embedding", "hybrid" | "keyword" | "embedding">;
         scoreThreshold: import("@deepseek-ai/schemastery").default<number, number>;
         decayHalfLifeDays: import("@deepseek-ai/schemastery").default<number, number>;
     }>, Schemastery.ObjectT<{
@@ -183,7 +201,7 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
         timeoutMs: import("@deepseek-ai/schemastery").default<number, number>;
         includePersona: import("@deepseek-ai/schemastery").default<boolean, boolean>;
         includeSceneNav: import("@deepseek-ai/schemastery").default<boolean, boolean>;
-        strategy: import("@deepseek-ai/schemastery").default<"keyword" | "embedding" | "hybrid", "keyword" | "embedding" | "hybrid">;
+        strategy: import("@deepseek-ai/schemastery").default<"hybrid" | "keyword" | "embedding", "hybrid" | "keyword" | "embedding">;
         scoreThreshold: import("@deepseek-ai/schemastery").default<number, number>;
         decayHalfLifeDays: import("@deepseek-ai/schemastery").default<number, number>;
     }>>;
@@ -213,6 +231,15 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     llm: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
         provider: import("@deepseek-ai/schemastery").default<string, string>;
         model: import("@deepseek-ai/schemastery").default<string, string>;
+        fallbacks: import("@deepseek-ai/schemastery").default<({
+            provider?: string | null | undefined;
+            model?: string | null | undefined;
+            reasoningEffort?: "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | null | undefined;
+        } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<{
+            provider: import("@deepseek-ai/schemastery").default<string, string>;
+            model: import("@deepseek-ai/schemastery").default<string, string>;
+            reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
+        }>[]>;
         maxTokens: import("@deepseek-ai/schemastery").default<number, number>;
         reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
         temperature: import("@deepseek-ai/schemastery").default<number, number>;
@@ -221,6 +248,15 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     }>, Schemastery.ObjectT<{
         provider: import("@deepseek-ai/schemastery").default<string, string>;
         model: import("@deepseek-ai/schemastery").default<string, string>;
+        fallbacks: import("@deepseek-ai/schemastery").default<({
+            provider?: string | null | undefined;
+            model?: string | null | undefined;
+            reasoningEffort?: "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | null | undefined;
+        } & import("@deepseek-ai/cosmokit").Dict)[], Schemastery.ObjectT<{
+            provider: import("@deepseek-ai/schemastery").default<string, string>;
+            model: import("@deepseek-ai/schemastery").default<string, string>;
+            reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
+        }>[]>;
         maxTokens: import("@deepseek-ai/schemastery").default<number, number>;
         reasoningEffort: import("@deepseek-ai/schemastery").default<"" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", "" | "off" | "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max">;
         temperature: import("@deepseek-ai/schemastery").default<number, number>;

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)}`);

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,8 +24,9 @@ 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 } from './contract.js';
+export type { DistillBudgetLayer } from './contract.js';
 /** 各层内置默认预算（设置页"0 = 跟随默认"的默认值来源）。 */
 export declare const LAYER_DEFAULT_BUDGETS: Record<DistillBudgetLayer, number>;
 /**
@@ -55,6 +56,29 @@ 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[];
 export interface ModelEffortInfo {
     /** 模型可设置的思考档位 id（适配器声明；空 = 未声明/不可设置） */
     efforts: string[];
@@ -76,8 +100,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

@@ -54,11 +54,43 @@ 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;
+}
+/** 单路由持续失败的一次性告警去重表（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();
     effortWarned.clear();
+    routeDeadWarned.clear();
 }
 /** 探询某模型的思考档位能力；失败返回 null（调用方保持旧发送行为，不改判）。 */
 export async function resolveModelEfforts(ctx, provider, model) {
@@ -124,18 +156,46 @@ 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);
+    const primary = await resolveModelRoute(ctx, cfg);
+    const routes = buildRouteChain(
+    // 主路由显式档位来自运行时统一链（primaryEffort，'' = 跟随全局静态）
+    { provider: primary.provider, model: primary.model, effort: cfg.llm.primaryEffort || '' }, cfg.llm.fallbacks, cfg.llm.reasoningEffort);
+    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
@@ -209,20 +269,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)
         ? {
@@ -43,18 +61,28 @@ export function effectiveCfg(cfg, live) {
         }
         : 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)
         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 } : {}),
         },
     };
 }

package/dist/settings.d.ts

@@ -5,36 +5,25 @@
  */
 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 = 通过）。 */
+export declare function validateDistillChain(chain: unknown): string | null;
 export interface LiveSettingsHandle {
     /** settings 服务是否可用（不可用时 UI 侧隐藏开关面板） */
     supported: boolean;

package/dist/settings.js

@@ -1,6 +1,61 @@
 import Schema from '@deepseek-ai/schemastery';
 import { settingsNamespace } from '@deepseek-ai/dsh-settings';
 import { EFFORT_CHOICES } from './config.js';
+/**
+ * 运行时统一路由链条目：[0] = 主路由（provider/model 双空 = 跟随默认模型），
+ * [1..] = 回退链（按序降级）；reasoningEffort 为该路由的档位覆盖（'' = 跟随部署全局）。
+ */
+/** 运行时路由链上限（写入门与 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 = 通过）。 */
+export function validateDistillChain(chain) {
+    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 ((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 = settingsNamespace('dsh-memory');
 const ALWAYS_ON = {
     enabled: true,
@@ -10,6 +65,7 @@ const ALWAYS_ON = {
     reasoningEffort: '',
     distillProvider: '',
     distillModel: '',
+    distillChain: [],
     distillBudgets: { extract: 0, dedup: 0, l2: 0, l3: 0 },
     distillMaxInputChars: 0,
 };
@@ -40,6 +96,11 @@ export function liveSettingsSchema() {
         reasoningEffort: Schema.union([...EFFORT_CHOICES]).default(''),
         distillProvider: Schema.string().default(''),
         distillModel: Schema.string().default(''),
+        distillChain: Schema.array(Schema.object({
+            provider: Schema.string().default(''),
+            model: Schema.string().default(''),
+            reasoningEffort: Schema.union([...EFFORT_CHOICES]).default(''),
+        })).default([]),
         distillBudgets: Schema.object({
             extract: budget(),
             dedup: budget(),
@@ -153,10 +214,28 @@ export function registerLiveSettings(ctx, logger) {
 /** scope.get() 的防御性解析：异常值回退全开（宁可多记不可静默停摆）。 */
 function resolveSettings(value) {
     if (!value || typeof value !== 'object')
-        return { ...ALWAYS_ON };
+        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 rawChain = Array.isArray(v.distillChain) ? v.distillChain : [];
+    const chain = [];
+    for (const item of rawChain) {
+        if (chain.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
+            : '';
+        chain.push({
+            provider: typeof e.provider === 'string' ? e.provider.slice(0, 200) : '',
+            model: typeof e.model === 'string' ? e.model.slice(0, 200) : '',
+            reasoningEffort: eff,
+        });
+    }
     return {
         enabled: v.enabled !== false,
         capture: v.capture !== false,
@@ -167,6 +246,7 @@ function resolveSettings(value) {
             : '',
         distillProvider: typeof v.distillProvider === 'string' ? v.distillProvider : '',
         distillModel: typeof v.distillModel === 'string' ? v.distillModel : '',
+        distillChain: chain,
         distillBudgets: {
             extract: num(rawBudgets.extract),
             dedup: num(rawBudgets.dedup),