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

package/memory-engine/cli/distill.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// 记忆引擎 v2 · S3c —— 提炼 CLI（`cli/distill.mjs`）
+//
+// 用法：
+//   node cli/distill.mjs --db <memory.db> [选项]              # 默认 **dry-run**（只打印不写库）
+//   node cli/distill.mjs --db <memory.db> --apply             # 真跑：调模型 + 写库 + 写 state
+//
+// 选项：
+//   --db <path>            记忆库（**必填**，无默认 —— 写死生产路径是明令禁止的）
+//   --vectors-db <path>    向量库（默认 <home>/memory-vectors/vectors.db；home = db 的上上级）
+//   --state <path>         提炼 state（默认 <home>/butler-distill-state.json）
+//   --owner-user <id>      本机 owner 的 userid（缺省由身份表解析；解析不出 ⇒ **本轮 0 调用**）
+//   --window-hours <n>     增量窗口（默认 24）
+//   --limit <n>            输入条数上限（默认 0 = 不限）
+//   --max-calls / --max-tokens   成本闸（默认 20 次 / 150000 token 每日）
+//   --model / --base-url   模型档（默认 deepseek-flash @ 本鱼链；2026-09-21 主人拍板，不许改回第三方）
+//   --sim-threshold <f>    聚类余弦阈值（默认 0.60）
+//   --min-cluster-chars <n> 整组正文合计低于此值不调模型（默认 120）
+//   --min-cluster-size <n>  组内少于 N 条不提炼（默认 **2**：单条自成一组不算聚类，且少写几条以护住 memory:recall 段）
+//   --max-clusters <n>     单轮最多处理几组（默认 20）
+//   --now <iso>            以某个时刻为"现在"（演练/三天不自我指涉模拟用）
+//   --snapshot-dir <path>  写库前 `VACUUM INTO` 快照目录
+//   --no-dirty-probe       不跑全表 hash 比对（不读 memories_dirty 补充源）
+//   --daily-report <file>  追加/替换日报段（默认：今天的 <workspace>/docs/管家报告/<日期>-<设备>.md）
+//   --no-daily             不写日报段
+//   --json                 机器可读（stdout 只出 JSON，日志走 stderr）
+//   --quiet / --help
+//
+// 退出码：0 = 正常（含"没活干"）/ 1 = 失败 / 2 = 用法错 / 3 = 环境不可用（库不在）
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMainEntry, parseArgs, makeLogger, num } from '../lib/cli-util.mjs';
+import {
+  runDistill, readState, renderDailyLine, updateDailySection, dailyReportPath,
+  COST_LIMITS, DEFAULT_LLM, DEFAULT_WINDOW_HOURS, CLUSTER_DEFAULTS, STATE_SCHEMA,
+} from '../lib/distill.mjs';
+
+const USAGE = 'node cli/distill.mjs --db <memory.db> [--apply] [--window-hours 24] [--limit N] '
+  + '[--max-calls 20] [--max-tokens 150000] [--max-clusters 20] [--min-cluster-size 2] [--min-cluster-chars 120] '
+  + '[--model deepseek-flash] [--now <iso>] [--snapshot-dir <dir>] [--daily-report <file>] [--no-dirty-probe] '
+  + '[--no-daily] [--json] [--help]';
+
+/** 解析「本机 owner 的 userid」：权威实现优先，其次 fork 自检镜像，最后内置回落（与 domain-tags 同口径）。 */
+async function resolveOwnerUser(explicit, home) {
+  if (explicit) return { user: explicit, source: 'cli' };
+  const cands = ['../../memory-db-tools/lib/memory-scope.mjs', '../dsh-memory-local/src/schema-migrate.mjs'];
+  for (const rel of cands) {
+    try {
+      const mod = await import(new URL(rel, import.meta.url).href);
+      const identity = mod.readIdentityTable ? mod.readIdentityTable(home) : null;
+      const r = mod.resolveDefaultOwner ? mod.resolveDefaultOwner(identity) : null;
+      if (r && r.ownerUser) return { user: r.ownerUser, source: `${rel} (${r.source})`, notes: r.notes ?? [] };
+    } catch { /* 试下一个候选 */ }
+  }
+  return { user: null, source: '解析失败（两条权威源都不可用）', notes: ['⚠️ 本机 owner 解析不出来 ⇒ 按 D2 从严：本轮不调用任何第三方模型'] };
+}
+
+async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  if (flags.help) { process.stdout.write(`用法：${USAGE}\n`); return 0; }
+
+  const dbPath = flags.db ? path.resolve(String(flags.db)) : null;
+  if (!dbPath) {
+    process.stderr.write('用法错：必须给 --db <库路径>（本脚本没有默认库路径）\n');
+    return 2;
+  }
+  if (!fs.existsSync(dbPath)) {
+    process.stderr.write(`环境不可用：库不存在 ${dbPath}\n`);
+    return 3;
+  }
+
+  const home = path.resolve(flags.home ? String(flags.home) : path.dirname(path.dirname(dbPath)));
+  const vectorsDb = flags['vectors-db'] ? path.resolve(String(flags['vectors-db'])) : path.join(home, 'memory-vectors', 'vectors.db');
+  const stateFile = flags.state ? path.resolve(String(flags.state)) : path.join(home, 'butler-distill-state.json');
+  const apply = Boolean(flags.apply);
+  const now = flags.now ? Date.parse(String(flags.now)) : Date.now();
+  if (!Number.isFinite(now)) { process.stderr.write(`用法错：--now 不是合法时间：${flags.now}\n`); return 2; }
+  const limits = {
+    callsPerDay: num(flags['max-calls'], COST_LIMITS.callsPerDay),
+    tokensPerDay: num(flags['max-tokens'], COST_LIMITS.tokensPerDay),
+  };
+  const owner = await resolveOwnerUser(flags['owner-user'] ? String(flags['owner-user']) : null, home);
+  const snapshotDir = flags['snapshot-dir'] ? path.resolve(String(flags['snapshot-dir'])) : null;
+
+  log(`库      : ${dbPath}`);
+  log(`向量库  : ${vectorsDb}`);
+  log(`state   : ${stateFile}`);
+  log(`本机 owner: ${owner.user ?? '(未解析)'}（来源 ${owner.source}）`);
+  log(`模型    : ${flags.model ? String(flags.model) : DEFAULT_LLM.model}（成本闸 ≤${limits.callsPerDay} 次 / ≤${limits.tokensPerDay} token 每日）`);
+  log(`模式    : ${apply ? 'APPLY（写库）' : 'DRY-RUN（只打印不写库）'}`);
+  for (const n of owner.notes ?? []) log(`⚠️ ${n}`);
+
+  const r = await runDistill({
+    memoryDb: dbPath, vectorsDb, stateFile, now,
+    windowHours: num(flags['window-hours'], DEFAULT_WINDOW_HOURS),
+    apply,
+    limits,
+    model: flags.model ? String(flags.model) : DEFAULT_LLM.model,
+    baseUrl: flags['base-url'] ? String(flags['base-url']) : DEFAULT_LLM.baseUrl,
+    localOwner: owner.user,
+    limit: num(flags.limit, 0),
+    simThreshold: num(flags['sim-threshold'], CLUSTER_DEFAULTS.simThreshold),
+    minClusterChars: num(flags['min-cluster-chars'], CLUSTER_DEFAULTS.minClusterChars),
+    minClusterSize: num(flags['min-cluster-size'], CLUSTER_DEFAULTS.minClusterSize),
+    maxClustersPerRun: num(flags['max-clusters'], CLUSTER_DEFAULTS.maxClustersPerRun),
+    dirtyProbe: !flags['no-dirty-probe'],
+    snapshotFile: snapshotDir ? path.join(snapshotDir, `memory-before-distill-${new Date(now).toISOString().replace(/[:.]/g, '-')}.db`) : null,
+    log,
+  });
+
+  // 不调模型（dry-run / 环境问题）时也要留一行可查的"当日成本"，方便日报段
+  const state = r.state ?? readState(stateFile, dbPath, new Date(now).toISOString());
+  const dailyLine = r.dailyLine ?? renderDailyLine({ mode: r.mode, run: r.run ?? {}, cost: state.cost, limits, stopping: r.stopping });
+
+  let daily = { ok: false, reason: '未写日报（--no-daily）' };
+  if (!flags['no-daily'] && apply) {
+    const file = flags['daily-report'] ? path.resolve(String(flags['daily-report'])) : dailyReportPath({ now });
+    daily = updateDailySection({ file, line: dailyLine });
+    if (daily.ok) log(`日报段已更新：${file}（${daily.replaced ? '替换既有段' : '追加新段'}）`);
+    else log(`日报段未写：${daily.reason}（${file}）`);
+  }
+
+  const out = {
+    ok: r.ok, mode: r.mode, at: new Date(now).toISOString(),
+    db: dbPath, vectorsDb, stateFile, model: DEFAULT_LLM.model, ownerUser: owner.user, ownerSource: owner.source,
+    limits, inputs: r.inputs, clusterStats: r.clusterStats ?? null, dirty: r.dirty ?? null,
+    planned: r.planned, calls: r.calls, written: r.written, writtenIds: r.writtenIds,
+    cost: state.cost ?? null, stopping: r.stopping, warnings: r.warnings, dailyLine, daily,
+    snapshot: r.snapshot ?? null,
+  };
+  if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  else {
+    log('');
+    log(`输入 ${r.inputs?.accepted ?? 0} 条（窗口 ${r.inputs?.windowRows ?? 0} / 台账 ${r.inputs?.dirtyRows ?? 0}）⇒ 接受 ${r.inputs?.accepted ?? 0}`);
+    log(`聚类 ${r.clusterStats?.clusters ?? 0} 组（单条组 ${r.clusterStats?.singletonClusters ?? 0} · 无向量 ${r.clusterStats?.noVector ?? 0}）`);
+    for (const p of r.planned ?? []) log(`  ${p.action === 'call' ? '→ 调模型' : '· 跳过  '} ${p.key} ids=[${p.ids.join(',')}] ${p.action}${p.chars ? ` (${p.chars} 字)` : ''}`);
+    for (const c of r.calls ?? []) log(`  ✦ ${c.key} 调用 ${c.ok ? 'OK' : '失败'} · ${c.tokens} token · 结论 ${c.conclusionChars} 字${c.error ? ` · ${c.error}` : ''}`);
+    log(`提炼条数 ${r.written}${r.writtenIds?.length ? `（新 id ${r.writtenIds.join(',')}）` : ''}`);
+    if (r.stopping) log(`停机：${r.stopping}`);
+    log(`当日调用 ${state.cost?.calls ?? 0}/${limits.callsPerDay} · 当日 token ${(Number(state.cost?.promptTokens ?? 0) + Number(state.cost?.completionTokens ?? 0))}/${limits.tokensPerDay}`);
+    for (const w of r.warnings ?? []) log(`⚠️ ${w}`);
+    log(`日报行：${dailyLine}`);
+  }
+  return r.ok ? 0 : (r.exitCode || 1);
+}
+
+if (isMainEntry(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; }).catch((e) => {
+    console.error(`未捕获异常：${e && e.stack ? e.stack : e}`);
+    process.exitCode = 1;
+  });
+}
+
+export { main, resolveOwnerUser, STATE_SCHEMA };

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

