@kira905/dsh-memory-toolkit 0.1.3 → 0.2.0

package/memory-engine/cli/band-sentinel.mjs

@@ -0,0 +1,164 @@
+// 号段哨兵入口：一条命令看「下一条新 id 会不会落到别人的号段里」。
+//
+//   node memory-engine/cli/band-sentinel.mjs                    # 单机缺省：只读本机库，只打印
+//   node memory-engine/cli/band-sentinel.mjs --line              # 只打一行
+//   node memory-engine/cli/band-sentinel.mjs --apply --out r.json # 落盘报告（JSON）
+//
+// 退出码：0 正常（含"远端未探测"，只看本机）/ 2 用法或配置错 / 3 号段异常 / 4 本机库读不到 / 5 加了 --require-all 且有段未探测
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCli, rejectBadArgs, usageError, settle, writeTextFile } from '../lib/cli-strict.mjs';
+import { isMainEntry } from '../lib/cli-util.mjs';
+import { defaultMemoryDbPath } from '../lib/layers.mjs';
+import { loadBandConfig, evaluate, formatHuman, formatLine, EXIT as SENTINEL_EXIT } from '../lib/band-sentinel.mjs';
+
+const HELP = `band-sentinel —— 记忆 id 号段哨兵（纯只读；缺省单机退化）
+
+用法：
+  node memory-engine/cli/band-sentinel.mjs                       单机缺省：只读本机库、只打印
+  node memory-engine/cli/band-sentinel.mjs --line                只打一行（日报正文用）
+  node memory-engine/cli/band-sentinel.mjs --only <host[,host]>  只看某几段
+  node memory-engine/cli/band-sentinel.mjs --apply --out <file>  把结论落盘成 JSON 报告
+
+开关：
+  --db <path>             本机记忆库（缺省 = 引擎配置里的 memory.db）
+  --config <file>         号段配置（缺省 memory-engine/config/bands.json）
+  --only <host[,host]>    只跑这几段
+  --band <host>=<base>    临时改某段的基值（可重复；验收用：故意传错看它会不会点名）
+  --timeout <ms>          单段远端超时（缺省 20000）
+  --require-all           有段未探测 / 不可达也判失败（rc=5）—— 接定时/自检时用
+  --apply                 允许把报告落盘（缺省只读 + 只打印，一个文件都不写）
+  --out <file>            --apply 的落盘路径
+  --json                  报告用 JSON（**只落文件**，必须与 --apply --out 同用）
+  --line                  只打一行
+  --quiet                 不出人话
+  --help
+
+两种模式（怎么退化）：
+  · 单机（缺省）：配置里只有一条 band ⇒ 只读本机库的 sqlite_sequence，
+    判「下一条新 id」是否落在 [base, base+width)；**不 ssh、不假装知道别的机器**。
+  · 多机（可选）：配置里有多条 band 且非本机条目给了 remote（ssh 别名 + 远端 node 路径）时才去读。
+    任一远端读不到 ⇒ 结论写「未探测 / 不可达」，**退出码不会是 4**（4 只留给本机库读不到）。
+
+判据：
+  · 下一条新 id 越出本段（低于下界 / 冲出上界）⇒ 红；
+  · 出现更高位段的行 ⇒ 红；出现更低位的别台段行 ⇒ **只披露不判红**（删行=删记忆，且不影响后续新 id）；
+  · 本机库读不到 ⇒ rc=4（fail-closed，不算通过）。
+
+退出码：0 正常 · 2 用法/配置错 · 3 号段异常 · 4 本机库读不到 · 5 --require-all 且有段未探测
+`;
+
+const SPEC = {
+  db: 'string',
+  config: 'string',
+  only: 'string',
+  band: 'string',
+  timeout: 'number',
+  'require-all': 'bool',
+  apply: 'bool',
+  out: 'string',
+  json: 'bool',
+  line: 'bool',
+  quiet: 'bool',
+};
+
+/** 可重复开关：`--band a=1 --band b=2` 与 `--band=a=1` 都收。 */
+function collectPairs(argv, name) {
+  const out = [];
+  const eqForm = `${name}=`;
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === name) {
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) out.push(next);
+      continue;
+    }
+    if (token.startsWith(eqForm)) out.push(token.slice(eqForm.length));
+  }
+  return out;
+}
+
+function parseOverrides(list) {
+  const out = {};
+  for (const item of list) {
+    const at = item.indexOf('=');
+    if (at <= 0) throw new Error(`--band 的形状是 host=base，收到 ${JSON.stringify(item)}`);
+    const host = item.slice(0, at).trim().toLowerCase();
+    const base = Number(item.slice(at + 1).trim());
+    if (!Number.isInteger(base) || base <= 0) throw new Error(`--band ${host}=${item.slice(at + 1)} 的 base 不是正整数`);
+    out[host] = base;
+  }
+  return out;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const parsed = parseCli(argv, SPEC);
+  if (parsed.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const bad = rejectBadArgs(parsed);
+  if (bad.length) return usageError([...bad, '（--help 看用法）']);
+
+  const f = parsed.flags;
+  const json = Boolean(f.json);
+  const apply = Boolean(f.apply);
+  const out = f.out ? path.resolve(f.out) : null;
+
+  if (json && !apply) return usageError('`--json` 只落文件：请与 --apply --out <file> 同用（缺省只读只打印）');
+  if (json && !out) return usageError('`--json` 要配 --out <file>');
+  if (out && !apply) return usageError('给了 --out 就要加 --apply：缺省模式一个文件都不写');
+
+  let overrides;
+  try {
+    overrides = parseOverrides(collectPairs(argv, '--band'));
+  } catch (e) {
+    return usageError(e.message);
+  }
+
+  let config;
+  try {
+    config = loadBandConfig({ file: f.config || null });
+  } catch (e) {
+    return usageError(`号段配置不成立：${e.message}`);
+  }
+
+  const dbPath = f.db ? path.resolve(f.db) : defaultMemoryDbPath();
+  const only = f.only ? String(f.only).split(/[\s,，]+/).map((s) => s.trim()).filter(Boolean) : null;
+  const report = evaluate({
+    config,
+    dbPath,
+    only,
+    overrides,
+    timeoutMs: Number.isFinite(f.timeout) ? f.timeout : 20000,
+  });
+
+  // --require-all：有段未探测就判失败。必须在渲染 / 落盘之前写回 report.exitCode，
+  // 否则人类结论行与 JSON 报告里的 rc 会和真实退出码不一致（只有 process.exitCode 是对的）。
+  if (Boolean(f['require-all']) && report.unprobed.length) report.exitCode = SENTINEL_EXIT.UNPROBED;
+
+  if (apply && out) {
+    writeTextFile(out, `${JSON.stringify({ ...report, dbPath, reportFile: out }, null, 2)}\n`);
+  }
+  if (!f.quiet) {
+    process.stdout.write(`${f.line ? `${formatLine(report)}\n` : `${formatHuman(report)}\n`}`);
+    if (apply && out) process.stdout.write(`  报告已落盘：${out}\n`);
+  }
+
+  const exit = report.exitCode;
+  process.exitCode = exit;
+  if (exit === SENTINEL_EXIT.LOCAL_UNREADABLE && !f.quiet) {
+    process.stderr.write(`  本机库读不到 ⇒ rc=${SENTINEL_EXIT.LOCAL_UNREADABLE}（fail-closed，不算通过）\n`);
+  }
+  if (!fs.existsSync(dbPath)) {
+    // 本机库不在时 evaluate 已判 LOCAL-UNREADABLE；这里只是让 --line 输出时也提醒一句
+    if (!f.quiet && !f.line) process.stderr.write(`  缺省库路径：${dbPath}\n`);
+  }
+}
+
+try {
+  if (isMainEntry(import.meta.url)) main();
+} catch (e) {
+  settle(e, { prefix: '[band-sentinel]' });
+}

package/memory-engine/cli/distill-rollback.mjs

@@ -1,86 +1,154 @@
 #!/usr/bin/env node
-// 记忆引擎 v2 · S3c —— 提炼产物回滚 CLI（`cli/distill-rollback.mjs`）
+// 提炼产物回滚 CLI：把 `distilled…` 标签的条目按组 / 按 id 删掉，删之前先留快照 + 一键恢复脚本。
 //
 // 用法：
-//   node cli/distill-rollback.mjs --db <memory.db>                 # **默认 dry-run**：只列出会被删的条
-//   node cli/distill-rollback.mjs --db <memory.db> --apply         # 真删（先 VACUUM INTO 快照 + 生成一键恢复脚本）
+//   node cli/distill-rollback.mjs --db <memory.db>                 # 缺省 dry-run：只列会被删的条
+//   node cli/distill-rollback.mjs --db <memory.db> --apply         # 真删（先 VACUUM INTO 快照 + 生成恢复脚本）
 //   node cli/distill-rollback.mjs --db <memory.db> --key <srcKey>  # 只回滚某一组
 //   node cli/distill-rollback.mjs --db <memory.db> --id 1001 --apply
 //   node cli/distill-rollback.mjs --db <memory.db> --digest        # 只算内容摘要（演练对照用）
 //
-// 判据：`tags LIKE 'distilled%'`（回滚面就是这个前缀——提炼产物唯一性标记）
+// 回滚面 = `tags LIKE 'distilled%'` —— 这个前缀就是提炼产物的唯一性标记。
 // 退出码：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 { listDistilled, rollbackDistilled, contentDigest, fileSha256 } from '../lib/distill-rollback.mjs';
 
-const USAGE = 'node cli/distill-rollback.mjs --db <memory.db> [--apply] [--key <srcKey>]... [--id <id>]... '
-  + '[--snapshot-dir <dir>] [--limit N] [--digest [--real-only]] [--show N] [--json] [--help]';
+const USAGE = [
+  'node cli/distill-rollback.mjs',
+  '--db <memory.db>',
+  '[--apply]',
+  '[--key <srcKey>]...',
+  '[--id <id>]...',
+  '[--snapshot-dir <dir>]',
+  '[--limit N]',
+  '[--digest [--real-only]]',
+  '[--show N]',
+  '[--json]',
+  '[--help]',
+].join(' ');
+
+const DISTILLED_LIKE = 'distilled%';
+const DEFAULT_SHOW = 50;
+
+/** 逗号分隔的多值开关 → 干净数组（空串与首尾空白都丢掉）。 */
+function splitList(raw) {
+  if (raw === undefined) return [];
+  return String(raw)
+    .split(',')
+    .map((piece) => piece.trim())
+    .filter(Boolean);
+}
+
+function emit(json, payload, human, log) {
+  if (json) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  else if (human) log(human);
+}
+
+/** 只算摘要：`--real-only` 排除派生条，判据才是「真实条一个字节没动」。 */
+function runDigest({ dbPath, json, log, realOnly }) {
+  const d = contentDigest(dbPath, { excludeTagsLike: realOnly ? DISTILLED_LIKE : null });
+  const sha = fileSha256(dbPath);
+  const payload = { db: dbPath, realOnly: Boolean(realOnly), ...d, fileSha256: sha };
+  const scope = realOnly ? '真实条' : '整表';
+  emit(json, payload, `${scope}内容摘要：条数 ${d.count} · digest ${d.digest} · 全表条数 ${d.allCount} · 文件 sha ${sha}`, log);
+  return 0;
+}
+
+/** 把当前状态 + 命中清单讲清楚（人看的四行）。 */
+function describeSelection({ dbPath, apply, before, items, keys, ids, log }) {
+  log(`库      : ${dbPath}`);
+  log(`模式    : ${apply ? 'APPLY（真删）' : 'DRY-RUN（只列不删）'}`);
+  log(`库现状  : 全表 ${before.allCount} 条（其中提炼条 ${before.allCount - before.count} 条）· 内容摘要 ${before.digest}`);
+  log(`命中筛选: ${items.length} 条（--key ${keys.length ? keys.join(',') : '-'} / --id ${ids.length ? ids.join(',') : '-'}）`);
+}
+
+/** 真删：先快照、再删、再把删除前后摘要摆一起。 */
+function runApply({ dbPath, keys, ids, snapshotDir, before, json, log }) {
+  const r = rollbackDistilled({
+    dbPath,
+    apply: true,
+    keys: keys.length ? keys : null,
+    ids: ids.length ? ids : null,
+    snapshotDir,
+  });
+  log(`已删除  : ${r.deleted} 条（id ${r.deletedIds.join(',')}）`);
+  log(`删除前快照: ${r.snapshot}${r.snapshotSha256 ? ` · sha ${r.snapshotSha256}` : ''}`);
+  log(`一键恢复: ${r.rollbackFile}`);
+  const same = r.after.digest === before.digest;
+  log(`回滚后  : 全表 ${r.after.allCount} 条 · 内容摘要 ${r.after.digest}${same ? ' ✅ 与删除前一致' : ' ⚠️ 与删除前不一致'}`);
+  for (const warn of r.warnings ?? []) log(`⚠️ ${warn}`);
+  emit(json, { ok: true, ...r, fileSha256: fileSha256(dbPath) }, null, log);
+  return 0;
+}
 
 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; }
