@kira905/dsh-memory-toolkit 0.1.2 → 0.2.0

package/memory-engine/cli/layer-migrate.mjs

@@ -0,0 +1,176 @@
+// 给记忆库加 `layer` 字段的入口。默认 dry-run；动 schema 必须先备份。
+//
+//   node memory-engine/cli/layer-migrate.mjs                                  # 干跑：只说会做什么
+//   node memory-engine/cli/layer-migrate.mjs --db <库> --apply --backup <备份路径>
+//   node memory-engine/cli/layer-migrate.mjs --db <库> --restore <备份路径>    # 干跑还原
+//   node memory-engine/cli/layer-migrate.mjs --db <库> --restore <备份路径> --apply
+//   node memory-engine/cli/layer-migrate.mjs --help
+//
+// 退出码：0 正常 · 1 迁移/复核失败 · 2 用法错 · 3 库不可读
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCli, rejectBadArgs, usageError, settle, emitJsonReport, EXIT } from '../lib/cli-strict.mjs';
+import { isMainEntry } from '../lib/cli-util.mjs';
+import { loadLayerConfig, defaultMemoryDbPath, describeConfig, splitNames } from '../lib/layers.mjs';
+import { buildPlan, applyMigration, restoreDatabase } from '../lib/layer-migrate.mjs';
+
+const HELP = `layer-migrate —— 给记忆库加「层」字段（默认干跑；动 schema 前必先备份）
+
+用法：
+  node memory-engine/cli/layer-migrate.mjs [--db <库>]                       干跑：只说会做什么
+  node memory-engine/cli/layer-migrate.mjs --db <库> --apply --backup <文件>  真加列 + 回填
+  node memory-engine/cli/layer-migrate.mjs --db <库> --restore <备份>         干跑还原
+  node memory-engine/cli/layer-migrate.mjs --db <库> --restore <备份> --apply  真还原
+  node memory-engine/cli/layer-migrate.mjs --help
+
+开关：
+  --db <path>            目标记忆库（干跑缺省 = 引擎配置里的 memory.db；--apply 必须显式给）
+  --apply                真写（缺省 dry-run，一个字节都不动）
+  --dry-run              显式声明干跑（缺省就是它；与 --apply 互斥）
+  --backup <path>        --apply 必填：动库前先把库文件备份到这里（已存在则拒写，不覆盖旧备份）
+  --restore <path>       从备份还原（默认干跑；配 --apply 才替换库文件）
+  --column <name>        层列名（缺省取配置，内置 layer）
+  --layers <a,b,c>       层名集合（缺省取配置，内置 core,recall,archival）
+  --default-layer <name> 存量行回填到哪一层（缺省取配置，内置 recall；必须在层名集合里）
+  --config <file>        换一份层配置（缺省 memory-engine/config/layers.json）
+  --json                 机器可读摘要（**只落文件**，必须配 --out）
+  --out <file>           --json 的落点
+  --quiet                少说两句
+  --help
+
+语义：
+  · 只加列 + 回填，**一行不删**：行数 / sqlite_sequence / integrity_check 三项改完复核；
+  · 幂等：列已在、空值已清零 ⇒ 第二次 --apply 一个字节都不写；
+  · 跨盘安全：备份走「写新文件 + sha 校验」，还原走「同目录临时文件 + rename」，不用跨盘 rename。
+
+退出码：0 正常 · 1 迁移或复核失败 · 2 用法错 · 3 库不可读
+`;
+
+const SPEC = {
+  db: 'string',
+  apply: 'bool',
+  'dry-run': 'bool',
+  backup: 'string',
+  restore: 'string',
+  column: 'string',
+  layers: 'string',
+  'default-layer': 'string',
+  config: 'string',
+  json: 'bool',
+  out: 'string',
+  quiet: 'bool',
+};
+
+function printPlan(plan, cfg) {
+  const say = (line) => process.stdout.write(`${line}\n`);
+  say(`库：${plan.dbPath}${plan.info.exists ? `（${plan.info.bytes} B · ${plan.info.rowCount} 行）` : ''}`);
+  say(`层配置：${describeConfig(cfg)}`);
+  if (plan.blockers.length) {
+    for (const b of plan.blockers) say(`  ❌ ${b}`);
+    return;
+  }
+  say(`列 ${cfg.column}：${plan.hasColumn ? '已在' : '不在 ⇒ 将新增（NOT NULL DEFAULT ' + cfg.defaultLayer + '）'}`);
+  say(`待回填（层为空）行数：${plan.emptyLayerRows}`);
+  if (plan.hasColumn && Object.keys(plan.histogram).length) {
+    const hist = Object.entries(plan.histogram).map(([k, v]) => `${k}=${v}`).join(' · ');
+    say(`当前层分布：${hist}`);
+  }
+  if (Object.keys(plan.outOfSet).length) {
+    say(`⚠️ 有行落在层名集合之外（不改它们，只报告）：${Object.entries(plan.outOfSet).map(([k, v]) => `${k}=${v}`).join(' · ')}`);
+  }
+  say(`整库完整性：${plan.integrity ?? '(无)'} · seq=${plan.seq}`);
+  say(
+    plan.needsAlter || plan.needsBackfill
+      ? `计划：${plan.needsAlter ? '加列' : ''}${plan.needsAlter && plan.needsBackfill ? ' + ' : ''}${plan.needsBackfill ? `回填 ${plan.emptyLayerRows} 行到「${cfg.defaultLayer}」` : ''}（dry-run：未写任何东西）`
+      : '计划：无事可做（列已在、没有空层行）⇒ 再跑 --apply 也不会写',
+  );
+}
+
+function printRestore(plan) {
+  const say = (line) => process.stdout.write(`${line}\n`);
+  say(`备份：${plan.backup.path}（${plan.backup.bytes} B · ${plan.backup.rows} 行 · sha ${String(plan.backup.sha256).slice(0, 16)}）`);
+  say(`目标：${plan.target.path}${plan.target.missing ? '（不存在，将新建）' : `（${plan.target.bytes} B · ${plan.target.rows} 行 · sha ${String(plan.target.sha256).slice(0, 16)}）`}`);
+  if (plan.sidecars.length) say(`⚠️ 目标旁有 ${plan.sidecars.join(' ')} —— 还原时会先摘掉（陈旧 WAL 配新库文件 = 直接损坏）`);
+  say(plan.applied ? `✅ 已还原（sha ${String(plan.verify.sha256).slice(0, 16)} · ${plan.verify.rows} 行 · integrity ${plan.verify.integrity}）` : 'dry-run：未替换任何文件（加 --apply 才写）');
+}
+
+function main() {
+  const parsed = parseCli(process.argv.slice(2), SPEC);
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const bad = rejectBadArgs(parsed);
+  if (bad.length) return usageError([...bad, '（--help 看用法）']);
+
+  const f = parsed.flags;
+  if (f.apply && f['dry-run']) return usageError('--apply 与 --dry-run 不能同时给（缺省就是 dry-run）');
+  const json = Boolean(f.json);
+  const quiet = Boolean(f.quiet);
+  const say = (line) => {
+    if (!quiet) process.stdout.write(`${line}\n`);
+  };
+
+  let cfg;
+  try {
+    cfg = loadLayerConfig({ file: f.config || null, layers: f.layers || null, defaultLayer: f['default-layer'] || null, column: f.column || null });
+  } catch (e) {
+    return usageError(`层配置不成立：${e.message}`);
+  }
+  for (const w of cfg.warnings) say(`⚠️ ${w}`);
+
+  const dbPath = f.db ? path.resolve(f.db) : defaultMemoryDbPath();
+  // 先把手滑闸摆好：真写必须点名库、且（迁移时）必须带备份
+  if (f.apply && !f.db) return usageError('--apply 必须显式给 --db <库>：不许靠缺省路径改到家目录那本库');
+  if (f.apply && !f.restore && !f.backup) return usageError('--apply 必须先备份：加 --backup <文件>（拒绝无备份写入）');
+  if (!fs.existsSync(dbPath)) {
+    process.stderr.write(`❌ 库不可读：${dbPath} 不存在\n`);
+    process.exitCode = EXIT.UNREADABLE;
+    return;
+  }
+
+  // ── 还原分支
+  if (f.restore) {
+    if (!fs.existsSync(f.restore)) {
+      process.stderr.write(`❌ 备份不存在：${path.resolve(f.restore)}\n`);
+      process.exitCode = EXIT.UNREADABLE;
+      return;
+    }
+    const plan = restoreDatabase({ backupPath: f.restore, dbPath, apply: Boolean(f.apply) });
+    if (!quiet) printRestore(plan);
+    emitJsonReport({ json, out: f.out, payload: { tool: 'layer-migrate', mode: 'restore', db: dbPath, ...plan } });
+    process.exitCode = EXIT.OK;
+    return;
+  }
+
+  // ── 迁移分支
+  const plan = buildPlan(dbPath, cfg);
+  if (plan.blockers.length) {
+    for (const b of plan.blockers) process.stderr.write(`❌ ${b}\n`);
+    process.exitCode = EXIT.UNREADABLE;
+    return;
+  }
+  if (!quiet) printPlan(plan, cfg);
+  if (!f.apply) {
+    emitJsonReport({ json, out: f.out, payload: { tool: 'layer-migrate', mode: 'dry-run', db: dbPath, cfg: { column: cfg.column, layers: cfg.layers, defaultLayer: cfg.defaultLayer }, plan: { ...plan, info: undefined } } });
+    process.exitCode = EXIT.OK;
+    return;
+  }
+
+  const result = applyMigration({ dbPath, cfg, backupPath: f.backup });
+  if (!quiet) {
+    if (!result.changed) say('✅ 无事可做（幂等：列已在、没有空层行）—— 一个字节都没写');
+    else {
+      say(`✅ 已加列/回填：动 ${result.touched} 行 · 备份 ${result.backup.method} → ${result.backup.path}（${result.backup.bytes} B · sha ${result.backup.sha256.slice(0, 16)}）`);
+      say(`   复核：行数不变 ${result.verify.rowCountSame} · seq 不变 ${result.verify.seqSame} · 完整性 ${result.verify.integrity} · 空层行 ${result.verify.emptyAfter}`);
+    }
+  }
+  emitJsonReport({ json, out: f.out, payload: { tool: 'layer-migrate', mode: 'apply', db: dbPath, changed: result.changed, touched: result.touched ?? 0, backup: result.backup, verify: result.verify } });
+  process.exitCode = EXIT.OK;
+}
+
+try {
+  if (isMainEntry(import.meta.url)) main();
+} catch (e) {
+  settle(e, { prefix: '[layer-migrate]' });
+}

