@kira905/dsh-memory-toolkit 0.1.2 → 0.2.0

package/memory-engine/tools/bridge-smoke.mjs

@@ -1,78 +1,117 @@
-// 记忆引擎 v2 · 离线层 —— 编码桥实测（方案 §3.1 编码通道契约）
+// 记忆引擎 · 离线层 —— 编码桥联调（编码通道契约）
 //
-// 同进程内起桥 → 打 /health 与 /encode → 校验端口顺延 → 关桥。
-// 为什么不走 ssh 后台进程：SSH 会话结束会带走 detached 进程（跨机技能坑 3），
-// 起与测必须同一条命令；本脚本把「起 + 测 + 关」放进同一个 node 进程，最省事也最可靠。
+// 一个进程管全流程：起桥 → 轮询 /health 直到模型就绪 → 打两个 /encode →
+// 确认第二个实例顺延到下一个端口 → 确认非回环绑定被拒 → 关桥。
+// 为什么不起后台进程：SSH 会话一结束会把 detached 进程一起带走（跨机踩过的坑），
+// 「起 + 测 + 关」必须落在同一条命令里 —— 本脚本就是那条命令。
 import { startBridge } from '../serve.mjs';
 import { parseArgs, isMainEntry } from '../lib/cli-util.mjs';
 
