@kira905/dsh-memory-toolkit 0.1.2 → 0.2.0

package/memory-engine/lib/cli-util.mjs

@@ -1,7 +1,9 @@
-// 记忆引擎 v2 · 离线层 —— CLI 公共工具
+// 命令行公共件：参数解析、入口守卫、日志出口、运行时装配。
 //
-// 入口守卫（铁律）：工作区下可能存在目录 junction，`import.meta.url` 会解析为物理路径而
-// `process.argv[1]` 是逻辑路径 ⇒ 必须 realpath 双方再比，否则 main 入口永不触发、脚本静默退出 0。
+// 入口守卫这条是铁律：工作区里可能挂着目录链接，`import.meta.url` 会被解析成物理路径，
+// 而 `process.argv[1]` 仍是调用方给的那条逻辑路径 ⇒ 两边都 realpath 之后再比；
+// 否则 main 永远不触发，脚本一声不响地以 0 退出。
+
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -12,186 +14,206 @@ import { openPitfallSource } from './pitfall-source.mjs';
 import { openPolicySource, scanPolicySources } from './policy-source.mjs';
 import { createStubEmbedder, createHttpEmbedder, createLocalEmbedder } from './embedder.mjs';
 
-/** 已实现的向量来源（值 = `vectors.source` 的取值） */
+/** 已实现的向量来源（取值即 `vectors.source` 里的字符串）。 */
 export const KNOWN_SOURCES = ['memory', 'pitfall', 'policy'];
 
-/** `--source` 取值（默认 memory；缺省不改任何现有行为） */
+// `--source` 的默认值：没给、给了空值、给了裸开关，一律当"没给" ⇒ 仍是 memory。
 export function resolveSourceName(flags = {}, dflt = 'memory') {
-  const s = flags.source;
-  if (s === undefined || s === true || s === '') return dflt;
-  return String(s);
+  const given = flags.source;
+  const missing = given === undefined || given === true || given === '';
+  return missing ? dflt : String(given);
 }
 
 /**
- * 按来源选数据源（方案 §A.2 第 11 行 I-1：**运行时选源单例**）。
- * ⚠️ 不改这里 ⇒ 即使 sync/sweep/recall 全参数化，命令行也**选不到**坑源。
+ * 按名字挑数据源 —— 运行时选源的唯一分发点。
+ * 下游就算全参数化了，命令行也只从这里才拿得到坑源与规则源。
  */
 export function openDataSource(name, config) {
-  const n = String(name);
-  if (n === 'memory') return openMemorySource(config.memoryDb);
-  if (n === 'pitfall') return openPitfallSource(config.pitfallsFile);
-  // 【2026-10-10 · 补坑库联动BCD】policy 源 = **每次现扫**（语料是文件，不是库）：
-  //   段清单由 `scanPolicySources()` 只读扫描得到 ⇒ 无需另建状态文件；增量同步靠 (refId, textHash) 幂等。
-  if (n === 'policy') {
-    return openPolicySource({
-      segments: scanPolicySources({
-        personaDir: config.policyPersonaDir,
-        skillsRoot: config.policySkillsRoot,
-        docsPaths: config.policyDocsPaths,
-      }),
-    });
+  const which = String(name);
+  if (which === 'memory') return openMemorySource(config.memoryDb);
+  if (which === 'pitfall') return openPitfallSource(config.pitfallsFile);
+  if (which === 'policy') {
+    // 规则源没有库：语料本身就是文件，每次现扫一份段清单喂进去
+    // （增量靠 refId + textHash 幂等，不需要另建状态文件）。
+    const segments = scanPolicySources({ personaDir: config.policyPersonaDir, skillsRoot: config.policySkillsRoot, docsPaths: config.policyDocsPaths });
+    return openPolicySource({ segments });
   }
-  throw new Error(`未知来源: ${n}（现支持 memory / pitfall / policy）`);
+  throw new Error(`未知来源: ${which}（现支持 memory / pitfall / policy）`);
 }
 
+// 两边都取物理路径再比；取不到（文件不在 / 权限不够）就当"不是入口"，不抛错。
 export function isMainEntry(importMetaUrl, argv1 = process.argv[1]) {
   if (!argv1) return false;
   try {
-    const a = fs.realpathSync(fileURLToPath(importMetaUrl));
-    const b = fs.realpathSync(argv1);
-    return a === b;
+    const self = fs.realpathSync(fileURLToPath(importMetaUrl));
+    return self === fs.realpathSync(argv1);
   } catch {
     return false;
   }
 }
 
+// 长开关的正则：`--name` 或 `--name=value` 两种形态一把抓（值里允许再出现等号）。
+const LONG_OPTION = /^--([^=]*)(?:=([\s\S]*))?$/;
+
+/**
+ * 极简参数解析：`--k=v`、`--k v`、`--k`（布尔）三种写法都认，其余进 rest。
+ * 不认识的开关不做校验 —— 交给各命令自己决定要不要报错。
+ */
 export function parseArgs(argv = process.argv.slice(2)) {
   const flags = {};
   const rest = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i];
-    if (a.startsWith('--')) {
-      const body = a.slice(2);
-      const eq = body.indexOf('=');
-      if (eq >= 0) {
-        flags[body.slice(0, eq)] = body.slice(eq + 1);
-      } else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) {
-        flags[body] = argv[i + 1];
-        i += 1;
-      } else {
-        flags[body] = true;
-      }
-    } else {
-      rest.push(a);
+  let at = 0;
+  while (at < argv.length) {
+    const token = argv[at];
+    const hit = LONG_OPTION.exec(token);
+    if (!hit) {
+      rest.push(token);
+      at += 1;
+      continue;
+    }
+    const [, name, inlineValue] = hit;
+    if (inlineValue !== undefined) {
+      flags[name] = inlineValue;
+      at += 1;
+      continue;
     }
+    const next = argv[at + 1];
+    // 下一个词本身还是开关 ⇒ 当前这个只能当布尔开关
+    if (next !== undefined && !next.startsWith('--')) {
+      flags[name] = next;
+      at += 2;
+      continue;
+    }
+    flags[name] = true;
+    at += 1;
   }
   return { flags, rest };
 }
 