+  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 collect = (v) => (v === undefined ? [] : String(v).split(',').map((x) => x.trim()).filter(Boolean));
-  const keys = collect(flags.key);
-  const ids = collect(flags.id).map((x) => Number(x)).filter((x) => Number.isFinite(x));
-
-  if (flags.digest) {
-    // `--real-only`：只算**真实（非派生）条**的内容摘要 —— 演练判据要的是「回滚后真实条一个字节没变」
-    //   （整表摘要会把被删掉的提炼条也算进去 ⇒ 对比必然"不一致"，那是判据写错、不是回滚失败）
-    const exclude = flags['real-only'] ? 'distilled%' : null;
-    const d = contentDigest(dbPath, { excludeTagsLike: exclude });
-    const out = { db: dbPath, realOnly: Boolean(exclude), ...d, fileSha256: fileSha256(dbPath) };
-    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
-    else log(`${exclude ? '真实条' : '整表'}内容摘要：条数 ${d.count} · digest ${d.digest} · 全表条数 ${d.allCount} · 文件 sha ${out.fileSha256}`);
-    return 0;
+  if (!dbPath) {
+    process.stderr.write('用法错：必须给 --db <库路径>\n');
+    return 2;
+  }
+  if (!fs.existsSync(dbPath)) {
+    process.stderr.write(`环境不可用：库不存在 ${dbPath}\n`);
+    return 3;
   }
 
+  if (flags.digest) return runDigest({ dbPath, json, log, realOnly: Boolean(flags['real-only']) });
+
+  const keys = splitList(flags.key);
+  const ids = splitList(flags.id).map((x) => Number(x)).filter((x) => Number.isFinite(x));
   const apply = Boolean(flags.apply);
   const before = contentDigest(dbPath);
-  const items = listDistilled({ dbPath, keys: keys.length ? keys : null, ids: ids.length ? ids : null, limit: num(flags.limit, 0) });
+  const items = listDistilled({
+    dbPath,
+    keys: keys.length ? keys : null,
+    ids: ids.length ? ids : null,
+    limit: num(flags.limit, 0),
+  });
 
-  log(`库      : ${dbPath}`);
-  log(`模式    : ${apply ? 'APPLY（真删）' : 'DRY-RUN（只列不删）'}`);
-  log(`库现状  : 全表 ${before.allCount} 条（其中提炼条 ${before.allCount - before.count} 条）· 内容摘要 ${before.digest}`);
-  log(`命中筛选: ${items.length} 条（--key ${keys.length ? keys.join(',') : '-'} / --id ${ids.length ? ids.join(',') : '-'}）`);
-  for (const it of items.slice(0, Number(flags.show ?? 50))) log(`  #${it.id} src=${it.srcKey} date=${it.date} ${it.chars} 字 · ${it.head.slice(0, 70)}`);
+  describeSelection({ dbPath, apply, before, items, keys, ids, log });
+  const show = Number(flags.show ?? DEFAULT_SHOW);
+  for (const it of items.slice(0, show)) log(`  #${it.id} src=${it.srcKey} date=${it.date} ${it.chars} 字 · ${it.head.slice(0, 70)}`);
 
   if (!items.length) {
-    if (json) process.stdout.write(JSON.stringify({ ok: true, matched: 0, deleted: 0, before }, null, 2) + '\n');
+    emit(json, { ok: true, matched: 0, deleted: 0, before }, null, log);
     return 0;
   }
   if (!apply) {
     log('（dry-run：未删除任何东西；加 --apply 才真删，删除前会自动 VACUUM INTO 快照）');
-    if (json) process.stdout.write(JSON.stringify({ ok: true, dryRun: true, matched: items.length, ids: items.map((x) => x.id), before }, null, 2) + '\n');
+    emit(json, { ok: true, dryRun: true, matched: items.length, ids: items.map((x) => x.id), before }, null, log);
     return 0;
   }
 
-  const r = rollbackDistilled({
-    dbPath, apply: true, keys: keys.length ? keys : null, ids: ids.length ? ids : null,
+  return runApply({
+    dbPath,
+    keys,
+    ids,
     snapshotDir: flags['snapshot-dir'] ? path.resolve(String(flags['snapshot-dir'])) : null,
+    before,
+    json,
+    log,
   });
-  log(`已删除  : ${r.deleted} 条（id ${r.deletedIds.join(',')}）`);
-  log(`删除前快照: ${r.snapshot}${r.snapshotSha256 ? ` · sha ${r.snapshotSha256}` : ''}`);
-  log(`一键恢复: ${r.rollbackFile}`);
-  log(`回滚后  : 全表 ${r.after.allCount} 条 · 内容摘要 ${r.after.digest}${r.after.digest === before.digest ? ' ✅ 与删除前一致' : ' ⚠️ 与删除前不一致'}`);
-  for (const w of r.warnings ?? []) log(`⚠️ ${w}`);
-  if (json) process.stdout.write(JSON.stringify({ ok: true, ...r, fileSha256: fileSha256(dbPath) }, null, 2) + '\n');
-  return 0;
 }
 
 if (isMainEntry(import.meta.url)) {
-  main().then((code) => { process.exitCode = code; }).catch((e) => {
-    console.error(`未捕获异常：${e && e.stack ? e.stack : e}`);
-    process.exitCode = 1;
-  });
+  main()
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((e) => {
+      console.error(`未捕获异常：${e?.stack ?? e}`);
+      process.exitCode = 1;
+    });
 }
 
 export { main };

package/memory-engine/cli/distill-sessions.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+// 会话日志 → 记忆条（新入口；与内核的 `cli/distill.mjs` 并存，互不影响）。
+//
+// 与旧入口的分工：
+//   旧入口吃「库里窗口内变动的记忆」，按语义聚类再提炼；
+//   本入口吃「一份会话 JSONL」，只抽能回指来源的结论句，再合成 ≤N 条写回。
+//   旧入口的默认值 / 参数名 / 退出码一个都没改 —— 两边是两条独立的路。
+//
+// 用法：
+//   node memory-engine/cli/distill-sessions.mjs --source <会话.jsonl>                    缺省 dry-run：只抽、只规划
+//   node memory-engine/cli/distill-sessions.mjs --source <会话.jsonl> --max-tokens 30000  dry-run + 预算（列出将写什么）
+//   node memory-engine/cli/distill-sessions.mjs --source <会话.jsonl> --db <memory.db> --max-tokens 30000 --apply
+//
+// 退出码：0 = 正常（**含"没配预算所以没跑"**）/ 1 = 失败 / 2 = 用法错 / 3 = 环境不可用（源文件或库不在）
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMainEntry } from '../lib/cli-util.mjs';
+import { parseCli, rejectBadArgs, usageError, settle, emitJsonReport, EXIT } from '../lib/cli-strict.mjs';
+import {
+  runSessionDistill, DEFAULT_LIMIT, NO_BUDGET_MESSAGE, makeRunId, runKeyOf,
+} from '../lib/session-distill.mjs';
+import { DEFAULT_LLM } from '../lib/distill.mjs';
+import { DEFAULTS as SOURCE_DEFAULTS } from '../lib/session-source.mjs';
+
+const HELP = `distill-sessions —— 会话日志 → 记忆（提炼的输入面；缺省 dry-run）
+
+用法：
+  node memory-engine/cli/distill-sessions.mjs --source <会话.jsonl>
+  node memory-engine/cli/distill-sessions.mjs --source <会话.jsonl> --max-tokens <n> [--limit 5]
+  node memory-engine/cli/distill-sessions.mjs --source <会话.jsonl> --db <memory.db> --max-tokens <n> --apply
+
+它做什么：
+  一行一个事件的 .jsonl 进来 → 只挑「能回指来源的结论句」（决定 / 口径 / 偏好 / 修复方案）→
+  交给模型合成 ≤N 条结论 → 写回记忆库，标签以 distilled 开头并带 sess= 与 run=session:<批次>。
+  每条结论都挂着来源（场次 + 行号 + 原文锚），不写摘要、不写过程叙述。
+
+开关：
+  --source <file>          会话日志（一行一个 JSON 事件）。给 .jsonl.zstd 也行：能用 node 内置 zstd 逐帧解就解开，
+                           解不开会明确告诉你「这是压缩日志，先解压」（不会静默失败）
+  --db <path>              记忆库；--apply 时必填（无默认值：写死生产路径是明令禁止的）
+  --apply                  真跑：调模型 → 拍快照 → 写库 → 记台账
+  --dry-run                显式干跑（缺省就是这个）；与 --apply 同时给算用法错
+  --limit <n>              最多写几条结论（缺省 ${DEFAULT_LIMIT}）
+  --max-tokens <n>         每日预算（token）。**不给、台账里也没配 ⇒ 本轮一次模型都不调**（rc=0）
+                           给了就在 --apply 时写进台账，往后不带这个开关也按台账里的预算走
+  --state <file>           台账（缺省：库同级的 butler-session-distill-state.json；没有库就没有台账）
+  --snapshot-dir <dir>     写库前 VACUUM INTO 的落点（缺省：库同级 snapshots/）
+  --run <id>               批次 id（缺省自动生成）。撤回就按这一批：整批一个来源键
+  --owner-user <id>        库里有 owner_user 列时写它（缺省 local）
+  --session-id <id>        日志里没有 type=session 事件时，用它补来源 id
+  --max-chars <n>          单句长度上限（缺省 ${SOURCE_DEFAULTS.maxChars}；超了跳过并计数）
+  --model <name>           模型名（缺省 ${DEFAULT_LLM.model}）
+  --base-url <url>         模型服务地址（缺省 ${DEFAULT_LLM.baseUrl}）
+  --now <iso>              把某个时刻当"现在"（演练 / 复现用）
+  --json                   机器可读报告落文件（**必须配 --out，且不上 stdout**）
+  --out <file>             --json 的落盘路径
+  --quiet                  只打最终那几行
+  --help
+
+提炼的边界（三条，别指望它干第四件）：
+  · 不做摘要式写入：过程叙述、寒暄、疑问、推测、工具输出一律不进库；
+  · 只写能回指来源的结论条：每条都带场次 / 行号 / 原文锚，回不去原文的宁可不写；
+  · 没配每日预算就不跑：不继承任何缺省额度，也不"没配=无限跑"。
+
+撤回：
+  node memory-engine/cli/distill-rollback.mjs --db <memory.db> --key <批次键> --apply
+  （批次键 = 本轮打印的 src=，一批一个键 ⇒ 一条命令整批撤掉；撤前会先拍快照）
+
+退出码：0 正常（含"没配预算 / 没候选 / 已产出过"）/ 1 失败 / 2 用法错 / 3 环境不可用
+`;
+
+const SPEC = {
+  source: 'string',
+  db: 'string',
+  apply: 'bool',
+  'dry-run': 'bool',
+  limit: 'number',
+  'max-tokens': 'number',
+  state: 'string',
+  'snapshot-dir': 'string',
+  run: 'string',
+  'owner-user': 'string',
+  'session-id': 'string',
+  'max-chars': 'number',
+  model: 'string',
+  'base-url': 'string',
+  now: 'string',
+  json: 'bool',
+  out: 'string',
+  quiet: 'bool',
+};
+
+/** 台账缺省落点：库同级（没有库就没有台账 —— 别偷偷往生产路径写）。 */
+export function defaultStateFile(dbPath) {
+  if (!dbPath) return null;
+  return path.join(path.dirname(path.resolve(dbPath)), 'butler-session-distill-state.json');
+}
+
+export function parseCliArgs(argv) {
+  const parsed = parseCli(argv, SPEC);
+  return { parsed, bad: rejectBadArgs(parsed) };
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { parsed } = parseCliArgs(argv);
+  if (parsed.help) {
+    process.stdout.write(`${HELP}\n`);
+    return EXIT.OK;
+  }
+  const bad = rejectBadArgs(parsed);
+  if (bad.length) {
+    usageError([...bad, '', '先 --help 看一眼可用开关。']);
+    return EXIT.USAGE;
+  }
+  const flags = parsed.flags;
+  const say = (line) => { if (!flags.quiet) process.stdout.write(`${line}\n`); };
+
+  if (flags.apply && flags['dry-run']) {
+    usageError(['--apply 与 --dry-run 不能同时给：缺省就是 dry-run，要真写只加 --apply。']);
+    return EXIT.USAGE;
+  }
+  if (!flags.source) {
+    usageError(['缺少 --source <会话.jsonl>：没有输入就没什么可提炼的。']);
+    return EXIT.USAGE;
+  }
+  if (flags.apply && !flags.db) {
+    usageError(['--apply 必须配 --db <memory.db>：本工具不会猜你的库在哪。']);
+    return EXIT.USAGE;
+  }
+  if (flags.json && !flags.out) {
+    usageError(['--json 要配 --out <file>：机器可读内容只落文件，不上 stdout。']);
+    return EXIT.USAGE;
+  }
+  if (flags.db && !fs.existsSync(flags.db) && flags.apply) {
+    process.stderr.write(`❌ 记忆库不存在：${flags.db}\n`);
+    return EXIT.UNREADABLE;
+  }
+  if (flags.now && Number.isNaN(Date.parse(flags.now))) {
+    usageError([`--now 不是可解析的时间：${flags.now}`]);
+    return EXIT.USAGE;
+  }
+
+  const now = flags.now ? Date.parse(flags.now) : Date.now();
+  const apply = Boolean(flags.apply);
+  const dbPath = flags.db ? path.resolve(flags.db) : null;
+  const stateFile = flags.state ? path.resolve(flags.state) : defaultStateFile(dbPath);
+  const runId = flags.run ? String(flags.run) : makeRunId(now);
+
+  say(`[distill-sessions] ${apply ? '真跑' : '干跑（dry-run）'} · 批次 ${runId} · 来源 ${flags.source}`);
+  const result = await runSessionDistill({
+    source: path.resolve(flags.source),
+    dbPath,
+    apply,
+    limit: flags.limit ?? DEFAULT_LIMIT,
+    maxTokens: flags['max-tokens'] ?? null,
+    maxChars: flags['max-chars'] ?? SOURCE_DEFAULTS.maxChars,
+    stateFile,
+    snapshotDir: flags['snapshot-dir'] ? path.resolve(flags['snapshot-dir']) : null,
+    runId,
+    ownerUser: flags['owner-user'] ?? null,
+    sessionId: flags['session-id'] ?? null,
+    model: flags.model ?? DEFAULT_LLM.model,
+    baseUrl: flags['base-url'] ?? DEFAULT_LLM.baseUrl,
+    now,
+  });
+
+  const ext = result.extraction;
+  if (ext) {
+    say(`[distill-sessions] 抽句：${ext.lines} 行 / ${ext.events} 个事件 ⇒ 候选 ${ext.candidates} 条（挡下：${ext.skippedLine}）`);
+  }
+  if (result.source?.compressed) say(`[distill-sessions] ${result.source.note}`);
+  for (const warning of result.warnings ?? []) say(`[distill-sessions] ⚠️ ${warning}`);
+
+  // 结论类几行**不受 --quiet 影响**：--quiet 只压过程日志，压掉结论等于不告诉你跑没跑。
+  const emit = (line) => process.stdout.write(`${line}\n`);
+
+  if (result.stopping === 'NO_BUDGET') {
+    emit(`[distill-sessions] ${NO_BUDGET_MESSAGE}`);
+    say(`[distill-sessions] 怎么配：给 --max-tokens <n>（真跑时会写进台账），或先一次 --dry-run 看估算 token。`);
+  } else if (result.stopping === 'BUDGET_SPENT' || result.stopping === 'ESTIMATE_OVER') {
+    emit(`[distill-sessions] ${result.message}`);
+  } else if (result.stopping === 'SOURCE_UNREADABLE') {
+    process.stderr.write(`❌ ${result.message}\n`);
+  } else if (result.message) {
+    emit(`[distill-sessions] ${result.message}`);
+  }
+
+  if (result.planned?.length) {
+    say('');
+    say(`将写（最多 ${flags.limit ?? DEFAULT_LIMIT} 条）${apply ? '—— 已写' : '—— dry-run 不会写'}：`);
+    for (const item of result.planned) {
+      if (item.conclusion) {
+        say(`  ${item.index}. [L${item.lines?.join(',') ?? '?'}] ${item.conclusion}`);
+        for (const anchor of item.anchors ?? []) say(`       锚：L${anchor.line} ${anchor.anchor}`);
+      } else {
+        say(`  ${item.index}. [${item.kind} · L${item.line}] ${item.text}`);
+        say(`       锚：${item.anchor}`);
+      }
+    }
+  }
+
+  if (result.budget) {
+    const b = result.budget;
+    const budgetLine = b.tokens === null ? '未配置' : `${b.spent}/${b.tokens} token（剩余 ${b.remaining}，来源 ${b.source}）`;
+    say('');
+    say(`预算：${budgetLine}${result.tokens ? ` · 本轮估算 ${result.tokens.estimated} token` : ''}`);
+  }
+  if (result.model) {
+    say(`模型：${result.model.model} · ${result.model.ok ? 'ok' : `失败：${result.model.error}`} · ${result.model.ms}ms · `
+      + `${result.model.promptTokens}+${result.model.completionTokens} token`);
+  }
+  if (apply && result.written) {
+    emit(`写回：${result.written} 条（跳过已存在 ${result.skippedExisting ?? 0} 条）· 快照 ${result.snapshot}`);
+    emit(`撤回：node memory-engine/cli/distill-rollback.mjs --db ${dbPath} --key ${result.srcKey} --apply`);
+  }
+  emit(`[distill-sessions] 结论：${result.stopping ?? 'OK'}${result.exitCode ? `（rc=${result.exitCode}）` : ''}`);
+
+  if (flags.json) {
+    const payload = {
+      ...result,
+      at: new Date(now).toISOString(),
+      srcKey: result.srcKey,
+      srcKeyFull: runKeyOf(runId),
+      candidates: result.planned,
+    };
+    delete payload.warningsText;
+    const written2 = emitJsonReport({ json: true, out: flags.out, payload });
+    say(`JSON → ${written2}`);
+  }
+  return result.exitCode ?? EXIT.OK;
+}
+
+if (isMainEntry(import.meta.url)) {
+  main()
+    .then((code) => { process.exitCode = code ?? 0; })
+    .catch((failure) => settle(failure, { prefix: '[distill-sessions]' }));
+}