package/memory-engine/cli/layer-move.mjs

@@ -0,0 +1,189 @@
+// 软淘汰执行器入口：把一整层搬进本库的边表（不删），一条命令出去、一条命令回来。
+//
+//   node memory-engine/cli/layer-move.mjs --db <库> --layer archival                 干跑：说会搬几行
+//   node memory-engine/cli/layer-move.mjs --db <库> --layer archival --apply          真搬（主表 → 边表）
+//   node memory-engine/cli/layer-move.mjs --db <库> --layer archival --back --apply   搬回（边表 → 主表）
+//   node memory-engine/cli/layer-move.mjs --db <库> --dump <before.json>              搬前留一份逐行指纹
+//   node memory-engine/cli/layer-move.mjs --db <库> --verify <before.json>            搬回后逐行对拍
+//
+// 退出码：0 正常 · 1 校验失败 / 保护性拒跑 · 2 用法错 · 3 库不可读
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCli, rejectBadArgs, usageError, settle, emitJsonReport, EXIT } from '../lib/cli-strict.mjs';
+import { isMainEntry } from '../lib/cli-util.mjs';
+import { loadLayerConfig, defaultMemoryDbPath, canonicalLayerName, describeConfig } from '../lib/layers.mjs';
+import {
+  planMove, moveOut, moveBack, dumpDigests, verifyAgainstDump, writeDump, readDump, EVICTED_TABLE,
+} from '../lib/layer-move.mjs';
+
+const HELP = `layer-move —— 软淘汰：整层搬走（不删），一条命令出去、一条命令回来
+
+用法：
+  node memory-engine/cli/layer-move.mjs --db <库> --layer <层>                  干跑：说会搬几行（零写）
+  node memory-engine/cli/layer-move.mjs --db <库> --layer <层> --apply          搬出：主表 → ${EVICTED_TABLE}
+  node memory-engine/cli/layer-move.mjs --db <库> --layer <层> --back --apply   搬回：${EVICTED_TABLE} → 主表
+  node memory-engine/cli/layer-move.mjs --db <库> --dump <file>                 导出逐行指纹（搬前凭据）
+  node memory-engine/cli/layer-move.mjs --db <库> --verify <file>               拿指纹件对拍当前主表
+  node memory-engine/cli/layer-move.mjs --help
+
+开关：
+  --db <path>        目标记忆库（--apply 必须显式给；干跑缺省 = 引擎配置里的 memory.db）
+  --layer <name>     要搬出/搬回的层（必须在层名集合里）
+  --apply            真写（缺省 dry-run：一个字节都不动）
+  --dry-run          显式声明干跑（缺省就是它；与 --apply 互斥）
+  --back             反向：把这一层从边表搬回主表
+  --force            搬走会清空主表时才需要的显式确认（防层名写错）
+  --dump <file>      把当前主表（或 --layer 限定的那层）的逐行指纹写成 JSON
+  --verify <file>    拿 --dump 的产物对拍：缺行 / 多行 / 内容变了 三类分开报
+  --batch <name>     批次名（缺省 evict-<时间戳>），落在边表的 batch 列
+  --column <name>    层列名（缺省取配置）
+  --layers <a,b,c>   层名集合（缺省取配置）
+  --config <file>    换一份层配置
+  --json             机器可读摘要（**只落文件**，必须配 --out）
+  --out <file>       --json 的落点
+  --quiet            少说两句
+  --help
+
+语义（别把它当删除）：
+  · 搬走的行原样躺在 ${EVICTED_TABLE} 里，带 content_sha 指纹；搬回时先核指纹再写回。
+  · 硬判据：搬出层行数 + 剩下行数 == 搬前总行数（事务内断言，不成立整批回滚）。
+  · 软淘汰省的是上下文与召回面，不是磁盘：搬走的行仍占库体积，边表也没有 FTS 索引。
+
+退出码：0 正常 · 1 校验失败或保护性拒跑 · 2 用法错 · 3 库不可读
+`;
+
+const SPEC = {
+  db: 'string',
+  layer: 'string',
+  apply: 'bool',
+  'dry-run': 'bool',
+  back: 'bool',
+  force: 'bool',
+  dump: 'string',
+  verify: 'string',
+  batch: 'string',
+  column: 'string',
+  layers: 'string',
+  config: 'string',
+  json: 'bool',
+  out: 'string',
+  quiet: 'bool',
+};
+
+const stamp = () => {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+};
+
+function main() {
+  const parsed = parseCli(process.argv.slice(2), SPEC);
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const bad = rejectBadArgs(parsed);
+  if (bad.length) return usageError([...bad, '（--help 看用法）']);
+
+  const f = parsed.flags;
+  if (f.apply && f['dry-run']) return usageError('--apply 与 --dry-run 不能同时给（缺省就是 dry-run）');
+  const say = (line) => {
+    if (!f.quiet) process.stdout.write(`${line}\n`);
+  };
+  const modes = ['dump', 'verify', 'back'].filter((k) => f[k]);
+  if (modes.length > 1) return usageError(`一次只能干一件事：${modes.map((m) => `--${m}`).join(' / ')} 互斥`);
+
+  let cfg;
+  try {
+    cfg = loadLayerConfig({ file: f.config || null, layers: f.layers || null, column: f.column || null });
+  } catch (e) {
+    return usageError(`层配置不成立：${e.message}`);
+  }
+  for (const w of cfg.warnings) say(`⚠️ ${w}`);
+
+  const dbPath = f.db ? path.resolve(f.db) : defaultMemoryDbPath();
+  if (!fs.existsSync(dbPath)) {
+    process.stderr.write(`❌ 库不可读：${dbPath} 不存在\n`);
+    process.exitCode = EXIT.UNREADABLE;
+    return;
+  }
+
+  // ── 导出指纹
+  if (f.dump) {
+    const dump = dumpDigests({ dbPath, cfg, layer: f.layer ? canonicalLayerName(cfg, f.layer) : null });
+    const out = writeDump(f.dump, dump);
+    say(`✅ 指纹已导出：${out}（${dump.count} 行 · 层=${dump.layer ?? '(全表)'}）`);
+    emitJsonReport({ json: f.json, out: f.out, payload: { tool: 'layer-move', mode: 'dump', db: dbPath, layer: dump.layer, count: dump.count, file: out } });
+    process.exitCode = EXIT.OK;
+    return;
+  }
+
+  // ── 对拍指纹
+  if (f.verify) {
+    const dump = readDump(f.verify);
+    const res = verifyAgainstDump({ dbPath, cfg, dump });
+    say(`指纹对拍：核 ${res.checked} 行 · 当前 ${res.currentCount} 行`);
+    if (res.ok) {
+      say('✅ 逐行一致（缺 0 / 多 0 / 变 0）');
+    } else {
+      say(`❌ 不一致：缺 [${res.missing.join(',')}] 多 [${res.extra.join(',')}] 变 [${res.changed.join(',')}]`);
+    }
+    emitJsonReport({ json: f.json, out: f.out, payload: { tool: 'layer-move', mode: 'verify', db: dbPath, ...res } });
+    process.exitCode = res.ok ? EXIT.OK : EXIT.FAIL;
+    return;
+  }
+
+  if (!f.layer) return usageError('缺 --layer <层>：要搬哪一层（--help 看层名集合从哪来）');
+  const layer = canonicalLayerName(cfg, f.layer);
+  if (!layer) return usageError(`「${f.layer}」不在层名集合 [${cfg.layers.join(', ')}] 里（--layers 可改，或改配置）`);
+
+  // ── 搬回
+  if (f.back) {
+    if (!f.apply) {
+      const plan = planMove({ dbPath, cfg, layer });
+      say(`干跑（搬回）：层「${layer}」在边表里有 ${plan.evictedRows} 行 · 主表 ${plan.totalRows} 行`);
+      say('dry-run：未写任何东西（加 --apply 才搬）');
+      emitJsonReport({ json: f.json, out: f.out, payload: { tool: 'layer-move', mode: 'back-dry-run', db: dbPath, layer, evicted: plan.evictedRows, total: plan.totalRows } });
+      process.exitCode = EXIT.OK;
+      return;
+    }
+    const res = moveBack({ dbPath, cfg, layer });
+    say(`✅ 搬回 ${res.restored} 行（主表 ${res.totalBefore} → ${res.totalAfter}）${res.reason ? ` · ${res.reason}` : ''}`);
+    if (res.seqBefore !== undefined && res.seqAfter !== res.seqBefore) say(`⚠️ sqlite_sequence 变了：${res.seqBefore} → ${res.seqAfter}`);
+    emitJsonReport({ json: f.json, out: f.out, payload: { tool: 'layer-move', mode: 'back', db: dbPath, layer, ...res } });
+    process.exitCode = EXIT.OK;
+    return;
+  }
+
+  // ── 搬出
+  const plan = planMove({ dbPath, cfg, layer });
+  if (plan.blockers.length) {
+    for (const b of plan.blockers) process.stderr.write(`❌ ${b}\n`);
+    process.exitCode = EXIT.UNREADABLE;
+    return;
+  }
+  say(`层配置：${describeConfig(cfg)}`);
+  say(`主表 ${plan.totalRows} 行 · 层「${layer}」${plan.layerRows} 行 · 边表已有该层 ${plan.evictedRows} 行`);
+  if (plan.leavesEmpty) say(`⚠️ 这一搬会把主表搬空（${plan.layerRows}/${plan.totalRows}）—— 真要这么干得加 --force`);
+  if (!f.apply) {
+    say('dry-run：未写任何东西（加 --apply 才搬）');
+    emitJsonReport({ json: f.json, out: f.out, payload: { tool: 'layer-move', mode: 'move-dry-run', db: dbPath, layer, plan } });
+    process.exitCode = EXIT.OK;
+    return;
+  }
+  if (!f.db) return usageError('--apply 必须显式给 --db <库>：不许靠缺省路径改到家目录那本库');
+  const batch = f.batch || `evict-${stamp()}`;
+  const res = moveOut({ dbPath, cfg, layer, batch, force: Boolean(f.force) });
+  say(`✅ 搬出 ${res.moved} 行 → ${EVICTED_TABLE}（批次 ${res.batch}）`);
+  say(`   守恒：搬出 ${res.evicted} + 剩下 ${res.remaining} = 搬前 ${res.totalBefore} ${res.evicted + res.remaining === res.totalBefore ? '✅' : '❌'}`);
+  if (res.moved === 0) say('   （这一层本来就是空的 —— 没搬任何行）');
+  if (res.seqBefore !== undefined && res.seqAfter !== res.seqBefore) say(`⚠️ sqlite_sequence 变了：${res.seqBefore} → ${res.seqAfter}`);
+  emitJsonReport({ json: f.json, out: f.out, payload: { tool: 'layer-move', mode: 'move', db: dbPath, layer, ...res } });
+  process.exitCode = EXIT.OK;
+}
+
+try {
+  if (isMainEntry(import.meta.url)) main();
+} catch (e) {
+  settle(e, { prefix: '[layer-move]' });
+}

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

