@kira905/dsh-memory-toolkit 0.1.3 → 0.2.0

package/memory-engine/cli/doc-index-rebuild.mjs

@@ -1,12 +1,12 @@
-// 记忆引擎 v2 · 离线层 —— 文档索引**逃生舱**（方案 §7「doc-index.db 损坏 / 陈旧 → 重建器一键全量刷新」）
+// 文档索引的「逃生舱」：库烂了 / 陈旧了，用它重建；重建前自动留快照，出事能一键盖回去。
 //
-// 用法：
-//   node cli/doc-index-rebuild.mjs                  # 一键全量刷新（范围内按 path 重跑，幂等）
-//   node cli/doc-index-rebuild.mjs --purge          # 先清空范围内全部条再重建（模拟库损坏/陈旧）
-//   node cli/doc-index-rebuild.mjs --no-snapshot    # 不写重建前快照（默认会写）
-//   node cli/doc-index-rebuild.mjs --restore <快照文件>   # 回滚：用快照覆盖当前库
-//   node cli/doc-index-rebuild.mjs --list-snapshots # 列出可用快照
-//   路径可注入：--docs-root / --dsh-root / --doc-index-db / --state-file / --home / --snapshot-dir
+// 支持的动作与开关：
+//   无开关            一键全量刷新（范围内按 path 重跑，幂等）
+//   --purge           先清空范围内的条再重建（模拟"库损坏 / 陈旧"）
+//   --no-snapshot     不留重建前快照（缺省会留）
+//   --restore <快照>  回滚：用快照覆盖当前库
+//   --list-snapshots  列出可用快照
+//   路径注入：--docs-root / --dsh-root / --doc-index-db / --state-file / --home / --snapshot-dir
 //
 // 退出码：0 成功 / 1 有失败 / 2 用法错
 import fs from 'node:fs';
@@ -16,140 +16,174 @@ import { isMainEntry, parseArgs, makeLogger } from '../lib/cli-util.mjs';
 import { runDocIndexOnce } from '../lib/doc-index.mjs';
 import { openDocIndexStore, snapshotDb } from '../lib/doc-index-store.mjs';
 
-const EXIT = { OK: 0, FAIL: 1, USAGE: 2 };
+const RC = { ok: 0, fail: 1, usage: 2 };
+const SNAP_HEAD = 'doc-index-';
+const SNAP_TAIL = '.db';
 
+/** 本地时间戳（快照文件名）：YYYYMMDD-HHMMSS。 */
+function stamp(when = new Date()) {
+  const two = (v) => `${v}`.padStart(2, '0');
+  const day = `${when.getFullYear()}${two(when.getMonth() + 1)}${two(when.getDate())}`;
+  const clock = [when.getHours(), when.getMinutes(), when.getSeconds()].map(two).join('');
+  return `${day}-${clock}`;
+}
+
+/** 落点解析：home 一定，其余三项才有默认值。 */
 function resolvePaths(flags, env = process.env) {
-  const home = path.resolve(String(flags.home || env.DSH_HOME || path.join(os.homedir(), '.dsh')));
+  const fallbackHome = path.join(os.homedir(), '.dsh');
+  const home = path.resolve(String(flags.home || env.DSH_HOME || fallbackHome));
   const vectorsDir = path.join(home, 'memory-vectors');
   const dbPath = path.resolve(String(flags['doc-index-db'] || env.DOC_INDEX_DB || path.join(vectorsDir, 'doc-index.db')));
-  const snapshotDir = path.resolve(String(flags['snapshot-dir'] || path.join(vectorsDir, 'doc-index-snapshots')));
-  return { home, vectorsDir, dbPath, snapshotDir };
+  return {
+    home,
+    vectorsDir,
+    dbPath,
+    snapshotDir: path.resolve(String(flags['snapshot-dir'] || path.join(vectorsDir, 'doc-index-snapshots'))),
+  };
 }
 
