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

package/memory-db-tools/refine-memories.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * refine-memories.mjs —— 记忆库「按 payload 逐条改写」通用写入入口（先 dry-run，--apply 才写）
+ *
+ * 与既有一次性大扫除脚本的关系：
+ *   · 后者是 **2026-09-15 长期库大扫除 L4 那次的一次性脚本** —— 它的 `validate()` 内置
+ *     `IDS_EXPECTED = [17 个固定 id]` 覆盖度自检（"载荷必须恰好是那 17 条"）⇒ **新 payload 必被 fail-closed 拒**，
+ *     不可复用（2026-09-24 实测：新载荷报「载荷缺条目 / 含计划外条目」）。
+ *   · 本脚本 = 同一套安全骨架（单事务 / 逐条校验 / 改前全文留档 / 可回滚），**去掉硬编码 id 清单**，
+ *     改为「payload 声明什么就改什么」；其余纪律一致。**未改动旧脚本一个字节。**
+ *
+ * 安全纪律（与旧脚本同）：
+ *   · 只 UPDATE memories.text（按 id 逐条），**不碰 pinned / tags / created_at**，不插入、不删除；
+ *   · 单事务：任一条校验失败 ⇒ 整体不执行；
+ *   · 校验：id 必须真实存在 · text 非空 · `must_contain` 逐条字面命中 · `forbid` 正则不得命中 · 载荷无重复 id；
+ *   · 报告含**改前全文**（供回滚），默认落 `_archive`；`--rollback <报告>` 可逐条写回。
+ *
+ * 用法：
+ *   node refine-memories.mjs --payload <f>                      # dry-run（默认）
+ *   node refine-memories.mjs --payload <f> --apply              # 真写（单事务）
+ *   node refine-memories.mjs --payload <f> --self-test          # 在临时库副本上跑完整通路 + 反校验
+ *   node refine-memories.mjs --rollback <报告.json>             # 按报告把改前全文写回
+ *   （可选 --db <库> --report <报告>；默认见常量）
+ * 退出码：0 正常 ／ 1 校验或执行失败 ／ 2 用法错 ／ 3 环境不可用
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+const HOME = (process.env.USERPROFILE ?? '').replaceAll('\\', '/');
+const DEF_DB = `${HOME}/.dsh/memory/memory.db`;
+const DEF_REPORT = path.join(process.cwd(), '_archive', 'memory-refine', 'refine-report.json');
+
+function argOf(argv, name, def) {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : def;
+}
+function realOr(p) {
+  try { return fs.realpathSync.native(p); } catch { return path.resolve(p); }
+}
+function mainEntry() {
+  const a1 = process.argv[1] ? realOr(process.argv[1]) : '';
+  const a2 = realOr(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
+  return a1.toLowerCase() === a2.toLowerCase();
+}
+
+/** 逐条校验；返回 {ok, errors, rows} */
+function validate(db, payload) {
+  const errors = [];
+  const rows = [];
+  const seen = new Set();
+  for (const e of payload.entries ?? []) {
+    if (!Number.isInteger(e.id) || typeof e.text !== 'string' || !e.text.trim()) {
+      errors.push(`#${e.id} 载荷形态非法（id 需整数、text 需非空字符串）`);
+      continue;
+    }
+    if (seen.has(e.id)) { errors.push(`#${e.id} 载荷内重复 id`); continue; }
+    seen.add(e.id);
+    const cur = db.prepare('SELECT text, pinned FROM memories WHERE id=?').get(e.id);
+    if (!cur) { errors.push(`#${e.id} 库中不存在（拒绝凭空插入）`); continue; }
+    for (const need of e.must_contain ?? []) {
+      if (!e.text.includes(need)) errors.push(`#${e.id} 新正文未命中必需关键词「${need}」`);
+    }
+    for (const pat of e.forbid ?? []) {
+      const hit = e.text.match(new RegExp(pat, 'g'));
+      if (hit) errors.push(`#${e.id} 新正文命中禁串正则 /${pat}/ → ${hit.slice(0, 2).join(' | ')}`);
+    }
+    rows.push({ id: e.id, oldLen: cur.text.length, newLen: e.text.length, pinned: cur.pinned });
+  }
+  if (!rows.length && !errors.length) errors.push('载荷为空');
+  return { ok: errors.length === 0, errors, rows };
+}
+
+function selfTest(payload, srcDb) {
+  console.log('=== self-test：在临时库副本上跑完整 UPDATE 通路（不碰生产库）===');
+  const tmp = path.join(os.tmpdir(), `mem-refine-selftest-${Date.now()}.db`);
+  try {
+    const src = new DatabaseSync(srcDb, { readOnly: true });
+    src.exec(`VACUUM INTO '${tmp.replaceAll("'", "''")}'`);
+    src.close();
+    const t = new DatabaseSync(tmp);
+    const v = validate(t, payload);
+    if (!v.ok) { console.error(`  ✗ 校验未过：\n    ${v.errors.join('\n    ')}`); t.close(); return false; }
+    t.exec('BEGIN');
+    const ts = Date.now();
+    const up = t.prepare('UPDATE memories SET text=?, updated_at=? WHERE id=?');
+    for (const e of payload.entries) up.run(e.text, ts, e.id);
+    t.exec('COMMIT');
+    let bad = 0;
+    for (const e of payload.entries) {
+      const after = t.prepare('SELECT text FROM memories WHERE id=?').get(e.id).text;
+      if (after !== e.text) { console.error(`  ✗ #${e.id} 写回不一致`); bad++; }
+    }
+    const nAll = t.prepare('SELECT COUNT(*) n FROM memories').get().n;
+    const nSrc = (() => { const d = new DatabaseSync(srcDb, { readOnly: true }); const n = d.prepare('SELECT COUNT(*) n FROM memories').get().n; d.close(); return n; })();
+    t.close();
+    const ok = bad === 0 && nAll === nSrc;
+    console.log(`  ${payload.entries.length} 条 UPDATE → 条数 ${nAll}（源 ${nSrc}）· 逐条比对不一致 ${bad} 处 ${ok ? '✅ 通路正常' : '✗'}`);
+    return ok;
+  } catch (e) {
+    console.error(`  ✗ self-test 失败：${e.message}`);
+    return false;
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* 忽略 */ }
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help')) {
+    console.log('用法: node refine-memories.mjs --payload <f> [--apply|--self-test] [--db <库>] [--report <报告>]');
+    console.log('      node refine-memories.mjs --rollback <报告.json>');
+    return;
+  }
+  const dbPath = argOf(argv, '--db', DEF_DB);
+  const reportPath = argOf(argv, '--report', DEF_REPORT);
+
+  // ---- 回滚分支
+  const rbi = argv.indexOf('--rollback');
+  if (rbi >= 0) {
+    const rep = argv[rbi + 1];
+    if (!rep || !fs.existsSync(rep)) { console.error(`[rollback] 报告不存在：${rep}`); process.exitCode = 2; return; }
+    const r = JSON.parse(fs.readFileSync(rep, 'utf8'));
+    const before = r.before ?? {};
+    const beforePinned = r.beforePinned ?? {};
+    const ids = Object.keys(before).map(Number);
+    const pinIds = Object.keys(beforePinned).map(Number);
+    if (!ids.length && !pinIds.length) { console.error('[rollback] 报告既无 before 也无 beforePinned 段'); process.exitCode = 1; return; }
+    const db = new DatabaseSync(dbPath);
+    db.exec('BEGIN');
+    try {
+      let n = 0;
+      if (ids.length) {
+        const up = db.prepare('UPDATE memories SET text=?, updated_at=? WHERE id=?');
+        for (const id of ids) { const c = up.run(before[id], Date.now(), id); if (c.changes !== 1) throw new Error(`#${id} 回写影响行数 ${c.changes}`); n++; }
+      }
+      if (pinIds.length) {
+        const up = db.prepare('UPDATE memories SET pinned=?, updated_at=? WHERE id=?');
+        for (const id of pinIds) { const c = up.run(beforePinned[id], Date.now(), id); if (c.changes !== 1) throw new Error(`#${id} pinned 回写影响行数 ${c.changes}`); n++; }
+      }
+      db.exec('COMMIT');
+      console.log(`[rollback] 已写回 ${n} 条（text ${ids.length} · pinned ${pinIds.length}）`);
+    } catch (e) { db.exec('ROLLBACK'); console.error(`[rollback] 失败已回滚：${e.message}`); process.exitCode = 1; }
+    db.close();
+    return;
+  }
+
+  // ---- unpin 分支：把指定 id 的 pinned 置 0（**内容保留**，只减注入量）
+  const upi = argv.indexOf('--unpin');
+  if (upi >= 0) {
+    const ids = String(argv[upi + 1] ?? '').split(',').map((s) => Number(s.trim())).filter(Number.isInteger);
+    if (!ids.length) { console.error('[unpin] 需要 --unpin <id,id,...>'); process.exitCode = 2; return; }
+    const db = new DatabaseSync(dbPath);
+    const rows = ids.map((id) => {
+      const r = db.prepare('SELECT id, pinned, LENGTH(text) AS len FROM memories WHERE id=?').get(id);
+      return { id, exists: !!r, pinned: r?.pinned ?? null, len: r?.len ?? null };
+    });
+    const missing = rows.filter((r) => !r.exists).map((r) => r.id);
+    const pinnedNow = db.prepare('SELECT COUNT(*) n FROM memories WHERE pinned=1').get().n;
+    console.log(`[unpin] 目标 ${ids.length} 条 · 缺失 ${missing.length} · 当前 pinned 总数 ${pinnedNow}`);
+    for (const r of rows) console.log(`  #${r.id}  pinned=${r.pinned}  ${r.len} 字符`);
+    if (missing.length) { console.error(`[fail-closed] 以下 id 不存在：${missing.join(',')}`); db.close(); process.exitCode = 1; return; }
+    if (!argv.includes('--apply')) { db.close(); console.log('[unpin] dry-run 未写库；加 --apply 执行'); return; }
+    const beforePinned = {};
+    db.exec('BEGIN');
+    try {
+      const up = db.prepare('UPDATE memories SET pinned=0, updated_at=? WHERE id=?');
+      let n = 0;
+      for (const r of rows) {
+        beforePinned[r.id] = r.pinned;
+        const c = up.run(Date.now(), r.id);
+        if (c.changes !== 1) throw new Error(`#${r.id} 影响行数=${c.changes}`);
+        n++;
+      }
+      db.exec('COMMIT');
+      const np = db.prepare('SELECT COUNT(*) n FROM memories WHERE pinned=1').get().n;
+      console.log(`\n✅ 已降级 ${n} 条 → 现 pinned 条数 = ${np}`);
+      fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+      fs.writeFileSync(reportPath, JSON.stringify({
+        at: new Date().toISOString(), session: process.env.DSH_SESSION_ID ?? null, dbPath,
+        unpinned: Object.keys(beforePinned).map(Number), beforePinned, pinnedAfter: np,
+      }, null, 2) + '\n', 'utf8');
+      console.log(`留档：${reportPath}\n回滚：node refine-memories.mjs --rollback "${reportPath}"`);
+    } catch (e) { db.exec('ROLLBACK'); console.error(`✗ 事务失败已回滚：${e.message}`); process.exitCode = 1; }
+    db.close();
+    return;
+  }
+
+  const payloadPath = argOf(argv, '--payload', null);
+  if (!payloadPath || !fs.existsSync(payloadPath)) { console.error(`[fail-closed] 找不到载荷 ${payloadPath}`); process.exitCode = 3; return; }
+  if (!fs.existsSync(dbPath)) { console.error(`[fail-closed] 找不到记忆库 ${dbPath}`); process.exitCode = 3; return; }
+
+  const payload = JSON.parse(fs.readFileSync(payloadPath, 'utf8'));
+  console.log(`载荷：${payloadPath}（${(payload.entries ?? []).length} 条）\n目标库：${dbPath}`);
+
+  if (argv.includes('--self-test')) {
+    process.exitCode = selfTest(payload, dbPath) ? 0 : 1;
+    return;
+  }
+
+  const db = new DatabaseSync(dbPath);
+  const v = validate(db, payload);
+  console.log(`\n校验：${v.ok ? '✅ 全通过' : `✗ ${v.errors.length} 项不通过`}`);
+  for (const e of v.errors) console.log(`  ✗ ${e}`);
+  console.log('\n逐条明细（id · 改前→改后字符数 · pinned）：');
+  for (const r of v.rows) console.log(`  #${String(r.id).padStart(4)}  ${r.oldLen} → ${r.newLen} 字符  pinned=${r.pinned}`);
+
+  if (!v.ok) { db.close(); process.exitCode = 1; return; }
+  if (!argv.includes('--apply')) {
+    db.close();
+    console.log('\n（dry-run：未写库；加 --apply 执行改写）');
+    return;
+  }
+
+  const stamp = Date.now();
+  db.exec('BEGIN');
+  try {
+    const up = db.prepare('UPDATE memories SET text=?, updated_at=? WHERE id=?');
+    const rd = db.prepare('SELECT text FROM memories WHERE id=?');
+    const before = {};
+    for (const e of payload.entries) before[e.id] = rd.get(e.id).text;
+    let n = 0;
+    for (const e of payload.entries) {
+      const r = up.run(e.text, stamp, e.id);
+      if (r.changes !== 1) throw new Error(`#${e.id} UPDATE 影响行数=${r.changes}（期望 1）`);
+      n++;
+    }
+    db.exec('COMMIT');
+    const after = db.prepare('SELECT COUNT(*) n, SUM(LENGTH(text)) c FROM memories').get();
+    console.log(`\n✅ 已改写 ${n} 条 → 库内 ${after.n} 条 / ${after.c} 字符`);
+    fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+    fs.writeFileSync(reportPath, JSON.stringify({
+      at: new Date().toISOString(), session: process.env.DSH_SESSION_ID ?? null,
+      payloadPath, dbPath, updated: n, totalAfter: after.n, charsAfter: after.c, before,
+    }, null, 2) + '\n', 'utf8');
+    console.log(`改前全文留档（供回滚）：${reportPath}`);
+    console.log(`回滚：node refine-memories.mjs --rollback "${reportPath}"`);
+  } catch (err) {
+    db.exec('ROLLBACK');
+    console.error(`✗ 事务失败已回滚：${err.message}`);
+    process.exitCode = 1;
+  }
+  db.close();
+}
+
+if (mainEntry()) main();