@@ -0,0 +1,155 @@
+// 记忆引擎 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
+//
+// 退出码：0 成功 / 1 有失败 / 2 用法错
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+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 };
+
+function resolvePaths(flags, env = process.env) {
+  const home = path.resolve(String(flags.home || env.DSH_HOME || path.join(os.homedir(), '.dsh')));
+  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 };
+}
+
+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`);
+  const store = openDocIndexStore(dbPath, { create: false });
+  try {
+    snapshotDb(store.db, dest);
+  } finally {
+    try {
+      store.db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+  const size = fs.statSync(dest).size;
+  log(`[rebuild] 重建前快照：${dest}（${size} B）`);
+  return { ok: true, dest, size };
+}
+
+/** 列出快照（按时间倒序）。 */
+export function listSnapshots(snapshotDir) {
+  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);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 回滚：用快照覆盖当前库（先把当前库另存为 `.before-restore-<ts>`，绝不静默丢）。
+ * ⚠️ WAL 副作用：覆盖前必须清掉 `-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}`;
+    if (fs.existsSync(f)) fs.rmSync(f, { force: true });
+  }
+  fs.copyFileSync(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);
+
+  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;
+    }
+
+    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;
+    }
+
+    // ① 重建前快照（默认开）
+    let snapshot = { ok: true, skipped: true, reason: '--no-snapshot' };
+    if (!flags['no-snapshot'] && !flags['dry-run']) {
+      snapshot = takeSnapshot({ dbPath, 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 */
+        }
+      }
+    }
+
+    // ③ 一键全量刷新（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;
+  } 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}`);
+    return EXIT.USAGE;
+  }
+}
+
+if (isMainEntry(import.meta.url)) process.exitCode = await main();

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