-function ts() {
-  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())}`;
-}
-
-/** 重建前快照（VACUUM INTO；库不存在则跳过——没有可备份的东西）。 */
-export function takeSnapshot({ dbPath, snapshotDir, log = () => {} }) {
-  if (!fs.existsSync(dbPath)) return { ok: true, skipped: true, reason: '库不存在（首次建库无需快照）' };
-  const dest = path.join(snapshotDir, `doc-index-${ts()}.db`);
+/** 开库 → 干活 → 无论成败都把库关掉（快照与清表都借这个壳）。 */
+function withStore(dbPath, work) {
   const store = openDocIndexStore(dbPath, { create: false });
   try {
-    snapshotDb(store.db, dest);
+    return work(store.db);
   } finally {
-    try {
-      store.db.close();
-    } catch {
-      /* ignore */
-    }
+    try { store.db.close(); } catch { /* 关不掉不盖住真正的错 */ }
   }
-  const size = fs.statSync(dest).size;
-  log(`[rebuild] 重建前快照：${dest}（${size} B）`);
-  return { ok: true, dest, size };
 }
 
-/** 列出快照（按时间倒序）。 */
+/** 重建前快照（VACUUM INTO）。库还不存在 ⇒ 没有可备份的东西，跳过即可。 */
+export function takeSnapshot({ dbPath, snapshotDir, log = () => {} }) {
+  const hasDb = fs.existsSync(dbPath);
+  if (!hasDb) return { ok: true, skipped: true, reason: '库不存在（首次建库无需快照）' };
+  const dest = path.join(snapshotDir, `${SNAP_HEAD}${stamp()}${SNAP_TAIL}`);
+  withStore(dbPath, (db) => snapshotDb(db, dest));
+  const { size } = fs.statSync(dest);
+  log(`[rebuild] 重建前快照已留：${dest}（${size} B）`);
+  return { ok: true, size, dest };
+}
+
+/** 列快照（新→旧）。目录不在 = 没有快照，不是错误。 */
 export function listSnapshots(snapshotDir) {
+  let entries;
   try {
-    return fs
-      .readdirSync(snapshotDir)
-      .filter((n) => n.startsWith('doc-index-') && n.endsWith('.db'))
-      .map((n) => ({ name: n, file: path.join(snapshotDir, n), size: fs.statSync(path.join(snapshotDir, n)).size, mtime: fs.statSync(path.join(snapshotDir, n)).mtimeMs }))
-      .sort((a, b) => b.mtime - a.mtime);
+    entries = fs.readdirSync(snapshotDir);
+  } catch {
+    return [];
+  }
+  try {
+    const picked = [];
+    for (const name of entries) {
+      const looksLikeSnap = name.startsWith(SNAP_HEAD) && name.endsWith(SNAP_TAIL);
+      if (!looksLikeSnap) continue;
+      const file = path.join(snapshotDir, name);
+      const info = fs.statSync(file);
+      picked.push({ name, file, size: info.size, mtime: info.mtimeMs });
+    }
+    picked.sort((a, b) => b.mtime - a.mtime);
+    return picked;
   } catch {
     return [];
   }
 }
 
+function existenceProblem(file, label) {
+  return fs.existsSync(file) ? null : `${label}：${file}`;
+}
+
 /**
- * 回滚：用快照覆盖当前库（先把当前库另存为 `.before-restore-<ts>`，绝不静默丢）。
- * ⚠️ WAL 副作用：覆盖前必须清掉 `-wal` / `-shm`，否则新库会被旧 WAL 污染。
+ * 回滚：快照盖回当前库。当前库先另存一份 `.before-restore-<ts>`，绝不静默丢东西。
+ * 注意覆盖前必须清 `-wal` / `-shm`，否则新库会被旧 WAL 污染。
  */
 export function restoreFromSnapshot({ dbPath, snapshotFile, log = () => {} }) {
-  if (!fs.existsSync(snapshotFile)) return { ok: false, error: `快照不存在：${snapshotFile}` };
-  if (!fs.existsSync(dbPath)) return { ok: false, error: `目标库不存在：${dbPath}` };
-  const backup = `${dbPath}.before-restore-${ts()}`;
-  fs.copyFileSync(dbPath, backup);
-  for (const suffix of ['-wal', '-shm']) {
-    const f = `${dbPath}${suffix}`;
+  const blocker = existenceProblem(snapshotFile, '快照不存在') ?? existenceProblem(dbPath, '目标库不存在');
+  if (blocker) return { ok: false, error: blocker };
+  const backup = `${dbPath}.before-restore-${stamp()}`;
+  copyFile(dbPath, backup);
+  for (const sidecar of ['-wal', '-shm']) {
+    const f = `${dbPath}${sidecar}`;
     if (fs.existsSync(f)) fs.rmSync(f, { force: true });
   }
-  fs.copyFileSync(snapshotFile, dbPath);
-  log(`[rebuild] 已回滚：${snapshotFile} → ${dbPath}（回滚前副本：${backup}）`);
+  copyFile(snapshotFile, dbPath);
+  log(`[rebuild] 快照已回滚：${snapshotFile} → ${dbPath}（回滚前副本 ${backup}）`);
   return { ok: true, backup, from: snapshotFile };
 }
 
-export async function main() {
-  const { flags } = parseArgs();
-  const json = Boolean(flags.json);
-  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
-  const { dbPath, snapshotDir, home } = resolvePaths(flags);
+function copyFile(from, to) {
+  fs.copyFileSync(from, to);
+}
 
-  try {
-    if (flags['list-snapshots']) {
-      const snaps = listSnapshots(snapshotDir);
-      if (json) process.stdout.write(JSON.stringify({ ok: true, snapshotDir, snapshots: snaps }, null, 2) + '\n');
-      else {
-        log(`快照目录：${snapshotDir}`);
-        if (!snaps.length) log('（无快照）');
-        for (const s of snaps) log(`  ${new Date(s.mtime).toLocaleString('zh-CN')}  ${s.size} B  ${s.file}`);
-      }
-      return EXIT.OK;
-    }
+/** 子命令：列快照。 */
+function cmdList({ flags, json, log, paths }) {
+  const snaps = listSnapshots(paths.snapshotDir);
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ ok: true, snapshotDir: paths.snapshotDir, snapshots: snaps }, null, 2)}\n`);
+    return RC.ok;
+  }
+  log(`快照目录：${paths.snapshotDir}`);
+  if (!snaps.length) log('（这个目录里还没有快照）');
+  for (const s of snaps) log(`  ${new Date(s.mtime).toLocaleString('zh-CN')}  ${s.size} B  ${s.file}`);
+  return RC.ok;
+}
 
