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

package/memory-engine/test/11-policy-source.test.mjs

@@ -0,0 +1,224 @@
+// 记忆引擎 v2 · 离线层 —— policy 来源（方案 §4 B 点）单测
+//
+// 覆盖：① persona 块标量抽取；② 段化规则（【…】/`- 【…】`/`##`、≤400 字硬上限、超长按句切）；
+//   ③ 段身份锚（refId 稳定 / 唯一 / 与正文无关 ⇒ 改正文是"同一条换 text_hash"）；
+//   ④ 与 memory-source 同形状（sync/sweep 会按方法名硬调用）；⑤ `sync --source policy` 端到端 + 幂等；
+//   ⑥ **默认行为不变**（不传 --source 仍走 memory）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { test, assert, assertEq, section } from './harness.mjs';
+import { makeTempRoot, makeMemoryDb, sampleRows } from './fixtures.mjs';
+import {
+  POLICY_MAX_CHARS,
+  extractPersonaText,
+  segmentText,
+  scanPolicySources,
+  openPolicySource,
+  policyRefId,
+  normalizeDocPath,
+} from '../lib/policy-source.mjs';
+import { openDataSource, KNOWN_SOURCES } from '../lib/cli-util.mjs';
+import { openVectorsStore, countVectors, getMetaFor, META_KEYS } from '../lib/vectors-store.mjs';
+import { runIncrementalSync } from '../lib/sync.mjs';
+import { createStubEmbedder } from '../lib/embedder.mjs';
+import { openMemorySource } from '../lib/memory-source.mjs';
+import { openPitfallSource } from '../lib/pitfall-source.mjs';
+
+export const __section = 'B 点 · policy 段源（抽取 / 段化 / 契约 / sync 端到端）';
+
+const TMP = makeTempRoot('memv2-policy-');
+
+/** 造一棵隔离语料树（persona + skills），返回 { personaDir, skillsRoot } */
+function makeCorpus(name) {
+  const root = path.join(TMP.root, name);
+  const personaDir = path.join(root, '.agent-presets', 'demo');
+  const skillsRoot = path.join(root, 'skills');
+  fs.mkdirSync(personaDir, { recursive: true });
+  fs.mkdirSync(path.join(skillsRoot, 'demo-skill'), { recursive: true });
+  fs.writeFileSync(
+    path.join(personaDir, 'agent.cordis.yml'),
+    [
+      '# 注释行（不进 persona）',
+      '- id: persona',
+      '  config:',
+      '    prefix: |-',
+      '      你是本鱼。',
+      '',
+      '      【身份】软萌鲸鱼娘。',
+      '',
+      '      【协作偏好】',
+      '      - 【规矩甲】甲甲甲。',
+      '      - 【规矩乙】乙乙乙。',
+      '',
+      '      【能力】能干活。',
+      '    suffix: |-',
+      '      不该被抽进来。',
+    ].join('\n'),
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(skillsRoot, 'demo-skill', 'SKILL.md'),
+    ['---', 'name: demo-skill', '---', '# demo', '', '## 一、第一段', '内容内容。', '', '## 二、第二段', '更多内容。'].join('\n'),
+    'utf8',
+  );
+  return { root, personaDir, skillsRoot };
+}
+
+section('① persona 块标量抽取（extractPersonaText）');
+test('抽 prefix: |- 的块内容，遇到去缩进行即停（suffix 不进）', () => {
+  const { personaDir } = makeCorpus('c1');
+  const raw = fs.readFileSync(path.join(personaDir, 'agent.cordis.yml'), 'utf8');
+  const t = extractPersonaText(raw);
+  assert(t.includes('你是本鱼。'), '应含首行');
+  assert(t.includes('【身份】'), '应含 【身份】');
+  assert(t.includes('【规矩甲】'), '应含列表式 【规矩甲】');
+  assert(!t.includes('不该被抽进来'), 'suffix 块不得混入');
+  assert(!t.includes('# 注释行'), '块外注释不得混入');
+});
+test('抽不到块标量 ⇒ 退回整份文本（不抛错、不断链）', () => {
+  const t = extractPersonaText('随便一段文本\n没有块标量');
+  assertEq(t, '随便一段文本\n没有块标量');
+});
+
+section('② 段化规则');
+test('persona：行首 【…】 与 `- 【…】` 都算段起点', () => {
+  const text = '你是本鱼。\n\n【身份】甲。\n\n【偏好】\n- 【规矩甲】甲甲。\n- 【规矩乙】乙乙。\n';
+  const segs = segmentText(text, { kind: 'persona' });
+  const labels = segs.map((s) => s.section);
+  assert(labels.some((x) => x.includes('【身份】')), `应有 【身份】段：${labels.join(' | ')}`);
+  assert(labels.some((x) => x.includes('【规矩甲】')), `应有 【规矩甲】段：${labels.join(' | ')}`);
+  assert(labels.some((x) => x.includes('【规矩乙】')), `应有 【规矩乙】段：${labels.join(' | ')}`);
+});
+test('markdown：按 ## / ### 切小节', () => {
+  const segs = segmentText('前言\n\n## 甲\n甲甲\n\n### 乙\n乙乙\n', { kind: 'markdown' });
+  assert(segs.some((s) => s.section.startsWith('## 甲')), '应有 ## 甲');
+  assert(segs.some((s) => s.section.startsWith('### 乙')), '应有 ### 乙');
+});
+test('≤400 字硬上限：长段按句切，且无一段超上限', () => {
+  const long = `## 长段\n${'这是一句很长的话。'.repeat(80)}`;
+  const segs = segmentText(long, { kind: 'markdown' });
+  assert(segs.length > 1, `应被切成多段，实际 ${segs.length}`);
+  for (const s of segs) assert(s.text.length <= POLICY_MAX_CHARS, `段超上限：${s.text.length}`);
+});
+test('超长无标点块：硬切到上限内', () => {
+  const segs = segmentText('## 硬切\n' + 'x'.repeat(1000), { kind: 'markdown' });
+  assert(segs.length >= 3, `应硬切多段，实际 ${segs.length}`);
+  for (const s of segs) assert(s.text.length <= POLICY_MAX_CHARS, `段超上限：${s.text.length}`);
+});
+
+section('③ 段身份锚（refId）');
+test('refId 稳定：同输入两次扫描逐条相同', () => {
+  const { personaDir, skillsRoot } = makeCorpus('c3');
+  const a = scanPolicySources({ personaDir, skillsRoot });
+  const b = scanPolicySources({ personaDir, skillsRoot });
+  assertEq(a.map((x) => x.refId), b.map((x) => x.refId), 'refId 序列应逐条相同');
+  assert(a.length > 0, '应有段');
+});
+test('refId 唯一（同文件同名小节重复出现也不撞）', () => {
+  const { personaDir, skillsRoot } = makeCorpus('c3b');
+  const segs = scanPolicySources({ personaDir, skillsRoot });
+  const set = new Set(segs.map((s) => s.refId));
+  assertEq(set.size, segs.length, `refId 应唯一：${segs.length} 段 / ${set.size} 唯一`);
+});
+test('refId 只由「文件+段锚+分片号」决定 ⇒ 改正文不动 refId（增量重编码而非产生孤儿）', () => {
+  const id1 = policyRefId('/x/a.md', '## 甲#1', 1);
+  const id2 = policyRefId('/x/a.md', '## 甲#1', 1);
+  const id3 = policyRefId('/x/a.md', '## 甲#1', 2);
+  assertEq(id1, id2, '同参应同 id');
+  assert(id1 !== id3, '不同分片号应不同 id');
+  assertEq(id1.length, 16, '应为 16 位 hex');
+  assert(/^[0-9a-f]{16}$/.test(id1), '应为 hex');
+});
+test('normalizeDocPath：反斜杠转正斜杠 + 盘符小写', () => {
+  const winPath = path.win32.join('Q:', 'A', 'b', 'C.MD');
+  const expected = path.win32.join('q:', 'A', 'b', 'C.MD').replace(/\\/g, '/');
+  assertEq(normalizeDocPath(winPath), expected);
+});
+
+section('④ 契约：与 memory-source / pitfall-source 同形状');
+test('policy 源具备 sync/sweep/recall 硬调用的全部方法', () => {
+  const { personaDir, skillsRoot } = makeCorpus('c4');
+  const src = openPolicySource({ segments: scanPolicySources({ personaDir, skillsRoot }) });
+  for (const m of ['count', 'maxUpdatedAt', 'idRange', 'pinnedIds', 'incrementalPage', 'segment', 'getById', 'allTexts', 'allTags', 'ftsSearch', 'close']) {
+    assert(typeof src[m] === 'function', `缺方法 ${m}`);
+  }
+  assertEq(src.sourceName, 'policy');
+  assertEq(src.pinnedIds(), []);
+  assertEq(src.ftsSearch(), { error: 'policy 段源无 FTS5（policy source 无 FTS 补位路）' });
+  const r = src.idRange();
+  assert(r.n === src.count(), 'idRange.n 应等于 count()');
+});
+test('segment / incrementalPage 返回行必含 id/text/updated_at（缺 updated_at 会写 undefined 进向量）', () => {
+  const { personaDir, skillsRoot } = makeCorpus('c4b');
+  const src = openPolicySource({ segments: scanPolicySources({ personaDir, skillsRoot }) });
+  const rng = src.idRange();
+  const rows = src.segment(rng.lo, Math.min(rng.hi, rng.lo + 1)).concat(src.incrementalPage(0, null, 3));
+  assert(rows.length > 0, '应有行');
+  for (const r of rows) {
+    assert(r.id !== undefined && r.text !== undefined && r.updated_at !== undefined, `行字段缺失：${JSON.stringify(Object.keys(r))}`);
+    assert(typeof r.updated_at === 'number' && Number.isFinite(r.updated_at), 'updated_at 应为有限数字');
+  }
+});
+test('KNOWN_SOURCES 含 policy；openDataSource("policy") 可开、未知来源仍抛错', () => {
+  assert(KNOWN_SOURCES.includes('policy'), 'KNOWN_SOURCES 应含 policy');
+  const { personaDir, skillsRoot } = makeCorpus('c4c');
+  const src = openDataSource('policy', { policyPersonaDir: personaDir, policySkillsRoot: skillsRoot });
+  assert(src.sourceName === 'policy' && src.count() > 0, '应开出非空 policy 源');
+  let threw = false;
+  try { openDataSource('nope', {}); } catch { threw = true; }
+  assert(threw, '未知来源应抛错');
+});
+
+section('⑤ sync --source policy 端到端 + 幂等 + 不串味');
+test('sync policy：写入 source=policy，条数 = 段数；重跑同哈希跳过', async () => {
+  const { personaDir, skillsRoot } = makeCorpus('c5');
+  const segs = scanPolicySources({ personaDir, skillsRoot });
+  const store = openVectorsStore(path.join(TMP.root, 'c5', 'v.db'), { create: true });
+  const embedder = createStubEmbedder({ dim: 64, modelId: 'stub' });
+  const src = openPolicySource({ segments: segs });
+  const r1 = await runIncrementalSync({ source: src, store, embedder, modelId: 'stub', dim: 64, sourceName: 'policy' });
+  assertEq(r1.encoded, segs.length, '首次应全量编码');
+  assertEq(countVectors(store.db, 'policy'), segs.length, '应写入同条数向量');
+  assertEq(countVectors(store.db, 'memory'), 0, '不得写到 memory 源');
+  const r2 = await runIncrementalSync({ source: openPolicySource({ segments: segs }), store, embedder, modelId: 'stub', dim: 64, sourceName: 'policy' });
+  assertEq(r2.encoded, 0, '重跑应同哈希跳过（幂等，零重编码）');
+  assertEq(r2.vectorsAfter, segs.length, '向量条数应保持不变（无新增/重复）');
+  assertEq(r2.skippedSameHash, r2.scanned, '本轮扫到的应全部同哈希跳过');
+  // ⚠️ 语义说明（实测口径，别写成"每轮都全表重扫"）：水位 = `max(updated_at)`，而 policy 段的
+  //    `updated_at` = **文件 mtime** ⇒ 同文件的多段共享同一时间戳，水位一推进就把整个文件带过去了
+  //    ⇒ 第二轮只重扫「mtime 最新的那一批」（可能少于全量）。这是**设计内**行为（与 memory 源同款
+  //    watermark 语义），不变量是「不重编码、条数不变」；漏改由 `sweep --source policy` 按 text_hash 兜底。
+  assert(r2.scanned <= segs.length, `本轮扫描数不应超过全量：${r2.scanned} vs ${segs.length}`);
+  store.db.close();
+});
+test('跨源不串味：跑完 policy 后 memory 侧四类水位键不受影响', async () => {
+  const { personaDir, skillsRoot } = makeCorpus('c5b');
+  const vpath = path.join(TMP.root, 'c5b', 'v.db');
+  const mdb = makeMemoryDb(path.join(TMP.root, 'c5b', 'memory.db'), sampleRows(6));
+  const store = openVectorsStore(vpath, { create: true });
+  const embedder = createStubEmbedder({ dim: 32, modelId: 'stub' });
+  const mem = openMemorySource(mdb);
+  await runIncrementalSync({ source: mem, store, embedder, modelId: 'stub', dim: 32, sourceName: 'memory' });
+  const before = ['modelId', 'dim', 'lastIncrementalSyncAt', 'hashSweepCursor'].map((k) => getMetaFor(store.db, META_KEYS[k], 'memory'));
+  await runIncrementalSync({ source: openPolicySource({ segments: scanPolicySources({ personaDir, skillsRoot }) }), store, embedder, modelId: 'stub', dim: 32, sourceName: 'policy' });
+  const after = ['modelId', 'dim', 'lastIncrementalSyncAt', 'hashSweepCursor'].map((k) => getMetaFor(store.db, META_KEYS[k], 'memory'));
+  assertEq(after, before, '记忆侧四类水位键应逐字节不变');
+  assert(countVectors(store.db, 'policy') > 0, 'policy 应有向量');
+  store.db.close();
+});
+
+section('⑥ 默认行为不变（不传 --source 仍走 memory）');
+test('openDataSource("memory") 仍是记忆源、pitfall 仍是坑源', () => {
+  const mdb = makeMemoryDb(path.join(TMP.root, 'c6', 'memory.db'), sampleRows(4));
+  const msrc = openDataSource('memory', { memoryDb: mdb });
+  assertEq(msrc.sourceName, undefined, 'memory-source 无 sourceName 字段（旧形状不变）');
+  assertEq(msrc.count(), 4);
+  const pjson = path.join(TMP.root, 'c6', 'pitfalls.json');
+  fs.mkdirSync(path.dirname(pjson), { recursive: true });
+  fs.writeFileSync(pjson, JSON.stringify({ schemaVersion: 1, pitfalls: [{ id: 'a'.repeat(16), normText: 'x', lastSeen: 1 }] }), 'utf8');
+  const psrc = openDataSource('pitfall', { pitfallsFile: pjson });
+  assertEq(psrc.sourceName, 'pitfall');
+  assertEq(psrc.count(), 1);
+  const okP = openPitfallSource(pjson);
+  assertEq(typeof okP.count, 'function');
+});

