@modusensus/dsh-mneme 0.8.2 → 0.8.4

package/lib/config.js

@@ -1,500 +1,533 @@
-import z from "@deepseek-ai/schemastery";
-import { TYPE_DECAY_DEFAULTS } from "./heat.js";
-
-export const Config = z.object({
-  // 记忆语言：生成记忆、注入标题与后台 LLM 提示词所用语言；'zh'（默认，
-  // 行为不变）/ 'en'。启动时读入，切换后重启生效。
-  language: z.union([z.const("zh"), z.const("en")]).default("zh")
-    .description("记忆语言：生成的记忆条目、注入标题与后台 LLM 提示词所用语言（zh=默认中文，en=英文）。"),
-  memoryDir: z.string().default("~/.dsh/memory"),
-  autoInject: z.boolean().default(true),
-  autoSummarize: z.boolean().default(true),
-  // Optional model override for summarization. When both are non-empty, they
-  // take priority over the session's current model. Empty = use the session's
-  // active provider/model (same as before).
-  summarizeProvider: z.string().default(""),
-  summarizeModel: z.string().default(""),
-  // 蒸馏转录上限（字符）。借鉴 Codex「保留原始、替代压缩摘要」的思路：
-  // 蒸馏把完整对话上下文交给 LLM 提炼，不硬裁到 8000 字就截断语义；默认
-  // 24000 字符（约覆盖一整轮中等对话），需要更完整可调大。
-  distillMaxChars: z.natural().min(1000).max(200000).default(24000),
-  // autoSummarize 节流、产出上限与写入端同会话去重（Issue #127，默认全 0/off =
-  // 零行为变化）。此前每个 turn/end 必跑、产出条数由模型输出决定、写入端只按
-  // 「同类型 + 标题 trim 全等」去重——本机实测单日 84 次、单会话一天 198 条、
-  // 同一事实 6 小时铸出 28+ 条。阀门交给用户按需拧，升级本身不改行为。
-  summarizeMinIntervalMinutes: z.natural().min(0).max(10080).default(0),
-  summarizeMaxEntriesPerRun: z.natural().min(0).max(50).default(0),
-  // 落库前去重档位：off（默认，等同现状）/ title（零成本，仅拦完全同名）/
-  // vector（复用已有 embedding 列做同会话语义近邻，无 LLM 调用）。
-  summarizeDedupeMode: z.union([z.const("off"), z.const("title"), z.const("vector")]).default("off"),
-  summarizeDedupeMinSim: z.number().min(0.5).max(0.99).default(0.92),
-  summarizeDedupeWindowHours: z.natural().min(0).max(168).default(24),
-  // 智能调速器（429 保护，默认开）：蒸馏 LLM 调用全局串行排队，相邻请求
-  // 间隔 distillRateLimitIntervalMs（默认 1s 一次）；命中 429 限流时按
-  // distillRateLimitBaseDelayMs 指数退避（1s→2s→4s…）自动重试
-  // distillRateLimitRetries 次，全程对用户透明，不把 429 错误码抛给用户。
-  distillRateLimitIntervalMs: z.natural().min(0).max(60000).default(1000),
-  distillRateLimitRetries: z.natural().min(0).max(10).default(3),
-  distillRateLimitBaseDelayMs: z.natural().min(100).max(60000).default(1000),
-  maxInjectedItems: z.natural().min(1).max(20).default(5),
-  importanceThreshold: z.natural().min(1).max(5).default(3),
-  // 编码记忆蒸馏（codingRetrospect，opt-in，默认关）。开启时，turn/end 蒸馏
-  // 额外提取三类编码专属记忆：rejected_solution（被否决方案）/ pitfall（踩坑）/
-  // constraint（工程约束）。蒸馏上下文为整轮完整对话（用户输入 → 助手思考/回答
-  // → 工具调用与结果 → 代码执行），不再只看用户消息，便于提炼踩坑根因。
-  // 关闭时行为与之前完全一致。
-  codingRetrospect: z.boolean().default(false),
-  // 编码任务识别词表（读取侧门控用）：命中即视为编码类任务，编码记忆才注入。
-  codingKeywords: z.array(z.string()).default([
-    "代码", "编码", "写一个", "写个", "实现", "函数", "方法", "类",
-    "接口", "bug", "调试", "报错", "错误", "异常", "堆栈", "脚本",
-    "python", "javascript", "typescript", "node", "js", "ts",
-    "sql", "sqlite", "数据库", "算法", "重构", "优化", "性能",
-    "测试", "单测", "修复", "补丁", "依赖", "npm", "pip",
-    "命令行", "shell", "配置", "配置文件", "yaml", "json",
-    "插件", "开发", "编译", "构建", "部署", "git", "commit",
-    "review", "前端", "后端", "页面", "组件", "dsh", "memos"
-  ]),
-  // 编码记忆注入加权系数：编码任务时对 rejected_solution/pitfall/constraint
-  // 记忆的 importance 乘以该系数排序，让编码记忆在编码场景更靠前。
-  codingBoostFactor: z.number().min(1).max(5).default(2),
-  // 注入边界花括号转义（issue #162，v0.7.4 曾修后被 v0.7.11 重构误删）：默认开启，
-  // 在 memory / 短期上下文 / 用户设置三处注入出口对连续 2+ 个花括号插 `\`
-  // （`{{a}}`→`{\{a\}\}`），让 DSH 的 interpolate() 不再扫到非法变量名而 throw。
-  // 关闭时按原样透传。
-  escapePromptVariables: z.boolean().default(true),
-  autoDream: z.boolean().default(true),
-  dreamThresholdCount: z.natural().min(1).max(1000).default(10),
-  dreamThresholdChars: z.natural().min(100).max(100000).default(5000),
-  dreamDelayMs: z.natural().min(0).max(60000).default(2000),
-  // autoDream 触发最小间隔（分钟，0 = 不限制，Issue #89 请求 2）：高频写入
-  // 场景下防止巩固调用（含失败重试）连发刷爆配额。间隔从每次实际开跑时刻
-  // 起算，失败/degraded 的 run 也占用间隔；间隔内的触发请求静默跳过，下一次
-  // 写入事件会重新评估。
-  dreamMinIntervalMinutes: z.natural().min(0).max(10080).default(0),
-  // 巩固模型路由（settings panel「巩固模型」/ dreamProvider+dreamModel）：
-  // dream 的记忆沉淀专用 LLM 路由，显式配置优先于 agent 默认模型（config-first，
-  // Issue #25）。模型分类声明：
-  //   - 非思考模型（推荐，如 glm-5-2 类）：无 reasoning 声明，effort 请求被 harness
-  //     拒绝后 withEffortFallback 去掉字段重试即成功；空体/no json array 风险最低。
-  //   - 思考模型（如 deepseek-v4-flash-ga 等 v4-flash-ga 系）：默认开推理，可能烧光
-  //     token 预算返回空体；且部分（如 v4-flash-ga）在 harness 侧被声明为不接受任何
-  //     reasoning effort —— 即使去掉 effort 重试，harness 的 defaultEffort 也会顶上来
-  //     再次拒绝（UNSUPPORTED_REASONING_EFFORT），插件 fallback 无法绕开。
-  //     选用时建议配 dreamReasoningEffort 并实测；不行就换非思考模型。
-  dreamProvider: z.string().description("记忆巩固专用模型的服务商（settings「巩固模型」）。巩固反复失败时，优先改用官方非思考模型的服务商（如 deepseek / glm）。"),
-  dreamModel: z.string().description("记忆巩固专用模型。建议选非思考模型（如 deepseek-chat、glm-5-2 类）：思考模型可能烧光 token 预算返回空体，导致巩固失败（UNSUPPORTED_REASONING_EFFORT）。"),
-  // Issue #135 建议 3：#9 只抬了 max（8192→131072），default 停在 32768。思考型
-  // 模型的推理与正文共享该预算，effort 未压低时 32768 恰好被推理烧光 → 空体
-  // （"no json array in llm output"，报告实测 146 轮因此失败）。默认抬到上限，
-  // 让默认配置也留足正文预算；流式计费按实际用量，不按上限。
-  dreamMaxTokens: z.natural().min(256).max(131072).default(131072),
-  // Pass-through reasoning effort for dream's LLM calls (Issue #135 建议 4/5).
-  // Unset (no value) resolves to the LOWEST effort the model declares before
-  // streaming: background consolidation must produce JSON, and omitting the
-  // field lets the harness substitute the model's defaultEffort (thinking-type
-  // models often default to high/max) — the reasoning then drains the whole
-  // token budget and the run dies with an empty body. Explicit 'none' still
-  // omits the field (provider default applies); off/low/medium/high are
-  // forwarded verbatim, unsupported values are remapped (v0.7.26+).
-  // Caveat: on some thinking models (e.g. v4-flash-ga) the harness declares NO
-  // supported effort, so even the fallback retry (field stripped) is rejected
-  // again via its defaultEffort — prefer a non-reasoning dreamProvider/dreamModel.
-  dreamReasoningEffort: z.union([
-    z.const("off"),
-    z.const("low"),
-    z.const("medium"),
-    z.const("high"),
-    z.const("none")
-  ]).description("巩固模型的推理档位：未配置 = 自动取模型支持的最低档（避免思考模型用自带默认档烧光预算返回空体，#135）；显式 'none' = 不发送字段、用服务商自带默认；off/low/medium/high 原样传递。模型不支持的值会自动换用其支持的档位（v0.7.26+）。"),
-  // 滑动窗口上限（v0.4.4）：autoDream 每次只对最近 dreamMaxSnapshotSize 条
-  // 记忆做 consolidation。大记忆量下全量快照会把 LLM 输入撑爆（636 记忆 →
-  // 677 "missing" errors、applied=0），窗口外的旧记忆不进 snapshot。
-  dreamMaxSnapshotSize: z.natural().min(1).max(1000).default(200),
-  // Issue #104 方向 2：单轮 archive 决策上限。一次性大扫除（12 条互不相关主题
-  // 被批量归档，其中 8 条疑似误伤长保留类型）是失控信号，与 update 上限同类的
-  // 全局闸门：skipInvalid 也不豁免，超限整单拒绝。正常清理可调高。
-  dreamMaxArchivePerRun: z.natural().min(1).max(200).default(8),
-  // Issue #125：候选集构造方式。"window"（默认，等同现状）只取最近
-  // dreamMaxSnapshotSize 条；"hybrid" 在此基础上并入**向量翻出的高相似组**——
-  // 本机实测 45 对「双方活跃且 sim≥0.85」里 0 对能同时进窗口（窗口覆盖率 11.7%），
-  // 纯时间窗口让"该合并的一对"几乎永远碰不到面。候选总量仍由下面的上限封顶、
-  // 与库总量解耦，这是相对"调大窗口"的核心收益：输入成本不随库增长。
-  dreamCandidateMode: z.union([
-    z.const("window"),
-    z.const("hybrid")
-  ]).default("window"),
-  // hybrid 的候选总量上限；0 = 复用 dreamMaxSnapshotSize（不迁移，需要时显式覆盖）。
-  dreamCandidateMax: z.natural().min(0).max(5000).default(0),
-  // hybrid 判"高相似"的阈值；0.85 与 sleep normal 档对齐——两个模块对"高相似"
-  // 保持同一个定义。
-  dreamCandidateMinSim: z.number().min(0.5).max(0.99).default(0.85),
-  // 隐式 keep（v0.4.4）：LLM 未提及的 snapshot 记忆自动补 {action:"keep"}，
-  // 避免"未覆盖即全拒"白白浪费整轮 run。设为 false 时保留旧的严格校验
-  // （未覆盖即拒绝整单）。
-  dreamImplicitKeep: z.boolean().default(true),
-  // 显式决策覆盖率下限（v0.4.4 fix）：dreamImplicitKeep 开启时，LLM 输出被
-  // 截断只显式 claim 少量 snapshot 记忆（claimed.size / snapshot.size < 该阈值）
-  // → 整单拒绝，防止残缺输出被隐式 keep 洗白成 ok 后再被真实 apply。0-1，
-  // 默认 0.5（至少显式覆盖一半 snapshot）。
-  dreamMinExplicitCoverage: z.number().min(0).max(1).default(0.5),
-  // Issue #89：v0.6.9（Issue #26）的宽容路径回归。默认跳过单条非法决策
-  // （未知 id / 跨类型合并等）、应用合法子集、run 记 degraded；设 false 恢复
-  // 整单拒绝的严格模式。全局上限与覆盖率下限不受此开关影响、始终整单拒绝。
-  dreamSkipInvalid: z.boolean().default(true),
-  // 显式开启后放宽跨类型合并检查（类型边界由用户自行承担）；配合
-  // dreamSkipInvalid 理解：关闭 skipInvalid 时跨类型 merge 直接整单拒绝。
-  allowCrossTypeMerge: z.boolean().default(false),
-  // Rule version for dream adjudication: when this bumps, older dream_runs
-  // degrade to historical evidence (their receipts no longer drive live
-  // decisions). Default 0 = no versioning in use yet.
-  policyEpoch: z.natural().min(0).max(1000000).default(0),
-
-  // --- API protection ------------------------------------------------------
-  // Optional shared token for the plugin's HTTP API. Empty (default) keeps
-  // the API open (DSH binds to 127.0.0.1 and has no built-in auth); when set,
-  // sensitive endpoints (vector-config, vector-reindex, and all write ops on
-  // profile/rules/commands) require `Authorization: Bearer <apiToken>` (or
-  // `X-DSH-Mneme-Token`). Read-only list/search/semantic stay open so the
-  // Web panel keeps working without the token.
-  apiToken: z.string(),
-
-  // --- semantic: local embedding provider (v0.2) --------------------------
-  // "openai" keeps the legacy external-API path (settings vector config);
-  // "local" runs an ONNX model in-process; "ollama" calls a local Ollama.
-  embedProvider: z.union([z.const("openai"), z.const("local"), z.const("ollama")]).default("openai"),
-
-  // Local ONNX embedder (transformers.js / onnxruntime).
-  localEmbedModel: z.string().default("Xenova/bge-small-zh-v1.5"),
-  localEmbedDimension: z.natural().default(512),
-  localEmbedDevice: z.union([z.const("cpu"), z.const("gpu")]).default("cpu"),
-  localEmbedBatchSize: z.natural().min(1).max(64).default(8),
-
-  // Ollama embedder.
-  ollamaBaseUrl: z.string().default("http://localhost:11434"),
-  ollamaModel: z.string().default("nomic-embed-text"),
-
-  // Model download/cache. When empty (default), models are cached under the
-  // user-level path ~/.dsh/mneme/models (resolved in local-embedder/reranker);
-  // a non-empty value is used verbatim.
-  embedModelCacheDir: z.string().default(""),
-  embedModelMirror: z.string().default("https://hf-mirror.com"),
-
-  // 自管运行时目录（issue #131）。空 = ~/.dsh/mneme/runtime：里面放收编或下载来的
-  // transformers + onnxruntime 闭包，插件经 src/runtime/loader.js 的三层解析加载它。
-  // 目的就是让这条重依赖不必留在宿主 profile 的依赖图里——profile 是所有插件共用的
-  // 依赖图，留在里面会让「装任何插件都要替它重走一遍这条链」。
-  runtimeDir: z.string().default(""),
-
-  // 运行时取件的两个来源（issue #131 / PR-C）。都是「克制」的默认：留空 = 不额外改变行为。
-  // - runtimeTarballDir：本地 .tgz 目录。某个包网络下不到时（例如 onnxruntime-node），
-  //   把 `npm pack <pkg>` 出来的 tgz 丢进这个目录即可离线取件；有它就优先于联网。
-  // - runtimeMirror：registry 镜像前缀，例如 https://npmmirror.com/mirrors/npm/ 。
-  //   留空则用 runtime-manifest.json 里写死的官方地址（那是随包发布的固定清单）。
-  runtimeTarballDir: z.string().default(""),
-  runtimeMirror: z.string().default(""),
-
-  // Vector search tuning.
-  vectorSearchTopK: z.natural().min(1).max(100).default(20),
-  vectorSearchThreshold: z.number().min(0).max(1).default(0.65),
-  hybridSearchVectorWeight: z.number().min(0).max(1).default(0.6),
-  hybridSearchKeywordWeight: z.number().min(0).max(1).default(0.4),
-  // Lazy auto-backfill of missing embeddings on boot (Bug2): when the vector
-  // API is configured and rows still lack an embedding, the index is rebuilt
-  // in the background after a short delay, rate-limited in batches. On by
-  // default; set false to keep the backfill manual only.
-  autoReindexOnBoot: z.boolean().default(true),
-  // Semantic-first injection (Bug4): when enabled, injectCandidates with a
-  // non-empty query recalls via the vector index first and falls back to the
-  // rule-based pick to fill/dedupe. Empty query / no vector → legacy behavior.
-  hybridInject: z.boolean().default(true),
-
-  // --- recall optimization (v0.5.0) ----------------------------------------
-  // BM25 third recall path beside vector + LIKE keyword (1.1): per-token IDF
-  // scoring recalls rows whose query terms are scattered — identifiers, code
-  // fragments, mixed CJK/ASCII — where substring LIKE cannot match.
-  bm25SearchEnabled: z.boolean().default(true),
-  // Query-aware vector cutoff (1.2) replacing the fixed 0.65: entity:/attr:
-  // prefixes loosen to 0.5, short queries tighten to 0.7, long queries loosen
-  // to 0.6, and a decisive top-1/top-5 score gap loosens to 0.5 so the tail
-  // still reaches the reranker. Off = legacy fixed threshold behavior.
-  adaptiveThresholdEnabled: z.boolean().default(true),
-  // Session-scoped hot memory (1.3): the latest N dialogue rounds rendered
-  // ahead of the long-term recall block — short-term context that never
-  // enters the memory store.
-  hotMemoryEnabled: z.boolean().default(true),
-  hotMemoryRounds: z.natural().min(1).max(50).default(5),
-  hotMemoryMaxTokens: z.natural().min(200).max(32000).default(2000),
-  // Topic-ranked injection (2.2): when a query vector is available the whole
-  // injection candidate list is re-ordered by similarity to the current
-  // query instead of keeping the rule-based order.
-  selectiveInjectEnabled: z.boolean().default(true),
-  // Search-time semantic dedup (2.3): greedy pass over the merged candidate
-  // list dropping rows whose embedding cosine-similarity to an already-kept
-  // row exceeds the threshold — duplicates are filtered at recall time
-  // instead of waiting for a dream consolidation. Opt-in aggressive mode:
-  // small embedding models can collapse legitimately distinct rows, so the
-  // default keeps every recalled row.
-  searchSemanticDedup: z.boolean().default(false),
-  searchSemanticDedupThreshold: z.number().min(0.5).max(1).default(0.95),
-
-  // Recall fusion recipe (plan #1): how the keyword/vector/BM25 ranked lists
-  // are combined into the final ranking. `blend` (default) is the legacy
-  // behavior — weighted sum for vector/hybrid, union backfill for auto —
-  // unchanged. `rrf` (Reciprocal Rank Fusion) and `minmax` (min-max normalized
-  // weighted sum) are rank/scale-aware recipes that fix the unit mismatch the
-  // issue describes (raw cosine vs keyword score vs normalized IDF are added
-  // directly). Off by default so existing behavior holds exactly.
-  recallFusion: z.union([z.const("blend"), z.const("rrf"), z.const("minmax")]).default("blend"),
-  // Attach a `signals` object { keyword, vector, bm25, final } to each search
-  // result for transparency/debugging (plan #2). Default off; when on it only
-  // decorates the returned rows, never changes the ranking.
-  signalTransparency: z.boolean().default(false),
-
-  // --- semantic: rerank layer (v0.2) --------------------------------------
-  // Opt-in by default (item ⑥): the local cross-encoder pulls in onnxruntime
-  // (transformers.js) at init, so a bare install must not load it. Only an
-  // explicit rerankEnabled=true + rerankProvider="local" constructs LocalReranker.
-  rerankEnabled: z.boolean().default(false),
-  rerankProvider: z.union([z.const("local"), z.const("none")]).default("none"),
-  rerankModel: z.string().default("Xenova/bge-reranker-base"),
-  rerankBatchSize: z.natural().min(1).max(64).default(8),
-  rerankMaxCandidates: z.natural().min(5).max(100).default(30),
-  rerankScoreThreshold: z.number().min(0).max(1).default(0.1),
-  // #188：量化档，与嵌入层的 useDtype 同语义（q8 = model_quantized.onnx，约为
-  // fp32 体积的 1/4）。此前重排层不传 dtype，即使缓存里已有量化文件也会去下载
-  // 1GB 级的 model.onnx。非法值由 transformers 在 init 时抛出 → 重排降级并告警。
-  rerankDtype: z.string().default("q8"),
-
-  // --- reflection: update decision + failure tracking (v0.2.1) ------------
-  reflectionUpdateEnabled: z.boolean().default(true),
-  reflectionFailureTracking: z.boolean().default(true),
-  reflectionUpdateMaxPerRun: z.natural().min(0).max(5).default(2),
-  reflectionUpdateMinAgeHours: z.natural().min(0).max(168).default(24),
-
-  // --- conflict freeze: manual review for conflicting memories (v0.2.1) ---
-  // Opt-in by default: when true, conflicting memories are not auto-merged
-  // and are marked as pending manual review instead.
-  conflictFreezeEnabled: z.boolean().default(false),
-  // Maximum number of frozen conflicts to keep pending for manual review.
-  conflictFreezeMaxPending: z.natural().min(1).max(1000).default(100),
-
-  // --- entity gene (v0.3.0) -----------------------------------------------
-  // Opt-in: when false (default) nothing in the pipeline extracts entities.
-  // The storage layer (entities/entity_attrs/entity_relations tables + CRUD)
-  // is always available regardless of this flag.
-  entityExtractionEnabled: z.boolean().default(false),
-  // Optional provider override for entity extraction; empty = use the caller's
-  // default provider/model. Combined with entityExtractionModel — provider
-  // without model (or vice versa) falls through to the caller default.
-  entityExtractionProvider: z.string().default(""),
-  // Optional model override for entity extraction; empty = use the caller's
-  // default provider/model.
-  entityExtractionModel: z.string().default(""),
-  // Reasoning effort for entity extraction (issue #109), mirrors
-  // dreamReasoningEffort pass-through: 'none' omits the field / provider
-  // default; off/low/medium/high passed through. A provider that rejects the
-  // effort retries once without it, so opting in is safe to experiment with.
-  entityExtractionReasoning: z.union([
-    z.const("low"),
-    z.const("medium"),
-    z.const("high"),
-    z.const("none")
-  ]).default("none"),
-  // Cap on entities per extraction pass and attributes per entity.
-  entityExtractionMaxEntities: z.natural().min(1).max(20).default(10),
-  entityExtractionMaxAttrs: z.natural().min(1).max(50).default(20),
-  // Prefix/semantic search over entity names (used by recall).
-  entitySearchEnabled: z.boolean().default(true),
-
-  // --- sleep mode: idle-triggered deep maintenance (v0.4.0) ---------------
-  // Opt-in, off by default. Unlike autoDream (threshold-triggered, lightweight)
-  // sleep fires when the store has been quiet for sleepIdleMinutes and deep-
-  // maintains the whole library: conflict resolution, archival demotion,
-  // pattern discovery and entity relation completion. Abortable on user
-  // activity, audited into dream_runs (run_type='sleep'), and serialized with
-  // autoDream so the two never overlap.
-  sleepModeEnabled: z.boolean().default(false),
-  // Quiet window before a cycle fires (minutes).
-  sleepIdleMinutes: z.natural().min(1).max(60).default(5),
-  // Minimum gap between two sleep runs (hours) — a second idle window within
-  // this interval does not retrigger.
-  sleepMinIntervalHours: z.natural().min(1).max(168).default(8),
-  // Conflict adjudication strictness:
-  //   gentle    only high-confidence conflicts (threshold 0.92) are resolved
-  //   normal    standard dream-level (threshold 0.85)
-  //   aggressive low-confidence pairs are also adjudicated (threshold 0.75)
-  sleepConflictStrictness: z.union([
-    z.const("gentle"),
-    z.const("normal"),
-    z.const("aggressive")
-  ]).default("normal"),
-  // Issue #126：冲突阶段的动作集。"conflict"（默认 = 现状）只用 conflict/keep——
-  // 后台自动流程不静默扩张行为；"full" 开放六分支（merge / update / supersede /
-  // differentiate / conflict / keep），互补型与演进型重复因此有了正确出口，不再
-  // 被迫"输赢化"（实测抽样 10 对里 2 对属演进型/互补型，用 conflict 处理会丢信息）。
-  sleepActionSet: z.union([
-    z.const("conflict"),
-    z.const("full")
-  ]).default("conflict"),
-  // Archival demotion tiering (days since last access):
-  //   >= sleepArchiveDays  → shrink to summary, full body kept in _full_content
-  //   >= sleepCompressDays → archived outright (entity relations preserved)
-  sleepArchiveDays: z.natural().min(7).max(365).default(30),
-  sleepCompressDays: z.natural().min(7).max(365).default(90),
-  // Pattern discovery scan window (most recent memories to scan).
-  sleepPatternMinMemories: z.natural().min(10).max(1000).default(100),
-  // How far back pattern discovery considers entity attr changes (days).
-  sleepPatternLookbackDays: z.natural().min(1).max(90).default(30),
-  // Max pattern memories minted per run (0 = disabled).
-  sleepMaxPatternPerRun: z.natural().min(0).max(10).default(3),
-  // Optional LLM route override for sleep's bulk passes (empty = use dream
-  // route / agent default model).
-  sleepProvider: z.string().default("").description("sleep 深维护专用模型服务商，留空用巩固模型或当前模型。"),
-  sleepModel: z.string().default("").description("sleep 深维护专用模型，留空用巩固模型或当前模型；建议同巩固模型选非思考模型。"),
-  // Pass-through reasoning effort for sleep's LLM passes, same semantics as
-  // dreamReasoningEffort (Issue #135 建议 4/5): unset resolves to the lowest
-  // effort the model declares; explicit 'none' omits the field; off/low/
-  // medium/high are forwarded verbatim.
-  sleepReasoningEffort: z.union([
-    z.const("off"),
-    z.const("low"),
-    z.const("medium"),
-    z.const("high"),
-    z.const("none")
-  ]).description("同 dreamReasoningEffort：sleep 各阶段 LLM 的推理档位，未配置 = 自动取模型支持的最低档；显式 'none' = 不发送字段、用服务商自带默认。"),
-
-  // --- epistemic trust: memory source credibility (v0.4.5) -----------------
-  // Distinguish memories by source: observation (measured / witnessed),
-  // subjective (opinion / guess) and inferred (derived from other evidence).
-  // Opt-in by default: when false (default) retrieval ranking, injection
-  // marking and dream merge/conflict keepSource are untouched and
-  // epistemic_status stays inert data (still written + inferred on save, just
-  // never used to influence behavior).
-  trustEpistemicWeighting: z.boolean().default(false),
-
-  // --- memory quality filter (Bug7) ------------------------------------------
-  // Heuristic gate on what deserves the injection/recall surface. When enabled,
-  // saveWithDedupe scores each new memory after dedupe and before write:
-  //   score >= degradeThreshold (60) → stored normally
-  //   archiveThreshold (30) <= score < 60 → quality_score persisted and the
-  //       injection sort re-ranks by importance * quality_score/100 (degraded)
-  //   score < 30 → archived + tagged low_quality (still explicitly searchable)
-  // Meta-memory markers, near-duplicates and repetitive filler lose points.
-  memoryQualityFilter: z.object({
-    enabled: z.boolean().default(true),
-    archiveThreshold: z.natural().min(1).max(100).default(30),
-    degradeThreshold: z.natural().min(1).max(100).default(60),
-    minContentLength: z.natural().min(1).max(1000).default(10),
-    // Issue #135 附属发现 1：importance ≥ 该值的记忆不参与静默自动归档——评分
-    // 与信号标签照常写入（可观测）、注入排序照常降权，但 setArchived 跳过。
-    // 报告实测 150 条低分归档里 128 条 importance ≥ 4（51 条 = 5）。设 1 = 全部
-    // 豁免（等效关闭自动归档），设 5 = 仅最重要的豁免。
-    exemptImportance: z.natural().min(1).max(5).default(4)
-  }).default({}),
-
-  // --- LLM audit trail (Bug8) ------------------------------------------------
-  // Records every background LLM call (autoDream consolidation + summary,
-  // autoSummarize compression) into llm_audit_logs: tokens, duration, status
-  // and which trigger produced it. Failures are recorded as status=error and
-  // never block the feature. retentionDays bounds the table: older rows are
-  // purged on boot.
-  llmAudit: z.object({
-    enabled: z.boolean().default(true),
-    retentionDays: z.natural().min(1).max(3650).default(90)
-  }).default({}),
-
-  // --- recall evaluation: test-result storage (v0.4.6, 方案 B) --------------
-  // Separate retrieval evaluation snapshots from the production recall audit.
-  // When false (default) evaluateRetrieval still computes precision/recall/mrr
-  // and returns them to the caller, but writes nothing to recall_evals — the
-  // eval table only grows when the operator opts in. Production searchMemories
-  // audits to recall_runs and NEVER touches recall_evals, regardless of this
-  // flag (production isolation is unconditional).
-  evalPersistTestResults: z.boolean().default(false),
-
-  // --- standalone external API (v0.7.12) ------------------------------------
-  // A plain node:http server for ecosystem integrations that cannot reach the
-  // DSH-internal webServer. Disabled by default; when enabled the Bearer token
-  // is persisted in the settings kv ("external_api"), auto-generated on first
-  // boot. Bind host: keep the loopback default — moving it to a non-loopback
-  // address exposes the whole memory store to the network and is the
-  // operator's responsibility.
-  externalApiEnabled: z.boolean().default(false),
-  externalApiPort: z.natural().default(8790),
-  externalApiHost: z.string().default("127.0.0.1"),
-
-  // --- light mode preset (v0.7.12) -------------------------------------------
-  // One switch for low-resource setups: turns off every background/semantic
-  // heavy path (dream consolidation, entity extraction, vector pipeline,
-  // reranker, BM25, semantic dedup / selective inject, sleep mode) while
-  // keeping the core loop (autoInject, autoSummarize, hot memory, quality
-  // filter, keyword search). Applied by applyLightModePreset before the config
-  // reaches any service; a persisted panel_mode="light" (settings kv) counts
-  // as lightMode=true too and wins over the bundle config.
-  lightMode: z.boolean().default(false),
-
-  // --- heat: v0.7.0 self-evolution (heat + interest drift) ----------------
-  // 总开关，默认关（v0.7.12+ 用户已习惯无 heat 行为，默认开=全员行为变更）。
-  // 开启后：提供热度字段 / sleep 降级联合判定保护 / 前端热度投影，不改变
-  // 召回排序。关闭则跳过所有 heat 计算与热度触达，sleep 降级退回纯时间分层。
-  // 也走 feature_flags（FEATURE_FLAG_BOOLEANS 白名单），面板可启停=线上回滚开关。
-  heatEnabled: z.boolean().default(false),
-  // 幂律形状参数 α（heat = 1/(1+λΔt)^α），越大衰减越快。
-  heatGlobalAlpha: z.number().min(0.1).max(5).default(1.2),
-  // per-type 衰减因子 λ；λ=0 的类型免疫（热度恒 1.0，sleep 永不降级）。
-  // 未知类型走默认 0.002。dict 的键为 type 字符串、值为数字 λ。
-  heatTypeDecay: z.dict(z.number(), z.string()).default({ ...TYPE_DECAY_DEFAULTS }),
-  // sleep 降级联合判定的热度下限：heat < 该值 且 importance<5 才允许降级。
-  sleepHeatThreshold: z.number().min(0).max(1).default(0.05),
-  // recordRecall 默认值（recall_runs 记录默认开；显式传 false 的调用方不受影响）。
-  recallRecordDefault: z.boolean().default(true),
-  // recall_runs 滚动清理保留天数。
-  recallRetentionDays: z.natural().min(1).max(3650).default(90),
-
-  // --- scope: v0.8.0 A1 存储层（issue #17）--------------------------------
-  // 总开关默认关：关闭时写入不标注 scope、去重维持 (type, title) 现状，行为
-  // 逐字节不变。开启后 memory_save 写入 agent_scope（session header 的
-  // agentPreset）与 workspace_scope（registry 反查 canonical path，header.cwd
-  // 兜底，取不到 NULL——解析绝不阻塞写入），去重键扩展为 (type, title,
-  // agent_scope, workspace_scope, sensitivity)。检索侧加权/过滤在 A2/A3 落地。
-  // 也走 feature_flags（FEATURE_FLAG_BOOLEANS 白名单），面板可启停=线上回滚开关。
-  scopeEnabled: z.boolean().default(false),
-  // strictScope（A3）：硬过滤模式。关闭=A2 软隔离（他 scope 降权保留可见）；
-  // 开启后检索/注入/list/get 按 issue #17 四象限可见性公式硬过滤——带他 scope
-  // 的记忆完全不可见，未标注（NULL）恒可见；当前会话某维度解析不到时该维度
-  // 带标注的记忆一律不可见（fail-closed：身份不明只见全局）。依赖 scopeEnabled
-  // 打开才有意义（没有写入标注就无可过滤维度），但独立成键：可先开标注积累
-  // 数据、观察 A2 加权质量后再切硬过滤。
-  strictScope: z.boolean().default(false),
-});
-
-// Fields forced to false by the light-mode preset. Everything not listed here
-// (autoInject, autoSummarize, hotMemory*, memoryQualityFilter, dream
-// thresholds/delays, ...) is left untouched — those are the core loop.
-const LIGHT_MODE_OFF = [
-  "entityExtractionEnabled",
-  "autoDream",
-  "sleepModeEnabled",
-  "rerankEnabled",
-  "autoReindexOnBoot",
-  "hybridInject",
-  "searchSemanticDedup",
-  "selectiveInjectEnabled",
-  "bm25SearchEnabled",
-  // 轻量模式不开热计算（heat 属于重型增强；关掉后 sleep 降级也退回纯时间分层）。
-  "heatEnabled"
-];
-
-/**
- * Apply the light-mode preset to a resolved config object (pure function,
- * exported for tests). When cfg.lightMode is not exactly true the config is
- * returned unchanged; otherwise a shallow copy carries false for every heavy
- * feature. Idempotent and side-effect free.
- */
-export function applyLightModePreset(cfg) {
-  if (cfg?.lightMode !== true) return cfg;
-  const preset = { ...cfg, lightMode: true };
-  for (const key of LIGHT_MODE_OFF) preset[key] = false;
-  return preset;
-}
+import z from "@deepseek-ai/schemastery";
+import { TYPE_DECAY_DEFAULTS } from "./heat.js";
+
+export const Config = z.object({
+  // 记忆语言：生成记忆、注入标题与后台 LLM 提示词所用语言；'zh'（默认，
+  // 行为不变）/ 'en'。启动时读入，切换后重启生效。
+  language: z.union([z.const("zh"), z.const("en")]).default("zh")
+    .description("记忆语言：生成的记忆条目、注入标题与后台 LLM 提示词所用语言（zh=默认中文，en=英文）。"),
+  memoryDir: z.string().default("~/.dsh/memory"),
+  autoInject: z.boolean().default(true),
+  autoSummarize: z.boolean().default(true),
+  // Optional model override for summarization. When both are non-empty, they
+  // take priority over the session's current model. Empty = use the session's
+  // active provider/model (same as before).
+  summarizeProvider: z.string().default(""),
+  summarizeModel: z.string().default(""),
+  // 蒸馏转录上限（字符）。借鉴 Codex「保留原始、替代压缩摘要」的思路：
+  // 蒸馏把完整对话上下文交给 LLM 提炼，不硬裁到 8000 字就截断语义；默认
+  // 24000 字符（约覆盖一整轮中等对话），需要更完整可调大。
+  distillMaxChars: z.natural().min(1000).max(200000).default(24000),
+  // autoSummarize 节流、产出上限与写入端同会话去重（Issue #127，默认全 0/off =
+  // 零行为变化）。此前每个 turn/end 必跑、产出条数由模型输出决定、写入端只按
+  // 「同类型 + 标题 trim 全等」去重——本机实测单日 84 次、单会话一天 198 条、
+  // 同一事实 6 小时铸出 28+ 条。阀门交给用户按需拧，升级本身不改行为。
+  summarizeMinIntervalMinutes: z.natural().min(0).max(10080).default(0),
+  summarizeMaxEntriesPerRun: z.natural().min(0).max(50).default(0),
+  // 落库前去重档位：off（默认，等同现状）/ title（零成本，仅拦完全同名）/
+  // vector（复用已有 embedding 列做同会话语义近邻，无 LLM 调用）。
+  summarizeDedupeMode: z.union([z.const("off"), z.const("title"), z.const("vector")]).default("off"),
+  summarizeDedupeMinSim: z.number().min(0.5).max(0.99).default(0.92),
+  summarizeDedupeWindowHours: z.natural().min(0).max(168).default(24),
+  // 智能调速器（429 保护，默认开）：蒸馏 LLM 调用全局串行排队，相邻请求
+  // 间隔 distillRateLimitIntervalMs（默认 1s 一次）；命中 429 限流时按
+  // distillRateLimitBaseDelayMs 指数退避（1s→2s→4s…）自动重试
+  // distillRateLimitRetries 次，全程对用户透明，不把 429 错误码抛给用户。
+  distillRateLimitIntervalMs: z.natural().min(0).max(60000).default(1000),
+  distillRateLimitRetries: z.natural().min(0).max(10).default(3),
+  distillRateLimitBaseDelayMs: z.natural().min(100).max(60000).default(1000),
+  maxInjectedItems: z.natural().min(1).max(20).default(5),
+  // Issue #205：注入位跨轮轮换。同一会话里，最近 N 个不同用户查询轮次注入过
+  // 的记忆本轮不再优先（新鲜优先、原序回填，槽位数不变）；长会话中避免相邻
+  // 轮次反复注入同一条（实测 15.5h 会话 86 次注入 93% 重复）。0 = 关闭（默认，
+  // 保持既有行为）。会话边界自动重置：新会话从零开始。
+  injectRotationTurns: z.natural().min(0).max(20).default(0),
+  // Issue #164①：注入单条正文截断上限可配（原硬编码 300）。截断时尾部带
+  // 提示：上限/原长/全文 memory_get 指引（BUDGET_EXCEEDED 原则——绝不静默）。
+  // 默认 300 = 与既有行为一致。
+  injectContentMaxChars: z.natural().min(60).max(4000).default(300),
+  importanceThreshold: z.natural().min(1).max(5).default(3),
+  // 编码记忆蒸馏（codingRetrospect，opt-in，默认关）。开启时，turn/end 蒸馏
+  // 额外提取三类编码专属记忆：rejected_solution（被否决方案）/ pitfall（踩坑）/
+  // constraint（工程约束）。蒸馏上下文为整轮完整对话（用户输入 → 助手思考/回答
+  // → 工具调用与结果 → 代码执行），不再只看用户消息，便于提炼踩坑根因。
+  // 关闭时行为与之前完全一致。
+  codingRetrospect: z.boolean().default(false),
+  // 编码任务识别词表（读取侧门控用）：命中即视为编码类任务，编码记忆才注入。
+  codingKeywords: z.array(z.string()).default([
+    "代码", "编码", "写一个", "写个", "实现", "函数", "方法", "类",
+    "接口", "bug", "调试", "报错", "错误", "异常", "堆栈", "脚本",
+    "python", "javascript", "typescript", "node", "js", "ts",
+    "sql", "sqlite", "数据库", "算法", "重构", "优化", "性能",
+    "测试", "单测", "修复", "补丁", "依赖", "npm", "pip",
+    "命令行", "shell", "配置", "配置文件", "yaml", "json",
+    "插件", "开发", "编译", "构建", "部署", "git", "commit",
+    "review", "前端", "后端", "页面", "组件", "dsh", "memos"
+  ]),
+  // 编码记忆注入加权系数：编码任务时对 rejected_solution/pitfall/constraint
+  // 记忆的 importance 乘以该系数排序，让编码记忆在编码场景更靠前。
+  codingBoostFactor: z.number().min(1).max(5).default(2),
+  // 注入边界花括号转义（issue #162，v0.7.4 曾修后被 v0.7.11 重构误删）：默认开启，
+  // 在 memory / 短期上下文 / 用户设置三处注入出口对连续 2+ 个花括号插 `\`
+  // （`{{a}}`→`{\{a\}\}`），让 DSH 的 interpolate() 不再扫到非法变量名而 throw。
+  // 关闭时按原样透传。
+  escapePromptVariables: z.boolean().default(true),
+  autoDream: z.boolean().default(true),
+  dreamThresholdCount: z.natural().min(1).max(1000).default(10),
+  dreamThresholdChars: z.natural().min(100).max(100000).default(5000),
+  dreamDelayMs: z.natural().min(0).max(60000).default(2000),
+  // autoDream 触发最小间隔（分钟，0 = 不限制，Issue #89 请求 2）：高频写入
+  // 场景下防止巩固调用（含失败重试）连发刷爆配额。间隔从每次实际开跑时刻
+  // 起算，失败/degraded 的 run 也占用间隔；间隔内的触发请求静默跳过，下一次
+  // 写入事件会重新评估。
+  dreamMinIntervalMinutes: z.natural().min(0).max(10080).default(0),
+  // 巩固模型路由（settings panel「巩固模型」/ dreamProvider+dreamModel）：
+  // dream 的记忆沉淀专用 LLM 路由，显式配置优先于 agent 默认模型（config-first，
+  // Issue #25）。模型分类声明：
+  //   - 非思考模型（推荐，如 glm-5-2 类）：无 reasoning 声明，effort 请求被 harness
+  //     拒绝后 withEffortFallback 去掉字段重试即成功；空体/no json array 风险最低。
+  //   - 思考模型（如 deepseek-v4-flash-ga 等 v4-flash-ga 系）：默认开推理，可能烧光
+  //     token 预算返回空体；且部分（如 v4-flash-ga）在 harness 侧被声明为不接受任何
+  //     reasoning effort —— 即使去掉 effort 重试，harness 的 defaultEffort 也会顶上来
+  //     再次拒绝（UNSUPPORTED_REASONING_EFFORT），插件 fallback 无法绕开。
+  //     选用时建议配 dreamReasoningEffort 并实测；不行就换非思考模型。
+  dreamProvider: z.string().description("记忆巩固专用模型的服务商（settings「巩固模型」）。巩固反复失败时，优先改用官方非思考模型的服务商（如 deepseek / glm）。"),
+  dreamModel: z.string().description("记忆巩固专用模型。建议选非思考模型（如 deepseek-chat、glm-5-2 类）：思考模型可能烧光 token 预算返回空体，导致巩固失败（UNSUPPORTED_REASONING_EFFORT）。"),
+  // Issue #135 建议 3：#9 只抬了 max（8192→131072），default 停在 32768。思考型
+  // 模型的推理与正文共享该预算，effort 未压低时 32768 恰好被推理烧光 → 空体
+  // （"no json array in llm output"，报告实测 146 轮因此失败）。默认抬到上限，
+  // 让默认配置也留足正文预算；流式计费按实际用量，不按上限。
+  dreamMaxTokens: z.natural().min(256).max(131072).default(131072),
+  // Pass-through reasoning effort for dream's LLM calls (Issue #135 建议 4/5).
+  // Unset (no value) resolves to the LOWEST effort the model declares before
+  // streaming: background consolidation must produce JSON, and omitting the
+  // field lets the harness substitute the model's defaultEffort (thinking-type
+  // models often default to high/max) — the reasoning then drains the whole
+  // token budget and the run dies with an empty body. Explicit 'none' still
+  // omits the field (provider default applies); off/low/medium/high are
+  // forwarded verbatim, unsupported values are remapped (v0.7.26+).
+  // Caveat: on some thinking models (e.g. v4-flash-ga) the harness declares NO
+  // supported effort, so even the fallback retry (field stripped) is rejected
+  // again via its defaultEffort — prefer a non-reasoning dreamProvider/dreamModel.
+  dreamReasoningEffort: z.union([
+    z.const("off"),
+    z.const("low"),
+    z.const("medium"),
+    z.const("high"),
+    z.const("none")
+  ]).description("巩固模型的推理档位：未配置 = 自动取模型支持的最低档（避免思考模型用自带默认档烧光预算返回空体，#135）；显式 'none' = 不发送字段、用服务商自带默认；off/low/medium/high 原样传递。模型不支持的值会自动换用其支持的档位（v0.7.26+）。"),
+  // 滑动窗口上限（v0.4.4）：autoDream 每次只对最近 dreamMaxSnapshotSize 条
+  // 记忆做 consolidation。大记忆量下全量快照会把 LLM 输入撑爆（636 记忆 →
+  // 677 "missing" errors、applied=0），窗口外的旧记忆不进 snapshot。
+  dreamMaxSnapshotSize: z.natural().min(1).max(1000).default(200),
+  // Issue #104 方向 2：单轮 archive 决策上限。一次性大扫除（12 条互不相关主题
+  // 被批量归档，其中 8 条疑似误伤长保留类型）是失控信号，与 update 上限同类的
+  // 全局闸门：skipInvalid 也不豁免，超限整单拒绝。正常清理可调高。
+  dreamMaxArchivePerRun: z.natural().min(1).max(200).default(8),
+  // Issue #125：候选集构造方式。"window"（默认，等同现状）只取最近
+  // dreamMaxSnapshotSize 条；"hybrid" 在此基础上并入**向量翻出的高相似组**——
+  // 本机实测 45 对「双方活跃且 sim≥0.85」里 0 对能同时进窗口（窗口覆盖率 11.7%），
+  // 纯时间窗口让"该合并的一对"几乎永远碰不到面。候选总量仍由下面的上限封顶、
+  // 与库总量解耦，这是相对"调大窗口"的核心收益：输入成本不随库增长。
+  dreamCandidateMode: z.union([
+    z.const("window"),
+    z.const("hybrid")
+  ]).default("window"),
+  // hybrid 的候选总量上限；0 = 复用 dreamMaxSnapshotSize（不迁移，需要时显式覆盖）。
+  dreamCandidateMax: z.natural().min(0).max(5000).default(0),
+  // hybrid 判"高相似"的阈值；0.85 与 sleep normal 档对齐——两个模块对"高相似"
+  // 保持同一个定义。
+  dreamCandidateMinSim: z.number().min(0.5).max(0.99).default(0.85),
+  // 叙述条（#164 对齐，opt-in）：dream 期间按共享 tag 主题聚类（dream/
+  // narratives.js），每簇 LLM 合成一条叙述落库（source=narrative、evidence
+  // 回链簇内原子记忆、求交防捏造）。按需检索、不常驻注入。默认关=行为与
+  // 此前一致；lightMode 强制关闭。
+  dreamNarrativeEnabled: z.boolean().default(false),
+  // 成簇门槛：共享同一 tag 的记忆 ≥ 此值才合成叙述条。
+  dreamNarrativeMinCluster: z.natural().min(2).max(20).default(3),
+  // 隐式 keep（v0.4.4）：LLM 未提及的 snapshot 记忆自动补 {action:"keep"}，
+  // 避免"未覆盖即全拒"白白浪费整轮 run。设为 false 时保留旧的严格校验
+  // （未覆盖即拒绝整单）。
+  dreamImplicitKeep: z.boolean().default(true),
+  // 显式决策覆盖率下限（v0.4.4 fix）：dreamImplicitKeep 开启时，LLM 输出被
+  // 截断只显式 claim 少量 snapshot 记忆（claimed.size / snapshot.size < 该阈值）
+  // → 整单拒绝，防止残缺输出被隐式 keep 洗白成 ok 后再被真实 apply。0-1，
+  // 默认 0.5（至少显式覆盖一半 snapshot）。
+  dreamMinExplicitCoverage: z.number().min(0).max(1).default(0.5),
+  // Issue #89：v0.6.9（Issue #26）的宽容路径回归。默认跳过单条非法决策
+  // （未知 id / 跨类型合并等）、应用合法子集、run 记 degraded；设 false 恢复
+  // 整单拒绝的严格模式。全局上限与覆盖率下限不受此开关影响、始终整单拒绝。
+  dreamSkipInvalid: z.boolean().default(true),
+  // 显式开启后放宽跨类型合并检查（类型边界由用户自行承担）；配合
+  // dreamSkipInvalid 理解：关闭 skipInvalid 时跨类型 merge 直接整单拒绝。
+  allowCrossTypeMerge: z.boolean().default(false),
+  // Rule version for dream adjudication: when this bumps, older dream_runs
+  // degrade to historical evidence (their receipts no longer drive live
+  // decisions). Default 0 = no versioning in use yet.
+  policyEpoch: z.natural().min(0).max(1000000).default(0),
+
+  // --- API protection ------------------------------------------------------
+  // Optional shared token for the plugin's HTTP API. Empty (default) keeps
+  // the API open (DSH binds to 127.0.0.1 and has no built-in auth); when set,
+  // sensitive endpoints (vector-config, vector-reindex, and all write ops on
+  // profile/rules/commands) require `Authorization: Bearer <apiToken>` (or
+  // `X-DSH-Mneme-Token`). Read-only list/search/semantic stay open so the
+  // Web panel keeps working without the token.
+  apiToken: z.string(),
+
+  // --- semantic: local embedding provider (v0.2) --------------------------
+  // "openai" keeps the legacy external-API path (settings vector config);
+  // "local" runs an ONNX model in-process; "ollama" calls a local Ollama.
+  embedProvider: z.union([z.const("openai"), z.const("local"), z.const("ollama")]).default("openai"),
+
+  // Local ONNX embedder (transformers.js / onnxruntime).
+  localEmbedModel: z.string().default("Xenova/bge-small-zh-v1.5"),
+  localEmbedDimension: z.natural().default(512),
+  localEmbedDevice: z.union([z.const("cpu"), z.const("gpu")]).default("cpu"),
+  localEmbedBatchSize: z.natural().min(1).max(64).default(8),
+
+  // Ollama embedder.
+  ollamaBaseUrl: z.string().default("http://localhost:11434"),
+  ollamaModel: z.string().default("nomic-embed-text"),
+
+  // Model download/cache. When empty (default), models are cached under the
+  // user-level path ~/.dsh/mneme/models (resolved in local-embedder/reranker);
+  // a non-empty value is used verbatim.
+  embedModelCacheDir: z.string().default(""),
+  embedModelMirror: z.string().default("https://hf-mirror.com"),
+
+  // issue #194：模型文件下载的断点续传与重试。开启时 transformers.js 的 env.fetch 被
+  // 替换为带断点续传的实现（已收字节落盘、Range/If-Range 续传、空闲看门狗），大文件
+  // 中断后不必整份重来；关闭 = env.fetch 保持原样（线上回滚开关）。
+  resilientModelDownload: z.boolean().default(true),
+
+  // 自管运行时目录（issue #131）。空 = ~/.dsh/mneme/runtime：里面放收编或下载来的
+  // transformers + onnxruntime 闭包，插件经 src/runtime/loader.js 的三层解析加载它。
+  // 目的就是让这条重依赖不必留在宿主 profile 的依赖图里——profile 是所有插件共用的
+  // 依赖图，留在里面会让「装任何插件都要替它重走一遍这条链」。
+  runtimeDir: z.string().default(""),
+
+  // 运行时取件的两个来源（issue #131 / PR-C）。都是「克制」的默认：留空 = 不额外改变行为。
+  // - runtimeTarballDir：本地 .tgz 目录。某个包网络下不到时（例如 onnxruntime-node），
+  //   把 `npm pack <pkg>` 出来的 tgz 丢进这个目录即可离线取件；有它就优先于联网。
+  // - runtimeMirror：registry 镜像前缀，例如 https://npmmirror.com/mirrors/npm/ 。
+  //   留空则用 runtime-manifest.json 里写死的官方地址（那是随包发布的固定清单）。
+  runtimeTarballDir: z.string().default(""),
+  runtimeMirror: z.string().default(""),
+
+  // Vector search tuning.
+  vectorSearchTopK: z.natural().min(1).max(100).default(20),
+  vectorSearchThreshold: z.number().min(0).max(1).default(0.65),
+  hybridSearchVectorWeight: z.number().min(0).max(1).default(0.6),
+  hybridSearchKeywordWeight: z.number().min(0).max(1).default(0.4),
+  // Lazy auto-backfill of missing embeddings on boot (Bug2): when the vector
+  // API is configured and rows still lack an embedding, the index is rebuilt
+  // in the background after a short delay, rate-limited in batches. On by
+  // default; set false to keep the backfill manual only.
+  autoReindexOnBoot: z.boolean().default(true),
+  // Semantic-first injection (Bug4): when enabled, injectCandidates with a
+  // non-empty query recalls via the vector index first and falls back to the
+  // rule-based pick to fill/dedupe. Empty query / no vector → legacy behavior.
+  hybridInject: z.boolean().default(true),
+
+  // --- recall optimization (v0.5.0) ----------------------------------------
+  // BM25 third recall path beside vector + LIKE keyword (1.1): per-token IDF
+  // scoring recalls rows whose query terms are scattered — identifiers, code
+  // fragments, mixed CJK/ASCII — where substring LIKE cannot match.
+  bm25SearchEnabled: z.boolean().default(true),
+  // Query-aware vector cutoff (1.2) replacing the fixed 0.65: entity:/attr:
+  // prefixes loosen to 0.5, short queries tighten to 0.7, long queries loosen
+  // to 0.6, and a decisive top-1/top-5 score gap loosens to 0.5 so the tail
+  // still reaches the reranker. Off = legacy fixed threshold behavior.
+  adaptiveThresholdEnabled: z.boolean().default(true),
+  // Session-scoped hot memory (1.3): the latest N dialogue rounds rendered
+  // ahead of the long-term recall block — short-term context that never
+  // enters the memory store.
+  hotMemoryEnabled: z.boolean().default(true),
+  hotMemoryRounds: z.natural().min(1).max(50).default(5),
+  hotMemoryMaxTokens: z.natural().min(200).max(32000).default(2000),
+  // Topic-ranked injection (2.2): when a query vector is available the whole
+  // injection candidate list is re-ordered by similarity to the current
+  // query instead of keeping the rule-based order.
+  selectiveInjectEnabled: z.boolean().default(true),
+  // Search-time semantic dedup (2.3): greedy pass over the merged candidate
+  // list dropping rows whose embedding cosine-similarity to an already-kept
+  // row exceeds the threshold — duplicates are filtered at recall time
+  // instead of waiting for a dream consolidation. Opt-in aggressive mode:
+  // small embedding models can collapse legitimately distinct rows, so the
+  // default keeps every recalled row.
+  searchSemanticDedup: z.boolean().default(false),
+  searchSemanticDedupThreshold: z.number().min(0.5).max(1).default(0.95),
+
+  // Recall fusion recipe (plan #1): how the keyword/vector/BM25 ranked lists
+  // are combined into the final ranking. `blend` (default) is the legacy
+  // behavior — weighted sum for vector/hybrid, union backfill for auto —
+  // unchanged. `rrf` (Reciprocal Rank Fusion) and `minmax` (min-max normalized
+  // weighted sum) are rank/scale-aware recipes that fix the unit mismatch the
+  // issue describes (raw cosine vs keyword score vs normalized IDF are added
+  // directly). Off by default so existing behavior holds exactly.
+  recallFusion: z.union([z.const("blend"), z.const("rrf"), z.const("minmax")]).default("blend"),
+  // Attach a `signals` object { keyword, vector, bm25, final } to each search
+  // result for transparency/debugging (plan #2). Default off; when on it only
+  // decorates the returned rows, never changes the ranking.
+  signalTransparency: z.boolean().default(false),
+
+  // --- semantic: rerank layer (v0.2) --------------------------------------
+  // Opt-in by default (item ⑥): the local cross-encoder pulls in onnxruntime
+  // (transformers.js) at init, so a bare install must not load it. Only an
+  // explicit rerankEnabled=true + rerankProvider="local" constructs LocalReranker.
+  rerankEnabled: z.boolean().default(false),
+  rerankProvider: z.union([z.const("local"), z.const("none")]).default("none"),
+  rerankModel: z.string().default("Xenova/bge-reranker-base"),
+  rerankBatchSize: z.natural().min(1).max(64).default(8),
+  rerankMaxCandidates: z.natural().min(5).max(100).default(30),
+  rerankScoreThreshold: z.number().min(0).max(1).default(0.1),
+  // #188：量化档，与嵌入层的 useDtype 同语义（q8 = model_quantized.onnx，约为
+  // fp32 体积的 1/4）。此前重排层不传 dtype，即使缓存里已有量化文件也会去下载
+  // 1GB 级的 model.onnx。非法值由 transformers 在 init 时抛出 → 重排降级并告警。
+  rerankDtype: z.string().default("q8"),
+
+  // --- reflection: update decision + failure tracking (v0.2.1) ------------
+  reflectionUpdateEnabled: z.boolean().default(true),
+  reflectionFailureTracking: z.boolean().default(true),
+  reflectionUpdateMaxPerRun: z.natural().min(0).max(5).default(2),
+  reflectionUpdateMinAgeHours: z.natural().min(0).max(168).default(24),
+
+  // --- conflict freeze: manual review for conflicting memories (v0.2.1) ---
+  // Opt-in by default: when true, conflicting memories are not auto-merged
+  // and are marked as pending manual review instead.
+  conflictFreezeEnabled: z.boolean().default(false),
+  // Maximum number of frozen conflicts to keep pending for manual review.
+  conflictFreezeMaxPending: z.natural().min(1).max(1000).default(100),
+
+  // --- entity gene (v0.3.0) -----------------------------------------------
+  // Opt-in: when false (default) nothing in the pipeline extracts entities.
+  // The storage layer (entities/entity_attrs/entity_relations tables + CRUD)
+  // is always available regardless of this flag.
+  entityExtractionEnabled: z.boolean().default(false),
+  // Optional provider override for entity extraction; empty = use the caller's
+  // default provider/model. Combined with entityExtractionModel — provider
+  // without model (or vice versa) falls through to the caller default.
+  entityExtractionProvider: z.string().default(""),
+  // Optional model override for entity extraction; empty = use the caller's
+  // default provider/model.
+  entityExtractionModel: z.string().default(""),
+  // Reasoning effort for entity extraction (issue #109), mirrors
+  // dreamReasoningEffort pass-through: 'none' omits the field / provider
+  // default; off/low/medium/high passed through. A provider that rejects the
+  // effort retries once without it, so opting in is safe to experiment with.
+  entityExtractionReasoning: z.union([
+    z.const("low"),
+    z.const("medium"),
+    z.const("high"),
+    z.const("none")
+  ]).default("none"),
+  // Cap on entities per extraction pass and attributes per entity.
+  entityExtractionMaxEntities: z.natural().min(1).max(20).default(10),
+  entityExtractionMaxAttrs: z.natural().min(1).max(50).default(20),
+  // Prefix/semantic search over entity names (used by recall).
+  entitySearchEnabled: z.boolean().default(true),
+  // 图召回轴（issue #219）：查询文本命中实体名时，把该实体挂联的记忆并入
+  // 检索融合池（与 BM25 同级的确认/回填信号）。默认关=检索行为与 #219 前
+  // 逐字节一致；走 feature_flags 面板可启停，lightMode 强制关闭。
+  entityRecallEnabled: z.boolean().default(false),
+
+  // --- sleep mode: idle-triggered deep maintenance (v0.4.0) ---------------
+  // Opt-in, off by default. Unlike autoDream (threshold-triggered, lightweight)
+  // sleep fires when the store has been quiet for sleepIdleMinutes and deep-
+  // maintains the whole library: conflict resolution, archival demotion,
+  // pattern discovery and entity relation completion. Abortable on user
+  // activity, audited into dream_runs (run_type='sleep'), and serialized with
+  // autoDream so the two never overlap.
+  sleepModeEnabled: z.boolean().default(false),
+  // Quiet window before a cycle fires (minutes).
+  sleepIdleMinutes: z.natural().min(1).max(60).default(5),
+  // Minimum gap between two sleep runs (hours) — a second idle window within
+  // this interval does not retrigger.
+  sleepMinIntervalHours: z.natural().min(1).max(168).default(8),
+  // Conflict adjudication strictness:
+  //   gentle    only high-confidence conflicts (threshold 0.92) are resolved
+  //   normal    standard dream-level (threshold 0.85)
+  //   aggressive low-confidence pairs are also adjudicated (threshold 0.75)
+  sleepConflictStrictness: z.union([
+    z.const("gentle"),
+    z.const("normal"),
+    z.const("aggressive")
+  ]).default("normal"),
+  // Issue #126：冲突阶段的动作集。"conflict"（默认 = 现状）只用 conflict/keep——
+  // 后台自动流程不静默扩张行为；"full" 开放六分支（merge / update / supersede /
+  // differentiate / conflict / keep），互补型与演进型重复因此有了正确出口，不再
+  // 被迫"输赢化"（实测抽样 10 对里 2 对属演进型/互补型，用 conflict 处理会丢信息）。
+  sleepActionSet: z.union([
+    z.const("conflict"),
+    z.const("full")
+  ]).default("conflict"),
+  // Archival demotion tiering (days since last access):
+  //   >= sleepArchiveDays  → shrink to summary, full body kept in _full_content
+  //   >= sleepCompressDays → archived outright (entity relations preserved)
+  sleepArchiveDays: z.natural().min(7).max(365).default(30),
+  sleepCompressDays: z.natural().min(7).max(365).default(90),
+  // Pattern discovery scan window (most recent memories to scan).
+  sleepPatternMinMemories: z.natural().min(10).max(1000).default(100),
+  // How far back pattern discovery considers entity attr changes (days).
+  sleepPatternLookbackDays: z.natural().min(1).max(90).default(30),
+  // Max pattern memories minted per run (0 = disabled).
+  sleepMaxPatternPerRun: z.natural().min(0).max(10).default(3),
+  // Optional LLM route override for sleep's bulk passes (empty = use dream
+  // route / agent default model).
+  sleepProvider: z.string().default("").description("sleep 深维护专用模型服务商，留空用巩固模型或当前模型。"),
+  sleepModel: z.string().default("").description("sleep 深维护专用模型，留空用巩固模型或当前模型；建议同巩固模型选非思考模型。"),
+  // Pass-through reasoning effort for sleep's LLM passes, same semantics as
+  // dreamReasoningEffort (Issue #135 建议 4/5): unset resolves to the lowest
+  // effort the model declares; explicit 'none' omits the field; off/low/
+  // medium/high are forwarded verbatim.
+  sleepReasoningEffort: z.union([
+    z.const("off"),
+    z.const("low"),
+    z.const("medium"),
+    z.const("high"),
+    z.const("none")
+  ]).description("同 dreamReasoningEffort：sleep 各阶段 LLM 的推理档位，未配置 = 自动取模型支持的最低档；显式 'none' = 不发送字段、用服务商自带默认。"),
+
+  // --- epistemic trust: memory source credibility (v0.4.5) -----------------
+  // Distinguish memories by source: observation (measured / witnessed),
+  // subjective (opinion / guess) and inferred (derived from other evidence).
+  // Opt-in by default: when false (default) retrieval ranking, injection
+  // marking and dream merge/conflict keepSource are untouched and
+  // epistemic_status stays inert data (still written + inferred on save, just
+  // never used to influence behavior).
+  trustEpistemicWeighting: z.boolean().default(false),
+
+  // --- memory quality filter (Bug7) ------------------------------------------
+  // Heuristic gate on what deserves the injection/recall surface. When enabled,
+  // saveWithDedupe scores each new memory after dedupe and before write:
+  //   score >= degradeThreshold (60) → stored normally
+  //   archiveThreshold (30) <= score < 60 → quality_score persisted and the
+  //       injection sort re-ranks by importance * quality_score/100 (degraded)
+  //   score < 30 → archived + tagged low_quality (still explicitly searchable)
+  // Meta-memory markers, near-duplicates and repetitive filler lose points.
+  memoryQualityFilter: z.object({
+    enabled: z.boolean().default(true),
+    archiveThreshold: z.natural().min(1).max(100).default(30),
+    degradeThreshold: z.natural().min(1).max(100).default(60),
+    minContentLength: z.natural().min(1).max(1000).default(10),
+    // Issue #135 附属发现 1：importance ≥ 该值的记忆不参与静默自动归档——评分
+    // 与信号标签照常写入（可观测）、注入排序照常降权，但 setArchived 跳过。
+    // 报告实测 150 条低分归档里 128 条 importance ≥ 4（51 条 = 5）。设 1 = 全部
+    // 豁免（等效关闭自动归档），设 5 = 仅最重要的豁免。
+    exemptImportance: z.natural().min(1).max(5).default(4)
+  }).default({}),
+
+  // --- LLM audit trail (Bug8) ------------------------------------------------
+  // Records every background LLM call (autoDream consolidation + summary,
+  // autoSummarize compression) into llm_audit_logs: tokens, duration, status
+  // and which trigger produced it. Failures are recorded as status=error and
+  // never block the feature. retentionDays bounds the table: older rows are
+  // purged on boot.
+  llmAudit: z.object({
+    enabled: z.boolean().default(true),
+    retentionDays: z.natural().min(1).max(3650).default(90)
+  }).default({}),
+
+  // --- recall evaluation: test-result storage (v0.4.6, 方案 B) --------------
+  // Separate retrieval evaluation snapshots from the production recall audit.
+  // When false (default) evaluateRetrieval still computes precision/recall/mrr
+  // and returns them to the caller, but writes nothing to recall_evals — the
+  // eval table only grows when the operator opts in. Production searchMemories
+  // audits to recall_runs and NEVER touches recall_evals, regardless of this
+  // flag (production isolation is unconditional).
+  evalPersistTestResults: z.boolean().default(false),
+
+  // --- standalone external API (v0.7.12) ------------------------------------
+  // A plain node:http server for ecosystem integrations that cannot reach the
+  // DSH-internal webServer. Disabled by default; when enabled the Bearer token
+  // is persisted in the settings kv ("external_api"), auto-generated on first
+  // boot. Bind host: keep the loopback default — moving it to a non-loopback
+  // address exposes the whole memory store to the network and is the
+  // operator's responsibility.
+  externalApiEnabled: z.boolean().default(false),
+  externalApiPort: z.natural().default(8790),
+  externalApiHost: z.string().default("127.0.0.1"),
+
+  // --- light mode preset (v0.7.12) -------------------------------------------
+  // One switch for low-resource setups: turns off every background/semantic
+  // heavy path (dream consolidation, entity extraction, vector pipeline,
+  // reranker, BM25, semantic dedup / selective inject, sleep mode) while
+  // keeping the core loop (autoInject, autoSummarize, hot memory, quality
+  // filter, keyword search). Applied by applyLightModePreset before the config
+  // reaches any service; a persisted panel_mode="light" (settings kv) counts
+  // as lightMode=true too and wins over the bundle config.
+  lightMode: z.boolean().default(false),
+
+  // --- heat: v0.7.0 self-evolution (heat + interest drift) ----------------
+  // 总开关，默认关（v0.7.12+ 用户已习惯无 heat 行为，默认开=全员行为变更）。
+  // 开启后：提供热度字段 / sleep 降级联合判定保护 / 前端热度投影，并只在
+  // 注入排序的优先级层内乘 heat（#218 v1；store 的 order=chrono 分页序与
+  // 召回融合序不动）。关闭则跳过所有 heat 计算与热度触达，注入排序乘数
+  // 恒 1，sleep 降级退回纯时间分层。
+  // 也走 feature_flags（FEATURE_FLAG_BOOLEANS 白名单），面板可启停=线上回滚开关。
+  heatEnabled: z.boolean().default(false),
+  // 广义指数形状参数 β（heat = exp(-λ·Δt^β)，issue #218 拍板）：β=1 纯指数。
+  // 快慢以 Δt>1 小时为准——β<1 衰减更慢（亚线性长尾）、β>1 更快（超线性）；
+  // 0<Δt<1 的首小时内方向相反（Δt^β 随 β 增大而变小）。专家调优项，不进面板白名单。
+  heatGlobalBeta: z.number().min(0.5).max(2).default(1.0),
+  // per-type 衰减因子 λ；λ=0 的类型免疫（热度恒 1.0，sleep 永不降级）。
+  // 未知类型走默认 0.002。dict 的键为 type 字符串、值为数字 λ。
+  heatTypeDecay: z.dict(z.number(), z.string()).default({ ...TYPE_DECAY_DEFAULTS }),
+  // sleep 降级联合判定的热度下限：heat < 该值 且 importance<5 才允许降级。
+  sleepHeatThreshold: z.number().min(0).max(1).default(0.05),
+  // recordRecall 默认值（recall_runs 记录默认开；显式传 false 的调用方不受影响）。
+  recallRecordDefault: z.boolean().default(true),
+  // recall_runs 滚动清理保留天数。
+  recallRetentionDays: z.natural().min(1).max(3650).default(90),
+
+  // --- scope: v0.8.0 A1 存储层（issue #17）--------------------------------
+  // 总开关默认关：关闭时写入不标注 scope、去重维持 (type, title) 现状，行为
+  // 逐字节不变。开启后 memory_save 写入 agent_scope（session header 的
+  // agentPreset）与 workspace_scope（registry 反查 canonical path，header.cwd
+  // 兜底，取不到 NULL——解析绝不阻塞写入），去重键扩展为 (type, title,
+  // agent_scope, workspace_scope, sensitivity)。检索侧加权/过滤在 A2/A3 落地。
+  // 也走 feature_flags（FEATURE_FLAG_BOOLEANS 白名单），面板可启停=线上回滚开关。
+  scopeEnabled: z.boolean().default(false),
+  // strictScope（A3）：硬过滤模式。关闭=A2 软隔离（他 scope 降权保留可见）；
+  // 开启后检索/注入/list/get 按 issue #17 四象限可见性公式硬过滤——带他 scope
+  // 的记忆完全不可见，未标注（NULL）恒可见；当前会话某维度解析不到时该维度
+  // 带标注的记忆一律不可见（fail-closed：身份不明只见全局）。依赖 scopeEnabled
+  // 打开才有意义（没有写入标注就无可过滤维度），但独立成键：可先开标注积累
+  // 数据、观察 A2 加权质量后再切硬过滤。
+  strictScope: z.boolean().default(false),
+});
+
+// Fields forced to false by the light-mode preset. Everything not listed here
+// (autoInject, autoSummarize, hotMemory*, memoryQualityFilter, dream
+// thresholds/delays, ...) is left untouched — those are the core loop.
+const LIGHT_MODE_OFF = [
+  "entityExtractionEnabled",
+  "autoDream",
+  "sleepModeEnabled",
+  "rerankEnabled",
+  "autoReindexOnBoot",
+  "hybridInject",
+  "searchSemanticDedup",
+  "selectiveInjectEnabled",
+  "bm25SearchEnabled",
+  // 轻量模式不开图召回轴（#219，依赖实体抽取产出；抽取本身已被关掉）。
+  "entityRecallEnabled",
+  // 轻量模式不开叙述条（额外 LLM 调用；#164 对齐，opt-in）。
+  "dreamNarrativeEnabled",
+  // 轻量模式不开热计算（heat 属于重型增强；关掉后 sleep 降级也退回纯时间分层）。
+  "heatEnabled"
+];
+
+/**
+ * Apply the light-mode preset to a resolved config object (pure function,
+ * exported for tests). When cfg.lightMode is not exactly true the config is
+ * returned unchanged; otherwise a shallow copy carries false for every heavy
+ * feature. Idempotent and side-effect free.
+ */
+export function applyLightModePreset(cfg) {
+  if (cfg?.lightMode !== true) return cfg;
+  const preset = { ...cfg, lightMode: true };
+  for (const key of LIGHT_MODE_OFF) preset[key] = false;
+  return preset;
+}