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

package/memory-engine/cli/pitfall-hook.mjs

@@ -0,0 +1,91 @@
+// 记忆引擎 v2 · 离线层 —— 坑库向量同步钩子 CLI（A 点 · 标记/状态/消费三用）
+//
+// 用法：
+//   node cli/pitfall-hook.mjs --status --json            # 只读：标记现值 + 两个来源的向量条数
+//   node cli/pitfall-hook.mjs --run --json               # **预演**（默认 dry-run：只算不写、不清标记）
+//   node cli/pitfall-hook.mjs --run --apply --json       # 真消费（写向量 + 清标记）
+//   node cli/pitfall-hook.mjs --mark --reason "pitfall job 变动"   # 置标记（pitfall job 侧一行调用）
+//   路径可注入：--marker-file / --pitfalls-file / --vectors-db / --dsh-home
+//
+// ⚠️ 生态规矩：动数据的动作一律**默认 dry-run**，`--apply` 才真写。
+import { isMainEntry, parseArgs, makeLogger, openRuntime, num } from '../lib/cli-util.mjs';
+import { readMarker, markDirty, runPitfallHook } from '../lib/tick-hook.mjs';
+import { countVectors } from '../lib/vectors-store.mjs';
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  const mode = flags.run ? 'run' : flags.mark ? 'mark' : 'status';
+  const apply = Boolean(flags.apply);
+  let rt = null;
+  try {
+    // 钩子只关心坑源 ⇒ 不预开默认来源（默认来源 = memory，会被守卫拒掉）
+    rt = await openRuntime(flags, { withSource: false, withEmbedder: mode === 'run' });
+    const markerPath = rt.config.pitfallVectorDirtyFile;
+    const out = {
+      ok: true,
+      mode,
+      apply,
+      markerPath,
+      pitfallsFile: rt.config.pitfallsFile,
+      vectorsDb: rt.config.vectorsDb,
+      counts: { memory: countVectors(rt.store.db, 'memory'), pitfall: countVectors(rt.store.db, 'pitfall') },
+    };
+
+    if (mode === 'status') {
+      const r = readMarker(markerPath);
+      out.marker = { present: r.present, value: r.marker, error: r.error };
+    } else if (mode === 'mark') {
+      out.mark = markDirty(markerPath, {
+        reason: flags.reason === undefined || flags.reason === true ? null : String(flags.reason),
+        by: 'cli/pitfall-hook.mjs',
+      });
+    } else {
+      out.hook = await runPitfallHook({
+        markerPath,
+        store: rt.store,
+        // ⚠️ 必须是**坑源**：默认来源（memory）会被 runPitfallHook 的守卫拒掉
+        source: rt.openSource('pitfall'),
+        embedder: rt.embedder,
+        modelId: rt.config.modelId,
+        dim: rt.config.dim,
+        batchSize: num(flags.batch, rt.config.batchSize),
+        full: Boolean(flags.full),
+        dryRun: !apply,
+        log,
+      });
+      out.countsAfter = {
+        memory: countVectors(rt.store.db, 'memory'),
+        pitfall: countVectors(rt.store.db, 'pitfall'),
+      };
+    }
+
+    if (json) process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+    else {
+      log(`=== 坑库向量钩子（${mode}${apply ? ' · --apply' : ' · 预演'}） ===`);
+      log(`标记文件    : ${markerPath}`);
+      log(`坑库        : ${rt.config.pitfallsFile}`);
+      log(`向量库      : ${rt.config.vectorsDb}`);
+      log(`向量条数    : memory=${out.counts.memory} / pitfall=${out.counts.pitfall}`);
+      if (mode === 'status') log(`标记        : ${out.marker.present ? JSON.stringify(out.marker.value) : `无${out.marker.error ? `（读失败：${out.marker.error}）` : ''}`}`);
+      if (mode === 'mark') log(`已置标记    : updatedAt=${out.mark.updatedAt}`);
+      if (mode === 'run') {
+        log(`钩子结果    : ${out.hook.ok ? '✅' : '❌'} ${out.hook.skipped ? `（${out.hook.skipped}）` : ''}`);
+        if (out.hook.stats) log(`同步        : 扫 ${out.hook.stats.scanned} / 编码 ${out.hook.stats.encoded}（跳过 ${out.hook.stats.skippedSameHash}）向量 ${out.hook.stats.vectorsBefore} → ${out.hook.stats.vectorsAfter}`);
+        log(`清标记      : ${JSON.stringify(out.hook.cleared)}`);
+        log(`向量条数    : memory=${out.countsAfter.memory} / pitfall=${out.countsAfter.pitfall}`);
+      }
+    }
+    process.exitCode = out.hook && out.hook.ok === false ? 1 : 0;
+  } catch (e) {
+    const msg = String(e && e.stack ? e.stack : e);
+    if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: msg }, null, 2)}\n`);
+    else log(`❌ ${msg}`);
+    process.exitCode = 2;
+  } finally {
+    if (rt) rt.close();
+  }
+}
+
+if (isMainEntry(import.meta.url)) await main();

package/memory-engine/cli/recall.mjs

@@ -0,0 +1,132 @@
+// 记忆引擎 v2 · 离线层 —— 召回 CLI（向量 + FTS 补位 + RRF 融合 + 排除 pinned）
+//
+// 用法：
+//   node cli/recall.mjs --query "退下吧" [--top-k 8]
+//   node cli/recall.mjs --query "task-board 看板" --json
+//   node cli/recall.mjs --query "..." --repeat 100     # 计时（V2 用 bench 更完整）
+//   node cli/recall.mjs --query "..." --source pitfall          # 只召回坑源（默认 memory）
+//   node cli/recall.mjs --query "..." --sources memory,pitfall  # 多来源召回（RRF 跨源融合）
+import { isMainEntry, parseArgs, makeLogger, openRuntime, num } from '../lib/cli-util.mjs';
+import {
+  recall,
+  recallMulti,
+  buildVectorIndex,
+  shouldTrigger,
+  extractFtsTokens,
+  buildFtsMatch,
+} from '../lib/recall.mjs';
+
+function parseSourceList(flags) {
+  const raw = flags.sources;
+  if (raw === undefined || raw === true || raw === '') return null;
+  const list = String(raw)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return list.length ? list : null;
+}
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  const query = flags.query === undefined || flags.query === true ? '' : String(flags.query);
+  const multiSources = parseSourceList(flags);
+  let rt = null;
+  try {
+    rt = await openRuntime(flags);
+    const repeat = num(flags.repeat, 1);
+    let last = null;
+    const times = [];
+    let indexSize = 0;
+
+    for (let i = 0; i < repeat; i += 1) {
+      if (multiSources) {
+        const entries = multiSources.map((name) => ({
+          name,
+          source: rt.openSource(name),
+          index: buildVectorIndex(rt.store.db, { source: name }),
+        }));
+        indexSize = entries.reduce((a, e) => a + (e.index.count || 0), 0);
+        last = await recallMulti({
+          query,
+          store: rt.store,
+          entries,
+          embedder: rt.embedder,
+          perSourceTopK: num(flags['per-source-top-k'], 5),
+          rrfK: num(flags['rrf-k'], rt.config.rrfK),
+          resultTopK: num(flags['top-k'], rt.config.resultTopK),
+          log,
+        });
+      } else {
+        const index = buildVectorIndex(rt.store.db, { source: rt.sourceName });
+        indexSize = index.count;
+        last = await recall({
+          query,
+          store: rt.store,
+          source: rt.source,
+          embedder: rt.embedder,
+          index,
+          sourceName: rt.sourceName,
+          vectorTopK: num(flags['vector-top-k'], rt.config.vectorTopK),
+          ftsTopK: num(flags['fts-top-k'], rt.config.ftsTopK),
+          rrfK: num(flags['rrf-k'], rt.config.rrfK),
+          resultTopK: num(flags['top-k'], rt.config.resultTopK),
+          log,
+        });
+      }
+      times.push(last.timings.totalMs);
+    }
+    times.sort((a, b) => a - b);
+    const pct = (p) => times[Math.min(times.length - 1, Math.floor((p / 100) * times.length))];
+
+    const out = {
+      ok: true,
+      source: multiSources ? multiSources.join(',') : rt.sourceName,
+      vectorsDb: rt.config.vectorsDb,
+      indexSize,
+      gate: shouldTrigger(query),
+      ftsTokens: extractFtsTokens(query),
+      ftsMatchExpr: buildFtsMatch(extractFtsTokens(query)),
+      ...last,
+      repeat: { n: times.length, p50: pct(50), p95: pct(95), min: times[0], max: times[times.length - 1] },
+    };
+    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    else {
+      log(`=== 召回 ===`);
+      log(`来源        : ${out.source}`);
+      log(`查询        : ${JSON.stringify(query)}`);
+      log(`触发        : ${last.triggered ? `是（${last.reason}）` : `否（${last.reason}）`}`);
+      if (last.triggered) {
+        if (multiSources) {
+          for (const [name, rec] of Object.entries(last.perSource || {})) {
+            log(
+              `  · ${name}: 索引 ${rec.indexSize} 条 / 排除 pinned ${rec.pinnedExcluded} / 向量命中 ${rec.vectorHits} / FTS 命中 ${rec.ftsHits}${rec.error ? ` / ⚠️ ${rec.error}` : ''}`,
+            );
+          }
+        } else {
+          log(`索引规模    : ${last.stats.indexSize} 条向量 / 排除 pinned ${last.stats.pinnedExcluded} 条`);
+          log(`FTS 补位    : tokens=${JSON.stringify(last.stats.ftsTokens)} → 命中 ${last.stats.ftsMatched}`);
+        }
+        log(`耗时        : 编码 ${last.timings.encodeMs.toFixed(1)}ms / 向量 ${last.timings.vectorMs.toFixed(1)}ms / 融合 ${last.timings.fuseMs.toFixed(1)}ms / 合计 ${last.timings.totalMs.toFixed(1)}ms`);
+        log(`命中 top-${last.hits.length}：`);
+        for (const h of last.hits) {
+          log(
+            `  #${h.refId}${multiSources ? ` [${h.source}]` : ''}  score=${h.score.toFixed(5)}  来源=${h.sources.join('+')}  vecRank=${h.vectorRank ?? '-'} ftsRank=${h.ftsRank ?? '-'}`,
+          );
+        }
+      }
+      if (repeat > 1) log(`重复 ${times.length} 次：P50 ${pct(50).toFixed(1)}ms / P95 ${pct(95).toFixed(1)}ms`);
+    }
+    process.exitCode = 0;
+  } catch (e) {
+    const msg = String(e && e.stack ? e.stack : e);
+    if (json) process.stdout.write(JSON.stringify({ ok: false, error: msg }, null, 2) + '\n');
+    else log(`❌ ${msg}`);
+    process.exitCode = 2;
+  } finally {
+    if (rt) rt.close();
+  }
+}
+
+if (isMainEntry(import.meta.url)) await main();