-    if (typeof flags.restore === 'string') {
-      const r = restoreFromSnapshot({ dbPath, snapshotFile: path.resolve(flags.restore), log });
-      if (json) process.stdout.write(JSON.stringify({ ok: r.ok, ...r }, null, 2) + '\n');
-      return r.ok ? EXIT.OK : EXIT.FAIL;
-    }
+/** 子命令：从快照回滚。 */
+function cmdRestore({ flags, json, log, paths }) {
+  const r = restoreFromSnapshot({ dbPath: paths.dbPath, snapshotFile: path.resolve(flags.restore), log });
+  if (json) process.stdout.write(`${JSON.stringify({ ok: r.ok, ...r }, null, 2)}\n`);
+  return r.ok ? RC.ok : RC.fail;
+}
 
-    // ① 重建前快照（默认开）
-    let snapshot = { ok: true, skipped: true, reason: '--no-snapshot' };
-    if (!flags['no-snapshot'] && !flags['dry-run']) {
-      snapshot = takeSnapshot({ dbPath, snapshotDir, log });
-    }
+/** 子命令：一键重建（缺省动作）。 */
+async function cmdRebuild({ flags, json, log, paths }) {
+  // ① 先留退路（--no-snapshot / --dry-run 时不写）
+  let snapshot = { ok: true, skipped: true, reason: '--no-snapshot' };
+  const wantSnapshot = !flags['no-snapshot'] && !flags['dry-run'];
+  if (wantSnapshot) snapshot = takeSnapshot({ dbPath: paths.dbPath, snapshotDir: paths.snapshotDir, log });
 
-    // ② --purge：先清空范围内全部条（模拟"库损坏 / 陈旧"后的干净重建）
-    if (flags.purge && !flags['dry-run'] && fs.existsSync(dbPath)) {
-      const store = openDocIndexStore(dbPath, { create: false });
-      try {
-        const n = store.db.prepare('DELETE FROM doc_index').run().changes;
-        log(`[rebuild] --purge：已清空 doc_index（删除 ${Number(n) || 0} 条）`);
-      } finally {
-        try {
-          store.db.close();
-        } catch {
-          /* ignore */
-        }
-      }
-    }
+  // ② --purge：先把范围内的条清空，模拟"库烂了"从零重建
+  const canPurge = flags.purge && !flags['dry-run'] && fs.existsSync(paths.dbPath);
+  if (canPurge) {
+    const removed = withStore(paths.dbPath, (db) => db.prepare('DELETE FROM doc_index').run().changes);
+    log(`[rebuild] 清表完成：doc_index 删了 ${Number(removed) || 0} 条`);
+  }
+
+  // ③ 全量刷新：ignore 差分、按 path 覆盖，所以重跑幂等
+  const r = await runDocIndexOnce({ flags: { ...flags, rebuild: true, home: paths.home, 'doc-index-db': paths.dbPath } });
+  for (const line of r.lines) log(line);
+
+  const payload = {
+    ok: r.status !== 'failed',
+    status: r.status,
+    dbPath: paths.dbPath,
+    snapshot,
+    stats: r.stats,
+    dailyLine: r.state.lastDailyLine,
+  };
+  if (json) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  else log(`[rebuild] 收工：${r.state.lastDailyLine}`);
+  return r.status === 'failed' ? RC.fail : RC.ok;
+}
 