-/** --json 时日志只上 stderr（机器只读 stdout 的 JSON） */
+/** `--json` 时人话日志一律走 stderr —— 机器只解析 stdout 上那一份 JSON。 */
 export function makeLogger({ json = false, quiet = false, prefix = '' } = {}) {
-  const write = (s) => {
-    if (quiet) return;
-    if (json) process.stderr.write(s + '\n');
-    else process.stdout.write(s + '\n');
+  const emit = (line) => {
+    if (!quiet) {
+      const sink = json ? process.stderr : process.stdout;
+      sink.write(`${line}\n`);
+    }
   };
-  return (msg) => write(prefix ? `${prefix} ${msg}` : String(msg));
+  return (msg) => emit(prefix ? `${prefix} ${msg}` : String(msg));
 }
 
+// 数值兜底：没给 / null / 裸开关都回默认值；转不成有限数字也回默认值。
 export function num(v, dflt) {
-  if (v === undefined || v === null || v === true) return dflt;
-  const n = Number(v);
-  return Number.isFinite(n) ? n : dflt;
+  const absent = v === undefined || v === null || v === true;
+  if (absent) return dflt;
+  const parsed = Number(v);
+  return Number.isFinite(parsed) ? parsed : dflt;
+}
+
+// 纯字符串型开关 → 配置字段（给了就带过去；空串与裸开关算没给）。
+const STRING_FLAGS = [
+  ['memoryDb', 'memory-db'],
+  ['vectorsDb', 'vectors-db'],
+  ['vectorsDir', 'vectors-dir'],
+  ['stateFile', 'state-file'],
+  ['pitfallsFile', 'pitfalls-file'],
+  ['pitfallVectorDirtyFile', 'pitfall-dirty-file'],
+  ['policyPersonaDir', 'policy-persona-dir'],
+  ['policySkillsRoot', 'policy-skills-root'],
+  ['modelDir', 'model-dir'],
+  ['modelId', 'model'],
+  ['hostId', 'host'],
+  ['dshHome', 'dsh-home'],
+];
+
+// 数值型开关 → 配置字段（裸开关按 Number(true) = 1 算，与历史口径一致）。
+const NUMBER_FLAGS = [
+  ['dim', 'dim'],
+  ['batchSize', 'batch'],
+  ['bridgePort', 'bridge-port'],
+];
+
+const wasGiven = (raw) => raw !== undefined && raw !== '' && raw !== false;
+
+// 命令行 → 覆盖项。只带真给了的那几项，剩下的留给环境变量与默认值。
+function configOverrides(flags) {
+  const overrides = {};
+  for (const [field, flag] of STRING_FLAGS) {
+    if (wasGiven(flags[flag])) overrides[field] = flags[flag];
+  }
+  for (const [field, flag] of NUMBER_FLAGS) {
+    if (wasGiven(flags[flag])) overrides[field] = Number(flags[flag]);
+  }
+  const docs = flags['policy-docs'];
+  if (docs) {
+    overrides.policyDocsPaths = String(docs).split(',').map((piece) => piece.trim()).filter(Boolean);
+  }
+  return overrides;
+}
+
+// 三种编码器按开关挑：stub（骨架）> http（回环桥）> local（默认）。
+function buildEmbedder(flags, config) {
+  if (flags['stub-embedder']) {
+    return createStubEmbedder({ dim: config.dim, modelId: `${config.modelId}-stub` });
+  }
+  if (flags['http-embedder']) {
+    const bridge = { host: config.bridgeHost, port: config.bridgePort, modelId: config.modelId, dim: config.dim };
+    return createHttpEmbedder({ ...bridge, timeoutMs: num(flags['bridge-timeout'], 250) });
+  }
+  return createLocalEmbedder({ modelDir: config.modelDir, modelId: config.modelId, dim: config.dim, quantized: Boolean(flags.quantized), dtype: flags.dtype || null });
 }
 
 /**
- * 打开运行时（配置 / 向量库 / 记忆库只读 / 编码器）。
- * 一切路径可注入；CLI 未传时落默认（≈ `~/.dsh`）。
+ * 装配一次运行时：配置 + 向量库 + 数据源 + 编码器。
+ * 所有路径都能注入；命令行没给时落默认（≈ 用户主目录下的引擎根）。
  */
 export async function openRuntime(flags = {}, { withSource = true, withEmbedder = true } = {}) {
-  const config = resolveConfig({
-    memoryDb: flags['memory-db'] || undefined,
-    vectorsDb: flags['vectors-db'] || undefined,
-    vectorsDir: flags['vectors-dir'] || undefined,
-    stateFile: flags['state-file'] || undefined,
-    pitfallsFile: flags['pitfalls-file'] || undefined,
-    pitfallVectorDirtyFile: flags['pitfall-dirty-file'] || undefined,
-    // 【2026-10-10 · 补坑库联动BCD】policy 语料面（隔离建库时用：向量库落隔离 home、
-    //   语料仍指生产只读路径 ⇒ 既不动生产库，又能编出真语料）
-    policyPersonaDir: flags['policy-persona-dir'] || undefined,
-    policySkillsRoot: flags['policy-skills-root'] || undefined,
-    policyDocsPaths: flags['policy-docs']
-      ? String(flags['policy-docs']).split(',').map((s) => s.trim()).filter(Boolean)
-      : undefined,
-    modelDir: flags['model-dir'] || undefined,
-    modelId: flags.model || undefined,
-    dim: flags.dim ? Number(flags.dim) : undefined,
-    hostId: flags.host || undefined,
-    batchSize: flags.batch ? Number(flags.batch) : undefined,
-    bridgePort: flags['bridge-port'] ? Number(flags['bridge-port']) : undefined,
-    dshHome: flags['dsh-home'] || undefined,
-  });
-
-  const store = openVectorsStore(config.vectorsDb, { create: true });
-  store.hostId = config.hostId;
-
-  // 数据源按名字缓存（多来源召回要同时开 memory + pitfall；同一来源只开一次）
-  const cache = new Map();
-  const openSource = (name) => {
-    const n = String(name);
-    if (!cache.has(n)) cache.set(n, openDataSource(n, config));
-    return cache.get(n);
+  const config = resolveConfig(configOverrides(flags));
+  const vault = openVectorsStore(config.vectorsDb, { create: true });
+  vault.hostId = config.hostId;
+
+  // 数据源按名字缓存：多来源召回会同时开 memory 与 pitfall，同一个名字只开一次、收尾一次关掉。
+  const opened = new Map();
+  const sourceFor = (name) => {
+    const key = String(name);
+    if (!opened.has(key)) opened.set(key, openDataSource(key, config));
+    return opened.get(key);
   };
-  const sourceName = resolveSourceName(flags);
-  let source = null;
-  if (withSource) source = openSource(sourceName);
-
-  let embedder = null;
-  if (!withEmbedder) {
-    embedder = null;
-  } else if (flags['stub-embedder']) {
-    embedder = createStubEmbedder({ dim: config.dim, modelId: `${config.modelId}-stub` });
-  } else if (flags['http-embedder']) {
-    embedder = createHttpEmbedder({
-      host: config.bridgeHost,
-      port: config.bridgePort,
-      timeoutMs: num(flags['bridge-timeout'], 250),
-      modelId: config.modelId,
-      dim: config.dim,
-    });
-  } else {
-    embedder = await createLocalEmbedder({
-      modelDir: config.modelDir,
-      modelId: config.modelId,
-      dim: config.dim,
-      quantized: Boolean(flags.quantized),
-      dtype: flags.dtype || null,
-    });
-  }
+  const chosen = resolveSourceName(flags);
+  const source = withSource ? sourceFor(chosen) : null;
+  const embedder = withEmbedder ? await buildEmbedder(flags, config) : null;
 
   return {
-    config,
-    store,
-    source,
-    sourceName,
-    openSource,
-    embedder,
+    config, store: vault, source, sourceName: chosen, openSource: sourceFor, embedder,
     close() {
-      for (const s of cache.values()) {
+      for (const handle of opened.values()) {
         try {
-          if (s) s.close();
+          if (handle) handle.close();
         } catch {
-          /* ignore */
+          // 关不掉不算错
         }
       }
-      cache.clear();
+      opened.clear();
       try {
-        store.db.close();
+        vault.db.close();
       } catch {
-        /* ignore */
+        // 同上
       }
     },
   };
 }
 
+// 日志里尽量给相对路径（短、好读）；算不出来就原样回。
 export function relForLog(p) {
   try {
-    return path.relative(process.cwd(), p) || p;
+    const rel = path.relative(process.cwd(), p);
+    return rel || p;
   } catch {
     return p;
   }
 }
 
+// 毫秒读数统一保留一位小数，后缀写死。
 export function fmtMs(v) {
-  return `${Number(v).toFixed(1)}ms`;
+  const fixed = Number(v).toFixed(1);
+  return `${fixed}ms`;
 }

package/memory-engine/lib/config.mjs

@@ -1,135 +1,122 @@
-// 记忆引擎 v2 · 离线层 —— 配置与路径解析
+// 配置解析层：所有落盘位置、模型参数、同步与召回阈值都从这一处成形，别处不再自己拼路径。
 //
-// 铁律（方案 §4 宿主迁移契约 / 本卡「测试不得写生产路径」）：
-//   1. 一切路径都可注入（overrides）或经环境变量覆盖，默认值才落 ~/.dsh；
-//   2. 测试一律显式传临时目录，绝不落到生产路径；
-//   3. 不写死机器名/主机名常量。
+// 取值优先级是固定的三段：显式入参 > 环境变量 > 内置默认。
+// 只有三段都没给，才退回用户主目录下的默认根；因此同一份代码换台机器只需换环境变量。
+// 这里不写死任何机器名/主机名；测试必须自带临时目录，不许落默认位置。
+
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-// ⚠️ 本常量 = **向量库（vectors.db）** 的 schema 版本。
-//   2026-10-10 · 补坑库联动A：'1' → '2'（meta 键位加 `<key>:<source>` 命名空间；**表结构未变**，
-//   老库靠 `migrateMetaNamespace()` 幂等迁移 + 兼容读，回滚靠「冗余写」保持旧键同值）。
-//   ⚠️ 文档索引库（doc-index.db）的 DDL 与本库无关，**不要**跟着改 —— 它有独立常量（见下）。
+// 向量库的结构版本：只有键位/表结构真的改了才动它。
+// 文档索引库是另一只库，版本号各算各的，别跟着这里一起抬。
 export const SCHEMA_VERSION = '2';
-/** 文档索引库（doc-index.db）的 schema 版本（本轮未动其 DDL ⇒ 保持 '1'） */
 export const DOC_INDEX_SCHEMA_VERSION = '1';
 export const DEFAULT_MODEL_ID = 'bge-small-zh-v1.5';
 export const DEFAULT_DIM = 512;
 
-/** 模型权重目录候选（第一个存在的即用；都不存在则用最后一个 = 会被创建的那个） */
+// 权重目录的三个候选，按优先级排：环境变量 > 用户目录 > 本地缓存目录。
 export function defaultModelDirCandidates() {
+  const home = os.homedir();
   return [
     process.env.MEMORY_ENGINE_MODEL_DIR,
-    path.join(os.homedir(), '.dsh', 'memory-engine', 'models'), // 可经 MEMORY_ENGINE_MODEL_DIR 覆盖
-    path.join(os.homedir(), '.cache', 'dsh-memory-engine', 'models'),
+    path.join(home, '.dsh', 'memory-engine', 'models'),
+    path.join(home, '.cache', 'dsh-memory-engine', 'models'),
   ].filter(Boolean);
 }
 
+// 取第一个真实存在的候选；一个都不在就返回末位那个（调用方负责去创建）。
 export function defaultModelDir() {
-  const candidates = defaultModelDirCandidates();
-  for (const c of candidates) {
+  const dirs = defaultModelDirCandidates();
+  for (const dir of dirs) {
     try {
-      if (fs.existsSync(c)) return c;
+      if (fs.existsSync(dir)) return dir;
     } catch {
-      /* 忽略探测失败 */
+      // 探测失败当作"不存在"，继续看下一个
     }
   }
-  return candidates[candidates.length - 1];
+  return dirs[dirs.length - 1];
 }
 
+// 字符串字段：入参 > 环境变量 > 兜底。用 || 是故意的 —— 空串同样算"没给"。
+const pick = (value, envValue, fallback) => value || envValue || fallback;
+
+// 路径字段：兜底值由 dshHome 拼出来，换根目录时整棵树跟着搬。
+const pickPath = (dshHome, value, envValue, segments) =>
+  pick(value, envValue, path.join(dshHome, ...segments));
+
+// 数值字段：只做一次 Number，非数字怎么处理交给上层（保持既有口径，不在这里纠偏）。
+const pickNumber = (value, envValue, fallback) => Number(pick(value, envValue, fallback));
+
 /**
- * 解析配置。overrides 优先级最高，其次环境变量，最后默认值。
- * 关键字段（测试可全部覆盖）：memoryDb / vectorsDb / stateFile / modelDir。
+ * 把三层来源折成一份配置。
+ * 关键位置（记忆库 / 向量库 / 状态文件 / 模型目录）测试可以全部覆盖。
  */
 export function resolveConfig(overrides = {}) {
   const env = overrides.env || process.env;
-  const dshHome =
-    overrides.dshHome ||
-    env.DSH_HOME ||
-    path.join(os.homedir(), '.dsh');
-
-  const vectorsDir =
-    overrides.vectorsDir ||
-    env.MEMORY_ENGINE_VECTORS_DIR ||
-    path.join(dshHome, 'memory-vectors');
+  const dshHome = pick(overrides.dshHome, env.DSH_HOME, path.join(os.homedir(), '.dsh'));
+  const vectorsDir = pick(
+    overrides.vectorsDir,
+    env.MEMORY_ENGINE_VECTORS_DIR,
+    path.join(dshHome, 'memory-vectors'),
+  );
 
   return {
     dshHome,
-    // 数据源：默认生产库；本卡一律传副本路径（方案 §8.1 铁律）
-    memoryDb:
-      overrides.memoryDb ||
-      env.MEMORY_ENGINE_MEMORY_DB ||
-      path.join(dshHome, 'memory', 'memory.db'),
+    memoryDb: pickPath(dshHome, overrides.memoryDb, env.MEMORY_ENGINE_MEMORY_DB, ['memory', 'memory.db']),
     vectorsDir,
-    vectorsDb:
-      overrides.vectorsDb ||
-      env.MEMORY_ENGINE_VECTORS_DB ||
-      path.join(vectorsDir, 'vectors.db'),
-    stateFile:
-      overrides.stateFile ||
-      env.MEMORY_ENGINE_STATE ||
-      path.join(dshHome, 'butler-memory-vectors-state.json'),
-
-    // 【2026-10-10 · 补坑库联动A】坑库第二向量来源（source='pitfall'）的输入与标记文件
-    //   · pitfallsFile：坑库状态文件（**只读**，A 点不写它）
-    //   · pitfallVectorDirtyFile：置/清标记双写者的那个标记文件（登记见 dsh-butler/lib/state-files.mjs）
-    pitfallsFile:
-      overrides.pitfallsFile ||
-      env.MEMORY_ENGINE_PITFALLS_FILE ||
-      path.join(dshHome, 'butler-pitfalls.json'),
-    pitfallVectorDirtyFile:
-      overrides.pitfallVectorDirtyFile ||
-      env.MEMORY_ENGINE_PITFALL_DIRTY ||
-      path.join(dshHome, 'butler-pitfall-vector-dirty.json'),
-
-    // 【2026-10-10 · 补坑库联动BCD】policy 语料面（source='policy' · 落地判据向量化 · B 点）
-    //   语料三份里 MVP 只做前两份（方案 §4 B.3-1）：① persona 铁律段 ② 技能段；③ 文档段默认空
-    //   （「不做全量 docs」是方案的明写 Non-goal —— 那是 S3 doc-index 的活）。
-    //   ⚠️ policy 库**只在本机建**（D5 已拍 = 不跨机传 persona/技能文本）⇒ 库不进任何同步仓。
-    policyPersonaDir:
-      overrides.policyPersonaDir ||
-      env.MEMORY_ENGINE_POLICY_PERSONA_DIR ||
-      path.join(dshHome, '.agent-presets'),
-    policySkillsRoot:
-      overrides.policySkillsRoot ||
-      env.MEMORY_ENGINE_POLICY_SKILLS_ROOT ||
-      path.join(dshHome, 'skills'),
-    policyDocsPaths: overrides.policyDocsPaths || null, // 默认空（后置项，不默认扫全量 docs）
-
-    // 文档索引层（方案 §3.2：独立库出主库；§4 载体清单）
-    docIndexDb:
-      overrides.docIndexDb ||
-      env.DOC_INDEX_DB ||
-      path.join(vectorsDir, 'doc-index.db'),
-    docIndexState:
-      overrides.docIndexState ||
-      env.DOC_INDEX_STATE ||
-      path.join(dshHome, 'butler-doc-index-state.json'),
-    // 扫描面与 path 口径锚（不写死机器名；方案 §4 宿主迁移契约）
-    docsRoot: overrides.docsRoot || env.DOC_INDEX_DOCS_ROOT || path.join(process.cwd(), 'docs'),
-    dshRoot: overrides.dshRoot || env.DOC_INDEX_DSH_ROOT || process.cwd(),
+    vectorsDb: pick(overrides.vectorsDb, env.MEMORY_ENGINE_VECTORS_DB, path.join(vectorsDir, 'vectors.db')),
+    stateFile: pickPath(dshHome, overrides.stateFile, env.MEMORY_ENGINE_STATE, [
+      'butler-memory-vectors-state.json',
+    ]),
+
+    // 坑库这条来源的两个文件：一个只读输入，一个置/清标记用（都不由本层写）。
+    pitfallsFile: pickPath(dshHome, overrides.pitfallsFile, env.MEMORY_ENGINE_PITFALLS_FILE, [
+      'butler-pitfalls.json',
+    ]),
+    pitfallVectorDirtyFile: pickPath(
+      dshHome,
+      overrides.pitfallVectorDirtyFile,
+      env.MEMORY_ENGINE_PITFALL_DIRTY,
+      ['butler-pitfall-vector-dirty.json'],
+    ),
+
+    // 规则/技能语料面：persona 与技能目录各一处；文档面默认关（要扫时由调用方显式给）。
+    // 这三处只读，且只在产生它的那台机器上有意义，不跟着任何同步走。
+    policyPersonaDir: pickPath(dshHome, overrides.policyPersonaDir, env.MEMORY_ENGINE_POLICY_PERSONA_DIR, [
+      '.agent-presets',
+    ]),
+    policySkillsRoot: pickPath(dshHome, overrides.policySkillsRoot, env.MEMORY_ENGINE_POLICY_SKILLS_ROOT, [
+      'skills',
+    ]),
+    policyDocsPaths: overrides.policyDocsPaths || null,
+
+    // 文档索引是独立库：库文件和运行状态都与向量库分开摆。
+    docIndexDb: pick(overrides.docIndexDb, env.DOC_INDEX_DB, path.join(vectorsDir, 'doc-index.db')),
+    docIndexState: pickPath(dshHome, overrides.docIndexState, env.DOC_INDEX_STATE, [
+      'butler-doc-index-state.json',
+    ]),
+    docsRoot: pick(overrides.docsRoot, env.DOC_INDEX_DOCS_ROOT, path.join(process.cwd(), 'docs')),
+    dshRoot: pick(overrides.dshRoot, env.DOC_INDEX_DSH_ROOT, process.cwd()),
 
     modelDir: overrides.modelDir || defaultModelDir(),
-    modelId: overrides.modelId || env.MEMORY_ENGINE_MODEL_ID || DEFAULT_MODEL_ID,
-    dim: Number(overrides.dim || env.MEMORY_ENGINE_DIM || DEFAULT_DIM),
+    modelId: pick(overrides.modelId, env.MEMORY_ENGINE_MODEL_ID, DEFAULT_MODEL_ID),
+    dim: pickNumber(overrides.dim, env.MEMORY_ENGINE_DIM, DEFAULT_DIM),
 
-    // 同步参数（方案 §3.1：批 50）
-    batchSize: Number(overrides.batchSize || env.MEMORY_ENGINE_BATCH || 50),
-    // 兜底 hash 轮转段数（方案 §3.1：按周 / id 段轮转覆盖全表）
-    sweepSegments: Number(overrides.sweepSegments || env.MEMORY_ENGINE_SWEEP_SEGMENTS || 20),
+    // 同步：一批多少条；兜底轮转把全表切几段。
+    batchSize: pickNumber(overrides.batchSize, env.MEMORY_ENGINE_BATCH, 50),
+    sweepSegments: pickNumber(overrides.sweepSegments, env.MEMORY_ENGINE_SWEEP_SEGMENTS, 20),
 
-    // 召回参数（方案 §3.3）
-    vectorTopK: Number(overrides.vectorTopK || env.MEMORY_ENGINE_VEC_TOPK || 20),
-    ftsTopK: Number(overrides.ftsTopK || env.MEMORY_ENGINE_FTS_TOPK || 20),
-    rrfK: Number(overrides.rrfK || env.MEMORY_ENGINE_RRF_K || 60),
-    resultTopK: Number(overrides.resultTopK || env.MEMORY_ENGINE_RESULT_TOPK || 8),
+    // 召回：向量候选数 / 关键词候选数 / 融合常数 / 最终条数。
+    vectorTopK: pickNumber(overrides.vectorTopK, env.MEMORY_ENGINE_VEC_TOPK, 20),
+    ftsTopK: pickNumber(overrides.ftsTopK, env.MEMORY_ENGINE_FTS_TOPK, 20),
+    rrfK: pickNumber(overrides.rrfK, env.MEMORY_ENGINE_RRF_K, 60),
+    resultTopK: pickNumber(overrides.resultTopK, env.MEMORY_ENGINE_RESULT_TOPK, 8),
 
-    // 编码桥（方案 §3.1 编码通道契约：仅回环、端口 8201）
-    bridgeHost: overrides.bridgeHost || env.MEMORY_ENGINE_BRIDGE_HOST || '127.0.0.1',
-    bridgePort: Number(overrides.bridgePort || env.MEMORY_ENGINE_BRIDGE_PORT || 8201),
+    // 编码桥只走回环地址，端口默认 8201。
+    bridgeHost: pick(overrides.bridgeHost, env.MEMORY_ENGINE_BRIDGE_HOST, '127.0.0.1'),
+    bridgePort: pickNumber(overrides.bridgePort, env.MEMORY_ENGINE_BRIDGE_PORT, 8201),
 
-    hostId: overrides.hostId || env.MEMORY_ENGINE_HOST_ID || os.hostname(),
+    hostId: pick(overrides.hostId, env.MEMORY_ENGINE_HOST_ID, os.hostname()),
   };
 }