@kira905/dsh-memory-toolkit 0.1.2 → 0.2.0

package/memory-engine/cli/recall.mjs

@@ -1,11 +1,21 @@
-// 记忆引擎 v2 · 离线层 —— 召回 CLI（向量 + FTS 补位 + RRF 融合 + 排除 pinned）
+// 召回入口：向量召回 + FTS 补位 + 倒数排名融合，pinned 条目全程排除。
+// 这里只管参数整形与结果排版；召回算法在 ../lib/recall.mjs。
 //
-// 用法：
-//   node cli/recall.mjs --query "退下吧" [--top-k 8]
+// 常用姿势：
+//   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 跨源融合）
+//   node cli/recall.mjs --query "..." --repeat 100              # 连跑取分位数
+//   node cli/recall.mjs --query "..." --source pitfall          # 换来源（缺省 memory）
+//   node cli/recall.mjs --query "..." --sources memory,pitfall  # 多来源跨源融合
+//
+// 本版新增（都是可选开关，不改变既有默认行为）：
+//   node cli/recall.mjs --query "..." --lexicon on               # 打开词表第二路（默认读 dict/lexicon-config.json）
+//   node cli/recall.mjs --query "..." --fallback-top-k 8         # 编码失败时的固定兜底条数
+//   node cli/recall.mjs --query "..." --encode-timeout-ms 1500   # 编码预算
+//   node cli/recall.mjs --query "..." --recall-log <目录>         # 旁路留痕（默认不写）
+//
+// 退出码：0 = 正常跑完（未触发也算正常）· 2 = 起不来/跑炸（--json 时错误也只上 stdout 的 JSON）。
+import path from 'node:path';
 import { isMainEntry, parseArgs, makeLogger, openRuntime, num } from '../lib/cli-util.mjs';
 import {
   recall,
@@ -14,118 +24,241 @@ import {
   shouldTrigger,
   extractFtsTokens,
   buildFtsMatch,
+  truncateQuery,
+  QUERY_CHAR_LIMIT,
+  ENCODE_TIMEOUT_MS,
+  FALLBACK_TOP_K,
 } from '../lib/recall.mjs';
+import { getLexiconIndex, resolveLexiconSwitch } from '../lib/lexicon-recall.mjs';
+import { openRecallLog } from '../lib/recall-log.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;
-}
+const CLEAN = 0;
+const CRASH = 2;
+const COLUMNS = 12;
 