-async function waitReady(port, timeoutMs = 60000) {
-  const t0 = Date.now();
+const FALLBACK_PORT = 8201;
+const POLL_MS = 400;
+const LOAD_BUDGET_MS = 60000;
+const LOOPBACK = '127.0.0.1';
+
+const delay = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/** 按要打印的键投影一份快照，保持声明顺序。 */
+const pick = (snapshot, keys) => Object.fromEntries(keys.map((key) => [key, snapshot[key]]));
+
+const meanSquare = (vector) => vector.reduce((sum, value) => sum + value * value, 0);
+
+async function callJson(port, route, init) {
+  const response = await fetch(`http://${LOOPBACK}:${port}${route}`, init);
+  return response.json();
+}
+
+const healthOf = (port) => callJson(port, '/health');
+
+/** 正常请求的 /encode；只有传输层或 JSON 坏掉才会抛。 */
+const encodeTexts = (port, texts) =>
+  callJson(port, '/encode', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ texts }),
+  });
+
+/** 故意打坏请求的 /encode；状态码先取下来再解析正文。 */
+async function encodeBroken(port, payload) {
+  const response = await fetch(`http://${LOOPBACK}:${port}/encode`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+  return { status: response.status, body: await response.json() };
+}
+
+/**
+ * 轮询 /health 直到模型就绪。
+ * 桥报了加载错误也只等到预算耗尽才抛 —— 与桥的懒加载行为对齐，期间的加载失败
+ * 不算终局（模型可能重试后起来）。
+ */
+async function awaitReady(port, budget = LOAD_BUDGET_MS) {
+  const startedAt = Date.now();
+  const overdue = () => Date.now() - startedAt > budget;
   for (;;) {
     try {
-      const h = await fetch(`http://127.0.0.1:${port}/health`).then((r) => r.json());
-      if (h.ready) return h;
-      if (h.lastError) throw new Error(`模型加载失败：${h.lastError}`);
-    } catch (e) {
-      if (Date.now() - t0 > timeoutMs) throw e;
+      const snapshot = await healthOf(port);
+      if (snapshot.ready) return snapshot;
+      if (snapshot.lastError) throw new Error(`模型加载失败：${snapshot.lastError}`);
+    } catch (err) {
+      if (overdue()) throw err;
     }
-    if (Date.now() - t0 > timeoutMs) throw new Error('等待模型就绪超时');
-    await new Promise((r) => setTimeout(r, 400));
+    if (overdue()) throw new Error('等待模型就绪超时');
+    await delay(POLL_MS);
+  }
+}
+
+function reportPortShift(first, second) {
+  const verdict = second.port === first.port + 1 ? ' ✅' : ' ❌';
+  console.log(`端口顺延检查：首个=${first.port}，第二个=${second.port}${verdict}`);
+}
+
+/** 除了回环，桥不许绑任何地址。 */
+async function probeLoopbackGuard(modelDir) {
+  try {
+    await startBridge({ flags: { 'model-dir': modelDir, bind: '0.0.0.0' }, log: () => {} });
+    return '未拦截 ❌';
+  } catch (err) {
+    return `已拦截 ✅（${String(err.message).slice(0, 40)}…）`;
   }
 }
 
 async function main() {
   const { flags } = parseArgs();
   const modelDir = flags['model-dir'];
-  const wantPort = Number(flags.port || 8201);
-  const logs = [];
-  const log = (m) => {
-    logs.push(m);
-    console.log(m);
-  };
+  const wantPort = Number(flags.port || FALLBACK_PORT);
+  const log = (message) => console.log(message);
 
   console.log('=== 编码桥实测（仅回环） ===');
-  const b1 = await startBridge({ flags: { 'model-dir': modelDir, port: String(wantPort) }, log });
-  const b2 = await startBridge({ flags: { 'model-dir': modelDir, port: String(wantPort), warm: false }, log });
-  console.log(`端口顺延检查：首个=${b1.port}，第二个=${b2.port}${b2.port === b1.port + 1 ? ' ✅' : ' ❌'}`);
+  const primary = await startBridge({ flags: { 'model-dir': modelDir, port: String(wantPort) }, log });
+  const secondary = await startBridge({ flags: { 'model-dir': modelDir, port: String(wantPort), warm: false }, log });
+  reportPortShift(primary, secondary);
 
-  const health0 = await fetch(`http://127.0.0.1:${b1.port}/health`).then((r) => r.json());
-  console.log(`/health（加载中）：${JSON.stringify({ ready: health0.ready, modelLoading: health0.modelLoading, model: health0.model, dim: health0.dim })}`);
+  const whileLoading = await healthOf(primary.port);
+  console.log(`/health（加载中）：${JSON.stringify(pick(whileLoading, ['ready', 'modelLoading', 'model', 'dim']))}`);
 
-  const ready = await waitReady(b1.port);
-  console.log(`/health（就绪）：${JSON.stringify({ ready: ready.ready, model: ready.model, dim: ready.dim, port: ready.port })}`);
+  const ready = await awaitReady(primary.port);
+  console.log(`/health（就绪）：${JSON.stringify(pick(ready, ['ready', 'model', 'dim', 'port']))}`);
 
-  const t0 = performance.now();
-  const enc = await fetch(`http://127.0.0.1:${b1.port}/encode`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ texts: ['跨机同步的挡推裁决', '整夜干活'] }),
-  }).then((r) => r.json());
-  const ms = performance.now() - t0;
-  console.log(`/encode 2 条：${ms.toFixed(1)}ms · model=${enc.model} dim=${enc.dim} · 首向量前 5 维 ${enc.vectors[0].slice(0, 5).map((x) => x.toFixed(4)).join(', ')}`);
-  const norm = Math.sqrt(enc.vectors[0].reduce((s, x) => s + x * x, 0));
-  console.log(`首向量 L2 范数：${norm.toFixed(6)}（契约要求归一化 ⇒ 应 ≈1）`);
-
-  const bad = await fetch(`http://127.0.0.1:${b1.port}/encode`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ nope: 1 }),
-  }).then((r) => ({ status: r.status, body: r.json() }));
-  const badRes = await bad.body;
-  console.log(`坏请求处理：HTTP ${bad.status} ${JSON.stringify(badRes)}`);
+  const startedAt = performance.now();
+  const encoded = await encodeTexts(primary.port, ['跨机同步的挡推裁决', '整夜干活']);
+  const elapsed = performance.now() - startedAt;
+  const firstVector = encoded.vectors[0];
+  const headDims = firstVector.slice(0, 5).map((value) => value.toFixed(4)).join(', ');
+  console.log(`/encode 2 条：${elapsed.toFixed(1)}ms · model=${encoded.model} dim=${encoded.dim} · 首向量前 5 维 ${headDims}`);
+  console.log(`首向量 L2 范数：${Math.sqrt(meanSquare(firstVector)).toFixed(6)}（契约要求归一化 ⇒ 应 ≈1）`);
 
