dsh-prime-memory 0.24.2 → 0.26.0

package/dist/config.d.ts

@@ -123,12 +123,31 @@ export interface MemoryConfig {
         /** active 技能闲置多少天后自动归档（0 = 不做闲置归档）。 */
         idleArchiveDays: number;
     };
-    /** wing 存量回填护栏（默认 300 条/120s；想一次多跑点可调大，代价是后台占用更久）。 */
+    /**
+     * 存量回填护栏（wing / keyword / redistill 共用，默认 300 条 / 30min 总预算 / 串行 / 单条请求 240s）。
+     *
+     * 形状约定（用户定）：**按单元、串行、不合并**——一个请求只装一条记忆，跑完一条再发下一条。
+     * 实测单条 35B 只要 ~2.6s，而 20 条合并成一批要 200s+ 且一次空输出/截断就带走整批，
+     * 所以“批量”在这里不省时间只堆风险。`concurrency` 默认 1；拖高概览页滑块可临时多路在飞。
+     *
+     * 三个旋钮分工（别混淆）：
+     * - `maxRecords` = **一轮最多处理多少条**（防一次点击拖过久；真实队列没跑完的计入 deferred，
+     *   再点一次继续）。注意它**不是**请求批大小：逐条形状下每个请求只装 1 条。
+     * - `timeBudgetMs` = **本轮总墙钟预算**（防跑飞）。与 maxRecords 谁先到谁生效：
+     *   默认 300 条 × ~2.6s ≈ 13min < 30min，正常由 maxRecords 先结算。
+     * - `callTimeoutMs` = **一次 `callLLM`（含整条回退链）**的超时。不能沿用 `llm.timeoutMs`（120s）：
+     *   它是**整次调用**的预算而非每条路由各享一份——真机踩到主路由（9B）空输出吃 95s，
+     *   降到 35B 后只剩余量在线上被掐死（看似“35B 也跑不完”）。默认 240s 按「路由数 × 单路由耗时」留余量。
+     */
     backfill: {
         /** 单次回填处理条数上限。 */
         maxRecords: number;
-        /** 单次回填墙钟预算(ms)，超时剩留待再次触发。 */
+        /** 单次回填总墙钟预算(ms)，超时剩留待再次触发。 */
         timeBudgetMs: number;
+        /** LLM 批调用的并行度(1 = 串行)。 */
+        concurrency: number;
+        /** 一次 LLM 调用（含整条回退链）的超时(ms)，比对话蒸馏的 llm.timeoutMs 宽；按路由数留余量。 */
+        callTimeoutMs: number;
     };
     /**
      * 内容路由（workspace 归属）：按「这条记忆**谈到**哪个项目」给记录补 `workspace_id`。
@@ -193,6 +212,32 @@ export interface MemoryConfig {
     usageScenario: {
         enabled: boolean;
     };
+    /**
+     * 关键词蒸馏回填（keyword 检索轴的产出方）：**独立回填批扫**，为缺 `metadata.dsh_keywords` 的
+     * L1 记录批量补关键词，喂 `l1_fts` 的关键词轴（`ftsKeywordText` 读该键）。由
+     * `dsh-memory/keyword-backfill` 端点触发，镜像 wing 回填（单飞/后台/有界）。
+     *
+     * **默认关**：关时不回填、不产该键、`l1_fts.keywords` 列逐字不变（零漂移）。护栏复用 `backfill`。
+     * 注：写回走 `patchMetadata` 只改主表，回填会**额外重索引该记录的 fts 行**（见 keyword-backfill），
+     * 否则关键词轴对存量记录不生效。
+     */
+    keyword: {
+        enabled: boolean;
+    };
+    /**
+     * 存量记忆重蒸馏整形（redistill）：**独立回填批扫**，把活跃且 `scoreSkeleton` 判「骨架不齐备」
+     * 的 L1 正文按 G2 分类型骨架重排，并顺带产 `dsh_keywords` / `dsh_usage_scenario`。由
+     * `dsh-memory/redistill-backfill` 端点触发，镜像 keyword/wing 回填（单飞/后台/有界）。
+     *
+     * **默认关**：关时不整形、content/FTS/投射逐字不变（零漂移）。护栏复用 `backfill`。
+     * 与 keyword 回填的关键差异：本项**改 content**，写回走 `L1Store.appendNew`（追加 JSONL 事实源
+     * + 重嵌 + FTS + 投射点火），且入口要求 `vectorsReady()`（embed 未就绪时改正文会静默丢向量）。
+     * 只有整形后骨架分严格更优才写回，并盖整形版本戳（`dsh_reshape_ver`）；未过闸的留原文**不打标记**，
+     * 下轮仍可再试——即只有「成功替换的」不再进入。
+     */
+    redistill: {
+        enabled: boolean;
+    };
     /**
      * 类型叙述模板（G2）：抽取时按 7 类型各自的“前因后果”骨架写 content。
      *

package/dist/config.js

@@ -80,6 +80,22 @@ export function liveSettingsSchema() {
         conflictFreeze: Schema.boolean().default(false),
         // 轨2 技能结晶总开关(看板可拨):默认 false。开=注册 memory_skill_* 工具 + 注入 active 技能 + skills-* 端点可用。
         skillsEnabled: Schema.boolean().default(false),
+        // 存量回填/进阶功能的启用开关（概览「存量回填与整形」区可拨）：默认 false，
+        // 与部署 cfg.<x>.enabled 取或（经 effectiveCfg）——部署可强制开，live 只能追加开。
+        // 存在的理由：这些面都有对应按钮/端点，若开关只住 YAML，用户点了只会报“未开启”却没处翻。
+        keywordEnabled: Schema.boolean().default(false),
+        redistillEnabled: Schema.boolean().default(false),
+        mdSyncEnabled: Schema.boolean().default(false),
+        memportEnabled: Schema.boolean().default(false),
+        /**
+         * 存量回填（keyword / redistill）LLM 批调用的**运行时并行度**覆盖：
+         * `0` = 跟随部署 `cfg.backfill.concurrency`；1–8 = 直接覆盖。
+         *
+         * 为什么要是 live 而不是只住 YAML：真机出过“3 并发把每请求拖过超时线、13 批全 abort”，
+         * 排查时需要的恰好是“立刻降到 1 串行再看一遍”——为此改 YAML + 重启不现实。
+         * 概览页 0–8 滑块写的就是它（0 = 跟随部署，默认部署值是 1 串行）。
+         */
+        backfillConcurrency: Schema.number().min(0).max(8).default(0),
         // 工具分组封印(v0.21.0):false = 该组工具不注册,从模型工具列表消失。
         // 核心读(memory_search/read_scene/receipts/conversation_search)与槽位三件不受控。
         toolRoom: Schema.boolean().default(true),