package/memory-db-tools/show-mem-times.mjs

@@ -0,0 +1,22 @@
+import { DatabaseSync } from "node:sqlite";
+
+// 只读列出全部记忆的 id / 创建时间 / 更新时间 / 标题（毫秒 epoch 已转本地时间）。
+// 用法：node show-mem-times.mjs [id ...]   （不给 id 则列全部；dsh 运行中也可安全执行）
+const db = new DatabaseSync(`${process.env.USERPROFILE.replaceAll("\\", "/")}/.dsh/memory/memory.db`, { readOnly: true });
+const fmt = ms => new Date(ms).toLocaleString("zh-CN", { hour12: false, timeZone: "Asia/Shanghai" });
+
+const args = process.argv.slice(2);
+let rows;
+if (args.length === 0) {
+  rows = db.prepare("SELECT id, created_at, updated_at, text, pinned FROM memories ORDER BY id").all();
+} else {
+  const ids = args.map(Number).filter(Number.isInteger);
+  if (!ids.length) { console.error("用法：node show-mem-times.mjs <id> [id ...]（不给 id 列全部）"); process.exit(1); }
+  const ph = ids.map(() => "?").join(",");
+  rows = db.prepare(`SELECT id, created_at, updated_at, text, pinned FROM memories WHERE id IN (${ph}) ORDER BY id`).all(...ids);
+}
+for (const r of rows) {
+  const firstLine = r.text.split("\n")[0].slice(0, 60);
+  console.log(`#${String(r.id).padStart(3)} [${r.pinned === 1 ? "pin" : "  -"}] 创建 ${fmt(r.created_at)}  更新 ${fmt(r.updated_at)}  ${firstLine}`);
+}
+db.close();