-  const nonLoop = await (async () => {
-    try {
-      await startBridge({ flags: { 'model-dir': modelDir, bind: '0.0.0.0' }, log: () => {} });
-      return '未拦截 ❌';
-    } catch (e) {
-      return `已拦截 ✅（${String(e.message).slice(0, 40)}…）`;
-    }
-  })();
-  console.log(`非回环绑定拦截：${nonLoop}`);
+  const broken = await encodeBroken(primary.port, { nope: 1 });
+  console.log(`坏请求处理：HTTP ${broken.status} ${JSON.stringify(broken.body)}`);
+
+  console.log(`非回环绑定拦截：${await probeLoopbackGuard(modelDir)}`);
 
-  await b2.close();
-  await b1.close();
+  await secondary.close();
+  await primary.close();
   console.log('桥已关闭');
   process.exitCode = 0;
 }

package/memory-engine/tools/fetch-model.mjs

@@ -1,92 +1,179 @@
-// 记忆引擎 v2 · 离线层 —— 模型权重获取器（node 版，不用 curl）
+// 记忆引擎 · 离线层 —— 模型权重获取器（纯 Node，不依赖 curl）
 //
-// 为什么要有这个脚本（Windows + schannel 环境实测坑）：
-//   Windows 自带 curl.exe 走 schannel；HF 的 LFS 大文件会 302 到 Xet CAS 桥
-//   （cas-bridge.xethub.hf.co），部分 Windows 主机上 schannel 对该域名 TLS 握手直接失败
-//   （curl: (35) SEC_E_ILLEGAL_MESSAGE），而小文件（走 hf-mirror 直连）没问题。
-//   node 自带 TLS 栈不受 schannel 影响 ⇒ 用本脚本取权重。
+// 为什么不用 curl：Windows 自带的 curl.exe 走 schannel 做 TLS，而 Hub 上的大文件
+// 会 302 到 Xet CAS 桥（cas-bridge.xethub.hf.co）；部分 Windows 主机对这个域名的
+// 握手直接失败（curl: (35) SEC_E_ILLEGAL_MESSAGE），反倒是直连下发的小文件没事。
+// Node 自带独立 TLS 栈，能绕开 schannel 这条路。
 //
 // 用法：
 //   node tools/fetch-model.mjs --out <模型目录> [--base https://hf-mirror.com]
-//        [--repo Xenova/bge-small-zh-v1.5] [--variant fp32|int8] [--force]
-// 幂等：已存在且大小与远端一致 → 跳过（--force 强制重下）。
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
+//        [--repo Xenova/bge-small-zh-v1.5] [--variant fp32|int8|fp16] [--force]
+// 幂等：本地文件的字节数与服务端 content-length 相同就不动它；--force 要求重下。
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { parseArgs, isMainEntry } from '../lib/cli-util.mjs';
 
