dsh-layered-memory 0.7.0 → 0.8.0

package/dist/store/sqlite.js

@@ -19,6 +19,7 @@ import { existsSync, mkdirSync } from 'node:fs';
 import * as path from 'node:path';
 import { familyForType } from '../types.js';
 import { bm25RankToScore, buildFtsQuery, tokenizeForFts } from './search-utils.js';
+import { describeTokenizer, ensureTokenizer, tokenizerStamp } from '../util/tokenizer.js';
 const require = createRequire(import.meta.url);
 const TAG = '[memory][sqlite]';
 /** vec0 KNN 对遗留零向量的补偿缓冲（官方同款）。 */
@@ -45,6 +46,8 @@ export class MemoryDb {
     logger;
     stmtUpsertL1;
     stmtGetL1;
+    /** 主表存在性点查（防御性 FTS 删除的前置判断，走主键索引）。 */
+    stmtL1Exists;
     stmtDeleteL1Meta;
     stmtDeleteL1Vec;
     stmtInsertL1Vec;
@@ -55,6 +58,8 @@ export class MemoryDb {
     stmtL1FtsSearchFamily;
     stmtUpsertL0;
     stmtGetL0;
+    /** 主表存在性点查（同 L1：防御性 FTS 删除的前置判断）。 */
+    stmtL0Exists;
     stmtDeleteL0Vec;
     stmtInsertL0Vec;
     stmtSearchL0Vec;
@@ -72,9 +77,12 @@ export class MemoryDb {
                 mkdirSync(dbDir, { recursive: true });
             const { DatabaseSync: DbSync } = require('node:sqlite');
             this.db = new DbSync(dbPath, { allowExtension: true });
-            // 并发读优化 + 有界内存（照搬官方 PRAGMA 组合）
+            // 并发读优化 + 有界内存（照搬官方 PRAGMA 组合，synchronous 为本仓新增：
+            // WAL 下官方推荐 NORMAL——批量写从"每事务一次 fsync"降为"每 checkpoint 一次"，
+            // 重嵌入/导入提速明显；代价仅是断电时丢最后若干已提交事务（只丢不损，无损坏风险））
             this.db.exec('PRAGMA busy_timeout = 5000');
             this.db.exec('PRAGMA journal_mode = WAL');
+            this.db.exec('PRAGMA synchronous = NORMAL');
             this.db.exec('PRAGMA cache_size = -65536');
             this.db.exec('PRAGMA mmap_size = 134217728');
             this.db.exec('PRAGMA wal_autocheckpoint = 1000');
@@ -104,6 +112,9 @@ export class MemoryDb {
         // dimensions=0 是合法的"纯 FTS 模式"，不能因 sqlite-vec 缺失而降级（官方语义）；
         // 后续活切换本地嵌入（维度 > 0）时由 swapProvider 补加载
         this.ensureVecLoaded();
+        // 分词器在首次 FTS 写入（迁移回灌）前定死模式：jieba 就绪 info / 回退 warn 一次
+        ensureTokenizer();
+        this.logger?.info(`${TAG} 分词器：${describeTokenizer()}`);
         try {
             return this.initSchema(providerInfo);
         }
@@ -284,6 +295,7 @@ export class MemoryDb {
              timestamp_start, timestamp_end, created_time, updated_time, metadata_json, family
       FROM l1_records WHERE record_id = ?
     `);
+        this.stmtL1Exists = this.db.prepare('SELECT 1 FROM l1_records WHERE record_id = ?');
         this.stmtDeleteL1Meta = this.db.prepare('DELETE FROM l1_records WHERE record_id = ?');
         this.prepareL1VecStatements();
         // ── L0 schema ──
@@ -311,15 +323,28 @@ export class MemoryDb {
         timestamp=excluded.timestamp
     `);
         this.stmtGetL0 = this.db.prepare('SELECT session_id, role, message_text, recorded_at, timestamp FROM l0_conversations WHERE record_id = ?');
+        this.stmtL0Exists = this.db.prepare('SELECT 1 FROM l0_conversations WHERE record_id = ?');
         this.prepareL0VecStatements();
         // ── FTS5 全文索引（建表失败仅停用 FTS，不降级整个库） ──
         try {
-            // 旧 l1_fts 无 family 列（FTS5 无法 ALTER）→ drop 后从 l1_records 全量重建
+            // 索引重建判据（FTS5 无法 ALTER，只能 drop 后从源表全量回灌）：
+            // a) 旧 l1_fts 无 family 列；b) FTS 分词器版本戳 ≠ 当前生效分词器
+            //    （无戳 = jieba 引入前的二元组索引；jieba 升级/降级切换后旧 token
+            //    形态不再匹配，须按新分词器重建）。
+            const wantStamp = tokenizerStamp();
+            const savedStamp = this.readMetaString('fts_tokenizer') ?? 'bigram-v1';
+            const tokenizerChanged = savedStamp !== wantStamp;
             let ftsRebuilt = false;
-            if (this.tableExists('l1_fts') && !this.hasColumn('l1_fts', 'family')) {
+            if (this.tableExists('l1_fts') && (!this.hasColumn('l1_fts', 'family') || tokenizerChanged)) {
                 this.db.exec('DROP TABLE l1_fts');
                 ftsRebuilt = true;
-                this.logger?.info(`${TAG} l1_fts 缺 family 列，重建全文索引`);
+                this.logger?.info(`${TAG} l1_fts 缺 family 列或分词器已变更（${savedStamp} → ${wantStamp}），重建全文索引`);
+            }
+            let l0FtsRebuilt = false;
+            if (this.tableExists('l0_fts') && tokenizerChanged) {
+                this.db.exec('DROP TABLE l0_fts');
+                l0FtsRebuilt = true;
+                this.logger?.info(`${TAG} l0_fts 分词器已变更（${savedStamp} → ${wantStamp}），重建全文索引`);
             }
             this.db.exec(`
         CREATE VIRTUAL TABLE IF NOT EXISTS l1_fts USING fts5(
@@ -389,6 +414,15 @@ export class MemoryDb {
         ORDER BY rank ASC
         LIMIT ?
       `);
+            if (l0FtsRebuilt)
+                this.backfillL0Fts();
+            // 戳如实记录"构建当前 FTS 内容的分词器"（含全新空表：后续写入即该分词器）
+            try {
+                this.writeMetaString('fts_tokenizer', wantStamp);
+            }
+            catch {
+                /* 戳写失败只影响下次启动多一次重建，不阻断 */
+            }
             this.ftsAvailable = true;
         }
         catch (err) {
@@ -489,6 +523,22 @@ export class MemoryDb {
         if (rows.length > 0)
             this.logger?.info(`${TAG} l1_fts 回灌 ${rows.length} 行`);
     }
+    /** 重建后的 l0_fts 从 l0_conversations 全量回灌（仅 drop 重建时调用；iterate 流式防大库内存峰值）。 */
+    backfillL0Fts() {
+        let count = 0;
+        const stmt = this.db.prepare('SELECT record_id, session_id, role, message_text, recorded_at, timestamp FROM l0_conversations');
+        for (const r of stmt.iterate()) {
+            try {
+                this.stmtL0FtsInsert.run(tokenizeForFts(String(r.message_text ?? '')), String(r.message_text ?? ''), String(r.record_id ?? ''), String(r.session_id ?? 'default'), String(r.role ?? ''), String(r.recorded_at ?? ''), Number(r.timestamp ?? 0));
+                count++;
+            }
+            catch {
+                /* 单行失败跳过 */
+            }
+        }
+        if (count > 0)
+            this.logger?.info(`${TAG} l0_fts 回灌 ${count} 行`);
+    }
     readEmbeddingMeta() {
         try {
             const row = this.db
@@ -514,6 +564,23 @@ export class MemoryDb {
             .prepare('INSERT INTO embedding_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value')
             .run('embedding_provider_info', JSON.stringify(info));
     }
+    /** 通用字符串 kv（embedding_meta 表兼作元数据 kv 存储，如 FTS 分词器版本戳）。 */
+    readMetaString(key) {
+        try {
+            const row = this.db
+                .prepare('SELECT value FROM embedding_meta WHERE key = ?')
+                .get(key);
+            return row?.value ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    writeMetaString(key, value) {
+        this.db
+            .prepare('INSERT INTO embedding_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value')
+            .run(key, value);
+    }
     /**
      * 持久化 embedding meta（语义：物理向量表当前对应的 provider/维度）。
      * 活切换在 swapProvider 成功后即写（表已是新维度）；启动/补齐链在
@@ -603,6 +670,11 @@ export class MemoryDb {
     /** 事务内的单条写入体（upsertL1 / upsertL1Batch 共用；调用方负责 BEGIN/COMMIT）。 */
     upsertL1InTx(record, embedding) {
         const ts = timestampsToDb(record.timestamps);
+        // 防御性 FTS 删除的前置点查（主键索引，微秒级）：record_id 在 FTS 表是 UNINDEXED，
+        // 按 id DELETE 是 O(N) 全表扫描——导入/重建/重嵌等"全新增"路径曾为每条记录白付一次
+        // 全扫（批量写整体 O(N²)）。只有主表已有该行（覆盖/合并）才可能有旧 FTS 行需要删。
+        // 同批重复 id 也能正确处理：首条插入后，第二条的点查在同一事务内已见新行。
+        const ftsExisted = this.ftsAvailable ? this.stmtL1Exists.get(record.id) !== undefined : false;
         this.stmtUpsertL1.run(record.id, record.content, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, toIso(record.createdAt), toIso(record.updatedAt), JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
         // vec0 不支持 ON CONFLICT → 先删后插；零向量跳过（cosine 未定义）
         if (this.stmtDeleteL1Vec && this.stmtInsertL1Vec) {
@@ -614,7 +686,8 @@ export class MemoryDb {
         // FTS 删除/插入与元数据同事务：失败必须整体回滚——若只吞 FTS 错误照常 COMMIT，
         // 已执行的 DELETE 会让该 id 的索引行被删未补，记录从此全文检索不可见（静默丢数据）。
         if (this.ftsAvailable) {
-            this.stmtL1FtsDelete.run(record.id);
+            if (ftsExisted)
+                this.stmtL1FtsDelete.run(record.id);
             this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, record.type, record.priority, record.scene_name, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), record.family ?? familyForType(record.type));
         }
     }
@@ -860,6 +933,8 @@ export class MemoryDb {
             this.db.exec('BEGIN');
             for (let i = 0; i < records.length; i++) {
                 const r = records[i];
+                // 同 upsertL1 的点查预判：全新增路径跳过 UNINDEXED 列的 FTS 全扫删除
+                const ftsExisted = this.ftsAvailable ? this.stmtL0Exists.get(r.id) !== undefined : false;
                 this.stmtUpsertL0.run(r.id, r.sessionId, r.role, r.content, r.recordedAt, r.timestamp);
                 if (this.stmtDeleteL0Vec && this.stmtInsertL0Vec) {
                     this.stmtDeleteL0Vec.run(r.id);
@@ -870,7 +945,8 @@ export class MemoryDb {
                 }
                 if (this.ftsAvailable) {
                     // 同 upsertL1：FTS 失败冒泡触发整批回滚，禁止"删了没补"的索引空洞。
-                    this.stmtL0FtsDelete.run(r.id);
+                    if (ftsExisted)
+                        this.stmtL0FtsDelete.run(r.id);
                     this.stmtL0FtsInsert.run(tokenizeForFts(r.content), r.content, r.id, r.sessionId, r.role, r.recordedAt, r.timestamp);
                 }
             }
@@ -913,6 +989,31 @@ export class MemoryDb {
             return 0;
         }
     }
+    /** 按会话取最近消息（时间升序返回；走 idx_l0_session_id 索引）。
+     *  蒸馏背景参考专用——按会话现查替代全局内存数组（ADR-0003）。 */
+    recentL0BySession(sessionId, limit) {
+        if (this.degraded || limit <= 0)
+            return [];
+        try {
+            const rows = this.db
+                .prepare('SELECT record_id, session_id, role, message_text, recorded_at, timestamp FROM l0_conversations WHERE session_id = ? ORDER BY timestamp DESC, rowid DESC LIMIT ?')
+                .all(sessionId, limit);
+            return rows
+                .map((r) => ({
+                sessionId: r.session_id,
+                recordedAt: r.recorded_at,
+                id: r.record_id,
+                role: r.role,
+                content: r.message_text,
+                timestamp: r.timestamp ?? 0,
+            }))
+                .reverse();
+        }
+        catch (err) {
+            this.logger?.warn(`[memory] L0 按会话取最近消息失败（返回空）: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
     /** L0 全量列举（重建快照用；按时间升序，事务一致性避开 JSONL 追加竞态）。 */
     listL0All() {
         if (this.degraded)
@@ -1179,6 +1280,85 @@ export class MemoryDb {
             return false;
         }
     }
+    /**
+     * 批量更新 L1 向量行（重嵌入热路径）：单事务写入整批，替代逐条裸写——
+     * 逐条每行一次隐式事务，批量场景（万级记录重嵌）开销集中在 fsync 上。
+     * 整批失败回退逐条：好行照常入库，坏行只丢自身（向量行 id 寻址，无顺序依赖）。
+     * 返回成功写入的行数（零向量行防御性跳过、不计入）。
+     */
+    updateL1VecBatch(items) {
+        if (this.degraded || !this.stmtDeleteL1Vec || !this.stmtInsertL1Vec || items.length === 0)
+            return 0;
+        try {
+            this.db.exec('BEGIN');
+            try {
+                let written = 0;
+                for (const it of items) {
+                    if (isZeroVector(it.embedding))
+                        continue;
+                    this.stmtDeleteL1Vec.run(it.id);
+                    this.stmtInsertL1Vec.run(it.id, vecToBuffer(it.embedding), new Date().toISOString());
+                    written++;
+                }
+                this.db.exec('COMMIT');
+                return written;
+            }
+            catch (err) {
+                try {
+                    this.db.exec('ROLLBACK');
+                }
+                catch {
+                    /* ignore */
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L1 向量批量写入失败，回退逐条: ${err instanceof Error ? err.message : String(err)}`);
+            let ok = 0;
+            for (const it of items)
+                if (this.updateL1Vec(it.id, it.embedding))
+                    ok++;
+            return ok;
+        }
+    }
+    /** L0 版 updateL1VecBatch（语义同：单事务 + 失败回退逐条）。recordedAt 整批统一。 */
+    updateL0VecBatch(items, recordedAt) {
+        if (this.degraded || !this.stmtDeleteL0Vec || !this.stmtInsertL0Vec || items.length === 0)
+            return 0;
+        try {
+            this.db.exec('BEGIN');
+            try {
+                let written = 0;
+                for (const it of items) {
+                    if (isZeroVector(it.embedding))
+                        continue;
+                    this.stmtDeleteL0Vec.run(it.id);
+                    this.stmtInsertL0Vec.run(it.id, vecToBuffer(it.embedding), recordedAt);
+                    written++;
+                }
+                this.db.exec('COMMIT');
+                return written;
+            }
+            catch (err) {
+                try {
+                    this.db.exec('ROLLBACK');
+                }
+                catch {
+                    /* ignore */
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} L0 向量批量写入失败，回退逐条: ${err instanceof Error ? err.message : String(err)}`);
+            let ok = 0;
+            for (const it of items)
+                if (this.updateL0Vec(it.id, it.embedding, recordedAt))
+                    ok++;
+            return ok;
+        }
+    }
     close() {
         try {
             this.db.close();

package/dist/util/recall-budget.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 召回预算与超时（ADR-0001 / 规格 A 节；机制移植自 MemoryCore auto-recall 的
+ * applyRecallBudget，超时为 dsh 侧新增的总预算语义）。
+ *
+ * 预算：单条记忆截断上限 + 整轮总量上限——超限截断并以后缀引导模型用记忆工具
+ * 查全文（截断是引流而不是损失：工具路径返回完整记录）；总量超限按融合排名丢尾部。
+ * 超时：召回是增强能力，超时跳过本轮注入、绝不阻塞对话（CONTEXT.md「召回超时」语义
+ * 在本模块以 raceTimeout 落地）。
+ */
+/** 截断后缀：显式告诉模型全文在工具侧（引导主动深挖，原版同款设计）。 */
+export declare const RECALL_TRUNCATION_SUFFIX = "\u2026\uFF08\u5DF2\u622A\u65AD\uFF1B\u53EF\u7528 memory_search \u6216 conversation_search \u67E5\u770B\u8BE6\u60C5\uFF09";
+export interface RecallBudgetLimits {
+    /** 单条记忆注入长度上限（字符）；0 = 不限。 */
+    maxCharsPerMemory: number;
+    /** 整轮注入总量上限（字符）；0 = 不限。超限时低分（排名靠后）尾部先丢。 */
+    maxTotalRecallChars: number;
+}
+/** 按 code point 计数截断（不劈开代理对），带引导后缀。 */
+export declare function truncateRecallLine(line: string, maxChars: number): string;
+/**
+ * 对召回行施加预算：先逐条截断，再按总量预算装填——装不下的尾部整条丢弃。
+ * 输入行应按相关性降序（低分先丢）。
+ */
+export declare function applyRecallBudget(lines: string[], limits: RecallBudgetLimits): string[];
+/**
+ * 召回总预算：超时返回 undefined（调用方跳过本轮注入），正常 resolve 返回原值。
+ * resolve 为空结果（空数组）与超时（undefined）语义不同，调用方据此区分日志。
+ */
+export declare function raceRecallTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined>;
+/** 召回路径远程嵌入 fetch 的内层钳制（固定值）：给 FTS 降级留出总预算内的时间。
+ *  仅作用于远程 HTTP 调用；本地推理不受钳制（进程内 CPU 推理无挂起风险）。 */
+export declare const RECALL_EMBED_CAP_MS = 3000;

package/dist/util/recall-budget.js

@@ -0,0 +1,85 @@
+/**
+ * 召回预算与超时（ADR-0001 / 规格 A 节；机制移植自 MemoryCore auto-recall 的
+ * applyRecallBudget，超时为 dsh 侧新增的总预算语义）。
+ *
+ * 预算：单条记忆截断上限 + 整轮总量上限——超限截断并以后缀引导模型用记忆工具
+ * 查全文（截断是引流而不是损失：工具路径返回完整记录）；总量超限按融合排名丢尾部。
+ * 超时：召回是增强能力，超时跳过本轮注入、绝不阻塞对话（CONTEXT.md「召回超时」语义
+ * 在本模块以 raceTimeout 落地）。
+ */
+/** 截断后缀：显式告诉模型全文在工具侧（引导主动深挖，原版同款设计）。 */
+export const RECALL_TRUNCATION_SUFFIX = '…（已截断；可用 memory_search 或 conversation_search 查看详情）';
+/** 剩余预算小于该值时整条丢弃（截出比后缀还短的行没有意义）。 */
+const MIN_TRUNCATED_RECALL_LINE_CHARS = 40;
+function normalizeLimit(value) {
+    if (value == null || !Number.isFinite(value) || value <= 0)
+        return undefined;
+    return Math.floor(value);
+}
+/** 按 code point 计数截断（不劈开代理对），带引导后缀。 */
+export function truncateRecallLine(line, maxChars) {
+    const cps = Array.from(line);
+    if (cps.length <= maxChars)
+        return line;
+    if (maxChars <= RECALL_TRUNCATION_SUFFIX.length) {
+        return cps.slice(0, maxChars).join('');
+    }
+    return `${cps.slice(0, maxChars - RECALL_TRUNCATION_SUFFIX.length).join('').trimEnd()}${RECALL_TRUNCATION_SUFFIX}`;
+}
+/**
+ * 对召回行施加预算：先逐条截断，再按总量预算装填——装不下的尾部整条丢弃。
+ * 输入行应按相关性降序（低分先丢）。
+ */
+export function applyRecallBudget(lines, limits) {
+    const maxCharsPerMemory = normalizeLimit(limits.maxCharsPerMemory);
+    const maxTotalRecallChars = normalizeLimit(limits.maxTotalRecallChars);
+    if (!maxCharsPerMemory && !maxTotalRecallChars)
+        return lines;
+    const budgeted = [];
+    let usedChars = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const perBounded = maxCharsPerMemory ? truncateRecallLine(line, maxCharsPerMemory) : line;
+        if (!maxTotalRecallChars) {
+            budgeted.push(perBounded);
+            continue;
+        }
+        const separatorChars = budgeted.length > 0 ? 1 : 0; // 行间换行符计入预算
+        const remaining = maxTotalRecallChars - usedChars - separatorChars;
+        if (remaining <= 0)
+            break;
+        if (perBounded.length > remaining) {
+            const canFit = remaining >= MIN_TRUNCATED_RECALL_LINE_CHARS;
+            if (canFit)
+                budgeted.push(truncateRecallLine(perBounded, remaining));
+            break;
+        }
+        budgeted.push(perBounded);
+        usedChars += separatorChars + perBounded.length;
+    }
+    return budgeted;
+}
+/**
+ * 召回总预算：超时返回 undefined（调用方跳过本轮注入），正常 resolve 返回原值。
+ * resolve 为空结果（空数组）与超时（undefined）语义不同，调用方据此区分日志。
+ */
+export async function raceRecallTimeout(promise, timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return promise;
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** 召回路径远程嵌入 fetch 的内层钳制（固定值）：给 FTS 降级留出总预算内的时间。
+ *  仅作用于远程 HTTP 调用；本地推理不受钳制（进程内 CPU 推理无挂起风险）。 */
+export const RECALL_EMBED_CAP_MS = 3_000;

package/dist/util/text.d.ts

@@ -1,11 +1,16 @@
 /**
- * 文本工具：ContentBlock → 纯文本；BM25 分词。
+ * 文本工具：ContentBlock → 纯文本；FTS / BM25 共用分词。
  */
 import type { ContentBlock } from '@deepseek-ai/dsh-llm';
 /** 把消息的 ContentBlock[] 展平成纯文本（仅 text 块）。 */
 export declare function blocksToText(blocks: readonly ContentBlock[] | undefined): string;
 /**
- * 轻量中英混排分词：英文按词，中文按二元组。
- * 与 MemoryCore 的 BM25 思路一致（无外部分词依赖）。
+ * 中英混排分词：jieba 词元 ∪ 拉丁词 ∪ CJK 二元组，按首次出现顺序去重。
+ *
+ * - 词元给 BM25 提供高精度整词命中（"负载均衡"作为词，idf 远高于碎片二元组）；
+ * - 二元组保住子词召回底线：查询"负载"仍能命中只含"负载均衡"词元的行，
+ *   且旧库纯二元组索引无需迁移即可被新查询命中（新查询仍含二元组 token）；
+ * - 去重防 2 字词与其自身二元组重复计数（FTS tf / bm25.ts 词频被同一出现双计）；
+ * - jieba 加载失败时 jiebaCut 返回 undefined，自动退化为纯二元组（原 0.7 行为）。
  */
 export declare function tokenize(text: string): string[];

package/dist/util/text.js

@@ -1,3 +1,4 @@
+import { jiebaCut } from './tokenizer.js';
 /** 把消息的 ContentBlock[] 展平成纯文本（仅 text 块）。 */
 export function blocksToText(blocks) {
     if (!blocks)
@@ -13,17 +14,12 @@ export function blocksToText(blocks) {
 }
 const CJK_RE = /[\u3400-\u9fff\uf900-\ufaff]/;
 const WORD_RE = /[a-zA-Z0-9][a-zA-Z0-9_-]{1,}/g;
-/**
- * 轻量中英混排分词：英文按词，中文按二元组。
- * 与 MemoryCore 的 BM25 思路一致（无外部分词依赖）。
- */
-export function tokenize(text) {
+/** token 里至少要有一个字母/数字/CJK 字（输入已小写；滤掉 jieba 切出的纯标点 token）。 */
+const TOKEN_KEEP_RE = /[a-z0-9\u3400-\u9fff\uf900-\ufaff]/;
+/** CJK 连续段二元组（jieba 失败回退时的唯一分词，也是并集模式的子词召回底线）。 */
+function cjkBigrams(text) {
     const tokens = [];
-    const lower = text.toLowerCase();
-    for (const m of lower.matchAll(WORD_RE))
-        tokens.push(m[0]);
-    // CJK 二元组
-    const cjk = lower.replace(/[^\u3400-\u9fff\uf900-\ufaff]/g, ' ');
+    const cjk = text.replace(/[^\u3400-\u9fff\uf900-\ufaff]/g, ' ');
     let i = 0;
     while (i < cjk.length) {
         const ch = cjk[i];
@@ -33,11 +29,41 @@ export function tokenize(text) {
                 tokens.push(ch + next);
             else
                 tokens.push(ch);
-            i += 1;
-        }
-        else {
-            i += 1;
         }
+        i += 1;
     }
-    return tokens.filter((t) => t.length >= 2 || CJK_RE.test(t));
+    return tokens;
+}
+/**
+ * 中英混排分词：jieba 词元 ∪ 拉丁词 ∪ CJK 二元组，按首次出现顺序去重。
+ *
+ * - 词元给 BM25 提供高精度整词命中（"负载均衡"作为词，idf 远高于碎片二元组）；
+ * - 二元组保住子词召回底线：查询"负载"仍能命中只含"负载均衡"词元的行，
+ *   且旧库纯二元组索引无需迁移即可被新查询命中（新查询仍含二元组 token）；
+ * - 去重防 2 字词与其自身二元组重复计数（FTS tf / bm25.ts 词频被同一出现双计）；
+ * - jieba 加载失败时 jiebaCut 返回 undefined，自动退化为纯二元组（原 0.7 行为）。
+ */
+export function tokenize(text) {
+    const lower = text.toLowerCase();
+    const seen = new Set();
+    const tokens = [];
+    const push = (t) => {
+        if (t.length >= 2 && TOKEN_KEEP_RE.test(t) && !seen.has(t)) {
+            seen.add(t);
+            tokens.push(t);
+        }
+        else if (t.length === 1 && CJK_RE.test(t) && !seen.has(t)) {
+            seen.add(t);
+            tokens.push(t);
+        }
+    };
+    const words = jiebaCut(lower);
+    if (words)
+        for (const w of words)
+            push(w.trim());
+    for (const m of lower.matchAll(WORD_RE))
+        push(m[0]);
+    for (const bg of cjkBigrams(lower))
+        push(bg);
+    return tokens;
 }

package/dist/util/tokenizer.d.ts

@@ -0,0 +1,14 @@
+export type TokenizerMode = 'jieba' | 'bigram';
+/** 启动期主动初始化并返回模式（MemoryDb.init 记日志用）。 */
+export declare function ensureTokenizer(): TokenizerMode;
+/**
+ * FTS 分词器版本戳（存 embedding_meta 表，键 fts_tokenizer）。
+ * 戳 ≠ 当前生效分词器 → FTS 表 drop 后从源表全量回灌（与 family 列迁移同款语义）。
+ * 回退模式下戳为 bigram-v1：若历史索引是 jieba 分词建的，同样触发重建，
+ * 保证戳永远如实反映"构建当前 FTS 内容的分词器"。
+ */
+export declare function tokenizerStamp(): string;
+/** 模式描述（日志用）。 */
+export declare function describeTokenizer(): string;
+/** jieba 切词（回退模式下返回 undefined，调用方走二元组路径）。 */
+export declare function jiebaCut(text: string): string[] | undefined;

package/dist/util/tokenizer.js

@@ -0,0 +1,53 @@
+/**
+ * 分词器装配：jieba 词级分词（@node-rs/jieba，Rust napi 预编译二进制）优先，
+ * 加载失败（平台无预编译二进制等）永久回退 CJK 二元组。
+ *
+ * - 惰性单例：首次调用即定死本进程的分词模式，不会运行中漂移——
+ *   FTS 读写两侧共用同一实例（util/text.ts 的 tokenize），索引/查询天然对齐；
+ * - require 走 createRequire（与 sqlite-vec 同款）：失败只降级不抛出，
+ *   由 MemoryDb.init() 在启动时主动 ensure 并记录模式日志。
+ */
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+let mode;
+let cutFn;
+/** 惰性初始化（永不抛出）。词典约 5MB，首次加载 ~100ms。 */
+function ensure() {
+    if (mode !== undefined)
+        return mode;
+    try {
+        const { Jieba } = require('@node-rs/jieba');
+        const { dict } = require('@node-rs/jieba/dict');
+        const jieba = Jieba.withDict(dict);
+        cutFn = (text) => jieba.cut(text, true);
+        mode = 'jieba';
+    }
+    catch {
+        cutFn = undefined;
+        mode = 'bigram';
+    }
+    return mode;
+}
+/** 启动期主动初始化并返回模式（MemoryDb.init 记日志用）。 */
+export function ensureTokenizer() {
+    return ensure();
+}
+/**
+ * FTS 分词器版本戳（存 embedding_meta 表，键 fts_tokenizer）。
+ * 戳 ≠ 当前生效分词器 → FTS 表 drop 后从源表全量回灌（与 family 列迁移同款语义）。
+ * 回退模式下戳为 bigram-v1：若历史索引是 jieba 分词建的，同样触发重建，
+ * 保证戳永远如实反映"构建当前 FTS 内容的分词器"。
+ */
+export function tokenizerStamp() {
+    return ensure() === 'jieba' ? 'jieba-v1' : 'bigram-v1';
+}
+/** 模式描述（日志用）。 */
+export function describeTokenizer() {
+    return ensure() === 'jieba'
+        ? 'jieba 词级分词（@node-rs/jieba）+ CJK 二元组并集'
+        : 'jieba 加载失败，回退 CJK 二元组分词（子词召回降级）';
+}
+/** jieba 切词（回退模式下返回 undefined，调用方走二元组路径）。 */
+export function jiebaCut(text) {
+    return ensure() === 'jieba' ? cutFn(text) : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-layered-memory",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "L0~L3 分层蒸馏记忆插件 for DeepSeek Harness：自动捕获对话（L0）、抽取原子记忆（L1）、整合场景块（L2）、蒸馏核心画像/团队方法论（L3），并在模型步骤前自动召回注入。移植自 MemoryCore (TencentDB Agent Memory) 的管线设计。",
   "type": "module",
   "main": "dist/index.js",
@@ -51,6 +51,7 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "3.18.1",
+    "@node-rs/jieba": "^2.0.2",
     "sqlite-vec": "^0.1.7-alpha.2"
   },
   "peerDependencies": {