dsh-prime-memory 0.20.0-beta.2 → 0.20.0-beta.21

package/dist/index.js

@@ -36,9 +36,8 @@ import { SlotStore } from './store/slots.js';
 import { registerMemoryTools } from './tools/index.js';
 import { registerSlotTools } from './tools/slots.js';
 import { registerSlotRecall } from './hooks/slot-recall.js';
-import { registerLongTaskMonitor } from './hooks/long-task.js';
-import { ContextUsageStore } from './store/context-usage.js';
-import { TodoRefStore } from './store/todo-ref.js';
+import { RoomRegistryStore } from './store/rooms-registry.js';
+import { RecallUsageStore } from './store/recall-usage.js';
 import { registerSlotsProjection } from './projection/slots.js';
 import { errDetail, withFileLog } from './util/filelog.js';
 import { buildRouteChain, resolveModelRoute, invalidateEffortCache } from './llm.js';
@@ -161,6 +160,7 @@ export async function apply(ctx, config) {
         }
     }
     const stores = {
+        usage: undefined, // 装配于下方(依赖 dataDir 就绪)
         l0: new L0Store(dataDir, db, embed, logger),
         l1: new L1Store(dataDir, db, embed, config.recall.strategy, logger, config.recall.decayHalfLifeDays, 
         // §D 第 3 路:图谱回链。图谱不可用时 searchNodes 自带 no-op,不影响双路。
@@ -353,30 +353,23 @@ export async function apply(ctx, config) {
         backend = await createMemoryBackend({ dbPath: path.join(dataDir, 'memory.db'), dimensions: initial.dims, logger }, backend);
     }
     stores.backend = backend;
+    // Room 注册表(分类管理 beta.4;损坏降级为纯自生长目录)
+    const roomRegistry = new RoomRegistryStore(dataDir, logger);
+    await roomRegistry.init();
     const ruminate = storageOk && !db.isDegraded() && ruminateFile
-        ? new RuminateController(ctx, config, runner, stores, logger, live, ruminateFile)
+        ? new RuminateController(ctx, config, runner, stores, logger, live, ruminateFile, roomRegistry)
         : undefined;
     let flushL0;
     if (storageOk) {
         flushL0 = registerCapture(ctx, config, runner, stores.l0, logger, live, modes);
     }
-    // 长任务模式(cfg.longTask.enabled 门控,默认关):官方 usage 上下文计量 +
-    // todo/write 快照参考(仅长任务会话;写 pinned 槽位走 slot-recall 常驻注入)。
-    const contextUsage = new ContextUsageStore(logger);
-    const todoRef = new TodoRefStore();
-    if (storageOk) {
-        registerLongTaskMonitor(ctx, {
-            cfg: config,
-            modes,
-            slots: stores.slots,
-            contextUsage,
-            todoRef,
-            logger,
-        });
-    }
-    const recall = registerRecall(ctx, config, stores, logger, live, modes, dataDir);
+    // 召回使用统计(进 topN 才算 used;热路径只碰内存,去抖落盘)
+    const recallUsage = new RecallUsageStore(dataDir, logger);
+    await recallUsage.init();
+    stores.usage = recallUsage;
+    const recall = registerRecall(ctx, config, stores, logger, live, modes, dataDir, recallUsage);
     runner.setAfterRun(recall.invalidateProfile);
-    registerMemoryTools(ctx, config, stores, logger, modes, live, ruminate);
+    registerMemoryTools(ctx, config, stores, logger, modes, live, ruminate, storageOk ? roomRegistry : undefined);
     // 激活槽位(active slot):工具面 + 常驻注入 + 服务端投影(均走 ctx.effect,可撤销)
     registerSlotTools(ctx, config, stores.slots, logger, modes, live, stores.l1);
     const slotRecall = registerSlotRecall(ctx, config, stores.slots, logger, live);
@@ -395,7 +388,7 @@ export async function apply(ctx, config) {
         runnerView: (sid, mode) => runner.sessionView(sid, mode),
         l0Count: (sid) => stores.l0.countBySession(sid),
         capabilities: () => db.getCapabilities(),
-    }, ruminate, storageOk ? { runner, slots: stores.slots, contextUsage, todoRef } : undefined);
+    }, ruminate, storageOk ? roomRegistry : undefined);
     // bench 控制服务(config.benchControl 门控,默认关):仅基准/调试部署注册,
     // 供同进程的 bench-runner lifecycle 赛道触发 rebuild / 设置会话档位
     // (宿主侧 RPC 无 call(),见 bench-control.ts)