package/memory-engine/cli/selfcheck.mjs

@@ -0,0 +1,57 @@
+// 记忆引擎 v2 · 离线层 —— 启动自检 CLI
+//
+// 用法：node cli/selfcheck.mjs [--json] [--stub-embedder] [--memory-db X] [--vectors-db Y] [--model-dir Z]
+// 退出码：0 = 全过（warn 不算失败）· 1 = 有 fail · 2 = 运行异常
+import { isMainEntry, parseArgs, makeLogger, openRuntime } from '../lib/cli-util.mjs';
+import { runSelfcheck } from '../lib/selfcheck.mjs';
+
+const ICON = { ok: '✅', warn: '⚠️ ', fail: '❌', info: 'ℹ️ ' };
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  let rt = null;
+  try {
+    rt = await openRuntime(flags);
+    const result = await runSelfcheck({
+      store: rt.store,
+      source: rt.source,
+      embedder: rt.embedder,
+      config: rt.config,
+      allowHostMismatch: !flags['strict-host'],
+    });
+    const out = {
+      ok: result.ok,
+      host: rt.config.hostId,
+      memoryDb: rt.config.memoryDb,
+      vectorsDb: rt.config.vectorsDb,
+      modelId: rt.config.modelId,
+      modelDir: rt.config.modelDir,
+      embedder: rt.embedder.describe(),
+      ...result,
+    };
+    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    else {
+      log('=== 启动自检 ===');
+      log(`主机        : ${rt.config.hostId}`);
+      log(`记忆库      : ${rt.config.memoryDb}`);
+      log(`向量库      : ${rt.config.vectorsDb}`);
+      log(`编码器      : ${JSON.stringify(rt.embedder.describe())}`);
+      log('');
+      for (const c of result.checks) log(`${ICON[c.status] || '·'} ${c.name}：${c.detail}`);
+      log('');
+      log(result.ok ? `✅ 自检通过（warn ${result.warned}）` : `❌ 自检失败（fail ${result.failed}）`);
+    }
+    process.exitCode = result.ok ? 0 : 1;
+  } catch (e) {
+    const msg = String(e && e.stack ? e.stack : e);
+    if (json) process.stdout.write(JSON.stringify({ ok: false, error: msg }, null, 2) + '\n');
+    else log(`❌ ${msg}`);
+    process.exitCode = 2;
+  } finally {
+    if (rt) rt.close();
+  }
+}
+
+if (isMainEntry(import.meta.url)) await main();

