dsh-prime-memory 0.26.10 → 0.26.11

package/dist/pipeline/rebuild.js

@@ -26,29 +26,9 @@ import { runSceneConsolidation } from './l2.js';
 import { runPersona } from './l3.js';
 import { describePlan, gateClear, planPreserve, readFactSource, restorePreserved } from './rebuild-preserve.js';
 import { effectiveCfg } from './runner.js';
-export function groupL0Sessions(records) {
-    const bySession = new Map();
-    for (const r of records) {
-        if (!r || typeof r.id !== 'string' || typeof r.content !== 'string')
-            continue;
-        if (r.role !== 'user' && r.role !== 'assistant')
-            continue;
-        if (!r.content.trim())
-            continue;
-        const key = r.sessionId || 'default';
-        const arr = bySession.get(key) ?? [];
-        arr.push({ id: r.id, role: r.role, content: r.content, timestamp: r.timestamp ?? 0 });
-        bySession.set(key, arr);
-    }
-    const chunks = [];
-    for (const [sessionId, messages] of bySession) {
-        messages.sort((a, b) => a.timestamp - b.timestamp);
-        chunks.push({ sessionId, messages });
-    }
-    // 会话按首条消息时间升序:情境链按时间顺序衔接(与原始发生顺序一致)
-    chunks.sort((a, b) => a.messages[0].timestamp - b.messages[0].timestamp);
-    return chunks;
-}
+import { DrscFactSource, LocalL0FactSource, } from './fact-source.js';
+export { DrscFactSource, groupL0Sessions, LocalL0FactSource } from './fact-source.js';
+// `RebuildChunk` 与 `groupL0Sessions` 已迁到 pipeline/fact-source.ts（上面已转出）。
 /** 抽取调用数下界估算(与 l1.ts 的 perChunk 同式;会话数与字符预算取大)。 */
 export function estimateCalls(sessions, messages, chars, maxInputChars) {
     if (messages === 0)
@@ -56,6 +36,15 @@ export function estimateCalls(sessions, messages, chars, maxInputChars) {
     const perChunk = Math.max(20_000, maxInputChars - 42_000);
     return Math.max(sessions, Math.ceil((chars + 64 * messages) / perChunk));
 }
+/**
+ * 水位落差**提示**阀值：检索库里晚于 L0 水位的占比超过此值，就要求二次确认。
+ *
+ * 为什么叫“提示阀值”而不是“拒绝阀值”：L0 写停后这个比例只会单调上升，
+ * 拿它做硬门槛等于把重建**永久锁死**（issue #14 原提案的致命缺陷）。
+ * 所以它只负责“提醒你正在做什么”，放行靠 `force`；真正的**不丢**由
+ * `planPreserve` 的集合判据（`post-watermark`）结构性保证。
+ */
+export const STALE_RATIO_THRESHOLD = 0.5;
 function idleStatus() {
     return {
         running: false,
@@ -72,6 +61,9 @@ function idleStatus() {
         error: null,
         archiveNote: null,
         preserveNote: null,
+        rederivableCount: null,
+        preserveCount: null,
+        factWatermark: null,
     };
 }
 /** 时间戳后缀(归档命名,秒级防撞)。 */
@@ -88,7 +80,11 @@ export class RebuildController {
     logger;
     live;
     status = idleStatus();
-    chunks = [];
+    /**
+     * 会话级事实源迭代器（issue #14-B）：不再把全量 L0 正文驻留内存。
+     * null = 尚未进入蒸馏 / 已收尾。
+     */
+    chunkIter = null;
     cancelRequested = false;
     /** 快照时刻(收尾时按它区分重建产物与重建后新对话的记录)。 */
     rebuildStartMs = 0;
@@ -101,32 +97,88 @@ export class RebuildController {
         this.logger = logger;
         this.live = live;
     }
-    /** 状态快照(idle 时附带实时 L0 预估,供确认弹窗显示成本)。 */
+    /** 状态快照(idle 时附带实时预估与事实源水位,供确认弹窗讲清"会发生什么")。 */
     getStatus() {
         if (this.status.phase === 'idle') {
-            const est = this.db.l0RebuildEstimate();
-            return {
-                ...this.status,
-                sessionCount: est.sessions,
-                messageCount: est.messages,
-                estCalls: estimateCalls(est.sessions, est.messages, est.chars, effectiveCfg(this.cfg, this.live).llm.maxInputChars),
-            };
+            try {
+                const provider = this.provider();
+                const est = provider.estimate();
+                const cov = provider.coverage();
+                return {
+                    ...this.status,
+                    sessionCount: est.sessions,
+                    messageCount: est.messages,
+                    estCalls: estimateCalls(est.sessions, est.messages, est.chars, effectiveCfg(this.cfg, this.live).llm.maxInputChars),
+                    factWatermark: cov.untilIso,
+                };
+            }
+            catch {
+                // 事实源未就绪（如选了 drsc 但 collector 未装配）：面板不能因此整块挂，
+                // 只把水位置空；真正的错误留给 start() 显式报。
+                return { ...this.status, factWatermark: null };
+            }
         }
         return { ...this.status };
     }
-    /** 内存中尚未处理的会话快照块数(收尾后应为 0——快照即弃,诊断/冒烟用)。 */
+    /** 尚未处理的会话块数（流式下为估算 `total - done`；未运行时为 0，诊断/冒烟用）。 */
     get chunkCount() {
-        return this.chunks.length;
+        return this.status.running ? Math.max(0, this.status.total - this.status.done) : 0;
     }
-    /** 启动重建(校验后入队准备任务;真正的清库/归档在管线队列里串行执行,避开并发竞态)。 */
-    start() {
+    /**
+     * 按 `cfg.rebuild.factSource` 选事实源（issue #14-B）。
+     *
+     * 选 drsc 但客户端未装配时**显式抛错**，不静默回退本地表 —— “以为用了新源其实还是旧表”
+     * 会让用户拿重建结果去判断 DRSC 数据是否完整，那是最坏的误判。
+     */
+    provider() {
+        if (this.cfg.rebuild?.factSource === 'drsc') {
+            const drsc = this.stores.drsc;
+            if (!drsc) {
+                throw new Error('重建事实源配置为 drsc，但 collector 客户端未装配 —— 已中止且**未动任何数据**。'
+                    + '请先启用 reference-session-collector，或把 rebuild.factSource 改回 local。');
+            }
+            return new DrscFactSource(drsc, this.logger);
+        }
+        return new LocalL0FactSource(this.db, this.logger);
+    }
+    /**
+     * 启动重建(校验后入队准备任务;真正的清库/归档在管线队列里串行执行,避开并发竞态)。
+     *
+     * `force` 只用于跨过**提示门槛**（水位落差超过 `STALE_RATIO_THRESHOLD` 时的二次确认），
+     * 不能跨过唯一那条硬拒：「L0 一条消息都没有、检索库却有记录」—— 那种形状下重建
+     * 只会清空、一条也重造不出来，属于纯亏。
+     */
+    start(force = false) {
         if (this.status.running)
             throw new Error('重建已在进行中');
-        const est = this.db.l0RebuildEstimate();
-        if (est.messages === 0)
+        // drsc 但客户端未装配 → provider() 在这里显式抛（未动任何数据）
+        const provider = this.provider();
+        const est = provider.estimate();
+        const wm = this.db.rebuildWatermark();
+        // 同步门只对“能同步报数”的事实源成立（本地 L0）。DRSC 要发请求才知道会话数，
+        // known=false 时必须跳过 —— 否则会把“未知”当成“空”直接拒掉。
+        if (est.known && est.messages === 0) {
+            if (wm.l1Total > 0) {
+                throw new Error(`本地 L0 一条消息都没有,而检索库有 ${wm.l1Total} 条记忆 ——`
+                    + 'L0 正文自 T8.4 起已停写,用它重建只会清空检索库、一条也重造不出来。'
+                    + '已中止重建且**未动任何数据**。若确实需要以其他事实源重建,请先把该事实源接上后重试。');
+            }
             throw new Error('L0 无任何消息,无需重建');
+        }
+        // 水位落差**只做提示**:L0 停写后这个比例会单调上升，硬拒等于永久锁死重建。
+        // 真正的“不丢”由 planPreserve 的集合判据结构性保证，这里只负责让用户看清楚。
+        if (est.known && !force && wm.l1Total > 0) {
+            const ratio = wm.l1After / wm.l1Total;
+            if (ratio > STALE_RATIO_THRESHOLD) {
+                const pct = Math.round(ratio * 100);
+                throw new Error(`检索库有 ${wm.l1Total} 条记忆，其中 ${wm.l1After} 条(${pct}%)晚于本地 L0 水位`
+                    + `${wm.l0Iso ? ` ${wm.l0Iso}` : '(L0 为空)'} —— 这些记忆的原材料已不在本次快照里，`
+                    + '重建会把它们**原样保留但不再重蒸馏**(不会丢，只是不重造)。'
+                    + '确认要继续请带 force 重试。');
+            }
+        }
         this.cancelRequested = false;
-        this.chunks = [];
+        this.chunkIter = null;
         this.status = {
             ...idleStatus(),
             running: true,
@@ -135,9 +187,12 @@ export class RebuildController {
             messageCount: est.messages,
             estCalls: estimateCalls(est.sessions, est.messages, est.chars, effectiveCfg(this.cfg, this.live).llm.maxInputChars),
             startedAt: Date.now(),
+            factWatermark: provider.coverage().untilIso,
         };
         this.runner.enqueueRebuildTask(() => this.prepare());
-        this.logger.info(`[memory] 重建开始:${est.sessions} 个会话 / ${est.messages} 条 L0 消息(预计 ≥${this.status.estCalls} 次抽取调用)`);
+        this.logger.info(`[memory] 重建开始:${est.sessions} 个会话 / ${est.messages} 条 L0 消息`
+            + `(预计 ≥${this.status.estCalls} 次抽取调用;事实源水位 ${wm.l0Iso ?? '空'};`
+            + `检索库 ${wm.l1Total} 条,其中晚于水位 ${wm.l1After} 条)`);
         return { ...this.status };
     }
     /** 请求取消:当前块完成后停止,已重建部分保留并照常收尾 L2/L3。 */
@@ -151,18 +206,28 @@ export class RebuildController {
     }
     async prepare() {
         try {
-            // 快照:从检索库读全量 L0(事务一致;重建期间新捕获的消息走正常轮次,天然不重不漏)
+            // 事实源（issue #14-B）：默认本地 L0；drsc 需显式配置且必须有客户端。
+            const provider = this.provider();
+            // 快照时刻:重建期间新捕获的消息走正常轮次,天然不重不漏
             this.rebuildStartMs = Date.now();
-            this.chunks = groupL0Sessions(this.db.listL0All());
-            if (this.chunks.length === 0) {
-                this.finish('failed', 'L0 快照为空');
+            const est = await provider.prepare();
+            if (est.sessions === 0) {
+                this.finish('failed', `事实源(${provider.kind})为空，无可重建内容`);
                 return;
             }
-            this.status.total = this.chunks.length;
+            this.status.total = est.sessions;
+            if (est.messages > 0)
+                this.status.messageCount = est.messages;
+            // 本次事实源的**消息 id 集**：判"来源是否还在快照里"的唯一依据。
+            // 不取时间:时间差对停写的 L0 会永久走扩（详见 rebuild-preserve 的 post-watermark）。
+            // 注意这里**不读正文**：2.5 万条 id 约 1.5MB，而全量正文是 88MB。
+            const snapshotIds = await provider.snapshotIds();
             const dataDir = resolveDataDir(this.cfg);
             // ── ① 读事实源 + 判定保留集(必须在 archiveDerived 之前:归档会把 records/ 搬走)──
             const factRead = await readFactSource(path.join(dataDir, 'records'));
-            const plan = planPreserve(factRead.records, this.stores.l1.all());
+            const plan = planPreserve(factRead.records, this.stores.l1.all(), { snapshotIds });
+            this.status.rederivableCount = plan.rederivable;
+            this.status.preserveCount = plan.preserved.length;
             // ── ② 过闸门:判不出该保留什么时**拒绝清空**(见 rebuild-preserve.ts 文件头)──
             const gate = gateClear(factRead, plan);
             if (!gate.allowed) {
@@ -197,26 +262,53 @@ export class RebuildController {
                 this.stores.persona.work.init(),
             ]);
             this.status.phase = 'distilling';
-            this.logger.info(`[memory] 重建准备完成(归档:${archiveNote ?? '无旧产物'},保留:${this.status.preserveNote},${this.chunks.length} 个会话块)`);
-            this.scheduleChunk(0);
+            this.logger.info(`[memory] 重建准备完成(归档:${archiveNote ?? '无旧产物'},保留:${this.status.preserveNote},${est.sessions} 个会话块,事实源=${provider.kind})`);
+            this.chunkIter = provider.chunks()[Symbol.asyncIterator]();
+            this.scheduleNext();
         }
         catch (err) {
             this.finish('failed', `准备阶段失败: ${errDetail(err)}`);
         }
     }
-    /** 分块链:一次只挂一个重建块,跑完再挂下一块——正常轮次可随时插队。 */
-    scheduleChunk(i) {
-        if (this.cancelRequested || i >= this.chunks.length) {
+    /**
+     * 分块链:一次只挂一个重建块,跑完再挂下一块——正常轮次可随时插队。
+     *
+     * 流式版（issue #14-B）：从事实源迭代器拉下一个会话，不再按下标从内存数组取。
+     * 内存峰值从"全量正文"降到"单会话"。
+     */
+    scheduleNext() {
+        if (this.cancelRequested) {
+            this.runner.enqueueRebuildTask(() => this.finalize());
+            return;
+        }
+        const iter = this.chunkIter;
+        if (!iter) {
             this.runner.enqueueRebuildTask(() => this.finalize());
             return;
         }
-        const chunk = this.chunks[i];
         this.runner.enqueueRebuildTask(async () => {
             // 入队后开跑前可能已收到取消(等待插队的正常轮次期间),直接跳到收尾
             if (this.cancelRequested) {
                 this.runner.enqueueRebuildTask(() => this.finalize());
                 return;
             }
+            let next;
+            try {
+                next = await iter.next();
+            }
+            catch (err) {
+                // 事实源中途失败**不能**当“跑完了”：那会把“只重建了一部分”报成成功，
+                // 而用户会拿这个结论去判断数据是否重新生成。
+                this.logger.error(`[memory] 重建事实源中断(已完成 ${this.status.done}/${this.status.total} 个会话): ${errDetail(err)}`);
+                this.finish('failed', `事实源读取中断: ${errDetail(err)}`);
+                return;
+            }
+            if (next.done === true) {
+                this.chunkIter = null;
+                this.runner.enqueueRebuildTask(() => this.finalize());
+                return;
+            }
+            const chunk = next.value;
             try {
                 const n = await this.runner.runRebuildTurn(chunk.sessionId, chunk.messages);
                 this.status.recordsBuilt += n;
@@ -224,8 +316,8 @@ export class RebuildController {
             catch (err) {
                 this.logger.warn(`[memory] 重建块失败(session=${chunk.sessionId},跳过继续): ${errDetail(err)}`);
             }
-            this.status.done = i + 1;
-            this.scheduleChunk(i + 1);
+            this.status.done += 1;
+            this.scheduleNext();
         });
     }
     async finalize() {
@@ -307,9 +399,13 @@ export class RebuildController {
         this.status.phase = phase;
         this.status.error = error;
         this.status.finishedAt = Date.now();
-        // 快照即弃:全量 L0 消息(可能几十 MB)在重建结束/取消/失败后必须释放,
-        // 不能滞留到下一次 start() 覆盖(宿主长跑内存只增不减)
-        this.chunks = [];
+        // 事实源释放:迭代器持有单会话内存，收尾必须断开（不能滞留到下一次 start 覆盖）。
+        // 若它实现了 `return`（异步生成器），顺手关掉，避免上游资源悬着。
+        const iter = this.chunkIter;
+        this.chunkIter = null;
+        if (iter !== null && typeof iter.return === 'function') {
+            void iter.return().catch(() => { });
+        }
         const cost = this.status.finishedAt - (this.status.startedAt ?? this.status.finishedAt);
         this.logger.info(`[memory] 重建结束(${phase}):${this.status.done}/${this.status.total} 会话,产出 ${this.status.recordsBuilt} 条记录,耗时 ${Math.round(cost / 1000)}s` +
             (error ? `,错误:${error}` : ''));

package/dist/pipeline/runner.d.ts

@@ -16,6 +16,7 @@ import { type MemoryConfig } from '../config.js';
 import type { LiveSettingsHandle } from '../settings.js';
 import type { DrscClient } from '../clients/drsc.js';
 import type { GraphStore } from '../store/graph-store.js';
+import { graphFeatureOn } from '../graph/gate.js';
 import type { L1Store } from '../store/l1.js';
 import type { PersonaStore } from '../store/persona.js';
 import type { SceneStore } from '../store/scenes.js';
@@ -73,6 +74,7 @@ export declare function pickNextTaskIndex(tasks: PipelineTask[]): number;
  *   primaryEffort;非链模式旧键对静态回退条目盖章接管(存量兼容)。
  * - 输出预算/输入预算/通道覆盖/远程嵌入覆盖:非零/非空运行时值直接注入对应子树。
  */
+export { graphFeatureOn };
 export declare function effectiveCfg(cfg: MemoryConfig, live?: LiveSettingsHandle): MemoryConfig;
 export declare class MemoryRunner {
     private readonly ctx;
@@ -192,7 +194,8 @@ export declare class MemoryRunner {
     };
     /**
      * 图谱投影泵入队判定:
-     * - 双门:部署级 cfg.graph.enabled + 运行时 live.enabled/distill,任一为假不入队;
+     * - 双门:`graphFeatureOn`（部署 cfg.graph.enabled **或** 面板 live.graphEnabled）
+     *   + 运行时 live.enabled/distill,任一为假不入队;
      * - 占位:同一时刻至多一个 graph 任务在队列(靠 graphPumpQueued 标志),永不与
      *   live 抢位(pickNextTaskIndex 保证 live > graph);
      * - 退避/attempts 封顶:由 GraphStore.claimNext 的 WHERE 过滤与 fail 转 dead 承接,

package/dist/pipeline/runner.js

@@ -3,6 +3,7 @@ import { GRAPH_PRIORITY_NEW } from '../graph/types.js';
 import { NoDistillRouteError } from '../llm.js';
 import { startValidityBackfill } from '../validity-backfill.js';
 import { drscRowToConversationMessage } from '../clients/drsc.js';
+import { graphFeatureOn } from '../graph/gate.js';
 import { trace } from '../store/trace.js';
 import { emptyPending, freshWarmup, groupPendingBySession, loadPending, PENDING_MODES, pendingPathFor, savePending, } from '../store/pending.js';
 import { errDetail } from '../util/filelog.js';
@@ -41,6 +42,8 @@ export function pickNextTaskIndex(tasks) {
  *   primaryEffort;非链模式旧键对静态回退条目盖章接管(存量兼容)。
  * - 输出预算/输入预算/通道覆盖/远程嵌入覆盖:非零/非空运行时值直接注入对应子树。
  */
+// 外部（tools / index）用的同一判据从这里取，避免两处各写一份。
+export { graphFeatureOn };
 export function effectiveCfg(cfg, live) {
     const s = live?.get();
     const eff = s?.reasoningEffort ?? '';
@@ -145,6 +148,12 @@ export function effectiveCfg(cfg, live) {
     const vtOverride = s?.validityTiering !== undefined
         ? { validity: { ...(cfg.validity ?? {}), tieringEnabled: cfg.validity?.tieringEnabled === true || s.validityTiering === true } }
         : null;
+    // 知识图谱投影(issue #16):live.graphEnabled 与部署 cfg.graph.enabled 取或。
+    // 这里**直接复用 graphFeatureOn**，而不是再手写一遍“部署开关 或 面板开关”：
+    // 判据一旦有两份，将来改一处漏一处就会出现“面板显示开、覆盖算出来却是关”类的分叉。
+    const grOverride = s?.graphEnabled !== undefined
+        ? { graph: { ...(cfg.graph ?? { enabled: false }), enabled: graphFeatureOn(cfg, live) } }
+        : null;
     // md 投射/后缀收敛的单次动作护栏运行时覆盖(0 = 跟随部署 cfg.memExport.maxRecords)。
     // 只覆盖条数护栏，不动 enabled/root——开关与根路径仍属部署配置。
     const mdx = s?.mdExportMaxRecords ?? 0;
@@ -153,7 +162,7 @@ export function effectiveCfg(cfg, live) {
     // 不动 maxRecords/timeBudgetMs/callTimeoutMs——那三个仍属部署护栏，要改得改 YAML。
     const bf = s?.backfillConcurrency ?? 0;
     const backfillOverride = bf > 0 ? { backfill: { ...(cfg.backfill ?? {}), concurrency: bf } } : null;
-    if (!override && !budgets && !maxInput && !fallbacksTakeover && !chainEffort && !chainFallbacks && !effortInject && !layerChains && !hasChannel && !embedOverride && !cfOverride && !memExportOverride && !backfillOverride && !kwOverride && !rdOverride && !mdsOverride && !mpOverride && !vtOverride)
+    if (!override && !budgets && !maxInput && !fallbacksTakeover && !chainEffort && !chainFallbacks && !effortInject && !layerChains && !hasChannel && !embedOverride && !cfOverride && !memExportOverride && !backfillOverride && !kwOverride && !rdOverride && !mdsOverride && !mpOverride && !vtOverride && !grOverride)
         return cfg;
     return {
         ...cfg,
@@ -164,6 +173,7 @@ export function effectiveCfg(cfg, live) {
         ...(mdsOverride ?? {}),
         ...(mpOverride ?? {}),
         ...(vtOverride ?? {}),
+        ...(grOverride ?? {}),
         ...(memExportOverride ?? {}),
         ...(backfillOverride ?? {}),
         llm: {
@@ -266,20 +276,22 @@ export class MemoryRunner {
         const graphs = this.stores.graph;
         if (graphs) {
             graphs.recoverRunning();
-            if (this.cfg.graph?.enabled) {
-                this.ctx.effect(() => {
-                    const timer = setTimeout(() => {
-                        if (this.stopped)
-                            return;
-                        const jobs = graphs.queueMissing(9000);
-                        if (jobs > 0) {
-                            this.logger.info(`[memory] 图谱存量补投影:${jobs} 个任务入队`);
-                            this.maybeQueueGraphTask();
-                        }
-                    }, STARTUP_RETRY_DELAY_MS);
-                    return () => clearTimeout(timer);
-                });
-            }
+            // **无条件**挂启动补跑，开关在 tick 内判：
+            // 若在这里就判门注册，面板热开启后存量要等重启才补（issue #16 的半开态）。
+            this.ctx.effect(() => {
+                const timer = setTimeout(() => {
+                    if (this.stopped)
+                        return;
+                    if (!graphFeatureOn(this.cfg, this.live))
+                        return;
+                    const jobs = graphs.queueMissing(9000);
+                    if (jobs > 0) {
+                        this.logger.info(`[memory] 图谱存量补投影:${jobs} 个任务入队`);
+                        this.maybeQueueGraphTask();
+                    }
+                }, STARTUP_RETRY_DELAY_MS);
+                return () => clearTimeout(timer);
+            });
         }
     }
     /** 启动补跑:对每个非空桶的每个会话切片入队一次蒸馏尝试(受 live 开关与
@@ -468,12 +480,28 @@ export class MemoryRunner {
      */
     startGraphBackfillTimer() {
         const graphs = this.stores.graph;
-        if (!graphs || !this.cfg.graph?.enabled)
+        // 只依赖 store 存在：**不能**在注册时判 graph 开关 —— timer 只在 init 注册一次，
+        // 那样运行时开启后存量永远补不到（issue #16 的实证半开态）。开关改在 tick 内判。
+        if (!graphs)
             return;
+        // 热开启即时补一批：否则用户拨开开关要等一个周期（30 分钟）才看到图谱动起来。
+        this.ctx.on('loader/volatile-update', (paths) => {
+            if (!paths.some((p) => p[0] === 'live'))
+                return;
+            if (!graphFeatureOn(this.cfg, this.live))
+                return;
+            const jobs = graphs.queueMissing(500);
+            if (jobs > 0) {
+                this.logger.info(`[memory] 图谱热开启补投影:${jobs} 个任务入队`);
+                this.maybeQueueGraphTask();
+            }
+        });
         this.ctx.effect(() => {
             const timer = setInterval(() => {
                 if (this.stopped)
                     return;
+                if (!graphFeatureOn(this.cfg, this.live))
+                    return;
                 const jobs = graphs.queueMissing(500);
                 if (jobs > 0) {
                     this.logger.debug?.(`[memory] 图谱周期补投影:${jobs} 个任务入队`);
@@ -522,8 +550,14 @@ export class MemoryRunner {
      * 用户后续开启由启动/周期补投影兜底(与 distill 分支同一口径)。
      */
     enqueueGraphFor(recordIds) {
-        if (recordIds.length === 0 || !this.stores.graph || !this.cfg.graph?.enabled)
+        if (recordIds.length === 0 || !this.stores.graph)
+            return;
+        if (!graphFeatureOn(this.cfg, this.live)) {
+            // 关闭期写入也要记账：`graph_projected_records` 只按 record_id+version 记账、无内容版本，
+            // 若不抹掉，重开后 queueMissing 会认为“这条已投过”而永不补 → 图谱内容永久陈旧。
+            this.stores.graph.invalidateProjected(recordIds);
             return;
+        }
         this.stores.graph.queueGraphProjection([...recordIds], GRAPH_PRIORITY_NEW);
         this.maybeQueueGraphTask();
     }
@@ -535,7 +569,9 @@ export class MemoryRunner {
      */
     reprojectGraph(recordIds) {
         const graphs = this.stores.graph;
-        if (!graphs || !this.cfg.graph?.enabled || recordIds.length === 0)
+        if (!graphs || recordIds.length === 0)
+            return { queued: 0, jobIds: [] };
+        if (!graphFeatureOn(this.cfg, this.live))
             return { queued: 0, jobIds: [] };
         const r = graphs.forceReprojectRecord(recordIds);
         if (r.queued > 0)
@@ -544,7 +580,8 @@ export class MemoryRunner {
     }
     /**
      * 图谱投影泵入队判定:
-     * - 双门:部署级 cfg.graph.enabled + 运行时 live.enabled/distill,任一为假不入队;
+     * - 双门:`graphFeatureOn`（部署 cfg.graph.enabled **或** 面板 live.graphEnabled）
+     *   + 运行时 live.enabled/distill,任一为假不入队;
      * - 占位:同一时刻至多一个 graph 任务在队列(靠 graphPumpQueued 标志),永不与
      *   live 抢位(pickNextTaskIndex 保证 live > graph);
      * - 退避/attempts 封顶:由 GraphStore.claimNext 的 WHERE 过滤与 fail 转 dead 承接,
@@ -554,7 +591,7 @@ export class MemoryRunner {
         const graphs = this.stores.graph;
         if (!graphs || this.stopped || this.graphPumpQueued)
             return;
-        if (!this.cfg.graph?.enabled)
+        if (!graphFeatureOn(this.cfg, this.live))
             return;
         const liveNow = this.live.get();
         if (!(liveNow.enabled && liveNow.distill))
@@ -663,7 +700,7 @@ export class MemoryRunner {
             if ((opts?.force || sliceLen >= effective) && !backedOff) {
                 newRecords = await this.extractSessionSlice(sessionId, mode, cfg, effective, opts);
                 // 新记录入投影队列(优先级恒高于存量补投影)并拉起图谱泵;入队本身廉价,
-                // 部署未开图谱(cfg.graph.enabled)时不入队——用户后续开启由启动补投影兜底。
+                // 开关关时由 enqueueGraphFor 抹投影凭证(避免重开后永久陈旧)，重开由补投影兜底。
                 // (写面 R2:分支本体抽成 enqueueGraphFor,与工具三路径同源,不再两处漂移。)
                 this.enqueueGraphFor(newRecords.map((r) => r.id));
             }

package/dist/pipeline/workspace-relink.js

@@ -13,8 +13,13 @@ export async function relinkWorkspaces(deps) {
     const report = {
         dryRun, scanned: 0, matched: 0, unchanged: 0, toWrite: 0, written: 0, remaining: 0, byWorkspace: {},
     };
-    if (routes.length === 0)
-        return report;
+    // 空路由表 = **未配置**（issue #13 把默认值改成 `[]`）。这里必须显式拒绕：
+    // 旧行为是返回全零报告，面板显示“扫 0 / 剩 0” —— 看起来像“已经做完了”，
+    // 真正的原因（一条路由都没配）反而看不见。
+    if (routes.length === 0) {
+        throw new Error('未配置任何内容路由规则（workspaceSource.routes 为空）：'
+            + '先在配置里写下至少一条 {path, anyOf}，再执行归属回填');
+    }
     let offset = 0;
     let batch = [];
     // 计数在此结算：`flush()` 会清空 batch，调用点再拿 `batch.length` 必然归零。

package/dist/room-review.d.ts

@@ -75,7 +75,7 @@ export interface RoomCandidate {
     id: string;
     rooms: string[];
 }
-/** 解析标注器输出的逐条候选(容错:id 配对失败丢弃;isTag 校验;目录内优先,≤3)。 */
+/** 解析标注器输出的逐条候选(容错:id 配对失败丢弃;isRoomSlug 校验(两级制);目录内优先,≤3)。 */
 export declare function parseRoomCandidateItems(parsed: ReadonlyArray<{
     id: string;
     rooms: readonly string[];

package/dist/room-review.js

@@ -1,8 +1,8 @@
-import { isTag } from './metadata-validators.js';
+import { isRoomSlug } from './metadata-validators.js';
 import { callLLM, parseJsonLogged } from './llm.js';
 export const ROOM_CANDIDATES_KEY = 'roomCandidates';
 export const ROOM_REVIEW_KEY = 'roomReview';
-/** 解析标注器输出的逐条候选(容错:id 配对失败丢弃;isTag 校验;目录内优先,≤3)。 */
+/** 解析标注器输出的逐条候选(容错:id 配对失败丢弃;isRoomSlug 校验(两级制);目录内优先,≤3)。 */
 export function parseRoomCandidateItems(parsed, ids, roomCatalog) {
     const idSet = new Set(ids);
     const catalogSet = new Set(roomCatalog.map((r) => r.room));
@@ -13,7 +13,9 @@ export function parseRoomCandidateItems(parsed, ids, roomCatalog) {
         const cleaned = [];
         for (const r of item.rooms) {
             const slug = typeof r === 'string' ? r.trim().toLowerCase() : '';
-            if (!slug || !isTag(slug))
+            // 两级制(`major` 或 `major/minor`)：与 rooms-registry 同一判据。用 isTag 会把
+            // `mpu/qos` 这类合法子类静默丢掉——注册表收得下、写回却挂不上(issue #12)。
+            if (!slug || !isRoomSlug(slug))
                 continue;
             if (!cleaned.includes(slug))
                 cleaned.push(slug);
@@ -35,7 +37,8 @@ export function roomCandidateSystemPrompt(roomCatalog) {
     return ('你是记忆库的 Room 归类器。给你一条记忆与现有 Room 词表(带计数),' +
         '为这条记忆选出它最可能归属的 1-3 个 Room slug。规则:\n' +
         '1. **优先从现有 Room 词表里选**(保持分类收敛,避免碎片化);\n' +
-        '2. 词表确实没有合适主题时,才提议最多 2 个新 slug(小写字母/数字/连字符);\n' +
+        '2. 词表确实没有合适主题时,才提议最多 2 个新 slug(小写字母/数字/连字符;' +
+        '两级制写成 `大类/子类` 形式,如 `mpu/qos`,全串至多一个斜杠);\n' +
         '3. 完全无法判断时返回空数组(宁缺毋滥,不硬猜)。\n' +
         `现有 Room 词表:\n${catalog}\n\n` +
         '输出 JSON 对象:{"rooms":["slug1","slug2"]}。只输出 JSON,不要多余文字。');
@@ -264,7 +267,9 @@ export function confirmReview(l1, id, rooms) {
         if (typeof r !== 'string')
             continue;
         const slug = r.trim().toLowerCase();
-        if (!slug || !isTag(slug) || cleaned.includes(slug))
+        // 同 parseRoomCandidateItems：走两级制判据，否则 `mpu/qos` 会被判非法、
+        // confirm 返回 null 且错误文案误导成"id 不存在"(issue #12)。
+        if (!slug || !isRoomSlug(slug) || cleaned.includes(slug))
             continue;
         cleaned.push(slug);
     }

package/dist/settings.js

@@ -82,6 +82,8 @@ const ALWAYS_ON = {
     memoryMutate: false,
     conflictFreeze: false,
     skillsEnabled: false,
+    // 知识图谱投影:默认关(部署 cfg.graph.enabled 仍可强制开;这里只做追加开)
+    graphEnabled: false,
     keywordEnabled: false,
     redistillEnabled: false,
     mdSyncEnabled: false,
@@ -329,6 +331,8 @@ function resolveSettings(value) {
         conflictFreeze: v.conflictFreeze === true,
         // 轨2 技能结晶:严格 === true(默认关,新功能默认关)
         skillsEnabled: v.skillsEnabled === true,
+        // 知识图谱投影:严格 === true(默认关);与部署 graph.enabled 取或后生效
+        graphEnabled: v.graphEnabled === true,
         // 存量回填/进阶功能启用开关:严格 === true(默认关)
         keywordEnabled: v.keywordEnabled === true,
         redistillEnabled: v.redistillEnabled === true,

package/dist/stats.js

@@ -1119,9 +1119,13 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 return v;
             }
             if (kind === 'records') {
-                const tag = String(p.tag ?? '').trim();
+                // 与 list-records 同口径(见下方 tagSel):Room slug 是自生长的两级制形状,
+                // 非法形状在这里就拒,不做“静默返回空 CSV”。
+                const tag = typeof p.tag === 'string' ? p.tag.trim().slice(0, 64) : '';
                 if (!tag)
                     throw new Error('kind=records 需要 tag(目标 Room slug)');
+                if (!isRoomSlug(tag))
+                    throw new Error('tag 非法(两级制:major 或 major/minor,各段小写字母数字连字符)');
                 const header = 'id,type,scene_name,updated_at,tags,content';
                 const lines = [header];
                 let n = 0;
@@ -1351,6 +1355,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     memoryMutate: false,
                     conflictFreeze: live?.get()?.conflictFreeze === true,
                     skillsEnabled: live?.get()?.skillsEnabled === true,
+                    graphEnabled: live?.get()?.graphEnabled === true,
                     keywordEnabled: live?.get()?.keywordEnabled === true,
                     redistillEnabled: live?.get()?.redistillEnabled === true,
                     mdSyncEnabled: live?.get()?.mdSyncEnabled === true,
@@ -1402,7 +1407,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const patch = (payload ?? {});
             const clean = {};
             // 布尔开关组:memoryMutate(高权限写删门)与主开关同列;conflictFreeze(§C 人工冲突裁决)
-            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate', 'conflictFreeze', 'skillsEnabled', 'keywordEnabled', 'redistillEnabled', 'mdSyncEnabled', 'memportEnabled', 'toolRoom', 'toolGraph', 'toolRuminate', 'toolConflict', 'toolMutate', 'toolSkills']) {
+            for (const key of ['enabled', 'capture', 'distill', 'recall', 'memoryMutate', 'conflictFreeze', 'skillsEnabled', 'graphEnabled', 'keywordEnabled', 'redistillEnabled', 'mdSyncEnabled', 'memportEnabled', 'toolRoom', 'toolGraph', 'toolRuminate', 'toolConflict', 'toolMutate', 'toolSkills']) {
                 if (typeof patch[key] === 'boolean')
                     clean[key] = patch[key];
             }
@@ -2117,7 +2122,9 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 throw new Error('蒸馏开关已关闭,请先开启蒸馏再重建');
             if (!cfg.extract.enabled)
                 throw new Error('部署配置已停用蒸馏(extract.enabled=false),无法重建');
-            const result = rebuild.start();
+            // force 只跨“水位落差”的二次确认；“L0 无正文而检索库非空”仍由 start() 硬拒。
+            const p = (payload ?? {});
+            const result = rebuild.start(p.force === true);
             deps.logger.info('[memory] 收到重建指令(设置页按钮)');
             return result;
         }