package/dist/metadata-validators.d.ts

@@ -10,6 +10,11 @@
  * 已是 string 的变量收窄成 `never`(该分支内无法再 `.slice`,已在 wing-backfill 踩过)。
  */
 export declare function isWingId(v: unknown): boolean;
+/**
+ * 两级 Room slug(`major` 或 `major/minor`,各段满足 isTag;至多一个 slash)。
+ * Room 注册表/归类写回的 tags 域;与 rooms-registry.ts 同一事实源(就近定义避免依赖环)。
+ */
+export declare function isRoomSlug(v: unknown): boolean;
 /** 同为布尔谓词(理由见 isWingId 注释)。 */
 export declare function isTag(v: unknown): boolean;
 /**

package/dist/metadata-validators.js

@@ -31,6 +31,16 @@ export function isWingId(v) {
 }
 /** 标签(Room 的构成单元)校验:小写字母数字连字符,1-32 字符。 */
 const TAG_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/**
+ * 两级 Room slug(`major` 或 `major/minor`,各段满足 isTag;至多一个 slash)。
+ * Room 注册表/归类写回的 tags 域;与 rooms-registry.ts 同一事实源(就近定义避免依赖环)。
+ */
+export function isRoomSlug(v) {
+    if (typeof v !== 'string')
+        return false;
+    const parts = v.split('/');
+    return parts.length <= 2 && parts.every((p) => TAG_RE.test(p));
+}
 /** 同为布尔谓词(理由见 isWingId 注释)。 */
 export function isTag(v) {
     return typeof v === 'string' && TAG_RE.test(v);
@@ -47,7 +57,7 @@ export function normTags(v, max = 3) {
         if (typeof raw !== 'string')
             continue;
         const t = raw.trim().toLowerCase();
-        if (!isTag(t) || out.includes(t))
+        if (!(isTag(t) || isRoomSlug(t)) || out.includes(t))
             continue;
         out.push(t);
         if (out.length >= max)

package/dist/pipeline/recluster.js

@@ -15,7 +15,7 @@ export async function processSceneReclusterJobs(source, scenes, logger, maxJobs
         const family = job.family === 'work' ? 'work' : 'chat';
         const store = scenes[family];
         // 快照在 try 外声明:catch 的回滚要用它
-        let snapshots = [];
+        const snapshots = [];
         try {
             // ① 内存快照:按场景名(文件 basename)匹配当前存在的摘要文件
             const all = await store.list();

package/dist/pipeline/ruminate.d.ts

@@ -66,6 +66,8 @@ export declare class RuminateController {
     private sessions;
     private totalL1;
     private pendingFile;
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    private readonly roomRegistry;
     /** 记忆后端:未注入时包 l1(进程内,行为与改造前等价)。 */
     private backend;
     constructor(ctx: Context, cfg: MemoryConfig, runner: Pick<MemoryRunner, 'enqueue' | 'states'>, stores: {
@@ -75,7 +77,15 @@ export declare class RuminateController {
         scenes: Record<MemoryFamily, SceneStore>;
         persona: Record<MemoryFamily, PersonaStore>;
         state: StateStore;
-    }, logger: MemoryLogger, live: LiveSettingsHandle, pendingFile: string);
+    }, logger: MemoryLogger, live: LiveSettingsHandle, pendingFile: string, 
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    roomRegistry?: {
+        listActive(): Array<{
+            slug: string;
+            label?: string;
+            description?: string;
+        }>;
+    });
     /** 状态快照 */
     getStatus(): RuminateStatus;
     /**

package/dist/pipeline/ruminate.js

@@ -4,6 +4,7 @@ import { errDetail } from '../util/filelog.js';
 import { runSceneConsolidation } from './l2.js';
 import { relabelPass } from './relabel.js';
 import { processSceneReclusterJobs } from './recluster.js';
+import { annotateOrphanCandidates } from '../room-review.js';
 import { runPersona } from './l3.js';
 const IDLE_STATUS = {
     running: false,
@@ -45,11 +46,15 @@ export class RuminateController {
     sessions = [];
     totalL1 = 0;
     pendingFile;
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    roomRegistry;
     /** 记忆后端:未注入时包 l1(进程内,行为与改造前等价)。 */
     backend() {
         return this.stores.backend ?? new InProcMemoryBackend(this.stores.l1);
     }
-    constructor(ctx, cfg, runner, stores, logger, live, pendingFile) {
+    constructor(ctx, cfg, runner, stores, logger, live, pendingFile, 
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    roomRegistry) {
         this.ctx = ctx;
         this.cfg = cfg;
         this.runner = runner;
@@ -57,6 +62,7 @@ export class RuminateController {
         this.logger = logger;
         this.live = live;
         this.pendingFile = pendingFile;
+        this.roomRegistry = roomRegistry;
     }
     /** 状态快照 */
     getStatus() {
@@ -233,6 +239,17 @@ export class RuminateController {
             catch (err) {
                 this.logger.warn(`[memory] 场景重聚类调度失败(忽略): ${errDetail(err)}`);
             }
+            // 孤儿候选预标记(长尾治理):无 Room 的活跃孤儿对照现有 Room 词表产出
+            // 候选(roomReview='pending'),由 agent 用 memory_room_review 逐个复查;
+            // 每轮至多 40 条,吞错不拖垮反刍。
+            try {
+                const r = await annotateOrphanCandidates(this.ctx, this.cfg, { l1: this.stores.l1, logger: this.logger, registry: this.roomRegistry }, 40);
+                if (r.written > 0)
+                    this.status.detail = `孤儿候选预标记 ${r.written} 条(待 agent 复查,工具 memory_room_review)`;
+            }
+            catch (err) {
+                this.logger.warn(`[memory] 孤儿候选预标记失败(忽略): ${errDetail(err)}`);
+            }
             this.status.phase = 'done';
             this.finish(null);
         }

package/dist/room-review.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 孤儿记忆的 Room 候选预标记 + agent 逐个复查(长尾治理)。
+ *
+ * 背景:Room 由 metadata.tags 自生长,但 tags 只在反刍 relabel 段随 wing 补打
+ * 顺带产出(每轮 ≤40 条、且只覆盖本轮补 wing 的记录)——「有 wing 无 tags」与
+ * 「预算用尽被 deferred」的记录成为无 Room 绑定的孤儿,且标注器不参考现有
+ * Room 词表,产出碎片化新 slug(81 个 Room 大多 1 条的成因)。
+ *
+ * 两段式:
+ *  1. **预标记(annotateOrphanCandidates)**:抽取活跃孤儿,LLM 对照**现有 Room
+ *     词表**产出候选(优先挂靠现有 Room,≤2 个新 slug 兜底),写
+ *     `metadata.roomCandidates` + `roomReview:'pending'`——不动 tags、不进
+ *     Room、不进召回,只是"待确认的建议"。
+ *  2. **逐个复查(memory_room_review 工具)**:agent 取下一条待复查记录
+ *     (带候选 + 现有 Room 词表),确认后 confirm 写入 tags(进 Room,高权限
+ *     门控),或 skip 跳过。确认/跳过都是显式动作,预标记本身零行为面。
+ *
+ * 存储即 metadata 保留键(与 relabel 写 tags 同款 patchMetadata 合并纪律,
+ * 写前重读):`roomCandidates` / `roomReview:'pending'|'confirmed'|'skipped'`。
+ * 两键不在 rooms 聚合(rooms 只读 $.tags)、不在快照哈希投影关注的治理列——
+ * 与既有 metadata 键同层,无 schema 变更。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from './config.js';
+import type { MemoryLogger, MemoryRecord } from './types.js';
+export declare const ROOM_CANDIDATES_KEY = "roomCandidates";
+export declare const ROOM_REVIEW_KEY = "roomReview";
+export type RoomReviewState = 'pending' | 'confirmed' | 'skipped';
+/** 复查与候选操作对 L1 的最小依赖面(便于测试注入)。 */
+export interface RoomReviewStore {
+    list(opts: {
+        untagged?: boolean;
+        retired?: boolean;
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    getByIds(ids: readonly string[]): MemoryRecord[];
+    patchMetadata(id: string, metadata: Record<string, unknown>): boolean;
+    listRooms(): Array<{
+        room: string;
+        count: number;
+    }>;
+    /** 确认写 tags 后失效 Room 计数缓存(30s TTL)。 */
+    invalidateRooms(): void;
+}
+/** merge/rename 的 store 面(RoomReviewStore + 游标重写与备份;L1Store 已实现)。 */
+export interface RoomMergeStore extends RoomReviewStore {
+    listByTagAll(tag: string, cap?: number): MemoryRecord[];
+    backupTagRecords(tag: string): {
+        file: string;
+        count: number;
+    };
+    rewriteTag(from: string, to: string, cap?: number): {
+        rewritten: number;
+        scanned: number;
+        families: string[];
+        scenes: string[];
+        hasMore: boolean;
+    };
+}
+/** Room 注册表最小面(merge 收尾;RoomRegistryStore 已满足)。 */
+export interface RoomRegistryMerge {
+    markMerged(fromSlug: string, toSlug: string): Promise<boolean>;
+    renameSlug(oldSlug: string, newSlug: string): Promise<boolean>;
+    /** rename 收尾恢复先前状态用(active 条目改名后不掉出标注词表)。 */
+    bySlug?(slug: string): {
+        status: 'active' | 'retired';
+    } | undefined;
+    setStatus?(slug: string, status: 'active' | 'retired'): Promise<boolean>;
+}
+export interface RoomCandidate {
+    id: string;
+    rooms: string[];
+}
+/** 解析标注器输出的逐条候选(容错:id 配对失败丢弃;isTag 校验;目录内优先,≤3)。 */
+export declare function parseRoomCandidateItems(parsed: ReadonlyArray<{
+    id: string;
+    rooms: readonly string[];
+}>, ids: ReadonlyArray<string>, roomCatalog: ReadonlyArray<{
+    room: string;
+    count: number;
+}>): RoomCandidate[];
+/** 候选标注系统 prompt:喂现有 Room 词表(带计数),优先挂靠、少量新建兜底。 */
+export declare function roomCandidateSystemPrompt(roomCatalog: ReadonlyArray<{
+    room: string;
+    count: number;
+}>): string;
+/** 候选标注器:一批孤儿记录 → 候选 Room(优先现有词表;失败返回空,调用方零改动)。 */
+export declare function roomCandidateChunk(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, chunk: MemoryRecord[], roomCatalog: ReadonlyArray<{
+    room: string;
+    count: number;
+}>): Promise<Array<{
+    id: string;
+    rooms: string[];
+}>>;
+export interface OrphanAnnotateIO {
+    l1: RoomReviewStore;
+    logger: MemoryLogger;
+    /** Room 注册表(可选:未装配 = 词表只用自生长聚合,无注册条目)。 */
+    registry?: {
+        listActive(): Array<{
+            slug: string;
+            label?: string;
+            description?: string;
+        }>;
+    };
+}
+/**
+ * 预标记消费器:活跃孤儿(≤limit 条)批量产候选并写 pending。
+ * 写前重读合并(与 relabel 同纪律);失败单条跳过、原记录零改动。
+ */
+export interface OrphanAnnotateOverrides {
+    /** 测试注入口:替换 LLM 候选标注器(默认走真实 callLLM 路径);第二参为合并词表。 */
+    chunkAnnotator?: (chunk: MemoryRecord[], catalog: ReadonlyArray<{
+        room: string;
+        count: number;
+        label?: string;
+        description?: string;
+    }>) => Promise<Array<{
+        id: string;
+        rooms: string[];
+    }>>;
+}
+export declare function annotateOrphanCandidates(ctx: Context, cfg: MemoryConfig, io: OrphanAnnotateIO, limit?: number, overrides?: OrphanAnnotateOverrides): Promise<{
+    selected: number;
+    candidates: number;
+    written: number;
+}>;
+export interface MergeRoomResult {
+    dryRun: boolean;
+    /** 影响条数(dryRun=预览数;实跑=实际重写数)。 */
+    affected: number;
+    preview: string[];
+    applied: number;
+    hasMore: boolean;
+    backupFile?: string;
+    /** 实跑时回传:受影响的族与场景(调用方入队 recluster 'room-merge')。 */
+    families?: string[];
+    scenes?: string[];
+}
+/**
+ * Room merge/rename 编排(破坏性动作,分类管理 beta.5):
+ *  - dryRun(缺省 true):只统计 affected + 前 6 条预览,**零写入**;
+ *  - 实跑:执行前备份(matching rows → rooms-merge-backups/)→ 游标重写
+ *    (写前重读-合并-写回,其余 metadata 键保全)→ 注册表 markMerged/renameSlug
+ *    → 返回受影响 (family, scene) 供调用方入队 recluster('room-merge');
+ *  - 单飞:并发 merge 直接抛错;与 relabel/ruminate 的时间错开由调用方保证。
+ * 抛错语义:非法参数/注册表冲突直接抛(调用方转 notice)。
+ */
+export declare function mergeRoom(io: {
+    l1: RoomMergeStore;
+    registry: RoomRegistryMerge;
+    logger: MemoryLogger;
+}, from: string, to: string, opts?: {
+    dryRun?: boolean;
+    cap?: number;
+}): Promise<MergeRoomResult>;
+/** rename = merge 1:1 + 注册表改名(冲突时抛错提示走 merge)。
+ *  归类语义:改名**不是退役**——merge 编排的 markMerged 会把旧条目置 retired,
+ *  这里在改名后恢复其先前状态(active 条目改名后仍 active,不掉出标注词表)。 */
+export declare function renameRoom(io: {
+    l1: RoomMergeStore;
+    registry: RoomRegistryMerge;
+    logger: MemoryLogger;
+}, from: string, to: string, opts?: {
+    dryRun?: boolean;
+    cap?: number;
+}): Promise<MergeRoomResult>;
+/** 下一条待复查(供 agent 逐个过):记录摘要 + 候选 + 现有 Room 词表 + 剩余数。 */
+export declare function nextReview(l1: RoomReviewStore): {
+    id: string;
+    content: string;
+    type: string;
+    sceneName: string;
+    candidates: string[];
+    roomCatalog: Array<{
+        room: string;
+        count: number;
+    }>;
+    remaining: number;
+} | null;
+/** 待复查剩余数(面板/工具兜底信息)。 */
+export declare function pendingReviewCount(l1: RoomReviewStore): number;
+/**
+ * 确认复查结果:候选(或 agent 改写的)写入 metadata.tags(**进 Room**),
+ * 清候选、标 confirmed。**高权限门控由调用方执行**(与 memory_delete 同款)。
+ * 返回写入的 tags;id 不存在/状态非法返回 null。
+ */
+export declare function confirmReview(l1: RoomReviewStore, id: string, rooms: readonly string[]): {
+    tags: string[];
+} | null;
+/** 跳过:标 skipped(不再进 pending 队列)。已 confirmed 的记录不受 skip 影响(挂了 Room 的不算长尾)。 */
+export declare function skipReview(l1: RoomReviewStore, id: string): boolean;

package/dist/room-review.js

@@ -0,0 +1,281 @@
+import { isTag } 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)。 */
+export function parseRoomCandidateItems(parsed, ids, roomCatalog) {
+    const idSet = new Set(ids);
+    const catalogSet = new Set(roomCatalog.map((r) => r.room));
+    const byId = new Map();
+    for (const item of parsed) {
+        if (!idSet.has(item.id))
+            continue;
+        const cleaned = [];
+        for (const r of item.rooms) {
+            const slug = typeof r === 'string' ? r.trim().toLowerCase() : '';
+            if (!slug || !isTag(slug))
+                continue;
+            if (!cleaned.includes(slug))
+                cleaned.push(slug);
+        }
+        // 目录内优先排前,其余兜底;截断到 3
+        cleaned.sort((a, b) => Number(catalogSet.has(b)) - Number(catalogSet.has(a)));
+        byId.set(item.id, cleaned.slice(0, 3));
+    }
+    return [...byId.entries()].map(([id, rooms]) => ({ id, rooms }));
+}
+/** 候选标注系统 prompt:喂现有 Room 词表(带计数),优先挂靠、少量新建兜底。 */
+export function roomCandidateSystemPrompt(roomCatalog) {
+    const catalog = roomCatalog.length > 0
+        ? roomCatalog
+            .slice(0, 40)
+            .map((r) => `- ${r.room}(现有 ${r.count} 条)`)
+            .join('\n')
+        : '(暂无现有 Room)';
+    return ('你是记忆库的 Room 归类器。给你若干条记忆(带 id)与现有 Room 词表(带计数),' +
+        '为每条记忆选出它最可能归属的 1-3 个 Room slug。规则:\n' +
+        '1. **优先从现有 Room 词表里选**(保持分类收敛,避免碎片化);\n' +
+        '2. 词表确实没有合适主题时,才提议最多 2 个新 slug(小写字母/数字/连字符);\n' +
+        '3. 完全无法判断时返回空数组(宁缺毋滥,不硬猜)。\n' +
+        `现有 Room 词表:\n${catalog}\n\n` +
+        '输出 JSON 数组:[{"id":"<原id>","rooms":["slug1","slug2"]}]。只输出 JSON,不要多余文字。');
+}
+/** 候选标注器:一批孤儿记录 → 候选 Room(优先现有词表;失败返回空,调用方零改动)。 */
+export async function roomCandidateChunk(ctx, cfg, logger, chunk, roomCatalog) {
+    const list = chunk.map((r, i) => `${i + 1}. id=${r.id}\n${r.content.slice(0, 300)}`).join('\n\n');
+    try {
+        const raw = await callLLM(ctx, cfg, {
+            system: roomCandidateSystemPrompt(roomCatalog),
+            user: `记忆列表:\n${list}`,
+            maxTokens: 4096,
+            layer: 'l1-extract',
+            logger,
+        });
+        const parsed = parseJsonLogged(raw, 'Room 候选标注', logger);
+        if (!Array.isArray(parsed))
+            return [];
+        const shape = parsed
+            .map((item) => ({
+            id: typeof item?.id === 'string' ? item.id : '',
+            rooms: Array.isArray(item?.rooms) ? item.rooms : [],
+        }))
+            .filter((x) => x.id !== '');
+        return parseRoomCandidateItems(shape, chunk.map((r) => r.id), roomCatalog);
+    }
+    catch (err) {
+        logger.warn(`[memory] Room 候选标注块失败(跳过 ${chunk.length} 条,原记录未改): ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+/** 活跃孤儿的选择器:untagged + 未退场,跳过已 skipped 的。 */
+function selectPendingOrphans(l1, limit) {
+    const out = [];
+    const seen = new Set();
+    for (let offset = 0; offset < 2000; offset += 200) {
+        const page = l1.list({ untagged: true, retired: false, limit: 200, offset });
+        for (const r of page.items) {
+            if (seen.has(r.id))
+                continue;
+            seen.add(r.id);
+            if (r.metadata?.[ROOM_REVIEW_KEY] === 'skipped')
+                continue;
+            out.push(r);
+            if (out.length >= limit)
+                return out;
+        }
+        if (page.items.length < 200)
+            break;
+    }
+    return out;
+}
+export async function annotateOrphanCandidates(ctx, cfg, io, limit = 40, overrides = {}) {
+    const selected = selectPendingOrphans(io.l1, limit);
+    if (selected.length === 0)
+        return { selected: 0, candidates: 0, written: 0 };
+    // 合并词表:注册表条目排前(附 description,对 LLM 归类价值最高),封顶 120;
+    // 无注册表 = 纯自生长聚合(计数降序)。整批共享一张词表(一次 LLM 调用)。
+    const grown = io.l1.listRooms();
+    const regActive = io.registry?.listActive() ?? [];
+    const regSet = new Set(regActive.map((e) => e.slug));
+    const merged = [
+        ...regActive.map((e) => ({ room: e.slug, count: 0, label: e.label, description: e.description })),
+        ...grown.filter((r) => !regSet.has(r.room)).map((r) => ({ room: r.room, count: r.count })),
+    ].slice(0, 120);
+    const rows = overrides.chunkAnnotator !== undefined
+        ? await overrides.chunkAnnotator(selected, merged)
+        : await roomCandidateChunk(ctx, cfg, io.logger, selected, merged);
+    let written = 0;
+    for (const { id, rooms: candidates } of rows) {
+        if (candidates.length === 0)
+            continue;
+        const fresh = io.l1.getByIds([id])[0];
+        if (!fresh)
+            continue;
+        const meta = { ...(fresh.metadata ?? {}) };
+        meta[ROOM_CANDIDATES_KEY] = candidates;
+        meta[ROOM_REVIEW_KEY] = 'pending';
+        if (io.l1.patchMetadata(id, meta))
+            written++;
+    }
+    io.logger.info(`[memory] 孤儿候选预标记:选中 ${selected.length},产候选 ${rows.length},写 pending ${written} 条(待 agent 复查)`);
+    return { selected: selected.length, candidates: rows.length, written };
+}
+/** 待复查队列:pending 且有候选的活跃孤儿,按更新时间升序(最旧的先复查)。 */
+function pendingQueue(l1) {
+    const out = [];
+    const seen = new Set();
+    for (let offset = 0; offset < 2000; offset += 200) {
+        const page = l1.list({ untagged: true, retired: false, limit: 200, offset });
+        for (const r of page.items) {
+            if (seen.has(r.id))
+                continue;
+            seen.add(r.id);
+            const meta = (r.metadata ?? {});
+            if (meta[ROOM_REVIEW_KEY] === 'pending' && Array.isArray(meta[ROOM_CANDIDATES_KEY]))
+                out.push(r);
+        }
+        if (page.items.length < 200)
+            break;
+    }
+    return out.sort((a, b) => a.updatedAt - b.updatedAt);
+}
+/** merge 单飞哨兵(模块级;与 ruminate/wing-backfill 的时间错开由调用方保证)。 */
+let roomMergeRunning = false;
+/**
+ * Room merge/rename 编排(破坏性动作,分类管理 beta.5):
+ *  - dryRun(缺省 true):只统计 affected + 前 6 条预览,**零写入**;
+ *  - 实跑:执行前备份(matching rows → rooms-merge-backups/)→ 游标重写
+ *    (写前重读-合并-写回,其余 metadata 键保全)→ 注册表 markMerged/renameSlug
+ *    → 返回受影响 (family, scene) 供调用方入队 recluster('room-merge');
+ *  - 单飞:并发 merge 直接抛错;与 relabel/ruminate 的时间错开由调用方保证。
+ * 抛错语义:非法参数/注册表冲突直接抛(调用方转 notice)。
+ */
+export async function mergeRoom(io, from, to, opts = {}) {
+    const dryRun = opts.dryRun !== false;
+    const cap = Math.min(Math.max(opts.cap ?? 500, 1), 2000);
+    if (from === to)
+        throw new Error('from 与 to 相同');
+    if (!from.trim())
+        throw new Error('from 不能为空');
+    if (roomMergeRunning)
+        throw new Error('Room merge 已在进行中(单飞)');
+    const previewRows = io.l1.listByTagAll(from, 7);
+    const affected = io.l1.listByTagAll(from, cap + 1).length;
+    const preview = previewRows.slice(0, 6).map((r) => r.id);
+    if (dryRun)
+        return { dryRun: true, affected, preview, applied: 0, hasMore: affected > cap };
+    if (roomMergeRunning)
+        throw new Error('Room merge 已在进行中(单飞)');
+    roomMergeRunning = true;
+    try {
+        const backup = io.l1.backupTagRecords(from);
+        io.logger.info(`[memory] Room merge 备份:${from} → ${to},${backup.count} 条 → ${backup.file}`);
+        let applied = 0;
+        const hasMore = false; // 循环到收敛,单次调用内 hasMore 恒 false(重写返回值沿用结果形状)
+        const families = new Set();
+        const scenes = new Set();
+        // 游标重写:上限 cap/次,r.hasMore 时继续(总量受 cap×轮次约束,单飞内收敛)
+        for (;;) {
+            const r = io.l1.rewriteTag(from, to, cap);
+            applied += r.rewritten;
+            for (const f of r.families)
+                families.add(f);
+            for (const sc of r.scenes)
+                scenes.add(sc);
+            if (!r.hasMore || r.rewritten === 0)
+                break;
+        }
+        await io.registry.markMerged(from, to);
+        io.l1.invalidateRooms();
+        io.logger.info(`[memory] Room merge 完成:${from} → ${to},重写 ${applied} 条;受影响场景 ${scenes.size} 个`);
+        return {
+            dryRun: false,
+            affected,
+            preview,
+            applied,
+            hasMore,
+            backupFile: backup.file,
+            ...(families.size > 0 || scenes.size > 0 ? { families: [...families], scenes: [...scenes] } : {}),
+        };
+    }
+    finally {
+        roomMergeRunning = false;
+    }
+}
+/** rename = merge 1:1 + 注册表改名(冲突时抛错提示走 merge)。
+ *  归类语义:改名**不是退役**——merge 编排的 markMerged 会把旧条目置 retired,
+ *  这里在改名后恢复其先前状态(active 条目改名后仍 active,不掉出标注词表)。 */
+export async function renameRoom(io, from, to, opts = {}) {
+    const priorStatus = io.registry.bySlug?.(from)?.status ?? 'active';
+    const r = await mergeRoom(io, from, to, opts);
+    if (!r.dryRun && r.applied > 0) {
+        await io.registry.renameSlug(from, to);
+        if (priorStatus === 'active')
+            await io.registry.setStatus?.(to, 'active');
+    }
+    return r;
+}
+/** 下一条待复查(供 agent 逐个过):记录摘要 + 候选 + 现有 Room 词表 + 剩余数。 */
+export function nextReview(l1) {
+    const queue = pendingQueue(l1);
+    if (queue.length === 0)
+        return null;
+    const r = queue[0];
+    const meta = (r.metadata ?? {});
+    return {
+        id: r.id,
+        content: r.content.slice(0, 600),
+        type: r.type,
+        sceneName: r.scene_name,
+        candidates: meta[ROOM_CANDIDATES_KEY] ?? [],
+        roomCatalog: l1.listRooms().slice(0, 40),
+        remaining: queue.length,
+    };
+}
+/** 待复查剩余数(面板/工具兜底信息)。 */
+export function pendingReviewCount(l1) {
+    return pendingQueue(l1).length;
+}
+/**
+ * 确认复查结果:候选(或 agent 改写的)写入 metadata.tags(**进 Room**),
+ * 清候选、标 confirmed。**高权限门控由调用方执行**(与 memory_delete 同款)。
+ * 返回写入的 tags;id 不存在/状态非法返回 null。
+ */
+export function confirmReview(l1, id, rooms) {
+    const found = l1.getByIds([id])[0];
+    if (!found)
+        return null;
+    const meta = { ...(found.metadata ?? {}) };
+    // 已确认/已跳过的不允许重复确认(防止 agent 循环空转)
+    if (meta[ROOM_REVIEW_KEY] === 'confirmed')
+        return null;
+    const cleaned = [];
+    for (const r of rooms) {
+        if (typeof r !== 'string')
+            continue;
+        const slug = r.trim().toLowerCase();
+        if (!slug || !isTag(slug) || cleaned.includes(slug))
+            continue;
+        cleaned.push(slug);
+    }
+    if (cleaned.length === 0)
+        return null;
+    meta.tags = cleaned;
+    delete meta[ROOM_CANDIDATES_KEY];
+    meta[ROOM_REVIEW_KEY] = 'confirmed';
+    if (!l1.patchMetadata(id, meta))
+        return null;
+    l1.invalidateRooms();
+    return { tags: cleaned };
+}
+/** 跳过:标 skipped(不再进 pending 队列)。已 confirmed 的记录不受 skip 影响(挂了 Room 的不算长尾)。 */
+export function skipReview(l1, id) {
+    const found = l1.getByIds([id])[0];
+    if (!found)
+        return false;
+    const meta = { ...(found.metadata ?? {}) };
+    if (meta[ROOM_REVIEW_KEY] === 'confirmed')
+        return false;
+    meta[ROOM_REVIEW_KEY] = 'skipped';
+    return l1.patchMetadata(id, meta);
+}