dsh-prime-memory 0.24.1 → 0.25.0

package/dist/config.js

@@ -226,6 +226,10 @@ export const memorySchema = Schema.object({
     usageScenario: Schema.object({
         enabled: Schema.boolean().default(false),
     }),
+    // 关键词蒸馏回填：默认关（关时不回填、不产 dsh_keywords、FTS 逐字不变）；护栏复用 backfill。
+    keyword: Schema.object({
+        enabled: Schema.boolean().default(false),
+    }),
     // 类型叙述模板（G2）：默认**开**；开时抽取 prompt 追加分类型 content 骨架（关时仍逐字不变）。
     // 默认值从关改开的理由写在上方接口注释：只给定义实测骨架齐备 0/23，
     // 而"没前因后果就不算可用"是用户定的判据，所以默认值要按可用性定而不是按保守定。

package/dist/contract.d.ts

@@ -647,6 +647,18 @@ export interface WingBackfillResponse {
     started: boolean;
     running: boolean;
 }
+/** dsh-memory/keyword-backfill（关键词蒸馏回填，后台任务；门控关时 enabled=false 不启动）。 */
+export interface KeywordBackfillResponse {
+    /** true = 本次触发启动了新任务；false = 已有任务在跑或门控关。 */
+    started: boolean;
+    running: boolean;
+    /** 门控 `cfg.keyword.enabled`；关时不启动，面板据此提示先开开关。 */
+    enabled: boolean;
+    /** 本进程累计成功回填条数（重启归零；观测用）。 */
+    updated: number;
+    /** 失败/跳过数。 */
+    failed: number;
+}
 /** dsh-memory/session-stats(悬浮卡信息区;热路径端点)。 */
 export interface SessionStatsRequest {
     sessionId: string;
@@ -852,6 +864,28 @@ export interface UiRecord {
     maturity?: 'low' | 'mid' | 'high';
     /** 使用场景（G1）：从 metadata.dsh_usage_scenario 读出；功能关/无则 undefined。 */
     usageScenario?: string[];
+    /**
+     * 名称（md 投射相，N1）：名称蒸馏产出的短标题，**投射文件名就取它**
+     * （`<type>/<name>.memory.md` 的 stem）。`undefined`/`null` = 还没名字（存量记录），
+     * 投射器回落 `mem-<id8>`。面板显示它是为了核对“这条记忆对应哪个投射文件”。
+     * 纯投影字段：读时从 `l1_records.name` 带出，不进存储改动。
+     */
+    name?: string | null;
+    /**
+     * 可见范围（§E）：`global` = 用户默认（任何工作区可见）；`workspace` = 仅归属工作区可见。
+     * 展示用（读时从 `l1_records.scope` 带出，纯投影）。
+     */
+    scope?: 'global' | 'workspace';
+    /** 归属工作区路径（仅 `scope='workspace'` 时非空；`global` 恒为 `null`）。展示用。 */
+    workspaceId?: string | null;
+    /**
+     * 关键词（保留字段，**用于 BM25 匹配**）：从 `metadata.dsh_keywords` 读出。
+     *
+     * 与 `usageScenario` 同范式（保留键、随 metadata 落库、不进 `l1_records` DDL）。
+     * **当前无产出方**——抽取/命名尚未产出该键，故实机上恒为空；先预留字段与检索轴，
+     * 让 UI 与 BM25 都就位。无键 → `undefined`（缺席 ≠ 空数组）。
+     */
+    keywords?: string[];
     /**
      * 人给的相关度均值(0..5)；从未被 0..5 打过分为 undefined（**缺席 ≠ 0 分**）。
      * 读时从 recall-feedback sidecar 派生，不进存储/快照。
@@ -1628,6 +1662,7 @@ export interface DshMemoryRequestMap {
     'dsh-memory/room-register': RoomRegisterRequest;
     'dsh-memory/room-admin': RoomAdminRequest;
     'dsh-memory/wing-backfill': Record<string, never>;
+    'dsh-memory/keyword-backfill': Record<string, never>;
     'dsh-memory/session-stats': SessionStatsRequest;
     'dsh-memory/settings-get': Record<string, never>;
     'dsh-memory/settings-set': SettingsSetRequest;
@@ -1690,6 +1725,7 @@ export interface DshMemoryResponseMap {
     'dsh-memory/room-register': RoomRegisterResponse;
     'dsh-memory/room-admin': RoomAdminResponse;
     'dsh-memory/wing-backfill': WingBackfillResponse;
+    'dsh-memory/keyword-backfill': KeywordBackfillResponse;
     'dsh-memory/session-stats': SessionStatsResponse;
     'dsh-memory/settings-get': SettingsGetResponse;
     'dsh-memory/settings-set': SettingsSetResponse;

package/dist/keyword-backfill.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 关键词蒸馏回填（keyword axis 产出方）。
+ *
+ * 职责：从 L1 记录中找「缺 dsh_keywords」的存量记录，按 chunk 20 条一批送 LLM 提炼关键词
+ * 与使用场景，归一后写 `metadata.dsh_keywords` + `metadata.dsh_usage_scenario`，
+ * 并用 `patchMetadataAndReindex` 保证新关键词**立即进 FTS BM25 轴**。
+ *
+ * 安全边界（继承 wing-backfill）：
+ * - 单飞：同时最多一个回填任务,重复触发直接返回 running(不排队不叠加)
+ * - 后台执行：端点立即返回,逐块推进(每块 20 条),不阻塞 RPC/管线
+ * - 失败可退：LLM 失败/输出不合法只跳过当前块,原记录零改动(标签只写成功的)
+ * - 有界：单次任务最多处理 cfg.backfill.maxRecords 条,防止一次跑飞;其余可再次触发
+ * - 门控关（`cfg.keyword.enabled = false`）：run() 入口立即跳过——无回填、FTS 逐字不变
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryLogger, MemoryRecord } from './types.js';
+import type { MemoryBackend } from './store/memory-backend.js';
+import type { MemoryConfig } from './config.js';
+export interface KeywordBackfillDeps {
+    ctx: Context;
+    cfg: MemoryConfig;
+    backend: MemoryBackend;
+    logger: MemoryLogger;
+}
+export interface KeywordBackfillState {
+    running: boolean;
+    updated: number;
+    failed: number;
+}
+export declare function keywordBackfillState(): KeywordBackfillState;
+/** 启动后台关键词回填；已在运行返回 false（单飞）。 */
+export declare function startKeywordBackfill(deps: KeywordBackfillDeps): {
+    started: boolean;
+    running: boolean;
+};
+/**
+ * 回填主体（导出供单测 await 到完成；生产走 `startKeywordBackfill` 的单飞后台包装）。
+ * 门控关（`cfg.keyword.enabled = false`）时入口立即返回，不碰任何记录与 fts。
+ */
+export declare function runKeywordBackfillOnce(deps: KeywordBackfillDeps): Promise<void>;
+/** 关键词标注器（导出供单测）。 */
+export declare function labelKeywordChunk(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, chunk: MemoryRecord[]): Promise<Array<{
+    record: MemoryRecord;
+    keywords: string[];
+    usageScenario?: string[];
+}>>;

package/dist/keyword-backfill.js

@@ -0,0 +1,143 @@
+import { callLLM, parseJsonLogged } from './llm.js';
+import { normKeywords, normUsageScenario, KEYWORDS_METADATA_KEY } from './metadata-validators.js';
+import { yieldLoop } from './util/yield.js';
+/** 每块条数（一次 LLM 调用判定的记录数；与 wing-backfill 同口径）。 */
+const CHUNK = 20;
+/** 扫描页大小（轻量投影分页；与 wing-backfill 一致）。 */
+const PAGE = 200;
+/** 单次任务默认处理上限（cfg.backfill.maxRecords 优先）。 */
+const DEFAULT_MAX_RECORDS = 300;
+/** 墙钟默认预算（cfg.backfill.timeBudgetMs 优先）。 */
+const DEFAULT_TIME_BUDGET_MS = 120_000;
+const state = { running: false, updated: 0, failed: 0 };
+export function keywordBackfillState() {
+    return { ...state };
+}
+// ── SYSTEM 提示词（定稿版，由 tools/keyword-distill.prompt.md 的 ```text 块迁移） ──
+const SYSTEM_PROMPT = [
+    '你是记忆库的关键词与情景标注器。给定若干条记忆（每条含 id、标题、正文摘要），为每条提炼：',
+    '1) keywords：最能代表该记忆的检索词，用于精确命中；2) usage_scenario：未来「何时应当浮现这条记忆」的场景短语。',
+    '',
+    '严格规则：',
+    '- keywords 的唯一判据：**用户未来会输入什么词把这条记忆捞出来**。优先具体名词性标识——项目/模块/文件/函数/配置项/命令/错误码/版本号/数字阈值/工具名/专有实体名。',
+    '- **禁止**把正文里的动宾短语压缩成抽象黑话当关键词（反例：把"判定批量流量"压成"批量流量判定"、把"做窗口滑动归因"压成"窗口滑动归因"、把"保持只读约束"压成"只读约束"）——这类词没人会拿去搜，一律换成它指向的具体实体/标识，或直接删掉。',
+    '- keywords：2–5 个（宁少勿滥，够区分即可）；每个 2–6 词或 1 个复合术语；不得与标题字面重复、不得互相近义堆叠、不收停用词/整句。',
+    '- usage_scenario：1–3 条；每条 5–10 词的短场景描述（不是完整命令句）；彼此必须可区分，相似的合并成更泛化的一条。',
+    '- 语言跟随该记忆正文：中文记忆产出中文（技术标识符、API 名、错误码原样保留），英文记忆产出英文。',
+    '- id 必须原样照抄，不得改写、截断或改用序号；一条记忆只产一组，不要拆分。',
+    '',
+    '输出：只输出一个 JSON 数组，不要多余文字、不要解释。每项形如：',
+    '{"id":"<原id>","keywords":["…","…"],"usage_scenario":["…","…"]}',
+].join('\n');
+/** 启动后台关键词回填；已在运行返回 false（单飞）。 */
+export function startKeywordBackfill(deps) {
+    if (state.running)
+        return { started: false, running: true };
+    state.running = true;
+    state.updated = 0;
+    state.failed = 0;
+    void runKeywordBackfillOnce(deps).finally(() => {
+        state.running = false;
+        deps.logger.info(`[memory] keyword 回填结束:成功 ${state.updated} 条,失败 ${state.failed} 条`);
+    });
+    return { started: true, running: true };
+}
+/**
+ * 回填主体（导出供单测 await 到完成；生产走 `startKeywordBackfill` 的单飞后台包装）。
+ * 门控关（`cfg.keyword.enabled = false`）时入口立即返回，不碰任何记录与 fts。
+ */
+export async function runKeywordBackfillOnce(deps) {
+    const { cfg, backend, logger } = deps;
+    if (!cfg.keyword?.enabled) {
+        logger.info('[memory] keyword 回填跳过：keyword.enabled = false（功能关，不回填）');
+        return;
+    }
+    const MAX_RECORDS = cfg.backfill?.maxRecords ?? DEFAULT_MAX_RECORDS;
+    const TIME_BUDGET_MS = cfg.backfill?.timeBudgetMs ?? DEFAULT_TIME_BUDGET_MS;
+    const startedAt = Date.now();
+    // ── 扫描阶段（轻量投影，不反序列化正文）──
+    const total = await backend.size();
+    const pendingIds = [];
+    let scanned = 0;
+    for (let offset = 0;; offset += PAGE) {
+        const page = await backend.allLite(PAGE, offset);
+        if (page.length === 0)
+            break;
+        for (const r of page) {
+            const kw = r.metadata?.[KEYWORDS_METADATA_KEY];
+            if (!(Array.isArray(kw) && kw.length > 0))
+                pendingIds.push(r.id);
+        }
+        scanned += page.length;
+        if (Date.now() - startedAt > TIME_BUDGET_MS) {
+            logger.info(`[memory] keyword 回填：墙钟预算(${TIME_BUDGET_MS / 1000}s)在扫描阶段用尽(已扫 ${scanned}/${total}),留待再触发`);
+            return;
+        }
+        await yieldLoop();
+    }
+    let budget = Math.min(pendingIds.length, MAX_RECORDS);
+    logger.info(`[memory] keyword 回填启动：缺关键词 ${pendingIds.length} 条,本次上限 ${budget} 条`);
+    // ── 标注阶段（补水→LLM→归一→写回）──
+    for (let offset = 0; offset < pendingIds.length && budget > 0; offset += CHUNK) {
+        if (Date.now() - startedAt > TIME_BUDGET_MS) {
+            logger.info(`[memory] keyword 回填：墙钟预算用尽,剩余 ${pendingIds.length - offset} 条留待再触发`);
+            break;
+        }
+        const hydrated = await backend.getByIds(pendingIds.slice(offset, offset + CHUNK));
+        const chunk = hydrated.filter((r) => r.content && r.content.trim() !== '');
+        if (chunk.length === 0)
+            continue;
+        budget -= chunk.length;
+        const labeled = await labelKeywordChunk(deps.ctx, cfg, logger, chunk);
+        for (const { record, keywords, usageScenario } of labeled) {
+            const meta = { ...(record.metadata ?? {}) };
+            meta[KEYWORDS_METADATA_KEY] = keywords;
+            if (usageScenario && usageScenario.length > 0)
+                meta.dsh_usage_scenario = usageScenario;
+            if (await backend.patchMetadataAndReindex(record.id, meta))
+                state.updated++;
+            else
+                state.failed++;
+            await yieldLoop();
+        }
+    }
+}
+/** 关键词标注器（导出供单测）。 */
+export async function labelKeywordChunk(ctx, cfg, logger, chunk) {
+    const list = chunk.map((r, i) => `${i + 1}. id=${r.id}\n标题：${r.name ?? ''}\n正文：${r.content.slice(0, 300)}`).join('\n\n');
+    const user = '记忆列表:\n' + list;
+    try {
+        const raw = await callLLM(ctx, cfg, {
+            system: SYSTEM_PROMPT,
+            user,
+            maxTokens: 4096,
+            layer: 'l1-extract',
+            logger,
+        });
+        const parsed = parseJsonLogged(raw, 'keyword 回填', logger);
+        if (!Array.isArray(parsed))
+            return [];
+        const byId = new Map(chunk.map((r) => [r.id, r]));
+        const out = [];
+        for (const item of parsed) {
+            const record = typeof item?.id === 'string' ? byId.get(item.id) : undefined;
+            if (!record) {
+                logger.warn(`[memory] keyword 回填:id 配对失败,已丢弃(id=${String(item?.id).slice(0, 40)})`);
+                continue;
+            }
+            const keywords = normKeywords(item.keywords, 5);
+            if (keywords.length === 0) {
+                logger.warn(`[memory] keyword 回填:normKeywords 结果为空,已跳过(id=${record.id})`);
+                continue;
+            }
+            const usageScenario = normUsageScenario(item.usage_scenario, 3);
+            out.push({ record, keywords, usageScenario: usageScenario.length > 0 ? usageScenario : undefined });
+        }
+        return out;
+    }
+    catch (err) {
+        logger.warn(`[memory] keyword 回填块失败(跳过 ${chunk.length} 条,原记录未改): ${err instanceof Error ? err.message : String(err)}`);
+        state.failed += chunk.length;
+        return [];
+    }
+}

package/dist/metadata-validators.d.ts

@@ -32,6 +32,15 @@ export { isCognitiveHall, COGNITIVE_HALLS, type CognitiveHall } from './cognitiv
  * 非数组或空→ `[]`（缺字段中性，不抛——防单条抽取失败波及整切片重试）。
  */
 export declare function normUsageScenario(v: unknown, max?: number): string[];
+/** 关键词检索轴的磁盘保留键（喂 `l1_fts.keywords` 列，读取侧见 `sqlite.ftsKeywordText`）。 */
+export declare const KEYWORDS_METADATA_KEY = "dsh_keywords";
+/**
+ * 关键词归一 + 去重（忽略大小写）+ 长度钳 + 上限。**所有 `dsh_keywords` 写回点必须过这里**。
+ *
+ * 与 `normUsageScenario` 同范式（关键词是自然语言术语/标识符，非 slug，不做字符集校验），
+ * 只是上限更紧（≤5）、单条更短。非数组/空→`[]`（缺字段中性，不抛——防单条产出失败波及整批）。
+ */
+export declare function normKeywords(v: unknown, max?: number): string[];
 /**
  * 读 **Wing（生活域）**。⚠️ 磁盘键是 `metadata.hall`——历史别名，存的其实是 **wing 值**。
  * 只认词表内的合法 wing（8 角 + general），否则 undefined。

package/dist/metadata-validators.js

@@ -92,6 +92,37 @@ export function normUsageScenario(v, max = 3) {
     }
     return out;
 }
+/** 关键词检索轴的磁盘保留键（喂 `l1_fts.keywords` 列，读取侧见 `sqlite.ftsKeywordText`）。 */
+export const KEYWORDS_METADATA_KEY = 'dsh_keywords';
+/** 单个关键词最大字符数：按“词”太主观，用字符上限兜住整句泄漏（CJK 复合术语通常 ≤12）。 */
+const KEYWORD_MAX_CHARS = 24;
+/**
+ * 关键词归一 + 去重（忽略大小写）+ 长度钳 + 上限。**所有 `dsh_keywords` 写回点必须过这里**。
+ *
+ * 与 `normUsageScenario` 同范式（关键词是自然语言术语/标识符，非 slug，不做字符集校验），
+ * 只是上限更紧（≤5）、单条更短。非数组/空→`[]`（缺字段中性，不抛——防单条产出失败波及整批）。
+ */
+export function normKeywords(v, max = 5) {
+    if (!Array.isArray(v) || max <= 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const raw of v) {
+        if (typeof raw !== 'string')
+            continue;
+        const t = raw.trim();
+        if (!t)
+            continue;
+        const key = t.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(t.slice(0, KEYWORD_MAX_CHARS));
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
 /**
  * 读 **Wing（生活域）**。⚠️ 磁盘键是 `metadata.hall`——历史别名，存的其实是 **wing 值**。
  * 只认词表内的合法 wing（8 角 + general），否则 undefined。

package/dist/stats.d.ts

@@ -177,6 +177,12 @@ export declare function hitToUiRecord(r: {
     metadata?: Record<string, unknown>;
     score?: number;
     family?: string;
+    /** 名称（md 投射相）：投射文件名取它；无名字 = undefined。 */
+    name?: string;
+    /** 可见范围（§E）：'workspace' 才带归属，其余一律归一 'global'。 */
+    scope?: string;
+    /** 归属工作区路径（仅 scope='workspace' 时非空）。 */
+    workspaceId?: string;
     /** 退场判据:`valid_to` 闭合即已退场(软删)。由 `listL1`/`getByIds` 透传。 */
     validTo?: number;
 }, extra?: {

package/dist/stats.js

@@ -33,6 +33,7 @@ import { isRoomSlug } from './metadata-validators.js';
 import { InProcMemoryBackend } from './store/memory-backend.js';
 import { isWingCorner } from './store/session-modes.js';
 import { startWingBackfill } from './wing-backfill.js';
+import { startKeywordBackfill, keywordBackfillState } from './keyword-backfill.js';
 import { errDetail } from './util/filelog.js';
 import { snapshotTokenCost } from './token-cost.js';
 import { computeMaturity } from './util/maturity.js';
@@ -70,6 +71,7 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/room-register',
     'dsh-memory/room-admin',
     'dsh-memory/wing-backfill',
+    'dsh-memory/keyword-backfill',
     'dsh-memory/session-stats',
     'dsh-memory/settings-get',
     'dsh-memory/settings-set',
@@ -1140,6 +1142,19 @@ export async function handleEndpoint(endpoint, payload, deps) {
             });
             return r;
         }
+        case 'dsh-memory/keyword-backfill': {
+            // 门控关：不启动，如实报 enabled=false（面板据此提示“先开关键词回填开关”）。
+            if (!cfg.keyword?.enabled)
+                return { started: false, running: false, enabled: false, updated: 0, failed: 0 };
+            const r = startKeywordBackfill({
+                ctx: deps.ctx,
+                cfg: deps.cfg,
+                backend: stores.backend ?? new InProcMemoryBackend(stores.l1),
+                logger: deps.logger,
+            });
+            const st = keywordBackfillState();
+            return { started: r.started, running: r.running, enabled: true, updated: st.updated, failed: st.failed };
+        }
         // ── 会话级统计(悬浮卡信息区;热路径端点,见 SessionInfoSource 的零 I/O 硬规则) ──
         case 'dsh-memory/session-stats': {
             if (!sessionInfo)
@@ -2226,6 +2241,16 @@ export function hitToUiRecord(r, extra) {
         }),
         // G1 使用场景：从命名空间保留键读出（功能关/无键 → undefined）。
         usageScenario: Array.isArray(r.metadata?.dsh_usage_scenario) ? r.metadata?.dsh_usage_scenario : undefined,
+        // 投射身份三项（N1）：名称 / 可见范围 / 归属工作区。面板靠它们核对“这条记忆
+        // 对应哪个投射文件、对谁可见”——这三个值此前从不进 UiRecord，于是面板上
+        // 无法把记忆与投射文件对上。纯投影，不从存储侧另算。
+        name: r.name ?? null,
+        scope: r.scope === 'workspace' ? 'workspace' : 'global',
+        workspaceId: r.scope === 'workspace' ? (r.workspaceId ?? '') || null : null,
+        // 关键词（保留字段，用于 BM25）：与 usageScenario 同范式，从保留键读出（无键 → undefined）。
+        keywords: Array.isArray(r.metadata?.dsh_keywords)
+            ? (r.metadata?.dsh_keywords).filter((k) => typeof k === 'string' && k !== '')
+            : undefined,
         // 人给相关度均值：读时从 sidecar 派生（不进存储/快照）；未打分 → 字段缺席。
         userRelevance: extra?.userRelevance ?? undefined,
     };

package/dist/store/l1.d.ts

@@ -127,6 +127,12 @@ export declare class L1Store {
      * 返回 false 表示 id 不存在或写入失败——调用方须记账,不许静默。
      */
     patchMetadata(id: string, metadata: Record<string, unknown>): boolean;
+    /**
+     * 写 metadata_json + 顺带重索引 `l1_fts`（关键词回填专用）。
+     * 与 `patchMetadata` 的区分：后者只改主表（适合 tags/room/relabel 这类不进 fts 的元数据）；
+     * 本方法额外重跑该行的 fts 插入，让新写的 `dsh_keywords` 立刻进 BM25 关键词轴。
+     */
+    patchMetadataAndReindex(id: string, metadata: Record<string, unknown>): boolean;
     /** repo 归属修补(ADR-0015 T3.3;人工消歧用)。CAS:expectRepoKeyName 非空时要求当前值匹配。 */
     patchRepoKey(id: string, patch: {
         repoKeyName?: string;

package/dist/store/l1.js

@@ -156,6 +156,14 @@ export class L1Store {
     patchMetadata(id, metadata) {
         return this.db.patchL1Metadata(id, metadata);
     }
+    /**
+     * 写 metadata_json + 顺带重索引 `l1_fts`（关键词回填专用）。
+     * 与 `patchMetadata` 的区分：后者只改主表（适合 tags/room/relabel 这类不进 fts 的元数据）；
+     * 本方法额外重跑该行的 fts 插入，让新写的 `dsh_keywords` 立刻进 BM25 关键词轴。
+     */
+    patchMetadataAndReindex(id, metadata) {
+        return this.db.patchL1MetadataAndReindex(id, metadata);
+    }
     /** repo 归属修补(ADR-0015 T3.3;人工消歧用)。CAS:expectRepoKeyName 非空时要求当前值匹配。 */
     patchRepoKey(id, patch, expectRepoKeyName) {
         const changed = this.db.patchRepoKey(id, patch, expectRepoKeyName);

package/dist/store/memory-backend-worker.d.ts

@@ -29,6 +29,7 @@ export declare class WorkerMemoryBackend implements MemoryBackend {
     getByIds(ids: string[]): Promise<MemoryRecord[]>;
     list(opts: L1ListOpts): Promise<L1ListResult>;
     patchMetadata(id: string, metadata: Record<string, unknown>): Promise<boolean>;
+    patchMetadataAndReindex(id: string, metadata: Record<string, unknown>): Promise<boolean>;
     size(): Promise<number>;
     dispose(): Promise<void>;
 }

package/dist/store/memory-backend-worker.js

@@ -100,6 +100,9 @@ export class WorkerMemoryBackend {
     async patchMetadata(id, metadata) {
         return this.call('patchMetadata', [id, metadata]);
     }
+    async patchMetadataAndReindex(id, metadata) {
+        return this.call('patchMetadataAndReindex', [id, metadata]);
+    }
     async size() {
         return this.call('size', []);
     }

package/dist/store/memory-backend.d.ts

@@ -50,6 +50,8 @@ export interface MemoryBackend {
     list(opts: L1ListOpts): Promise<L1ListResult>;
     /** **只**更新 metadata_json(不动 content,不重算嵌入)。 */
     patchMetadata(id: string, metadata: Record<string, unknown>): Promise<boolean>;
+    /** 写 metadata_json + 重索引该行的 `l1_fts`（关键词回填专用；新 `dsh_keywords` 要立刻进 BM25 轴）。 */
+    patchMetadataAndReindex(id: string, metadata: Record<string, unknown>): Promise<boolean>;
     /** L1 记录总数(巡检进度分母)。 */
     size(): Promise<number>;
     /** 释放后端(worker 实现会 terminate 线程)。 */
@@ -68,6 +70,7 @@ export declare class InProcMemoryBackend implements MemoryBackend {
     getByIds(ids: string[]): Promise<MemoryRecord[]>;
     list(opts: L1ListOpts): Promise<L1ListResult>;
     patchMetadata(id: string, metadata: Record<string, unknown>): Promise<boolean>;
+    patchMetadataAndReindex(id: string, metadata: Record<string, unknown>): Promise<boolean>;
     size(): Promise<number>;
     dispose(): Promise<void>;
 }

package/dist/store/memory-backend.js

@@ -21,6 +21,9 @@ export class InProcMemoryBackend {
     async patchMetadata(id, metadata) {
         return this.l1.patchMetadata(id, metadata);
     }
+    async patchMetadataAndReindex(id, metadata) {
+        return this.l1.patchMetadataAndReindex(id, metadata);
+    }
     async size() {
         return this.l1.size;
     }

package/dist/store/memory-md-disable.js

@@ -12,7 +12,7 @@
  * 「文件存在性 + 当前后缀 + 指纹一致性」三项检查重算一遍，与退场路径无关。
  *
  * 点火已由 `L1Store` 的汇流口接管（`store/memory-md-sync.ts`），本模块只供收敛器与
- * 单条凭证两个原件——曾经在这里的 `makeSuffixSync` 点火器已退役，不留第二事实源。
+ * 单条凭证两个原件——曾经住在这里的旧「后缀点火器工厂」已退役，不留第二事实源。
  *
  * 单点失效联动（`disableProjectionFile`）的三种落点：
  * - 盘上有 `.memory.md`（**不再要求有 workspace**：无归属那条也要改，它的文件本来就在单根）→ **改名**成 `.memory.md.disable`；

package/dist/store/memory-md-sync.js

@@ -14,7 +14,7 @@
  *
  * 一句话口径：**投射文件形状是库状态的函数，不是任何调用点的事件**（事件只是重算契机）。
  *
- * 四条契约（前三条与 `makeSuffixSync` 时期一致，收口没有放宽）：
+ * 四条契约（前三条与收口前一致，收口没有放宽）：
  * 1. **不阻塞库**：钩子同步返回，文件侧在后台跑；磁盘满不能变成「记忆删不掉」。
  * 2. **绝不抛**：异常一律收敛成 warn（与 `disableProjectionFile` 同纪律）。
  * 3. **现读配置与账本**：`memExport` 是 volatile，快照会让「事后打开旋钮」一直到下次启动

package/dist/store/memory-worker.js

@@ -60,6 +60,9 @@ else {
                     case 'patchMetadata':
                         reply(id, true, handle.patchL1Metadata(String(args[0]), args[1]));
                         return;
+                    case 'patchMetadataAndReindex':
+                        reply(id, true, handle.patchL1MetadataAndReindex(String(args[0]), args[1]));
+                        return;
                     case 'size':
                         reply(id, true, handle.countL1());
                         return;

package/dist/store/sqlite.d.ts

@@ -305,6 +305,17 @@ export declare class MemoryDb {
     /** 打标作业完成/失败(失败保留行供诊断;重算由下一次触发再入队)。 */
     finishSceneRecluster(jobId: string, ok: boolean): void;
     patchL1Metadata(id: string, metadata: Record<string, unknown>): boolean;
+    /**
+     * 更新 metadata_json 后**顺带重索引该行的 `l1_fts`**（关键词回填专用）。
+     *
+     * `patchL1Metadata` 本身不碰 fts——多数写回点（tags / room / relabel）不需要、也不想付这个代价；
+     * 但关键词轴若只写元数据不重索引，`ftsKeywordText` 读不到新 `dsh_keywords`，那条 BM25 轴
+     * 对存量记录永远空。故把「写元数据 + 重索引」焊在一个方法里，杜绝“写了关键词但检索看不到”。
+     *
+     * 退场/不存在的行：只从 fts 删除（幂等），不插入。fts 不可用时降级为纯 `patchL1Metadata`。
+     * 参数列表与 `stmtL1FtsInsert` / `backfillL1Fts` 逐位对齐（同三处列清单，漏一列静默丢索引）。
+     */
+    patchL1MetadataAndReindex(id: string, metadata: Record<string, unknown>): boolean;
     /** 全量读取(调试/迁移/重嵌入用;检索请走 FTS/向量)。 */
     getAllL1(): MemoryRecord[];
     getL1ByIds(ids: string[]): MemoryRecord[];

package/dist/store/sqlite.js

@@ -561,10 +561,10 @@ export class MemoryDb {
             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') || !this.hasColumn('l1_fts', 'scope') || tokenizerChanged)) {
+            if (this.tableExists('l1_fts') && (!this.hasColumn('l1_fts', 'family') || !this.hasColumn('l1_fts', 'scope') || !this.hasColumn('l1_fts', 'keywords') || tokenizerChanged)) {
                 this.db.exec('DROP TABLE l1_fts');
                 ftsRebuilt = true;
-                this.logger?.info(`${TAG} l1_fts 缺 family/scope 列或分词器已变更(${savedStamp} → ${wantStamp}),重建全文索引`);
+                this.logger?.info(`${TAG} l1_fts 缺 family/scope/keywords 列或分词器已变更(${savedStamp} → ${wantStamp}),重建全文索引`);
             }
             let l0FtsRebuilt = false;
             if (this.tableExists('l0_fts') && tokenizerChanged) {
@@ -574,6 +574,7 @@ export class MemoryDb {
             }
             this.db.exec(`
         CREATE VIRTUAL TABLE IF NOT EXISTS l1_fts USING fts5(
+          keywords,
           content,
           content_original UNINDEXED,
           record_id UNINDEXED,
@@ -603,10 +604,10 @@ export class MemoryDb {
         )
       `);
             this.stmtL1FtsInsert = this.db.prepare(`
-        INSERT INTO l1_fts (content, content_original, record_id, type, priority, scene_name,
+        INSERT INTO l1_fts (keywords, content, content_original, record_id, type, priority, scene_name,
           session_id, version, timestamp_str, timestamp_start, timestamp_end, metadata_json, family,
           scope, workspace_id)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `);
             this.stmtL1FtsDelete = this.db.prepare('DELETE FROM l1_fts WHERE record_id = ?');
             // §E 可见范围过滤的**唯一缝**。设计要点:
@@ -783,7 +784,7 @@ export class MemoryDb {
          WHERE NOT (${retiredL1Sql()})`);
         for (const r of stmt.iterate()) {
             try {
-                this.stmtL1FtsInsert.run(tokenizeForFts(String(r.content ?? '')), String(r.content ?? ''), String(r.record_id ?? ''), String(r.type ?? ''), Number(r.priority ?? 50), String(r.scene_name ?? ''), String(r.session_id ?? 'default'), Number(r.version ?? 0), String(r.timestamp_str ?? ''), String(r.timestamp_start ?? ''), String(r.timestamp_end ?? ''), String(r.metadata_json ?? '{}'), String(r.family ?? 'chat'), 
+                this.stmtL1FtsInsert.run(tokenizeForFts(ftsKeywordText(parseMetadataJson(String(r.metadata_json ?? '{}')))), tokenizeForFts(String(r.content ?? '')), String(r.content ?? ''), String(r.record_id ?? ''), String(r.type ?? ''), Number(r.priority ?? 50), String(r.scene_name ?? ''), String(r.session_id ?? 'default'), Number(r.version ?? 0), String(r.timestamp_str ?? ''), String(r.timestamp_start ?? ''), String(r.timestamp_end ?? ''), String(r.metadata_json ?? '{}'), String(r.family ?? 'chat'), 
                 // §E:回灌必须带上可见范围——漏掉这两列等于**每次 FTS 重建都把隔离抹平**
                 // (所有行回落 'global',跨工作区记忆瞬间互相可见),且没有任何报错。
                 normScope(r.scope), String(r.workspace_id ?? ''));
@@ -1011,7 +1012,7 @@ export class MemoryDb {
             if (ftsExisted || retiredNow)
                 this.stmtL1FtsDelete.run(record.id);
             if (!retiredNow) {
-                this.stmtL1FtsInsert.run(tokenizeForFts(record.content), record.content, record.id, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), family, scope, workspaceId);
+                this.stmtL1FtsInsert.run(tokenizeForFts(ftsKeywordText(record.metadata)), tokenizeForFts(record.content), record.content, record.id, type, priority, sceneName, record.sessionId ?? 'default', record.version ?? 0, ts.str, ts.start, ts.end, JSON.stringify(record.metadata ?? {}), family, scope, workspaceId);
             }
         }
     }
@@ -1508,6 +1509,39 @@ export class MemoryDb {
             return false;
         }
     }
+    /**
+     * 更新 metadata_json 后**顺带重索引该行的 `l1_fts`**（关键词回填专用）。
+     *
+     * `patchL1Metadata` 本身不碰 fts——多数写回点（tags / room / relabel）不需要、也不想付这个代价；
+     * 但关键词轴若只写元数据不重索引，`ftsKeywordText` 读不到新 `dsh_keywords`，那条 BM25 轴
+     * 对存量记录永远空。故把「写元数据 + 重索引」焊在一个方法里，杜绝“写了关键词但检索看不到”。
+     *
+     * 退场/不存在的行：只从 fts 删除（幂等），不插入。fts 不可用时降级为纯 `patchL1Metadata`。
+     * 参数列表与 `stmtL1FtsInsert` / `backfillL1Fts` 逐位对齐（同三处列清单，漏一列静默丢索引）。
+     */
+    patchL1MetadataAndReindex(id, metadata) {
+        const ok = this.patchL1Metadata(id, metadata);
+        if (!ok || this.degraded || !this.ftsAvailable)
+            return ok;
+        try {
+            const r = this.db
+                .prepare(`SELECT record_id, content, type, priority, scene_name, session_id, version,
+                  timestamp_str, timestamp_start, timestamp_end, metadata_json, family,
+                  scope, workspace_id FROM l1_records
+           WHERE record_id = ? AND NOT (${retiredL1Sql()})`)
+                .get(id);
+            // 退场/缺失行：只确保从 fts 剔除（幂等），不插入；活跃行：删旧行再按当前（含新关键词）元数据重插。
+            this.stmtL1FtsDelete.run(id);
+            if (r) {
+                this.stmtL1FtsInsert.run(tokenizeForFts(ftsKeywordText(parseMetadataJson(String(r.metadata_json ?? '{}')))), tokenizeForFts(String(r.content ?? '')), String(r.content ?? ''), String(r.record_id ?? ''), String(r.type ?? ''), Number(r.priority ?? 50), String(r.scene_name ?? ''), String(r.session_id ?? 'default'), Number(r.version ?? 0), String(r.timestamp_str ?? ''), String(r.timestamp_start ?? ''), String(r.timestamp_end ?? ''), String(r.metadata_json ?? '{}'), String(r.family ?? 'chat'), normScope(r.scope), String(r.workspace_id ?? ''));
+            }
+        }
+        catch (err) {
+            // 重索引失败不回滚元数据写（关键词已落主表）；下次全量 FTS 重建会对齐，并留痕。
+            this.logger?.warn(`${TAG} 关键词重索引失败(id=${id}，元数据已写、fts 待重建对齐): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return ok;
+    }
     /** 全量读取(调试/迁移/重嵌入用;检索请走 FTS/向量)。 */
     getAllL1() {
         if (this.degraded)
@@ -2598,6 +2632,23 @@ export class MemoryDb {
         }
     }
 }
+/**
+ * 关键词轴的索引文本（保留字段 `metadata.dsh_keywords`）。
+ *
+ * 为什么是**独立列**而不是并进 `content`：关键词是一条**独立的检索轴**——它要么
+ * 精确命中、要么不命中，与正文里的 BM25 词频不是一回事（并进正文等于让关键词的
+ * 权重被正文长度稀释）。`l1_fts` 因此排成「keywords → content」两列索引：将来
+ * 关键词蒸馏上线时**先命中关键词轴、再回落到全文**，无需再改表结构（FTS5 不能 ALTER）。
+ *
+ * 目前无产出方（抽取/命名尚未产出该键）⇒ 恒为空串：空串不产生任何 token，
+ * 索引与改动前逐字相同（零漂移），所以先接线、后接产线是安全的。
+ */
+function ftsKeywordText(metadata) {
+    const kw = Array.isArray(metadata?.dsh_keywords)
+        ? metadata.dsh_keywords.filter((k) => typeof k === 'string' && k.trim() !== '')
+        : [];
+    return kw.join('\n');
+}
 /** 容忍坏 JSON 的 metadata 解析(与 rowToRecord 同口径:解析失败退化为空对象,不抛)。 */
 function parseMetadataJson(raw) {
     try {

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-prime-memory",
   "name": "dsh-prime-memory",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": {
     "en": "Layered distilled memory plugin (L0 capture → L1 atomic memory → L2 scenes → L3 persona) with automatic recall injection before each model step.",
     "zh": "L0~L3 分层蒸馏记忆插件:自动捕获对话、抽取原子记忆、整合场景块、蒸馏核心画像,并在模型步骤前自动召回注入。"