-const COMMON = [
+const MIB = 1024 * 1024;
+
+/** 所有变体都要的配套文件，按这个顺序取。 */
+const SHARED_FILES = [
   'config.json',
   'tokenizer.json',
   'tokenizer_config.json',
   'special_tokens_map.json',
   'vocab.txt',
 ];
-const VARIANTS = {
+
+/** 变体名 → 仓内的权重文件（键顺序会出现在报错文案里，别乱动）。 */
+const WEIGHTS = {
   fp32: 'onnx/model.onnx',
   int8: 'onnx/model_quantized.onnx',
   fp16: 'onnx/model_fp16.onnx',
 };
 
-async function fetchOne({ url, dest, force, log }) {
-  const head = await fetch(url, { method: 'GET', redirect: 'follow' });
-  if (!head.ok) throw new Error(`HTTP ${head.status} ${head.statusText} (${url})`);
-  const total = Number(head.headers.get('content-length') || 0);
-  const name = path.basename(dest);
-  if (!force && fs.existsSync(dest) && total > 0 && fs.statSync(dest).size === total) {
-    await head.body?.cancel?.();
-    return { file: name, status: 'skip', size: total, sha: shortSha(dest) };
+/** 命令行没给时的兜底值。 */
+const BAREFALLS = {
+  base: 'https://hf-mirror.com',
+  repo: 'Xenova/bge-small-zh-v1.5',
+  variant: 'fp32',
+};
+
+const USAGE =
+  '用法: node tools/fetch-model.mjs --out <dir> [--base <url>] [--repo <owner/name>] [--variant fp32|int8|fp16] [--force]';
+
+const pause = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/** sha256 前 32 位 hex：够人对一眼，又不至于刷出 64 位。 */
+const shortDigest = (filePath) => createHash('sha256').update(readFileSync(filePath)).digest('hex').slice(0, 32);
+
+const asMegabytes = (bytes) => (bytes / MIB).toFixed(1);
+
+/** 每跨过 10 % 才打一行进度，免得刷屏。 */
+function announce(name, received, total, cursor, say) {
+  if (!total) return;
+  const percent = Math.floor((received / total) * 100);
+  if (percent < cursor.last + 10) return;
+  cursor.last = percent;
+  say(`    ${name}: ${percent}%（${asMegabytes(received)}/${asMegabytes(total)} MB）`);
+}
+
+/** 把一块 Uint8Array 全写进去；短写就接着写剩下的。 */
+async function writeAll(handle, chunk) {
+  let written = 0;
+  while (written < chunk.byteLength) {
+    const { bytesWritten } = await handle.write(chunk, written, chunk.byteLength - written);
+    if (!bytesWritten) throw new Error('写入中断（0 字节）');
+    written += bytesWritten;
   }
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  const part = `${dest}.part`;
-  let got = 0;
-  let lastPct = -1;
-  const src = Readable.fromWeb(head.body);
-  src.on('data', (c) => {
-    got += c.length;
-    if (total) {
-      const pct = Math.floor((got / total) * 100);
-      if (pct >= lastPct + 10) {
-        lastPct = pct;
-        log(`    ${name}: ${pct}%（${(got / 1048576).toFixed(1)}/${(total / 1048576).toFixed(1)} MB）`);
-      }
+}
+
+/**
+ * 把响应体逐块落到临时文件里，每块都 await ⇒ 套接字永远不会跑到磁盘前面。
+ * 落完怎么处理（改名 / 丢弃）由调用方决定。
+ */
+async function spoolTo(partialPath, body, expected, name, say) {
+  if (!body) throw new Error(`${name}：响应没有正文`);
+  const reader = body.getReader();
+  const handle = await open(partialPath, 'w');
+  const cursor = { last: -1 };
+  let received = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      await writeAll(handle, value);
+      received += value.byteLength;
+      announce(name, received, expected, cursor, say);
     }
-  });
-  await pipeline(src, fs.createWriteStream(part));
-  if (total && fs.statSync(part).size !== total) {
-    throw new Error(`${name} 大小不符：期望 ${total}，实际 ${fs.statSync(part).size}`);
+  } finally {
+    await handle.close();
   }
-  fs.renameSync(part, dest);
-  return { file: name, status: 'fetched', size: fs.statSync(dest).size, sha: shortSha(dest) };
 }
 
-function shortSha(p) {
-  return crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex').slice(0, 32);
+/**
+ * 取一个远端路径到 destination。
+ * 返回 {file,status:'skip'|'fetched',size,sha}；传输层出问题就抛。
+ */
+async function pullFile({ url, destination, overwrite, say }) {
+  const response = await fetch(url, { method: 'GET', redirect: 'follow' });
+  if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText} (${url})`);
+
+  const expected = Number(response.headers.get('content-length') || 0);
+  const name = basename(destination);
+  const localSize = existsSync(destination) ? statSync(destination).size : -1;
+
+  if (!overwrite && expected > 0 && localSize === expected) {
+    await response.body?.cancel?.();
+    return { file: name, status: 'skip', size: expected, sha: shortDigest(destination) };
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  const partialPath = `${destination}.part`;
+  await spoolTo(partialPath, response.body, expected, name, say);
+
+  const landed = statSync(partialPath).size;
+  if (expected && landed !== expected) throw new Error(`${name} 大小不符：期望 ${expected}，实际 ${landed}`);
+  renameSync(partialPath, destination);
+  return { file: name, status: 'fetched', size: statSync(destination).size, sha: shortDigest(destination) };
 }
 
-export async function fetchModel({ out, base, repo, variant, force, log, retries = 3 }) {
-  const files = [...COMMON, VARIANTS[variant]];
-  const results = [];
-  for (const f of files) {
-    const url = `${base}/${repo}/resolve/main/${f}`;
-    let lastErr = null;
-    for (let attempt = 1; attempt <= retries; attempt += 1) {
-      try {
-        log(`  → ${f}${attempt > 1 ? `（第 ${attempt} 次尝试）` : ''}`);
-        results.push(await fetchOne({ url, dest: path.join(out, f.replace(/\//g, path.sep)), force, log }));
-        lastErr = null;
-        break;
-      } catch (e) {
-        lastErr = e;
-        log(`    ⚠ ${String(e && e.message ? e.message : e)}`);
-        await new Promise((r) => setTimeout(r, 1500 * attempt));
-      }
+/**
+ * 一个远端路径 + 重试预算。
+ * 调用方把 retries 设成 0 时返回 null（一条记录都不写，保持原语义）。
+ */
+async function attemptFile({ url, destination, force, log, retries, name }) {
+  let failure = null;
+  for (let round = 1; round <= retries; round += 1) {
+    log(`  → ${name}${round > 1 ? `（第 ${round} 次尝试）` : ''}`);
+    try {
+      return await pullFile({ url, destination, overwrite: force, say: log });
+    } catch (err) {
+      failure = err;
+      log(`    ⚠ ${String(err && err.message ? err.message : err)}`);
+      await pause(1500 * round);
     }
-    if (lastErr) {
-      results.push({ file: f, status: 'FAILED', error: String(lastErr.message || lastErr) });
+  }
+  if (!failure) return null;
+  return { file: name, status: 'FAILED', error: String(failure.message || failure) };
+}
+
+/** 逐条打结果，并定进程退出码。 */
+function summarize(results) {
+  console.log('\n=== 结果 ===');
+  let failed = 0;
+  for (const item of results) {
+    if (item.status === 'FAILED') {
+      failed += 1;
+      console.log(`❌ ${item.file}：${item.error}`);
+      continue;
     }
+    const mark = item.status === 'skip' ? '⏭️ ' : '✅';
+    console.log(`${mark} ${item.file.padEnd(28)} ${(item.size / MIB).toFixed(2)} MB  sha256=${item.sha}`);
+  }
+  console.log(failed ? `\n❌ ${failed} 个文件失败` : '\n✅ 全部就绪');
+  process.exitCode = failed ? 1 : 0;
+}
+
+/**
+ * 把某个变体需要的文件全取到 out 里。
+ * 普通下载失败不会让本函数 reject —— 那些都变成 FAILED 记录。
+ */
+export async function fetchModel({ out, base, repo, variant, force, log, retries = 3 }) {
+  const remotePaths = [...SHARED_FILES, WEIGHTS[variant]];
+  const results = [];
+  for (const remotePath of remotePaths) {
+    const settled = await attemptFile({
+      url: `${base}/${repo}/resolve/main/${remotePath}`,
+      destination: join(out, remotePath.replace(/\//g, sep)),
+      force,
+      log,
+      retries,
+      name: remotePath,
+    });
+    if (settled) results.push(settled);
   }
   return results;
 }
@@ -94,35 +181,28 @@ export async function fetchModel({ out, base, repo, variant, force, log, retries
 async function main() {
   const { flags } = parseArgs();
   if (flags.help) {
-    console.log(`用法: node tools/fetch-model.mjs --out <dir> [--base <url>] [--repo <owner/name>] [--variant fp32|int8|fp16] [--force]`);
+    console.log(USAGE);
     return;
   }
-  const out = flags.out || process.env.MEMORY_ENGINE_MODEL_DIR;
-  if (!out) throw new Error('必须指定 --out（模型落盘目录）');
-  const opts = {
-    out: path.resolve(out),
-    base: flags.base || 'https://hf-mirror.com',
-    repo: flags.repo || 'Xenova/bge-small-zh-v1.5',
-    variant: flags.variant || 'fp32',
+  const requestedOut = flags.out || process.env.MEMORY_ENGINE_MODEL_DIR;
+  if (!requestedOut) throw new Error('必须指定 --out（模型落盘目录）');
+
+  const settings = {
+    out: resolve(requestedOut),
+    base: flags.base || BAREFALLS.base,
+    repo: flags.repo || BAREFALLS.repo,
+    variant: flags.variant || BAREFALLS.variant,
     force: Boolean(flags.force),
   };
-  console.log(`模型获取器：${opts.repo}（${opts.variant}）`);
-  console.log(`镜像      ：${opts.base}`);
-  console.log(`目标目录  ：${opts.out}`);
-  if (!VARIANTS[opts.variant]) throw new Error(`未知 variant=${opts.variant}（可选 ${Object.keys(VARIANTS).join('/')}）`);
-  const results = await fetchModel({ ...opts, log: (m) => console.log(m) });
-  console.log('\n=== 结果 ===');
-  let failed = 0;
-  for (const r of results) {
-    if (r.status === 'FAILED') {
-      failed += 1;
-      console.log(`❌ ${r.file}：${r.error}`);
-    } else {
-      console.log(`${r.status === 'skip' ? '⏭️ ' : '✅'} ${r.file.padEnd(28)} ${(r.size / 1048576).toFixed(2)} MB  sha256=${r.sha}`);
-    }
+  console.log(`模型获取器：${settings.repo}（${settings.variant}）`);
+  console.log(`镜像      ：${settings.base}`);
+  console.log(`目标目录  ：${settings.out}`);
+
+  if (!WEIGHTS[settings.variant]) {
+    throw new Error(`未知 variant=${settings.variant}（可选 ${Object.keys(WEIGHTS).join('/')}）`);
   }
-  console.log(failed ? `\n❌ ${failed} 个文件失败` : '\n✅ 全部就绪');
-  process.exitCode = failed ? 1 : 0;
+
+  summarize(await fetchModel({ ...settings, log: (message) => console.log(message) }));
 }
 
 if (isMainEntry(import.meta.url)) await main();

package/memory-engine/tools/smoke-recall.mjs

@@ -1,8 +1,9 @@
-// 记忆引擎 v2 · 离线层 —— 真实模型召回冒烟（人读证据）
+// 记忆引擎 · 离线层 —— 真实模型召回冒烟（给人读的证据）
 //
-// 为什么单独一个脚本：命令行传中文经 cmd/ssh 会乱码，这里把查询集写死在文件里，
-// 在目标机上直接跑，得到「真实模型 + 真实语料」的可读召回证据（含短暗号）。
-import fs from 'node:fs';
+// 单独成一个脚本的理由：中文查询经 cmd/ssh 传过去会变乱码，所以把探针查询集写死在
+// 这个文件里当数据用；在目标机上跑一条命令，就能拿到「真模型 + 真语料」的可读召回
+// 证据（含短暗号）。
+import { existsSync } from 'node:fs';
 import { parseArgs, isMainEntry } from '../lib/cli-util.mjs';
 import { resolveConfig } from '../lib/config.mjs';
 import { openVectorsStore, countVectors, getMetaAll } from '../lib/vectors-store.mjs';
@@ -10,7 +11,8 @@ import { openMemorySource } from '../lib/memory-source.mjs';
 import { createLocalEmbedder } from '../lib/embedder.mjs';
 import { recall, buildVectorIndex, shouldTrigger } from '../lib/recall.mjs';
 
-const QUERIES = [
+/** 固定探针集：日常暗号、工程问题，外加一个裸端口号。 */
+const PROBES = [
   '退下吧',
   '整夜干活',
   '去深水区',
@@ -23,16 +25,84 @@ const QUERIES = [
   '3080 端口',
 ];
 
+/** CLI 里能改配置路径的几个开关。 */
+const PATH_FLAGS = [
+  ['memoryDb', 'memory-db'],
+  ['vectorsDb', 'vectors-db'],
+  ['modelDir', 'model-dir'],
+];
+
+const LABEL_COLUMNS = 9;
+const HIT_INDENT = '   ';
+const MAX_BRIEF_CHARS = 58;
+const TOP_K = 5;
+
+/** 字符串的终端宽度：CJK 码点按两列算（首列才能对齐）。 */
+const widthOf = (text) => [...text].reduce((cols, ch) => cols + (ch.codePointAt(0) > 0x2e7f ? 2 : 1), 0);
+
+const padLabel = (text) => text + ' '.repeat(Math.max(0, LABEL_COLUMNS - widthOf(text)));
+
+const collapse = (text) => String(text).replace(/\s+/g, ' ');
+
+/** 一条记忆的单行、截断版摘要。 */
+const excerpt = (text) => collapse(text).slice(0, MAX_BRIEF_CHARS);
+
+const gateVerdict = (gate) => (gate.trigger ? '是' : `否(${gate.reason})`);
+
+/** 把命令行开关翻成 resolveConfig 的覆盖项；没给的键一律不出现。 */
+function overridesFrom(flags) {
+  const overrides = {};
+  for (const [key, flag] of PATH_FLAGS) {
+    if (flags[flag]) overrides[key] = flags[flag];
+  }
+  if (flags.model) overrides.modelId = flags.model;
+  if (flags.dim) overrides.dim = Number(flags.dim);
+  return overrides;
+}
+
+/** 表头段：查之前先把语料形状交代清楚。 */
+function printCorpora({ config, source, store, embedder }) {
+  const rows = [
+    ['主机', process.env.COMPUTERNAME || '?'],
+    ['记忆库', `${config.memoryDb}（${source.count()} 条 / pinned ${source.pinnedIds().length} 条）`],
+    ['向量库', `${config.vectorsDb}（${countVectors(store.db, 'memory')} 条向量）`],
+    ['meta', JSON.stringify(getMetaAll(store.db))],
+    ['模型', `${config.modelId} dim=${embedder.dim}`],
+  ];
+  console.log('=== 真实模型召回冒烟 ===');
+  for (const [label, value] of rows) console.log(`${padLabel(label)}: ${value}`);
+  console.log('');
+}
+
+function printHit(hit, row) {
+  const stored = row ? row.pinned : '?';
+  const text = excerpt(row ? row.text : '(已删除)');
+  console.log(`${HIT_INDENT}#${hit.refId} score=${hit.score.toFixed(5)} [${hit.sources.join('+')}] pinned=${stored} · ${text}…`);
+}
+
+/** 跑一条探针；返回这条命中里漏进了几条 pinned。 */
+async function runProbe({ query, store, source, embedder, index, pinnedIds }) {
+  const gate = shouldTrigger(query);
+  const startedAt = performance.now();
+  const outcome = await recall({ query, store, source, embedder, index, resultTopK: TOP_K });
+  const elapsed = performance.now() - startedAt;
+
+  const ftsMatched = outcome.stats.ftsMatched ?? 0;
+  console.log(`【${query}】触发=${gateVerdict(gate)} 命中 ${outcome.hits.length} 条 · ${elapsed.toFixed(1)}ms · FTS命中=${ftsMatched}`);
+
+  let leaked = 0;
+  for (const hit of outcome.hits) {
+    if (pinnedIds.has(String(hit.refId))) leaked += 1;
+    printHit(hit, source.getById(hit.id));
+  }
+  console.log('');
+  return leaked;
+}
+
 async function main() {
   const { flags } = parseArgs();
-  const config = resolveConfig({
-    memoryDb: flags['memory-db'] || undefined,
-    vectorsDb: flags['vectors-db'] || undefined,
-    modelDir: flags['model-dir'] || undefined,
-    modelId: flags.model || undefined,
-    dim: flags.dim ? Number(flags.dim) : undefined,
-  });
-  if (!fs.existsSync(config.memoryDb)) throw new Error(`记忆库不存在：${config.memoryDb}`);
+  const config = resolveConfig(overridesFrom(flags));
+  if (!existsSync(config.memoryDb)) throw new Error(`记忆库不存在：${config.memoryDb}`);
 
   const embedder = await createLocalEmbedder({
     modelDir: config.modelDir,
@@ -43,34 +113,20 @@ async function main() {
   const source = openMemorySource(config.memoryDb);
   const index = buildVectorIndex(store.db, { source: 'memory' });
 
-  console.log('=== 真实模型召回冒烟 ===');
-  console.log(`主机     : ${process.env.COMPUTERNAME || '?'}`);
-  console.log(`记忆库   : ${config.memoryDb}（${source.count()} 条 / pinned ${source.pinnedIds().length} 条）`);
-  console.log(`向量库   : ${config.vectorsDb}（${countVectors(store.db, 'memory')} 条向量）`);
-  console.log(`meta     : ${JSON.stringify(getMetaAll(store.db))}`);
-  console.log(`模型     : ${config.modelId} dim=${embedder.dim}`);
-  console.log('');
+  printCorpora({ config, source, store, embedder });
 
-  const pinned = new Set(source.pinnedIds().map(String));
-  let pinnedLeak = 0;
-  for (const q of QUERIES) {
-    const gate = shouldTrigger(q);
-    const t0 = performance.now();
-    const r = await recall({ query: q, store, source, embedder, index, resultTopK: 5 });
-    const ms = performance.now() - t0;
-    console.log(`【${q}】触发=${gate.trigger ? '是' : `否(${gate.reason})`} 命中 ${r.hits.length} 条 · ${ms.toFixed(1)}ms · FTS命中=${r.stats.ftsMatched ?? 0}`);
-    for (const h of r.hits) {
-      if (pinned.has(String(h.refId))) pinnedLeak += 1;
-      const row = source.getById(h.id);
-      const brief = (row ? row.text : '(已删除)').replace(/\s+/g, ' ').slice(0, 58);
-      console.log(`   #${h.refId} score=${h.score.toFixed(5)} [${h.sources.join('+')}] pinned=${row ? row.pinned : '?'} · ${brief}…`);
+  const pinnedIds = new Set(source.pinnedIds().map(String));
+  let leakedTotal = 0;
+  try {
+    for (const query of PROBES) {
+      leakedTotal += await runProbe({ query, store, source, embedder, index, pinnedIds });
     }
-    console.log('');
+    console.log(`pinned 泄漏检查：${leakedTotal === 0 ? '✅ 0 条（排除生效）' : `❌ ${leakedTotal} 条`}`);
+  } finally {
+    source.close();
+    store.db.close();
   }
-  console.log(`pinned 泄漏检查：${pinnedLeak === 0 ? '✅ 0 条（排除生效）' : `❌ ${pinnedLeak} 条`}`);
-  source.close();
-  store.db.close();
-  process.exitCode = pinnedLeak === 0 ? 0 : 4;
+  process.exitCode = leakedTotal === 0 ? 0 : 4;
 }
 
 if (isMainEntry(import.meta.url)) await main();