@kenz1117/dsh-engram 0.7.2 → 0.7.4

package/lib/index.js

@@ -30,7 +30,13 @@ const CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"rankProofWeight",
 	"queryRewrite",
 	"autoSlot",
-	"reviewScheduling"
+	"reviewScheduling",
+	"historyBackfillDays",
+	"historyBackfillMaxTurnsPerSession",
+	"historyBackfillMaxTotalTurns",
+	"historyBackfillIncludeSubagents",
+	"historyBackfillIncludeSeeded",
+	"historyBackfillIncludeNoCwd"
 ]);
 const INGEST_MODES = /* @__PURE__ */ new Set([
 	"off",
@@ -54,13 +60,19 @@ const Config = z.object({
 	rankProofWeight: z.number().min(0).max(2),
 	queryRewrite: z.boolean(),
 	autoSlot: z.boolean(),
-	reviewScheduling: z.boolean()
+	reviewScheduling: z.boolean(),
+	historyBackfillDays: z.number().step(1).min(0).max(3650),
+	historyBackfillMaxTurnsPerSession: z.number().step(1).min(1).max(500),
+	historyBackfillMaxTotalTurns: z.number().step(1).min(1).max(5e3),
+	historyBackfillIncludeSubagents: z.boolean(),
+	historyBackfillIncludeSeeded: z.boolean(),
+	historyBackfillIncludeNoCwd: z.boolean()
 });
 /**
 * 显式 resolve 步骤：默认值只在唯一的此处落地，非法值 loud 失败。
 * @param config - cordis.yml 传入的未校验配置。
 * @returns 完整解析配置。
-* @throws 未知键、ingest 档位非法、provider/model 只给其一、decay/预算/排序权重越界时抛错。
+* @throws 未知键、ingest 档位非法、provider/model 只给其一、decay/预算/排序权重/历史回填规则越界时抛错。
 */
 function resolveConfig(config = {}) {
 	for (const key of Object.keys(config)) if (!CONFIG_KEYS.has(key)) throw new Error(`dsh-engram: unknown config key "${key}"`);
@@ -74,6 +86,9 @@ function resolveConfig(config = {}) {
 	if (config.injectTokenBudget !== void 0 && (!Number.isInteger(config.injectTokenBudget) || config.injectTokenBudget < 128 || config.injectTokenBudget > 8192)) throw new Error("dsh-engram: injectTokenBudget must be an integer in [128, 8192]");
 	if (config.rankRecencyWeight !== void 0 && (config.rankRecencyWeight < 0 || config.rankRecencyWeight > 2)) throw new Error("dsh-engram: rankRecencyWeight must be in [0, 2]");
 	if (config.rankProofWeight !== void 0 && (config.rankProofWeight < 0 || config.rankProofWeight > 2)) throw new Error("dsh-engram: rankProofWeight must be in [0, 2]");
+	if (config.historyBackfillDays !== void 0 && (!Number.isInteger(config.historyBackfillDays) || config.historyBackfillDays < 0 || config.historyBackfillDays > 3650)) throw new Error("dsh-engram: historyBackfillDays must be an integer in [0, 3650] (0 = unlimited)");
+	if (config.historyBackfillMaxTurnsPerSession !== void 0 && (!Number.isInteger(config.historyBackfillMaxTurnsPerSession) || config.historyBackfillMaxTurnsPerSession < 1 || config.historyBackfillMaxTurnsPerSession > 500)) throw new Error("dsh-engram: historyBackfillMaxTurnsPerSession must be an integer in [1, 500]");
+	if (config.historyBackfillMaxTotalTurns !== void 0 && (!Number.isInteger(config.historyBackfillMaxTotalTurns) || config.historyBackfillMaxTotalTurns < 1 || config.historyBackfillMaxTotalTurns > 5e3)) throw new Error("dsh-engram: historyBackfillMaxTotalTurns must be an integer in [1, 5000]");
 	const dbDir = config.dbDir ?? join(homedir(), ".dsh", "engram");
 	return {
 		dbDir,
@@ -93,7 +108,15 @@ function resolveConfig(config = {}) {
 		rankProofWeight: config.rankProofWeight ?? .1,
 		queryRewrite: config.queryRewrite ?? true,
 		autoSlot: config.autoSlot ?? true,
-		reviewScheduling: config.reviewScheduling ?? true
+		reviewScheduling: config.reviewScheduling ?? true,
+		historyBackfill: {
+			days: config.historyBackfillDays ?? 7,
+			maxTurnsPerSession: config.historyBackfillMaxTurnsPerSession ?? 20,
+			maxTotalTurns: config.historyBackfillMaxTotalTurns ?? 200,
+			includeSubagents: config.historyBackfillIncludeSubagents ?? false,
+			includeSeeded: config.historyBackfillIncludeSeeded ?? false,
+			includeNoCwd: config.historyBackfillIncludeNoCwd ?? false
+		}
 	};
 }
 //#endregion
@@ -656,7 +679,7 @@ async function ingestPreviousTurn(deps) {
 		written: 0,
 		skipped: "already-ingested"
 	};
-	if (sliceMode === "previous") {
+	if (sliceMode === "previous" || deps.throttle === true) {
 		const throttled = throttleDecision(slice);
 		if (throttled !== null) return {
 			scannedEvents: slice.length,
@@ -726,7 +749,7 @@ async function ingestPreviousTurn(deps) {
 		}
 		if (writtenContents.includes(content)) continue;
 		await store.write({
-			scope: "user",
+			scope: deps.writeScope ?? "user",
 			kind,
 			content,
 			importance,
@@ -734,7 +757,8 @@ async function ingestPreviousTurn(deps) {
 			sourceSessionId: deps.sessionId,
 			sourceRound: round,
 			...minSeq === null ? {} : { sourceSeq: minSeq },
-			...embedder === void 0 ? {} : { embedding: (await embedder.embed([content]))[0] }
+			...embedder === void 0 ? {} : { embedding: (await embedder.embed([content]))[0] },
+			...deps.history === true ? { initialReviewAt: null } : {}
 		});
 		writtenContents.push(content);
 		written += 1;
@@ -824,6 +848,286 @@ async function replayPendingIngests(deps) {
 	};
 }
 //#endregion
+//#region src/ingest/history.ts
+const DAY_MS$1 = 864e5;
+/** 估算时并发读取的会话数（读取是 IO，适度并发；摄取阶段始终串行）。 */
+const ESTIMATE_CONCURRENCY = 4;
+/**
+* 合并规则：默认值来自 Config，覆盖项来自面板/工具；总轮数上限是硬顶（只能调低）。
+* @param defaults - 配置默认规则。
+* @param overrides - 本次覆盖项。
+* @returns 生效规则。
+* @throws 覆盖项越界时抛错（与配置校验同界）。
+*/
+function mergeHistoryRules(defaults, overrides) {
+	const days = overrides.days ?? defaults.days;
+	if (!Number.isInteger(days) || days < 0 || days > 3650) throw new Error("historyBackfill: days 必须是 [0, 3650] 的整数（0 = 不限）");
+	const maxTurnsPerSession = overrides.maxTurnsPerSession ?? defaults.maxTurnsPerSession;
+	if (!Number.isInteger(maxTurnsPerSession) || maxTurnsPerSession < 1 || maxTurnsPerSession > 500) throw new Error("historyBackfill: maxTurnsPerSession 必须是 [1, 500] 的整数");
+	const maxTotalTurns = overrides.maxTotalTurns ?? defaults.maxTotalTurns;
+	if (!Number.isInteger(maxTotalTurns) || maxTotalTurns < 1 || maxTotalTurns > 5e3) throw new Error("historyBackfill: maxTotalTurns 必须是 [1, 5000] 的整数");
+	if ((overrides.provider !== void 0 && overrides.provider !== "") !== (overrides.model !== void 0 && overrides.model !== "")) throw new Error("historyBackfill: provider 与 model 必须成对提供");
+	return {
+		days,
+		maxTurnsPerSession,
+		maxTotalTurns: Math.min(maxTotalTurns, defaults.maxTotalTurns),
+		includeSubagents: overrides.includeSubagents ?? defaults.includeSubagents,
+		includeSeeded: overrides.includeSeeded ?? defaults.includeSeeded,
+		includeNoCwd: overrides.includeNoCwd ?? defaults.includeNoCwd
+	};
+}
+/** 事件流里的轮次号（按出现顺序，缺 data.turn 的 turn/start 忽略）。 */
+function turnNumbers(events) {
+	const turns = [];
+	for (const event of events) {
+		if (event.type !== "turn/start") continue;
+		const turn = event.data?.turn;
+		if (typeof turn === "number" && Number.isFinite(turn)) turns.push(turn);
+	}
+	return turns;
+}
+/** 单个会话的日志是否读取成功（失败返回 undefined，调用方计入 unreadable）。 */
+async function loadSession(source, id) {
+	try {
+		return (await source.load(id)).events;
+	} catch {
+		return;
+	}
+}
+/**
+* 枚举并筛选可回填的会话：过滤子代理/种子/无 cwd/超窗，按单会话与总轮数上限截断。
+* @param deps - 历史回填依赖。
+* @param rules - 生效规则。
+* @returns 候选会话与排除统计。
+*/
+async function selectSessions(deps, rules) {
+	const source = deps.source;
+	if (source === void 0) return {
+		candidates: [],
+		skipped: {
+			subagent: 0,
+			seeded: 0,
+			noCwd: 0,
+			tooOld: 0,
+			unreadable: 0
+		},
+		truncated: false
+	};
+	const now = (deps.now ?? Date.now)();
+	const headers = await source.list();
+	const skipped = {
+		subagent: 0,
+		seeded: 0,
+		noCwd: 0,
+		tooOld: 0,
+		unreadable: 0
+	};
+	/** 时间窗内、需要读日志的 header（按创建时间倒序，先处理最近的）。 */
+	const kept = [];
+	for (const header of [...headers].sort((a, b) => b.createdAt - a.createdAt)) {
+		if (header.origin === "subagent" && !rules.includeSubagents) {
+			skipped.subagent += 1;
+			continue;
+		}
+		if (header.isSeeded === true && !rules.includeSeeded) {
+			skipped.seeded += 1;
+			continue;
+		}
+		if ((header.cwd === void 0 || header.cwd === "") && !rules.includeNoCwd) {
+			skipped.noCwd += 1;
+			continue;
+		}
+		if (rules.days > 0 && header.createdAt < now - rules.days * DAY_MS$1) {
+			skipped.tooOld += 1;
+			continue;
+		}
+		kept.push(header);
+	}
+	const loaded = [];
+	for (let i = 0; i < kept.length; i += ESTIMATE_CONCURRENCY) {
+		const batch = kept.slice(i, i + ESTIMATE_CONCURRENCY);
+		const settled = await Promise.all(batch.map(async (header) => {
+			const events = await loadSession(source, header.id);
+			if (events === void 0) {
+				skipped.unreadable += 1;
+				return;
+			}
+			const all = turnNumbers(events);
+			const turns = all.slice(Math.max(0, all.length - rules.maxTurnsPerSession));
+			if (turns.length === 0) return void 0;
+			const cwd = header.cwd;
+			return cwd === void 0 || cwd === "" ? {
+				header,
+				events,
+				turns,
+				openStore: deps.openUserStore,
+				writeScope: "user",
+				storeKey: "user"
+			} : {
+				header,
+				events,
+				turns,
+				openStore: () => deps.resolveStore(cwd),
+				writeScope: "project",
+				storeKey: cwd
+			};
+		}));
+		loaded.push(...settled);
+	}
+	const candidates = [];
+	let budget = rules.maxTotalTurns;
+	let truncated = false;
+	for (const candidate of loaded) {
+		if (candidate === void 0) continue;
+		if (budget <= 0) {
+			truncated = true;
+			continue;
+		}
+		const allowed = candidate.turns.slice(Math.max(0, candidate.turns.length - budget));
+		if (allowed.length < candidate.turns.length) truncated = true;
+		candidates.push({
+			...candidate,
+			turns: allowed
+		});
+		budget -= allowed.length;
+	}
+	return {
+		candidates,
+		skipped,
+		truncated
+	};
+}
+/** 环境不支持读取历史会话时的统一说明。 */
+const UNAVAILABLE_REASON = "当前环境未挂载会话持久化服务（会话日志不可读，例如 headless 组合），无法回填历史会话";
+/**
+* 估算：候选会话数、规则内轮数、以及扣掉已摄取后的真正待处理轮数。
+* 估算阶段只在库文件已存在时打开目标库（不创建空库、不写入）。
+* @param deps - 历史回填依赖。
+* @param defaults - 配置默认规则。
+* @param overrides - 本次覆盖项。
+* @returns 估算结果；环境不支持时 `unavailable` 有值。
+*/
+async function estimateHistoryBackfill(deps, defaults, overrides = {}) {
+	const rules = mergeHistoryRules(defaults, overrides);
+	if (deps.source === void 0) return {
+		rules,
+		candidates: 0,
+		eligibleTurns: 0,
+		pendingTurns: 0,
+		alreadyIngested: 0,
+		skipped: {
+			subagent: 0,
+			seeded: 0,
+			noCwd: 0,
+			tooOld: 0,
+			unreadable: 0
+		},
+		truncated: false,
+		unavailable: UNAVAILABLE_REASON
+	};
+	const { candidates, skipped, truncated } = await selectSessions(deps, rules);
+	let eligibleTurns = 0;
+	let alreadyIngested = 0;
+	for (const candidate of candidates) {
+		eligibleTurns += candidate.turns.length;
+		const store = candidate.writeScope === "user" ? await deps.resolveExistingUserStore() : await deps.resolveExistingStore(candidate.storeKey);
+		if (store === void 0) continue;
+		for (const turn of candidate.turns) if (await store.hasAudit("ingest-done", encodeTurnKey(candidate.header.id, turn))) alreadyIngested += 1;
+	}
+	return {
+		rules,
+		candidates: candidates.length,
+		eligibleTurns,
+		pendingTurns: eligibleTurns - alreadyIngested,
+		alreadyIngested,
+		skipped,
+		truncated
+	};
+}
+/**
+* 执行回填：逐会话、逐轮调用实时摄取管线；单轮失败只记录并继续，中断后重跑只补未完成轮次。
+* @param deps - 历史回填依赖。
+* @param defaults - 配置默认规则。
+* @param overrides - 本次覆盖项。
+* @param onProgress - 进度回调（每个会话结束时调用一次）。
+* @param signal - 取消信号（面板「暂停」/工具超时）。
+* @returns 运行结果。
+*/
+async function runHistoryBackfill(deps, defaults, overrides, onProgress, signal) {
+	const rules = mergeHistoryRules(defaults, overrides);
+	const { candidates } = deps.source === void 0 ? { candidates: [] } : await selectSessions(deps, rules);
+	const routeOverride = overrides.provider !== void 0 && overrides.model !== void 0 ? {
+		provider: overrides.provider,
+		model: overrides.model
+	} : deps.routeOverride;
+	const failures = [];
+	/** 内部可变累加器（对外以只读的 HistoryRunProgress 暴露）。 */
+	const progress = {
+		state: "running",
+		sessionsTotal: candidates.length,
+		sessionsDone: 0,
+		turnsPlanned: candidates.reduce((sum, candidate) => sum + candidate.turns.length, 0),
+		turnsDone: 0,
+		memoriesWritten: 0,
+		turnsSkipped: 0,
+		turnsFailed: 0,
+		skipReasons: {}
+	};
+	onProgress({ ...progress });
+	for (const candidate of candidates) {
+		if (signal.aborted) break;
+		for (const turn of candidate.turns) {
+			if (signal.aborted) break;
+			try {
+				const outcome = await ingestPreviousTurn({
+					events: candidate.events,
+					sessionId: candidate.header.id,
+					turn,
+					slice: turn,
+					openStore: () => candidate.openStore(),
+					embedder: deps.embedder,
+					mode: deps.mode,
+					routeOverride,
+					call: deps.call,
+					logRequest: deps.logRequest,
+					signal,
+					throttle: true,
+					history: true,
+					writeScope: candidate.writeScope
+				});
+				progress.memoriesWritten += outcome.written;
+				if (outcome.skipped !== null) {
+					progress.turnsSkipped += 1;
+					progress.skipReasons[outcome.skipped] = (progress.skipReasons[outcome.skipped] ?? 0) + 1;
+				}
+			} catch (error) {
+				progress.turnsFailed += 1;
+				failures.push({
+					sessionId: candidate.header.id,
+					turn,
+					reason: error instanceof Error ? error.message : String(error)
+				});
+			}
+			progress.turnsDone += 1;
+		}
+		progress.sessionsDone += 1;
+		onProgress({
+			...progress,
+			currentSession: candidate.header.id
+		});
+	}
+	const state = signal.aborted ? "cancelled" : "done";
+	onProgress({
+		...progress,
+		state
+	});
+	return {
+		...progress,
+		state,
+		failures
+	};
+}
+//#endregion
 //#region src/consolidation/run.ts
 /** 单条整理动作（写入 op_log 的统一标记）。 */
 const CONSOLIDATION_OP = "consolidation";
@@ -971,11 +1275,11 @@ function cosine$1(a, b) {
 //#region src/mirror/markdown.ts
 /**
 * Markdown 镜像：把 SQLite 记忆库导出为可被 Obsidian / VS Code / git 直接漫游的
-* 文件树，每个房间一个 .md + frontmatter，附楼层清单 _meta.json 与全宫殿入口 _index.md。
+* 文件树：按房间（kind）分目录，每条记忆一个 .md + frontmatter，附房间清单 _meta.json 与全宫殿入口 _index.md。
 * 写入过程全部幂等：重复执行只会覆盖同名文件，不会向 SQLite 写任何东西（只读）。
 * @module @kenz1117/dsh-engram/mirror/markdown
 */
-/** 房间铭牌 URL/路径安全的 slug（仅 ASCII、连字符分隔）。 */
+/** 记忆铭牌 URL/路径安全的 slug（仅 ASCII、连字符分隔）。 */
 function slugify(input) {
 	const stripped = input.toLowerCase().replace(/[\u4e00-\u9fa5]+/g, "记").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 	return stripped === "" ? "untitled" : stripped.slice(0, 32);
@@ -990,30 +1294,31 @@ function yaml(value) {
 function iso(ms) {
 	return new Date(ms).toISOString();
 }
-/** 楼层中文别名（与面板 i18n 的 kindLabel 保持一致；只用做目录名）。 */
-const FLOOR_LABEL = {
-	fact: "fact",
-	preference: "preference",
-	decision: "decision",
-	episode: "episode",
-	skill: "skill"
+/** 房间展示名（kind → 中文房间名；与 client 词典的 kindFact… 对应，host 侧不引 client 模块）。
+*  仅用于 _index.md 的可读标签，目录名仍用 kind 原值以保持路径稳定。 */
+const ROOM_LABEL = {
+	fact: "事实厅",
+	preference: "偏好阁",
+	decision: "决策堂",
+	episode: "往事廊",
+	skill: "技法坊"
 };
-/** 顶层 _index.md 的纯文本模板（楼层卡片 + 房间清单链接）。 */
-function renderIndex(scope, data, floors) {
+/** 顶层 _index.md 的纯文本模板（房间导览 + 记忆清单链接）。 */
+function renderIndex(scope, data, rooms) {
 	const total = data.records.length;
 	const active = data.records.filter((r) => r.status === "active").length;
 	const edges = data.edges.length;
 	return `# 记忆宫殿 · ${scope === "user" ? "私人宫殿" : "项目宫殿"}\n` + [
 		"",
-		`> 导出时间 ${iso(data.exportedAt)} · 共 **${total}** 间房间（对外开放 ${active}） · 走廊 ${edges} 条`,
+		`> 导出时间 ${iso(data.exportedAt)} · 共 **${total}** 条记忆（对外开放 ${active}） · 走廊 ${edges} 条`,
 		"",
-		"## 楼层导览",
+		"## 房间导览",
 		"",
-		...floors.map((f) => `- **${FLOOR_LABEL[f.kind] ?? f.kind} 层** · ${f.roomCount} 间（开放 ${f.active} · 展厅 ${f.archived} · 闭馆 ${f.forgotten}）`),
+		...rooms.map((room) => `- **${ROOM_LABEL[room.kind] ?? room.kind}** · ${room.memoryCount} 条记忆（开放 ${room.active} · 展厅 ${room.archived} · 闭馆 ${room.forgotten}）`),
 		"",
-		"## 房间清单",
+		"## 记忆清单",
 		"",
-		...data.records.slice().sort((a, b) => b.importance - a.importance).map((record) => `- [${record.status === "active" ? "●" : record.status === "archived" ? "◇" : "×"}][${FLOOR_LABEL[record.kind] ?? record.kind}] ${record.content.slice(0, 60)}${record.content.length > 60 ? "…" : ""} — [[${record.id.slice(0, 8)}]]`),
+		...data.records.slice().sort((a, b) => b.importance - a.importance).map((record) => `- [${record.status === "active" ? "●" : record.status === "archived" ? "◇" : "×"}][${ROOM_LABEL[record.kind] ?? record.kind}] ${record.content.slice(0, 60)}${record.content.length > 60 ? "…" : ""} — [[${record.id.slice(0, 8)}]]`),
 		"",
 		"## 走廊（关系边）",
 		"",
@@ -1021,8 +1326,8 @@ function renderIndex(scope, data, floors) {
 		""
 	].join("\n");
 }
-/** 单房间 .md 模板：YAML frontmatter + 铭牌正文 + 走廊列表。 */
-function renderRoom(record, edges) {
+/** 单条记忆 .md 模板：YAML frontmatter + 铭牌正文 + 走廊列表。 */
+function renderMemory(record, edges) {
 	const relEdges = edges.filter((edge) => edge.from === record.id || edge.to === record.id);
 	const tags = [];
 	if (record.outcome !== void 0) tags.push(`outcome-${record.outcome}`);
@@ -1048,13 +1353,13 @@ function renderRoom(record, edges) {
 		"---"
 	].join("\n");
 	const body = [
-		`# ${record.content.split("\n")[0]?.slice(0, 80) ?? "房间铭牌"}`,
+		`# ${record.content.split("\n")[0]?.slice(0, 80) ?? "记忆铭牌"}`,
 		"",
 		record.content,
 		"",
 		"## 走廊",
 		"",
-		...relEdges.length === 0 ? ["（此房间暂未连接任何走廊）"] : relEdges.map((edge) => {
+		...relEdges.length === 0 ? ["（此记忆暂未连接任何走廊）"] : relEdges.map((edge) => {
 			const other = edge.from === record.id ? edge.to : edge.from;
 			return `- ${edge.from === record.id ? "→" : "←"} \`${other.slice(0, 8)}\`（${edge.type}）`;
 		}),
@@ -1062,27 +1367,27 @@ function renderRoom(record, edges) {
 	].join("\n");
 	return frontmatter + "\n" + body;
 }
-/** 楼层 _meta.json 模板。 */
-function renderMeta(scope, data, floors) {
+/** 房间清单 _meta.json 模板。 */
+function renderMeta(scope, data, rooms) {
 	const payload = {
 		scope,
 		exportedAt: data.exportedAt,
 		total: data.records.length,
-		floors
+		rooms
 	};
 	return JSON.stringify(payload, null, 2) + "\n";
 }
-/** 计算楼层摘要（按 kind 分组统计 active/archived/forgotten）。 */
-function summarizeFloors(records) {
+/** 计算房间摘要（按 kind 分组统计 active/archived/forgotten 的记忆条数）。 */
+function summarizeRooms(records) {
 	const map = /* @__PURE__ */ new Map();
 	for (const record of records) {
 		const entry = map.get(record.kind) ?? {
-			roomCount: 0,
+			memoryCount: 0,
 			active: 0,
 			archived: 0,
 			forgotten: 0
 		};
-		entry.roomCount += 1;
+		entry.memoryCount += 1;
 		if (record.status === "active") entry.active += 1;
 		else if (record.status === "archived") entry.archived += 1;
 		else if (record.status === "forgotten") entry.forgotten += 1;
@@ -1097,7 +1402,7 @@ function summarizeFloors(records) {
 * 把一份 exportAll 数据写入镜像目录。
 * @param rootDir - 镜像根目录（通常 `${exportDir}/mirror/<scope>/`，由调用方拼）。
 * @param data - exportAll 的产物（含 records + edges）。
-* @returns 写入摘要（rootDir / fileCount / floors）。
+* @returns 写入摘要（rootDir / fileCount / rooms）。
 */
 async function writeMirror(rootDir, data) {
 	const scope = data.records[0]?.scope ?? "user";
@@ -1105,7 +1410,7 @@ async function writeMirror(rootDir, data) {
 		recursive: true,
 		mode: 448
 	});
-	const floors = summarizeFloors(data.records);
+	const rooms = summarizeRooms(data.records);
 	const recordsByKind = /* @__PURE__ */ new Map();
 	for (const record of data.records) {
 		const list = recordsByKind.get(record.kind) ?? [];
@@ -1114,20 +1419,20 @@ async function writeMirror(rootDir, data) {
 	}
 	let fileCount = 0;
 	for (const record of data.records) {
-		const floor = recordsByKind.get(record.kind);
-		if (floor === void 0) continue;
-		const indexInFloor = floor.indexOf(record);
-		const floorDir = join(rootDir, FLOOR_LABEL[record.kind] ?? record.kind);
-		await mkdir(floorDir, {
+		const roomRecords = recordsByKind.get(record.kind);
+		if (roomRecords === void 0) continue;
+		const indexInRoom = roomRecords.indexOf(record);
+		const roomDir = join(rootDir, record.kind);
+		await mkdir(roomDir, {
 			recursive: true,
 			mode: 448
 		});
-		const fileName = `${record.id.slice(0, 8)}-${slugify(record.content)}-${String(indexInFloor).padStart(3, "0")}.md`;
-		await writeFile(join(floorDir, fileName), renderRoom(record, data.edges), { mode: 384 });
+		const fileName = `${record.id.slice(0, 8)}-${slugify(record.content)}-${String(indexInRoom).padStart(3, "0")}.md`;
+		await writeFile(join(roomDir, fileName), renderMemory(record, data.edges), { mode: 384 });
 		fileCount += 1;
 	}
-	await writeFile(join(rootDir, "_index.md"), renderIndex(scope, data, floors), { mode: 384 });
-	await writeFile(join(rootDir, "_meta.json"), renderMeta(scope, data, floors), { mode: 384 });
+	await writeFile(join(rootDir, "_index.md"), renderIndex(scope, data, rooms), { mode: 384 });
+	await writeFile(join(rootDir, "_meta.json"), renderMeta(scope, data, rooms), { mode: 384 });
 	fileCount += 2;
 	if (scope === "shared") {
 		const manifest = buildShareManifest(data);
@@ -1137,7 +1442,7 @@ async function writeMirror(rootDir, data) {
 	return {
 		rootDir,
 		fileCount,
-		floors,
+		rooms,
 		exportedAt: data.exportedAt
 	};
 }
@@ -1159,7 +1464,7 @@ function buildShareManifest(data, now = Date.now()) {
 	return {
 		generatedAt: now,
 		scope: "shared",
-		roomCount: loans.length,
+		memoryCount: loans.length,
 		loans
 	};
 }
@@ -1447,7 +1752,7 @@ function buildTourProposal(scope, records, focusKind) {
 		return focusBoost(b) * 1e3 + b.importance * b.confidence * 100 - scoreA;
 	}).slice(0, limit);
 	return {
-		greeting: empty ? `[${scope}] 宫殿尚空。建议：先放第一段记忆（例如一条 fact 或 preference），让后续会话有锚点可循。` : `[${scope}] 宫殿现存 ${active.length} 间 active 房间。建议开场巡游：${scored.map((r, i) => `第 ${i + 1} 站「${r.content.slice(0, 24)}${r.content.length > 24 ? "…" : ""}」`).join("；")}。`,
+		greeting: empty ? `[${scope}] 宫殿尚空。建议：先放第一段记忆（例如一条 fact 或 preference），让后续会话有锚点可循。` : `[${scope}] 宫殿现存 ${active.length} 条 active 记忆。建议开场巡游：${scored.map((r, i) => `第 ${i + 1} 站「${r.content.slice(0, 24)}${r.content.length > 24 ? "…" : ""}」`).join("；")}。`,
 		suggestedStops: scored,
 		activeCount: active.length,
 		empty
@@ -1457,6 +1762,7 @@ function buildTourProposal(scope, records, focusKind) {
 //#region src/refurb.ts
 /** 缺省参数。 */
 const DEFAULT_REFURB_OPTIONS = {
+	minActive: 8,
 	demoteBelow: .2,
 	staleDays: 60,
 	duplicateTitleWindow: 0
@@ -1464,11 +1770,13 @@ const DEFAULT_REFURB_OPTIONS = {
 /**
 * 扫描一组 active 条目，按规则生成翻新建议。
 * 仅扫描同 scope 内的内容；跨 scope 的相似合并留给上层判定。
+* active 条目少于 `options.minActive` 时返回空列表：小库样本太少，逐条命中噪声大于价值。
 */
 function gatherRefurbSuggestions(records, options = DEFAULT_REFURB_OPTIONS) {
 	const suggestions = [];
 	const now = Date.now();
 	const active = records.filter((r) => r.status === "active");
+	if (active.length < options.minActive) return [];
 	const byScope = /* @__PURE__ */ new Map();
 	for (const record of active) {
 		const list = byScope.get(record.scope) ?? [];
@@ -1506,7 +1814,7 @@ function gatherRefurbSuggestions(records, options = DEFAULT_REFURB_OPTIONS) {
 					primaryId: record.id,
 					candidates: dupes.map((d) => d.id),
 					scope,
-					reason: `与 ${dupes.length} 间房间内容前 20 字重复，建议蒸馏合并。`,
+					reason: `与 ${dupes.length} 条记忆内容前 20 字重复，建议蒸馏合并。`,
 					confidence: .6
 				});
 			}
@@ -1525,7 +1833,7 @@ function gatherRefurbSuggestions(records, options = DEFAULT_REFURB_OPTIONS) {
 		primaryId: record.id,
 		candidates: [],
 		scope: record.scope,
-		reason: `内容长度 ${record.content.length} > 400，建议拆为多条独立房间。`,
+		reason: `内容长度 ${record.content.length} > 400，建议拆为多条独立记忆。`,
 		confidence: .6
 	});
 	for (const record of active) {
@@ -1617,6 +1925,36 @@ function scopeOf$1(raw, fallback) {
 	if (raw === "user" || raw === "project" || raw === "shared") return raw;
 	return fallback;
 }
+/** 宽松取数：数字与数字字符串都接受，其余返回 undefined（回退配置默认）。 */
+function toNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+}
+/** 宽松取布尔：真值/假值的字符串与布尔都接受，其余返回 undefined。 */
+function toBoolean(value) {
+	if (value === true || value === "true") return true;
+	if (value === false || value === "false") return false;
+}
+/** 从 query 或 body 收敛历史回填规则（未给或非法的字段留给配置默认值）。 */
+function historyRulesOf(raw) {
+	const days = toNumber(raw["days"]);
+	const maxTurnsPerSession = toNumber(raw["maxTurnsPerSession"]);
+	const maxTotalTurns = toNumber(raw["maxTotalTurns"]);
+	const includeSubagents = toBoolean(raw["includeSubagents"]);
+	const includeSeeded = toBoolean(raw["includeSeeded"]);
+	const includeNoCwd = toBoolean(raw["includeNoCwd"]);
+	return {
+		...days === void 0 ? {} : { days },
+		...maxTurnsPerSession === void 0 ? {} : { maxTurnsPerSession },
+		...maxTotalTurns === void 0 ? {} : { maxTotalTurns },
+		...includeSubagents === void 0 ? {} : { includeSubagents },
+		...includeSeeded === void 0 ? {} : { includeSeeded },
+		...includeNoCwd === void 0 ? {} : { includeNoCwd }
+	};
+}
 /**
 * 注册 /engram 页面与 /api/engram/* 接口（effect 由调用方持有，disposer 可逆）。
 * @param ctx - 携带 webServer 服务的宿主上下文。
@@ -1838,7 +2176,7 @@ function registerEngramRoutes(ctx, deps) {
 					json(res, 200, {
 						...await writeMirror(join(deps.mirrorDir, scope, stamp), data),
 						scope,
-						roomCount: data.records.length,
+						memoryCount: data.records.length,
 						edgeCount: data.edges.length
 					});
 					return;
@@ -1967,6 +2305,47 @@ function registerEngramRoutes(ctx, deps) {
 					});
 					return;
 				}
+				if (req.method === "GET" && route === "models") {
+					json(res, 200, await deps.history.models());
+					return;
+				}
+				if (req.method === "GET" && route === "history-backfill") {
+					json(res, 200, {
+						defaults: deps.history.defaults,
+						estimate: await deps.history.estimate(historyRulesOf(Object.fromEntries(url.searchParams)))
+					});
+					return;
+				}
+				if (req.method === "GET" && route === "history-backfill/status") {
+					json(res, 200, deps.history.status());
+					return;
+				}
+				if (req.method === "POST" && route === "history-backfill/start") {
+					if (!guardWrite(req, res)) return;
+					const body = await readJsonBody(req);
+					const started = deps.history.start(historyRulesOf(body ?? {}));
+					if (!started.ok) {
+						json(res, 409, {
+							ok: false,
+							error: started.reason ?? "无法启动回填"
+						});
+						return;
+					}
+					json(res, 200, {
+						ok: true,
+						status: deps.history.status()
+					});
+					return;
+				}
+				if (req.method === "POST" && route === "history-backfill/cancel") {
+					if (!guardWrite(req, res)) return;
+					deps.history.cancel();
+					json(res, 200, {
+						ok: true,
+						status: deps.history.status()
+					});
+					return;
+				}
 				if (req.method === "POST" && route === "consolidate") {
 					if (!guardWrite(req, res)) return;
 					const body = await readJsonBody(req);
@@ -2649,7 +3028,7 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 	* 写入期自动化（save/批量/摄取/update/蒸馏全部写入路径统一在此落地；调用方须已持事务）：
 	* 1) 排桩——显式 slot 优先，否则按 kind 分房自动分配（满员开新房并记 op_log）；
 	* 2) 门牌评分——有铭牌时按「唯一/差异化/带日期」启发式落库；
-	* 3) 初始排期——reviewScheduling 开启且未显式指定时，1 天后首次到期；
+	* 3) 初始排期——reviewScheduling 开启且未显式指定时，1 天后首次到期（显式 null = 明确不排期）；
 	* 4) 巡游路线——有桩位的条目登记到固定路线末尾。
 	* @returns 合入 WriteInput 的自动化字段。
 	*/
@@ -2676,7 +3055,7 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 				roomCaptions: slot === void 0 ? [] : placards.filter((row) => row.room === slot.room).map((row) => row.caption)
 			});
 		}
-		const initialReviewAt = input.initialReviewAt ?? (automation.reviewScheduling ? at + 864e5 : void 0);
+		const initialReviewAt = input.initialReviewAt === void 0 ? automation.reviewScheduling ? at + 864e5 : void 0 : input.initialReviewAt ?? void 0;
 		if (slot !== void 0 && sqlRouteHas.get(id) === void 0) sqlRouteAppend.run(id);
 		return {
 			...slot === void 0 ? {} : { slot },
@@ -2811,11 +3190,21 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 		},
 		async timeline(query) {
 			const limit = query.limit ?? 20;
-			const placeholders = query.scopes.map(() => "?").join(",");
-			return db.prepare(`SELECT * FROM nodes WHERE status = 'active' AND scope IN (${placeholders})
-        AND (? IS NULL OR created_at >= ?) AND (? IS NULL OR created_at <= ?)
-        AND (? IS NULL OR instr(content, ?) > 0)
-        ORDER BY created_at DESC LIMIT ?`).all(...query.scopes, query.since ?? null, query.since ?? null, query.until ?? null, query.until ?? null, query.topic ?? null, query.topic ?? null, limit).map(rowToRecord);
+			const where = `nodes.status = 'active' AND nodes.scope IN (${query.scopes.map(() => "?").join(",")})
+        AND (? IS NULL OR nodes.created_at >= ?) AND (? IS NULL OR nodes.created_at <= ?)
+        AND (? IS NULL OR instr(nodes.content, ?) > 0)`;
+			const params = [
+				...query.scopes,
+				query.since ?? null,
+				query.since ?? null,
+				query.until ?? null,
+				query.until ?? null,
+				query.topic ?? null,
+				query.topic ?? null,
+				limit
+			];
+			return (query.order === "tour" ? db.prepare(`SELECT nodes.* FROM nodes LEFT JOIN tour_routes ON tour_routes.node_id = nodes.id
+            WHERE ${where} ORDER BY tour_routes.position IS NULL, tour_routes.position ASC, nodes.created_at DESC LIMIT ?`).all(...params) : db.prepare(`SELECT nodes.* FROM nodes WHERE ${where} ORDER BY nodes.created_at DESC LIMIT ?`).all(...params)).map(rowToRecord);
 		},
 		async update(input) {
 			const old = getRow(input.id);
@@ -3354,6 +3743,33 @@ const KINDS = [
 	"episode",
 	"skill"
 ];
+/** 历史回填估算的模型可读文本（零成本，先看数再决定跑不跑）。 */
+function renderHistoryEstimate(estimate) {
+	if (estimate.unavailable !== void 0) return `历史回填不可用：${estimate.unavailable}`;
+	const rules = estimate.rules;
+	const window = rules.days === 0 ? "不限" : `${String(rules.days)} 天`;
+	const lines = [
+		`历史回填估算：候选 ${String(estimate.candidates)} 个会话 · 规则内 ${String(estimate.eligibleTurns)} 轮 · 待处理 ${String(estimate.pendingTurns)} 轮（此前已摄取 ${String(estimate.alreadyIngested)} 轮会自动跳过）。`,
+		`规则：时间窗 ${window} · 单会话≤${String(rules.maxTurnsPerSession)} 轮 · 总轮数≤${String(rules.maxTotalTurns)} · 含子代理 ${rules.includeSubagents ? "是" : "否"} · 含种子 ${rules.includeSeeded ? "是" : "否"} · 含无 cwd ${rules.includeNoCwd ? "是" : "否"}`,
+		`已排除：子代理 ${String(estimate.skipped.subagent)} · 种子 ${String(estimate.skipped.seeded)} · 无 cwd ${String(estimate.skipped.noCwd)} · 超时间窗 ${String(estimate.skipped.tooOld)} · 日志不可读 ${String(estimate.skipped.unreadable)}`
+	];
+	if (estimate.truncated) lines.push("注意：候选超出总轮数上限，本次只会处理最近的一部分会话；可调大 maxTotalTurns 或缩小时间窗分几次跑。");
+	lines.push("实际 LLM 调用次数不超过待处理轮数（低活动/寒暄/显式禁记的轮次会被节流跳过）。确认要真正回填请再传 dryRun=false。");
+	return lines.join("\n");
+}
+/** 历史回填执行结果的模型可读文本。 */
+function renderHistoryRun(result) {
+	const lines = [`历史回填${result.state === "done" ? "完成" : result.state === "cancelled" ? "已中止（可重跑续做）" : "失败"}：处理 ${String(result.sessionsDone)}/${String(result.sessionsTotal)} 个会话 · ${String(result.turnsDone)} 轮 → 写入 ${String(result.memoriesWritten)} 条记忆；跳过 ${String(result.turnsSkipped)} 轮 · 失败 ${String(result.turnsFailed)} 轮。`];
+	const reasons = Object.entries(result.skipReasons).sort(([, a], [, b]) => b - a);
+	if (reasons.length > 0) lines.push(`跳过原因：${reasons.map(([reason, count]) => `${reason} ${String(count)}`).join(" · ")}`);
+	if (result.failures.length > 0) {
+		const shown = result.failures.slice(0, 3).map((failure) => `${failure.sessionId.slice(-12)} 第 ${String(failure.turn)} 轮：${failure.reason}`);
+		lines.push(`失败明细（前 ${String(shown.length)} 条）：${shown.join("；")}`);
+		lines.push("若失败原因是历史会话记录的路由在当前环境不可用，可在 cordis.yml 配 provider/model，或让一个会话先用目标模型跑一轮（回填会优先复用当前在用的路由）后重跑——已完成的轮次会自动跳过。");
+	}
+	lines.push("同一批可重复执行：已完成的轮次按幂等键跳过，只补未完成的部分。");
+	return lines.join("\n");
+}
 /** 从模型参数收敛 scope（非法值或缺失回退 fallback）。 */
 function scopeOf(raw, fallback) {
 	if (raw === "user" || raw === "project" || raw === "shared") return raw;
@@ -3423,8 +3839,8 @@ async function rewriteQueries(deps, exec, query) {
 	}
 }
 /**
-* 构造 15 个工具定义（engram_save/search/timeline/update/forget/report/review/review_queue/
-* stats/export/distill/examine/neighbors/audit_forgotten/tour）。
+* 构造 16 个工具定义（engram_save/search/timeline/update/forget/report/review/review_queue/
+* stats/export/distill/examine/neighbors/audit_forgotten/tour/ingest_history）。
 * @param deps - 分库打开器、嵌入器、辅助 LLM、导出目录。
 * @returns 可直接 register 的工具定义数组。
 */
@@ -3818,7 +4234,7 @@ function createEngramTools(deps) {
 	});
 	const timeline = defineTool({
 		name: "engram_timeline",
-		description: "按时间范围与主题浏览记忆（时间倒序，最近 20 条）。无参数直接列出最近记录。",
+		description: "按时间范围与主题浏览记忆（默认时间倒序，最近 20 条）。order=tour 时改按固定巡游路线的桩位顺序走（未上路线者排末尾），输出附宫殿坐标——适合按宫殿固定路线复述；多作用域按 user→project→shared 顺序拼接（桩位顺序只在各自库内有意义）。无参数直接列出最近记录。",
 		parameters: {
 			scope: {
 				type: "string",
@@ -3841,6 +4257,11 @@ function createEngramTools(deps) {
 			until: {
 				type: "string",
 				description: "结束时间"
+			},
+			order: {
+				type: "string",
+				enum: ["time", "tour"],
+				description: "排序：缺省 'time' 按创建时间倒序；'tour' 按固定巡游路线桩位顺序"
 			}
 		},
 		output: {
@@ -3860,6 +4281,7 @@ function createEngramTools(deps) {
 		async execute(args) {
 			const input = args;
 			const scopes = scopesOf(input.scope);
+			const order = input.order === "tour" ? "tour" : "time";
 			const parseTime = (raw, field) => {
 				if (raw === void 0) return void 0;
 				const ms = Date.parse(raw);
@@ -3868,15 +4290,22 @@ function createEngramTools(deps) {
 			};
 			const since = parseTime(input.since, "since");
 			const until = parseTime(input.until, "until");
-			return { text: renderMemoryPacket(enforceBudget((await Promise.all(scopes.map(async (scope) => {
+			const results = await Promise.all(scopes.map(async (scope) => {
 				return (await deps.openStore(scope)).timeline({
 					scopes: [scope],
 					...input.topic === void 0 ? {} : { topic: input.topic },
 					...since === void 0 ? {} : { since },
 					...until === void 0 ? {} : { until },
+					order,
 					limit: 20
 				});
-			}))).flat().sort((a, b) => b.createdAt - a.createdAt).slice(0, 20).map((record) => `${new Date(record.createdAt).toISOString()} [${record.scope}/${record.kind}] ${truncateItem(record.content)}（id=${record.id}）`)).join("\n") || "时间线为空", "tool_timeline", input.topic ?? "（对话继续）") };
+			}));
+			const body = enforceBudget((order === "tour" ? results.flat().slice(0, 20) : results.flat().sort((a, b) => b.createdAt - a.createdAt).slice(0, 20)).map((record) => {
+				const slot = order === "tour" && record.slot !== void 0 ? ` ${record.slot.room}#${record.slot.index}` : "";
+				return `${new Date(record.createdAt).toISOString()}${slot} [${record.scope}/${record.kind}] ${truncateItem(record.content)}（id=${record.id}）`;
+			}));
+			const tail = order === "tour" ? "\n（按固定巡游路线桩位顺序；未上路线者按创建时间排末尾）" : "";
+			return { text: renderMemoryPacket(`${body.join("\n") || "时间线为空"}${tail}`, "tool_timeline", input.topic ?? "（对话继续）") };
 		}
 	});
 	const update = defineTool({
@@ -4001,7 +4430,7 @@ function createEngramTools(deps) {
 			},
 			render: (_args, value) => [{
 				type: "text",
-				text: `房间 ${value.id} 已闭馆（软删，可恢复），墓志铭已刻入操作日志。`
+				text: `记忆 ${value.id} 已闭馆（软删，可恢复），墓志铭已刻入操作日志。`
 			}]
 		},
 		async execute(args) {
@@ -4018,6 +4447,73 @@ function createEngramTools(deps) {
 			})).id };
 		}
 	});
+	/**
+	* 历史回填：把 dsh 历史会话逐轮提炼进宫殿（按会话 cwd 分库、已有幂等键的轮次跳过）。
+	* dryRun 默认 true——避免模型顺手触发成百次辅助调用；显式传 false 才真正写入。
+	*/
+	const ingestHistory = defineTool({
+		name: "engram_ingest_history",
+		description: "历史会话回填：把 dsh 的历史会话逐轮提炼进记忆宫殿（写进各会话自己 cwd 对应的项目库；此前已摄取的轮次自动跳过，中断后可重跑续做）。dryRun 缺省 true，只返回估算（候选会话数 / 规则内轮数 / 待处理轮数）而不调 LLM、不写库；确认后再传 dryRun=false 执行。大批量回填建议用设置页「历史回填」tab（有规则选择、进度与暂停）；本工具适合先估算或小批量执行。",
+		parameters: {
+			dryRun: {
+				type: "boolean",
+				description: "只估算不执行（默认 true；显式 false 才真正回填）"
+			},
+			days: {
+				type: "number",
+				description: "时间窗天数，0 = 不限；缺省用部署配置值"
+			},
+			maxTurnsPerSession: {
+				type: "number",
+				description: "单个会话最多摄取轮数；缺省用部署配置值"
+			},
+			maxTotalTurns: {
+				type: "number",
+				description: "本次最多处理的总轮数（只能调低配置硬上限）"
+			},
+			includeSubagents: {
+				type: "boolean",
+				description: "是否包含子代理会话（默认 false）"
+			},
+			includeSeeded: {
+				type: "boolean",
+				description: "是否包含种子会话（默认 false）"
+			},
+			includeNoCwd: {
+				type: "boolean",
+				description: "是否包含无 cwd 会话（默认 false；这类会话只能写进 user 库）"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { text: {
+					type: "string",
+					required: true
+				} }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args, exec) {
+			const input = args;
+			const history = deps.historyBackfill;
+			if (history === void 0) return { text: "历史回填不可用：当前组合未挂载会话持久化服务（会话日志不可读，例如 headless profile）。" };
+			const rules = {
+				...typeof input.days === "number" ? { days: input.days } : {},
+				...typeof input.maxTurnsPerSession === "number" ? { maxTurnsPerSession: input.maxTurnsPerSession } : {},
+				...typeof input.maxTotalTurns === "number" ? { maxTotalTurns: input.maxTotalTurns } : {},
+				...typeof input.includeSubagents === "boolean" ? { includeSubagents: input.includeSubagents } : {},
+				...typeof input.includeSeeded === "boolean" ? { includeSeeded: input.includeSeeded } : {},
+				...typeof input.includeNoCwd === "boolean" ? { includeNoCwd: input.includeNoCwd } : {}
+			};
+			if (input.dryRun !== false) return { text: renderHistoryEstimate(await history.estimate(rules)) };
+			return { text: renderHistoryRun(await history.run(rules, exec.signal)) };
+		}
+	});
 	/** P0-3 闭馆考古：返回最近 N 条 forgotten 条目 + 墓志铭。 */
 	const auditForgotten = defineTool({
 		name: "engram_audit_forgotten",
@@ -4316,7 +4812,7 @@ function createEngramTools(deps) {
 		}),
 		defineTool({
 			name: "engram_export",
-			description: "把记忆库导出为文件（Markdown / JSON / 镜像目录），返回文件路径。redactedView=true 时输出脱敏视图（内容二次清洗并截断为 40 字预览，可安全分享）。format=markdown-mirror 时每个房间一个 .md + frontmatter，附楼层清单 _meta.json 与全宫殿入口 _index.md，可直接用 Obsidian / git 漫游。",
+			description: "把记忆库导出为文件（Markdown / JSON / 镜像目录），返回文件路径。redactedView=true 时输出脱敏视图（内容二次清洗并截断为 40 字预览，可安全分享）。format=markdown-mirror 时按房间（kind）分目录、每条记忆一个 .md + frontmatter，附房间清单 _meta.json 与全宫殿入口 _index.md，可直接用 Obsidian / git 漫游。",
 			parameters: {
 				format: {
 					type: "string",
@@ -4325,7 +4821,7 @@ function createEngramTools(deps) {
 						"json",
 						"markdown-mirror"
 					],
-					description: "导出格式：markdown 单文件、json 单文件、markdown-mirror 每房间一文件（默认 markdown）"
+					description: "导出格式：markdown 单文件、json 单文件、markdown-mirror 每条记忆一文件（按房间分目录，默认 markdown）"
 				},
 				scope: {
 					type: "string",
@@ -4376,7 +4872,7 @@ function createEngramTools(deps) {
 						const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-").slice(0, 19);
 						const mirrorRoot = join(deps.exportDir, `mirror-${scope}-${stamp}`);
 						const report = await writeMirror(mirrorRoot, data);
-						written.push(`${mirrorRoot}（${report.fileCount} 个文件，${data.records.length} 间房间，${report.floors.length} 个楼层）`);
+						written.push(`${mirrorRoot}（${report.fileCount} 个文件，${data.records.length} 条记忆，${report.rooms.length} 个房间）`);
 						continue;
 					}
 					const payload = redactedView ? {
@@ -4459,11 +4955,11 @@ function createEngramTools(deps) {
 		}),
 		defineTool({
 			name: "engram_examine",
-			description: "渐进式披露：按 id 批量拉取房间完整铭牌（content + 楼层 + 状态 + 边关系）。仅在已通过 engram_search/timeline/neighbors 拿到候选 id 后调用，避免一次性吞全文。建议 ≤16 个 id，超出会按入参顺序保留前 N 条。",
+			description: "渐进式披露：按 id 批量拉取记忆完整铭牌（content + 房间 + 状态 + 边关系）。仅在已通过 engram_search/timeline/neighbors 拿到候选 id 后调用，避免一次性吞全文。建议 ≤16 个 id，超出会按入参顺序保留前 N 条。",
 			parameters: { ids: {
 				type: "array",
 				items: { type: "string" },
-				description: "房间 id 列表"
+				description: "记忆 id 列表"
 			} },
 			output: {
 				schema: {
@@ -4498,11 +4994,11 @@ function createEngramTools(deps) {
 		}),
 		defineTool({
 			name: "engram_neighbors",
-			description: "走廊漫步：从某间出发走 1-3 跳内的 related/supersedes/contradicts 边，返回邻居房间简表（仅 id + scope + kind + status + content），便于判断下一站。",
+			description: "走廊漫步：从某条记忆出发走 1-3 跳内的 related/supersedes/contradicts 边，返回邻居记忆简表（仅 id + scope + kind + status + content），便于判断下一站。",
 			parameters: {
 				id: {
 					type: "string",
-					description: "起点房间 id"
+					description: "起点记忆 id"
 				},
 				depth: {
 					type: "integer",
@@ -4534,9 +5030,9 @@ function createEngramTools(deps) {
 				if (seedRow === void 0) throw new Error(`engram_neighbors: 起点 ${seed} 不存在`);
 				const seedScope = seedRow.scope;
 				const neighbors = await (seedScope === "user" ? userStore : projectStore).neighbors(seed, depth);
-				if (neighbors.length === 0) return { text: `从 ${seed}（${seedScope}）出发，${depth} 跳内无邻居房间。` };
+				if (neighbors.length === 0) return { text: `从 ${seed}（${seedScope}）出发，${depth} 跳内无邻居记忆。` };
 				const lines = neighbors.map((record, index) => `${index + 1}. [${record.scope}/${record.kind}/${record.status}] ${record.content.slice(0, 80)}${record.content.length > 80 ? "…" : ""}（id=${record.id}）`);
-				return { text: `起点 ${seed}（${seedScope}）→ ${depth} 跳走廊共访 ${neighbors.length} 间：\n${lines.join("\n")}` };
+				return { text: `起点 ${seed}（${seedScope}）→ ${depth} 跳走廊共访 ${neighbors.length} 条：\n${lines.join("\n")}` };
 			}
 		}),
 		defineTool({
@@ -4642,13 +5138,14 @@ function createEngramTools(deps) {
 				return { text: `${degraded ? "（语义嵌入不可用，仅关键词检索）\n" : ""}${route.narrative}` };
 			}
 		}),
-		auditForgotten
+		auditForgotten,
+		ingestHistory
 	];
 }
 /**
 * 构造巡游路径：在 search 命中的基础上按路径策略重排。
 * 1) 起点簇：取命中中 kind 出现频次最高的前 N 个同 kind 节点（同类巩固）。
-* 2) 走廊扩展：从起点簇每个节点的 1-跳 neighbors 中挑 active 且 score > 0 的房间。
+* 2) 走廊扩展：从起点簇每个节点的 1-跳 neighbors 中挑 active 且 score > 0 的记忆。
 * 3) 反差收束：从剩余命中挑一个 emotionalValence ≥ 0.7 的做收束（强反差唤醒）。
 * 命中不足时按可用性回退；命中为 0 时返回空 stops。
 */
@@ -4731,13 +5228,13 @@ function renderTourNarrative(stops, query) {
 }
 //#endregion
 //#region src/selection-rationale.ts
-/** 给定一组入选房间，返回归因 XML 字符串；空 rooms 返回空串。 */
+/** 给定一组入选记忆，返回归因 XML 字符串；空 rooms 返回空串。 */
 function buildSelectionRationale(records) {
 	if (records.length === 0) return "";
 	const now = Date.now();
 	const lines = [
 		"<engram_selection_rationale>",
-		`本轮画像共 ${String(records.length)} 间房间，挑选理由如下：`,
+		`本轮画像共 ${String(records.length)} 条记忆，挑选理由如下：`,
 		""
 	];
 	for (const record of records) {
@@ -4894,6 +5391,10 @@ async function compressProfileOverflow(ctx, agent, routeOverride, overflow, sign
 async function preStep(ctx, openStore, resolved, embedder, state, logRequest, { agent, step, turn, signal }, next) {
 	const decision = await next();
 	if (decision.kind === "reject") return decision;
+	if (step === 1) {
+		const currentRoute = resolved.routeOverride ?? routeFromEvents(agent.session.snapshotEvents());
+		if (currentRoute !== void 0) state.route = currentRoute;
+	}
 	const mode = resolved.ingest;
 	if (step === 1 && mode !== "off") {
 		if (!state.pendingReplayed) {
@@ -5015,10 +5516,11 @@ function apply(ctx, config = {}) {
 		decayAfterDays: resolved.decayAfterDays
 	};
 	const stores = /* @__PURE__ */ new Map();
-	const openStore = (scope) => {
-		const existing = stores.get(scope);
+	/** 打开（或复用）一个分库文件；首次打开时幂等补齐存量排桩。 */
+	const openDb = (dbName) => {
+		const existing = stores.get(dbName);
 		if (existing !== void 0) return existing;
-		const path = scope === "user" ? join(resolved.dbDir, "user.db") : scope === "shared" ? join(resolved.dbDir, "shared.db") : join(resolved.dbDir, identity.dbName);
+		const path = join(resolved.dbDir, dbName);
 		const created = openEngramStore(path, rankBoost, {
 			autoSlot: resolved.autoSlot,
 			reviewScheduling: resolved.reviewScheduling
@@ -5029,12 +5531,168 @@ function apply(ctx, config = {}) {
 			if (assigned > 0) console.warn(`[dsh-engram] 存量记忆排桩完成：${assigned} 条已钉入宫殿（${path}）`);
 			return store;
 		});
-		stores.set(scope, created);
+		stores.set(dbName, created);
 		return created;
 	};
+	const openStore = (scope) => openDb(scope === "user" ? "user.db" : scope === "shared" ? "shared.db" : identity.dbName);
+	/** cwd → 分库文件名（历史回填会对每个历史 cwd 解析一次，避免重复读 git 元数据）。 */
+	const cwdDbNames = /* @__PURE__ */ new Map();
+	/**
+	* 按任意 cwd 的项目标识打开分库（历史回填专用）：历史会话写进它自己项目的库，
+	* 而不是当前工作目录的库——否则跨项目内容会串库。
+	* @param cwd - 历史会话 header 里记录的 cwd。
+	* @returns 该 cwd 对应项目分库的连接。
+	*/
+	/** cwd → 分库文件名（缓存，避免重复读 git 元数据与重复迁移检查）。 */
+	const dbNameForCwd = (cwd) => {
+		const cached = cwdDbNames.get(cwd);
+		if (cached !== void 0) return cached;
+		const projectIdentity = resolveProjectIdentity(cwd);
+		if (migrateProjectDb(resolved.dbDir, projectIdentity) === "renamed") console.warn(`[dsh-engram] 历史项目库已迁移为 origin 命名（${cwd}）`);
+		cwdDbNames.set(cwd, projectIdentity.dbName);
+		return projectIdentity.dbName;
+	};
+	const openStoreForProjectCwd = (cwd) => openDb(dbNameForCwd(cwd));
 	const embedder = createLocalEmbedder(resolved.modelCacheDir, resolved.hfEndpoint).catch((error) => {
 		console.warn("[dsh-engram] 嵌入器不可用，检索降级为纯关键词模式：", error);
 	});
+	const logIngestRequest = (data) => {
+		openStore("user").then((store) => store.audit("ingest-request", "AUX", JSON.stringify(data))).catch(() => {});
+	};
+	const preStepState = {
+		pendingReplayed: false,
+		lastProfileAgent: null,
+		lastProfileHash: null,
+		route: void 0
+	};
+	/** 会话持久化服务（可选；缺席时历史回填不可用）。 */
+	const persistenceService = () => {
+		const persistence = ctx.get("sessionPersistence");
+		if (persistence === void 0) return void 0;
+		return {
+			list: (signal) => persistence.list(signal),
+			load: (id) => persistence.load(id)
+		};
+	};
+	/** user 分库若已存在则打开（估算用：不因估算产生空库文件）。 */
+	const openUserStoreIfExists = () => existsSync(join(resolved.dbDir, "user.db")) ? openStore("user") : Promise.resolve(void 0);
+	/** 指定 cwd 的项目库若已存在则打开（估算用：不因估算产生空库文件）。 */
+	const openProjectStoreIfExists = (cwd) => {
+		const dbName = dbNameForCwd(cwd);
+		return existsSync(join(resolved.dbDir, dbName)) ? openDb(dbName) : Promise.resolve(void 0);
+	};
+	/** 组装历史回填依赖；source 每次现取，兼容持久化服务在插件之后挂载的组合。 */
+	const buildHistoryDeps = () => ({
+		source: persistenceService(),
+		resolveStore: openStoreForProjectCwd,
+		resolveExistingStore: openProjectStoreIfExists,
+		openUserStore: () => openStore("user"),
+		resolveExistingUserStore: openUserStoreIfExists,
+		embedder,
+		mode: resolved.ingest === "off" ? "light" : resolved.ingest,
+		routeOverride: resolved.routeOverride ?? preStepState.route,
+		call: (callParams) => streamText(ctx, {
+			...callParams,
+			sessionId: ""
+		}),
+		logRequest: logIngestRequest
+	});
+	/** 回填任务（进程内单例；面板轮询它的进度，工具同步等待自己的那一次运行）。 */
+	let backfillJob;
+	/** 历史回填对外接口：面板路由（异步 job）与工具（同步运行）共用。 */
+	const historyApi = {
+		/** 已注册的 provider 与模型清单（面板「辅助模型」下拉的数据源）。 */
+		models: async () => {
+			const llm = ctx.get("llm");
+			if (llm === void 0) return {
+				providers: [],
+				failures: []
+			};
+			const failures = [];
+			return {
+				providers: await Promise.all(llm.listProviders().map(async (provider) => {
+					try {
+						const models = await llm.listModels(provider.id);
+						return {
+							id: provider.id,
+							name: provider.name,
+							models: models.map((model) => ({
+								id: model.id,
+								name: model.name
+							}))
+						};
+					} catch (error) {
+						failures.push(`${provider.id}: ${error instanceof Error ? error.message : String(error)}`);
+						return {
+							id: provider.id,
+							name: provider.name,
+							models: []
+						};
+					}
+				})),
+				failures
+			};
+		},
+		estimate: (rules) => estimateHistoryBackfill(buildHistoryDeps(), resolved.historyBackfill, rules),
+		run: (rules, signal) => runHistoryBackfill(buildHistoryDeps(), resolved.historyBackfill, rules, () => {}, signal),
+		/** 启动后台回填；已有任务在跑时拒绝（面板按钮据此禁用）。 */
+		start: (rules) => {
+			if (backfillJob !== void 0 && backfillJob.progress.state === "running") return {
+				ok: false,
+				reason: "已有回填任务正在运行，请先暂停或等待完成"
+			};
+			const controller = new AbortController();
+			const job = {
+				controller,
+				failures: [],
+				progress: {
+					state: "running",
+					sessionsTotal: 0,
+					sessionsDone: 0,
+					turnsPlanned: 0,
+					turnsDone: 0,
+					memoriesWritten: 0,
+					turnsSkipped: 0,
+					turnsFailed: 0,
+					skipReasons: {}
+				}
+			};
+			backfillJob = job;
+			runHistoryBackfill(buildHistoryDeps(), resolved.historyBackfill, rules, (progress) => {
+				job.progress = progress;
+			}, controller.signal).then((result) => {
+				job.progress = result;
+				job.failures = result.failures;
+			}).catch((error) => {
+				console.warn("[dsh-engram] 历史回填失败：", error);
+				job.progress = {
+					...job.progress,
+					state: "failed"
+				};
+				job.error = error instanceof Error ? error.message : String(error);
+			});
+			return { ok: true };
+		},
+		cancel: () => {
+			backfillJob?.controller.abort();
+		},
+		/** 当前任务快照；从未跑过时返回 idle 占位。 */
+		status: () => ({
+			progress: backfillJob?.progress ?? {
+				state: "done",
+				sessionsTotal: 0,
+				sessionsDone: 0,
+				turnsPlanned: 0,
+				turnsDone: 0,
+				memoriesWritten: 0,
+				turnsSkipped: 0,
+				turnsFailed: 0,
+				skipReasons: {}
+			},
+			failures: backfillJob?.failures ?? [],
+			...backfillJob?.error === void 0 ? {} : { error: backfillJob.error }
+		})
+	};
 	for (const tool of createEngramTools({
 		openStore,
 		embedder,
@@ -5044,7 +5702,11 @@ function apply(ctx, config = {}) {
 		}),
 		routeOverride: resolved.routeOverride,
 		queryRewrite: resolved.queryRewrite,
-		exportDir: `${resolved.dbDir}/exports`
+		exportDir: `${resolved.dbDir}/exports`,
+		historyBackfill: {
+			estimate: historyApi.estimate,
+			run: historyApi.run
+		}
 	})) ctx.tools.register(tool);
 	ctx.inject(["webServer"], (webCtx) => {
 		registerEngramRoutes(webCtx, {
@@ -5053,20 +5715,18 @@ function apply(ctx, config = {}) {
 			mirrorDir: `${resolved.dbDir}/palaces`,
 			dbDir: resolved.dbDir,
 			pluginVersion: VERSION,
-			embedder
+			embedder,
+			history: {
+				estimate: historyApi.estimate,
+				start: historyApi.start,
+				cancel: historyApi.cancel,
+				status: historyApi.status,
+				models: historyApi.models,
+				defaults: resolved.historyBackfill
+			}
 		});
 	});
-	const logIngestRequest = (data) => {
-		openStore("user").then((store) => store.audit("ingest-request", "AUX", JSON.stringify(data))).catch(() => {});
-	};
-	if (resolved.injectProfile || resolved.ingest !== "off") {
-		const state = {
-			pendingReplayed: false,
-			lastProfileAgent: null,
-			lastProfileHash: null
-		};
-		ctx.on("agent/pre-step", (payload, next) => preStep(ctx, openStore, resolved, embedder, state, logIngestRequest, payload, next), { prepend: true });
-	}
+	if (resolved.injectProfile || resolved.ingest !== "off") ctx.on("agent/pre-step", (payload, next) => preStep(ctx, openStore, resolved, embedder, preStepState, logIngestRequest, payload, next), { prepend: true });
 	if (resolved.ingest !== "off") ctx.on("session/disposed", (session) => {
 		const mode = resolved.ingest;
 		if (mode === "off") return;