@@ -164,10 +180,14 @@ export const memorySchema = Schema.object({
         excerptChars: Schema.number().min(0).max(4000).default(240),
         idleArchiveDays: Schema.number().min(0).max(3650).default(90),
     }),
-    // wing 回填护栏：默认与旧行为一致(300 条 / 120s)，需一次多跑点时调大。
+    // wing/keyword/redistill 回填护栏。maxRecords 是“一轮处理多少条”，timeBudgetMs 是“本轮不跑飞”，
+    // callTimeoutMs 是“单次请求（含回退链）不撞线”；逐条形状下每请求只装 1 条（不是 20 条一批）。
+    // maxRecords 不得低于真实队列量级：真机活跃集里待整形真目标 251 条，砍到 40 就等于“点一次只动 40”。
     backfill: Schema.object({
         maxRecords: Schema.number().min(1).max(10_000).default(300),
-        timeBudgetMs: Schema.number().min(1000).max(1_800_000).default(120_000),
+        timeBudgetMs: Schema.number().min(1000).max(1_800_000).default(1_800_000),
+        concurrency: Schema.number().min(1).max(8).default(1),
+        callTimeoutMs: Schema.number().min(1000).max(1_800_000).default(240_000),
     }),
     /**
      * 内容路由：默认**开**（用户口径：谈到本仓/dsh 生态的记忆要归到本仓 workspace，
@@ -226,6 +246,14 @@ 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),
+    }),
+    // 存量记忆重蒸馏整形：默认关（关时不整形、content/FTS/投射逐字不变）；护栏复用 backfill。
+    redistill: Schema.object({
+        enabled: Schema.boolean().default(false),
+    }),
     // 类型叙述模板（G2）：默认**开**；开时抽取 prompt 追加分类型 content 骨架（关时仍逐字不变）。
     // 默认值从关改开的理由写在上方接口注释：只给定义实测骨架齐备 0/23，
     // 而"没前因后果就不算可用"是用户定的判据，所以默认值要按可用性定而不是按保守定。

package/dist/contract.d.ts

@@ -106,9 +106,20 @@ export interface MemoryLiveSettings {
     /** 轨2 技能结晶总开关（看板可拨）:true = 注册 memory_skill_* 工具、注入 active 技能、skills-* 端点可用。
      *  默认 false（新功能默认关）；与部署 cfg.skills.enabled 取或（任一开则生效）。 */
     skillsEnabled: boolean;
