dsh-layered-memory 0.7.1 → 0.8.0

package/dist/store/pending.js

@@ -7,6 +7,12 @@
  */
 import * as path from 'node:path';
 import { atomicWriteJson, readJsonIfExists } from './io.js';
+/** 旧格式（无 sessionId 字段）条目加载时归属的会话组。 */
+export const LEGACY_SESSION = 'legacy';
+/** 全新起步：三档都从 1 爬坡（首轮即触发抽取）。 */
+export function freshWarmup() {
+    return { auto: 1, chat: 1, work: 1 };
+}
 export function emptyPending() {
     return { auto: [], chat: [], work: [] };
 }
@@ -16,7 +22,8 @@ function isMessage(m) {
     const r = m;
     return typeof r.id === 'string' && typeof r.content === 'string' && (r.role === 'user' || r.role === 'assistant');
 }
-/** 读取缓冲文件：文件缺失/损坏 → 空桶（不抛出——丢了缓冲 L0 事实源仍在）。 */
+/** 读取缓冲文件：文件缺失/损坏 → 空桶（不抛出——丢了缓冲 L0 事实源仍在）。
+ *  旧格式条目（无 sessionId）归 legacy 组；warmup 缺省 = 全新起步。 */
 export async function loadPending(file, logger) {
     const out = emptyPending();
     let raw;
@@ -26,27 +33,60 @@ export async function loadPending(file, logger) {
     catch {
         raw = undefined;
     }
-    if (!raw || typeof raw !== 'object' || !raw.buckets || typeof raw.buckets !== 'object')
-        return out;
+    if (!raw || typeof raw !== 'object' || !raw.buckets || typeof raw.buckets !== 'object') {
+        return { buckets: out, warmup: freshWarmup() };
+    }
     let dropped = 0;
+    let legacy = 0;
     for (const key of ['auto', 'chat', 'work']) {
         const arr = raw.buckets[key];
         if (!Array.isArray(arr))
             continue;
         for (const m of arr) {
-            if (isMessage(m))
-                out[key].push(m);
-            else
+            if (!isMessage(m)) {
                 dropped++;
+                continue;
+            }
+            const sid = m.sessionId;
+            if (typeof sid === 'string' && sid) {
+                out[key].push({ ...m, sessionId: sid });
+            }
+            else {
+                legacy++;
+                out[key].push({ ...m, sessionId: LEGACY_SESSION });
+            }
         }
     }
     if (dropped > 0)
         logger?.warn(`[memory] 未蒸馏缓冲文件含 ${dropped} 条坏记录，已丢弃`);
-    return out;
+    if (legacy > 0)
+        logger?.info(`[memory] 未蒸馏缓冲含 ${legacy} 条旧格式条目，归入 legacy 会话组`);
+    const warmup = freshWarmup();
+    for (const key of ['auto', 'chat', 'work']) {
+        const w = raw.warmup?.[key];
+        if (typeof w === 'number' && Number.isFinite(w) && w >= 0)
+            warmup[key] = Math.floor(w);
+    }
+    return { buckets: out, warmup };
+}
+/** 按会话分组（会话切片）：组按首条时间排序、组内按时间稳定排序——
+ *  蒸馏的一切触发都以切片为单位，切片内永不跨会话混装（ADR-0003）。 */
+export function groupPendingBySession(messages) {
+    const groups = new Map();
+    for (const m of messages) {
+        const g = groups.get(m.sessionId);
+        if (g)
+            g.push(m);
+        else
+            groups.set(m.sessionId, [m]);
+    }
+    return [...groups.entries()]
+        .map(([sessionId, msgs]) => ({ sessionId, messages: [...msgs].sort((a, b) => a.timestamp - b.timestamp) }))
+        .sort((a, b) => a.messages[0].timestamp - b.messages[0].timestamp);
 }
 /** 全量原子落盘（每次蒸馏尝试后调用；桶有上限，量级为百条级）。 */
-export async function savePending(file, buckets) {
-    const payload = { version: 1, buckets };
+export async function savePending(file, buckets, warmup) {
+    const payload = { version: 1, buckets, ...(warmup ? { warmup } : {}) };
     await atomicWriteJson(file, payload);
 }
 export function pendingPathFor(dataDir) {

package/dist/store/search-utils.js

@@ -3,8 +3,9 @@
  * - rrfMerge：RRF（Reciprocal Rank Fusion，k=60）多路结果融合，hybrid 检索用；
  * - bm25RankToScore：FTS5 bm25 rank（负值=更相关）转 0~1 分数；
  * - buildFtsQuery / tokenizeForFts：FTS5 查询构造与写入侧分词。
- *   官方用 jieba 分词；这里用项目自带的 CJK 二元组 + 英文词分词（util/text.ts），
- *   读写两侧共用同一分词器，保证查询 token 与索引 token 对齐，且零原生依赖。
+ *   分词走 util/text.ts 的 tokenize（jieba 词 + CJK 二元组并集，@node-rs/jieba
+ *   预编译二进制，加载失败自动回退纯二元组），读写两侧共用同一分词器，
+ *   保证查询 token 与索引 token 对齐；FTS 索引按分词器版本戳自动重建（sqlite.ts）。
  */
 import { tokenize } from '../util/text.js';
 /** 标准 RRF 常数（原论文值）；k 越大越偏向低排名项（分布更平滑）。 */

package/dist/store/session-modes.d.ts

@@ -7,6 +7,8 @@ export declare class SessionModeStore {
     private readonly entries;
     private readonly loaded;
     private persistFailed;
+    /** 档位切换回调（index.ts 装配 runner 的同步动作：切片落袋/挂起，ADR-0003）。 */
+    private onModeChange?;
     /** 串行化持久化写（避免并发原子写撞临时文件名）。 */
     private writeChain;
     constructor(dataDir: string, defaultMode: Extract<MemoryMode, 'auto' | 'chat' | 'work'>, logger?: MemoryLogger | undefined);
@@ -15,6 +17,8 @@ export declare class SessionModeStore {
     get default(): MemoryMode;
     /** 同步读取：未设置过的会话返回默认档。 */
     get(sessionId: string): MemoryMode;
+    /** 注册档位切换回调（同步调用；回调异常只记日志不阻断写穿）。 */
+    setModeChangeHandler(cb: (sessionId: string, oldMode: MemoryMode, newMode: MemoryMode) => void): void;
     /** 设置会话档位（写穿持久化；持久化失败保持内存态生效）。 */
     set(sessionId: string, mode: MemoryMode): void;
     /** 等待在途持久化写完成（测试/停机用）。 */

package/dist/store/session-modes.js

@@ -5,6 +5,7 @@
  * 存储失败只降级为内存态（warn 不崩），与插件的存储降级不变量一致。
  */
 import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
 import { atomicWriteJson, ensureDir, readJsonIfExists } from './io.js';
 const MODES = ['auto', 'chat', 'work', 'off'];
 const PRUNE_MS = 90 * 24 * 3600_000;
@@ -19,6 +20,8 @@ export class SessionModeStore {
     entries = new Map();
     loaded;
     persistFailed = false;
+    /** 档位切换回调（index.ts 装配 runner 的同步动作：切片落袋/挂起，ADR-0003）。 */
+    onModeChange;
     /** 串行化持久化写（避免并发原子写撞临时文件名）。 */
     writeChain = Promise.resolve();
     constructor(dataDir, defaultMode, logger) {
@@ -52,10 +55,23 @@ export class SessionModeStore {
     get(sessionId) {
         return this.entries.get(sessionId)?.mode ?? this.loaded;
     }
+    /** 注册档位切换回调（同步调用；回调异常只记日志不阻断写穿）。 */
+    setModeChangeHandler(cb) {
+        this.onModeChange = cb;
+    }
     /** 设置会话档位（写穿持久化；持久化失败保持内存态生效）。 */
     set(sessionId, mode) {
+        const old = this.get(sessionId);
         this.entries.set(sessionId, { mode, updatedAt: Date.now() });
         this.writeChain = this.writeChain.then(() => this.persist());
+        if (old !== mode && this.onModeChange) {
+            try {
+                this.onModeChange(sessionId, old, mode);
+            }
+            catch (err) {
+                this.logger?.warn(`[memory] 档位切换回调失败: ${errDetail(err)}`);
+            }
+        }
     }
     /** 等待在途持久化写完成（测试/停机用）。 */
     flush() {

package/dist/store/sqlite.d.ts

@@ -34,6 +34,8 @@ export declare class MemoryDb {
     private readonly logger?;
     private stmtUpsertL1;
     private stmtGetL1;
+    /** 主表存在性点查（防御性 FTS 删除的前置判断，走主键索引）。 */
+    private stmtL1Exists;
     private stmtDeleteL1Meta;
     private stmtDeleteL1Vec?;
     private stmtInsertL1Vec?;
@@ -44,6 +46,8 @@ export declare class MemoryDb {
     private stmtL1FtsSearchFamily;
     private stmtUpsertL0;
     private stmtGetL0;
+    /** 主表存在性点查（同 L1：防御性 FTS 删除的前置判断）。 */
+    private stmtL0Exists;
     private stmtDeleteL0Vec?;
     private stmtInsertL0Vec?;
     private stmtSearchL0Vec?;
@@ -81,8 +85,13 @@ export declare class MemoryDb {
     private hasColumn;
     /** 重建后的 l1_fts 从 l1_records 全量回灌（仅在 drop 重建时调用）。 */
     private backfillL1Fts;
+    /** 重建后的 l0_fts 从 l0_conversations 全量回灌（仅 drop 重建时调用；iterate 流式防大库内存峰值）。 */
+    private backfillL0Fts;
     private readEmbeddingMeta;
     private writeEmbeddingMeta;
+    /** 通用字符串 kv（embedding_meta 表兼作元数据 kv 存储，如 FTS 分词器版本戳）。 */
+    private readMetaString;
+    private writeMetaString;
     /**
      * 持久化 embedding meta（语义：物理向量表当前对应的 provider/维度）。
      * 活切换在 swapProvider 成功后即写（表已是新维度）；启动/补齐链在
@@ -139,6 +148,9 @@ export declare class MemoryDb {
     countL0(): number;
     /** 统计 recorded_at >= iso 的消息数（状态面板"今日捕获"用）。 */
     countL0Since(iso: string): number;
+    /** 按会话取最近消息（时间升序返回；走 idx_l0_session_id 索引）。
+     *  蒸馏背景参考专用——按会话现查替代全局内存数组（ADR-0003）。 */
+    recentL0BySession(sessionId: string, limit: number): L0MessageRecord[];
     /** L0 全量列举（重建快照用；按时间升序，事务一致性避开 JSONL 追加竞态）。 */
     listL0All(): L0MessageRecord[];
     /** 重建成本预估（一次全表聚合：会话数 / 消息数 / 字符量）。 */

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;
@@ -107,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);
         }
@@ -287,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 ──
@@ -314,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(
@@ -392,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) {
@@ -492,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
@@ -517,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 成功后即写（表已是新维度）；启动/补齐链在
@@ -606,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) {
@@ -617,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));
         }
     }
@@ -863,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);
@@ -873,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);
                 }
             }
@@ -916,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)

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;