@modusensus/dsh-mneme 0.7.14 → 0.7.16

package/src/dream.js

@@ -1,7 +1,7 @@
 import { validateDecisions, applyDecisions } from "./dream/decisions.js";
 import { clusterMemories, findPotentialConflicts } from "./dream/clustering.js";
 import { createHash, randomUUID } from "node:crypto";
-export { validateDecisions, applyDecisions };
+export { validateDecisions, applyDecisions, withEffortFallback };
 
 
 // Extract the first JSON array from LLM output, tolerating markdown fences,
@@ -282,6 +282,15 @@ async function runAuditedLlm(ctx, service, config, spec, body) {
       // record it as error here so the audit shows the truth.
       status = "error";
       errorMessage = errorMessage ?? "llm stream aborted or errored";
+    } else if (typeof spec.auditError === "function") {
+      // A stream that returned text but yields nothing usable is still a
+      // failed call — record it as error, not the default success, so the
+      // audit no longer contradicts a failed run (dream "no json array").
+      const message = spec.auditError(result);
+      if (message) {
+        status = "error";
+        errorMessage = message;
+      }
     }
     return result;
   } catch (error) {
@@ -311,20 +320,50 @@ async function runAuditedLlm(ctx, service, config, spec, body) {
 }
 
 /**
- * Resolve the LLM route: agent default model (deployment) first, plugin config
- * (dreamProvider/dreamModel) as fallback. Falls through to undefined when no
- * route exists — runDream then fails safe. Fallback is logged so a silent
- * route switch is observable.
+ * Reasoning-effort rejection fallback (v0.8.1): a configured dreamReasoningEffort
+ * / sleepReasoningEffort may be rejected by the provider (volcano-engine returns
+ * UNSUPPORTED_REASONING_EFFORT for values it does not accept — "off" is known
+ * rejected there). When that happens, retry once WITHOUT the reasoning field
+ * instead of hard-failing the run, so effort config is safe to experiment with:
+ * accepted → reasoning capped; rejected → provider default (old behavior),
+ * logged so the rejection is observable.
+ */
+async function withEffortFallback(ctx, effort, attempt, fallback) {
+  if (!effort || effort === "none") return attempt();
+  try {
+    return await attempt();
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    // matches both "reasoning effort" (natural language) and the bare
+    // "UNSUPPORTED_REASONING_EFFORT" error code (underscore).
+    if (!/reasoning[\s_]*effort/i.test(message)) throw error;
+    ctx.logger?.warn?.(`dsh-mneme dream: reasoningEffort "${effort}" rejected (${message}); retrying without it`);
+    return fallback();
+  }
+}
+
+/**
+ * Resolve the LLM route (Issue #25): an explicit plugin config
+ * (dreamProvider/dreamModel) is the user's declared override and wins; the
+ * agent default model (deployment) is only a fallback when no config route is
+ * set. In a standard DSH install agentDefaultModel always resolves, so without
+ * this ordering the config route would be dead code and dreamProvider/dreamModel
+ * could never take effect (v0.7.11 regressed this; README §config documents
+ * config-first). Falls through to undefined when no route exists — runDream
+ * then fails safe. A config→default switch is logged so it is observable.
  */
 function resolveRoute(ctx, config, logger) {
+  if (config.dreamProvider && config.dreamModel) return { provider: config.dreamProvider, model: config.dreamModel };
   try {
     const sel = ctx.agentDefaultModel?.currentSelection?.();
-    if (sel?.provider && sel?.model) return { provider: sel.provider, model: sel.model };
-    logger?.warn?.("dsh-mneme dream: agentDefaultModel unavailable, falling back to config route");
+    if (sel?.provider && sel?.model) {
+      logger?.info?.("dsh-mneme dream: no dreamProvider/dreamModel config, falling back to agent default");
+      return { provider: sel.provider, model: sel.model };
+    }
+    logger?.warn?.("dsh-mneme dream: agentDefaultModel unavailable, no config route either");
   } catch (error) {
-    logger?.warn?.(`dsh-mneme dream: agentDefaultModel lookup failed, falling back to config route: ${String(error)}`);
+    logger?.warn?.(`dsh-mneme dream: agentDefaultModel lookup failed: ${String(error)}`);
   }
-  if (config.dreamProvider && config.dreamModel) return { provider: config.dreamProvider, model: config.dreamModel };
   return undefined;
 }
 
@@ -585,28 +624,37 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       ? CONSOLIDATION_PROMPT + `\n\n当前为「冲突冻结」模式：检测到内容矛盾的条目时，仍请输出 conflict，并以 winner/loser 作为候选、reason 说明理由；冲突不会被自动裁决，而会冻结待人工确认。`
       : CONSOLIDATION_PROMPT;
     let decisionText;
+    // 加固（v0.8.1）：配置的 reasoningEffort 被 provider 拒收时回退重试一次
+    // （不带该字段），避免 thinking 模型配置 low/medium 直接整单失败。解析放
+    // 在 auditError 检查器里、闭包交回主流程，避免二次解析；解析失败同时如实
+    // 记 audit error 并在日志带原始输出前 300 字节，便于定位"推理吞预算返回空体"。
+    const effort = config.dreamReasoningEffort && config.dreamReasoningEffort !== "none" ? config.dreamReasoningEffort : null;
+    let decisions = null;
+    const runConsolidation = (withEffort) => runAuditedLlm(ctx, service, config, {
+      triggerSource: "autoDream",
+      operationType: "dream_consolidate",
+      modelId: `${route.provider}:${route.model}`,
+      relatedMemoryIds: [...snapshot.keys()],
+      auditError: (text) => {
+        decisions = extractJsonArray(text);
+        return Array.isArray(decisions) ? null : "no json array in llm output";
+      }
+    }, (reportUsage) => streamText(ctx, {
+      provider: route.provider,
+      model: route.model,
+      purpose: "compaction",
+      maxTokens: config.dreamMaxTokens ?? 4096,
+      ...(withEffort && effort ? { reasoningEffort: effort } : {}),
+      messages: [
+        { role: "system", content: [{ type: "text", text: consolidationPrompt }] },
+        { role: "user", content: [{ type: "text", text: listText }] }
+      ]
+    }, reportUsage));
     try {
       // Bug8: the consolidation call is audited (tokens/time/status). A throw
       // re-propagates to the catch below; an aborted stream returns undefined
       // and is treated as a failed run after the check below.
-      decisionText = await runAuditedLlm(ctx, service, config, {
-        triggerSource: "autoDream",
-        operationType: "dream_consolidate",
-        modelId: `${route.provider}:${route.model}`,
-        relatedMemoryIds: [...snapshot.keys()]
-      }, (reportUsage) => streamText(ctx, {
-        provider: route.provider,
-        model: route.model,
-        purpose: "compaction",
-        maxTokens: config.dreamMaxTokens ?? 4096,
-        ...(config.dreamReasoningEffort && config.dreamReasoningEffort !== "none"
-          ? { reasoningEffort: config.dreamReasoningEffort }
-          : {}),
-        messages: [
-          { role: "system", content: [{ type: "text", text: consolidationPrompt }] },
-          { role: "user", content: [{ type: "text", text: listText }] }
-        ]
-      }, reportUsage));
+      decisionText = await withEffortFallback(ctx, effort, () => runConsolidation(true), () => runConsolidation(false));
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: consolidation llm call failed: ${String(error)}`);
       return finish({ ok: false, error: "llm failed", summary: false });
@@ -615,10 +663,9 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       logger?.warn?.("dsh-mneme dream: consolidation llm stream aborted or errored");
       return finish({ ok: false, error: "llm failed", summary: false });
     }
-
-    const decisions = extractJsonArray(decisionText);
     if (!Array.isArray(decisions)) {
-      logger?.warn?.(`dsh-mneme dream: no json array in llm output (raw length ${decisionText?.length ?? 0})`);
+      const head = (decisionText ?? "").slice(0, 300).replace(/\s+/g, " ").trim();
+      logger?.warn?.(`dsh-mneme dream: no json array in llm output (raw length ${decisionText?.length ?? 0}; head: ${head})`);
       return finish({ ok: false, error: "no json array in llm output", summary: false });
     }
     const { ok, errors } = validateDecisions(decisions, snapshot, {
@@ -735,26 +782,25 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // Summary generation (second LLM call). A throwing stream is reported as
     // a failed run; summary:false marks a run that produced no summary.
     let summaryText;
+    const runSummary = (withEffort) => runAuditedLlm(ctx, service, config, {
+      triggerSource: "autoDream",
+      operationType: "dream_summarize",
+      modelId: `${route.provider}:${route.model}`,
+      relatedMemoryIds: []
+    }, (reportUsage) => streamText(ctx, {
+      provider: route.provider,
+      model: route.model,
+      purpose: "compaction",
+      maxTokens: config.dreamMaxTokens ?? 2048,
+      ...(withEffort && effort ? { reasoningEffort: effort } : {}),
+      messages: [
+        { role: "system", content: [{ type: "text", text: SUMMARY_PROMPT }] },
+        { role: "user", content: [{ type: "text", text: service.all().filter((m) => !m.archived && m.type !== "summary").map((m) => `- ${m.title}: ${m.content}`).join("\n") }] }
+      ]
+    }, reportUsage));
     try {
       // Bug8: the summary call is audited too (operation dream_summarize).
-      summaryText = await runAuditedLlm(ctx, service, config, {
-        triggerSource: "autoDream",
-        operationType: "dream_summarize",
-        modelId: `${route.provider}:${route.model}`,
-        relatedMemoryIds: []
-      }, (reportUsage) => streamText(ctx, {
-        provider: route.provider,
-        model: route.model,
-        purpose: "compaction",
-        maxTokens: config.dreamMaxTokens ?? 2048,
-        ...(config.dreamReasoningEffort && config.dreamReasoningEffort !== "none"
-          ? { reasoningEffort: config.dreamReasoningEffort }
-          : {}),
-        messages: [
-          { role: "system", content: [{ type: "text", text: SUMMARY_PROMPT }] },
-          { role: "user", content: [{ type: "text", text: service.all().filter((m) => !m.archived && m.type !== "summary").map((m) => `- ${m.title}: ${m.content}`).join("\n") }] }
-        ]
-      }, reportUsage));
+      summaryText = await withEffortFallback(ctx, effort, () => runSummary(true), () => runSummary(false));
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: summary llm call failed: ${String(error)}`);
       return finish({ ok: false, error: "llm failed", applied, decisions: auditDecisions, outcome, frozen: frozenCount, summary: false });

package/src/index.js

@@ -66,7 +66,30 @@ export const apply = (ctx, config) => {
   // semantic feature off and keeps the core loop (autoInject, autoSummarize,
   // hot memory, quality filter).
   const lightMode = rawCfg.lightMode === true || settings.getPanelMode() === "light";
-  const cfg = applyLightModePreset({ ...rawCfg, lightMode });
+  // 功能开关合并顺序即优先级：用户显式开关（feature_flags kv，面板写入）>
+  // 轻量预设（applyLightModePreset 批量置关的重型能力）> bundle 配置。预设必须
+  // 先应用、用户开关后展开，否则 LIGHT_MODE_OFF 会把用户显式打开的开关再次
+  // 压掉。合并结果只作用于本次启动：面板改开关后与 panel_mode 一样在下次
+  // 启动生效。
+  // 嵌套对象开关按首个点号拆开（kv 里平铺存的 "memoryQualityFilter.enabled" →
+  // cfg.memoryQualityFilter.enabled），点号键不原样留在 cfg 顶层属性里。
+  const flags = settings.getFeatureFlags();
+  const flatFlags = {};
+  const nestedFlags = {};
+  for (const [key, value] of Object.entries(flags)) {
+    const dot = key.indexOf(".");
+    if (dot > 0) {
+      const objKey = key.slice(0, dot);
+      const subKey = key.slice(dot + 1);
+      nestedFlags[objKey] = { ...(nestedFlags[objKey] ?? {}), [subKey]: value };
+    } else {
+      flatFlags[key] = value;
+    }
+  }
+  const cfg = { ...applyLightModePreset({ ...rawCfg, lightMode }), ...flatFlags };
+  for (const [objKey, sub] of Object.entries(nestedFlags)) {
+    cfg[objKey] = { ...(cfg[objKey] ?? {}), ...sub };
+  }
 
   const mirror = createMirror(memoryDir);
   const service = createService({ store, mirror, config: cfg, logger: ctx.logger });
@@ -340,7 +363,7 @@ export const apply = (ctx, config) => {
       add: () => { throw new Error("commands unavailable"); },
       remove: () => false,
       list: () => []
-    }, embedder, { vectorIndex, reranker }, cfg.apiToken);
+    }, embedder, { vectorIndex, reranker }, cfg.apiToken, cfg);
     disposers.push(api.dispose);
   }
 