+    /** 关键词回填启用开关（概览区可拨）:true = 放行 dsh-memory/keyword-backfill。与部署 cfg.keyword.enabled 取或。 */
+    keywordEnabled: boolean;
+    /** 重蒸馏整形启用开关（概览区可拨）:true = 放行 dsh-memory/redistill-backfill。与部署 cfg.redistill.enabled 取或。 */
+    redistillEnabled: boolean;
+    /** md 反向同步启用开关（概览区可拨）:true = 放行 md-sync 回灌。与部署 cfg.mdSync.enabled 取或。 */
+    mdSyncEnabled: boolean;
+    /** 外部记忆来源 Connect 启用开关（概览区可拨）:true = 放行 memport-* 端点。与部署 cfg.memport.enabled 取或。 */
+    memportEnabled: boolean;
     /** md 投射/后缀收敛的单次动作护栏运行时覆盖:0 = 跟随部署 `cfg.memExport.maxRecords`（默认 2000）。
      *  存在的理由：一次点完多少条属于“回填历史时才改一下”的旋钮，不该要求改 YAML + 重启。 */
     mdExportMaxRecords: number;
+    /** 存量回填（keyword/redistill）LLM 批调用的运行时并行度覆盖：0 = 跟随部署
+     *  `cfg.backfill.concurrency`（默认 2）；1–8 = 直接覆盖。概览页 1–3 滑块写的就是它。 */
+    backfillConcurrency: number;
 }
 /** 召回停用原因(session-stats recall.enabled=false 时带出;短路序第一个为假的因子)。 */
 export type RecallDisabledReason = 'deploy' | 'global' | 'session' | 'mode';
@@ -641,12 +652,69 @@ export interface RoomAdminResponse {
     /** retire withRecords 实际退场的记录条数(软删,可恢复)。 */
     retiredRecords?: number;
 }
+/**
+ * 回填端点(wing/keyword/redistill)的请求体。三者都同时是「触发器 + 状态查询」：
+ * - `probe` 缺省/false：空闲时**启动**一轮；已在跑则只回状态(单飞)。
+ * - `probe: true`：**只读快照**,绝不启动——供 UI 离开区域再回来时恢复在途任务的进度
+ *   (否则计时器随组件卸载而清,回到页面只能看到卡住的最后一帧)。
+ */
+export interface BackfillTriggerRequest {
+    probe?: boolean;
+}
 /** dsh-memory/wing-backfill(一键回填,后台任务;端点立即返回,进度以 wing-overview 轮询)。 */
 export interface WingBackfillResponse {
     /** true = 本次触发启动了新任务;false = 已有任务在跑(单飞,不叠加)。 */
     started: boolean;
     running: boolean;
 }
