@kira905/dsh-memory-toolkit 0.1.2 → 0.2.0

package/memory-engine/lib/memory-source.mjs

@@ -1,127 +1,125 @@
-// 记忆引擎 v2 · 离线层 —— 记忆库只读数据源
+// 记忆库的只读数据源。
 //
-// 铁律（方案 §3.1 / §7）：对 memory.db 只读，绝不写。只读连接在 DELETE journal 模式下
-// 不阻塞写者，也不被写者阻塞（A6 实测：未提交写不阻塞读）。
+// 契约：对 memory.db 只开只读连接；语句在**打开阶段**一次性备好 —— 表结构不对应当是
+// open 当场就炸，而不是拖到某次查询才现形。只读连接在 DELETE journal 下既不挡写者、
+// 也不被写者挡。
 import fs from 'node:fs';
 import { DatabaseSync } from 'node:sqlite';
 
+const BUSY_TIMEOUT_MS = 5000;
+
+/** 全部预编译语句（键名即内部代号，SQL 文本集中在这里便于比对 schema）。 */
+const STATEMENT_SQL = {
+  count: 'SELECT COUNT(*) AS n FROM memories',
+  maxUpdated: 'SELECT MAX(updated_at) AS m FROM memories',
+  idRange: 'SELECT MIN(id) AS lo, MAX(id) AS hi, COUNT(*) AS n FROM memories',
+  pinned: 'SELECT id FROM memories WHERE pinned = 1 ORDER BY id',
+  page: `SELECT id, text, tags, pinned, updated_at FROM memories
+         WHERE updated_at >= ? AND id > ? ORDER BY id LIMIT ?`,
+  segment: `SELECT id, text, tags, pinned, updated_at FROM memories
+            WHERE id >= ? AND id <= ? ORDER BY id`,
+  byId: 'SELECT id, text, tags, pinned, created_at, updated_at FROM memories WHERE id = ?',
+  allTexts: 'SELECT id, text FROM memories ORDER BY id',
+  allTags: 'SELECT id, tags, updated_at FROM memories',
+  recent: 'SELECT id FROM memories ORDER BY updated_at DESC, id DESC LIMIT ?',
+};
+
+/** FTS5 补位：中文连续串几乎不可用，只补标签/英文/数字。 */
+const FTS_SQL = `SELECT m.id AS id, m.pinned AS pinned, bm25(memories_fts) AS score
+                 FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid
+                 WHERE memories_fts MATCH ? AND m.pinned = 0
+                 ORDER BY score LIMIT ?`;
+
+function asVecRow(r) {
+  return {
+    id: Number(r.id),
+    text: r.text,
+    tags: r.tags,
+    pinned: Number(r.pinned),
+    updated_at: Number(r.updated_at),
+  };
+}
+
+const nullableNumber = (v) => (v == null ? null : Number(v));
+
 export function openMemorySource(dbPath) {
   if (!fs.existsSync(dbPath)) {
     throw new Error(`记忆库不存在: ${dbPath}`);
   }
+
   const db = new DatabaseSync(dbPath, { readOnly: true });
-  db.exec('PRAGMA busy_timeout = 5000;');
-
-  const S = {
-    count: db.prepare('SELECT COUNT(*) AS n FROM memories'),
-    maxUpdated: db.prepare('SELECT MAX(updated_at) AS m FROM memories'),
-    idRange: db.prepare('SELECT MIN(id) AS lo, MAX(id) AS hi, COUNT(*) AS n FROM memories'),
-    pinned: db.prepare('SELECT id FROM memories WHERE pinned = 1 ORDER BY id'),
-    page: db.prepare(
-      `SELECT id, text, tags, pinned, updated_at FROM memories
-       WHERE updated_at >= ? AND id > ? ORDER BY id LIMIT ?`,
-    ),
-    segment: db.prepare(
-      `SELECT id, text, tags, pinned, updated_at FROM memories
-       WHERE id >= ? AND id <= ? ORDER BY id`,
-    ),
-    byId: db.prepare(
-      'SELECT id, text, tags, pinned, created_at, updated_at FROM memories WHERE id = ?',
-    ),
-    allTexts: db.prepare('SELECT id, text FROM memories ORDER BY id'),
-    tagsOf: db.prepare('SELECT id, tags, updated_at FROM memories'),
-  };
+  db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS};`);
+
+  const q = {};
+  for (const [key, sql] of Object.entries(STATEMENT_SQL)) q[key] = db.prepare(sql);
+
+  let closed = false;
+  // FTS 表可能不存在 / 表达式可能非法 ⇒ 语句**懒备**，失败要走「补位路径空」而不是让 open 失败
+  let ftsStmt = null;
 
   return {
     dbPath,
     readOnly: true,
 
-    count() {
-      return Number(S.count.get().n);
-    },
+    count: () => Number(q.count.get().n),
 
-    maxUpdatedAt() {
-      const v = S.maxUpdated.get().m;
+    maxUpdatedAt: () => {
+      const v = q.maxUpdated.get().m;
       return v == null ? 0 : Number(v);
     },
 
-    idRange() {
-      const r = S.idRange.get();
-      return { lo: r.lo == null ? null : Number(r.lo), hi: r.hi == null ? null : Number(r.hi), n: Number(r.n) };
+    idRange: () => {
+      const r = q.idRange.get();
+      return { lo: nullableNumber(r.lo), hi: nullableNumber(r.hi), n: Number(r.n) };
     },
 
-    /** 召回用：pinned 集合（方案 §3.3：召回排除 pinned，交给 dsh-memory 注入） */
-    pinnedIds() {
-      return S.pinned.all().map((r) => Number(r.id));
-    },
+    /** 召回排除集合（pinned 条目由宿主插件注入，引擎侧不重复给）。 */
+    pinnedIds: () => q.pinned.all().map((r) => Number(r.id)),
 
-    /** 增量页：updated_at >= sinceTs 且 id > afterId，按 id 升序 */
-    incrementalPage(sinceTs, afterId, limit) {
-      return S.page.all(Number(sinceTs), Number(afterId), Number(limit)).map(mapRow);
-    },
+    /** 增量页：updated_at >= sinceTs 且 id > afterId，按 id 升序。 */
+    incrementalPage: (sinceTs, afterId, limit) =>
+      q.page.all(Number(sinceTs), Number(afterId), Number(limit)).map(asVecRow),
 
-    /** id 段（兜底 hash 轮转用） */
-    segment(lo, hi) {
-      return S.segment.all(Number(lo), Number(hi)).map(mapRow);
-    },
+    /** id 闭区间段（兜底轮转用）。 */
+    segment: (lo, hi) => q.segment.all(Number(lo), Number(hi)).map(asVecRow),
 
-    getById(id) {
-      const r = S.byId.get(Number(id));
+    getById: (id) => {
+      const r = q.byId.get(Number(id));
       return r ? { ...r, id: Number(r.id) } : null;
     },
 
-    /** 全表 id + 正文（兜底校验用；570 条量级纯内存可承受） */
-    allTexts() {
-      return S.allTexts.all().map((r) => ({ id: Number(r.id), text: r.text }));
-    },
+    /** 全表 id + 正文（兜底校验用，体量在内存可承受范围内）。 */
+    allTexts: () => q.allTexts.all().map((r) => ({ id: Number(r.id), text: r.text })),
 
-    allTags() {
-      return S.tagsOf.all().map((r) => ({ id: Number(r.id), tags: r.tags }));
-    },
+    allTags: () => q.allTags.all().map((r) => ({ id: Number(r.id), tags: r.tags })),
+
+    /** 最近改动的若干条（降级兜底用：编码失败时按这个顺序给固定 Top-K，不依赖向量）。 */
+    recent: (limit) => q.recent.all(Math.max(1, Math.trunc(Number(limit) || 1))).map((r) => ({ id: Number(r.id) })),
 
-    /**
-     * FTS5 补位检索（方案 §3.4 A4：中文连续串几近不可用，只补标签/英文/数字）。
-     * @param {string} matchExpr 已构造好的 FTS5 MATCH 表达式
-     */
     ftsSearch(matchExpr, limit) {
       try {
-        return db
-          .prepare(
-            `SELECT m.id AS id, m.pinned AS pinned, bm25(memories_fts) AS score
-             FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid
-             WHERE memories_fts MATCH ? AND m.pinned = 0
-             ORDER BY score LIMIT ?`,
-          )
+        if (!ftsStmt) ftsStmt = db.prepare(FTS_SQL);
+        return ftsStmt
           .all(String(matchExpr), Number(limit))
           .map((r) => ({ id: Number(r.id), score: Number(r.score) }));
       } catch (e) {
-        // 表达式非法/表缺失 → 补位路径空（方案 §3.3：FTS 缺失时不参与，不做零分占位）
+        // 表达式非法 / 表缺失：补位路径返回空，不做零分占位
         return { error: String(e && e.message ? e.message : e) };
       }
     },
 
     close() {
-      // 幂等：重复 close 不得抛错（调用方常在 finally 里再关一次）
-      if (this._closed) return;
-      this._closed = true;
+      if (closed) return;
+      closed = true;
       try {
         db.close();
       } catch {
-        /* ignore */
+        /* 关闭失败不算错：调用方常在 finally 里重复关 */
       }
     },
+
     get closed() {
-      return Boolean(this._closed);
+      return closed;
     },
   };
 }
-
-function mapRow(r) {
-  return {
-    id: Number(r.id),
-    text: r.text,
-    tags: r.tags,
-    pinned: Number(r.pinned),
-    updated_at: Number(r.updated_at),
-  };
-}

package/memory-engine/lib/pitfall-source.mjs

@@ -1,47 +1,67 @@
-// 记忆引擎 v2 · 离线层 —— **坑库只读数据源**（方案 §3 A 点 · 第二向量来源 source='pitfall'）
+// 坑库的只读数据源：把 `butler-pitfalls.json` 摆成与记忆源一模一样的形状。
 //
-// 为什么需要它：开工简报原来无差别取 `topN(pitfalls,3)`（与本次任务语义无关，229 条里永远只看最高 3 条）。
-// A 点要把「坑库」变成向量库里的第二个来源，让开工简报按任务语义召回相关坑。
+// 为什么要有它：开工简报原来固定取"出现最多的三条"，跟本轮任务毫无关系；
+// 有了这个源，坑条目也能按语义被召回。
 //
-// 铁律（方案 §A.2 / §A.4）：
-//   1. **只读** `butler-pitfalls.json`（A 点不写它）；`readOnly: true` 是自证字段。
-//   2. 接口必须与 `memory-source.mjs` 的 `openMemorySource` **同形状**（硬契约）——
-//      下游三个消费面按方法名硬调用：`sync.mjs:81 incrementalPage` / `sweep.mjs:36 idRange`+`:69 segment`
-//      / `recall.mjs:120 pinnedIds`+`:141 ftsSearch`。少一个方法 = 第一次跑就 `is not a function`。
-//      ⚠️ 方案旧文写的 `{ list(), count(), maxSeen() }` 是**错的**（`maxSeen` 在对照物里不存在，实际名 `maxUpdatedAt`）。
-//   3. `segment()` / `incrementalPage()` 返回行**必须含 `id / text / updated_at`**：
-//      `sweep.mjs:77` 读 `r.text`、`:110` 取 `r.updated_at`，缺 `updated_at` 不报错、只会把 `undefined` 写进向量行。
-//   4. 轮转语义**不是 id 段**：坑无数字 id 段 ⇒ `idRange()` 给 `{lo:0,hi:n-1,n}`（稳定等价量，= 排序后下标），
-//      `segment(lo,hi)` 按 `lastSeen` 升序（平局按 `id` 字典序）切片；`incrementalPage` 用同一排序做**稳定游标**。
+// 四条不许破的口径：
+//   1. 只读那个 JSON，一个字节都不回写；`readOnly:true` 是自证字段。
+//   2. 方法与记忆源一一对应（下游按名字硬调，少一个当场 is not a function）：
+//      count / maxUpdatedAt / idRange / pinnedIds / incrementalPage / segment /
+//      getById / allTexts / allTags / ftsSearch / close。注意名字是 maxUpdatedAt。
+//   3. 分页与分段吐出来的行必须带 id / text / updated_at —— 上层直接取，
+//      缺了不会报错，只会把 undefined 写进向量行。
+//   4. 坑没有数字 id 段：idRange 给"排序后的下标区间"，排序键是 lastSeen 升序、
+//      平局按 id 字典序；分页沿用同一套顺序做游标，所以集合中途变了也只多扫不漏、不重复。
+
 import fs from 'node:fs';
 
-/** 坑条目的向量文本（方案 §A.3 定稿；**不含**建议文本 —— 候选池的 suggested/why 不进向量，避免建议变化导致向量漂移） */
+const SEED_MARK = '[seed]';
+const CURSOR_WIDTH = 16;
+
+/** 一条坑进向量的文本：seed 标记 + 分类前缀 + 正文 + 工具后缀；建议文本一律不进（会随建议漂移）。 */
 export function pitfallText(row) {
-  const cat = row.category ? `[${row.category}] ` : '';
-  const seed = String(row.source || '') === 'seed' ? '[seed]' : '';
+  const seed = String(row.source || '') === 'seed' ? SEED_MARK : '';
+  const label = row.category ? `[${row.category}] ` : '';
   const tools = row.tools && typeof row.tools === 'object' ? Object.keys(row.tools).join(',') : '';
-  return `${seed}${cat}${row.normText ?? ''}${tools ? ` | tools=${tools}` : ''}`;
+  const suffix = tools ? ` | tools=${tools}` : '';
+  return `${seed}${label}${row.normText ?? ''}${suffix}`;
 }
 
-function sortRows(rows) {
-  return rows
-    .slice()
-    .sort((a, b) => a.updated_at - b.updated_at || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+// 工具字段的规范形态：对象取键名拼串，其它一律空串。
+function toolsText(item) {
+  if (!item.tools || typeof item.tools !== 'object') return '';
+  return Object.keys(item.tools).join(',');
 }
 
-/** 稳定游标键：`<lastSeen 补零>|<id>`（同 `sortRows` 的序即字符串序，平局按 id 字典序） */
-function cursorKey(lastSeen, id) {
-  return `${String(lastSeen).padStart(16, '0')}|${id}`;
+// 稳定顺序：先 lastSeen，再 id 字典序。平局必须先定死，否则翻页会来回抖。
+function byLastSeenThenId(a, b) {
+  if (a.updated_at !== b.updated_at) return a.updated_at - b.updated_at;
+  if (a.id === b.id) return 0;
+  return a.id < b.id ? -1 : 1;
 }
 
-function mapRow(r) {
-  return {
-    id: r.id,
-    text: r.text,
-    tags: r.tags,
-    pinned: 0,
-    updated_at: r.updated_at,
-  };
+// 游标的可比较形态：时间戳左补零到定长，再接 '|' 与 id ⇒ 字典序正好等于上面的顺序。
+function cursorOf(updatedAt, id) {
+  return `${String(updatedAt).padStart(CURSOR_WIDTH, '0')}|${id}`;
+}
+
+// 内层行 → 向量层要的形状（pinned 恒 0：坑库没有这个字段）
+function toPageRow(row) {
+  return { id: row.id, text: row.text, tags: row.tags, pinned: 0, updated_at: row.updated_at };
+}
+
+// 解析文件并取出条目数组：顶层直接是数组、或外面套一层 `pitfalls` 都认。
+function readEntryList(jsonPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+  } catch (e) {
+    const why = e && e.message ? e.message : String(e);
+    throw new Error(`坑库解析失败: ${jsonPath}（${why}）`);
+  }
+  const list = Array.isArray(parsed) ? parsed : Array.isArray(parsed.pitfalls) ? parsed.pitfalls : null;
+  if (!list) throw new Error(`坑库结构不认识（应含 pitfalls 数组）: ${jsonPath}`);
+  return list;
 }
 
 /**
@@ -52,119 +72,100 @@ export function openPitfallSource(jsonPath) {
   if (!fs.existsSync(jsonPath)) {
     throw new Error(`坑库不存在: ${jsonPath}`);
   }
-  let raw;
-  try {
-    raw = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
-  } catch (e) {
-    throw new Error(`坑库解析失败: ${jsonPath}（${String(e && e.message ? e.message : e)}）`);
-  }
-  const list = Array.isArray(raw) ? raw : Array.isArray(raw.pitfalls) ? raw.pitfalls : null;
-  if (!list) throw new Error(`坑库结构不认识（应含 pitfalls 数组）: ${jsonPath}`);
 
-  const rows = sortRows(
-    list
-      .filter((x) => x && x.id != null)
-      .map((x) => ({
-        id: String(x.id),
-        text: pitfallText(x),
-        tags: x.tools && typeof x.tools === 'object' ? Object.keys(x.tools).join(',') : '',
-        updated_at: Number(x.lastSeen || 0),
-      })),
-  );
-  const byId = new Map(rows.map((r) => [r.id, r]));
-
-  let closed = false;
+  const rows = readEntryList(jsonPath)
+    .filter((item) => item && item.id != null)
+    .map((item) => ({
+      id: String(item.id),
+      text: pitfallText(item),
+      tags: toolsText(item),
+      updated_at: Number(item.lastSeen || 0),
+    }))
+    .sort(byLastSeenThenId);
+  const index = new Map(rows.map((row) => [row.id, row]));
+
+  let shut = false;
   return {
     dbPath: jsonPath,
     readOnly: true,
-    /** 自证：来源名（下游日志/自检按它报"逐 source"） */
+    /** 自证：下游日志/自检按它报"逐来源" */
     sourceName: 'pitfall',
-    /** 原始条目数（= rows.length；观测用） */
+    /** 条目总数（观测用，等于 rows.length） */
     n: rows.length,
 
-    count() {
-      return rows.length;
-    },
+    count: () => rows.length,
 
-    maxUpdatedAt() {
-      let m = 0;
-      for (const r of rows) if (r.updated_at > m) m = r.updated_at;
-      return m;
-    },
+    maxUpdatedAt: () => rows.reduce((peak, row) => (row.updated_at > peak ? row.updated_at : peak), 0),
 
-    /** 坑无数字 id 段 ⇒ 给稳定等价量（排序后下标区间） */
-    idRange() {
-      if (!rows.length) return { lo: null, hi: null, n: 0 };
-      return { lo: 0, hi: rows.length - 1, n: rows.length };
-    },
+    /** 坑没有数字 id ⇒ 给稳定等价量：排序后的下标闭区间。 */
+    idRange: () => (rows.length ? { lo: 0, hi: rows.length - 1, n: rows.length } : { lo: null, hi: null, n: 0 }),
 
-    /** 坑库无 pinned 概念 ⇒ 空集（召回侧据此不排除任何条目） */
-    pinnedIds() {
-      return [];
-    },
+    /** 坑库没有 pinned 概念 ⇒ 永远空集（召回侧据此不排除任何条目）。 */
+    pinnedIds: () => [],
 
     /**
-     * 增量页：`updated_at >= sinceTs`，按 (lastSeen, id) 升序，游标 = 上一页末条 `id`。
-     * 游标按「键比较」而非仅按下标：翻页期间即使集合变化也不会重复/跳过（键比较天然幂等）。
+     * 增量页：取 `updated_at >= sinceTs` 的条目，按 (lastSeen, id) 升序往后翻，
+     * 游标就是上一页末条的 id。游标按"键比较"而不是按下标 ⇒ 中途删改也不会重也不会漏。
      */
-    incrementalPage(sinceTs, afterId, limit) {
+    incrementalPage: (sinceTs, afterId, limit) => {
       const since = Number(sinceTs) || 0;
-      const lim = Number(limit) || 0;
-      if (!rows.length || lim <= 0) return [];
-      const cur = afterId == null || afterId === '' ? null : String(afterId);
+      const cap = Number(limit) || 0;
+      if (!rows.length || cap <= 0) return [];
+      const cursorId = afterId == null || afterId === '' ? null : String(afterId);
       let floor = '';
-      if (cur != null) {
-        const hit = byId.get(cur);
-        if (hit) floor = cursorKey(hit.updated_at, hit.id);
-        else floor = cursorKey(0, cur); // 游标条已被删：退化成"按 id 起步"（仍单调、不重复）
+      if (cursorId != null) {
+        const known = index.get(cursorId);
+        // 游标条已经被删：退化成"从这个 id 起步"，整体仍然单调
+        floor = known ? cursorOf(known.updated_at, known.id) : cursorOf(0, cursorId);
       }
-      const out = [];
-      for (const r of rows) {
-        if (r.updated_at < since) continue;
-        if (floor && cursorKey(r.updated_at, r.id) <= floor) continue;
-        out.push(mapRow(r));
-        if (out.length >= lim) break;
+      const page = [];
+      for (const row of rows) {
+        if (row.updated_at < since) continue;
+        if (floor && cursorOf(row.updated_at, row.id) <= floor) continue;
+        page.push(toPageRow(row));
+        if (page.length >= cap) break;
       }
-      return out;
+      return page;
     },
 
-    /** 段（下标区间，排序 = lastSeen 升序）：返回行含 id/text/updated_at（sweep 硬契约） */
-    segment(lo, hi) {
-      const a = Number(lo);
-      const b = Number(hi);
-      if (!Number.isFinite(a) || !Number.isFinite(b)) return [];
-      return rows.slice(Math.max(0, a), Math.max(0, b) + 1).map(mapRow);
+    /** 段（下标闭区间，顺序 = lastSeen 升序）：行里必须带 text 与 updated_at，上层直接取。 */
+    segment: (lo, hi) => {
+      const begin = Number(lo);
+      const end = Number(hi);
+      if (!Number.isFinite(begin) || !Number.isFinite(end)) return [];
+      const from = Math.max(0, begin);
+      return rows.slice(from, Math.max(0, end) + 1).map(toPageRow);
     },
 
-    getById(id) {
-      const r = byId.get(String(id));
-      if (!r) return null;
-      return { id: r.id, text: r.text, tags: r.tags, pinned: 0, created_at: r.updated_at, updated_at: r.updated_at };
+    getById: (id) => {
+      const found = index.get(String(id));
+      if (!found) return null;
+      return {
+        id: found.id,
+        text: found.text,
+        tags: found.tags,
+        pinned: 0,
+        created_at: found.updated_at,
+        updated_at: found.updated_at,
+      };
     },
 
-    allTexts() {
-      return rows.map((r) => ({ id: r.id, text: r.text }));
-    },
+    allTexts: () => rows.map((row) => ({ id: row.id, text: row.text })),
 
-    allTags() {
-      return rows.map((r) => ({ id: r.id, tags: r.tags }));
-    },
+    allTags: () => rows.map((row) => ({ id: row.id, tags: row.tags })),
 
     /**
-     * ⚠️ 坑库**没有 FTS5** ⇒ 必须返回对象而不是抛错（`recall.mjs:141` 期望拿到对象、拿数组才走补位路）。
-     * 照 `memory-source.mjs:86-101` 的兜底形状。
+     * 坑库没有 FTS5 ⇒ 这里必须回一个对象而不是抛错：
+     * 召回侧拿对象就走"无关键词补位"那条路，抛错会整条链断掉。
      */
-    ftsSearch() {
-      return { error: '坑库无 FTS5（pitfall source 无 FTS 补位路）' };
-    },
+    ftsSearch: () => ({ error: '坑库无 FTS5（pitfall source 无 FTS 补位路）' }),
 
     close() {
-      // 幂等：重复 close 不得抛错（调用方常在 finally 里再关一次）
-      if (closed) return;
-      closed = true;
+      // 幂等：调用方常在 finally 里再关一次，重复关不许抛
+      shut = true;
     },
     get closed() {
-      return closed;
+      return shut;
     },
   };
 }