package/memory-engine/test/_tickhook-worker.mjs

@@ -0,0 +1,56 @@
+// tick-hook 并发压测的「子进程工人」（只被 10-tick-hook.test.mjs 拉起）
+// 用法：node _tickhook-worker.mjs <mark|consume> <markerPath> <durationMs>
+//   mark    —— 循环置标记（每次写自己的 updatedAt），结束打印事件数与 errors
+//   consume —— 循环清标记（每次取 consumeStart），结束打印每次的 cleared/consumeStart/consumedUpdatedAt
+// 设计：**捕异常计数上报**（不吞），事件列表截断到 2000 条上限（防超大 stdout）。
+import { markDirty, clearMarkerIfStale } from '../lib/tick-hook.mjs';
+
+const [mode, markerPath, durationRaw] = process.argv.slice(2);
+const durationMs = Number(durationRaw) || 1500;
+const deadline = Date.now() + durationMs;
+const events = [];
+const errors = [];
+let n = 0;
+let violations = 0;
+let minAt = null;
+let maxAt = null;
+
+function note(at) {
+  if (minAt === null || at < minAt) minAt = at;
+  if (maxAt === null || at > maxAt) maxAt = at;
+}
+
+try {
+  if (mode === 'mark') {
+    while (Date.now() < deadline) {
+      const at = Date.now();
+      try {
+        markDirty(markerPath, { at, reason: `loadtest-${n}` });
+        n += 1;
+        note(at);
+        if (events.length < 2000) events.push(at);
+      } catch (e) {
+        errors.push(`${e && e.code ? e.code : 'ERR'}:${String(e && e.message).slice(0, 80)}`);
+      }
+    }
+  } else {
+    while (Date.now() < deadline) {
+      const consumeStart = Date.now();
+      try {
+        const r = clearMarkerIfStale(markerPath, consumeStart);
+        if (r.cleared && !(Number(r.consumedUpdatedAt) < consumeStart)) violations += 1;
+        if (r.cleared) note(Number(r.consumedUpdatedAt));
+        n += 1;
+        if (events.length < 2000) {
+          events.push({ cleared: r.cleared, reason: r.reason, consumeStart, consumedUpdatedAt: r.consumedUpdatedAt ?? null });
+        }
+      } catch (e) {
+        errors.push(`${e && e.code ? e.code : 'ERR'}:${String(e && e.message).slice(0, 80)}`);
+      }
+    }
+  }
+} catch (e) {
+  errors.push(`fatal:${String(e && e.stack).slice(0, 200)}`);
+}
+
+process.stdout.write(`${JSON.stringify({ mode, n, violations, errors, minAt, maxAt, events })}\n`);