-    // ③ 一键全量刷新（force = 忽略差分，按 path 覆盖）
-    const r = await runDocIndexOnce({
-      flags: { ...flags, rebuild: true, home, 'doc-index-db': dbPath },
-    });
-    for (const l of r.lines) log(l);
-
-    const out = {
-      ok: r.status !== 'failed',
-      status: r.status,
-      dbPath,
-      snapshot,
-      stats: r.stats,
-      dailyLine: r.state.lastDailyLine,
-    };
-    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
-    else log(`[rebuild] 完成：${r.state.lastDailyLine}`);
-    return r.status === 'failed' ? EXIT.FAIL : EXIT.OK;
+const SUBCOMMANDS = [
+  { pick: (flags) => Boolean(flags['list-snapshots']), run: cmdList },
+  { pick: (flags) => typeof flags.restore === 'string', run: cmdRestore },
+];
+
+export async function main() {
+  const { flags } = parseArgs();
+  const asJson = Boolean(flags.json);
+  const log = makeLogger({ json: asJson, quiet: Boolean(flags.quiet) });
+  const paths = resolvePaths(flags);
+  const chosen = SUBCOMMANDS.find((c) => c.pick(flags));
+  try {
+    return await (chosen ? chosen.run({ flags, json: asJson, log, paths }) : cmdRebuild({ flags, json: asJson, log, paths }));
   } 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');
+    const msg = String(e?.stack ?? e);
+    if (asJson) process.stdout.write(`${JSON.stringify({ ok: false, error: msg }, null, 2)}\n`);
     else log(`❌ ${msg}`);
-    return EXIT.USAGE;
+    return RC.usage;
   }
 }
 
-if (isMainEntry(import.meta.url)) process.exitCode = await main();
+const launchedDirectly = isMainEntry(import.meta.url);
+if (launchedDirectly) process.exitCode = await main();

package/memory-engine/cli/doc-index.mjs