package/src/mirror.js

@@ -47,6 +47,92 @@ function renderMemory(m) {
   return lines.join("\n");
 }
 
+/**
+ * Render one type's memories into exactly the mirror-file text (header +
+ * per-memory blocks, updated_at DESC like sync). sync() writes this to disk;
+ * the /export endpoint returns the same text, so an exported markdown is
+ * byte-compatible with a mirror file and can be fed straight back through
+ * parseHumanEdits → mergeHumanEdits. Unknown type → undefined.
+ */
+export function renderMirrorText(type, memories) {
+  const name = TYPE_FILE[type];
+  if (!name) return undefined;
+  const items = (memories ?? [])
+    .slice()
+    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+  const header = `# ${name} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`;
+  const body = items.map(renderMemory).join("\n");
+  return header + body;
+}
+
+/**
+ * Parse mirror text back into {id, title, content} entries for human edits.
+ * Pure text-in/edits-out core: readHumanEdits feeds it mirror file contents
+ * and the /import endpoint feeds it user-pasted markdown, so both paths share
+ * one parsing implementation (行为一致是硬约束——import 必须能吃回 export 与
+ * 磁盘镜像)。Entries are anchored on "- **ID**: `...`" lines that are followed
+ * by the "- **类型**:" metadata line (structural entry head): each entry's
+ * block spans from its ID line up to the next ID line (or end of text). The
+ * block head (the ID line plus the generated metadata run) and the trailing
+ * structural "---" separator are stripped; everything in between is the entry
+ * body, so user content containing "---", metadata-like lines, or even a
+ * machine-format "- **ID**: `x`" line is preserved. The title is the "## "
+ * heading preceding the ID line.
+ */
+export function parseHumanEdits(text) {
+  // CRLF 归一化（readHumanEdits 原有的读取侧处理移入纯函数，Windows 手工编辑
+  // 的文件与导入文本都能正确解析）。
+  const normalized = String(text ?? "").replace(/\r\n/g, "\n");
+  const edits = [];
+  // Anchor on the ID line only when it is a structural entry head: the
+  // machine-rendered ID line is always followed by the "- **类型**:" line.
+  // A body line like "- **ID**: `x`" is not, so it never splits the block
+  // or produces a ghost entry.
+  const anchors = [...normalized.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*类型\*\*:/gm)];
+  let prevEnd = 0;
+  for (let i = 0; i < anchors.length; i++) {
+    const anchor = anchors[i];
+    const blockStart = anchor.index;
+    const blockEnd = i + 1 < anchors.length ? anchors[i + 1].index : normalized.length;
+
+    // Title: last "## " heading before this ID line (file header region /
+    // previous block tail). Body headings of earlier entries come before
+    // the structural "---" + "## " of this entry, so the last match wins.
+    const titleMatches = [...normalized.slice(prevEnd, blockStart).matchAll(/^## (.+)$/gm)];
+    const titleMatch = titleMatches[titleMatches.length - 1];
+
+    // Body: the ID line and the generated metadata run are structural head;
+    // everything after them up to the trailing "---" separator is the body.
+    let body = normalized
+      .slice(blockStart, blockEnd)
+      .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
+      .replace(/^(- \*\*(类型|重要性|标签|更新时间|来源)\*\*:.*\n?)+/, "")
+      .replace(/^<!-- mirror-digest: [a-f0-9]+ -->\n?/m, "");
+    const separators = [...body.matchAll(/^---\s*$/gm)];
+    const lastSep = separators[separators.length - 1];
+    if (lastSep) body = body.slice(0, lastSep.index);
+    body = body.trim();
+
+    // The machine-written "更新时间" line records the store's updated_at at
+    // render time — the version token for detecting a concurrent store write
+    // during a three-way merge of human edits (see service.syncMirror).
+    const block = normalized.slice(blockStart, blockEnd);
+    const updatedMatch = block.match(/- \*\*更新时间\*\*: ([^\n]+)/);
+    const digestMatch = block.match(/<!-- mirror-digest: ([a-f0-9]+) -->/);
+    edits.push({
+      id: anchor[1],
+      title: titleMatch ? unescape(titleMatch[1]).trim() : undefined,
+      content: body,
+      updated_at: updatedMatch ? updatedMatch[1].trim() : undefined,
+      digest: digestMatch ? digestMatch[1] : undefined
+    });
+
+    const lineEnd = normalized.indexOf("\n", blockStart);
+    prevEnd = lineEnd === -1 ? normalized.length : lineEnd + 1;
+  }
+  return edits;
+}
+
 export function createMirror(dir) {
   mkdirSync(dir, { recursive: true });
 
@@ -56,15 +142,9 @@ export function createMirror(dir) {
   }
 
   /**
-   * Parse a mirror file back into {id, title, content} entries for human edits.
-   * Entries are anchored on "- **ID**: `...`" lines that are followed by the
-   * "- **类型**:" metadata line (structural entry head): each entry's block
-   * spans from its ID line up to the next ID line (or end of file). The block
-   * head (the ID line plus the generated metadata run) and the trailing
-   * structural "---" separator are stripped; everything in between is the entry
-   * body, so user content containing "---", metadata-like lines, or even a
-   * machine-format "- **ID**: `x`" line is preserved. The title is the "## "
-   * heading preceding the ID line.
+   * Read the mirror files and parse them back into human edits. The pure
+   * parsing logic lives in the exported parseHumanEdits (shared with /import);
+   * this wrapper only owns the "read file → text" side.
    */
   function readHumanEdits(type = undefined) {
     const types = type ? [type] : Object.keys(TYPE_FILE);
@@ -72,53 +152,7 @@ export function createMirror(dir) {
     for (const t of types) {
       const file = filePath(t);
       if (!file || !existsSync(file)) continue;
-      const text = readFileSync(file, "utf8").replace(/\r\n/g, "\n");
-      // Anchor on the ID line only when it is a structural entry head: the
-      // machine-rendered ID line is always followed by the "- **类型**:" line.
-      // A body line like "- **ID**: `x`" is not, so it never splits the block
-      // or produces a ghost entry.
-      const anchors = [...text.matchAll(/^- \*\*ID\*\*: `([^`]+)`\n- \*\*类型\*\*:/gm)];
-      let prevEnd = 0;
-      for (let i = 0; i < anchors.length; i++) {
-        const anchor = anchors[i];
-        const blockStart = anchor.index;
-        const blockEnd = i + 1 < anchors.length ? anchors[i + 1].index : text.length;
-
-        // Title: last "## " heading before this ID line (file header region /
-        // previous block tail). Body headings of earlier entries come before
-        // the structural "---" + "## " of this entry, so the last match wins.
-        const titleMatches = [...text.slice(prevEnd, blockStart).matchAll(/^## (.+)$/gm)];
-        const titleMatch = titleMatches[titleMatches.length - 1];
-
-        // Body: the ID line and the generated metadata run are structural head;
-        // everything after them up to the trailing "---" separator is the body.
-        let body = text
-          .slice(blockStart, blockEnd)
-          .replace(/^- \*\*ID\*\*: `[^`]+`\n?/, "")
-          .replace(/^(- \*\*(类型|重要性|标签|更新时间|来源)\*\*:.*\n?)+/, "")
-          .replace(/^<!-- mirror-digest: [a-f0-9]+ -->\n?/m, "");
-        const separators = [...body.matchAll(/^---\s*$/gm)];
-        const lastSep = separators[separators.length - 1];
-        if (lastSep) body = body.slice(0, lastSep.index);
-        body = body.trim();
-
-        // The machine-written "更新时间" line records the store's updated_at at
-        // render time — the version token for detecting a concurrent store write
-        // during a three-way merge of human edits (see service.syncMirror).
-        const block = text.slice(blockStart, blockEnd);
-        const updatedMatch = block.match(/- \*\*更新时间\*\*: ([^\n]+)/);
-        const digestMatch = block.match(/<!-- mirror-digest: ([a-f0-9]+) -->/);
-        edits.push({
-          id: anchor[1],
-          title: titleMatch ? unescape(titleMatch[1]).trim() : undefined,
-          content: body,
-          updated_at: updatedMatch ? updatedMatch[1].trim() : undefined,
-          digest: digestMatch ? digestMatch[1] : undefined
-        });
-
-        const lineEnd = text.indexOf("\n", blockStart);
-        prevEnd = lineEnd === -1 ? text.length : lineEnd + 1;
-      }
+      edits.push(...parseHumanEdits(readFileSync(file, "utf8")));
     }
     return edits;
   }
@@ -145,9 +179,9 @@ export function createMirror(dir) {
           // memories do not "resurrect" via readHumanEdits
           rmSync(file, { force: true });
         } else {
-          const header = `# ${TYPE_FILE[type]} — dsh-mneme 镜像\n\n<!-- 手工编辑此文件会被合并回记忆库（人工优先）。 -->\n\n`;
-          const body = items.map(renderMemory).join("\n");
-          writeFileSync(file, header + body, "utf8");
+          // 渲染走 renderMirrorText（与 /export 共用同一条渲染路径），磁盘镜像
+          // 与导出文本永远同构。
+          writeFileSync(file, renderMirrorText(type, items), "utf8");
         }
         results[type] = { ok: true };
       } catch (error) {

package/src/service.js

@@ -1511,6 +1511,8 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     findEntityByName: (n) => store.findEntityByName(n),
     findEntityById: (id) => store.findEntityById(id),
     getAttrsByMemory: (id) => store.getAttrsByMemory(id),
+    // 记忆详情侧栏：一条记忆关联到的实体（entity_attrs.memory_id 反查，纯读）。
+    entitiesForMemory: (id) => store.entitiesForMemory(id),
     getCurrentAttrs: (id) => store.getCurrentAttrs(id),
     migrateAttrsToMemory: (fromId, toId, now) => store.migrateAttrsToMemory(fromId, toId, now)
   };

package/src/settings.js

@@ -31,6 +31,155 @@ function parseList(raw) {
   }
 }
 