package/memory-engine/cli/serve-start.mjs

@@ -0,0 +1,247 @@
+// 记忆引擎 v2 · S2c —— 编码桥**幂等启动器**（方案 §3.1「谁起」+ §3.5 第 5 条）
+//
+// 契约（照方案原文，本文件是它的落地件）：
+//   · 幂等：先 `GET /health` 探活；**已在跑 → 直接退出 0 并打印端口**（不重复拉起、不抢端口）；
+//   · 不在跑 → 拉起 `serve.mjs`（detached），轮询 `/health` 直到 `ready:true`（默认 30s 上限）；
+//   · 端口顺延：`serve.mjs` 自己 +1 顺延（最多 10 次）；启动器**按子进程 pid 在
+//     [port, port+10] 里定位真实端口**，顺势落 `bridge-port.json` ⇒ 顺延后调用方仍查得到；
+//   · 崩溃 / 冷启：桥不在 / 模型仍在加载 / 返回异常 ⇒ **调用方 fail-open**（S2b 已做），
+//     启动器**只负责把桥拉起来**，不做无限重试（每轮 tick 幂等重启，靠 job 节奏兜底）；
+//   · 仅绑回环：`--bind` 非回环一律拒绝（与 serve.mjs 同款铁律，双层防呆）。
+//
+// 退出码：0 = 已在跑（跳过）或拉起成功且 ready / 1 = 拉起失败（超时 / spawn 失败 / 非回环）
+//         3 = `--no-start` 且桥不在（只探活模式，供调用方判让路）/ 2 = 用法错
+//
+// 用法：
+//   node cli/serve-start.mjs                        # 幂等确保 127.0.0.1:8201 在跑
+//   node cli/serve-start.mjs --json                 # 机器可读
+//   node cli/serve-start.mjs --no-start             # 只探活，不拉起
+//   node cli/serve-start.mjs --port-file <path>     # 覆盖端口台账落点（默认 <DSH_HOME>/memory-vectors/bridge-port.json）
+//   node cli/serve-start.mjs --port 18201 --wait-ms 20000 --log <file>
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveConfig } from '../lib/config.mjs';
+import { parseArgs, num, isMainEntry } from '../lib/cli-util.mjs';
+
+export const SERVE_START_VERSION = '0.1.0';
+
+/** 与 serve.mjs 的 MAX_PORT_TRIES 保持一致（顺延搜索范围 = 同款 +1 逻辑的镜像）。 */
+export const MAX_PORT_TRIES = 10;
+const PROBE_TIMEOUT_MS = 1200;
+const PROBE_TIMEOUT_FAST_MS = 400;
+const POLL_INTERVAL_MS = 500;
+const DEFAULT_WAIT_MS = 30_000;
+const LOG_MAX_BYTES = 2 * 1024 * 1024;
+const PORT_FILE_SCHEMA = 1;
+
+export const EXIT = { OK: 0, FAIL: 1, USAGE: 2, NOT_RUNNING: 3 };
+
+const LOOPBACK_RE = /^(127\.0\.0\.1|localhost|::1)$/;
+
+/** `/health` 响应是否为**本编码桥**（而不是恰好占着端口的路人服务，如 3080 的 web）。 */
+export function isBridgeHealth(body) {
+  return Boolean(body) && typeof body === 'object'
+    && typeof body.ready === 'boolean' && typeof body.modelLoading === 'boolean'
+    && (typeof body.model === 'string' || typeof body.dim === 'number');
+}
+
+/** 单端口探活：命中返回 { ok:true, port, body }；否则 { ok:false, port, error }。 */
+export async function probeHealth(port, { host = '127.0.0.1', timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  const ac = new AbortController();
+  const t = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://${host}:${port}/health`, { signal: ac.signal });
+    if (!res.ok) return { ok: false, port, error: `HTTP ${res.status}` };
+    const body = await res.json();
+    if (!isBridgeHealth(body)) return { ok: false, port, error: 'not-a-bridge' };
+    return { ok: true, port, body };
+  } catch (e) {
+    const name = e && e.name;
+    return { ok: false, port, error: name === 'AbortError' || name === 'TimeoutError' ? 'timeout' : String(e?.message ?? e) };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/** 端口台账（bridge-port.json）读取：读不到/坏 JSON 一律 null（台账是派生物，不阻断）。 */
+export function readPortFile(file) {
+  try {
+    const txt = fs.readFileSync(file, 'utf8');
+    const obj = JSON.parse(txt);
+    return obj && typeof obj === 'object' ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 原子写端口台账（同目录 tmp → rename；失败不致命）。 */
+export function writePortFile(file, obj) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 候选端口（去重、保序）：显式 `--port` / 台账记录 / 顺延窗。 */
+export function candidatePorts(basePort, recorded = null) {
+  const out = [];
+  const push = (p) => {
+    const n = Number(p);
+    if (!Number.isInteger(n) || n <= 0 || n > 65535) return;
+    if (!out.includes(n)) out.push(n);
+  };
+  push(basePort);
+  push(recorded);
+  for (let i = 1; i <= MAX_PORT_TRIES; i += 1) push(Number(basePort) + i);
+  return out;
+}
+
+/** 在候选端口里找**已在跑的桥**（顺延后仍能查到）。 */
+export async function findRunningBridge({ host = '127.0.0.1', ports = [], timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+  for (const port of ports) {
+    // eslint-disable-next-line no-await-in-loop
+    const r = await probeHealth(port, { host, timeoutMs });
+    if (r.ok) return r;
+  }
+  return null;
+}
+
+function truncateLog(file) {
+  try {
+    const st = fs.existsSync(file) ? fs.statSync(file) : null;
+    if (st && st.size > LOG_MAX_BYTES) fs.writeFileSync(file, '', 'utf8');
+  } catch { /* 忽略 */ }
+}
+
+/**
+ * 幂等确保桥在跑（job / 人工都走这一个入口）。
+ * @param {{flags?:object, log?:(msg:string)=>void}} opts
+ * @returns {Promise<{ok:boolean, started:boolean, port:number|null, pid:number|null, ready:boolean,
+ *                    skippedReason?:string, error?:string, portFile:string, bypass?:string}>}
+ */
+export async function ensureBridge({ flags = {}, log = (m) => process.stdout.write(m + '\n') } = {}) {
+  const config = resolveConfig({
+    modelDir: flags['model-dir'] || undefined,
+    modelId: flags.model || undefined,
+    dim: flags.dim ? Number(flags.dim) : undefined,
+    bridgeHost: flags.host || undefined,
+    bridgePort: flags.port ? Number(flags.port) : undefined,
+  });
+  const host = flags.bind || config.bridgeHost;
+  if (!LOOPBACK_RE.test(String(host))) {
+    return { ok: false, started: false, port: null, pid: null, ready: false, portFile: '', error: `只允许回环绑定（方案 §3.1），收到 ${host}` };
+  }
+  const basePort = Number(flags.port || config.bridgePort);
+  const portFile = flags['port-file']
+    ? path.resolve(String(flags['port-file']))
+    : path.join(config.vectorsDir, 'bridge-port.json');
+  const logFile = flags.log ? path.resolve(String(flags.log)) : path.join(path.dirname(portFile), 'bridge.log');
+  const recorded = readPortFile(portFile);
+  const ports = candidatePorts(basePort, recorded?.port ?? null);
+
+  // ① 探活：已在跑 → 幂等跳过（唯一权威判据 = /health，不是 pid 文件）
+  const found = await findRunningBridge({ host, ports });
+  if (found) {
+    const b = found.body;
+    writePortFile(portFile, {
+      schemaVersion: PORT_FILE_SCHEMA, host, port: found.port, pid: b.pid ?? null,
+      modelId: b.model ?? config.modelId, modelDir: b.modelDir ?? config.modelDir,
+      ready: b.ready === true, modelLoading: b.modelLoading === true,
+      startedAt: b.uptimeMs ? new Date(Date.now() - Number(b.uptimeMs)).toISOString() : null,
+      checkedAt: new Date().toISOString(), via: 'serve-start(probe)',
+    });
+    log(`[serve-start] 已在跑，跳过拉起：http://${host}:${found.port} pid=${b.pid ?? '?'} ready=${b.ready} model=${b.model ?? '?'}（台账 ${portFile}）`);
+    return { ok: true, started: false, port: found.port, pid: b.pid ?? null, ready: b.ready === true, portFile, health: b };
+  }
+
+  if (flags['no-start']) {
+    log(`[serve-start] 桥不在跑（探了 ${ports.length} 个端口），--no-start ⇒ 不拉起`);
+    return { ok: false, started: false, port: null, pid: null, ready: false, portFile, skippedReason: 'not-running' };
+  }
+
+  // ② 拉起（detached：本进程退出后桥继续活着；日志走文件，不污染调用方 stdout）
+  const serveScript = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'serve.mjs');
+  fs.mkdirSync(path.dirname(logFile), { recursive: true });
+  truncateLog(logFile);
+  const fd = fs.openSync(logFile, 'a');
+  let child;
+  try {
+    child = spawn(process.execPath, [
+      serveScript,
+      '--model-dir', config.modelDir,
+      '--port', String(basePort),
+      '--bind', host,
+    ], { detached: true, stdio: ['ignore', fd, fd], windowsHide: true });
+  } catch (e) {
+    try { fs.closeSync(fd); } catch { /* 忽略 */ }
+    return { ok: false, started: false, port: null, pid: null, ready: false, portFile, error: `spawn 失败：${e?.message ?? e}` };
+  }
+  child.unref();
+  try { fs.closeSync(fd); } catch { /* 忽略 */ }
+
+  // ③ 等 ready：按 pid 在顺延窗里定位真实端口
+  const waitMs = num(flags['wait-ms'], DEFAULT_WAIT_MS);
+  const deadline = Date.now() + waitMs;
+  let lastSeen = null;
+  while (Date.now() < deadline) {
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    for (const port of ports) {
+      // eslint-disable-next-line no-await-in-loop
+      const r = await probeHealth(port, { host, timeoutMs: PROBE_TIMEOUT_FAST_MS });
+      if (!r.ok) continue;
+      if (r.body.pid !== child.pid) continue;   // 别人占着这个端口 → 不是我们拉的那只
+      lastSeen = r;
+      if (r.body.ready === true) {
+        writePortFile(portFile, {
+          schemaVersion: PORT_FILE_SCHEMA, host, port, pid: child.pid,
+          modelId: r.body.model ?? config.modelId, modelDir: r.body.modelDir ?? config.modelDir,
+          ready: true, modelLoading: false,
+          startedAt: new Date().toISOString(), readyAt: new Date().toISOString(), checkedAt: new Date().toISOString(),
+          via: 'serve-start(spawn)', logFile,
+        });
+        log(`[serve-start] 已拉起并就绪：http://${host}:${port} pid=${child.pid} model=${r.body.model ?? '?'}`
+          + `${port !== basePort ? `（端口 ${basePort} 被占，顺延到 ${port}）` : ''} 日志 ${logFile}`);
+        return { ok: true, started: true, port, pid: child.pid, ready: true, portFile, health: r.body };
+      }
+    }
+  }
+
+  writePortFile(portFile, {
+    schemaVersion: PORT_FILE_SCHEMA, host, port: lastSeen?.port ?? basePort, pid: child.pid,
+    modelId: lastSeen?.body?.model ?? config.modelId, modelDir: config.modelDir,
+    ready: false, modelLoading: lastSeen?.body?.modelLoading ?? null,
+    startedAt: new Date().toISOString(), checkedAt: new Date().toISOString(),
+    via: 'serve-start(spawn)', logFile, error: 'not-ready-in-wait-window',
+  });
+  return {
+    ok: false, started: true, port: lastSeen?.port ?? null, pid: child.pid, ready: false, portFile,
+    error: `拉起后 ${waitMs}ms 内未就绪${lastSeen ? `（pid 已探到，modelLoading=${lastSeen.body.modelLoading}）` : '（未探到 pid）'}；日志 ${logFile}`,
+  };
+}
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = (m) => { if (!json) process.stdout.write(m + '\n'); };
+  if (flags.help) {
+    process.stdout.write('用法：node cli/serve-start.mjs [--port N] [--bind 127.0.0.1] [--model-dir P] '
+      + '[--port-file P] [--log P] [--wait-ms N] [--no-start] [--json]\n');
+    return EXIT.OK;
+  }
+  const r = await ensureBridge({ flags, log });
+  if (json) process.stdout.write(JSON.stringify(r, null, 2) + '\n');
+  if (r.ok) return EXIT.OK;
+  // 失败原因必须说人话（否则 `--bind 0.0.0.0` 这类用法错只会得到一个静默的 exit 1）
+  if (r.error) log(`[serve-start] 失败：${r.error}`);
+  return r.skippedReason === 'not-running' ? EXIT.NOT_RUNNING : EXIT.FAIL;
+}
+
+if (isMainEntry(import.meta.url)) process.exitCode = await main();

package/memory-engine/cli/sweep.mjs

@@ -0,0 +1,58 @@
+// 记忆引擎 v2 · 离线层 —— 兜底 hash 段轮转 CLI（方案 §3.1 兜底）
+//
+// 用法：
+//   node cli/sweep.mjs                  # 跑 1 段（默认 20 段轮转；每周跑一次即可）
+//   node cli/sweep.mjs --rounds 5
+//   node cli/sweep.mjs --all            # 一轮完整覆盖（= --rounds <segments>）
+//   node cli/sweep.mjs --dry-run --json
+//   node cli/sweep.mjs --source pitfall    # 坑源兜底轮转（默认 memory；坑源按 lastSeen 排序切片）
+import { isMainEntry, parseArgs, makeLogger, openRuntime, num } from '../lib/cli-util.mjs';
+import { runHashSweep } from '../lib/sweep.mjs';
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  let rt = null;
+  try {
+    rt = await openRuntime(flags);
+    const segments = num(flags.segments, rt.config.sweepSegments);
+    const rounds = flags.all ? segments : num(flags.rounds, 1);
+    const stats = await runHashSweep({
+      source: rt.source,
+      store: rt.store,
+      embedder: rt.embedder,
+      modelId: rt.config.modelId,
+      dim: rt.config.dim,
+      sourceName: rt.sourceName,
+      segments,
+      rounds,
+      dryRun: Boolean(flags['dry-run']),
+      log,
+    });
+    const out = { ok: !stats.error, source: rt.sourceName, vectorsDb: rt.config.vectorsDb, ...stats };
+    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    else {
+      log('');
+      log('=== 兜底 hash 段轮转结果 ===');
+      log(`来源         : ${rt.sourceName}`);
+      log(`id 段        : ${stats.range.lo} - ${stats.range.hi}（${stats.range.n} 条）`);
+      log(`轮转游标     : ${stats.cursorStart} → ${stats.cursorEnd} / ${stats.segments}`);
+      log(`扫描/重编码  : ${stats.scanned} / ${stats.fixed}（缺失 ${stats.missing} / 哈希不符 ${stats.mismatched}）`);
+      log(`一轮完整覆盖 : ${stats.completedFullSweep ? '是（已更新 lastFullHashSweepAt）' : '否'}`);
+      log(`耗时         : ${(stats.elapsedMs / 1000).toFixed(2)}s`);
+      if (stats.error) log(`❌ 失败      : ${stats.error}`);
+      else log('✅ 完成');
+    }
+    process.exitCode = stats.error ? 1 : 0;
+  } catch (e) {
+    const msg = String(e && e.stack ? e.stack : e);
+    if (json) process.stdout.write(JSON.stringify({ ok: false, error: msg }, null, 2) + '\n');
+    else log(`❌ ${msg}`);
+    process.exitCode = 2;
+  } finally {
+    if (rt) rt.close();
+  }
+}
+
+if (isMainEntry(import.meta.url)) await main();

package/memory-engine/cli/sync.mjs

@@ -0,0 +1,69 @@
+// 记忆引擎 v2 · 离线层 —— 增量同步 CLI
+//
+// 用法：
+//   node cli/sync.mjs                        # 增量（只读 memory.db → 写 vectors.db）
+//   node cli/sync.mjs --full                 # 全量重建（换模型/维度也自动触发）
+//   node cli/sync.mjs --dry-run              # 只算不写（计划与差异）
+//   node cli/sync.mjs --json                 # 机器可读（日志走 stderr）
+//   node cli/sync.mjs --stub-embedder        # 骨架模式（无模型依赖）
+//   node cli/sync.mjs --source pitfall       # 同步**坑库**来源（默认 memory；两来源共库、meta 分命名空间）
+//   路径可注入：--memory-db / --vectors-db / --pitfalls-file / --model-dir / --model / --dim / --batch
+import { isMainEntry, parseArgs, makeLogger, openRuntime, num } from '../lib/cli-util.mjs';
+import { runIncrementalSync } from '../lib/sync.mjs';
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  let rt = null;
+  try {
+    rt = await openRuntime(flags);
+    const stats = await runIncrementalSync({
+      source: rt.source,
+      store: rt.store,
+      embedder: rt.embedder,
+      modelId: rt.config.modelId,
+      dim: rt.config.dim,
+      sourceName: rt.sourceName,
+      batchSize: num(flags.batch, rt.config.batchSize),
+      full: Boolean(flags.full),
+      dryRun: Boolean(flags['dry-run']),
+      log,
+    });
+    const out = {
+      ok: !stats.error,
+      source: rt.sourceName,
+      // 兼容字段：默认来源（memory）时语义与旧版一致
+      memoryDb: rt.config.memoryDb,
+      dataSource: rt.source.dbPath,
+      vectorsDb: rt.config.vectorsDb,
+      modelId: rt.config.modelId,
+      ...stats,
+    };
+    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+    else {
+      log('');
+      log('=== 增量同步结果 ===');
+      log(`模式        : ${stats.mode}${stats.reasons.length ? `（${stats.reasons.join(' / ')}）` : ''}`);
+      log(`来源        : ${rt.sourceName}（${rt.source.dbPath}）`);
+      log(`向量库      : ${rt.config.vectorsDb}`);
+      log(`模型        : ${rt.config.modelId}（${rt.embedder.dim} 维）`);
+      log(`扫描/编码   : ${stats.scanned} / ${stats.encoded}（同哈希跳过 ${stats.skippedSameHash}）`);
+      log(`向量条数    : ${stats.vectorsBefore} → ${stats.vectorsAfter}`);
+      log(`水位        : ${stats.watermarkStart} → ${stats.watermarkEnd}`);
+      log(`耗时        : ${(stats.elapsedMs / 1000).toFixed(2)}s`);
+      if (stats.error) log(`❌ 失败      : ${stats.error}（进度已保留，可直接续跑）`);
+      else log('✅ 完成');
+    }
+    process.exitCode = stats.error ? 1 : 0;
+  } catch (e) {
+    const msg = String(e && e.stack ? e.stack : e);
+    if (json) process.stdout.write(JSON.stringify({ ok: false, error: msg }, null, 2) + '\n');
+    else log(`❌ ${msg}`);
+    process.exitCode = 2;
+  } finally {
+    if (rt) rt.close();
+  }
+}
+
+if (isMainEntry(import.meta.url)) await main();