@modusensus/dsh-mneme 0.14.0-beta.1 → 0.14.0-beta.2

package/lib/settings.js

@@ -1,817 +1,827 @@
-// User-configurable settings: profile (user self-description), rules (behavior
-// rules the agent must follow), and custom slash commands. Stored in the same
-// SQLite database via dedicated tables, isolated from the memories store.
-import { randomUUID } from "node:crypto";
-
-const SCHEMA = `
-CREATE TABLE IF NOT EXISTS user_settings (
-  key   TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-);
-CREATE TABLE IF NOT EXISTS custom_commands (
-  id          TEXT PRIMARY KEY,
-  name        TEXT NOT NULL UNIQUE,
-  description TEXT NOT NULL DEFAULT '',
-  instruction TEXT NOT NULL,
-  created_at  TEXT NOT NULL,
-  updated_at  TEXT NOT NULL
-);
-`;
-
-// DSH command names must match this (lowercase, start with a letter).
-const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/;
-
-/** Parse a JSON array out of a stored string, tolerant of corruption. */
-function parseList(raw) {
-  try {
-    const value = JSON.parse(raw);
-    return Array.isArray(value) ? value : [];
-  } catch {
-    return [];
-  }
-}
-
-// persona 对象的字段白名单：写入时只挑这些键，未知字段丢弃（设计稿①：字段从简，
-// beta 收到真实反馈再加；provenance 是 v1.5 协作式人格的预留位，v1 不写管道）。
-// 读侧损坏即回空对象——同一容错口径照 parseList（坏值不抛错、面板显示为空可重写）。
-// scenario / mesExample（#606）：对标 Character Card V2 的同名字段，是「人格卡能装
-// 下完整角色」所需的最小补充。两者都可选、都不写时渲染零输出（老用户逐字节不变）。
-const PERSONA_FIELDS = ["name", "personality", "replyStyle", "scenario", "mesExample", "enabled", "provenance"];
-
-function parsePersona(raw) {
-  try {
-    const value = JSON.parse(raw);
-    if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
-    const out = {};
-    for (const key of PERSONA_FIELDS) {
-      if (value[key] !== undefined) out[key] = value[key];
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
-
-// 多卡模型（v1.2）：存储形为 { default: <卡>, byAgent: { <agentId>: <卡>, … } }。
-// 兼容层：v1 存的是单对象（有 PERSONA_FIELDS 键、无 default/byAgent 键），读侧
-// 判形状——单对象原样落 default 位，旧数据零迁移。byAgent 的键是 agent 身份
-// id（注入时按会话身份寻址，取不到落 default）。default 卡不可删（兜底位）。
-//
-// 绑会话（v1.3，#606）：加第三维 bySession: { <sessionId>: <卡> }。为什么需要它——
-// byAgent 的键来自 session.header.agentPreset，而 DS Bot 这类宿主把它写成常量
-// （所有 bot 会话都是 "standard"，实测 43/50），按 bot 名字建卡永远不命中。会话 id
-// 才是那个「一个 bot 一张卡」真正能分开的键。bySession 同样是纯加法：没有这个键
-// 的老数据读成 {}，注入文本逐字节不变。
-function parsePersonaStore(raw) {
-  try {
-    const value = JSON.parse(raw);
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-      return { default: {}, byAgent: {}, bySession: {} };
-    }
-    // 新形：含 default / byAgent / bySession 任一键 → 按多卡解析
-    if ("default" in value || "byAgent" in value || "bySession" in value) {
-      const byAgent = {};
-      if (value.byAgent && typeof value.byAgent === "object" && !Array.isArray(value.byAgent)) {
-        for (const [agentId, card] of Object.entries(value.byAgent)) {
-          const parsed = parsePersona(JSON.stringify(card ?? {}));
-          if (Object.keys(parsed).length) byAgent[String(agentId)] = parsed;
-        }
-      }
-      const bySession = {};
-      if (value.bySession && typeof value.bySession === "object" && !Array.isArray(value.bySession)) {
-        for (const [sessionId, card] of Object.entries(value.bySession)) {
-          const parsed = parsePersona(JSON.stringify(card ?? {}));
-          if (Object.keys(parsed).length) bySession[String(sessionId)] = parsed;
-        }
-      }
-      return { default: parsePersona(JSON.stringify(value.default ?? {})), byAgent, bySession };
-    }
-    // 旧形：v1 单对象 → 整体作 default（字段白名单在 parsePersona 内裁）
-    return { default: parsePersona(raw), byAgent: {}, bySession: {} };
-  } catch {
-    return { default: {}, byAgent: {}, bySession: {} };
-  }
-}
-
-function serializePersonaStore(store) {
-  const out = {
-    default: parsePersona(JSON.stringify(store?.default ?? {})),
-    byAgent: {},
-    bySession: {}
-  };
-  if (store?.byAgent && typeof store.byAgent === "object") {
-    for (const [agentId, card] of Object.entries(store.byAgent)) {
-      const parsed = parsePersona(JSON.stringify(card ?? {}));
-      if (Object.keys(parsed).length) out.byAgent[String(agentId)] = parsed;
-    }
-  }
-  if (store?.bySession && typeof store.bySession === "object") {
-    for (const [sessionId, card] of Object.entries(store.bySession)) {
-      const parsed = parsePersona(JSON.stringify(card ?? {}));
-      if (Object.keys(parsed).length) out.bySession[String(sessionId)] = parsed;
-    }
-  }
-  return JSON.stringify(out);
-}
-
-// --- 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",
-  // Issue #34（v0.7.2 引入；v0.7.11 误删后随 #333 恢复）：对话开始注入当前时间。
-  // 顶层扁平键，随白名单回面板（FEATURE_GROUPS 的 group.core）。
-  "injectTimePrefix",
-  // Issue #239 第 5 项：注入条数的查询自适应（确定性强则收缩注入条数，默认关）。
-  "injectUncertaintyAdaptive",
-  // Issue #249：能力说明（工具描述判断指引 + order 150 总则段）。第二批起它是
-  // 注入父开关 autoInject 的子项、默认开（父关时不生效，闸门见 config.js）。
-  "injectGuidanceEnabled",
-  // Issue #249 N3：压缩边缘双落点——上下文即将精简前落一条连续性提案 + 往
-  // 序列末尾追加同一份快照。默认关（新注入表面，见 config.js），父开关 autoInject。
-  "continuityRescueEnabled",
-  "entityExtractionEnabled",
-  // Issue #219：图召回轴——查询命中实体名时把挂联记忆并入检索融合池
-  // （默认关；依赖实体抽取产出，lightMode 强制关闭）。
-  "entityRecallEnabled",
-  // Issue #24 块1：图谱锚定层级联——命中实体作种子、沿关系表向邻居扩散
-  // （默认关；依赖实体抽取产出，lightMode 强制关闭）。
-  "graphAnchoringEnabled",
-  // Issue #24 块2：边权重演化总闸——关着时任何触达都不改边权（默认关；
-  // 依赖实体抽取产出，lightMode 强制关闭）。块4 的被动确认是它底下的一个通道。
-  "graphWeightEnabled",
-  // Issue #24 块3：关联提示防幻觉——图召回线索行以「[检索线索]」标注进注入
-  // （默认关=线索只参与排序不进块；依赖实体抽取产出，lightMode 强制关闭）。
-  "graphInjectHint",
-  // Issue #24 块4：被动确认通道——正常触达即对该记忆挂联的边 bump 一格
-  // （默认关；需总闸 graphWeightEnabled 同开）。
-  "graphPassiveConfirm",
-  // Issue #164：叙述条——dream 期间按 tag 主题簇合成叙述落库（source=
-  // narrative，evidence 回链簇内记忆；按需检索不常驻注入；默认关）。
-  "dreamNarrativeEnabled",
-  // Issue #230：document 型记忆——agent 产长文档的指针行（注册校验/摘要+
-  // doc_path 落库/C2 去重/supersede 记账；全文归 agent；默认关，lightMode 强制关）。
-  "documentMemoryEnabled",
-  // 日记本：跨天惰性判定 + 启动补写，正文落 <memoryDir>/diaries/<项目键>/。
-  // 默认关，进 LIGHT_MODE_OFF（要调模型，与低资源档互斥）。与 documentMemoryEnabled
-  // 成对但不相依：关掉文档记忆只影响检索，正文照样写。
-  "diaryEnabled",
-  "codingRetrospect",
-  "autoDream",
-  // Issue #292：autoDream 连续失败退避（默认关）。基数是 dreamMinIntervalMinutes，
-  // 有效间隔 = 基数 × 2^连续失败数（成功清零），封顶 30 分钟；面板可启停。
-  "autoDreamFailureBackoff",
-  // Issue #557：dream 审计行输入快照瘦身（默认关）。开启后 auto 轮只落骨架
-  // （不含 content），organize 轮的重放载荷不受影响；面板可启停。
-  "dreamInputSummaryEnabled",
-  "sleepModeEnabled",
-  // Issue #529：sleep 连续失败退避（默认关）。基数是 sleepMinIntervalHours，
-  // 有效间隔 = 基数 × 2^连续失败数（成功清零），封顶 max(基数, 24h)；面板可启停。
-  "sleepFailureBackoff",
-  // Issue #619：情感归因相位（默认关）。把「某人某场合的情绪」写成 occasion-bound
-  // 的 affective_context 关系，只有跨够 sleepAffectiveTraitMinSessions 个独立会话
-  // 才允许升成稳定特质。要调模型且依赖实体抽取，所以必须显式打开、可随时关掉；
-  // 它是 sleepModeEnabled 的子相：父开关关着时整个 sleep 不跑。
-  "sleepAffectiveEnabled",
-  "heatEnabled",
-  // issue #218 / E5：注入侧 heat 独立开关（默认关，老用户 injectHeatEnabled=true 回滚）。
-  "injectHeatEnabled",
-  "hybridInject",
-  "selectiveInjectEnabled",
-  "searchSemanticDedup",
-  "rerankEnabled",
-  "resilientModelDownload",
-  "adaptiveThresholdEnabled",
-  "reflectionUpdateEnabled",
-  "reflectionFailureTracking",
-  "bm25SearchEnabled",
-  "conflictFreezeEnabled",
-  // Issue #603 第 4 层：自动裁决档（默认关）。相似度极高的同 scope 重复对直接
-  // 保留新条、归档旧条，不进人工队列；模糊地带照旧留给人。会归档记忆，所以必须
-  // 显式打开，面板可启停。阈值见 FEATURE_FLAG_NUMBER_RANGES 的
-  // conflictAutoResolveMinSimilarity。
-  "conflictAutoResolveEnabled",
-  // Issue #641（beta 第一阶段）：conflictLedgerMode / conflictLedgerDupMinSimilarity
-  // 不在本表——前者是枚举键（FEATURE_FLAG_ENUMS），后者是数值键
-  // （FEATURE_FLAG_NUMBER_RANGES），flagKeysFromSpec 会把三张表合成一份白名单，
-  // 在这里重复登记会让同键被收两次（config-keys 的覆盖完整性锁抓过）。
-  "trustEpistemicWeighting",
-  // Plan #2: attach per-source {keyword, vector, bm25, final} signals to each
-  // search result for transparency/debugging. Default off, purely decorative.
-  "signalTransparency",
-  // Issue #89：宽容校验回归（默认开）+ 跨类型合并显式放宽（默认关）。
-  "dreamSkipInvalid",
-  "allowCrossTypeMerge",
-  // Issue #339 / E8：guarded 类型 merge 护栏（默认开）——合并对象命中
-  // 长保留类型的 merge 决策整条跳过。关掉 = guarded 类型的 merge 不再被跳过，
-  // 「更精炼的摘要」重新成为约束失真的主通道（面板可关，供需要旧行为的库回退）。
-  "dreamMergeGuard",
-  // Issue #17（v0.8.0 A1）：scope 隔离存储层总开关。开启后写入标注
-  // agent_scope/workspace_scope、去重键扩展（含 sensitivity）；检索侧过滤在
-  // A2/A3。默认关=行为与 A1 前逐字节一致。
-  "scopeEnabled",
-  // Issue #17（v0.8.0 A3）：strictScope 硬过滤——他 scope 完全不可见（关闭时
-  // 为 A2 软隔离：降权保留可见）。
-  "strictScope",
-  // Issue #471：政策轴——作用域级可逆闸门（scopeState）。与上面两个键是两条不同的
-  // 轴：那两个管「这条记忆属于谁」（事实轴），这两个管「这个作用域现在通不通」
-  // （政策轴，按作用域整体按下、跨会话存续、松开即恢复）。两级语义同
-  // writeAdmission/preInjectGate——enabled 跑判定（观察档，留审计行但照常注入）、
-  // enforce 真拦（不注入）；都默认关。点号键平铺存、合并时展开回 scopeState 对象。
-  "scopeState.enabled",
-  "scopeState.enforce",
-  // 工具暴露开关（v0.8.5）：记忆已每轮自动注入，memory_search/memory_archive
-  // 在慢/轻量模型上是多余往返，面板可关（默认关=行为不变）。
-  "disableMemorySearch",
-  "disableMemoryArchive",
-  // Issue #231 第二批：agent 主动整理（memory_organize 工具）的暴露闸。与上面两个
-  // 反向——那两个藏默认在场的工具，本键开默认不在场的能力（默认关=工具根本不存在，
-  // 行为逐字节不变）。面板可启停=线上回滚开关。
-  "organizeEnabled",
-  // chorography（仓库地志）的暴露闸：开默认不在场的三个只读工具 + 面板浏览页
-  // （默认关=模型工具列表里根本没有它们，行为逐字节不变）。同 organizeEnabled
-  // 的反向语义——见 config.js 的键注释。
-  "chorographyEnabled",
-  // 嵌套对象开关：config.js 里是 memoryQualityFilter / llmAudit 对象的 enabled
-  // 子字段。kv 按点号键平铺存（"memoryQualityFilter.enabled": false），index.js
-  // 合并时展开回嵌套对象，api.js 的 effective 从对象子字段取值。
-  "memoryQualityFilter.enabled",
-  "llmAudit.enabled",
-  // Issue #254：写入准入（第 1 级确定性拒绝）。两个键分层——enabled 跑判据、
-  // enforce 真拦；都默认关。同上，点号键平铺存、合并时展开回
-  // writeAdmission 对象。
-  "writeAdmission.enabled",
-  "writeAdmission.enforce",
-  // Issue #380：注入前判定（preInjectGate）。两级语义同 writeAdmission——
-  // enabled 跑判定（观察档）、enforce 缓存命中帧真滤除；都默认关。点号键平铺存、
-  // 合并时展开回 preInjectGate 对象。
-  "preInjectGate.enabled",
-  "preInjectGate.enforce",
-  // Issue #164 A2：写入边界的密钥 / PII 判据（src/sensitive-scan.js）。与上面两个
-  // 键分层——本键决定「这类判据参不参与」（默认关），命中之后是仅告警还是真拦仍由
-  // writeAdmission.enforce 决定（#164 口径：默认仅告警、拦截 opt-in）。
-  "sensitiveScanEnabled",
-  // Issue #399：蒸馏原文留存 + 记忆级溯源。enabled 决定蒸馏时是否把公开正文原样
-  // 落盘（distill_records）并给记忆挂窗口链接（memory_provenance）；默认关。
-  // 点号键平铺存、合并时展开回 distillRecords 对象（同 llmAudit.enabled）。
-  // retentionDays 是 int，走下面的 INT_RANGES 表，不进开关白名单。
-  "distillRecords.enabled",
-  // v0.9.0：M.O.（Modus Operandi，beta）客户端视图开关。客户端读 /features
-  // 的 effective
-  // 决定是否注册座位（会话头图标 / 浮层 / 右栏 / 对话行卡片），服务端只负责把
-  // 这个键稳定暴露出来——键若不在 effective 里，客户端静默少键、一个座位都不注册。
-  // 默认关（beta、opt-in）；顶层扁平键，因此不需要 NESTED_FLAG_PATHS 条目。
-  "actionPipelineEnabled",
-  // v0.9.0 第二批：M.O. 执行记账（`/mo-run` 开窗 → 窗口内命令被记成一条 run）。
-  // 与上面那个键分开：那个管「看图的座位」，这个管「往账本里写」。默认关（beta、
-  // opt-in），顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。
-  "actionRunEnabled",
-  // v0.9.0 第三批：M.O. 自动沉淀（会话跑完一轮 → 挖这个项目自己的会话日志 → 落提议）。
-  // 与前两个分开：这个管「从日志里长出候选」，那个管记账、另一个管看图。默认关
-  // （beta、opt-in）；顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。进 LIGHT_MODE_OFF。
-  "actionNudgeEnabled",
-  // 人格定义页（beta）：注入器渲染人格段的顶层总闸（双闸门的 config 半边；对象内
-  // 的 persona.enabled 是 per-agent 半边，存 user_settings 的 "persona" 键，见
-  // getPersona/setPersona）。默认关（beta、opt-in，老用户行为逐字节不变）；不进
-  // LIGHT_MODE_OFF——人格段是用户自写的一小段轻量常驻文本，不引入任何重型后台
-  // 路径，轻量档用户显式勾选仍然赢（同 actionPipelineEnabled 的定性）。顶层扁平
-  // 键，不需要 NESTED_FLAG_PATHS 条目。
-  "personaEnabled",
-  // 人格寻址口径（上一条打开时才有意义）：开 = 身份没建卡/卡被关时不注入人格，
-  // default 只兜解析不到身份的会话。默认关（历史行为，升级零变化）。
-  "personaStrictAddressing",
-  // Issue #497：画像提取草稿（POST /profile/extract）。默认关——每次调用一次 LLM 且
-  // 读上百行记忆；产物只回草稿，绝不写 user_settings。进 LIGHT_MODE_OFF（预设关）。
-  "profileExtractEnabled",
-  // 「Agent 眼中的你」自动事实（2026-11-06）：dream 后逐卡维护 + 手动轮 + 注入段，
-  // 事实住 profile_facts 独立三表，绝不写 user_settings（#497 口径不变）。默认关，
-  // 进 LIGHT_MODE_OFF（自动维护轮与低资源档互斥）。顶层扁平键，与 config.js schema
-  // 成对出现（计数锁 test/api.test.js 钉住）。
-  "profileFactsEnabled",
-  // #539：逐会话无痕默认关闭；子代理开关受总开关约束。手动 session id 名单留在配置，
-  // 不进入只支持标量的 feature_flags 白名单。
-  "sessionGateEnabled",
-  "sessionGateSubagents",
-  // 2026-11-08 kb-qoder parity（契约 §3.1）：chorography 面板闭环的两个授权闸 +
-  // kb 子系统总闸。三条都与 config.js schema 成对出现，计数锁 test/api.test.js 钉住。
-  // 不进 LIGHT_MODE_OFF —— 它们是「谁按下了按钮」而不是「每轮付多少」，理由写在
-  // config.js 那三个键的注释里。kbEnabled 本车道只登记、不接线（B 线做子系统）。
-  "chorographyAutoRefresh",
-  "chorographyT1FromPanel",
-  "kbEnabled"
-];
-// 整数开关的闭区间，与 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],
-  dreamMinIntervalMinutes: [0, 10080],
-  // Issue #637：注入跨轮轮换的窗口（0 = 关，#205 既有语义；config.js 的
-  // z.natural().min(0).max(20) 与此成对）。此前不在白名单——报告者想开只能写
-  // 宿主 patch 文件（cordis.patch.yml），面板上根本看不见这个键的存在。
-  injectRotationTurns: [0, 20],
-  dreamMaxTokens: [256, 131072],
-  // Issue #127：autoSummarize 节流三键（0 = 零行为变化，等同现状）。
-  summarizeMinIntervalMinutes: [0, 10080],
-  summarizeMaxEntriesPerRun: [0, 50],
-  summarizeDedupeWindowHours: [0, 168],
-  // Issue #239：蒸馏零 LLM 预判（窗口最小字符数）与每会话 run 预算（0 = 零行为变化）。
-  summarizeMinWindowChars: [0, 100000],
-  summarizeMaxRunsPerSession: [0, 1000],
-  // Issue #493：连续解析失败几次后放弃当前窗口（0 = 关）。与 config.js 的
-  // z.natural().min(0).max(10) 成对。
-  summarizeParseFailureMaxRetries: [0, 10],
-  // Issue #239 第 4 项：高峰顺延上限（分钟，0 = 不设上限）。
-  summarizePeakMaxDeferMinutes: [0, 1440],
-  // Issue #239 第 4 项镜像到巩固：同一口径（分钟，0 = 不设上限）。
-  dreamPeakMaxDeferMinutes: [0, 1440],
-  // v0.13 日记定时写：每隔 N 分钟唤醒一次跨天判定（0 = 关，只在 turn/end 与
-  // 启动时判）。上限一天——判定单位是天，更长的间隔没有意义。
-  diaryWriteEveryMinutes: [0, 1440],
-  // Issue #125：hybrid 候选量上限（0 = 复用 dreamMaxSnapshotSize）。
-  dreamCandidateMax: [0, 5000],
-  // #135 成本审计派生：单轮 merge 决策上限（merge 是唯一回吐正文的动作，默认 40
-  // = 实测分布上沿；与 config.js 的 z.natural().min(1).max(200) 对齐）。
-  dreamMaxMergePerRun: [1, 200],
-  // Issue #164①：注入单条正文截断上限（默认 300 = 既有行为）。
-  injectContentMaxChars: [60, 4000],
-  // Issue #164：叙述条成簇门槛（共享同一 tag 的记忆数下限）。
-  dreamNarrativeMinCluster: [2, 20],
-  // Issue #230：document 摘要行的注入预算（次优先档内最多几条指针行）。
-  documentInjectBudget: [1, 5],
-  // Issue #249 第一批：B1 pin 池（约束/偏好）的独立条数预算（0 = 关闭/现状）。
-  pinnedInjectBudget: [0, 5],
-  // Issue #257：sleep 冲突/模式阶段的 LLM 输出预算（原硬编码 2048，实测不足）。
-  sleepMaxTokens: [256, 131072],
-  // Issue #619：情感归因的两个闸——升特质所需的最小独立会话数（下界 2：N=1 就是
-  // 单次场合，正是必须禁止升特质的那个情形），以及单轮可写的 affective_context
-  // 关系条数上限（0 = 关闭关系通道）。闭区间与 config.js 的 z.natural() 对齐。
-  sleepAffectiveTraitMinSessions: [2, 10],
-  sleepAffectiveMaxRelationsPerRun: [0, 50],
-  // Issue #529：sleep 冲突阶段的输入侧预算（此前完全没有——全部候选对一次进一个
-  // prompt，实测 163,054 token 撞服务端 163,840 上限）。两个键都是 0 = 不设上限，
-  // 与 config.js 的 z.natural().min(0).max() 成对。
-  sleepConflictMaxPairs: [0, 500],
-  sleepConflictMaxPairsPerRun: [0, 5000],
-  // Issue #258：总览（dream_summarize）输入条数硬上限（0 = 不设上限）。
-  dreamSummaryMaxInputs: [0, 100000],
-  // Issue #24 块1：锚定种子上限与级联深度（闭区间与 config.js 的 z.natural() 对齐）。
-  graphSeedCap: [1, 30],
-  graphCascadeDepth: [1, 3],
-  // Issue #24 块3：图线索行的独立注入预算（0 = 线索不进块）。
-  graphInjectBudget: [0, 5],
-  // Issue #399：蒸馏原文记录的保留天数（与 config.js 的 z.natural().min(1).max(3650)
-  // 对齐；同 llmAudit.retentionDays，是 int 而非开关）。
-  "distillRecords.retentionDays": [1, 3650],
-  // #275 容量预警阈值（嵌套点号键，必须同时进 api.js 的 NESTED_FLAG_PATHS）。
-  // 0 = 显式关掉那一条检查（阈值判级的启用条件写在 service.getCapacityHealth）。
-  // 上限与 config.js 的 z.natural().min(0).max() 成对。
-  "capacityWarning.dbSizeWarnMb": [0, 1048576],
-  "capacityWarning.archivedRowsWarn": [0, 10000000]
-};
-// 浮点开关的闭区间（与 config.js 的 z.number().min().max() 对齐）。与整数开关
-// 分开：面板的整数控件要求 Number.isInteger，而余弦相似度阈值必须允许小数。
-const FEATURE_FLAG_NUMBER_RANGES = {
-  // Issue #127：vector 去重档的并入阈值。
-  summarizeDedupeMinSim: [0.5, 0.99],
-  // Issue #125：hybrid 判"高相似"的阈值。
-  dreamCandidateMinSim: [0.5, 0.99],
-  // Issue #24 块2：单次有效触达的边权抬升幅度（与 config.js 的闭区间对齐）。
-  graphWeightDelta: [0, 1],
-  // Issue #603 第 4 层：自动裁决的相似度门槛。下界 0.85 与冲突检测阈值同源——
-  // 低于它就不是「重复」而是「相似」，不该自动归档任何一条。
-  conflictAutoResolveMinSimilarity: [0.85, 1],
-  // Issue #641：T1（dup）档的相似度下限。检测阈值（normal 0.85）与自动档 autoMin
-  // （0.95，#616 重测在现库覆盖为 0）之间的空带由它接管，下界与检测阈值同源。
-  conflictLedgerDupMinSimilarity: [0.85, 1],
-  // #275 容量预警的归档占比阈值（0 = 关）：健康形态本身就落在 0.8~0.9，默认
-  // 0.95 起才算「归档区吞掉活跃区」——0.9 会对着健康库天天报警（依据见 config.js
-  // capacityWarning 的注释）。浮点键，同 conflictAutoResolveMinSimilarity 的缘由。
-  "capacityWarning.archivedRatioWarn": [0, 1]
-};
-// 自由字符串开关（与 config.js 的 z.string() 同名同型）：trim 后 ≤200 字符，
-// 空串合法（= 跟随主对话模型/默认路径，面板显示 placeholder）。
-const FEATURE_FLAG_STRINGS = [
-  "dreamProvider",
-  "dreamModel",
-  // 睡眠侧专用路由（sleep.js 的 config-first 第三层）：面板下拉随
-  // /llm-providers 端点一起提供，留空 = 用巩固模型或当前模型。
-  "sleepProvider",
-  "sleepModel",
-  // 实体抽取侧专用路由（issue #109）：provider/model 显式指定，
-  // 留空 = 用当前默认模型。
-  "entityExtractionProvider",
-  "entityExtractionModel",
-  // Issue #258：总览（dream_summarize）专用路由，留空 = 用巩固模型。
-  "dreamSummaryProvider",
-  "dreamSummaryModel",
-  "localEmbedModel",
-  "ollamaModel",
-  // Issue #239 第 4 项：高峰时段串（"09:00-18:00"，空串 = 关闭）。
-  "summarizePeakHours",
-  // Issue #239 第 4 项镜像到巩固：同一份时段语法，空串 = 关闭（行为与现状一致）。
-  "dreamPeakHours"
-];
-// 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"],
-  // Plan #1: recall fusion recipe. blend = legacy (default); rrf / minmax are
-  // rank/scale-aware alternatives selected by the panel.
-  recallFusion: ["blend", "rrf", "minmax"],
-  // 实体抽取思考强度（issue #109）：与 dreamReasoningEffort 枚举对齐。
-  entityExtractionReasoning: ["low", "medium", "high", "none"],
-  // 蒸馏思考强度（issue #315）：与 entityExtractionReasoning 枚举对齐，
-  // 多一个 off（显式关思考，思考型模型蒸馏防推理烧预算）。
-  summarizeReasoningEffort: ["off", "low", "medium", "high", "none"],
-  // Issue #127：落库前去重档位（off 默认，等同现状）。
-  summarizeDedupeMode: ["off", "title", "vector"],
-  // Issue #126：sleep 冲突阶段的动作集（conflict 默认 = 现状；full = 六分支）。
-  sleepActionSet: ["conflict", "full"],
-    // Issue #125：dream 候选集构造方式（window 默认 = 现状；hybrid 并入向量组）。
-    dreamCandidateMode: ["window", "hybrid"],
-    // 本地嵌入池化：auto = 按模型族判定（BGE → cls），可显式覆盖为 cls / mean。
-    localEmbedPooling: ["auto", "cls", "mean"],
-  // M3 开局注入档位（spec §7）：轻量档在消费侧压成 off，见 wiki/inject.js 的
-  // resolveInjectTier——LIGHT_MODE_OFF 对平铺键一律赋 false，枚举值进去会静默失效。
-  chorographyInject: ["off", "light", "full"],
-  // Issue #641：冲突分诊账本档位。off（默认，零行为）/ shadow（只记账）/ enforce
-  // （确定性处置：T1 信息量优先 supersede，T2-T4 记账不停车不送 LLM）。三个档位
-  // 都有真实行为——「设了但没行为」的档位不进枚举（#616「假成功」教训）。
-  conflictLedgerMode: ["off", "shadow", "enforce"]
-};
-const FEATURE_FLAG_STRING_MAX = 200;
-
-// 供 api.js 复用同一份白名单（effective 只在白名单键上计算）。
-export const FEATURE_FLAG_SPEC = {
-  booleans: FEATURE_FLAG_BOOLEANS,
-  ints: FEATURE_FLAG_INT_RANGES,
-  numbers: FEATURE_FLAG_NUMBER_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;
-  }
-  const numRange = FEATURE_FLAG_NUMBER_RANGES[key];
-  if (numRange) {
-    const [min, max] = numRange;
-    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
-      throw new TypeError(`feature flag "${key}" must be a number 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, [min, max]] of Object.entries(FEATURE_FLAG_NUMBER_RANGES)) {
-    if (typeof raw[key] === "number" && Number.isFinite(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);
-
-  function getSetting(key) {
-    const row = db.prepare("SELECT value FROM user_settings WHERE key = ?").get(key);
-    return row?.value ?? undefined;
-  }
-
-  function setSetting(key, value) {
-    db.prepare(
-      `INSERT INTO user_settings (key, value) VALUES (?, ?)
-       ON CONFLICT(key) DO UPDATE SET value = excluded.value`
-    ).run(key, value);
-  }
-
-  function toCommand(row) {
-    if (!row) return undefined;
-    return {
-      id: row.id,
-      name: row.name,
-      description: row.description,
-      instruction: row.instruction,
-      created_at: row.created_at,
-      updated_at: row.updated_at
-    };
-  }
-
-  return {
-    /** The user's self-description (free text) or "" when unset. */
-    getProfile() {
-      return getSetting("profile") ?? "";
-    },
-    setProfile(text) {
-      setSetting("profile", String(text ?? ""));
-    },
-
-    /** Behavior rules as an array of strings. */
-    getRules() {
-      return parseList(getSetting("rules") ?? "[]").filter((r) => typeof r === "string");
-    },
-    setRules(rules) {
-      const list = Array.isArray(rules) ? rules.filter((r) => typeof r === "string") : [];
-      setSetting("rules", JSON.stringify(list));
-    },
-
-    /**
-     * Agent persona (name / personality / replyStyle + enabled gate), stored as
-     * one JSON key. v1.2 多卡：存储形 { default, byAgent }，旧 v1 单对象读作
-     * default 兼容。getPersona 返回全量多卡形（面板与注入寻址都用它）。
-     * 寻址与兜底口径不在这里——住 src/user-settings.js 的 resolvePersonaCard，
-     * 注入与面板预览共用那一份；这里若再留一个 getPersonaFor，就是两张皮。
-     */
-    getPersona() {
-      return parsePersonaStore(getSetting("persona") ?? "{}");
-    },
-    setPersona(input) {
-      // 双形兼容：单对象形 = 只更新 default、byAgent/bySession 保留（旧面板/旧调用方
-      // 合并语义）；多卡形 = 全量替换。坏体（非对象）在此不落库不抛错，保值由调用方守卫。
-      if (typeof input !== "object" || input === null || Array.isArray(input)) return;
-      if ("default" in input || "byAgent" in input || "bySession" in input) {
-        setSetting("persona", serializePersonaStore(input));
-        return;
-      }
-      const current = parsePersonaStore(getSetting("persona") ?? "{}");
-      current.default = parsePersona(JSON.stringify(input));
-      setSetting("persona", serializePersonaStore(current));
-    },
-    /** Replace one byAgent card wholesale (panel save); default 不可经此改。 */
-    setPersonaFor(agentId, card) {
-      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
-      if (!id || id === "default") return false;
-      const store = parsePersonaStore(getSetting("persona") ?? "{}");
-      const clean = parsePersona(JSON.stringify(
-        typeof card === "object" && card !== null && !Array.isArray(card) ? card : {}
-      ));
-      if (Object.keys(clean).length) store.byAgent[id] = clean;
-      else delete store.byAgent[id];
-      setSetting("persona", serializePersonaStore(store));
-      return true;
-    },
-    /** byAgent 键列表（面板卡列表用，default 不在其中）。 */
-    listPersonas() {
-      return Object.keys(parsePersonaStore(getSetting("persona") ?? "{}").byAgent);
-    },
-    /** 删一张 byAgent 卡；default 不可删（返回 false）。 */
-    removePersona(agentId) {
-      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
-      if (!id || id === "default") return false;
-      const store = parsePersonaStore(getSetting("persona") ?? "{}");
-      if (!(id in store.byAgent)) return false;
-      delete store.byAgent[id];
-      setSetting("persona", serializePersonaStore(store));
-      return true;
-    },
-
-    /**
-     * 绑会话卡（#606）：按 sessionId 存/删/列。形状与 setPersonaFor 一族逐一对应，
-     * 只是换了一个维度——为什么需要第二维见 parsePersonaStore 的注释。
-     * sessionId 为空或 "default" 拒绝（与 byAgent 同一条纪律：兜底位不可被顶替）。
-     */
-    setPersonaForSession(sessionId, card) {
-      const id = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "";
-      if (!id || id === "default") return false;
-      const store = parsePersonaStore(getSetting("persona") ?? "{}");
-      const clean = parsePersona(JSON.stringify(
-        typeof card === "object" && card !== null && !Array.isArray(card) ? card : {}
-      ));
-      if (Object.keys(clean).length) store.bySession[id] = clean;
-      else delete store.bySession[id];
-      setSetting("persona", serializePersonaStore(store));
-      return true;
-    },
-    /** bySession 键列表（面板「按会话建的卡」用，default 不在其中）。 */
-    listPersonaSessions() {
-      return Object.keys(parsePersonaStore(getSetting("persona") ?? "{}").bySession);
-    },
-    /** 删一张 bySession 卡；不存在返回 false。 */
-    removePersonaForSession(sessionId) {
-      const id = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "";
-      if (!id || id === "default") return false;
-      const store = parsePersonaStore(getSetting("persona") ?? "{}");
-      if (!(id in store.bySession)) return false;
-      delete store.bySession[id];
-      setSetting("persona", serializePersonaStore(store));
-      return true;
-    },
-
-    /** All custom commands, sorted by name. */
-    listCommands() {
-      const rows = db.prepare("SELECT * FROM custom_commands ORDER BY name ASC").all();
-      return rows.map(toCommand);
-    },
-
-    /**
-     * Add or replace a custom command by name.
-     * @returns the stored command.
-     * @throws when name is invalid or does not match DSH's command-name grammar.
-     */
-    addCommand({ name, description = "", instruction }) {
-      const cmdName = String(name ?? "").trim();
-      if (!COMMAND_NAME.test(cmdName)) {
-        throw new Error(`invalid command name "${cmdName}": must match /^[a-z][a-z0-9_-]*$/`);
-      }
-      if (typeof instruction !== "string" || !instruction.trim()) {
-        throw new Error("command instruction must be a non-empty string");
-      }
-      const now = new Date().toISOString();
-      const existing = db.prepare("SELECT id FROM custom_commands WHERE name = ?").get(cmdName);
-      if (existing) {
-        db.prepare(
-          "UPDATE custom_commands SET description = ?, instruction = ?, updated_at = ? WHERE id = ?"
-        ).run(String(description ?? ""), instruction, now, existing.id);
-        return toCommand(db.prepare("SELECT * FROM custom_commands WHERE id = ?").get(existing.id));
-      }
-      const id = randomUUID();
-      db.prepare(
-        `INSERT INTO custom_commands (id, name, description, instruction, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?)`
-      ).run(id, cmdName, String(description ?? ""), instruction, now, now);
-      return toCommand(db.prepare("SELECT * FROM custom_commands WHERE id = ?").get(id));
-    },
-
-    /** Remove a custom command by id; returns true when removed. */
-    removeCommand(id) {
-      const result = db.prepare("DELETE FROM custom_commands WHERE id = ?").run(id);
-      return result.changes > 0;
-    },
-
-    /** Vector-search provider config (OpenAI-compatible embeddings endpoint). */
-    getVectorConfig() {
-      const raw = getSetting("vector");
-      if (!raw) return undefined;
-      try {
-        const cfg = JSON.parse(raw);
-        return typeof cfg === "object" && cfg !== null ? cfg : undefined;
-      } catch {
-        return undefined;
-      }
-    },
-    setVectorConfig({ enabled, baseUrl, apiKey, model }) {
-      const cfg = {
-        enabled: enabled === true || enabled === 1,
-        baseUrl: String(baseUrl ?? "").trim().replace(/\/+$/, ""),
-        apiKey: String(apiKey ?? "").trim(),
-        model: String(model ?? "").trim()
-      };
-      setSetting("vector", JSON.stringify(cfg));
-      return cfg;
-    },
-
-    /**
-     * Standalone external API settings (kv "external_api"): {enabled, port,
-     * token}. The Bearer token is auto-generated on first boot and persisted
-     * here. Partial writes preserve the keys they don't mention.
-     */
-    getExternalApi() {
-      const raw = getSetting("external_api");
-      if (!raw) return undefined;
-      try {
-        const cfg = JSON.parse(raw);
-        return typeof cfg === "object" && cfg !== null ? cfg : undefined;
-      } catch {
-        return undefined;
-      }
-    },
-    setExternalApi(patch = {}) {
-      const prev = this.getExternalApi() ?? {};
-      const port = Number(patch.port ?? prev.port);
-      const host = typeof patch.host === "string" && patch.host.trim() ? patch.host.trim() : (prev.host ?? "127.0.0.1");
-      const cfg = {
-        enabled: patch.enabled !== undefined ? patch.enabled === true : prev.enabled === true,
-        port: Number.isInteger(port) && port > 0 ? port : 8790,
-        host,
-        token: String(patch.token ?? prev.token ?? "")
-      };
-      setSetting("external_api", JSON.stringify(cfg));
-      return cfg;
-    },
-
-    /**
-     * Web panel mode (kv "panel_mode"): "light" (low-resource preset) or
-     * "standard" (full feature set). Unset reads as "standard".
-     */
-    getPanelMode() {
-      return getSetting("panel_mode") === "light" ? "light" : "standard";
-    },
-    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;
-    }
-  };
-}
+// User-configurable settings: profile (user self-description), rules (behavior
+// rules the agent must follow), and custom slash commands. Stored in the same
+// SQLite database via dedicated tables, isolated from the memories store.
+import { randomUUID } from "node:crypto";
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS user_settings (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS custom_commands (
+  id          TEXT PRIMARY KEY,
+  name        TEXT NOT NULL UNIQUE,
+  description TEXT NOT NULL DEFAULT '',
+  instruction TEXT NOT NULL,
+  created_at  TEXT NOT NULL,
+  updated_at  TEXT NOT NULL
+);
+`;
+
+// DSH command names must match this (lowercase, start with a letter).
+const COMMAND_NAME = /^[a-z][a-z0-9_-]*$/;
+
+/** Parse a JSON array out of a stored string, tolerant of corruption. */
+function parseList(raw) {
+  try {
+    const value = JSON.parse(raw);
+    return Array.isArray(value) ? value : [];
+  } catch {
+    return [];
+  }
+}
+
+// persona 对象的字段白名单：写入时只挑这些键，未知字段丢弃（设计稿①：字段从简，
+// beta 收到真实反馈再加；provenance 是 v1.5 协作式人格的预留位，v1 不写管道）。
+// 读侧损坏即回空对象——同一容错口径照 parseList（坏值不抛错、面板显示为空可重写）。
+// scenario / mesExample（#606）：对标 Character Card V2 的同名字段，是「人格卡能装
+// 下完整角色」所需的最小补充。两者都可选、都不写时渲染零输出（老用户逐字节不变）。
+const PERSONA_FIELDS = ["name", "personality", "replyStyle", "scenario", "mesExample", "enabled", "provenance"];
+
+function parsePersona(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+    const out = {};
+    for (const key of PERSONA_FIELDS) {
+      if (value[key] !== undefined) out[key] = value[key];
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// 多卡模型（v1.2）：存储形为 { default: <卡>, byAgent: { <agentId>: <卡>, … } }。
+// 兼容层：v1 存的是单对象（有 PERSONA_FIELDS 键、无 default/byAgent 键），读侧
+// 判形状——单对象原样落 default 位，旧数据零迁移。byAgent 的键是 agent 身份
+// id（注入时按会话身份寻址，取不到落 default）。default 卡不可删（兜底位）。
+//
+// 绑会话（v1.3，#606）：加第三维 bySession: { <sessionId>: <卡> }。为什么需要它——
+// byAgent 的键来自 session.header.agentPreset，而 DS Bot 这类宿主把它写成常量
+// （所有 bot 会话都是 "standard"，实测 43/50），按 bot 名字建卡永远不命中。会话 id
+// 才是那个「一个 bot 一张卡」真正能分开的键。bySession 同样是纯加法：没有这个键
+// 的老数据读成 {}，注入文本逐字节不变。
+function parsePersonaStore(raw) {
+  try {
+    const value = JSON.parse(raw);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return { default: {}, byAgent: {}, bySession: {} };
+    }
+    // 新形：含 default / byAgent / bySession 任一键 → 按多卡解析
+    if ("default" in value || "byAgent" in value || "bySession" in value) {
+      const byAgent = {};
+      if (value.byAgent && typeof value.byAgent === "object" && !Array.isArray(value.byAgent)) {
+        for (const [agentId, card] of Object.entries(value.byAgent)) {
+          const parsed = parsePersona(JSON.stringify(card ?? {}));
+          if (Object.keys(parsed).length) byAgent[String(agentId)] = parsed;
+        }
+      }
+      const bySession = {};
+      if (value.bySession && typeof value.bySession === "object" && !Array.isArray(value.bySession)) {
+        for (const [sessionId, card] of Object.entries(value.bySession)) {
+          const parsed = parsePersona(JSON.stringify(card ?? {}));
+          if (Object.keys(parsed).length) bySession[String(sessionId)] = parsed;
+        }
+      }
+      return { default: parsePersona(JSON.stringify(value.default ?? {})), byAgent, bySession };
+    }
+    // 旧形：v1 单对象 → 整体作 default（字段白名单在 parsePersona 内裁）
+    return { default: parsePersona(raw), byAgent: {}, bySession: {} };
+  } catch {
+    return { default: {}, byAgent: {}, bySession: {} };
+  }
+}
+
+function serializePersonaStore(store) {
+  const out = {
+    default: parsePersona(JSON.stringify(store?.default ?? {})),
+    byAgent: {},
+    bySession: {}
+  };
+  if (store?.byAgent && typeof store.byAgent === "object") {
+    for (const [agentId, card] of Object.entries(store.byAgent)) {
+      const parsed = parsePersona(JSON.stringify(card ?? {}));
+      if (Object.keys(parsed).length) out.byAgent[String(agentId)] = parsed;
+    }
+  }
+  if (store?.bySession && typeof store.bySession === "object") {
+    for (const [sessionId, card] of Object.entries(store.bySession)) {
+      const parsed = parsePersona(JSON.stringify(card ?? {}));
+      if (Object.keys(parsed).length) out.bySession[String(sessionId)] = parsed;
+    }
+  }
+  return JSON.stringify(out);
+}
+
+// --- 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",
+  // Issue #34（v0.7.2 引入；v0.7.11 误删后随 #333 恢复）：对话开始注入当前时间。
+  // 顶层扁平键，随白名单回面板（FEATURE_GROUPS 的 group.core）。
+  "injectTimePrefix",
+  // Issue #239 第 5 项：注入条数的查询自适应（确定性强则收缩注入条数，默认关）。
+  "injectUncertaintyAdaptive",
+  // Issue #249：能力说明（工具描述判断指引 + order 150 总则段）。第二批起它是
+  // 注入父开关 autoInject 的子项、默认开（父关时不生效，闸门见 config.js）。
+  "injectGuidanceEnabled",
+  // Issue #249 N3：压缩边缘双落点——上下文即将精简前落一条连续性提案 + 往
+  // 序列末尾追加同一份快照。默认关（新注入表面，见 config.js），父开关 autoInject。
+  "continuityRescueEnabled",
+  "entityExtractionEnabled",
+  // Issue #219：图召回轴——查询命中实体名时把挂联记忆并入检索融合池
+  // （默认关；依赖实体抽取产出，lightMode 强制关闭）。
+  "entityRecallEnabled",
+  // Issue #24 块1：图谱锚定层级联——命中实体作种子、沿关系表向邻居扩散
+  // （默认关；依赖实体抽取产出，lightMode 强制关闭）。
+  "graphAnchoringEnabled",
+  // Issue #24 块2：边权重演化总闸——关着时任何触达都不改边权（默认关；
+  // 依赖实体抽取产出，lightMode 强制关闭）。块4 的被动确认是它底下的一个通道。
+  "graphWeightEnabled",
+  // Issue #24 块3：关联提示防幻觉——图召回线索行以「[检索线索]」标注进注入
+  // （默认关=线索只参与排序不进块；依赖实体抽取产出，lightMode 强制关闭）。
+  "graphInjectHint",
+  // Issue #24 块4：被动确认通道——正常触达即对该记忆挂联的边 bump 一格
+  // （默认关；需总闸 graphWeightEnabled 同开）。
+  "graphPassiveConfirm",
+  // Issue #164：叙述条——dream 期间按 tag 主题簇合成叙述落库（source=
+  // narrative，evidence 回链簇内记忆；按需检索不常驻注入；默认关）。
+  "dreamNarrativeEnabled",
+  // Issue #230：document 型记忆——agent 产长文档的指针行（注册校验/摘要+
+  // doc_path 落库/C2 去重/supersede 记账；全文归 agent；默认关，lightMode 强制关）。
+  "documentMemoryEnabled",
+  // 日记本：跨天惰性判定 + 启动补写，正文落 <memoryDir>/diaries/<项目键>/。
+  // 默认关，进 LIGHT_MODE_OFF（要调模型，与低资源档互斥）。与 documentMemoryEnabled
+  // 成对但不相依：关掉文档记忆只影响检索，正文照样写。
+  "diaryEnabled",
+  "codingRetrospect",
+  "autoDream",
+  // Issue #292：autoDream 连续失败退避（默认关）。基数是 dreamMinIntervalMinutes，
+  // 有效间隔 = 基数 × 2^连续失败数（成功清零），封顶 30 分钟；面板可启停。
+  "autoDreamFailureBackoff",
+  // Issue #557：dream 审计行输入快照瘦身（默认关）。开启后 auto 轮只落骨架
+  // （不含 content），organize 轮的重放载荷不受影响；面板可启停。
+  "dreamInputSummaryEnabled",
+  "sleepModeEnabled",
+  // Issue #529：sleep 连续失败退避（默认关）。基数是 sleepMinIntervalHours，
+  // 有效间隔 = 基数 × 2^连续失败数（成功清零），封顶 max(基数, 24h)；面板可启停。
+  "sleepFailureBackoff",
+  // Issue #619：情感归因相位（默认关）。把「某人某场合的情绪」写成 occasion-bound
+  // 的 affective_context 关系，只有跨够 sleepAffectiveTraitMinSessions 个独立会话
+  // 才允许升成稳定特质。要调模型且依赖实体抽取，所以必须显式打开、可随时关掉；
+  // 它是 sleepModeEnabled 的子相：父开关关着时整个 sleep 不跑。
+  "sleepAffectiveEnabled",
+  "heatEnabled",
+  // issue #218 / E5：注入侧 heat 独立开关（默认关，老用户 injectHeatEnabled=true 回滚）。
+  "injectHeatEnabled",
+  "hybridInject",
+  "selectiveInjectEnabled",
+  "searchSemanticDedup",
+  "rerankEnabled",
+  "resilientModelDownload",
+  "adaptiveThresholdEnabled",
+  "reflectionUpdateEnabled",
+  "reflectionFailureTracking",
+  "bm25SearchEnabled",
+  "conflictFreezeEnabled",
+  // Issue #603 第 4 层：自动裁决档（默认关）。相似度极高的同 scope 重复对直接
+  // 保留新条、归档旧条，不进人工队列；模糊地带照旧留给人。会归档记忆，所以必须
+  // 显式打开，面板可启停。阈值见 FEATURE_FLAG_NUMBER_RANGES 的
+  // conflictAutoResolveMinSimilarity。
+  "conflictAutoResolveEnabled",
+  // Issue #641（beta 第一阶段）：conflictLedgerMode / conflictLedgerDupMinSimilarity
+  // 不在本表——前者是枚举键（FEATURE_FLAG_ENUMS），后者是数值键
+  // （FEATURE_FLAG_NUMBER_RANGES），flagKeysFromSpec 会把三张表合成一份白名单，
+  // 在这里重复登记会让同键被收两次（config-keys 的覆盖完整性锁抓过）。
+  "trustEpistemicWeighting",
+  // Plan #2: attach per-source {keyword, vector, bm25, final} signals to each
+  // search result for transparency/debugging. Default off, purely decorative.
+  "signalTransparency",
+  // Issue #89：宽容校验回归（默认开）+ 跨类型合并显式放宽（默认关）。
+  "dreamSkipInvalid",
+  "allowCrossTypeMerge",
+  // Issue #339 / E8：guarded 类型 merge 护栏（默认开）——合并对象命中
+  // 长保留类型的 merge 决策整条跳过。关掉 = guarded 类型的 merge 不再被跳过，
+  // 「更精炼的摘要」重新成为约束失真的主通道（面板可关，供需要旧行为的库回退）。
+  "dreamMergeGuard",
+  // Issue #17（v0.8.0 A1）：scope 隔离存储层总开关。开启后写入标注
+  // agent_scope/workspace_scope、去重键扩展（含 sensitivity）；检索侧过滤在
+  // A2/A3。默认关=行为与 A1 前逐字节一致。
+  "scopeEnabled",
+  // Issue #17（v0.8.0 A3）：strictScope 硬过滤——他 scope 完全不可见（关闭时
+  // 为 A2 软隔离：降权保留可见）。
+  "strictScope",
+  // Issue #471：政策轴——作用域级可逆闸门（scopeState）。与上面两个键是两条不同的
+  // 轴：那两个管「这条记忆属于谁」（事实轴），这两个管「这个作用域现在通不通」
+  // （政策轴，按作用域整体按下、跨会话存续、松开即恢复）。两级语义同
+  // writeAdmission/preInjectGate——enabled 跑判定（观察档，留审计行但照常注入）、
+  // enforce 真拦（不注入）；都默认关。点号键平铺存、合并时展开回 scopeState 对象。
+  "scopeState.enabled",
+  "scopeState.enforce",
+  // 工具暴露开关（v0.8.5）：记忆已每轮自动注入，memory_search/memory_archive
+  // 在慢/轻量模型上是多余往返，面板可关（默认关=行为不变）。
+  "disableMemorySearch",
+  "disableMemoryArchive",
+  // Issue #231 第二批：agent 主动整理（memory_organize 工具）的暴露闸。与上面两个
+  // 反向——那两个藏默认在场的工具，本键开默认不在场的能力（默认关=工具根本不存在，
+  // 行为逐字节不变）。面板可启停=线上回滚开关。
+  "organizeEnabled",
+  // chorography（仓库地志）的暴露闸：开默认不在场的三个只读工具 + 面板浏览页
+  // （默认关=模型工具列表里根本没有它们，行为逐字节不变）。同 organizeEnabled
+  // 的反向语义——见 config.js 的键注释。
+  "chorographyEnabled",
+  // 嵌套对象开关：config.js 里是 memoryQualityFilter / llmAudit 对象的 enabled
+  // 子字段。kv 按点号键平铺存（"memoryQualityFilter.enabled": false），index.js
+  // 合并时展开回嵌套对象，api.js 的 effective 从对象子字段取值。
+  "memoryQualityFilter.enabled",
+  "llmAudit.enabled",
+  // Issue #254：写入准入（第 1 级确定性拒绝）。两个键分层——enabled 跑判据、
+  // enforce 真拦；都默认关。同上，点号键平铺存、合并时展开回
+  // writeAdmission 对象。
+  "writeAdmission.enabled",
+  "writeAdmission.enforce",
+  // Issue #380：注入前判定（preInjectGate）。两级语义同 writeAdmission——
+  // enabled 跑判定（观察档）、enforce 缓存命中帧真滤除；都默认关。点号键平铺存、
+  // 合并时展开回 preInjectGate 对象。
+  "preInjectGate.enabled",
+  "preInjectGate.enforce",
+  // Issue #164 A2：写入边界的密钥 / PII 判据（src/sensitive-scan.js）。与上面两个
+  // 键分层——本键决定「这类判据参不参与」（默认关），命中之后是仅告警还是真拦仍由
+  // writeAdmission.enforce 决定（#164 口径：默认仅告警、拦截 opt-in）。
+  "sensitiveScanEnabled",
+  // Issue #399：蒸馏原文留存 + 记忆级溯源。enabled 决定蒸馏时是否把公开正文原样
+  // 落盘（distill_records）并给记忆挂窗口链接（memory_provenance）；默认关。
+  // 点号键平铺存、合并时展开回 distillRecords 对象（同 llmAudit.enabled）。
+  // retentionDays 是 int，走下面的 INT_RANGES 表，不进开关白名单。
+  "distillRecords.enabled",
+  // v0.9.0：M.O.（Modus Operandi，beta）客户端视图开关。客户端读 /features
+  // 的 effective
+  // 决定是否注册座位（会话头图标 / 浮层 / 右栏 / 对话行卡片），服务端只负责把
+  // 这个键稳定暴露出来——键若不在 effective 里，客户端静默少键、一个座位都不注册。
+  // 默认关（beta、opt-in）；顶层扁平键，因此不需要 NESTED_FLAG_PATHS 条目。
+  "actionPipelineEnabled",
+  // v0.9.0 第二批：M.O. 执行记账（`/mo-run` 开窗 → 窗口内命令被记成一条 run）。
+  // 与上面那个键分开：那个管「看图的座位」，这个管「往账本里写」。默认关（beta、
+  // opt-in），顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。
+  "actionRunEnabled",
+  // v0.9.0 第三批：M.O. 自动沉淀（会话跑完一轮 → 挖这个项目自己的会话日志 → 落提议）。
+  // 与前两个分开：这个管「从日志里长出候选」，那个管记账、另一个管看图。默认关
+  // （beta、opt-in）；顶层扁平键，不需要 NESTED_FLAG_PATHS 条目。进 LIGHT_MODE_OFF。
+  "actionNudgeEnabled",
+  // 人格定义页（beta）：注入器渲染人格段的顶层总闸（双闸门的 config 半边；对象内
+  // 的 persona.enabled 是 per-agent 半边，存 user_settings 的 "persona" 键，见
+  // getPersona/setPersona）。默认关（beta、opt-in，老用户行为逐字节不变）；不进
+  // LIGHT_MODE_OFF——人格段是用户自写的一小段轻量常驻文本，不引入任何重型后台
+  // 路径，轻量档用户显式勾选仍然赢（同 actionPipelineEnabled 的定性）。顶层扁平
+  // 键，不需要 NESTED_FLAG_PATHS 条目。
+  "personaEnabled",
+  // 人格寻址口径（上一条打开时才有意义）：开 = 身份没建卡/卡被关时不注入人格，
+  // default 只兜解析不到身份的会话。默认关（历史行为，升级零变化）。
+  "personaStrictAddressing",
+  // Issue #497：画像提取草稿（POST /profile/extract）。默认关——每次调用一次 LLM 且
+  // 读上百行记忆；产物只回草稿，绝不写 user_settings。进 LIGHT_MODE_OFF（预设关）。
+  "profileExtractEnabled",
+  // 「Agent 眼中的你」自动事实（2026-11-06）：dream 后逐卡维护 + 手动轮 + 注入段，
+  // 事实住 profile_facts 独立三表，绝不写 user_settings（#497 口径不变）。默认关，
+  // 进 LIGHT_MODE_OFF（自动维护轮与低资源档互斥）。顶层扁平键，与 config.js schema
+  // 成对出现（计数锁 test/api.test.js 钉住）。
+  "profileFactsEnabled",
+  // 图像描述档（docs/DISTILL.md:346）：蒸馏前给窗口里的图出描述。默认关，进
+  // LIGHT_MODE_OFF —— 它是一次额外的视觉调用，与低资源档互斥。路由两个键走
+  // FEATURE_FLAG_STRINGS（留空 = 不描述，理由写在 config.js 那三个键的注释里）。
+  "imageDescribeEnabled",
+  // #539：逐会话无痕默认关闭；子代理开关受总开关约束。手动 session id 名单留在配置，
+  // 不进入只支持标量的 feature_flags 白名单。
+  "sessionGateEnabled",
+  "sessionGateSubagents",
+  // 2026-11-08 kb-qoder parity（契约 §3.1）：chorography 面板闭环的两个授权闸 +
+  // kb 子系统总闸。三条都与 config.js schema 成对出现，计数锁 test/api.test.js 钉住。
+  // 不进 LIGHT_MODE_OFF —— 它们是「谁按下了按钮」而不是「每轮付多少」，理由写在
+  // config.js 那三个键的注释里。kbEnabled 本车道只登记、不接线（B 线做子系统）。
+  "chorographyAutoRefresh",
+  "chorographyT1FromPanel",
+  "kbEnabled"
+];
+// 整数开关的闭区间，与 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],
+  dreamMinIntervalMinutes: [0, 10080],
+  // Issue #637：注入跨轮轮换的窗口（0 = 关，#205 既有语义；config.js 的
+  // z.natural().min(0).max(20) 与此成对）。此前不在白名单——报告者想开只能写
+  // 宿主 patch 文件（cordis.patch.yml），面板上根本看不见这个键的存在。
+  injectRotationTurns: [0, 20],
+  dreamMaxTokens: [256, 131072],
+  // Issue #127：autoSummarize 节流三键（0 = 零行为变化，等同现状）。
+  summarizeMinIntervalMinutes: [0, 10080],
+  summarizeMaxEntriesPerRun: [0, 50],
+  summarizeDedupeWindowHours: [0, 168],
+  // Issue #239：蒸馏零 LLM 预判（窗口最小字符数）与每会话 run 预算（0 = 零行为变化）。
+  summarizeMinWindowChars: [0, 100000],
+  summarizeMaxRunsPerSession: [0, 1000],
+  // Issue #493：连续解析失败几次后放弃当前窗口（0 = 关）。与 config.js 的
+  // z.natural().min(0).max(10) 成对。
+  summarizeParseFailureMaxRetries: [0, 10],
+  // Issue #239 第 4 项：高峰顺延上限（分钟，0 = 不设上限）。
+  summarizePeakMaxDeferMinutes: [0, 1440],
+  // Issue #239 第 4 项镜像到巩固：同一口径（分钟，0 = 不设上限）。
+  dreamPeakMaxDeferMinutes: [0, 1440],
+  // v0.13 日记定时写：每隔 N 分钟唤醒一次跨天判定（0 = 关，只在 turn/end 与
+  // 启动时判）。上限一天——判定单位是天，更长的间隔没有意义。
+  diaryWriteEveryMinutes: [0, 1440],
+  // Issue #125：hybrid 候选量上限（0 = 复用 dreamMaxSnapshotSize）。
+  dreamCandidateMax: [0, 5000],
+  // #135 成本审计派生：单轮 merge 决策上限（merge 是唯一回吐正文的动作，默认 40
+  // = 实测分布上沿；与 config.js 的 z.natural().min(1).max(200) 对齐）。
+  dreamMaxMergePerRun: [1, 200],
+  // Issue #164①：注入单条正文截断上限（默认 300 = 既有行为）。
+  injectContentMaxChars: [60, 4000],
+  // Issue #164：叙述条成簇门槛（共享同一 tag 的记忆数下限）。
+  dreamNarrativeMinCluster: [2, 20],
+  // Issue #230：document 摘要行的注入预算（次优先档内最多几条指针行）。
+  documentInjectBudget: [1, 5],
+  // Issue #249 第一批：B1 pin 池（约束/偏好）的独立条数预算（0 = 关闭/现状）。
+  pinnedInjectBudget: [0, 5],
+  // Issue #257：sleep 冲突/模式阶段的 LLM 输出预算（原硬编码 2048，实测不足）。
+  sleepMaxTokens: [256, 131072],
+  // Issue #619：情感归因的两个闸——升特质所需的最小独立会话数（下界 2：N=1 就是
+  // 单次场合，正是必须禁止升特质的那个情形），以及单轮可写的 affective_context
+  // 关系条数上限（0 = 关闭关系通道）。闭区间与 config.js 的 z.natural() 对齐。
+  sleepAffectiveTraitMinSessions: [2, 10],
+  sleepAffectiveMaxRelationsPerRun: [0, 50],
+  // Issue #529：sleep 冲突阶段的输入侧预算（此前完全没有——全部候选对一次进一个
+  // prompt，实测 163,054 token 撞服务端 163,840 上限）。两个键都是 0 = 不设上限，
+  // 与 config.js 的 z.natural().min(0).max() 成对。
+  sleepConflictMaxPairs: [0, 500],
+  sleepConflictMaxPairsPerRun: [0, 5000],
+  // Issue #258：总览（dream_summarize）输入条数硬上限（0 = 不设上限）。
+  dreamSummaryMaxInputs: [0, 100000],
+  // Issue #24 块1：锚定种子上限与级联深度（闭区间与 config.js 的 z.natural() 对齐）。
+  graphSeedCap: [1, 30],
+  graphCascadeDepth: [1, 3],
+  // Issue #24 块3：图线索行的独立注入预算（0 = 线索不进块）。
+  graphInjectBudget: [0, 5],
+  // Issue #399：蒸馏原文记录的保留天数（与 config.js 的 z.natural().min(1).max(3650)
+  // 对齐；同 llmAudit.retentionDays，是 int 而非开关）。
+  "distillRecords.retentionDays": [1, 3650],
+  // #275 容量预警阈值（嵌套点号键，必须同时进 api.js 的 NESTED_FLAG_PATHS）。
+  // 0 = 显式关掉那一条检查（阈值判级的启用条件写在 service.getCapacityHealth）。
+  // 上限与 config.js 的 z.natural().min(0).max() 成对。
+  "capacityWarning.dbSizeWarnMb": [0, 1048576],
+  "capacityWarning.archivedRowsWarn": [0, 10000000]
+};
+// 浮点开关的闭区间（与 config.js 的 z.number().min().max() 对齐）。与整数开关
+// 分开：面板的整数控件要求 Number.isInteger，而余弦相似度阈值必须允许小数。
+const FEATURE_FLAG_NUMBER_RANGES = {
+  // Issue #127：vector 去重档的并入阈值。
+  summarizeDedupeMinSim: [0.5, 0.99],
+  // Issue #125：hybrid 判"高相似"的阈值。
+  dreamCandidateMinSim: [0.5, 0.99],
+  // Issue #24 块2：单次有效触达的边权抬升幅度（与 config.js 的闭区间对齐）。
+  graphWeightDelta: [0, 1],
+  // Issue #603 第 4 层：自动裁决的相似度门槛。下界 0.85 与冲突检测阈值同源——
+  // 低于它就不是「重复」而是「相似」，不该自动归档任何一条。
+  conflictAutoResolveMinSimilarity: [0.85, 1],
+  // Issue #641：T1（dup）档的相似度下限。检测阈值（normal 0.85）与自动档 autoMin
+  // （0.95，#616 重测在现库覆盖为 0）之间的空带由它接管，下界与检测阈值同源。
+  conflictLedgerDupMinSimilarity: [0.85, 1],
+  // #275 容量预警的归档占比阈值（0 = 关）：健康形态本身就落在 0.8~0.9，默认
+  // 0.95 起才算「归档区吞掉活跃区」——0.9 会对着健康库天天报警（依据见 config.js
+  // capacityWarning 的注释）。浮点键，同 conflictAutoResolveMinSimilarity 的缘由。
+  "capacityWarning.archivedRatioWarn": [0, 1]
+};
+// 自由字符串开关（与 config.js 的 z.string() 同名同型）：trim 后 ≤200 字符，
+// 空串合法（= 跟随主对话模型/默认路径，面板显示 placeholder）。
+const FEATURE_FLAG_STRINGS = [
+  "dreamProvider",
+  "dreamModel",
+  // 睡眠侧专用路由（sleep.js 的 config-first 第三层）：面板下拉随
+  // /llm-providers 端点一起提供，留空 = 用巩固模型或当前模型。
+  "sleepProvider",
+  "sleepModel",
+  // 实体抽取侧专用路由（issue #109）：provider/model 显式指定，
+  // 留空 = 用当前默认模型。
+  "entityExtractionProvider",
+  "entityExtractionModel",
+  // Issue #258：总览（dream_summarize）专用路由，留空 = 用巩固模型。
+  "dreamSummaryProvider",
+  "dreamSummaryModel",
+  "localEmbedModel",
+  "ollamaModel",
+  // Issue #239 第 4 项：高峰时段串（"09:00-18:00"，空串 = 关闭）。
+  "summarizePeakHours",
+  // Issue #239 第 4 项镜像到巩固：同一份时段语法，空串 = 关闭（行为与现状一致）。
+  "dreamPeakHours",
+  // 图像描述档专用路由（docs/DISTILL.md:346）：与上面几条不同，这两条留空不是
+  // 「跟随当前模型」而是「整档不描述」——蒸馏路由与会话主模型都可能是纯文本
+  // 模型，跟着它们跑只会拿回一行 textOnly 占位。所以面板上它们是空串 + 说明，
+  // 不是下拉默认值。
+  "imageDescribeProvider",
+  "imageDescribeModel"
+];
+// 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"],
+  // Plan #1: recall fusion recipe. blend = legacy (default); rrf / minmax are
+  // rank/scale-aware alternatives selected by the panel.
+  recallFusion: ["blend", "rrf", "minmax"],
+  // 实体抽取思考强度（issue #109）：与 dreamReasoningEffort 枚举对齐。
+  entityExtractionReasoning: ["low", "medium", "high", "none"],
+  // 蒸馏思考强度（issue #315）：与 entityExtractionReasoning 枚举对齐，
+  // 多一个 off（显式关思考，思考型模型蒸馏防推理烧预算）。
+  summarizeReasoningEffort: ["off", "low", "medium", "high", "none"],
+  // Issue #127：落库前去重档位（off 默认，等同现状）。
+  summarizeDedupeMode: ["off", "title", "vector"],
+  // Issue #126：sleep 冲突阶段的动作集（conflict 默认 = 现状；full = 六分支）。
+  sleepActionSet: ["conflict", "full"],
+    // Issue #125：dream 候选集构造方式（window 默认 = 现状；hybrid 并入向量组）。
+    dreamCandidateMode: ["window", "hybrid"],
+    // 本地嵌入池化：auto = 按模型族判定（BGE → cls），可显式覆盖为 cls / mean。
+    localEmbedPooling: ["auto", "cls", "mean"],
+  // M3 开局注入档位（spec §7）：轻量档在消费侧压成 off，见 wiki/inject.js 的
+  // resolveInjectTier——LIGHT_MODE_OFF 对平铺键一律赋 false，枚举值进去会静默失效。
+  chorographyInject: ["off", "light", "full"],
+  // Issue #641：冲突分诊账本档位。off（默认，零行为）/ shadow（只记账）/ enforce
+  // （确定性处置：T1 信息量优先 supersede，T2-T4 记账不停车不送 LLM）。三个档位
+  // 都有真实行为——「设了但没行为」的档位不进枚举（#616「假成功」教训）。
+  conflictLedgerMode: ["off", "shadow", "enforce"]
+};
+const FEATURE_FLAG_STRING_MAX = 200;
+
+// 供 api.js 复用同一份白名单（effective 只在白名单键上计算）。
+export const FEATURE_FLAG_SPEC = {
+  booleans: FEATURE_FLAG_BOOLEANS,
+  ints: FEATURE_FLAG_INT_RANGES,
+  numbers: FEATURE_FLAG_NUMBER_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;
+  }
+  const numRange = FEATURE_FLAG_NUMBER_RANGES[key];
+  if (numRange) {
+    const [min, max] = numRange;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+      throw new TypeError(`feature flag "${key}" must be a number 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, [min, max]] of Object.entries(FEATURE_FLAG_NUMBER_RANGES)) {
+    if (typeof raw[key] === "number" && Number.isFinite(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);
+
+  function getSetting(key) {
+    const row = db.prepare("SELECT value FROM user_settings WHERE key = ?").get(key);
+    return row?.value ?? undefined;
+  }
+
+  function setSetting(key, value) {
+    db.prepare(
+      `INSERT INTO user_settings (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+    ).run(key, value);
+  }
+
+  function toCommand(row) {
+    if (!row) return undefined;
+    return {
+      id: row.id,
+      name: row.name,
+      description: row.description,
+      instruction: row.instruction,
+      created_at: row.created_at,
+      updated_at: row.updated_at
+    };
+  }
+
+  return {
+    /** The user's self-description (free text) or "" when unset. */
+    getProfile() {
+      return getSetting("profile") ?? "";
+    },
+    setProfile(text) {
+      setSetting("profile", String(text ?? ""));
+    },
+
+    /** Behavior rules as an array of strings. */
+    getRules() {
+      return parseList(getSetting("rules") ?? "[]").filter((r) => typeof r === "string");
+    },
+    setRules(rules) {
+      const list = Array.isArray(rules) ? rules.filter((r) => typeof r === "string") : [];
+      setSetting("rules", JSON.stringify(list));
+    },
+
+    /**
+     * Agent persona (name / personality / replyStyle + enabled gate), stored as
+     * one JSON key. v1.2 多卡：存储形 { default, byAgent }，旧 v1 单对象读作
+     * default 兼容。getPersona 返回全量多卡形（面板与注入寻址都用它）。
+     * 寻址与兜底口径不在这里——住 src/user-settings.js 的 resolvePersonaCard，
+     * 注入与面板预览共用那一份；这里若再留一个 getPersonaFor，就是两张皮。
+     */
+    getPersona() {
+      return parsePersonaStore(getSetting("persona") ?? "{}");
+    },
+    setPersona(input) {
+      // 双形兼容：单对象形 = 只更新 default、byAgent/bySession 保留（旧面板/旧调用方
+      // 合并语义）；多卡形 = 全量替换。坏体（非对象）在此不落库不抛错，保值由调用方守卫。
+      if (typeof input !== "object" || input === null || Array.isArray(input)) return;
+      if ("default" in input || "byAgent" in input || "bySession" in input) {
+        setSetting("persona", serializePersonaStore(input));
+        return;
+      }
+      const current = parsePersonaStore(getSetting("persona") ?? "{}");
+      current.default = parsePersona(JSON.stringify(input));
+      setSetting("persona", serializePersonaStore(current));
+    },
+    /** Replace one byAgent card wholesale (panel save); default 不可经此改。 */
+    setPersonaFor(agentId, card) {
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      const clean = parsePersona(JSON.stringify(
+        typeof card === "object" && card !== null && !Array.isArray(card) ? card : {}
+      ));
+      if (Object.keys(clean).length) store.byAgent[id] = clean;
+      else delete store.byAgent[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+    /** byAgent 键列表（面板卡列表用，default 不在其中）。 */
+    listPersonas() {
+      return Object.keys(parsePersonaStore(getSetting("persona") ?? "{}").byAgent);
+    },
+    /** 删一张 byAgent 卡；default 不可删（返回 false）。 */
+    removePersona(agentId) {
+      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      if (!(id in store.byAgent)) return false;
+      delete store.byAgent[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+
+    /**
+     * 绑会话卡（#606）：按 sessionId 存/删/列。形状与 setPersonaFor 一族逐一对应，
+     * 只是换了一个维度——为什么需要第二维见 parsePersonaStore 的注释。
+     * sessionId 为空或 "default" 拒绝（与 byAgent 同一条纪律：兜底位不可被顶替）。
+     */
+    setPersonaForSession(sessionId, card) {
+      const id = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      const clean = parsePersona(JSON.stringify(
+        typeof card === "object" && card !== null && !Array.isArray(card) ? card : {}
+      ));
+      if (Object.keys(clean).length) store.bySession[id] = clean;
+      else delete store.bySession[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+    /** bySession 键列表（面板「按会话建的卡」用，default 不在其中）。 */
+    listPersonaSessions() {
+      return Object.keys(parsePersonaStore(getSetting("persona") ?? "{}").bySession);
+    },
+    /** 删一张 bySession 卡；不存在返回 false。 */
+    removePersonaForSession(sessionId) {
+      const id = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "";
+      if (!id || id === "default") return false;
+      const store = parsePersonaStore(getSetting("persona") ?? "{}");
+      if (!(id in store.bySession)) return false;
+      delete store.bySession[id];
+      setSetting("persona", serializePersonaStore(store));
+      return true;
+    },
+
+    /** All custom commands, sorted by name. */
+    listCommands() {
+      const rows = db.prepare("SELECT * FROM custom_commands ORDER BY name ASC").all();
+      return rows.map(toCommand);
+    },
+
+    /**
+     * Add or replace a custom command by name.
+     * @returns the stored command.
+     * @throws when name is invalid or does not match DSH's command-name grammar.
+     */
+    addCommand({ name, description = "", instruction }) {
+      const cmdName = String(name ?? "").trim();
+      if (!COMMAND_NAME.test(cmdName)) {
+        throw new Error(`invalid command name "${cmdName}": must match /^[a-z][a-z0-9_-]*$/`);
+      }
+      if (typeof instruction !== "string" || !instruction.trim()) {
+        throw new Error("command instruction must be a non-empty string");
+      }
+      const now = new Date().toISOString();
+      const existing = db.prepare("SELECT id FROM custom_commands WHERE name = ?").get(cmdName);
+      if (existing) {
+        db.prepare(
+          "UPDATE custom_commands SET description = ?, instruction = ?, updated_at = ? WHERE id = ?"
+        ).run(String(description ?? ""), instruction, now, existing.id);
+        return toCommand(db.prepare("SELECT * FROM custom_commands WHERE id = ?").get(existing.id));
+      }
+      const id = randomUUID();
+      db.prepare(
+        `INSERT INTO custom_commands (id, name, description, instruction, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?)`
+      ).run(id, cmdName, String(description ?? ""), instruction, now, now);
+      return toCommand(db.prepare("SELECT * FROM custom_commands WHERE id = ?").get(id));
+    },
+
+    /** Remove a custom command by id; returns true when removed. */
+    removeCommand(id) {
+      const result = db.prepare("DELETE FROM custom_commands WHERE id = ?").run(id);
+      return result.changes > 0;
+    },
+
+    /** Vector-search provider config (OpenAI-compatible embeddings endpoint). */
+    getVectorConfig() {
+      const raw = getSetting("vector");
+      if (!raw) return undefined;
+      try {
+        const cfg = JSON.parse(raw);
+        return typeof cfg === "object" && cfg !== null ? cfg : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    setVectorConfig({ enabled, baseUrl, apiKey, model }) {
+      const cfg = {
+        enabled: enabled === true || enabled === 1,
+        baseUrl: String(baseUrl ?? "").trim().replace(/\/+$/, ""),
+        apiKey: String(apiKey ?? "").trim(),
+        model: String(model ?? "").trim()
+      };
+      setSetting("vector", JSON.stringify(cfg));
+      return cfg;
+    },
+
+    /**
+     * Standalone external API settings (kv "external_api"): {enabled, port,
+     * token}. The Bearer token is auto-generated on first boot and persisted
+     * here. Partial writes preserve the keys they don't mention.
+     */
+    getExternalApi() {
+      const raw = getSetting("external_api");
+      if (!raw) return undefined;
+      try {
+        const cfg = JSON.parse(raw);
+        return typeof cfg === "object" && cfg !== null ? cfg : undefined;
+      } catch {
+        return undefined;
+      }
+    },
+    setExternalApi(patch = {}) {
+      const prev = this.getExternalApi() ?? {};
+      const port = Number(patch.port ?? prev.port);
+      const host = typeof patch.host === "string" && patch.host.trim() ? patch.host.trim() : (prev.host ?? "127.0.0.1");
+      const cfg = {
+        enabled: patch.enabled !== undefined ? patch.enabled === true : prev.enabled === true,
+        port: Number.isInteger(port) && port > 0 ? port : 8790,
+        host,
+        token: String(patch.token ?? prev.token ?? "")
+      };
+      setSetting("external_api", JSON.stringify(cfg));
+      return cfg;
+    },
+
+    /**
+     * Web panel mode (kv "panel_mode"): "light" (low-resource preset) or
+     * "standard" (full feature set). Unset reads as "standard".
+     */
+    getPanelMode() {
+      return getSetting("panel_mode") === "light" ? "light" : "standard";
+    },
+    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;
+    }
+  };
+}