package/memory-engine/test/fixtures.mjs

@@ -0,0 +1,205 @@
+// 记忆引擎 v2 · 离线层 —— 测试夹具
+//
+// 铁律：测试输出路径一律落 os.tmpdir() 下的临时目录（可注入），绝不写生产路径。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+/** 建独立临时根；返回 { root, cleanup } */
+export function makeTempRoot(prefix = 'dsh-mem-engine-test-') {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  return {
+    root,
+    paths: {
+      memoryDb: path.join(root, 'memory', 'memory.db'),
+      vectorsDb: path.join(root, 'memory-vectors', 'vectors.db'),
+      stateFile: path.join(root, 'butler-memory-vectors-state.json'),
+      pitfallsFile: path.join(root, 'butler-pitfalls.json'),
+      pitfallDirtyFile: path.join(root, 'butler-pitfall-vector-dirty.json'),
+      modelDir: path.join(root, 'models'),
+    },
+    cleanup() {
+      try {
+        fs.rmSync(root, { recursive: true, force: true });
+      } catch {
+        /* ignore */
+      }
+    },
+  };
+}
+
+const DDL = `
+CREATE TABLE memories (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  text TEXT NOT NULL,
+  tags TEXT NOT NULL DEFAULT '',
+  pinned INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE VIRTUAL TABLE memories_fts USING fts5(text, tags, content='memories', content_rowid='id');
+CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, text, tags) VALUES (new.id, new.text, new.tags);
+END;
+CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text, tags) VALUES ('delete', old.id, old.text, old.tags);
+END;
+CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, text, tags) VALUES ('delete', old.id, old.text, old.tags);
+  INSERT INTO memories_fts(rowid, text, tags) VALUES (new.id, new.text, new.tags);
+END;
+`;
+
+/**
+ * 造夹具记忆库（与生产同构：memories + external content FTS5 + 3 触发器）。
+ * @param {string} dbPath
+ * @param {Array<{id?:number,text:string,tags?:string,pinned?:number,updated_at:number,created_at?:number}>} rows
+ */
+export function makeMemoryDb(dbPath, rows) {
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  if (fs.existsSync(dbPath)) fs.rmSync(dbPath);
+  const db = new DatabaseSync(dbPath);
+  db.exec(DDL);
+  const ins = db.prepare(
+    'INSERT INTO memories (id, text, tags, pinned, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)',
+  );
+  for (const r of rows) {
+    ins.run(
+      r.id ?? null,
+      r.text,
+      r.tags ?? '',
+      r.pinned ?? 0,
+      r.created_at ?? r.updated_at,
+      r.updated_at,
+    );
+  }
+  db.close();
+  return dbPath;
+}
+
+/** 直接改 text 而**不动 updated_at**（复刻 A7 的 apply-pinned-refine.mjs 行为） */
+export function silentTextUpdate(dbPath, id, newText) {
+  const db = new DatabaseSync(dbPath);
+  db.prepare('UPDATE memories SET text = ? WHERE id = ?').run(newText, Number(id));
+  db.close();
+}
+
+/** 直接改 pinned（测试排除 pinned 用） */
+export function setPinned(dbPath, id, pinned) {
+  const db = new DatabaseSync(dbPath);
+  db.prepare('UPDATE memories SET pinned = ? WHERE id = ?').run(pinned ? 1 : 0, Number(id));
+  db.close();
+}
+
+/** 读取向量库里某条的 text_hash */
+export function readVectorHash(db, source, refId) {
+  const r = db.prepare('SELECT text_hash FROM vectors WHERE source = ? AND ref_id = ?').get(source, String(refId));
+  return r ? r.text_hash : null;
+}
+
+// ─────────────────────────── 坑库夹具（2026-10-10 · 补坑库联动A） ───────────────────────────
+
+/** 16 位 hex 稳定 id（与生产同形：sigKey sha1 前 16 位） */
+export function pitfallId(i) {
+  return (i + 1).toString(16).padStart(16, '0');
+}
+
+/**
+ * 造 `butler-pitfalls.json` 夹具（与生产同构：`{schemaVersion,updatedAt,device,counters,pitfalls[],seedSources}`）。
+ * @param {Array<object>} rows 见 samplePitfalls
+ */
+export function makePitfallJson(jsonPath, rows) {
+  fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+  const doc = {
+    schemaVersion: 1,
+    updatedAt: Math.max(...rows.map((r) => r.lastSeen), 0),
+    device: 'TEST-HOST',
+    counters: { scans: 0, findings: rows.length, excluded: 0 },
+    pitfalls: rows,
+    seedSources: { keng: 0, persona: 0, memory: 0 },
+  };
+  fs.writeFileSync(jsonPath, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+  return jsonPath;
+}
+
+/**
+ * 生成 N 条坑（含**同一 lastSeen 的平局条**，用来验稳定游标 = lastSeen 升序 + id 字典序）。
+ * 前 2 条按 `source:'seed'`（无 tools）造，验 seed 文本前缀分支。
+ */
+export function samplePitfalls(n, baseTs = 1_760_000_000_000) {
+  const rows = [];
+  for (let i = 0; i < n; i += 1) {
+    // 每 3 条共用同一 lastSeen（制造平局）；其余递增
+    const lastSeen = baseTs + Math.floor(i / 3) * 1000;
+    const seed = i < 2;
+    rows.push({
+      id: pitfallId(i),
+      sigKey: `Error|NO_CODE|夹具坑 ${i}`,
+      name: seed ? '' : `Error${i}`,
+      code: seed ? '' : `E${i}`,
+      normText: `夹具坑 ${i}：${i % 2 ? '跨机同步挡推口径' : '看板卡验收双判据'}`,
+      category: i % 2 ? '同步' : '看板',
+      tools: seed ? {} : { edit: i + 1, bash: 1 },
+      count: i + 1,
+      firstSeen: lastSeen - 500,
+      lastSeen,
+      sessions: [],
+      devices: [],
+      samples: [],
+      source: seed ? 'seed' : 'scan',
+      excluded: 0,
+    });
+  }
+  return rows;
+}
+
+/** 造一个"第 N 次 encodeBatch 必炸"的编码器（测失败保留进度） */
+export function makeFlakyEmbedder(base, { failOnBatchCall = 2 } = {}) {
+  let calls = 0;
+  return {
+    kind: 'flaky',
+    get modelId() {
+      return base.modelId;
+    },
+    get dim() {
+      return base.dim;
+    },
+    describe: () => ({ kind: 'flaky', wrapped: base.describe() }),
+    health: () => base.health(),
+    encode: (t) => base.encode(t),
+    async encodeBatch(texts) {
+      calls += 1;
+      if (calls === failOnBatchCall) throw new Error(`模拟编码崩溃（第 ${calls} 次 encodeBatch）`);
+      return base.encodeBatch(texts);
+    },
+  };
+}
+
+/** 生成 N 条中文记忆（表意稳定、便于断言） */
+export function sampleRows(n, baseTs = 1_760_000_000_000) {
+  const topics = [
+    '跨机同步的挡推裁决口径与三仓推送顺序',
+    '守护鱼崩溃链路与分身唤醒条件',
+    '看板卡的验收双判据与执行会话绑定',
+    '生图角色一致性参考图与提示词模板',
+    '记忆库的 FTS5 分词实测结论与召回策略',
+    '任务看板 ledger 并回与版本门',
+    '权限默认值的部署 override 注入路径',
+    '会话归档与 zstd 多帧修复流程',
+    '代理自控脚本的直连优先判断',
+    '本地 ComfyUI 栈的启动与模型切换',
+  ];
+  const rows = [];
+  for (let i = 0; i < n; i += 1) {
+    rows.push({
+      id: i + 1,
+      text: `#${i + 1} ${topics[i % topics.length]}（第 ${i + 1} 条样本，含 task-board 与 3080 关键词）`,
+      tags: i % 3 === 0 ? 'task-board, 同步' : '技术',
+      pinned: 0,
+      created_at: baseTs + i * 1000,
+      updated_at: baseTs + i * 1000,
+    });
+  }
+  return rows;
+}

package/memory-engine/test/harness.mjs

@@ -0,0 +1,73 @@
+// 记忆引擎 v2 · 离线层 —— 零依赖测试 runner
+const cases = [];
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+export function test(name, fn) {
+  cases.push({ name, fn });
+}
+
+export function skip(name, why = '') {
+  cases.push({ name, fn: null, why });
+}
+
+export async function runAll() {
+  for (const c of cases) {
+    if (!c.fn) {
+      console.log(`  ⏭️  ${c.name}${c.why ? `（跳过：${c.why}）` : ''}`);
+      continue;
+    }
+    const t0 = Date.now();
+    try {
+      await c.fn();
+      passed += 1;
+      console.log(`  ✅ ${c.name}  (${Date.now() - t0}ms)`);
+    } catch (e) {
+      failed += 1;
+      const msg = String(e && e.stack ? e.stack : e);
+      failures.push({ name: c.name, msg });
+      console.log(`  ❌ ${c.name}`);
+      console.log(`     ${msg.split('\n').slice(0, 6).join('\n     ')}`);
+    }
+  }
+  console.log('');
+  console.log(`—— 合计 ${passed + failed} 项：通过 ${passed} / 失败 ${failed} ——`);
+  return { passed, failed, failures };
+}
+
+export function assert(cond, msg = '断言失败') {
+  if (!cond) throw new Error(msg);
+}
+
+export function assertEq(actual, expected, msg = '') {
+  // 数组/对象按 JSON 深度比较（否则 [0,1,0] !== [0,1,0] 会假红）
+  const deep = (actual !== null && typeof actual === 'object') || (expected !== null && typeof expected === 'object');
+  const same = deep ? JSON.stringify(actual) === JSON.stringify(expected) : actual === expected;
+  if (!same) {
+    throw new Error(`${msg ? msg + '：' : ''}期望 ${JSON.stringify(expected)}，实际 ${JSON.stringify(actual)}`);
+  }
+}
+
+export function assertDeepEq(actual, expected, msg = '') {
+  const a = JSON.stringify(actual);
+  const b = JSON.stringify(expected);
+  if (a !== b) throw new Error(`${msg ? msg + '：' : ''}期望 ${b}，实际 ${a}`);
+}
+
+export async function assertThrows(fn, msg = '期望抛错但未抛') {
+  let threw = null;
+  try {
+    await fn();
+  } catch (e) {
+    threw = e;
+  }
+  if (!threw) throw new Error(msg);
+  return threw;
+}
+
+export function section(title) {
+  console.log(`\n▶ ${title}`);
+}
+
+export { passed, failed, failures };

package/memory-engine/test/run.mjs

@@ -0,0 +1,35 @@
+// 记忆引擎 v2 · 离线层 —— 测试入口
+// 用法：node test/run.mjs            （全部）
+//       node test/run.mjs sync      （只跑文件名含 sync 的）
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { runAll } from './harness.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const filter = process.argv[2] || '';
+const files = fs
+  .readdirSync(here)
+  .filter((f) => f.endsWith('.test.mjs'))
+  .filter((f) => !filter || f.includes(filter))
+  .sort();
+
+console.log(`记忆引擎 v2 · 离线层 单测（夹具目录 = 系统临时区）`);
+console.log(`node ${process.version} · ${process.platform} · ${osLabel()}`);
+console.log(`用例文件：${files.join(', ') || '(无)'}`);
+
+for (const f of files) {
+  const mod = await import(pathToFileURL(path.join(here, f)).href);
+  if (mod?.__section) console.log(`\n▶ ${mod.__section}`);
+}
+
+const res = await runAll();
+process.exitCode = res.failed ? 1 : 0;
+
+function osLabel() {
+  try {
+    return `${process.env.COMPUTERNAME || 'unknown-host'}`;
+  } catch {
+    return 'unknown-host';
+  }
+}

package/memory-engine/tools/bridge-smoke.mjs

@@ -0,0 +1,80 @@
+// 记忆引擎 v2 · 离线层 —— 编码桥实测（方案 §3.1 编码通道契约）
+//
+// 同进程内起桥 → 打 /health 与 /encode → 校验端口顺延 → 关桥。
+// 为什么不走 ssh 后台进程：SSH 会话结束会带走 detached 进程（跨机技能坑 3），
+// 起与测必须同一条命令；本脚本把「起 + 测 + 关」放进同一个 node 进程，最省事也最可靠。
+import { startBridge } from '../serve.mjs';
+import { parseArgs, isMainEntry } from '../lib/cli-util.mjs';
+
+async function waitReady(port, timeoutMs = 60000) {
+  const t0 = Date.now();
+  for (;;) {
+    try {
+      const h = await fetch(`http://127.0.0.1:${port}/health`).then((r) => r.json());
+      if (h.ready) return h;
+      if (h.lastError) throw new Error(`模型加载失败：${h.lastError}`);
+    } catch (e) {
+      if (Date.now() - t0 > timeoutMs) throw e;
+    }
+    if (Date.now() - t0 > timeoutMs) throw new Error('等待模型就绪超时');
+    await new Promise((r) => setTimeout(r, 400));
+  }
+}
+
+async function main() {
+  const { flags } = parseArgs();
+  const modelDir = flags['model-dir'];
+  const wantPort = Number(flags.port || 8201);
+  const logs = [];
+  const log = (m) => {
+    logs.push(m);
+    console.log(m);
+  };
+
+  console.log('=== 编码桥实测（仅回环） ===');
+  const b1 = await startBridge({ flags: { 'model-dir': modelDir, port: String(wantPort) }, log });
+  const b2 = await startBridge({ flags: { 'model-dir': modelDir, port: String(wantPort), warm: false }, log });
+  console.log(`端口顺延检查：首个=${b1.port}，第二个=${b2.port}${b2.port === b1.port + 1 ? ' ✅' : ' ❌'}`);
+
+  const health0 = await fetch(`http://127.0.0.1:${b1.port}/health`).then((r) => r.json());
+  console.log(`/health（加载中）：${JSON.stringify({ ready: health0.ready, modelLoading: health0.modelLoading, model: health0.model, dim: health0.dim })}`);
+
+  const ready = await waitReady(b1.port);
+  console.log(`/health（就绪）：${JSON.stringify({ ready: ready.ready, model: ready.model, dim: ready.dim, port: ready.port })}`);
+
+  const t0 = performance.now();
+  const enc = await fetch(`http://127.0.0.1:${b1.port}/encode`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ texts: ['跨机同步的挡推裁决', '整夜干活'] }),
+  }).then((r) => r.json());
+  const ms = performance.now() - t0;
+  console.log(`/encode 2 条：${ms.toFixed(1)}ms · model=${enc.model} dim=${enc.dim} · 首向量前 5 维 ${enc.vectors[0].slice(0, 5).map((x) => x.toFixed(4)).join(', ')}`);
+  const norm = Math.sqrt(enc.vectors[0].reduce((s, x) => s + x * x, 0));
+  console.log(`首向量 L2 范数：${norm.toFixed(6)}（契约要求归一化 ⇒ 应 ≈1）`);
+
+  const bad = await fetch(`http://127.0.0.1:${b1.port}/encode`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ nope: 1 }),
+  }).then((r) => ({ status: r.status, body: r.json() }));
+  const badRes = await bad.body;
+  console.log(`坏请求处理：HTTP ${bad.status} ${JSON.stringify(badRes)}`);
+
+  const nonLoop = await (async () => {
+    try {
+      await startBridge({ flags: { 'model-dir': modelDir, bind: '0.0.0.0' }, log: () => {} });
+      return '未拦截 ❌';
+    } catch (e) {
+      return `已拦截 ✅（${String(e.message).slice(0, 40)}…）`;
+    }
+  })();
+  console.log(`非回环绑定拦截：${nonLoop}`);
+
+  await b2.close();
+  await b1.close();
+  console.log('桥已关闭');
+  process.exitCode = 0;
+}
+
+if (isMainEntry(import.meta.url)) await main();