@kira905/dsh-memory-toolkit 0.1.2 → 0.2.0

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

@@ -1,16 +1,19 @@
-// 记忆引擎 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 = 用法错
+// 行为约定：
+//   · 幂等 —— 权威判据是 `GET /health`（不是 pid 文件、不是端口台账）。已在跑就 exit 0，只把端口报出来，
+//     绝不重复拉起、不抢端口；
+//   · 冷启 —— spawn `serve.mjs`（detached：本进程退出后桥照样活），然后轮询 `/health` 到 `ready:true`
+//     （默认最多等 30s）；
+//   · 端口顺延 —— `serve.mjs` 自己 +1 找空位（最多 10 次）。启动器按**子进程 pid** 在 [port, port+10]
+//     里认领真实端口，并把结果落到端口台账，下游照着台账也能找到；
+//   · 不做无限重试 —— 崩了/模型还在加载就当这轮失败，下一轮 tick 会再幂等调一次；
+//   · 只许回环 —— `--bind` 给非回环一律拒（和 serve.mjs 同一条铁律，双层防呆）。
+//
+// 退出码：0 = 已在跑或拉起成功且就绪 / 1 = 拉起失败（超时、spawn 失败、非回环）
+//         3 = `--no-start` 且桥不在（纯探活模式，调用方据此让路）/ 2 = 用法错
 //
 // 用法：
 //   node cli/serve-start.mjs                        # 幂等确保 127.0.0.1:8201 在跑
@@ -27,106 +30,118 @@ import { parseArgs, num, isMainEntry } from '../lib/cli-util.mjs';
 
 export const SERVE_START_VERSION = '0.1.0';
 
-/** 与 serve.mjs 的 MAX_PORT_TRIES 保持一致（顺延搜索范围 = 同款 +1 逻辑的镜像）。 */
+/** 与 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 TIMEOUT_PROBE_MS = 1200;
+const TIMEOUT_WAIT_MS = 400;
+const POLL_GAP_MS = 500;
+const WAIT_BUDGET_MS = 30_000;
+const LOG_ROTATE_BYTES = 2 * 1024 * 1024;
+const LEDGER_SCHEMA = 1;
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
 
-const LOOPBACK_RE = /^(127\.0\.0\.1|localhost|::1)$/;
+export const EXIT = { OK: 0, FAIL: 1, USAGE: 2, NOT_RUNNING: 3 };
 
-/** `/health` 响应是否为**本编码桥**（而不是恰好占着端口的路人服务，如 3080 的 web）。 */
+/** 这条 `/health` 响应到底是不是本编码桥？（3080 那类路人服务也占端口，不能见到 200 就认） */
 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');
+  const isObj = Boolean(body) && typeof body === 'object';
+  if (!isObj) return false;
+  const flagsOk = typeof body.ready === 'boolean' && typeof body.modelLoading === 'boolean';
+  const identityOk = typeof body.model === 'string' || typeof body.dim === 'number';
+  return flagsOk && identityOk;
 }
 
-/** 单端口探活：命中返回 { 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);
+/** 探一个端口：活着且是桥 → {ok:true, port, body}；否则 {ok:false, port, error}（**不抛**）。 */
+export async function probeHealth(port, { host = '127.0.0.1', timeoutMs = TIMEOUT_PROBE_MS } = {}) {
   try {
-    const res = await fetch(`http://${host}:${port}/health`, { signal: ac.signal });
+    const res = await fetch(`http://${host}:${port}/health`, { signal: AbortSignal.timeout(timeoutMs) });
     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 };
+    return isBridgeHealth(body) ? { ok: true, port, body } : { ok: false, port, error: 'not-a-bridge' };
   } catch (e) {
-    const name = e && e.name;
-    return { ok: false, port, error: name === 'AbortError' || name === 'TimeoutError' ? 'timeout' : String(e?.message ?? e) };
-  } finally {
-    clearTimeout(t);
+    const timedOut = e?.name === 'TimeoutError' || e?.name === 'AbortError';
+    return { ok: false, port, error: timedOut ? 'timeout' : String(e?.message ?? e) };
   }
 }
 
-/** 端口台账（bridge-port.json）读取：读不到/坏 JSON 一律 null（台账是派生物，不阻断）。 */
+/** 读端口台账：台账是派生物，读不到 / 坏 JSON 一律当没有，绝不因此阻断启动。 */
 export function readPortFile(file) {
   try {
-    const txt = fs.readFileSync(file, 'utf8');
-    const obj = JSON.parse(txt);
-    return obj && typeof obj === 'object' ? obj : null;
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
   } catch {
     return null;
   }
 }
 
