@kira905/dsh-memory-toolkit 0.1.3 → 0.2.0

package/memory-engine/cli/sync.mjs

@@ -1,68 +1,104 @@
-// 记忆引擎 v2 · 离线层 —— 增量同步 CLI
+// 增量同步入口：把数据源里新增/改过的条目编码进独立向量库。
+// 源库只读、向量库只写；--dry-run 时一条都不落盘，只报计划与差异。
+// 换模型 / 换维度 / --full ⇒ 自动转全量重建（清掉该来源的旧向量再编）。
 //
-// 用法：
-//   node cli/sync.mjs                        # 增量（只读 memory.db → 写 vectors.db）
-//   node cli/sync.mjs --full                 # 全量重建（换模型/维度也自动触发）
-//   node cli/sync.mjs --dry-run              # 只算不写（计划与差异）
-//   node cli/sync.mjs --json                 # 机器可读（日志走 stderr）
-//   node cli/sync.mjs --stub-embedder        # 骨架模式（无模型依赖）
-//   node cli/sync.mjs --source pitfall       # 同步**坑库**来源（默认 memory；两来源共库、meta 分命名空间）
-//   路径可注入：--memory-db / --vectors-db / --pitfalls-file / --model-dir / --model / --dim / --batch
+// 路径与模型一律可注入：--memory-db / --vectors-db / --pitfalls-file / --model-dir / --model / --dim / --batch
+// 退出码：0 = 跑完（0 条也算跑完）· 1 = 中途失败（进度已保存，可直接续跑）· 2 = 启动即炸。
 import { isMainEntry, parseArgs, makeLogger, openRuntime, num } from '../lib/cli-util.mjs';
 import { runIncrementalSync } from '../lib/sync.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) });