+/** 回填批扫的逐条进度（keyword/redistill 共用）：后台任务一轮可达几分钟，没有它 UI 只能转圈圈。 */
+export interface BackfillProgress {
+    /** 每个请求处理的条数（两个回填都已改成逐条 = 1；保留字段供未来批量形状复用）。 */
+    chunk: number;
+    /** 扫描阶段确定的**真目标**总数（扫描未完成时为已发现数）。 */
+    candidates: number;
+    /** 本次已完成（送过 LLM 且已提交结果）条数。 */
+    processed: number;
+    /** 仍在扫描阶段（此阶段报「扫描中」而不是「第 N 条」）。 */
+    scanning: boolean;
+    /** 已完成条数 / 本次要处理的总条数。 */
+    batchesDone: number;
+    batchTotal: number;
+    /** LLM 批调用并行度（cfg.backfill.concurrency）。 */
+    concurrency: number;
+    /** 预算/上限用尽未处理、留下次的条数（跟“跑完了”区分开的关键一个数）。 */
+    deferred: number;
+}
+/** dsh-memory/keyword-backfill（关键词蒸馏回填，后台任务；门控关时 enabled=false 不启动）。 */
+export interface KeywordBackfillResponse {
+    /** true = 本次触发启动了新任务；false = 已有任务在跑或门控关。 */
+    started: boolean;
+    running: boolean;
+    /** 门控 `cfg.keyword.enabled`；关时不启动，面板据此提示先开开关。 */
+    enabled: boolean;
+    /** 本进程累计成功回填条数（重启归零；观测用）。 */
+    updated: number;
+    /** 失败/跳过数。 */
+    failed: number;
+    /** 分批进度（运行期轮询显示用）。 */
+    progress: BackfillProgress;
+}
+/** dsh-memory/redistill-backfill（存量记忆重蒸馏整形，后台任务；门控关时 enabled=false 不启动）。 */
+export interface RedistillBackfillResponse {
+    /** true = 本次触发启动了新任务；false = 已有任务在跑或门控关。 */
+    started: boolean;
+    running: boolean;
+    /** 门控 `cfg.redistill.enabled`；关时不启动。 */
+    enabled: boolean;
+    /** 本进程累计整形写回条数（重启归零；观测用）。 */
+    updated: number;
+    /** 质量闸判不写（留原文）条数。 */
+    skipped: number;
+    /** 失败/跳过数（LLM 失败、id 配不上、embed 掉线）。 */
+    failed: number;
+    /** 分批进度（运行期轮询显示用）。 */
+    progress: BackfillProgress;
+}
 /** dsh-memory/session-stats(悬浮卡信息区;热路径端点)。 */
 export interface SessionStatsRequest {
     sessionId: string;
@@ -880,6 +948,38 @@ export interface UiRecord {
      */
     userRelevance?: number;
 }
+/** dsh-memory/records-meta（按 ID 批量查元数据，供 .memory.md 查看器拼接 Qoder 风格条目）。 */
+export interface RecordsMetaRequest {
+    /** L1 record_id 列表（上限 50）。 */
+    ids: string[];
+}
+/** 单条轻量元数据（含正文，供 .memory.md 查看器拼接头部条）。 */
+export interface RecordMeta {
+    id: string;
+    /** 名称蒸馏产出的短标题；无 name 时为 null。 */
+    name: string | null;
+    type: string;
+    priority: number;
+    /** 正文全文（markdown）。 */
+    content: string;
+    maturity?: 'low' | 'mid' | 'high';
+    createdAt: string | null;
+    updatedAt: string | null;
+    scene: string;
+    scope: 'global' | 'workspace';
+    workspaceId: string | null;
+    /** 关键词（metadata.dsh_keywords）。 */
+    keywords?: string[];
+    /** 使用场景（metadata.dsh_usage_scenario）。 */
+    usageScenario?: string[];
+    /** 投射文件相对路径 `<type>/<stem>.memory.md`。 */
+    filePath: string;
+    /** 是否已退场（软删）。 */
+    retired: boolean;
+}
+export interface RecordsMetaResponse {
+    items: RecordMeta[];
+}
 export interface ListRecordsResponse {
     items: UiRecord[];
     hasMore: boolean;
@@ -1649,11 +1749,14 @@ export interface DshMemoryRequestMap {
     'dsh-memory/rooms-export': RoomsExportRequest;
     'dsh-memory/room-register': RoomRegisterRequest;
     'dsh-memory/room-admin': RoomAdminRequest;
-    'dsh-memory/wing-backfill': Record<string, never>;
+    'dsh-memory/wing-backfill': BackfillTriggerRequest;
+    'dsh-memory/keyword-backfill': BackfillTriggerRequest;
+    'dsh-memory/redistill-backfill': BackfillTriggerRequest;
     'dsh-memory/session-stats': SessionStatsRequest;
     'dsh-memory/settings-get': Record<string, never>;
     'dsh-memory/settings-set': SettingsSetRequest;
     'dsh-memory/list-records': ListRecordsRequest;
+    'dsh-memory/records-meta': RecordsMetaRequest;
     'dsh-memory/records-delete': RecordsDeleteRequest;
     'dsh-memory/receipts': ReceiptsRequest;
     'dsh-memory/conflicts': ConflictsRequest;
@@ -1712,10 +1815,13 @@ 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/redistill-backfill': RedistillBackfillResponse;
     'dsh-memory/session-stats': SessionStatsResponse;
     'dsh-memory/settings-get': SettingsGetResponse;
     'dsh-memory/settings-set': SettingsSetResponse;
     'dsh-memory/list-records': ListRecordsResponse;
+    'dsh-memory/records-meta': RecordsMetaResponse;
     'dsh-memory/records-delete': RecordsDeleteResponse;
     'dsh-memory/receipts': ReceiptsResponse;
     'dsh-memory/conflicts': ConflictsResponse;

package/dist/keyword-backfill.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 关键词蒸馏回填（keyword axis 产出方）。
+ *
+ * 职责：从 L1 记录中找「缺 dsh_keywords」的存量记录，**一条一个请求**送 LLM 提炼关键词
+ * 与使用场景，归一后写 `metadata.dsh_keywords` + `metadata.dsh_usage_scenario`，
+ * 并用 `patchMetadataAndReindex` 保证新关键词**立即进 FTS BM25 轴**。
+ *
+ * 安全边界（继承 wing-backfill）：
+ * - 单飞：同时最多一个回填任务,重复触发直接返回 running(不排队不叠加)
+ * - 后台执行：端点立即返回,**逐条推进、跑完一条再发下一条**,不阻塞 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;
+    /**
+     * 运行时**生效并发**读取器（可选）：给正在跑的任务即时改并发用——池子每完成一条重读一次。
+     * 缺省 = 启动时读一次 `cfg.backfill.concurrency`（旧行为）。
+     */
+    concurrency?: () => number | undefined;
+}
+export interface KeywordBackfillState {
+    running: boolean;
+    updated: number;
+    failed: number;
+    /** 分批进度（UI 轮询据此显示「扫描中 / 第几条」，否则运行期只有一个「回填中…」）： */
+    /** 每个请求处理的条数——已改逐条，永远为 1（与 redistill 同形状）。 */
+    chunk: number;
+    /** 扫描阶段确定的真目标总数（缺关键词；扫描未完成时为已发现数）。 */
+    candidates: number;
+    /** 本次已完成（送过 LLM 且已写回）**在请求完成时才自增**，否则“全失败”跟“全成功”看起来一样。 */
+    processed: number;
+    /** 仍在扫描阶段。 */
+    scanning: boolean;
+    /** 已完成条数（与 processed 同值）。 */
+    batchesDone: number;
+    /** 本次要处理的总条数。 */
+    batchTotal: number;
+    /** LLM 批调用并行度。 */
+    concurrency: number;
+    /** 预算/上限用尽未处理、留下次的条数。 */
+    deferred: 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 interface KeywordOneResult {
+    keywords: string[];
+    usageScenario: string[];
+}
+/**
+ * 标注**一条**记忆的关键词与情景（一个请求只装一条）。失败/无合法关键词返回 null。
+ *
+ * 旧名 `labelKeywordChunk`（多条一次）已废：合并请求下一次截断/空输出就整批丢弃，
+ * 而逐条只花秒级。记账（state.failed 等）全部归调用方——标注器不再动全局状态，
+ * 否则同一条会被两处各计一次。
+ */
+export declare function labelKeywordOne(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, rec: MemoryRecord, callTimeoutMs?: number): Promise<KeywordOneResult | null>;

package/dist/keyword-backfill.js

@@ -0,0 +1,218 @@
+import { callLLM, parseJsonLogged } from './llm.js';
+import { normKeywords, normUsageScenario, KEYWORDS_METADATA_KEY } from './metadata-validators.js';
+import { yieldLoop } from './util/yield.js';
+// 一个请求只装**一条**记忆（旧形状是 20 条/次，已改）。与 redistill 同口径：
+// 合并请求把爆炸半径从 1 条放大到 20 条（一次截断/空输出就整批丢弃），而实测单条
+// 在本地端点上只是秒级，合并并不省时间。
+/** 扫描页大小（轻量投影分页；与 wing-backfill 一致）。 */
+const PAGE = 200;
+/** 单次任务默认处理上限（cfg.backfill.maxRecords 优先）。 */
+const DEFAULT_MAX_RECORDS = 40;
+/** 总墙钟默认预算（cfg.backfill.timeBudgetMs 优先）。 */
+const DEFAULT_TIME_BUDGET_MS = 1_800_000;
+/** 默认并行度（cfg.backfill.concurrency 优先）：1 = 串行逐条（用户定的形状）。 */
+const DEFAULT_CONCURRENCY = 1;
+/**
+ * 一次调用（含整条回退链）的默认超时（cfg.backfill.callTimeoutMs 优先）。
+ * 不能沿用 `llm.timeoutMs`（120s）：它是整次调用的预算而不是每条路由各享一份，
+ * 主路由空转一轮再降级就会撞线。
+ */
+const DEFAULT_CALL_TIMEOUT_MS = 240_000;
+/** 单条关键词标注的输出预算（5 关键词 + 3 情景，实测远低于此）。 */
+const LABEL_MAX_TOKENS = 512;
+/** 并发度钳位（与 schema 的 min1/max8 同口径）。 */
+function clampConcurrency(raw) {
+    const n = typeof raw === 'number' && Number.isFinite(raw) ? Math.round(raw) : DEFAULT_CONCURRENCY;
+    return Math.min(8, Math.max(1, n));
+}
+const state = {
+    running: false, updated: 0, failed: 0,
+    chunk: 1, candidates: 0, processed: 0,
+    scanning: false, batchesDone: 0, batchTotal: 0, concurrency: DEFAULT_CONCURRENCY, deferred: 0,
+};
+export function keywordBackfillState() {
+    return { ...state };
+}
+// ── SYSTEM 提示词（定稿版，由 tools/keyword-distill.prompt.md 的 ```text 块迁移） ──
+const SYSTEM_PROMPT = [
+    '你是记忆库的关键词与情景标注器。给定**一条**记忆（含标题与正文），为它提炼：',
+    '1) keywords：最能代表该记忆的检索词，用于精确命中；2) usage_scenario：未来「何时应当浮现这条记忆」的场景短语。',
+    '',
+    '严格规则：',
+    '- keywords 的唯一判据：**用户未来会输入什么词把这条记忆捞出来**。优先具体名词性标识——项目/模块/文件/函数/配置项/命令/错误码/版本号/数字阈值/工具名/专有实体名。',
+    '- **禁止**把正文里的动宾短语压缩成抽象黑话当关键词（反例：把"判定批量流量"压成"批量流量判定"、把"做窗口滑动归因"压成"窗口滑动归因"、把"保持只读约束"压成"只读约束"）——这类词没人会拿去搜，一律换成它指向的具体实体/标识，或直接删掉。',
+    '- keywords：2–5 个（宁少勿滥，够区分即可）；每个 2–6 词或 1 个复合术语；不得与标题字面重复、不得互相近义堆叠、不收停用词/整句。',
+    '- usage_scenario：1–3 条；每条 5–10 词的短场景描述（不是完整命令句）；彼此必须可区分，相似的合并成更泛化的一条。',
+    '- 语言跟随该记忆正文：中文记忆产出中文（技术标识符、API 名、错误码原样保留），英文记忆产出英文。',
+    '',
+    '输出：只输出**一个 JSON 对象**（不是数组），不要多余文字、不要解释。形如：',
+    '{"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;
+    state.candidates = 0;
+    state.processed = 0;
+    state.scanning = true;
+    state.batchesDone = 0;
+    state.batchTotal = 0;
+    state.deferred = 0;
+    state.concurrency = clampConcurrency(deps.cfg.backfill?.concurrency);
+    void runKeywordBackfillOnce(deps).finally(() => {
+        state.running = false;
+        state.scanning = false;
+        deps.logger.info(`[memory] keyword 回填结束:成功 ${state.updated} 条,失败 ${state.failed} 条`
+            + (state.deferred > 0 ? `,留待下次 ${state.deferred} 条` : ''));
+    });
+    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 LIMIT = clampConcurrency(cfg.backfill?.concurrency);
+    state.concurrency = LIMIT;
+    const startedAt = Date.now();
+    // ── 扫描阶段（轻量投影，不反序列化正文；分页 + 每页让位，不设墙钟）──
+    const total = await backend.size();
+    const pendingIds = [];
+    let scanned = 0;
+    state.scanning = true;
+    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;
+        state.candidates = pendingIds.length;
+        await yieldLoop();
+    }
+    state.scanning = false;
+    const batch = pendingIds.slice(0, MAX_RECORDS);
+    state.candidates = batch.length;
+    state.batchTotal = batch.length;
+    state.deferred = Math.max(0, pendingIds.length - batch.length);
+    const callTimeoutMs = cfg.backfill?.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+    logger.info(`[memory] keyword 回填启动：已扫 ${scanned}/${total} 行,缺关键词 ${pendingIds.length} 条,本次处理 ${batch.length} 条,并行度 ${LIMIT}`);
+    /** 一条一个请求：取一条 → 标注 → **即时写回**（含 fts 重索引）。 */
+    const labelAndCommit = async (id) => {
+        const [rec] = await backend.getByIds([id]);
+        if (!rec || !rec.content || rec.content.trim() === '') {
+            state.processed++;
+            state.batchesDone++;
+            return;
+        }
+        const labeled = await labelKeywordOne(deps.ctx, cfg, logger, rec, callTimeoutMs);
+        if (!labeled) {
+            state.failed++;
+        }
+        else {
+            const meta = { ...(rec.metadata ?? {}) };
+            meta[KEYWORDS_METADATA_KEY] = labeled.keywords;
+            if (labeled.usageScenario.length > 0)
+                meta.dsh_usage_scenario = labeled.usageScenario;
+            if (await backend.patchMetadataAndReindex(rec.id, meta))
+                state.updated++;
+            else
+                state.failed++;
+        }
+        // 完成才计数（同 redistill）：否则“全失败”在面板上跟“全成功”长得一样。
+        state.processed++;
+        state.batchesDone++;
+        await yieldLoop();
+    };
+    /**
+     * 弹性工作池（与 redistill 同构）：每完成一条重读一次**生效并发**，拖概览页滑块即时生效。
+     * 拖高立刻补 worker；拖低则各自干完手头那条后自然收工。缺省 getter = 启动值。
+     * 预算只在**条前**检查，中途不挖已烧 token 的那条。
+     */
+    const readLimit = () => {
+        const raw = deps.concurrency ? deps.concurrency() : undefined;
+        return clampConcurrency(raw ?? cfg.backfill?.concurrency);
+    };
+    let cursor = 0;
+    let budgetHit = false;
+    const work = async () => {
+        for (;;) {
+            if (budgetHit || Date.now() - startedAt > TIME_BUDGET_MS) {
+                budgetHit = true;
+                return;
+            }
+            const i = cursor++;
+            if (i >= batch.length)
+                return;
+            await labelAndCommit(batch[i]);
+        }
+    };
+    const inFlight = new Set();
+    const spawn = () => {
+        const p = work().finally(() => inFlight.delete(p));
+        inFlight.add(p);
+    };
+    for (;;) {
+        const target = Math.max(1, Math.min(readLimit(), batch.length));
+        state.concurrency = target; // 面板「并行 N」跟实时值走
+        while (!budgetHit && inFlight.size < target && cursor < batch.length)
+            spawn();
+        if (inFlight.size === 0)
+            break;
+        await Promise.race(inFlight);
+    }
+    if (budgetHit) {
+        state.deferred += Math.max(0, batch.length - state.processed);
+        logger.info(`[memory] keyword 回填：墙钟预算(${Math.round(TIME_BUDGET_MS / 1000)}s)用尽,累计留待再触发 ${state.deferred} 条`);
+    }
+}
+/**
+ * 标注**一条**记忆的关键词与情景（一个请求只装一条）。失败/无合法关键词返回 null。
+ *
+ * 旧名 `labelKeywordChunk`（多条一次）已废：合并请求下一次截断/空输出就整批丢弃，
+ * 而逐条只花秒级。记账（state.failed 等）全部归调用方——标注器不再动全局状态，
+ * 否则同一条会被两处各计一次。
+ */
+export async function labelKeywordOne(ctx, cfg, logger, rec, callTimeoutMs = DEFAULT_CALL_TIMEOUT_MS) {
+    const user = `记忆:\n标题：${rec.name ?? ''}\n正文：${rec.content.slice(0, 900)}`;
+    const t0 = Date.now();
+    const secs = () => Math.round((Date.now() - t0) / 10);
+    try {
+        const raw = await callLLM(ctx, cfg, {
+            system: SYSTEM_PROMPT,
+            user,
+            maxTokens: LABEL_MAX_TOKENS,
+            layer: 'l1-extract',
+            logger,
+            signal: AbortSignal.timeout(callTimeoutMs > 0 ? callTimeoutMs : DEFAULT_CALL_TIMEOUT_MS),
+        });
+        logger.debug?.(`[memory] keyword 单条耗时 ${(Date.now() - t0) / 1000}s(id=${rec.id})`);
+        const parsed = parseJsonLogged(raw, 'keyword 回填', logger);
+        const obj = Array.isArray(parsed) ? parsed[0] : parsed;
+        if (!obj || typeof obj !== 'object')
+            return null;
+        const keywords = normKeywords(obj.keywords, 5);
+        if (keywords.length === 0) {
+            logger.warn(`[memory] keyword 回填:normKeywords 结果为空,已跳过(id=${rec.id})`);
+            return null;
+        }
+        return { keywords, usageScenario: normUsageScenario(obj.usage_scenario, 3) };
+    }
+    catch (err) {
+        logger.warn(`[memory] keyword 单条失败(id=${rec.id},已等 ${secs() / 10}s,原记录未改): ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}

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。