@@ -0,0 +1,48 @@
+// 记忆引擎 v2 · 离线层 —— 文档索引 CLI（方案 §3.2）
+//
+// 用法：
+//   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
+import { isMainEntry, parseArgs, makeLogger } from '../lib/cli-util.mjs';
+import { runDocIndexOnce } from '../lib/doc-index.mjs';
+
+export async function main() {
+  const { flags } = parseArgs();
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json, quiet: Boolean(flags.quiet) });
+  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;
+  } 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;
+  }
+}
+
+if (isMainEntry(import.meta.url)) await main();

package/memory-engine/cli/domain-tags.mjs

@@ -0,0 +1,251 @@
+// 记忆引擎 v2 · S3b —— 域标签补齐 CLI（方案 §3.6 / §5.4 / §7 / §3.9 D2）
+//
+// 用法：
+//   node cli/domain-tags.mjs --db <库路径>                       # dry-run（默认；只读规划，零写入）
+//   node cli/domain-tags.mjs --db <库路径> --apply                # 真跑（副本库；分批 + 可续跑）
+//   node cli/domain-tags.mjs --db <库路径> --apply --snapshot <dir>   # 跑前 VACUUM INTO 快照
+//   node cli/domain-tags.mjs --db <库路径> --limit 25 --batch 25   # 只跑 1 批（试跑）
+//   node cli/domain-tags.mjs --db <库路径> --apply --json          # 机器可读（stdout 只有 JSON）
+//
+// 关键开关：`--batch`（每批条数，默认 25）· `--max-chars-per-item`（送模型的单条截断，默认 240）
+//           `--owner-user`（本机 owner 的 userid；缺省由身份表解析、再回落常量）· `--state <file>`
+//           `--max-calls`（默认 20）· `--max-tokens`（默认 150000）· `--model` · `--base-url`
+//           `--no-daily-report`（不写日报段）· `--daily-report <path>`（覆盖日报路径）
+//
+// 退出码：0 = 完成/无待处理（含"成本闸停机"这种受控停止）；1 = 有异常；2 = 用法错；3 = 环境不可用（无 key / 库不存在）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { isMainEntry, parseArgs, num, makeLogger } from '../lib/cli-util.mjs';
+import * as D from '../lib/domain-tags.mjs';
+
+const argv = process.argv.slice(2);
+if (isMainEntry(import.meta.url)) {
+  main().catch((e) => {
+    console.error(`未捕获异常：${e && e.stack ? e.stack : e}`);
+    process.exitCode = 1;
+  });
+}
+
+/** 解析「本机 owner 的 userid」：优先 ⑤-3 的权威实现，其次 fork 的自检镜像，最后内置回落。 */
+async function resolveOwnerUser(explicit, home) {
+  if (explicit) return { user: explicit, source: 'cli' };
+  const cands = ['../../memory-db-tools/lib/memory-scope.mjs', '../dsh-memory-local/src/schema-migrate.mjs'];
+  for (const rel of cands) {
+    try {
+      const mod = await import(new URL(rel, import.meta.url).href);
+      const identity = mod.readIdentityTable ? mod.readIdentityTable(home) : null;
+      const r = mod.resolveDefaultOwner ? mod.resolveDefaultOwner(identity) : null;
+      if (r && r.ownerUser) return { user: r.ownerUser, source: `${rel} (${r.source})`, notes: r.notes ?? [] };
+    } catch { /* 试下一个候选 */ }
+  }
+  return { user: 'LiJianXiao', source: '内置回落（两条权威源都不可用）', notes: ['⚠️ 身份表解析不可用 ⇒ 回落常量'] };
+}
+
+async function main() {
+  const { flags } = parseArgs(argv);
+  const json = Boolean(flags.json);
+  const log = makeLogger({ json });
+  const dbPath = flags.db ? path.resolve(String(flags.db)) : null;
+  if (!dbPath) {
+    console.error('用法错：必须给 --db <库路径>（本脚本没有默认库路径 —— 写死路径是明令禁止的）');
+    process.exitCode = 2;
+    return;
+  }
+  if (!fs.existsSync(dbPath)) {
+    console.error(`环境不可用：库不存在 ${dbPath}`);
+    process.exitCode = 3;
+    return;
+  }
+
+  const apply = Boolean(flags.apply);
+  const batchSize = num(flags.batch, 25);
+  const limit = num(flags.limit, 0);
+  const maxCharsPerItem = num(flags['max-chars-per-item'], 240);
+  const limits = { callsPerDay: num(flags['max-calls'], D.COST_LIMITS.callsPerDay), tokensPerDay: num(flags['max-tokens'], D.COST_LIMITS.tokensPerDay) };
+  const home = path.dirname(path.dirname(dbPath)); // <home>/memory/memory.db → <home>
+  const stateFile = flags.state ? path.resolve(String(flags.state)) : path.join(home, 'memory', 'domain-tags-state.json');
+  const snapshotDir = flags.snapshot ? path.resolve(String(flags.snapshot)) : null;
+  const model = flags.model ? String(flags.model) : D.DEFAULT_LLM.model;
+  const baseUrl = flags['base-url'] ? String(flags['base-url']) : D.DEFAULT_LLM.baseUrl;
+  const nowIso = new Date().toISOString();
+
+  const owner = await resolveOwnerUser(flags['owner-user'] ? String(flags['owner-user']) : null, home);
+  const result = {
+    at: nowIso, mode: apply ? 'apply' : 'dry-run', db: dbPath, model, baseUrl,
+    ownerUser: owner.user, ownerSource: owner.source, limits, batchSize, maxCharsPerItem,
+    stats: {}, cost: null, stopping: null, ok: false, exitCode: 0,
+  };
+
+  log(`库      : ${dbPath}`);
+  log(`本机 owner: ${owner.user}（来源 ${owner.source}）`);
+  log(`模型    : ${model} @ ${baseUrl}（成本闸 ≤${limits.callsPerDay} 次 / ≤${limits.tokensPerDay} token 每日）`);
+  for (const n of owner.notes ?? []) log(`⚠️ ${n}`);
+
+  // ── 只读取样 + 过滤 ────────────────────────────────────────────────────────
+  const scanned = D.readCandidates(dbPath, { limit, maxCharsPerItem });
+  const state = D.readState(stateFile, dbPath, nowIso);
+  if (!scanned.ownerColumn) log('⚠️ 库无 owner_user 列（未迁移的老库形态）⇒ 全部条目按「本机 owner」处理');
+
+  const pending = [];
+  const skippedOwner = [];
+  for (const it of scanned.items) {
+    const ownerUser = scanned.ownerColumn ? it.ownerUser : owner.user;
+    if (ownerUser !== owner.user) {
+      // D2 从严：归属不明 / 非本机 owner ⇒ **一律不送第三方模型**，跳过并记账
+      skippedOwner.push({ id: it.id, ownerUser: ownerUser ?? '(空)' });
+      continue;
+    }
+    if (state.processed[String(it.id)]) continue; // 幂等台账：已处理过的不再送模型
+    pending.push(it);
+  }
+  const batches = Math.ceil(pending.length / batchSize);
+  const estimated = pending.slice(0, batchSize).length ? D.estimateTokens(pending.slice(0, batchSize)) : 0;
+  result.stats = {
+    scanned: scanned.items.length, skippedOwner: skippedOwner.length, alreadyProcessed: scanned.items.length - pending.length - skippedOwner.length,
+    pending: pending.length, plannedBatches: batches, estimatedTokensPerBatch: estimated,
+  };
+  log(`扫描 ${scanned.items.length} 条 · 跳过(非本机 owner) ${skippedOwner.length} · 已处理(台账) ${result.stats.alreadyProcessed} · 待处理 ${pending.length}（${batches} 批）`);
+  if (skippedOwner.length) log(`  ⚠️ 跳过条目（D2 从严：不进第三方）id=[${skippedOwner.map((s) => s.id).slice(0, 20).join(',')}${skippedOwner.length > 20 ? '…' : ''}]`);
+
+  if (!apply) {
+    log('\n[DRY-RUN] 未写任何内容（未调模型、未写 state）；要真跑加 --apply');
+    result.ok = true;
+    result.state = { file: stateFile, cost: state.cost };
+    return finish(result, 0, json, log);
+  }
+
+  // ── 成本闸（调用前总检查） ─────────────────────────────────────────────────
+  if (pending.length === 0) {
+    log('\n无待处理条目（幂等台账已覆盖）—— 零写入');
+    result.ok = true;
+    result.state = { file: stateFile, cost: state.cost, processed: Object.keys(state.processed).length };
+    return finish(result, 0, json, log);
+  }
+  const gate0 = D.costGate(state, estimated, limits);
+  if (!gate0.ok) {
+    result.stopping = gate0.reason;
+    log(`\n[STOP] 成本闸：${gate0.reason}（超限即停，不重试）`);
+    result.ok = true;
+    return finish(result, 0, json, log);
+  }
+
+  // ── 快照（§3.6 前置） ──────────────────────────────────────────────────────
+  if (snapshotDir) {
+    const dest = path.join(snapshotDir, 'memory.db');
+    const file = D.vacuumInto(dbPath, dest);
+    const st = fs.statSync(file);
+    result.snapshot = { file, bytes: st.size };
+    log(`✓ 快照：${file}（${st.size} B）`);
+  } else {
+    log('⚠️ 未给 --snapshot：本次无快照（副本演练可接受，生产前置必须有）');
+    result.snapshot = null;
+  }
+
+  // ── 分类模型 key ──────────────────────────────────────────────────────────
+  const apiKey = process.env[D.DEFAULT_LLM.credentialKey] || D.readCredential(D.DEFAULT_LLM.credentialKey);
+  if (!apiKey) {
+    log(`环境不可用：找不到 ${D.DEFAULT_LLM.credentialKey}（env 与 .credentials.yaml 都没有）`);
+    result.exitCode = 3;
+    return finish(result, 3, json, log);
+  }
+
+  // ── 分批跑 ────────────────────────────────────────────────────────────────
+  const db = D.openDb(dbPath, { write: true });
+  state.stats.runs = Number(state.stats.runs ?? 0) + 1;
+  const runStart = Date.now();
+  try {
+    for (let b = 0; b < batches; b += 1) {
+      const slice = pending.slice(b * batchSize, (b + 1) * batchSize);
+      if (slice.length === 0) break;
+      const est = D.estimateTokens(slice);
+      const gate = D.costGate(state, est, limits);
+      if (!gate.ok) {
+        result.stopping = gate.reason;
+        log(`\n[STOP] 成本闸：${gate.reason}（超限即停，不重试）`);
+        break;
+      }
+      const callStart = Date.now();
+      const resp = await D.callClassifier({ items: slice, apiKey, baseUrl, model });
+      if (!resp.ok) {
+        result.stopping = `模型调用失败（第 ${b + 1} 批）：${resp.error}`;
+        log(`\n[STOP] ${result.stopping}`);
+        break;
+      }
+      state.cost.calls = Number(state.cost.calls ?? 0) + 1;
+      state.cost.promptTokens = Number(state.cost.promptTokens ?? 0) + Number(resp.usage?.prompt_tokens ?? 0);
+      state.cost.completionTokens = Number(state.cost.completionTokens ?? 0) + Number(resp.usage?.completion_tokens ?? 0);
+      state.cost.date = nowIso.slice(0, 10);
+
+      // 模型输出 → 只保留本批条目的 id（防模型编 id）；域标签只从固定集合里认（appendDomainTags 里过滤）
+      const inBatch = new Map(slice.map((it) => [Number(it.id), it]));
+      const results = [];
+      let unknownDomainDropped = 0;
+      for (const item of resp.items) {
+        const id = Number(item?.id);
+        if (!Number.isFinite(id) || !inBatch.has(id)) continue;
+        const rawDomains = Array.isArray(item?.domains) ? item.domains : (Array.isArray(item?.domain) ? item.domain : []);
+        const valid = rawDomains.filter((d) => D.DOMAIN_TOKEN_BY_LABEL[String(d).trim()] !== undefined);
+        unknownDomainDropped += rawDomains.length - valid.length;
+        results.push({ id, domains: valid });
+      }
+      const missing = slice.filter((it) => !results.some((r) => r.id === Number(it.id)));
+      for (const m of missing) results.push({ id: Number(m.id), domains: [] }); // 模型漏答 ⇒ 记为"无标签"，不写库
+
+      const wr = await D.applyResults(db, results);
+      if (!wr.ok) {
+        result.stopping = `写库失败（第 ${b + 1} 批）：${wr.error}`;
+        log(`\n[STOP] ${result.stopping}`);
+        break;
+      }
+      // 幂等台账：本批已处理（含"无标签"——它们也算处理过，避免每轮重复问模型）
+      for (const it of slice) {
+        const r = results.find((x) => x.id === Number(it.id));
+        state.processed[String(it.id)] = D.tagSetHash(r ? r.domains : []);
+      }
+      state.stats.batches = Number(state.stats.batches ?? 0) + 1;
+      state.stats.tagged = Number(state.stats.tagged ?? 0) + wr.written;
+      state.stats.noTag = Number(state.stats.noTag ?? 0) + results.filter((r) => r.domains.length === 0).length;
+      state.stats.skippedOwner = skippedOwner.length;
+      state.stats.skippedUnknownDomain = Number(state.stats.skippedUnknownDomain ?? 0) + unknownDomainDropped;
+      state.updatedAt = new Date().toISOString();
+      D.writeState(stateFile, state); // **每批落盘** ⇒ 可中断续跑
+      log(`  批 ${b + 1}/${batches}: 调用 ${state.cost.calls} 次 · 写 ${wr.written} 条 · 已是 ${wr.unchanged} 条 · 耗时 ${Date.now() - callStart}ms · 当日 token ${Number(state.cost.promptTokens) + Number(state.cost.completionTokens)}`);
+    }
+  } finally {
+    try { db.close(); } catch { /* 忽略 */ }
+  }
+
+  // ── 汇总 + 日报一行 ───────────────────────────────────────────────────────
+  for (const s of skippedOwner) state.skipped[String(s.id)] = `owner=${s.ownerUser}`;
+  state.updatedAt = new Date().toISOString();
+  D.writeState(stateFile, state);
+  const usedTokens = Number(state.cost.promptTokens) + Number(state.cost.completionTokens);
+  const line = D.renderDailyLine({
+    mode: 'apply', stats: state.stats, cost: state.cost, state: { processedCount: Object.keys(state.processed).length },
+    limits, stoppedReason: result.stopping,
+  });
+  result.cost = { ...state.cost, usedTokens };
+  result.state = { file: stateFile, processed: Object.keys(state.processed).length };
+  log(`\n完成：批次 ${state.stats.batches} · 本轮写 ${state.stats.tagged} 条 · 当日调用 ${state.cost.calls}/${limits.callsPerDay} · 当日 token ${usedTokens}/${limits.tokensPerDay} · 用时 ${Date.now() - runStart}ms`);
+  if (!flags['no-daily-report']) {
+    const reportFile = flags['daily-report'] ? path.resolve(String(flags['daily-report'])) : D.dailyReportPath({});
+    const r = D.updateDailySection({ file: reportFile, line, dryRun: false });
+    result.dailyReport = { file: reportFile, ...r, line };
+    log(`${r.ok ? '✓' : '⚠️'} 日报：${reportFile}${r.ok ? `（${r.replaced ? '段替换' : '追加段'}）` : `（${r.reason}）`}`);
+  }
+  result.dailyLine = line;
+  result.ok = true;
+  return finish(result, 0, json, log);
+}
+
+function finish(result, code, json, log) {
+  result.exitCode = code;
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    log(`\n[${code === 0 ? 'OK' : 'STOP'}] exit=${code}`);
+  }
+  process.exitCode = code;
+}