@kira905/dsh-memory-toolkit 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,197 @@
+// 记忆引擎 v2 · 离线层 —— CLI 公共工具
+//
+// 入口守卫（铁律）：工作区下可能存在目录 junction，`import.meta.url` 会解析为物理路径而
+// `process.argv[1]` 是逻辑路径 ⇒ 必须 realpath 双方再比，否则 main 入口永不触发、脚本静默退出 0。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveConfig } from './config.mjs';
+import { openVectorsStore } from './vectors-store.mjs';
+import { openMemorySource } from './memory-source.mjs';
+import { openPitfallSource } from './pitfall-source.mjs';
+import { openPolicySource, scanPolicySources } from './policy-source.mjs';
+import { createStubEmbedder, createHttpEmbedder, createLocalEmbedder } from './embedder.mjs';
+
+/** 已实现的向量来源（值 = `vectors.source` 的取值） */
+export const KNOWN_SOURCES = ['memory', 'pitfall', 'policy'];
+
+/** `--source` 取值（默认 memory；缺省不改任何现有行为） */
+export function resolveSourceName(flags = {}, dflt = 'memory') {
+  const s = flags.source;
+  if (s === undefined || s === true || s === '') return dflt;
+  return String(s);
+}
+
+/**
+ * 按来源选数据源（方案 §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,
+      }),
+    });
+  }
+  throw new Error(`未知来源: ${n}（现支持 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;
+  } catch {
+    return false;
+  }
+}
+
+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);
+    }
+  }
+  return { flags, rest };
+}
+
+/** --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');
+  };
+  return (msg) => write(prefix ? `${prefix} ${msg}` : String(msg));
+}
+
+export function num(v, dflt) {
+  if (v === undefined || v === null || v === true) return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : dflt;
+}
+
+/**
+ * 打开运行时（配置 / 向量库 / 记忆库只读 / 编码器）。
+ * 一切路径可注入；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 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,
+    });
+  }
+
+  return {
+    config,
+    store,
+    source,
+    sourceName,
+    openSource,
+    embedder,
+    close() {
+      for (const s of cache.values()) {
+        try {
+          if (s) s.close();
+        } catch {
+          /* ignore */
+        }
+      }
+      cache.clear();
+      try {
+        store.db.close();
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+export function relForLog(p) {
+  try {
+    return path.relative(process.cwd(), p) || p;
+  } catch {
+    return p;
+  }
+}
+
+export function fmtMs(v) {
+  return `${Number(v).toFixed(1)}ms`;
+}

package/memory-engine/lib/config.mjs

@@ -0,0 +1,135 @@
+// 记忆引擎 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() {
+  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'),
+  ].filter(Boolean);
+}
+
+export function defaultModelDir() {
+  const candidates = defaultModelDirCandidates();
+  for (const c of candidates) {
+    try {
+      if (fs.existsSync(c)) return c;
+    } catch {
+      /* 忽略探测失败 */
+    }
+  }
+  return candidates[candidates.length - 1];
+}
+
+/**
+ * 解析配置。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');
+
+  return {
+    dshHome,
+    // 数据源：默认生产库；本卡一律传副本路径（方案 §8.1 铁律）
+    memoryDb:
+      overrides.memoryDb ||
+      env.MEMORY_ENGINE_MEMORY_DB ||
+      path.join(dshHome, '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(),
+
+    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),
+
+    // 同步参数（方案 §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),
+
+    // 召回参数（方案 §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),
+
+    // 编码桥（方案 §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),
+
+    hostId: overrides.hostId || env.MEMORY_ENGINE_HOST_ID || os.hostname(),
+  };
+}

package/memory-engine/lib/dirty-ledger.mjs

@@ -0,0 +1,174 @@
+// 记忆引擎 v2 · S3c —— `memories_dirty` 台账（兜底 hash 轮转的**产物**）
+//
+// 为什么要有它（方案 §3.5 输入行「v3 补漏（关 I5）」）：
+//   A7 实测 5 个脚本 41 处 `UPDATE memories SET text=?`，其中 `apply-pinned-refine.mjs:110`
+//   改 text **不动 `updated_at`** ⇒ 这类被勘误的记忆**永远不在 24h 增量窗口内**。
+//   方案给的修法 = 把「§3.1 全表 `text_hash` 段轮转」的**产物**（差异清单）作为提炼 job 的补充输入源。
+//
+// 关键设计：差异清单必须**持久化**，不能只在内存里过一遍 ——
+//   轮转（`lib/sweep.mjs`）发现差异后会**立刻重编码并更新 `vectors.text_hash`**，
+//   差异信号当场消失；若当时没人消费，这条改动就永久消失在增量窗口之外（正是要治的病）。
+//   ⇒ 检测到差异的**那一刻**就落台账；提炼 job 事后按台账补齐输入。
+//
+// 落点：`vectors.db`（独立向量库，`sync:false` 不进任何仓，可重建）。
+//   放这里而不是新开 state 文件：它**本来就是**向量层的派生产物（与 `vectors.text_hash` 同源），
+//   且向量库随 `~/.dsh/memory-vectors/` 一起被清理/重建，台账不会成为孤儿。
+//
+// 语义：一条 = 一个 `ref_id`（memory.id）。
+//   · `kind='mismatch'`：正文哈希与向量库记录不符 ⇒ **正文被改过**（本台账的唯一入账类型）
+//   · `consumed_at`：提炼 job 消费过（= 已并入某次提炼输入）
+//     ⚠️ **不删行**：删了就没法回答"这条改动是谁消费的"；保留 + 定期 prune。
+import { DatabaseSync } from 'node:sqlite';
+
+/** 台账 DDL（幂等；与 `vectors-store.mjs` 同库，加表不前向破坏既有表）。 */
+export const DIRTY_DDL = `
+CREATE TABLE IF NOT EXISTS memories_dirty (
+  ref_id      TEXT    NOT NULL PRIMARY KEY,
+  kind        TEXT    NOT NULL,
+  old_hash    TEXT,
+  new_hash    TEXT,
+  first_at    INTEGER NOT NULL,
+  last_at     INTEGER NOT NULL,
+  hits        INTEGER NOT NULL DEFAULT 1,
+  consumed_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS memories_dirty_open ON memories_dirty (consumed_at, last_at);
+`;
+
+export const DIRTY_SCHEMA = 1;
+
+export function ensureDirtySchema(db) {
+  db.exec(DIRTY_DDL);
+  return true;
+}
+
+function hasTable(db, name) {
+  return Boolean(db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name = ?").get(name));
+}
+
+/**
+ * 记一批差异（**幂等 upsert**）。
+ *
+ * 重复记账的口径（写死，别再各写各的）：
+ *   · 同一 `ref_id` 再次被检测到 → `hits+1` / `last_at` 刷新 / `new_hash` 刷新；
+ *   · **`new_hash` 与库里不同 = 正文又变了** ⇒ 把 `consumed_at` 清空（重新变成待消费），
+ *     否则"消费过"的标记会把第二次改动永久吞掉（这正是台账最容易写错的一处）。
+ *
+ * @param {object} db 向量库连接（写）
+ * @param {Array<{refId:string|number, kind?:string, oldHash?:string|null, newHash?:string|null}>} items
+ * @param {{now?:number}} [opts]
+ * @returns {{recorded:number, reopened:number}}
+ */
+export function recordDirty(db, items, opts = {}) {
+  if (!items || !items.length) return { recorded: 0, reopened: 0 };
+  ensureDirtySchema(db);
+  const now = Number(opts.now ?? Date.now());
+  const sel = db.prepare('SELECT ref_id, new_hash, consumed_at FROM memories_dirty WHERE ref_id = ?');
+  const ins = db.prepare(`INSERT INTO memories_dirty (ref_id, kind, old_hash, new_hash, first_at, last_at, hits, consumed_at)
+                          VALUES (?, ?, ?, ?, ?, ?, 1, NULL)`);
+  const upd = db.prepare(`UPDATE memories_dirty SET kind = ?, old_hash = ?, new_hash = ?, last_at = ?, hits = hits + 1,
+                          consumed_at = ? WHERE ref_id = ?`);
+  let recorded = 0;
+  let reopened = 0;
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    for (const it of items) {
+      const refId = String(it.refId);
+      if (!refId) continue;
+      const kind = String(it.kind ?? 'mismatch');
+      const oldHash = it.oldHash ?? null;
+      const newHash = it.newHash ?? null;
+      const prev = sel.get(refId);
+      if (!prev) {
+        ins.run(refId, kind, oldHash, newHash, now, now);
+        recorded += 1;
+        continue;
+      }
+      const changedAgain = newHash != null && prev.new_hash != null && prev.new_hash !== newHash;
+      if (changedAgain && prev.consumed_at != null) reopened += 1;
+      // ⚠️ 只有"正文又变了"才清 consumed_at；**同一条重复被扫到不得清**（否则每轮轮转都会重新消费一遍）
+      upd.run(kind, oldHash, newHash, now, changedAgain ? null : prev.consumed_at, refId);
+      recorded += 1;
+    }
+    db.exec('COMMIT');
+  } catch (e) {
+    try { db.exec('ROLLBACK'); } catch { /* ignore */ }
+    throw e;
+  }
+  return { recorded, reopened };
+}
+
+/**
+ * 读台账。
+ * @param {object} db
+ * @param {{includeConsumed?:boolean, openOnly?:boolean, limit?:number}} [opts]
+ */
+export function listDirty(db, opts = {}) {
+  if (!hasTable(db, 'memories_dirty')) return [];
+  const openOnly = opts.openOnly !== false && opts.includeConsumed !== true;
+  const lim = Number(opts.limit ?? 0);
+  const sql = `SELECT ref_id, kind, old_hash, new_hash, first_at, last_at, hits, consumed_at
+               FROM memories_dirty ${openOnly ? 'WHERE consumed_at IS NULL' : ''}
+               ORDER BY last_at DESC${lim > 0 ? ` LIMIT ${lim}` : ''}`;
+  return db.prepare(sql).all().map((r) => ({
+    refId: String(r.ref_id), kind: r.kind, oldHash: r.old_hash, newHash: r.new_hash,
+    firstAt: Number(r.first_at), lastAt: Number(r.last_at), hits: Number(r.hits),
+    consumedAt: r.consumed_at == null ? null : Number(r.consumed_at),
+  }));
+}
+
+/** 标记已消费（提炼 job 把这批 id 并入输入后调用）。 */
+export function markConsumed(db, refIds, opts = {}) {
+  if (!refIds || !refIds.length) return 0;
+  if (!hasTable(db, 'memories_dirty')) return 0;
+  const now = Number(opts.now ?? Date.now());
+  const stmt = db.prepare('UPDATE memories_dirty SET consumed_at = ? WHERE ref_id = ? AND consumed_at IS NULL');
+  let n = 0;
+  db.exec('BEGIN IMMEDIATE');
+  try {
+    for (const id of refIds) n += Number(stmt.run(now, String(id)).changes || 0);
+    db.exec('COMMIT');
+  } catch (e) {
+    try { db.exec('ROLLBACK'); } catch { /* ignore */ }
+    throw e;
+  }
+  return n;
+}
+
+/** 台账概览（state / CLI / 日报用）。 */
+export function dirtyStats(db) {
+  if (!hasTable(db, 'memories_dirty')) return { table: false, total: 0, open: 0, consumed: 0, lastAt: null };
+  const r = db.prepare(`SELECT COUNT(*) total,
+      SUM(CASE WHEN consumed_at IS NULL THEN 1 ELSE 0 END) open_count,
+      SUM(CASE WHEN consumed_at IS NOT NULL THEN 1 ELSE 0 END) consumed_count,
+      MAX(last_at) last_at FROM memories_dirty`).get();
+  return {
+    table: true,
+    total: Number(r.total ?? 0),
+    open: Number(r.open_count ?? 0),
+    consumed: Number(r.consumed_count ?? 0),
+    lastAt: r.last_at == null ? null : Number(r.last_at),
+  };
+}
+
+/** 定期清理：清掉**已消费**且早于 `keepDays` 的行（未消费的永不清理）。 */
+export function pruneDirty(db, opts = {}) {
+  if (!hasTable(db, 'memories_dirty')) return 0;
+  const now = Number(opts.now ?? Date.now());
+  const keepDays = Number(opts.keepDays ?? 90);
+  const cutoff = now - keepDays * 86_400_000;
+  const r = db.prepare('DELETE FROM memories_dirty WHERE consumed_at IS NOT NULL AND consumed_at < ?').run(cutoff);
+  return Number(r.changes || 0);
+}
+
+/** 便捷：直接按库路径开一个写连接执行 fn（台账写入方都是短命脚本）。 */
+export function withDirtyDb(dbPath, fn) {
+  const db = new DatabaseSync(dbPath);
+  try {
+    db.exec('PRAGMA busy_timeout = 5000;');
+    ensureDirtySchema(db);
+    return fn(db);
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+}

package/memory-engine/lib/distill-rollback.mjs

@@ -0,0 +1,178 @@
+// 记忆引擎 v2 · S3c —— 提炼产物回滚（方案 §3.5 回滚行）
+//
+// 口径：**按 `tags LIKE 'distilled%'` 批量列出 / 删除**；默认 dry-run；删除前 `VACUUM INTO` 快照。
+// 为什么按 tag 而不是按 id 清单：提炼条是**推断产物**，主人可能整批否定（"这批结论不对"），
+//   也可能只否定某几组 ⇒ 两种粒度都要能选：`--key <srcKey>`（整组）/ `--id <行 id>`（单条）。
+// ⚠️ 删除语句**恒带 `AND tags LIKE 'distilled%'`** —— 即使调用方算错了 id 集合，也不可能误删真实记忆。
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { vacuumInto } from './domain-tags.mjs';
+import { DISTILL_PREFIX } from './distill.mjs';
+
+/** 解析提炼条标签 → {srcKey, srcIds, date}。 */
+export function parseDistilledTags(tags) {
+  const t = String(tags ?? '');
+  if (!t.startsWith(DISTILL_PREFIX)) return null;
+  const key = t.match(/(?:^|\s)src=([0-9a-f]+)(?:\s|$)/);
+  const ids = t.match(/(?:^|\s)srcids=([0-9,\s]*)(?:\s|$)/);
+  const date = t.match(/(?:^|\s)date=(\d{8})(?:\s|$)/);
+  return {
+    srcKey: key ? key[1] : null,
+    srcIds: ids && ids[1] ? ids[1].split(',').map((x) => Number(x.trim())).filter((x) => Number.isFinite(x)) : [],
+    date: date ? date[1] : null,
+  };
+}
+
+function open(dbPath, { readOnly = false } = {}) {
+  const db = readOnly ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
+  if (!readOnly) db.exec('PRAGMA busy_timeout = 5000;');
+  return db;
+}
+
+/**
+ * 列出提炼条（只读）。
+ * @param {{dbPath:string, keys?:string[], ids?:number[], limit?:number, headChars?:number}} p
+ */
+export function listDistilled({ dbPath, keys = null, ids = null, limit = 0, headChars = 100 }) {
+  const db = open(dbPath, { readOnly: true });
+  try {
+    const rows = db
+      .prepare(`SELECT id, text, tags, updated_at, created_at${hasCol(db, 'owner_user') ? ', owner_user, visibility' : ''} FROM memories WHERE tags LIKE 'distilled%' ORDER BY id`)
+      .all();
+    let items = rows.map((r) => {
+      const meta = parseDistilledTags(r.tags) ?? { srcKey: null, srcIds: [], date: null };
+      return {
+        id: Number(r.id), srcKey: meta.srcKey, srcIds: meta.srcIds, date: meta.date,
+        chars: String(r.text ?? '').length,
+        head: String(r.text ?? '').slice(0, headChars).replace(/\s+/g, ' '),
+        tags: r.tags, createdAt: Number(r.created_at), updatedAt: Number(r.updated_at),
+        ownerUser: r.owner_user ?? null, visibility: r.visibility ?? null,
+      };
+    });
+    if (Array.isArray(keys) && keys.length) {
+      const want = new Set(keys.map((k) => String(k)));
+      items = items.filter((x) => want.has(String(x.srcKey)));
+    }
+    if (Array.isArray(ids) && ids.length) {
+      const want = new Set(ids.map((x) => Number(x)));
+      items = items.filter((x) => want.has(x.id));
+    }
+    if (limit > 0) items = items.slice(0, Number(limit));
+    return items;
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+}
+
+function hasCol(db, name) {
+  return db.prepare('PRAGMA table_info(memories)').all().some((r) => r.name === name);
+}
+
+/**
+ * **内容级摘要**：按 id 排序取 (id, text, tags, pinned, updated_at) 逐行哈希再整体哈希。
+ * 为什么不用文件 sha256：SQLite 写回后页布局会变（同样的内容也可能字节不同），
+ *   文件 sha 无法回答"回滚后库是否回到原状"；内容摘要可以（本卡演练的判据就靠它）。
+ */
+export function contentDigest(dbPath, { excludeTagsLike = null } = {}) {
+  const db = open(dbPath, { readOnly: true });
+  try {
+    const where = excludeTagsLike ? ` WHERE tags NOT LIKE '${excludeTagsLike}'` : '';
+    const rows = db.prepare(`SELECT id, text, tags, pinned, updated_at FROM memories${where} ORDER BY id`).all();
+    const h = crypto.createHash('sha256');
+    for (const r of rows) h.update(`${r.id}\u0001${r.text}\u0001${r.tags}\u0001${r.pinned}\u0001${r.updated_at}\u0002`, 'utf8');
+    return { count: rows.length, digest: h.digest('hex'), allCount: Number(db.prepare('SELECT COUNT(*) n FROM memories').get().n) };
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+}
+
+export function fileSha256(file) {
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 批量回滚。
+ * @param {{dbPath:string, apply?:boolean, keys?:string[], ids?:number[], snapshotDir?:string,
+ *          now?:number, keepSnapshot?:boolean}} p
+ * @returns {{ok:boolean, matched:number, deleted:number, deletedIds:number[], snapshot:string|null,
+ *            before:object, after:object, dryRun:boolean, rollbackFile:string|null}}
+ */
+export function rollbackDistilled(p = {}) {
+  const { dbPath, keys = null, ids = null, snapshotDir = null, now = Date.now(), apply = false } = p;
+  const before = contentDigest(dbPath);
+  const items = listDistilled({ dbPath, keys, ids });
+  const out = {
+    ok: true, dryRun: !apply, matched: items.length, deleted: 0, deletedIds: [],
+    snapshot: null, before, after: before, items: items.map((x) => ({ id: x.id, srcKey: x.srcKey, head: x.head })),
+    rollbackFile: null, warnings: [],
+  };
+  if (!items.length) return out;
+
+  if (!apply) return out;
+
+  // 删除前快照（**唯一回滚点**）
+  const dir = snapshotDir ?? path.join(path.dirname(dbPath), 'snapshots');
+  fs.mkdirSync(dir, { recursive: true });
+  const stamp = new Date(Number(now)).toISOString().replace(/[:.]/g, '-');
+  const snap = path.join(dir, `memory-before-distill-rollback-${stamp}.db`);
+  vacuumInto(dbPath, snap);
+  out.snapshot = snap;
+  out.snapshotSha256 = fileSha256(snap);
+
+  const db = open(dbPath);
+  try {
+    // FTS 同步靠 `memories_ad` 触发器（触发器缺失时 DELETE 不会清 FTS 影子表 ⇒ 显式提示）
+    const triggers = db.prepare("SELECT name FROM sqlite_master WHERE type='trigger' AND tbl_name='memories'").all().map((r) => r.name);
+    out.triggers = triggers;
+    if (!triggers.some((n) => /_ad$|delete/i.test(n))) out.warnings.push('未发现 memories 的 AFTER DELETE 触发器 ⇒ FTS 影子表可能残留（建议核对 memories_fts）');
+
+    const targetIds = items.map((x) => x.id);
+    const stmt = db.prepare(`DELETE FROM memories WHERE id = ? AND tags LIKE 'distilled%'`);
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      for (const id of targetIds) {
+        const r = stmt.run(id);
+        if (Number(r.changes || 0) > 0) out.deletedIds.push(id);
+      }
+      db.exec('COMMIT');
+    } catch (e) {
+      try { db.exec('ROLLBACK'); } catch { /* ignore */ }
+      throw e;
+    }
+    out.deleted = out.deletedIds.length;
+  } finally {
+    try { db.close(); } catch { /* ignore */ }
+  }
+  out.after = contentDigest(dbPath);
+  // 反向回滚脚本（把快照拷回去 = 一键恢复）
+  if (out.snapshot) {
+    const rbFile = path.join(dir, `restore-memory-${stamp}.mjs`);
+    fs.writeFileSync(rbFile, restoreScript({ snapshot: snap, target: dbPath }), 'utf8');
+    out.rollbackFile = rbFile;
+  }
+  return out;
+}
+
+/** 生成"把快照写回目标库"的一键恢复脚本（纯 ASCII 头 + 覆盖前校验存在性）。 */
+function restoreScript({ snapshot, target }) {
+  return `// 自动生成：把提炼回滚前的快照写回目标记忆库（覆盖式）
+// 用法：node ${path.basename('restore-memory.mjs')}  或  node "本文件路径"
+import fs from 'node:fs';
+const SNAP = ${JSON.stringify(snapshot)};
+const TARGET = ${JSON.stringify(target)};
+if (!fs.existsSync(SNAP)) { console.error('快照不存在：' + SNAP); process.exit(3); }
+for (const suffix of ['', '-wal', '-shm']) {
+  const f = TARGET + suffix;
+  try { if (fs.existsSync(f)) fs.copyFileSync(f, f + '.before-restore'); } catch { /* ignore */ }
+}
+fs.copyFileSync(SNAP, TARGET);
+for (const suffix of ['-wal', '-shm']) { try { fs.rmSync(TARGET + suffix, { force: true }); } catch { /* ignore */ } }
+console.log('已恢复：' + TARGET + ' <- ' + SNAP);
+`;
+}