+// --- feature flags（功能开关）白名单 -----------------------------------------
+// 面板可逐项开关的后端能力。设计约束：
+// 1. 键名与类型必须和 config.js schema 同名同型，这份白名单是唯一校验源
+//    （api.js 复用它计算 effective），schema 增删能力键时要同步改这里。
+// 2. 持久化（kv "feature_flags"）只落白名单键；读到未知键、类型损坏或越界的
+//    值一律丢弃而不是报错——kv 会残留旧版本写入的键，读路径必须向前兼容。
+// 3. 写入是逐键校验的合并写：未知键/类型/范围不符抛 TypeError（消息含键名，
+//    供 API 透传给前端定位），校验不通过不落库，坏值永远进不了 kv。
+const FEATURE_FLAG_BOOLEANS = [
+  "autoInject",
+  "autoSummarize",
+  "hotMemoryEnabled",
+  "entityExtractionEnabled",
+  "codingRetrospect",
+  "autoDream",
+  "sleepModeEnabled",
+  "hybridInject",
+  "selectiveInjectEnabled",
+  "searchSemanticDedup",
+  "rerankEnabled",
+  "adaptiveThresholdEnabled",
+  "reflectionUpdateEnabled",
+  "reflectionFailureTracking",
+  "bm25SearchEnabled",
+  "conflictFreezeEnabled",
+  "trustEpistemicWeighting",
+  // 嵌套对象开关：config.js 里是 memoryQualityFilter / llmAudit 对象的 enabled
+  // 子字段。kv 按点号键平铺存（"memoryQualityFilter.enabled": false），index.js
+  // 合并时展开回嵌套对象，api.js 的 effective 从对象子字段取值。
+  "memoryQualityFilter.enabled",
+  "llmAudit.enabled"
+];
+// 整数开关的闭区间，与 config.js 里 z.natural().min().max() 对齐。
+const FEATURE_FLAG_INT_RANGES = {
+  distillRateLimitIntervalMs: [0, 60000],
+  distillRateLimitRetries: [0, 10],
+  distillRateLimitBaseDelayMs: [100, 60000],
+  distillMaxChars: [1000, 200000],
+  codingBoostFactor: [1, 5]
+};
+// 自由字符串开关（与 config.js 的 z.string() 同名同型）：trim 后 ≤200 字符，
+// 空串合法（= 跟随主对话模型/默认路径，面板显示 placeholder）。
+const FEATURE_FLAG_STRINGS = [
+  "dreamProvider",
+  "dreamModel",
+  "localEmbedModel",
+  "ollamaModel"
+];
+// URL 字符串开关：trim 后必须为空或合法 http/https URL（new URL() 校验协议，
+// 拒绝其余协议——这是 SSRF 防线的一部分）。
+const FEATURE_FLAG_URLS = ["ollamaBaseUrl"];
+// 枚举开关（与 config.js 的 z.union(z.const(...)) 对齐）：仅允许列出的值。
+const FEATURE_FLAG_ENUMS = {
+  embedProvider: ["openai", "local", "ollama"]
+};
+const FEATURE_FLAG_STRING_MAX = 200;
+
+// 供 api.js 复用同一份白名单（effective 只在白名单键上计算）。
+export const FEATURE_FLAG_SPEC = {
+  booleans: FEATURE_FLAG_BOOLEANS,
+  ints: FEATURE_FLAG_INT_RANGES,
+  strings: FEATURE_FLAG_STRINGS,
+  urls: FEATURE_FLAG_URLS,
+  enums: FEATURE_FLAG_ENUMS
+};
+
+/** ollamaBaseUrl 的协议白名单：只接受 http/https（SSRF 防线的一部分）。 */
+function isHttpUrl(value) {
+  try {
+    const protocol = new URL(value).protocol;
+    return protocol === "http:" || protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/** 校验单个开关值；不合法抛 TypeError（消息含键名）。 */
+function validateFlag(key, value) {
+  if (FEATURE_FLAG_BOOLEANS.includes(key)) {
+    if (typeof value !== "boolean") {
+      throw new TypeError(`feature flag "${key}" must be a boolean`);
+    }
+    return value;
+  }
+  const range = FEATURE_FLAG_INT_RANGES[key];
+  if (range) {
+    const [min, max] = range;
+    if (!Number.isInteger(value) || value < min || value > max) {
+      throw new TypeError(`feature flag "${key}" must be an integer in [${min}, ${max}]`);
+    }
+    return value;
+  }
+  if (FEATURE_FLAG_STRINGS.includes(key)) {
+    if (typeof value !== "string") {
+      throw new TypeError(`feature flag "${key}" must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > FEATURE_FLAG_STRING_MAX) {
+      throw new TypeError(`feature flag "${key}" must be at most ${FEATURE_FLAG_STRING_MAX} characters`);
+    }
+    return trimmed; // 空串合法 = 跟随默认
+  }
+  if (FEATURE_FLAG_URLS.includes(key)) {
+    if (typeof value !== "string") {
+      throw new TypeError(`feature flag "${key}" must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed && !isHttpUrl(trimmed)) {
+      throw new TypeError(`feature flag "${key}" must be empty or a valid http(s) URL`);
+    }
+    return trimmed; // 空串合法 = 跟随默认
+  }
+  const allowed = FEATURE_FLAG_ENUMS[key];
+  if (allowed) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+      throw new TypeError(`feature flag "${key}" must be one of: ${allowed.join(", ")}`);
+    }
+    return value;
+  }
+  throw new TypeError(`unknown feature flag "${key}"`);
+}
+
+/** 清洗已存的 feature_flags 对象：只保留白名单键，类型/范围损坏的键丢弃。 */
+function sanitizeFlags(raw) {
+  const out = {};
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return out;
+  for (const key of FEATURE_FLAG_BOOLEANS) {
+    if (typeof raw[key] === "boolean") out[key] = raw[key];
+  }
+  for (const [key, [min, max]] of Object.entries(FEATURE_FLAG_INT_RANGES)) {
+    if (Number.isInteger(raw[key]) && raw[key] >= min && raw[key] <= max) out[key] = raw[key];
+  }
+  for (const key of FEATURE_FLAG_STRINGS) {
+    if (typeof raw[key] === "string" && raw[key].trim().length <= FEATURE_FLAG_STRING_MAX) {
+      out[key] = raw[key].trim();
+    }
+  }
+  for (const key of FEATURE_FLAG_URLS) {
+    if (typeof raw[key] === "string") {
+      const trimmed = raw[key].trim();
+      if (!trimmed || isHttpUrl(trimmed)) out[key] = trimmed;
+    }
+  }
+  for (const [key, allowed] of Object.entries(FEATURE_FLAG_ENUMS)) {
+    if (allowed.includes(raw[key])) out[key] = raw[key];
+  }
+  return out;
+}
+
 export function createSettings(db) {
   db.exec(SCHEMA);
 
@@ -177,6 +326,31 @@ export function createSettings(db) {
     },
     setPanelMode(mode) {
       setSetting("panel_mode", mode === "light" ? "light" : "standard");
+    },
+
+    /**
+     * Feature flags（kv "feature_flags"）：面板对后端能力的显式覆盖。读取只
+     * 返回白名单内的合法键（默认 {}），写入是逐键校验后的合并持久化。
+     */
+    getFeatureFlags() {
+      const raw = getSetting("feature_flags");
+      if (!raw) return {};
+      try {
+        return sanitizeFlags(JSON.parse(raw));
+      } catch {
+        return {};
+      }
+    },
+    setFeatureFlags(patch) {
+      if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+        throw new TypeError("feature flags patch must be a plain object");
+      }
+      const merged = this.getFeatureFlags();
+      for (const [key, value] of Object.entries(patch)) {
+        merged[key] = validateFlag(key, value);
+      }
+      setSetting("feature_flags", JSON.stringify(merged));
+      return merged;
     }
   };
 }