package/memory-engine/README.md

@@ -0,0 +1,70 @@
+# 记忆引擎 v2 · 离线层（S1）
+
+> 定位：DSH 生态的**离线记忆层**（向量库 / 增量同步 / 召回 / 自检 / 编码桥），可独立运行。
+> 落点：向量库默认 `~/.dsh/memory-vectors/`；依赖自带于本目录，**绝不装进宿主的 `profiles/node_modules`**。
+
+## 这是什么
+
+记忆引擎 v2 的**离线层**（不含 S2 注入插件）：
+
+| 能力 | 实现 | 方案条款 |
+|---|---|---|
+| 独立向量库 | `vectors` 表 + `meta` 表（schemaVersion / hostId / modelId / dim / lastIncrementalSyncAt / lastFullHashSweepAt） | §3.1 |
+| 增量同步 | 按 `updated_at ≥ 水位` 只读扫 `memory.db`，批 50，失败保留进度可续跑；换模型/维度自动全量重建 | §3.1 |
+| 兜底校验 | 每周按 id 段轮转做全表 `text_hash` 校验（治「改 text 不动 updated_at」的外部写口，A7） | §3.1 / §6.2 |
+| 召回 | 向量余弦 top-20 为主 + FTS5 仅补标签/英文/数字 + RRF(k=60) 融合 + **排除 pinned**；非空即触发，纯符号/单字跳过 | §3.3 |
+| 启动自检 | 模型可用性 / 维度一致 / 表存在性（缺则重建）/ hostId 校验 | §8.3 #9 |
+| 编码桥 | `serve.mjs`，**仅绑 127.0.0.1:8201**，`GET /health` + `POST /encode` | §3.1 编码通道契约 |
+
+## 目录
+
+```
+memory-engine/
+├─ serve.mjs            编码桥（回环 HTTP，模型常驻）
+├─ cli/                 sync.mjs · sweep.mjs · recall.mjs · selfcheck.mjs
+├─ lib/                 config / vectors-store / memory-source / embedder / sync / sweep / recall / selfcheck / cli-util / hashes
+├─ tools/fetch-model.mjs  模型权重获取器（node fetch，绕开 Windows curl 的 schannel 坑）
+├─ test/                单测（夹具全部落系统临时目录）+ run.mjs
+└─ bench/bench.mjs      V1 / V2 基准（方案 §9）
+```
+
+## 常用命令
+
+```powershell
+# 一次性：取权重（fp32 90MB / int8 约 25MB）
+node tools\fetch-model.mjs --out <模型目录> --variant fp32
+
+# 启动自检
+node cli\selfcheck.mjs [--json]
+
+# 编码桥幂等启动（S2c）：探活优先（在跑就跳过），不在跑才 detached 拉起；
+# 端口 8201 被占 +1 顺延，真实端口按子进程 pid 定位后落 bridge-port.json
+node cli\serve-start.mjs [--port 8201] [--port-file <台账路径>] [--no-start] [--json]
+#   退出码：0 已在跑 / 拉起就绪 · 1 拉起失败 · 3 --no-start 且桥不在（让路）· 2 用法错
+
+# 增量同步 / 全量重建（--memory-db 必须指向记忆库副本，勿指生产库）
+node cli\sync.mjs --memory-db <副本> [--full] [--dry-run]
+
+# 兜底 hash 轮转：每次 1 段，--all 一轮完整覆盖
+node cli\sweep.mjs --memory-db <副本> [--rounds N | --all]
+
+# 召回（人工查验用）
+node cli\recall.mjs --query "退下吧" --json
+
+# 基准（写报告）
+node bench\bench.mjs --memory-db <副本> --out bench-report.json
+```
+
+## 边界（硬约束）
+
+1. **对 `memory.db` 只读**——所有打开方式都是 `new DatabaseSync(path, { readOnly: true })`，同步只写独立向量库。
+2. **向量库不进任何同步仓**：默认落 `~/.dsh/memory-vectors/`，在仓1 采集白名单之外（方案 D3 的机制收益）。
+3. **模型权重不进同步仓**：放中枢机本地目录（`MEMORY_ENGINE_MODEL_DIR` 可覆盖），两机各下一份。
+4. **依赖不污染闭包**：`node_modules` 只在本目录，绝不装进 `profiles\node_modules`（生态铁律）。
+5. 一切路径可注入：`--memory-db / --vectors-db / --model-dir`，或环境变量 `MEMORY_ENGINE_*`；**测试一律落临时目录**。
+
+## 已知坑（实测）
+
+- **Windows curl 取不到 HF 大文件**：HF 的 LFS 文件 302 到 Xet CAS 桥（`cas-bridge.xethub.hf.co`），部分 Windows 主机上 schannel 握手失败（`curl: (35) SEC_E_ILLEGAL_MESSAGE`）。用 `tools/fetch-model.mjs`（node 自带 TLS 栈）下载，别用 curl。
+- **`memory-source.close()` 幂等**：调用方常在 `finally` 里再关一次，重复 `db.close()` 会抛 `database is not open`——已做幂等保护。
+- **入口守卫必须 realpath**：工作区里常有目录 junction，`import.meta.url` 解析为物理路径而 `process.argv[1]` 是逻辑路径，直接字符串比较会让脚本静默退出 0（`lib/cli-util.mjs` 的 `isMainEntry`）。