@@ -1,90 +1,156 @@
-// 记忆引擎 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` 才真写。
+//   node cli/pitfall-hook.mjs --status --json        # 只看：标记现值 + 两个来源的向量条数
+//   node cli/pitfall-hook.mjs --run --json           # 预演（缺省就是不写、不清标记）
+//   node cli/pitfall-hook.mjs --run --apply --json   # 真消费（写向量 + 清标记）
+//   node cli/pitfall-hook.mjs --mark --reason "原因"  # 置标记
+//
+// 路径可注入：--marker-file / --pitfalls-file / --vectors-db / --dsh-home
+// 退出码：0 = 正常（含没标记可消费）· 1 = 消费失败（标记保留）· 2 = 起不来。
 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 OK = 0;
+const FAIL_RUN = 1;
+const CRASH = 2;
+const COLUMNS = 12;
+
+/** 统一的启动三件套：原始 flag、是否机器可读、以及分好流的 logger */
+function boot() {
   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;
+  return { flags, json, log: makeLogger({ json, quiet: Boolean(flags.quiet) }) };
+}
+
+/** 开一个运行时，交给回调用，出了什么事都把库关掉 */
+async function withRuntime(flags, work, opts) {
+  const rt = await openRuntime(flags, opts);
   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') },
-    };
+    return await work(rt);
+  } finally {
+    rt.close();
+  }
+}
 