@@ -1,48 +1,57 @@
-// 记忆引擎 v2 · 离线层 —— 文档索引 CLI（方案 §3.2）
+// 文档索引 CLI（离线层）：跑一轮「文档 → 索引库」的增量同步。
 //
-// 用法：
-//   node cli/doc-index.mjs                          # 增量（默认范围 = 首期 10 篇）
-//   node cli/doc-index.mjs --all                    # 扫描面全量（⚠️ 全量是 §10 T2 触发器事项）
-//   node cli/doc-index.mjs --only docs/a.md,docs/b.md
-//   node cli/doc-index.mjs --rebuild                # 忽略差分，范围内全部重跑（按 path 覆盖，幂等）
-//   node cli/doc-index.mjs --dry-run                # 只算不写（不建库、不改 state、不写日报）
-//   node cli/doc-index.mjs --llm                    # 摘要走便宜模型（受 §3.5 成本闸）
-//   node cli/doc-index.mjs --json                   # 机器可读（日志走 stderr）
-//   路径可注入：--docs-root / --dsh-root / --doc-index-db / --state-file / --home
+// 常见用法
+//   什么都不给                     增量跑一轮，范围是首期那 10 篇
+//   --all                          扫描面全量（重活，别随手跑）
+//   --only a.md,b.md               只处理点名的几篇
+//   --rebuild                      无视差分，范围内按 path 全跑（覆盖写，重跑幂等）
+//   --dry-run                      只算不写：不建库、不动 state、不写日报
+//   --llm                          摘要改走便宜模型（同样受成本闸约束）
+//   --json                         机器可读；人话日志改走 stderr
+// 路径都能改：--docs-root / --dsh-root / --doc-index-db / --state-file / --home
 import { isMainEntry, parseArgs, makeLogger } from '../lib/cli-util.mjs';
 import { runDocIndexOnce } from '../lib/doc-index.mjs';
 
+/** 机器读 JSON，人读逐行 —— 两条路别混。 */
+function narrate(run, { json, log }) {
+  if (!json) {
+    for (const line of run.lines) log(line);
+    return;
+  }
+  const digest = {
+    ok: run.ok,
+    status: run.status,
+    exitCode: run.exitCode,
+    stats: run.stats,
+    dailyLine: run.state.lastDailyLine,
+    paths: run.state.paths,
+  };
+  process.stdout.write(`${JSON.stringify(digest, null, 2)}\n`);
+}
+
+/** 出错也要分两条路说清楚，然后按既定语义回 2。 */
+function complain(e, { json, log }) {
+  const msg = String(e?.stack ?? e);
+  if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: msg }, null, 2)}\n`);
+  else log(`❌ ${msg}`);
+  return 2;
+}
+
 export async function main() {
-  const { flags } = parseArgs();
-  const json = Boolean(flags.json);
-  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  const parsed = parseArgs();
+  const flags = parsed.flags;
+  const asJson = Boolean(flags.json);
+  const log = makeLogger({ json: asJson, quiet: Boolean(flags.quiet) });
+  const channel = { json: asJson, log };
+
   try {
-    const r = await runDocIndexOnce({ flags });
-    if (json) {
-      process.stdout.write(
-        JSON.stringify(
-          {
-            ok: r.ok,
-            status: r.status,
-            exitCode: r.exitCode,
-            stats: r.stats,
-            dailyLine: r.state.lastDailyLine,
-            paths: r.state.paths,
-          },
-          null,
-          2,
-        ) + '\n',
-      );
-    } else {
-      for (const l of r.lines) log(l);
-    }
-    process.exitCode = r.exitCode;
+    const run = await runDocIndexOnce({ flags });
+    narrate(run, channel);
+    process.exitCode = run.exitCode;
   } 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;
+    process.exitCode = complain(e, channel);
   }
 }
 
-if (isMainEntry(import.meta.url)) await main();
+const invokedDirectly = isMainEntry(import.meta.url);
+if (invokedDirectly) await main();