-  let rt = null;
+  return { flags, json, log: makeLogger({ json, quiet: Boolean(flags.quiet) }) };
+}
+
+/** 开一个运行时，交给回调用，出了什么事都把库关掉 */
+async function withRuntime(flags, work) {
+  const rt = await openRuntime(flags);
   try {
-    rt = await openRuntime(flags);
-    const stats = await runIncrementalSync({
-      source: rt.source,
-      store: rt.store,
-      embedder: rt.embedder,
-      modelId: rt.config.modelId,
-      dim: rt.config.dim,
-      sourceName: rt.sourceName,
-      batchSize: num(flags.batch, rt.config.batchSize),
-      full: Boolean(flags.full),
-      dryRun: Boolean(flags['dry-run']),
-      log,
-    });
-    const out = {
-      ok: !stats.error,
-      source: rt.sourceName,
-      // 兼容字段：默认来源（memory）时语义与旧版一致
-      memoryDb: rt.config.memoryDb,
-      dataSource: rt.source.dbPath,
-      vectorsDb: rt.config.vectorsDb,
-      modelId: rt.config.modelId,
-      ...stats,
-    };
-    if (json) process.stdout.write(JSON.stringify(out, null, 2) + '\n');
-    else {
-      log('');
-      log('=== 增量同步结果 ===');
-      log(`模式        : ${stats.mode}${stats.reasons.length ? `（${stats.reasons.join(' / ')}）` : ''}`);
-      log(`来源        : ${rt.sourceName}（${rt.source.dbPath}）`);
-      log(`向量库      : ${rt.config.vectorsDb}`);
-      log(`模型        : ${rt.config.modelId}（${rt.embedder.dim} 维）`);
-      log(`扫描/编码   : ${stats.scanned} / ${stats.encoded}（同哈希跳过 ${stats.skippedSameHash}）`);
-      log(`向量条数    : ${stats.vectorsBefore} → ${stats.vectorsAfter}`);
-      log(`水位        : ${stats.watermarkStart} → ${stats.watermarkEnd}`);
-      log(`耗时        : ${(stats.elapsedMs / 1000).toFixed(2)}s`);
-      if (stats.error) log(`❌ 失败      : ${stats.error}（进度已保留，可直接续跑）`);
-      else log('✅ 完成');
-    }
-    process.exitCode = stats.error ? 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;
+    return await work(rt);
   } finally {
-    if (rt) rt.close();
+    rt.close();
+  }
+}
+
+/** 起来就炸：json 走 stdout，文本走 logger，退出码固定 2 */
+function oops(json, log, err) {
+  const detail = String(err?.stack ?? err);
+  if (json) process.stdout.write(`${JSON.stringify({ ok: false, error: detail }, null, 2)}\n`);
+  else log(`❌ ${detail}`);
+  process.exitCode = CRASH;
+}
+
+/** 中文占两格：按显示宽度补空格，冒号右对齐 */
+function field(text) {
+  let used = 0;
+  for (const ch of String(text)) used += ch.codePointAt(0) > 0xff ? 2 : 1;
+  return String(text) + ' '.repeat(Math.max(0, COLUMNS - used));
+}
+
+function report(log, view, stats) {
+  const row = (name, value) => log(`${field(name)}: ${value}`);
+  log('');
+  log('=== 增量同步结果 ===');
+  row('模式', stats.mode + (stats.reasons.length ? `（${stats.reasons.join(' / ')}）` : ''));
+  row('来源', `${view.source}（${view.dataSource}）`);
+  row('向量库', view.vectorsDb);
+  row('模型', `${view.modelId}（${view.dim} 维）`);
+  row('扫描/编码', `${stats.scanned} / ${stats.encoded}（同哈希跳过 ${stats.skippedSameHash}）`);
+  row('向量条数', `${stats.vectorsBefore} → ${stats.vectorsAfter}`);
+  row('水位', `${stats.watermarkStart} → ${stats.watermarkEnd}`);
+  row('耗时', `${(stats.elapsedMs / 1000).toFixed(2)}s`);
+  if (stats.error) log(`❌ 失败      : ${stats.error}（进度已保留，可直接续跑）`);
+  else log('✅ 完成');
+}
+
+async function work(rt, flags, log, json) {
+  const { config, embedder, source, sourceName, store } = rt;
+  const stats = await runIncrementalSync({
+    source,
+    store,
+    embedder,
+    modelId: config.modelId,
+    dim: config.dim,
+    sourceName,
+    batchSize: num(flags.batch, config.batchSize),
+    full: Boolean(flags.full),
+    dryRun: Boolean(flags['dry-run']),
+    log,
+  });
+  const out = {
+    ok: !stats.error,
+    source: sourceName,
+    // 兼容老读法：缺省来源（memory）时与旧字段同义
+    memoryDb: config.memoryDb,
+    dataSource: source.dbPath,
+    vectorsDb: config.vectorsDb,
+    modelId: config.modelId,
+    ...stats,
+  };
+  if (json) process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+  else {
+    report(log, {
+      source: sourceName, dataSource: source.dbPath, vectorsDb: config.vectorsDb, modelId: config.modelId, dim: embedder.dim,
+    }, stats);
+  }
+  process.exitCode = stats.error ? FAIL_RUN : OK;
+}
+
+async function main() {
+  const { flags, json, log } = boot();
+  try {
+    await withRuntime(flags, (rt) => work(rt, flags, log, json));
+  } catch (err) {
+    oops(json, log, err);
   }
 }
 

package/memory-engine/config/audit-devices.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "体检工具的「已知设备名」名单。代码里不写死任何机器名 —— 换机器只改这里，或设环境变量 MEMORY_DB_AUDIT_DEVICES（优先生效）。",
+  "_comment_fields": "devices = 设备标【设备：X】里 X 那一段的名单（大小写敏感的子串匹配；数组顺序 = 统计输出里各设备键的顺序）。内置缺省 alpha / beta 只是中性示例名，不代表任何真实机器。",
+  "_comment_why": "名字不认识的一律归 OTHER（结构探针会把它列出来让人复核）；名单为空或全不合法时退回缺省，并打一行警告。",
+  "devices": ["alpha", "beta"]
+}