-    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({
+/** 起来就炸：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));
+}
+
+/** 模式判定：--run 优先，其次 --mark，都没有就是 --status */
+const readMode = (flags) => ['run', 'mark'].find((k) => Boolean(flags[k])) || 'status';
+
+function banner(log, mode, apply) {
+  log(`=== 坑库向量钩子（${mode}${apply ? ' · --apply' : ' · 预演'}） ===`);
+}
+
+function report(log, out) {
+  const row = (name, value) => log(`${field(name)}: ${value}`);
+  row('标记文件', out.markerPath);
+  row('坑库', out.pitfallsFile);
+  row('向量库', out.vectorsDb);
+  row('向量条数', `memory=${out.counts.memory} / pitfall=${out.counts.pitfall}`);
+  const hook = out.hook;
+  if (out.mode === 'status') {
+    const unread = !out.marker.present && out.marker.error;
+    const shown = out.marker.present ? JSON.stringify(out.marker.value) : '无';
+    row('标记', unread ? `${shown}（读失败：${out.marker.error}）` : shown);
+  }
+  if (out.mode === 'mark') row('已置标记', `updatedAt=${out.mark.updatedAt}`);
+  if (hook) {
+    const skip = hook.skipped ? `（${hook.skipped}）` : '';
+    row('钩子结果', `${hook.ok ? '✅' : '❌'} ${skip}`);
+    if (hook.stats) {
+      const s = hook.stats;
+      row('同步', `扫 ${s.scanned} / 编码 ${s.encoded}（跳过 ${s.skippedSameHash}）向量 ${s.vectorsBefore} → ${s.vectorsAfter}`);
+    }
+    row('清标记', JSON.stringify(hook.cleared));
+    row('向量条数', `memory=${out.countsAfter.memory} / pitfall=${out.countsAfter.pitfall}`);
+  }
+}
+
+/** 三种模式各交一段「往结果上补的字段」；消费是唯一异步的那个 */
+function handlersFor(ctx) {
+  const { rt, flags, markerPath, apply, tally, log } = ctx;
+  return {
+    status() {
+      const seen = readMarker(markerPath);
+      return { marker: { present: seen.present, value: seen.marker, error: seen.error } };
+    },
+    mark() {
+      const reason = flags.reason === undefined || flags.reason === true ? null : String(flags.reason);
+      return { mark: markDirty(markerPath, { reason, by: 'cli/pitfall-hook.mjs' }) };
+    },
+    async run() {
+      const { config, embedder, store } = rt;
+      const hook = await runPitfallHook({
         markerPath,
-        store: rt.store,
-        // ⚠️ 必须是**坑源**：默认来源（memory）会被 runPitfallHook 的守卫拒掉
+        store,
+        // 必须是坑源：别的来源会被 runPitfallHook 的守卫直接拒掉
         source: rt.openSource('pitfall'),
-        embedder: rt.embedder,
-        modelId: rt.config.modelId,
-        dim: rt.config.dim,
-        batchSize: num(flags.batch, rt.config.batchSize),
+        embedder,
+        modelId: config.modelId,
+        dim: config.dim,
+        batchSize: num(flags.batch, config.batchSize),
         full: Boolean(flags.full),
         dryRun: !apply,
         log,
       });
-      out.countsAfter = {
-        memory: countVectors(rt.store.db, 'memory'),
-        pitfall: countVectors(rt.store.db, 'pitfall'),
-      };
-    }
+      return { hook, countsAfter: tally() };
+    },
+  };
+}
 
-    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();
+async function work(rt, flags, ctx) {
+  const { json, log, mode } = ctx;
+  const { config, store } = rt;
+  const apply = Boolean(flags.apply);
+  const markerPath = config.pitfallVectorDirtyFile;
+  const tally = () => ({ memory: countVectors(store.db, 'memory'), pitfall: countVectors(store.db, 'pitfall') });
+  const out = {
+    ok: true,
+    mode,
+    apply,
+    markerPath,
+    pitfallsFile: config.pitfallsFile,
+    vectorsDb: config.vectorsDb,
+    counts: tally(),
+  };
+  Object.assign(out, await handlersFor({ rt, flags, markerPath, apply, tally, log })[mode]());
+  if (json) process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  else {
+    banner(log, mode, apply);
+    report(log, out);
+  }
+  const failed = out.hook !== undefined && out.hook.ok === false;
+  process.exitCode = failed ? FAIL_RUN : OK;
+}
+
+async function main() {
+  const { flags, json, log } = boot();
+  const mode = readMode(flags);
+  try {
+    // 钩子只关心坑源 ⇒ 不预开默认来源（默认来源会被守卫拒掉）；非 run 模式连编码器都不建
+    await withRuntime(flags, (rt) => work(rt, flags, { json, log, mode }), {
+      withSource: false,
+      withEmbedder: mode === 'run',
+    });
+  } catch (err) {
+    oops(json, log, err);
   }
 }