package/memory-engine/bench/bench.mjs

@@ -0,0 +1,221 @@
+// 记忆引擎 v2 · 离线层 —— 基准（方案 §9 V1 / V2，判据只认真机实测）
+//
+// V1：① 单句编码延迟  ② 全量记忆条编码耗时（首次全量 / 重建成本）
+// V2：100 次召回（含 query 编码 + 余弦 + FTS 补位 + RRF 融合）对照 §3.4 的 300ms 硬预算
+//
+// 用法（数据源必须是记忆库副本，绝不直连在用库）：
+//   node bench/bench.mjs --memory-db <记忆库副本路径>
+//        [--vectors-db <path>] [--model-dir <dir>] [--iterations 100] [--json] [--out report.json]
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseArgs, isMainEntry } from '../lib/cli-util.mjs';
+import { resolveConfig } from '../lib/config.mjs';
+import { openVectorsStore, countVectors } from '../lib/vectors-store.mjs';
+import { openMemorySource } from '../lib/memory-source.mjs';
+import { createLocalEmbedder } from '../lib/embedder.mjs';
+import { runIncrementalSync } from '../lib/sync.mjs';
+import { recall, buildVectorIndex, shouldTrigger } from '../lib/recall.mjs';
+import { runSelfcheck } from '../lib/selfcheck.mjs';
+
+const SHORT_QUERIES = ['退下吧', '整夜干活', '去深水区', '落卡', '回浅水区'];
+
+function stats(samples) {
+  const a = [...samples].sort((x, y) => x - y);
+  const at = (p) => a[Math.min(a.length - 1, Math.floor((p / 100) * a.length))];
+  const mean = a.reduce((s, v) => s + v, 0) / (a.length || 1);
+  return {
+    n: a.length,
+    min: +a[0].toFixed(2),
+    p50: +at(50).toFixed(2),
+    p95: +at(95).toFixed(2),
+    max: +a[a.length - 1].toFixed(2),
+    mean: +mean.toFixed(2),
+  };
+}
+
+export async function runBench({ config, iterations = 100, log = console.log, doSync = true }) {
+  const report = {
+    at: new Date().toISOString(),
+    host: os.hostname(),
+    platform: `${process.platform} ${os.arch()}`,
+    node: process.version,
+    cpu: (os.cpus()[0] || {}).model || 'unknown',
+    cpuCount: os.cpus().length,
+    totalMemGB: +(os.totalmem() / 1024 ** 3).toFixed(1),
+    config: {
+      memoryDb: config.memoryDb,
+      vectorsDb: config.vectorsDb,
+      modelId: config.modelId,
+      modelDir: config.modelDir,
+    },
+    v1: {},
+    v2: {},
+    selfcheck: null,
+  };
+
+  // 冷启动：模型加载计时
+  const tLoad0 = performance.now();
+  const embedder = await createLocalEmbedder({
+    modelDir: config.modelDir,
+    modelId: config.modelId,
+    dim: config.dim,
+    quantized: Boolean(config.quantized),
+  });
+  report.v1.modelLoadMs = +(performance.now() - tLoad0).toFixed(1);
+  report.v1.dim = embedder.dim;
+  report.v1.embedder = embedder.describe();
+  log(`[V1] 模型加载（冷启动）：${report.v1.modelLoadMs} ms · dim=${embedder.dim} · ${JSON.stringify(embedder.describe())}`);
+
+  const store = openVectorsStore(config.vectorsDb);
+  store.hostId = config.hostId;
+  const source = openMemorySource(config.memoryDb);
+  const total = source.count();
+  report.v1.memoryRows = total;
+
+  // ① 全量编码计时（逐条，含批 50 的同步写库）
+  let syncStats = null;
+  if (doSync) {
+    const tFull0 = performance.now();
+    syncStats = await runIncrementalSync({
+      source,
+      store,
+      embedder,
+      modelId: config.modelId,
+      dim: config.dim,
+      batchSize: config.batchSize,
+      full: true,
+      log: () => {},
+    });
+    const fullMs = performance.now() - tFull0;
+    report.v1.fullEncode = {
+      rows: syncStats.encoded,
+      batches: syncStats.batches,
+      totalMs: +fullMs.toFixed(1),
+      perItemMs: +(fullMs / Math.max(1, syncStats.encoded)).toFixed(2),
+      error: syncStats.error || null,
+    };
+    log(
+      `[V1] 全量编码 ${syncStats.encoded} 条：${fullMs.toFixed(0)} ms（${(fullMs / Math.max(1, syncStats.encoded)).toFixed(2)} ms/条，${syncStats.batches} 批）`,
+    );
+  } else {
+    report.v1.fullEncode = { rows: countVectors(store.db, 'memory'), skipped: true };
+    log('[V1] 跳过全量编码（--no-sync）');
+  }
+
+  // ② 单句编码计时
+  const singleSamples = [];
+  const probeText = '跨机同步的挡推裁决口径与三仓推送顺序';
+  for (let i = 0; i < iterations; i += 1) {
+    const t0 = performance.now();
+    await embedder.encode(probeText);
+    singleSamples.push(performance.now() - t0);
+  }
+  report.v1.singleEncode = stats(singleSamples);
+  log(`[V1] 单句编码 ${iterations} 次：P50 ${report.v1.singleEncode.p50} ms / P95 ${report.v1.singleEncode.p95} ms`);
+
+  // ③ 长句编码（记忆条均长 740 字）
+  const longRows = source.incrementalPage(0, 0, 20);
+  const longText = longRows.map((r) => r.text).join('\n').slice(0, 2000) || probeText.repeat(20);
+  const longSamples = [];
+  for (let i = 0; i < Math.min(30, iterations); i += 1) {
+    const t0 = performance.now();
+    await embedder.encode(longText);
+    longSamples.push(performance.now() - t0);
+  }
+  report.v1.longEncode = { chars: longText.length, ...stats(longSamples) };
+  log(
+    `[V1] 长文本（${longText.length} 字）编码 ${longSamples.length} 次：P50 ${report.v1.longEncode.p50} ms / P95 ${report.v1.longEncode.p95} ms`,
+  );
+
+  // V2：召回计时
+  const index = buildVectorIndex(store.db, { source: 'memory' });
+  report.v2.indexSize = index.count;
+  const idx = { source: 'memory', model: config.modelId };
+  void idx;
+  const queries = [];
+  const seed = source.incrementalPage(0, 0, Math.min(10, total)) || [];
+  for (const r of seed) queries.push(String(r.text).slice(0, 40));
+  queries.push(...SHORT_QUERIES);
+  const fireable = queries.filter((q) => shouldTrigger(q).trigger);
+  report.v2.querySet = { count: fireable.length, samples: fireable.slice(0, 5) };
+
+  const recallSamples = [];
+  const parts = { encodeMs: [], vectorMs: [], ftsMs: [], fuseMs: [] };
+  const qStats = new Map();
+  for (let i = 0; i < iterations; i += 1) {
+    const q = fireable[i % fireable.length];
+    const r = await recall({ query: q, store, source, embedder, index, resultTopK: config.resultTopK });
+    recallSamples.push(r.timings.totalMs);
+    parts.encodeMs.push(r.timings.encodeMs);
+    parts.vectorMs.push(r.timings.vectorMs);
+    parts.ftsMs.push(r.timings.ftsMs);
+    parts.fuseMs.push(r.timings.fuseMs);
+    const cur = qStats.get(q) || [];
+    cur.push(r.timings.totalMs);
+    qStats.set(q, cur);
+  }
+  report.v2.recall = stats(recallSamples);
+  report.v2.budgetMs = 300;
+  report.v2.verdict = report.v2.recall.p95 <= 300 ? 'PASS' : 'FAIL';
+  report.v2.breakdown = {
+    encode: stats(parts.encodeMs),
+    vector: stats(parts.vectorMs),
+    fts: stats(parts.ftsMs),
+    fuse: stats(parts.fuseMs),
+  };
+  report.v2.perQuery = [...qStats.entries()].map(([q, v]) => ({ query: q, ...stats(v) }));
+  log(
+    `[V2] 召回 ${iterations} 次：P50 ${report.v2.recall.p50} ms / P95 ${report.v2.recall.p95} ms / max ${report.v2.recall.max} ms（预算 ${report.v2.budgetMs} ms ⇒ ${report.v2.verdict}）`,
+  );
+  log(
+    `     分解 P50：编码 ${report.v2.breakdown.encode.p50} · 向量 ${report.v2.breakdown.vector.p50} · FTS ${report.v2.breakdown.fts.p50} · 融合 ${report.v2.breakdown.fuse.p50} ms`,
+  );
+
+  // 顺带跑一次启动自检（交付物 #9 的现场证据）
+  report.selfcheck = await runSelfcheck({ store, source, embedder, config });
+  log(`[自检] ${report.selfcheck.ok ? '✅ 通过' : '❌ 失败'}（warn ${report.selfcheck.warned} / fail ${report.selfcheck.failed}）`);
+
+  source.close();
+  store.db.close();
+  return report;
+}
+
+async function main() {
+  const { flags } = parseArgs();
+  const config = resolveConfig({
+    memoryDb: flags['memory-db'] || undefined,
+    vectorsDb: flags['vectors-db'] || undefined,
+    vectorsDir: flags['vectors-dir'] || 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,
+  });
+  if (!fs.existsSync(config.memoryDb)) {
+    throw new Error(`记忆库不存在：${config.memoryDb}（本卡须用 ROG 生产库的只读副本，勿指向生产库）`);
+  }
+  console.log('=== 记忆引擎 v2 · 离线层基准 ===');
+  console.log(`主机     : ${os.hostname()} · ${os.cpus().length} 核 ${(os.cpus()[0] || {}).model}`);
+  console.log(`内存     : ${(os.totalmem() / 1024 ** 3).toFixed(1)} GB · node ${process.version}`);
+  console.log(`记忆库   : ${config.memoryDb}`);
+  console.log(`向量库   : ${config.vectorsDb}`);
+  console.log(`模型目录 : ${config.modelDir}`);
+  console.log('');
+  const report = await runBench({
+    config,
+    iterations: Number(flags.iterations || 100),
+    log: (m) => console.log(m),
+    doSync: !flags['no-sync'],
+  });
+  if (flags.out) {
+    fs.mkdirSync(path.dirname(path.resolve(flags.out)), { recursive: true });
+    fs.writeFileSync(path.resolve(flags.out), JSON.stringify(report, null, 2), 'utf8');
+    console.log(`\n报告已写入：${path.resolve(flags.out)}`);
+  }
+  if (flags.json) process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  process.exitCode = report.v2.verdict === 'PASS' || flags['allow-slow'] ? 0 : 3;
+}
+
+if (isMainEntry(import.meta.url)) await main();

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// 记忆引擎 v2 · S3c —— 提炼产物回滚 CLI（`cli/distill-rollback.mjs`）
+//
+// 用法：
+//   node cli/distill-rollback.mjs --db <memory.db>                 # **默认 dry-run**：只列出会被删的条
+//   node cli/distill-rollback.mjs --db <memory.db> --apply         # 真删（先 VACUUM INTO 快照 + 生成一键恢复脚本）
+//   node cli/distill-rollback.mjs --db <memory.db> --key <srcKey>  # 只回滚某一组
+//   node cli/distill-rollback.mjs --db <memory.db> --id 1001 --apply
+//   node cli/distill-rollback.mjs --db <memory.db> --digest        # 只算内容摘要（演练对照用）
+//
+// 判据：`tags LIKE 'distilled%'`（回滚面就是这个前缀——提炼产物唯一性标记）
+// 退出码：0 = 正常 / 1 = 失败 / 2 = 用法错 / 3 = 环境不可用
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMainEntry, parseArgs, makeLogger, num } from '../lib/cli-util.mjs';
+import { listDistilled, rollbackDistilled, contentDigest, fileSha256 } from '../lib/distill-rollback.mjs';
+
+const USAGE = 'node cli/distill-rollback.mjs --db <memory.db> [--apply] [--key <srcKey>]... [--id <id>]... '
+  + '[--snapshot-dir <dir>] [--limit N] [--digest [--real-only]] [--show N] [--json] [--help]';
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  if (flags.help) { process.stdout.write(`用法：${USAGE}\n`); return 0; }
+
+  const dbPath = flags.db ? path.resolve(String(flags.db)) : null;
+  if (!dbPath) { process.stderr.write('用法错：必须给 --db <库路径>\n'); return 2; }
+  if (!fs.existsSync(dbPath)) { process.stderr.write(`环境不可用：库不存在 ${dbPath}\n`); return 3; }
+
+  const collect = (v) => (v === undefined ? [] : String(v).split(',').map((x) => x.trim()).filter(Boolean));
+  const keys = collect(flags.key);
+  const ids = collect(flags.id).map((x) => Number(x)).filter((x) => Number.isFinite(x));
+
+  if (flags.digest) {
+    // `--real-only`：只算**真实（非派生）条**的内容摘要 —— 演练判据要的是「回滚后真实条一个字节没变」
+    //   （整表摘要会把被删掉的提炼条也算进去 ⇒ 对比必然"不一致"，那是判据写错、不是回滚失败）
+    const exclude = flags['real-only'] ? 'distilled%' : null;
+    const d = contentDigest(dbPath, { excludeTagsLike: exclude });
+    const out = { db: dbPath, realOnly: Boolean(exclude), ...d, fileSha256: fileSha256(dbPath) };
+    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    else log(`${exclude ? '真实条' : '整表'}内容摘要：条数 ${d.count} · digest ${d.digest} · 全表条数 ${d.allCount} · 文件 sha ${out.fileSha256}`);
+    return 0;
+  }
+
+  const apply = Boolean(flags.apply);
+  const before = contentDigest(dbPath);
+  const items = listDistilled({ dbPath, keys: keys.length ? keys : null, ids: ids.length ? ids : null, limit: num(flags.limit, 0) });
+
+  log(`库      : ${dbPath}`);
+  log(`模式    : ${apply ? 'APPLY（真删）' : 'DRY-RUN（只列不删）'}`);
+  log(`库现状  : 全表 ${before.allCount} 条（其中提炼条 ${before.allCount - before.count} 条）· 内容摘要 ${before.digest}`);
+  log(`命中筛选: ${items.length} 条（--key ${keys.length ? keys.join(',') : '-'} / --id ${ids.length ? ids.join(',') : '-'}）`);
+  for (const it of items.slice(0, Number(flags.show ?? 50))) log(`  #${it.id} src=${it.srcKey} date=${it.date} ${it.chars} 字 · ${it.head.slice(0, 70)}`);
+
+  if (!items.length) {
+    if (json) process.stdout.write(JSON.stringify({ ok: true, matched: 0, deleted: 0, before }, null, 2) + '\n');
+    return 0;
+  }
+  if (!apply) {
+    log('（dry-run：未删除任何东西；加 --apply 才真删，删除前会自动 VACUUM INTO 快照）');
+    if (json) process.stdout.write(JSON.stringify({ ok: true, dryRun: true, matched: items.length, ids: items.map((x) => x.id), before }, null, 2) + '\n');
+    return 0;
+  }
+
+  const r = rollbackDistilled({
+    dbPath, apply: true, keys: keys.length ? keys : null, ids: ids.length ? ids : null,
+    snapshotDir: flags['snapshot-dir'] ? path.resolve(String(flags['snapshot-dir'])) : null,
+  });
+  log(`已删除  : ${r.deleted} 条（id ${r.deletedIds.join(',')}）`);
+  log(`删除前快照: ${r.snapshot}${r.snapshotSha256 ? ` · sha ${r.snapshotSha256}` : ''}`);
+  log(`一键恢复: ${r.rollbackFile}`);
+  log(`回滚后  : 全表 ${r.after.allCount} 条 · 内容摘要 ${r.after.digest}${r.after.digest === before.digest ? ' ✅ 与删除前一致' : ' ⚠️ 与删除前不一致'}`);
+  for (const w of r.warnings ?? []) log(`⚠️ ${w}`);
+  if (json) process.stdout.write(JSON.stringify({ ok: true, ...r, fileSha256: fileSha256(dbPath) }, null, 2) + '\n');
+  return 0;
+}
+
+if (isMainEntry(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; }).catch((e) => {
+    console.error(`未捕获异常：${e && e.stack ? e.stack : e}`);
+    process.exitCode = 1;
+  });
+}
+
+export { main };