dsh-thesis 1.0.0

package/lib/intake/state.js

@@ -0,0 +1,420 @@
+/**
+ * 追问状态的落盘与读取：`.paper/intake.json`（相对论文工作区根）。
+ *
+ * 三条硬规则：
+ * 1. **原子写**：先写同目录临时文件，再改名覆盖目标。中途断电只会留下一个
+ *    可识别的临时文件，绝不会把状态写成半截 JSON。改名走可注入的
+ *    {@link IntakeIo.rename} 接口——真机上是 `node:fs/promises` 的 rename，
+ *    测试里是内存实现，两条路径都必须走通。
+ * 2. **损坏时报错，不静默重置**：JSON 解析失败、版本不符、结构不对，一律抛出
+ *    带文件路径与修复建议的中文错误。悄悄重置会丢掉用户已经答过的每一个问题，
+ *    这比报错严重得多。
+ * 3. **断点续问**：状态是唯一的真相来源，新会话读回它就能从正确的问题继续。
+ *
+ * @module dsh-thesis/intake
+ */
+import * as nodePath from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { isMissingError } from "../shared/fs-errors.js";
+/** 状态文件相对论文工作区根的路径。 */
+export const STATE_REL = '.paper/intake.json';
+/** 状态 schema 版本；结构不兼容变更时必须递增（旧状态将明确报错而非被猜读）。 */
+export const STATE_VERSION = 1;
+/** 合法阶段集合（状态迁移校验用）。 */
+export const INTAKE_STAGES = ['asking', 'done'];
+/** 建一份全新状态。 */
+export function defaultState(now = new Date(), specPath = '') {
+    const iso = now.toISOString();
+    return {
+        version: STATE_VERSION,
+        createdAt: iso,
+        updatedAt: iso,
+        stage: 'asking',
+        askedIds: [],
+        answers: {},
+        skipped: [],
+        skipReasons: {},
+        specPath,
+    };
+}
+// ---------------------------------------------------------------------------
+// 序列化与宽容解析
+// ---------------------------------------------------------------------------
+/** 稳定序列化：键序固定、2 空格缩进、结尾换行（同样的状态 → 同样的字节）。 */
+export function serializeState(state) {
+    const answers = {};
+    for (const id of Object.keys(state.answers).sort()) {
+        const rec = state.answers[id];
+        const out = {
+            value: rec.value,
+            at: rec.at,
+            source: rec.source,
+            confirmed: rec.confirmed,
+        };
+        if (rec.valid !== undefined)
+            out.valid = rec.valid;
+        if (rec.note !== undefined)
+            out.note = rec.note;
+        answers[id] = out;
+    }
+    const ordered = {
+        version: state.version,
+        createdAt: state.createdAt,
+        updatedAt: state.updatedAt,
+        stage: state.stage,
+        askedIds: [...state.askedIds],
+        answers,
+        skipped: [...state.skipped],
+        skipReasons: { ...state.skipReasons },
+        specPath: state.specPath,
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+/** 状态损坏：带路径与修复建议的可读错误。 */
+export class IntakeStateError extends Error {
+    path;
+    constructor(path, detail) {
+        super(`追问状态文件无法使用：${path}\n原因：${detail}\n` +
+            `处理建议：修正该 JSON（或先备份后删除它，用 thesis_intake action=start 重新开始追问）。` +
+            `请勿手工把 answers 改空——那会丢掉已确认的全部答案。`);
+        this.name = 'IntakeStateError';
+        this.path = path;
+    }
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === 'string');
+}
+function asStringRecord(value) {
+    const out = {};
+    if (value === null || typeof value !== 'object')
+        return out;
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+}
+function parseAnswers(value) {
+    const out = {};
+    if (value === null || typeof value !== 'object')
+        return out;
+    for (const [id, raw] of Object.entries(value)) {
+        if (raw === null || typeof raw !== 'object')
+            continue;
+        const rec = raw;
+        if (typeof rec.value !== 'string' || rec.value.trim() === '')
+            continue;
+        const answer = {
+            value: rec.value,
+            at: typeof rec.at === 'string' ? rec.at : new Date().toISOString(),
+            source: rec.source === 'materials' ? 'materials' : 'user',
+            confirmed: rec.confirmed === true,
+        };
+        if (typeof rec.valid === 'boolean')
+            answer.valid = rec.valid;
+        if (typeof rec.note === 'string')
+            answer.note = rec.note;
+        out[id] = answer;
+    }
+    return out;
+}
+/**
+ * 解析状态文本。任何结构性问题都抛出 {@link IntakeStateError}，
+ * 绝不返回「看起来能用」的默认状态。
+ */
+export function parseState(raw, path = STATE_REL) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new IntakeStateError(path, `不是合法 JSON（${error instanceof Error ? error.message : String(error)}）`);
+    }
+    if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        throw new IntakeStateError(path, '顶层不是 JSON 对象');
+    }
+    const obj = data;
+    if (obj.version !== STATE_VERSION) {
+        throw new IntakeStateError(path, `version 期望 ${STATE_VERSION}，实际 ${JSON.stringify(obj.version)}（可能是旧版本或被别的工具改写）`);
+    }
+    const stage = obj.stage === 'done' ? 'done' : 'asking';
+    const specPath = typeof obj.specPath === 'string' ? obj.specPath : '';
+    const iso = new Date().toISOString();
+    return {
+        version: STATE_VERSION,
+        createdAt: typeof obj.createdAt === 'string' ? obj.createdAt : iso,
+        updatedAt: typeof obj.updatedAt === 'string' ? obj.updatedAt : iso,
+        stage,
+        askedIds: asStringArray(obj.askedIds),
+        answers: parseAnswers(obj.answers),
+        skipped: asStringArray(obj.skipped),
+        skipReasons: asStringRecord(obj.skipReasons),
+        specPath,
+    };
+}
+/**
+ * 校验「把阶段推进到 to」是否被允许。
+ *
+ * 规则：`asking → done` 只能由 `done` 动作在必答项齐全后触发（由调用方保证）；
+ * 已经 `done` 的状态允许重答问题，但不会被自动退回 `asking`——回退必须显式
+ * 重答一个必答项（见 {@link applyAnswer}），避免状态在两次读取间莫名倒退。
+ */
+export function canTransition(state, to) {
+    if (!INTAKE_STAGES.includes(to)) {
+        return { ok: false, reason: `未知阶段：${String(to)}。有效值：${INTAKE_STAGES.join('、')}。` };
+    }
+    if (state.stage === to)
+        return { ok: true, reason: '' };
+    if (state.stage === 'done' && to === 'asking') {
+        return { ok: false, reason: '已完成的追问不会自动退回进行中；如发现答案有误，直接重答该问题即可。' };
+    }
+    return { ok: true, reason: '' };
+}
+/** 校验通过后写入阶段；不通过时返回原状态（调用方负责提示原因）。 */
+export function setStage(state, to, now = new Date()) {
+    const check = canTransition(state, to);
+    if (!check.ok)
+        return check;
+    state.stage = to;
+    state.updatedAt = now.toISOString();
+    return { ok: true, reason: '' };
+}
+/** 记录一次「已提问」（幂等：重复记同一个 id 不改变状态）。 */
+export function markAsked(state, id, now = new Date()) {
+    if (state.askedIds.includes(id))
+        return false;
+    state.askedIds.push(id);
+    state.updatedAt = now.toISOString();
+    return true;
+}
+/**
+ * 写入一条答案。**幂等**：`value` 与原值完全一致时不改动 `at`/`updatedAt`，
+ * 返回 `changed:false`——重复提交同一个答案不会污染历史。
+ */
+export function applyAnswer(state, id, value, opts = {}) {
+    const now = opts.now ?? new Date();
+    const trimmed = value.trim();
+    const existing = state.answers[id];
+    if (existing !== undefined && existing.value === trimmed) {
+        // 同样的答案：只更新确认位（材料推断 → 用户确认是唯一有意义的变化）。
+        const wantConfirmed = opts.confirmed ?? true;
+        if (existing.confirmed !== wantConfirmed) {
+            existing.confirmed = wantConfirmed;
+            state.updatedAt = now.toISOString();
+            return { changed: true, record: existing };
+        }
+        return { changed: false, record: existing };
+    }
+    const record = {
+        value: trimmed,
+        at: now.toISOString(),
+        source: opts.source ?? 'user',
+        confirmed: opts.confirmed ?? true,
+    };
+    if (opts.valid !== undefined)
+        record.valid = opts.valid;
+    if (opts.note !== undefined)
+        record.note = opts.note;
+    state.answers[id] = record;
+    state.skipped = state.skipped.filter(s => s !== id);
+    delete state.skipReasons[id];
+    state.updatedAt = now.toISOString();
+    // 重答必答项后，已完成的追问回到进行中：规格必须重新收敛。
+    if (state.stage === 'done' && record.valid !== false) {
+        state.stage = 'asking';
+    }
+    return { changed: true, record };
+}
+/** 记录一次跳过（必须带理由；跳过必答项会让 `done` 拒绝）。 */
+export function applySkip(state, id, reason, now = new Date()) {
+    if (!state.skipped.includes(id))
+        state.skipped.push(id);
+    state.skipReasons[id] = reason.trim();
+    state.updatedAt = now.toISOString();
+}
+/**
+ * 用 `ctx.fs` 拼一个 I/O；默认改名走 `node:fs/promises`（真机路径）。
+ *
+ * **`read` 只把「确认不存在」折叠成 `undefined`**：权限与 IO 错误一律上抛。
+ * 否则调用方会以为状态还没建过，用默认态覆盖掉用户已答的每一个问题
+ * （详见 `shared/fs-errors.ts`）。
+ */
+export function fsIo(fs, signal, rename) {
+    return {
+        async read(path) {
+            try {
+                return await fs.readText(await fs.resolve(path, { signal }), signal);
+            }
+            catch (error) {
+                if (isMissingError(error))
+                    return undefined;
+                throw error;
+            }
+        },
+        async write(path, content) {
+            await fs.writeText(await fs.resolve(path, { signal }), content, undefined, signal);
+        },
+        async exists(path) {
+            const info = await fs.stat(await fs.resolve(path, { signal }));
+            return info !== undefined && !info.isDirectory;
+        },
+        async listDir(path) {
+            try {
+                const entries = await fs.listDir(await fs.resolve(path, { signal }), signal);
+                return entries.map(e => e.name);
+            }
+            catch (error) {
+                // 目录不存在 = 空目录；读失败必须上抛，否则「材料清单读不出来」会被当成「没有材料」。
+                if (isMissingError(error))
+                    return [];
+                throw error;
+            }
+        },
+        ...(rename === undefined
+            ? {}
+            : {
+                async rename(from, to) {
+                    await rename(from, to);
+                },
+            }),
+        async remove(path) {
+            // `ctx.fs` 没有删除原语，写空内容即可；残留的空临时文件不影响正确性。
+            await fs.writeText(await fs.resolve(path, { signal }), '', undefined, signal).catch(() => undefined);
+        },
+    };
+}
+/** 真机改名：`node:fs/promises` 的 readFile + writeFile（同一目录内的替换）。 */
+export const nodeRename = async (from, to) => {
+    const data = await readFile(from, 'utf8');
+    await writeFile(to, data, 'utf8');
+};
+/**
+ * 原子写：先写临时文件，再改名覆盖目标。
+ *
+ * 有 `io.rename` 时是真改名；没有时退化为「写临时 → 写目标 → 清临时」。
+ * 任何一步失败都会尽力清掉临时文件，并把错误原样抛给调用方（不吞）。
+ */
+export async function writeAtomic(io, path, content) {
+    const tmp = `${path}.tmp-${process.pid}-${Date.now().toString(36)}`;
+    await io.write(tmp, content);
+    try {
+        if (io.rename !== undefined) {
+            await io.rename(tmp, path);
+        }
+        else {
+            await io.write(path, content);
+            await io.remove?.(tmp);
+        }
+    }
+    catch (error) {
+        await io.remove?.(tmp);
+        throw error;
+    }
+}
+/** 读取状态；文件不存在返回 `undefined`（由调用方决定是否初始化）。 */
+export async function loadState(io, root) {
+    const path = nodePath.join(root, STATE_REL);
+    const raw = await io.read(path);
+    if (raw === undefined)
+        return undefined;
+    return parseState(raw, path);
+}
+/** 原子落盘状态。 */
+export async function saveState(io, root, state, now = new Date()) {
+    state.updatedAt = now.toISOString();
+    await writeAtomic(io, nodePath.join(root, STATE_REL), serializeState(state));
+}
+// ---------------------------------------------------------------------------
+// 材料清单与台账：宽容读取
+// ---------------------------------------------------------------------------
+/** `thesis_ingest` 的材料清单相对路径。 */
+export const MATERIALS_REL = '00-管理/材料清单.md';
+/** 台账相对路径（复用 paper 模块的约定，但不 import 它，避免模块间耦合成环）。 */
+const LEDGER_REL = '00-管理/进度台账.md';
+const EXT_RE = /\.([A-Za-z0-9]{1,5})$/;
+function extOf(path) {
+    const m = EXT_RE.exec(path);
+    return m === null ? '' : m[1].toLowerCase();
+}
+/** 去掉 Markdown 的包裹标记（反引号、加粗星号）与首尾空白。 */
+function unwrapCell(cell) {
+    return cell.replace(/[`*]/g, '').trim();
+}
+/**
+ * 宽容解析材料清单 Markdown。
+ *
+ * 只认「一行的表格里有 `.扩展名` 的单元格」：取该行第一个（剥掉反引号/星号后）
+ * 含扩展名的单元格为路径，其余单元格里第一个非空、非数字的当类型。
+ * 表头、分隔行、段落一律跳过。
+ * 解析不出任何条目时返回空清单——宁可多问一个，也不要凭猜免问。
+ */
+export function parseMaterials(md) {
+    const items = [];
+    for (const line of md.split(/\r?\n/)) {
+        if (!line.includes('|'))
+            continue;
+        const cells = line.split('|').map(c => c.trim()).filter(c => c.length > 0);
+        if (cells.length === 0)
+            continue;
+        if (cells.every(c => /^:?-{2,}:?$/.test(c)))
+            continue; // 表格分隔行
+        // 路径优先：剥掉反引号后能看出扩展名的那个单元格。
+        const pathCell = cells.find(c => EXT_RE.test(unwrapCell(c)) && !/^[-–—\s]*$/.test(c));
+        if (pathCell === undefined)
+            continue;
+        const path = unwrapCell(pathCell);
+        if (path === '')
+            continue;
+        const kind = cells.find(c => c !== pathCell && !/^\d+(\.\d+)?\s*(B|KB|MB|GB)?$/i.test(c) && !/^[-–—\s]*$/.test(c)) ?? '';
+        items.push({ path, kind: unwrapCell(kind), ext: extOf(path) });
+    }
+    return { found: items.length > 0, items };
+}
+/** 读材料清单；缺失或为空返回 `{ found:false, items:[] }`。 */
+export async function loadMaterials(io, root) {
+    const raw = await io.read(nodePath.join(root, MATERIALS_REL));
+    if (raw === undefined)
+        return { found: false, items: [] };
+    return parseMaterials(raw);
+}
+/**
+ * 从进度台账推断当前阶段名。
+ *
+ * 台账的机器真相是 `<!-- thesis:state ... -->` 里的 `currentStage`（数字），
+ * 这里只做「读到就用、读不到就按开题前」的宽容推断，绝不因为台账异常而中断追问。
+ */
+export function stageFromLedger(md) {
+    if (md === undefined)
+        return undefined;
+    const block = /<!-- thesis:state\n([\s\S]*?)\n-->/.exec(md);
+    if (block === null || block[1] === undefined)
+        return undefined;
+    let stage;
+    try {
+        stage = JSON.parse(block[1]).currentStage;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof stage !== 'number' || !Number.isFinite(stage))
+        return undefined;
+    const names = {
+        1: '选题',
+        2: '开题',
+        3: '文献调研',
+        4: '系统设计',
+        5: '系统实现',
+        6: '系统测试',
+        7: '论文撰写',
+        8: '定稿与合规',
+        9: '答辩',
+    };
+    return names[Math.floor(stage)];
+}
+/** 读台账并推断阶段（读不到返回 undefined，由 {@link makeContext} 落到默认值）。 */
+export async function loadStage(io, root) {
+    return stageFromLedger(await io.read(nodePath.join(root, LEDGER_REL)));
+}
+export { LEDGER_REL };

package/lib/memory/recall.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 记忆回灌：把「用户已知的稳定事实」在相关时自动放回上下文。
+ *
+ * 只提供 `fact_search/remember/context` 三个工具的跨会话事实是**被动**的——模型得先想起来去查。
+ * 真实使用里最常发生的是：用户上次说过「我们学校要求页边距 3cm、查重阈值 20%」，
+ * 这次新开会话问「帮我写绪论」，模型不知道这条约束，于是白写一版。
+ *
+ * 所以这里补一个 `agent/pre-step` 监听：当用户这句话与事实库里的 Key/Value 有词面重叠时，
+ * 注入一张**有界**的事实卡片（默认最多 4 条 / 600 字符）。四条护栏：
+ *
+ * 1. **只在相关时出现**：没有任何关键词命中就一个字节都不注入（避免每条消息都塞满事实）；
+ * 2. **有界**：条数与字符数都封顶，且明确标注「可能过时，冲突时以用户当前说法为准」；
+ * 3. **不重复**：按 agent 记住上次注入时的事实指纹（最大 updatedAt + 条数），未变化不再注入；
+ * 4. **永不抛进 agent 循环**：取事实、算关键词、渲染全部包在 try 里。
+ *
+ * @module dsh-thesis/memory/recall
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryEntry } from './service.ts';
+/** 记忆回灌参数。 */
+export interface RecallOptions {
+    /** 单次最多注入几条记忆。 */
+    maxEntries: number;
+    /** 注入卡片的最大字符数（含标题与说明）。 */
+    maxChars: number;
+    /** 参与匹配的关键词最短长度。 */
+    minKeywordLength: number;
+}
+/** 出厂默认值（与 `PAPER_DEFAULTS.recall` 保持一致，单一来源见 `src/config.ts`）。 */
+export declare const RECALL_DEFAULTS: RecallOptions;
+/**
+ * 提取用于匹配的关键词：中文按 2-gram 滑窗、拉丁按词，去停用词并按长度降序（长词更具体）。
+ *
+ * 中文没有空格，直接用整句匹配会永远命中不了；用 2-gram 能把「查重阈值」拆成
+ * 「查重」「重阈」「阈值」这样的片段，与记忆里的同名字段天然对齐。
+ */
+export declare function keywordsOf(text: string, minLength?: number): string[];
+/** 一条记忆与关键词集合的重叠得分（命中数为主，置信度与更新时间作微调）。 */
+export declare function scoreEntry(entry: MemoryEntry, keywords: readonly string[]): number;
+/**
+ * 选出与关键词相关的记忆：至少命中 1 个词，按得分降序，同分取更新更近的，截断到上限。
+ */
+export declare function selectRelevant(entries: readonly MemoryEntry[], keywords: readonly string[], maxEntries?: number): MemoryEntry[];
+/** 卡片正文（不含 source 包装）。 */
+export declare function renderRecallCard(entries: readonly MemoryEntry[], maxChars: number): string;
+/** 构造注入消息（user 角色、插件来源、snapshot 形态）。 */
+export declare function makeRecallMessage(entries: readonly MemoryEntry[], maxChars: number): {
+    id: string;
+    role: 'user';
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    source: {
+        kind: string;
+        plugin: string;
+        form: string;
+        sections: Array<{
+            name: string;
+            text: string;
+        }>;
+    };
+};
+/**
+ * 安装跨会话事实回灌监听。
+ *
+ * 需要一个已注册的 `ctx.memory`（由 `registerFacts` 提供）；没有则静默不装。
+ */
+export declare function installFactRecall(ctx: Context, options?: RecallOptions): void;

package/lib/memory/recall.js

@@ -0,0 +1,177 @@
+/**
+ * 记忆回灌：把「用户已知的稳定事实」在相关时自动放回上下文。
+ *
+ * 只提供 `fact_search/remember/context` 三个工具的跨会话事实是**被动**的——模型得先想起来去查。
+ * 真实使用里最常发生的是：用户上次说过「我们学校要求页边距 3cm、查重阈值 20%」，
+ * 这次新开会话问「帮我写绪论」，模型不知道这条约束，于是白写一版。
+ *
+ * 所以这里补一个 `agent/pre-step` 监听：当用户这句话与事实库里的 Key/Value 有词面重叠时，
+ * 注入一张**有界**的事实卡片（默认最多 4 条 / 600 字符）。四条护栏：
+ *
+ * 1. **只在相关时出现**：没有任何关键词命中就一个字节都不注入（避免每条消息都塞满事实）；
+ * 2. **有界**：条数与字符数都封顶，且明确标注「可能过时，冲突时以用户当前说法为准」；
+ * 3. **不重复**：按 agent 记住上次注入时的事实指纹（最大 updatedAt + 条数），未变化不再注入；
+ * 4. **永不抛进 agent 循环**：取事实、算关键词、渲染全部包在 try 里。
+ *
+ * @module dsh-thesis/memory/recall
+ */
+import { randomUUID } from 'node:crypto';
+import { textOfBlocks } from "../shared/text.js";
+/** 出厂默认值（与 `PAPER_DEFAULTS.recall` 保持一致，单一来源见 `src/config.ts`）。 */
+export const RECALL_DEFAULTS = { maxEntries: 4, maxChars: 600, minKeywordLength: 2 };
+/** 停用词（中英混合，只去最吵的一批；不求语言学完备）。 */
+const STOP_WORDS = new Set([
+    '的', '了', '是', '在', '我', '你', '他', '她', '它', '们', '这', '那', '有', '和', '与', '或',
+    '把', '被', '让', '给', '对', '为', '从', '到', '就', '都', '也', '还', '很', '要', '会', '能',
+    '一个', '什么', '怎么', '如何', '可以', '需要', '现在', '我们', '你们', '他们', '这个', '那个',
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'to', 'of', 'in', 'on', 'for', 'and', 'or',
+    'it', 'this', 'that', 'with', 'my', 'me', 'you', 'we', 'please', 'help',
+]);
+/**
+ * 提取用于匹配的关键词：中文按 2-gram 滑窗、拉丁按词，去停用词并按长度降序（长词更具体）。
+ *
+ * 中文没有空格，直接用整句匹配会永远命中不了；用 2-gram 能把「查重阈值」拆成
+ * 「查重」「重阈」「阈值」这样的片段，与记忆里的同名字段天然对齐。
+ */
+export function keywordsOf(text, minLength = RECALL_DEFAULTS.minKeywordLength) {
+    const found = new Set();
+    const latin = text.toLowerCase().match(/[a-z][a-z0-9_.-]{1,30}/g) ?? [];
+    for (const word of latin) {
+        if (!STOP_WORDS.has(word) && word.length >= minLength)
+            found.add(word);
+    }
+    const han = text.match(/[\u4e00-\u9fa5]{2,}/g) ?? [];
+    for (const run of han) {
+        if (run.length <= 4) {
+            if (!STOP_WORDS.has(run))
+                found.add(run);
+            continue;
+        }
+        for (let i = 0; i + 2 <= run.length; i += 1) {
+            const gram = run.slice(i, i + 2);
+            if (!STOP_WORDS.has(gram))
+                found.add(gram);
+        }
+    }
+    return [...found].sort((a, b) => b.length - a.length || a.localeCompare(b)).slice(0, 24);
+}
+/** 一条记忆与关键词集合的重叠得分（命中数为主，置信度与更新时间作微调）。 */
+export function scoreEntry(entry, keywords) {
+    const haystack = `${entry.key}\n${entry.value}`.toLowerCase();
+    let hits = 0;
+    for (const keyword of keywords) {
+        if (haystack.includes(keyword.toLowerCase()))
+            hits += 1;
+    }
+    if (hits === 0)
+        return 0;
+    return hits + entry.confidence * 0.01;
+}
+/**
+ * 选出与关键词相关的记忆：至少命中 1 个词，按得分降序，同分取更新更近的，截断到上限。
+ */
+export function selectRelevant(entries, keywords, maxEntries = RECALL_DEFAULTS.maxEntries) {
+    return entries
+        .map(entry => ({ entry, score: scoreEntry(entry, keywords) }))
+        .filter(item => item.score > 0)
+        .sort((a, b) => b.score - a.score || b.entry.updatedAt - a.entry.updatedAt)
+        .slice(0, Math.max(0, maxEntries))
+        .map(item => item.entry);
+}
+/** 卡片正文（不含 source 包装）。 */
+export function renderRecallCard(entries, maxChars) {
+    const header = '【已确认事实 · dsh-thesis】以下是你以前确认过的稳定事实（跨会话记住的，可能过时；与用户当前说法冲突时以用户为准）：';
+    const lines = [header];
+    for (const entry of entries) {
+        const line = `- ${entry.key} = ${entry.value}`;
+        if (lines.join('\n').length + line.length + 1 > maxChars) {
+            lines.push('- …（还有更多事实，需要时用 fact_context 查询）');
+            break;
+        }
+        lines.push(line);
+    }
+    return lines.join('\n').slice(0, maxChars);
+}
+/**
+ * 取出全部事实用于相关性打分。
+ *
+ * 优先 `context('')`（语义就是「列出全部」）；只实现了 `search` 的替身退回
+ * `search('', …)`，这样回灌在两种服务形状下都能工作。
+ */
+function listAllFacts(service) {
+    if (typeof service.context === 'function')
+        return service.context('', { limit: 500 });
+    return service.search('', { limit: 500 });
+}
+/** 构造注入消息（user 角色、插件来源、snapshot 形态）。 */
+export function makeRecallMessage(entries, maxChars) {
+    const text = renderRecallCard(entries, maxChars);
+    return {
+        id: randomUUID(),
+        role: 'user',
+        content: [{ type: 'text', text }],
+        source: {
+            kind: 'plugin',
+            plugin: 'dsh-thesis',
+            form: 'snapshot',
+            sections: [{ name: '已确认事实', text }],
+        },
+    };
+}
+/** 记忆指纹：用于「记忆没变就不再注入」。 */
+function fingerprint(entries) {
+    let latest = 0;
+    for (const entry of entries)
+        latest = Math.max(latest, entry.updatedAt);
+    return `${entries.length}:${latest}`;
+}
+/**
+ * 安装跨会话事实回灌监听。
+ *
+ * 需要一个已注册的 `ctx.memory`（由 `registerFacts` 提供）；没有则静默不装。
+ */
+export function installFactRecall(ctx, options = RECALL_DEFAULTS) {
+    const lastInjected = new WeakMap();
+    ctx.on('agent/pre-step', async (payload, next) => {
+        const downstream = await next();
+        if (downstream.kind !== 'enter')
+            return downstream;
+        try {
+            const messages = payload.messages;
+            const last = messages?.[messages.length - 1];
+            if (last === undefined || last.source?.kind !== 'user')
+                return downstream;
+            const text = textOfBlocks((last.content ?? []));
+            if (text.trim().length < 8 || text.trim().startsWith('/'))
+                return downstream;
+            const service = ctx.get('memory');
+            if (service === undefined || typeof service.search !== 'function')
+                return downstream;
+            // 取全量事实用于相关性打分。注意不能用 `search('')`：空 query 会抛错
+            // （避免"匹配一切"的静默语义）。优先用 `context('')`——它的语义就是"列出全部"；
+            // 只有实现了 search 的替身才退回 search（此时按老语义传空 query）。
+            const entries = listAllFacts(service);
+            if (entries.length === 0)
+                return downstream;
+            const keywords = keywordsOf(text, options.minKeywordLength);
+            if (keywords.length === 0)
+                return downstream;
+            const relevant = selectRelevant(entries, keywords, options.maxEntries);
+            if (relevant.length === 0)
+                return downstream;
+            const agent = payload.agent;
+            if (agent !== undefined) {
+                const mark = fingerprint(entries);
+                if (lastInjected.get(agent) === mark)
+                    return downstream;
+                lastInjected.set(agent, mark);
+            }
+            const injected = makeRecallMessage(relevant, options.maxChars);
+            return { kind: 'enter', messages: [...downstream.messages, injected] };
+        }
+        catch {
+            // 记忆回灌是增益功能：任何异常都不允许影响对话本身。
+            return downstream;
+        }
+    });
+}