-async function main() {
+/** 统一的启动三件套：原始 flag、是否机器可读、以及分好流的 logger */
+function boot() {
   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;
+  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 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);
+    return await work(rt);
+  } finally {
+    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));
+}
+
+const row = (log, name, value) => log(`${field(name)}: ${value}`);
+
+const readQuery = (flags) => (flags.query === undefined || flags.query === true ? '' : String(flags.query));
+
+/** `--sources a,b` → ['a','b']；没给 / 给了空 ⇒ null（退回单来源那条路） */
+function pickNames(flags) {
+  const raw = flags.sources;
+  if (raw === undefined || raw === true || raw === '') return null;
+  const names = String(raw).split(',').map((s) => s.trim()).filter(Boolean);
+  return names.length ? names : null;
+}
+
+/** 分位数取最接近那条（不插值，和原来一致） */
+const at = (sorted, pct) => sorted[Math.min(sorted.length - 1, Math.floor((pct / 100) * sorted.length))];
+
+/** 三态开关：`--lexicon`（裸）= 开；`--lexicon on/off` 两种写法都认；没给 ⇒ null（读配置文件）。 */
+function triState(raw, name) {
+  if (raw === undefined) return null;
+  if (raw === true) return true;
+  const text = String(raw).trim().toLowerCase();
+  if (['on', '1', 'true', 'yes', 'enable', 'enabled'].includes(text)) return true;
+  if (['off', '0', 'false', 'no', 'disable', 'disabled'].includes(text)) return false;
+  throw new Error(`--${name} 只认 on / off（收到 ${JSON.stringify(String(raw))}）`);
+}
+
+/** 单来源一轮：建一次向量索引（词表路开着就顺手建好词表索引，省一次预热等待） */
+async function singleRound(rt, opts, log) {
+  const { store, source, sourceName, embedder } = rt;
+  const index = buildVectorIndex(store.db, { source: sourceName });
+  const lexiconIndex = opts.lexiconEnabled ? getLexiconIndex(source, { allowBuild: true }) : null;
+  const res = await recall({
+    query: opts.query, store, source, embedder, index, sourceName,
+    vectorTopK: opts.vectorTopK, ftsTopK: opts.ftsTopK, rrfK: opts.rrfK, resultTopK: opts.topK,
+    queryCharLimit: opts.queryCharLimit, encodeTimeoutMs: opts.encodeTimeoutMs, fallbackTopK: opts.fallbackTopK,
+    lexiconEnabled: opts.lexiconEnabled, lexiconTopK: opts.lexiconTopK, lexiconFloor: opts.lexiconFloor,
+    lexiconIndex, recallLog: opts.recallLog,
+    log,
+  });
+  return { size: index.count, res };
+}
+
+/** 多来源一轮：每源各建索引、各出候选，融合交给 recallMulti */
+async function fusedRound(rt, opts, log) {
+  const { store, embedder } = rt;
+  const entries = opts.names.map((name) => ({
+    name, source: rt.openSource(name), index: buildVectorIndex(store.db, { source: name }),
+  }));
+  const res = await recallMulti({
+    query: opts.query, store, entries, embedder,
+    perSourceTopK: opts.perSource, rrfK: opts.rrfK, resultTopK: opts.topK,
+    queryCharLimit: opts.queryCharLimit, encodeTimeoutMs: opts.encodeTimeoutMs,
+    lexiconEnabled: opts.lexiconEnabled, lexiconTopK: opts.lexiconTopK, lexiconFloor: opts.lexiconFloor,
+    recallLog: opts.recallLog,
+    log,
+  });
+  return { size: entries.reduce((sum, e) => sum + (e.index.count || 0), 0), res };
+}
+
+function printHit(log, hit, multi) {
+  const owner = multi ? ` [${hit.source}]` : '';
+  const vec = hit.vectorRank ?? '-';
+  const fts = hit.ftsRank ?? '-';
+  const lex = hit.lexiconRank == null ? '' : `  lexRank=${hit.lexiconRank}`;
+  const fallback = hit.fallbackRank == null ? '' : `  fallback=${hit.fallbackRank}`;
+  log(`  #${hit.refId}${owner}  score=${hit.score.toFixed(5)}  来源=${hit.sources.join('+')}  vecRank=${vec} ftsRank=${fts}${lex}${fallback}`);
+}
+
+function printReport(log, out, last, names, repeat, times) {
+  const multi = Boolean(names);
+  const timings = last.timings;
+  log('=== 召回 ===');
+  row(log, '来源', out.source);
+  row(log, '查询', JSON.stringify(out.query));
+  row(log, '触发', last.triggered ? `是（${last.reason}）` : `否（${last.reason}）`);
+  if (last.triggered) {
+    const stats = last.stats || {};
+    if (stats.queryTruncated) {
+      row(log, '查询截断', `${stats.queryChars} → ${stats.queryCharsUsed} 字符（上限 ${stats.queryCharLimit}）`);
     }
-    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`);
+    // 降级是「这一轮记忆从哪来的」的判据：显眼打出来，别让 SLI 只看到"有命中"
+    row(log, '降级', last.degraded
+      ? `是（${last.degraded.mode} / ${last.degraded.reason}）→ 固定 Top-${last.hits.length}`
+      : '否');
+    if (multi) {
+      Object.entries(last.perSource || {}).forEach(([name, rec]) => log(
+        `  · ${name}: 索引 ${rec.indexSize} 条 / 排除 pinned ${rec.pinnedExcluded} / 向量命中 ${rec.vectorHits} / FTS 命中 ${rec.ftsHits}${rec.lexiconHits ? ` / 词表命中 ${rec.lexiconHits}` : ''}${rec.fallbackHits ? ` / 兜底 ${rec.fallbackHits}` : ''}${rec.error ? ` / ⚠️ ${rec.error}` : ''}`,
+      ));
+    } else {
+      row(log, '索引规模', `${stats.indexSize} 条向量 / 排除 pinned ${stats.pinnedExcluded} 条`);
+      row(log, 'FTS 补位', stats.ftsSkipped
+        ? '本轮跳过（编码降级）'
+        : `tokens=${JSON.stringify(stats.ftsTokens)} → 命中 ${stats.ftsMatched}`);
+      row(log, '词表路', stats.lexiconEnabled
+        ? `开（${stats.lexiconStatus}${stats.lexiconHits ? ` / 命中 ${stats.lexiconHits}` : ''}${stats.lexiconBuildMs != null ? ` / 建索引 ${stats.lexiconBuildMs}ms` : ''}）`
+        : `关（${stats.lexiconSwitchSource || 'default'}）`);
     }
-    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();
+    const lexiconMs = timings.lexiconMs == null ? '' : `词表 ${timings.lexiconMs.toFixed(1)}ms / `;
+    row(
+      log,
+      '耗时',
+      `编码 ${timings.encodeMs.toFixed(1)}ms / 向量 ${timings.vectorMs.toFixed(1)}ms / ${lexiconMs}融合 ${timings.fuseMs.toFixed(1)}ms / 合计 ${timings.totalMs.toFixed(1)}ms`,
+    );
+    log('命中 top-' + last.hits.length + '：');
+    last.hits.forEach((hit) => printHit(log, hit, multi));
+  }
+  if (out.recallLog) row(log, '留痕', out.recallLog.file);
+  if (repeat > 1) {
+    log(`重复 ${times.length} 次：P50 ${at(times, 50).toFixed(1)}ms / P95 ${at(times, 95).toFixed(1)}ms`);
+  }
+}
+
+async function work(rt, flags, log, json) {
+  const { config, sourceName } = rt;
+  const query = readQuery(flags);
+  const names = pickNames(flags);
+  const repeat = num(flags.repeat, 1);
+  // 词表开关：命令行 > 环境变量 > dict/lexicon-config.json > 默认（关）
+  const lexiconSetting = resolveLexiconSwitch({
+    enabled: triState(flags.lexicon, 'lexicon'),
+    topK: num(flags['lexicon-top-k'], null),
+    floor: num(flags['lexicon-floor'], null),
+  });
+  // 留痕：给了 --recall-log 才写；--no-recall-log 或 DSH_MEMORY_RECALL_LOG=off 一键关回
+  const wantedLog = flags['no-recall-log'] ? false : flags['recall-log'] === undefined ? null : true;
+  const logDir = flags['recall-log'] === true
+    ? path.join(config.dshHome, 'logs', 'memory-recall')
+    : typeof flags['recall-log'] === 'string' ? flags['recall-log'] : null;
+  const recallLog = wantedLog === false ? null : openRecallLog({ dir: logDir, enabled: wantedLog, env: process.env });
+
+  const opts = {
+    query,
+    names,
+    perSource: num(flags['per-source-top-k'], 5),
+    vectorTopK: num(flags['vector-top-k'], config.vectorTopK),
+    ftsTopK: num(flags['fts-top-k'], config.ftsTopK),
+    rrfK: num(flags['rrf-k'], config.rrfK),
+    topK: num(flags['top-k'], config.resultTopK),
+    queryCharLimit: num(flags['query-max-chars'], QUERY_CHAR_LIMIT),
+    encodeTimeoutMs: num(flags['encode-timeout-ms'], ENCODE_TIMEOUT_MS),
+    fallbackTopK: num(flags['fallback-top-k'], FALLBACK_TOP_K),
+    lexiconEnabled: lexiconSetting.enabled,
+    lexiconTopK: lexiconSetting.topK,
+    lexiconFloor: lexiconSetting.floor,
+    recallLog,
+  };
+  // 连跑 --repeat 次只为拿分位数：每轮的结果都覆盖，只留最后一轮做展示
+  const run = { times: [], last: null, indexSize: 0 };
+  while (run.times.length < repeat) {
+    const done = await (names ? fusedRound : singleRound)(rt, opts, log);
+    run.indexSize = done.size;
+    run.last = done.res;
+    run.times.push(done.res.timings.totalMs);
+  }
+  run.times.sort((a, b) => a - b);
+  const shaped = truncateQuery(query, opts.queryCharLimit);
+  const tokens = extractFtsTokens(shaped.text);
+  const out = {
+    ok: true,
+    source: names ? names.join(',') : sourceName,
+    vectorsDb: config.vectorsDb,
+    indexSize: run.indexSize,
+    gate: shouldTrigger(shaped.text),
+    ftsTokens: tokens,
+    ftsMatchExpr: buildFtsMatch(tokens),
+    lexicon: {
+      enabled: lexiconSetting.enabled,
+      switchSource: lexiconSetting.source,
+      topK: lexiconSetting.topK,
+      floor: lexiconSetting.floor,
+    },
+    recallLog: recallLog ? { file: recallLog.file, stats: recallLog.stats() } : null,
+    ...run.last,
+    repeat: {
+      n: run.times.length,
+      p50: at(run.times, 50),
+      p95: at(run.times, 95),
+      min: run.times[0],
+      max: run.times[run.times.length - 1],
+    },
+  };
+  if (json) process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  else printReport(log, out, run.last, names, repeat, run.times);
+  process.exitCode = CLEAN;
+}
+
+async function main() {
+  const { flags, json, log } = boot();
+  try {
+    await withRuntime(flags, (rt) => work(rt, flags, log, json));
+  } catch (err) {
+    oops(json, log, err);
   }
 }
 

package/memory-engine/cli/selfcheck.mjs

@@ -1,56 +1,105 @@
-// 记忆引擎 v2 · 离线层 —— 启动自检 CLI
+// 启动自检入口：把「向量表在不在 / schema 对不对 / 编码器活不活 / 维度合不合 / 库是不是本机的」一次问清，
+// 顺带报一行各来源的向量覆盖度。warn 不算失败 —— 自检结果只是给人看和给调用方判断降级用。
 //
-// 用法：node cli/selfcheck.mjs [--json] [--stub-embedder] [--memory-db X] [--vectors-db Y] [--model-dir Z]
-// 退出码：0 = 全过（warn 不算失败）· 1 = 有 fail · 2 = 运行异常
+//   node cli/selfcheck.mjs [--json] [--stub-embedder] [--memory-db X] [--vectors-db Y] [--model-dir Z]
+//
+// 退出码：0 = 没有 fail 项（warn 照旧 0）· 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: 'ℹ️ ' };
+const OK = 0;
+const FAIL_CHECK = 1;
+const CRASH = 2;
+const COLUMNS = 12;
 
-async function main() {
+const MARKS = new Map([
+  ['ok', '✅'],
+  ['warn', '⚠️ '],
+  ['fail', '❌'],
+  ['info', 'ℹ️ '],
+]);
+
+/** 统一的启动三件套：原始 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 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;
+    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, view, result) {
+  const row = (name, value) => log(`${field(name)}: ${value}`);
+  log('=== 启动自检 ===');
+  row('主机', view.host);
+  row('记忆库', view.memoryDb);
+  row('向量库', view.vectorsDb);
+  row('编码器', JSON.stringify(view.embedder));
+  log('');
+  result.checks.forEach((c) => log(`${MARKS.get(c.status) || '·'} ${c.name}：${c.detail}`));
+  log('');
+  log(result.ok ? `✅ 自检通过（warn ${result.warned}）` : `❌ 自检失败（fail ${result.failed}）`);
+}
+
+async function work(rt, flags, log, json) {
+  const { config, embedder, source, store } = rt;
+  const result = await runSelfcheck({
+    store,
+    source,
+    embedder,
+    config,
+    // 缺省容忍 hostId 不一致（只告警）；--strict-host 才当失败
+    allowHostMismatch: !flags['strict-host'],
+  });
+  const described = embedder.describe();
+  const out = {
+    ok: result.ok,
+    host: config.hostId,
+    memoryDb: config.memoryDb,
+    vectorsDb: config.vectorsDb,
+    modelId: config.modelId,
+    modelDir: config.modelDir,
+    embedder: described,
+    ...result,
+  };
+  if (json) process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  else {
+    report(log, {
+      host: config.hostId, memoryDb: config.memoryDb, vectorsDb: config.vectorsDb, embedder: described,
+    }, result);
+  }
+  process.exitCode = result.ok ? OK : FAIL_CHECK;
+}
+
+async function main() {
+  const { flags, json, log } = boot();
+  try {
+    await withRuntime(flags, (rt) => work(rt, flags, log, json));
+  } catch (err) {
+    oops(json, log, err);
   }
 }