-/** 原子写端口台账（同目录 tmp → rename；失败不致命）。 */
+/** 写端口台账：先写同目录临时件再 rename，读者永远看不到半截 JSON。失败返回 false（不致命）。 */
 export function writePortFile(file, obj) {
+  const tmp = `${file}.tmp-${process.pid}`;
   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.writeFileSync(tmp, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
     fs.renameSync(tmp, file);
     return true;
   } catch {
+    try {
+      fs.rmSync(tmp, { force: 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;
+  const wanted = [basePort, recorded];
+  const base = Number(basePort);
+  for (let step = 1; step <= MAX_PORT_TRIES; step += 1) wanted.push(base + step);
+  const seen = new Set();
+  for (const raw of wanted) {
+    const port = Number(raw);
+    const legal = Number.isInteger(port) && port > 0 && port <= 65535;
+    if (legal) seen.add(port);
+  }
+  return [...seen];
 }
 
-/** 在候选端口里找**已在跑的桥**（顺延后仍能查到）。 */
-export async function findRunningBridge({ host = '127.0.0.1', ports = [], timeoutMs = PROBE_TIMEOUT_MS } = {}) {
+/** 在候选端口里找已经在跑的桥（顺延之后也照样能认出来）。 */
+export async function findRunningBridge({ host = '127.0.0.1', ports = [], timeoutMs = TIMEOUT_PROBE_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;
+    const hit = await probeHealth(port, { host, timeoutMs });
+    if (hit.ok) return hit;
   }
   return null;
 }
 
-function truncateLog(file) {
+/** 日志文件太大就先清空，免得它无限长。 */
+function capLog(file) {
   try {
-    const st = fs.existsSync(file) ? fs.statSync(file) : null;
-    if (st && st.size > LOG_MAX_BYTES) fs.writeFileSync(file, '', 'utf8');
-  } catch { /* 忽略 */ }
+    if (!fs.existsSync(file)) return;
+    if (fs.statSync(file).size > LOG_ROTATE_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') } = {}) {
+/** 一轮把候选端口全扫一遍：既拿到「最后见到的自家 pid」，也拿到「第一个就绪的」。 */
+async function sweepPorts({ ports, host, pid }) {
+  let seen = null;
+  for (const port of ports) {
+    // eslint-disable-next-line no-await-in-loop
+    const hit = await probeHealth(port, { host, timeoutMs: TIMEOUT_WAIT_MS });
+    if (!hit.ok || hit.body.pid !== pid) continue; // 端口上有东西但不是我们拉的那只 ⇒ 不认
+    if (hit.body.ready === true) return { ready: { ...hit, port }, seen };
+    seen = { ...hit, port };
+  }
+  return { ready: null, seen };
+}
+
+/** 解析本次要用的入口/端口/台账/日志四件套。 */
+function planTargets(flags) {
   const config = resolveConfig({
     modelDir: flags['model-dir'] || undefined,
     modelId: flags.model || undefined,
@@ -135,30 +150,57 @@ export async function ensureBridge({ flags = {}, log = (m) => process.stdout.wri
     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;
+  return {
+    config,
+    host,
+    basePort: Number(flags.port || config.bridgePort),
+    portFile,
+    logFile: flags.log ? path.resolve(String(flags.log)) : path.join(path.dirname(portFile), 'bridge.log'),
+  };
+}
+
+/**
+ * 幂等确保桥在跑 —— 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, health?:object}>}
+ */
+export async function ensureBridge({ flags = {}, log = (m) => process.stdout.write(`${m}\n`) } = {}) {
+  const target = planTargets(flags);
+  const { config, host, basePort, portFile, logFile } = target;
+
+  if (!LOOPBACK_HOSTS.has(String(host))) {
+    return {
+      ok: false, started: false, port: null, pid: null, ready: false, portFile: '',
+      error: `只允许回环绑定（收到 ${host}）`,
+    };
+  }
+
+  const ledger = readPortFile(portFile);
+  const ports = candidatePorts(basePort, ledger?.port ?? null);
+
+  // ① 先探活：已经在跑就收工（幂等点就在这一句里）
+  const alive = await findRunningBridge({ host, ports });
+  if (alive) {
+    const h = alive.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)',
+      schemaVersion: LEDGER_SCHEMA,
+      host,
+      port: alive.port,
+      pid: h.pid ?? null,
+      modelId: h.model ?? config.modelId,
+      modelDir: h.modelDir ?? config.modelDir,
+      ready: h.ready === true,
+      modelLoading: h.modelLoading === true,
+      startedAt: h.uptimeMs ? new Date(Date.now() - Number(h.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 };
+    log(`[serve-start] 已在跑，跳过拉起：http://${host}:${alive.port} pid=${h.pid ?? '?'} ready=${h.ready} model=${h.model ?? '?'}（台账 ${portFile}）`);
+    return { ok: true, started: false, port: alive.port, pid: h.pid ?? null, ready: h.ready === true, portFile, health: h };
   }
 
   if (flags['no-start']) {
@@ -166,80 +208,119 @@ export async function ensureBridge({ flags = {}, log = (m) => process.stdout.wri
     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}` };
+  // ② 拉起：detached 运行，stdout/stderr 全进日志文件，绝不污染调用方的输出
+  const child = launchBridge({ target, host, basePort });
+  if (child.error) {
+    return { ok: false, started: false, port: null, pid: null, ready: false, portFile, error: child.error };
   }
-  child.unref();
-  try { fs.closeSync(fd); } catch { /* 忽略 */ }
+  const pid = child.pid;
 
-  // ③ 等 ready：按 pid 在顺延窗里定位真实端口
-  const waitMs = num(flags['wait-ms'], DEFAULT_WAIT_MS);
-  const deadline = Date.now() + waitMs;
+  // ③ 等就绪：顺延之后真实端口靠 pid 认领
+  const waitMs = num(flags['wait-ms'], WAIT_BUDGET_MS);
+  const giveUpAt = Date.now() + waitMs;
   let lastSeen = null;
-  while (Date.now() < deadline) {
+  while (Date.now() < giveUpAt) {
     // 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 };
-      }
+    await new Promise((done) => setTimeout(done, POLL_GAP_MS));
+    // eslint-disable-next-line no-await-in-loop
+    const round = await sweepPorts({ ports, host, pid });
+    if (round.seen) lastSeen = round.seen;
+    if (round.ready) {
+      const hit = round.ready;
+      const nowIso = new Date().toISOString();
+      writePortFile(portFile, {
+        schemaVersion: LEDGER_SCHEMA,
+        host,
+        port: hit.port,
+        pid,
+        modelId: hit.body.model ?? config.modelId,
+        modelDir: hit.body.modelDir ?? config.modelDir,
+        ready: true,
+        modelLoading: false,
+        startedAt: nowIso,
+        readyAt: nowIso,
+        checkedAt: nowIso,
+        via: 'serve-start(spawn)',
+        logFile,
+      });
+      const shiftNote = hit.port !== basePort ? `（端口 ${basePort} 被占，顺延到 ${hit.port}）` : '';
+      log(`[serve-start] 已拉起并就绪：http://${host}:${hit.port} pid=${pid} model=${hit.body.model ?? '?'}${shiftNote} 日志 ${logFile}`);
+      return { ok: true, started: true, port: hit.port, pid, ready: true, portFile, health: hit.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',
+    schemaVersion: LEDGER_SCHEMA,
+    host,
+    port: lastSeen?.port ?? basePort,
+    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',
   });
+  const why = lastSeen ? `（pid 已探到，modelLoading=${lastSeen.body.modelLoading}）` : '（未探到 pid）';
   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}`,
+    ok: false, started: true, port: lastSeen?.port ?? null, pid, ready: false, portFile,
+    error: `拉起后 ${waitMs}ms 内未就绪${why}；日志 ${logFile}`,
   };
 }
 
+/** 真正 spawn 子进程（返回 pid 或 error，不外抛）。 */
+function launchBridge({ target, host, basePort }) {
+  const serveScript = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'serve.mjs');
+  const { config, logFile } = target;
+  let fd = null;
+  try {
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    capLog(logFile);
+    fd = fs.openSync(logFile, 'a');
+    const child = spawn(process.execPath, [
+      serveScript,
+      '--model-dir', config.modelDir,
+      '--port', String(basePort),
+      '--bind', host,
+    ], { detached: true, stdio: ['ignore', fd, fd], windowsHide: true });
+    child.unref();
+    return { pid: child.pid };
+  } catch (e) {
+    return { error: `spawn 失败：${e?.message ?? e}` };
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+const USAGE_PARTS = [
+  '用法：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]',
+];
+
 async function main() {
   const { flags } = parseArgs();
   const json = Boolean(flags.json);
-  const log = (m) => { if (!json) process.stdout.write(m + '\n'); };
+  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');
+    process.stdout.write(`${USAGE_PARTS.join(' ')}\n`);
     return EXIT.OK;
   }
   const r = await ensureBridge({ flags, log });
-  if (json) process.stdout.write(JSON.stringify(r, null, 2) + '\n');
+  if (json) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
   if (r.ok) return EXIT.OK;
-  // 失败原因必须说人话（否则 `--bind 0.0.0.0` 这类用法错只会得到一个静默的 exit 1）
+  // 失败一定要说人话，否则 `--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;
 }

package/memory-engine/cli/sweep.mjs

@@ -1,57 +1,96 @@
-// 记忆引擎 v2 · 离线层 —— 兜底 hash 段轮转 CLI（方案 §3.1 兜底）
+// 兜底轮转入口：按 id 段一圈一圈扫全表，重编码「正文哈希与向量库不符」和「库里压根没有」的条目。
+// 主增量路径靠 updated_at 水位，摸不到那种「改了正文却没动 updated_at」的勘误；本命令就是补它的。
 //
-// 用法：
-//   node cli/sweep.mjs                  # 跑 1 段（默认 20 段轮转；每周跑一次即可）
+//   node cli/sweep.mjs                  # 走 1 段（默认把全表切 20 段，一周跑一次足够）
 //   node cli/sweep.mjs --rounds 5
-//   node cli/sweep.mjs --all            # 一轮完整覆盖（= --rounds <segments>）
+//   node cli/sweep.mjs --all            # 一次走完一整圈（= --rounds <段数>）
 //   node cli/sweep.mjs --dry-run --json
-//   node cli/sweep.mjs --source pitfall    # 坑源兜底轮转（默认 memory；坑源按 lastSeen 排序切片）
+//   node cli/sweep.mjs --source pitfall  # 换来源（坑源按 lastSeen 排序后切片）
+//
+// 退出码：0 = 跑完 · 1 = 中途失败 · 2 = 启动即炸。
 import { isMainEntry, parseArgs, makeLogger, openRuntime, num } from '../lib/cli-util.mjs';
 import { runHashSweep } from '../lib/sweep.mjs';
 
-async function main() {
+const OK = 0;
+const FAIL_RUN = 1;
+const CRASH = 2;
+const COLUMNS = 13;
+
+/** 统一的启动三件套：原始 flag、是否机器可读、以及分好流的 logger */
+function boot() {
   const { flags } = parseArgs();
   const json = Boolean(flags.json);
-  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
-  let rt = null;
+  return { flags, json, log: makeLogger({ json, quiet: Boolean(flags.quiet) }) };
+}
+
+/** 开一个运行时，交给回调用，出了什么事都把库关掉 */
+async function withRuntime(flags, work) {
+  const rt = await openRuntime(flags);
   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;
+    return await work(rt);
   } finally {
-    if (rt) rt.close();
+    rt.close();
+  }
+}
+
+/** 起来就炸：json 走 stdout，文本走 logger，退出码固定 2 */
+function oops(json, log, err) {
+  const detail = String(err?.stack ?? err);
+  if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: detail }, null, 2)}\n`);
+  else log(`❌ ${detail}`);
+  process.exitCode = CRASH;
+}
+
+/** 中文占两格：按显示宽度补空格，冒号右对齐 */
+function field(text) {
+  let used = 0;
+  for (const ch of String(text)) used += ch.codePointAt(0) > 0xff ? 2 : 1;
+  return String(text) + ' '.repeat(Math.max(0, COLUMNS - used));
+}
+
+function report(log, sourceName, stats) {
+  const row = (name, value) => log(`${field(name)}: ${value}`);
+  log('');
+  log('=== 兜底 hash 段轮转结果 ===');
+  row('来源', sourceName);
+  row('id 段', `${stats.range.lo} - ${stats.range.hi}（${stats.range.n} 条）`);
+  row('轮转游标', `${stats.cursorStart} → ${stats.cursorEnd} / ${stats.segments}`);
+  row('扫描/重编码', `${stats.scanned} / ${stats.fixed}（缺失 ${stats.missing} / 哈希不符 ${stats.mismatched}）`);
+  row('一轮完整覆盖', stats.completedFullSweep ? '是（已更新 lastFullHashSweepAt）' : '否');
+  row('耗时', `${(stats.elapsedMs / 1000).toFixed(2)}s`);
+  if (stats.error) log(`❌ 失败      : ${stats.error}`);
+  else log('✅ 完成');
+}
+
+async function work(rt, flags, log, json) {
+  const { config, embedder, source, sourceName, store } = rt;
+  const segments = num(flags.segments, config.sweepSegments);
+  // --all 就是把段数当轮数（一次覆盖全表）；否则默认只走 1 段
+  const rounds = flags.all ? segments : num(flags.rounds, 1);
+  const stats = await runHashSweep({
+    source,
+    store,
+    embedder,
+    modelId: config.modelId,
+    dim: config.dim,
+    sourceName,
+    segments,
+    rounds,
+    dryRun: Boolean(flags['dry-run']),
+    log,
+  });
+  const out = { ok: !stats.error, source: sourceName, vectorsDb: config.vectorsDb, ...stats };
+  if (json) process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  else report(log, sourceName, stats);
+  process.exitCode = stats.error ? FAIL_RUN : OK;
+}
+
+async function main() {
+  const { flags, json, log } = boot();
+  try {
+    await withRuntime(flags, (rt) => work(rt, flags, log, json));
+  } catch (err) {
+    oops(json, log, err);
   }
 }