package/memory-engine/config/bands.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "号段表。单机安装只留一条 local 就够了；多机共用一个记忆库时按机器各加一条。",
+  "_comment_fields": "host = 这一段的名字（自定）；base = 该段起始 id；width = 段宽（所有段共用）。非本机条目要加 remote 才会去读：{ ssh: 别名, node: 远端 node 路径, db: 远端库路径(可省) }。",
+  "self": "local",
+  "width": 1000000,
+  "bands": [{ "host": "local", "base": 2000000 }]
+}

package/memory-engine/config/layers.json

@@ -0,0 +1,7 @@
+{
+  "_comment": "层名集合与缺省层。换一套层名只改这里：代码里没有任何一处写死 core / recall / archival。default 必须在 layers 里。",
+  "_comment_zh": "column = 记忆表上加的那一列的名字；default = 存量行回填到哪一层（绝不影响行数）。",
+  "column": "layer",
+  "layers": ["core", "recall", "archival"],
+  "default": "recall"
+}

package/memory-engine/dict/LICENSE-/350/257/215/345/205/270.md

@@ -0,0 +1,53 @@
+本目录下的「词典.txt」不是本项目原创，它来自 jieba 中文分词项目：
+
+    https://github.com/fxsjy/jieba
+
+原文件是 jieba 的 extra_dict/dict.txt.small（README 里称「占用内存较小的词典」）。
+本插件只保留其中的**词条本身**，去掉了原来的词频和词性两列（本插件不用那两列）。
+
+--------------------------------------------------------------------------
+
+本目录下的「词频.txt」跟「词典.txt」**来自同一个文件**，也是 jieba 的
+extra_dict/dict.txt.small。区别是它**用回了原来被丢掉的那一列「词频」**。
+
+它记的是「这个词在通用中文里有多常见」——跟谁在用、说过什么话都无关。
+插件拿它做一件事：**最常用的那些中文词，不当检索线索**。
+
+每行格式是「词 两位数字」：
+
+    词    通用中文里的常见程度，0 = 最常用，99 = 很具体（越少见数字越大）
+
+算法（生成脚本里就这几行，可复现）：
+
+    稀有度 = 1 - log10(词频 + 1) / log10(最大词频 + 1)     → 0 ~ 1
+    数字   = round(稀有度 × 99)
+
+只收通用中文里**最常见的前 20000 个词**；更靠后的词一律当「很具体」，
+所以查不到就等于 99，不必全收进来（省体积）。
+
+--------------------------------------------------------------------------
+
+jieba 采用 MIT 授权协议。按协议要求，原样附上版权声明：
+
+--------------------------------------------------------------------------
+The MIT License (MIT)
+
+Copyright (c) 2013 Sun Junyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+--------------------------------------------------------------------------

package/memory-engine/dict/lexicon-config.json

@@ -0,0 +1,11 @@
+{
+  "_note": "词表第二路（稀疏召回）的开关文件。enabled=false（出厂值）时这一路完全不存在，召回结果与没有它逐字节一致；改成 true 即启用，不必改代码（改完下一次调用生效）。",
+  "_keys": "enabled 总开关 · topK 这一路给几条候选 · floor 通用词门限 0~1（越大越只用生僻词，0.3 只滤掉最常见的那批） · ttlMs 索引缓存寿命(ms) · k1/b BM25 的 tf 饱和与长度归一键",
+  "_switch": "临时开关：环境变量 MEMORY_ENGINE_LEXICON=on|off（优先级高于本文件）；调用方也可以显式传 lexiconEnabled。",
+  "enabled": false,
+  "topK": 20,
+  "floor": 0.3,
+  "ttlMs": 600000,
+  "k1": 1.2,
+  "b": 0.75
+}